doc patch.

1 files changed, 85 insertions, 76 deletions

diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml
index 5b705115a..daaba9ac4 100644
--- a/winsup/utils/utils.sgml
+++ b/winsup/utils/utils.sgml
@@ -3,7 +3,10 @@
 <para>Cygwin comes with a number of command-line utilities that are
 used to manage the UNIX emulation portion of the Cygwin environment.
 While many of these reflect their UNIX counterparts, each was written
-specifically for Cygwin.</para>
+specifically for Cygwin.  You may use the long or short option names 
+interchangeably; for example, <literal>--help</literal> and 
+<literal>-h</literal> function identically.
+</para>
 
 <sect2 id="cygcheck"><title>cygcheck</title>
 
@@ -22,29 +25,20 @@ You must at least give either -s or -k or a program name
 <para>The <command>cygcheck</command> program is a diagnostic utility
 that examines your system and reports the information that is
 significant to the proper operation of Cygwin programs.  It can give
-information about a specific program (or program) you are trying to
+information about specific programs or libraries you are trying to
 run, general system information, or both.  If you list one or more
 programs on the command line, it will diagnose the runtime environment
-of that program or programs.  If you specify the <literal>-s</literal>
+of that program or programs, providing the names of DLL files on which
+the program depends.  If you specify the <literal>-s</literal>
 option, it will give general system information.  If you specify
 <literal>-s</literal> and list one or more programs on the command line,
 it reports on both.</para>
 
-<para>The <literal>-c</literal> option causes the "program" arguments
-to be interpreted as package names.  <command>cygcheck</command> will
-report the current version of the package that you specify.  With no
-arguments, <command>cygcheck</command> will report on all packages.</para>
-
-<para>The <command>cygcheck</command> program should be used to send
-information about your system to Cygnus for troubleshooting (if your
-support representative requests it).  When asked to run this command,
-include all the options plus any commands you are having trouble with,
-and save the output so that you can mail it to Cygnus, like
-this:</para>
-
-<screen>
-<prompt>C:\Cygnus&gt;</prompt> <userinput>cygcheck -s -v -r -h &gt; tocygnus.txt</userinput>
-</screen>
+<para>The <literal>-h</literal> option prints additional helpful
+messages in the report, at the beginning of each section.  It also
+adds table column headings.  While this is useful information, it also
+adds some to the size of the report, so if you want a compact report
+or if you know what everything is already, just leave this out.</para>
 
 <para>The <literal>-v</literal> option causes the output to be more
 verbose.  What this means is that additional information will be
@@ -55,67 +49,75 @@ directories on the PATH.  </para>
 
 <para>The <literal>-r</literal> option causes
 <command>cygcheck</command> to search your registry for information
-that is relevent to Cygnus programs.  These registry entries are the
-ones that have "Cygnus" in the name.  If you are paranoid about
+that is relevent to Cygwin programs.  These registry entries are the
+ones that have "Cygwin" in the name.  If you are paranoid about
 privacy, you may remove information from this report, but please keep
-in mind that doing so makes it harder for Cygnus to diagnose your
-problems.</para>
+in mind that doing so makes it harder to diagnose your problems.</para>
 
-<para>The <literal>-h</literal> option prints additional helpful
-messages in the report, at the beginning of each section.  It also
-adds table column headings.  While this is useful information, it also
-adds some to the size of the report, so if you want a compact report
-or if you know what everything is already, just leave this out.</para>
+<para>The <literal>-c</literal> option causes the arguments
+to be interpreted as package names.  <command>cygcheck</command> will
+report the current version of the package that you specify, or with no
+arguments, on all packages.</para>
+
+<para>The <command>cygcheck</command> program should be used to send
+information about your system for troubleshooting when requested.  
+When asked to run this command save the output so that you can email it,
+for example:</para>
+
+<screen>
+<prompt>C:\cygwin&gt;</prompt> <userinput>cygcheck -s -v -r -h &gt; cygcheck_output.txt</userinput>
+</screen>
 
 </sect2>
 
 <sect2 id="cygpath"><title>cygpath</title>
 
 <screen>
