[PATCH 1 of 2] help: don't try to render a section on sub-topics
Gregory Szorc
gregory.szorc at gmail.com
Sun Aug 7 00:14:44 UTC 2016
# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1470528262 25200
# Sat Aug 06 17:04:22 2016 -0700
# Node ID 40a3ee1fbba0c636c67aa69426459f606887828a
# Parent 3ef9aa7ad1fc4c43b92d48e4bb1f4e3de68b6910
help: don't try to render a section on sub-topics
This patch subtly changes the behavior of the parsing of "X.Y" values
to not set the "section" variable when rendering a known sub-topic.
Previously, "section" would be the same as the sub-topic name. This
required the sub-topic RST to have a section named the same as the
sub-topic name.
When I made this change, the descriptions from help.internalstable
started being rendered in command line output. This didn't look correct
to me, as it didn't match the formatting of main help pages. I
corrected this by moving the top section to help.internalstable and
changing the section levels of all the "internals" topics.
The end result is that "internals" topics now match the rendering of
main topics on both the CLI and HTML. And, "internals" topics no longer
require a main section matching the name of the topic.
diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -4597,22 +4597,25 @@ def help_(ui, name=None, **opts):
keep.append('unix')
keep.append(sys.platform.lower())
if ui.verbose:
keep.append('verbose')
section = None
subtopic = None
if name and '.' in name:
- name, section = name.split('.', 1)
- section = encoding.lower(section)
- if '.' in section:
- subtopic, section = section.split('.', 1)
+ name, remaining = name.split('.', 1)
+ remaining = encoding.lower(remaining)
+ if '.' in remaining:
+ subtopic, section = remaining.split('.', 1)
else:
- subtopic = section
+ if name in help.subtopics:
+ subtopic = remaining
+ else:
+ section = remaining
text = help.help_(ui, name, subtopic=subtopic, **opts)
formatted, pruned = minirst.format(text, textwidth, keep=keep,
section=section)
# We could have been given a weird ".foo" section without a name
# to look for, or we could have simply failed to found "foo.bar"
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -179,23 +179,23 @@ def loaddoc(topic, subdir=None):
doc = gettext(util.readfile(path))
for rewriter in helphooks.get(topic, []):
doc = rewriter(ui, topic, doc)
return doc
return loader
internalstable = sorted([
- (['bundles'], _('container for exchange of repository data'),
+ (['bundles'], _('Bundles'),
loaddoc('bundles', subdir='internals')),
- (['changegroups'], _('representation of revlog data'),
+ (['changegroups'], _('Changegroups'),
loaddoc('changegroups', subdir='internals')),
- (['requirements'], _('repository requirements'),
+ (['requirements'], _('Repository Requirements'),
loaddoc('requirements', subdir='internals')),
- (['revlogs'], _('revision storage mechanism'),
+ (['revlogs'], _('Revision Logs'),
loaddoc('revlogs', subdir='internals')),
])
def internalshelp(ui):
"""Generate the index for the "internals" topic."""
lines = []
for names, header, doc in internalstable:
lines.append(' :%s: %s\n' % (names[0], header))
diff --git a/mercurial/help/internals/bundles.txt b/mercurial/help/internals/bundles.txt
--- a/mercurial/help/internals/bundles.txt
+++ b/mercurial/help/internals/bundles.txt
@@ -1,19 +1,16 @@
-Bundles
-=======
-
A bundle is a container for repository data.
Bundles are used as standalone files as well as the interchange format
over the wire protocol used when two Mercurial peers communicate with
each other.
Headers
--------
+=======
Bundles produced since Mercurial 0.7 (September 2005) have a 4 byte
header identifying the major bundle type. The header always begins with
``HG`` and the follow 2 bytes indicate the bundle type/version. Some
bundle types have additional data after this 4 byte header.
The following sections describe each bundle header/type.
diff --git a/mercurial/help/internals/changegroups.txt b/mercurial/help/internals/changegroups.txt
--- a/mercurial/help/internals/changegroups.txt
+++ b/mercurial/help/internals/changegroups.txt
@@ -1,11 +1,8 @@
-Changegroups
-============
-
Changegroups are representations of repository revlog data, specifically
the changelog, manifest, and filelogs.
There are 3 versions of changegroups: ``1``, ``2``, and ``3``. From a
high-level, versions ``1`` and ``2`` are almost exactly the same, with
the only difference being a header on entries in the changeset
segment. Version ``3`` adds support for exchanging treemanifests and
includes revlog flags in the delta header.
@@ -30,17 +27,17 @@ is a framed piece of data::
Each chunk starts with a 32-bit big-endian signed integer indicating
the length of the raw data that follows.
There is a special case chunk that has 0 length (``0x00000000``). We
call this an *empty chunk*.
Delta Groups
-------------
+============
A *delta group* expresses the content of a revlog as a series of deltas,
or patches against previous revisions.
Delta groups consist of 0 or more *chunks* followed by the *empty chunk*
to signal the end of the delta group::
+------------------------------------------------------------------------+
@@ -106,31 +103,31 @@ In version 1, the delta is always applie
the changegroup or the first parent if this is the first entry in the
changegroup.
In version 2, the delta base node is encoded in the entry in the
changegroup. This allows the delta to be expressed against any parent,
which can result in smaller deltas and more efficient encoding of data.
Changeset Segment
------------------
+=================
The *changeset segment* consists of a single *delta group* holding
changelog data. It is followed by an *empty chunk* to denote the
boundary to the *manifests segment*.
Manifest Segment
-----------------
+================
The *manifest segment* consists of a single *delta group* holding
manifest data. It is followed by an *empty chunk* to denote the boundary
to the *filelogs segment*.
Filelogs Segment
-----------------
+================
The *filelogs* segment consists of multiple sub-segments, each
corresponding to an individual file whose data is being described::
+--------------------------------------+
| | | | |
| filelog0 | filelog1 | filelog2 | ... |
| | | | |
@@ -149,9 +146,8 @@ Each filelog sub-segment consists of the
| | | |
| filename size | filename | delta group |
| (32 bits) | (various) | (various) |
| | | |
+------------------------------------------+
That is, a *chunk* consisting of the filename (not terminated or padded)
followed by N chunks constituting the *delta group* for this file.
-
diff --git a/mercurial/help/internals/requirements.txt b/mercurial/help/internals/requirements.txt
--- a/mercurial/help/internals/requirements.txt
+++ b/mercurial/help/internals/requirements.txt
@@ -1,10 +1,8 @@
-Requirements
-============
Repositories contain a file (``.hg/requires``) containing a list of
features/capabilities that are *required* for clients to interface
with the repository. This file has been present in Mercurial since
version 0.9.2 (released December 2006).
One of the first things clients do when opening a repository is read
``.hg/requires`` and verify that all listed requirements are supported,
@@ -14,97 +12,97 @@ formats or even corrupting them by writi
Extensions may add requirements. When they do this, clients not running
an extension will be unable to read from repositories.
The following sections describe the requirements defined by the
Mercurial core distribution.
revlogv1
---------
+========
When present, revlogs are version 1 (RevlogNG). RevlogNG was introduced
in 2006. The ``revlogv1`` requirement has been enabled by default
since the ``requires`` file was introduced in Mercurial 0.9.2.
If this requirement is not present, version 0 revlogs are assumed.
store
------
+=====
The *store* repository layout should be used.
This requirement has been enabled by default since the ``requires`` file
was introduced in Mercurial 0.9.2.
fncache
--------
+=======
The *fncache* repository layout should be used.
The *fncache* layout hash encodes filenames with long paths and
encodes reserved filenames.
This requirement is enabled by default when the *store* requirement is
enabled (which is the default behavior). It was introduced in Mercurial
1.1 (released December 2008).
shared
-------
+======
Denotes that the store for a repository is shared from another location
(defined by the ``.hg/sharedpath`` file).
This requirement is set when a repository is created via :hg:`share`.
The requirement was added in Mercurial 1.3 (released July 2009).
dotencode
----------
+=========
The *dotencode* repository layout should be used.
The *dotencode* layout encodes the first period or space in filenames
to prevent issues on OS X and Windows.
This requirement is enabled by default when the *store* requirement
is enabled (which is the default behavior). It was introduced in
Mercurial 1.7 (released November 2010).
parentdelta
------------
+===========
Denotes a revlog delta encoding format that was experimental and
replaced by *generaldelta*. It should not be seen in the wild because
it was never enabled by default.
This requirement was added in Mercurial 1.7 and removed in Mercurial
1.9.
generaldelta
-------------
+============
Revlogs should be created with the *generaldelta* flag enabled. The
generaldelta flag will cause deltas to be encoded against a parent
revision instead of the previous revision in the revlog.
Support for this requirement was added in Mercurial 1.9 (released
July 2011). The requirement was disabled on new repositories by
default until Mercurial 3.7 (released February 2016).
manifestv2
-----------
+==========
Denotes that version 2 of manifests are being used.
Support for this requirement was added in Mercurial 3.4 (released
May 2015). The requirement is currently experimental and is disabled
by default.
treemanifest
-------------
+============
Denotes that tree manifests are being used. Tree manifests are
one manifest per directory (as opposed to a single flat manifest).
Support for this requirement was added in Mercurial 3.4 (released
August 2015). The requirement is currently experimental and is
disabled by default.
diff --git a/mercurial/help/internals/revlogs.txt b/mercurial/help/internals/revlogs.txt
--- a/mercurial/help/internals/revlogs.txt
+++ b/mercurial/help/internals/revlogs.txt
@@ -1,11 +1,8 @@
-Revlogs
-=======
-
Revision logs - or *revlogs* - are an append only data structure for
storing discrete entries, or *revisions*. They are the primary storage
mechanism of repository data.
Revlogs effectively model a directed acyclic graph (DAG). Each node
has edges to 1 or 2 *parent* nodes. Each node contains metadata and
the raw value for that node.
@@ -23,17 +20,17 @@ writes can be performed by truncating fi
using simple techniques. This means that references to other data in
the same revlog *always* refer to a previous entry.
Revlogs can be modeled as 0-indexed arrays. The first revision is
revision #0 and the second is revision #1. The revision -1 is typically
used to mean *does not exist* or *not defined*.
File Format
------------
+===========
A revlog begins with a 32-bit big endian integer holding version info
and feature flags. This integer is shared with the first revision
entry.
This integer is logically divided into 2 16-bit shorts. The least
significant half of the integer is the format/version short. The other
short holds feature flags that dictate behavior of the revlog.
@@ -72,17 +69,17 @@ 00 03 00 01
RevlogNG + inline + generaldelta
Following the 32-bit header is the remainder of the first index entry.
Following that are remaining *index* data. Inlined revision data is
possibly located between index entries. More on this layout is described
below.
RevlogNG Format
----------------
+===============
RevlogNG (version 1) begins with an index describing the revisions in
the revlog. If the ``inline`` flag is set, revision data is stored inline,
or between index entries (as opposed to in a separate container).
Each index entry is 64 bytes. The byte layout of each entry is as
follows, with byte 0 being the first byte (all data stored as big endian):
@@ -124,17 +121,17 @@ is no padding between it and the index e
If revision data is not inline, then raw revision data is stored in a
separate byte container. The offsets from bytes 0-5 and the compressed
length from bytes 8-11 define how to access this data.
The first 4 bytes of the revlog are shared between the revlog header
and the 6 byte absolute offset field from the first revlog entry.
Delta Chains
-------------
+============
Revision data is encoded as a chain of *chunks*. Each chain begins with
the compressed original full text for that revision. Each subsequent
*chunk* is a *delta* against the previous revision. We therefore call
these chains of chunks/deltas *delta chains*.
The full text for a revision is reconstructed by loading the original
full text for the base revision of a *delta chain* and then applying
@@ -148,17 +145,17 @@ amount of read I/O to load all chunks in
Deltas and delta chains are either computed against the previous
revision in the revlog or another revision (almost certainly one of
the parents of the revision). Historically, deltas were computed against
the previous revision. The *generaldelta* revlog feature flag (enabled
by default in Mercurial 3.7) activates the mode where deltas are
computed against an arbitrary revision (almost certainly a parent revision).
File Storage
-------------
+============
Revlogs logically consist of an index (metadata of entries) and
revision data. This data may be stored together in a single file or in
separate files. The mechanism used is indicated by the ``inline`` feature
flag on the revlog.
Mercurial's behavior is to use inline storage until a revlog reaches a
certain size, at which point it will be converted to non-inline. The
@@ -167,32 +164,32 @@ bound on how much data must be read to l
to read tens or hundreds of extra megabytes of data just to access the
index data.
The actual layout of revlog files on disk is governed by the repository's
*store format*. Typically, a ``.i`` file represents the index revlog
(possibly containing inline data) and a ``.d`` file holds the revision data.
Revision Entries
-----------------
+================
Revision entries consist of an optional 1 byte header followed by an
encoding of the revision data. The headers are as follows:
\0 (0x00)
Revision data is the entirety of the entry, including this header.
u (0x75)
Raw revision data follows.
x (0x78)
zlib (RFC 1950) data.
The 0x78 value is actually the first byte of the zlib header (CMF byte).
Hash Computation
-----------------
+================
The hash of the revision is stored in the index and is used both as a primary
key and for data integrity verification.
Currently, SHA-1 is the only supported hashing algorithm. To obtain the SHA-1
hash of a revision:
1. Hash the parent nodes
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -924,26 +924,26 @@ Test list of internal help commands
(use "hg help -v debug" to show built-in aliases and global options)
internals topic renders index of available sub-topics
$ hg help internals
Technical implementation topics
"""""""""""""""""""""""""""""""
- bundles container for exchange of repository data
- changegroups representation of revlog data
- requirements repository requirements
- revlogs revision storage mechanism
+ bundles Bundles
+ changegroups Changegroups
+ requirements Repository Requirements
+ revlogs Revision Logs
sub-topics can be accessed
$ hg help internals.changegroups
- Changegroups
- ============
+ Changegroups
+ """"""""""""
Changegroups are representations of repository revlog data, specifically
the changelog, manifest, and filelogs.
There are 3 versions of changegroups: "1", "2", and "3". From a high-
level, versions "1" and "2" are almost exactly the same, with the only
difference being a header on entries in the changeset segment. Version "3"
adds support for exchanging treemanifests and includes revlog flags in the
@@ -969,17 +969,17 @@ sub-topics can be accessed
Each chunk starts with a 32-bit big-endian signed integer indicating the
length of the raw data that follows.
There is a special case chunk that has 0 length ("0x00000000"). We call
this an *empty chunk*.
Delta Groups
- ------------
+ ============
A *delta group* expresses the content of a revlog as a series of deltas,
or patches against previous revisions.
Delta groups consist of 0 or more *chunks* followed by the *empty chunk*
to signal the end of the delta group:
+------------------------------------------------------------------------+
@@ -1045,31 +1045,31 @@ sub-topics can be accessed
the changegroup or the first parent if this is the first entry in the
changegroup.
In version 2, the delta base node is encoded in the entry in the
changegroup. This allows the delta to be expressed against any parent,
which can result in smaller deltas and more efficient encoding of data.
Changeset Segment
- -----------------
+ =================
The *changeset segment* consists of a single *delta group* holding
changelog data. It is followed by an *empty chunk* to denote the boundary
to the *manifests segment*.
Manifest Segment
- ----------------
+ ================
The *manifest segment* consists of a single *delta group* holding manifest
data. It is followed by an *empty chunk* to denote the boundary to the
*filelogs segment*.
Filelogs Segment
- ----------------
+ ================
The *filelogs* segment consists of multiple sub-segments, each
corresponding to an individual file whose data is being described:
+--------------------------------------+
| | | | |
| filelog0 | filelog1 | filelog2 | ... |
| | | | |
@@ -2867,38 +2867,38 @@ Sub-topic indexes rendered properly
<table class="bigtable">
<tr><td colspan="2"><h2><a name="main" href="#topics">Topics</a></h2></td></tr>
<tr><td>
<a href="/help/internals.bundles">
bundles
</a>
</td><td>
- container for exchange of repository data
+ Bundles
</td></tr>
<tr><td>
<a href="/help/internals.changegroups">
changegroups
</a>
</td><td>
- representation of revlog data
+ Changegroups
</td></tr>
<tr><td>
<a href="/help/internals.requirements">
requirements
</a>
</td><td>
- repository requirements
+ Repository Requirements
</td></tr>
<tr><td>
<a href="/help/internals.revlogs">
revlogs
</a>
</td><td>
- revision storage mechanism
+ Revision Logs
</td></tr>
</table>
</div>
@@ -2952,18 +2952,17 @@ Sub-topic topics rendered properly
<form class="search" action="/log">
<p><input name="rev" id="search1" type="text" size="30" /></p>
<div id="hint">Find changesets by keywords (author, files, the commit message), revision
number or hash, or <a href="/help/revsets">revset expression</a>.</div>
</form>
<div id="doc">
- <h1>representation of revlog data</h1>
- <h2>Changegroups</h2>
+ <h1>Changegroups</h1>
<p>
Changegroups are representations of repository revlog data, specifically
the changelog, manifest, and filelogs.
</p>
<p>
There are 3 versions of changegroups: "1", "2", and "3". From a
high-level, versions "1" and "2" are almost exactly the same, with
the only difference being a header on entries in the changeset
@@ -2995,17 +2994,17 @@ Sub-topic topics rendered properly
<p>
Each chunk starts with a 32-bit big-endian signed integer indicating
the length of the raw data that follows.
</p>
<p>
There is a special case chunk that has 0 length ("0x00000000"). We
call this an *empty chunk*.
</p>
- <h3>Delta Groups</h3>
+ <h2>Delta Groups</h2>
<p>
A *delta group* expresses the content of a revlog as a series of deltas,
or patches against previous revisions.
</p>
<p>
Delta groups consist of 0 or more *chunks* followed by the *empty chunk*
to signal the end of the delta group:
</p>
@@ -3086,29 +3085,29 @@ Sub-topic topics rendered properly
the changegroup or the first parent if this is the first entry in the
changegroup.
</p>
<p>
In version 2, the delta base node is encoded in the entry in the
changegroup. This allows the delta to be expressed against any parent,
which can result in smaller deltas and more efficient encoding of data.
</p>
- <h3>Changeset Segment</h3>
+ <h2>Changeset Segment</h2>
<p>
The *changeset segment* consists of a single *delta group* holding
changelog data. It is followed by an *empty chunk* to denote the
boundary to the *manifests segment*.
</p>
- <h3>Manifest Segment</h3>
+ <h2>Manifest Segment</h2>
<p>
The *manifest segment* consists of a single *delta group* holding
manifest data. It is followed by an *empty chunk* to denote the boundary
to the *filelogs segment*.
</p>
- <h3>Filelogs Segment</h3>
+ <h2>Filelogs Segment</h2>
<p>
The *filelogs* segment consists of multiple sub-segments, each
corresponding to an individual file whose data is being described:
</p>
<pre>
+--------------------------------------+
| | | | |
| filelog0 | filelog1 | filelog2 | ... |
More information about the Mercurial-devel
mailing list