Inline Semantics in AsciiDoc(sy)

AsciiDoc offers semantic tagging of words and phrases. Called “inline semantics,” this syntax enables stylized representation of text depending on its role.

For a crash course in the power of semantics, look at AsciiDocsy’s term-popover feature. AsciiDocsy supports a terms data object — an array of objects representing glossary terms, their definitions, and some other metadata.

Inline semantic tagging for term ‘AsciiDoc’
 Now let's see what happens when we wrap the term [.term]*AsciiDoc* in semantic syntax.
Hover your cursor over ‘AsciiDoc’ in this rendered sample

Now let’s see what happens when we wrap the term AsciiDoc in semantic syntax.

And then we have flat file, which is a version of flat files, a term defined in terms.yml. Since it carries the role .flat-files (note the s), the lookup can find it. (Here is that same term flat file without the role helper).

Inline semantic tags do not have to involve popovers or animations, of course. For the most part, they are just used for distinctive styling.

Here is an interface element, just to demonstrate how creative syntax styling can get.

Here is a Book Volume Title: Second Edition.

Here is a /path/to/filename.adoc.

And finally, a command --line example.

Certain types of text receive special formatting considerations, noted inline. In AsciiDoc, these types are denoted by “roles”, designated by a role name wrapped in square brackets and prefixed with a dot, such as [.cite]. The text to be formatted is then wrapped in characters called “quotes”, with the character pair itself determined by the role.

To be clear, the concept of inline semantic tagging is built into the AsciiDoc language. This article documents the specific implementation suggested by AsciiDocsy, also serving to document the way AsciiDocsy handles HTML rendering of these particular styles.

Inline Semantic Roles

The following roles are matched with their quote character (_, `, *, or #). The rendered rich-text formatting such as font face, color, and styling may vary in published editions.

This is a listing of AsciiDocsy’s default settings for inline semantics, including the semantics namespace itself and how to display the various types in HTML. To customize for your purposes, see Semantics Configuration.
.term

For significant terms, usually only used for the first appearance. A word or phrase marked for the term role may also be provided a role that fits the slug for a term in the site.data.terms registry, in which case term metadata becomes available.

Quotes

asterisk

Example

Let’s explore [.term]*inline semantics*!

Renders

Let’s explore inline semantics!
.cite

For citations of publication titles.

Quotes

underscore

Example

See the [.cite]_Proper Noun User Guide_ for more.

Renders

See the Proper Noun User Guide for more.
.cmd

For literal characters intended to potentially be copied and pasted to the commandline. The cmd role can also be applied to process/service names that might appear in a terminal console.

Quotes

backtick

Example

Run the [.cmd]`typical command` command.

Renders

Run the typical command command.
.code

Literal characters from one-line code listing. Use for variable names, short snippets, and so forth.

Quotes

backtick

Example

Use the [.code]`.term` class to designate a defined word or phrase.

Renders

Use the .term class to designate a defined word or phrase.
.gui

For exact text from a graphical user interface (or other screen element).

Quotes

asterisk

Example

Click [.gui]*Add Item* on the screen.

Renders

Click Add Item on the screen.
.path

For literal file paths to system resources.

Quotes

backtick

Example

Browse to [.path]`/etc/<somefile>/path`.

Renders

Browse to /etc/somefile/path.
.buz

For crass marketing terms. Probably best kept out of technical docs altogether, AsciiDocsy violates this rule for demonstration purposes.

Quotes

underscore

Example

Take advantage of [.buz]_SuperGloo_ sticky sidebar.

Renders

Take advantage of SuperGloo sticky sidebar.
.case

Identifies “inline conditions”. Usually used when multiple such “cases” are presented in the same section of a topic.

Quotes

underscore

Example

[.case]_If you chose Implementation Strategy A_, you should establish start with the default settings.

[.case]_If you chose Implementation Strategy B_, use the guide below to get set up.

Renders

If you chose Implementation Strategy A, you should start with the default settings.

If you chose Implementation Strategy B, use the guide below to get set up.
.sub

For literal substitution tokens embedded in code or command examples. Use with or without visual wrapping charactes (such as < > or ${ }).

Quotes

backtick

Example

Use the format [.code]`base.<file_ext>`, where [.sub]`<file_ext>` is the filename followed by an underscore and the file extension.+

Renders

Use the format base.<file_ext>, where <file_ext> is the filename followed by an underscore and the file extension.
.tip

For highlighting a bit of text as sound advice.

Quotes

asterisk

Example

When you find yourself stuck in Vi's exit menu, [.tip]*keep trying kbd:[⇑Shift+:] and random keys* until you escape.

Renders

When you find yourself stuck in Vi’s exit menu, keep trying kbd:[Shift+:] and random keys until you escape.
Related Topics
Feedback, please.