Often nonfiction books need a glossary. AsciiDoc makes it easy to add a glossary. By way of example, let’s define glossary and term so you can see how asciidoctor renders a glossary term.

glossary

An alphabetical list of terms or words found in or relating to a specific subject, text, or dialect, with explanations; a brief dictionary.

term

A word or phrase used to describe a thing or to express a concept, especially in a particular kind of language or branch of study.

The Easy Way—​Inline

You can include a glossary of terms and definitions by including the [glossary] marker before the section header.

[glossary] (1)
== Glossary (2)

draft:: (3)
   The book's content at a particular point in time. Typically a first draft is followed by later drafts. The final draft is self-published. (4)

draft:: The book's content at a particular point in time. Typically a first draft is followed by later drafts. The final draft is self-published. (5)
  1. The glossary marker for asciidoctor to identify this section as the glossary.

  2. The chapter or section title (depends on the number of equal signs you use).

  3. The term, separated by double colons "::"

  4. The definition.

  5. Although you can stuff both the term and the definition all on the same line, it makes the AsciiDoc plain text file harder for humans to read.

A Harder Way to Organize Glossary Terms for Reuse

AsciiDoc also makes it easy to reuse a glossary entry (a term + its definition) from a small text file. This is how I use glossary terms.

If you’re just writing one book, there is no need for this.

=== E (1)

include::ebook.adoc[] (2)
  1. My book’s glossary is separated by letter headings.

  2. I use the asciidoctor "include::" command to tell the rendering app to include everthing in that text file called draft.adoc.

Inside that separate file, I have only my term and its definition.

eBook::
  An electronic version of a book that is read using mobile devices with reader apps or on a laptop or desktop if a reader app is installed. It is essentially a self-contained website in a zip file.

I include a blank line before each glossary entry (term + definition) so they don’t run together when rendered all in the same location.

This allows me to organize all my glossary entries in a single folder.

media\GlossaryItemsOrganization
Figure 1. Glossary Files

And it still renders all together.

media\HTMLGlossaryTerms
Figure 2. HTML Version of Glossary Entry

And finally, this method of glossary chunking allows me to have a single source for definitions that can be referenced in the book in multiple places if necessary.

Image

Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview