Richard Biener <[email protected]> writes: > 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 >
Right, this is nasty where something is "on in the common case, but not always" (so -O2 here). I also don't think everyone is aware of this convention of "list the inverse thing" (had to explain it to a few people the last few months for autoconf). Listing both makes any anchor links more robust in the future too. > 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? We shouldn't have any passes at least that are always-off ;) > > Richard. > >> >> -Sandra >>
