doc: unify section level between help topics

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.

doc/gendoc.py

@@ -64,16 +64,16 b' def get_cmd(cmd, cmdtable):'
     return d
 
 def section(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
+    ui.write("%s\n%s\n\n" % (s, "\"" * encoding.colwidth(s)))
 
 def subsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s)))
+    ui.write("%s\n%s\n\n" % (s, '=' * encoding.colwidth(s)))
 
 def subsubsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "." * encoding.colwidth(s)))
+    ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
 
 def subsubsubsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "#" * encoding.colwidth(s)))
+    ui.write("%s\n%s\n\n" % (s, "." * encoding.colwidth(s)))
 
 
 def show_doc(ui):

doc/hg.1.txt

@@ -18,16 +18,16 b' Mercurial source code management system'
 
 
 Synopsis
---------
+""""""""
 **hg** *command* [*option*]... [*argument*]...
 
 Description
------------
+"""""""""""
 The **hg** command provides a command line interface to the Mercurial
 system.
 
 Command Elements
-----------------
+""""""""""""""""
 
 files...
     indicates one or more filename or relative path filenames; see
@@ -48,7 +48,7 b' repository path'
 .. include:: hg.1.gendoc.txt
 
 Files
------
+"""""
 
 ``/etc/mercurial/hgrc``, ``$HOME/.hgrc``, ``.hg/hgrc``
     This file contains defaults and configuration. Values in
@@ -90,20 +90,20 b' if the ``.orig`` file already exists and'
 it will be overwritten.
 
 Bugs
-----
+""""
 Probably lots, please post them to the mailing list (see Resources_
 below) when you find them.
 
 See Also
---------
+""""""""
 |hgignore(5)|_, |hgrc(5)|_
 
 Author
-------
+""""""
 Written by Matt Mackall <[e-mail]>
 
 Resources
----------
+"""""""""
 Main Web Site: http://mercurial.selenic.com/
 
 Source code repository: http://selenic.com/hg
@@ -111,7 +111,7 b' Source code repository: http://selenic.c'
 Mailing list: http://selenic.com/mailman/listinfo/mercurial
 
 Copying
--------
+"""""""
 Copyright (C) 2005-2012 Matt Mackall.
 Free use of this software is granted under the terms of the GNU General
 Public License version 2 or any later version.

doc/hgignore.5.txt

@@ -14,17 +14,17 b' syntax for Mercurial ignore files'
 .. include:: ../mercurial/help/hgignore.txt
 
 Author
-------
+======
 Vadim Gelfer <[e-mail]>
 
 Mercurial was written by Matt Mackall <[e-mail]>.
 
 See Also
---------
+========
 |hg(1)|_, |hgrc(5)|_
 
 Copying
--------
+=======
 This manual page is copyright 2006 Vadim Gelfer.
 Mercurial is copyright 2005-2012 Matt Mackall.
 Free use of this software is granted under the terms of the GNU General

doc/hgrc.5.txt

@@ -17,22 +17,22 b' configuration files for Mercurial'
 
 
 Synopsis
---------
+========
 
 .. include:: ../mercurial/help/config.txt
 
 Author
-------
+======
 Bryan O'Sullivan <[e-mail]>.
 
 Mercurial was written by Matt Mackall <[e-mail]>.
 
 See Also
---------
+========
 |hg(1)|_, |hgignore(5)|_
 
 Copying
--------
+=======
 This manual page is copyright 2005 Bryan O'Sullivan.
 Mercurial is copyright 2005-2012 Matt Mackall.
 Free use of this software is granted under the terms of the GNU General

hgext/acl.py

@@ -32,7 +32,7 b' 4) Allow list for paths (section ``ac'
 The allow and deny sections take key-value pairs.
 
 Branch-based Access Control
-...........................
+---------------------------
 
 Use the ``acl.deny.branches`` and ``acl.allow.branches`` sections to
 have branch-based access control. Keys in these sections can be
@@ -50,7 +50,7 b' You can add the "!" prefix to a user or '
 of the match.
 
 Path-based Access Control
-.........................
+-------------------------
 
 Use the ``acl.deny`` and ``acl.allow`` sections to have path-based
 access control. Keys in these sections accept a subtree pattern (with
@@ -58,7 +58,7 b' a glob syntax by default). The correspon'
 syntax as the other sections above.
 
 Groups
-......
+------
 
 Group names must be prefixed with an ``@`` symbol. Specifying a group
 name has the same effect as specifying all the users in that group.
@@ -69,7 +69,7 b' a Unix-like system, the list of users wi'
 Otherwise, an exception will be raised.
 
 Example Configuration
-.....................
+---------------------
 
 ::
 

hgext/convert/__init__.py

@@ -138,7 +138,7 b' def convert(ui, src, dest=None, revmapfi'
     repository from "default" to a named branch.
 
     Mercurial Source
-    ''''''''''''''''
+    ################
 
     The Mercurial source recognizes the following configuration
     options, which you can set on the command line with ``--config``:
@@ -155,7 +155,7 b' def convert(ui, src, dest=None, revmapfi'
         It takes a hg revision identifier and defaults to 0.
 
     CVS Source
-    ''''''''''
+    ##########
 
     CVS source will use a sandbox (i.e. a checked-out copy) from CVS
     to indicate the starting point of what will be converted. Direct
@@ -207,7 +207,7 b' def convert(ui, src, dest=None, revmapfi'
     the command help for more details.
 
     Subversion Source
-    '''''''''''''''''
+    #################
 
     Subversion source detects classical trunk/branches/tags layouts.
     By default, the supplied ``svn://repo/path/`` source URL is
@@ -239,7 +239,7 b' def convert(ui, src, dest=None, revmapfi'
         The default is 0.
 
     Perforce Source
-    '''''''''''''''
+    ###############
 
     The Perforce (P4) importer can be given a p4 depot path or a
     client specification as source. It will convert all files in the
@@ -255,7 +255,7 b' def convert(ui, src, dest=None, revmapfi'
         Perforce changelist number).
 
     Mercurial Destination
-    '''''''''''''''''''''
+    #####################
 
     The following options are supported:
 

mercurial/help/config.txt

@@ -13,7 +13,7 b' The above entries will be referred to as'
 ``ui.verbose``, respectively. See the Syntax section below.
 
 Files
------
+=====
 
 Mercurial reads configuration data from several files, if they exist.
 These files do not exist by default and you will have to create the
@@ -86,7 +86,7 b' ones.'
     order until one or more configuration files are detected.
 
 Syntax
-------
+======
 
 A configuration file consists of sections, led by a ``[section]`` header
 and followed by ``name = value`` entries (sometimes called
@@ -171,14 +171,14 b' quotation marks at the beginning of a wo'
 (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).
 
 Sections
---------
+========
 
 This section describes the different sections that may appear in a
 Mercurial configuration file, the purpose of each section, its possible
 keys, and their possible values.
 
 ``alias``
-"""""""""
+---------
 
 Defines command aliases.
 Aliases allow you to define your own commands in terms of other
@@ -238,7 +238,7 b' echo foo`` call above, ``$HG_ARGS`` woul'
 
 
 ``annotate``
-""""""""""""
+------------
 
 Settings used when displaying file annotations. All values are
 Booleans and default to False. See ``diff`` section for related
@@ -255,7 +255,7 b' options for the diff command.'
 
 
 ``auth``
-""""""""
+--------
 
 Authentication credentials for HTTP authentication. This section
 allows you to store usernames and passwords for use when logging
@@ -322,7 +322,7 b' for credentials as usual if required by '
 
 
 ``decode/encode``
-"""""""""""""""""
+-----------------
 
 Filters for transforming files on checkout/checkin. This would
 typically be used for newline processing or other
@@ -369,7 +369,7 b' format. We suggest you use the ``eol`` e'
 
 
 ``defaults``
-""""""""""""
+------------
 
 (defaults are deprecated. Don't use them. Use aliases instead)
 
@@ -389,7 +389,7 b' to the aliases of the commands defined.'
 
 
 ``diff``
-""""""""
+--------
 
 Settings used when displaying diffs. Everything except for ``unified``
 is a Boolean and defaults to False. See ``annotate`` section for
@@ -417,7 +417,7 b' related options for the annotate command'
     Number of lines of context to show.
 
 ``email``
-"""""""""
+---------
 
 Settings for extensions that send email messages.
 
@@ -472,7 +472,7 b' Email example::'
 
 
 ``extensions``
-""""""""""""""
+--------------
 
 Mercurial has an extension mechanism for adding new features. To
 enable an extension, create an entry for it in this section.
@@ -499,7 +499,7 b' Example for ``~/.hgrc``::'
 
 
 ``format``
-""""""""""
+----------
 
 ``usestore``
     Enable or disable the "store" repository format which improves
@@ -526,7 +526,7 b' Example for ``~/.hgrc``::'
     repositories will be compatible with Mercurial before version 1.7.
 
 ``graph``
-"""""""""
+---------
 
 Web graph view configuration. This section let you change graph
 elements display properties by branches, for instance to make the
@@ -554,7 +554,7 b' Supported arguments:'
     Set branch edges color in hexadecimal RGB notation.
 
 ``hooks``
-"""""""""
+---------
 
 Commands or Python functions that get automatically executed by
 various actions such as starting or finishing a commit. Multiple
@@ -733,7 +733,7 b' is treated as a failure.'
 
 
 ``hostfingerprints``
-""""""""""""""""""""
+--------------------
 
 Fingerprints of the certificates of known HTTPS servers.
 A HTTPS connection to a server with a fingerprint configured here will
@@ -751,7 +751,7 b' This feature is only supported when usin'
 
 
 ``http_proxy``
-""""""""""""""
+--------------
 
 Used to access web-based Mercurial repositories through a HTTP
 proxy.
@@ -775,7 +775,7 b' proxy.'
     in ``http_proxy.no``. True or False. Default: False.
 
 ``merge-patterns``
-""""""""""""""""""
+------------------
 
 This section specifies merge tools to associate with particular file
 patterns. Tools matched here will take precedence over the default
@@ -789,7 +789,7 b' Example::'
   **.jpg = myimgmerge
 
 ``merge-tools``
-"""""""""""""""
+---------------
 
 This section configures external merge tools to use for file-level
 merges.
@@ -889,7 +889,7 b' Supported arguments:'
 
 
 ``patch``
-"""""""""
+---------
 
 Settings used when applying patches, for instance through the 'import'
 command or with Mercurial Queues extension.
@@ -907,7 +907,7 b' command or with Mercurial Queues extensi'
 
 
 ``paths``
-"""""""""
+---------
 
 Assigns symbolic names to repositories. The left side is the
 symbolic name, and the right gives the directory or URL that is the
@@ -924,7 +924,7 b' the following entries.'
     is specified.
 
 ``phases``
-""""""""""
+----------
 
 Specifies default handling of phases. See :hg:`help phases` for more
 information about working with phases.
@@ -940,7 +940,7 b' information about working with phases.'
     Default: draft
 
 ``profiling``
-"""""""""""""
+-------------
 
 Specifies profiling type, format, and file output. Two profilers are
 supported: an instrumenting profiler (named ``ls``), and a sampling
@@ -988,12 +988,12 b' profiling is done using lsprof.'
     stderr
 
 ``revsetalias``
-"""""""""""""""
+---------------
 
 Alias definitions for revsets. See :hg:`help revsets` for details.
 
 ``server``
-""""""""""
+----------
 
 Controls generic server settings.
 
@@ -1019,7 +1019,7 b' Controls generic server settings.'
     present. Default is False.
 
 ``smtp``
-""""""""
+--------
 
 Configuration for extensions that need to send email messages.
 
@@ -1048,7 +1048,7 b' Configuration for extensions that need t'
 
 
 ``subpaths``
-""""""""""""
+------------
 
 Subrepository source URLs can go stale if a remote server changes name
 or becomes temporarily unavailable. This section lets you define
@@ -1070,7 +1070,7 b' rewrite rules are then applied on the fu'
 are applied in definition order.
 
 ``trusted``
-"""""""""""
+-----------
 
 Mercurial will not use the settings in the
 ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
@@ -1094,7 +1094,7 b' user or service running Mercurial.'
 
 
 ``ui``
-""""""
+------
 
 User interface controls.
 
@@ -1213,7 +1213,7 b' User interface controls.'
 
 
 ``web``
-"""""""
+-------
 
 Web interface configuration. The settings in this section apply to
 both the builtin webserver (started by :hg:`serve`) and the script you

mercurial/help/hgignore.txt

@@ -1,12 +1,12 b''
 Synopsis
---------
+========
 
 The Mercurial system uses a file called ``.hgignore`` in the root
 directory of a repository to control its behavior when it searches
 for files that it is not currently tracking.
 
 Description
------------
+===========
 
 The working directory of a Mercurial repository will often contain
 files that should not be tracked by Mercurial. These include backup
@@ -39,7 +39,7 b' added with :hg:`add X`, even if X would '
 in .hgignore.
 
 Syntax
