As evidenced by the list in section 7.2.1 of the Porter's Handbook (https://docs.freebsd.org/en/books/porters-handbook/flavors/#flavors-using), the AsciiDoctor toolchain doesn't translate _flavor__CONFLICTS to <em>flavor</em>_CONFLICTS as expected. AllanJude mentioned https://docs.asciidoctor.org/asciidoc/latest/text/troubleshoot-unconstrained-formatting/ in IRC, and I think the start of that section says __flavor___CONFLICTS should work. In other words, when there's a _ immediately after the end marker, wrap the text inside __...__ instead of _..._. This seems to also apply to *...*_ sequences, which should be **...**_ instead. This may affect the web pages as well as the documentation itself, and should IMO be documented in the FDP primer for future-proofing.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=b31c144ef2ade65b730306a8b79a19b410c75cce commit b31c144ef2ade65b730306a8b79a19b410c75cce Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2023-04-10 08:50:00 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2023-04-10 08:50:00 +0000 Porters handbook - flavors: Fix italic render PR: 262001 .../en/books/porters-handbook/flavors/_index.adoc | 33 +++++++++++----------- 1 file changed, 16 insertions(+), 17 deletions(-)
Thanks to Sergio for the fix. I'll take this bug, with a view to possible identification of files elsewhere that should benefit from a similar fix. Sergio, override me (take over) if you like.
(In reply to Graham Perrin from comment #2) Perfect, thanks
tl;dr use pairs. AsciiDoc Syntax Quick Reference uses the word 'unconstrained'.
Created attachment 241402 [details] Screenshot: part of the FreeBSD Developers' Handbook <https://docs.freebsd.org/en/books/developers-handbook/ipv6/#_sockaddr_storage> (pictured) was found through a lazy (inaccurate) run of: rg __ /usr/doc Many results, this chunk below caught my eye as things sped past. A better search should yield more useful results. I'll not yet give thought to what must be done with .po files. ---- /usr/doc/documentation/content/en/books/developers-handbook/ipv6/_index.po 1471:"sockaddr_storage members are named. One proposal is to prepend \"__\" to " 1472:"the members (like \"__ss_len\") as they should not be touched. The other " 1487:"\t\tu_char\t__ss_len;\t/* address length */\n" 1488:"\t\tu_char\t__ss_family;\t/* address family */\n" 1541:"have -Dss_family=__ss_family to unify all occurrences (including header " 1542:"file) into __ss_family, or" 1547:msgid "never touch __ss_family. cast to sockaddr * and use sa_family like:" /usr/doc/documentation/content/en/books/developers-handbook/ipv6/_index.adoc 617:One proposal is to prepend "__" to the members (like "__ss_len") as they should not be touched. 626: u_char __ss_len; /* address length */ 627: u_char __ss_family; /* address family */ 651:. have -Dss_family=__ss_family to unify all occurrences (including header file) into __ss_family, or 652:. never touch __ss_family. cast to sockaddr * and use sa_family like: