Help Style Guide

How to format help texts for the builtin help in Mercurial.

1. Overview

The help system in Mercurial displays help texts in reStructuredText format on both the terminal (when you run 'hg help'), online (see http://selenic.com/hg/help/), and in manpages (see 'man hgrc' or http://www.selenic.com/mercurial/hgrc.5.html).

We reuse the help texts as much as possible and because different systems are used to generate the different formats, you need to be careful with what markup you use so that the help texts can be parsed by both. The two formatters are minirst and Docutils.

2. The minirst Formatter

For display in the terminal and in hgweb, we use our own parser and pretty-printer for reStructuredText. This parser is called minirst since it does not support the full reStructuredText language and since it takes many shortcuts when converting reStructuredText to pure ASCII.

The supported constructs are described in the following sections.

2.1. Sections

(reStructuredText reference)

You can only use the set of recommended characters for underlining sections:

- = ` : . ' " ~ ^ _ * + #

Sections can only be underlined, overlines are not supported. The underlines must match the length of the section exactly.

For successful building of documents in HTML or other formats, you should use characters for underlining sections in order below(6th level section is not yet written in documents for recent Mercurial):

- " . # '

In addition to it, each documents are automatically sub-sectioned, so only a part of them are available.

For help topics ("mercurial/help/*.txt"):

" . # '

For commands defined in Mercurial core ("mercurial/commands.py"):

. # '

For descriptions of extensions:

. # '

For commands defined in extensions:

'

2.2. Paragraphs

(reStructuredText reference)

These work as in normal reStructuredText. The text is re-wrapped to match the width of the terminal and in this process any double-spaces after sentences are removed.

2.3. Literal Blocks

(reStructuredText reference)

Works as in normal reStructuredText, including support for starting a literal block using '::' in the preceding paragraph:

Paragraph::

  Literal block. The above paragraph ends with a single ':'

Paragraph. ::

  Literal block, The above paragraph ends with a '.'

2.4. Definition Lists

(reStructuredText reference)

Only the simple form is supported:

A term
  A definition
Another term
  Another definition

2.5. Bullet Lists

(reStructuredText reference)

Almost like in normal reStructuredText, but the only supported bullet is '-':

- foo
- bar

2.6. Enumerated Lists

(reStructuredText reference)

Almost like in normal reStructuredText:

1. foo
2. bar

(a) foo
(b) bar

The numbers are not parsed or understood in any way, so it is up to you to number them correctly.

2.7. Field Lists

(reStructuredText reference)

Almost as in normal reStructuredText, except that colons cannot be escaped in the fields. The maximum field width is automatically computed so you can format your lists like this:

:a field: just a short field
:another field: a somewhat longer field

and the alignment will be corrected for you.

2.8. Option Lists

(reStructuredText reference)

There is only support for long options:

--long-option         Description of the long option.
--even-longer-option  A very long option.

The whitespace following the option is 'significant' and you have to align the descriptions yourself.

2.9. Inline Literals

(reStructuredText reference)

This is sort-of supported, but in a different way than in normal reStructuredText. It is used merely for markup and not for escaping. However, this is not a problem since inlike markup such as '*' for emphasis (italic) and '**' for strong emphasis (bold) is ignored anyway.

So minirst simply turns '``' into '"', that is, it converts the double-backping into a double-quote.

2.10. hg Interpreted Text Role

For linking to other commands, minirst supports a 'hg' interpreted text role. This lets you write

Please see :hg:`clone` for more information.

in the help text and it will come out as

Please see "hg clone" for more information.

on the terminal. While this looks the same in the terminal as if you had written 'Please see ``hg clone`` for more information.', the hg role creates a real link in the HTML version of the documentation.

3. The Docutils Formatter

For the manual page, we use the real Docutils package to parse and format everything. We have extended it with the custom hg role mentioned above, but apart from that it supports the full reStructuredText language.

4. Working with both minirst and Docutils

In most cases, minirst will be the limiting factor. So make sure to test how your help strings look in the terminal before you submit patches. However, minirst has been designed in such a way that it will parse everything -- it will never give up and tell you there is a syntax error. What happens is simply that all text blocks are classified as paragraphs to begin with, and minirst will then try to recognize different kinds of markup and change the classification accordingly.

So a paragraph containing too advanced reStructuredText will simply be treated as a plain paragraph by minirst. When Docutils sees the paragraph, the markup is of course recognized and you can get syntax errors or strange formatting if you are unlucky. As an example, a paragraph with

The active bookmark is marked with a *.

passes straight through minirst, whereas Docutils will complain about you forgetting to close the emphasis you started with '*'. The solution is to write

The active bookmark is marked with a ``*``.

which quotes the '*' correctly for Docutils and makes minirst turn it into '"*"' in the terminal output, which also looks nice.

You should therefore run 'make doc' once in a while to generate the documentation and make sure that there are no complaints from Docutils.

CategoryDeveloper