documentation feature request: don't alphabetize subcommands

[Augie Fackler]

> On Mar 26, 2019, at 18:56, Sietse Brouwer <sbbrouwer at gmail.com> wrote:
> 
> 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.

I don't have any guidance to offer, but will gladly review patches (and try to answer questions - though the manpage is pretty unloved at the moment) to improve our manpage story.

> 
> 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/
> _______________________________________________
> Mercurial mailing list
> Mercurial at mercurial-scm.org
> https://www.mercurial-scm.org/mailman/listinfo/mercurial