# HG changeset patch # User FUJIWARA Katsunori # Date 2012-07-25 07:40:38 # Node ID 979b107eaea2497d902af98ef6f3a46d2253be4a # Parent 4e35dea77e3120fe4bd003b5a113fcd60f8fdcd5 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. diff --git a/doc/gendoc.py b/doc/gendoc.py --- a/doc/gendoc.py +++ b/doc/gendoc.py @@ -64,16 +64,16 @@ 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): diff --git a/doc/hg.1.txt b/doc/hg.1.txt --- a/doc/hg.1.txt +++ b/doc/hg.1.txt @@ -18,16 +18,16 @@ 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 @@ 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 @@ 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 Resources ---------- +""""""""" Main Web Site: http://mercurial.selenic.com/ Source code repository: http://selenic.com/hg @@ -111,7 +111,7 @@ 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. diff --git a/doc/hgignore.5.txt b/doc/hgignore.5.txt --- a/doc/hgignore.5.txt +++ b/doc/hgignore.5.txt @@ -14,17 +14,17 @@ syntax for Mercurial ignore files .. include:: ../mercurial/help/hgignore.txt Author ------- +====== Vadim Gelfer Mercurial was written by Matt Mackall . 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 diff --git a/doc/hgrc.5.txt b/doc/hgrc.5.txt --- a/doc/hgrc.5.txt +++ b/doc/hgrc.5.txt @@ -17,22 +17,22 @@ configuration files for Mercurial Synopsis --------- +======== .. include:: ../mercurial/help/config.txt Author ------- +====== Bryan O'Sullivan . Mercurial was written by Matt Mackall . 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 diff --git a/hgext/acl.py b/hgext/acl.py --- a/hgext/acl.py +++ b/hgext/acl.py @@ -32,7 +32,7 @@ 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 @@ 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 @@ 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 @@ a Unix-like system, the list of users wi Otherwise, an exception will be raised. Example Configuration -..................... +--------------------- :: diff --git a/hgext/convert/__init__.py b/hgext/convert/__init__.py --- a/hgext/convert/__init__.py +++ b/hgext/convert/__init__.py @@ -138,7 +138,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ def convert(ui, src, dest=None, revmapfi Perforce changelist number). Mercurial Destination - ''''''''''''''''''''' + ##################### The following options are supported: diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt --- a/mercurial/help/config.txt +++ b/mercurial/help/config.txt @@ -13,7 +13,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ format. We suggest you use the ``eol`` e ``defaults`` -"""""""""""" +------------ (defaults are deprecated. Don't use them. Use aliases instead) @@ -389,7 +389,7 @@ 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 @@ 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 @@ 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 @@ Example for ``~/.hgrc``:: ``format`` -"""""""""" +---------- ``usestore`` Enable or disable the "store" repository format which improves @@ -526,7 +526,7 @@ 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 @@ 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 @@ 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 @@ This feature is only supported when usin ``http_proxy`` -"""""""""""""" +-------------- Used to access web-based Mercurial repositories through a HTTP proxy. @@ -775,7 +775,7 @@ 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 @@ Example:: **.jpg = myimgmerge ``merge-tools`` -""""""""""""""" +--------------- This section configures external merge tools to use for file-level merges. @@ -889,7 +889,7 @@ Supported arguments: ``patch`` -""""""""" +--------- Settings used when applying patches, for instance through the 'import' command or with Mercurial Queues extension. @@ -907,7 +907,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ Controls generic server settings. present. Default is False. ``smtp`` -"""""""" +-------- Configuration for extensions that need to send email messages. @@ -1048,7 +1048,7 @@ 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 @@ 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 @@ user or service running Mercurial. ``ui`` -"""""" +------ User interface controls. @@ -1213,7 +1213,7 @@ 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 diff --git a/mercurial/help/hgignore.txt b/mercurial/help/hgignore.txt --- a/mercurial/help/hgignore.txt +++ b/mercurial/help/hgignore.txt @@ -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 @@ 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 @@ regexp pattern, start it with ``^``. Please see :hg:`help patterns` for details. Example -------- +======= Here is an example ignore file. :: diff --git a/mercurial/help/merge-tools.txt b/mercurial/help/merge-tools.txt --- a/mercurial/help/merge-tools.txt +++ b/mercurial/help/merge-tools.txt @@ -17,7 +17,7 @@ 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 @@ 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: diff --git a/mercurial/help/phases.txt b/mercurial/help/phases.txt --- a/mercurial/help/phases.txt +++ b/mercurial/help/phases.txt @@ -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 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 @@ 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 @@ See :hg:`help config` for more informati publishing. Examples --------- +======== - list changesets in draft or secret phase:: diff --git a/mercurial/help/subrepos.txt b/mercurial/help/subrepos.txt --- a/mercurial/help/subrepos.txt +++ b/mercurial/help/subrepos.txt @@ -43,7 +43,7 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/tests/test-convert.t b/tests/test-convert.t --- a/tests/test-convert.t +++ b/tests/test-convert.t @@ -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: