[[a_few_basics]]
== 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:

 * Asciidoc/asciidoctor https://asciidoctor.org/docs/asciidoc-writers-guide/[writers' guide].
 * Asciidoc http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference].
 * Asciidoctor http://asciidoctor.org/docs/user-manual/[user manual].

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 help@riscv.org
====

=== 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,adoc]
----
[source,python]
....
mono-spaced code block
add a1,a2,a3; # do an ADD
....
----

renders as follows:

[source,python]
----
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.

```adoc
= 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:

[source,adoc]
----
https://asciidoctor.org[Asciidoctor]
----

You can set https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[attributes for your external links]


==== Cross references

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

[source,adoc]
----
<<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:

[source,adoc]
----
The table below, <<trapcharacteristics,Characteristics of traps>> shows the characteristics of each
kind of trap.
----

[source,adoc]
----
[[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, <<trapcharacteristics>> shows the characteristics of each
kind of trap.

[[trapcharacteristics]]
.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
|===

=== 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 https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install.

[source,adoc]
----
[stem]
++++
sqrt(4) = 2
++++
----

[stem]
++++
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 https://github.com/asciidoctor/asciidoctor-pdf/issues/486

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

Updates to asciidoctor-pdf: https://github.com/asciidoctor/asciidoctor-pdf


