[PATCH 6 of 6 STABLE] doc: unify section level between help topics for TOC in generated documents

[Matt Mackall]

On Mon, 2012-05-14 at 12:07 +0900, FUJIWARA Katsunori wrote:
> At Fri, 11 May 2012 22:57:53 +0200,
> Matt Mackall wrote:
> > 
> > On Fri, 2012-05-11 at 11:41 +0900, FUJIWARA Katsunori wrote:
> > > At Fri, 27 Apr 2012 11:44:12 -0500,
> > > Matt Mackall wrote:
> > > > 
> > > > On Thu, 2012-04-26 at 21:38 +0900, FUJIWARA Katsunori wrote:
> > > > > # HG changeset patch
> > > > > # User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
> > > > > # Date 1335443568 -32400
> > > > > # Branch stable
> > > > > # Node ID a60e7e24b3486a93f619559df576835776975875
> > > > > # Parent  5a697ab463387ab6e7c934765e7858730e8af97e
> > > > > doc: unify section level between help topics for TOC in generated documents
> > > > > 
> > > > > some help topics use "-" for top level underlining section mark.
> > > > 
> > > > I think this is a great idea, but I think we should have a discussion
> > > > about a standard hierarchy of markers first. I for one don't like
> > > > '""""""' as a section marker at all.
> > > 
> > > Thank you for your comments.
> > > 
> > > As described in "HelpStyleGuide#Sections" wiki page (I wrote it, in
> > > fact), current implementation of 'doc/gendoc.py' and help documents
> > > use underlining section marks in order below:
> > > 
> > >     - " . # '
> > 
> > Ok, but I still really don't like '""""""' and would rather we didn't
> > use it heavily. I think we should start with the following sequence:
> 
> I'll use section marks below:
> 
>   level1
>   ======
> 
>     level2
>     ------
> 
>       level3
>       ......
> 
>         level4
>         ######
> 
>           level5
>           ''''''
> 
> and current 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 extension commands can use level4 or more
>   (now convert of hgext/convert uses level4)
> 
> BTW, are level4(#) and level5(') good to be used ? at least, level5
> seems to be bad as same as '"""""' mark, even though it is not yet
> used in documentation.

Seems fine. Not sure if we'll run into it.

-- 
Mathematics is the supreme nostalgia of our time.