-Usage: cygpath.exe (-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME
-       cygpath.exe [-ADHPSW] 
-Output type options (required):
-  -u|--unix             print Unix form of NAME (default)
-  -w|--windows          print Windows form of NAME 
-  -t|--type             print Windows form of NAME with TYPE one of
-     dos                drive letter with backslashes (C:\WINNT)
-     mixed              drive letter with regular slashes (C:/WINNT)
+Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME
+       cygpath [-ADHPSW] 
+Output type options:
+  -d, --dos             print DOS (short) form of NAME (C:\PROGRA~1\)
+  -m, --mixed           like --windows, but with regular slashes (C:/WINNT)
+  -u, --unix            (default) print Unix form of NAME (/cygdrive/c/winnt)
+  -w, --windows         print Windows form of NAME (C:\WINNT)
+  -t, --type TYPE       print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
 Path conversion options:
-  -a|--absolute         output absolute path
-  -c|--close HANDLE     close HANDLE (for use in captured process)
-  -f|--file FILE        read FILE for input; use - to read from STDIN
-  -i|--ignore           ignore missing argument
-  -l|--long-name        print Windows long form of NAME (with -w only)
-  -p|--path             NAME is a PATH list (i.e., '/bin:/usr/bin')
-  -s|--short-name       print Windows short form of NAME (with -w only)
-System information output:
-  -A|--allusers         use `All Users' instead of current user for -D, -P
-  -D|--desktop          output `Desktop' directory and exit
-  -H|--homeroot         output `Profiles' directory (home root) and exit
-  -P|--smprograms       output Start Menu `Programs' directory and exit
-  -S|--sysdir           output system directory and exit
-  -W|--windir           output `Windows' directory and exit
-Other options:
-  -h|--help             output usage information and exit
-  -v|--version          output version information and exit
+  -a, --absolute        output absolute path
+  -l, --long-name       print Windows long form of NAME (with -w, -m only)
+  -p, --path            NAME is a PATH list (i.e., '/bin:/usr/bin')
+  -s, --short-name      print DOS (short) form of NAME (with -w, -m only)
+System information:
+  -A, --allusers        use `All Users' instead of current user for -D, -P
+  -D, --desktop         output `Desktop' directory and exit
+  -H, --homeroot        output `Profiles' directory (home root) and exit
+  -P, --smprograms      output Start Menu `Programs' directory and exit
+  -S, --sysdir          output system directory and exit
+  -W, --windir          output `Windows' directory and exit
 </screen>
 
 <para>The <command>cygpath</command> program is a utility that
 converts Windows native filenames to Cygwin POSIX-style pathnames and
-back.  It can be used when a Cygwin program needs to pass a file name
-to a native Windows program, or expects to get a file name from a
-native Windows program.  You may use the long or short option names
-interchangeably, even though only the short ones are described
-here.</para>
+vice versa.  It can be used when a Cygwin program needs to pass a file 
+name to a native Windows program, or expects to get a file name from a
+native Windows program.  Alternatively, <command>cygpath</command> can 
+output information about the location of important system directories 
+in either format.  
+</para>
 
 <para>The <literal>-u</literal> and <literal>-w</literal> options
-indicate whether you want a conversion from Windows to UNIX (POSIX)
-format (<literal>-u</literal>) or a conversion from UNIX (POSIX) to
-Windows format (<literal>-w</literal>).  You must give exactly
-one of these.  To give neither or both is an error.  Use the
-<literal>-l</literal> or <literal>-s</literal> option in combination 
-with the <literal>-w</literal> option to convert to Windows long or 
-short form.</para>
+indicate whether you want a conversion to UNIX (POSIX) format 
+(<literal>-u</literal>) or to Windows format (<literal>-w</literal>).  
+Use the <literal>-d</literal> to get DOS-style (8.3) file and path names.
+The <literal>-m</literal> option will output Windows-style format
+but with forward slashes instead of backslashes.  This option is 
+especially useful in shell scripts, which use backslashes as an escape 
+character.
+
+<para> In combination with the <literal>-w</literal> option, you can use
+the <literal>-l</literal> and <literal>-s</literal> options to use normal
+(long) or DOS-style (short) form. The <literal>-d</literal> option is 
+identical to <literal>-w</literal> and <literal>-s</literal> together.
+</para>
 
 <para>Caveat: The <literal>-l</literal> option does not work if the
 <em>check_case</em> parameter of <em>CYGWIN</em> is set to <em>strict</em>,
@@ -131,16 +133,22 @@ formats.</para>
 
 <para>The <literal>-i</literal> option supresses the print out of the
 usage message if no filename argument was given.  It can be used in
-make file rules converting variables to a proper format that may be
-omitted.</para>
+make file rules converting variables that may be omitted
+to a proper format.  Note that <command>cygpath</command> output may 
+contain spaces (C:\Program Files) so should be enclosed in quotes.
+</para>
+
 
 <example><title>Example cygpath usage</title>
 <screen>
 #!/bin/sh
-for i in `echo *.exe | sed 's/\.exe/.cc/'`
-do
-  notepad "`cygpath -w $i`"
-done
+if [ "${1}" = "" ];
+	then
+		XPATH=".";
+	else
+		XPATH="$(cygpath -w "${1}")";
+	fi
+	explorer $XPATH &
 </screen>
 </example>
 
@@ -149,14 +157,15 @@ done
 <literal>-S</literal>, and <literal>-W</literal> output directories used 
 by Windows that are not the same on all systems, for example 
 <literal>-S</literal> might output C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM. 
-The <literal>-A</literal> option forces use of the "All Users" directories 
-instead of the current user for the <literal>-D</literal> and 
-<literal>-P</literal> options. The <literal>-H</literal> shows the Windows'
-profiles directory that can be used as root of home.
+The <literal>-H</literal> shows the Windows profiles directory that can 
+be used as root of home.  The <literal>-A</literal> option forces use of 
+the "All Users" directories instead of the current user for the 
+<literal>-D</literal> and <literal>-P</literal> options. 
 On Win9x systems with only a single user, <literal>-A</literal> has no
 effect; <literal>-D</literal> and <literal>-AD</literal> would have the
-same output.
-The <literal>-ws</literal> options can be combined with the capital options.
+same output.  By default the output is in UNIX (POSIX) format; 
+use the <literal>-w</literal> or <literal>-d</literal> options to get
+other formats.
 
 </sect2>