- add documentation section to README

README

@@ -21,8 +21,9 @@ directory (which contains this file), run:
 
 Run programs as "wine [options] program".  For more information and
 problem resolution, read the rest of this file, the Wine man page,
-the files in the documentation directory in the Wine source, and
-especially the wealth of information found at http://www.winehq.com.
+the files in the documentation directory in the Wine source
+(see "DOCUMENTATION"), and especially the wealth of information
+found at http://www.winehq.com.
 
 3. REQUIREMENTS
 
@@ -87,8 +88,8 @@ You also need flex version 2.5 or later and yacc.
 Bison will work as a replacement for yacc. If you are
 using RedHat or Debian, install the flex and bison packages.
 
-In case you want to build the documentation yourself, you'll also
-need the DocBook tools (db2html, db2ps, db2pdf).
+For requirements in case you intend to build the documentation yourself,
+see "DOCUMENTATION" section.
 
 4. COMPILATION
 
@@ -116,7 +117,6 @@ where "patch-file" is the name of the patch file (something like
 Wine-yymmdd.diff.gz). You can then re-run "./configure", and then
 run "make depend && make".
 
-
 5. SETUP
 
 Once Wine has been built correctly, you can do "make install"; this
@@ -127,8 +127,8 @@ Don't forget to uninstall any conflicting previous Wine installation
 first.  Try either "dpkg -r wine" or "rpm -e wine" or "make uninstall"
 before installing.
 
-If you want to build the documentation, you can run "make" in the
-documentation directory.
+If you want to read the documentation supplied with the Wine source,
+then see the "DOCUMENTATION" section.
 
 Wine requires a configuration file named named "config" in your
 ~/.wine directory. The format of this file is explained in the config file
@@ -164,7 +164,7 @@ For example: to run Solitaire:
 Note: the path of the file will also be added to the path when
       a full name is supplied on the commandline.
 
-Wine is not yet complete, so some programs may crash. Provided you set up
+Wine is not yet complete, so several programs may crash. Provided you set up
 winedbg correctly according to documentation/debugger.sgml, you will be dropped
 into a debugger so that you can investigate and fix the problem. For more
 information on how to do this, please read the file documentation/debugging.
@@ -180,16 +180,27 @@ as they launch Explorer somehow. This particular corruption (!$!$!$!$.pfr)
 can at least partially be fixed by using
 http://home.nexgo.de/andi.mohr/download/decorrupt_explorer
 
+7. DOCUMENTATION
+
+Some documentation (various Wine Guides etc.) can be found in the
+documentation/ directory (apart from also being available on WineHQ).
+
+If you want to process the SGML files in there, then you can run "make"
+in the documentation/ directory.
+Doing so requires the sgml tools package (for db2html, db2ps, db2pdf) named:
+Debian:		docbook-utils
+Mandrake:	sgml-tools-A.B.C-DDmdk
+SuSE:		docbktls-A.BB.C-DD
 
-7. GETTING MORE INFORMATION
+8. GETTING MORE INFORMATION
 
 WWW:	A great deal of information about Wine is available from WineHQ at
-	http://www.winehq.com/ : various user guides, application database,
+	http://www.winehq.com/ : various Wine Guides, application database,
 	bug tracking. This is probably the best starting point.
 
 FAQ:	The Wine FAQ is located at http://www.winehq.com/FAQ
 
-HOWTO:	The Wine HOWTO is available at
+HOWTO:	The Wine HOWTO (outdated !) is available at
 	http://www.westfalen.de/witch/wine-HOWTO.txt .
 
 Usenet:	The best place to get help or to report bugs is the Usenet newsgroup
@@ -210,10 +221,9 @@ Mailing lists:
 	There are several mailing lists for Wine developers; see 
 	http://www.winehq.com/dev.shtml#ml for more information.
 
-If you add something, or fix a bug, please send a patch ('diff -u'
-format preferred) to julliard@winehq.com or to the
-wine-patches@winehq.com mailing list for inclusion in the next
-release.
+If you add something, or fix a bug, please send a patch (in 'diff -u'
+format) to julliard@winehq.com or to the wine-patches@winehq.com
+mailing list for inclusion in the next release.
 
 --
 Alexandre Julliard

documentation/HOWTO-winelib

@@ -141,7 +141,7 @@ If you plan on using MFC, there are three hurdles to legally using
 MFC. The first hurdle is how to legally get MFC source code on your
 computer. MFC source code comes as a part of Visual Studio. The
 license for Visual Studio implies it is a single product that can not
