2004-01-11 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

        * Makefile.in: Add new target for single-file User's Guide, use new
        cygwin.dsl for output.
        * cygwin.dsl: New file, DSSSL stylesheet for custom Cygwin output.
        * cygwin-api.in.sgml: Update to DocBook SGML 4.2 DTD.
        * cygwin-ug-net.in.sgml: Update to DocBook SGML 4.2 DTD.
        * cygwin-ug.in.sgml: Update to DocBook SGML 4.2 DTD.
        * cygwinenv.sgml: Correct some tags. Add description of default values
        to ntsec, export, and error_start items.
        * dll.sgml: Add explanation of cyg prefix for DLLs.
        * effectively.sgml: Use systemitem tag for names of Cygwin packages.
        * how-programming.texinfo: Add example to FAQ entry.
        * pathnames.sgml: Add discussion of /proc filesystem.
	* setup-net.sgml: Correct some typos and grammar.

12 files changed, 297 insertions, 63 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 96e19d9a9..ed67974ef 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,19 @@
+2004-01-11  Joshua Daniel Franklin <joshuadfranklin@yahoo.com>
+
+	* Makefile.in: Add new target for single-file User's Guide, use new
+	cygwin.dsl for output.
+	* cygwin.dsl: New file, DSSSL stylesheet for custom Cygwin output.
+	* cygwin-api.in.sgml: Update to DocBook SGML 4.2 DTD.
+	* cygwin-ug-net.in.sgml: Update to DocBook SGML 4.2 DTD.
+	* cygwin-ug.in.sgml: Update to DocBook SGML 4.2 DTD.
+	* cygwinenv.sgml: Correct some tags. Add description of default values
+	to ntsec, export, and error_start items.
+	* dll.sgml: Add explanation of cyg prefix for DLLs.
+	* effectively.sgml: Use systemitem tag for names of Cygwin packages.
+	* how-programming.texinfo: Add example to FAQ entry.
+	* pathnames.sgml: Add discussion of /proc filesystem.
+	* setup-net.sgml: Correct some typos and grammar.
+
 2003-09-01  Corinna Vinschen  <corinna@vinschen.de>
 
 	* pathnames.sgml: Remove description how to mount raw devices and
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index 4be5f06e5..d3e7772e2 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -29,45 +29,51 @@ TEXI2HTML:=texi2html
 
 include $(srcdir)/../Makefile.common
 
-TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool \
-	 cygwin-ug.sgml cygwin-ug-net.sgml
+TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool.exe *.junk \
+	 cygwin-ug.sgml cygwin-ug \
+	 cygwin-ug-net.sgml cygwin-ug-net cygwin-ug-net.html \
+	 cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int
 
 .SUFFIXES:
 
-# You can add cygwin-api/cygwin-api.html if you want to.
 all : \
 	cygwin-ug/cygwin-ug.html \
 	cygwin-ug-net/cygwin-ug-net.html \
+	cygwin-ug-net.html \
 	cygwin-api-int/cygwin-api-int.html \
 	cygwin-api/cygwin-api.html \
 	$(DOC) \
 	$(HTMLDOC)
 
 clean:
-	rm -f $(TOCLEAN)
+	rm -Rf $(TOCLEAN)
 
 install:	all
 
+# jw -d $(srcdir)/cygwin.dsl#html cygwin-ug-net.sgml
 cygwin-ug/cygwin-ug.html : cygwin-ug.sgml doctool
-	-db2html $<
+	-db2html -d $(srcdir)/cygwin.dsl#html $<
 
 cygwin-ug.sgml : cygwin-ug.in.sgml ./doctool Makefile
 	-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
 
+cygwin-ug-net.html : cygwin-ug-net.sgml doctool
+	-jw -d $(srcdir)/cygwin.dsl#html -u $<
+
 cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool
-	-db2html $<
+	-db2html -d $(srcdir)/cygwin.dsl#html $<
 
 cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile
 	-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
 
 cygwin-api/cygwin-api.html : cygwin-api.sgml
-	-db2html $<
+	-db2html -d $(srcdir)/cygwin.dsl#html $<
 
 cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile
 	-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
 
 cygwin-api-int/cygwin-api-int.html : cygwin-api-int.sgml
