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.
This was an old left-over from when the synopsis line was used as a
header. We now have the command name by itself as the header and the
synopsis as a literal block immediately after..
Adds a section in the hg.1 manpage and corresponding hg.1.html
file. Each extension is listed with its module docstring, followed by
the commands defined by that extendsion.
Creates help for extensions by extracting doc strings from the extension modules
and its commands.
When getting docstrings from the source they are indented to look good
in the code. This indentation interferes with how the text is parsed
by rst. Therefore this indentation is removed.
this helps users to know what kind of option is:
- no value is required(flag option)
- value is required
- value is required, and multiple occurrences are allowed
each kinds are shown as below:
-f --force force push
-e --ssh CMD specify ssh command to use
-b --branch BRANCH [+] a specific branch you would like to push
if one or more 3rd type options are shown, explanation for '[+]' mark
is also shown as footnote.
The synopsis is used as an inline literal when generating the manpage.
There should not be any whitespace on the inside of the quotation
marks in inline literals.
Commands with an empty synopsis (such as tags) produces ``tags `` as
synopsis, which triggers a warning.
This ensures that we catch errors in the reST syntax early and for all
languages. The only change needed in gendoc.py was to correct the
computation of section underlines for Asian languages.
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.
When a topic provides a callable method for its text, most likely
this text will be generated from different parts, so it does not
make sense to apply gettext on the whole result, rather the method
should provide translation by itself.
This is the case with the extensions topic, which triggers a double
gettext call, making the ASCII codec fail when it encounters 8 bit
characters, and prevents the documentation from being built.
When looking up a help topic, the key is now only matched against the
short names for each topic, and not the header. So
hg help 'Environment Variables'
must be replaced with
hg help env
The helptable is used for helptopics listed in the manual
page, so the order of topics should not be random.
Convert it from a dictionary into a tuple of tuples.
Also reorder helptable entries to keep previous manual
page order.
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.