Skip to content

Latest commit

 

History

History
592 lines (461 loc) · 18.6 KB

tables_graphics.adoc

File metadata and controls

592 lines (461 loc) · 18.6 KB
Raw

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:

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

The above renders as follows:

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:

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

1

2

3

4

5

6

7

8

9

10

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

Note
 Annotations have been added to the code to illustrate their use. 
[[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
|===

  1. Link target.

  2. Numbered table title.

Table 1. proposed 16-bit encodings-1
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 instruction

100

1

0

0

0

field

0

0

00

field

00

mnemonic1

100

1

0

0

field

bit

1

field

00

mnemonic2

110

1

0

0

field

1

0

field

00

mnemonic3

This row spans the whole table

100

1

1

1

field

00

mnemonic4

Unicode symbols

For pdf, five-digit unicdole symbols generally don’t work and some other unicode symbols are buggy. This happens because the Ruby asciidcotor-pdf toolchain makes ue 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, ♦ is encoded as follows:

&#9830;
Table 2. Useful unicode for specifications
sym num name

^

94

caret

ˆ

136

⋮

8942

vdots

♦

9830

name

"

0034

name

w

0077

w

∴

8756

therefore

♯

9839

sharp

ш

1096

shcy

ϖ

982

piv varpi

ω

969

omega

℘

8472

weierp wp

∑

8721

sum

∞

8734

infin

∫

8747

integral

≠

8800

not equal to

≤

8804

le

≥

8805

ge

≈

8776

numerical approximation

D

68

mathematical D?

⇒

8658

rightwards double arrow

X

88

Latin Capital x

χ

967

Greek x

×

215

times

☑

9745

boxed checkmark

r

114

latin small letter r

For many symbols, then, we must turn to asciidoctor-mathematical. See [Superscipts and other mathematical notations].

Table 3. Unicode identified as not working
sym num name

⍼

9084

angzarr not working

⋙

8921

ggg not working

↩

8617

hookleftarrow not working

⍻

9083

not checkmark not working

Graphics

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

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.

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 asciidoctor-diagram extension supports numerous diagram types, including WaveDrom diagramming for sequence and waveform diagrams, and Graphviz digrams, which can be useful for illustrating software, networking, and security concepts.

The requirements for building WaveDrom diagrams are specified in the 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:

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

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

With the following result:

image placeholder
Figure 1. Test for wavedrom

  1. Wavedrom code for all diagrams in this illustration stored in wavedrom subdirectory within the images directory.

  2. Link target that, along with settings in the book_header file, automates the inclusion, in the text, of the figure number and caption.

  3. Figure caption.

  4. "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:

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

Following are some examples of Wavedrom diagrams:

.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.
{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
{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
Figure 2. This example is from an svg generated prior to the build.

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.

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 Graphiviz diagrams in the images/graphviz directory, as <filename>.txt

  • import the Graphviz by reference using the pattern in the following example.

.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"]

Key for sample litmus test

Hart 0 Hart 1

\(\vdots\)

\(\vdots\)

li t1,1

li t4,4

(a)

sw t1,0(s0)

(e)

sw t4,0(s0)

\(\vdots\)

\(\vdots\)

li t2,2

(b)

sw t2,0(s0)

\(\vdots\)

\(\vdots\)

(c)

lw a0,0(s0)

\(\vdots\)

\(\vdots\)

li t3,3

li t5,5

(d)

sw t3,0(s0)

(f)

sw t5,0(s0)

\(\vdots\)

\(\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:

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

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

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

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

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

Which renders to:

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
Note
 Asciidoctor supports dditional diagram types. For information on additional diagram types, see the Asciidoctor-diagram documentation.
A mention of Bytefield

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

Mathematical notations

Warning
 Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered virtically. In some cases where there is a single-character Asciidoctor-mathemtical expresssion, it unintentionally looks like a superscript. For this reason, always use viable alternatives like italics or unicode (see Unicode symbols).

Superscritps and subscripts

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

2^8^

Which renders as:

28

You can indicate text in a superscript as well:

1234^NOTE^

Which renders as:

1234NOTE

For subscripts, use tildes:

C~2~ H~6~

With the followoing result:

C2 H6

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 H2O formula written on their whiteboard could be part of a shopping list, but I don’t think the local bodega sells E=mc2," Lazarus replied.

Latexmath

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

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

Which renders as:

\(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 mathemtical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expresions inline and prefentially make use of unicode or superscripts and subscripts when possible.