Patchwork [2,of,9] help: document bundle specifications

diff --git a/contrib/wix/help.wxs b/contrib/wix/help.wxs
--- a/contrib/wix/help.wxs
+++ b/contrib/wix/help.wxs
@@ -15,6 +15,7 @@ 
     <DirectoryRef Id="INSTALLDIR">
       <Directory Id="helpdir" Name="help" FileSource="$(var.SourceDir)">
         <Component Id="help.root" Guid="$(var.help.root.guid)" Win64='$(var.IsX64)'>
+          <File Name="bundlespec.txt" />
           <File Name="color.txt" />
           <File Name="config.txt" KeyPath="yes" />
           <File Name="dates.txt" />
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -210,6 +210,7 @@  def internalshelp(ui):
     return ''.join(lines)
 
 helptable = sorted([
+    (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
     (['color'], _("Colorizing Outputs"), loaddoc('color')),
     (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
     (["dates"], _("Date Formats"), loaddoc('dates')),
@@ -283,6 +284,8 @@  def addtopicsymbols(topic, marker, symbo
         return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
     addtopichook(topic, add)
 
+addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
+                util.bundlecompressiontopics())
 addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
 addtopicsymbols('merge-tools', '.. internaltoolsmarker',
                 filemerge.internalsdoc)
diff --git a/mercurial/help/bundlespec.txt b/mercurial/help/bundlespec.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/bundlespec.txt
@@ -0,0 +1,84 @@ 
+Mercurial supports generating standalone "bundle" files that hold repository
+data. These "bundles" are typically saved locally and used later or exchanged
+between different repositories, possibly on different machines. Example
+commands using bundles are :hg:`bundle` and :hg:`unbundle`.
+
+Generation of bundle files is controlled by a "bundle specification"
+("bundlespec") string. This string tells the bundle generation process how
+to create the bundle.
+
+A "bundlespec" string is composed of the following elements:
+
+type
+    A string denoting the bundle format to use.
+
+compression
+    Denotes the compression engine to use compressing the raw bundle data.
+
+parameters
+    Arbitrary key-value parameters to further control bundle generation.
+
+A "bundlespec" string has the following formats:
+
+<type>
+    The literal bundle format string is used.
+
+<compression>-<type>
+    The compression engine and format are delimited by a hypthen (``-``).
+
+Optional parameters follow the ``<type>``. Parameters are URI escaped
+``key=value`` pairs. Each pair is delimited by a semicolon (``;``). The
+first parameter begins after a ``;`` immediately following the ``<type>``
+value.
+
+Available Types
+===============
+
+The following bundle <type> strings are available:
+
+v1
+    Produces a legacy "changegroup" version 1 bundle.
+
+    This format is compatible with nearly all Mercurial clients because it is
+    the oldest. However, it has some limitations, which is why it is no longer
+    the default for new repositories.
+
+    ``v1`` bundles can be used with modern repositories using the "generaldelta"
+    storage format. However, it may take longer to produce the bundle and the
+    resulting bundle may be significantly larger than a ``v2`` bundle.
+
+    ``v1`` bundles can only use the ``gzip``, ``bzip2``, and ``none`` compression
+    formats.
+
+v2
+    Produces a version 2 bundle.
+
+    Version 2 bundles are an extensible format that can store additional
+    repository data (such as bookmarks and phases information) and they can
+    store data more efficiently, resulting in smaller bundles.
+
+    Version 2 bundles can also use modern compression engines, such as
+    ``zstd``, making them faster to compress and often smaller.
+
+Available Compression Engines
+=============================
+
+The following bundle <compression> engines can be used:
+
+.. bundlecompressionmarker
+
+Examples
+========
+
+``v2``
+    Produce a ``v2`` bundle using default options, including compression.
+
+``none-v1``
+    Produce a ``v2`` bundle with no compression.
+
+``zstd-v2``
+    Produce a ``v2`` bundle with zstandard compression using default
+    settings.
+
+``zstd-v1``
+    This errors because ``zstd`` is not supported for ``v1`` types.
diff --git a/tests/test-globalopts.t b/tests/test-globalopts.t
--- a/tests/test-globalopts.t
+++ b/tests/test-globalopts.t
@@ -340,6 +340,7 @@  Testing -h/--help:
   
   additional help topics:
   
+   bundlespec    Bundle File Formats
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
@@ -423,6 +424,7 @@  Testing -h/--help:
   
   additional help topics:
   
+   bundlespec    Bundle File Formats
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -102,6 +102,7 @@  Short help:
   
   additional help topics:
   
+   bundlespec    Bundle File Formats
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
@@ -179,6 +180,7 @@  Short help:
   
   additional help topics:
   
+   bundlespec    Bundle File Formats
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
@@ -827,6 +829,7 @@  Test that default list of commands omits
   
   additional help topics:
   
+   bundlespec    Bundle File Formats
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
@@ -1838,6 +1841,15 @@  Test dynamic list of merge tools only sh
       See the merge-tools and ui sections of hgrc(5) for details on the
       configuration of merge tools.
 
+Compression engines listed in `hg help bundlespec`
+
+  $ hg help bundlespec | grep gzip
+          "v1" bundles can only use the "gzip", "bzip2", and "none" compression
+        An algorithm that produces smaller bundles than "gzip".
+        This engine will likely produce smaller bundles than "gzip" but will be
+      "gzip"
+        better compression than "gzip". It also frequently yields better
+
 Test usage of section marks in help documents
 
   $ cd "$TESTDIR"/../doc
@@ -1899,6 +1911,13 @@  Dish up an empty repo; serve it cold.
   <tr><td colspan="2"><h2><a name="topics" href="#topics">Topics</a></h2></td></tr>
   
   <tr><td>
+  <a href="/help/bundlespec">
+  bundlespec
+  </a>
+  </td><td>
+  Bundle File Formats
+  </td></tr>
+  <tr><td>
   <a href="/help/color">
   color
   </a>
diff --git a/tests/test-hgweb-json.t b/tests/test-hgweb-json.t
--- a/tests/test-hgweb-json.t
+++ b/tests/test-hgweb-json.t
@@ -1549,6 +1549,10 @@  help/ shows help topics
     ],
     "topics": [
       {
+        "summary": "Bundle File Formats",
+        "topic": "bundlespec"
+      },
+      {
         "summary": "Colorizing Outputs",
         "topic": "color"
       },