annotate doc/README @ 8781:385a2d94885e

hgrc.5: fix quoting of literal strings

The quotes would go wrong in many places due to differences between
asciidoc version 8.2.7 used by Benoit and 8.4.5 used by me. Between
those versions asciidoc stopped interpreting the content of `quoted
strings`, and so `*` would start bold text in the old version, but do
nothing in the new version.

To complicate things further, `\*` would escape the bold tag in the
old version, but in the new version the backslash was inserted
literally into the output (because the backtick quotes it).

I've now replaced backticks with non-quoting plusses and escaped
backslashes as appropriate.

Mercurial's documentation is currently kept in ASCIIDOC format, which
is a simple plain text format that's easy to read and edit. It's also
convertible to a variety of other formats including standard UNIX man
page format and HTML.

To do this, you'll need to install ASCIIDOC:

 http://www.methods.co.nz/asciidoc/

To generate the man page:

 asciidoc -d manpage -b docbook hg.1.txt
 xmlto man hg.1.xml

To display:

 groff -mandoc -Tascii hg.1 | more

To create the html page (without stylesheets):

 asciidoc -b html4 hg.1.txt

(older asciidoc may want html instead of html4 above)