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.

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

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 decisionmaking process is to convert to this format with the TIP icon that illustrates a conversation or discussion, as in the following example:

.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')

****

The above renders as:

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

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.

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

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:

[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

Table 1. Customized colors for icons

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:

{
    "weather": {
        "city":       "Zurich",
        "temperature":      25,
    }
}

Change bars

Change indicators within text files are exceedlingly 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 possbile 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:

[.Changed]#SELECT clause#

Text without the change bar

[.Changed]#Text with the change bar#

SELECT clause

Text without the change bar

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:

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

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

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.

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:

double^[1]
tertiary
apocalyptic

A bold statement!^[2]

Another outrageous statement.^[2]

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:

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:

indexterm:[<primary>, <secondary>, <tertiary>]

--or--

(((<primary>, <secondary>, <tertiary>)))

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)

The double parenthesis form adds a primary index term and includes the term in the generated output.
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).
The inline macro indexterm2\:[primary] is equivalent to the double parenthesis form.
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:

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

I, King Arthur.

--or--

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

I, King Arthur.

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

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

: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 asciidocotor-bibtex to use while building the bibliogrpahy.

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:

 cite:[riscvtr(12)]

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

Add age numbers (locators) using the pattern:

cite:[Kim-micro2005(45)]

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

Add pretext using the pattern:

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 to prevent problems with other appendices, leave keep the index as the second-to-last appendix and the bibliography as the last appendix in you 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:

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

@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 bibliogprapy.

Text with markup that will generate links:

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

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

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

1. The double hail-and-rainbow level makes my toes tingle.

2. Opinions are my own.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

blocks_notes_markers.adoc

blocks_notes_markers.adoc

Blocks, notes and markers

Blocks

Sidebars

Admonition blocks

Code blocks

Change bars

Indicate changes

Check for changed lines before a `git commit`

Footnotes

Index markers

Bibliography and references

Automated bibliography procedures with asciidoctor-bibtex

Manual bibliography procedures

Files

blocks_notes_markers.adoc

Latest commit

History

blocks_notes_markers.adoc

File metadata and controls

Blocks, notes and markers

Blocks

Sidebars

Admonition blocks

Code blocks

Change bars

Indicate changes

Check for changed lines before a git commit

Footnotes

Index markers

Bibliography and references

Automated bibliography procedures with asciidoctor-bibtex

Manual bibliography procedures

Check for changed lines before a `git commit`