On 2025-03-09 at 19:45:11, Jean-Noël Avila via GitGitGadget wrote:

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <redacted>

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