This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: RFA: Extending --help
* Nick Clifton wrote on Mon, Jan 22, 2007 at 12:34:15PM CET:
>
> >>+@item @var{optimizers}
> >>+This will display all of the optimization options supported by the
> >>+compiler.
> >
> >Why use future tense here?
>
> Because the options are only displayed when the command is used. Since
> the reader is currently viewing this manual page it follows that their
> attention is here rather than on running gcc, so the display of the
> command line options will only happen in the future when they use the
> knowledge that they have gleaned from this manual entry.
Manuals are usually written in present tense, as far as I know.
They describe a state of things: the compiler has these semantics
whether or not I ever choose to invoke it, or have already done.
For a manual, it doesn't matter when the reader does something,
or whether she does at all. Only if a time ordering is implied,
a change of tense seems appropriate, e.g., when comparing previous
behavior, or the order of passes, or arguments on the command line.
But hey, I'm neither a native speaker nor a GCC developer, I merely
point out what I observe and am happy with it either way.
> I also chose this tense because of its imperative nature. The
> documentation is saying that the described behaviour *will* occur, not
> that it *might* occur.
Yes, but nothing in the manual is speculative (at least I hope ;-)
> I think that this choice of tense also follows similar choices made in
> other entries in the invoke.texi document.
Most of the manual seems to be written in present tense, with few
exceptions. I can't easily deduce systematics for those exceptions,
except for reasons I stated above. ;-)
> >>+for example it is possible to display all target specific options
> >>+which control optimizations by using the following:
> >
> >s/But for/For/
>
> I think that this entire paragraph needs a rewrite. In the attached
> revision I have gone for the following:
>
> A class can also be used as a qualifier, although this usually
> restricts the output by so much that there is nothing to display.
> One case where it does work however is when one of the classes is
> 'target'. So for example to display all the target-specific
> optimization options the following can be used:
Sounds better. I'd put a comma after `options'.
> >>+@option{--help=} is changed. Instead of describing the displayed
> >>+options, an indication is given as to whether the option is enabled,
> >>+disabled or set to a specific value. (Assuming that the compiler
> >>+knows this at the point where the @option{--help=} option is used).
> >
> >s/disabled/&,/
>
> Ah now here my old English teacher would disagree with you.
I think I learned:
foo, bar and baz British English (and German, BTW) style
foo, bar, and baz preferred in American English
for lists of items. I think the distinction was more blurry when the
items were more than simple nouns, for example subclauses. But then
again, my English teacher disagreed with me more than once. ;-)
> >>+ if (any_flags & all_langs_mask)
> >>+ description = _("The following options are language related");
> >>+ else
> >>+ description = _("The following options are
> >>language-independent");
> >
> >Why not also language-related?
>
> Because if they were related to one or more languages they should have
> been included in one or more of the language specific *.opt files, and
> hence had one or more of the language identifier bits set in their
> flags. Options which do not have any language bits set must be assumed
> to be independent of the language(s) chosen for compilation.
I think this was a misunderstanding. I meant to imply this typo
question only:
s/\(language\) \(related\)/\1-\2/
rather than commenting on the actual semantics (but I do tend to err on
the written-as-one-word and written-with-hyphen sides in case of doubt,
blaim my native tongue).
> I have attached a revised patch to the invoke.texi file, should you wish
> to review it.
Thanks.
> +@item --help=@var{class}@r{[},@var{qualifier}@r{]}
> +Print (on the standard output) a description of the command line
> +options understood by the compiler that fit into a specific class.
> +The class can be one of @var{optimizers}, @var{warnings}, @var{target}
> +or @var{params}:
> +
> +@table @gcctabopt
> +@item @var{optimizers}
> +This will display all of the optimization options supported by the
> +compiler.
> +
> +@item @var{warnings}
> +This will display all of the options controlling warning messages
> +produced by the compiler.
> +
> +@item @var{target}
> +This behaves in the same way as the @option{--target-help} option,
> +except that only target-specific options supported by the compiler are
> +displayed. Target specific options supported by the assembler or
> +linker are not displayed.
Now, here you change back to present tense. Barring above comments, at
least that seems inconsistent to me: in what way should `target' be
different than `warnings' that it deserves a different language?
I think all should be present tense.
> +
> +@item @var{params}
> +This will display the values recognized by the @option{--param}
> +option.
> +@end table
> +@item joined
> +Display options which take an argument that appears after an equal
> +sign in the same continuous piece of text. e.g. @samp{--help=target}.
> +
> +@item separate
> +Display options which take an argument that appears as a separate word
> +following the original option. e.g. @samp{-o output-file}.
> +@end table
These still have the `e.g.' after period, without capitalization.
I think this abbreviation does not look nice at the beginning of a
sentence; that does not make sense. Also, you should either follow
with a comma, or with `@:' in order not to mess up the spacing.
> +Thus for example to display all the undocumented target-specific
> +switches supported by the compiler the following can be used:
See above (comma after compiler).
> +The sense of a qualifier can be inverted by prefixing it with the
> +@var{^} character, so for example to display all binary warning
> +options (i.e. ones that are either on or off and that do not take an
> +argument) which have a description the following can be used:
See above (i.e.); comma after description.
> +A class can also be used as a qualifier, although this usually
> +restricts the output by so much that there is nothing to display. One
> +case where it does work however is when one of the classes is
> +@var{target}. So for example to display all the target-specific
> +optimization options the following can be used:
See above (comma after options).
> +If the @option{-Q} option appears on the command line before the
> +@option{--help=} option, then the descriptive text displayed by
> +@option{--help=} is changed. Instead of describing the displayed
> +options, an indication is given as to whether the option is enabled,
> +disabled or set to a specific value. (Assuming that the compiler
> +knows this at the point where the @option{--help=} option is used).
s/value\. (A/value (a/ sounds better to me.
Again, I'm only suggesting changes, don't take this as a given.
Cheers,
Ralf