Chapter 2. AsciiDoc Indexing Guidelines

Indexing Syntax

Index entries should be added inline in a text block using the syntax described below.

Basic Index Entry

((("primary index term")))

Secondary Entry (Subentry)

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

Tertiary Entry (Sub-subentry)

((("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 with a "(see)" and No Page Reference

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

Changing How an Entry Is Alphabetized

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

A "(see also)" Entry

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

For basic index entries without attributes (i.e., without ranges, a "see", a "see also", or a "sortas"), you do not need to enclose terms in quotation marks. For example, the following markup is fine:

(((XML, RDF, SPARQL)))

However, if you include any attributes, you must put all entries in quotes, e.g.:

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

Otherwise, entries will not be converted properly to DocBook and the PDF output.

An Entry with Special Characters

Often the entry will appear in the index, but the character will be missing. For example, this markup:

((("# symbol")))

will generate just the word "symbol" in the index, without the "#".

First try escaping the character:

((("\# symbol")))

If that doesn’t work, try an inline passthrough (three plus signs on either side):

((("+++#+++ symbol")))

Note this only works on special characters in indexterms, not in attributes. See “Dos and Don’ts” for more about what not to put in attributes.

Please refer to the AsciiDoc User Guide or contact mailto:toolsreq@oreilly.com if you need further guidance on how to format the markup.

Dos and Don’ts

One downside of indexing in the current version of Atlas is that it permits PDF builds even if the files contains validity errors. Our in-house production tools do not allow builds if the files contain validity errors. This can lead to cases where an indexer generates a perfectly nice-looking index in Atlas and sends the files back to the Prod Ed, only to have the Prod Ed run into errors when trying to make a PDF with our tools.

If you are interested in setting up a local toolchain for validation purposes, we’d be happy to help with the setup. Just send a note to .

You can steer clear of validity errors by keeping the following in mind. See the Chapter 1 for more general dos and don’ts.

Don’t put spaces between index markers

Bad:

Para ends here. ((("XHTML"))) ((("widgets")))

Good:

Para ends here.((("XHTML")))((("widgets")))

Don’t use duplicate IDs

Bad:

((("XHTML", id="ix_XHTML", range="startofrange"))) ((("widgets", id="ix_XHTML", range="startofrange")))

Good:

((("XHTML", id="ix_XHTML", range="startofrange")))((("widgets", id="ix_widgets", range="startofrange")))

Don’t omit the commas between attributes

Bad:

((("XHTML" id="ix_XHTML" range="startofrange")))

Good:

((("XHTML", id="ix_XHTML", range="startofrange")))

Don’t put spaces or special characters in id/startref attributes

Use underscores between words instead of spaces in attributes, and don’t use symbols or punctuation (parentheses, equals signs, etc.), although these can go in the actual indexterms. In other words the id and startref attributes should only contain letters, digits, and underscores. Since they are only used as internal links, it’s fine if they don’t match the indexterm values precisely.

Bad:

((("getElementById() method", id="getElementById() method", range="startofrange")))

Good:

((("getElementById() method", id="getElementById_method", range="startofrange")))

Bad:

((("fixed layouts", id="ix_fixed layouts", range="startofrange")))

Good:

((("fixed layouts", id="ix_fixed_layouts", range="startofrange")))

Don’t put indexterms in figures, titles, or code

Put the terms in a nearby para instead.

Bad:

[[structural_semantics_vocabulary]]
.Example of typical property definitions found in the Structural Semantics Vocabulary
image::images/epbp_0301.png ((("property definitions")))

Para starts here.

Good:

[[structural_semantics_vocabulary]]
.Example of typical property definitions found in the Structural Semantics Vocabulary
image::images/epbp_0301.png

((("property definitions")))Para starts here.

Don’t have startrefs that point to non-existent ids

Make sure each end marker’s startref matches some starting marker’s id, and vice versa.