Chapter 4. AsciiDoc 101

AsciiDoc is a text document format for writing (among other things) books, ebooks, and documentation. It’s similar to wiki markup—if you can write a Wikipedia article, then you’ll have no problem with AsciiDoc. The main advantages of AsciiDoc are that it is easy to use and plays well with O’Reilly’s publishing tools, including Atlas.

Use the Source, Luke

If you’re viewing this document as a PDF, EPUB, or KF8, you’re seeing the output from the AsciiDoc source, rather than the AsciiDoc markup itself. Since this chapter is intended as an introduction to the markup, it may be helpful to view the source, available at cdn.oreilly.com/atlas_docs.zip.

How Do I Get Started Writing?

There are two ways you can write with AsciiDoc in Atlas:

  1. Write directly in the Atlas web interface. Simply click on the "Write" tab in Atlas. Select an existing chapter file to edit, or choose "New File" to create one.
  2. Write in a text editor and add it to Atlas. You can add text to Atlas by pasting the text directly into the writing interface or by using git (see Chapter 5) to push your local .asciidoc files to the Atlas repository.

Notes to Production

To leave a note to the Production team, please use a passthrough block with the Docbook <remark> element, like this:

++++
<remark>Use a passthrough block like this for notes to production staff</remark>
++++

AsciiDoc does have specific markup for comments (two slash characters, like this: //, followed by the comment text), but they do not get passed to the DocBook output by default. In order to make sure the Production team sees your comments, please use the DocBook passthrough method listed above. (See “Passthroughs” for more info on DocBook passthroughs.)

AsciiDoc Markup Reference

This section illustrates some of the most common elements used in writing technical documentation. The AsciiDoc User Guide and the AsciiDoc cheat sheet are other helpful references, but the following sections will give you an overview of the markup you’ll use most frequently, plus some customized markup that is specific to Atlas.

If you can’t find what you’re looking for here or if you just need a quick answer, please don’t hesitate to email our support team at .

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 markup such as italics to your text see the “Inline Markup” section below.

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 string above the chapter title, surrounded in 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 that 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 DocBook <sect1>).

Top-level heading

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

=== Top-Level Heading

Second-level heading

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

==== Second-Level Heading

Third-level heading

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

===== Third-level heading

Parts

If you want to group your chapters into parts, navigate to the file that should be the first chapter in that part, and add the part markup above the chapter title. It’s good practice to always include a unique ID string above the part title, like so:

[[unique_part_id]]
= Part Title

[[unique_chapter_id]]
== Chapter Title

Chapter text begins here.

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

[[unique_part_id]]
= Part Title

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

[[unique_chapter_id]]
== Chapter Title

Chapter text begins here.

Prefaces

A preface file should begin with the word 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

Forewords are treated as prefaces, except they have a title of Foreword. For example:

[preface]
== Foreword

Foreword text begins here.

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:

[preface]
[role="afterword"]
== Afterword

Afterword text begins here.

Dedications

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

[dedication]
== Dedication

This book is dedicated to my cat, Garfield.

Dedication pages render on their own page at the beginning of the book, before the table of contents.

Praise Pages

Praise pages are marked up similarly to “Dedications”, but you will add a special role="praise" attribute. For each item of praise, use the quote markup (discussed in “Quotes”):

["dedication", role="praise"]
== Praise for Getting Started with Atlas

[quote, Jane Doe]
____
"This book is awesome."
____

Praise pages render at the beginning of the book, before the title page, and are not included in the regular page numbering of the book.

Glossaries

A glossary file should begin with the word glossary in double brackets, followed by the glossary title and a blank line. Following the blank line should be another instance of the word 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, simply add the word appendix in single brackets at the top of the file. Immediately below it should be the title of the Appendix. For example:

[appendix]
== Resources

The following list of resources ...

Chapter Contributors

For books with multiple contributors, you may want an author name to appear with each chapter. Simply add the following markup above each chapter title:

[au="Author Name"]
== Chapter Title

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

[au="Author Name", au2="Another Author", au3="Last Author"]
== Chapter Title

You can also use this same markup for forewords, prefaces, and appendixes. Please note that contributor names in a foreword will render at the end of the foreword, right-aligned, and preceded by an em dash. Foreword author attributions can also include an affiliation. The markup looks like this:

[au="Author Name", auaffil="Editor, Such and Such Journal"]

Inline Markup

Here are some standard O’Reilly typographical conventions with explanations of 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. Note that O'Reilly house style prefers italics for emphasis. The AsciiDoc markup is one asterisk on either side of the text to be bolded.

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 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

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.

Notes, Tips, Warnings, and Cautions

You have the option of using note, tip, warning, and caution elements for supplemental information. Please note that the O’Reilly stylesheets make no visual distinction between the way warning and caution elements render, as well as the way note and tip elements render.

You may also notice that some of the admonitions below have a title. We do support optional titles in admonitions (in most series). If you don’t want a title for your note, tip, warning, or caution, 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:

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:

Titled Tip

Here’s some text inside a tip.

Or you could use a warning:

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

Titled Warning

This is how warnings render. Warnings can be used for including supplemental information in your text. Including a warning title is optional.

Finally, here’s a caution:

[CAUTION]
====
Here's some text inside a caution.
====

This is how cautions render. Cautions can be used for including supplemental information in your text.

Footnotes

To create a footnote, place the footnote macro directly after the text where the note number should appear, with no space between.[2] 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 “Footnotes” 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 word 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

Full figure markup should include a unique ID attribute, so the figure can be cross-referenced (see “Cross-References” for more info on using cross-references). Please note the figure IDs should be unique throughout the book. Non-captioned figures don’t have ID attributes or figure numbers and are not cross-referenced.

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 4-1. An example 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, these figures will also have no figure number and cannot be cross-referenced in the body of the text.

Here’s the markup:

image::images/screenshot.png["Screenshot of the AsciiDoc website."]

And here’s how it renders:

Screenshot of the AsciiDoc website.

Figure floating

Figures appear exactly where you place them in the text, which can sometimes create PDF pages with a lot of white space. While it is not generally necessary, you can add an attribute of float="true" so that the text flows around the image:

[[unique_id]]
.A Figure
[float="true"]
image::images/tiger.png[]

To combine a float attribute with alt text, see “Adding alt text an images” below.

Adding alt text an 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"]

Please note, to combine the alt-text attribute with a float="true" attribute, use the following markup:

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

Adjust image size

While it should not be necessary in most circumstances, you can control the size of an image in the PDF output by adding an absolute value of width or height, like so:

image::images/filename.png[width="2in"]

image::images/filename.png[height="2in"]

Or you can use scale as a percentage to limit the width:

image::images/filename.png[scale="75"]

Note that you should not include a percentage sign.

Lists

There are three common types of lists. The O’Reilly Stylesheet and Word List has more details about when to use them, but here’s the markup and an example of each.

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.

The list renders as you’d expect:

  • 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 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:

  1. Preparation
  2. Assembly

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

    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 can be used to add additional 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 look like this:

Term 1
Definition/description
Term 2
Something else

Tables

Atlas table styles vary slightly between series. If your material warrants something other than the default style as shown in Table 4-1, please consult with your editor.

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 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 you have that you have the same number of vertical bars for each row.

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

Table 4-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 AsciiDoc 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 4-1. A code block with a title
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890

Inline formatting within code

In AsciiDoc, there is no built-in mechanism for inline formatting within code.[3] If you want to use inline formatting—in particular, for standard O’Reilly typographical conventions such as <userinput> (CW+bold) and <replaceable> (CW+italic) or if you want to include line annotations—you can do so by using a passthrough block (see “Passthroughs” for an explanation of passthroughs). Here’s the markup to use a passthrough with the DocBook element <screen>:

++++
<screen>hostname $ <userinput>date</userinput>
Sun Apr  1 12:34:56 GMT 1984</screen>
++++

