From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by sourceware.org (Postfix) with ESMTP id CB8E2385E82C for ; Mon, 16 Mar 2020 18:11:10 +0000 (GMT) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 75F931FB; Mon, 16 Mar 2020 11:11:10 -0700 (PDT) Received: from localhost (e121540-lin.manchester.arm.com [10.32.98.126]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 01FC13F67D; Mon, 16 Mar 2020 11:11:09 -0700 (PDT) From: Richard Sandiford To: Lewis Hyatt via Gcc-patches Mail-Followup-To: Lewis Hyatt via Gcc-patches , Lewis Hyatt , richard.sandiford@arm.com Subject: Re: [PATCH] driver: Improve the generated help text for alias options with arguments References: <20200315135300.GA32701@ldh-macbook.local> Date: Mon, 16 Mar 2020 18:11:08 +0000 In-Reply-To: <20200315135300.GA32701@ldh-macbook.local> (Lewis Hyatt via Gcc-patches's message of "Sun, 15 Mar 2020 09:53:00 -0400") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Status: No, score=-5.0 required=5.0 tests=GIT_PATCH_2, KAM_DMARC_STATUS, SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 16 Mar 2020 18:11:11 -0000 Lewis Hyatt via Gcc-patches writes: > Hello- > > Currently, if an option is both undocumented and an alias for a second option, > the help text generated by gcc --help directs the reader to use the other > option instead. This makes sense for deprecated options, but it seems this > pattern is also used for another case, namely when an option exists so as to > pass a default argument to another option. For instance this one, from > common.opt: > > ------------- > fdiagnostics-color > Common Alias(fdiagnostics-color=,always,never) > ; > > fdiagnostics-color= > Driver Common Joined RejectNegative Var(flag_diagnostics_show_color) Enum(diagnostic_color_rule) Init(DIAGNOSTICS_COLOR_NO) > -fdiagnostics-color=[never|always|auto] Colorize diagnostics. > ------------- > > This is nice because it means you can say -fdiagnostics-color as a shorthand > for -fdiagnostics-color=always, or -fno-diagnostics-color as a shorthand for > -fdiagnostics-color=never. However, the generated help text does not describe > it this way: > > ------------- > $ gcc --help=common | grep fdiagnostics-color > -fdiagnostics-color Same as -fdiagnostics-color=. Use the latter option instead. > -fdiagnostics-color=[never|always|auto] Colorize diagnostics. > ------------- > > Perhaps I am wrong and the non-argument usage is indeed meant to be deprecated, > but it feels more like it was intended as a convenience and could be documented > as such. What actually prompted this patch is that I am adding a new option for > GCC 11 with these never/always/auto semantics and I am a bit confused whether I > am supposed to add the aliased version or not. Feels like it's nice to add it, > but then the --help output says the opposite... > > Anyway, the attached patch would change the help output to the following... If > that seems to be an improvement and closer to the intended behavior, please let > me know. Thanks! > > ------------- > -fdiagnostics-color Same as -fdiagnostics-color=always (or, in negated form, -fdiagnostics-color=never). > -fdiagnostics-color=[never|always|auto] Colorize diagnostics. > ------------- > > FWIW there are three other options currently affected by this change > (-Wimplicit-fallthrough, -fcf-protection, and -flive-patching). The change for > -Wimplicit-fallthrough I think is particularly helpful: > > -Wimplicit-fallthrough Same as -Wimplicit-fallthrough=. Use the latter option instead. > becomes > -Wimplicit-fallthrough Same as -Wimplicit-fallthrough=3 (or, in negated form, -Wimplicit-fallthrough=0). I also see: - -ftail-call-workaround Same as -ftail-call-workaround=. Use the latter option instead. + -ftail-call-workaround Same as -ftail-call-workaround=1 (or, in negated form, -ftail-call-workaround=0). -ftail-call-workaround=<0,2> Disallow tail call optimization when a calling routine may have omitted character lengths. ... --imacros Same as -imacros. Use the latter option instead. --imacros= Same as -imacros. Use the latter option instead. --include Same as -include. Use the latter option instead. - --include-barrier Same as -I. Use the latter option instead. + --include-barrier Same as -I-. --include-directory Same as -I. Use the latter option instead. --include-directory-after Same as -idirafter. Use the latter option instead. --include-directory-after= Same as -idirafter. Use the latter option instead. ... - -Wnormalized Same as -Wnormalized=. Use the latter option instead. + -Wnormalized Same as -Wnormalized=nfc (or, in negated form, -Wnormalized=none). -Wnormalized=[none|id|nfc|nfkc] Warn about non-normalized Unicode strings. I agree all of these look like improvements, especially the --include-barrier one. But I think the include ones also show that the "Use the latter option instead." decision is independent of whether the option is defined to be an alias. FWIW, there's also: Wmissing-format-attribute C ObjC C++ ObjC++ Warning Alias(Wsuggest-attribute=format) ; which still ends up as: -Wmissing-format-attribute Same as -Wsuggest-attribute=format. Use the latter option instead. Not really my area though, so I don't have any specific suggestion about how to separate the cases. Thanks, Richard