Publications Development using the GitLab® and AsciiDoc® Toolchain

Appendix B: AsciiDoc Markup Language.

This appendix provides further examples of the styles used to develop The Open Group Standards in the AsciiDoc markup language.

Additional resources including a writer’s guide, user manual, and syntax reference manual are available at https://asciidoctor.org/.

Guidance

For chapter headings, always use Heading 1 (=).

[#ch-chaptername]
= Chapter Heading Text

Copy this section to create further chapters.

Use regular paragraphs for basic paragraph text.

B.1. Sample Heading at Level 2

Sample Text

Guidance

Within a chapter use Heading 2 (==), Heading 3 (===), Heading 4 (====), and Unnumbered Heading (text).

=== Sample Heading at Level 3

==== Sample Heading at Level 4

*Sample Unnumbered Heading*

B.1.1. Sample Heading at Level 3

B.1.1.1. Sample Heading at Level 4

Sample Unnumbered Heading

B.2. IDs

The following conventions should be used when assigning AsciiDoc IDs for chapters, tables, and figures.

The recommended ID convention follows the recommended AsciiDoc Custom ID and Reference Text syntax of [#sec-id] instead of the legacy [[sec-id]] syntax.

Asciidoctor also auto-generates section IDs, so creating a separate ID for each section is not strictly necessary. However, use of custom IDs defines a stable anchor for linking to a section using a cross reference (xref), which will both help future authors and the editing process. manually defining custom IDs for sections is recommended.

Table 3. Section ID Conventions
Content Type	ID Convention	Example	Notes
Chapter title	`[#ch-Chapter-Title]`	`[#ch-Business-Layer]`	Only occurs once at the top of a file
Figures and Images	[`#fig-image-name]`	`[#fig-Business-Layer-Metamodel]`
Section	`[#sec-Section-Content]`	`[#sec-Business-Actor]`	Use for referencable sections at any level
Example	`[#ex-Example-Content]`	`[#ex-Business-Active-Structure-Elements]`
Tables	`[#tbl-Table-Name]`	`[#tbl-Business-Layer-Elements]`

B.3. Code Blocks and Literal Text

Guidance

Code examples should appear in constant-width font. Prefix text by whitespace or using a line delimiter (----) before and after the text.

Example with text prefixed by whitespace:

Sample code example
Sample code example

Using a line delimiter (----):

Guidance

(Note there should be no whitespace before the line delimiter.)

----
Sample code example
Sample code example
The code is displayed literally as <pre> text
----

Would produce:

Sample code example
Sample code example
The code is displayed literally as <pre> text

B.4. Lists

Guidance

The preferred list formats are bullet, Arabic numeric, and variable.

For bullet lists, use the Bullet List style (*). For sublists below bullets, use the Dashed List style (-); note that dashed lists may render similar to bullets.

For numeric lists, use the Numbered List style (.). For sublists below numerics, use either the Dashed List style or the Numbered Sublist style.

If you have text between two numbered list items, you can use a [start] directive; for example:

. Item 1.

****
[NOTE]
====
Note text
====
****
[start=2]
 . Item 2.

produces:

Item 1.

Note text

Item 2.

For variable lists, use the Variable List style.

Bullet list:

Sample bullet list item

Numbered list:

Sample numbered list item

Variable list:

Variable List item: Text to go with the item.

Guidance

* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+

list continuation: a plus sign (+) on a line by itself

* A literal paragraph does not require a list continuation

 $ gem install asciidoctor

A list with a paragraph of content, which may be wrapped, even using a hanging indent

Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

B.5. Tables

Guidance

The %header option makes the first row of the table into the header row. In the example below we have three columns, set by cols=3*.

The .Sample Table below sets the Table Caption

[%header, cols=3*]
.Sample Table
|===
| Table Column Heading | Table Column Heading | Table Column Heading
|Table text
|Table text
|Table text
|===

Table 4. Sample Table
Table Column Heading	Table Column Heading	Table Column Heading
Table text	Table text	Table text

Guidance

To set relative widths of columns use column specifiers – a comma-separated list of relative values defined in the cols block attribute. The number of entries in the list determines the number of columns.

[%header, cols="2,3,5"]
.Table with Relative-Width Columns
|===
| Heading 1 | Heading 2 | Heading 3
|Table text
|Table text
|Table text
|===

Table 5. Table with Relative-Width Columns
Heading 1	Heading 2	Heading 3
Table text	Table text	Table text

Guidance

If you want to include blocks or lists inside the contents of a column, you can put an a (for AsciiDoc) at the end of the column’s relative value.

[%header, cols="2,3,5a"]
.Table with AsciiDoc Output in a Column
|===
| Heading 1 | Heading 2 | Heading 3
|Table text
|Table text
|The Open Group Standards are designed for:

* Standards compliance
* Interoperability
* Portability

|===

Table 6. Table with AsciiDoc Output in a Column
Heading 1	Heading 2	Heading 3
Table text	Table text	The Open Group Standards are designed for: Standards compliance Performance Portability

B.6. Note Blocks

Guidance

A note block can be added as:

NOTE: This is a simple note block.

or:

[NOTE]
====
A note block can contain complex content.

. A list
- One
- Two
- Three

Another paragraph.
====

This is a simple note block.

A note block can contain complex content.

A list
- One
- Two
- Three

Another paragraph.

B.7. Indexing Terms

Guidance

Terms can be indexed as follows:

This text has an (((indexed term)))indexed term.

This text indexterm:[indexing terms] has a term that is indexed.

Note three parentheses and the indexterm macro conceal the indexed term. If you want the term to be visible in the text use two parentheses or indexterm2.

This text has ((another example)).

This text has indexterm2:[guidance on indexing].

The inline macro indexterm2:[primary] is equivalent to the double parenthesis form. The inline macro indexterm can also be used to make optional secondary and tertiary index terms, using indexterm:[primary, secondary, tertiary] .

King Arthur was to carry Excalibur. indexterm:[Sword, Broadsword, Excalibur]

This text has an indexed term.

This text has a term that is indexed.

This text has another example.

This text has guidance on indexing.

King Arthur was to carry Excalibur.

B.8. Figures

Guidance

Graphics can be incorporated into the document; for example:

// This is an anchor for cross-referencing
[#fig-chap03-core-process]
.Caption Text
image::sample-figure.png[alt text, size, float="left"]

A caption is added below the figure. It is recommended that if adding an anchor for cross-referencing, the name is prefixed with fig-.

Figure 70. Caption Text

B.9. Web Links

Guidance

https://www.opengroup.org &#8211; automatic!

https://www.opengroup.org[The Open Group]

https://www.opengroup.org/library/C182[The TOGAF^(R)^ Standard, Version 9.2]

https://www.opengroup.org – automatic!

The Open Group

The TOGAF^® Standard, Version 9.2

B.10. Quotations

Guidance

Single-line quote:

[quote]
Never do today what you can put off 'til tomorrow

Never do today what you can put off 'til tomorrow

Guidance

Multi-line quote:

 [quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
 ____
 Four score and seven years ago our fathers brought forth
 on this continent a new nation ...

 Now we are engaged in a great civil war, testing whether
 that nation, or any nation so conceived and so dedicated,
 can long endure. ...
 ____

Four score and seven years ago our fathers brought forth on this continent a new nation …

Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. …

— Abraham Lincoln
Address delivered at the dedication of the Cemetery at Gettysburg

B.11. Cross-References

Guidance

Use the inline xref macro as a way to create a cross-reference.

An anchor to reference has the format [#anchor-name].

Reference with the format xref:anchor-name[] or xref:anchor-name[display text]; for example:

The section on xref:chap03-quotes[providing quotation guidance] above describes how to insert quotations into a document.

The section on providing quotation guidance above describes how to insert quotations into a document.

This is a link back to the earlier figure, Figure 70.

B.12. Advanced Cross-referencing

B.12.1. Overview

One key benefit of using the publication framework that The Open Group has adopted is that it allows cross linking both within a document and across different documents. In this template we keep the examples fairly simple and use the Antora format by default, that uses a source-to-source linking syntax allowing the author to specify where in the original source material to link to, with the system figuring how to actually link the published content. This means when cross linking outside an adoc file you need to know the filename where the target reference resides.

This kind of cross-linking is referred to as an xref after the Asciidoc directive that specifies the destination or target of a link. There are a number of ways you can specify the xref target, depending on exactly what you are trying to link to. However, there are a few cases that you will use frequently - there are some examples below, and fully covered in the official online documentation under Xref Macros and Page Links.

While the xref directive specifies the from end of the link, it is helpful to have a high-level understanding of the target - where you are linking to. In general, you need to know:

The component name of the project you are linking to - this is the name attribute in antora.yml, and usually set by the editors e.g., name: the-open-group-standard-template
The name of the module containing the file you want to reference - this is likely to be project dependent, so you will need to understand the structure of the document you are linking to, the typical convention we use is '00-front-matter' for front matter material such as the Preface, '01-doc' for content pages, and '99-appendices' for the appendices and index
The name of the Asciidoc file containing the material you want to refer to, e.g, chap03.adoc
An optional anchor for a topic somewhere inside that Asciidoc file, e.g., [#content_framework] or - these anchors can be both defined by the authors, and are also auto-generated from section headings

With these target destinations in mind, you can construct an xref of the form:

xref:component:module:file-coordinate-of-target-page§adoc#anchor[optional link text]

B.12.2. Example

An example of this would be if you wanted to make a reference in the Preface of this template to the chapters of this document.

This content is The Open Group Standard Template, which has the project name the-open-group-standard-template (set in the top level antora.yml file). The Introduction chapter is in the file named chap01.adoc within the module 01-doc, and the specific reference is at an anchor called #Introduction. (Authors are encouraged to give meaningful names to their anchors.

So, with this information in mind, your reference would look like:

xref:component:module:name-of-target-page§adoc#anchor[optional link text]
xref:the-open-group-standard-template:01-doc:chap01§adoc#Introduction[Introduction]

You can also drop the component name when referencing within the document itself. So, use the abbreviated form:

xref:01-doc:chap01§adoc#Introduction[Introduction]

B.13. Inline Rationale

Guidance

One technique, especially when drafting a standard, is to insert inline rationale as a shaded text block. An example follows:

Rationale (Informative)

This text is part of the informative rationale and will be moved to an appendix for publication of the final standard.

The technique of including inline rationale can be used to explain to the readers the motivations of the standard developers.

B.14. Inline Citations to References

Guidance

This is an example reference: The Open Group Standards Process is defined in [1].

This is an example reference, The Open Group Standards Process is defined in [xref:00-front-matter:references§adoc#Ref1[1]].

B.15. Diagrams in AsciiDoc

Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.

The extensions support the AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite, and WaveDrom syntax.

For more details, see https://asciidoctor.org/docs/asciidoctor-diagram/.

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

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

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

B.16. Curly Quotes

This is an example of "`double curly quotes`".

This renders as:

This is an example of “double curly quotes”.

If you run curly quotes up against Italics, they may not render. In that case use a zero-width space character.

(_You should be able to contrast the main differences between "`waterfall`" and "`Agile`"{zwsp}_)

Without the zero-width space, this renders incorrectly as:

(You should be able to contrast the main differences between “waterfall” and "`Agile`")

With the zero-width space we get:

(You should be able to contrast the main differences between “waterfall” and “Agile”)

The following could be used for a long quotation:

"`{zwsp}
_...{nbsp}the best team leaders are those that take on the leadership role 100% all of the time_
{zwsp}`"

Which renders as:

“ … the best team leaders are those that take on the leadership role 100% all of the time. ”

1. If your birthday falls on the weekend, please refer to the Staff Handbook:https://staffhandbook.com