Chapter 10. Text Formatting

Words and phrases can be formatted by enclosing inline text with quote characters:

New quote types can be defined by editing asciidoc(1) configuration files. See the Configuration Files section for details.

10.1.1. Quoted text attributes

Quoted text can be prefixed with an attribute list. The first positional attribute (role attribute) is translated by AsciiDoc to an HTML span element class attribute or a DocBook phrase element role attribute.

DocBook XSL Stylesheets translate DocBook phrase elements with role attributes to corresponding HTML span elements with the same class attributes; CSS can then be used to style the generated HTML. Thus CSS styling can be applied to both DocBook and AsciiDoc generated HTML outputs. You can also specify multiple class names separated by spaces.

CSS rules for text color, text background color, text size and text decorators are included in the distributed AsciiDoc CSS files and are used in conjunction with AsciiDoc xhtml11, html5 and docbook outputs. The CSS class names are:

• <color> (text foreground color).
• <color>-background (text background color).
• big and small (text size).
• underline, overline and line-through (strike through) text decorators.

Where <color> can be any of the sixteen HTML color names. Examples:

[red]#Obvious# and [big red yellow-background]*very obvious*.

[underline]#Underline text#, [overline]#overline text# and
[blue line-through]*bold blue and line-through*.

is rendered as:

Obvious and very obvious.

Underline text, overline text and bold blue and line-through.

	Color and text decorator attributes are rendered for XHTML and HTML 5 outputs using CSS stylesheets. The mechanism to implement color and text decorator attributes is provided for DocBook toolchains via the DocBook phrase element role attribute, but the actual rendering is toolchain specific and is not part of the AsciiDoc distribution.

__unconstrained emphasized text__
**unconstrained strong text**
++unconstrained monospaced text++
##unconstrained unquoted text##

**F**ile Open...

Put ^carets on either^ side of the text to be superscripted, put ~tildes on either side~ of text to be subscripted. For example, the following line:

e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~

Is rendered like:

e^πi+1 = 0. H₂O and x¹⁰. Some ^{super text} and _{some sub text}

Superscripts and subscripts are implemented as unconstrained quotes and they can be escaped with a leading backslash and prefixed with with an attribute list.

A plus character preceded by at least one space character at the end of a non-blank line forces a line break. It generates a line break (br) tag for HTML outputs and a custom XML asciidoc-br processing instruction for DocBook outputs. The asciidoc-br processing instruction is handled by a2x(1).

A line of three or more less-than (<<<) characters will generate a hard page break in DocBook and printed HTML outputs. It uses the CSS page-break-after property for HTML outputs and a custom XML asciidoc-pagebreak processing instruction for DocBook outputs. The asciidoc-pagebreak processing instruction is handled by a2x(1). Hard page breaks are sometimes handy but as a general rule you should let your page processor generate page breaks for you.

A line of three or more apostrophe characters will generate a ruler line. It generates a ruler (hr) tag for HTML outputs and a custom XML asciidoc-hr processing instruction for DocBook outputs. The asciidoc-hr processing instruction is handled by a2x(1).

By default tab characters input files will translated to 8 spaces. Tab expansion is set with the tabsize entry in the configuration file [miscellaneous] section and can be overridden in included files by setting a tabsize attribute in the include macro’s attribute list. For example:

include::addendum.txt[tabsize=2]

The tab size can also be set using the attribute command-line option, for example --attribute tabsize=4

The following replacements are defined in the default AsciiDoc configuration:

(C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
double arrow, <= left double arrow.

Which are rendered as:

© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right double arrow, ⇐ left double arrow.

You can also include arbitrary entity references in the AsciiDoc source. Examples:

➊ ¶

renders:

➊ ¶

To render a replacement literally escape it with a leading back-slash.

The Configuration Files section explains how to configure your own replacements.

Words defined in [specialwords] configuration file sections are automatically marked up without having to be explicitly notated.

The Configuration Files section explains how to add and replace special words.