Mercurial docs improvements?

Jordi GutiƩrrez Hermoso jordigh at octave.org
Mon Feb 18 14:43:24 EST 2019


On Mon, 2019-02-18 at 12:48 -0500, Ludovic Chabant wrote:
> 
> 1. Make doc/Makefile also generate one html and man page per command and
>    extension.
> 
> - This would let us see the doc for, say, `hg status` over at
>   https://www.mercurial-scm.org/doc/hg-status.1.html

As we discussed in IRC, that page already exists, but it's hard to
find:

https://www.mercurial-scm.org/repo/hg/help/status

> 2. Improve integration of generated docs inside the website
> 
> - Change the html template used to generate the html docs so that it has
>   the standard website navigation around the content.

We can make the hgweb installation at mercurial-scm.org use whatever
template we want. It makes sense to me to give it a template that
matches the non-hgweb part of mercurial-scm.org, including static
links back to the non-hgweb site. I think making a custom template
might be easier than writing parsers and converters into manpage
formats (I've never really liked manpage formats to begin with though,
so maybe my opinion here doesn't count.)

I think as a matter of labour to be done, it would be easiest to
leverage hgweb and just write a custom mercurial-scm.org template for
it than anything else.

Speaking of default templates, maybe we should make something other
than paper the default. I don't like that it doesn't show full commit
messages and it overuses zebras when showing source code. The zebras
were something that mpm particularly insisted upon for a11y, but I
don't think this is a common a11y practice. (This is possibly a topic
for another time, though, or maybe it's related, not sure.)

> - Generate some doc index page with links to all the other generated
>   pages (categorized links to each command page, general links to
>   hgignore/hgrc, extensions, etc.)

hgweb already does this too, as you mentioned yourself.

https://www.mercurial-scm.org/repo/hg/help

> 3. Improve the website itself

Good ideas here. Just looks like a lot of work.

> 4. Make reference docs versioned

This would be helpful. Lots of other projects do this. Postgres and
Django and everything at Read The Docs comes to mind.



More information about the Mercurial-devel mailing list