Some help topics use "-" for the top level underlining section mark,
but "-" is used also for the top level categorization in generated
documents: "hg.1.html", for example.
So, TOC in such documents contain "sections in each topics", too.
This patch changes underlining section mark in some help topics to
unify section level in generated documents.
After this patching, levels of each section marks are:
level0
""""""
level1
======
level2
------
level3
......
level4
######
And use of section markers in each documents are:
- mercurial/help/*.txt can use level1 or more
(now these use level1 and level2)
- help for core commands can use level2 or more
(now these use no section marker)
- descriptions of extensions can use level2 or more
(now hgext/acl uses level2)
- help for commands defined in extension can use level4 or more
(now "convert" of hgext/convert uses level4)
"Level0" is used as top level categorization only in "doc/hg.1.txt"
and the intermediate file generated by "doc/gendoc.py", so end users
don't see it in "hg help" outoput and so on.
I sometimes look at a piece of software and if the man page says
"Copyright 2004", then I'm inclined to think that the project is stale
or that the authors are lazy. Neither is good publicity for us :-)
I believe the backslash prevented asciidoc from automatically turning
"(C)" into a real copyright symbol. This replacement is not done in
reST in the first place.
This exposed a bug in rst2man where it neglects to escape a literal
backslash. A patch has been applied upstream, but not yet packaged in,
say, Debian unstable. A forward-compatible work-around has therefore
been put in place.
The Makefile now requires the rst2html and rst2man programs. Both can
be found in Debian testing or downloaded from the Docutils homepage:
http://docutils.sf.net/http://docutils.sf.net/sandbox/manpage-writer/
The new HTML and man pages no longer contain huge amounts of
un-wrapping literal blocks, thanks to how snippets of reStructuredText
can easily be included inside other reStructuredText documents.
The HTML pages now have anchors for all sections, including the help
topics in hgrc.1 which were missing from the old HTML pages.
Now that arguments can be mixed with options we can simplify the
synopsis considerably. Also, highlighting the command name in bold
(instead of italics) seem to be the standard convention.
Move the "Specifying Single Revisions" and "Specifying Multiple
Revisions" help topics from the manual page into the helptable
so they are available both online and in the manual page.
These names were disappearing in the asciidoc output and no form of
escaping seems to help. Let's just add repo/ to make it explicit that
they're in the repository root.
if set, override default hgrc search path.
if empty, only .hg/hgrc of current repo read.
for each element, if directory, all entries in directory with end in
".rc" are added to path. else, element is added to path.
big thing about this change is that user "~/.hgrc" and system hgrc not
longer breaks tests. run-tests makes HGRCPATH empty now.
gendoc.py is a script generating a part of the manpage (the commands
help and options) from the docstring in commands.py.
It avoids duplicating the doc between the doc/ directory and the docstrings.
To generate the manpage, 'make doc' will create all the necessary intermediate
files.