doc: add a blank line around block delimiters #1878
Conversation
|
There are issues in commit 1c4b015: |
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>
jnavila
force-pushed
the
fix_empty_line_before_block
branch
from
1c4b015 to
2a9f518
Compare
|
/submit |
|
Submitted as pull.1878.git.1741549511665.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
On the Git mailing list, "brian m. carlson" wrote (reply to this): On 2025-03-09 at 19:45:11, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> 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.
This seems like a reasonable thing to do.
> The issue arose with a Chinese translation where the length of the
> paragraph turned out to be smaller than the original English and to just
> fit the number of hyphens of the following block starter.
I was wondering what language you were referring to in the commit
message, but I can definitely imagine how Chinese would cause this
problem since there tend to be fewer Unicode code points than in
languages that use alphabets or abugidas. Thanks for satisfying my
curiosity.
> An a longer term, I'm wondering how converting all the asciidoc files to
> the modern style (i.e. atx-style, with variable "=" characters in front
> of the line) would be perceived by the community.
I feel like Junio may not love it due to the churn, but I'm fine with
it, assuming that it continues to work with Python Asciidoc, which my
testing shows that it does. (I know it works with Asciidoctor, which I
use.)
I think if you can articulate a good reason which is well explained in
the commit message (and honestly, I find that it's hard to remember how
to do the underlining beyond the top 2 title levels, which may be
compelling enough), then it will probably be fine.
--
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA |
|
User |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> This patch is basically a mass-replace of occurrences of paragraphs
> followed by a block delimiter.
>
> The issue arose with a Chinese translation where the length of the
> paragraph turned out to be smaller than the original English and to just
> fit the number of hyphens of the following block starter.
;-)
> An a longer term, I'm wondering how converting all the asciidoc files to
> the modern style (i.e. atx-style, with variable "=" characters in front
> of the line) would be perceived by the community.
It would be a one-time churn that may be worth doing, when the tree
is quiescent.
|
|
This patch series was integrated into seen via git@ff80a43. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@fb2deda. |
|
This patch series was integrated into seen via git@f9dd4a9. |
|
This patch series was integrated into next via git@8d6641a. |
|
This patch series was integrated into seen via git@6dbd264. |
|
There was a status update in the "New Topics" section about the branch Doc markup updates. Will cook in 'next'. source: <pull.1878.git.1741549511665.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@203ee42. |
|
This patch series was integrated into seen via git@7f8722d. |
|
There was a status update in the "Cooking" section about the branch Doc markup updates. Will cook in 'next'. source: <pull.1878.git.1741549511665.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@e16b228. |
|
This patch series was integrated into seen via git@f3aaed7. |
|
This patch series was integrated into seen via git@4715785. |
|
This patch series was integrated into seen via git@3beb6ac. |
|
There was a status update in the "Cooking" section about the branch Doc markup updates. Will merge to 'master'. source: <pull.1878.git.1741549511665.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@cf54ec1. |
|
There was a status update in the "Cooking" section about the branch Doc markup updates. Will merge to 'master'. source: <pull.1878.git.1741549511665.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@2218818. |
|
This patch series was integrated into seen via git@ae92ad9. |
|
There was a status update in the "Graduated to 'master'" section about the branch Doc markup updates. source: <pull.1878.git.1741549511665.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@87a8e53. |
|
This patch series was integrated into master via git@87a8e53. |
|
This patch series was integrated into next via git@87a8e53. |
|
Closed via 87a8e53. |
This patch is basically a mass-replace of occurrences of paragraphs followed by a block delimiter.
The issue arose with a Chinese translation where the length of the paragraph turned out to be smaller than the original English and to just fit the number of hyphens of the following block starter.
An a longer term, I'm wondering how converting all the asciidoc files to the modern style (i.e. atx-style, with variable "=" characters in front of the line) would be perceived by the community.
cc: "brian m. carlson" sandals@crustytoothpaste.net