As Yuya pointed out during a review a month ago, _admonitions and
_admonitiontitles are largely redundant. With the last commit, they
are exactly redundant. So, remove _admonitions and use
_admonitiontitles.keys() instead.
The "admonition" rst primitive is split into "specific" admonitions
("attention," "caution," etc) and the "generic" admonition
("admonition"). For more, see
http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
The _admonitions set and keys of the _admonitiontitles dict
overlap exactly except _admonitions has an "admonition" entry.
Nowhere in Mercurial is the "admonition" admonition directive used.
Even if it were, it doesn't have a title, so it wouldn't be rendered
correctly.
So, let's remove "admonition" from the set of recognized admonition
directives.
This will allow consumers to declare a custom list of admonitions
to parse. Without this patch, custom admonitions would get removed
when prunecomments() is run. We could add an argument controlling
whether prunecomments() is run. However, it is better to convert
the "paragraph" block to an "admonition" block so consumers don't
have to parse for custom admonitions.
Currently, parsing admonitions uses a static regular expression created
from a pre-defined list of admonitions. A future patch will introduce a
feature that needs to parse custom admonitions. Prepare for this by
compiling the admonitions regular expression during each function
invocation.
Strictly speaking, there is a slight performance loss here. But we only
run this code as part of displaying help text. I don't think the loss
will be noticeable and I don't think we care if it were.
Previously, the "bullet" regular expression excluded the asterisk
('*') as a character denoting a bulleted list. Why I'm not sure
because the asterisk seems to be the canonical bullet character
in reST these days.
This patch makes asterisk-prefixed lines parse as bulleted lists.
Before this patch, "hg help topic.section" might show unexpected
section of help topic in some encoding.
It applies str.lower() instead of encoding.lower(str) on translated
message to search section case-insensitively, but some encoding uses
0x41(A) - 0x5a(Z) as the second or later byte of multi-byte character
(for example, ja_JP.cp932), and str.lower() causes unexpected result.
To search section of help topic by translated section name correctly,
this patch replaces str.lower() by encoding.lower(str) for both query
string (in commands.help()) and translated help text (in
minirst.getsections()).
test for "hg help -c config" in help config
``section``
-----------
section text
``def1``
definition of def1
$ hg help scope.def1
should list this paragraph, but not section text below...
section text
``def2``
definition of def2
$ hg help scope.def2
should list this paragraph, but not section text below...
section text
$ hg help scope.section should show everything from the first
section text to this last line.
``section2``
------------
Used to be that `hg help hgrc.paths` would show
"paths"
-------
Assigns symbolic names to repositories. The left side is the symbolic
name, and the right gives the directory or URL that is the location of the
repository. Default paths can be declared by setting the following
entries.
and stop there. Obviously the result seems better as shown in the
attached test.
There was a bug in df3ceb2fbb4d. The block that added definitions to
getsections should have been an elif, not an if. Otherwise section
titles get added twice, since the else clause would always get
executed for section titles.
When table data contained a newline, the result of minirst.maketable
did not look nice plus it was not recognised by minirst.format:
== === ====
l1 1 one
l2 2 2
22
l3
== === ====
This problem occurred when the description of options had a very long
translation which was split by newlines. Do not bother a translator with
this detail.
The multiline translations for option descriptions have been fixed in
7a88a81d5d9e in it.po, de.po and ro.po. I manually did the same as this patch
does, I removed the newlines.
When a newline was in the description, this created unusable help output:
$ hg help somecommand
hg somecommand [option]...
with somecommand, you can...
options:
== =================== =======================================================
=================================== --longdesc VALUE xxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -n --norm
normal desc --newline VALUE line1 line2 == =================== ===============
===========================================================================
now this looks much nicer:
...
options:
--longdesc VALUE xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-n --norm normal desc
--newline VALUE line1 line2
Lines with only a directive are not deleted anymore because they are detected
before comments are deleted by prunecomments().
addmargins() will be adapted later.
The default width of field lists is changed from 12 to 14 to align minirst with
the rst2html tool. Shrinking the width of the left column to fit the content is
removed, to keep formatting simple and uniform.
# this change redones part of e0051068893a, backed out by 38c00c035629
Some character encodings use ASCII characters other than
control/alphabet/digit as a part of multi-bytes characters, so direct
replacing with such characters on strings in local encoding causes
invalid byte sequences.
[mpm: test changed to simple doctest]
