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
