Hi!
We got internally a question about the Spec File syntax, misunderstanding
what is the literal syntax and what are the placeholder variables in
the syntax descriptions.
The following patch attempts to use @var{S} etc. instead of just S
to clarify it stands for any option (or start of option etc.) rather
than literal S, say in %{S:X}. At least in HTML documentation it
then uses italics.
Bootstrapped/regtested on x86_64-linux and i686-linux, ok for trunk?
2024-03-26 Jakub Jelinek
* doc/invoke.texi (Spec Files): Use @var{S} instead of S,
@var{X} instead of X etc. for other placeholders.
--- gcc/doc/invoke.texi.jj 2024-03-26 10:01:08.290920704 +0100
+++ gcc/doc/invoke.texi 2024-03-26 21:56:46.133690400 +0100
@@ -36794,17 +36794,17 @@ Substitute the variable part of a matche
Note that each comma in the substituted string is replaced by
a single space.
-@item %S
-Similar to @samp{%@var{S}
+Similar to @samp{%<@var{S}}, but keep @code{-@var{S}} in the GCC command line.
@item %:@var{function}(@var{args})
Call the named function @var{function}, passing it @var{args}.
@@ -36988,47 +36988,47 @@ otherwise.
@end smallexample
@end table
-@item %@{S@}
-Substitutes the @code{-S} switch, if that switch is given to GCC@.
+@item %@{@var{S}@}
+Substitutes the @code{-@var{S}} switch, if that switch is given to GCC@.
If that switch is not specified, this substitutes nothing. Note that
the leading dash is omitted when specifying this option, and it is
automatically inserted if the substitution is performed. Thus the spec
string @samp{%@{foo@}} matches the command-line option @option{-foo}
and outputs the command-line option @option{-foo}.
-@item %W@{S@}
-Like %@{@code{S}@} but mark last argument supplied within as a file to be
+@item %W@{@var{S}@}
+Like %@{@code{@var{S}}@} but mark last argument supplied within as a file to be
deleted on failure.
-@item %@@@{S@}
-Like %@{@code{S}@} but puts the result into a @code{FILE} and substitutes
+@item %@@@{@var{S}@}
+Like %@{@code{@var{S}}@} but puts the result into a @code{FILE} and substitutes
@code{@@FILE} if an @code{@@file} argument has been supplied.
-@item %@{S*@}
+@item %@{@var{S}*@}
Substitutes all the switches specified to GCC whose names start
-with @code{-S}, but which also take an argument. This is used for
+with @code{-@var{S}}, but which also take an argument. This is used for
switches like @option{-o}, @option{-D}, @option{-I}, etc.
GCC considers @option{-o foo} as being
one switch whose name starts with @samp{o}. %@{o*@} substitutes this
text, including the space. Thus two arguments are generated.
-@item %@{S*&T*@}
-Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
-(the order of @code{S} and @code{T} in the spec is not significant).
+@item %@{@var{S}*&@var{T}*@}
+Like %@{@code{@var{S}}*@}, but preserve order of @code{@var{S}} and
@code{@var{T}} options
+(the order of @code{@var{S}} and @code{@var{T}} in the spec is not
significant).
There can be any number of ampersand-separated variables; for each the
wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
-@item %@{S:X@}
-Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
+@item %@{@var{S}:@var{X}@}
+Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is given to GCC@.
-@item %@{!S:X@}
-Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
+@item %@{!@var{S}:@var{X}@}
+Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is @emph{not}
given to GCC@.
-@item %@{S*:X@}
-Substitutes @code{X} if one or more switches whose names start with
-@code{-S} are specified to GCC@. Normally @code{X} is substituted only
+@item %@{@var{S}*:@var{X}@}
+Substitutes @code{@var{X}} if one or more switches whose names start with
+@code{-@var{S}} are specified to GCC@. Normally @code{@var{X}} is substituted
only
once, no matter how many such switches appeared. However, if @code{%*}
-appears somewhere in @code{X}, then @code{X} is substituted once
+appears somewhere in @code{@var{X}}, then @code{@var{X}} is substituted once
for each matching switch, with the @code{%*} replaced by the part of
that switch matching the @code{*}.
@@ -37049,23 +37049,23 @@ when matching an option like @option{-mc
--script=newchip/memory.ld
@end smallexample
-@item %@{.S:X@}
-Substitutes @code{X}, if processing a file with suffix @code{S}.
+@item %@{.@var{S}:@var{X}@}
+Substitutes @code{@var{X}}, if processing a file with suffix @code{@var{S}}.
-@item %@{!.S:X@}
-Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
+@item %@{!.@var{S}:@var{X}@}
+Substitutes @code{@var{X}}, if @emph{not} processing a file with suffix
@code{@var{S}}.
-@item %@{,S:X@}
-Substitutes @code{X}, if processing a file for language @code{S}.
+@item %@{,@var{S}:@var{X}@}
+Substitutes @code{@var{X}}, if processing a file for language @code{@var{S}}.
-@item %@{!,S:X@}
-Substitutes @code{X},
