git.oblomov.eu Git - wine/blob - documentation/configuring.sgml

   1   <chapter id="configuring">
   2     <title>Configuring Wine</title>
   3     <para>Setting up config files, etc.</para>
   4
   5     <sect1 id="config">
   6       <title>General Configuration</title>
   7       <para>
   8         Copyright 1999 &name-adam-sacarny; <email>&email-adam-sacarny;</email>
   9       </para>
  10       <para>
  11         (Extracted from <filename>wine/documentation/config</filename>)
  12       </para>
  13
  14       <sect2>
  15         <title>The Wine Config File</title>
  16         <para>
  17           The Wine config file stores various settings for Wine. These include:
  18           <itemizedlist>
  19             <listitem>
  20               <para>
  21                 Drives and information about them
  22               </para>
  23             </listitem>
  24             <listitem>
  25               <para>
  26                 Directory settings
  27               </para>
  28             </listitem>
  29             <listitem>
  30               <para>
  31                 Port settings
  32               </para>
  33             </listitem>
  34             <listitem>
  35               <para>
  36                 The Wine look and feel
  37               </para>
  38             </listitem>
  39             <listitem>
  40               <para>
  41                 Wine's DLL usage
  42               </para>
  43             </listitem>
  44             <listitem>
  45               <para>
  46                 Wine's multimedia drivers and DLL configuration
  47               </para>
  48             </listitem>
  49           </itemizedlist>
  50         </para>
  51       </sect2>
  52
  53       <sect2>
  54         <title>How Do I Make One?</title>
  55         <para>
  56           This section will guide you through the process of making a
  57           config file. Take a look at the file <filename>&lt;dirs to
  58           wine>/documentation/samples/config</filename>. It is organized by section.
  59         </para>
  60
  61         <informaltable frame="all">
  62           <tgroup cols="3">
  63             <thead>
  64               <row>
  65                 <entry>Section Name</entry>
  66                 <entry>Needed?</entry>
  67                 <entry>What it Does</entry>
  68               </row>
  69             </thead>
  70             <tbody>
  71               <row>
  72                 <entry>[Drive X]</entry>
  73                 <entry>yes</entry>
  74                 <entry>Sets up drives recognized by wine</entry>
  75               </row>
  76               <row>
  77                 <entry>[wine]</entry>
  78                 <entry>yes</entry>
  79                 <entry>Settings for wine directories</entry>
  80               </row>
  81               <row>
  82                 <entry>[DllDefaults]</entry>
  83                 <entry>recmd</entry>
  84                 <entry>Defaults for loading DLL's</entry>
  85               </row>
  86               <row>
  87                 <entry>[DllPairs]</entry>
  88                 <entry>recmd</entry>
  89                 <entry>Sanity checkers for DLL's</entry>
  90               </row>
  91               <row>
  92                 <entry>[DllOverrides]</entry>
  93                 <entry>recmd</entry>
  94                 <entry>Overides defaults for DLL loading</entry>
  95               </row>
  96               <row>
  97                 <entry>[x11drv]</entry>
  98                 <entry>recmd</entry>
  99                 <entry>Graphic driver settings</entry>
 100               </row>
 101               <row>
 102                 <entry>[fonts]</entry>
 103                 <entry>yes</entry>
 104                 <entry>Font appearance and recognition</entry>
 105               </row>
 106               <row>
 107                 <entry>[serialports]</entry>
 108                 <entry>no</entry>
 109                 <entry>COM ports seen by wine</entry>
 110               </row>
 111               <row>
 112                 <entry>[parallelports]</entry>
 113                 <entry>no</entry>
 114                 <entry>LPT ports seen by wine</entry>
 115               </row>
 116               <row>
 117                 <entry>[ppdev]</entry>
 118                 <entry>no</entry>
 119                 <entry>Parallelport emulation</entry>
 120               </row>
 121               <row>
 122                 <entry>[spooler]</entry>
 123                 <entry>no</entry>
 124                 <entry>Print spooling</entry>
 125               </row>
 126               <row>
 127                 <entry>[ports]</entry>
 128                 <entry>no</entry>
 129                 <entry>Direct port access</entry>
 130               </row>
 131               <row>
 132                 <entry>[spy]</entry>
 133                 <entry>no</entry>
 134                 <entry>What to do with certain debug messages</entry>
 135               </row>
 136               <row>
 137                 <entry>[Registry]</entry>
 138                 <entry>no</entry>
 139                 <entry>Specifies locations of windows registry files</entry>
 140               </row>
 141               <row>
 142                 <entry>[tweak.layout]</entry>
 143                 <entry>recmd</entry>
 144                 <entry>Appearance of wine</entry>
 145               </row>
 146               <row>
 147                 <entry>[programs]</entry>
 148                 <entry>no</entry>
 149                 <entry>Programs to be run automatically</entry>
 150               </row>
 151               <row>
 152                 <entry>[Console]</entry>
 153                 <entry>no</entry>
 154                 <entry>Console settings</entry>
 155               </row>
 156               <row>
 157                 <entry>[Clipboard]</entry>
 158                 <entry>no</entry>
 159                 <entry>Interaction for wine and X11 clipboard</entry>
 160               </row>
 161               <row>
 162                 <entry>[afmdirs]</entry>
 163                 <entry>no</entry>
 164                 <entry>Postscript driver settings</entry>
 165               </row>
 166               <row>
 167                 <entry>[WinMM]</entry>
 168                 <entry>yes</entry>
 169                 <entry>Multimedia settings</entry>
 170               </row>
 171               <row>
 172                 <entry>[AppDefaults]</entry>
 173                 <entry>no</entry>
 174                 <entry>Overwrite the settings of previous sections for special programs</entry>
 175               </row>
 176             </tbody>
 177           </tgroup>
 178         </informaltable>
 179
 180         <sect3>
 181           <title>The [Drive X] Section</title>
 182           <para>
 183             These sections are supposed to make certain Unix
 184             directory locations accessible to Wine as a DOS/Windows drive
 185             (drive 'X:') and thus accessible to Windows programs
 186             under the drive name you specified.
 187             Every DOS/Windows program sort of expects at least a C: drive (and
 188             sometimes also an A: floppy drive), so your config file should
 189             at least contain the corresponding sections, [Drive C] and
 190             [Drive A].
 191             You need to decide on whether you want to use an existing Windows
 192             partition as the C drive or whether you want to create your own
 193             Wine drive C directory tree somewhere (take care about
 194             permissions !).
 195             Each drive section may specify up to 6 different settings
 196             as explained below.
 197           </para>
 198           <para>
 199             <programlisting>[Drive X]</programlisting>
 200             The above line begins the section for a drive whose letter is X
 201             (DOS notation: drive 'X:').
 202             You could e.g. create an equivalent to a drive 'C:'
 203             under DOS/Windows by using a [Drive C] section name.
 204           </para>
 205           <para>
 206             <programlisting>"Path" = "/dir/to/path"</programlisting>
 207             This specifies the directory where the drive will begin.
 208             When Wine is browsing in drive X, it will be able
 209             to see the files that are in the directory
 210             <filename>/dir/to/path</filename> and below.
 211             (note that symlinks to directories won't get included !
 212             see "<link linkend="dirsymlinks">ShowDirSymlinks</link>"
 213             config setting)
 214             You can also make use of environment variables like $HOME here,
 215             an example for using a mywinedrive directory in your home dir
 216             would be
 217             "Path" = "${HOME}/mywinedrive"
 218             Don't forget to leave off the trailing slash!
 219           </para>
 220           <para>
 221             <programlisting>"Type" = "hd|cdrom|network|floppy"</programlisting>
 222             Sets up the type of drive Wine will see it as. Type must
 223             equal one of the four <literal>floppy</literal>,
 224             <literal>hd</literal>, <literal>cdrom</literal>, or
 225             <literal>network</literal>. They are self-explanatory.
 226             (The |'s mean "Type = '&lt;one of the options&gt;'".)
 227             Usually, you choose "hd" for a drive ("hd" is default anyway).
 228           </para>
 229           <para>
 230             <programlisting>"Label" = "blah"</programlisting>
 231             Defines the drive label. Generally only needed
 232             for programs that look for a special CD-ROM.
 233             The label may be up to 11 characters.
 234             Note that the preferred way of managing labels and serial numbers
 235             of CD-ROMs and floppies is to give Wine raw device access for
 236             reading these on a per-CD case (see "Device" below) instead of
 237             hardcoding one specific "Label".
 238           </para>
 239           <para>
 240             <programlisting>"Serial" = "deadbeef"</programlisting>
 241             Tells Wine the serial number of the drive. A few programs with
 242             intense protection for pirating might need this, but otherwise
 243             it's not needed. Up to 8 characters and hexadecimal.
 244             Using a "Device" entry instead of hardcoding the "Serial" probably
 245             is a smarter choice.
 246           </para>
 247           <para>
 248             <programlisting>"Filesystem" = "win95|unix|msdos"</programlisting>
 249             Sets up the way Wine looks at files on the drive.
 250           </para>
 251
 252           <variablelist>
 253             <varlistentry>
 254               <term><literal>win95</literal></term>
 255               <listitem>
 256                 <para>
 257                   Case insensitive. Alike to Windows 9x/NT 4. This is
 258                   the long filename filesystem you are probably used
 259                   to working with. The filesystem of choice for most
 260                   applications to be run under wine.  PROBABLY THE ONE
 261                   YOU WANT!
 262                 </para>
 263               </listitem>
 264             </varlistentry>
 265             <varlistentry>
 266               <term><literal>unix</literal></term>
 267               <listitem>
 268                 <para>
 269                   Case sensitive. This filesystem has almost no use
 270                   (Windows apps expect case insensitive filenames).
 271                   Try it if you dare, but win95 is a  much better
 272                   choice.
 273                 </para>
 274               </listitem>
 275             </varlistentry>
 276             <varlistentry>
 277               <term><literal>msdos</literal></term>
 278               <listitem>
 279                 <para>
 280                   Case insensitive filesystem. Alike to DOS and
 281                   Windows 3.x. <literal>8.3</literal> is the maximum
 282                   length of files (eightdot.123) - longer ones will be
 283                   truncated. (NOTE: this is a very bad choice if you
 284                   plan on running apps that use long filenames. win95
 285                   should work fine with apps that were designed to run
 286                   under the msdos system. In other words, you might
 287                   not want to use this.)
 288                 </para>
 289               </listitem>
 290             </varlistentry>
 291           </variablelist>
 292
 293           <programlisting>"Device" = "/dev/xx"</programlisting>
 294           <para>
 295             Needed for raw device access and label and serial number reading.
 296             Use this ONLY for floppy and cdrom devices. Using it on
 297             Extended2 or other Unix file systems can have dire results
 298             (when a windows app tries to do a lowlevel write,
 299             they do it in a FAT way -- FAT format is completely different from
 300             any Unix file system).
 301             Also, make sure that you have proper permissions to this device
 302             file.
 303           </para>
 304           <note>
 305             <para>
 306               This setting is not really important; almost all apps
 307               will have no problem if it remains unspecified. For
 308               CD-ROMs it's quite useful in order to get automatic label
 309               detection, though. If you are unsure about specifying
 310               device names, just leave out this setting for your
 311               drives.
 312             </para>
 313           </note>
 314           <para>
 315             Here are a few sample entries:
 316             <programlisting>
 317 Here is a setup for Drive C, a generic hard drive:
 318 [Drive C]
 319 "Path" = "/dosc"
 320 "Type" = "hd"
 321 "Label" = "Hard Drive"
 322 "Filesystem" = "win95"
 323 This is a setup for Drive E, a generic CD-ROM drive:
 324 [Drive E]
 325 "Path" = "/mnt/cdrom"
 326 "Type" = "cdrom"
 327 "Label" = "Total Annihilation"
 328 "Filesystem" = "win95"
 329 "Device" = "/dev/cdrom"
 330 And here is a setup for Drive A, a generic floppy drive:
 331 [Drive A]
 332 "Type" = "floppy"
 333 "Path" = "/mnt/floppy"
 334 "Label" = "Floppy Drive"
 335 "Serial" = "87654321"
 336 "Filesystem" = "win95"
 337 "Device" = "/dev/fd0"
 338             </programlisting>
 339           </para>
 340         </sect3>
 341
 342         <sect3>
 343           <title>The [wine] Section </title>
 344           <para>
 345             The [wine] section of the configuration file contains all kinds
 346             of general settings for Wine.
 347           </para>
 348           <para>
 349             <programlisting>"Windows" = "c:\\windows"</programlisting>
 350             This tells Wine and Windows programs where the
 351             <filename>Windows</filename> directory is.  It is
 352             recommended to have this directory somewhere on your
 353             configured <medialabel>C</medialabel> drive, and it's also
 354             recommended to just call the directory "windows" (this is
 355             the default setup on Windows, and some stupid applications
 356             might rely on this).  So in case you chose a "Windows"
 357             setting of "c:\\windows" and you chose to set up a drive C
 358             e.g. at <filename>/usr/local/wine_c</filename>, the
 359             corresponding directory would be
 360             <filename>/usr/local/wine_c/windows</filename>.  Make one
 361             if you don't already have one. NO TRAILING SLASH (NOT
 362             <filename>C:\\windows\</filename>)! Write access strongly
 363             recommended!
 364           </para>
 365           <para>
 366             <programlisting>"System" = "c:\\windows\\system"</programlisting>
 367             This sets up where the windows system files are. The Windows
 368             system directory should reside below the directory used for the
 369             <literal>Windows</literal> setting.
 370             Thus when using the example above, the system directory would be
 371             <filename>/usr/local/wine_c/windows/system</filename>.
 372             Again, no trailing slash, and write access!
 373           </para>
 374           <para>
 375             <programlisting>"Temp" = "c:\\temp"</programlisting> This should
 376             be the directory you want your temp files stored in,
 377             /usr/local/wine_c/temp in our example.
 378             Again, no trailing slash, and WRITE ACCESS!!
 379           </para>
 380           <para>
 381             <programlisting>
 382 "Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"
 383             </programlisting>
 384           </para>
 385           <para>
 386             Behaves like the <envar>PATH</envar> setting on UNIX
 387             boxes. When wine is run like <userinput>wine
 388               sol.exe</userinput>, if <filename>sol.exe</filename>
 389             resides in a directory specified in the
 390             <literal>Path</literal> setting, wine will run it (Of
 391             course, if <filename>sol.exe</filename> resides in the
 392             current directory, wine will run that one). Make sure it
 393             always has your <filename>windows</filename> directory and
 394             system directory (For this setup, it must have
 395             <filename>"c:\\windows;c:\\windows\\system"</filename>).
 396           </para>
 397           <para>
 398             <programlisting>"GraphicsDriver" = "x11drv|ttydrv"</programlisting>
 399             Sets the graphics driver to use for Wine output.
 400             x11drv is for X11 output, ttydrv is for text console output.
 401             WARNING: if you use ttydrv here, then you won't be able to run
 402             any Windows GUI programs. Thus this option is mainly interesting
 403             for e.g. embedded use of Wine in web server scripts.
 404           </para>
 405           <para>
 406             <programlisting>"Printer" = "off|on"</programlisting> Tells wine
 407             whether to allow printing via printer drivers to work.
 408             This option isn't needed for our builtin psdrv printer driver
 409             at all.
 410             Using these things are pretty alpha, so you might want to
 411             watch out. Some people might find it useful, however. If
 412             you're not planning on working on printing via windows printer
 413             drivers, don't even add this to your wine config file
 414             (It probably isn't already in it).
 415             Check out the [spooler] and [parallelports] sections too.
 416           </para>
 417           <para>
 418             <programlisting>"ShellLinker" = "wineshelllink"</programlisting>
 419             This setting specifies the shell linker script to use for setting
 420             up Windows icons in e.g. KDE or Gnome that are given by programs
 421             making use of appropriate shell32.dll functionality to create
 422             icons on the desktop/start menu during installation.
 423           </para>
 424           <para id="dirsymlinks">
 425             <programlisting>"ShowDirSymlinks" = "1"</programlisting>
 426             Wine doesn't pass directory symlinks to Windows programs by
 427             default, as doing so may crash some programs that do
 428             recursive lookups of whole subdirectory trees
 429             whenever a directory symlink points back to itself or one of its
 430             parent directories.
 431             That's why we disallowed the use of directory symlinks
 432             and added this setting to reenable ("1") this functionality.
 433           </para>
 434           <para>
 435             <programlisting>"SymbolTableFile" = "wine.sym"</programlisting>
 436             Sets up the symbol table file for the wine debugger. You
 437             probably don't need to fiddle with this. May be useful if
 438             your wine is stripped.
 439           </para>
 440         </sect3>
 441
 442         <sect3>
 443           <title>Introduction To DLL Sections</title>
 444           <para>
 445             There are a few things you will need to know before
 446             configuring the DLL sections in your wine configuration
 447             file.
 448           </para>
 449           <sect4>
 450             <title>Windows DLL Pairs</title>
 451             <para>
 452               Most windows DLL's have a win16 (Windows 3.x) and win32
 453               (Windows 9x/NT) form.  The combination of the win16 and
 454               win32 DLL versions are called the "DLL pair". This is a
 455               list of the most common pairs:
 456             </para>
 457
 458             <informaltable>
 459               <tgroup cols="3">
 460                 <thead>
 461                   <row>
 462                     <entry>Win16</entry>
 463                     <entry>Win32</entry>
 464                     <entry>
 465                       Native
 466                       <footnote>
 467                         <para>
 468                           Is it possible to use native dll with wine?
 469                           (See next section)
 470                         </para>
 471                       </footnote>
 472                     </entry>
 473                   </row>
 474                 </thead>
 475                 <tbody>
 476                   <row>
 477                     <entry>KERNEL</entry>
 478                     <entry>KERNEL32</entry>
 479                     <entry>No!</entry>
 480                   </row>
 481                   <row>
 482                     <entry>USER</entry>
 483                     <entry>USER32</entry>
 484                     <entry>No!</entry>
 485                   </row>
 486                   <row>
 487                     <entry>SHELL</entry>
 488                     <entry>SHELL32</entry>
 489                     <entry>Yes</entry>
 490                   </row>
 491                   <row>
 492                     <entry>GDI</entry>
 493                     <entry>GDI32</entry>
 494                     <entry>No!</entry>
 495                   </row>
 496                   <row>
 497                     <entry>COMMDLG</entry>
 498                     <entry>COMDLG32</entry>
 499                     <entry>Yes</entry>
 500                   </row>
 501                   <row>
 502                     <entry>VER</entry>
 503                     <entry>VERSION</entry>
 504                     <entry>Yes</entry>
 505                   </row>
 506                 </tbody>
 507               </tgroup>
 508             </informaltable>
 509           </sect4>
 510
 511           <sect4>
 512             <title>Different Forms Of DLL's</title>
 513             <para>
 514               There are a few different forms of DLL's wine can load:
 515               <variablelist>
 516                 <varlistentry>
 517                   <term>native</term>
 518                   <listitem><para>
 519                       The DLL's that are included with windows. Many
 520                       windows DLL's can be loaded in their native
 521                       form. Many times these native versions work
 522                       better than their non-Microsoft equivalent --
 523                       other times they don't.
 524                     </para></listitem>
 525                 </varlistentry>
 526                 <varlistentry>
 527                   <term>builtin</term>
 528                   <listitem><para>
 529                       The most common form of DLL loading. This is
 530                       what you will use if the DLL is error-prone in
 531                       native form (KERNEL for example), you don't have
 532                       the native DLL, or you just want to be
 533                       Microsoft-free.
 534                     </para></listitem>
 535                 </varlistentry>
 536                 <varlistentry>
 537                   <term>so</term>
 538                   <listitem><para>
 539                       Native ELF libraries. Will not work yet.
 540                     </para></listitem>
 541                 </varlistentry>
 542                 <varlistentry>
 543                   <term>elfdll</term>
 544                   <listitem><para>
 545                       ELF encapsulated windows DLL's.
 546                       No longer used, ignored.
 547                     </para></listitem>
 548                 </varlistentry>
 549               </variablelist>
 550             </para>
 551           </sect4>
 552         </sect3>
 553
 554         <sect3>
 555           <title>The [DllDefaults] Section</title>
 556           <para>
 557             These settings provide wine's default handling of DLL loading.
 558           </para>
 559           <para>
 560             <programlisting>"DefaultLoadOrder" =" native, so, builtin"</programlisting>
 561           </para>
 562           <para>
 563             This setting is a comma-delimited list of the order in
 564             which to attempt loading DLLs. If the first option fails,
 565             it will try the second, and so on. The order specified
 566             above is probably the best in most conditions.
 567           </para>
 568         </sect3>
 569
 570         <sect3>
 571           <title>The [DllPairs] Section</title>
 572           <para>
 573           At one time, there was a section called [DllPairs] in the
 574           default configuration file, but this has been obsoleted
 575           because the pairing information has now been embedded into
 576           Wine itself. (The purpose of this section was merely to be
 577           able to issue warnings if the user attempted to pair
 578           codependent 16-bit/32-bit DLLs of different types.) If you
 579           still have this in your <filename>~/.wine/.config</filename> or
 580           <filename>wine.conf</filename>, you may safely delete it.
 581           </para>
 582         </sect3>
 583
 584         <sect3>
 585           <title>The [DllOverrides] Section</title>
 586           <para>
 587             The format for this section is the same for each line:
 588             <programlisting>
 589 &lt;DLL>{,&lt;DLL>,&lt;DLL>...} = &lt;FORM>{,&lt;FORM>,&lt;FORM>...}
 590             </programlisting>
 591           </para>
 592           <para>
 593             For example, to load builtin KERNEL pair (case doesn't
 594             matter here):
 595             <programlisting>
 596 "kernel,kernel32" = "builtin"
 597             </programlisting>
 598           </para>
 599           <para>
 600             To load the native COMMDLG pair, but if that doesn't work
 601             try builtin:
 602             <programlisting>
 603 "commdlg,comdlg32" = "native,builtin"
 604             </programlisting>
 605           </para>
 606           <para>
 607             To load the native COMCTL32:
 608             <programlisting>
 609 "comctl32" = "native"
 610             </programlisting>
 611           </para>
 612           <para>
 613             Here is a good generic setup (As it is defined in config
 614             that was included with your wine package):
 615             <programlisting>
 616 [DllOverrides]
 617 "rpcrt4"       = "builtin, native"
 618 "oleaut32"     = "builtin, native"
 619 "ole32"        = "builtin, native"
 620 "commdlg"      = "builtin, native"
 621 "comdlg32"     = "builtin, native"
 622 "ver"          = "builtin, native"
 623 "version"      = "builtin, native"
 624 "shell"        = "builtin, native"
 625 "shell32"      = "builtin, native"
 626 "shfolder"     = "builtin, native"
 627 "shlwapi"      = "builtin, native"
 628 "shdocvw"      = "builtin, native"
 629 "lzexpand"     = "builtin, native"
 630 "lz32"         = "builtin, native"
 631 "comctl32"     = "builtin, native"
 632 "commctrl"     = "builtin, native"
 633 "advapi32"     = "builtin, native"
 634 "crtdll"       = "builtin, native"
 635 "mpr"          = "builtin, native"
 636 "winspool.drv" = "builtin, native"
 637 "ddraw"        = "builtin, native"
 638 "dinput"       = "builtin, native"
 639 "dsound"       = "builtin, native"
 640 "opengl32"     = "builtin, native"
 641 "msvcrt"       = "native, builtin"
 642 "msvideo"      = "builtin, native"
 643 "msvfw32"      = "builtin, native"
 644 "mcicda.drv"   = "builtin, native"
 645 "mciseq.drv"   = "builtin, native"
 646 "mciwave.drv"  = "builtin, native"
 647 "mciavi.drv"   = "native, builtin"
 648 "mcianim.drv"  = "native, builtin"
 649 "msacm.drv"    = "builtin, native"
 650 "msacm"        = "builtin, native"
 651 "msacm32"      = "builtin, native"
 652 "midimap.drv"  = "builtin, native"
 653 ; you can specify applications too
 654 "notepad.exe"  = "native, builtin"
 655 ; default for all other dlls
 656 "*" = "native, builtin"
 657             </programlisting>
 658           </para>
 659           <note>
 660             <para>
 661               If loading of the libraries that are listed first fails,
 662               wine will just go on by using the second or third option.
 663             </para>
 664           </note>
 665         </sect3>
 666
 667         <sect3>
 668           <title>The [fonts] Section</title>
 669           <para>
 670             This section sets up wine's font handling.
 671           </para>
 672           <para>
 673             <programlisting>"Resolution" = "96"</programlisting>
 674           </para>
 675           <para>
 676             Since the way X handles fonts is different from the way
 677             Windows does, wine uses a special mechanism to deal with
 678             them. It must scale them using the number defined in the
 679             "Resolution" setting. 60-120 are reasonable values, 96 is
 680             a nice in the middle one. If you have the real windows
 681             fonts available (<filename>&lt;dirs to
 682               wine>/documentation/ttfserver</filename> and
 683             <filename>fonts</filename>), this parameter will not be as
 684             important. Of course, it's always good to get your X fonts
 685             working acceptably in wine.
 686           </para>
 687           <para>
 688             <programlisting>"Default" = "-adobe-times-"</programlisting>
 689             The default font wine uses. Fool around with it if you'd like.
 690           </para>
 691           <para>
 692 OPTIONAL:
 693           </para>
 694           <para>
 695             The <literal>Alias</literal> setting allows you to map an X font to a font
 696             used in wine. This is good for apps that need a special font you don't have,
 697             but a good replacement exists. The syntax is like so:
 698             <programlisting>
 699 "AliasX" = "[Fake windows name],[Real X name]"&lt;,optional "masking" section>
 700             </programlisting>
 701           </para>
 702           <para>
 703             Pretty straightforward. Replace "AliasX" with "Alias0",
 704             then "Alias1" and so on. The fake windows name is the name
 705             that the font will be under a windows app in wine. The
 706             real X name is the font name as seen by X (Run
 707             "xfontsel"). The optional "masking" section allows you to
 708             utilize the fake windows name you define. If it is not
 709             used, then wine will just try to extract the fake windows
 710             name itself and not use the value you enter.
 711           </para>
 712           <para>
 713             Here is an example of an alias without masking. The font will show up in windows
 714             apps as "Google".
 715
 716             <programlisting>
 717 "Alias0" = "Foo,--google-"
 718             </programlisting>
 719           </para>
 720           <para>
 721             Here is an example with masking enabled. The font will show up as "Foo" in
 722             windows apps.
 723             <programlisting>
 724 "Alias1" = "Foo,--google-,subst"
 725             </programlisting>
 726           </para>
 727           <para>
 728             For more info check out the <link linkend="fonts">Fonts</link>
 729             chapter.
 730           </para>
 731         </sect3>
 732
 733         <sect3>
 734           <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
 735           <para>
 736             Even though it sounds like a lot of sections, these are
 737             all closely related. They are all for communications and
 738             parallel ports.
 739           </para>
 740           <para>
 741             The [serialports] section tells wine what serial ports it
 742             is allowed to use.
 743             <programlisting>"ComX" = "/dev/cuaY"</programlisting>
 744           </para>
 745           <para>
 746             Replace <literal>X</literal> with the number of the COM
 747             port in Windows (1-8) and <literal>Y</literal> with the
 748             number of it in <literal>X</literal> (Usually the number
 749             of the port in Windows minus 1). <literal>ComX</literal>
 750             can actually equal any device
 751             (<medialabel>/dev/modem</medialabel> is acceptable). It is
 752             not always necessary to define any COM ports (An optional
 753             setting). Here is an example:
 754             <programlisting>"Com1" = "/dev/cua0"</programlisting>
 755           </para>
 756           <para>
 757             Use as many of these as you like in the section to define
 758             all of the COM ports you need.
 759           </para>
 760           <para>
 761             The [parallelports] section sets up any parallel ports
 762             that will be allowed access under wine.
 763             <programlisting>"LptX" = "/dev/lpY"</programlisting>
 764           </para>
 765           <para>
 766             Sounds familiar? Syntax is just like the COM port setting.
 767             Replace <literal>X</literal> with a value from 1-4 as it
 768             is in Windows and <literal>Y</literal> with a value from
 769             0-3 (<literal>Y</literal> is usually the value in windows
 770             minus 1, just like for COM ports). You don't always need
 771             to define a parallel port (AKA, it's optional). As with
 772             the other section, LptX can equal  any device (Maybe
 773             <medialabel>/dev/printer</medialabel>). Here is an
 774             example:  <programlisting>"Lpt1" = "/dev/lp0"</programlisting>
 775           </para>
 776           <para>
 777             The [spooler] section will inform wine where to spool
 778             print jobs. Use this if you want to try printing. Wine
 779             docs claim that spooling is "rather primitive" at this
 780             time, so it won't work perfectly. IT IS OPTIONAL. The only
 781             setting you use in this section works to map a port (LPT1,
 782             for example) to a file or a command. Here is an example,
 783             mapping LPT1 to the file <filename>out.ps</filename>:
 784             <programlisting>"LPT1:" = "out.ps"</programlisting>
 785           </para>
 786           <para>
 787             The following command maps printing jobs to LPT1 to the
 788             command <command>lpr</command>. Notice  the |:
 789             <programlisting>"LPT1:" = "|lpr"</programlisting>
 790           </para>
 791           <para>
 792             The [ports] section is usually useful only for people who
 793             need direct port access for programs requiring dongles or
 794             scanners. IF YOU DON'T NEED IT, DON'T USE IT!
 795           </para>
 796           <para>
 797             <programlisting>"read" = "0x779,0x379,0x280-0x2a0"</programlisting>
 798             Gives direct read access to those IO's.
 799           </para>
 800           <para>
 801             <programlisting>"write" = "0x779,0x379,0x280-0x2a0"</programlisting>
 802             Gives direct write access to those IO's. It's probably a
 803             good idea to keep the values of the
 804             <literal>read</literal> and <literal>write</literal>
 805             settings the same. This stuff will only work when you're
 806             root.
 807           </para>
 808         </sect3>
 809
 810         <sect3>
 811           <title>The [spy], [Registry], [tweak.layout], and [programs] Sections</title>
 812           <para>
 813             [spy] is used to include or exclude debug messages, and to
 814             output them to a file. The latter is rarely used. THESE
 815             ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
 816             REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
 817           </para>
 818           <para>
 819             <programlisting>"File" = "/blanco"</programlisting>
 820             Sets the logfile for wine. Set to CON to log to standard out.
 821             THIS IS RARELY USED.
 822           </para>
 823           <para>
 824             <programlisting>"Exclude" = "WM_SIZE;WM_TIMER;"</programlisting>
 825             Excludes debug messages about <constant>WM_SIZE</constant>
 826             and <constant>WM_TIMER</constant> in the logfile.
 827           </para>
 828           <para>
 829             <programlisting>"Include" = "WM_SIZE;WM_TIMER;"</programlisting>
 830             Includes debug messages about <constant>WM_SIZE</constant>
 831             and <constant>WM_TIMER</constant> in the logfile.
 832           </para>
 833           <para>
 834             [Registry] can be used to tell wine where your old windows
 835             registry files exist. This section is completely optional
 836             and useless to people using wine without an existing
 837             windows installation.
 838           </para>
 839           <para>
 840             <programlisting>"UserFileName" = "/dirs/to/user.reg"</programlisting>
 841             The location of your old <filename>user.reg</filename> file.
 842           </para>
 843           <para>
 844             [tweak.layout] is devoted to wine's look. There is only
 845             one setting for it.
 846           </para>
 847           <para>
 848             <programlisting>"WineLook" = "win31|win95|win98"</programlisting>
 849             Will change the look of wine from Windows 3.1 to Windows 95.
 850             The <literal>win98</literal> setting behaves
 851             just like <literal>win95</literal> most of the time.
 852           </para>
 853           <para>
 854             [programs] can be used to say what programs run under
 855             special conditions.
 856           </para>
 857           <para>
 858             <programlisting>"Default" = "/program/to/execute.exe"</programlisting>
 859             Sets the program to be run if wine is started without specifying a program.
 860           </para>
 861           <para>
 862             <programlisting>"Startup" = "/program/to/execute.exe"</programlisting>
 863             Sets the program to automatically be run at startup every time.
 864           </para>
 865         </sect3>
 866
 867         <sect3>
 868           <title>The [WinMM] Section</title>
 869           <para>
 870             [WinMM] is used to define which multimedia drivers have to be loaded. Since
 871             those drivers may depend on the multimedia interfaces available on your sustem
 872             (OSS, Alsa... to name a few), it's needed to be able to configure which driver
 873             has to be loaded.
 874           </para>
 875
 876           <para>
 877             The content of the section looks like:
 878             <programlisting>
 879 [WinMM]
 880 "Drivers" = "wineoss.drv"
 881 "WaveMapper" = "msacm.drv"
 882 "MidiMapper" = "midimap.drv"
 883             </programlisting>
 884             All the keys must be defined:
 885             <itemizedlist>
 886               <listitem>
 887                 <para>
 888                   The "Drivers" key is a ';' separated list of modules name, each of
 889                   them containing a low level driver. All those drivers will be loaded
 890                   when MMSYSTEM/WINMM is started and will provide their inner features.
 891                 </para>
 892               </listitem>
 893               <listitem>
 894                 <para>
 895                   The "WaveMapper" represents the name of the module containing the Wave
 896                   Mapper driver. Only one wave mapper can be defined in the system.
 897                 </para>
 898               </listitem>
 899               <listitem>
 900                 <para>
 901                   The "MidiMapper" represents the name of the module containing the MIDI
 902                   Mapper driver. Only one MIDI mapper can be defined in the system.
 903                 </para>
 904               </listitem>
 905             </itemizedlist>
 906           </para>
 907         </sect3>
 908
 909         <sect3>
 910           <title>The [AppDefaults] Section</title>
 911           <para>
 912             The section is used to overwrite certain settings of this file for a
 913             special program with different settings.
 914             [AppDefaults] is not the real name of the section. The real name
 915             consists of the leading word AppDefaults followed by the name
 916             of the executable the section is valid for.
 917             The end of the section name is the name of the
 918             corresponding "standard" section of the configuration file
 919             that should have some of its settings overwritten with the
 920             application specific settings you define.
 921             The three parts of the section name are separated by two backslashes.
 922           </para>
 923           <para>
 924             Currently wine supports only overwriting the sections
 925             [DllOverrides], [x11drv], [version] and [dsound].
 926           </para>
 927           <para>
 928             Here is an example that overwrites the normal settings for a
 929             program:
 930             <programlisting>
 931 ;; default settings
 932 [x11drv]
 933 "Managed" = "Y"
 934 "Desktop" = "N"
 935
 936 ;; run install in desktop mode
 937 [AppDefaults\\install.exe\\x11drv]
 938 "Managed" = "N"
 939 "Desktop" = "800x600"
 940             </programlisting>
 941           </para>
 942         </sect3>
 943       </sect2>
 944
 945       <sect2>
 946         <title>Where Do I Put It?</title>
 947         <para>
 948           The wine config file can go in two places.
 949         </para>
 950         <variablelist>
 951           <varlistentry>
 952             <term><filename>/usr/local/etc/wine.conf</filename></term>
 953             <listitem><para>
 954                 A systemwide config file, used for anyone who doesn't
 955                 have their own. NOTE: this file is currently unused as a
 956                 new global configuration mechanism is not in place at this
 957                 time.
 958             </para></listitem>
 959           </varlistentry>
 960           <varlistentry>
 961             <term><filename>$HOME/.wine/config</filename></term>
 962             <listitem><para>
 963                 Your own config file (which only is used for your user).
 964             </para></listitem>
 965           </varlistentry>
 966         </variablelist>
 967         <para>
 968           So copy your version of the wine config file to
 969           <filename>$HOME/.wine/config</filename>
 970           or <filename>/usr/local/etc/wine.conf</filename>
 971           for wine to recognize it.
 972         </para>
 973       </sect2>
 974
 975       <sect2>
 976         <title>What If It Doesn't Work?</title>
 977         <para>
 978           There is always a chance that things will go wrong. If the
 979           unthinkable happens, report the problem to
 980           <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>,
 981           try the newsgroup
 982           <systemitem>comp.emulators.ms-windows.wine</systemitem>,
 983           or the IRCnet channel <systemitem>#WineHQ</systemitem> found on
 984           irc.stealth.net:6668,  or connected servers.
 985           Make sure that you have looked over this document thoroughly,
 986           and have also read:
 987         </para>
 988         <itemizedlist>
 989           <listitem>
 990             <para><filename>README</filename></para>
 991           </listitem>
 992           <listitem>
 993             <para>
 994               <filename>http://www.winehq.org/trouble/</filename>
 995             </para>
 996           </listitem>
 997         </itemizedlist>
 998         <para>
 999           If indeed it looks like you've done your research, be
1000           prepared for helpful suggestions. If you haven't, brace
1001           yourself for heaving flaming.
1002         </para>
1003       </sect2>
1004     </sect1>
1005
1006     <sect1 id="x11drv">
1007       <title>Configuring the x11drv Driver</title>
1008
1009       <para>
1010         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1011       </para>
1012       <para>
1013         (Extracted from <filename>wine/documentation/x11drv</filename>)
1014       </para>
1015
1016       <para>
1017         Most Wine users run Wine under the windowing system known as
1018         X11. During most of Wine's history, this was the only display
1019         driver available, but in recent years, parts of Wine has been
1020         reorganized to allow for other display drivers (although the
1021         only alternative currently available is Patrik Stridvall's
1022         ncurses-based ttydrv, which he claims works for displaying
1023         calc.exe). The display driver is chosen with the
1024         <literal>GraphicsDriver</literal> option in the [wine] section
1025         of <filename>~/.wine/config</filename>, but I will only cover the
1026         x11drv driver in this article.
1027       </para>
1028
1029       <sect2>
1030         <title>x11drv modes of operation</title>
1031
1032         <para>
1033           <!-- FIXME: This is outdated -->
1034           Note: This is now all done in the config file. Needs an update...
1035         </para>
1036
1037         <para>
1038           The x11drv driver consists of two conceptually distinct
1039           pieces, the graphics driver (GDI part), and the windowing
1040           driver (USER part). Both of these are linked into the
1041           <filename>libx11drv.so</filename> module, though (which you
1042           load with the <literal>GraphicsDriver</literal> option). In
1043           Wine, running on X11, the graphics driver must draw on
1044           drawables (window interiors) provided by the windowing
1045           driver. This differs a bit from the Windows model, where the
1046           windowing system creates and configures device contexts
1047           controlled by the graphics driver, and applications are
1048           allowed to hook into this relationship anywhere they like.
1049           Thus, to provide any reasonable tradeoff between
1050           compatibility and usability, the x11drv has three different
1051           modes of operation.
1052         </para>
1053
1054         <variablelist>
1055           <varlistentry>
1056             <term>Unmanaged/Normal</term>
1057             <listitem>
1058               <para>
1059                 The default. Window-manager-independent (any running
1060                 window manager is ignored completely). Window
1061                 decorations (title bars, borders, etc) are drawn by
1062                 Wine to look and feel like the real Windows. This is
1063                 compatible with applications that depend on being able
1064                 to compute the exact sizes of any such decorations, or
1065                 that want to draw their own.
1066               </para>
1067             </listitem>
1068           </varlistentry>
1069           <varlistentry>
1070             <term>Managed</term>
1071             <listitem>
1072               <para>
1073                 Specified by using the <literal>Managed</literal>
1074                 wine config file option (see below).
1075                 Ordinary top-level frame windows with thick borders,
1076                 title bars, and system menus will be managed by your
1077                 window manager. This lets these applications integrate
1078                 better with the rest of your desktop, but may not
1079                 always work perfectly. (A rewrite of this mode of
1080                 operation, to make it more robust and less patchy, is
1081                 highly desirable, though, and is planned to be done
1082                 before the Wine 1.0 release.)
1083               </para>
1084             </listitem>
1085           </varlistentry>
1086           <varlistentry>
1087             <term>Desktop-in-a-Box</term>
1088             <listitem>
1089               <para>
1090                 Specified by using the <literal>Desktop</literal>
1091                 wine config file option (see below).
1092                 (adding a geometry, e.g. <literal>800x600</literal>
1093                 for a such-sized desktop, or
1094                 even <literal>800x600+0+0</literal> to
1095                 automatically position the desktop at the upper-left
1096                 corner of the display). This is the mode most
1097                 compatible with the Windows model. All application
1098                 windows will just be Wine-drawn windows inside the
1099                 Wine-provided desktop window (which will itself be
1100                 managed by your window manager), and Windows
1101                 applications can roam freely within this virtual
1102                 workspace and think they own it all, without
1103                 disturbing your other X apps.
1104                 Note: currently there's on desktop window for every
1105                 application; this will be fixed in the future.
1106               </para>
1107             </listitem>
1108           </varlistentry>
1109         </variablelist>
1110       </sect2>
1111
1112       <sect2>
1113         <title>The [x11drv] section</title>
1114
1115         <variablelist>
1116           <varlistentry>
1117             <term>Managed</term>
1118             <listitem>
1119               <para>
1120                 Wine can let frame windows be managed by your window
1121                 manager. This option specifies whether you want that
1122                 by default.
1123               </para>
1124             </listitem>
1125           </varlistentry>
1126           <varlistentry>
1127             <term>Desktop</term>
1128             <listitem>
1129               <para>
1130                 Creates a main desktop window of a specified size
1131                 to display all Windows applications in.
1132                 The size argument could e.g. be "800x600".
1133               </para>
1134             </listitem>
1135           </varlistentry>
1136           <varlistentry>
1137             <term>DXGrab</term>
1138             <listitem>
1139               <para>
1140                 If you don't use DGA, you may want an alternative
1141                 means to convince the mouse cursor to stay within the
1142                 game window. This option does that. Of course, as with
1143                 DGA, if Wine crashes, you're in trouble (although not
1144                 as badly as in the DGA case, since you can still use
1145                 the keyboard to get out of X).
1146               </para>
1147             </listitem>
1148           </varlistentry>
1149           <varlistentry>
1150             <term>UseDGA</term>
1151             <listitem>
1152               <para>
1153                 This specifies whether you want DirectDraw to use
1154                 XFree86's <firstterm>Direct Graphics
1155                   Architecture</firstterm> (DGA), which is able to
1156                 take over the entire display and run the game
1157                 full-screen at maximum speed. (With DGA1 (XFree86
1158                 3.x), you still have to configure the X server to the
1159                 game's requested bpp first, but with DGA2 (XFree86
1160                 4.x), runtime depth-switching may be possible,
1161                 depending on your driver's capabilities.) But be aware
1162                 that if Wine crashes while in DGA mode, it may not be
1163                 possible to regain control over your computer without
1164                 rebooting. DGA normally requires either root
1165                 privileges or read/write access to
1166                 <filename>/dev/mem</filename>.
1167               </para>
1168             </listitem>
1169           </varlistentry>
1170           <varlistentry>
1171             <term>UseXShm</term>
1172             <listitem>
1173               <para>
1174                 If you don't want DirectX to use DGA, you can at least
1175                 use X Shared Memory extensions (XShm). It is much
1176                 slower than DGA, since the app doesn't have direct
1177                 access to the physical frame buffer, but using shared
1178                 memory to draw the frame is at least faster than
1179                 sending the data through the standard X11 socket, even
1180                 though Wine's XShm support is still known to crash
1181                 sometimes.
1182               </para>
1183             </listitem>
1184           </varlistentry>
1185           <varlistentry>
1186             <term>DesktopDoubleBuffered</term>
1187             <listitem>
1188               <para>
1189                 Applies only if you use the
1190                 <parameter>--desktop</parameter> command-line option
1191                 to run in a desktop window. Specifies whether to
1192                 create the desktop window with a double-buffered
1193                 visual, something most OpenGL games need to run
1194                 correctly.
1195               </para>
1196             </listitem>
1197           </varlistentry>
1198           <varlistentry>
1199             <term>AllocSystemColors</term>
1200             <listitem>
1201               <para>
1202                 Applies only if you have a palette-based display, i.e.
1203                 if your X server is set to a depth of 8bpp, and if you
1204                 haven't requested a private color map. It specifies
1205                 the maximum number of shared colormap cells (palette
1206                 entries) Wine should occupy. The higher this value,
1207                 the less colors will be available to other
1208                 applications.
1209               </para>
1210             </listitem>
1211           </varlistentry>
1212           <varlistentry>
1213             <term>PrivateColorMap</term>
1214             <listitem>
1215               <para>
1216                 Applies only if you have a palette-based display, i.e.
1217                 if your X server is set to a depth of 8bpp. It
1218                 specifies that you don't want to use the shared color
1219                 map, but a private color map, where all 256 colors are
1220                 available. The disadvantage is that Wine's private
1221                 color map is only seen while the mouse pointer is
1222                 inside a Wine window, so psychedelic flashing and
1223                 funky colors will become routine if you use the mouse
1224                 a lot.
1225               </para>
1226             </listitem>
1227           </varlistentry>
1228           <varlistentry>
1229             <term>Synchronous</term>
1230             <listitem>
1231               <para>
1232                 To be used for debugging X11 operations.
1233                 If Wine crashes with an X11 error, then you should enable
1234                 Synchronous mode to disable X11 request caching in order
1235                 to make sure that the X11 error happens directly after
1236                 the corresponding X11 call in the log file appears.
1237                 Will slow down X11 output !
1238               </para>
1239             </listitem>
1240           </varlistentry>
1241           <varlistentry>
1242             <term>ScreenDepth</term>
1243             <listitem>
1244               <para>
1245                 Applies only to multi-depth displays. It specifies
1246                 which of the available depths Wine should use (and
1247                 tell Windows apps about).
1248               </para>
1249             </listitem>
1250           </varlistentry>
1251           <varlistentry>
1252             <term>Display</term>
1253             <listitem>
1254               <para>
1255                 This specifies which X11 display to use, and if
1256                 specified, will override the
1257                 <envar>DISPLAY</envar> environment variable.
1258               </para>
1259             </listitem>
1260           </varlistentry>
1261           <varlistentry>
1262             <term>PerfectGraphics</term>
1263             <listitem>
1264               <para>
1265                 This option only determines whether fast X11 routines
1266                 or exact Wine routines will be used for certain ROP
1267                 codes in blit operations. Most users won't notice any
1268                 difference.
1269               </para>
1270             </listitem>
1271           </varlistentry>
1272           <varlistentry>
1273             <term>TextCP</term>
1274             <listitem>
1275               <para>
1276                 <!-- FIXME: To be documented -->
1277                 To be documented...
1278               </para>
1279             </listitem>
1280           </varlistentry>
1281           <varlistentry>
1282             <term>XVideoPort</term>
1283             <listitem>
1284               <para>
1285                 <!-- FIXME: To be documented -->
1286                 To be documented...
1287               </para>
1288             </listitem>
1289           </varlistentry>
1290         </variablelist>
1291       </sect2>
1292     </sect1>
1293
1294     &registry;
1295
1296     <sect1 id="cdrom-labels">
1297       <sect1info>
1298         <authorgroup>
1299           <author>
1300             <firstname>Petr</firstname>
1301             <surname>Tomasek</surname>
1302             <affiliation>
1303               <address><email>&email-petr-tomasek;</email></address>
1304             </affiliation>
1305             <contrib>Nov 14 1999</contrib>
1306           </author>
1307           <author>
1308             <firstname>Andreas</firstname>
1309             <surname>Mohr</surname>
1310             <affiliation>
1311               <address><email>&email-andreas-mohr;</email></address>
1312             </affiliation>
1313             <contrib>Jan 25 2000</contrib>
1314           </author>
1315         </authorgroup>
1316       </sect1info>
1317
1318       <title>Drive labels and serial numbers with wine</title>
1319       <para>
1320         Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
1321         Nov 14 1999
1322       </para>
1323       <para>
1324         Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1325         Jan 25 2000
1326       </para>
1327       <para>
1328         (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1329       </para>
1330       <para>
1331         Until now, your only possibility of specifying drive volume
1332         labels and serial numbers was to set them manually in the wine
1333         config file. By now, wine can read them directly from the
1334         device as well. This may be useful for many Win 9x games or
1335         for setup programs distributed on CD-ROMs that check for
1336         volume label.
1337       </para>
1338
1339       <sect2>
1340         <title>What's Supported?</title>
1341
1342         <informaltable frame="all">
1343           <tgroup cols="3">
1344             <thead>
1345               <row>
1346                 <entry>File System</entry>
1347                 <entry>Types</entry>
1348                 <entry>Comment</entry>
1349               </row>
1350             </thead>
1351             <tbody>
1352               <row>
1353                 <entry>FAT systems</entry>
1354                 <entry>hd, floppy</entry>
1355                 <entry>reads labels and serial numbers</entry>
1356               </row>
1357               <row>
1358                 <entry>ISO9660</entry>
1359                 <entry>cdrom</entry>
1360                 <entry>reads labels and serial numbers (not mixed-mode CDs yet !)</entry>
1361               </row>
1362             </tbody>
1363           </tgroup>
1364         </informaltable>
1365
1366       </sect2>
1367
1368       <sect2>
1369         <title>How To Set Up?</title>
1370         <para>
1371           Reading labels and serial numbers just works automagically
1372           if you specify a <literal>Device=</literal> line in the
1373           [Drive X] section in your <filename>~/.wine/config</filename>.
1374           Note that the device has to exist and must be accessible if
1375           you do this, though.
1376         </para>
1377         <para>
1378           If you don't do that, then you should give fixed
1379           <literal>"Label" =</literal> or <literal>"Serial" =</literal>
1380           entries in <filename>~./wine/config</filename>, as Wine returns
1381           these entries instead if no device is given. If they don't
1382           exist, then Wine will return default values (label
1383           <literal>Drive X</literal> and serial
1384           <literal>12345678</literal>).
1385         </para>
1386         <para>
1387           If you want to give a <literal>"Device" =</literal> entry
1388           <emphasis>only</emphasis> for drive raw sector accesses,
1389           but not for reading the volume info from the device (i.e. you want
1390           a <emphasis>fixed</emphasis>, preconfigured label), you need
1391           to specify <literal>"ReadVolInfo" = "0"</literal> to tell Wine
1392           to skip the volume reading.
1393         </para>
1394       </sect2>
1395
1396       <sect2>
1397         <title>EXAMPLES</title>
1398         <para>
1399           Here's a simple example of cdrom and floppy; labels will be
1400           read from the device on both cdrom and floppy; serial
1401           numbers on floppy only:
1402         </para>
1403         <screen>
1404 [Drive A]
1405 "Path" = "/mnt/floppy"
1406 "Type" = "floppy"
1407 "Device" = "/dev/fd0"
1408 "Filesystem" = "msdos"
1409
1410 [Drive R]
1411 "Path" = "/mnt/cdrom"
1412 "Type" = "cdrom"
1413 "Device" = "/dev/hda1"
1414 "Filesystem" = "win95"
1415         </screen>
1416         <para>
1417           Here's an example of overriding the CD-ROM label:
1418         </para>
1419         <screen>
1420 [Drive J]
1421 "Path" = "/mnt/cdrom"
1422 "Type" = "cdrom"
1423 "Label" = "X234GCDSE"
1424 ; note that the device isn't really needed here as we have a fixed label
1425 "Device" = "/dev/cdrom"
1426 "Filesystem" = "msdos"
1427         </screen>
1428       </sect2>
1429
1430       <sect2>
1431         <title>Todo / Open Issues</title>
1432         <itemizedlist>
1433           <listitem> <para>
1434               The cdrom label can be read only if the data track of
1435               the disk resides in the first track and the cdrom is
1436               iso9660.
1437             </para> </listitem>
1438           <listitem> <para>
1439               Better checking for FAT superblock (it now checks only
1440               one byte). </para>
1441           </listitem>
1442           <listitem> <para>
1443               Support for labels/serial nums WRITING.
1444             </para> </listitem>
1445           <listitem> <para>
1446               Can the label be longer than 11 chars? (iso9660 has 32
1447               chars).
1448             </para> </listitem>
1449           <listitem> <para>
1450               What about reading ext2 volume label? ....
1451             </para> </listitem>
1452         </itemizedlist>
1453       </sect2>
1454     </sect1>
1455
1456     <sect1 id="dll-config">
1457       <title>DLL configuration</title>
1458       <sect2 id="dll-overrides">
1459         <title>DLL Overrides</title>
1460
1461         <para>
1462           Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1463         </para>
1464         <para>
1465           (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1466         </para>
1467
1468         <para>
1469           The wine config file directives [DllDefaults]
1470           and [DllOverrides] are the subject of some confusion. The
1471           overall purpose of most of these directives are clear enough,
1472           though - given a choice, should Wine use its own built-in
1473           DLLs, or should it use <filename>.DLL</filename> files found
1474           in an existing Windows installation? This document explains
1475           how this feature works.
1476         </para>
1477
1478         <sect3>
1479           <title>DLL types</title>
1480           <variablelist>
1481             <varlistentry>
1482               <term>native</term>
1483               <listitem> <para>
1484                   A "native" DLL is a <filename>.DLL</filename> file
1485                   written for the real Microsoft Windows.
1486                 </para> </listitem>
1487             </varlistentry>
1488             <varlistentry>
1489               <term>builtin</term>
1490               <listitem> <para>
1491                   A "builtin" DLL is a Wine DLL. These can either be a
1492                   part of <filename>libwine.so</filename>, or more
1493                   recently, in a special <filename>.so</filename> file
1494                   that Wine is able to load on demand.
1495                 </para> </listitem>
1496             </varlistentry>
1497             <varlistentry>
1498               <term>so</term>
1499               <listitem> <para>
1500                   A native Unix <filename>.so</filename> file, with
1501                   calling convention conversion thunks generated on the
1502                   fly as the library is loaded. This is mostly useful
1503                   for libraries such as "glide" that have exactly the
1504                   same API on both Windows and Unix.
1505                 </para> </listitem>
1506             </varlistentry>
1507           </variablelist>
1508         </sect3>
1509
1510         <sect3>
1511           <title>The [DllDefaults] section</title>
1512           <variablelist>
1513             <varlistentry>
1514               <term>DefaultLoadOrder</term>
1515               <listitem> <para>
1516                   This specifies in what order Wine should search for
1517                   available DLL types, if the DLL in question was not
1518                   found in the [DllOverrides] section.
1519                 </para> </listitem>
1520             </varlistentry>
1521           </variablelist>
1522         </sect3>
1523
1524         <sect3>
1525           <title>The [DllPairs] section</title>
1526           <para>
1527             At one time, there was a section called [DllPairs] in the
1528             default configuration file, but this has been obsoleted
1529             because the pairing information has now been embedded into
1530             Wine itself. (The purpose of this section was merely to be
1531             able to issue warnings if the user attempted to pair
1532             codependent 16-bit/32-bit DLLs of different types.) If you
1533             still have this in your <filename>~/.wine/config</filename> or
1534             <filename>wine.conf</filename>, you may safely delete it.
1535           </para>
1536         </sect3>
1537
1538         <sect3>
1539           <title>The [DllOverrides] section</title>
1540           <para>
1541             This section specifies how you want specific DLLs to be
1542             handled, in particular whether you want to use "native" DLLs
1543             or not, if you have some from a real Windows configuration.
1544             Because builtins do not mix seamlessly with native DLLs yet,
1545             certain DLL dependencies may be problematic, but workarounds
1546             exist in Wine for many popular DLL configurations. Also see
1547             WWN's [16]Status Page to figure out how well your favorite
1548             DLL is implemented in Wine.
1549           </para>
1550           <para>
1551             It is of course also possible to override these settings by
1552             explictly using Wine's <parameter>--dll</parameter>
1553             command-line option (see the man page for details).  Some
1554             hints for choosing your optimal configuration (listed by
1555             16/32-bit DLL pair):
1556           </para>
1557           <variablelist>
1558             <varlistentry>
1559               <term>krnl386, kernel32</term>
1560               <listitem> <para>
1561                   Native versions of these will never work, so don't try. Leave
1562                   at <literal>builtin</literal>.
1563                 </para> </listitem>
1564             </varlistentry>
1565             <varlistentry>
1566               <term>gdi, gdi32</term>
1567               <listitem> <para>
1568                   Graphics Device Interface. No effort has been made at trying to
1569                   run native GDI. Leave at <literal>builtin</literal>.
1570                 </para> </listitem>
1571             </varlistentry>
1572             <varlistentry>
1573               <term>user, user32</term>
1574               <listitem> <para>
1575                   Window management and standard controls. It was
1576                   possible to use Win95's <literal>native</literal>
1577                   versions at some point (if all other DLLs that depend
1578                   on it, such as comctl32 and comdlg32, were also run
1579                   <literal>native</literal>). However, this is no longer
1580                   possible after the Address Space Separation, so leave
1581                   at <literal>builtin</literal>.
1582                 </para> </listitem>
1583             </varlistentry>
1584             <varlistentry>
1585               <term>ntdll</term>
1586               <listitem> <para>
1587                   NT kernel API. Although badly documented, the
1588                   <literal>native</literal> version of this will never
1589                   work. Leave at <literal>builtin</literal>.
1590                 </para> </listitem>
1591             </varlistentry>
1592             <varlistentry>
1593               <term>w32skrnl</term>
1594               <listitem> <para>
1595                   Win32s (for Win3.x). The <literal>native</literal>
1596                   version will probably never work. Leave at
1597                   <literal>builtin</literal>.
1598                 </para> </listitem>
1599             </varlistentry>
1600             <varlistentry>
1601               <term>wow32</term>
1602               <listitem> <para>
1603                   Win16 support library for NT. The
1604                   <literal>native</literal> version will probably never
1605                   work. Leave at <literal>builtin</literal>.
1606                 </para> </listitem>
1607             </varlistentry>
1608             <varlistentry>
1609               <term>system</term>
1610               <listitem> <para>
1611                   Win16 kernel stuff. Will never work
1612                   <literal>native</literal>. Leave at
1613                   <literal>builtin</literal>.
1614                 </para> </listitem>
1615             </varlistentry>
1616             <varlistentry>
1617               <term>display</term>
1618               <listitem> <para>
1619                   Display driver. Definitely leave at <literal>builtin</literal>.
1620                 </para> </listitem>
1621             </varlistentry>
1622             <varlistentry>
1623               <term>toolhelp</term>
1624               <listitem> <para>
1625                   Tool helper routines. This is rarely a source of problems.
1626                   Leave at <literal>builtin</literal>.
1627                 </para> </listitem>
1628             </varlistentry>
1629             <varlistentry>
1630               <term>ver, version</term>
1631               <listitem> <para>
1632                   Versioning. Seldom useful to mess with.
1633                 </para> </listitem>
1634             </varlistentry>
1635             <varlistentry>
1636               <term>advapi32</term>
1637               <listitem> <para>
1638                   Registry and security features. Trying the
1639                   <literal>native</literal> version of this may or may
1640                   not work.
1641                 </para> </listitem>
1642             </varlistentry>
1643             <varlistentry>
1644               <term>commdlg, comdlg32</term>
1645               <listitem> <para>
1646                   Common Dialogs, such as color picker, font dialog,
1647                   print dialog, open/save dialog, etc. It is safe to try
1648                   <literal>native</literal>.
1649                 </para> </listitem>
1650             </varlistentry>
1651             <varlistentry>
1652               <term>commctrl, comctl32</term>
1653               <listitem> <para>
1654                   Common Controls. This is toolbars, status bars, list controls,
1655                   the works. It is safe to try <literal>native</literal>.
1656                 </para> </listitem>
1657             </varlistentry>
1658             <varlistentry>
1659               <term>shell, shell32</term>
1660               <listitem> <para>
1661                   Shell interface (desktop, filesystem, etc). Being one of the
1662                   most undocumented pieces of Windows, you may have luck with the
1663                   <literal>native</literal> version, should you need it.
1664                 </para> </listitem>
1665             </varlistentry>
1666             <varlistentry>
1667               <term>winsock, wsock32</term>
1668               <listitem> <para>
1669                   Windows Sockets. The <literal>native</literal> version
1670                   will not work under Wine, so leave at
1671                   <literal>builtin</literal>.
1672                 </para> </listitem>
1673             </varlistentry>
1674             <varlistentry>
1675               <term>icmp</term>
1676               <listitem> <para>
1677                   ICMP routines for wsock32. As with wsock32, leave at
1678                   <literal>builtin</literal>.
1679                 </para> </listitem>
1680             </varlistentry>
1681             <varlistentry>
1682               <term>mpr</term>
1683               <listitem> <para>
1684                   The <literal>native</literal> version may not work due
1685                   to thunking issues. Leave at
1686                   <literal>builtin</literal>.
1687                 </para> </listitem>
1688             </varlistentry>
1689             <varlistentry>
1690               <term>lzexpand, lz32</term>
1691               <listitem> <para>
1692                   Lempel-Ziv decompression. Wine's
1693                   <literal>builtin</literal> version ought to work fine.
1694                 </para> </listitem>
1695             </varlistentry>
1696             <varlistentry>
1697               <term>winaspi, wnaspi32</term>
1698               <listitem> <para>
1699                   Advanced SCSI Peripheral Interface. The
1700                   <literal>native</literal> version will probably never
1701                   work. Leave at <literal>builtin</literal>.
1702                 </para> </listitem>
1703             </varlistentry>
1704             <varlistentry>
1705               <term>crtdll</term>
1706               <listitem> <para>
1707                   C Runtime library. The <literal>native</literal>
1708                   version will easily work better than Wine's on this
1709                   one.
1710                 </para> </listitem>
1711             </varlistentry>
1712             <varlistentry>
1713               <term>winspool.drv</term>
1714               <listitem> <para>
1715                   Printer spooler. You are not likely to have more luck
1716                   with the <literal>native</literal> version.
1717                 </para> </listitem>
1718             </varlistentry>
1719             <varlistentry>
1720               <term>ddraw</term>
1721               <listitem> <para>
1722                   DirectDraw/Direct3D. Since Wine does not implement the
1723                   DirectX HAL, the <literal>native</literal> version
1724                   will not work at this time.
1725                 </para> </listitem>
1726             </varlistentry>
1727             <varlistentry>
1728               <term>dinput</term>
1729               <listitem> <para>
1730                   DirectInput. Running this <literal>native</literal>
1731                   may or may not work.
1732                 </para> </listitem>
1733             </varlistentry>
1734             <varlistentry>
1735               <term>dsound</term>
1736               <listitem> <para>
1737                   DirectSound. It may be possible to run this
1738                   <literal>native</literal>, but don't count on it.
1739                 </para> </listitem>
1740             </varlistentry>
1741             <varlistentry>
1742               <term>dplay/dplayx</term>
1743               <listitem> <para>
1744                   DirectPlay. The <literal>native</literal> version
1745                   ought to work best on this, if at all.
1746                 </para> </listitem>
1747             </varlistentry>
1748             <varlistentry>
1749               <term>mmsystem, winmm</term>
1750               <listitem> <para>
1751                   Multimedia system. The <literal>native</literal>
1752                   version is not likely to work. Leave at
1753                   <literal>builtin</literal>.
1754                 </para> </listitem>
1755             </varlistentry>
1756             <varlistentry>
1757               <term>msacm, msacm32</term>
1758               <listitem> <para>
1759                   Audio Compression Manager. The
1760                   <literal>builtin</literal> version works best, if you
1761                   set msacm.drv to the same.
1762                 </para> </listitem>
1763             </varlistentry>
1764             <varlistentry>
1765               <term>msvideo, msvfw32</term>
1766               <listitem> <para>
1767                   Video for Windows. It is safe (and recommended) to try
1768                   <literal>native</literal>.
1769                 </para> </listitem>
1770             </varlistentry>
1771             <varlistentry>
1772               <term>mcicda.drv</term>
1773               <listitem> <para>
1774                   CD Audio MCI driver.
1775                 </para> </listitem>
1776             </varlistentry>
1777             <varlistentry>
1778               <term>mciseq.drv</term>
1779               <listitem> <para>
1780                   MIDI Sequencer MCI driver (<filename>.MID</filename>
1781                   playback).
1782                 </para> </listitem>
1783             </varlistentry>
1784             <varlistentry>
1785               <term>mciwave.drv</term>
1786               <listitem> <para>
1787                   Wave audio MCI driver (<filename>.WAV</filename> playback).
1788                 </para> </listitem>
1789             </varlistentry>
1790             <varlistentry>
1791               <term>mciavi.drv</term>
1792               <listitem> <para>
1793                   AVI MCI driver (<filename>.AVI</filename> video
1794                   playback). Best to use <literal>native</literal>.
1795                 </para> </listitem>
1796             </varlistentry>
1797             <varlistentry>
1798               <term>mcianim.drv</term>
1799               <listitem> <para>
1800                   Animation MCI driver.
1801                 </para> </listitem>
1802             </varlistentry>
1803             <varlistentry>
1804               <term>msacm.drv</term>
1805               <listitem> <para>
1806                   Audio Compression Manager. Set to same as msacm32.
1807                 </para> </listitem>
1808             </varlistentry>
1809             <varlistentry>
1810               <term>midimap.drv</term>
1811               <listitem> <para>
1812                   MIDI Mapper.
1813                 </para> </listitem>
1814             </varlistentry>
1815             <varlistentry>
1816               <term>wprocs</term>
1817               <listitem> <para>
1818                   This is a pseudo-DLL used by Wine for thunking
1819                   purposes. A <literal>native</literal> version of this
1820                   doesn't exist.
1821                 </para> </listitem>
1822             </varlistentry>
1823           </variablelist>
1824         </sect3>
1825       </sect2>
1826       <sect2 id="dll-missing">
1827         <title>Missing DLLs</title>
1828
1829         <para>
1830           Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1831         </para>
1832
1833         <para>
1834           In case Wine complains about a missing DLL, you should check whether
1835           this file is a publicly available DLL or a custom DLL belonging
1836           to your program (by searching for its name on the internet).
1837           If you managed to get hold of the DLL, then you should make sure
1838           that Wine is able to find and load it.
1839           DLLs usually get loaded according to the mechanism of the
1840           SearchPath() function.
1841           This function searches directories in the following order:
1842
1843           <orderedlist>
1844             <listitem>
1845               <para>
1846                 The directory the program was started from.
1847               </para>
1848             </listitem>
1849             <listitem>
1850               <para>
1851                 The current directory.
1852               </para>
1853             </listitem>
1854             <listitem>
1855               <para>
1856                 The Windows system directory.
1857               </para>
1858             </listitem>
1859             <listitem>
1860               <para>
1861                 The Windows directory.
1862               </para>
1863             </listitem>
1864             <listitem>
1865               <para>
1866                 The PATH variable directories.
1867               </para>
1868             </listitem>
1869           </orderedlist>
1870
1871           In short: either put the required DLL into your application
1872           directory (might be ugly), or usually put it into the Windows system
1873           directory. Just find out its directory by having a look at the Wine
1874           config File variable "System" (which indicates the location of the
1875           Windows system directory) and the associated drive entry.
1876         </para>
1877       </sect2>
1878     </sect1>
1879
1880     &fonts;
1881     &printing;
1882
1883     <sect1 id="win95look">
1884       <title>Win95/98 Look</title>
1885       <para>
1886         Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
1887       </para>
1888       <para>
1889         (Extracted from <filename>wine/documentation/win95look</filename>)
1890       </para>
1891       <para>
1892         Win95/Win98 interface code is being introduced.
1893       </para>
1894       <para>
1895         Instead of compiling Wine for Win3.1 vs. Win95 using
1896         <constant>#define</constant> switches, the code now looks in a
1897         special [Tweak.Layout] section of
1898         <filename>~/.wine/config</filename> for a
1899         <literal>"WineLook" = "Win95"</literal> or
1900         <literal>"WineLook" = "Win98"</literal> entry.
1901       </para>
1902       <para>
1903         A few new sections and a number of entries have been added to
1904         the <filename>~/.wine/config</filename> file -- these are for
1905         debugging the Win95 tweaks only and may be removed in a future
1906         release!  These entries/sections are:
1907       </para>
1908       <programlisting>
1909 [Tweak.Fonts]
1910 "System.Height" = "&lt;point size>"    # Sets the height of the system typeface
1911 "System.Bold" = "[true|false]"      # Whether the system font should be boldfaced
1912 "System.Italic" = "[true|false]"    # Whether the system font should be italicized
1913 "System.Underline" = "[true|false]" # Whether the system font should be underlined
1914 "System.StrikeOut" = "[true|false]" # Whether the system font should be struck out
1915 "OEMFixed.xxx"                  # Same parameters for the OEM fixed typeface
1916 "AnsiFixed.xxx"                 # Same parameters for the Ansi fixed typeface
1917 "AnsiVar.xxx"                   # Same parameters for the Ansi variable typeface
1918 "SystemFixed.xxx"               # Same parameters for the System fixed typeface
1919
1920 [Tweak.Layout]
1921 "WineLook" = "[Win31|Win95|Win98]"  # Changes Wine's look and feel
1922       </programlisting>
1923     </sect1>
1924
1925     <sect1 id="keyboard">
1926       <title>Keyboard</title>
1927
1928       <para>
1929         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1930       </para>
1931       <para>
1932         (Extracted from <filename>wine/documentation/keyboard</filename>)
1933       </para>
1934
1935       <para>
1936         Wine now needs to know about your keyboard layout. This
1937         requirement comes from a need from many apps to have the
1938         correct scancodes available, since they read these directly,
1939         instead of just taking the characters returned by the X
1940         server. This means that Wine now needs to have a mapping from
1941         X keys to the scancodes these applications expect.
1942       </para>
1943       <para>
1944         On startup, Wine will try to recognize the active X layout by
1945         seeing if it matches any of the defined tables. If it does,
1946         everything is alright. If not, you need to define it.
1947       </para>
1948       <para>
1949         To do this, open the file
1950         <filename>dlls/x11drv/keyboard.c</filename> and take a look
1951         at the existing tables. Make a backup copy of it, especially
1952         if you don't use CVS.
1953       </para>
1954       <para>
1955         What you really would need to do, is find out which scancode
1956         each key needs to generate.  Find it in the
1957         <function>main_key_scan</function> table, which looks like
1958         this:
1959       </para>
1960       <programlisting>
1961 static const int main_key_scan[MAIN_LEN] =
1962 {
1963 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1964    0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
1965    0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
1966    0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
1967    0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
1968    0x56 /* the 102nd key (actually to the right of l-shift) */
1969 };
1970       </programlisting>
1971       <para>
1972         Next, assign each scancode the characters imprinted on the
1973         keycaps. This was done (sort of) for the US 101-key keyboard,
1974         which you can find near the top in
1975         <filename>keyboard.c</filename>. It also shows that if there
1976         is no 102nd key, you can skip that.
1977       </para>
1978       <para>
1979         However, for most international 102-key keyboards, we have
1980         done it easy for you. The scancode layout for these already
1981         pretty much matches the physical layout in the
1982         <function>main_key_scan</function>, so all you need to do is
1983         to go through all the keys that generate characters on your
1984         main keyboard (except spacebar), and stuff those into an
1985         appropriate table. The only exception is that the 102nd key,
1986         which is usually to the left of the first key of the last line
1987         (usually <keycap>Z</keycap>), must be placed on a separate
1988         line after the last line.
1989       </para>
1990       <para>
1991         For example, my Norwegian keyboard looks like this
1992       </para>
1993       <screen>
1994 §  !  "  #  ¤  %  &  /  (  )  =  ?  `  Back-
1995 |  1  2@ 3£ 4$ 5  6  7{ 8[ 9] 0} +  \´ space
1996
1997 Tab Q  W  E  R  T  Y  U  I  O  P  Å  ^
1998                                      ¨~
1999                                         Enter
2000 Caps A  S  D  F  G  H  J  K  L  Ø  Æ  *
2001 Lock                                  '
2002
2003 Sh- > Z  X  C  V  B  N  M  ;  :  _  Shift
2004 ift &lt;                      ,  .  -
2005
2006 Ctrl  Alt       Spacebar       AltGr  Ctrl
2007       </screen>
2008       <para>
2009         Note the 102nd key, which is the <keycap>&lt;></keycap> key, to
2010         the left of <keycap>Z</keycap>. The character to the right of
2011         the main character is the character generated by
2012         <keycap>AltGr</keycap>.
2013       </para>
2014       <para>
2015         This keyboard is defined as follows:
2016       </para>
2017       <programlisting>
2018 static const char main_key_NO[MAIN_LEN][4] =
2019 {
2020  "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
2021  "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
2022  "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
2023  "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
2024  "&lt;>"
2025 };
2026       </programlisting>
2027       <para>
2028         Except that " and \ needs to be quoted with a backslash, and
2029         that the 102nd key is on a separate line, it's pretty
2030         straightforward.
2031       </para>
2032       <para>
2033         After you have written such a table, you need to add it to the
2034         <function>main_key_tab[]</function> layout index table. This
2035         will look like this:
2036       </para>
2037       <programlisting>
2038 static struct {
2039  WORD lang, ansi_codepage, oem_codepage;
2040  const char (*key)[MAIN_LEN][4];
2041 } main_key_tab[]={
2042 ...
2043 ...
2044  {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT),  1252, 865, &amp;main_key_NO},
2045 ...
2046       </programlisting>
2047       <para>
2048         After you have added your table, recompile Wine and test that
2049         it works. If it fails to detect your table, try running
2050       </para>
2051       <screen>
2052 wine --debugmsg +key,+keyboard >& key.log
2053       </screen>
2054       <para>
2055         and look in the resulting <filename>key.log</filename> file to
2056         find the error messages it gives for your layout.
2057       </para>
2058       <para>
2059         Note that the <constant>LANG_*</constant> and
2060         <constant>SUBLANG_*</constant> definitions are in
2061         <filename>include/winnls.h</filename>, which you might need to
2062         know to find out which numbers your language is assigned, and
2063         find it in the debugmsg output. The numbers will be
2064         <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
2065         the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
2066         <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
2067         <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
2068         could look for <literal>0414</literal> in the debugmsg output
2069         to find out why my keyboard won't detect.
2070       </para>
2071       <para>
2072         Once it works, submit it to the Wine project. If you use CVS,
2073         you will just have to do
2074       </para>
2075       <screen>
2076 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
2077       </screen>
2078       <para>
2079         from your main Wine directory, then submit
2080         <filename>layout.diff</filename> to
2081         <email>wine-patches@winehq.com</email> along with a brief note
2082         of what it is.
2083       </para>
2084       <para>
2085         If you don't use CVS, you need to do
2086       </para>
2087       <screen>
2088 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
2089       </screen>
2090       <para>
2091         and submit it as explained above.
2092       </para>
2093       <para>
2094         If you did it right, it will be included in the next Wine
2095         release, and all the troublesome applications (especially
2096         remote-control applications) and games that use scancodes will
2097         be happily using your keyboard layout, and you won't get those
2098         annoying fixme messages either.
2099       </para>
2100       <para>
2101         Good luck.
2102       </para>
2103     </sect1>
2104
2105   </chapter>
2106
2107 <!-- Keep this comment at the end of the file
2108 Local variables:
2109 mode: sgml
2110 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
2111 End:
2112 -->