Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5

["SZEDER Gábor" <szeder.dev@gmail.com>]

On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
> Continue the move of existing Documentation/technical/* protocol and
> file-format documentation into our main documentation space.
> 
> By moving the documentation for the commit-graph format into man
> section 5 and the new "developerinterfaces" category. This change is
> split from subsequent commits due to the relatively large amount of
> ASCIIDOC formatting changes that are required.

So after this series I got a couple of gitformat-* manpages, but,
alas, most of them render improperly: a lot of paragraphs are for some
reason fixed width even in a fullscreen terminal window, and their
width is more than 80 chars, so they are rather awkward in a
standard-width terminal.  This also affects the html version, where
those paragraphs are rendered with a fixed-width font.

> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/Makefile                        |  1 +
>  Documentation/git-commit-graph.txt            |  5 ++
>  ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------
>  Documentation/technical/chunk-format.txt      |  4 +-
>  command-list.txt                              |  1 +
>  5 files changed, 41 insertions(+), 17 deletions(-)
>  rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 1a4a545f44a..e7bd72bb84e 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt
>  # man5 / man7 guides (note: new guides should also be added to command-list.txt)
>  MAN5_TXT += gitattributes.txt
>  MAN5_TXT += gitformat-bundle.txt
> +MAN5_TXT += gitformat-commit-graph.txt
>  MAN5_TXT += githooks.txt
>  MAN5_TXT += gitignore.txt
>  MAN5_TXT += gitmailmap.txt
> diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
> index e1f48c95b3c..047decdb65b 100644
> --- a/Documentation/git-commit-graph.txt
> +++ b/Documentation/git-commit-graph.txt
> @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
>  ------------------------------------------------
>  
>  
> +FILE FORMAT
> +-----------
> +
> +see linkgit:gitformat-commit-graph[5].
> +
>  GIT
>  ---
>  Part of the linkgit:git[1] suite
> diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt
> similarity index 88%
> rename from Documentation/technical/commit-graph-format.txt
> rename to Documentation/gitformat-commit-graph.txt
> index 484b185ba98..108dc2295c0 100644
> --- a/Documentation/technical/commit-graph-format.txt
> +++ b/Documentation/gitformat-commit-graph.txt
> @@ -1,5 +1,18 @@
> -Git commit graph format
> -=======================
> +gitformat-commit-graph(5)
> +=========================
> +
> +NAME
> +----
> +gitformat-commit-graph - Git commit graph format
> +
> +SYNOPSIS
> +--------
> +[verse]
> +$GIT_DIR/objects/info/commit-graph
> +$GIT_DIR/objects/info/commit-graphs/*
> +
> +DESCRIPTION
> +-----------
>  
>  The Git commit graph stores a list of commit OIDs and some associated
>  metadata, including:
> @@ -30,7 +43,7 @@ and hash type.
>  
>  All multi-byte numbers are in network byte order.
>  
> -HEADER:
> +=== HEADER:
>  
>    4-byte signature:
>        The signature is: {'C', 'G', 'P', 'H'}
> @@ -52,7 +65,7 @@ HEADER:
>        We infer the length (H*B) of the Base Graphs chunk
>        from this value.
>  
> -CHUNK LOOKUP:
> +=== CHUNK LOOKUP:
>  
>    (C + 1) * 12 bytes listing the table of contents for the chunks:
>        First 4 bytes describe the chunk id. Value 0 is a terminating label.
> @@ -68,17 +81,17 @@ CHUNK LOOKUP:
>    these chunks may be given in any order. Chunks are required unless
>    otherwise specified.
>  
> -CHUNK DATA:
> +=== CHUNK DATA:
>  
> -  OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
> +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
>        The ith entry, F[i], stores the number of OIDs with first
>        byte at most i. Thus F[255] stores the total
>        number of commits (N).
>  
> -  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
> +====  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
>        The OIDs for all commits in the graph, sorted in ascending order.
>  
> -  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
> +====  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
>      * The first H bytes are for the OID of the root tree.
>      * The next 8 bytes are for the positions of the first two parents
>        of the ith commit. Stores value 0x70000000 if no parent in that
> @@ -93,7 +106,7 @@ CHUNK DATA:
>        2 bits of the lowest byte, storing the 33rd and 34th bit of the
>        commit time.
>  
> -  Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
> +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
>      * This list of 4-byte values store corrected commit date offsets for the
>        commits, arranged in the same order as commit data chunk.
>      * If the corrected commit date offset cannot be stored within 31 bits,
> @@ -104,7 +117,7 @@ CHUNK DATA:
>        by compatible versions of Git and in case of split commit-graph chains,
>        the topmost layer also has Generation Data chunk.
>  
> -  Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
> +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
>      * This list of 8-byte values stores the corrected commit date offsets
>        for commits with corrected commit date offsets that cannot be
>        stored within 31 bits.
> @@ -112,7 +125,7 @@ CHUNK DATA:
>        chunk is present and atleast one corrected commit date offset cannot
>        be stored within 31 bits.
>  
> -  Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
> +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
>        This list of 4-byte values store the second through nth parents for
>        all octopus merges. The second parent value in the commit data stores
>        an array position within this list along with the most-significant bit
> @@ -120,14 +133,14 @@ CHUNK DATA:
>        positions for the parents until reaching a value with the most-significant
>        bit on. The other bits correspond to the position of the last parent.
>  
> -  Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
> +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
>      * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters
>        from commit 0 to commit i (inclusive) in lexicographic order. The Bloom
>        filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header
>        length), where BIDX[-1] is 0.
>      * The BIDX chunk is ignored if the BDAT chunk is not present.
>  
> -  Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
> +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
>      * It starts with header consisting of three unsigned 32-bit integers:
>        - Version of the hash algorithm being used. We currently only support
>  	value 1 which corresponds to the 32-bit version of the murmur3 hash
> @@ -147,13 +160,13 @@ CHUNK DATA:
>        of length one, with either all bits set to zero or one respectively.
>      * The BDAT chunk is present if and only if BIDX is present.
>  
> -  Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
> +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
>        This list of H-byte hashes describe a set of B commit-graph files that
>        form a commit-graph chain. The graph position for the ith commit in this
>        file's OID Lookup chunk is equal to i plus the number of commits in all
>        base graphs.  If B is non-zero, this chunk must exist.
>  
> -TRAILER:
> +=== TRAILER:
>  
>  	H-byte HASH-checksum of all of the above.
>  
> @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote
>  possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By
>  changing the IDs, newer versions of Git will silently ignore those older
>  chunks and write the new information without trusting the incorrect data.
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite
> diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt
> index 593614fceda..f36ce42f37c 100644
> --- a/Documentation/technical/chunk-format.txt
> +++ b/Documentation/technical/chunk-format.txt
> @@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by
>  scanning a small "table of contents" for the remaining data. This common
>  format is used by the `commit-graph` and `multi-pack-index` files. See
>  link:technical/pack-format.html[the `multi-pack-index` format] and
> -link:technical/commit-graph-format.html[the `commit-graph` format] for
> +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
>  how they use the chunks to describe structured data.
>  
>  A chunk-based file format begins with some header information custom to
> @@ -108,7 +108,7 @@ for future formats:
>  * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`
>    in `commit-graph.c` for how the chunk-format API is used to write and
>    parse the commit-graph file format documented in
> -  link:technical/commit-graph-format.html[the commit-graph file format].
> +  the commit-graph file format in linkgit:gitformat-commit-graph[5].
>  
>  * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
>    in `midx.c` for how the chunk-format API is used to write and
> diff --git a/command-list.txt b/command-list.txt
> index 1950c4ccd9c..3afcfcd35f0 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -210,6 +210,7 @@ gitdiffcore                             guide
>  giteveryday                             guide
>  gitfaq                                  guide
>  gitformat-bundle                        developerinterfaces
> +gitformat-commit-graph                  developerinterfaces
>  gitglossary                             guide
>  githooks                                userinterfaces
>  gitignore                               userinterfaces
> -- 
> 2.37.1.1233.g61622908797
>