Mercurial docs improvements?

[Ludovic Chabant]

> > - 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

Ah yes I forgot to mention that. There's a couple of things that I don't
like about this, though:

1) It doesn't work well (or at all) if we are thinking of having access
   to versioned docs.
2) I don't really like the idea of having an official Mercurial website
   that's an unholy mix of Flask views, generated html pages, wiki
   pages, and hgweb-served pages. We can try to make it look consistent
   (and thus transparent) by sharing templates and CSS styles, though,
   but, well, my gut feeling is that we should try and have a few moving
   parts as possible.
3) That URL is for the specific "status" command help of the "hg"
   repository. You can access the same page here for the "hg-committed"
   repository:
   https://www.mercurial-scm.org/repo/hg-committed/help/status So this
   duplicates things and makes things confusing for users, has a non-
   obvious URL, and, for pages like the "extensions" help
   (https://www.mercurial-scm.org/repo/hg-committed/help/extensions)
   lists the enabled/disabled extensions *for that repo*.

So as such, I don't think it's a good fit for a global, repo-independent
reference documentation.


> 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.)

Making a prettier default template for hgweb (and one that would be
consistent with the official website) would definitely be awesome
indeed, but it's outside the scope of what I want to achieve here. (as
such, for now at least, I'm going to ignore all your other comments
about hgweb :) )

I don't think we need to write parser and converters either. The hg help
pages can be generated into rST and that's probably all we need for now.

Although I could of course be mistaken, I frankly anticipate spending a
lot more time fiddling around with CSS, templates, and Makefiles that I
would with writing extra bits of code for HTML rendering or whatnot.

-- 
 l u d o .
 . 8 0 17 80