Added a description of the "-E" command-line option to cl65's document.

Improved other descriptions, to make them more consistent and accurate.

diff --git a/doc/cl65.sgml b/doc/cl65.sgml
index ffeba23213f9310ef76daed20f6586c7fe38a2c1..8b3c02cbb88050544bec4e47cdc4a9b305c5e35d 100644 (file)
--- a/doc/cl65.sgml
+++ b/doc/cl65.sgml
@@ -2,8 +2,9 @@
 
 <article>
 <title>cl65 Users Guide
-<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
-<date>01.08.2000, 27.11.2000, 02.10.2001
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+<date>2017-05-24
 
 <abstract>
 cl65 is the compile &amp; link utility for cc65, the 6502 C compiler. It was
@@ -50,6 +51,7 @@ Short options:
   -C name                       Use linker config file
   -Cl                           Make local variables static
   -D sym[=defn]                 Define a preprocessor symbol
+  -E                            Stop after the preprocessing stage
   -I dir                        Set a compiler include directory path
   -L path                       Specify a library search path
   -Ln name                      Create a VICE label file
@@ -120,56 +122,66 @@ Long options:
 ---------------------------------------------------------------------------
 </verb></tscreen>
 
-Most of the options have the same meaning than the corresponding compiler,
-assembler or linker option. See the documentation for these tools for an
+Most of the options have the same meanings as the corresponding compiler,
+assembler, and linker options. See the documentation for those tools for an
 explanation. If an option is available for more than one of the tools, it
-is set for all tools, where it is available. One example for this is <tt/-v/:
-The compiler, the assembler and the linker are all called with the <tt/-v/
+is set for all tools where it is available. One example for that is <tt/-v/:
+The compiler, the assembler, and the linker are all called with the <tt/-v/
 switch.
 
 There are a few remaining options that control the behaviour of cl65:
 
 <descrip>
 
+  <tag><tt>-E</tt></tag>
+
+  This option is passed to the cc65 compiler; and, it forces cl65 to stop
+  before the assembly step. That means that C-level preprocessor directives
+  are obeyed; and, macroes are expanded.  But, the C source isn't compiled.
+  If the <tt/-o/ option isn't used, then the C code results are written into
+  files with a ".i" suffix on their base names.  Assembler files, object
+  files, and libraries given on the command line are ignored.
+
+
   <tag><tt>-S</tt></tag>
 
-  This option forces cl65 to stop after the assembly step. This means that
-  C files are translated into assembler files, but nothing more is done.
-  Assembler files, object files and libraries given on the command line
+  This option forces cl65 to stop before the assembly step. That means that
+  C files are translated into assembler files; but, nothing more is done.
+  Assembler files, object files, and libraries given on the command line
   are ignored.
 
 
   <tag><tt>-c</tt></tag>
 
-  This options forces cl65 to stop after the assembly step. This means
+  This option forces cl65 to stop after the assembly step. That means
   that C and assembler files given on the command line are translated into
-  object files, but there is no link step, and object files and libraries
+  object files; but, there is no link step.  Object files and libraries
   given on the command line are ignored.
 
 
   <tag><tt>-o name</tt></tag>
 
-  The -o option is used for the target name in the final step. This causes
-  problems, if the linker will not be called, and there are several input
-  files on the command line. In this case, the name given with -o will be
+  The -o option is used for the target name in the final step. That causes
+  problems if the linker will not be called, and there are several input
+  files on the command line. In that case, the name given with -o will be
   used for all of them, which makes the option pretty useless. You
-  shouldn't use -o when more than one output file is created.
+  shouldn't use <tt/-o/ when more than one output file is created.
 
 
   <tag><tt>--print-target-path</tt></tag>
 
-  This option prints the absolute path of the target file directory and exits
+  This option prints the absolute path of the target file directory, and exits
   then. It is supposed to be used with shell backquotes or the GNU make shell
-  function. This way you can write build scripts or Makefiles accessing target
+  function. That way, you can write build scripts or Makefiles accessing target
   files without any assumption about the cc65 installation path.
 
 
   <tag><tt>-t sys, --target sys</tt></tag>
 
