{"thread":{"id":"63082","subject":"[PATCH] doc: add a blank line around block delimiters","startedAt":"2025-03-09T19:45:15Z","lastAt":"2025-03-10T16:19:18Z","messageCount":3,"participants":["Jean-Noël Avila via GitGitGadget","brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"513852","messageId":"pull.1878.git.1741549511665.gitgitgadget@gmail.com","threadId":"63082","inReplyTo":null,"subject":"[PATCH] doc: add a blank line around block delimiters","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-09T19:45:11Z","receivedAt":"2025-03-09T19:45:15Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nThe documentation is using the historical mode for titles, which is a\nsetext-style (i.e., two-line) section title.\n\nThe issue with this mode is that starting block delimiters (e.g.,\n`----`) can be confused with a section title when they are exactly the\nsame length as the preceding line. In the original documentation, this\nis taken care of for English by the writer, but it is not the case for\ntranslations where these delimiters are hidden. A translator can\ngenerate a line that is exactly the same length as the following block\ndelimiter, which leads to this line being considered as a title.\n\nTo safeguard against this issue, add a blank line before and after\nblock delimiters where block is at root level, else add a \"+\" line\nbefore block delimiters to link it to the preceding paragraph.\n\nSigned-off-by: Jean-Noël Avila \n---\n doc: add a blank line around block delimiters\n \n This patch is basically a mass-replace of occurrences of paragraphs\n followed by a block delimiter.\n \n The issue arose with a Chinese translation where the length of the\n paragraph turned out to be smaller than the original English and to just\n fit the number of hyphens of the following block starter.\n \n An a longer term, I'm wondering how converting all the asciidoc files to\n the modern style (i.e. atx-style, with variable \"=\" characters in front\n of the line) would be perceived by the community.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1878%2Fjnavila%2Ffix_empty_line_before_block-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1878/jnavila/fix_empty_line_before_block-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1878\n\n Documentation/MyFirstContribution.adoc | 1 +\n Documentation/MyFirstObjectWalk.adoc | 2 ++\n Documentation/ToolsForGit.adoc | 1 +\n Documentation/git-bisect.adoc | 1 +\n Documentation/git-cat-file.adoc | 4 ++--\n Documentation/git-check-attr.adoc | 6 ++++++\n Documentation/git-column.adoc | 3 +++\n Documentation/git-cvsserver.adoc | 4 ++++\n Documentation/git-for-each-ref.adoc | 2 ++\n Documentation/git-p4.adoc | 14 ++++++++++++++\n Documentation/git-rebase.adoc | 3 +++\n Documentation/gitattributes.adoc | 24 ++++++++++++++++--------\n Documentation/gitcli.adoc | 2 +-\n Documentation/gitprotocol-common.adoc | 2 ++\n Documentation/gitweb.adoc | 11 +++++++++++\n Documentation/gitweb.conf.adoc | 2 ++\n Documentation/rev-list-options.adoc | 2 ++\n 17 files changed, 73 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex e41654c00a6..71dd8557192 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -367,6 +367,7 @@ But as we drill down, we can find that `status_init_config()` wraps a call\n to `git_config()`. Let's modify the code we wrote in the previous commit.\n \n Be sure to include the header to allow you to use `struct wt_status`:\n+\n ----\n #include \"wt-status.h\"\n ----\ndiff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc\nindex dec8afe5b10..e165d34d208 100644\n--- a/Documentation/MyFirstObjectWalk.adoc\n+++ b/Documentation/MyFirstObjectWalk.adoc\n@@ -287,6 +287,7 @@ static void final_rev_info_setup(struct rev_info *rev)\n ====\n Instead of using the shorthand `add_head_to_pending()`, you could do\n something like this:\n+\n ----\n \tstruct setup_revision_opt opt;\n \n@@ -295,6 +296,7 @@ something like this:\n \topt.revarg_opt = REVARG_COMMITTISH;\n \tsetup_revisions(argc, argv, rev, &opt);\n ----\n+\n Using a `setup_revision_opt` gives you finer control over your walk's starting\n point.\n ====\ndiff --git a/Documentation/ToolsForGit.adoc b/Documentation/ToolsForGit.adoc\nindex ae7690b45d0..a842c133279 100644\n--- a/Documentation/ToolsForGit.adoc\n+++ b/Documentation/ToolsForGit.adoc\n@@ -34,6 +34,7 @@ This is adapted from Linux's suggestion in its CodingStyle document:\n \n - To follow the rules in CodingGuidelines, it's useful to put the following in\n GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n+\n ----\n ;; note the first part is useful for C editing, too\n ((nil . ((indent-tabs-mode . t)\ndiff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\nindex 82f944dc03d..58dbb74a157 100644\n--- a/Documentation/git-bisect.adoc\n+++ b/Documentation/git-bisect.adoc\n@@ -495,6 +495,7 @@ $ git bisect old HEAD~10 # the tenth commit from now is marked as old\n ------------\n +\n or:\n++\n ------------\n $ git bisect start --term-old broken --term-new fixed\n $ git bisect fixed\ndiff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc\nindex d5890ae3686..30359f5dbdb 100644\n--- a/Documentation/git-cat-file.adoc\n+++ b/Documentation/git-cat-file.adoc\n@@ -322,10 +322,10 @@ of `%(objectsize)` bytes), followed by a newline.\n \n For example, `--batch` without a custom format would produce:\n \n-------------\n+-----------\n SP SP LF\n LF\n-------------\n+-----------\n \n Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:\n \ndiff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc\nindex cb5a6c8f335..503b6446574 100644\n--- a/Documentation/git-check-attr.adoc\n+++ b/Documentation/git-check-attr.adoc\n@@ -76,6 +76,7 @@ EXAMPLES\n --------\n \n In the examples, the following '.gitattributes' file is used:\n+\n ---------------\n *.java diff=java -crlf myAttr\n NoMyAttr.java !myAttr\n@@ -83,12 +84,14 @@ README caveat=unspecified\n ---------------\n \n * Listing a single attribute:\n++\n ---------------\n $ git check-attr diff org/example/MyClass.java\n org/example/MyClass.java: diff: java\n ---------------\n \n * Listing multiple attributes for a file:\n++\n ---------------\n $ git check-attr crlf diff myAttr -- org/example/MyClass.java\n org/example/MyClass.java: crlf: unset\n@@ -97,6 +100,7 @@ org/example/MyClass.java: myAttr: set\n ---------------\n \n * Listing all attributes for a file:\n++\n ---------------\n $ git check-attr --all -- org/example/MyClass.java\n org/example/MyClass.java: diff: java\n@@ -104,6 +108,7 @@ org/example/MyClass.java: myAttr: set\n ---------------\n \n * Listing an attribute for multiple files:\n++\n ---------------\n $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java\n org/example/MyClass.java: myAttr: set\n@@ -111,6 +116,7 @@ org/example/NoMyAttr.java: myAttr: unspecified\n ---------------\n \n * Not all values are equally unambiguous:\n++\n ---------------\n $ git check-attr caveat README\n README: caveat: unspecified\ndiff --git a/Documentation/git-column.adoc b/Documentation/git-column.adoc\nindex 85fb87c94a4..5a4f2b6fde9 100644\n--- a/Documentation/git-column.adoc\n+++ b/Documentation/git-column.adoc\n@@ -50,6 +50,7 @@ EXAMPLES\n --------\n \n Format data by columns:\n++\n ------------\n $ seq 1 24 | git column --mode=column --padding=5\n 1 4 7 10 13 16 19 22\n@@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5\n ------------\n \n Format data by rows:\n++\n ------------\n $ seq 1 21 | git column --mode=row --padding=5\n 1 2 3 4 5 6 7\n@@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5\n ------------\n \n List some tags in a table with unequal column widths:\n++\n ------------\n $ git tag --list 'v2.4.*' --column=row,dense\n v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3\ndiff --git a/Documentation/git-cvsserver.adoc b/Documentation/git-cvsserver.adoc\nindex 4c475efeab9..fe822f571d0 100644\n--- a/Documentation/git-cvsserver.adoc\n+++ b/Documentation/git-cvsserver.adoc\n@@ -125,9 +125,11 @@ creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or\n pwhash in NetBSD) and paste it in the right location.\n \n Then provide your password via the pserver method, for example:\n+\n ------\n cvs -d:pserver:someuser:somepassword@server:/path/repo.git co \n ------\n+\n No special setup is needed for SSH access, other than having Git tools\n in the PATH. If you have clients that do not accept the CVS_SERVER\n environment variable, you can rename 'git-cvsserver' to `cvs`.\n@@ -138,6 +140,7 @@ CVS_SERVER directly in CVSROOT like\n ------\n cvs -d \":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git\" co \n ------\n+\n This has the advantage that it will be saved in your 'CVS/Root' files and\n you don't need to worry about always setting the correct environment\n variable. SSH users restricted to 'git-shell' don't need to override the default\n@@ -168,6 +171,7 @@ All configuration variables can also be overridden for a specific method of\n access. Valid method names are \"ext\" (for SSH access) and \"pserver\". The\n following example configuration would disable pserver access while still\n allowing access over SSH.\n+\n ------\n [gitcvs]\n enabled=0\ndiff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc\nindex ffb97e62c2d..5ef89fc0fe3 100644\n--- a/Documentation/git-for-each-ref.adoc\n+++ b/Documentation/git-for-each-ref.adoc\n@@ -441,6 +441,7 @@ Ref: %(*refname)\n \n A simple example showing the use of shell eval on the output,\n demonstrating the use of --shell. List the prefixes of all heads:\n+\n ------------\n #!/bin/sh\n \n@@ -455,6 +456,7 @@ done\n \n A bit more elaborate report on tags, demonstrating that the format\n may be an entire script:\n+\n ------------\n #!/bin/sh\n \ndiff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc\nindex de5ee6748e3..f97b786bf98 100644\n--- a/Documentation/git-p4.adoc\n+++ b/Documentation/git-p4.adoc\n@@ -80,6 +80,7 @@ This:\n \n To reproduce the entire p4 history in Git, use the '@all' modifier on\n the depot path:\n+\n ------------\n $ git p4 clone //depot/path/project@all\n ------------\n@@ -89,19 +90,23 @@ Sync\n ~~~~\n As development continues in the p4 repository, those changes can\n be included in the Git repository using:\n+\n ------------\n $ git p4 sync\n ------------\n+\n This command finds new changes in p4 and imports them as Git commits.\n \n P4 repositories can be added to an existing Git repository using\n 'git p4 sync' too:\n+\n ------------\n $ mkdir repo-git\n $ cd repo-git\n $ git init\n $ git p4 sync //path/in/your/perforce/depot\n ------------\n+\n This imports the specified depot into\n 'refs/remotes/p4/master' in an existing Git repository. The\n `--branch` option can be used to specify a different branch to\n@@ -125,6 +130,7 @@ and merge them with local uncommitted changes. Often, the p4 repository\n is the ultimate location for all code, thus a rebase workflow makes\n sense. This command does 'git p4 sync' followed by 'git rebase' to move\n local commits on top of updated p4 changes.\n+\n ------------\n $ git p4 rebase\n ------------\n@@ -140,16 +146,19 @@ will be created and populated if it does not already exist.\n \n To submit all changes that are in the current Git branch but not in\n the 'p4/master' branch, use:\n+\n ------------\n $ git p4 submit\n ------------\n \n To specify a branch other than the current one, use:\n+\n ------------\n $ git p4 submit topicbranch\n ------------\n \n To specify a single commit or a range of commits, use:\n+\n ------------\n $ git p4 submit --commit \n $ git p4 submit --commit \n@@ -510,20 +519,24 @@ when cloning or syncing to have 'git p4' automatically find\n subdirectories in p4, and to generate these as branches in Git.\n \n For example, if the P4 repository structure is:\n+\n ----\n //depot/main/...\n //depot/branch1/...\n ----\n \n And \"p4 branch -o branch1\" shows a View line that looks like:\n+\n ----\n //depot/main/... //depot/branch1/...\n ----\n \n Then this 'git p4 clone' command:\n+\n ----\n git p4 clone --detect-branches //depot@all\n ----\n+\n produces a separate branch in 'refs/remotes/p4/' for //depot/main,\n called 'master', and one for //depot/branch1 called 'depot/branch1'.\n \n@@ -536,6 +549,7 @@ simple p4 branch specification, where the \"source\" and \"destination\" are\n the path elements in the p4 repository. The example above relied on the\n presence of the p4 branch. Without p4 branches, the same result will\n occur with:\n+\n ----\n git init depot\n cd depot\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex 153cb69a4f8..956d3048f5a 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -1107,10 +1107,12 @@ In that case, the fix is easy because 'git rebase' knows to skip\n changes that are already present in the new upstream (unless\n `--reapply-cherry-picks` is given). So if you say\n (assuming you're on 'topic')\n+\n ------------\n $ git rebase subsystem\n ------------\n you will end up with the fixed history\n+\n ------------\n o---o---o---o---o---o---o---o master\n \t\t\t\t \\\n@@ -1145,6 +1147,7 @@ of the old 'subsystem', for example:\n \n You can then transplant the old `subsystem..topic` to the new tip by\n saying (for the reflog case, and assuming you are on 'topic' already):\n+\n ------------\n $ git rebase --onto subsystem subsystem@{1}\n ------------\ndiff --git a/Documentation/gitattributes.adoc b/Documentation/gitattributes.adoc\nindex 7eaca899725..ba8aa111b12 100644\n--- a/Documentation/gitattributes.adoc\n+++ b/Documentation/gitattributes.adoc\n@@ -531,13 +531,14 @@ must not send any response before it received the content and the\n final flush packet. Also note that the \"value\" of a \"key=value\" pair\n can contain the \"=\" character whereas the key would never contain\n that character.\n-------------------------\n+\n+-----------------------\n packet: git> command=smudge\n packet: git> pathname=path/testfile.dat\n packet: git> 0000\n packet: git> CONTENT\n packet: git> 0000\n-------------------------\n+-----------------------\n \n The filter is expected to respond with a list of \"key=value\" pairs\n terminated with a flush packet. If the filter does not experience\n@@ -559,6 +560,7 @@ packet: git< 0000 # empty list, keep \"status=success\" unchanged!\n \n If the result content is empty then the filter is expected to respond\n with a \"success\" status and a flush packet to signal the empty content.\n+\n ------------------------\n packet: git< status=success\n packet: git< 0000\n@@ -568,14 +570,16 @@ packet: git< 0000 # empty list, keep \"status=success\" unchanged!\n \n In case the filter cannot or does not want to process the content,\n it is expected to respond with an \"error\" status.\n-------------------------\n+\n+-----------------------\n packet: git< status=error\n packet: git< 0000\n-------------------------\n+-----------------------\n \n If the filter experiences an error during processing, then it can\n send the status \"error\" after the content was (partially or\n completely) sent.\n+\n ------------------------\n packet: git< status=success\n packet: git< 0000\n@@ -589,10 +593,11 @@ In case the filter cannot or does not want to process the content\n as well as any future content for the lifetime of the Git process,\n then it is expected to respond with an \"abort\" status at any point\n in the protocol.\n-------------------------\n+\n+-----------------------\n packet: git< status=abort\n packet: git< 0000\n-------------------------\n+-----------------------\n \n Git neither stops nor restarts the filter process in case the\n \"error\"/\"abort\" status is set. However, Git sets its exit code\n@@ -613,7 +618,8 @@ flag \"can-delay\" after the filter command and pathname. This flag\n denotes that the filter can delay filtering the current blob (e.g. to\n compensate network latencies) by responding with no content but with\n the status \"delayed\" and a flush packet.\n-------------------------\n+\n+-----------------------\n packet: git> command=smudge\n packet: git> pathname=path/testfile.dat\n packet: git> can-delay=1\n@@ -622,7 +628,7 @@ packet: git> CONTENT\n packet: git> 0000\n packet: git< status=delayed\n packet: git< 0000\n-------------------------\n+-----------------------\n \n If the filter supports the \"delay\" capability then it must support the\n \"list_available_blobs\" command. If Git sends this command, then the\n@@ -647,10 +653,12 @@ packet: git< status=success\n packet: git< 0000\n ------------------------\n \n+\n After Git received the pathnames, it will request the corresponding\n blobs again. These requests contain a pathname and an empty content\n section. The filter is expected to respond with the smudged content\n in the usual way as explained above.\n+\n ------------------------\n packet: git> command=smudge\n packet: git> pathname=path/testfile.dat\ndiff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc\nindex 04193ec9078..1ea681b59da 100644\n--- a/Documentation/gitcli.adoc\n+++ b/Documentation/gitcli.adoc\n@@ -209,13 +209,13 @@ $ git foo -o Arg\n \n However, this is *NOT* allowed for switches with an optional value, where the\n 'stuck' form must be used:\n+\n ----------------------------\n $ git describe --abbrev HEAD # correct\n $ git describe --abbrev=10 HEAD # correct\n $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT\n ----------------------------\n \n-\n NOTES ON FREQUENTLY CONFUSED OPTIONS\n ------------------------------------\n \ndiff --git a/Documentation/gitprotocol-common.adoc b/Documentation/gitprotocol-common.adoc\nindex cdc9d6e7075..b4a5316ca4b 100644\n--- a/Documentation/gitprotocol-common.adoc\n+++ b/Documentation/gitprotocol-common.adoc\n@@ -21,11 +21,13 @@ ABNF Notation\n \n ABNF notation as described by RFC 5234 is used within the protocol documents,\n except the following replacement core rules are used:\n+\n ----\n HEXDIG = DIGIT / \"a\" / \"b\" / \"c\" / \"d\" / \"e\" / \"f\"\n ----\n \n We also define the following common rules:\n+\n ----\n NUL = %x00\n zero-id = 40*\"0\"\ndiff --git a/Documentation/gitweb.adoc b/Documentation/gitweb.adoc\nindex 5e2b491ec22..4261f9e235d 100644\n--- a/Documentation/gitweb.adoc\n+++ b/Documentation/gitweb.adoc\n@@ -103,6 +103,7 @@ You can generate the projects list index file using the project_index action\n \"Generating projects list using gitweb\" section below.\n \n Example contents:\n+\n -----------------------------------------------------------------------\n foo.git Joe+R+Hacker+\n foo/bar.git O+W+Ner+\n@@ -124,6 +125,7 @@ Generating projects list using gitweb\n \n We assume that GITWEB_CONFIG has its default Makefile value, namely\n 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:\n+\n ----------------------------------------------------------------------------\n read_config_file(\"gitweb_config.perl\");\n $projects_list = $projectroot;\n@@ -518,12 +520,14 @@ rules.\n If you use the rewrite rules from the example you *might* also need\n something like the following in your gitweb configuration file\n (`/etc/gitweb.conf` following example):\n+\n ----------------------------------------------------------------------------\n @stylesheets = (\"/some/absolute/path/gitweb.css\");\n $my_uri = \"/\";\n $home_link = \"/\";\n $per_request_config = 1;\n ----------------------------------------------------------------------------\n+\n Nowadays though gitweb should create HTML base tag when needed (to set base\n URI for relative links), so it should work automatically.\n \n@@ -535,6 +539,7 @@ Apache virtual host and gitweb configuration files in the following way.\n \n The virtual host configuration (in Apache configuration file) should look\n like this:\n+\n --------------------------------------------------------------------------\n \n ServerName git.example.org\n@@ -575,9 +580,11 @@ like this:\n Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`\n environment variable from a web server, so you need to put the following\n line in gitweb configuration file (`/etc/gitweb.conf` in above example):\n+\n --------------------------------------------------------------------------\n $projectroot = $ENV{'GITWEB_PROJECTROOT'} || \"/pub/git\";\n --------------------------------------------------------------------------\n+\n *Note* that this requires to be set for each request, so either\n `$per_request_config` must be false, or the above must be put in code\n referenced by `$per_request_config`;\n@@ -604,9 +611,11 @@ the third and the fourth.\n PATH_INFO usage\n ~~~~~~~~~~~~~~~\n If you enable PATH_INFO usage in gitweb by putting\n+\n ----------------------------------------------------------------------------\n $feature{'pathinfo'}{'default'} = [1];\n ----------------------------------------------------------------------------\n+\n in your gitweb configuration file, it is possible to set up your server so\n that it consumes and produces URLs in the form\n \n@@ -636,6 +645,7 @@ complementary static files (stylesheet, favicon, JavaScript):\n \t\n \n ----------------------------------------------------------------------------\n+\n The rewrite rule guarantees that existing static files will be properly\n served, whereas any other URL will be passed to gitweb as PATH_INFO\n parameter.\n@@ -647,6 +657,7 @@ for fetching\" section). A possible workaround for the latter is the\n following: in your project root dir (e.g. `/pub/git`) have the projects\n named *without* a .git extension (e.g. `/pub/git/project` instead of\n `/pub/git/project.git`) and configure Apache as follows:\n+\n ----------------------------------------------------------------------------\n \n \tServerAlias git.example.com\ndiff --git a/Documentation/gitweb.conf.adoc b/Documentation/gitweb.conf.adoc\nindex 85983587fcf..1348e9b1250 100644\n--- a/Documentation/gitweb.conf.adoc\n+++ b/Documentation/gitweb.conf.adoc\n@@ -603,6 +603,7 @@ Many gitweb features can be enabled (or disabled) and configured using the\n \n Each `%feature` hash element is a hash reference and has the following\n structure:\n+\n ----------------------------------------------------------------------\n \"\" => {\n \t\"sub\" => ,\n@@ -613,6 +614,7 @@ structure:\n Some features cannot be overridden per project. For those\n features the structure of appropriate `%feature` hash element has a simpler\n form:\n+\n ----------------------------------------------------------------------\n \"\" => {\n \t\"override\" => 0,\ndiff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\nindex 785c0786e0c..9d020e305a7 100644\n--- a/Documentation/rev-list-options.adoc\n+++ b/Documentation/rev-list-options.adoc\n@@ -429,6 +429,7 @@ filtered for `foo`, they look different and equal, respectively.)\n In the following, we will always refer to the same example history to\n illustrate the differences between simplification settings. We assume\n that you are filtering for a file `foo` in this commit graph:\n+\n -----------------------------------------------------------------------\n \t .-A---M---N---O---P---Q\n \t / / / / / /\n@@ -436,6 +437,7 @@ that you are filtering for a file `foo` in this commit graph:\n \t \\ / / / / /\n \t `-------------' X\n -----------------------------------------------------------------------\n+\n The horizontal line of history A---Q is taken to be the first parent of\n each merge. The commits are:\n \n\nbase-commit: e969bc875963a10890d61ba84eab3a460bd9e535\n-- \ngitgitgadget\n"},{"id":"513853","messageId":"Z84Y2mmenFVqDU-v@tapette.crustytoothpaste.net","threadId":"63082","inReplyTo":"pull.1878.git.1741549511665.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add a blank line around block delimiters","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-03-09T22:40:26Z","receivedAt":"2025-03-09T22:48:25Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-03-09 at 19:45:11, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n> \n> The documentation is using the historical mode for titles, which is a\n> setext-style (i.e., two-line) section title.\n> \n> The issue with this mode is that starting block delimiters (e.g.,\n> `----`) can be confused with a section title when they are exactly the\n> same length as the preceding line. In the original documentation, this\n> is taken care of for English by the writer, but it is not the case for\n> translations where these delimiters are hidden. A translator can\n> generate a line that is exactly the same length as the following block\n> delimiter, which leads to this line being considered as a title.\n> \n> To safeguard against this issue, add a blank line before and after\n> block delimiters where block is at root level, else add a \"+\" line\n> before block delimiters to link it to the preceding paragraph.\n\nThis seems like a reasonable thing to do.\n\n> The issue arose with a Chinese translation where the length of the\n> paragraph turned out to be smaller than the original English and to just\n> fit the number of hyphens of the following block starter.\n\nI was wondering what language you were referring to in the commit\nmessage, but I can definitely imagine how Chinese would cause this\nproblem since there tend to be fewer Unicode code points than in\nlanguages that use alphabets or abugidas. Thanks for satisfying my\ncuriosity.\n\n> An a longer term, I'm wondering how converting all the asciidoc files to\n> the modern style (i.e. atx-style, with variable \"=\" characters in front\n> of the line) would be perceived by the community.\n\nI feel like Junio may not love it due to the churn, but I'm fine with\nit, assuming that it continues to work with Python Asciidoc, which my\ntesting shows that it does. (I know it works with Asciidoctor, which I\nuse.)\n\nI think if you can articulate a good reason which is well explained in\nthe commit message (and honestly, I find that it's hard to remember how\nto do the underlining beyond the top 2 title levels, which may be\ncompelling enough), then it will probably be fine.\n-- \nbrian m. carlson (they/them or he/him)\nToronto, Ontario, CA\n"},{"id":"513920","messageId":"xmqqsenk97uk.fsf@gitster.g","threadId":"63082","inReplyTo":"pull.1878.git.1741549511665.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add a blank line around block delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-03-10T16:19:15Z","receivedAt":"2025-03-10T16:19:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> This patch is basically a mass-replace of occurrences of paragraphs\n> followed by a block delimiter.\n> \n> The issue arose with a Chinese translation where the length of the\n> paragraph turned out to be smaller than the original English and to just\n> fit the number of hyphens of the following block starter.\n\n;-)\n\n> An a longer term, I'm wondering how converting all the asciidoc files to\n> the modern style (i.e. atx-style, with variable \"=\" characters in front\n> of the line) would be perceived by the community.\n\nIt would be a one-time churn that may be worth doing, when the tree\nis quiescent.\n\n"}]}