-be broken up into its components. The cleanest way to get MFC on you
+be broken up into its components. The cleanest way to get MFC on your
 system is to use a dual boot Linux box with the windows partition
 visible to the Linux OS. Boot into windows and install Visual
 Studio. Since Visual Studio is installed on the computer, you have not
@@ -221,7 +221,7 @@ protection program that does work under Linux.
 During the execution of your program, Wine prints error messages to
 standard error. These error messages include "stubs", which are
 windows API functions that have not been completely
-implemented. Depending on the the system call, these could be harmless
+implemented. Depending on the system call, these could be harmless
 or crash your program. Most of the common windows API functions have
 already been implemented, so you should have no missing API functions
 or only a few missing functions. If you intend to continue with the
@@ -403,9 +403,7 @@ init	WinMain
 import  winmm
 
 If you need to list multiple DLLs, then the import specification can
-appear multiple times.
-
-FIXME: can multiple libraries appear on one import line?
+appear multiple times, one line per imported DLL.
 
 VI. Compiling A Win32 Program With Resources
 
@@ -494,7 +492,7 @@ windows program dumpbin and the windows version of the DLL. See the
 file <wine>/tools/winebuild/README for more details on the spec file
 format.
 
-During the the compile process, a command like
+During the compile process, a command like
     winebuild -fPIC -o winedll.spec.c -spec winedll.spec
 will be executed to create the file winedll.spec.c from information in
 the file winedll.spec. The file winedll.spec.c and winedll.c are
@@ -551,7 +549,7 @@ that will load the "hidden" DLL and initialize the function
 pointers. There is no need for any function ordinals unless your
 program calls functions by the ordinal.
 
-During the the compile process, a command like
+During the compile process, a command like
     winebuild -fPIC -o winedll.spec.c -spec winedll.spec
 will be executed to create the file winedll.spec.c from information in
 the file winedll.spec. The file winedll.spec.c and winedll.c are
@@ -559,7 +557,7 @@ compiled into object files and used to create the shared library.
 
 Now that the shared library is compiled, you still need to compile
 your program. Part of the compile process for your program will
-consist of a spec file for you program. For example,
+consist of a spec file for your program. For example,
     name	program
     mode	guiexe
     type	win32
@@ -571,7 +569,7 @@ specification that tells WineLib that the main program uses
 winedll.dll. If this import line is not included, the "hidden" DLL
 will not be loaded and the function pointers will not be initialized.
 
-During the the compile process, a command like
+During the compile process, a command like
     winebuild -fPIC -o program.spec.c -spec program.spec
 will be executed to create the file program.spec.c from information in
 the file program.spec. The file program.spec.c and your source code are
@@ -596,7 +594,7 @@ The init function is the name of the initialization function for the
 shared library (what you renamed DllMain to). There is no need for any
 function ordinals unless your program calls functions by the ordinal.
 
-During the the compile process, a command like
+During the compile process, a command like
     winebuild -fPIC -o winedll.spec.c -spec winedll.spec
 will be executed to create the file winedll.spec.c from information in
 the file winedll.spec. The file winedll.spec.c and the source code for
@@ -611,7 +609,7 @@ spec file for you program will look something like
     init	WinMain
     import winedll.dll
 
-During the the compile process, a command like
+During the compile process, a command like
     winebuild -fPIC -o program.spec.c -spec program.spec
 will be executed to create the file program.spec.c from information in
 the file program.spec. The file program.spec.c and your source code are
@@ -638,7 +636,7 @@ First of all WineLib suppport for Win16 has been discontinued
 for quite some time, because:
 
 1. It is difficult for us to support and it is impossible
-   to do so prefectly without special compiler support,
+   to do so perfectly without special compiler support,
    because of memory layout issues. For example Win16 int
    is 16-bit and data is aligned 16-bit.
 2. It is in almost all cases easier to port a

documentation/configuring.sgml

@@ -1434,8 +1434,10 @@ OPTIONAL:
       </sect2>
     </sect1>
 
-    <sect1 id="dll-overrides">
-      <title>Dll Overrides</title>
+    <sect1 id="dll-config">
+      <title>DLL configuration</title>
+      <sect2 id="dll-overrides">
+        <title>DLL Overrides</title>
   
         <para>
           Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
@@ -1454,7 +1456,7 @@ OPTIONAL:
           how this feature works.
         </para>
   
-      <sect2>
+        <sect3>
           <title>DLL types</title>
           <variablelist>
             <varlistentry>
