3. Document authoring and formatting

This chapter explains the document authoring and formatting.

3.1 Use of Markdown and kramdown syntax

The Accellera documentation flow uses Markdown as primary text input format. More specifically, the kramdown flavor of Markdown is used, since it offers additional capabilities and extensions.

This section gives an overview of the commonly used structural elements.

3.1.1 Headers

Headings are created by starting a line with one or more hash (#) characters and then the header text. The number of hash characters specifies the heading level: one hash character means the first level heading, two means second level heading and so on, until a maximum of six hash characters for a sixth level heading.

No spaces are allowed before the hash characters. Optionally, hashes may be used at the end of the line to close the header. Any leading or trailing spaces are stripped from the header text.

Like with paragraphs, separate the heading from everything else with an empty line space.

Example:

## This is a second-level heading

This is a paragraph.

By default, kramdown will automatically create an ID for each header, such that it can be referenced (see also 3.1.10.3).

NOTE—The use of user-defined IDs is not recommended, as GitHub will not render these links correctly in the source files.

3.1.2 Paragraphs

Consecutive lines of text are considered to be one paragraph. Paragraphs are separated by a blank line.

In Markdown, line brakes are replaced by spaces. A paragraph in Markdown ends when using an empty line.

Example:

This is a the first paragraph.

This is the second
paragraph.

Renders into:

This is a the first paragraph.

This is the second paragraph.

Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line.

Example:

This is a paragraph\\
which contains a hard line break.

Renders into:

3.1.4.1 Unordered lists

Unordered lists are started by using a hyphen (-) followed by a space and then the list item text. To enforce the next sentence to a new line, two backslashes should be added.

Example:

This paragraph will contain an unordered list:
- Unordered list item 1.
  This sentence is part of the same line.
- Unordered list item 2.\\
This sentence will move to the next line.

Renders into:

This paragraph will contain an unordered list:

Unordered list item 1. This sentence is part of the same line.
Unordered list item 2.
This sentence will move to the next line.

Note that the unordered list items should follow the paragraph heading text immediately, without an empty line in between.

3.1.4.2 Ordered lists

Ordered lists are started by using a number followed by a period, a space and then the list item text. According to the IEEE SA Standards Style Manual, ordered items use letters a), b), c), etc. If a subdivision of the items is necessary, 1), 2), 3); i), ii), iii); dashed subdivision items, etc., should be used to form a tiered list.

Example:

This paragraph will contain an ordered list:
First list item will get letter a).
This sentence is part of the same line.
first subitem will get number 1.
first subitem under a subitem will get letter i.
first subitem under a subitem will get letter ii.
second subitem will get number 2.
Second list item will get letter b).
Third list item will get letter c). The typo in the number is deliberate, to show that the flow will correct this when rendering.

Renders into:

This paragraph will contain an ordered list:

First list item will get letter a). This sentence is part of the same line.
1. first subitem will get number 1.
  1. first subitem under a subitem will get letter i.
  2. first subitem under a subitem will get letter ii.
2. second subitem will get number 2.
Second list item will get letter b).
Third list item will get letter c). The typo in the number is deliberate, to show that the flow will correct this when rendering.

3.1.5 Tables

To include a table the container {% include table %} should be used. Depending on the complexity of the table, a table can be described in Markdown format or use HTML syntax.

3.1.5.1 Simple table using Markdown format

Simple tables can be created by using the Markdown format, using pipe characters (|), dash characters (-) and the equal sign character (=).

A table row starts with a pipe character (|) followed by a space and the text of the column. Multiple columns are added by repeating this pattern. There is no need to vertically align the text and columns, however, for readability this is recommended. If a pipe characters is immediately followed by a dash (-), a horizontal separator line is created to mark the end of the table header. If the pipe character is followed by an equal sign (=), the tables rows below it are part of the table footer.

The table reference, caption and style can be added to the {% include table %} container. The table implementation is embedded in this container using the markdown property, see the example below.

Example:

{% include table
   reference="Table 3"
   caption="This is the table caption"
   class="fixed allow-break"
   caption-position="top"
   markdown="
| column 1      | column 2 |
|---------------|----------|
| A simple      | table    |
| with multiple | lines    |
"
%}

