Lewis Hyatt via Gcc-patches <gcc-patches@gcc.gnu.org> 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
