[PATCH v3 0/3] bundle doc: generaliz & elaborate

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

This started as 1 patch in
https://lore.kernel.org/git/patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com/
but is now 3.

In rewriting the DESCRIPTION section per Junio's feedback I went on to
elaborate on the thin v.s. not thin bundles and in 3/3 rewrote some
prose to make heavier use of show and tell.

Per a certain recent CodingGuidelines discussion about patterns in our
documentation I've long thought that the sort of change I'm doing in
3/3 is something we could do more of. I.e. replacing somewhat complex
and dense prose with short paragraphs broken up by simple command
examples (and output), whenever possible.

Ævar Arnfjörð Bjarmason (3):
  bundle doc: rewrite the "DESCRIPTION" section
  bundle doc: split out thin v.s. not discussion from <rev-arg>
  bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 111 +++++++++++++++++++++++++++--------
 1 file changed, 87 insertions(+), 24 deletions(-)

Range-diff against v2:
1:  bc6a6d89224 ! 1:  2824133f423 bundle doc: rewrite the "DESCRIPTION" section
    @@ Commit message
     
         Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
         about what bundles are in general terms, rather than diving directly
    -    into one example of what they might be used for. This changes
    -    documentation that's been substantially the same ever since the
    -    command was added in 2e0afafebd8 (Add git-bundle: move objects and
    -    references by archive, 2007-02-22).
    +    into one example of what they might be used for.
    +
    +    This changes documentation that's been substantially the same ever
    +    since the command was added in 2e0afafebd8 (Add git-bundle: move
    +    objects and references by archive, 2007-02-22).
    +
    +    I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
    +    section, it briefly discusses the format, but then links to the
    +    technical/bundle-format.txt documentation.
    +
    +    The "the user must specify a basis" part of this is discussed below in
    +    "SPECIFYING REFERENCES", so I'm removing that part and letting the
    +    brief mention of "thin" suffice.
    +
    +    To the extent that we should say more on the topic that documentation
    +    will be improved by subsequent commits.
     
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Documentation/git-bundle.txt ##
    -@@ Documentation/git-bundle.txt: git-bundle(1)
    - 
    - NAME
    - ----
    --git-bundle - Move objects and refs by archive
    -+git-bundle - Create, unpack and manipulate bundles
    - 
    - 
    - SYNOPSIS
     @@ Documentation/git-bundle.txt: SYNOPSIS
      DESCRIPTION
      -----------
    @@ Documentation/git-bundle.txt: SYNOPSIS
     -machine be replicated on another machine, but the two machines cannot
     -be directly connected, and therefore the interactive Git protocols (git,
     -ssh, http) cannot be used.
    -+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
    -+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
    -+what references are contained within the bundle. The header is in the
    -+format emitted by linkgit:git-show-ref[1].
    - 
    +-
     -The 'git bundle' command packages objects and references in an archive
     -at the originating machine, which can then be imported into another
     -repository using 'git fetch', 'git pull', or 'git clone',
     -after moving the archive by some means (e.g., by sneakernet).
    +-
    +-As no
    +-direct connection between the repositories exists, the user must specify a
    +-basis for the bundle that is held by the destination repository: the
    +-bundle assumes that all objects in the basis are already in the
    +-destination repository.
    ++Create, unpack, and manipulate "bundle" files. Bundles are used for
    ++the "offline" transfer of Git objects without an active "server"
    ++sitting on the other side of the network connection.
    ++
    ++They can be used to create both incremental and full backups of a
    ++repository, and to relay the state of the references in one repository
    ++to another.
    ++
    ++Other git commands that understand protocols such as `ssh://` and
    ++`https://` can also operate on bundle files. It is possible
    ++linkgit:git-clone[1] a new repository from a bundle, to use
    ++linkgit:git-fetch[1] to fetch from one, and to list the references
    ++contained within it with linkgit:git-ls-remote[1].
    ++
    ++See the "EXAMPLES" section below for examples of how to use bundles.
    ++
    ++BUNDLE FORMAT
    ++-------------
    ++
    ++Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
    ++header indicating what references are contained within the bundle. The
    ++header is (mostly) in the format emitted by linkgit:git-show-ref[1].
    ++
     +Like the the packed archive format itself bundles can either be
     +self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
     +
    -+Bundles are useful for numerous purposes. They were originally
    -+designed to facilitate the transfer of repository data between
    -+repositories which could not be directly connect to each other, and
    -+therefore the interactive Git protocols (git, ssh, http) could not be
    -+used.
    -+
    -+In that scenario a bundle is produced on the originating machine. It
    -+is then transferred to the other machine (e.g. by sneakernet), and
    -+unpacked on the other end. The unpacking can happen either with
    -+linkgit:git-clone[1] (which knows how to clone from bundle files), or
    -+by "git bundle unbundle".
    - 
    - As no
    - direct connection between the repositories exists, the user must specify a
    -@@ Documentation/git-bundle.txt: basis for the bundle that is held by the destination repository: the
    - bundle assumes that all objects in the basis are already in the
    - destination repository.
    ++See link:technical/bundle-format.html[the `bundle-format`
    ++documentation] for more details.
      
    -+Similarly, bundles are commonly used to produce incremental backups of
    -+git repositories. See the "EXAMPLES" section below.
    -+
      OPTIONS
      -------
    - 
-:  ----------- > 2:  63f871a0c72 bundle doc: split out thin v.s. not discussion from <rev-arg>
-:  ----------- > 3:  14e4a724fb2 bundle doc: elaborate on rev<->ref restriction
-- 
2.32.0.610.gd639e370050