Mercurial docs improvements?

Ludovic Chabant ludovic at chabant.com
Mon Feb 18 12:48:03 EST 2019


Hi there!

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

- This would let us see the doc for, say, `hg status` over at
  https://www.mercurial-scm.org/doc/hg-status.1.html
- 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
  helping someone).


Phew, I think that's it!   Right now, I've got #1 mostly figured out and
done, and I started playing around with #2.

Comments?

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


More information about the Mercurial-devel mailing list