Handling Special Chars via Attributes Substitutions

[tajmone]

• Create the gitbuch_custom-attributes.adoc file for defining custom attributes for special characters substitutions (and any other substitution that might be useful)
  • Include it in the main gitbuch.asciidoc source.
• When the draft translation is completed, work out which special chars need to be substituted with custom attributes and update this tasks list.

---

The AsciiDoc source docs contain many special characters that need to be represented either via a predefined attribute for character replacements or an SVG/HTML entity character reference.

When a native textual symbol replacement is not available, we should always use a predefined attribute for character replacements, if available (and not too verbose), failing that we should use custom-defined attributes (with intuitive IDs) that will be translated to the character's HTML numerical entity representation.

There are various issues at stake here:

1. cross-format support — named HTML entities should be avoided in favor of their numerical representation, because they are not supported by all backends (e.g. PDF). From the Asciidoctor Manual (emphasis added):

   [3] Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., € resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named character references—​with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character references (e.g., €).

2. human readability — HTML entities (especially in their numerical format) don't provide a good reading experience for the maintainers — e.g. – for en-dash (–), whereas a custom attribute like {en-dash} looks better.

3. editors/IDEs highlighting — due to the complex nature of the AsciiDoc syntax, the presence of special chars which are also formatting tokens (e.g. *, _, ^, etc.) will break syntax coloring (for the whole document) in many editors when these occur as mere characters. Custom attributes will effectively prevent this, simplifying the editing work.

Of course, the downside of using custom-defined attributes for substitutions is that inside source or verbatim blocks it becomes necessary to enable attributes substitutions (via [subs=]).

References

• Asciidoctor Manual:
  • A.3. Predefined Attributes for Character Replacements
  • 37.1. Special Characters
  • §37.4. Replacements
    • Anatomy of a character reference