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
* 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.
---
gcc/doc/cppopts.texi | 17 ++++++++++++++---
gcc/doc/invoke.texi | 4 +---
2 files changed, 15 insertions(+), 6 deletions(-)
diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi
index c899ffcc024..ff4a365b86a 100644
--- 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 8a538d028b9..551142f1fc1 100644
--- 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
--
2.39.5
