Writing in AsciiDoc

Atlas supports writing in AsciiDoc, a text document format for writing (among other things) books, ebooks, and documentation. It is similar to wiki markup—if you can write a Wikipedia article, then you’ll have no problem with AsciiDoc. AsciiDoc files in Atlas can be edited using the Code Editor.

Note

AsciiDoc files are converted to HTMLBook in Atlas's backend before generating output formats. Syntax errors for AsciiDoc markup are typically, and unfortunately, cited at line numbers in the generated HTMLBook

AsciiDoc Markup Reference

This section provides markup examples for some of the most common elements used in writing technical documentation. These examples comprise some of the most common use cases for typical O'Reilly authors, as well as a few examples highlighting markup idiosyncratic to Atlas's support for AsciiDoc.

Note

Atlas uses a custom implementation of Asciidoctor 1.5.0. Please consult the Asciidoctor documentation for a more complete guide on AsciiDoc syntax, but please be aware that Atlas's custom implementaton may not support all Asciidoctor syntax.

Text

Regular paragraph text does not need any special markup in AsciiDoc. Just add a blank line both above and below each paragraph, and the first word in the paragraph should not have a space before it. Here are some example paragraphs in AsciiDoc:

This is an example paragraph written in AsciiDoc. See, it's just plain text; no special markup necessary! Do make sure there aren't spaces or manual indentations at the beginning of your paragraph text.

This is a second example paragraph in AsciiDoc. Note that there's a line break and a blank line between paragraphs.

To learn how to add inline styling (such as italics) to your text, see the Inline Markup section.

Chapters

The top of each chapter file should begin with a chapter title preceded by two equals signs. It's good practice to always include a unique ID above the chapter title, surrounded by double brackets. For example:

[[unique_chapter_id]]
== Chapter Title

Chapter text begins here.

Headings

There are multiple ways to mark up heading levels in AsciiDoc. We've chosen our favorite "delimited" style to show you below, but feel free to use the two-line underlined heading style if you prefer.

Note

