Skip to content
Snippets Groups Projects
  • Katsunori FUJIWARA's avatar
    979b107e
    doc: unify section level between help topics · 979b107e
    Katsunori FUJIWARA authored
    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.
    979b107e
    History
    doc: unify section level between help topics
    Katsunori FUJIWARA authored
    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.
test-convert.t 15.89 KiB
  $ cat >> $HGRCPATH <<EOF
  > [extensions]
  > convert=
  > [convert]
  > hg.saverev=False
  > EOF
  $ hg help convert
  hg convert [OPTION]... SOURCE [DEST [REVMAP]]
  
  convert a foreign SCM repository to a Mercurial one.
  
      Accepted source formats [identifiers]:
  
      - Mercurial [hg]
      - CVS [cvs]
      - Darcs [darcs]
      - git [git]
      - Subversion [svn]
      - Monotone [mtn]
      - GNU Arch [gnuarch]
      - Bazaar [bzr]
      - Perforce [p4]
  
      Accepted destination formats [identifiers]:
  
      - Mercurial [hg]
      - Subversion [svn] (history on branches is not preserved)
  
      If no revision is given, all revisions will be converted. Otherwise,
      convert will only import up to the named revision (given in a format
      understood by the source).
  
      If no destination directory name is specified, it defaults to the basename
      of the source with "-hg" appended. If the destination repository doesn't
      exist, it will be created.
  
      By default, all sources except Mercurial will use --branchsort. Mercurial
      uses --sourcesort to preserve original revision numbers order. Sort modes
      have the following effects:
  
      --branchsort  convert from parent to child revision when possible, which
                    means branches are usually converted one after the other.
                    It generates more compact repositories.
      --datesort    sort revisions by date. Converted repositories have good-
                    looking changelogs but are often an order of magnitude
                    larger than the same ones generated by --branchsort.
      --sourcesort  try to preserve source revisions order, only supported by
                    Mercurial sources.
  
      If "REVMAP" isn't given, it will be put in a default location
      ("<dest>/.hg/shamap" by default). The "REVMAP" is a simple text file that
      maps each source commit ID to the destination ID for that revision, like
      so:
  
        <source ID> <destination ID>
  
      If the file doesn't exist, it's automatically created. It's updated on
      each commit copied, so "hg convert" can be interrupted and can be run
      repeatedly to copy new commits.
  
      The authormap is a simple text file that maps each source commit author to
      a destination commit author. It is handy for source SCMs that use unix
      logins to identify authors (eg: CVS). One line per author mapping and the
      line format is:
  
        source author = destination author
  
      Empty lines and lines starting with a "#" are ignored.
  
      The filemap is a file that allows filtering and remapping of files and