[[blocks_notes_markers]]
== Blocks, notes and markers

RISC-V specifications are notable for their extended commentaries that explain the thinking behind various important aspects of the technologies.

In most cases, contributors should make use of admonition blocks for their commentaries.


=== Blocks

Asciidoctor allows for many types of blocks, as documented at https://docs.asciidoctor.org/asciidoc/latest/blocks/.

==== Sidebars

Sidebars provide for a form of commentary.

[source,adoc]
----

****
This is content in a sidebar block.

image:example-3.svg[]

This is more content in the sidebar block.
****
----

This renders as follows:

****
This is content in a sidebar block.

image:example-3.svg[]

This is more content in the sidebar block.
****


You can add a title, along with any kind of content. Best practice for many of the "commentaries" in the LaTeX source that elucidate the decision-making process is to convert to this format with the `TIP` icon that illustrates a conversation or discussion, as in the following example:

[source,adoc]
----
.Optional Title
****
Sidebars are used to visually separate auxiliary bits of content
that supplement the main text.

TIP: They can contain any type of content, including admonitions like this, and code examples like the following.

.Source code block within a sidebar
[source,js]
/----   (1)
const { expect, expectCalledWith, heredoc } = require('../test/test-utils')
/----  (2)
****

----

1 and 2. Escapes are necessary to preserve this as an AsciiDoc code example.

Once the escapes are removed, the above renders with both the admonition and code blocks within the sidebar:

.Optional Title
****
Sidebars are used to visually separate auxiliary bits of content
that supplement the main text.

TIP: They can contain any type of content, including admonitions like this, and code examples like the following.

.Source code block in a sidebar
[source,js]
----
const { expect, expectCalledWith, heredoc } = require('../test/test-utils')
----
****

==== Admonition blocks

Five kinds of standard admonition blocks are available in asciidoc and these can be mapped to either default or custom icons.

[source,adoc]
----
[NOTE]
====
This is an example of an admonition block.

Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
====
----

This renders as:

[NOTE]
====
This is an example of an admonition block.

Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
====

For a single paragraph admonition, simply use a double colon:

[source,adoc]
----
NOTE: Note content.
----

which renders as:

NOTE: Note content.

Alternate octicons:

* alert-24
* comment-discussion-24
* flame-24
* info-24
* pencil-24
* question-24
* sheild-24
* squirrel-24
* zap-24


Another example of an admonition block:

[source,adoc]
----
[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:

. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
----

Rendered:

[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:

. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====


https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#key-prefix-admonition-icon

The default admonition icons don't look right for RISC-V specification, and alternate icons and colors have been set in risc-v_spec-pdf.yml.  and will be considered.

Current icons, edited to tone down color:

NOTE: note

TIP: tip

WARNING: warning

CAUTION: caution

IMPORTANT: important

[[custom-color-icons]]
.Customized colors for icons
[width="100%",options=header,format=csv]
|===
Icon,default,customized
NOTE,19407c,6489b3
TIP,111111,5g27ag
WARNING,bf6900,9c4d4b
CAUTION,bf3400,c99a2c
IMPORTANT,bf0000,b58f5b
|===

==== Code blocks

AsciiDoc enables code blocks that support syntax highlighting.

For example, preceding a block with a macro `[source,json]` enables `json` syntax highlighting:

[source,json]
----
{
    "weather": {
        "city":       "Zurich",
        "temperature":      25,
    }
}
----

While syntax highlighters for machine code that integrate with the Asciidoctor Ruby toolchain do leave something to be desired, the Rouge highlighter enables line numbers within the code examples.

We are numbering examples as in the following:

[source,adoc]
----
.A spinlock with fences
[source%linenums,asm]
....
          sd           x1, (a1)     # Arbitrary unrelated store
          ld           x2, (a2)     # Arbitrary unrelated load
          li           t0, 1        # Initialize swap value.
      again:
          amoswap.w    t0, t0, (a0) # Attempt to acquire lock.
          fence        r, rw        # Enforce "acquire" memory ordering
          bnez         t0, again    # Retry if held.
          # ...
          # Critical section.
          # ...
          fence        rw, w        # Enforce "release" memory ordering
          amoswap.w    x0, x0, (a0) # Release lock by storing 0.
          sd           x3, (a3)     # Arbitrary unrelated store
          ld           x4, (a4)     # Arbitrary unrelated load
....
----

With the following result:

[[spinlock_fences]]
.A spinlock with fences
[source%linenums,asm]
....
          sd           x1, (a1)     # Arbitrary unrelated store
          ld           x2, (a2)     # Arbitrary unrelated load
          li           t0, 1        # Initialize swap value.
      again:
          amoswap.w    t0, t0, (a0) # Attempt to acquire lock.
          fence        r, rw        # Enforce "acquire" memory ordering
          bnez         t0, again    # Retry if held.
          # ...
          # Critical section.
          # ...
          fence        rw, w        # Enforce "release" memory ordering
          amoswap.w    x0, x0, (a0) # Release lock by storing 0.
          sd           x3, (a3)     # Arbitrary unrelated store
          ld           x4, (a4)     # Arbitrary unrelated load
....


=== Change bars

Change indicators within text files are exceedingly useful and also can be equally complex to implement. Please consider the fact that much of the software programming for Git revolves around handling various kinds of change indicators.

In exploring possible implementation of change bars for RISC-V, we have looked for a solution that is as simple as possible while maximizing value with respect to the time invested in implementing, maintaining, and using the tools and procedures.

The suggested solution makes use of:

- an AsciiDoc `role`.
- modification of two files in the Ruby gem with code snippets (see procedure in the README for https://github.com/riscv/docs-templates).
- Git features.
- a few procedures associated, specifically, with Git updates.

==== Indicate changes

With apologies for requiring a manual step at this time, indicators for the changed lines must be inserted:

[source,adoc]
----
[.Changed]#SELECT clause#

Text without the change bar

[.Changed]#Text with the change bar#
----

[.Changed]#SELECT clause#

Text without the change bar

[.Changed]#Text with the change bar#


For change bars associated with headings, place the change indicator after the heading indicator and before the text, like the following:

----
== [.Changed]#SELECT clause#
----

==== Check for changed lines before a `git commit`

You can double check for all changed lines just before doing a commit, using this pattern:

[source,cmd]
----
git blame <file> | grep -n '^0\{8\} ' | cut -f1 -d:
----

This lists the line numbers of changes within the specified file like the following:

[source,cmd]
----
5
38
109
237
----


=== Footnotes

Asciidoc has a limitation in that footnotes appear at the end of each chapter. Asciidoctor does not support footnotes appearing at the bottom of each page.

You can add footnotes to your presentation using the footnote macro. If you plan to reference a footnote more than once, use the footnote macro with a target that you identify in the brackets.

[source,adoc]
----
Initiate the hail-and-rainbow protocol at one of three levels:

- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.]
- tertiary
- apocalyptic

A bold statement!footnote:disclaimer[Opinions are my own.]

Another outrageous statement.footnote:disclaimer[]
----

Renders as:

The hail-and-rainbow protocol can be initiated at three levels:

- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.]
- tertiary
- apocalyptic

A bold statement!footnote:disclaimer[Opinions are my own.]

Another outrageous statement.footnote:disclaimer[]

=== Index markers

There are two types of index terms in AsciiDoc:

*A flow index term.* appears in the flow of text (a visible term) and in the index. This type of index term can only be used to define a primary entry:

[source,adoc]
----
indexterm2:[<primary>] or ((<primary>))
----

*A concealed index term.* a group of index terms that appear only in the index. This type of index term can be used to define a primary entry as well as optional secondary and tertiary entries:

[source,adoc]
----
indexterm:[<primary>, <secondary>, <tertiary>]
----

--or--

[source,adoc]
----
(((<primary>, <secondary>, <tertiary>)))
----

[source,adoc]
----
The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)), <1>
was to carry Excalibur (((Sword, Broadsword, Excalibur))). <2>
That is why I am your king. Shut up! Will you shut up?!
Burn her anyway! I'm not a witch.
Look, my liege! We found them.

indexterm2:[Lancelot] was one of the Knights of the Round Table. <3>
indexterm:[knight, Knight of the Round Table, Lancelot] <4>
----