The levels described in the AsciiDoc User Guide can be confusing: in AsciiDoc, the document (book) is considered level 0; generally a chapter will be at AsciiDoc level 1 (unless you're dividing the book into parts), and sections within chapters start at AsciiDoc level 3 (which is equivalent to HTMLBook section data-type="sect1").

Top-level heading

Within a chapter, the first and highest heading level uses three equals signs:

=== A-Head

Second-level heading

This heading level should only follow a top-level heading:

==== B-Head

Third-level heading

This heading level should follow a second-level heading only:

===== C-Head

Parts

If you want to group your chapters into parts, you can do so by creating a new AsciiDoc file (for example, part1.asciidoc) and then inserting the following part markup:

[[unique_part_id]]
[part]
== Part Title

Once you have created the part file, include it in the Build Contents on the Configure page before the first chapter you wish to be included in the part.

To add introductory text to a part, add this partintro markup after the part title:

[[unique_part_id]]
[part]
== Part Title

[partintro]
--
Insert introductory text here.
--

Prefaces

A preface file should begin with the data-type preface in single brackets, followed on the next line by two equals signs and the preface title:

[preface]
== Preface Title

Preface text begins here.

Forewords

A foreword file should begin with the data-type foreword in single brackets, followed on the next line by two equals signs and the foreword title:

[foreword]
== Foreword

Foreword text begins here.

[role="byline"]
Some Famous Person

Afterwords

The markup for an afterword is similar to the preface markup, but it has an additional role attribute with a value of afterword. Here's the markup:

[appendix]
[role="afterword"]
== Afterword

Afterword text begins here.

Dedications

A dedication file should begin with the word dedication in single brackets, followed by the dedication title and text. The title must be present and must be "Dedication", but it will not render in the output:

[dedication]
== Dedication

This book is dedicated to my cat, Garfield.

Glossaries

A glossary file should begin with the section ID glossary in double brackets, followed by the glossary title and a blank line. Following the blank line should be another instance of the data-type glossary, this time in single brackets.

Each glossary entry should consist of one glossary term, followed by two colons and a space, then the glossary definition. If you’d like to add an additional paragraph to a glossary definition, add a plus sign ("+") on the following line by itself, and begin the additional paragraph on the line after it.

Here’s an example of the markup:

[[glossary]]
== Glossary

[glossary]
Crawler:: A program used to index documents.
+
See Also Spider

Appendixes

To designate a file as an appendix, add the data-type appendix in single brackets at the top of the file. Immediately below it should be the title of the Appendix. For example:

[appendix]
[[unique_appendix_id]]
== Resources

The following list of resources ...

Chapter Contributors

For books with multiple contributors, you may want an author name to appear with each chapter. O'Reilly themes support placing, when appropriate, the name of the chapter contributor below the chapter heading. You can add the following markup as a separate paragraph between the chapter title and first paragraph of content:

[role="byline"]
Author Name

When multiple lines are necessary—for example, when you would like to include the author's affiliation—use the [role="byline cont"] markup in a separate paragraph for every line that should follow the first:

[role="byline"]
Author Name

[role="byline cont"]
Author Affiliation

For multiple authors of one chapter, the markup looks like this:

[role="byline"]
Author Name

[role="byline cont"]
Author Affiliation

[role="byline"]
Another Author

[role="byline cont"]
Another Author's Affiliation

You can also use this same markup for forewords, prefaces, and appendixes. Please note that contributor names in a foreword will render preceded by an em dash (—), since house style is to place foreword author bylines at the end of the foreword.

Inline Markup

The following list comprises typographical conventions and O'Reilly house style recommendations for their use.

_Italic_

Italic text indicates new terms, URLs, email addresses, filenames, and file extensions. The AsciiDoc markup is one underscore character on either side of the text to be italic.

To mark a a few letters of a word in italics, or a word that abuts a non-whitespace character, double up the underscore characters on either side of the text, like this: __Part__ial word i__tal__ic

*Bold*

Bolded text is used to emphasize a word or phrase. The AsciiDoc markup is one asterisk on either side of the text to be bolded.

Warning

Please note that O'Reilly house style prefers italics for emphasis.

To mark a partial word in bold, or a word that abuts a non-whitespace character, double up the asterisk characters on either side of the text, like this: **Part**ial word b**ol**d

+Constant Width+

Constant width, or monospaced, text is used for code, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. The AsciiDoc markup is one plus sign on either side of the text to be monospaced.

To mark a partial word in constant width, or a word that abuts a non-whitespace character, double up the plus signs on either side of the text, like this: ++Part++ial word con++st++ant wid++th++

*+Constant Width Bold+*

Monospaced and bolded text is used to show commands or other text that should be typed literally by the user. The AsciiDoc markup is one asterisk and one plus sign on either side of the text. Note that the asterisk (*) pair should be on the outside and the plus-symbol (+) pair on the inside.

To mark a partial word in constant width bold, or a word that abuts a non-whitespace character, double up the markup on either side of the text, like this: **++Part++**ial word constant w**++id++**th bold

_++Constant Width Italic++_

Monospaced and italicized text indicates where text should be replaced with user-supplied values or by values determined by context. The AsciiDoc markup is one underscore and two plus signs on either side of the text. Note that the underscore (_) must be on the outside and the plus-symbol (+) pair on the inside.

To mark a partial word in constant width italic, or a word that abuts a non-whitespace character, double up the underscore markup on either side of the text, like this: __++Part++__ial word con__++st++__ant width ital__++ic++__

_~subscript~

For _subscript text, use a tilde character (~) on either side of the subscript text.

^{^superscript^}

For ^superscript text, use a caret (^) character on either side of the superscript text.

Hyperlinks

For hyperlinks to external sources, just add the full URL string followed by brackets containing the text to which you'd like to anchor the URL. The bracketed text will become a clickable link in web versions. In print versions, it will appear in the text, followed by the actual URL in parentheses.

The markup looks like this:

Visit the http://oreilly.com[O'Reilly website]

Note that these will become hyperlinks in online versions, so for fake or example URLs, use +constant width+ or _italic_ markup instead.

Troubleshooting Inline Markup

Using inlines in AsciiDoc can sometimes be tricky. If you’re having problems with inline markup not rendering correctly, or if it’s producing validation errors, check if it’s an issue with nested inlines. Attempting to nest inlines within each other may sometimes result in problems if the markup is done in the wrong order. For example, constant width bold text uses an asterisk and a plus sign on either side of the text, but the asterisk pair must be on the outside of the plus sign pair; otherwise, you’ll get an error.

Another common issue is when inline markup occurs within a single word, like foobar, or if the inline markup abuts some other non-whitespace character on one or more sides (like an em dash), it may render incorrectly like this: foo+bar. The fix for this is to double up the markup. For example: ++foo++bar will display as foobar. See Inline Markup.

HTML passthroughs sometimes represent the most straightforward way to meet an AsciiDoc formatting challenge (see Passthroughs). For inline markup within code blocks, you should plan on placing the entire code block within a passthrough (see Inline formatting within code). What follows are examples of inline passthroughs for formatting regular text in constant-width italic, constant-width bold, and constant-width bold italic, respectively:

pass:[<em><code>foo</code></em>]
pass:[<strong><code>foo</code></strong>]
pass:[<strong><code><em>foo</em></code></strong>]

You may also run into difficulties if you want to literally display characters used for Asciidoc markup (e.g., *, +, or _). If there are two or more of the same character in a single line, the Asciidoc parser will read these characters as markup instead of text. To fix this, you can use backslashes to escape these characters. Note that you only need to escape the first character for every set of two. For example:

To display the asterisk characters \*here*  and \*here*, escape the first with a backslash.

Curly brackets, { and }, may cause rendering problems because they indicate macros in AsciiDoc. If you are having trouble getting curly brackets to render, try escaping them with backslashes like this: \{ and \}

Sidebars

Sidebar markup looks like this:

.Sidebar Title
****
Sidebar text is surrounded by four asterisk characters above and below.
****

The appearance of sidebars will vary by theme, but they will look approximately like the following:

Notes, Tips, Warnings, and Cautions

You have the option of using note, tip, and warning elements for supplemental information.

You may also notice that some of the admonitions below have a title. We do support optional titles in admonitions. If you don’t want a title for your note, tip, or warning, just leave out the entire .Tip Title line in the markup below.

The markup for a note looks like this:

[NOTE]
====
Here's some text inside a note.
====

And here’s how it renders:

Note

Here’s some text inside a note.

You’d create a tip with a title like so:

.Tip Title
[TIP]
====
Here's some text inside a tip.
====

…which will yield this result:

Tip

Tip Title

Here’s some text inside a tip.

Or you could use a warning:

.Warning Title
[WARNING]
====
Here's some text inside a warning.
====

Warning

Warning Title

Here's some text inside a warning.

Footnotes

To create a footnote, place the footnote macro directly after the text/end punctuation where the note number should appear, with no space between.¹ The content of the footnote should appear within the brackets. Footnotes at the end of a sentence belong after the period:

footnote:[This is a standard footnote.]

Here’s an example of the markup placement in the text:

There should be no spacefootnote:[This is a standard footnote.] between the text and the note number.

For an example of the footnote rendering, see the first paragraph in this section. You should see the content of the note rendering at the bottom of the page.

Quotes

To add a block quote to your text, use the keyword quote inside single brackets, followed by a comma and the full name of the quote’s author. The text of the quote itself should appear immediately below, with four underscore characters above and below it.

Here’s some example markup, a quote attributed to Benjamin Disraeli (by Wilfred Meynell, according to Frank Muir):

[quote, Wilfred Meynell]
____
Many thanks; I shall lose no time in reading it.
____

And here’s how it renders:

Many thanks; I shall lose no time in reading it.

Wilfred Meynell

Figures and Other Images

Figure markup for figures that will be referenced in the text should include a unique ID attribute (see Cross-References for more info on using cross-references). Please note that a given ID should be unique in the context of an entire book.

Create a figure with a caption like so:

[[unique_id]]
.A Figure
image::images/tiger.png["An image of a cartoonish tiger head"]

And here’s how it renders:

An image of a cartoonish tiger head — Figure 7-1. A Figure

If you’d like your figure to appear without a caption, just omit the .title line. Please keep in mind that in addition to having no title, O'Reilly themes will not give these figures a figure number and the figures cannot be cross-referenced in the body of the text.

Here’s the markup:

image::images/tiger.png["An image of a cartoonish tiger head."]

And here’s how it renders:

Adding alt text to images

To improve accessibility in your ebook files, please consider adding alt text to the images. To do this, just add the descriptive text in quotes inside the brackets, which are at the end of the image markup:

[[unique_id]]
.A Figure
image::images/tiger.png["An image of a cartoonish tiger head"]

Tip

For some tips on writing good alt text, O’Reilly’s Universal Design for Web Applications is a great resource. In particular, see the section, “Keys to Writing Good Text Alternatives.”

Lists

There are three common types of lists. The following sections provide markup examples of each.

Note

The O’Reilly Style Guide and Word List has more details about when to use which type of list.

Bulleted (aka, itemized) lists

Here’s the markup for a bulleted list:

* lions
* tigers
** sabre-toothed
** teapotted
* lions, tigers, and bears
+
Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

This list markup could be rendered like this:

lions
tigers
- sabre-toothed
- teapotted
lions, tigers, and bears

Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Note that the final item in the list has multiple paragraphs. As you can see in the markup example, a plus (+) character on its own line can be used to add additional paragraphs to a list item.

Ordered (aka, numbered) lists

Here’s the markup for a numbered list:

. Preparation
. Assembly
.. Measure
.. Combine
.. Bake
. Applause
+
Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Using the above markup will generate a numbered list:

Preparation
Assembly
1. Measure
2. Combine
3. Bake
Applause

Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Labeled (aka variable or term-definition) lists

Here’s the markup for a labeled list:

Term 1::
  Definition/description
Term 2::
  Something else

Labeled lists may be rendered like this:

Term 1: Definition/description
Term 2: Something else

Tables

Standard AsciiDoc markup for a simple table follows:

.A Table
[options="header"]
|=======
|P|Q|P^Q
|T|T|T
|T|F|F
|F|T|F
|F|F|F
|=======

Note

Note that a single vertical bar (|) character is used to separate each box in the table. If you’re having a problem with your table columns rendering oddly, make sure that you have the same number of vertical bars for each row.

The table will render with a title and a header row:

Table 7-1. An example table
P	Q	P^Q
T	T	T
T	F	F
F	T	F
F	F	F

Code

Code blocks (or as the AsciiDoctor documentation refers to them, “listing” blocks), are defined using four hyphens above and below the code block content:

----
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890
----

Which will render like this:

Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890

Formal code blocks (titled and cross-referenced)

If you’d like the code block to have a title and be able to cross-reference it, you should use the formal code block markup. As you can see below, you’ll need to additionally surround the code block with four equals signs, a title, and an ID in double brackets:

[[EX1]]
.A code block with a title
====
----
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890
----
====

The results:

Example 7-1. A code block with a title

Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890

Inline formatting within code

If you want to use inline formatting in code—in particular, to specify typographical conventions such as bold or italic—you can do so by using an HTML passthrough block (see Passthroughs for an explanation of passthroughs). Here’s the markup to use a passthrough with the HTML element <pre>:

++++
<pre data-type="programlisting">hostname $ <strong>date</strong>
<em>Sun</em> Apr  1 12:34:56 GMT 1984</pre>
++++

which may be rendered like this:

hostname $ date
Sun Apr  1 12:34:56 GMT 1984

Angle Brackets in Passthrough Code

If you need to display angle brackets in code that is in a passthrough, make sure to use the entities < (for <) and > (for >) instead of the characters, or you may run into build errors. For example:

++++
<pre data-type="programlisting">&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Title of the document&lt;/title&gt;
&lt;/head&gt;

&lt;body&gt;
The content of the document...
&lt;/body&gt;

&lt;/html&gt;</pre>
++++

will render like this:

<!DOCTYPE HTML>
<html>
<head>
<title>Title of the document</title>
</head>

<body>
The content of the document...
</body>

</html>

Syntax highlighting

The Atlas book-building toolchain supports syntax highlighting via Pygments. You need only add [source] above each code block that should include syntax highlighting and specify the language of the code using the Pygments short name for the lexer. For example:

[source,java]
----
int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;
----

This will render with colors identifying different syntax elements:

int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;

Here is the markup if you want to add syntax highlighting to a formal code block—note the placement of [source] is the same:

[[id_here]]
.Syntax highlighting sample
====
[source,java]
----
int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;
----
====

Pygments supports a wide variety of languages that can be used in [source]; see the full list available on the the Pygments website. Ebook readers that do not have color screens will still display the highlighting, but in more subtle shades of gray.

Note

The color scheme for each code language is consistent across books and cannot be changed at this time.

External code files

There are two ways to include external code files. You can include an external file that is text-only (no markup like line annotations or inline formatting), or you can include an external file marked up with valid XHTML, which can contain inline markup. Callouts will work with either method.

To include an external code file that is text-only (no inline markup besides callouts), use the include:: macro inside of a delimited code block, as shown here:

[source,java]
----
include::code/HelloWorld.java[]
----

For info about using callouts with your external AsciiDoc code file, see Code callouts.

To include an external file that contains inline markup (e.g., line annotations or inline font formatting), use passthrough markup around around the include:: macro, instead of code block delimiters:

++++
include::code/inline_markup.html[]
++++

In the above case, the contents of inline_markup.html would contain only the HTML markup. In our example, which might look something like this:

<pre data-type="programlisting">Roses are <em>red</em>,
   Violets are <em>blue</em>.
Some poems rhyme;
   This one <strong>doesn't</strong>.</pre>

The results will look like this:

Roses are red,
   Violets are blue.
Some poems rhyme;
   This one doesn't.

Code callouts

Code callouts are used to mark specific lines of code with icons keyed to explanatory text outside the code block. These icon pairs function as bidirectional links in electronic PDF and ebooks (i.e., you can click on the icon in the code to jump to the explanation, and vice versa).

Here’s the AsciiDoc markup for code callouts:

----
Roses are red,
   Violets are blue. <1>
Some poems rhyme;
   This one doesn't. <2>
----
<1> Violets actually have a color value of +#9933cc+.
<2> This poem uses the literary device known as a "surprise ending."

The output will include callouts numbers in the code, followed by a numbered list, as shown here:

Roses are red,
   Violets are blue. 
Some poems rhyme;
   This one doesn't.

To use code callouts with an external AsciiDoc code file, add the callout text items below the code block, like so:

[source,java]
----
include::code/HelloWorld.java[]
----
<1> This is number one.
<2> This is number two.

Note

Please ensure that the number of callouts in the code block and the number of callout list items match. If they do not (e.g., if the code has three callouts but the list only explains two of them), the toolchain will generate a link pointing to a nonexistent target.

Cross-References

All references to titled block elements and book components—figures, tables, examples, sections, chapters, parts, and so on—should be marked up as cross-references, not entered as plain text. Cross-reference markup will become a live hyperlink to the target in digital versions and will resolve automatically if you move numbered elements (figures, chapters, etc.) around while editing.

Warning

You should not make untitled elements like paragraphs or lists the targets of cross-references. Properly marked-up cross-references without a valid target will be rendered in PDF output as three question marks ("???").

To insert a cross-reference, follow these steps:

Note the id of the element you are referencing. If the element does not have an id, you will need to add one. For the book to be valid, an id must be unique within the project, have no spaces, and not start with a number. For example, the top line here gives this figure the ID “unique_id”:
```
[[unique_id]]
.Figure title
image::images/figure.png[]
```
Once you have the id, you can insert a cross-reference to that element elsewhere in the text by enclosing the id in double angle brackets, like so:
```
<<unique_id>>
```

The Atlas build system will use this id generate HTMLBook cross-reference markup cross-reference (i.e., an <a> element with proper href value) for you. O'Reilly themes will adjust the text in output if you later move the target or reword its title, and it will work as a hyperlink in digital versions.

The following table shows the text generated from the cross-references in PDFs styled with O'Reilly themes.

Table 7-2. Standard cross-reference formats
Target	Generated Cross-Reference Text
chapter	Chapter 17
table	Table 4-1
figure	Figure 2-3
example	Example 3-5
sidebar	"Fooing the Bar" on page 23
section	"Inline Macros" on page 14

Here are some live examples:

See Indexing for details.
The result is shown in Figure 7-1.

which were generated from this source:

* See <<indexing>> for details.
* The results is shown in <<unique_id>>.

Passthroughs

This section makes several references to “passthroughs.” You can use an HTML passthrough when you’ve got an especially complex piece of markup or you’re trying to do something that our implementation of AsciiDoc doesn’t support. AsciiDoc supports two types of passthroughs:

Inline passthroughs

For inlines, you can indicate a passthrough at any time by adding this passthrough markup within the text paragraph:

pass:[inline HTML markup here]

See Troubleshooting Inline Markup for examples of inline passthroughs.

Block passthroughs

You can also pass through a block of HTML by adding four plus signs above and below the block of HTML. Here’s the image markup that we used above, passed through as HTML:

++++
<figure id="unique_id" float="none">
<figcaption>A Figure</figcaption>
<img alt="A Figure" src="images/tiger.png"/>
</figure>
++++

Math Support via LaTeX

Atlas supports math equations marked up as LaTeX. For inline LaTeX equations, use the latexmath: macro as follows:

The Pythagorean Theorem is latexmath:[\(a^2 + b^2 = c^2\)].

yielding this result:

The Pythagorean Theorem is \(a^2 + b^2 = c^2\) .

For block TeX equations, use a latexmath passthrough as follows:

[latexmath]
++++
\begin{equation}
{x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}}
\end{equation}
++++

