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

[FUJIWARA Katsunori]

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.

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