[PATCH 0 of 1] doc: add the tool to check section marks in help documents

[FUJIWARA Katsunori]

At Mon, 13 Aug 2012 15:23:09 +0200,
Mads Kiilerich wrote:
> 
> On 13/08/12 14:35, FUJIWARA Katsunori wrote:
> > This patch series adds "doc/check-seclevel.py" which checks section
> > mark usages in Mercurial help documents.
> >
> > In this series, to avoid adding new test script under tests, I added
> > "doc/check-seclevel.py" invocation to "tests/test-help.t", because I
> 
> ('sec' translates to 'security' for me. 'check-rst' seems more spot-on')

Would 'check-rst' seem to be inflated name for only checking section
marking ?

What about 'check-sectionmarks' ?

> > couldn't find other appropriate tests for it.
> >
> > But "tests/test-help.t" seems to be the test only for the help
> > function itself.
> >
> > Should I add it to another one or add new test script under tests ?
> 
> Wouldn't it be simpler to do the strict validation in the normal code 
> path in minirst and let it fail or warn if the markup doesn't comply 
> with our standards? I doubt the overhead would be measurable. Being less 
> flexible could perhaps even make it faster ...

By your comments, I understand that section marks in help documents
will be checked in minirst processing at each "hg help"
invocations. Am I right ?

From the point of view of implementation, we can add the code
validating usage of section marks in help documents to minirst normal
code path easily. But:

> but I guess we perhaps 
> still want to be able to handle all kinds of (non-compliant) rst.

I think so, too.

Users should want only to see help documents, but not to know whether
help documents comply with our standards or not.

----------------------------------------------------------------------
[FUJIWARA Katsunori]                             foozy at lares.dti.ne.jp