[patch, committed] invoke.texi: clean up texinfo markup

[Sandra Loosemore]

On 05/02/2012 12:41 AM, Gerald Pfeifer wrote:

> Hi Sandra,
>
> On Fri, 6 Apr 2012, Sandra Loosemore wrote:
>> > This is another installment in my series of cleanups to invoke.texi.
>> > In this patch I have taken a break from nit-picking grammar and have
>> > nit-picked some Texinfo markup issues instead.
> kudos for the work you are doing on this front!  This is quite
> laborsome and not exactly thankful, but worthwhile.

NP.  Actually, the most laborsome part of it is not copy-editing the 
text, but figuring out how to batch up the edits and prepare the 
patches.  I know I've been short-cutting things a bit by just checking 
things in directly, so if you do see something that I've screwed up, 
it's fine with me if you likewise just go ahead and fix it as you'd 
like.  I don't think it's a good use of anybody's time to get into 
protracted discussions about each edit, anyway.

> Index: gcc/doc/invoke.texi
> ===================================================================
> -With -std=c++11, @option{-Wno-narrowing} suppresses the diagnostic
> +With @option{-std=c++11}, @option{-Wno-narrowing} suppresses the diagnostic
>   required by the standard.  Note that this does not affect the meaning
>   of well-formed code; narrowing conversions are still considered
>   ill-formed in SFINAE context.
>
> I am not sure this change is correct.  I believe the intended meaning
> was "when the active standard is C++11" which may include "-std=g++11"
> as well, or other ways to activate that, not to refer to that specific
> command-line option.

If the intended meaning is "when the active standard is C++11", say so?

> -either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
> -@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
> +either specify @option{-Wextra -Wunused} (note that @option{-Wall} implies
> +@option{-Wunused}), or separately specify @option{-Wunused-parameter}.
>
> Is @option{...} appropriate for a combination of two options as well?

I think so.  The Texinfo manual specifically says that @option has 
identical formatting effects as @samp (quotes and fixed-width font).  It 
would look pretty funny to use @option{-Wextra} @option{-Wunused} to 
refer to two options used together, yet these are definitely options 
rather than any of the things @samp is documented to be used for.

> +This is a set of options that are used to explicitly disable/enable
> +optimization passes.  These options are intended for use for debugging GCC.
>
> How about "intended to debug GCC"?

Yeah, or "intended for debugging GCC".  Sorry, I'm usually better about 
catching excess verbiage like that.

> +Specify type of floating-point unit.  Valid values for @var{name} are
>
> Should this read "the type of"?

OK.

> -@samp{extern} declarations are not affected by @samp{-fvisibility}, so
> -a lot of code can be recompiled with @samp{-fvisibility=hidden} with
> -no modifications.  However, this means that calls to @samp{extern}
> +@samp{extern} declarations are not affected by @option{-fvisibility}, so
> +a lot of code can be recompiled with @option{-fvisibility=hidden} with
> +no modifications.  However, this means that calls to @code{extern}
>
> Why @samp{extern} and not @code{extern}?

Uh, I missed this one?  ;-)

> -declare all peripheral bit-fields as ``unsigned short'' (assuming short
> +declare all peripheral bit-fields as @code{unsigned short} (assuming short
>
> Should "short" be "@code{short}" here?

It could be, but I think it's also valid to refer to a short or short 
integer as a conceptual thing, without markup, rather than just as a 
built-in data type name.  (I see there are other places where int, long, 
pointer, etc sizes are similarly discussed without @code markup on those 
terms.)  I guess you could sidestep the question in this instance by 
saying "(assuming this type is 16 bits..." instead.  Anyway, I think 
here I was more focused on replacing the quotes with more appropriate 
markup on the other use in the sentence.

-Sandra