which renders like this:

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

And here’s the markup to use a passthrough with the <programlisting> and <lineannotation> DocBook elements:

++++
<programlisting>from __future__ import with_statement # This isn't required in Python 2.6
                     <lineannotation>Above is a comment in the code, while this is an "annotation"</lineannotation>

with open("<replaceable>hello.txt</replaceable>") as f:
    for line in f:  <lineannotation>(note regular italic here vs. constant-width in "hello.txt" on line above)</lineannotation>
        print line</programlisting>
++++

which renders like this:

from __future__ import with_statement # This isn't required in Python 2.6
                     Above is a comment in the code, while this is an "annotation"

with open("hello.txt") as f:
    for line in f:  (note regular italic here vs. constant-width in "hello.txt" on line above)
        print line

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. For example:

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

This will render in the EPUB, PDF, and KF8 (Kindle Fire only) as follows:[4]

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.

Please note the following caveats:

  • The color scheme is consistent across books and cannot be changed at this time.
  • Unless your book is printing in color, the PDF used for print will contain no highlighting.

Code line length

The allowed number of characters per line of code varies depending on the book series and where the code is positioned in the markup. The following table lists some common cases.

Please keep in mind that these are just the maximum characters allowed. You should review your PDFs and make your own judgments about the best way to present code to the reader.

Series Body (top-level code) Examples Lists Sidebars/notes/warnings

Animal or Cookbook

80

85

76

74

Small Animal (6x9)

64

68

60

58

Theory in Practice

85

90

80

72

Nutshell

76

80

72

66

Pocket Reference

52

56

48

46

Hacks

76

80

72

70

Please rebreak any code lines that exceed the max number of characters; otherwise, the code will run into the margin in your PDFs, which is unacceptable for print. It’s best to fix long code lines in the manuscript stage, while you still have access to the source. Making such edits during Production is much more cumbersome for everyone involved.

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 Docbook, 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.txt[]
++++

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

<programlisting>Roses are <replaceable>red</replaceable>,
   Violets are <replaceable>blue</replaceable>. <lineannotation>This is a line annotation</lineannotation>
Some poems rhyme;
   This one <userinput>doesn't</userinput>.</programlisting>

The results will look like this:

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

Code snippets

Atlas now supports including “snippets” in your book content so that you can excerpt just a portion of a code listing from an external code file.

The code snippet functionality is currently in beta. Feedback is welcome.

Each snippet that you’d like to pull into the book content must be delimited with BEGIN identifier and END identifier comment lines, where identifier is a unique identifier for the given snippet. Here is a sample JavaScript file with one snippet:

Example 4-2. factorial.js
alert("This code has a snippet below!");
factorial(3);

// BEGIN FACTORIAL_FUNC
function factorial(number) {
    if (number == 0) {
       return 1
       } else {
        return factorial(number - 1) * number
  }
}
// END FACTORIAL_FUNC

To include this snippet in an AsciiDoc file, add the following block:

[filename="factorial.js", language="js", identifier="FACTORIAL_FUNC"]
snippet~~~~
Put any descriptive text you want here. It will be replaced with the
specified code snippet when you build ebook outputs
snippet~~~~

When the ebook is generated, the following output will be present in place of the snippet block:

function factorial(number) {
    if (number == 0) {
       return 1
       } else {
    return factorial(number - 1) * number
  }
}

The filename attribute references the external file containing the snippet. Paths to filenames should be relative to the AsciiDoc file to which you’re adding the snippet. So if you’ve got all your book files in the repository root directory, and all your code files in a code directory in the root directory, your filename attribute will look like filename="code/filename.js".

The language attribute is the programming language of the code snippet you’re including. Current supported language values are:

  • clj (clojure)
  • css
  • groovy
  • html
  • java
  • js (javascript)
  • pl (perl)
  • py (python)
  • rb (ruby)
  • scala
  • xml

If you’d like support added for another programming language, please give us feedback.

