Skip to content

Latest commit

 

History

History
187 lines (125 loc) · 5.59 KB

a_few_basics.adoc

File metadata and controls

187 lines (125 loc) · 5.59 KB
Raw

A few AsciiDoc basics

AsciiDoc is fully documented, and its documentation is actively maintained. This document contains some information on asciidoc markup to get you started.

For details and additional options, see:

In addition, you have the option of asking questions in the asciidoctor discussion list:

As is true of any complex process, asciidoc/asciidoctor has some quirks. Please be certain to make use of these templates because they provide you with files that will result in fully featured pdf output.

Best practice is to test the pdf build frequently to ensure that you have not accidentally introduced something that breaks the build.

Warning
 PDF generation currently requires the use of Ruby 2.7.2.
Note

Please feel free to send questions to [email protected]

Paragraphs

In AsciiDoc, normal paragraphs require no markup at all.

Basics of blocks and indents

If you simply add an indent, your indented text becomes a block like this.

  • You can add indented, explanatory paragraphs to lists.

    Add a + directly above the line of text that you want to be indented within the list.

  • Another point.

    Using the + to create an indented paragraph only works within the context of a numbered or bulleted list.

Asciidoc/asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:

[source,python]
....
mono-spaced code block
add a1,a2,a3; # do an ADD
....

renders as follows:

mono-spaced code block
add a1,a2,a3; # do an ADD

See [blocks_notes_markers] for additional information on blocks.

Headers

While authoring in asciidoc, you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, asciidoctor throws an error.

Following is an axample of a valid sequence of headers.

= Title head (book or report title)

[colophon]
= Colophon head (in frontmatter, used for preface)

[[chapter_title]]
== Head 1 (chapter)

=== Head 2 (section)

==== Head 3 (subsection)

===== Head 4 (sub-subsection)

[appendix]
== Appendix title

[index]
Index
Note
 Settings in the header file (book_header.adoc in the docs-templates repo) trigger auto-generation of Appendix prefixes and of the Index (among other things).

Hyperlinks and cross references

Asciidoctor automates some linking as follows:

  • Asciidoctor recognizes hyperlinks to Web pages and shortens them for readability.

  • Asciidoctor automatically creates an anchor for every section and discrete heading.

Hyperlinks

To create highlighted links, use the pattern in the following example:

https://asciidoctor.org[Asciidoctor]

Cross references

Use macros for cross references (links within a document) as in the following example:

<<Index markers>> describes how index markers work.

This renders as:

[Index markers] describes how index markers work.

The book_header.adoc file in the docs-templates repo sets the full cross reference attribute to enable the display of captions from targets in the anchors. This allows you to set captions for tables, blocks, and illustrations. If no caption is provided, Asciidoctor defaults to the basic cross reference style.

To set a caption for a table or image, use the pattern as follows:

The table below, <<trapcharacteristics,Characteristics of traps>> shows the characteristics of each
kind of trap.
[[trapcharacteristics,Characteristics of traps]]
.Characteristics of traps.
[cols="<,^,^,^,^",options="header",]
|===
| |Contained |Requested |Invisible |Fatal
|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes
|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$]
|Handled by environment |No |Yes |Yes |Yes
|===

The table below, Characteristics of traps. shows the characteristics of each kind of trap.

Table 1. Characteristics of traps.
Contained Requested Invisible Fatal

Execution terminates

No

No\(^{1}\)

No

Yes

Software is oblivious

No

No

Yes

Yes\(^{2}\)

Handled by environment

No

Yes

Yes

Yes

Stem content

The :stem: latexmath setting makes use of asciidoctor-mathematical for asciidoctor-pdf output.

Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the README in the RISC-V docs-templates repo for information on the asciidoctor-mathematical install.

[stem]
++++
sqrt(4) = 2
++++
\$sqrt(4) = 2\$

In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf currently only supports decimal character references. See asciidoctor/asciidoctor-pdf#486

Hexadecimal unicode looks like it has problems in the pdf. This is gnarley.