Document exceptions to the nobreak role and non-breaking characters

[ryan-carpenter]

The nobreak role and non-breaking characters should prevent breaks from occuring within a span or string of text, but unintended breaks may occur in files generated with Prawn when the span or string includes mixed fonts. The reason is that Prawn creates separate fragments for the different fonts, and allows breaks between the fragments. This means that the nobreak role and non-breaking glyphs will only behave as intended when supported by the target font. Unfortunately, this is not the case for many of the most common fonts, which typically do not include non-breaking hyphens, narrow no-break space, or zero-width word joiner.

See discussion in the Asciidoctor Zulip chat

Suggestions

• Document exceptions to the nobreak role
• Consider adding a note about formatting table content by cell as this is a common context for using non-breaking text.
• Consider adding more information about the Character Replacements page
• Adjust the documentation for Asciidoctor PDF about required characters on the Prepare a Custom Font page which advises that "You need to ensure these glyphs are present in your prepared font or configure a fallback font that provides them." This instruction is suitable for most of the required non-Latin characters, but not for the non-breaking ones, which will not behave as intended if these alone (and not the surrounding text) are supplied by Prawn's fallback font.

[mojavelinux]

Document exceptions to the nobreak role (Not applicable to Asciidoctor PDF)

Actually, I would say that these exceptions are specifically applicable to Asciidoctor PDF since it's Asciidoctor PDF that cannot always honor the requested behavior.

[ryan-carpenter]

Document exceptions to the nobreak role (Not applicable to Asciidoctor PDF)

Actually, I would say that these exceptions are specifically applicable to Asciidoctor PDF since it's Asciidoctor PDF that cannot always honor the requested behavior.

Good point. Edited the issue to reinstate all the suggestions.

[mojavelinux]

Consider adding more information about the Character Replacements page

What information is expected here? It's not clear how that page is related to this issue.

[ryan-carpenter]

Consider adding more information about the Character Replacements page

What information is expected here? It's not clear how that page is related to this issue.

Initially, I was thinking it might be helpful to add   to the examples, because it is used so often in html, and seems like a likely avenue for discovering unexpected breaks. You have already pointed out that the language documentation is not the place for details about the PDF converter, so I suppose the suggestion is not an important one.

Something else I overlooked was the Asciidoctor PDF page on roles. This is another potential place to mention the exceptions.

The custom font page already states clearly that some of the required Unicode characters are often missing from non-default fonts.

"You need to ensure these glyphs are present in your prepared font or configure a fallback font that provides them."

Maybe the only clarification needed is to add that non-breaking glyphs, if used, should be included in the primary font to ensure that Asciidoctor PDF will honor them.

[mojavelinux]

Initially, I was thinking it might be helpful to add   to the examples, because it is used so often in html, and seems like a likely avenue for discovering unexpected breaks.

nbsp is a built-in attribute in AsciiDoc and can be referenced using {nbsp}. So there is no need to use   directly.

The custom font page already states clearly that some of the required Unicode characters are often missing from non-default fonts.

And it also mentions the requirements for using a custom font with Asciidoctor PDF. See https://docs.asciidoctor.org/pdf-converter/latest/theme/prepare-custom-font/#required-characters

Maybe the only clarification needed is to add that non-breaking glyphs, if used, should be included in the primary font to ensure that Asciidoctor PDF will honor them.

I feel like this is already implied. A font needs to provide glyphs for the required characters or else unexpected behavior will likely happen.

[mojavelinux]

So here's what I realized. The documentation for Asciidoctor PDF lists the built-in inline roles that it supports, but it does not include nobreak, nowrap, and pre-wrap. Since these roles have nuances (such as the impact of a fallback font) when used with Asciidoctor PDF, it is worth repeating them here. That gives us the opportunity to document the exceptions.

In brief, if Asciidoctor PDF reaches for the fallback font to render a character, that will introduce a break opportunity, regardless of what role is set or what the adjacent characters are.

I have added a warning to the page about fallback fonts.