[doc PATCH] fix up C++ option references (PR 71283)

[Martin Sebor <msebor at gmail dot com>]

Attached is the final version of the patch to adjust the lists
of options (C++ Language Options and -Wall) to include missing
C++ options, reference the forms of options that aren't
the default, and use TexInfo tables for the lists of options
in -Wall and -Wextra to address Nathan's comment.  The patch
also fixes bug 71283.

Martin

PR c++/71283 - Inconsistent location for C++ warning options in the manual

gcc/ChangeLog:

	PR c++/71283
	* doc/invoke.texi (C++ Language Options): Add -Wno-terminate.
	Reference -Wno-conversion-null, -Wno-delete-incomplete, and
	-Wno-subobject-linkage instead of the default positive forms.
	(-Wall): Use a table for options.
	Mention -Wclass-memaccess.
	(-Wextra): Use a table for options.

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 259040)
+++ gcc/doc/invoke.texi	(working copy)
@@ -213,12 +213,12 @@ in the following sections.
 -fvisibility-inlines-hidden @gol
 -fvisibility-ms-compat @gol
 -fext-numeric-literals @gol
--Wabi=@var{n}  -Wabi-tag  -Wconversion-null  -Wctor-dtor-privacy @gol
+-Wabi=@var{n}  -Wabi-tag  -Wno-conversion-null  -Wctor-dtor-privacy @gol
 -Wdelete-non-virtual-dtor  -Wliteral-suffix  -Wmultiple-inheritance @gol
 -Wnamespaces  -Wnarrowing @gol
 -Wnoexcept  -Wnoexcept-type  -Wclass-memaccess @gol
 -Wnon-virtual-dtor  -Wreorder  -Wregister @gol
--Weffc++  -Wstrict-null-sentinel  -Wtemplates @gol
+-Weffc++  -Wstrict-null-sentinel  -Wtemplates  -Wno-terminate @gol
 -Wno-non-template-friend  -Wold-style-cast @gol
 -Woverloaded-virtual  -Wno-pmf-conversions @gol
 -Wsign-promo  -Wvirtual-inheritance}
@@ -270,9 +270,9 @@ Objective-C and Objective-C++ Dialects}.
 -Wc++-compat  -Wc++11-compat  -Wc++14-compat  @gol
 -Wcast-align  -Wcast-align=strict  -Wcast-function-type  -Wcast-qual  @gol
 -Wchar-subscripts  -Wchkp  -Wcatch-value  -Wcatch-value=@var{n} @gol
--Wclobbered  -Wcomment  -Wconditionally-supported @gol
+-Wclass-memaccess -Wclobbered  -Wcomment  -Wconditionally-supported @gol
 -Wconversion  -Wcoverage-mismatch  -Wno-cpp  -Wdangling-else  -Wdate-time @gol
--Wdelete-incomplete @gol
+-Wno-delete-incomplete @gol
 -Wno-deprecated  -Wno-deprecated-declarations  -Wno-designated-init @gol
 -Wdisabled-optimization @gol
 -Wno-discarded-qualifiers  -Wno-discarded-array-qualifiers @gol
@@ -318,7 +318,7 @@ Objective-C and Objective-C++ Dialects}.
 -Wstringop-overflow=@var{n} -Wstringop-truncation @gol
 -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}malloc@r{]} @gol
 -Wsuggest-final-types @gol  -Wsuggest-final-methods  -Wsuggest-override @gol
--Wmissing-format-attribute  -Wsubobject-linkage @gol
+-Wmissing-format-attribute  -Wno-subobject-linkage @gol
 -Wswitch  -Wswitch-bool  -Wswitch-default  -Wswitch-enum @gol
 -Wswitch-unreachable  -Wsync-nand @gol
 -Wsystem-headers  -Wtautological-compare  -Wtrampolines  -Wtrigraphs @gol
@@ -3006,8 +3006,20 @@ void h() @{ f(g); @}
 In C++14, @code{f} calls calls @code{f<void(*)()>}, but in
 C++17 it calls @code{f<void(*)()noexcept>}.
 
-@item -Wclass-memaccess @r{(C++ and Objective-C++ only)}
+@item -Wcatch-value
+@itemx -Wcatch-value=@var{n} @r{(C++ and Objective-C++ only)}
+@opindex Wcatch-value
+@opindex Wno-catch-value
+Warn about catch handlers that do not catch via reference.
+With @option{-Wcatch-value=1} (or @option{-Wcatch-value} for short)
+warn about polymorphic class types that are caught by value.
+With @option{-Wcatch-value=2} warn about all class types that are caught
+by value. With @option{-Wcatch-value=3} warn about all types that are
+not caught by reference. @option{-Wcatch-value} is enabled by @option{-Wall}.
+
+@item -Wclass-memaccess @r{(C++ only)}
 @opindex Wclass-memaccess
