From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-qt1-x844.google.com (mail-qt1-x844.google.com [IPv6:2607:f8b0:4864:20::844]) by sourceware.org (Postfix) with ESMTPS id BCD133877027 for ; Sun, 15 Mar 2020 13:53:03 +0000 (GMT) Received: by mail-qt1-x844.google.com with SMTP id l20so11837838qtp.4 for ; Sun, 15 Mar 2020 06:53:03 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:subject:message-id:mime-version :content-disposition:user-agent; bh=qYCM+AeX/K0vVIsehhsSBXFonbgWLKyRIXNhdvoIlXc=; b=BmVDoMjAh5IpsLwd1SZUluIo4/TF78JsSpw6HmNjTpZXpQRvzVoGB6/8Lvq0xR8vDb v06dyO/EoVHDjBo6ZawR9hdMcjHGnKu/+Izls/92I5dqUV/N/qP0K+RwVsq4LJ8lfwW2 aFqOr+0MUFuC6j4e+/4w4vtf8vssVXycywFkbDP58zuYoITEZURBtmNx+TjBB/oZC2X5 f3Cxu+2Uj6y4EeJEPszZ54hijPLSY1v4asDM6R+IAzLxE9UemjZb8ElkJueD815OOmKR MQpI6zLzHdd6YA2f5fKkfZXj9LzdTL6EjuEctuYgpuJwuEZuKjnPkamy3a9E8aYwQy9e lNrA== X-Gm-Message-State: ANhLgQ36JweHd0OQX7FAE5KUblqg+7aiEWpmbAPk/fZ8OEqhyzdCOg16 FbwBahMK+WIiLFn6ELPLSru4rg+z X-Google-Smtp-Source: ADFU+vuXTKahbvcO2tS1E33sWFEfXQrnJNKDYH+Janzh9NJy/QqRboupV4TRJ1jAiL6/Y1ICNAfDpQ== X-Received: by 2002:ac8:6c6:: with SMTP id j6mr21073845qth.231.1584280383044; Sun, 15 Mar 2020 06:53:03 -0700 (PDT) Received: from ldh-macbook.local (pool-173-54-19-91.nwrknj.fios.verizon.net. [173.54.19.91]) by smtp.gmail.com with ESMTPSA id j7sm29847138qti.14.2020.03.15.06.53.02 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 15 Mar 2020 06:53:02 -0700 (PDT) Date: Sun, 15 Mar 2020 09:53:00 -0400 From: Lewis Hyatt To: gcc-patches@gcc.gnu.org Subject: [PATCH] driver: Improve the generated help text for alias options with arguments Message-ID: <20200315135300.GA32701@ldh-macbook.local> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="qMm9M+Fa2AknHoGS" Content-Disposition: inline User-Agent: Mutt/1.12.2 (2019-09-21) X-Spam-Status: No, score=-25.2 required=5.0 tests=DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, 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: Sun, 15 Mar 2020 13:53:04 -0000 --qMm9M+Fa2AknHoGS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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). -Lewis --qMm9M+Fa2AknHoGS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline; filename="ChangeLog.txt" 2020-03-15 Lewis Hyatt * opts.c (print_filtered_help): Improve the help text for alias options with arguments. --qMm9M+Fa2AknHoGS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline; filename="alias_opt.patch" diff --git a/gcc/opts.c b/gcc/opts.c index ac160ed8404..a120858d77b 100644 --- a/gcc/opts.c +++ b/gcc/opts.c @@ -1315,14 +1315,31 @@ print_filtered_help (unsigned int include_flags, if (option->alias_target < N_OPTS && cl_options [option->alias_target].help) { + const struct cl_option *target = cl_options + option->alias_target; if (option->help == NULL) { - /* For undocumented options that are aliases for other options - that are documented, point the reader to the other option in - preference of the former. */ - snprintf (new_help, sizeof new_help, - _("Same as %s. Use the latter option instead."), - cl_options [option->alias_target].opt_text); + /* The option is undocumented but is an alias for an option that + is documented. If the option has alias arguments, then its + purpose is to provide certain arguments to the other option, so + inform the reader of this. Otherwise, point the reader to the + other option in preference to the former. */ + + if (option->alias_arg) + { + if (option->neg_alias_arg) + snprintf (new_help, sizeof new_help, + _("Same as %s%s (or, in negated form, %s%s)."), + target->opt_text, option->alias_arg, + target->opt_text, option->neg_alias_arg); + else + snprintf (new_help, sizeof new_help, + _("Same as %s%s."), + target->opt_text, option->alias_arg); + } + else + snprintf (new_help, sizeof new_help, + _("Same as %s. Use the latter option instead."), + target->opt_text); } else { --qMm9M+Fa2AknHoGS--