-	-db2html $<
+	-db2html -d $(srcdir)/cygwin.dsl#html $<
 
 cygwin-api-int.sgml : cygwin-api.in.sgml ./doctool Makefile
 	-./doctool -i -m $(SGMLDIRS) -s $(srcdir) -b cygwin-api-int -o $@ $<
diff --git a/winsup/doc/cygwin-api.in.sgml b/winsup/doc/cygwin-api.in.sgml
index 06baf5247..d141935f6 100644
--- a/winsup/doc/cygwin-api.in.sgml
+++ b/winsup/doc/cygwin-api.in.sgml
@@ -1,4 +1,4 @@
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
   <!ENTITY cygnus-copyright "<YEAR>1998</YEAR><HOLDER>Red Hat, Inc.</HOLDER>">
   <!ENTITY cygnus-code-copyright "
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
diff --git a/winsup/doc/cygwin-ug-net.in.sgml b/winsup/doc/cygwin-ug-net.in.sgml
index aceb33460..634c9acab 100644
--- a/winsup/doc/cygwin-ug-net.in.sgml
+++ b/winsup/doc/cygwin-ug-net.in.sgml
@@ -1,4 +1,4 @@
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
   <!ENTITY cygnus-copyright
   "<YEAR>1999,2000,2001</YEAR>
   <HOLDER>Red Hat, Inc.</HOLDER>">
diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml
index 91054f324..7727b1767 100644
--- a/winsup/doc/cygwin-ug.in.sgml
+++ b/winsup/doc/cygwin-ug.in.sgml
@@ -1,4 +1,4 @@
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
   <!ENTITY cygnus-copyright "<YEAR>1999,2000,2001</YEAR>
   <HOLDER>Red Hat, Inc.</HOLDER>">
   <!ENTITY cygnus-code-copyright "
