Mercurial docs improvements?
ludovic at chabant.com
Mon Feb 18 17:15:37 EST 2019
> > - 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:
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"
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
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
> 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
More information about the Mercurial-devel