<1> The double parenthesis form adds a primary index term and includes the term in the generated output.
<2> The triple parenthesis form allows for an optional second and third index term and does not include the terms in the generated output (a concealed index term).
<3> The inline macro `indexterm2\:[primary]` is equivalent to the double parenthesis form.
<4> The inline macro `indexterm:\[primary, secondary, tertiary]`` is equivalent to the triple parenthesis form.

If you’re defining a concealed index term (the indexterm macro), and one of the terms contains a comma, you must surround that segment in double quotes so the comma is treated as content. For example:

[source,adoc]
----
I, King Arthur.
indexterm:[knight, "Arthur, King"]
----

I, King Arthur.
indexterm:[knight, "Arthur, King"]

--or--

[source,adoc]
----
I, King Arthur.
(((knight, "Arthur, King")))
----

I, King Arthur.
(((knight, "Arthur, King")))

=== Bibliography and references

There are two ways of handling bibliographies:

- making manual entries to which you can create links from the text in the body of your document.
- using automated features provided by asciidoctor-bibtex[]

You can add bibliographic entries to the last appendix that you use in a book document.

==== Automated bibliography procedures with asciidoctor-bibtex

Asciidoctor-bibtex enables options that allow for establishing a single source of bibliographic entries that we can use for RISC-V specifications. As an added benefit we can make use of existing bibtex files.

For asciidoctor-bibtex to work, please install the Ruby gems as documented in the docs-templates README file.

NOTE: This has now been tested and is the preferred procedure for adding a bibliography.

The doc header file in the docs-templates repo now contains the following attributes for the purpose of implementing a bibliography using asciidoctor-bibtex:

[source,adoc]
----
:bibtex-file: resources/references.bib
:bibtex-order: alphabetical
:bibtex-style: apa
----

The repo also contains the most recent version of the `riscv-spec.bib` file for asciidoctor-bibtex to use while building the bibliography.

When you run asciidoctor-bibtex as part of the build, it searches for the bibtex file first in the folder and subfolders of the document header, and then in `\~/Documents`."

Within your text, add author-year references using the pattern:

[source,adoc]
----
 cite:[riscvtr(12)]
----

with the result, cite:[riscvtr(12)]

Add age numbers (locators) using the pattern:

[source,adoc]
----
cite:[Kim-micro2005(45)]
----

with the result: cite:[Kim-micro2005(45)]

Add pretext using the pattern:

[source,adoc]
----
cite:See[Kim-micro2005(45)]
----

with the result: cite:See[Kim-micro2005(45)]

It's possible to include other files, which are also processed.

[CAUTION]
=====
To prevent problems with other appendices, keep the index as the second-to-last appendix and the bibliography as the last appendix in your list of included chapter sections within the book-header file.

Citations must be contained within a single line.
=====

The bibliography section of the book must be set up as follows, to receive the entries during the build:

[source,adoc]
----
== Bibliography

bibliography::[]
----

WARNING: When using the automated option, _do not_ manually add entries to the `bibliography.adoc` file.

Following are example json-formatted bibliographic entries:

[source,json]
----
@book{Lane12a,
	author = {P. Lane},
	title =	 {Book title},
	publisher = {Publisher},
	year =	 {2000}
}

@book{Lane12b,
	author = {K. Mane and D. Smith},
	title =	 {Book title},
	publisher = {Publisher},
	year =	 {2000}
}

@article{Anderson04,
	author = {J. R. Anderson and D. Bothell and M. D. Byrne and S. Douglass and C. Lebiere and Y. L. Qin},
	title = {An integrated theory of the mind},
	journal = {Psychological Review},
	volume = {111},
	number = {4},
	pages = {1036--1060},
	year = {2004}
}
----

==== Manual bibliography procedures

While the automated procedure and use of the RISC-V bibtex file is preferred, it is also possible to manually create and reference a bibliography.

Text with markup that will generate links:

[source,adoc]
----
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.
----

Links from within text to bibliographic entries:

[source.adoc]
----
[[bibliography]]
== References

* [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
From Journeyman to Master. Addison-Wesley. 1999.
* [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides.
Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
----

Text that links to bibliography:

[source,adoc]
----
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.
----
