Character Replacement Attributes Reference

This page identifies built-in document attributes populated by the AsciiDoc processor that are geared towards character replacement.

This category of attributes provide portable replacements for common typographical marks (e.g., smart quotes and symbols) and non-visible characters (e.g., empty and no break space), an escaping mechanism for characters which have special meaning in AsciiDoc (e.g., plus and colon), and passthroughs for characters which get encoded by default (e.g., less than and greater than). Like all document attributes, you can insert the value of any one of these attributes in your content using an attribute reference (e.g., {nbsp}).

The AsciiDoc processor does not prevent you from reassigning these predefined attributes. However, you’re encouraged to treat them as read-only. Only a converter should override these attributes if the output format requires the use of a different encoding scheme.
Built-in document attributes for character replacement
Attribute name Replacement text Appearance

blank[1]

nothing

empty

nothing

sp

space

nbsp

 

 

zwsp[2]

​

wj[3]

⁠

apos

'

'

quot

"

"

lsquo

‘

rsquo

’

ldquo

“

rdquo

”

deg

°

°

plus

+

+

brvbar

¦

¦

vbar

|

|

amp

&

&

lt

<

<

gt

>

>

startsb

[

[

endsb

]

]

caret

^

^

asterisk

*

*

tilde

~

~

backslash

\

\

backtick

`

`

two-colons

::

::

two-semicolons

;;

;;

cpp

C++

C++

pp

&#43;&#43;

++

[1] An alias for the attribute empty, for those who find this terminology clearer.

[2] The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.

[3] The word joiner (WJ) is a code point in Unicode that prevents a line break at its position.

Notice that some replacement values are Unicode characters, whereas others are numeric character references (e.g., &#34;). The numeric character reference is when the Unicode character could interfere with the AsciiDoc syntax. In this case, it’s the responsiblity of the converter to transform that numeric character reference into a format that is compatibile with the output format. For example, in the man page converter, each character reference is replaced with a troff macro.

Thus, the abstraction of using AsciiDoc attributes for character replacements not only gives the author control over how the document is interpreted, it also helps decouple content and presentation. In other words, it’s more protable to use an attribute reference in the content rather than hardcode a nummeric character reference.