Mercurial docs improvements?
ludovic at chabant.com
Mon Feb 18 12:48:03 EST 2019
I started playing around with improving the Mercurial docs but before I
work on it more and send some patches, I wanted to get some opinions
about what people would like to see here. Sorry about the length of this
email but there's a lot to do IMHO.
What I have in mind is the following grand plan (I don't know if I'll
get to do everything but this is what I would _like_ to happen):
1. Make doc/Makefile also generate one html and man page per command and
- This would let us see the doc for, say, `hg status` over at
- When you just want to check the docs for a single command, it's a lot
easier than having to search "status" (with multiple hits) on the
giant hg.1.html page (I know I could just check the doc in my
terminal but sometimes I can't, or I prefer the browser for one
reason or another)
- It would generate `hg-<cmd>.1` pages (note the .1 suffix) because we
have this 1:1 mapping between man pages and html pages -- I assume we
want to keep that.
- This would also give us the ability to type, say, `man hg-status` and
get a man-formatted version of `hg help status`. I don't care too much
for that but I suppose it doesn't hurt.
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.
- Right now that's the top horizontal menu, more or less (but that might
change, see next points).
- If people prefer the online docs to not have this, we could generate 2
versions of the html: the `<whatever>.1.html` would be the "naked" man-
like doc in html form, while the `<whatever>.html` (without the man-
like number suffix) would be the "website integrated form"... or maybe
not and we just force people to hit the Back button often.
- 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.)
3. Improve the website itself
- Adding some proper link to the reference documentation (i.e. the
generated html doc pages... note how my previous point mentions
generating an index page for those, so that's what we would link to)
- Take a hard look at the navigation. Right now we have only a top
horizontal menu, which means only a handful of menu items at most.
This means that a lot of the navigation should be done with clear
lists of subpages on each top level page, so that it's easy to get a
mental picture of the website's structure, but in practice the links
are placed organically in the text and I find that confusing. It's
especially confusing when you have somewhat duplicate things (a
"Quickstart" sidebar on the main page, but also a dedicated
"quickstart" page), links to take you out to the wiki, interesting
pages whose links are buried in the text ("learn" page), etc.
- There should be a "Release Notes" or "What's New" link on the website
(I couldn't find one?), shown prominently on the "Downloads" page, and
that should link to a "proper" website page, too (possibly generated
like the reference docs), instead of linking to the wiki (but that
depends on how much manual labour goes into publishing the release
notes, I'm not familiar with that process).
- Similarly, I think the "Extensions" page on the website should be a
"proper" website page, at least as far as general docs and bundled
extensions go. It could link to the wiki for 3rd party extensions.
Honestly, it could (should?) be a link to the `hg help extensions`
topic as generated in html form, with some added bells and whistles
like links to each extension's reference doc page.
- Add some "Get Involved" page (couldn't find any either?) for how to
ask for help, report bugs, and contribute patches.
4. Make reference docs versioned
- The reference docs (hg.1.html, hg-status.1.html, hgignore.5.html,
etc.) should be versioned, so you can check out the docs from a
prior version of Mercurial (which is particularly helpful when
Phew, I think that's it! Right now, I've got #1 mostly figured out and
done, and I started playing around with #2.
l u d o .
. 8 0 17 80
More information about the Mercurial-devel