Re: Patch to add documentation for spec files

[craig at jcb-sc dot com]

Wow, thanks for this great work!  Very important to get into the docs ASAP.

I've enclosed a bunch of suggested edits.  For the most part, I think it's
safe to ignore them for however long you like, though you might want to
skim for the few that might affect comprehension/accuracy.  Most of them
are style (texinfo, tech-writing) issues.

        tq vm, (burley)



>+ * Spec Files::          How to pass switches to sub-processes.                        
[...]
>+ * Spec Files::          How to pass switches to sub-processes.                        

Please get rid of the trailing spaces.  ;-)

>  * Target Options::      Running a cross-compiler, or an old version of GNU CC.
>  @end menu
>  
>*************** program uses when determining what switc
>+ @code{GCC} is a driver program.  It performs its job by invoking a
>+ sequence of other programs to do its work for it.

Instead of "its work for it", I suggest "the work".

>+ more) string for each program that GCC can invoke.  GCC
>+ has a complete set of @code{spec} strings built in to it, but these can
[...]
>+ @code{Spec Files} are text based.  They consist of a sequence of

I think these are inappropriate uses of @code{}.  The first one or two
should perhaps be a @dfn{}.

"text based" seems a bit ambiguous to me.  Do you mean "plaintext files",
or something like that?

Also, I'm not sure "Spec Files" needs to be capitalized.  If "spec" is
the new concept to be introduced, can "spec string", "spec file", etc.,
serve adequately to name the pertinent concepts?  If so, I'd suggest
avoiding the extra capitalization, e.g. use "spec file" or "Spec file",
but not "Spec File".

>+ directives seperated by blank lines.  The type of directive is

"separated".

>+ determined by the first non whitespace character on the line and it can

"non-whitespace".

>+ @item %[command]
>+ Issues a [command] to the spec file processor.  The commands that can

I think, in place of your `[command]' syntax, texinfo offers a preferable
construct, @var{}, as in `@var{command}'.

>+ appear here are as follows: 

Strike "as follows" whenever feasible, such as introducing lists.  ;-)

>+ @item %include <@samp{file}>
[...]
>+ Search for @samp{file} and insert its text at the current point in the
[...]
>+ @item %include_noerr <@samp{file}>

Here, and in many subsequent cases, use @var instead of @samp and/or `[]'.

>+ current text for the spec, otherwise it will override the current text.

Replace `, otherwise' with `.  Otherwise,'.

>+ If the named spec does not exist, then a new spec will be created.

Is this true regardless of whether the text for the spec was nil, started
with `+', or replacement text?

If so, perhaps that sentence should be its own paragraph.

Otherwise, it'd be helpful to explain the effects of the three possible
actions (based on the text) in the presence of a non-existent spec,
as the only "obvious" combination is "replacement text for non-existent
spec creates new spec with that text".

>+ Says that any input file whoes name ends in @samp{.ZZ} should be

"[This] says", since its the start of a sentence (due to the `:' after
"For example").

"whose", not "whoes".

>+ command line switch @samp{-input} and with the result of performing the

"command-line switch" -- hyphenate adjective strings.  (Very painful to
get used to, I recall, but ultimately makes for easier reading by people
not already experts in the terminology -- as well as, at least theoretically,
by speech-synthesizer software, such as for the blind, and automated
translation software, which can make more sense of the resulting grouping.)

>+ @samp{%i} subsitution.  (See below).

`.)', not `).', when it ends a complete parenthetical sentence.

>+ similar to using the @code{-x} command line switch to GCC to specicy a

"specify", not "specicy".

>+ langauge explicitly.  For example:

"language", not "langauge".

>+ Says that .ZZ files are infact c++ source files.

"are, in fact, C++".

>+ @smallexample
>+   [name] compiler not installed on this system.
>+ @end smallexample

Don't bother indenting complete example blocks with spaces, readers
basically never count them anyway.  (I had to get out of the habit
of always indenting sample Fortran code by six spaces -- except, of
course, where the sample block contained label definitions.)

>+ including the text of the old defintion.

"definition".

>+ lib          Libraries to include of the command line to the linker

Do you mean "[in] the command line"?

>+ predefines   Defines to be passed to the C pre-processor

I think we normally don't hyphenate "preprocessor".

>+ signed_char  Defines to pass to CPP to say whether 'char' is signed by default

Here's a good place for @code{}: `@code{char}'.

>+ @code{Spec} strings are a list of command line switches to be passed to their

"command-line options" instead of "command line switches", as it both
fixes hyphenation and prefers consistent terminology.

>+ results of expanding these sequences, therefore you can concatenate them

I'd prefer `.  Therefore' or maybe `---therefore,' to `, therefore'.

>+ Substitute one % into the program name or argument.

`@code{%}', to be consistent with the item.  Or maybe these should all
be @samp{} -- I'm not sure of the distinctions sometimes!

>+ Marks the argument containing or following the %d as a

`@code{%d}'.

>+ successfully.  Unlike @samp{%g}, this contributes no text to the

Use @code, or @samp, consistently, for %X items.

>+ @item %gSUFFIX
>+ Substitute a file name that has suffix SUFFIX and is chosen

Use `@var{suffix}' in place of `SUFFIX', as per earlier suggestions,
throughout.

>+ chosen file names are known.  For example, `%g.s ... %g.o ... %g.s'

That should all be in a @samp{}.

>+ might turn into `ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s'.  SUFFIX matches

Ditto.

>+ the regexp "[.A-Za-z]*" or the special string "%O", which is

Here, I think the regexp should be a @samp{}, while the "%O" should
be whatever you decide for %X generally, `@code{%O}' or `@samp{%O}'.

>+ treated exactly as if %O had been pre-processed.  Previously, %g
>+ was simply substituted with a file name chosen once per compilation,

%O, %g -> @code/@samp.

Repeat the above several comments throughout subsequent items, so I don't
have to include them here.

>+ "output file" of this compilation.  This puts the argument

I've read the texinfo documentation as suggesting:

  ``output file'' of this compilation...

but I've also seen people use:

  `output file' of this compilation...

Maybe the double quotes work too.  I don't have a printer to confirm,
one way or another, which produces the appropriate output via TeX.

In the meantime, I pretty consistently use the double-apostrophe
convention, since that's what was documented when I read up on texinfo
authoring.

Actually, in this case, maybe dropping the quotes entirely works.  If
you want to highlight the fact that a sort of "variable" is being
defined, you could say "designated output file".  Consider:

  He was the driver for the trip home.

Versus:

  He was the designated driver for the trip home.

If the former is sufficient, it's fine, else the latter highlights
the "title" nature of the term "driver", which doesn't necessarily
carry it.

>+ current target machine.  Use this when running cpp.

`@code{cpp}'.

>+ (Except macros that already have __.)

`@samp{__}'.

>+ Substitute a -iprefix option made from GCC_EXEC_PREFIX.

`@samp{-iprefix}', though, I'm not quite sure why option names are @samp
but other names are @code....

>+ @item %eSTR
>+ Print STR as an error message.  STR is terminated by a newline.

`@var{str}'.

>+ Output "-" if the input for the current command is coming from a pipe.

`@samp{-}'.

>+ @item %(@samp{name})
>+ Subsitute the contents of spec string @samp{name} at this point.

`@var{name}', but I'll stop listing all these sorts of replacements from
here on.

>+ Output the accumulated linker options specified by @samp{-Wl} or a %x

`@samp{%x}'.

>+ (For version 2.9.n, this is 2.)

Instead of `.n', I suggest using something like `.3', to avoid having
to use @var or potentially confusing the reader.  (For least confusion,
use 2.8.1, since there's actually a release with that version number.)

>+ Dump out a -L option for each directory in startfile_prefixes.

`@samp{-L}'.

>+ If multilib_dir is set, extra entries are generated with it affixed.

`@code{multilib_dir}'?  Not sure what that keyword represents offhand,
maybe some description is in order.

>+ @item %l
>+ Process the @code{link} spec.  This is the spec for computing the
>+ command line passed to the linker.  Typically it will make use of the following
>+ items: 
>+ 
>+ @item %L

Wait, *which* following the items?  There isn't a new @itemize here,
so it looks like the list containing %l just continues.  Perhaps just
a quick in-line listing of "following items" is appropriate?  Or,
perhaps `...will make use of the remaining items in this list (@samp{%L},
@samp{%G}, and so on).', though that's a bit harder to maintain, e.g.
someone might later add an item in the wrong "section" of the list.

>+ this would be a file called @samp{crt0.o}. 

I think `named @file{crt0.o}' is the preferred phrasing.

>+ to be passed to the C pre-processor.

`preprocessor', again.

>+ to tell cpp whether a char is signed or not.  It typically has the

`@code{char}', and you can drop ` or not' with a `whether', as it is
implicit.

>+ passed to the actual C compiler (@samp{cc1}).

I think either @file or @code would be preferable to @samp here, and further.

>+ @item %@{@samp{S}@}
>+ Substitutes the -@samp{S} switch, if that switch was given to GCC.
>+ If that switch was not specified, this substitutes nothing.  Here
>+ @samp{S} is a metasyntactic variable. 

With @var{s}, you won't need that last sentence (at least, in theory ;-).

>+ with -@samp{S}, but which also take an argument.  This is used for

Move the `-' to within the {}.

>+ switches like -o, -D, -I, etc.  GCC considers `-o foo' as being
>+ one switch whose names starts with `o'.  %@{o*@} would substitute this

Lots of @ stuff needed here.

>+ -@samp{S} are specified to GCC.  Note that the tail part of the
>+ -@samp{S} option (i.e. the part matched by the `*') will be substituted

More hyphen movement and @ stuff needed.

>+ Like %@{@samp{S}:@samp{X}@}, but if no @samp{S} switch, substitute `-'.

Here, and below, `@samp{-}'.

>+ Substitutes @samp{X} if either -@samp{S} or -P was given to GCC.  This may be
>+ combined with ! and . as above binding stronger than the OR.

Hyphen movement, and @ stuff needed.

Also, maybe insert comma after `above'?  An example of the binding
(precedence) distinction might be helpful.

>+ %@{!@samp{S}:@samp{X}@} construct may contain other nested % constructs

`@samp{%}', or @code if that's what you decided for these.

>+ The -O, -f, -m, and -W switches are handled specifically in these
>+ constructs.  If another value of -O or the negated form of a -f, -m, or
>+ -W switch is found later in the command line, the earlier switch
>+ value is ignored, except with @{@samp{S}*@} where @samp{S} is just one
>+ letter; this passes all matching options.

@ stuff needed.

Also, I think `, which passes' would be clearer than `; this passes'.

>+ The character | at the beginning of the predicate text is used to indicate

`@samp{|}'.

>+ that a command should be piped to the following command, but only if -pipe

`@samp{-pipe}'.

>+ Note that it is built into GCC which switches take arguments and which
>+ do not.  You might think it would be useful to generalize this to
>+ allow each compiler's spec to say which switches take arguments.  But
>+ this cannot be done in a consistent fashion.  GCC cannot even decide
>+ which input files have been specified without knowing which switches
>+ take arguments, and it must know which input files to compile in order
>+ to tell which compilers to run.

That paragraph is just the sort of thing I write that people sometimes
complain about, but I think it's important, and perhaps belongs right
up there in the introduction, right after other GCC built-in concepts
are explained.

Whether you do move it, consider removing the initial `Note that' and
putting all subsequent sentences within a pair of parentheses.

>+ GCC also knows implicitly that arguments starting in `-l' are to be

`@samp{-l}'.

        tq vm, (burley)