doc: unify section level between help topics stable
authorFUJIWARA Katsunori <foozy@lares.dti.ne.jp>
Wed, 25 Jul 2012 16:40:38 +0900
branchstable
changeset 17267 979b107eaea2
parent 17266 4e35dea77e31
child 17268 8c31b652bdfe
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
doc/hg.1.txt
doc/hgignore.5.txt
doc/hgrc.5.txt
hgext/acl.py
hgext/convert/__init__.py
mercurial/help/config.txt
mercurial/help/hgignore.txt
mercurial/help/merge-tools.txt
mercurial/help/phases.txt
mercurial/help/subrepos.txt
tests/test-convert.t
--- a/doc/gendoc.py	Mon Jul 23 19:03:32 2012 +0200
+++ b/doc/gendoc.py	Wed Jul 25 16:40:38 2012 +0900
@@ -64,16 +64,16 @@
     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):
--- a/doc/hg.1.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/doc/hg.1.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -18,16 +18,16 @@
 
 
 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 @@
 .. 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 @@
 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 <mpm@selenic.com>
 
 Resources
----------
+"""""""""
 Main Web Site: http://mercurial.selenic.com/
 
 Source code repository: http://selenic.com/hg
@@ -111,7 +111,7 @@
 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.
--- a/doc/hgignore.5.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/doc/hgignore.5.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -14,17 +14,17 @@
 .. include:: ../mercurial/help/hgignore.txt
 
 Author
-------
+======
 Vadim Gelfer <vadim.gelfer@gmail.com>
 
 Mercurial was written by Matt Mackall <mpm@selenic.com>.
 
 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
--- a/doc/hgrc.5.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/doc/hgrc.5.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -17,22 +17,22 @@
 
 
 Synopsis
---------
+========
 
 .. include:: ../mercurial/help/config.txt
 
 Author
-------
+======
 Bryan O'Sullivan <bos@serpentine.com>.
 
 Mercurial was written by Matt Mackall <mpm@selenic.com>.
 
 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
--- a/hgext/acl.py	Mon Jul 23 19:03:32 2012 +0200
+++ b/hgext/acl.py	Wed Jul 25 16:40:38 2012 +0900
@@ -32,7 +32,7 @@
 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 @@
 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 @@
 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 @@
 Otherwise, an exception will be raised.
 
 Example Configuration
-.....................
+---------------------
 
 ::
 
--- a/hgext/convert/__init__.py	Mon Jul 23 19:03:32 2012 +0200
+++ b/hgext/convert/__init__.py	Wed Jul 25 16:40:38 2012 +0900
@@ -138,7 +138,7 @@
     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 @@
         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 @@
     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 @@
         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 @@
         Perforce changelist number).
 
     Mercurial Destination
-    '''''''''''''''''''''
+    #####################
 
     The following options are supported:
 
--- a/mercurial/help/config.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/mercurial/help/config.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -13,7 +13,7 @@
 ``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 @@
     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 @@
 (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 @@
 
 
 ``annotate``
-""""""""""""
+------------
 
 Settings used when displaying file annotations. All values are
 Booleans and default to False. See ``diff`` section for related
@@ -255,7 +255,7 @@
 
 
 ``auth``
-""""""""
+--------
 
 Authentication credentials for HTTP authentication. This section
 allows you to store usernames and passwords for use when logging
@@ -322,7 +322,7 @@
 
 
 ``decode/encode``
-"""""""""""""""""
+-----------------
 
 Filters for transforming files on checkout/checkin. This would
 typically be used for newline processing or other
@@ -369,7 +369,7 @@
 
 
 ``defaults``
-""""""""""""
+------------
 
 (defaults are deprecated. Don't use them. Use aliases instead)
 
@@ -389,7 +389,7 @@
 
 
 ``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 @@
     Number of lines of context to show.
 
 ``email``
-"""""""""
+---------
 
 Settings for extensions that send email messages.
 
@@ -472,7 +472,7 @@
 
 
 ``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 @@
 
 
 ``format``
-""""""""""
+----------
 
 ``usestore``
     Enable or disable the "store" repository format which improves
@@ -526,7 +526,7 @@
     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 @@
     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 @@
 
 
 ``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 @@
 
 
 ``http_proxy``
-""""""""""""""
+--------------
 
 Used to access web-based Mercurial repositories through a HTTP
 proxy.
@@ -775,7 +775,7 @@
     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 @@
   **.jpg = myimgmerge
 
 ``merge-tools``
-"""""""""""""""
+---------------
 
 This section configures external merge tools to use for file-level
 merges.
@@ -889,7 +889,7 @@
 
 
 ``patch``
-"""""""""
+---------
 
 Settings used when applying patches, for instance through the 'import'
 command or with Mercurial Queues extension.
@@ -907,7 +907,7 @@
 
 
 ``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 @@
     is specified.
 
 ``phases``
-""""""""""
+----------
 
 Specifies default handling of phases. See :hg:`help phases` for more
 information about working with phases.
@@ -940,7 +940,7 @@
     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 @@
     stderr
 
 ``revsetalias``
-"""""""""""""""
+---------------
 
 Alias definitions for revsets. See :hg:`help revsets` for details.
 
 ``server``
-""""""""""
+----------
 
 Controls generic server settings.
 
@@ -1019,7 +1019,7 @@
     present. Default is False.
 
 ``smtp``
-""""""""
+--------
 
 Configuration for extensions that need to send email messages.
 
@@ -1048,7 +1048,7 @@
 
 
 ``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 @@
 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 @@
 
 
 ``ui``
-""""""
+------
 
 User interface controls.
 
@@ -1213,7 +1213,7 @@
 
 
 ``web``
-"""""""
+-------
 
 Web interface configuration. The settings in this section apply to
 both the builtin webserver (started by :hg:`serve`) and the script you
--- a/mercurial/help/hgignore.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/mercurial/help/hgignore.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -1,12 +1,12 @@
 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 @@
 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 @@
   Please see :hg:`help patterns` for details.
 
 Example
--------
+=======
 
 Here is an example ignore file. ::
 
--- a/mercurial/help/merge-tools.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/mercurial/help/merge-tools.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -17,7 +17,7 @@
 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 @@
 not handle symlinks or binary files.
 
 Choosing a merge tool
-"""""""""""""""""""""
+=====================
 
 Mercurial uses these rules when deciding which merge tool to use:
 
--- a/mercurial/help/phases.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/mercurial/help/phases.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -1,5 +1,5 @@
 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 @@
 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 @@
 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 @@
   publishing.
 
 Examples
---------
+========
 
  - list changesets in draft or secret phase::
 
--- a/mercurial/help/subrepos.txt	Mon Jul 23 19:03:32 2012 +0200
+++ b/mercurial/help/subrepos.txt	Wed Jul 25 16:40:38 2012 +0900
@@ -43,7 +43,7 @@
 
 
 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 @@
 ``.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 @@
 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 @@
     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
--- a/tests/test-convert.t	Mon Jul 23 19:03:32 2012 +0200
+++ b/tests/test-convert.t	Wed Jul 25 16:40:38 2012 +0900
@@ -120,7 +120,7 @@
       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 @@
                     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 @@
       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 @@
                     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 @@
                     number).
   
       Mercurial Destination
-      '''''''''''''''''''''
+      #####################
   
       The following options are supported: