From patchwork Wed Mar 27 10:57:14 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jakub Jelinek X-Patchwork-Id: 87694 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id BEDEF3864820 for ; Wed, 27 Mar 2024 10:58:02 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id E8C683860760 for ; Wed, 27 Mar 2024 10:57:30 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E8C683860760 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org E8C683860760 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1711537053; cv=none; b=H7cJ3GA1MS4jeYbG0UzbQm20sJJE7yh+4mSstr+xhm5nj9Z/NVkD2AO+793UdkSusZkimq0g3g9lsK6KHTWq0dZZ1PEk0ZYfzrX1ZLByMFaJGCXHjL/ZNQo5qTjvM3jC4YZ8lDYu9C7YOGuL+nTHJEQEXQgQMkJvTnEzFIP+6k4= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1711537053; c=relaxed/simple; bh=GZ5bF3rqBxsKMVdEc648eaGbKCRWlZVWfPqdIGMzcBo=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=WDI45Y3iLYBbi7cUss1gKW1IF6oDkMqqJ5j833PhDYjErIvWcf1RCnwIV0aNupMxUyrj6lmjzqaaWDy1dr47RVy88K+IV+qA7NMAcwJzsFkMkfxPrxy5bcA5SE0nriGnnISz+XeZ8r4wk6Y1vm/+WaxPtQY554kXub5aN0Niv/U= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1711537050; h=from:from:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type; bh=L4uVVpTa64m1YDdASKxgXEfKOHM0ygmlcbK72UUXCyU=; b=CudPHWj6g5Q0FcEMPNpZlh7npqhbJBWHrHucA3V9cHxI7gIT4bHQfxlFvsG/AdfVyRHOBp Xo7wBHMrw2rvisRtt6usWLdYNSZNTFAS8weT3eqBHNFb8i2pmYyg6sR6mLvUkxWqCREseA VbkXvLBMkFBz28n8KLP1DotHyf9XqAg= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-3-P7HxQoL9N1W36A4cGbZUkQ-1; Wed, 27 Mar 2024 06:57:27 -0400 X-MC-Unique: P7HxQoL9N1W36A4cGbZUkQ-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 261E98F8F66; Wed, 27 Mar 2024 10:57:27 +0000 (UTC) Received: from tucnak.zalov.cz (unknown [10.39.192.57]) by smtp.corp.redhat.com (Postfix) with ESMTPS id DAF8B1C060D6; Wed, 27 Mar 2024 10:57:26 +0000 (UTC) Received: from tucnak.zalov.cz (localhost [127.0.0.1]) by tucnak.zalov.cz (8.17.1/8.17.1) with ESMTPS id 42RAvF711688668 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NOT); Wed, 27 Mar 2024 11:57:15 +0100 Received: (from jakub@localhost) by tucnak.zalov.cz (8.17.1/8.17.1/Submit) id 42RAvECo1688667; Wed, 27 Mar 2024 11:57:14 +0100 Date: Wed, 27 Mar 2024 11:57:14 +0100 From: Jakub Jelinek To: Gerald Pfeifer , "Joseph S. Myers" , Sandra Loosemore Cc: gcc-patches@gcc.gnu.org Subject: [PATCH] docs: Use @var{S} etc. in Spec File invoke.texi documentation Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline X-Spam-Status: No, score=-3.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Jakub Jelinek Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org 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. Jakub --- 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}, if not processing a file for language @code{S}. +@item %@{!,@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if not processing a file for language @code{@var{S}}. -@item %@{S|P:X@} -Substitutes @code{X} if either @code{-S} or @code{-P} is given to +@item %@{@var{S}|@var{P}:@var{X}@} +Substitutes @code{@var{X}} if either @code{-@var{S}} or @code{-@var{P}} is given to GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and @code{*} sequences as well, although they have a stronger binding than -the @samp{|}. If @code{%*} appears in @code{X}, all of the +the @samp{|}. If @code{%*} appears in @code{@var{X}}, all of the alternatives must be starred, and only the first matching alternative is substituted. @@ -37086,33 +37086,33 @@ jim.d -bar -boggle -d jim.d -bar -baz -boggle @end smallexample -@item %@{%:@var{function}(@var{args}):X@} +@item %@{%:@var{function}(@var{args}):@var{X}@} Call function named @var{function} with args @var{args}. If the -function returns non-NULL, then @code{X} is substituted, if it returns +function returns non-NULL, then @code{@var{X}} is substituted, if it returns NULL, it isn't substituted. -@item %@{S:X; T:Y; :D@} +@item %@{@var{S}:@var{X}; @var{T}:@var{Y}; :@var{D}@} -If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is -given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can +If @code{@var{S}} is given to GCC, substitutes @code{@var{X}}; else if @code{@var{T}} is +given to GCC, substitutes @code{@var{Y}}; else substitutes @code{@var{D}}. There can be as many clauses as you need. This may be combined with @code{.}, @code{,}, @code{!}, @code{|}, and @code{*} as needed. @end table -The switch matching text @code{S} in a @samp{%@{S@}}, @samp{%@{S:X@}} +The switch matching text @code{@var{S}} in a @samp{%@{@var{S}@}}, @samp{%@{@var{S}:@var{X}@}} or similar construct can use a backslash to ignore the special meaning of the character following it, thus allowing literal matching of a character that is otherwise specially treated. For example, -@samp{%@{std=iso9899\:1999:X@}} substitutes @code{X} if the +@samp{%@{std=iso9899\:1999:@var{X}@}} substitutes @code{@var{X}} if the @option{-std=iso9899:1999} option is given. -The conditional text @code{X} in a @samp{%@{S:X@}} or similar +The conditional text @code{@var{X}} in a @samp{%@{@var{S}:@var{X}@}} or similar construct may contain other nested @samp{%} constructs or spaces, or even newlines. They are processed as usual, as described above. -Trailing white space in @code{X} is ignored. White space may also +Trailing white space in @code{@var{X}} is ignored. White space may also appear anywhere on the left side of the colon in these constructs, except between @code{.} or @code{*} and the corresponding word. @@ -37120,7 +37120,7 @@ The @option{-O}, @option{-f}, @option{-m handled specifically in these constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or @option{-W} switch is found later in the command line, the earlier -switch value is ignored, except with @{@code{S}*@} where @code{S} is +switch value is ignored, except with @{@code{@var{S}}*@} where @code{@var{S}} is just one letter, which passes all matching options. The character @samp{|} at the beginning of the predicate text is used to