On Sat, Oct 4, 2025 at 10:27 AM Sandra Loosemore <[email protected]> wrote: > > While I was looking at something else I noticed that invoke.texi > explicitly documents both the positive and negative forms of several -g > options, both in the option summary list and the longer descriptions in > @node Debugging Options. > > Well, I see that the introductory text to the options chapter does say > > Many options have long names starting with @samp{-f} or with > @samp{-W}---for example, > @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of > these have both positive and negative forms; the negative form of > @option{-ffoo} is @option{-fno-foo}. This manual documents > only one of these two forms, whichever one is not the default. > > so to split hairs the convention that we only document one form only > applies to -f and -W options and not -g options, but it's silly to be > inconsistent about it. But, looking at these -g options, it's not > entirely clear to me which form is the default and which form we ought > to document. E.g. whether -gbtf is the default is target-specific; > -gprune-btf is the default if -gbtf is enabled but doesn't make sense at > all otherwise. > > I also see several -f, -W, and -m options that are documented as > "enabled by default", but listed in the positive form. Many others > listed in the positive form are enabled by default on some targets and > not others, or by some other optimization or target-specific codegen > options. So generally we are not applying the stated convention > consistently beyond these -g options, either. > > I think it might simplify things if we documented all options in the > positive form rather than having this mix of positive and negative, and > continual confusion about what "the default" is when it depends on other > things! Can we get some consensus between us documentation maintainers > about what to do here? Or does anybody else have strong opinions about it?
Not a documentation maintainer but as someone who points others to the documentation (due to bug triaging); I do find it would be useful to have both forms listed rather than a mix of one or the other. Having just the positive is also ok with me though not as good as both but still much better than the current situation. The current situation is a mix of: * negative form (mostly older options I think) * positive form (in some cases even if default) * both forms (some of the new options and depends on the person adding them) Thanks, Andrew > > -Sandra >