And the results:

\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\)

You could also add a title, like this:

[latexmath]
.The quadratic formula
++++
\begin{equation}
{x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}}
\end{equation}
++++

And get:

The quadratic formula

\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\)

Tip

See “Math” for more information.

Controlling Line Breaks

Use an inline passthrough to prevent a line break:

pass:[<span class="keep-together">Don't Break Me</span>] 
pass:[<span class="keep-together"><code>foobar</code></span>

Warning

Please do not use AsciiDoc’s mechanisms for forcing line breaks, as these aren't supported by Atlas’s toolchain.

Indexing

This section describes how to create an automatically generated index in AsciiDoc. We’ve extended indexing in AsciiDoc to include ranges, sees, and see alsos.

Note

During production, a freelance indexer will be hired to index your book, so you may not need to use this markup.

Create the index file

To include an index in your book, first create a ix.html file and add this single line of text:

<section data-type="index"/>

The index entries will be auto-generated during the build process, using the index markers you place in the text, as described in the next section. Just be sure to include the ix.html file in the build.

Syntax

Basic index entry:

((("primary index term")))

Quotation marks around terms are optional for simple entries:

(((XML, RDF, SPARQL)))

However, if you include any attributes (e.g., see, seealso, sortas, or the attributes indicating beginning and end of a range) you must put all terms in quotes:

((("XML", "RDF", "SPARQL", seealso="XQuery")))

Note

For anything not mentioned below, please refer to the Asciidoctor syntax reference.

Secondary entry:

((("primary index term", "subentry")))

Tertiary entry:

((("primary index term", "subentry", "sub-subentry")))

An index entry with a range:

The future of ebooks is HTML5.((("HTML5", id="ix_html5", range="startofrange")))
In the following pages
...
blah blah blah canvas
blah blah blah local storage
blah blah blah geolocation
...
Learn HTML 5 today!(((range="endofrange", startref="ix_html5")))

An index entry without a page number that refers the reader only to another entry in the index:

Flash has been supplanted by HTML5.((("Flash", see="HTML5")))

You can provide a page reference in combination with a reference to another entry in the index with a seealso, like this:

In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", seealso="RepRap")))

The seealso can be applied to a subentry as well:

In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", "3-D", seealso="RepRap")))

To alphabetize an index entry according to a spelling different from that of the term, assign the spelling to the sortas attribute:

Makerbot lets you produce your own 3-D trinkets.((("3-D", sortas="three-d")))

¹Otherwise you’ll introduce extra space in the text