[[tables_symbols_math]]
== Tables, symbols, and math

Asciidoc makes standard tables easy and also supports the creation of complex tables. As a general rule, do not present new information in tables

=== Table rules

==== Table formatting

- Align tables to center with the options `float="center"` and `align="center"`.
- Use table header coding to indicate a header. Don't use a different font, color, or any background indication.
- Sort rows in either a logical order or by alphabetizing the rows and columns.
- If your table is long or complicated, consider creating multiple tables. If you do choose to create a complicated table, make sure that
- Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme.
- If you use footnotes in your table, make sure they appear immediately after the table.
- Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text.


=== Column header formating

- Use sentence case.
- Write concise headings and omit articles (a, an, the).
- Don't end with punctuation, including a period, an ellipsis, or a colon.
- Use table headings for the first column and the first row only.

[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.
====

=== Simple table

The following example shows a simple table with 2 rows and 2 columns. To indicate a new row, put a empty line between them.

[source]
----
[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
----

Results in the following table.

[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===

=== Adding table headers

Headers can add additional information to your table, making them easier to understand.

You can add a header row by adding the first row of cells directly in a line.

----
[cols="1,1,1"]
|===
|Col 1, header row|Col 2, header row|Col 3, header row

|Cell in col 1, row 2
|Cell in col 2, row 2
|Cell in col 3, row 2
|===
----

Or you can use the `header` option.

----
[%header,cols="1,1,1"]
|===
|Col 1, header row
|Col 2, header row
|Col 3, header row

|Cell in col 1, row 2
|Cell in col 2, row 2
|Cell in col 3, row 2
|===
----

Either table renders with table headers.

[cols="1,1,1"]
|===
|Col 1, header row|Col 2, header row|Col 3, header row

|Cell in col 1, row 2
|Cell in col 2, row 2
|Cell in col 3, row 2
|===


=== Asciidoc tables from CSV data.

AsciiDoc tables can also be created directly from CSV data. Set the format block attribute to `csv` and insert the 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 previous example 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
|============================

The following example 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.

The previous example results in the following table.

[#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 failure 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 other symbols, use 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
|===


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

==== Stem content

The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output.

Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install.

[source,adoc]
----
[stem]
++++
sqrt(4) = 2
++++
----

[stem]
++++
sqrt(4) = 2
++++

In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486

For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf.