-  The default for this option is different from the compiler and linker in the
-  case that the option is missing: While the other tools (compiler, assembler
+  The default for this option is different from the compiler and linker, in the
+  case that the option is missing:  While the other tools (compiler, assembler,
   and linker) will use the "none" system settings by default, cl65 will use
-  the C64 as a target system by default. This was chosen since most people
+  "c64" as a target system by default. That was chosen because most people
   seem to use cc65 to develop for the C64.
 
 
@@ -177,10 +189,10 @@ There are a few remaining options that control the behaviour of cl65:
 
   Pass options directly to the assembler. This may be used to pass options
   that aren't directly supported by cl65. Several options may be separated by
-  commas, the commas are replaced by spaces when passing them to the
-  assembler. Beware: Passing arguments directly to the assembler may interfere
-  with some of the defaults, because cl65 doesn't parse the options passed. So
-  if cl65 supports an option by itself, do not pass this option to the
+  commas; the commas are replaced by spaces when passing them to the
+  assembler. Beware: Passing arguments directly to the assembler might interfere
+  with some of the defaults because cl65 doesn't parse the options passed. So,
+  if cl65 supports an option by itself, do not pass that option to the
   assembler by means of the <tt/-Wa/ switch.
 
 
@@ -188,10 +200,10 @@ There are a few remaining options that control the behaviour of cl65:
 
   Pass options directly to the compiler. This may be used to pass options
   that aren't directly supported by cl65. Several options may be separated by
-  commas, the commas are replaced by spaces when passing them to the
-  compiler. Beware: Passing arguments directly to the compiler may interfere
-  with some of the defaults, because cl65 doesn't parse the options passed. So
-  if cl65 supports an option by itself, do not pass this option to the
+  commas; the commas are replaced by spaces when passing them to the
+  compiler. Beware: Passing arguments directly to the compiler might interfere
+  with some of the defaults because cl65 doesn't parse the options passed. So,
+  if cl65 supports an option by itself, do not pass that option to the
   compiler by means of the <tt/-Wc/ switch.
 
 
@@ -199,10 +211,10 @@ There are a few remaining options that control the behaviour of cl65:
 
   Pass options directly to the linker. This may be used to pass options that
   aren't directly supported by cl65. Several options may be separated by
-  commas, the commas are replaced by spaces when passing them to the linker.
-  Beware: Passing arguments directly to the linker may interfere with some of
-  the defaults, because cl65 doesn't parse the options passed. So if cl65
-  supports an option by itself, do not pass this option to the linker by means
+  commas; the commas are replaced by spaces when passing them to the linker.
+  Beware: Passing arguments directly to the linker might interfere with some of
+  the defaults because cl65 doesn't parse the options passed. So, if cl65
+  supports an option by itself, do not pass that option to the linker by means
   of the <tt/-Wl/ switch.
 
 </descrip>
@@ -211,7 +223,7 @@ There are a few remaining options that control the behaviour of cl65:
 
 <sect>More usage<p>
 
-Since cl65 was created to simplify the use of the cc65 development
+Because cl65 was created to simplify the use of the cc65 development
 package, it tries to be smart about several things.
 
 <itemize>
@@ -219,15 +231,14 @@ package, it tries to be smart about several things.
 <item> If you don't give a target system on the command line, cl65
        defaults to the C64.
 
-<item> When linking, cl65 will supply the names of the startup file and
-       library for the target system to the linker, so you don't have to do
-       that.
+<item>  When linking, cl65 will supply the name of the library file for
+        the target system to the linker; so, you don't have to do that.
 
 <item> If the final step is the linker, and the name of the output file was
        not explicitly given, cl65 will use the name of the first input file
-       without the extension, provided that the name of this file has an
-       extension. So you don't need to name the executable name in most
-       cases, just give the name of your "main" file as first input file.
+        without the extension, provided that the name of that file has an
+        extension. So, you don't need to give the executable name in most
+        cases; just give the name of your "main" file as the first input file.
 </itemize>
 
 The command line is parsed from left to right, and the actual processing tool
@@ -248,7 +259,7 @@ The type of an input file is derived from its extension:
 <itemize>
 <item>C files: <tt/.c/
 <item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
-<item>Object files: <tt/.o/ <tt/.obj/
+<item>Object files: <tt/.o/, <tt/.obj/
 <item>Libraries: <tt/.a/, <tt/.lib/
 <item>GEOS resource files: <tt/.grc/
 <item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/