[[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 can ask questions in the https://discuss.asciidoctor.org/[Asciidoctor discussion list].

As is true of any complex process, AsciiDoc/Asciidoctor has some quirks. Please be certain to use the templates, as the templates provide you with files that 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]
====
Send questions to help@riscv.org.
====

=== Paragraphs

In AsciiDoc, normal paragraphs do not require markup.

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

This example renders as follows:

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

See <<blocks_notes_markers>> for additional information about blocks.

=== Headers

When you author 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.

The following example is 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).

=== Lists

Unordered list
* Priv
* Unpriv
* Debug

Ordered list
. Priv
. Unpriv
. Debug

Nested list
* Priv
** Intro
*** Definitions
** CSRs
* Unpriv

Add a title to a list
.Ordered list
. Priv
. Unpriv
. Debug

=== 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 example 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 captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, 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 following table, <<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 following table, <<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
|===
