Re: RFA: Extending --help

[Nick Clifton <nickc at redhat dot com>]

Hi Ralf,

> > > > +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.

> 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.

Fair enough :-)


> >   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'.

Really, why ?

> > > > +	  if (any_flags & all_langs_mask)
> > > > +	    description = _("The following options are language related");

> > > Why not also language-related?
> > Because if they were related to one or more languages they should have 

> I think this was a misunderstanding.  I meant to imply this typo
> question only:
>   s/\(language\) \(related\)/\1-\2/

Ah, yes, I see what you mean - I will fix this.

> > +@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.

Mmm, yes you are right.

> 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?

Because, for the moment, those tools do support a --target-help option 
but they do not support a --warnings-help.  So target help information 
is available in more tools than just the compiler.  I did not want to 
have to extend the linker and assembler to accept the --help= syntax 
(*), so it seemed easier to just make --help=target stop with the 
compiler and not carry on to the other tools.

(*): Well not yet anyway.  This may be a future enhancement.

> I think all should be present tense.

Well I still prefer the future tense, so how about this rewrite of the 
paragraph ?

  @item @var{target}
  This will display target-specific options.  Unlike the
  @option{--target-help} option however, target-specific
  options of the linker and assembler will not be displayed.
  This is because those tools do not currently support the
  extended @option{--help=} syntax.

Strictly speaking this is not totally true since gcc could translate 
--help=target into --target-help for the assembler and linker.  But it 
could not fully translate --help=target,undocumented or other qualified 
--help= options, so it seems best to just specify that --help=target 
stops with the compiler.


> > +@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.

You are right.  How about this rewrite ?

  @item joined
  Display options which take an argument that appears after
  an equal sign in the same continuous piece of text, such as:
  @samp{--help=target}.

  @item separate
  Display options which take an argument that appears as a
  separate word following the original option, such as:
  @samp{-o output-file}.


I have adjusted the text to match your other suggestions, so I think 
that it is only the above points that we need to discuss.

Cheers
  Nick