Renders into:

Table 3This is the table caption

column 1	column 2
A simple	table
with multiple	lines

3.1.5.2 Complex tables using HTML format

More complex table with merged cells or columns can be created using HTML syntax. Similar as with tables in Markdown format, HTML tables are wrapped in the {% include table %} container. The table implementation in HTML format is then embedded in this container using the html property, see the example below.

Example:

{% include table
   reference="Table 4"
   caption="This is the a more complex table with merged rows and columns"
   class="fixed allow-break"
   caption-position="top"
   html="
<table>
  <tr>
     <th>column 1</th>
     <th>column 2</th>
  </tr>
  <tr>
     <td>Row 1</td>
     <td rowspan='2'>Merged rows</td>
  </tr>
  <tr>
     <td>Row 2</td>
  </tr>
  <tr>
     <td colspan='2'>Merged columns</td>
   </tr>
</table>"
%}

Renders into:

Table 4This is the a more complex table with merged cells and columns

column 1	column 2
Row 1	Merged rows
Row 2	Merged rows
Merged columns

Important: In case quotes are used in the HTML table, for example to specify styles or attributes, these should not conflict with the opening and closing double quotes for the html block. Therefore single quotes should be used within such embedding.

3.1.6 Figures

To include a figure the container {% include figure %} should be used. The figure reference, caption and style can be added to this container. The image can be embedded in this container using the images property, see the example below. The size of the image can be specified using the image-height property, where the value represents the line height.

{% include figure
   reference="Figure 1"
   caption="Accellera logo as PNG"
   alt-text=""
   class="fixed"
   images="accellera_logo.png"
   image-height="10"
%}

Figure 1Accellera logo as PNG

3.1.7 Equations

To include an equation the container {% include equation %} should be used. Equation can be written in MathML or LaTex syntax. An optional equation reference can be added to the container. The container supports inclusion of a separate file containing the equation using the file property. Alternatively, an MathML equation can be embedded directly using the mathml property. Equations in LaTeX should use the latex property.

To ease the creation of mathematical equations, it is highly recommended to use an equation editor. For example, iMathEQ is an online mathematics equation editor (trail/demo version) to create an equation and shows the MathML or LaTex syntax.

3.1.7.1 MathML equation

Equation 1 shows the embedding of a MathML equation stored in a separate XML file.

Example:

{% include equation
   reference="1"
   file="equation-1.xml"
%}

Renders into:

x = \frac{- b \pm \sqrt{b^{2} - 4 a c}}{2 a}

(1)

3.1.7.2 LaTex equation

Equations in LaTex syntax are also supported, see Equation 2.

Example:

{% include equation
   reference="2"
   latex="
\begin{equation}
E_{0} = \frac{\sum\limits_{i = 1}^{N} E_{j}}{N}
\end{equation}
"
%}

Renders into:

\begin{equation} E_{0} = \frac{\sum\limits_{i = 1}^{N} E_{j}}{N} \end{equation}

(2)

3.1.8 Including code

3.1.8.1 Code blocks

Three consecutive backtick characters are used to mark the start and end of a code block. An optional language identifier can be added to enable syntax highlighting in the code block. The next example shows a C++ code block using the cpp language identifier.

```cpp
struct S {
  int a;
}
```

Renders into:

struct S {
  int a;
}

Alternatively, lines indented with either four spaces or one tab are also interpreted as an inline code block.

Example:

This is the paragraph explaining the sample code block.

    void function(int a);

Renders into:

This is the paragraph explaining the sample code block.

void function(int a);

3.1.8.2 Inline code

Inline code, as part of a sentence, can be marked by surrounding it with backticks.

Example:

The function `get_name` returns the name of the object.

Renders into:

The function get_name returns the name of the object.

3.1.8.3 Emphasis in code

When using a code block or inline code, emphasized text requires the use of HTML markup. The example below shows how to use emphasized text in a code block.

Example:

<pre><code>This is a code block containing <b>bold</b> text.
This is <u>underlined</u>, <i>italic</i> and <del>strikethrough</del> text.
</code></pre>

Renders into:

This is a code block containing bold text.
This is underlined, italic and strikethrough text.

The example below shows the use of emphasized text in inline code:

Example:

This sentence contains an inline definition of <code>function <b>hello_world()</b></code>.

Renders into:

This sentence contains an inline definition of function hello_world().

3.1.9 Footnotes

A footnote marker consists of square brackets with a caret and the footnote name inside. The footnote definition can be placed elsewhere in the document.

Example:

This is a text with a footnote[^fn].

[^fn]: And here is the footnote definition.

Renders into:

This is a text with a footnote¹.

The footnote name is only used for the anchors and the numbering is done automatically in document order. Repeated footnote markers will link to the same footnote definition.

When multiple footnotes are required for the same keyword, they should be separated by a comma. This comma should use the superscript tag <sub> to place the comma at the same height as the footnote number, as shown below.

[^fn2]<sup>,</sup> [^fn3]

3.1.10 Links and references

3.1.10.1 Automatic links

A web address or an email address surrounded by angle brackets will be turned into a proper link. In this case, the address will be used as link target and as link text.

Example:

Visit <https://accellera.org> for more information.

Renders into:

Visit https://accellera.org for more information.

3.1.10.2 Inline links

An inline style link can be created by surrounding the link text with square brackets, followed immediately by the link URL (and an optional title in single or double quotes preceded by at least one space) in normal parentheses.

Example:

Visit [Accellera](https://accellera.org "Visit Accellera") for more information.

Renders into:

Visit Accellera for more information.

Alternatively, the link and URL can be decoupled by using a reference name, such that the links can be listed in a separate section. For this, the reference name is used in square brackets instead of the link URL.

Example:

A [link][accellera] to the Accellera homepage.
...
[accellera]: https://accellera.org

3.1.10.3 Internal links / cross references

Within the document or document source tree, links can be added to files, clauses or subclauses, see the examples below.

Example:

See [Chapter 1](01.html) for more information.

Renders into

See Chapter 1 for more information.

To cross reference a subclause, use the header ID of that subclause. The default ID is a slug of the header, containing the section number and title. For example, for section 2.1 called “2.1 GitHub repository setup” the slug is 21-github-repository-setup. Note that special characters like dots, backslash, etc. in the section title are skipped when creating the reference ID. In case the section is located in a different file, the file needs to be specified as well.

Example:

The GitHub repository setup is explained in [2.1](02.html#21-github-repository-setup).

Renders into

The GitHub repository setup is explained in 2.1.

3.1.11 HTML entities and Unicode characters

Special characters can be included using HTML entities or Unicode notation. Table 5 gives a brief overview of commonly used HTML entities and Unicode characters. A full overview can be found here.

Table 5HTML entities and Unicode characters

Name	Character(s)	HTML entity	Unicode hex value
Less/greater than	< >	< >	> <
Em (long) dash	—	—	—
Copyright	©	©	©

3.1.12 HTML attributes

HTML attributes can be used to specify specific styles.

Example:

This is <span style="color: red">written in red</span>.

Renders into:

This is written in red.

3.1.13 Inline comments

Inline comments can be added to the document source files, but these are excluded in the document rendering process.

Example:

{% comment %} 
These comments are visible for the technical editor of the document, but these are not rendered in the final output.
{% endcomment %}

Alternatively, XML comments can be used. The content of XML comments may span multiple lines. The start of an XML comment may only appear at the beginning of a line, optionally indented up to three spaces. If there is text after the end of an XML comment, it will be parsed as if it appears on a separate line. kramdown syntax in XML comments is not processed.

This is the first sentence.
<!-- an inline comment may span
     multiple lines and will 
     *not* render kramdown syntax. 
--> The next sentence
starts here.

Renders into:

This is the first sentence. The next sentence starts here.

3.1.14 Predefined typographic symbols

For convenience, the following plain ASCII character sequences are available, which are converted into their corresponding typographic symbols:

--- will become an em-dash (like this —)
-- will become an en-dash (like this –)
... will become an ellipsis (like this …)
<< will become a left guillemet (like this «), where an optional following space will become a non-breakable space
>> will become a right guillemet (like this »), where an optional leading space will become a non-breakable space

3.2 Formatting classes

Table 6 defines the classes which can be used in the Markdown source files to enforce specific formatting.

Table 6Predefined formatting classes

Feature	Workflow class	Block or inline	Explanation and usage
Bibliography list	`.bibliography`	Block	Styles a list as a bibliography. To apply this class, place `{:.bibliography}` directly under the targeted list.
Box	`.box`	Block	Puts the element in a box, to set it off from the rest of the text. To apply this class, place `{:.box}` directly under the block of text.
Center text in table column	`.table-text-center`	Block	Align text in center of column. Apply `{:.table-text-center}` below the table.
First list item	`.list-start-n`	Block	Specify first marker number/character in ordered lists, where n is between 2 and 50. Mapping for alphabetic characters: 1=a, 2=b, etc. Place `{:.list-start-n}` at the start of the ordered list. NOTE: The actual markdown marker numbers are ignored in creating the list and therefore cannot be used to specify the start.
Fix table column width	`.table-columns-fixed`	Block	Table with equal widths of table columns, independent from actual content. Place `{:.table-columns-fixed}` directly under the table.
Float to top	`.float-top`	Block	Floats the element to the top of its page. Useful for boxes. Applies to print output only. Apply `{:.float-top}` under the element which you’d like to float to the top. Or add it to an existing class like `{:.box .float-top}`.
Float to bottom	`.float-bottom`	Block	Floats the element to the bottom of its page. Useful for boxes. Applies to print output only. Apply `{:.float-bottom}` under the element which you’d like to float to the top. Or add it to an existing class like `{:.box .float-bottom}`.
Footnote	`.sidenote .bottom`	Block or inline	When adding `.bottom` to `.sidenote`, the footnote appears at the foot of the page in print output. It remains on the side on screens.
Fractions	`.fractions`	Block or inline	If supported by the font, it converts characters like `1/2` into fraction characters. Add `{:.fractions}` to a span (e.g. italics, bold or link) or to a block element (e.g. list, paragraph) by adding it to the line immediately below it.
Glossary	`.glossary`	Block	Add `{:.glossary}` below the last entry in a series of definition lists to format the entire list of definitions as a glossary.
Hide bookmark	`.no-bookmark`	Block	Hides the element from the PDF bookmarks. Apply `{:.no-bookmark}` below the element.
Hide from print	`.non-printing`	Block or inline	Hides the element from print output. Useful for things like clickable buttons, which are only intended for screens, not paper. Apply `{:.non-printing}` below or next to the element.
Hide markers of list items	`.list-no-markers`	Block	Hide list item markers (e.g., bullets, numbers or dashes) for num, while keeping the list formatting. Note: only works for the first level. Apply `{:.no-list-markers}` below the list.
Hide PDF bookmark	`.no-bookmark`	Block	Disable creation of PDF bookmark for section. Place `{:.no-bookmark}` directly under the header. (PrinceXML only.)
Keep together	`.keep-together`	Block or inline	Prevents an element from breaking across pages. (e.g., keep a short list on the same page.) Apply `{:.keep-together}` to the end of the entire element. You can also apply it to a span (e.g. a phrase, like `<span class="keep-together">24/7</span>`) to prevent it breaking over a line.
Keep with next	`.keep-with-next`	Block	Prevents a page break between this element and the next one. Apply `{:.keep-with-next}` below the first element, to make sure it stays with the following element.
Line space above	`.space-above`	Block	Add line space above block. Spacing defined by `$line-height-default` property. Apply `{:.space-above}` below the block which requires additional spacing.
List numbers	`.list-numbers`	Block	Enforce use of list numbers as markers (IEEE-SA style manual defines Arabic markers as default). Note: only works for the first level. Apply `{:.list-numbers}` below the list.
Logo image	`.logo`	Block	Used for making images small, especially for small logos in text like on acknowledgements pages. Add `{:.logo}` immediately below the markdown image tag.
Note	`.note`	Block	Create a paragraph describing a note. According to the style manual, notes use a smaller font size. Place `{:.note}` directly under the block of text.
Page break after	`.page-break-after`	Block	Creates a page break after the element. Place `{:.page-break-after}` directly below the element preceding your desired page break.
Page break after, end of book	`.page-break-after-right`	Block	When applied to the very last element in the book, ensures a blank verso for an even-numbered page extent. Apply `{:.page-break-after-right}` to the last element.
Page break before	`.page-break-before`	Block	Starts its element on a new page. Apply `{:.page-break-before}` after the element that should come after the page break.
Page break: allow	`.allow-break`	Block	Allows an element to break over a page where the default styles would normally prevent that (for example a three-bullet list might not break over a page). Apply the class to the parent element, for example place `{:.allow-break}` directly below the entire list.
Page numbering restart	`.page-1`	Block	Restarts page numbering from 1. Can be added to the first block element on a page by using `{:.page-1}` after the first element, or to the YAML header, in addition to the main style, e.g. `style: halftitle-page page-1` or `style: chapter page-1`. As page numbering is defined in the Accellera and IEEE, it is not recommended to use this class.
Shift element down	`.shift-down`, `.shift-down-n`	Block	Shifts an element down in the document on output, where n is the number of sibling elements to shift it down.
Shift element up	`.shift-up`, `.shift-up-n`	Block	Shifts an element up in the document on output, where n is the number of sibling elements to shift it up.
Show URL	`.show-url`, `.pdf-show-url`, `.epub-show-url`	Inline	Apply to a link to show the URL in parentheses after the linked text in epub and PDF, PDF only, or epub only. For epub, this applies only to some e-ink ereaders.
Show page number	`.show-page-number`	Inline	Apply to a link to show the page number in parentheses after the linked text in PDF.
Show roman page number	`.show-page-number-lower-roman`	Inline	Apply to a link to show a roman-numeral page number in parentheses after the linked text in PDF.
Sidenote	`.sidenote`	Block or inline	A sidenote appears in a sidebar to the right of the text. Apply `{:.sidenote}` below the block of text.
Small caps (lowercase only)	`.smallcaps`	Block or inline	Small-caps glyphs if supported by the font. Only affects the lowercase letters. Apply `{:.smallcaps}` to the span inline (e.g. use `` like italics) or directly below the block of text. This class avoids making `` and `**` spans bold or italic. So add `.italics` or `.bold` if the small caps require italics or bold respectively.
Small caps throughout	`.allsmallcaps`	Block or inline	Small-caps glyphs if supported by the font. This makes all characters small caps, including capital letters. Apply `{:.allsmallcaps}` directly after a span element inline or directly below a block of text. Add `.italics` or `.bold` if the small caps require italics or bold respectively.
Start on right page	`.start-on-right`, `.start-on-recto`	Block	Creates a page break to start a new right-hand page. Apply to page frontmatter to start a chapter on the right, e.g. `style: chapter start-on-right`.
Remove table cell padding	`.table-no-padding`	Block	Remove padding (spacing) between table cells. Applied for all cells in the table. Apply `{:.table-no-padding}` below the table.
Table without borders	`.table-no-border`	Block	Creates a table without borders. Apply `{:.table-no-border}` below the table.
Thumbnail figure	`.thumbnail`, `.pdf-thumbnail`, `.web-thumbnail`, `.epub-thumbnail`	Block	Apply to figures to create a small, floated thumbnail. Format-specific classes allow different layouts for PDF, web and epub.
Tracking: tighten	`.tighten-1` to `.tighten-50`	Block or inline	Each increment tightens the space between letters by 0.001em (1/1000 of a em). E.g. add `{:.tighten-5}` directly below a paragraph to reduce its letter-spacing by 5/1000em. Affects print output only.
Tracking: loosen	`.loosen-1` to `.loosen-50`	Block or inline	Each increment loosens the space between letters by 0.001em (1/1000 of a em). E.g. add `{:.loosen-5}` directly below a paragraph to increase its letter-spacing by 5/1000em. Affects print output only.
Visually hide	`.visuallyhidden`	Block or inline	Used to hide elements from view, but not from screen readers.
Width	`.width-1` to `.width-100`	Block	Applied to `.verse` (only for PDF output) and to figures to set their width as a percentage

And here is the footnote definition. ↩