+@opindex Wno-class-memaccess
 Warn when the destination of a call to a raw memory function such as
 @code{memset} or @code{memcpy} is an object of class type, and when writing
 into such an object might bypass the class non-trivial or deleted constructor
@@ -3907,57 +3919,79 @@ Options} and @ref{Objective-C and Objective-C++ Di
 
 @option{-Wall} turns on the following warning flags:
 
-@gccoptlist{-Waddress   @gol
--Warray-bounds=1 @r{(only with} @option{-O2}@r{)}  @gol
--Wbool-compare  @gol
--Wbool-operation  @gol
--Wc++11-compat  -Wc++14-compat  @gol
--Wcatch-value @r{(C++ and Objective-C++ only)}  @gol
--Wchar-subscripts  @gol
--Wcomment  @gol
--Wduplicate-decl-specifier @r{(C and Objective-C only)} @gol
--Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
--Wformat   @gol
--Wint-in-bool-context  @gol
--Wimplicit @r{(C and Objective-C only)} @gol
--Wimplicit-int @r{(C and Objective-C only)} @gol
--Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
--Winit-self @r{(only for C++)} @gol
--Wlogical-not-parentheses @gol
--Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)}  @gol
--Wmaybe-uninitialized @gol
--Wmemset-elt-size @gol
--Wmemset-transposed-args @gol
--Wmisleading-indentation @r{(only for C/C++)} @gol
--Wmissing-attributes @gol
--Wmissing-braces @r{(only for C/ObjC)} @gol
--Wmultistatement-macros  @gol
--Wnarrowing @r{(only for C++)}  @gol
--Wnonnull  @gol
--Wnonnull-compare  @gol
--Wopenmp-simd @gol
--Wparentheses  @gol
--Wpointer-sign  @gol
--Wreorder   @gol
--Wrestrict   @gol
--Wreturn-type  @gol
--Wsequence-point  @gol
--Wsign-compare @r{(only in C++)}  @gol
--Wsizeof-pointer-div @gol
--Wsizeof-pointer-memaccess @gol
--Wstrict-aliasing  @gol
--Wstrict-overflow=1  @gol
--Wswitch  @gol
--Wtautological-compare  @gol
--Wtrigraphs  @gol
--Wuninitialized  @gol
--Wunknown-pragmas  @gol
--Wunused-function  @gol
--Wunused-label     @gol
--Wunused-value     @gol
--Wunused-variable  @gol
--Wvolatile-register-var @gol
-}
+@multitable @columnfractions .5 .5
+@headitem Option @tab Notes
+@item @option{-Waddress}
+@item @option{-Warray-bounds=1}
+@tab Only with @option{-O2}.
+@item @option{-Wbool-compare}
+@item @option{-Wlogical-not-parentheses}
+@item @option{-Wmaybe-uninitialized}
+@item @option{-Wbool-operation}
+@item @option{-Wc++11-compat}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wc++14-compat}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wcatch-value}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wchar-subscripts}
+@item @option{-Wclass-memaccess}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wcomment}
+@item @option{-Wduplicate-decl-specifier}
+@tab C and Objective-C only.
+@item @option{-Wenum-compare}
+@tab C and Objective-C. On by default in C++.
+@item @option{-Wformat}
+@item @option{-Wint-in-bool-context}
+@item @option{-Wimplicit}
+@tab C and Objective-C only.
+@item @option{-Wimplicit-int}
+@tab C and Objective-C only.
+@item @option{-Wimplicit-function-declaration}
+@tab C and Objective-C only.
+@item @option{-Winit-self}
+@tab C, C++, Objective-C, and Objective-C++ only.
+@item @option{-Wlogical-not-parentheses}
+@item @option{-Wmain}
+@tab C and Objective-C only, and unless @option{-ffreestanding} is set.
+@item @option{-Wmaybe-uninitialized}
+@item @option{-Wmemset-elt-size}
+@item @option{-Wmemset-transposed-args}
+@item @option{-Wmisleading-indentation}
+@tab C and C++ only.
+@item @option{-Wmissing-attributes}
+@item @option{-Wmissing-braces}
+@tab C and Objective-C only.
+@item @option{-Wmultistatement-macros}
+@item @option{-Wnarrowing}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wnonnull}
+@item @option{-Wnonnull-compare}
+@item @option{-Wopenmp-simd}
+@item @option{-Wparentheses}
+@item @option{-Wpointer-sign}
+@item @option{-Wreorder}
+@item @option{-Wrestrict}
+@item @option{-Wreturn-type}
+@item @option{-Wsequence-point}
+@item @option{-Wsign-compare}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wsizeof-pointer-div}
+@item @option{-Wsizeof-pointer-memaccess}
+@item @option{-Wstrict-aliasing}
+@item @option{-Wstrict-overflow=1}
+@item @option{-Wswitch}
+@item @option{-Wtautological-compare}
+@item @option{-Wtrigraphs}
+@item @option{-Wuninitialized}
+@item @option{-Wunknown-pragmas}
+@item @option{-Wunused-function}
+@item @option{-Wunused-label}
+@item @option{-Wunused-value}
+@item @option{-Wunused-variable}
+@item @option{-Wvolatile-register-var}
+@end multitable
 
 Note that some warning flags are not implied by @option{-Wall}.  Some of
 them warn about constructions that users generally do not consider
