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>[Debug]</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 id="config-wine">
 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             Note that ttydrv is still very lacking, so if it doesn't work,
 405             resort to using "xvfb", a virtual X11 server.
 406           </para>
 407           <para>
 408             <programlisting>"Printer" = "off|on"</programlisting> Tells wine
 409             whether to allow printing via printer drivers to work.
 410             This option isn't needed for our builtin psdrv printer driver
 411             at all.
 412             Using these things are pretty alpha, so you might want to
 413             watch out. Some people might find it useful, however. If
 414             you're not planning to work on printing via windows printer
 415             drivers, don't even add this to your wine config file
 416             (It probably isn't already in it).
 417             Check out the [spooler] and [parallelports] sections too.
 418           </para>
 419           <para>
 420             <programlisting>"ShellLinker" = "wineshelllink"</programlisting>
 421             This setting specifies the shell linker script to use for setting
 422             up Windows icons in e.g. KDE or Gnome that are given by programs
 423             making use of appropriate shell32.dll functionality to create
 424             icons on the desktop/start menu during installation.
 425           </para>
 426           <para id="dirsymlinks">
 427             <programlisting>"ShowDirSymlinks" = "1"</programlisting>
 428             Wine doesn't pass directory symlinks to Windows programs by
 429             default, as doing so may crash some programs that do
 430             recursive lookups of whole subdirectory trees
 431             whenever a directory symlink points back to itself or one of its
 432             parent directories.
 433             That's why we disallowed the use of directory symlinks
 434             and added this setting to reenable ("1") this functionality.
 435           </para>
 436           <para>
 437             <programlisting>"SymbolTableFile" = "wine.sym"</programlisting>
 438             Sets up the symbol table file for the wine debugger. You
 439             probably don't need to fiddle with this. May be useful if
 440             your wine is stripped.
 441           </para>
 442         </sect3>
 443
 444         <sect3>
 445           <title>Introduction To DLL Sections</title>
 446           <para>
 447             There are a few things you will need to know before
 448             configuring the DLL sections in your wine configuration
 449             file.
 450           </para>
 451           <sect4>
 452             <title>Windows DLL Pairs</title>
 453             <para>
 454               Most windows DLL's have a win16 (Windows 3.x) and win32
 455               (Windows 9x/NT) form.  The combination of the win16 and
 456               win32 DLL versions are called the "DLL pair". This is a
 457               list of the most common pairs:
 458             </para>
 459
 460             <informaltable>
 461               <tgroup cols="3">
 462                 <thead>
 463                   <row>
 464                     <entry>Win16</entry>
 465                     <entry>Win32</entry>
 466                     <entry>
 467                       Native
 468                       <footnote>
 469                         <para>
 470                           Is it possible to use native dll with wine?
 471                           (See next section)
 472                         </para>
 473                       </footnote>
 474                     </entry>
 475                   </row>
 476                 </thead>
 477                 <tbody>
 478                   <row>
 479                     <entry>KERNEL</entry>
 480                     <entry>KERNEL32</entry>
 481                     <entry>No!</entry>
 482                   </row>
 483                   <row>
 484                     <entry>USER</entry>
 485                     <entry>USER32</entry>
 486                     <entry>No!</entry>
 487                   </row>
 488                   <row>
 489                     <entry>SHELL</entry>
 490                     <entry>SHELL32</entry>
 491                     <entry>Yes</entry>
 492                   </row>
 493                   <row>
 494                     <entry>GDI</entry>
 495                     <entry>GDI32</entry>
 496                     <entry>No!</entry>
 497                   </row>
 498                   <row>
 499                     <entry>COMMDLG</entry>
 500                     <entry>COMDLG32</entry>
 501                     <entry>Yes</entry>
 502                   </row>
 503                   <row>
 504                     <entry>VER</entry>
 505                     <entry>VERSION</entry>
 506                     <entry>Yes</entry>
 507                   </row>
 508                 </tbody>
 509               </tgroup>
 510             </informaltable>
 511           </sect4>
 512
 513           <sect4>
 514             <title>Different Forms Of DLL's</title>
 515             <para>
 516               There are a few different forms of DLL's wine can load:
 517               <variablelist>
 518                 <varlistentry>
 519                   <term>native</term>
 520                   <listitem><para>
 521                       The DLL's that are included with windows. Many
 522                       windows DLL's can be loaded in their native
 523                       form. Many times these native versions work
 524                       better than their non-Microsoft equivalent --
 525                       other times they don't.
 526                     </para></listitem>
 527                 </varlistentry>
 528                 <varlistentry>
 529                   <term>builtin</term>
 530                   <listitem><para>
 531                       The most common form of DLL loading. This is
 532                       what you will use if the DLL is to system-specific
 533                       or error-prone in native form (KERNEL for example),
 534                       you don't have the native DLL, or you just want to be
 535                       Microsoft-free.
 536                     </para></listitem>
 537                 </varlistentry>
 538                 <varlistentry>
 539                   <term>so</term>
 540                   <listitem><para>
 541                       Native ELF libraries. Will not work yet.
 542                     </para></listitem>
 543                 </varlistentry>
 544                 <varlistentry>
 545                   <term>elfdll</term>
 546                   <listitem><para>
 547                       ELF encapsulated windows DLL's.
 548                       No longer used, ignored.
 549                     </para></listitem>
 550                 </varlistentry>
 551               </variablelist>
 552             </para>
 553           </sect4>
 554         </sect3>
 555
 556         <sect3>
 557           <title>The [DllDefaults] Section</title>
 558           <para>
 559             These settings provide wine's default handling of DLL loading.
 560           </para>
 561           <para>
 562             <programlisting>"DefaultLoadOrder" =" native, so, builtin"</programlisting>
 563           </para>
 564           <para>
 565             This setting is a comma-delimited list of the order in
 566             which to attempt loading DLLs. If the first option fails,
 567             it will try the second, and so on. The order specified
 568             above is probably the best in most conditions.
 569           </para>
 570         </sect3>
 571
 572         <sect3>
 573           <title>The [DllPairs] Section</title>
 574           <para>
 575           At one time, there was a section called [DllPairs] in the
 576           default configuration file, but this has been obsoleted
 577           because the pairing information has now been embedded into
 578           Wine itself. (The purpose of this section was merely to be
 579           able to issue warnings if the user attempted to pair
 580           codependent 16-bit/32-bit DLLs of different types.) If you
 581           still have this in your <filename>~/.wine/.config</filename> or
 582           <filename>wine.conf</filename>, you may safely delete it.
 583           </para>
 584         </sect3>
 585
 586         <sect3>
 587           <title>The [DllOverrides] Section</title>
 588           <para>
 589             The format for this section is the same for each line:
 590             <programlisting>
 591 &lt;DLL>{,&lt;DLL>,&lt;DLL>...} = &lt;FORM>{,&lt;FORM>,&lt;FORM>...}
 592             </programlisting>
 593           </para>
 594           <para>
 595             For example, to load builtin KERNEL pair (case doesn't
 596             matter here):
 597             <programlisting>
 598 "kernel,kernel32" = "builtin"
 599             </programlisting>
 600           </para>
 601           <para>
 602             To load the native COMMDLG pair, but if that doesn't work
 603             try builtin:
 604             <programlisting>
 605 "commdlg,comdlg32" = "native,builtin"
 606             </programlisting>
 607           </para>
 608           <para>
 609             To load the native COMCTL32:
 610             <programlisting>
 611 "comctl32" = "native"
 612             </programlisting>
 613           </para>
 614           <para>
 615             Here is a good generic setup (As it is defined in config
 616             that was included with your wine package):
 617             <programlisting>
 618 [DllOverrides]
 619 "rpcrt4"       = "builtin, native"
 620 "oleaut32"     = "builtin, native"
 621 "ole32"        = "builtin, native"
 622 "commdlg"      = "builtin, native"
 623 "comdlg32"     = "builtin, native"
 624 "ver"          = "builtin, native"
 625 "version"      = "builtin, native"
 626 "shell"        = "builtin, native"
 627 "shell32"      = "builtin, native"
 628 "shfolder"     = "builtin, native"
 629 "shlwapi"      = "builtin, native"
 630 "shdocvw"      = "builtin, native"
 631 "lzexpand"     = "builtin, native"
 632 "lz32"         = "builtin, native"
 633 "comctl32"     = "builtin, native"
 634 "commctrl"     = "builtin, native"
 635 "advapi32"     = "builtin, native"
 636 "crtdll"       = "builtin, native"
 637 "mpr"          = "builtin, native"
 638 "winspool.drv" = "builtin, native"
 639 "ddraw"        = "builtin, native"
 640 "dinput"       = "builtin, native"
 641 "dsound"       = "builtin, native"
 642 "opengl32"     = "builtin, native"
 643 "msvcrt"       = "native, builtin"
 644 "msvideo"      = "builtin, native"
 645 "msvfw32"      = "builtin, native"
 646 "mcicda.drv"   = "builtin, native"
 647 "mciseq.drv"   = "builtin, native"
 648 "mciwave.drv"  = "builtin, native"
 649 "mciavi.drv"   = "native, builtin"
 650 "mcianim.drv"  = "native, builtin"
 651 "msacm.drv"    = "builtin, native"
 652 "msacm"        = "builtin, native"
 653 "msacm32"      = "builtin, native"
 654 "midimap.drv"  = "builtin, native"
 655 ; you can specify applications too
 656 "notepad.exe"  = "native, builtin"
 657 ; default for all other dlls
 658 "*" = "native, builtin"
 659             </programlisting>
 660           </para>
 661           <note>
 662             <para>
 663               If loading of the libraries that are listed first fails,
 664               wine will just go on by using the second or third option.
 665             </para>
 666           </note>
 667         </sect3>
 668
 669         <sect3>
 670           <title>The [fonts] Section</title>
 671           <para>
 672             This section sets up wine's font handling.
 673           </para>
 674           <para>
 675             <programlisting>"Resolution" = "96"</programlisting>
 676           </para>
 677           <para>
 678             Since the way X handles fonts is different from the way
 679             Windows does, wine uses a special mechanism to deal with
 680             them. It must scale them using the number defined in the
 681             "Resolution" setting. 60-120 are reasonable values, 96 is
 682             a nice in the middle one. If you have the real windows
 683             fonts available (<filename>&lt;dirs to
 684               wine>/documentation/ttfserver</filename> and
 685             <filename>fonts</filename>), this parameter will not be as
 686             important. Of course, it's always good to get your X fonts
 687             working acceptably in wine.
 688           </para>
 689           <para>
 690             <programlisting>"Default" = "-adobe-times-"</programlisting>
 691             The default font wine uses. Fool around with it if you'd like.
 692           </para>
 693           <para>
 694 OPTIONAL:
 695           </para>
 696           <para>
 697             The <literal>Alias</literal> setting allows you to map an X font to a font
 698             used in wine. This is good for apps that need a special font you don't have,
 699             but a good replacement exists. The syntax is like so:
 700             <programlisting>
 701 "AliasX" = "[Fake windows name],[Real X name]"&lt;,optional "masking" section>
 702             </programlisting>
 703           </para>
 704           <para>
 705             Pretty straightforward. Replace "AliasX" with "Alias0",
 706             then "Alias1" and so on. The fake windows name is the name
 707             that the font will be under a windows app in wine. The
 708             real X name is the font name as seen by X (Run
 709             "xfontsel"). The optional "masking" section allows you to
 710             utilize the fake windows name you define. If it is not
 711             used, then wine will just try to extract the fake windows
 712             name itself and not use the value you enter.
 713           </para>
 714           <para>
 715             Here is an example of an alias without masking. The font will show up in windows
 716             apps as "Google".
 717
 718             <programlisting>
 719 "Alias0" = "Foo,--google-"
 720             </programlisting>
 721           </para>
 722           <para>
 723             Here is an example with masking enabled. The font will show up as "Foo" in
 724             windows apps.
 725             <programlisting>
 726 "Alias1" = "Foo,--google-,subst"
 727             </programlisting>
 728           </para>
 729           <para>
 730             For more info check out the <link linkend="fonts">Fonts</link>
 731             chapter.
 732           </para>
 733         </sect3>
 734
 735         <sect3>
 736           <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
 737           <para>
 738             Even though it sounds like a lot of sections, these are
 739             all closely related. They are all for communications and
 740             parallel ports.
 741           </para>
 742           <para>
 743             The [serialports] section tells wine what serial ports it
 744             is allowed to use.
 745             <programlisting>"ComX" = "/dev/ttySY"</programlisting>
 746           </para>
 747           <para>
 748             Replace <literal>X</literal> with the number of the COM
 749             port in Windows (1-8) and <literal>Y</literal> with the
 750             number of it in <literal>X</literal> (Usually the number
 751             of the port in Windows minus 1). <literal>ComX</literal>
 752             can actually equal any device
 753             (<medialabel>/dev/modem</medialabel> is acceptable). It is
 754             not always necessary to define any COM ports (An optional
 755             setting). Here is an example:
 756             <programlisting>"Com1" = "/dev/ttyS0"</programlisting>
 757           </para>
 758           <para>
 759             Use as many of these as you like in the section to define
 760             all of the COM ports you need.
 761           </para>
 762           <para>
 763             The [parallelports] section sets up any parallel ports
 764             that will be allowed access under wine.
 765             <programlisting>"LptX" = "/dev/lpY"</programlisting>
 766           </para>
 767           <para>
 768             Sounds familiar? Syntax is just like the COM port setting.
 769             Replace <literal>X</literal> with a value from 1-4 as it
 770             is in Windows and <literal>Y</literal> with a value from
 771             0-3 (<literal>Y</literal> is usually the value in windows
 772             minus 1, just like for COM ports). You don't always need
 773             to define a parallel port (AKA, it's optional). As with
 774             the other section, LptX can equal any device (Maybe
 775             <medialabel>/dev/printer</medialabel>). Here is an
 776             example:  <programlisting>"Lpt1" = "/dev/lp0"</programlisting>
 777           </para>
 778           <para>
 779             The [spooler] section will inform wine where to spool
 780             print jobs. Use this if you want to try printing. Wine
 781             docs claim that spooling is "rather primitive" at this
 782             time, so it won't work perfectly. IT IS OPTIONAL. The only
 783             setting you use in this section works to map a port (LPT1,
 784             for example) to a file or a command. Here is an example,
 785             mapping LPT1 to the file <filename>out.ps</filename>:
 786             <programlisting>"LPT1:" = "out.ps"</programlisting>
 787           </para>
 788           <para>
 789             The following command maps printing jobs to LPT1 to the
 790             command <command>lpr</command>. Notice  the |:
 791             <programlisting>"LPT1:" = "|lpr"</programlisting>
 792           </para>
 793           <para>
 794             The [ports] section is usually useful only for people who
 795             need direct port access for programs requiring dongles or
 796             scanners. IF YOU DON'T NEED IT, DON'T USE IT!
 797           </para>
 798           <para>
 799             <programlisting>"read" = "0x779,0x379,0x280-0x2a0"</programlisting>
 800             Gives direct read access to those IO's.
 801           </para>
 802           <para>
 803             <programlisting>"write" = "0x779,0x379,0x280-0x2a0"</programlisting>
 804             Gives direct write access to those IO's. It's probably a
 805             good idea to keep the values of the
 806             <literal>read</literal> and <literal>write</literal>
 807             settings the same. This stuff will only work when you're
 808             root.
 809           </para>
 810         </sect3>
 811
 812         <sect3 id="config-debug-etc">
 813           <title>The [Debug], [Registry], [tweak.layout], and [programs] Sections</title>
 814           <para>
 815             [Debug] is used to include or exclude debug messages, and to
 816             output them to a file. The latter is rarely used. THESE
 817             ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
 818             REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG. (In extreme
 819             cases you may want to use these options to manage the amount
 820             of information generated by the <parameter>--debugmsg +relay
 821             </parameter> option.)
 822           </para>
 823           <para>
 824             <programlisting>"File" = "/blanco"</programlisting>
 825             Sets the logfile for wine. Set to CON to log to standard out.
 826             THIS IS RARELY USED.
 827           </para>
 828           <para>
 829             <programlisting>"SpyExclude" = "WM_SIZE;WM_TIMER;"</programlisting>
 830             Excludes debug messages about <constant>WM_SIZE</constant>
 831             and <constant>WM_TIMER</constant> in the logfile.
 832           </para>
 833           <para>
 834             <programlisting>"SpyInclude" = "WM_SIZE;WM_TIMER;"</programlisting>
 835             Includes debug messages about <constant>WM_SIZE</constant>
 836             and <constant>WM_TIMER</constant> in the logfile.
 837           </para>
 838           <para>
 839             <programlisting>"RelayInclude" = "user32.CreateWindowA;comctl32.*"</programlisting>
 840             Include only the listed functions in a
 841             <parameter>--debugmsg +relay</parameter> trace.  This entry is
 842             ignored if there is a <parameter>RelayExclude</parameter> entry.
 843           </para>
 844           <para>
 845             <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
 846             Exclude the listed functions in a
 847             <parameter>--debugmsg +relay</parameter> trace.  This entry
 848             overrides any settings in a <parameter>RelayInclude</parameter>
 849             entry.  If neither entry is present then the trace includes
 850             everything.
 851           </para>
 852           <para>
 853             In both entries the functions may be specified either as a
 854             function name or as a module and function.  In this latter
 855             case specify an asterisk for the function name to include
 856             all functions in the module.
 857           </para>
 858           <para>
 859             [Registry] can be used to tell wine where your old windows
 860             registry files exist. This section is completely optional
 861             and useless to people using wine without an existing
 862             windows installation.
 863           </para>
 864           <para>
 865             <programlisting>"UserFileName" = "/dirs/to/user.reg"</programlisting>
 866             The location of your old <filename>user.reg</filename> file.
 867           </para>
 868           <para>
 869             [tweak.layout] is devoted to wine's look. There is only
 870             one setting for it.
 871           </para>
 872           <para>
 873             <programlisting>"WineLook" = "win31|win95|win98"</programlisting>
 874             Will change the look of wine from Windows 3.1 to Windows 95.
 875             The <literal>win98</literal> setting behaves
 876             just like <literal>win95</literal> most of the time.
 877           </para>
 878           <para>
 879             [programs] can be used to say what programs run under
 880             special conditions.
 881           </para>
 882           <para>
 883             <programlisting>"Default" = "/program/to/execute.exe"</programlisting>
 884             Sets the program to be run if wine is started without specifying a program.
 885           </para>
 886           <para>
 887             <programlisting>"Startup" = "/program/to/execute.exe"</programlisting>
 888             Sets the program to automatically be run at startup every time.
 889           </para>
 890         </sect3>
 891
 892         <sect3>
 893           <title>The [WinMM] Section</title>
 894           <para>
 895             [WinMM] is used to define which multimedia drivers have to be loaded. Since
 896             those drivers may depend on the multimedia interfaces available on your system
 897             (OSS, ALSA... to name a few), it's needed to be able to configure which driver
 898             has to be loaded.
 899           </para>
 900
 901           <para>
 902             The content of the section looks like:
 903             <programlisting>
 904 [WinMM]
 905 "Drivers" = "wineoss.drv"
 906 "WaveMapper" = "msacm.drv"
 907 "MidiMapper" = "midimap.drv"
 908             </programlisting>
 909             All the keys must be defined:
 910             <itemizedlist>
 911               <listitem>
 912                 <para>
 913                   The "Drivers" key is a ';' separated list of modules name, each of
 914                   them containing a low level driver. All those drivers will be loaded
 915                   when MMSYSTEM/WINMM is started and will provide their inner features.
 916                 </para>
 917               </listitem>
 918               <listitem>
 919                 <para>
 920                   The "WaveMapper" represents the name of the module containing the Wave
 921                   Mapper driver. Only one wave mapper can be defined in the system.
 922                 </para>
 923               </listitem>
 924               <listitem>
 925                 <para>
 926                   The "MidiMapper" represents the name of the module containing the MIDI
 927                   Mapper driver. Only one MIDI mapper can be defined in the system.
 928                 </para>
 929               </listitem>
 930             </itemizedlist>
 931           </para>
 932         </sect3>
 933
 934         <sect3 id="network-section">
 935           <title>The [Network] Section</title>
 936           <para>
 937             [Network] contains settings related to
 938             networking. Currently there is only one value that can be set.
 939           </para>
 940           <variablelist>
 941             <varlistentry>
 942               <term>UseDnsComputerName</term>
 943               <listitem>
 944                 <para>
 945                   A boolean setting (default: <literal>Y</literal>)
 946                   that affects the way Wine sets the computer name. The computer
 947                   name in the Windows world is the so-called <emphasis>NetBIOS name</emphasis>.
 948                   It is contained in the <varname>ComputerName</varname> in the registry entry
 949                   <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
 950                 </para>
 951                 <para>
 952                   If this option is set to "Y" or missing, Wine will set the
 953                   NetBIOS name to the Unix host name of your computer, if
 954                   necessary truncated to 31 characters. The Unix hostname is the output
 955                   of the shell command <command>hostname</command>, up to but not
 956                   including the first dot ('.'). Among other things, this means that
 957                   Windows programs running under Wine cannot change the NetBIOS computer name.
 958                 </para>
 959                 <para>
 960                   If this option is set to "N", Wine will use the registry value above
 961                   to set the NetBIOS name. Only if the registry entry doesn't exist (usually
 962                   only during the first wine startup) it will use the Unix hostname as
 963                   usual. Windows applications can change the NetBIOS name. The change
 964                   will be effective after a "reboot", i.e. after restarting Wine.
 965                 </para>
 966               </listitem>
 967             </varlistentry>
 968           </variablelist>
 969         </sect3>
 970
 971         <sect3 id="appdefaults-section">
 972           <title>The [AppDefaults] Section</title>
 973           <para>
 974             The section is used to overwrite certain settings of this file for a
 975             special program with different settings.
 976             [AppDefaults] is not the real name of the section. The real name
 977             consists of the leading word AppDefaults followed by the name
 978             of the executable the section is valid for.
 979             The end of the section name is the name of the
 980             corresponding "standard" section of the configuration file
 981             that should have some of its settings overwritten with the
 982             application specific settings you define.
 983             The three parts of the section name are separated by two backslashes.
 984           </para>
 985           <para>
 986             Currently wine supports overriding selected settings within
 987             the sections [DllOverrides], [x11drv], [version] and [dsound] only.
 988           </para>
 989           <para>
 990             Here is an example that overrides the normal settings for a
 991             program:
 992             <programlisting>
 993 ;; default settings
 994 [x11drv]
 995 "Managed" = "Y"
 996 "Desktop" = "N"
 997
 998 ;; run install in desktop mode
 999 [AppDefaults\\install.exe\\x11drv]
1000 "Managed" = "N"
1001 "Desktop" = "800x600"
1002             </programlisting>
1003           </para>
1004         </sect3>
1005       </sect2>
1006
1007       <sect2>
1008         <title>Where Do I Put It?</title>
1009         <para>
1010           The wine config file can go in two places.
1011         </para>
1012         <variablelist>
1013           <varlistentry>
1014             <term><filename>/usr/local/etc/wine.conf</filename></term>
1015             <listitem><para>
1016                 A systemwide config file, used for anyone who doesn't
1017                 have their own. NOTE: this file is currently unused as a
1018                 new global configuration mechanism is not in place at this
1019                 time.
1020             </para></listitem>
1021           </varlistentry>
1022           <varlistentry>
1023             <term><filename>$HOME/.wine/config</filename></term>
1024             <listitem><para>
1025                 Your own config file (which only is used for your user).
1026             </para></listitem>
1027           </varlistentry>
1028         </variablelist>
1029         <para>
1030           So copy your version of the wine config file to
1031           <filename>$HOME/.wine/config</filename>
1032           or <filename>/usr/local/etc/wine.conf</filename>
1033           for wine to recognize it.
1034         </para>
1035       </sect2>
1036
1037       <sect2>
1038         <title>What If It Doesn't Work?</title>
1039         <para>
1040           There is always a chance that things will go wrong. If the
1041           unthinkable happens, report the problem to
1042           <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>,
1043           try the newsgroup
1044           <systemitem>comp.emulators.ms-windows.wine</systemitem>,
1045           or the IRC channel <systemitem>#WineHQ</systemitem> found on
1046           irc.openprojects.net, or connected servers.
1047           Make sure that you have looked over this document thoroughly,
1048           and have also read:
1049         </para>
1050         <itemizedlist>
1051           <listitem>
1052             <para><filename>README</filename></para>
1053           </listitem>
1054           <listitem>
1055             <para>
1056               <filename>http://www.winehq.org/trouble/</filename>
1057             </para>
1058           </listitem>
1059         </itemizedlist>
1060         <para>
1061           If indeed it looks like you've done your research, be
1062           prepared for helpful suggestions. If you haven't, brace
1063           yourself for heaving flaming.
1064         </para>
1065       </sect2>
1066     </sect1>
1067
1068     <sect1 id="x11drv">
1069       <title>Configuring the x11drv Driver</title>
1070
1071       <para>
1072         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1073       </para>
1074       <para>
1075         (Extracted from <filename>wine/documentation/x11drv</filename>)
1076       </para>
1077
1078       <para>
1079         Most Wine users run Wine under the windowing system known as
1080         X11. During most of Wine's history, this was the only display
1081         driver available, but in recent years, parts of Wine have been
1082         reorganized to allow for other display drivers (although the
1083         only alternative currently available is Patrik Stridvall's
1084         ncurses-based ttydrv, which he claims works for displaying
1085         calc.exe). The display driver is chosen with the
1086         <literal>GraphicsDriver</literal> option in the [wine] section
1087         of <filename>~/.wine/config</filename>, but I will only cover the
1088         x11drv driver in this article.
1089       </para>
1090
1091       <sect2>
1092         <title>x11drv modes of operation</title>
1093
1094         <para>
1095           The x11drv driver consists of two conceptually distinct
1096           pieces, the graphics driver (GDI part), and the windowing
1097           driver (USER part). Both of these are linked into the
1098           <filename>libx11drv.so</filename> module, though (which you
1099           load with the <literal>GraphicsDriver</literal> option). In
1100           Wine, running on X11, the graphics driver must draw on
1101           drawables (window interiors) provided by the windowing
1102           driver. This differs a bit from the Windows model, where the
1103           windowing system creates and configures device contexts
1104           controlled by the graphics driver, and applications are
1105           allowed to hook into this relationship anywhere they like.
1106           Thus, to provide any reasonable tradeoff between
1107           compatibility and usability, the x11drv has three different
1108           modes of operation.
1109         </para>
1110
1111         <variablelist>
1112           <varlistentry>
1113             <term>Managed</term>
1114             <listitem>
1115               <para>
1116                 The default. Specified by using the <literal>Managed</literal>
1117                 wine config file option (see below).
1118                 Ordinary top-level frame windows with thick borders,
1119                 title bars, and system menus will be managed by your
1120                 window manager. This lets these applications integrate
1121                 better with the rest of your desktop, but may not
1122                 always work perfectly (a rewrite of this mode of
1123                 operation, to make it more robust and less patchy, is
1124                 currently being done, though, and it's planned to be
1125                 finished before the Wine 1.0 release).
1126               </para>
1127             </listitem>
1128           </varlistentry>
1129           <varlistentry>
1130             <term>Unmanaged/Normal</term>
1131             <listitem>
1132               <para>
1133                 Window manager independent (any running
1134                 window manager is ignored completely). Window
1135                 decorations (title bars, borders, etc) are drawn by
1136                 Wine to look and feel like the real Windows. This is
1137                 compatible with applications that depend on being able
1138                 to compute the exact sizes of any such decorations, or
1139                 that want to draw their own.
1140                 Unmanaged mode is only used if both Managed and Desktop
1141                 are set to disabled.
1142               </para>
1143             </listitem>
1144           </varlistentry>
1145           <varlistentry>
1146             <term>Desktop-in-a-Box</term>
1147             <listitem>
1148               <para>
1149                 Specified by using the <literal>Desktop</literal>
1150                 wine config file option (see below).
1151                 (adding a geometry, e.g. <literal>800x600</literal>
1152                 for a such-sized desktop, or
1153                 even <literal>800x600+0+0</literal> to
1154                 automatically position the desktop at the upper-left
1155                 corner of the display). This is the mode most
1156                 compatible with the Windows model. All application
1157                 windows will just be Wine-drawn windows inside the
1158                 Wine-provided desktop window (which will itself be
1159                 managed by your window manager), and Windows
1160                 applications can roam freely within this virtual
1161                 workspace and think they own it all, without
1162                 disturbing your other X apps.
1163                 Note: currently there's one desktop window for every
1164                 application; this will be fixed at some time.
1165               </para>
1166             </listitem>
1167           </varlistentry>
1168         </variablelist>
1169       </sect2>
1170
1171       <sect2>
1172         <title>The [x11drv] section</title>
1173
1174         <variablelist>
1175           <varlistentry>
1176             <term>Managed</term>
1177             <listitem>
1178               <para>
1179                 Wine can let frame windows be managed by your window
1180                 manager. This option specifies whether you want that
1181                 by default.
1182               </para>
1183             </listitem>
1184           </varlistentry>
1185           <varlistentry>
1186             <term>Desktop</term>
1187             <listitem>
1188               <para>
1189                 Creates a main desktop window of a specified size
1190                 to display all Windows applications in.
1191                 The size argument could e.g. be "800x600".
1192               </para>
1193             </listitem>
1194           </varlistentry>
1195           <varlistentry>
1196             <term>DXGrab</term>
1197             <listitem>
1198               <para>
1199                 If you don't use DGA, you may want an alternative
1200                 means to convince the mouse cursor to stay within the
1201                 game window. This option does that. Of course, as with
1202                 DGA, if Wine crashes, you're in trouble (although not
1203                 as badly as in the DGA case, since you can still use
1204                 the keyboard to get out of X).
1205               </para>
1206             </listitem>
1207           </varlistentry>
1208           <varlistentry>
1209             <term>UseDGA</term>
1210             <listitem>
1211               <para>
1212                 This specifies whether you want DirectDraw to use
1213                 XFree86's <firstterm>Direct Graphics
1214                   Architecture</firstterm> (DGA), which is able to
1215                 take over the entire display and run the game
1216                 full-screen at maximum speed. (With DGA1 (XFree86
1217                 3.x), you still have to configure the X server to the
1218                 game's requested bpp first, but with DGA2 (XFree86
1219                 4.x), runtime depth-switching may be possible,
1220                 depending on your driver's capabilities.) But be aware
1221                 that if Wine crashes while in DGA mode, it may not be
1222                 possible to regain control over your computer without
1223                 rebooting. DGA normally requires either root
1224                 privileges or read/write access to
1225                 <filename>/dev/mem</filename>.
1226               </para>
1227             </listitem>
1228           </varlistentry>
1229           <varlistentry>
1230             <term>UseXShm</term>
1231             <listitem>
1232               <para>
1233                 If you don't want DirectX to use DGA, you can at least
1234                 use X Shared Memory extensions (XShm). It is much
1235                 slower than DGA, since the app doesn't have direct
1236                 access to the physical frame buffer, but using shared
1237                 memory to draw the frame is at least faster than
1238                 sending the data through the standard X11 socket, even
1239                 though Wine's XShm support is still known to crash
1240                 sometimes.
1241               </para>
1242             </listitem>
1243           </varlistentry>
1244           <varlistentry>
1245             <term>DesktopDoubleBuffered</term>
1246             <listitem>
1247               <para>
1248                 Applies only if you use the
1249                 <parameter>--desktop</parameter> command-line option
1250                 to run in a desktop window. Specifies whether to
1251                 create the desktop window with a double-buffered
1252                 visual, something most OpenGL games need to run
1253                 correctly.
1254               </para>
1255             </listitem>
1256           </varlistentry>
1257           <varlistentry>
1258             <term>AllocSystemColors</term>
1259             <listitem>
1260               <para>
1261                 Applies only if you have a palette-based display, i.e.
1262                 if your X server is set to a depth of 8bpp, and if you
1263                 haven't requested a private color map. It specifies
1264                 the maximum number of shared colormap cells (palette
1265                 entries) Wine should occupy. The higher this value,
1266                 the less colors will be available to other
1267                 applications.
1268               </para>
1269             </listitem>
1270           </varlistentry>
1271           <varlistentry>
1272             <term>PrivateColorMap</term>
1273             <listitem>
1274               <para>
1275                 Applies only if you have a palette-based display, i.e.
1276                 if your X server is set to a depth of 8bpp. It
1277                 specifies that you don't want to use the shared color
1278                 map, but a private color map, where all 256 colors are
1279                 available. The disadvantage is that Wine's private
1280                 color map is only seen while the mouse pointer is
1281                 inside a Wine window, so psychedelic flashing and
1282                 funky colors will become routine if you use the mouse
1283                 a lot.
1284               </para>
1285             </listitem>
1286           </varlistentry>
1287           <varlistentry>
1288             <term>Synchronous</term>
1289             <listitem>
1290               <para>
1291                 To be used for debugging X11 operations.
1292                 If Wine crashes with an X11 error, then you should enable
1293                 Synchronous mode to disable X11 request caching in order
1294                 to make sure that the X11 error happens directly after
1295                 the corresponding X11 call in the log file appears.
1296                 Will slow down X11 output !
1297               </para>
1298             </listitem>
1299           </varlistentry>
1300           <varlistentry>
1301             <term>ScreenDepth</term>
1302             <listitem>
1303               <para>
1304                 Applies only to multi-depth displays. It specifies
1305                 which of the available depths Wine should use (and
1306                 tell Windows apps about).
1307               </para>
1308             </listitem>
1309           </varlistentry>
1310           <varlistentry>
1311             <term>Display</term>
1312             <listitem>
1313               <para>
1314                 This specifies which X11 display to use, and if
1315                 specified, will override the
1316                 <envar>DISPLAY</envar> environment variable.
1317               </para>
1318             </listitem>
1319           </varlistentry>
1320           <varlistentry>
1321             <term>PerfectGraphics</term>
1322             <listitem>
1323               <para>
1324                 This option only determines whether fast X11 routines
1325                 or exact Wine routines will be used for certain ROP
1326                 codes in blit operations. Most users won't notice any
1327                 difference.
1328               </para>
1329             </listitem>
1330           </varlistentry>
1331           <varlistentry>
1332             <term>TextCP</term>
1333             <listitem>
1334               <para>
1335                 Codepage to be used for rendering the text in X11
1336                 output. Some sample values would be 437 (USA, Canada),
1337                 850 (Europe), 852 (Central/Eastern Europe), 855
1338                 (Cyrillic). For additional suitable values, see e.g. the Linux
1339                 kernel's codepage configuration page.
1340               </para>
1341             </listitem>
1342           </varlistentry>
1343         </variablelist>
1344       </sect2>
1345     </sect1>
1346
1347     &registry;
1348
1349     <sect1 id="windows-versions">
1350
1351       <title>Setting the windows and DOS version value that's passed to
1352       programs</title>
1353
1354       <para>
1355         Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1356         Oct 18 2002
1357       </para>
1358
1359       <para>
1360         The windows and DOS version value a program gets e.g. by calling the
1361         Windows function GetVersion() plays a very important role:
1362         If your Wine installation for whatever reason fails to provide
1363         to your program the correct version value that it expects,
1364         then the program might assume some very bad things and fail (in
1365         the worst case even silently !).
1366
1367         Fortunately Wine contains some more or less intelligent Windows
1368         version guessing algorithm that will try to guess the Windows
1369         version a program might expect and pass that one on to the
1370         program.
1371
1372         Thus you should <emphasis>not</emphasis> lightly configure a version value, as this will be a "forced" value and thus turn out to be rather harmful to proper operation. In other words: only explicitly set a Windows version value in case Wine's own version detection was unable to provide the correct Windows version and the program fails.
1373       </para>
1374
1375       <sect2>
1376         <title>How to configure the Windows and DOS version value Wine
1377         should return</title>
1378
1379         <para>
1380         The version values can be configured in the wine config file in
1381         the [Version] section.
1382         </para>
1383
1384         <variablelist>
1385           <varlistentry>
1386             <term>"Windows" = "&lt;version string&gt;"</term>
1387             <listitem>
1388               <para>
1389                 default: none; chosen by semi-intelligent detection
1390                 mechanism based on DLL environment.
1391                 Used to specify which Windows version to return to
1392                 programs  (forced  value, overrides standard detection
1393                 mechanism  !). Valid  settings are e.g. "win31", "win95",
1394                 "win98",  "win2k",  "winxp".
1395                 Also valid as an
1396                 <link linkend="appdefaults-section">AppDefaults</link>
1397                 setting (recommended/preferred use).
1398               </para>
1399             </listitem>
1400           </varlistentry>
1401           <varlistentry>
1402             <term>"DOS"="&lt;version string&gt;"</term>
1403             <listitem>
1404               <para>
1405                 Used to specify the DOS version that should be returned
1406                 to programs. Only takes effect in case Wine acts as
1407                 "win31" Windows version ! Common DOS version settings
1408                 include 6.22, 6.20, 6.00, 5.00, 4.00, 3.30, 3.10.
1409                 Also valid as an
1410                 <link linkend="appdefaults-section">AppDefaults</link>
1411                 setting (recommended/preferred use).
1412               </para>
1413             </listitem>
1414           </varlistentry>
1415         </variablelist>
1416       </sect2>
1417     </sect1>
1418
1419     <sect1 id="cdrom-labels">
1420       <sect1info>
1421         <authorgroup>
1422           <author>
1423             <firstname>Petr</firstname>
1424             <surname>Tomasek</surname>
1425             <affiliation>
1426               <address><email>&email-petr-tomasek;</email></address>
1427             </affiliation>
1428             <contrib>Nov 14 1999</contrib>
1429           </author>
1430           <author>
1431             <firstname>Andreas</firstname>
1432             <surname>Mohr</surname>
1433             <affiliation>
1434               <address><email>&email-andreas-mohr;</email></address>
1435             </affiliation>
1436             <contrib>Jan 25 2000</contrib>
1437           </author>
1438         </authorgroup>
1439       </sect1info>
1440
1441       <title>Drive labels and serial numbers with wine</title>
1442       <para>
1443         Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
1444         Nov 14 1999
1445       </para>
1446       <para>
1447         Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1448         Jan 25 2000
1449       </para>
1450       <para>
1451         (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1452       </para>
1453       <para>
1454         Until now, your only possibility of specifying drive volume
1455         labels and serial numbers was to set them manually in the wine
1456         config file. By now, wine can read them directly from the
1457         device as well. This may be useful for many Win 9x games or
1458         for setup programs distributed on CD-ROMs that check for
1459         volume label.
1460       </para>
1461
1462       <sect2>
1463         <title>What's Supported?</title>
1464
1465         <informaltable frame="all">
1466           <tgroup cols="3">
1467             <thead>
1468               <row>
1469                 <entry>File System</entry>
1470                 <entry>Types</entry>
1471                 <entry>Comment</entry>
1472               </row>
1473             </thead>
1474             <tbody>
1475               <row>
1476                 <entry>FAT systems</entry>
1477                 <entry>hd, floppy</entry>
1478                 <entry>reads labels and serial numbers</entry>
1479               </row>
1480               <row>
1481                 <entry>ISO9660</entry>
1482                 <entry>cdrom</entry>
1483                 <entry>reads labels and serial numbers (not mixed-mode CDs yet !)</entry>
1484               </row>
1485             </tbody>
1486           </tgroup>
1487         </informaltable>
1488
1489       </sect2>
1490
1491       <sect2>
1492         <title>How To Set Up?</title>
1493         <para>
1494           Reading labels and serial numbers just works automagically
1495           if you specify a <literal>Device=</literal> line in the
1496           [Drive X] section in your <filename>~/.wine/config</filename>.
1497           Note that the device has to exist and must be accessible if
1498           you do this, though.
1499         </para>
1500         <para>
1501           If you don't do that, then you should give fixed
1502           <literal>"Label" =</literal> or <literal>"Serial" =</literal>
1503           entries in <filename>~/.wine/config</filename>, as Wine returns
1504           these entries instead if no device is given. If they don't
1505           exist, then Wine will return default values (label
1506           <literal>Drive X</literal> and serial
1507           <literal>12345678</literal>).
1508         </para>
1509         <para>
1510           If you want to give a <literal>"Device" =</literal> entry
1511           <emphasis>only</emphasis> for drive raw sector accesses,
1512           but not for reading the volume info from the device (i.e. you want
1513           a <emphasis>fixed</emphasis>, preconfigured label), you need
1514           to specify <literal>"ReadVolInfo" = "0"</literal> to tell Wine
1515           to skip the volume reading.
1516         </para>
1517       </sect2>
1518
1519       <sect2>
1520         <title>EXAMPLES</title>
1521         <para>
1522           Here's a simple example of cdrom and floppy; labels will be
1523           read from the device on both cdrom and floppy; serial
1524           numbers on floppy only:
1525         </para>
1526         <screen>
1527 [Drive A]
1528 "Path" = "/mnt/floppy"
1529 "Type" = "floppy"
1530 "Device" = "/dev/fd0"
1531 "Filesystem" = "msdos"
1532
1533 [Drive R]
1534 "Path" = "/mnt/cdrom"
1535 "Type" = "cdrom"
1536 "Device" = "/dev/hda1"
1537 "Filesystem" = "win95"
1538         </screen>
1539         <para>
1540           Here's an example of overriding the CD-ROM label:
1541         </para>
1542         <screen>
1543 [Drive J]
1544 "Path" = "/mnt/cdrom"
1545 "Type" = "cdrom"
1546 "Label" = "X234GCDSE"
1547 ; note that the device isn't really needed here as we have a fixed label
1548 "Device" = "/dev/cdrom"
1549 "Filesystem" = "msdos"
1550         </screen>
1551       </sect2>
1552
1553       <sect2>
1554         <title>Todo / Open Issues</title>
1555         <itemizedlist>
1556           <listitem> <para>
1557               The cdrom label can be read only if the data track of
1558               the disk resides in the first track and the cdrom is
1559               iso9660.
1560             </para> </listitem>
1561           <listitem> <para>
1562               Better checking for FAT superblock (it now checks only
1563               one byte). </para>
1564           </listitem>
1565           <listitem> <para>
1566               Support for labels/serial nums WRITING.
1567             </para> </listitem>
1568           <listitem> <para>
1569               Can the label be longer than 11 chars? (iso9660 has 32
1570               chars).
1571             </para> </listitem>
1572           <listitem> <para>
1573               What about reading ext2 volume label? ....
1574             </para> </listitem>
1575         </itemizedlist>
1576       </sect2>
1577     </sect1>
1578
1579     <sect1 id="dll-config">
1580       <title>DLL configuration</title>
1581       <sect2 id="dll-overrides">
1582         <title>DLL Overrides</title>
1583
1584         <para>
1585           Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1586         </para>
1587         <para>
1588           (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1589         </para>
1590
1591         <para>
1592           The wine config file directives [DllDefaults]
1593           and [DllOverrides] are the subject of some confusion. The
1594           overall purpose of most of these directives are clear enough,
1595           though - given a choice, should Wine use its own built-in
1596           DLLs, or should it use <filename>.DLL</filename> files found
1597           in an existing Windows installation? This document explains
1598           how this feature works.
1599         </para>
1600
1601         <sect3>
1602           <title>DLL types</title>
1603           <variablelist>
1604             <varlistentry>
1605               <term>native</term>
1606               <listitem> <para>
1607                   A "native" DLL is a <filename>.DLL</filename> file
1608                   written for the real Microsoft Windows.
1609                 </para> </listitem>
1610             </varlistentry>
1611             <varlistentry>
1612               <term>builtin</term>
1613               <listitem> <para>
1614                   A "builtin" DLL is a Wine DLL. These can either be a
1615                   part of <filename>libwine.so</filename>, or more
1616                   recently, in a special <filename>.so</filename> file
1617                   that Wine is able to load on demand.
1618                 </para> </listitem>
1619             </varlistentry>
1620             <varlistentry>
1621               <term>so</term>
1622               <listitem> <para>
1623                   A native Unix <filename>.so</filename> file, with
1624                   calling convention conversion thunks generated on the
1625                   fly as the library is loaded. This is mostly useful
1626                   for libraries such as "glide" that have exactly the
1627                   same API on both Windows and Unix.
1628                 </para> </listitem>
1629             </varlistentry>
1630           </variablelist>
1631         </sect3>
1632
1633         <sect3>
1634           <title>The [DllDefaults] section</title>
1635           <variablelist>
1636             <varlistentry>
1637               <term>DefaultLoadOrder</term>
1638               <listitem> <para>
1639                   This specifies in what order Wine should search for
1640                   available DLL types, if the DLL in question was not
1641                   found in the [DllOverrides] section.
1642                 </para> </listitem>
1643             </varlistentry>
1644           </variablelist>
1645         </sect3>
1646
1647         <sect3>
1648           <title>The [DllPairs] section</title>
1649           <para>
1650             At one time, there was a section called [DllPairs] in the
1651             default configuration file, but this has been obsoleted
1652             because the pairing information has now been embedded into
1653             Wine itself. (The purpose of this section was merely to be
1654             able to issue warnings if the user attempted to pair
1655             codependent 16-bit/32-bit DLLs of different types.) If you
1656             still have this in your <filename>~/.wine/config</filename> or
1657             <filename>wine.conf</filename>, you may safely delete it.
1658           </para>
1659         </sect3>
1660
1661         <sect3>
1662           <title>The [DllOverrides] section</title>
1663           <para>
1664             This section specifies how you want specific DLLs to be
1665             handled, in particular whether you want to use "native" DLLs
1666             or not, if you have some from a real Windows configuration.
1667             Because builtins do not mix seamlessly with native DLLs yet,
1668             certain DLL dependencies may be problematic, but workarounds
1669             exist in Wine for many popular DLL configurations. Also see
1670             WWN's [16]Status Page to figure out how well your favorite
1671             DLL is implemented in Wine.
1672           </para>
1673           <para>
1674             It is of course also possible to override these settings by
1675             explictly using Wine's <parameter>--dll</parameter>
1676             command-line option (see the man page for details).  Some
1677             hints for choosing your optimal configuration (listed by
1678             16/32-bit DLL pair):
1679           </para>
1680           <variablelist>
1681             <varlistentry>
1682               <term>krnl386, kernel32</term>
1683               <listitem> <para>
1684                   Native versions of these will never work, so don't try. Leave
1685                   at <literal>builtin</literal>.
1686                 </para> </listitem>
1687             </varlistentry>
1688             <varlistentry>
1689               <term>gdi, gdi32</term>
1690               <listitem> <para>
1691                   Graphics Device Interface. No effort has been made at trying to
1692                   run native GDI. Leave at <literal>builtin</literal>.
1693                 </para> </listitem>
1694             </varlistentry>
1695             <varlistentry>
1696               <term>user, user32</term>
1697               <listitem> <para>
1698                   Window management and standard controls. It was
1699                   possible to use Win95's <literal>native</literal>
1700                   versions at some point (if all other DLLs that depend
1701                   on it, such as comctl32 and comdlg32, were also run
1702                   <literal>native</literal>). However, this is no longer
1703                   possible after the Address Space Separation, so leave
1704                   at <literal>builtin</literal>.
1705                 </para> </listitem>
1706             </varlistentry>
1707             <varlistentry>
1708               <term>ntdll</term>
1709               <listitem> <para>
1710                   NT kernel API. Although badly documented, the
1711                   <literal>native</literal> version of this will never
1712                   work. Leave at <literal>builtin</literal>.
1713                 </para> </listitem>
1714             </varlistentry>
1715             <varlistentry>
1716               <term>w32skrnl</term>
1717               <listitem> <para>
1718                   Win32s (for Win3.x). The <literal>native</literal>
1719                   version will probably never work. Leave at
1720                   <literal>builtin</literal>.
1721                 </para> </listitem>
1722             </varlistentry>
1723             <varlistentry>
1724               <term>wow32</term>
1725               <listitem> <para>
1726                   Win16 support library for NT. The
1727                   <literal>native</literal> version will probably never
1728                   work. Leave at <literal>builtin</literal>.
1729                 </para> </listitem>
1730             </varlistentry>
1731             <varlistentry>
1732               <term>system</term>
1733               <listitem> <para>
1734                   Win16 kernel stuff. Will never work
1735                   <literal>native</literal>. Leave at
1736                   <literal>builtin</literal>.
1737                 </para> </listitem>
1738             </varlistentry>
1739             <varlistentry>
1740               <term>display</term>
1741               <listitem> <para>
1742                   Display driver. Definitely leave at <literal>builtin</literal>.
1743                 </para> </listitem>
1744             </varlistentry>
1745             <varlistentry>
1746               <term>toolhelp</term>
1747               <listitem> <para>
1748                   Tool helper routines. This is rarely a source of problems.
1749                   Leave at <literal>builtin</literal>.
1750                 </para> </listitem>
1751             </varlistentry>
1752             <varlistentry>
1753               <term>ver, version</term>
1754               <listitem> <para>
1755                   Versioning. Seldom useful to mess with.
1756                 </para> </listitem>
1757             </varlistentry>
1758             <varlistentry>
1759               <term>advapi32</term>
1760               <listitem> <para>
1761                   Registry and security features. Trying the
1762                   <literal>native</literal> version of this may or may
1763                   not work.
1764                 </para> </listitem>
1765             </varlistentry>
1766             <varlistentry>
1767               <term>commdlg, comdlg32</term>
1768               <listitem> <para>
1769                   Common Dialogs, such as color picker, font dialog,
1770                   print dialog, open/save dialog, etc. It is safe to try
1771                   <literal>native</literal>.
1772                 </para> </listitem>
1773             </varlistentry>
1774             <varlistentry>
1775               <term>commctrl, comctl32</term>
1776               <listitem> <para>
1777                   Common Controls. This is toolbars, status bars, list controls,
1778                   the works. It is safe to try <literal>native</literal>.
1779                 </para> </listitem>
1780             </varlistentry>
1781             <varlistentry>
1782               <term>shell, shell32</term>
1783               <listitem> <para>
1784                   Shell interface (desktop, filesystem, etc). Being one of the
1785                   most undocumented pieces of Windows, you may have luck with the
1786                   <literal>native</literal> version, should you need it.
1787                 </para> </listitem>
1788             </varlistentry>
1789             <varlistentry>
1790               <term>winsock, wsock32</term>
1791               <listitem> <para>
1792                   Windows Sockets. The <literal>native</literal> version
1793                   will not work under Wine, so leave at
1794                   <literal>builtin</literal>.
1795                 </para> </listitem>
1796             </varlistentry>
1797             <varlistentry>
1798               <term>icmp</term>
1799               <listitem> <para>
1800                   ICMP routines for wsock32. As with wsock32, leave at
1801                   <literal>builtin</literal>.
1802                 </para> </listitem>
1803             </varlistentry>
1804             <varlistentry>
1805               <term>mpr</term>
1806               <listitem> <para>
1807                   The <literal>native</literal> version may not work due
1808                   to thunking issues. Leave at
1809                   <literal>builtin</literal>.
1810                 </para> </listitem>
1811             </varlistentry>
1812             <varlistentry>
1813               <term>lzexpand, lz32</term>
1814               <listitem> <para>
1815                   Lempel-Ziv decompression. Wine's
1816                   <literal>builtin</literal> version ought to work fine.
1817                 </para> </listitem>
1818             </varlistentry>
1819             <varlistentry>
1820               <term>winaspi, wnaspi32</term>
1821               <listitem> <para>
1822                   Advanced SCSI Peripheral Interface. The
1823                   <literal>native</literal> version will probably never
1824                   work. Leave at <literal>builtin</literal>.
1825                 </para> </listitem>
1826             </varlistentry>
1827             <varlistentry>
1828               <term>crtdll</term>
1829               <listitem> <para>
1830                   C Runtime library. The <literal>native</literal>
1831                   version will easily work better than Wine's on this
1832                   one.
1833                 </para> </listitem>
1834             </varlistentry>
1835             <varlistentry>
1836               <term>winspool.drv</term>
1837               <listitem> <para>
1838                   Printer spooler. You are not likely to have more luck
1839                   with the <literal>native</literal> version.
1840                 </para> </listitem>
1841             </varlistentry>
1842             <varlistentry>
1843               <term>ddraw</term>
1844               <listitem> <para>
1845                   DirectDraw/Direct3D. Since Wine does not implement the
1846                   DirectX HAL, the <literal>native</literal> version
1847                   will not work at this time.
1848                 </para> </listitem>
1849             </varlistentry>
1850             <varlistentry>
1851               <term>dinput</term>
1852               <listitem> <para>
1853                   DirectInput. Running this <literal>native</literal>
1854                   may or may not work.
1855                 </para> </listitem>
1856             </varlistentry>
1857             <varlistentry>
1858               <term>dsound</term>
1859               <listitem> <para>
1860                   DirectSound. It may be possible to run this
1861                   <literal>native</literal>, but don't count on it.
1862                 </para> </listitem>
1863             </varlistentry>
1864             <varlistentry>
1865               <term>dplay/dplayx</term>
1866               <listitem> <para>
1867                   DirectPlay. The <literal>native</literal> version
1868                   ought to work best on this, if at all.
1869                 </para> </listitem>
1870             </varlistentry>
1871             <varlistentry>
1872               <term>mmsystem, winmm</term>
1873               <listitem> <para>
1874                   Multimedia system. The <literal>native</literal>
1875                   version is not likely to work. Leave at
1876                   <literal>builtin</literal>.
1877                 </para> </listitem>
1878             </varlistentry>
1879             <varlistentry>
1880               <term>msacm, msacm32</term>
1881               <listitem> <para>
1882                   Audio Compression Manager. The
1883                   <literal>builtin</literal> version works best, if you
1884                   set msacm.drv to the same.
1885                 </para> </listitem>
1886             </varlistentry>
1887             <varlistentry>
1888               <term>msvideo, msvfw32</term>
1889               <listitem> <para>
1890                   Video for Windows. It is safe (and recommended) to try
1891                   <literal>native</literal>.
1892                 </para> </listitem>
1893             </varlistentry>
1894             <varlistentry>
1895               <term>mcicda.drv</term>
1896               <listitem> <para>
1897                   CD Audio MCI driver.
1898                 </para> </listitem>
1899             </varlistentry>
1900             <varlistentry>
1901               <term>mciseq.drv</term>
1902               <listitem> <para>
1903                   MIDI Sequencer MCI driver (<filename>.MID</filename>
1904                   playback).
1905                 </para> </listitem>
1906             </varlistentry>
1907             <varlistentry>
1908               <term>mciwave.drv</term>
1909               <listitem> <para>
1910                   Wave audio MCI driver (<filename>.WAV</filename> playback).
1911                 </para> </listitem>
1912             </varlistentry>
1913             <varlistentry>
1914               <term>mciavi.drv</term>
1915               <listitem> <para>
1916                   AVI MCI driver (<filename>.AVI</filename> video
1917                   playback). Best to use <literal>native</literal>.
1918                 </para> </listitem>
1919             </varlistentry>
1920             <varlistentry>
1921               <term>mcianim.drv</term>
1922               <listitem> <para>
1923                   Animation MCI driver.
1924                 </para> </listitem>
1925             </varlistentry>
1926             <varlistentry>
1927               <term>msacm.drv</term>
1928               <listitem> <para>
1929                   Audio Compression Manager. Set to same as msacm32.
1930                 </para> </listitem>
1931             </varlistentry>
1932             <varlistentry>
1933               <term>midimap.drv</term>
1934               <listitem> <para>
1935                   MIDI Mapper.
1936                 </para> </listitem>
1937             </varlistentry>
1938             <varlistentry>
1939               <term>wprocs</term>
1940               <listitem> <para>
1941                   This is a pseudo-DLL used by Wine for thunking
1942                   purposes. A <literal>native</literal> version of this
1943                   doesn't exist.
1944                 </para> </listitem>
1945             </varlistentry>
1946           </variablelist>
1947         </sect3>
1948       </sect2>
1949       <sect2 id="dll-missing">
1950         <title>Missing DLLs</title>
1951
1952         <para>
1953           Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1954         </para>
1955
1956         <para>
1957           In case Wine complains about a missing DLL, you should check whether
1958           this file is a publicly available DLL or a custom DLL belonging
1959           to your program (by searching for its name on the internet).
1960           If you managed to get hold of the DLL, then you should make sure
1961           that Wine is able to find and load it.
1962           DLLs usually get loaded according to the mechanism of the
1963           SearchPath() function.
1964           This function searches directories in the following order:
1965
1966           <orderedlist>
1967             <listitem>
1968               <para>
1969                 The directory the program was started from.
1970               </para>
1971             </listitem>
1972             <listitem>
1973               <para>
1974                 The current directory.
1975               </para>
1976             </listitem>
1977             <listitem>
1978               <para>
1979                 The Windows system directory.
1980               </para>
1981             </listitem>
1982             <listitem>
1983               <para>
1984                 The Windows directory.
1985               </para>
1986             </listitem>
1987             <listitem>
1988               <para>
1989                 The PATH variable directories.
1990               </para>
1991             </listitem>
1992           </orderedlist>
1993
1994           In short: either put the required DLL into your application
1995           directory (might be ugly), or usually put it into the Windows system
1996           directory. Just find out its directory by having a look at the Wine
1997           config File variable "System" (which indicates the location of the
1998           Windows system directory) and the associated drive entry.
1999           Note that you probably shouldn't use NT-based native DLLs,
2000           since Wine's NT API support is somewhat weaker than its Win9x
2001           API support (thus leading to even worse compatibility with NT DLLs
2002           than with a no-windows setup !), so better use Win9x native DLLs
2003           instead or no native DLLs at all.
2004         </para>
2005       </sect2>
2006       <sect2 id="dll-windows">
2007         <title>Fetching native DLLs from a Windows CD</title>
2008
2009         <para>
2010           Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
2011         </para>
2012
2013         <para>
2014         The Linux <command>cabextract</command> utility can be used to
2015         extract native Windows .dll files from .cab files that are to be
2016         found on many Windows installation CDs.
2017         </para>
2018       </sect2>
2019     </sect1>
2020
2021     &fonts;
2022     &printing;
2023
2024     <sect1 id="win95look">
2025       <title>Win95/98 Look</title>
2026       <para>
2027         Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
2028       </para>
2029       <para>
2030         (Extracted from <filename>wine/documentation/win95look</filename>)
2031       </para>
2032       <para>
2033         Win95/Win98 interface code is being introduced.
2034       </para>
2035       <para>
2036         Instead of compiling Wine for Win3.1 vs. Win95 using
2037         <constant>#define</constant> switches, the code now looks in a
2038         special [Tweak.Layout] section of
2039         <filename>~/.wine/config</filename> for a
2040         <literal>"WineLook" = "Win95"</literal> or
2041         <literal>"WineLook" = "Win98"</literal> entry.
2042       </para>
2043       <para>
2044         A few new sections and a number of entries have been added to
2045         the <filename>~/.wine/config</filename> file -- these are for
2046         debugging the Win95 tweaks only and may be removed in a future
2047         release!  These entries/sections are:
2048       </para>
2049       <programlisting>
2050 [Tweak.Fonts]
2051 "System.Height" = "&lt;point size>"    # Sets the height of the system typeface
2052 "System.Bold" = "[true|false]"      # Whether the system font should be boldfaced
2053 "System.Italic" = "[true|false]"    # Whether the system font should be italicized
2054 "System.Underline" = "[true|false]" # Whether the system font should be underlined
2055 "System.StrikeOut" = "[true|false]" # Whether the system font should be struck out
2056 "OEMFixed.xxx"                  # Same parameters for the OEM fixed typeface
2057 "AnsiFixed.xxx"                 # Same parameters for the Ansi fixed typeface
2058 "AnsiVar.xxx"                   # Same parameters for the Ansi variable typeface
2059 "SystemFixed.xxx"               # Same parameters for the System fixed typeface
2060
2061 [Tweak.Layout]
2062 "WineLook" = "[Win31|Win95|Win98]"  # Changes Wine's look and feel
2063       </programlisting>
2064     </sect1>
2065
2066     <sect1 id="keyboard">
2067       <title>Keyboard</title>
2068
2069       <para>
2070         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
2071       </para>
2072       <para>
2073         (Extracted from <filename>wine/documentation/keyboard</filename>)
2074       </para>
2075
2076       <para>
2077         Wine now needs to know about your keyboard layout. This
2078         requirement comes from a need from many apps to have the
2079         correct scancodes available, since they read these directly,
2080         instead of just taking the characters returned by the X
2081         server. This means that Wine now needs to have a mapping from
2082         X keys to the scancodes these applications expect.
2083       </para>
2084       <para>
2085         On startup, Wine will try to recognize the active X layout by
2086         seeing if it matches any of the defined tables. If it does,
2087         everything is alright. If not, you need to define it.
2088       </para>
2089       <para>
2090         To do this, open the file
2091         <filename>dlls/x11drv/keyboard.c</filename> and take a look
2092         at the existing tables. Make a backup copy of it, especially
2093         if you don't use CVS.
2094       </para>
2095       <para>
2096         What you really would need to do, is find out which scancode
2097         each key needs to generate.  Find it in the
2098         <function>main_key_scan</function> table, which looks like
2099         this:
2100       </para>
2101       <programlisting>
2102 static const int main_key_scan[MAIN_LEN] =
2103 {
2104 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2105    0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
2106    0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
2107    0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
2108    0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
2109    0x56 /* the 102nd key (actually to the right of l-shift) */
2110 };
2111       </programlisting>
2112       <para>
2113         Next, assign each scancode the characters imprinted on the
2114         keycaps. This was done (sort of) for the US 101-key keyboard,
2115         which you can find near the top in
2116         <filename>keyboard.c</filename>. It also shows that if there
2117         is no 102nd key, you can skip that.
2118       </para>
2119       <para>
2120         However, for most international 102-key keyboards, we have
2121         done it easy for you. The scancode layout for these already
2122         pretty much matches the physical layout in the
2123         <function>main_key_scan</function>, so all you need to do is
2124         to go through all the keys that generate characters on your
2125         main keyboard (except spacebar), and stuff those into an
2126         appropriate table. The only exception is that the 102nd key,
2127         which is usually to the left of the first key of the last line
2128         (usually <keycap>Z</keycap>), must be placed on a separate
2129         line after the last line.
2130       </para>
2131       <para>
2132         For example, my Norwegian keyboard looks like this
2133       </para>
2134       <screen>
2135 §  !  "  #  ¤  %  &  /  (  )  =  ?  `  Back-
2136 |  1  2@ 3£ 4$ 5  6  7{ 8[ 9] 0} +  \´ space
2137
2138 Tab Q  W  E  R  T  Y  U  I  O  P  Å  ^
2139                                      ¨~
2140                                         Enter
2141 Caps A  S  D  F  G  H  J  K  L  Ø  Æ  *
2142 Lock                                  '
2143
2144 Sh- > Z  X  C  V  B  N  M  ;  :  _  Shift
2145 ift &lt;                      ,  .  -
2146
2147 Ctrl  Alt       Spacebar       AltGr  Ctrl
2148       </screen>
2149       <para>
2150         Note the 102nd key, which is the <keycap>&lt;></keycap> key, to
2151         the left of <keycap>Z</keycap>. The character to the right of
2152         the main character is the character generated by
2153         <keycap>AltGr</keycap>.
2154       </para>
2155       <para>
2156         This keyboard is defined as follows:
2157       </para>
2158       <programlisting>
2159 static const char main_key_NO[MAIN_LEN][4] =
2160 {
2161  "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
2162  "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
2163  "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
2164  "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
2165  "&lt;>"
2166 };
2167       </programlisting>
2168       <para>
2169         Except that " and \ needs to be quoted with a backslash, and
2170         that the 102nd key is on a separate line, it's pretty
2171         straightforward.
2172       </para>
2173       <para>
2174         After you have written such a table, you need to add it to the
2175         <function>main_key_tab[]</function> layout index table. This
2176         will look like this:
2177       </para>
2178       <programlisting>
2179 static struct {
2180  WORD lang, ansi_codepage, oem_codepage;
2181  const char (*key)[MAIN_LEN][4];
2182 } main_key_tab[]={
2183 ...
2184 ...
2185  {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT),  1252, 865, &amp;main_key_NO},
2186 ...
2187       </programlisting>
2188       <para>
2189         After you have added your table, recompile Wine and test that
2190         it works. If it fails to detect your table, try running
2191       </para>
2192       <screen>
2193 wine --debugmsg +key,+keyboard >& key.log
2194       </screen>
2195       <para>
2196         and look in the resulting <filename>key.log</filename> file to
2197         find the error messages it gives for your layout.
2198       </para>
2199       <para>
2200         Note that the <constant>LANG_*</constant> and
2201         <constant>SUBLANG_*</constant> definitions are in
2202         <filename>include/winnls.h</filename>, which you might need to
2203         know to find out which numbers your language is assigned, and
2204         find it in the debugmsg output. The numbers will be
2205         <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
2206         the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
2207         <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
2208         <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
2209         could look for <literal>0414</literal> in the debugmsg output
2210         to find out why my keyboard won't detect.
2211       </para>
2212       <para>
2213         Once it works, submit it to the Wine project. If you use CVS,
2214         you will just have to do
2215       </para>
2216       <screen>
2217 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
2218       </screen>
2219       <para>
2220         from your main Wine directory, then submit
2221         <filename>layout.diff</filename> to
2222         <email>wine-patches@winehq.com</email> along with a brief note
2223         of what it is.
2224       </para>
2225       <para>
2226         If you don't use CVS, you need to do
2227       </para>
2228       <screen>
2229 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
2230       </screen>
2231       <para>
2232         and submit it as explained above.
2233       </para>
2234       <para>
2235         If you did it right, it will be included in the next Wine
2236         release, and all the troublesome applications (especially
2237         remote-control applications) and games that use scancodes will
2238         be happily using your keyboard layout, and you won't get those
2239         annoying fixme messages either.
2240       </para>
2241       <para>
2242         Good luck.
2243       </para>
2244     </sect1>
2245
2246     <sect1 id="odbc">
2247       <title>Using ODBC</title>
2248       <para>
2249         This section describes how ODBC works within Wine and how to configure
2250         it to do what you want (if it can do what you want).
2251       </para>
2252       <para>
2253         The ODBC system within wine, as with the printing system, is designed
2254         to hook across to the Unix system at a high level.  Rather than
2255         ensuring that all the windows code works under wine it uses a suitable
2256         Unix ODBC provider, such as UnixODBC.  Thus if you configure Wine to
2257         use the builtin odbc32.dll that wine dll will interface to your
2258         Unix ODBC package and let that do the work, whereas if you configure
2259         Wine to use the native odbc32.dll it will try to use the native
2260         ODBC32 drivers etc.
2261       </para>
2262       <sect2>
2263         <title>Using a Unix ODBC system with Wine</title>
2264         <para>
2265           The first step in using a Unix ODBC system with Wine is, of course,
2266           to get the Unix ODBC system working itself.  This may involve
2267           downloading code or rpms etc.  There are several Unix ODBC systems
2268           available; the one the author is used to is unixODBC (with the
2269           IBM DB2 driver). Typically such systems will include a tool, such
2270           as isql, which will allow you to access the data from the command
2271           line so that you can check that the system is working.
2272         </para>
2273         <para>
2274           The next step is to hook the Unix ODBC library to the wine builtin
2275           odbc32 dll.  The builtin odbc32 (currently) looks to the
2276           environmental variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
2277           for the name of the odbc library.  For example in the author's
2278           .bashrc file is the line:
2279         </para>
2280         <programlisting>
2281 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
2282         </programlisting>
2283         <para>
2284           If that environmental variable is not set then it looks for a
2285           library called libodbc.so and so you can add a symbolic link to
2286           equate that to your own library.  For example as root you could
2287           run the commands:
2288         </para>
2289         <programlisting>
2290 ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so
2291 /sbin/ldconfig
2292         </programlisting>
2293         <para>
2294           The last step in configuring this is to ensure that Wine is set up
2295           to run the builtin version of odbc32.dll, by modifying the DLL
2296           configuration.  This builtin dll merely acts as a stub between the
2297           calling code and the Unix ODBC library.
2298         </para>
2299         <para>
2300           If you have any problems then you can use the debugmsg channel
2301           odbc32 to trace what is happening.  One word of warning.  Some
2302           programs actually cheat a little and bypass the odbc library.  For
2303           example the Crystal Reports engine goes to the registry to check on
2304           the DSN.  The fix for this is documented at unixODBC's site where
2305           there is a section on using unixODBC with Wine.
2306         </para>
2307       </sect2>
2308       <sect2>
2309         <title>Using Windows ODBC drivers</title>
2310         <para>
2311           Does anyone actually have any experience of this and anything to
2312           add?
2313         </para>
2314       </sect2>
2315     </sect1>
2316
2317   </chapter>
2318
2319 <!-- Keep this comment at the end of the file
2320 Local variables:
2321 mode: sgml
2322 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
2323 End:
2324 -->