[doc, committed] fix @var markup on option keyword choices

[doc, committed] fix @var markup on option keyword choices

[Sandra Loosemore]

[-- Attachment #1: Type: text/plain, Size: 1252 bytes --]

The documented syntax for most GCC options that take magic keywords is 
of the form @option{-ffoo=@var{magic}}, with the various literal values 
for @var{magic} listed in the option description.  There are a number, 
though, that list the keyword choices in the syntax, but with two 
different markup conventions.  This patch changes the ones that wrap the 
whole keyword list in @var, like -fvtable-verify, to use the same markup 
convention as the others, like -Wsuggest-attribute, which use the 
regular option/code font for the keywords but set off the syntactic 
delimiters "[", "|", and "]" in Roman font..  @var is supposed to be for 
metasyntactic variables and seems inappropriate for literal keywords, so 
I think it's less correct than the other convention.  Of course a third 
possibility would be to rewrite all the option descriptions in this 
class to use a metasyntactic variable instead of putting the keywords 
inline, but that's more work and more prone to possible unintended changes.

I've checked this in under the "obvious fix" rule.

-Sandra

2015-01-07  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/invoke.texi ([-fvtable-verify]): Fix markup on option
	keywords.
	([-fivar-visibility], [-fvisibility]): Likewise.

[-- Attachment #2: doc.patch --]
[-- Type: text/x-patch, Size: 2717 bytes --]

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 219322)
+++ gcc/doc/invoke.texi	(working copy)
@@ -193,7 +193,7 @@ in the following sections.
 -fno-threadsafe-statics  -fuse-cxa-atexit @gol
 -fno-weak  -nostdinc++ @gol
 -fvisibility-inlines-hidden @gol
--fvtable-verify=@var{std|preinit|none} @gol
+-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
 -fvtv-counts -fvtv-debug @gol
 -fvisibility-ms-compat @gol
 -fext-numeric-literals @gol
@@ -219,7 +219,7 @@ Objective-C and Objective-C++ Dialects}.
 -fobjc-nilcheck @gol
 -fobjc-std=objc1 @gol
 -fno-local-ivars @gol
--fivar-visibility=@var{public|protected|private|package} @gol
+-fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]} @gol
 -freplace-objc-classes @gol
 -fzero-link @gol
 -gen-decls @gol
@@ -1116,7 +1116,8 @@ See S/390 and zSeries Options.
 -fleading-underscore  -ftls-model=@var{model} @gol
 -fstack-reuse=@var{reuse_level} @gol
 -ftrapv  -fwrapv  -fbounds-check @gol
--fvisibility -fstrict-volatile-bitfields -fsync-libcalls}
+-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
+-fstrict-volatile-bitfields -fsync-libcalls}
 @end table
 
 
@@ -2436,7 +2437,7 @@ and that pointers to function members de
 objects may not compare equal.  When this flag is given, it is a
 violation of the ODR to define types with the same name differently.
 
-@item -fvtable-verify=@var{std|preinit|none}
+@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}
 @opindex fvtable-verify
 Turn on (or off, if using @option{-fvtable-verify=none}) the security
 feature that verifies at runtime, for every virtual call that is made, that
@@ -3013,7 +3014,7 @@ and other variables declared either loca
 globally with the same name.  Specifying the @option{-fno-local-ivars}
 flag disables this behavior thus avoiding variable shadowing issues.
 
-@item -fivar-visibility=@var{public|protected|private|package}
+@item -fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]}
 @opindex fivar-visibility
 Set the default instance variable visibility to the specified option
 so that instance variables declared outside the scope of any access
@@ -23492,7 +23493,7 @@ unit, or if @option{-fpic} is not given 
 The default without @option{-fpic} is @samp{initial-exec}; with
 @option{-fpic} the default is @samp{global-dynamic}.
 
-@item -fvisibility=@var{default|internal|hidden|protected}
+@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
 @opindex fvisibility
 Set the default ELF image symbol visibility to the specified option---all
 symbols are marked with this unless overridden within the code.

Re: [doc, committed] fix @var markup on option keyword choices

[Gerald Pfeifer]

On Wednesday 2015-01-07 19:20, Sandra Loosemore wrote:
> The documented syntax for most GCC options that take magic keywords is of the
> form @option{-ffoo=@var{magic}}, with the various literal values for
> @var{magic} listed in the option description.  There are a number, though,
> that list the keyword choices in the syntax, but with two different markup
> conventions.  This patch changes the ones that wrap the whole keyword list in
> @var, like -fvtable-verify, to use the same markup convention as the others,
> like -Wsuggest-attribute, which use the regular option/code font for the
> keywords but set off the syntactic delimiters "[", "|", and "]" in Roman
> font..  @var is supposed to be for metasyntactic variables and seems
> inappropriate for literal keywords, so I think it's less correct than the
> other convention.

Agreed, thanks for making this change!

Gerald