@@ -3975,22 +4009,32 @@ This enables some extra warning flags that are not
 @option{-Wall}. (This option used to be called @option{-W}.  The older
 name is still supported, but the newer name is more descriptive.)
 
-@gccoptlist{-Wclobbered  @gol
--Wcast-function-type  @gol
--Wempty-body  @gol
--Wignored-qualifiers @gol
--Wimplicit-fallthrough=3 @gol
--Wmissing-field-initializers  @gol
--Wmissing-parameter-type @r{(C only)}  @gol
--Wold-style-declaration @r{(C only)}  @gol
--Woverride-init  @gol
--Wsign-compare @r{(C only)} @gol
--Wtype-limits  @gol
--Wuninitialized  @gol
--Wshift-negative-value @r{(in C++03 and in C99 and newer)}  @gol
--Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
--Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}  @gol
-}
+@multitable @columnfractions .5 .5
+@headitem Option @tab Notes
+@item @option{-Wclobbered}
+@item @option{-Wcast-function-type}
+@item @option{-Wempty-body}
+@item @option{-Wignored-qualifiers}
+@item @option{-Wimplicit-fallthrough=3}
+@item @option{-Wmissing-field-initializers}
+@item @option{-Wmissing-parameter-type}
+@tab C only.
+@item @option{-Wold-style-declaration}
+@tab C only.
+@item @option{-Woverride-init}
+@item @option{-Wsign-compare}
+@tab C only.
+@item @option{-Wtype-limits}
+@item @option{-Wuninitialized}
+@item @option{-Wshift-negative-value}
+@tab C++03 and in C99 and newer.
+@item @option{-Wsized-deallocation}
+@tab @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
+@item @option{-Wunused-parameter}
+@tab Only with @option{-Wunused} or @option{-Wall}.
+@item @option{-Wunused-but-set-parameter}
+@tab Only with @option{-Wunused} or @option{-Wall}.
+@end multitable
 
 The option @option{-Wextra} also prints warning messages for the
 following cases:
@@ -6175,17 +6219,6 @@ When compiling C++, warn about the deprecated conv
 literals to @code{char *}.  This warning is enabled by default for C++
 programs.
 
-@item -Wcatch-value
-@itemx -Wcatch-value=@var{n} @r{(C++ and Objective-C++ only)}
-@opindex Wcatch-value
-@opindex Wno-catch-value
-Warn about catch handlers that do not catch via reference.
-With @option{-Wcatch-value=1} (or @option{-Wcatch-value} for short)
-warn about polymorphic class types that are caught by value.
-With @option{-Wcatch-value=2} warn about all class types that are caught
-by value. With @option{-Wcatch-value=3} warn about all types that are
-not caught by reference. @option{-Wcatch-value} is enabled by @option{-Wall}.
-
 @item -Wclobbered
 @opindex Wclobbered
 @opindex Wno-clobbered
@@ -6229,7 +6262,7 @@ types. @option{-Wconversion-null} is enabled by de
 Warn when a literal @samp{0} is used as null pointer constant.  This can
 be useful to facilitate the conversion to @code{nullptr} in C++11.
 
-@item -Wsubobject-linkage @r{(C++ and Objective-C++ only)}
+@item -Wno-subobject-linkage @r{(C++ and Objective-C++ only)}
 @opindex Wsubobject-linkage
 @opindex Wno-subobject-linkage
 Warn if a class type has a base or a field whose type uses the anonymous
@@ -6295,7 +6328,7 @@ Warn when macros @code{__TIME__}, @code{__DATE__}
 are encountered as they might prevent bit-wise-identical reproducible
 compilations.
 
-@item -Wdelete-incomplete @r{(C++ and Objective-C++ only)}
+@item -Wno-delete-incomplete @r{(C++ and Objective-C++ only)}
 @opindex Wdelete-incomplete
 @opindex Wno-delete-incomplete
 Warn when deleting a pointer to incomplete type, which may cause