{"thread":{"id":"64210","subject":"[RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","startedAt":"2025-09-26T00:28:08Z","lastAt":"2025-09-27T01:36:39Z","messageCount":6,"participants":["Ramsay Jones","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"527386","messageId":"875fb7a0-6dd9-412b-a34a-21758c339871@ramsayjones.plus.com","threadId":"64210","inReplyTo":null,"subject":"[RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T00:28:05Z","receivedAt":"2025-09-26T00:28:08Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\nSigned-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>\n---\n Documentation/technical/commit-graph.adoc | 34 +++++++++++------------\n 1 file changed, 16 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc\nindex 2c26e95e51..15396f58ab 100644\n--- a/Documentation/technical/commit-graph.adoc\n+++ b/Documentation/technical/commit-graph.adoc\n@@ -1,5 +1,4 @@\n-Git Commit-Graph Design Notes\n-=============================\n+= Git Commit-Graph Design Notes\n \n Git walks the commit graph for many reasons, including:\n \n@@ -39,6 +38,7 @@ A consumer may load the following info for a commit from the graph:\n Values 1-4 satisfy the requirements of parse_commit_gently().\n \n There are two definitions of generation number:\n+\n 1. Corrected committer dates (generation number v2)\n 2. Topological levels (generation number v1)\n \n@@ -122,8 +122,7 @@ can be stored in the commit-graph file using the 30 bits available\n to topological levels. This presents another case where a commit can\n have generation number equal to that of a parent.\n \n-Design Details\n---------------\n+== Design Details\n \n - The commit-graph file is stored in a file named 'commit-graph' in the\n   .git/objects/info directory. This could be stored in the info directory\n@@ -149,8 +148,7 @@ Design Details\n   helpful for these clones, anyway. The commit-graph will not be read or\n   written when shallow commits are present.\n \n-Commit-Graphs Chains\n---------------------\n+== Commit-Graphs Chains\n \n Typically, repos grow with near-constant velocity (commits per day). Over time,\n the number of commits added by a fetch operation is much smaller than the\n@@ -158,7 +156,7 @@ number of commits in the full history. By creating a \"chain\" of commit-graphs,\n we enable fast writes of new commit data without rewriting the entire commit\n history -- at least, most of the time.\n \n-## File Layout\n+=== File Layout\n \n A commit-graph chain uses multiple files, and we use a fixed naming convention\n to organize these files. Each commit-graph file has a name\n@@ -170,11 +168,11 @@ hashes for the files in order from \"lowest\" to \"highest\".\n \n For example, if the `commit-graph-chain` file contains the lines\n \n-```\n+----\n \t{hash0}\n \t{hash1}\n \t{hash2}\n-```\n+----\n \n then the commit-graph chain looks like the following diagram:\n \n@@ -213,7 +211,7 @@ specifying the hashes of all files in the lower layers. In the above example,\n `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains\n `{hash0}` and `{hash1}`.\n \n-## Merging commit-graph files\n+=== Merging commit-graph files\n \n If we only added a new commit-graph file on every write, we would run into a\n linear search problem through many commit-graph files.  Instead, we use a merge\n@@ -257,14 +255,14 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`\n according to the computed `{hash3}`. Finally, we write the new chain data to\n `commit-graph-chain.lock`:\n \n-```\n+----\n \t{hash3}\n \t{hash0}\n-```\n+----\n \n We then close the lock-file.\n \n-## Merge Strategy\n+=== Merge Strategy\n \n When writing a set of commits that do not exist in the commit-graph stack of\n height N, we default to creating a new file at level N + 1. We then decide to\n@@ -289,7 +287,7 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum\n number of commits) could be extracted into config settings for full\n flexibility.\n \n-## Handling Mixed Generation Number Chains\n+=== Handling Mixed Generation Number Chains\n \n With the introduction of generation number v2 and generation data chunk, the\n following scenario is possible:\n@@ -318,7 +316,7 @@ have corrected commit dates when written by compatible versions of Git. Thus,\n rewriting split commit-graph as a single file (`--split=replace`) creates a\n single layer with corrected commit dates.\n \n-## Deleting graph-{hash} files\n+=== Deleting graph-\\{hash\\} files\n \n After a new tip file is written, some `graph-{hash}` files may no longer\n be part of a chain. It is important to remove these files from disk, eventually.\n@@ -333,7 +331,7 @@ files whose modified times are older than a given expiry window. This window\n defaults to zero, but can be changed using command-line arguments or a config\n setting.\n \n-## Chains across multiple object directories\n+=== Chains across multiple object directories\n \n In a repo with alternates, we look for the `commit-graph-chain` file starting\n in the local object directory and then in each alternate. The first file that\n@@ -369,8 +367,8 @@ their custom environment:\n     access to the new chain until its chain is updated to reference those files.\n     (This may change in the future [5].)\n \n-Related Links\n--------------\n+== Related Links\n+\n [0] https://bugs.chromium.org/p/git/issues/detail?id=8\n     Chromium work item for: Serialized Commit Graph\n \n-- \n2.51.0\n"},{"id":"527430","messageId":"xmqqfrc9citl.fsf@gitster.g","threadId":"64210","inReplyTo":"875fb7a0-6dd9-412b-a34a-21758c339871@ramsayjones.plus.com","subject":"Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-26T15:52:22Z","receivedAt":"2025-09-26T15:52:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n\n> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>\n> ---\n>  Documentation/technical/commit-graph.adoc | 34 +++++++++++------------\n>  1 file changed, 16 insertions(+), 18 deletions(-)\n\nAre these the issues?\n\n - Use ={n} prefixes instead of underlines for the section headers.\n\n - Use ={n} not #{n} prefixes for the section headers.\n\n - A blank line between a leading text before a numbered list.\n\n - Mark-up of displayed materials.\n\nThe majority of our pages (I think all of the manual pages) use\nunderlines.  Are we getting warnings on them that we'd need to\nchange?  I personally find the underlined style easier to read\nin the source text (even though I understand why people would\nprefer to use the ={n} prefix style---having to adjust the length\nof the underline is a bit more work when retitling).\n\nThe remainder of this message does not have any comment from me,\nbut is left as a reference for others.\n\n> diff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc\n> index 2c26e95e51..15396f58ab 100644\n> --- a/Documentation/technical/commit-graph.adoc\n> +++ b/Documentation/technical/commit-graph.adoc\n> @@ -1,5 +1,4 @@\n> -Git Commit-Graph Design Notes\n> -=============================\n> += Git Commit-Graph Design Notes\n>  \n>  Git walks the commit graph for many reasons, including:\n>  \n> @@ -39,6 +38,7 @@ A consumer may load the following info for a commit from the graph:\n>  Values 1-4 satisfy the requirements of parse_commit_gently().\n>  \n>  There are two definitions of generation number:\n> +\n>  1. Corrected committer dates (generation number v2)\n>  2. Topological levels (generation number v1)\n>  \n> @@ -122,8 +122,7 @@ can be stored in the commit-graph file using the 30 bits available\n>  to topological levels. This presents another case where a commit can\n>  have generation number equal to that of a parent.\n>  \n> -Design Details\n> ---------------\n> +== Design Details\n>  \n>  - The commit-graph file is stored in a file named 'commit-graph' in the\n>    .git/objects/info directory. This could be stored in the info directory\n> @@ -149,8 +148,7 @@ Design Details\n>    helpful for these clones, anyway. The commit-graph will not be read or\n>    written when shallow commits are present.\n>  \n> -Commit-Graphs Chains\n> ---------------------\n> +== Commit-Graphs Chains\n>  \n>  Typically, repos grow with near-constant velocity (commits per day). Over time,\n>  the number of commits added by a fetch operation is much smaller than the\n> @@ -158,7 +156,7 @@ number of commits in the full history. By creating a \"chain\" of commit-graphs,\n>  we enable fast writes of new commit data without rewriting the entire commit\n>  history -- at least, most of the time.\n>  \n> -## File Layout\n> +=== File Layout\n>  \n>  A commit-graph chain uses multiple files, and we use a fixed naming convention\n>  to organize these files. Each commit-graph file has a name\n> @@ -170,11 +168,11 @@ hashes for the files in order from \"lowest\" to \"highest\".\n>  \n>  For example, if the `commit-graph-chain` file contains the lines\n>  \n> -```\n> +----\n>  \t{hash0}\n>  \t{hash1}\n>  \t{hash2}\n> -```\n> +----\n>  \n>  then the commit-graph chain looks like the following diagram:\n>  \n> @@ -213,7 +211,7 @@ specifying the hashes of all files in the lower layers. In the above example,\n>  `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains\n>  `{hash0}` and `{hash1}`.\n>  \n> -## Merging commit-graph files\n> +=== Merging commit-graph files\n>  \n>  If we only added a new commit-graph file on every write, we would run into a\n>  linear search problem through many commit-graph files.  Instead, we use a merge\n> @@ -257,14 +255,14 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`\n>  according to the computed `{hash3}`. Finally, we write the new chain data to\n>  `commit-graph-chain.lock`:\n>  \n> -```\n> +----\n>  \t{hash3}\n>  \t{hash0}\n> -```\n> +----\n>  \n>  We then close the lock-file.\n>  \n> -## Merge Strategy\n> +=== Merge Strategy\n>  \n>  When writing a set of commits that do not exist in the commit-graph stack of\n>  height N, we default to creating a new file at level N + 1. We then decide to\n> @@ -289,7 +287,7 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum\n>  number of commits) could be extracted into config settings for full\n>  flexibility.\n>  \n> -## Handling Mixed Generation Number Chains\n> +=== Handling Mixed Generation Number Chains\n>  \n>  With the introduction of generation number v2 and generation data chunk, the\n>  following scenario is possible:\n> @@ -318,7 +316,7 @@ have corrected commit dates when written by compatible versions of Git. Thus,\n>  rewriting split commit-graph as a single file (`--split=replace`) creates a\n>  single layer with corrected commit dates.\n>  \n> -## Deleting graph-{hash} files\n> +=== Deleting graph-\\{hash\\} files\n>  \n>  After a new tip file is written, some `graph-{hash}` files may no longer\n>  be part of a chain. It is important to remove these files from disk, eventually.\n> @@ -333,7 +331,7 @@ files whose modified times are older than a given expiry window. This window\n>  defaults to zero, but can be changed using command-line arguments or a config\n>  setting.\n>  \n> -## Chains across multiple object directories\n> +=== Chains across multiple object directories\n>  \n>  In a repo with alternates, we look for the `commit-graph-chain` file starting\n>  in the local object directory and then in each alternate. The first file that\n> @@ -369,8 +367,8 @@ their custom environment:\n>      access to the new chain until its chain is updated to reference those files.\n>      (This may change in the future [5].)\n>  \n> -Related Links\n> --------------\n> +== Related Links\n> +\n>  [0] https://bugs.chromium.org/p/git/issues/detail?id=8\n>      Chromium work item for: Serialized Commit Graph\n"},{"id":"527440","messageId":"c8e40336-0a16-4da9-b251-d166f80ffeb3@ramsayjones.plus.com","threadId":"64210","inReplyTo":"xmqqfrc9citl.fsf@gitster.g","subject":"Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T18:11:57Z","receivedAt":"2025-09-26T18:12:08Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 26/09/2025 4:52 pm, Junio C Hamano wrote:\n> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n> \n>> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>\n>> ---\n>>  Documentation/technical/commit-graph.adoc | 34 +++++++++++------------\n>>  1 file changed, 16 insertions(+), 18 deletions(-)\n> \n> Are these the issues?\n> \n>  - Use ={n} prefixes instead of underlines for the section headers.\n> \n>  - Use ={n} not #{n} prefixes for the section headers.\n> \n>  - A blank line between a leading text before a numbered list.\n> \n>  - Mark-up of displayed materials.\n> \n> The majority of our pages (I think all of the manual pages) use\n> underlines.  Are we getting warnings on them that we'd need to\n> change?  I personally find the underlined style easier to read\n> in the source text (even though I understand why people would\n> prefer to use the ={n} prefix style---having to adjust the length\n> of the underline is a bit more work when retitling).\n\nHeh, my first attempt used an '+' character for the underlining of the\n'next' level headers, rather than '## ', since that was what I thought\nit was (from a very vague memory), but asciidoc disagreed! ;)\n\nI tried searching the web for the answer, without success, so went with\nthe 'prefix' style used here. However, when I read the above, it made me\nlook at out current docs and gitworkflows.adoc showed me I should have\nused an '~' character instead.\n\nI just tried this and it works great (apart from having to \\-quote the\n'{' and '}' characters in one title), so a revised 'diff' is given below.\n\n[all the other problems remain, of course]\n\nWould you prefer this 'patch'?\n\nATB,\nRamsay Jones\n\n--- >8 ---\ndiff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc\nindex 2c26e95e51..f5522ba437 100644\n--- a/Documentation/technical/commit-graph.adoc\n+++ b/Documentation/technical/commit-graph.adoc\n@@ -39,6 +39,7 @@ A consumer may load the following info for a commit from the graph:\n Values 1-4 satisfy the requirements of parse_commit_gently().\n \n There are two definitions of generation number:\n+\n 1. Corrected committer dates (generation number v2)\n 2. Topological levels (generation number v1)\n \n@@ -158,7 +159,8 @@ number of commits in the full history. By creating a \"chain\" of commit-graphs,\n we enable fast writes of new commit data without rewriting the entire commit\n history -- at least, most of the time.\n \n-## File Layout\n+File Layout\n+~~~~~~~~~~~\n \n A commit-graph chain uses multiple files, and we use a fixed naming convention\n to organize these files. Each commit-graph file has a name\n@@ -170,11 +172,11 @@ hashes for the files in order from \"lowest\" to \"highest\".\n \n For example, if the `commit-graph-chain` file contains the lines\n \n-```\n+----\n \t{hash0}\n \t{hash1}\n \t{hash2}\n-```\n+----\n \n then the commit-graph chain looks like the following diagram:\n \n@@ -213,7 +215,8 @@ specifying the hashes of all files in the lower layers. In the above example,\n `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains\n `{hash0}` and `{hash1}`.\n \n-## Merging commit-graph files\n+Merging commit-graph files\n+~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n If we only added a new commit-graph file on every write, we would run into a\n linear search problem through many commit-graph files.  Instead, we use a merge\n@@ -257,14 +260,15 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`\n according to the computed `{hash3}`. Finally, we write the new chain data to\n `commit-graph-chain.lock`:\n \n-```\n+----\n \t{hash3}\n \t{hash0}\n-```\n+----\n \n We then close the lock-file.\n \n-## Merge Strategy\n+Merge Strategy\n+~~~~~~~~~~~~~~\n \n When writing a set of commits that do not exist in the commit-graph stack of\n height N, we default to creating a new file at level N + 1. We then decide to\n@@ -289,7 +293,8 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum\n number of commits) could be extracted into config settings for full\n flexibility.\n \n-## Handling Mixed Generation Number Chains\n+Handling Mixed Generation Number Chains\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n With the introduction of generation number v2 and generation data chunk, the\n following scenario is possible:\n@@ -318,7 +323,8 @@ have corrected commit dates when written by compatible versions of Git. Thus,\n rewriting split commit-graph as a single file (`--split=replace`) creates a\n single layer with corrected commit dates.\n \n-## Deleting graph-{hash} files\n+Deleting graph-\\{hash\\} files\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n After a new tip file is written, some `graph-{hash}` files may no longer\n be part of a chain. It is important to remove these files from disk, eventually.\n@@ -333,7 +339,8 @@ files whose modified times are older than a given expiry window. This window\n defaults to zero, but can be changed using command-line arguments or a config\n setting.\n \n-## Chains across multiple object directories\n+Chains across multiple object directories\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n In a repo with alternates, we look for the `commit-graph-chain` file starting\n in the local object directory and then in each alternate. The first file that\n"},{"id":"527447","messageId":"xmqqwm5kap0r.fsf@gitster.g","threadId":"64210","inReplyTo":"c8e40336-0a16-4da9-b251-d166f80ffeb3@ramsayjones.plus.com","subject":"Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-26T21:21:24Z","receivedAt":"2025-09-26T21:21:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n\n> I tried searching the web for the answer, without success, so went with\n> the 'prefix' style used here. However, when I read the above, it made me\n> look at out current docs and gitworkflows.adoc showed me I should have\n> used an '~' character instead.\n>\n> I just tried this and it works great (apart from having to \\-quote the\n> '{' and '}' characters in one title), so a revised 'diff' is given below.\n\nOy.  It is one of the special things I am unsure about---would a\ncharacter used for such quoting (e.g., backslash in this case) count\nas one display space to count the number of underlying characters?\n\nThat is, which one of these do AsciiDoc and Asciidoctor want?\n\n    Deleting graph-\\{hash\\} files\n    ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n    Deleting graph-\\{hash\\} files\n    ~~~~~~~~~~~~~~~~~~~~~~~~~~~--\n\nThere is\n\n    OPTIONS[[OPTIONS]]\n    ------------------\n\nthat appears in MyFirstContribution.adoc (even though that is an\nillustration of what you would write in the source and never used),\nand\n\n    `builtin_objectmode`\n    ~~~~~~~~~~~~~~~~~~~~\n\nthat appears in gitattributes.adoc (this one is rendered), so I've\nbeen assuming that these characters necessary for mark-up do count.\n\nI guess this is the same \"prefix is easier to write, underling is\nharder to write correctly\" theme?  If we know which one is correct\nand can use the correct version, then I do prefer the underlined\nform.\n\nThanks.\n\n"},{"id":"527467","messageId":"3323ebff-f6ac-4065-8507-efd5a9e4a16d@ramsayjones.plus.com","threadId":"64210","inReplyTo":"xmqqwm5kap0r.fsf@gitster.g","subject":"Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T23:30:31Z","receivedAt":"2025-09-26T23:30:43Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 26/09/2025 10:21 pm, Junio C Hamano wrote:\n> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n> \n>> I tried searching the web for the answer, without success, so went with\n>> the 'prefix' style used here. However, when I read the above, it made me\n>> look at out current docs and gitworkflows.adoc showed me I should have\n>> used an '~' character instead.\n>>\n>> I just tried this and it works great (apart from having to \\-quote the\n>> '{' and '}' characters in one title), so a revised 'diff' is given below.\n> \n> Oy.  It is one of the special things I am unsure about---would a\n> character used for such quoting (e.g., backslash in this case) count\n> as one display space to count the number of underlying characters?\n> \n> That is, which one of these do AsciiDoc and Asciidoctor want?\n> \n>     Deleting graph-\\{hash\\} files\n>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis is what I did and, with asciidoc anyway, looked fine.\n\n>     Deleting graph-\\{hash\\} files\n>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nI just tried this, and it was fine also! :)\n\nHmm, let me just try asciidoctor ...\n\nWell, with asciidoctor it requires the underlining to be exactly\nthe same size as the text (ie the second example above), otherwise\nit mangles the heading (well it doesn't seem to recognize it as a\nheading at all. It looks like:\n\nDeleting graph-{hash} files ~~~~~~~~~\n\nSo, not the first time asciidoc and asciidoctor differ in the rendered\noutput. (yes, the number of ~ chars is not the same as the input).\n\nSo, I need to change the diff to extend the underlining on that\nheading, so both asciidoc and asciidoctor both render it correctly.\n\nBTW, the asciidoc version of this document has a date which appears after\nthe initial heading (but it is the day before the 'last date updated' one\nat the end of the document) and I have no idea why it is there!\n\n(To be clear, it does not appear in the asciidoctor rendering!)\n\nATB,\nRamsay Jones\n\n\n"},{"id":"527472","messageId":"xmqqa52gad7f.fsf@gitster.g","threadId":"64210","inReplyTo":"3323ebff-f6ac-4065-8507-efd5a9e4a16d@ramsayjones.plus.com","subject":"Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-27T01:36:36Z","receivedAt":"2025-09-27T01:36:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n\n>> That is, which one of these do AsciiDoc and Asciidoctor want?\n>> \n>>     Deleting graph-\\{hash\\} files\n>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>\n> This is what I did and, with asciidoc anyway, looked fine.\n>\n>>     Deleting graph-\\{hash\\} files\n>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>\n> I just tried this, and it was fine also! :)\n>\n> Hmm, let me just try asciidoctor ...\n>\n> Well, with asciidoctor it requires the underlining to be exactly\n> the same size as the text (ie the second example above), otherwise\n> it mangles the heading (well it doesn't seem to recognize it as a\n> heading at all. It looks like:\n>\n> Deleting graph-{hash} files ~~~~~~~~~\n>\n> So, not the first time asciidoc and asciidoctor differ in the rendered\n> output. (yes, the number of ~ chars is not the same as the input).\n\nYeah, so the latter one (i.e. count escapes and mark-up letters when\ncomputing how long your underline need to be) is required to please\nboth.  I knew AsciiDoc allowed a bit of slop and that is how your\nexperiment (the first one above) was fine.  I didn't know how large\na slop AsciiDoc allowed, but it seems at least we can be missing two\nand the tool is still happy.\n\n> So, I need to change the diff to extend the underlining on that\n> heading, so both asciidoc and asciidoctor both render it correctly.\n\nSo it seems.\n\nThanks.\n"}]}