@@ -1502,9 +1504,9 @@ OPTIONAL:
                 </para> </listitem>
             </varlistentry>
           </variablelist>          
-      </sect2>
+        </sect3>
   
-      <sect2>
+        <sect3>
           <title>The [DllDefaults] section</title>
           <variablelist>
             <varlistentry>
@@ -1516,9 +1518,9 @@ OPTIONAL:
                 </para> </listitem>
             </varlistentry>
           </variablelist>
-      </sect2>
+        </sect3>
   
-      <sect2>
+        <sect3>
           <title>The [DllPairs] section</title>
           <para>
             At one time, there was a section called [DllPairs] in the
@@ -1530,9 +1532,9 @@ OPTIONAL:
             still have this in your <filename>wine.conf</filename> or
             <filename>~/.wine/config</filename>, you may safely delete it.
           </para>
-      </sect2>
+        </sect3>
   
-      <sect2>
+        <sect3>
           <title>The [DllOverrides] section</title>
           <para>
             This section specifies how you want specific DLLs to be
@@ -1818,6 +1820,37 @@ OPTIONAL:
                 </para> </listitem>
             </varlistentry>
           </variablelist>          
+        </sect3>
+      </sect2>
+      <sect2 id="dll-missing">
+        <title>Missing DLLs</title>
+  
+        <para>
+          Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
+        </para>
+  
+        <para>
+	  In case Wine complains about a missing DLL, you should check whether
+	  this file is a publicly available DLL or a custom DLL belonging
+	  to your program (by searching for its name on the internet).
+	  If you managed to get hold of the DLL, then you should make sure
+	  that Wine is able to find and load it.
+	  DLLs usually get loaded according to the mechanism of the
+	  SearchPath() function.
+	  This function searches directories in the following order:
+	  
+	  a) The directory the program was started from.
+	  b) The current directory.
+	  c) The Windows system directory.
+	  d) The Windows directory.
+	  e) The PATH variable directories.
+	  
+	  In short: either put the required DLL into your application
+	  directory (might be ugly), or usually put it into the Windows system
+	  directory. Just find out its directory by having a look at the Wine
+	  config File variable "System" (which indicates the location of the
+	  Windows system directory) and the associated drive entry.
+        </para>
       </sect2>
     </sect1>
 

documentation/wine.conf.man.in

@@ -104,25 +104,30 @@ programs always request read-write access, even on CD-ROM drives...).
 .br
 default: "C:\\\\WINDOWS"
 .br
-Used to specify a different Windows directory; make sure to double the
-backslashes.
-So if you previously configured drive C: to be at /dos, this now means that
-the windows directory should be at /dos/WINDOWS.
+Used to specify where Wine is supposed to have its Windows directory
+(which is an essential part of a Windows environment); make sure to double
+the backslashes.
+In case of e.g. C:\\WINDOWS, with drive C: being configured as
+/home/user/wine_c, the /home/user/wine_c/WINDOWS directory would be used for
+this.
 .PP
 .I format: """system""=""<directory>"""
 .br
 default: "C:\\\\WINDOWS\\\\System"
 .br
-Used to specify a different system directory; make sure to double the
-backslashes.
-Again, given a drive C: at /dos, this would be at /dos/WINDOWS/System.
+Used to specify where Wine is supposed to have its Windows system directory
+(again, essential part of Windows environment); make sure to double the backslashes.
+Given a setting of C:\\WINDOWS\\System (the standard setting on Windows)
+and a C: drive again at /home/user/wine_c, the /home/user/wine_c/WINDOWS/System
+directory would be used for this.
 .PP
 .I format: """temp""=""<directory>"""
 .br
 default: "C:\\\\TEMP"
 .br
 Used to specify a directory where Windows applications can store 
-temporary files.
+temporary files. E.g. with a C: drive at /home/user/wine_c, this would be
+the /home/user/wine_c/TEMP directory.
 .PP
 .I format: """profile""=""<directory>"""
 .br

documentation/wine.man.in

@@ -81,6 +81,8 @@ RtlEnterCriticalSection.
 .br 
 .I --debugmsg +relay=advapi32
 will only turn on relay messages into the ADVAPI32 code.
+Never ever use simply --debugmsg +all ! Way too much info, and it crashes
+way too easily, thus confusing unexperienced users.
 .PP
 The full list of names is:
 all, accel, advapi, animate, aspi, atom, avifile, bitblt, bitmap, caret,