doc patch.

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
+<para>The <literal>-h</literal> option prints additional helpful
-to be interpreted as package names.  <command>cygcheck</command> will
+messages in the report, at the beginning of each section.  It also
-report the current version of the package that you specify.  With no
+adds table column headings.  While this is useful information, it also
-arguments, <command>cygcheck</command> will report on all packages.</para>
+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 <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>-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
+that is relevent to Cygwin programs.  These registry entries are the
-ones that have "Cygnus" in the name.  If you are paranoid about
+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
+in mind that doing so makes it harder to diagnose your problems.</para>
-problems.</para>
 
-<para>The <literal>-h</literal> option prints additional helpful
+<para>The <literal>-c</literal> option causes the arguments
-messages in the report, at the beginning of each section.  It also
+to be interpreted as package names.  <command>cygcheck</command> will
-adds table column headings.  While this is useful information, it also
+report the current version of the package that you specify, or with no
-adds some to the size of the report, so if you want a compact report
+arguments, on all packages.</para>
-or if you know what everything is already, just leave this out.</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
+Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME
-       cygpath.exe [-ADHPSW] 
+       cygpath [-ADHPSW] 
-Output type options (required):
+Output type options:
-  -u|--unix             print Unix form of NAME (default)
+  -d, --dos             print DOS (short) form of NAME (C:\PROGRA~1\)
-  -w|--windows          print Windows form of NAME 
+  -m, --mixed           like --windows, but with regular slashes (C:/WINNT)
-  -t|--type             print Windows form of NAME with TYPE one of
+  -u, --unix            (default) print Unix form of NAME (/cygdrive/c/winnt)
-     dos                drive letter with backslashes (C:\WINNT)
+  -w, --windows         print Windows form of NAME (C:\WINNT)
-     mixed              drive letter with regular slashes (C:/WINNT)
+  -t, --type TYPE       print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
 Path conversion options:
-  -a|--absolute         output absolute path
+  -a, --absolute        output absolute path
-  -c|--close HANDLE     close HANDLE (for use in captured process)
+  -l, --long-name       print Windows long form of NAME (with -w, -m only)
-  -f|--file FILE        read FILE for input; use - to read from STDIN
+  -p, --path            NAME is a PATH list (i.e., '/bin:/usr/bin')
-  -i|--ignore           ignore missing argument
+  -s, --short-name      print DOS (short) form of NAME (with -w, -m only)
-  -l|--long-name        print Windows long form of NAME (with -w only)
+System information:
-  -p|--path             NAME is a PATH list (i.e., '/bin:/usr/bin')
+  -A, --allusers        use `All Users' instead of current user for -D, -P
-  -s|--short-name       print Windows short form of NAME (with -w only)
+  -D, --desktop         output `Desktop' directory and exit
-System information output:
+  -H, --homeroot        output `Profiles' directory (home root) and exit
-  -A|--allusers         use `All Users' instead of current user for -D, -P
+  -P, --smprograms      output Start Menu `Programs' directory and exit
-  -D|--desktop          output `Desktop' directory and exit
+  -S, --sysdir          output system directory and exit
-  -H|--homeroot         output `Profiles' directory (home root) and exit
+  -W, --windir          output `Windows' directory 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
 </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
+vice versa.  It can be used when a Cygwin program needs to pass a file 
-to a native Windows program, or expects to get a file name from a
+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
+native Windows program.  Alternatively, <command>cygpath</command> can 
-interchangeably, even though only the short ones are described
+output information about the location of important system directories 
-here.</para>
+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)
+indicate whether you want a conversion to UNIX (POSIX) format 
-format (<literal>-u</literal>) or a conversion from UNIX (POSIX) to
+(<literal>-u</literal>) or to Windows format (<literal>-w</literal>).  
-Windows format (<literal>-w</literal>).  You must give exactly
+Use the <literal>-d</literal> to get DOS-style (8.3) file and path names.
-one of these.  To give neither or both is an error.  Use the
+The <literal>-m</literal> option will output Windows-style format
-<literal>-l</literal> or <literal>-s</literal> option in combination 
+but with forward slashes instead of backslashes.  This option is 
-with the <literal>-w</literal> option to convert to Windows long or 
+especially useful in shell scripts, which use backslashes as an escape 
-short form.</para>
+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
+make file rules converting variables that may be omitted
-omitted.</para>
+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/'`
+if [ "${1}" = "" ];
-do
+	then
-  notepad "`cygpath -w $i`"
+		XPATH=".";
-done
+	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 
+The <literal>-H</literal> shows the Windows profiles directory that can 
-instead of the current user for the <literal>-D</literal> and 
+be used as root of home.  The <literal>-A</literal> option forces use of 
-<literal>-P</literal> options. The <literal>-H</literal> shows the Windows'
+the "All Users" directories instead of the current user for the 
-profiles directory that can be used as root of home.
+<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.
+same output.  By default the output is in UNIX (POSIX) format; 
-The <literal>-ws</literal> options can be combined with the capital options.
+use the <literal>-w</literal> or <literal>-d</literal> options to get
+other formats.
 
 </sect2>