diff --git a/winsup/doc/cygwin.dsl b/winsup/doc/cygwin.dsl
new file mode 100644
index 000000000..bf855c19f
--- /dev/null
+++ b/winsup/doc/cygwin.dsl
@@ -0,0 +1,149 @@
+<!DOCTYPE style-sheet PUBLIC
+          "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY % html "IGNORE">
+<![%html;[
+<!ENTITY % print "IGNORE">
+<!ENTITY docbook.dsl PUBLIC
+         "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
+	 CDATA dsssl>
+]]>
+<!ENTITY % print "INCLUDE">
+<![%print;[
+<!ENTITY docbook.dsl PUBLIC
+         "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
+	 CDATA dsssl>
+]]>
+]>
+
+<style-sheet>
+
+<!--      PRINT       -->
+<style-specification id="print" use="docbook">
+<style-specification-body> 
+
+;; The following are 
+;; <!-- Cygnus customizations by Mark Galassi -->
+;; ====================
+;; customize the print stylesheet
+;; ====================
+
+;; make funcsynopsis look pretty
+(define %funcsynopsis-decoration%
+  ;; Decorate elements of a FuncSynopsis?
+  #t)
+
+;; use graphics in admonitions, and have their path be "."
+;; NO: we are not yet ready to use gifs in TeX and so forth
+(define %admon-graphics-path%
+  "./")
+(define %admon-graphics%
+  #f)
+
+;; this is necessary because right now jadetex does not understand
+;; symbolic entities, whereas things work well with numeric entities.
+(declare-characteristic preserve-sdata?
+          "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
+          #f)
+(define %two-side% #t)
+
+(define %section-autolabel% 
+  ;; Are sections enumerated?
+  #t)
+;; (define %title-font-family% 
+;;   ;; The font family used in titles
+;;   "Ariel")
+(define %visual-acuity%
+  ;; General measure of document text size
+  ;; "presbyopic"
+  ;; "large-type"
+  "presbyopic")
+
+(define %generate-part-toc% #t)
+
+
+;;; The following customizations are from Tim Waugh's selfdocbook
+;;; http://cyberelk.net/tim/docbook/
+;;; 
+;;; TeX backend can go to PS (where EPS is needed)
+;;; or to PDF (where PNG is needed).  So, just
+;;; omit the file extension altogether and let
+;;; tex/pdfjadetex sort it out on its own.
+(define (graphic-file filename)
+ (let ((ext (file-extension filename)))
+  (if (or (equal? 'backend 'tex) ;; Leave off the extension for TeX
+          (not filename)
+          (not %graphic-default-extension%)
+          (member ext %graphic-extensions%))
+      filename
+      (string-append filename "." %graphic-default-extension%))))
+
+;;; Full justification.
+(define %default-quadding%
+ 'justify)
+
+;;; To make URLs line wrap we use the TeX 'url' package.
+;;; See also: jadetex.cfg
+;; First we need to declare the 'formatting-instruction' flow class.
+(declare-flow-object-class formatting-instruction
+"UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")
+;; Then redefine ulink to use it.
+(element ulink
+  (make sequence
+    (if (node-list-empty? (children (current-node)))
+	; ulink url="...", /ulink
+	(make formatting-instruction
+	  data: (string-append "\\url{"
+			       (attribute-string (normalize "url"))
+			       "}"))
+	(if (equal? (attribute-string (normalize "url"))
+		    (data-of (current-node)))
+	; ulink url="http://...", http://..., /ulink
+	    (make formatting-instruction data:
+		  (string-append "\\url{"
+				 (attribute-string (normalize "url"))
+				 "}"))
+	; ulink url="http://...", some text, /ulink
+	    (make sequence
+	      ($charseq$)
+	      (literal " (")
+	      (make formatting-instruction data:
+		    (string-append "\\url{"
+				   (attribute-string (normalize "url"))
+				   "}"))
+	      (literal ")"))))))
+;;; And redefine filename to use it too.
+(element filename
+  (make formatting-instruction
+    data: (string-append "\\path{" (data-of (current-node)) "}")))
+
+</style-specification-body>
+</style-specification>
+
+<!--      HTML       -->
+<style-specification id="html" use="docbook">
+<style-specification-body> 
+
+;; If true (non-zero), elements of the FuncSynopsis will be decorated 
+;; (e.g. bold or italic).
+(define %funcsynopsis-decoration% #t)
+
+;; If true, a Table of Contents will be generated for each 'Article'.
+(define %generate-article-toc% #t)
+
+;; If true, a Table of Contents will be generated for each Part.
+(define %generate-part-toc% #t)
+
+;; The name of the stylesheet to place in the HTML LINK TAG, 
+;; or #f to suppress the stylesheet LINK.
+(define %stylesheet% "docbook.css")
+
+(define %use-id-as-filename% #t)
+
+(define %html-ext% ".html")
+
+</style-specification-body>
+</style-specification>
+
+<external-specification id="docbook" document="docbook.dsl">
+
+</style-sheet>
diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml
index c78299e5e..439a22169 100644
--- a/winsup/doc/cygwinenv.sgml
+++ b/winsup/doc/cygwinenv.sgml
@@ -8,7 +8,7 @@ by prefixing with <literal>no </literal>.</para>
 
 <itemizedlist Mark="bullet">
 <listitem>
-<para><FirstTerm>(no)binmode</FirstTerm> - if set, non-disk 
+<para><envar>(no)binmode</envar> - if set, non-disk 
 (e.g. pipe and COM ports) file opens default to binary mode 
 (no CRLF translation) instead of text mode.  Defaults to set (binary
 mode).  By default, devices are opened in binary mode, so this option
@@ -24,24 +24,24 @@ pipe to binary by default.
 always open in binary mode.</para></warning>
 </listitem>
 <listitem>
-<para><FirstTerm>check_case:level</FirstTerm> - Controls the behaviour of
+<para><envar>check_case:level</envar> - Controls the behaviour of
 Cygwin when a user tries to open or create a file using a case different from
 the case of the path as asved on the disk.
 <literal>level</literal> is one of <literal>relaxed</literal>,
 <literal>adjust</literal> and <literal>strict</literal>.</para>
 <itemizedlist Mark="bullet">
 <listitem>
-<para><FirstTerm>relaxed</FirstTerm> which is the default behaviour simply
+<para><envar>relaxed</envar> which is the default behaviour simply
 ignores case. That's the default for native Windows applications as well.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>adjust</FirstTerm> behaves mostly invisible. The POSIX input
+<para><envar>adjust</envar> behaves mostly invisible. The POSIX input
 path is internally adjusted in case, so that the resulting DOS path uses the
 correct case throughout. You can see the result when changing the directory
 using a wrong case and calling <command>/bin/pwd</command> afterwards.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>strict</FirstTerm> results in a error message if the case
+<para><envar>strict</envar> results in a error message if the case
 isn't correct. Trying to open a file <filename>Foo</filename> while a file
 <filename>fOo</filename> exists results in a "no such file or directory"
 error. Trying to create a file <filename>BAR</filename> while a file
@@ -52,7 +52,7 @@ case" error.</para>
 </listitem>
 
 <listitem>
-<para><FirstTerm>codepage:[ansi|oem]</FirstTerm> - Windows console 
+<para><envar>codepage:[ansi|oem]</envar> - Windows console 
 applications can use different character sets (codepages) for drawing
 characters.  The first setting, called "ansi", is the default.
 This character set contains various forms of latin characters used
@@ -68,22 +68,33 @@ Cygwin, you can use this option to select an appropriate codepage.
 </listitem>
 
 <listitem>
-<para><FirstTerm>(no)envcache</FirstTerm> - If set, environment variable
+<para><envar>(no)envcache</envar> - If set, environment variable
 conversions (between Win32 and POSIX) are cached.  Note that this is may
 cause problems if the mount table changes, as the cache is not invalidated
 and may contain values that depend on the previous mount table
 contents. Defaults to set.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)export</FirstTerm> - if set, the final values of these
-settings are re-exported to the environment as $CYGWIN again.</para>
+<para><envar>(no)export</envar> - if set, the final values of these
+settings are re-exported to the environment as <envar>CYGWIN</envar> again.
+Defaults to off.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>error_start:filepath</FirstTerm> - if set, runs <filename>filepath</filename>
-when cygwin encounters a fatal error.  This is useful for debugging.
-<filename>filepath</filename> is usually set to the path to the <filename>gdb</filename>
-program.</para>
-<para><FirstTerm>(no)glob[:ignorecase]</FirstTerm> - if set, command line arguments
+<para><envar>error_start:filepath</envar> - if set, runs 
+<filename>filepath</filename> when cygwin encounters a fatal error.  This is
+useful for debugging.  <filename>filepath</filename> is usually set to the path
+to the <command>gdb</command> or <command>dumper</command> program.
+There is no default set.</para>
+</listitem>
+<listitem>
+<para><envar>forkchunk:32768</envar> - causes <function>fork()</function>
+to copy memory some number of bytes at a time, in the above example 
+32768 bytes (32Kb) at a time. The default is to copy as many bytes as 
+possible, which is preferable in most cases but may slow some older systems
+down.
+</listitem>
+<listitem>
+<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
 containing UNIX-style file wildcard characters (brackets, question mark,
 asterisk, escaped with \) are expanded into lists of files that match 
 those wildcards.
@@ -93,40 +104,41 @@ Default is set.</para>
 If supplied, wildcard matching is case insensitive.  The default is <literal>noignorecase</literal></para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)ntea</FirstTerm> - if set, use the full NT Extended
+<para><envar>(no)ntea</envar> - if set, use the full NT Extended
 Attributes to store UNIX-like inode information.
 This option only operates under Windows NT. Defaults to not set. </para>
 <Warning><Title>Warning!</Title> <para>This may create additional
 <emphasis>large</emphasis> files on non-NTFS partitions.</para></Warning>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)ntsec</FirstTerm> - if set, use the NT security
+<para><envar>(no)ntsec</envar> - if set, use the NT security
 model to set UNIX-like permissions on files and processes. The
 file permissions can only be set on NTFS partitions. FAT doesn't
-support the NT file security. For more information, read the documentation
-in <citation>ntsec.sgml</citation>.</para>
+support the NT file security. Defaults to set. For more information, read
+the documentation in <Xref Linkend="ntsec">.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)smbntsec</FirstTerm> - if set, use `ntsec' on remote
+<para><envar>(no)smbntsec</envar> - if set, use <envar>ntsec</envar> on remote
 drives as well (this is the default). If you encounter problems with NT shares
-or Samba drives, setting this to `nosmbntsec' could help. In that case the
-permission and owner/group information is faked as on FAT partitions.
-A reason for a non working ntsec on remote drives could be insufficient
-permissions of the users. Since the needed user rights are somewhat dangerous
-(SeRestorePrivilege) it's not always an option to grant that rights to users.
-However, this shouldn't be a problem in NT domain environments.</para>
+or Samba drives, setting this to <envar>nosmbntsec</envar> could help. In that
+case the permission and owner/group information is faked as on FAT partitions.
+A reason for a non working <envar>ntsec</envar> on remote drives could be
+insufficient permissions of the users. Since the needed user rights are
+somewhat dangerous (SeRestorePrivilege) it's not always an option to grant that
+rights to users.  However, this shouldn't be a problem in NT domain
+environments.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)reset_com</FirstTerm> - if set, serial ports are reset
+<para><envar>(no)reset_com</envar> - if set, serial ports are reset
 to 9600-8-N-1 with no flow control when used. This is done at open
 time and when handles are inherited.  Defaults to set.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)strip_title</FirstTerm> - if set, strips the directory
+<para><envar>(no)strip_title</envar> - if set, strips the directory
 part off the window title, if any.  Default is not set.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)title</FirstTerm> - if set, the title bar
+<para><envar>(no)title</envar> - if set, the title bar
 reflects the name of the program currently running.  Default is not
 set.  Note that under Win9x the title bar is always enabled and it is
 stripped by default, but this is because of the way Win9x works.  In
@@ -134,7 +146,7 @@ order not to strip, specify <literal>title</literal> or <literal>title
 nostrip_title</literal>.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)tty</FirstTerm> - if set, Cygwin enables extra support
+<para><envar>(no)tty</envar> - if set, Cygwin enables extra support
 (i.e., termios) for UNIX-like ttys. 
 It is not compatible with some Windows programs.
 Defaults to not set, in which case the tty is opened in text mode 
@@ -144,7 +156,7 @@ This option must be specified before starting a Cygwin shell
 and it cannot be changed in the shell.</para>
 </listitem>
 <listitem>
-<para><FirstTerm>(no)winsymlinks</FirstTerm> - if set, Cygwin creates
+<para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
 symlinks as Windows shortcuts with a special header and the R/O attribute
 set. If not set, Cygwin creates symlinks as plain files with a magic number,
 a path and the system attribute set. Defaults to set.</para>
diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.sgml
index 7bb10829c..a44129b3c 100644
--- a/winsup/doc/dll.sgml
+++ b/winsup/doc/dll.sgml
@@ -91,13 +91,21 @@ you will probably want to use the complete syntax:</para>
     -Wl,--out-implib=lib${module}.dll.a \
     -Wl,--export-all-symbols \
     -Wl,--enable-auto-import \
-    -Wl,--whole-archive ${old_lib} \
+    -Wl,--whole-archive ${old_libs} \
     -Wl,--no-whole-archive ${dependency_libs}</screen>
 
-<para>Where ${module} is the name of your DLL, ${old_lib} are all
+<para>
+The name of your library is <literal>${module}</literal>, prefixed with
+<literal>cyg</literal> for the DLL and <literal>lib</literal> for the
+import library. Cygwin DLLs use the <literal>cyg</literal> prefix to 
+differentiate them from native-Windows MinGW DLLs, see 
+<ulink URL="http://mingw.org">the MinGW website</ulink> for more details.
+<literal>${old_libs}</literal> are all
 your object files, bundled together in static libs or single object
-files and the ${dependency_libs} are import libs you need to
-link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'.</para>
+files and the <literal>${dependency_libs}</literal> are import libs you 
+need to link against, e.g 
+<userinput>'-lpng -lz -L/usr/local/special -lmyspeciallib'</userinput>.
+</para>
 </sect2>
 
 <sect2 id="dll-link"><title>Linking Against DLLs</title>
diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml
index d6c2d9ad9..59ab01ffb 100644
--- a/winsup/doc/effectively.sgml
+++ b/winsup/doc/effectively.sgml
@@ -83,7 +83,7 @@ Windows programs, use a DOS prompt, running only the occasional Cygwin
 command or script. Next would be to run <command>bash</command> with 
 the default DOS box. To make Cygwin more Unix compatible in this case, 
 set <EnVar>CYGWIN=tty</EnVar> (see <Xref Linkend="using-cygwinenv">).
-Alternatively, the optional <command>rxvt</command> package provides 
+Alternatively, the optional <systemitem>rxvt</systemitem> package provides 
 a native-Windows version of the popular X11 terminal emulator (it is not 
 necessary to set <EnVar>CYGWIN=tty</EnVar> with <command>rxvt</command>). 
 Using <command>rxvt.exe</command> provides the most Unix-like environment, 
@@ -94,14 +94,15 @@ but expect some compatibility problems with Windows programs.
 
 <sect2> <title>Cygwin and Windows Networking</title>
 <para>
-Many popular Cygwin packages, such as <command>ncftp</command>, 
-<command>lynx</command>, and <command>wget</command>, require a 
+Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>, 
+<systemitem>lynx</systemitem>, and <systemitem>wget</systemitem>, require a 
 network connection.  Since Cygwin relies on Windows for connectivity, 
 if one of these tools is not working as expected you may need to 
 troubleshoot using Windows tools. The first test is to see if you
 can reach the URL's host with <command>ping.exe</command>, one of the 
 few utilities included with every Windows version since Windows 95.
-If you chose to install the inetutils package, you may have both
+If you chose to install the <systemitem>inetutils</systemitem> package, 
+you may have both
 Windows and Cygwin versions of utilities such as <command>ftp</command>
 and <command>telnet</command>. If you are having problems using one
 of these programs, see if the alternate one works as expected. 
@@ -127,10 +128,10 @@ programs in your environment.
 <sect2><title>The cygutils package</title>
 
 <para>
-The optional cygutils package contains miscellaneous tools that are
+The optional <systemitem>cygutils</systemitem> package contains miscellaneous tools that are
 small enough to not require their own package. It is not included in a
 default Cygwin install; select it from the Utils category in 
-<command>setup.exe</command>. Several of the cygutils tools are useful
+<command>setup.exe</command>. Several of the <systemitem>cygutils</systemitem> tools are useful
 for interacting with Windows. 
 </para>
 
@@ -138,7 +139,7 @@ for interacting with Windows.
 One of the hassles of Unix-Windows interoperability is the different line 
 endings on text files.  As mentioned in <Xref Linkend="using-textbinary">, 
 Unix tools such as <command>tr</command> can convert between CRLF and LF 
-endings, but cygutils provides several dedicated programs: 
+endings, but <systemitem>cygutils</systemitem> provides several dedicated programs: 
 <command>conv</command>, <command>d2u</command>, <command>dos2unix</command>, 
 <command>u2d</command>, and <command>unix2dos</command>. Use the
 <literal>--help</literal> switch for usage information. 
@@ -153,7 +154,8 @@ different.  By default, Cygwin uses a mechanism that creates symbolic
 links that are compatible with standard Microsoft .lnk files. However,
 they do not include much of the information that is available in a 
 standard Microsoft shortcut, such as the working directory, an icon, 
-etc.  The cygutils package includes a <command>mkshortcut</command> 
+etc.  The <systemitem>cygutils</systemitem> package includes a 
+<command>mkshortcut</command> 
 utility for creating standard Microsoft .lnk files.
 </para>
 
@@ -172,8 +174,8 @@ Windows shortcuts.
 <sect2><title>Printing with cygutils</title>
 <para>
 There are several options for printing from Cygwin, including the 
-<command>lpr</command> found in cygutils (not to be confused with the 
-native Windows <command>lpr.exe</command>). The easiest way to use cygutils' 
+<command>lpr</command> found in <systemitem>cygutils</systemitem> (not to be confused with the 
+native Windows <command>lpr.exe</command>). The easiest way to use <systemitem>cygutils</systemitem>' 
 <command>lpr</command> is to specify a default device name in the 
 <EnVar>PRINTER</EnVar> environment variable.  You may also specify a device 
 on the command line with the <literal>-d</literal> or <literal>-P</literal> 
@@ -194,8 +196,9 @@ the backslash as an escape character.
 <command>lpr</command> sends raw data to the printer; no formatting is done.
 Many, but not all, printers accept plain text as input. If your printer 
 supports PostScript, packages such as 
-<command>a2ps</command> and <command>enscript</command> can prepare text
-files for printing. The ghostscript package also provides some translation
+<systemitem>a2ps</systemitem> and <systemitem>enscript</systemitem> can prepare 
+text files for printing. The <systemitem>ghostscript</systemitem> package also 
+provides some translation
 from PostScript to various native printer languages. Additionally, a native 
 Windows application for printing PostScript, <command>gsprint</command>, is 
 available from the <ulink URL="http://www.cs.wisc.edu/~ghost/">Ghostscript
diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo
index d54ec3d4e..3ec161e75 100644
--- a/winsup/doc/how-programming.texinfo
+++ b/winsup/doc/how-programming.texinfo
@@ -576,6 +576,18 @@ Unix emulation environment and defining _WIN32 confuses some programs
 which think that they have to make special concessions for a Windows
 environment which Cygwin handles automatically.
 
+Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to
+tell which compiler (or settings) you're running.
+Check this out in detail by running, for example
+
+@example
+       $ gcc  -dM -E -xc /dev/null >gcc.txt
+       $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt
+       $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt
+@end example
+Then use the diff and grep utilities to check
+what the difference is.
+
 @subsection How should I port my Unix GUI to Windows?
 
 There are two basic strategies for porting Unix GUIs to Windows.
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml
index 13441e995..56a5f7d69 100644
--- a/winsup/doc/pathnames.sgml
+++ b/winsup/doc/pathnames.sgml
@@ -292,6 +292,30 @@ when needed.
 </para>
 </sect2>
 
+<sect2><title>The /proc filesystem</title> 
+<para>
+Cygwin, like Linux and other similar operating systems, supports the
+<filename>/proc</filename> virtual filesystem. The files in this
+directory are representations of various aspects of your system,
+for example the command <userinput>cat /proc/cpuinfo</userinput> 
+displays information such as what model and speed processor you have.
+</para>
+<para>
+One unique aspect of the Cygwin <filename>/proc</filename> filesystem
+is <filename>/proc/registry</filename>, which displays the Windows
+registry with each <literal>KEY</literal> as a directory and each
+<literal>VALUE</literal> as a file. As anytime you deal with the
+Windows registry, use caution since changes may result in an unstable
+or broken system.
+</para>
+<para>
+The Cygwin <filename>/proc</filename> is not as complete as the
+one in Linux, but it provides significant capabilities. The
+<systemitem>procps</systemitem> package contains several utilities
+that use it.
+</para>
+</sect2>
+
 <sect2><title>The @pathnames</title> 
 <para>To circumvent the limitations on shell line length in the native
 Windows command shells, Cygwin programs expand their arguments
diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml
index c9b692712..a01472898 100644
--- a/winsup/doc/setup-net.sgml
+++ b/winsup/doc/setup-net.sgml
@@ -3,7 +3,7 @@
 <sect1><title>Internet Setup</title>
 <para>To install the Cygwin net release, go to <ulink
 URL="http://cygwin.com/">http://cygwin.com/</ulink> and click on <ulink
-URL="http://cygwin.com/">"Install Cygwin Now!"</ulink>.  This will
+URL="http://cygwin.com/setup.exe">"Install Cygwin Now!"</ulink>.  This will
 download a GUI installer called <command>setup.exe</command> which can
 be run to download a complete cygwin installation via the internet.
 Follow the instructions on each screen to install Cygwin.
@@ -141,9 +141,9 @@ For each selected mirror site, <command>setup.exe</command> downloads a
 small text file called <literal>setup.bz2</literal> that contains a list
 of packages available from that site along with some basic information about
 each package which <command>setup.exe</command> parses and uses to create the 
-chooser window. For details about the format of this file, see
-<ulink URL="http://sources.redhat.com/cygwin-apps/setup.html#setup.ini">
-http://sources.redhat.com/cygwin-apps/setup.html</ulink>.
+chooser window. For details about the format of this file, see 
+the <ulink URL="http://sources.redhat.com/cygwin-apps/setup.html">
+setup.exe homepage</ulink>.
 </para>
 <para>
 The chooser is the most complex part of <command>setup.exe</command>. 
@@ -155,7 +155,10 @@ will install only the packages in the <literal>Base</literal> category
 and their dependencies, resulting in a minimal Cygwin installation.
 However, this will not include many commonly used tools such as 
 <command>gcc</command> (which you will find in the <literal>Devel</literal> 
-category). 
+category).  Since <command>setup.exe</command> automatically selects
+dependencies, be careful not to unselect any required packages. In 
+particular, everything in the <literal>Base</literal> category is
+required.
 </para>
 <para>
 You can change <command>setup.exe</command>'s view style, which is helpful
@@ -191,7 +194,8 @@ though mirrors have at least one previous version and occasionally there
 is a testing or beta version of a package available. To see these package,
 click on the <literal>Prev</literal> or <literal>Exp</literal> radio button.
 Be warned, however, that the next time you run <command>setup.exe</command> 
-it will try to replace old or experimental versions with the latest. 
+it will try to replace old or experimental versions with the current
+stable version. 
 </para>
 </sect2>