On Sat, Oct 4, 2025 at 7:27 PM 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?
IMO the current state is a bit inconsistent and confusing so I support switching to documenting the positive form. I'm noticing @opindex Wstrict-aliasing @opindex Wno-strict-aliasing @item -Wstrict-aliasing ... @opindex fstrict-aliasing @item -fstrict-aliasing where for example -fstrict-aliasing is the default (now), but we do not document (in the index) its negative form. Also quite some options have the negative form disabled. So - should we consistently add the negative form to the index? At least when the positive is the default with any setting? Richard. > > -Sandra >
