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@xxxxxxx> > > 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
Attachment:
signature.asc
Description: PGP signature