-------
+======
 
 An ignore file is a plain text file consisting of a list of patterns,
 with one pattern per line. Empty lines are skipped. The ``#``
@@ -73,7 +73,7 b' regexp pattern, start it with ``^``.'
   Please see :hg:`help patterns` for details.
 
 Example
--------
+=======
 
 Here is an example ignore file. ::
 

mercurial/help/merge-tools.txt

@@ -17,7 +17,7 b' conflict markers. Mercurial does not inc'
 programs but relies on external tools for that.
 
 Available merge tools
-"""""""""""""""""""""
+=====================
 
 External merge tools and their properties are configured in the
 merge-tools configuration section - see hgrc(5) - but they can often just
@@ -40,7 +40,7 b' Internal tools are always available and '
 not handle symlinks or binary files.
 
 Choosing a merge tool
-"""""""""""""""""""""
+=====================
 
 Mercurial uses these rules when deciding which merge tool to use:
 

mercurial/help/phases.txt

@@ -1,5 +1,5 b''
 What are phases?
-----------------
+================
 
 Phases are a system for tracking which changesets have been or should
 be shared. This helps prevent common mistakes when modifying history
@@ -17,7 +17,7 b' changeset is public, all its ancestors a'
 changeset phases should only be changed towards the public phase.
 
 How are phases managed?
------------------------
+=======================
 
 For the most part, phases should work transparently. By default, a
 changeset is created in the draft phase and is moved into the public
@@ -29,7 +29,7 b' Phases can also be manually manipulated '
 if needed. See :hg:`help -v phase` for examples.
 
 Phases and servers
-------------------
+==================
 
 Normally, all servers are ``publishing`` by default. This means::
 
@@ -59,7 +59,7 b' See :hg:`help config` for more informati'
   publishing.
 
 Examples
---------
+========
 
  - list changesets in draft or secret phase::
 

mercurial/help/subrepos.txt

@@ -43,7 +43,7 b' 3. Nested repository states. They are de'
 
 
 Adding a Subrepository
-----------------------
+======================
 
 If ``.hgsub`` does not exist, create it and add it to the parent
 repository. Clone or checkout the external projects where you want it
@@ -53,7 +53,7 b' subrepository is tracked and the next co'
 ``.hgsubstate`` and bind it to the committed changeset.
 
 Synchronizing a Subrepository
------------------------------
+=============================
 
 Subrepos do not automatically track the latest changeset of their
 sources. Instead, they are updated to the changeset that corresponds
@@ -66,13 +66,13 b' subrepo at the desired revision, test in'
 commit in the parent repository to record the new combination.
 
 Deleting a Subrepository
-------------------------
+========================
 
 To remove a subrepository from the parent repository, delete its
 reference from ``.hgsub``, then remove its files.
 
 Interaction with Mercurial Commands
------------------------------------
+===================================
 
 :add: add does not recurse in subrepos unless -S/--subrepos is
     specified.  However, if you specify the full path of a file in a
@@ -132,7 +132,7 b' Interaction with Mercurial Commands'
     can require network access when using subrepositories.
 
 Remapping Subrepositories Sources
----------------------------------
+=================================
 
 A subrepository source location may change during a project life,
 invalidating references stored in the parent repository history. To

tests/test-convert.t

@@ -120,7 +120,7 b''
       to a named branch.
   
       Mercurial Source
-      ''''''''''''''''
+      ################
   
       The Mercurial source recognizes the following configuration options, which
       you can set on the command line with "--config":
@@ -138,7 +138,7 b''
                     revision identifier and defaults to 0.
   
       CVS Source
-      ''''''''''
+      ##########
   
       CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
       indicate the starting point of what will be converted. Direct access to
@@ -188,7 +188,7 b''
       more details.
   
       Subversion Source
-      '''''''''''''''''
+      #################
   
       Subversion source detects classical trunk/branches/tags layouts. By
       default, the supplied "svn://repo/path/" source URL is converted as a
@@ -220,7 +220,7 b''
                     specify start Subversion revision number. The default is 0.
   
       Perforce Source
-      '''''''''''''''
+      ###############
   
       The Perforce (P4) importer can be given a p4 depot path or a client
       specification as source. It will convert all files in the source to a flat
@@ -236,7 +236,7 b''
                     number).
   
       Mercurial Destination
-      '''''''''''''''''''''
+      #####################
   
       The following options are supported: