> On Mar 26, 2019, at 18:56, Sietse Brouwer <[email protected]> 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 > [email protected] > https://www.mercurial-scm.org/mailman/listinfo/mercurial _______________________________________________ Mercurial mailing list [email protected] https://www.mercurial-scm.org/mailman/listinfo/mercurial
