Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

From: Ramsay Jones <ramsay@ramsayjones.plus.com>
Date: Sep 26, 2025, 18:11 UTC
Message-ID: <c8e40336-0a16-4da9-b251-d166f80ffeb3@ramsayjones.plus.com>
In-Reply-To: <xmqqfrc9citl.fsf@gitster.g>

On 26/09/2025 4:52 pm, Junio C Hamano wrote:

Show 23 quoted lines

> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
>> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
>> ---
>>  Documentation/technical/commit-graph.adoc | 34 +++++++++++------------
>>  1 file changed, 16 insertions(+), 18 deletions(-)
> 
> Are these the issues?
> 
>  - Use ={n} prefixes instead of underlines for the section headers.
> 
>  - Use ={n} not #{n} prefixes for the section headers.
> 
>  - A blank line between a leading text before a numbered list.
> 
>  - Mark-up of displayed materials.
> 
> The majority of our pages (I think all of the manual pages) use
> underlines.  Are we getting warnings on them that we'd need to
> change?  I personally find the underlined style easier to read
> in the source text (even though I understand why people would
> prefer to use the ={n} prefix style---having to adjust the length
> of the underline is a bit more work when retitling).

Heh, my first attempt used an '+' character for the underlining of the 'next' level headers, rather than '## ', since that was what I thought it was (from a very vague memory), but asciidoc disagreed! ;)

I tried searching the web for the answer, without success, so went with the 'prefix' style used here. However, when I read the above, it made me look at out current docs and gitworkflows.adoc showed me I should have used an '~' character instead.

I just tried this and it works great (apart from having to \-quote the '{' and '}' characters in one title), so a revised 'diff' is given below.

[all the other problems remain, of course]

Would you prefer this 'patch'?

ATB, Ramsay Jones

--- >8 ---

diff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc
index 2c26e95e51..f5522ba437 100644
--- a/Documentation/technical/commit-graph.adoc
+++ b/Documentation/technical/commit-graph.adoc
@@ -39,6 +39,7 @@ A consumer may load the following info for a commit from the graph:
 Values 1-4 satisfy the requirements of parse_commit_gently().
 
 There are two definitions of generation number:
+
 1. Corrected committer dates (generation number v2)
 2. Topological levels (generation number v1)
 
@@ -158,7 +159,8 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
 we enable fast writes of new commit data without rewriting the entire commit
 history -- at least, most of the time.
 
-## File Layout
+File Layout
+~~~~~~~~~~~
 
 A commit-graph chain uses multiple files, and we use a fixed naming convention
 to organize these files. Each commit-graph file has a name
@@ -170,11 +172,11 @@ hashes for the files in order from "lowest" to "highest".
 
 For example, if the `commit-graph-chain` file contains the lines
 
-```
+----
 	{hash0}
 	{hash1}
 	{hash2}
-```
+----
 
 then the commit-graph chain looks like the following diagram:
 
@@ -213,7 +215,8 @@ specifying the hashes of all files in the lower layers. In the above example,
 `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
 `{hash0}` and `{hash1}`.
 
-## Merging commit-graph files
+Merging commit-graph files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If we only added a new commit-graph file on every write, we would run into a
 linear search problem through many commit-graph files.  Instead, we use a merge
@@ -257,14 +260,15 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`
 according to the computed `{hash3}`. Finally, we write the new chain data to
 `commit-graph-chain.lock`:
 
-```
+----
 	{hash3}
 	{hash0}
-```
+----
 
 We then close the lock-file.
 
-## Merge Strategy
+Merge Strategy
+~~~~~~~~~~~~~~
 
 When writing a set of commits that do not exist in the commit-graph stack of
 height N, we default to creating a new file at level N + 1. We then decide to
@@ -289,7 +293,8 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
 number of commits) could be extracted into config settings for full
 flexibility.
 
-## Handling Mixed Generation Number Chains
+Handling Mixed Generation Number Chains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 With the introduction of generation number v2 and generation data chunk, the
 following scenario is possible:
@@ -318,7 +323,8 @@ have corrected commit dates when written by compatible versions of Git. Thus,
 rewriting split commit-graph as a single file (`--split=replace`) creates a
 single layer with corrected commit dates.
 
-## Deleting graph-{hash} files
+Deleting graph-\{hash\} files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After a new tip file is written, some `graph-{hash}` files may no longer
 be part of a chain. It is important to remove these files from disk, eventually.
@@ -333,7 +339,8 @@ files whose modified times are older than a given expiry window. This window
 defaults to zero, but can be changed using command-line arguments or a config
 setting.
 
-## Chains across multiple object directories
+Chains across multiple object directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a repo with alternates, we look for the `commit-graph-chain` file starting
 in the local object directory and then in each alternate. The first file that