[[tables_symbols_graphics]]
== Tables, symbols, and graphics

Asciidoc makes standard tables easy and also supports the creation of complex tables.

[WARNING]
====
*Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph.
====

=== More on examples

AsciiDoc tables can also be created directly from CSV data. Just set the format block attribute to CSV and insert CSV data inside the block delimiters directly:

[source,adoc]
----
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
----

The above renders as follows:

[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===


There are numerous formatting options available. While some of the property settings are cryptic, they can be quite useful. There are numerous examples available at https://asciidoc.org/newtables.html. Here one example of what can be done with spans alignment in tables from that page:

[source,adoc]
----
[cols="e,m,^,>s",width="25%"]
|============================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|============================
----

Which renders as follows:

[cols="e,m,^,>s",width="25%"]
|============================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|============================

Following is code for a numbered encoding table with link target.

NOTE: Annotations have been added to the code to illustrate their use.

[source,adoc]
----
[[proposed-16bit-encodings-1]  <1>
.proposed 16-bit encodings-1    <2>
[width="100%",options=header]
|===
|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction
3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1
3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2
3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3
17+|This row spans the whole table
3+|100|1|1|1 8+|    field        2+| 00  | mnemonic4
|===
----
. Link target.
. Numbered table title.

[#proposed-16bit-encodings-1]
.proposed 16-bit encodings-1
[width="100%",options=header]
|===
|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction
3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1
3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2
3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3
17+|This row spans the whole table
3+|100|1|1|1 8+|    field        2+| 00  | mnemonic4
|===

=== Unicode symbols

For PDFs, five-digit unicode symbols generally don't work and some other unicode symbols are buggy. This happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it's Prawn that has the problems.

Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful:

As an example, &#9830; is encoded as follows:

```unicode
&#9830;
```

[[useful-unicode]]
.Useful unicode for specifications
[width="100%",options=header,format=csv]
|===
sym,num,name
&#94;,94,caret
&#136;,136,
&#8942;,8942,vdots
&#9830;,9830,name
&#0034;,0034,name
&#x0077;,0077,w
&#8756;,8756,therefore
&#9839;,9839,sharp
&#1096;,1096,shcy
&#982;,982,piv varpi
&#969;,969,omega
&#8472;,8472,weierp wp
&#8721;,8721,sum
&#8734;,8734,infin
&#8747;,8747,integral
&#8800;,8800,not equal to
&#8804;,8804,le
&#8805;,8805,ge
&#8776;,8776,numerical approximation
&#68;,68,mathematical D?
&#8658;,8658,rightwards double arrow
&#88;,88,Latin Capital x
&#967;,967,Greek x
&#215;,215,times
&#9745;,9745,boxed checkmark
&#114;,114,latin small letter r
|===

For many symbols, then, we must turn to asciidoctor-mathematical. See <<Superscripts and other mathematical notations>>.

[[unicode-not-working]]
.Unicode identified as not working
[width="100%",options=header,format=csv]
|===
sym,num,name
&#9084;,9084,angzarr not working
&#8921;,8921,ggg not working
&#8617;,8617,hookleftarrow not working
&#9083;,9083,not checkmark not working
|===

[[graphics]]
=== Graphics

While asciidoc can render graphics in all popular formats, by far the highest quality graphics rendering is from .svg format.

https://wavedrom.com/[WaveDrom sequence diagrams] are essential to the RISC-V specifications. We are in the process of phasing in an automated process for incorporating WaveDrom diagrams into the professional quality pdf output so please stay tuned.

https://asciidoctor.org/docs/asciidoctor-diagram/#image-output-location[Asciidocdoctor-pdf] enables automation of diagrams from scripts, including Wavedrom.

Even as we are using Wavedrom to simplify the creation of accurate SVGs for register diagrams, the graphical elements--those for the various diagrams--add complexity to the build.


==== Automated diagramming

Automated diagramming isn't easy. However, it can be important because some specifications require numerous, very accurate diagrams. Please feel free to ask questions about some of the details in this section.

The https://docs.asciidoctor.org/diagram-extension/latest/[asciidoctor-diagram extension] supports numerous diagram types, including https://wavedrom.com/[WaveDrom] diagramming for sequence and waveform diagrams, and https://graphviz.gitlab.io/[Graphviz digrams], which can be useful for illustrating software, networking, and security concepts.

The requirements for building WaveDrom diagrams are specified in the https://github.com/riscv/docs-templates/blob/main/README.md[docs templates README]. Graphviz does not require anything in addition to asciidoctor-diagram.

NOTE: To ensure findability of graphics source files, store the files in filetype subdirectories within the `images` directory.

ALERT: The build process for automated diagramming places an image file for each diagram into the `images` folder. Please do *not* check any generated image files into the git repository.

==== Wavedrom diagrams in specifications

The following json-formatted script, when added within an asciidoc block with the macro indicators `[wavedrom, ,]`, will embed the diagram output into the pdf:

[source,json]
....
{reg:[
    { bits:  7, name: 0x3b, attr: ['OP-32'] },
    { bits:  5, name: 'rd' },
    { bits:  3, name: 0x0, attr: ['ADD.UW'] },
    { bits:  5, name: 'rs1' },
    { bits:  5, name: 'rs2' },
    { bits:  7, name: 0x04, attr: ['ADD.UW'] },
]}
....

[WARNING]
====
The macro `[wavedrom, , ]` has two commas and leaves a blank space as an implicit indicator to the build processor to auto-generate identifiers for the images after they are created. After the first comma you can insert a name as an identifier of the file that is created in the /images directory for embedding in the pdf.

DO NOT make the mistake of simply using `[wavedrom,svg]`. Without the second comma, the build interprets 'svg' as a target name because it is the second value within the macro.
====

In the specifications, there are numerous instances in which several Wavedrom diagrams are grouped and presented as a single figure. To handle these while preserving consistency in how the build renders figure titles, we are making use of a minimalistic, white graphic with the filename `image_placeholder.png` that blends in with the page background. Following is the pattern of its use (minus the macro indicator `[]` in the first line:

[source,adoc]
....
include::images/wavedrom/instruction_formats.adoc
[[instruction_formats]]
.Test for wavedrom
image::image_placeholder.png[]
....

With the following result:

include::images/wavedrom/instruction_formats.adoc[]
[[instruction_formats]]
.Test for wavedrom
image::image_placeholder.png[]


. Wavedrom code for all diagrams in this illustration stored in `wavedrom` subdirectory within the `images` directory.
. Link target that, along with settings in the `book_header` file, automates the inclusion, in the text, of the figure number and caption.
. Figure caption.
. "Invisible" placeholder needed for figure caption to display consistently and correctly.


===== Explanation

For the above to build into a diagram that has a figure title, and a figure title and a macro the specifies the diagram type above the code block. You can add a `target` filename and, in addition, specify the image output format or leave output unspecified to default to png.

When prepended to the javascript for a Wavedrom diagram, the following creates `file-name.svg` with the legend `Figure title`:

[source,adoc]
----
.Figure title
[wavedrom,target="file-name",svg]
----

Following are some examples of Wavedrom diagrams:

[source,adoc]
----
.Figure title
[wavedrom,target="op-32-add-uw",]
....
{reg:[
    { bits:  7, name: 0x3b, attr: ['OP-32'] },
    { bits:  5, name: 'rd' },
    { bits:  3, name: 0x0, attr: ['ADD.UW'] },
    { bits:  5, name: 'rs1' },
    { bits:  5, name: 'rs2' },
    { bits:  7, name: 0x04, attr: ['ADD.UW'] },
]}
....
----

.For this example, the output format was not specified, so it defaults to a png.
[wavedrom,target="op-32-add-uw"]
----
{reg:[
    { bits:  7, name: 0x3b, attr: ['OP-32'] },
    { bits:  5, name: 'rd' },
    { bits:  3, name: 0x0, attr: ['ADD.UW'] },
    { bits:  5, name: 'rs1' },
    { bits:  5, name: 'rs2' },
    { bits:  7, name: 0x04, attr: ['ADD.UW'] },
]}
----

.Wavedrom example with svg output specified
[wavedrom,target="z-type",svg]
....
{reg: [
  {bits: 7,  name: 'opcode'},
  {bits: 5,  name: 'rd'},
  {bits: 3,  name: 'func3'},
  {bits: 5,  name: 'rs1'},
  {bits: 5,  name: 'rs2'},
  {bits: 7,  name: 'funct7'}
], config: {label: {right: 'z-Type'}}}
....

You have the option of referencing graphics files directly:

[#wavedrom_example2]
.This example is from an svg generated prior to the build.
image::wavedrom/wavedrom-example2.svg[wavedrom_example2]


Wavedrom Conversion

[NOTE]
====
The following string is lacking macro brackets (`[]`) that should appear after `filename.adoc` because adding the brackets will cause the include to activate even though it's within a code block. Best practice for automated diagramming is to save AsciiDoc files containing properly formatted AsciiDoc blocks, each block containing the code or script for either a single diagram or a group of diagrams that are presented together as a single figure.
[source,adoc]
----
include::images/wavedrom/filename.adoc
----
====

==== Graphviz

The Unpriv appendices contain Graphviz diagrams with associated keys that are arranged in tables. While in the LaTeX version, the diagrams and tables are arranged side-by-side, for the AsciiDoc version;

* each Graphviz diagram should be directly above the key table.
* store scripts for Graphviz diagrams in the images/graphviz directory, as <filename>.txt
* import the Graphviz by reference using the pattern in the following example.

[source,adoc]
----
.Sample litmus test
graphviz::images/graphviz/litmus_sample.txt[align="center"]

[cols="2,1"]
_Key for sample litmus test_
[width="60%",cols="^,<,^,<",options="header",align="center"]
|===
|Hart 0 | |Hart 1 |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t1,1 | |li t4,4
|(a) |sw t1,0(s0) |(e) |sw t4,0(s0)
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t2,2 | |
|(b) |sw t2,0(s0) | |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
|(c) |lw a0,0(s0) | |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t3,3 | |li t5,5
|(d) |sw t3,0(s0) |(f) |sw t5,0(s0)
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
|===
----

.Sample litmus test
graphviz::images/graphviz/litmus_sample.txt[align="center"]

[cols="2,1"]
_Key for sample litmus test_
[width="60%",cols="^,<,^,<",options="header",align="center"]
|===
|Hart 0 | |Hart 1 |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t1,1 | |li t4,4
|(a) |sw t1,0(s0) |(e) |sw t4,0(s0)
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t2,2 | |
|(b) |sw t2,0(s0) | |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
|(c) |lw a0,0(s0) | |
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
| |li t3,3 | |li t5,5
|(d) |sw t3,0(s0) |(f) |sw t5,0(s0)
| |latexmath:[$\vdots$] | |latexmath:[$\vdots$]
|===


CAUTION: The procedures for Graphviz diagrams are similar but not identical to procedures for <<Wavedrom diagrams in specifications>>.

Following is an example of Graphviz diagram source:

[source,adoc]
----
.Graphviz s
[graphviz, target="ethane",svg]
....
graph ethane {
     C_0 -- H_0 [type=s];
     C_0 -- H_1 [type=s];
     C_0 -- H_2 [type=s];
     C_0 -- C_1 [type=s];
     C_1 -- H_3 [type=s];
     C_1 -- H_4 [type=s];
     C_1 -- H_5 [type=s];
}
....
----

This renders as:

.Graphviz s
[graphviz, target="ethane",svg]
....
graph ethane {
     C_0 -- H_0 [type=s];
     C_0 -- H_1 [type=s];
     C_0 -- H_2 [type=s];
     C_0 -- C_1 [type=s];
     C_1 -- H_3 [type=s];
     C_1 -- H_4 [type=s];
     C_1 -- H_5 [type=s];
}
....

.An example graphviz diagram from a specification
[graphviz,test-diagram,svg]
....
digraph G {

splines=spline;
pad="0.000000";


/* the unlocked events */
eiid0 [label="a: Ry=1", shape="none", fontsize=8, pos="1.000000,1.125000!", fixedsize="false", height="0.111111", width="0.555556"];
eiid1 [label="c: Wx=t", shape="none", fontsize=8, pos="1.000000,0.562500!", fixedsize="false", height="0.111111", width="0.555556"];
eiid2 [label="d: Rx=t", shape="none", fontsize=8, pos="2.500000,1.125000!", fixedsize="false", height="0.111111", width="0.555556"];
eiid3 [label="e: Rt=$v$", shape="none", fontsize=8, pos="2.500000,0.562500!", fixedsize="false", height="0.111111", width="0.555556"];
eiid4 [label="f: Wy=1", shape="none", fontsize=8, pos="2.500000,0.000000!", fixedsize="false", height="0.111111", width="0.555556"];

/* the intra_causality_data edges */


/* the intra_causality_control edges */

/* the poi edges */
/* the rfmap edges */


/* The viewed-before edges */
eiid0 -> eiid1 [label=<<font color="darkgreen">fence</font><font color="indigo">ppo</font>>, color="darkgreen:indigo", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
eiid1 -> eiid2 [label=<<font color="red">rf</font>>, color="red", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
eiid2 -> eiid3 [label=<<font color="indigo">addr</font><font color="indigo">ppo</font>>, color="indigo", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
eiid2 -> eiid4 [label=<<font color="indigo">ppo</font>>, color="indigo", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
eiid3 -> eiid4 [label=<<font color="black">po</font>>, color="black", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
eiid4 -> eiid0 [label=<<font color="red">rf</font>>, color="red", fontsize=11, penwidth="3.000000", arrowsize="0.666700"];
}
....

==== Additional diagram type examples

Following is source for simple ditaa diagram:

[source,adoc]
----
[ditaa,target="image-example",svg]
....

                   +-------------+
                   | Asciidoctor |-------+
                   |   diagram   |       |
                   +-------------+       | SVG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /---------------\
 |        | --+ Asciidoctor +--> |               |
 |  Text  |   +-------------+    |   Beautiful   |
 |Document|   |   !magic!   |    |    Output     |
 |     {d}|   |             |    |               |
 +---+----+   +-------------+    \---------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
....
----

Which renders to:

[ditaa,target="image-example",svg]
....

                   +-------------+
                   | Asciidoctor |-------+
                   |   diagram   |       |
                   +-------------+       | SVG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /---------------\
 |        | --+ Asciidoctor +--> |               |
 |  Text  |   +-------------+    |   Beautiful   |
 |Document|   |   !magic!   |    |    Output     |
 |     {d}|   |             |    |               |
 +---+----+   +-------------+    \---------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
....

Following is source for a simple plantuml diagram:

[source,adoc]
----
[plantuml, diagram-classes, svg]
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....
----

Which renders to:

[plantuml, diagram-classes, svg]
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....

NOTE: Asciidoctor supports additional diagram types. For information on additional diagram types, see the https://docs.asciidoctor.org/diagram-extension/latest/[Asciidoctor-diagram documentation].

===== A mention of Bytefield

Currently the idea of making use of Bytefield as an additional diagram type is being explored.

//=== Bytefield
//
//
//.A byte field
//[bytefield]
//----
//(draw-column-headers)
//(draw-box 42)
//(draw-gap "Whee!")
//(draw-bottom)
//----


=== Mathematical notations

WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally looks like a superscript. For this reason, always use viable alternatives like _italics_ or unicode (see <<Unicode symbols>>).


==== Superscripts and subscripts

To indicate a superscript, enclose the string for the superscript in carets as in the following example:

----
2^8^
----

Which renders as:

2^8^

You can indicate text in a superscript as well:

----
1234^NOTE^
----

Which renders as:

1234^NOTE^

For subscripts, use tildes:

----
C~2~ H~6~
----

With the following result:

C~2~ H~6~

An example:
----
"`Well the H~2~O formula written on their whiteboard could be part
of a shopping list, but I don't think the local bodega sells
E=mc^2^,`" Lazarus replied.
----

Renders as:

"Well the H~2~O formula written on their whiteboard could be part
of a shopping list, but I don't think the local bodega sells
E=mc^2^," Lazarus replied.

==== Latexmath

You can make use of LaTeX notation as in the following:

----
latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
----

Which renders as:

latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]

[TIP]
====
Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible.
====
