Before this patch, ":hg:`help config.SECTION`" in online help text is
translated to a link to "hg.1.html#config.SECTION" in HTML
unintentionally.
This patch translates from :hg:`help config.SECTION` in online help
text to a valid link to "hgrc.5.html#SECTION" in HTML.
This patch ignores element(s) under "SECTION" (e.g. "ITEM" of
":hg:`help config.SECTION.ITEM`"), because there is no way to refer
directly to it in HTML, yet.
Before this patch, ":hg:`help config`" in online help text is
translated to a link to "hg.1.html#config" in HTML, even though actual
"hg help config" shows not help for "hg config" command but "config"
help topic, and all of current ":hg:`help config`" expects the latter.
This patch translates from ":hg:`help config`" in online help text to
a link to "hgrc.5.html" in HTML as expected.
This patch also allows ":hg:`help -c COMMAND`" style to link
"hg.1.html#COMMAND" for readability.
This is fixing for 'must indent 4 spaces' check-code rule.
check-code has overlooked this, because a file isn't recognized as one
to be checked (this problem is fixed by subsequent patch).
This is fixing for 'naked except clause' check-code rule.
check-code has overlooked this, because a file isn't recognized as one
to be checked (this problem is fixed by subsequent patch).
Specifically, :hg:`foo 'bar baz'` when rendered by `hg help`
results in:
'hg foo 'bar baz''
... which is hard to read.
We encourage :hg:`foo "bar baz"` instead.
This will make it possible to get semi-meaningful tracebacks if an import
error occurs.
Why care? Trying to run this script under pypy currently fails, but the
true error is obscured.
Without this, running gendoc.py during an install without C modules
available (via `make local`) will result in an import failure because
the default module load policy insists on C modules.
We also remove the sys.path adjustment because it is no longer needed
since our magic importer handles things.
If we don't change this, the upcoming change to make the module
loading policy only load C modules will cause this script to fail if
run with CPython against an unbuilt source checkout.
Future patches will require ui module to be passed to a help function, so
let's use it where appropriate.
Additional parens are necessary to silence a check-code warning.
Before this patch, short description of each commands is not shown in
generated documents (HTML file and UNIX man page). This omitting may
prevent users from understanding about commands.
This patch show it as the 1st paragraph in the help section of each
commands. This style is chosen because:
- showing it as the section title in "command - short desc" style
disallows referencing by "#command" in HTML file: in "en" locale,
hyphen concatenated title is used as the section ID in HTML file
for this style
- showing it as the 1st paragraph in "command - short desc" style
seems to be redundant: "command" appears also just before as the
section title
- showing it just after synopsis like "hg help command" seems not to
be reasonable in UNIX man page
This patch just writes short description ("d['desc'][0]") before "::",
because it should be already "strip()"-ed in "get_desc()", or empty
string for the command without description.
gendoc.py did not handle the hanging indentation for descriptions. Work around
this by joining all in one single line (same as in minirst since previous
patch).
This problem occurred when translations of option lines were very long. Do not
bother the translators with this detail.
On a long option description, the translator continued on a new line as usual.
gendoc.py created invalid rst syntax like this:
-o, --option
Description line 1
description line 2
The new output is:
-o, --option
Description line 1 description line 2
The lines could theoretically become very long, but line breaking is handled
when generating the final documentation.
Before this patch, HTML/man pages generated by docutils don't show
details of each command options, whether it should take argument or
not for example, even though "hg help" does.
This patch shows details of command options as same as "hg help"
shows.
This patch uses "--option <VALUE[+]>" style instead of "--option
<VALUE> [+]" used in output of "hg help", because docutils requires
that option argument strings starts with "<" and ends with ">".
Allow overwrite LANGUAGE and LC_ALL make variables, for make i18n man and html.
After this patch, we can make i18n man and html by following command:
$ make clean all LANGUAGE=ja
Before this patch, commnd __doc__ and extension __doc__ are not translatable.
But other messages, like doc of helptalbe, section headers, are translatable.
This patch makes commnd __doc__ and extension __doc__ translatable.
The check pattern only checked for whitespace between keyword and operator.
Now it also warns:
> x = f(),7
missing whitespace after ,
> x = f()+7
missing whitespace in expression
This patch adds "doc/check-seclevel.py" which checks below in help
documents:
- whether unknown or unavailable section marks are used or not
- whether appropriate section mark is used at sub-sectioning
It should be invoked in "doc" directory.
It checks all help documents of Mercurial (topics, commands,
extensions), if no file is specified by --file option.
With --file option, it checks contents of the specified file as help
document, for self testing purpose: -t/-c/-e/-C are used to specify
what kind of help document contents of the specified file is.
This checking is related to changeset 8d980034517b.
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.
Since docutils 0.9, `roman` module has been moved from module directory root
(i.e. `site-packages/roman.py`) to `docutils.utils` module. Therefore `import
roman` statement should be wrapped in `try: ... except ImportError: ...` block
to handle importing correctly.
