troubleshoot-unconstrained-formatting.adoc 6.65 KB
Newer Older
1
= Troubleshoot Unconstrained Formatting Pairs
2

3
An xref:index.adoc#unconstrained[unconstrained formatting pair] is often used to format just one or a few characters in a word.
4

5
6
[#use-unconstrained]
== When should I use unconstrained formatting?
7
8
9

Consider the following questions:

10
11
12
. Is there a letter, number, or underscore directly outside the opening or closing formatting marks?
. Is there a colon, semicolon, or closing curly bracket directly before the opening formatting mark?
. Is there a space directly inside of a formatting mark?
13

14
If you answered "`yes`" to any of these questions, you need to use an unconstrained pair.
15

16
To help you determine whether a particular syntax pattern requires an unconstrained pair versus a xref:index.adoc#constrained[constrained pair], consider the following scenarios:
17
18
19
20

.Constrained or Unconstrained?
[#constrained-or-unconstrained]
|===
21
|AsciiDoc |Result |Formatting Pair |Reason
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

|`+Sara__h__+`
|Sara__h__
|Unconstrained
|The letter `a` is directly adjacent to the opening mark.

|`+**B**old+`
|**B**old
|Unconstrained
|The `o` is directly adjacent to the closing mark.

|`+–**2016**+`
|–**2016**
|Unconstrained
|The `;` is directly adjacent to the opening mark.

|`+** bold **+`
|** bold **
|Unconstrained
|There are spaces directly inside the formatting marks.

|`+*2016*–+`
|*2016*–
|Constrained
|The adjacent `&` is not a letter, number, underscore, colon, or semicolon.

|`+*9*-to-*5*+`
|*9*-to-*5*
|Constrained
|The adjacent hyphen is not a letter, number, underscore, colon, or semicolon.
|===

[#unconstrained-edge-cases]
55
=== Unconstrained pair edge cases
56

57
There are cases when it might seem logical to use a constrained pair, but an unconstrained pair is required.
58
59
60
61
62
63
64
65
66
67
68
69
70
71
xref:subs:substitutions.adoc[Substitutions] may be applied by the parser before getting to the formatting marks, in which case the characters adjacent to those marks may not be what you see in the original source.

One such example is enclosing a xref:monospace.adoc[monospace phrase] inside xref:quotation-marks-and-apostrophes.adoc[curved quotation marks], such as "```end points```".

You might start with the following syntax:

[source]
----
"`end points`"
----

That only gives you "`end points`".
The backticks contribute to making the curved quotation marks, but the word isn't rendered in monospace.

72
Adding another pair of backticks isn't enough either.
73
74
75
76
77
78

[source]
----
"``end points``"
----

79
The parser ignores the inner pair of backticks and interprets them as literal characters, rendering the phrase as "``end points``".
80

81
82
You have to use an unconstrained pair of monospace formatting marks to render the phrase in monospace and a constrained pair of backticks to render the quotation marks as curved.
That's three pairs of backticks in total.
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

.A monospace phrase inside curved quotation marks
[source]
----
"```end points```"
----

If, instead, you wanted to surround the monospace phrase with typewriter quotation marks, such as "[.code]``end points``", then you need to interrupt the curved quotation marks by applying a role to the monospace phrase or escaping the typewriter quote.
For example:

.A monospace phrase inside typewriter quotation marks
[source]
----
"[.code]``end points``" or \"``end points``"
----

Another example is a possessive, monospace phrase that ends in an "`s`".
In this case, you must switch the monospace phrase to unconstrained formatting.

[source]
----
The ``class```' static methods make it easy to operate
on files and directories.
----

.Rendered possessive, monospace phrase
====
The ``class```' static methods make it easy to operate on files and directories.
====

Alternately, you could encode the curved apostrophe directly in the AsciiDoc source to get the same result.

[source]
----
The `class`’ static methods make it easy to operate on files and directories.
----

This situation is expected to improve in the future when Asciidoctor switches to using a parsing expression grammar for inline formatting instead of the current regular expression-based strategy.
For details, follow https://github.com/asciidoctor/asciidoctor/issues/61[issue #61].
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

[#escape-unconstrained]
== Escape unconstrained formatting marks

Since unconstrained formatting marks are meant to match anywhere in the text, context free, that means you may catch them formatting text that you don't want styled sometimes.
Admittedly, these symbols are a bit tricky to type literally when the content calls for it.
But being able to do so is just a matter of knowing the tricks, which this section will cover.

Let's assume you are typing the following two lines:

----
The __kernel qualifier can be used with the __attribute__ keyword...

#`CB###2`# and #`CB###3`#
----

In the first sentence, you aren't looking for any text formatting, but you're certainly going to get it.
The processor will interpret the double underscore in front of _++__kernel++_ as an unconstrained formatting mark.
In the second sentence, you might expect _++CB###2++_ and _++CB###3++_ to be highlighted and displayed using a monospace font.
However, what you get is a scrambled mess.
The mix of constrained and unconstrained formatting marks in the line is ambiguous.

There are two reliable solutions for escaping unconstrained formatting marks:

* use an attribute reference to insert the unconstrained formatting mark verbatim, or
* wrap the text you don't want formatted in an inline passthrough.

The attribute reference is preferred because it's the easiest to read:

----
:scores: __
:hash3: ###

The {scores}kernel qualifier can be used with the {scores}attribute{scores} keyword...

#`CB{hash3}2`# and #`CB{hash3}3`#
----

This works because xref:subs:attributes.adoc[attribute expansion] is performed after text formatting (i.e., xref:subs:quotes.adoc[quotes substitution]) in the normal substitution order.

Here's how you'd write these lines using the xref:pass:pass-macro.adoc[inline single plus macro] to escape the unconstrained formatting marks instead:

----
The +__kernel+ qualifier can be used with the +__attribute__+ keyword...

#`+CB###2+`# and #`+CB###3+`#
----

Notice the addition of the plus symbols.
Everything between the plus symbols is escaped from interpolation (attribute references, text formatting, etc.).
However, the text still receives proper output escaping for xref:subs:special-characters.adoc[HTML special characters] (e.g., `<` becomes `\&lt;`).

The enclosure `pass:[`+TEXT+`]` (text enclosed in pluses surrounded by backticks) is a special formatting combination in Asciidoctor.
It means to format TEXT as monospace, but don't interpolate formatting marks or attribute references in TEXT.
It's roughly equivalent to Markdown's backticks.
Since AsciiDoc offers more advanced formatting, the double enclosure is necessary.