Re: [patch, committed] invoke.texi: clean up texinfo markup
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
Re: [patch, committed] invoke.texi: clean up texinfo markup
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.
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.
-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?
-of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
+of @option{-Wextra} without this warning, use @option{-Wextra
-Wno-sign-compare}.
Same here.
-warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
+warnings without this one, use @option{-Wextra
-Wno-missing-field-initializers}.
And here.
-@option{-Wextra} warnings without this one, use @samp{-Wextra
+@option{-Wextra} warnings without this one, use @option{-Wextra
-Wno-override-init}.
And here.
+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"?
-compiling @file{foo.c} with @samp{-c -save-temps} would produce files
+compiling @file{foo.c} with @option{-c -save-temps} would produce files
See above.
-those listed here. You can invoke GCC with @samp{-Q --help=optimizers}
+those listed here. You can invoke GCC with @option{-Q --help=optimizers}
Same here.
-option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
+option @option{-Xlinker -z -Xlinker defs}). Only a few systems support
And here.
-@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
+@option{-Xlinker -assert -Xlinker definitions}. It does not work to write
And here.
-@samp{-Xlinker -Map=output.map} rather than
-@samp{-Xlinker -Map -Xlinker output.map}. Other linkers may not support
+@option{-Xlinker -Map=output.map} rather than
+@option{-Xlinker -Map -Xlinker output.map}. Other linkers may not support
And here.
-For example, @samp{-Wl,-Map,output.map} passes @samp{-Map output.map} to the
+For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to
the
And here.
+@option{-mno-shared -mabicalls}. For the n64 ABI, this option
And here.
+@option{-mcpu=970 -mno-altivec}.
And here.
+Specify type of floating-point unit. Valid values for @var{name} are
Should this read "the type of"?
-@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}?
-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?
Gerald
[patch, committed] invoke.texi: clean up texinfo markup
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.
Since this is supposed to be a content-free patch, I went ahead and
checked it in after inspecting the generated PDF manual.
-Sandra
2012-04-06 Sandra Loosemore
gcc/
* doc/invoke.texi: Clean up Texinfo markup throughout the file.
Use @option markup on command-line options. Use @samp markup on
literal keywords to options. Use @code markup on code fragments.
Use other markup in preference to quotation marks in the text.
Add markup to some passages without any.
Index: gcc/doc/invoke.texi
===
--- gcc/doc/invoke.texi (revision 186145)
+++ gcc/doc/invoke.texi (working copy)
@@ -1494,8 +1494,8 @@ accepts:
@cindex ISO support
@item -ansi
@opindex ansi
-In C mode, this is equivalent to @samp{-std=c90}. In C++ mode, it is
-equivalent to @samp{-std=c++98}.
+In C mode, this is equivalent to @option{-std=c90}. In C++ mode, it is
+equivalent to @option{-std=c++98}.
This turns off certain features of GCC that are incompatible with ISO
C90 (when compiling C code), or of standard C++ (when compiling C++ code),
@@ -1541,7 +1541,7 @@ The compiler can accept several base sta
@samp{gnu90} or @samp{gnu++98}. By specifying a base standard, the
compiler will accept all programs following that standard and those
using GNU extensions that do not contradict it. For example,
-@samp{-std=c90} turns off certain features of GCC that are
+@option{-std=c90} turns off certain features of GCC that are
incompatible with ISO C90, such as the @code{asm} and @code{typeof}
keywords, but not other GNU extensions that do not have a meaning in
ISO C90, such as omitting the middle term of a @code{?:}
@@ -1551,8 +1551,8 @@ those features change the meaning of the
strict-conforming programs may be rejected. The particular standard
is used by @option{-pedantic} to identify which features are GNU
extensions given that version of the standard. For example
-@samp{-std=gnu90 -pedantic} would warn about C++ style @samp{//}
-comments, while @samp{-std=gnu99 -pedantic} would not.
+@option{-std=gnu90 -pedantic} warns about C++ style @samp{//}
+comments, while @option{-std=gnu99 -pedantic} does not.
A value for this option must be provided; possible values are
@@ -1966,7 +1966,7 @@ is 512.
@item -fdeduce-init-list
@opindex fdeduce-init-list
Enable deduction of a template type parameter as
-std::initializer_list from a brace-enclosed initializer list, i.e.
+@code{std::initializer_list} from a brace-enclosed initializer list, i.e.@:
@smallexample
template auto forward(T t) -> decltype (realfn (t))
@@ -2436,7 +2436,7 @@ int i = @{ 2.2 @}; // error: narrowing f
This flag is included in @option{-Wall} and @option{-Wc++11-compat}.
-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.
@@ -3284,7 +3284,7 @@ included in @option{-Wformat-nonliteral}
@opindex Wformat=2
@opindex Wno-format=2
Enable @option{-Wformat} plus format checks not included in
-@option{-Wformat}. Currently equivalent to @samp{-Wformat
+@option{-Wformat}. Currently equivalent to @option{-Wformat
-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
@item -Wnonnull
@@ -3627,8 +3627,8 @@ This warning is enabled by @option{-Wall
All the above @option{-Wunused} options combined.
In order to get a warning about an unused function parameter, you must
-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}.
@item -Wuninitialized
@opindex Wuninitialized
@@ -3722,7 +3722,7 @@ the warnings were only enabled by the @o
@opindex Wpragmas
Do not warn about misuses of pragmas, such as incorrect parameters,
invalid syntax, or conflicts between pragmas. See also
-@samp{-Wunknown-pragmas}.
+@option{-Wunknown-pragmas}.
@item -Wstrict-aliasing
@opindex Wstrict-aliasing
@@ -3741,13 +3741,13 @@ This option is only active when @option{
It warns about code that might break the strict aliasing rules that the
compiler is using for optimization.
Higher levels correspond to higher accuracy (fewer false positives).
-Higher levels also correspond to more effort, similar to the way -O works.
-@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
-with n=3.
+Higher levels also correspond to more effort, similar to the way @option{-O}
+works.
+@option{-Wstrict-a
