Bug 262001 - "_italic_" doesn't render as HTML emphasis when immediately followed by another "_"
Summary: "_italic_" doesn't render as HTML emphasis when immediately followed by anoth...
Status: In Progress
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Sergio Carlavilla Delgado
URL: https://docs.asciidoctor.org/asciidoc...
Keywords:
Depends on:
Blocks:
 
Reported: 2022-02-16 21:25 UTC by Pau Amma
Modified: 2023-08-26 07:03 UTC (History)
2 users (show)

See Also:


Attachments
Screenshot: part of the FreeBSD Developers' Handbook (41.44 KB, image/png)
2023-04-10 15:32 UTC, Graham Perrin
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Pau Amma 2022-02-16 21:25:10 UTC
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.
Comment 1 commit-hook freebsd_committer freebsd_triage 2023-04-10 08:51:38 UTC
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(-)
Comment 2 Graham Perrin freebsd_committer freebsd_triage 2023-04-10 12:21:54 UTC
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.
Comment 3 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2023-04-10 13:06:45 UTC
(In reply to Graham Perrin from comment #2)
Perfect, thanks
Comment 4 Graham Perrin freebsd_committer freebsd_triage 2023-04-10 13:28:37 UTC
tl;dr use pairs. 

AsciiDoc Syntax Quick Reference uses the word 'unconstrained'.
Comment 5 Graham Perrin freebsd_committer freebsd_triage 2023-04-10 15:32:56 UTC
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: