Wine User Guide: update
Dimitrie O. Paun
dpaun at rogers.com
Thu Jan 29 17:35:48 CST 2004
ChangeLog
Move keyboard programming instructions to the Devel Guide.
Cleanup up a bunch of bits that don't belong in a book.
Index: documentation/configuring.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/configuring.sgml,v
retrieving revision 1.38
diff -u -r1.38 configuring.sgml
--- documentation/configuring.sgml 5 Jan 2004 21:16:53 -0000 1.38
+++ documentation/configuring.sgml 29 Jan 2004 15:09:18 -0000
@@ -169,12 +169,8 @@
script called <command>winecheck</command>, to be found
in Wine's tools/ directory. It tries to check your
configuration's correctness by checking for some popular
- problems.
-
- The latest version can always be found at
- <ulink url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
-
- To run it, run in a <glossterm>terminal</glossterm> in the Wine source tree directory:
+ problems. To run it, run in a <glossterm>terminal</glossterm>
+ in the Wine source tree directory:
</para>
<screen>
<prompt>$ </><userinput>cd tools</>
@@ -182,9 +178,8 @@
</screen>
<para>
The winecheck output will be a percentage score indicating Wine
- configuration correctness.
- Note that winecheck is only alpha, so it's not very complete or
- 100% accurate.
+ configuration correctness. Please note that winecheck is not
+ 100% accurate.
</para>
<para>
@@ -2830,196 +2825,12 @@
</programlisting>
</sect1>
-<sect1 id="config-keyboard">
-<title>Keyboard</title>
-
-<para>
-Wine now needs to know about your keyboard layout. This
-requirement comes from a need from many apps to have the
-correct scancodes available, since they read these directly,
-instead of just taking the characters returned by the X
-server. This means that Wine now needs to have a mapping from
-X keys to the scancodes these programs expect.
-</para>
-<para>
-On startup, Wine will try to recognize the active X layout by
-seeing if it matches any of the defined tables. If it does,
-everything is alright. If not, you need to define it.
-</para>
-<para>
-To do this, open the file
-<filename>dlls/x11drv/keyboard.c</filename> and take a look
-at the existing tables. Make a backup copy of it, especially
-if you don't use CVS.
-</para>
-<para>
-What you really would need to do, is find out which scancode
-each key needs to generate. Find it in the
-<function>main_key_scan</function> table, which looks like
-this:
-</para>
-<programlisting>
-static const int main_key_scan[MAIN_LEN] =
-{
-/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
-0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
-0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
-0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
-0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
-0x56 /* the 102nd key (actually to the right of l-shift) */
-};
-</programlisting>
-<para>
-Next, assign each scancode the characters imprinted on the
-keycaps. This was done (sort of) for the US 101-key keyboard,
-which you can find near the top in
-<filename>keyboard.c</filename>. It also shows that if there
-is no 102nd key, you can skip that.
-</para>
-<para>
-However, for most international 102-key keyboards, we have
-done it easy for you. The scancode layout for these already
-pretty much matches the physical layout in the
-<function>main_key_scan</function>, so all you need to do is
-to go through all the keys that generate characters on your
-main keyboard (except spacebar), and stuff those into an
-appropriate table. The only exception is that the 102nd key,
-which is usually to the left of the first key of the last line
-(usually <keycap>Z</keycap>), must be placed on a separate
-line after the last line.
-</para>
-<para>
-For example, my Norwegian keyboard looks like this
-</para>
-<screen>
-§ ! " # ¤ % & / ( ) = ? ` Back-
-| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
-
-Tab Q W E R T Y U I O P Å ^
- ¨~
- Enter
-Caps A S D F G H J K L Ø Æ *
-Lock '
-
-Sh- > Z X C V B N M ; : _ Shift
-ift < , . -
-
-Ctrl Alt Spacebar AltGr Ctrl
-</screen>
-<para>
-Note the 102nd key, which is the <keycap><></keycap> key, to
-the left of <keycap>Z</keycap>. The character to the right of
-the main character is the character generated by
-<keycap>AltGr</keycap>.
-</para>
-<para>
-This keyboard is defined as follows:
-</para>
-<programlisting>
-static const char main_key_NO[MAIN_LEN][4] =
-{
-"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
-"qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
-"aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
-"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
-"<>"
-};
-</programlisting>
-<para>
-Except that " and \ needs to be quoted with a backslash, and
-that the 102nd key is on a separate line, it's pretty
-straightforward.
-</para>
-<para>
-After you have written such a table, you need to add it to the
-<function>main_key_tab[]</function> layout index table. This
-will look like this:
-</para>
-<programlisting>
-static struct {
-WORD lang, ansi_codepage, oem_codepage;
-const char (*key)[MAIN_LEN][4];
-} main_key_tab[]={
-...
-...
-{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
-...
-</programlisting>
-<para>
-After you have added your table, recompile Wine and test that
-it works. If it fails to detect your table, try running
-</para>
-<screen>
-wine --debugmsg +key,+keyboard >& key.log
- </screen>
- <para>
- and look in the resulting <filename>key.log</filename> file to
- find the error messages it gives for your layout.
- </para>
- <para>
- Note that the <constant>LANG_*</constant> and
- <constant>SUBLANG_*</constant> definitions are in
- <filename>include/winnls.h</filename>, which you might need to
- know to find out which numbers your language is assigned, and
- find it in the debugmsg output. The numbers will be
- <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
- the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
- <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
- <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
- could look for <literal>0414</literal> in the debugmsg output
- to find out why my keyboard won't detect.
- </para>
- <para>
- Once it works, submit it to the Wine project. If you use CVS,
- you will just have to do
- </para>
- <screen>
-cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
- </screen>
- <para>
- from your main Wine directory, then submit
- <filename>layout.diff</filename> to
- <email>wine-patches at winehq.org</email> along with a brief note
- of what it is.
- </para>
- <para>
- If you don't use CVS, you need to do
- </para>
- <screen>
-diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
- </screen>
- <para>
- and submit it as explained above.
- </para>
- <para>
- If you did it right, it will be included in the next Wine
- release, and all the troublesome programs (especially
- remote-control programs) and games that use scancodes will
- be happily using your keyboard layout, and you won't get those
- annoying fixme messages either.
- </para>
- <para>
- Good luck.
- </para>
- </sect1>
-
<sect1 id="config-scsi-support">
<title>SCSI Support</title>
<para>
This file describes setting up the Windows ASPI interface.
- </para>
-
- <para>
- <warning><title>Warning/Warning/Warning!!!!!!</title>
- <para>This may trash your system if used incorrectly. It may
- even trash your system when used <emphasis>correctly</>!
- </para>
- </warning>
- </para>
-
- <para>
- Now that I have said that. ASPI is a direct link to SCSI devices from
- windows programs. ASPI just forwards the SCSI commands that programs send
+ ASPI is a direct link to SCSI devices from windows programs.
+ ASPI just forwards the SCSI commands that programs send
to it to the SCSI bus.
</para>
<para>
@@ -3033,22 +2844,17 @@
have their permissions set as restricted as possible!
</para>
- <para>
- Cookbook for setting up scanner: (At least how mine is to work)
- (well, for other devices such as CD burners, MO drives, ..., too)
- </para>
-
<sect2>
<title>Windows requirements</title>
<orderedlist>
<listitem>
<para>
- The scanner software needs to use the "Adaptec"
+ The software needs to use the "Adaptec"
compatible drivers (ASPI). At least with Mustek, they
allow you the choice of using the built-in card or the
"Adaptec (AHA)" compatible drivers. This will not work
any other way. Software that accesses the scanner via a
- DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
+ DOS ASPI driver (e.g. ASPI2DOS) is supported, too.
</para>
</listitem>
<listitem>
@@ -3136,28 +2942,9 @@
</sect2>
<sect2>
- <title>General Information</title>
- <para>
- The mustek scanner I have was shipped with a package
- "ipplus". This program uses the TWAIN driver specification
- to access scanners.
- </para>
- <para>
- (TWAIN MANAGER)
- </para>
- <para>
- <programlisting>
-ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>NOTES/BUGS</title>
+ <title>Notes</title>
<para>
The biggest drawback is that it only works under Linux at the moment.
- </para>
- <para>
The ASPI code has only been tested with:
</para>
<itemizedlist>
@@ -3181,19 +2968,13 @@
</para>
</listitem>
</itemizedlist>
- <para>
- I make no warranty to the ASPI code. It makes my scanner
- work. Your devices may explode. I have no way of determining
- this. I take zero responsibility!
- </para>
</sect2>
</sect1>
<sect1 id="config-odbc">
<title>Using ODBC</title>
<para>
- This section describes how ODBC works within Wine and how to configure
- it to do what you want (if it can do what you want).
+ This section describes how ODBC works within Wine and how to configure it.
</para>
<para>
The ODBC system within Wine, as with the printing system, is designed
Index: documentation/fonts.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/fonts.sgml,v
retrieving revision 1.17
diff -u -r1.17 fonts.sgml
--- documentation/fonts.sgml 26 Nov 2003 03:55:01 -0000 1.17
+++ documentation/fonts.sgml 29 Jan 2004 14:46:13 -0000
@@ -489,9 +489,6 @@
</listitem>
</orderedlist>
- <para>
- Hope this helps...
- </para>
</sect2>
</sect1>
Index: documentation/implementation.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/implementation.sgml,v
retrieving revision 1.10
diff -u -r1.10 implementation.sgml
--- documentation/implementation.sgml 27 Jan 2004 20:10:01 -0000 1.10
+++ documentation/implementation.sgml 29 Jan 2004 14:56:56 -0000
@@ -2,6 +2,177 @@
<title>Low-level Implementation</title>
<para>Details of Wine's Low-level Implementation...</para>
+<sect1 id="config-keyboard">
+<title>Keyboard</title>
+
+<para>
+Wine now needs to know about your keyboard layout. This
+requirement comes from a need from many apps to have the
+correct scancodes available, since they read these directly,
+instead of just taking the characters returned by the X
+server. This means that Wine now needs to have a mapping from
+X keys to the scancodes these programs expect.
+</para>
+<para>
+On startup, Wine will try to recognize the active X layout by
+seeing if it matches any of the defined tables. If it does,
+everything is alright. If not, you need to define it.
+</para>
+<para>
+To do this, open the file
+<filename>dlls/x11drv/keyboard.c</filename> and take a look
+at the existing tables. Make a backup copy of it, especially
+if you don't use CVS.
+</para>
+<para>
+What you really would need to do, is find out which scancode
+each key needs to generate. Find it in the
+<function>main_key_scan</function> table, which looks like
+this:
+</para>
+<programlisting>
+static const int main_key_scan[MAIN_LEN] =
+{
+/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
+0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
+0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
+0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
+0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
+0x56 /* the 102nd key (actually to the right of l-shift) */
+};
+</programlisting>
+<para>
+Next, assign each scancode the characters imprinted on the
+keycaps. This was done (sort of) for the US 101-key keyboard,
+which you can find near the top in
+<filename>keyboard.c</filename>. It also shows that if there
+is no 102nd key, you can skip that.
+</para>
+<para>
+However, for most international 102-key keyboards, we have
+done it easy for you. The scancode layout for these already
+pretty much matches the physical layout in the
+<function>main_key_scan</function>, so all you need to do is
+to go through all the keys that generate characters on your
+main keyboard (except spacebar), and stuff those into an
+appropriate table. The only exception is that the 102nd key,
+which is usually to the left of the first key of the last line
+(usually <keycap>Z</keycap>), must be placed on a separate
+line after the last line.
+</para>
+<para>
+For example, my Norwegian keyboard looks like this
+</para>
+<screen>
+§ ! " # ¤ % & / ( ) = ? ` Back-
+| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
+
+Tab Q W E R T Y U I O P Å ^
+ ¨~
+ Enter
+Caps A S D F G H J K L Ø Æ *
+Lock '
+
+Sh- > Z X C V B N M ; : _ Shift
+ift < , . -
+
+Ctrl Alt Spacebar AltGr Ctrl
+</screen>
+<para>
+Note the 102nd key, which is the <keycap><></keycap> key, to
+the left of <keycap>Z</keycap>. The character to the right of
+the main character is the character generated by
+<keycap>AltGr</keycap>.
+</para>
+<para>
+This keyboard is defined as follows:
+</para>
+<programlisting>
+static const char main_key_NO[MAIN_LEN][4] =
+{
+"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
+"qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
+"aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
+"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
+"<>"
+};
+</programlisting>
+<para>
+Except that " and \ needs to be quoted with a backslash, and
+that the 102nd key is on a separate line, it's pretty
+straightforward.
+</para>
+<para>
+After you have written such a table, you need to add it to the
+<function>main_key_tab[]</function> layout index table. This
+will look like this:
+</para>
+<programlisting>
+static struct {
+WORD lang, ansi_codepage, oem_codepage;
+const char (*key)[MAIN_LEN][4];
+} main_key_tab[]={
+...
+...
+{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
+...
+</programlisting>
+<para>
+After you have added your table, recompile Wine and test that
+it works. If it fails to detect your table, try running
+</para>
+<screen>
+wine --debugmsg +key,+keyboard >& key.log
+ </screen>
+ <para>
+ and look in the resulting <filename>key.log</filename> file to
+ find the error messages it gives for your layout.
+ </para>
+ <para>
+ Note that the <constant>LANG_*</constant> and
+ <constant>SUBLANG_*</constant> definitions are in
+ <filename>include/winnls.h</filename>, which you might need to
+ know to find out which numbers your language is assigned, and
+ find it in the debugmsg output. The numbers will be
+ <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
+ the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
+ <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
+ <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
+ could look for <literal>0414</literal> in the debugmsg output
+ to find out why my keyboard won't detect.
+ </para>
+ <para>
+ Once it works, submit it to the Wine project. If you use CVS,
+ you will just have to do
+ </para>
+ <screen>
+cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
+ </screen>
+ <para>
+ from your main Wine directory, then submit
+ <filename>layout.diff</filename> to
+ <email>wine-patches at winehq.org</email> along with a brief note
+ of what it is.
+ </para>
+ <para>
+ If you don't use CVS, you need to do
+ </para>
+ <screen>
+diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
+ </screen>
+ <para>
+ and submit it as explained above.
+ </para>
+ <para>
+ If you did it right, it will be included in the next Wine
+ release, and all the troublesome programs (especially
+ remote-control programs) and games that use scancodes will
+ be happily using your keyboard layout, and you won't get those
+ annoying fixme messages either.
+ </para>
+ </sect1>
+
+
<sect1 id="undoc-func">
<title>Undocumented APIs</title>
Index: documentation/printing.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/printing.sgml,v
retrieving revision 1.18
diff -u -r1.18 printing.sgml
--- documentation/printing.sgml 20 Jan 2004 01:23:04 -0000 1.18
+++ documentation/printing.sgml 29 Jan 2004 14:47:33 -0000
@@ -208,61 +208,6 @@
</sect4>
</sect3>
- <sect3>
- <title>TODO / Bugs</title>
-
- <itemizedlist>
- <listitem>
- <para>
- Driver does read PPD files, but ignores all constraints
- and doesn't let you specify whether you have optional
- extras such as envelope feeders. You will therefore find
- a larger than normal selection of input bins in the
- print setup dialog box. I've only really tested ppd
- parsing on the <filename>hp4m6_v1.ppd</filename> file.
- </para>
- </listitem>
- <listitem>
- <para>
- No TrueType download.
- </para>
- </listitem>
- <listitem>
- <para>
- StretchDIBits uses level 2 PostScript.
- </para>
- </listitem>
- <listitem>
- <para>
- AdvancedSetup dialog box.
- </para>
- </listitem>
- <listitem>
- <para>
- Many partially implemented functions.
- </para>
- </listitem>
- <listitem>
- <para>
- ps.c is becoming messy.
- </para>
- </listitem>
- <listitem>
- <para>
- Notepad often starts text too far to the left depending
- on the margin settings. However the win3.1
- <filename>pscript.drv</filename> (under wine) also does
- this.
- </para>
- </listitem>
- <listitem>
- <para>
- Probably many more...
- </para>
- </listitem>
- </itemizedlist>
-
- </sect3>
</sect2>
</sect1>
Index: documentation/registry.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/registry.sgml,v
retrieving revision 1.12
diff -u -r1.12 registry.sgml
--- documentation/registry.sgml 5 Jan 2004 21:11:45 -0000 1.12
+++ documentation/registry.sgml 29 Jan 2004 14:20:43 -0000
@@ -2,13 +2,9 @@
<title>The Registry</title>
<para>
- Originally written by Ove Kåven
- </para>
-
- <para>
After Win3.x, the registry became a fundamental part of Windows.
It is the place where both Windows itself, and all
- Win95/98/NT/2000/whatever-compliant applications, store
+ Win95/98/NT/2000/XP/etc.-compliant applications, store
configuration and state data. While most sane system
administrators (and Wine developers) curse badly at the twisted
nature of the Windows registry, it is still necessary for Wine
Index: documentation/running.sgml
===================================================================
RCS file: /var/cvs/wine/documentation/running.sgml,v
retrieving revision 1.26
diff -u -r1.26 running.sgml
--- documentation/running.sgml 28 Nov 2003 23:36:25 -0000 1.26
+++ documentation/running.sgml 29 Jan 2004 16:22:39 -0000
@@ -7,16 +7,6 @@
support programs etc.
</para>
- <para>
- This chapter will describe all aspects of running Wine, like e.g.
- basic Wine invocation, command line parameters of various Wine
- support programs etc.
- </para>
-
- <para>
-
- </para>
-
<sect1 id="basic-usage">
<title>Basic usage: applications and control panel applets</title>
<para>
@@ -75,21 +65,12 @@
remember to include the double quotes. Some programs don't
always use obvious naming for their directories and EXE files,
so you might have to look inside the program files directory to
- see what it put where.
+ see what was put where.
</para>
</sect1>
<sect1 id="running-wine">
<title>How to run Wine</title>
- <para>
- Wine is a very complicated piece of software with many ways to
- adjust how it runs. With very few exceptions, you can
- activate the same set of features through the <link
- linkend="config-file">configuration file</link> as you can
- with command-line parameters. In this chapter, we'll briefly
- discuss these parameters, and match them up with their
- corresponding configuration variables.
- </para>
<para>
You can invoke the <command>wine --help</command> command to
--
Dimi.
More information about the wine-patches
mailing list