On 11/18/2016 11:52 AM, Martin Sebor wrote:
[snip] I think it would be be ideal if all the options were sorted the same way in all sections. Is there some command to have texinfo sort them for us? If not, can we write a script to sort them, either each time just before generating the docs or manually? (I'm happy to help.) Otherwise, consistency will continue to be an elusive goal. There are at least two reasons why I don't think following the style used by each section is likely to yield good results (and clearly hasn't to date). First, the big sections already have examples of both approaches (or simply options out of order). In some of them it can also be hard to tell if the radix of the options you're looking to for guidance starts with an 'n'. Second, when adding more than one option to different sections (such as the -Wformat-length and -fprintf-format-length options) having to remember to apply a different sort order for each (warnings are sorted by radix but optimization options, for the most parts, strictly alphabetically), seems also likely to trip people up.
This is wandering off into a general documentation maintenance discussion that has little to do with the original patch review request.
GCC has way too many command-line options and most of them are interesting to only some tiny fraction of users. The documentation needs to be structured to focus on the options users are most likely to need or find useful, and not bury the information about the most important options in the middle of a huge pile of barely-useful documentation about barely-useful options. For this reason, I think a strict alphabetical sorting across the board is not helpful. E.g., for the list of optimization options, the -O options are clearly more important than the -f options controlling individual optimizations, so -O should be the first thing users see when they look at that section. Similarly for debug options, the vast majority of users won't care about anything other than -g. For target-specific options, it may make sense to list -march/-mcpu/-mtune together regardless of their alphabetization with respect to other -m options for that target.
My last round of cleanup on invoke.texi was focused on refining the categorization of options and moving some option documentation that was clearly mis-categorized to more appropriate places or newly-created categories. Having fewer items listed in each category makes the ordering of things within the group less critical.
I think people looking for documentation for a specific option should be looking in the index first. We should have @cindex entries for both the -ffoo and -fno-foo variants so the alphabetization works either way.
Anyway.... long story short.... there's probably no perfect organization for this chapter, and the sheer number of options being documented makes it a pile of work even to implement small changes in convention across the board. That shouldn't stop us from making incremental improvements in organization, one section at a time, or taking care not to make the current situation worse when adding documentation for new options.
-Sandra
