changeset 29759:aba2bb2a6d0f

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.
author Gregory Szorc <gregory.szorc@gmail.com>
date Sat, 06 Aug 2016 17:04:22 -0700
parents 3dbc95f3eb31
children 5e2365698d44
files mercurial/commands.py mercurial/help.py mercurial/help/internals/bundles.txt mercurial/help/internals/changegroups.txt mercurial/help/internals/requirements.txt mercurial/help/internals/revlogs.txt tests/test-help.t
diffstat 7 files changed, 51 insertions(+), 61 deletions(-) [+]
line wrap: on
line diff
--- a/mercurial/commands.py	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/commands.py	Sat Aug 06 17:04:22 2016 -0700
@@ -4593,12 +4593,15 @@
     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)
 
--- a/mercurial/help.py	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/help.py	Sat Aug 06 17:04:22 2016 -0700
@@ -184,13 +184,13 @@
     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')),
 ])
 
--- a/mercurial/help/internals/bundles.txt	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/help/internals/bundles.txt	Sat Aug 06 17:04:22 2016 -0700
@@ -1,6 +1,3 @@
-Bundles
-=======
-
 A bundle is a container for repository data.
 
 Bundles are used as standalone files as well as the interchange format
@@ -8,7 +5,7 @@
 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
--- a/mercurial/help/internals/changegroups.txt	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/help/internals/changegroups.txt	Sat Aug 06 17:04:22 2016 -0700
@@ -1,6 +1,3 @@
-Changegroups
-============
-
 Changegroups are representations of repository revlog data, specifically
 the changelog, manifest, and filelogs.
 
@@ -35,7 +32,7 @@
 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.
@@ -111,21 +108,21 @@
 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::
@@ -154,4 +151,3 @@
 
 That is, a *chunk* consisting of the filename (not terminated or padded)
 followed by N chunks constituting the *delta group* for this file.
-
--- a/mercurial/help/internals/requirements.txt	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/help/internals/requirements.txt	Sat Aug 06 17:04:22 2016 -0700
@@ -1,5 +1,3 @@
-Requirements
-============
 
 Repositories contain a file (``.hg/requires``) containing a list of
 features/capabilities that are *required* for clients to interface
@@ -19,7 +17,7 @@
 Mercurial core distribution.
 
 revlogv1
---------
+========
 
 When present, revlogs are version 1 (RevlogNG). RevlogNG was introduced
 in 2006. The ``revlogv1`` requirement has been enabled by default
@@ -28,7 +26,7 @@
 If this requirement is not present, version 0 revlogs are assumed.
 
 store
------
+=====
 
 The *store* repository layout should be used.
 
@@ -36,7 +34,7 @@
 was introduced in Mercurial 0.9.2.
 
 fncache
--------
+=======
 
 The *fncache* repository layout should be used.
 
@@ -48,7 +46,7 @@
 1.1 (released December 2008).
 
 shared
-------
+======
 
 Denotes that the store for a repository is shared from another location
 (defined by the ``.hg/sharedpath`` file).
@@ -58,7 +56,7 @@
 The requirement was added in Mercurial 1.3 (released July 2009).
 
 dotencode
----------
+=========
 
 The *dotencode* repository layout should be used.
 
@@ -70,7 +68,7 @@
 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
@@ -80,7 +78,7 @@
 1.9.
 
 generaldelta
-------------
+============
 
 Revlogs should be created with the *generaldelta* flag enabled. The
 generaldelta flag will cause deltas to be encoded against a parent
@@ -91,7 +89,7 @@
 default until Mercurial 3.7 (released February 2016).
 
 manifestv2
-----------
+==========
 
 Denotes that version 2 of manifests are being used.
 
@@ -100,7 +98,7 @@
 by default.
 
 treemanifest
-------------
+============
 
 Denotes that tree manifests are being used. Tree manifests are
 one manifest per directory (as opposed to a single flat manifest).
--- a/mercurial/help/internals/revlogs.txt	Fri Aug 05 15:01:16 2016 +0200
+++ b/mercurial/help/internals/revlogs.txt	Sat Aug 06 17:04:22 2016 -0700
@@ -1,6 +1,3 @@
-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.
@@ -28,7 +25,7 @@
 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
@@ -77,7 +74,7 @@
 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,
@@ -129,7 +126,7 @@
 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
@@ -153,7 +150,7 @@
 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
@@ -172,7 +169,7 @@
 (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:
@@ -187,7 +184,7 @@
    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.
--- a/tests/test-help.t	Fri Aug 05 15:01:16 2016 +0200
+++ b/tests/test-help.t	Sat Aug 06 17:04:22 2016 -0700
@@ -929,16 +929,16 @@
   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.
@@ -974,7 +974,7 @@
       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.
@@ -1050,21 +1050,21 @@
       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:
@@ -2872,28 +2872,28 @@
   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>
   
   
@@ -2957,8 +2957,7 @@
   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.
@@ -3000,7 +2999,7 @@
   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.
@@ -3091,19 +3090,19 @@
   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: