documentation feature request: don't alphabetize subcommands

[Sietse Brouwer]

Dear Frederik,

Thank you for your suggestion to order the man page by topic rather than 
by alphabet -- it is welcome and appreciated. I agree that the man page 
should be as user-friendly and beginner-friendly as possible, like 
everything else in Mercurial seems to be (to my love-struck eyes). Some 
observations / me investigating out loud / points for myself to follow 
up on:

* The man page is the exception here: when one types `hg help`, the 
commands are already grouped by topic. The order of these groups is 
defined in mercurial/help.py [1]; it would be good, and presumably 
doable, to reuse this.

[1] https://www.mercurial-scm.org/repo/hg/file/4.9.1/mercurial/help.py


* Question: which script is responsible for the generating the man page 
as it currently is?

   - The man page is doc/hg.1
   - Its template is hg.1.txt
   - This template includes hg.1.gendoc.txt, which contains all
     commands in non-alphabetical order
   - hg.1.gendoc.txt is generated by gendoc.py
   - In gendoc.py, function commandprinter, line 188 is
     `for f in sorted(cmds)`. This is probably the place
     to use mercurial.help.CATEGORY_ORDER.
   - TODO: alter gendoc.commandprinter's for-loop, remake all docs,
     see what changes
   - TODO: check where else gendoc.commandprinter is used

* Idle thought: the man page is so large it is unwieldy. A table of 
contents would also make it easier to use. Is this as simple as adding a 
`..toctree::` statement in hg.1.txt? I had better try this out. TODO.

* Idle thought: Mercurial has excellent Reference documentation, in the 
form of the various `hg help <command>` and `hg help <topic>` pages. 
Absent: a help page that teaches users to use Mercurial (Tutorial), and 
possibly one or more help pages that explain the main concepts behind 
distributed version control (Explanation). That would also make for nice 
first sections in the super-big man page.

I'll have a look at the TODO's above and report back.

Kind regards,
Sietse

P.S. The categories "Reference", "Tutorial", and "Explanation" and 
(How-To) come from Divio's excellent article "What nobody tells you 
about documentation" [2], which everybody should totally read -- it's a 
real education. Django explicitly organises its documentation into these 
four types. In brief:

- Tutorial: Goal-oriented, useful when learning.
- How-To: Goal-oriented, useful when working.
- Explanations: Information-oriented; useful when learning.
- Reference: Information-oriented; useful when working. (Mercurial's 
help pages are excellent References.)

[2] https://www.divio.com/blog/documentation/