Patchwork [1,of,2] help: don't try to render a section on sub-topics

login
register
mail settings
Submitter Gregory Szorc
Date Aug. 7, 2016, 12:14 a.m.
Message ID <40a3ee1fbba0c636c67a.1470528884@ubuntu-vm-main>
Download mbox | patch
Permalink /patch/16167/
State Accepted
Headers show

Comments

Gregory Szorc - Aug. 7, 2016, 12:14 a.m.
# HG changeset patch
# User Gregory Szorc <gregory.szorc@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.
Yuya Nishihara - Aug. 8, 2016, 1:27 p.m.
On Sat, 06 Aug 2016 17:14:44 -0700, Gregory Szorc wrote:
> # HG changeset patch
> # User Gregory Szorc <gregory.szorc@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.

Seems fine. I've queued only this since I can't be sure the next patch has
no factual errors, though it looks generally good.

Patch

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: &quot;1&quot;, &quot;2&quot;, and &quot;3&quot;. From a
   high-level, versions &quot;1&quot; and &quot;2&quot; 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 (&quot;0x00000000&quot;). 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 | ... |