[PATCH v2 0/5] git doc + "git help": move "format" docs from technical/*

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

[This is a more meaty re-roll of [1]. It previously conflicted with
topics that have now landed. There is a trivial conflict here with
tb/cruft-packs, but that one's easily solved (they both edit adjacent
but otherwise unrelated lines in Documentation/Makefile)]

Most of git is documented in its manual pages, but we have various
"technical" and "howto" docs that aren't built as manpages, only as
HTML documentation.

In many cases that's sensible, e.g. we've got one-off mailing list
posts in there, but in the case of documenting git's core file formats
I think these belong in the main documentation space, especially as
many existing manual pages refer to these, but need to do so by
linking from "man" pages to "*.html" files the user may or may not
have locally.

This series starts out by creating a "userformats" category in our
documentation. The documentation for ".gitignore", ".gitattributes",
".mailmap" etc. is currently in the "guides" space. We now have a
"userformats" space with file formats users are expected to interact
with:
    
    $ git help --user-formats
    
    The user-facing file formats are:
       gitattributes          Defining attributes per path
       githooks               Hooks used by Git
       gitignore              Specifies intentionally untracked files to ignore
       gitmailmap             Map author/committer names and/or E-Mail addresses
       gitmodules             Defining submodule properties
       gitrepository-layout   Git Repository Layout

We then have (the main meat of this series) a move of relevant
"internal" and "protocol" formats over to the main documentation
space:

    $ git help --git-formats
    
    Git's internal file and network formats are:
       gitformat-bitmap                  The bitmap file format
       gitformat-bundle                  The bundle file format
       gitformat-chunk                   Chunk-based file formats
       gitformat-commit-graph            Git commit graph format
       gitformat-index                   Git index format
       gitformat-pack-protocol           How packs are transferred over-the-wire
       gitformat-protocol-capabilities   Protocol v0 and v1 capabilities
       gitformat-protocol-common         Things common to various protocols
       gitformat-protocol-v2             Git Wire Protocol, Version 2
       gitformat-signature               Git cryptographic signature formats

This isn't all of them, there's some in-flight conflicts with other
(trivial) changes to those files, so I've skipped them for now. Taylor
also has an in-flight series to add a new Documentation/technical/*
series. I'm planning on an eventual follow-up series (and have most of
the changes already) to move those over.

This also doesn't move over the part of the api-trace2.txt that deals
with the format users interact with, i.e. the JSON schema. I'm
submitting other changes in that are currently, and will eventually
loop around to moving that part over to this new "gitformats" space.

1. https://lore.kernel.org/git/cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (5):
  git docs: split "User-facing file formats" off from "Guides"
  git docs: create a "Git file and wire formats" section
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move {index,signature,bitmap,chunk}-format docs to man section 5

 Documentation/Makefile                        | 19 ++++---
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 13 +++--
 Documentation/git-upload-pack.txt             |  5 +-
 Documentation/git.txt                         | 15 ++++++
 ...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++---
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 25 ++++++++--
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 20 +++++++-
 ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---
 ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 Documentation/technical/http-protocol.txt     |  6 +--
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/pack-format.txt       |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 16 ++++++
 command-list.txt                              | 30 +++++++++---
 help.c                                        | 22 +++++++++
 help.h                                        |  2 +
 t/t0012-help.sh                               | 16 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 31 files changed, 386 insertions(+), 89 deletions(-)
 rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (86%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

Range-diff against v1:
1:  19a8be1fc73 ! 1:  960574b7f05 git(1) docs: split "User-facing file formats" off from "Guides"
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git(1) docs: split "User-facing file formats" off from "Guides"
    +    git docs: split "User-facing file formats" off from "Guides"
     
    -    Create a new "User-facing file formats" section in the main "git(1)"
    -    manual page. The "Guides" section was added to the manual page in
    +    Create a new "User-facing file formats" section in the main "git help
    +    git" manual page. The "Guides" section was added to the manual page in
         f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
         to list all that documentation.
     
    @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
     
      ## Documentation/git-help.txt ##
     @@ Documentation/git-help.txt: SYNOPSIS
    - 	   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
    + --------
    + [verse]
    + 'git help' [-a|--all [--[no-]verbose]]
    +-	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
    ++	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
      'git help' [-g|--guides]
      'git help' [-c|--config]
     +'git help' [--user-formats]
    @@ Documentation/git-help.txt: SYNOPSIS
      DESCRIPTION
      -----------
      
    --With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
    -+With no options and no COMMAND or DOC given, the synopsis of the 'git'
    +-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
    ++With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
      command and a list of the most commonly used Git commands are printed
      on the standard output.
      
    @@ command-list.txt
     +# .mailmap etc. files lives in man section 5. These entries can only
     +# have the "userformats" attribute and nothing else.
     +#
    - ### command list (do not change this line, also do not change alignment)
    + ### command list (do not change this line)
      # command name                          category [category] [category]
      git-add                                 mainporcelain           worktree
    -@@ command-list.txt: gitweb                                  ancillaryinterrogators
    +@@ command-list.txt: git-verify-tag                          ancillaryinterrogators
      git-whatchanged                         ancillaryinterrogators          complete
      git-worktree                            mainporcelain
      git-write-tree                          plumbingmanipulators
    @@ command-list.txt: gitdiffcore                             guide
      gitglossary                             guide
     -githooks                                guide
     -gitignore                               guide
    --gitmailmap                              guide
    --gitmodules                              guide
     +githooks                                userformats
     +gitignore                               userformats
    + gitk                                    mainporcelain
    +-gitmailmap                              guide
    +-gitmodules                              guide
     +gitmailmap                              userformats
     +gitmodules                              userformats
      gitnamespaces                           guide
    @@ command-list.txt: gitdiffcore                             guide
     +gitrepository-layout                    userformats
      gitrevisions                            guide
      gitsubmodules                           guide
    - gittutorial-2                           guide
    + gittutorial                             guide
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
2:  5e80ee09523 ! 2:  b2d73f8c9da git(1) docs: create a "Git file and wire formats" section
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git(1) docs: create a "Git file and wire formats" section
    +    git docs: create a "Git file and wire formats" section
     
    -    Create a new "Git file and wire formats" section in the main "git(1)"
    -    manual page and start moving the documentation that now lives in
    +    Create a new "Git file and wire formats" section in the main "git help
    +    git" manual page and start moving the documentation that now lives in
         "Documentation/technical/*.git" over to it. This compliments the newly
         added and adjacent "User-facing file formats" section.
     
    @@ Commit message
         So let's start moving those over, starting with just the
         "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
         Git bundle format, 2020-02-07). We'll now have a new
    -    gitformat-bundle(5) man page.
    +    gitformat-bundle(5) man page. Subsequent commits will move more git
    +    internal format documentation over.
     
         Unfortunately the syntax of the current Documentation/technical/*.txt
         is not the same (when it comes to section headings etc.) as our
    @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
      
     
      ## Documentation/git-bundle.txt ##
    -@@ Documentation/git-bundle.txt: using "thin packs" bundles created using exclusions are smaller in
    +@@ Documentation/git-bundle.txt: using "thin packs", bundles created using exclusions are smaller in
      size. That they're "thin" under the hood is merely noted here as a
    - curiosity, and as a reference to other documentation
    + curiosity, and as a reference to other documentation.
      
     -See link:technical/bundle-format.html[the `bundle-format`
     -documentation] for more details and the discussion of "thin pack" in
    @@ command-list.txt
     +# *.bundle format lives in mn section 5. These entries can only have
     +# the "gitformats" attribute and nothing else.
     +#
    - ### command list (do not change this line, also do not change alignment)
    + ### command list (do not change this line)
      # command name                          category [category] [category]
      git-add                                 mainporcelain           worktree
    -@@ command-list.txt: githooks                                userformats
    - gitignore                               userformats
    - gitmailmap                              userformats
    - gitmodules                              userformats
    +@@ command-list.txt: gitcvs-migration                        guide
    + gitdiffcore                             guide
    + giteveryday                             guide
    + gitfaq                                  guide
     +gitformat-bundle                        gitformats
    - gitnamespaces                           guide
    - gitremote-helpers                       guide
    - gitrepository-layout                    userformats
    + gitglossary                             guide
    + githooks                                userformats
    + gitignore                               userformats
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
-:  ----------- > 3:  5abd59b807f docs: move commit-graph format docs to man section 5
-:  ----------- > 4:  fb91009c18f docs: move protocol-related docs to man section 5
-:  ----------- > 5:  5cb41bb0dcb docs: move {index,signature,bitmap,chunk}-format docs to man section 5
-- 
2.34.1.929.ge922d848c7a