2004-03-28 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

* how-programming.texinfo: Add note about gcc .lib linking.
        * pathnames.sgml: Mention create_devices.sh for /dev/ creation.

winsup/doc/ChangeLog

@@ -1,3 +1,8 @@
+2004-03-28  Joshua Daniel Franklin  <joshuadfranklin@yahoo.com>
+
+	* how-programming.texinfo: Add note about gcc .lib linking.
+	* pathnames.sgml: Mention create_devices.sh for /dev/ creation.
+
 2004-03-27  Corinna Vinschen  <corinna@vinschen.de>
 
 	* cygserver.sgml: New file.

winsup/doc/how-programming.texinfo

@@ -199,13 +199,14 @@ Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
 like it says that one may not "permit further redistribution of the
 Redistributables to their end users".  We take this to mean that we can
 give them to you, but you can't give them to anyone else, which is
-something that Cygnus (err... Red Hat) can't agree to.  Fortunately, we
+something that Red Hat can't agree to.  Fortunately, we
 have our own Win32 headers which are pretty complete.
 
-@subsection How do I link against .lib files?
+@subsection How do I link against a @samp{.lib} file?
 
-@strong{(Please note: This section has not yet been updated for the latest
-net release.)}
+If your @samp{.lib} file is a normal static or import library with
+C-callable entry points, you can list @samp{foo.lib} as an object file for
+gcc/g++, just like any @samp{*.o} file. Otherwise, here are some steps:
 
 1. Build a C file with a function table.  Put all functions you intend
 to use in that table.  This forces the linker to include all the object
@@ -263,22 +264,23 @@ make > make.log 2>&1
 make install > install.log 2>&1
 @end example
 
-Normally, this procedure will also attempt to build the documentation,
-which additionally requires db2html, and possibly other tools, which are
-not included in the Cygwin distribution.  You can get db2html as part of
-docbook, from @file{http://sources.redhat.com/docbook-tools/}.
+Normally, this procedure ignore errors in building the documentation,
+which requires tools which are not included in the Cygwin distribution.
+If you want to build the documentation on Linux, on most distributions a
+package named docbook-utils should get you most of what you need. For
+more information on building the documentation, see the README included
+in the cygwin-doc package.
 
 To check a cygwin1.dll, run "make check" in the winsup/cygwin directory.
 If that works, install everything @emph{except} the dll (if you can).
 Then, close down all cygwin programs (including bash windows, inetd,
-etc.), save your old dll, and copy the new dll to @emph{all} the
-places where the old dll was (if there is more than one on your
-machine).  Then start up a bash window and see what happens.  (Or better,
-run a cygwin program from the Windows command prompt.)
+etc.), save your old dll, and copy the new dll to the correct place.
+Then start up a bash window, or  run a cygwin program from the Windows
+command prompt, and see what happens.
 
 If you get the error "shared region is corrupted" it means that two
 different versions of cygwin1.dll are running on your machine at the
-same time.
+same time. Remove all but one. 
 
 @subsection How can I compile a powerpc NT toolchain?
 

winsup/doc/pathnames.sgml

@@ -159,6 +159,11 @@ default printer with the command <command>cat filename > PRN</command>
 directory as Cygwin automatically simulates it internally. 
 These devices cannot be seen with the command <command>ls /dev/</command>
 although commands such as <command>ls /dev/tty</command> work fine.
+If you want to be able to see all devices in
+<filename>/dev/</filename>, you can use Igor Pechtchanski's
+<ulink
+url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink>
+script.
 </para>
 <para>
 Cygwin supports the following devices commonly found on POSIX systems:
@@ -167,7 +172,8 @@ Cygwin supports the following devices commonly found on POSIX systems:
 <filename>/dev/tty</filename>, <filename>/dev/ttym</filename>, 
 <filename>/dev/ttyX</filename>, <filename>/dev/ttySX</filename>, 
 <filename>/dev/pipe</filename>, <filename>/dev/port</filename>, 
-<filename>/dev/ptmx</filename>, <filename>/dev/mem</filename>,
+<filename>/dev/ptmx</filename>, <filename>/dev/kmem</filename>,
+<filename>/dev/mem</filename>,
 <filename>/dev/random</filename>, and <filename>/dev/urandom</filename>.
 Cygwin also has several Windows-specific devices:
 <filename>/dev/comX</filename> (the serial ports, starting with 
@@ -175,8 +181,8 @@ Cygwin also has several Windows-specific devices:
 <filename>/dev/conin</filename> (Windows <filename>CONIN$</filename>),
 <filename>/dev/conout</filename> (Windows <filename>CONOUT$</filename>),
 <filename>/dev/clipboard</filename> (the Windows clipboard, currently
-text only), and
-<filename>/dev/windows</filename> (the Windows message queue).
+text only), and <filename>/dev/windows</filename> (the Windows message
+queue).
 </para>
 
 <para>Windows NT/W2K/XP additionally support raw devices like floppies,
@@ -254,9 +260,9 @@ The following three examples will not work as expected:
 </para>
 
 <screen>
-mount -f -b /dev/nst0 /dev/tape 
-mount -f -b /device/tape0 /dev/tape
-ln -s /device/tape0 /dev/tape
+mount -f -b /dev/nst0 /dev/tape     # DOES NOT WORK
+mount -f -b /device/tape0 /dev/tape # DOES NOT WORK
+ln -s /device/tape0 /dev/tape       # DOES NOT WORK
 </screen>
 </warning>
 
@@ -264,11 +270,11 @@ ln -s /device/tape0 /dev/tape
 
 <sect2><title>The .exe extension</title>
 
-<para> Executable program filenames end with .exe but the .exe need
-not be included in the command, so that traditional UNIX names can be
-used.  However, for programs that end in ".bat" and ".com", you cannot
-omit the extension.
-</para>
+<para> Executable program filenames end with <filename>.exe</filename>
+but the <filename>.exe</filename> need not be included in the command,
+so that traditional UNIX names can be used.  However, for programs that
+end in <filename>.bat</filename> and <filename>.com</filename>, you
+cannot omit the extension.  </para>
 
 <para>As a side effect, the <command> ls filename</command> gives
 information about <filename>filename.exe</filename> if