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.
--- 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: