Man page: grouping commands by topic (patch in Phabricator)

[Sietse Brouwer]

Dear all,
(CC: Frederick)

Just over a month ago, a personal called Frederick suggested to the 
general Mercurial mailing list that the hg(1) man page could present its 
commands in a learning-friendly order, rather than in alphabetical 
order. This seemed like a sensible and useful suggestion, and `hg help` 
already groups commands by category and defines a useful category order, 
so I have prepared a patch stack and submitted that to Phabricator.

In summary: this patch stack makes the man page group commands by the 
same categories used in `hg help`, that is "Repository creation", 
"Remote repository management", "Change creation", et cetera.

- The first patch in the stack is https://phab.mercurial-scm.org/D6324
   "help: register the 'gpg' command category and give it a description"

- The last patch in the stack is https://phab.mercurial-scm.org/D6329
   "gendoc: nest command headers under category headers"

- A comment on that last patch links to the original and changed output 
of `hg.1` and `hg.1.html`, so you can examine the result.

I hope that this patch looks interesting enough to review. Some final 
remarks:

- The command headers get pushed one level down by the appearance of the 
command category headers. In the HTML this works. In the man page, 
though, there are not enough section levels so both levels get rendered 
as .SS headers. In practice, you still get the effect of category 
headers, because those are sentence-case phrases whereas the commands 
are lowercase words.

- The output of hgignore.5, hgrc.5, hg-ssh.8, and their HTML 
counterparts remains unchanged. They, too, are generated by 
`doc/gendoc.py`, but the changes don't affect their output.

Kind regards,

Sietse
Sietse Brouwer

PS: In general, how does one present such a patch stack in Phabricator 
to the mailing list? Does one link to the first patch in the stack, or 
to the last one, or to every patch? Should I mail a list of patches, 
instead?