The identifier attribute references the unique identifier used in your snippet delimiters.

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 downstream formats (i.e., you can click on the icon in the code to jump to the explanation, and vice versa).[5]

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. 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."

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.

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.

To insert a cross-reference, follow these steps:

  1. 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, ids must be unique across the entire book, have no spaces, and not start with a number. For example, a figure id looks like this:

    [[unique_id]]
        .Figure title
        image::images/figure.png[]
  2. 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 transform this ID into a standard cross-reference (or <xref>) for you: the rendered text will adjust automatically if you later move the target or reword its title, and it will work as a hyperlink in digital versions.

Table 4-2 shows the standard text generated from the cross-references in PDF builds.

Table 4-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

"Fooing the Bar" on page 23

section

"Inline Macros" on page 14

Here are some live examples (hover over the text in the PDF to locate the hyperlink):

which were generated from this source:

* See <<indexing>> for details.
* The results is shown in <<unique_id>>.
* Flip ahead to <<working_with_github>> for a preview.

Passthroughs

Chapter 4 makes several references to “passthroughs.” You can use a DocBook passthrough when you’ve got an especially complex piece of markup or you’re trying to do something that 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 DocBook markup here]

See “Troubleshooting Inline Markup” for examples of inline passthroughs.

Block passthroughs

You can also pass though a block of DocBook XML by adding 4 plus signs above and below the DocBook. Here’s the image markup that we used in Chapter 4, passed through as DocBook:

++++
<figure id="unique_id" float="none">
<title>A Figure</title>
<mediaobject>
  <imageobject>
  <imagedata fileref="images/tiger.png"/>
  </imageobject>
</mediaobject>
</figure>
++++

Math Support via LaTeX

Atlas supports math equations set 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:

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

You could also add a title. Use this:

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

And get:

Equation 4-1. The quadratic formula
\begin{equation} {x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}} \end{equation}

Page Breaking

If you want to insert a hard page break into your PDF builds, you can do so with this passthrough:

++++
<?hard-pagebreak?>
++++

Please note that adding this page break processing instruction will have no effect on the EPUB and KF8 files.

Please do not use AsciiDoc’s mechanisms for forcing page breaks, as these don’t mesh with Atlas’s book building tools.

Controlling Line Breaks

Use an inline passthrough to prevent a line break:

pass:[<phrase role='keep-together'>Don'tBreakMe</phrase>]

Please do not use AsciiDoc’s mechanisms for forcing line breaks, as these don’t mesh with Atlas’s book building tools.

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.

Create the index file

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

== 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 index.asciidoc file in the build.

See the AsciiDoc source of this documentation for an example index.

Syntax

Each index marker is generally surrounded with quotation marks. But 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 as seen below, e.g.:

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

For anything not mentioned below, please refer to the AsciiDoc User Guide, or contact us if you have index entries with special characters (e.g., quote marks, commas) and need guidance on how to format the markup.

Basic index entry:

((("primary index term")))

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 with a “(see)” and no page reference:

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

An index entry with a “(see also)”:

There are two markup options for "see also" entries.

  • You can embed the seealso with the primary entry. This will render a page number next to the primary entry:
In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", seealso="RepRap")))
  • Or if there’s a subentry, you can embed the seealso entry after the it:
In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", "3-D", seealso="RepRap")))

Any "(see also)" entries that are nested under primary entries with no page numbers of their own (i.e., primary entries that have subentries) will render with extra indentation.

To alphabetize an index entry differently than the default, use "sortas" to assign a new label to be used for alphabetization. For example:

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


[2] Otherwise you’ll introduce extra space in the text

[3] We do support [subs="quotes"] markup in passthrough blocks, but note that this markup can become complicated. Contact with any questions.

[4] If you are viewing the HTML version of these guidelines on Chimera, syntax highlighting will not be shown.

[5] The built-in AsciiDoc mechanism is somewhat more limited in that icons are hyperlinked from text to code, but not vice versa. If two-way linking is important to you, consider using a passthrough block (see “Passthroughs”).