tables_graphics.adoc

Tables and graphics

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

Some table 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

Here is an additional example of what can be done with tables:

[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

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, some unicode symbols are buggy. There are some workarounds. I noticed the need for a mathematical w and because its encoding uses an integer that is in the 5+ digit category it doesn’t work.

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

As an example, ♦ is encoded as follows:

♦

Table 2. Useful unicode for specifications

sym	num	name
♦	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

Unfortunately a better checkmark is not available for asciidoctor-pdf, because anything above four digits doesn’t work. The fact that encodings for moe than four digits for HTML encoding doesn’t work is connected to prawn, which is used for generating the fully functional asciidoctor-pdf, and not to asciidoctor-pdf itself. Until the newer asciidoctor build that uses a different toolchain becomes fully featured, we must use a workaround.

It is possible to map fonts for better substitutes to numbers for which you don’t need to make use of the existing unicode mapping should the need become a priority. For example, if a perfect mathematical w is important, we can implement the workaround until the newer toolchain for the pdf build is fully featured.

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.

Figure 1. A wavedrom example

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.

A build that incorporates building of Wavedrom diagrams is under development. The build will support making use of the git repo as the single source of truth for a specification.

Until the automation has been developed ans tested, the code for the wavedrom diagrams should be maintained in the repository and the filename for the SVG output should have the same name (with the SVG extension).

Diagram types available

Asciidoctor supports numerous diagram types:

Simple ditaa diagrams:

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

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

Renders to (this feature is in process for pdf output):

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

Another example

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

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

Handling Wavedrom diagrams

The following json-formatted script is an example that will be used to generate an svg diagram once the automated process is fully implemented.

{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'] },
]}

While it appears that there is great interest within the asciidoctor community in enabling Wavedrom diagrams, to date it is not fully integrated with asciidoctor-diagram, which looks for a wavedrom-diagram.app. The downloaded app, however, is intended for use as a manual interface for processing one diagram at a time from individual scripts.

Figure 2. A second wavedrom example

{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'] },
]}

asciidoctor-pdf vs asciidoctor-web-pdf