Only document -A/--assert options in cpp manual [PR122243]

Assertions are a preprocessor feature that has been declared obsolete
with strong warnings not to use them since 2001.  The main GCC manual
documents the -A command-line option but doesn't include the section
that explains the purpose of the feature or that it is obsolete; that
material appears only in the preprocessor manual.  It seems rather pointless
to clutter up the GCC manual with unhelpful documentation of an obsolete
feature, so I've restricted the option documentation to the
preprocessor manual too.  I've also added the missing documentation
entries for the long form of the option, --assert.

gcc/ChangeLog
	PR other/122243
	* doc/cppopts.texi (-A): Restrict option documentation to the CPP
	manual.  Also document the --assert form.
	* doc/invoke.texi (Option Summary): Don't list the -A option.

diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi
index c899ffcc024d42e5d1110ceb0ad76189e47d3db9..ff4a365b86a5627657c541f3f8bb894aeba08f8a 100644 (file)
--- a/gcc/doc/cppopts.texi
+++ b/gcc/doc/cppopts.texi
@@ -397,19 +397,30 @@ form @option{-fno-working-directory}.  If the @option{-P} flag is
 present in the command line, this option has no effect, since no
 @code{#line} directives are emitted whatsoever.
 
+@c The documentation for this option is not helpful to users without
+@c the longer explanation that appears only in the CPP manual, plus
+@c it's been documented as obsolete and "do not use" since 2001!
+@ifset cppmanual
 @opindex A
+@opindex assert
 @item -A @var{predicate}=@var{answer}
+@itemx --assert @var{predicate}=@var{answer}
+@itemx --assert=@var{predicate}=@var{answer}
 Make an assertion with the predicate @var{predicate} and answer
 @var{answer}.  This form is preferred to the older form @option{-A
 @var{predicate}(@var{answer})}, which is still supported, because
 it does not use shell special characters.
-@ifset cppmanual
-@xref{Obsolete Features}.
-@end ifset
+
+Assertions are an obsolete feature of the preprocessor, supported only
+for compatibility with legacy system headers on some targets.
+@xref{Obsolete Features}, for more details on use.
 
 @item -A -@var{predicate}=@var{answer}
+@itemx --assert -@var{predicate}=@var{answer}
+@itemx --assert=-@var{predicate}=@var{answer}
 Cancel an assertion with the predicate @var{predicate} and answer
 @var{answer}.
+@end ifset
 
 @opindex C
 @item -C

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 8a538d028b95aa912b4c9a902dd9f7a361b13cbb..551142f1fc15adf5e67b10443b208918c7ab5369 100644 (file)
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -723,9 +723,7 @@ Objective-C and Objective-C++ Dialects}.
 
 @item Preprocessor Options
 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
-@gccoptlist{-A@var{question}=@var{answer}
--A-@var{question}@r{[}=@var{answer}@r{]}
--C  -CC  -D@var{macro}@r{[}=@var{defn}@r{]}
+@gccoptlist{-C  -CC  -D@var{macro}@r{[}=@var{defn}@r{]}
 -dD  -dI  -dM  -dN  -dU
 -fdebug-cpp  -fdirectives-only  -fdollars-in-identifiers
 -fexec-charset=@var{charset}  -fextended-identifiers