PATCH: tidy documentation of ld command-line option syntax

[Dave Korn]

Sandra Loosemore wrote:

> I just played a bit with listing *both* the "--option=value" and
> "--option value" forms of each command, as you suggest.  I didn't really
> have any particular reason not to do that in the first place, but having
> looked at it, I think it adds a great deal of verbosity and
> repetitiveness to the documentation and does not actually make ld any
> easier to use.  So I would not recommend that we do that.

  Okeydokey.  Looking at the rest of the context, I guess the formats are all
fairly well explained in the introductory paragraphs, so I don't object.

> I also note, BTW, that the manual is not consistent in using either
> "-ovalue" or "-o value" for single-letter options.  IMO, the former is
> somewhat hard to read.  How about if, as a compromise, I consistently
> formatted all single-letter options as "-o value", and all the long
> options as "--option=value"?  I think listing all 4 possible format
> permutations for each command would be silly, anyway.

  Yeah.  Your suggestion is nice: I agree the joined forms are less clear for
the single-letter options.  How about we append a bit to the bit about passing
options via the driver just to mention the joined forms are the easier to use
in that context, so people don't think "I can't use -o=value so I have to use
-Xlinker -o -Xlinker value" when they see only "-o VALUE" and not "-oVALUE"?

  How about something like:

Index: ld.texinfo
===================================================================
RCS file: /cvs/src/src/ld/ld.texinfo,v
retrieving revision 1.231
diff -p -u -r1.231 ld.texinfo
--- ld.texinfo	18 Feb 2009 18:23:07 -0000	1.231
+++ ld.texinfo	23 Feb 2009 20:36:57 -0000
@@ -339,7 +339,16 @@ compiler driver) like this:
 @end smallexample

 This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
+silently drop the linker options, resulting in a bad link.  Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument will act as
+a separator and cause the driver to pass only the option to the linker,
+and the argument to the compiler.  In this case, it is simplest to use
+the joined forms of both single- and multiple-letter options, such as:
+
+@smallexample
+  gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
+@end smallexample

 Here is a table of the generic command line switches accepted by the GNU
 linker:


    cheers,
      DaveK