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

[frederik at ofb.net]

Dear Sietse,

Thank you for the attention, I am humbled that you would mention me
when introducing your work. I haven't looked closely at your code
changes but based on the output files you attached, I would be in
favor of adopting them.

I am of course happy if any changes are discussed and approved before
returning to the proposal that I had made a while ago, or even if it
is never returned to, since I'm not really active on this list.

However, if you are still reading: There was slightly more to my
proposal - namely, I was proposing to remove the alphabetical ordering
even within groups, by choosing some other possibly somewhat arbitrary
ordering, just as long as it is better than alphabetical (which I
think it will be, if it is generated by a human).

If I were permitted to attempt to summarize my own philosophy again,
it is that the main manual of a project should be like a kind of
sacred text which tutorials and other kinds of documentation can
comment on, just as we share commentaries on various sacred texts, or
even non-sacred texts like legal codes. Its usefulness as a canonical
text, as a target for commentary, is enhanced if things are ordered in
a logical fashion. This usefulness is also enhanced if it doesn't have
an excessive amount of links, if it doesn't exist as a wiki, if it
doesn't contain excess information (e.g. fonts in a PDF file, or CSS
in an HTML file). This is one reason why I prefer 'man' to 'info' -
info has links. I think manual pages are underrated, maybe because
they give the impression of "not trying hard enough to look pretty".
Far from shunning them, we should embrace them for their simplicity.
This means treating them as canonical texts. Sacred texts are not
alphabetized by chapter, or in any other way (as far as I know), so we
should try to move in that direction. Of course it is OK to move very
slowly, as these things take time. Just think of hg(1) as this
project's Bible, is my advice. Then people will study it carefully,
treat it (mostly) with respect, and so on. Of course, this is for when
and if you are ready for that kind of attention to be given to your
documentation.

But I imagine that we should discuss and approve Sietse's current set
of changes before moving onto anything else.

Thank you,

Frederick

On Mon, Apr 29, 2019 at 04:41:27PM +0200, Sietse Brouwer wrote:
>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?
>