From 227c4f33a0351d12b04660a9f03ca96dbab1310a Mon Sep 17 00:00:00 2001
From: Jean-Noël Avila <jn.avila@free.fr>
Date: Sun, 9 Mar 2025 19:45:11 +0000
Subject: doc: add a blank line around block delimiters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The documentation is using the historical mode for titles, which is a
setext-style (i.e., two-line) section title.

The issue with this mode is that starting block delimiters (e.g.,
`----`) can be confused with a section title when they are exactly the
same length as the preceding line. In the original documentation, this
is taken care of for English by the writer, but it is not the case for
translations where these delimiters are hidden. A translator can
generate a line that is exactly the same length as the following block
delimiter, which leads to this line being considered as a title.

To safeguard against this issue, add a blank line before and after
block delimiters where block is at root level, else add a "+" line
before block delimiters to link it to the preceding paragraph.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/gitprotocol-common.adoc | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'Documentation/gitprotocol-common.adoc')

diff --git a/Documentation/gitprotocol-common.adoc b/Documentation/gitprotocol-common.adoc
index cdc9d6e707..b4a5316ca4 100644
--- a/Documentation/gitprotocol-common.adoc
+++ b/Documentation/gitprotocol-common.adoc
@@ -21,11 +21,13 @@ ABNF Notation
 
 ABNF notation as described by RFC 5234 is used within the protocol documents,
 except the following replacement core rules are used:
+
 ----
   HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
 ----
 
 We also define the following common rules:
+
 ----
   NUL       =  %x00
   zero-id   =  40*"0"
-- 
cgit v1.3-5-g9baa

