On 2/26/24 09:19, Joseph Myers wrote:
On Mon, 26 Feb 2024, Alejandro Colomar wrote:
The idea seems reasonable, but the patch needs documentation for the new
option in invoke.texi.
Thanks! Will do.
I don't see an obvious order in that file. Where would you put the
option? Do you want me to sort(1) it first, and then insert the new
option in alphabetic order?
Sandra might have a better idea of how the warning options ought to be
ordered in the manual. (Obviously, don't mix reordering with any content
changes.)
Please don't blindly sort the options sections of the manual. They've
typically been organized to present general options first (things like
-Wpedantic in the warning options section, or -g or -o in the debugging
and optimization optimization sections), then more specialized flags for
controlling specific individual behaviors. We could do a better job of
keeping the latter sublists alphabetized, but in some cases we have also
grouped documentation for related options together even if they are not
alphabetical, but that needs some manual review and decision-making and
should not be mixed with adding new content. We do try to keep the
lists in the "Option Summary" section alphabetized except for the
general options listed first, though.
As far as where to put documentation for new options, I'd say that you
should put it in alphabetical order in the appropriate section, unless
there is good reason to put it somewhere else, or the alphabetization of
the whole section is so messed-up you can't figure out where it should
go (putting it at the end is OK in that case, as opposed to some other
random location in the list). Remember to add the matching entry in the
appropriate "Option Summary" list, and for this option IIUC you also
need to add it to the lists of other options enabled by -Wextra and
-Wc++-compat.
Are we still accepting patches to add new options in stage 4, or is this
a stage 1 item?
-Sandra
