AsciiDoc Specification

AsciiDoc Support in EHANDBOOK

AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.

— https://asciidoc.org/

The Directory-based EHANDBOOK Container-Build Tool-Chain contains a converter for AsciiDoc sources. It generates textual and graphical content for EHANDBOOK containers out of AsciiDoc files.

  • For EHANDBOOK, the file extension for AsciiDoc files must be either *.adoc or *.asciidoc.

  • EHANDBOOK supports a subset of the full AsciiDoc syntax. Syntax elements that are not described below may also work, but are not guaranteed to work.

The following AsciiDoc syntax elements are supported:

Document Header and Section Titles

A document header in AsciiDoc represents the title of the document. The document header is typically followed by content such as text, images, lists and tables. The content itself can be further structured through sections and subsections.

The document header is specified using a single '=' character at the very beginning of the first line in a document. Sections and subsections are then created through multiple '=' characters.

= Document Header Text (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

  • For EHANDBOOK, the document header is expected as the very first line in the AsciiDoc file that represents a documentation chapter. If the document header is not present, then name of the name of the directory in which AsciiDoc file is stored will be used as document title.

  • The titles of subsections appear in the table of contents in EHANDBOOK-NAVIGATOR.

  • The maximum nesting level for subsections is 6.

More information can be found at https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles and https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/.

Formatted Text

Text style syntax: framing of text by special characters

Formatted text such as \*bold*, \_italic_, \^super^script phrase, \~sub~script phrase are supported. Nested formatting such as \*\_bold-italic_*  is also possible.

Representation in EHANDBOOK-NAVIGATOR:

Formatted text such as bold, italic, superscript phrase, subscript phrase are supported. Nested formatting such as bold-italic is also possible.

More information can be found at https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#formatted-text

Lists

Ordered List Syntax: using the '.' character at the beginning of a new line

'.' Ordered list can have a list title, followed by list elements in seperate lines
'.' In Ordered list, list elements starts with a dot '.'

Representation in EHANDBOOK-NAVIGATOR:

  1. Ordered list can have a list title followed by list elements in separate lines

  2. In Ordered list, list elements starts with dot '.'

Unordered List Syntax: using the '-' or '*' character at the beginning of a new line

'-' Unordered list can have a list title followed by list elements in separate lines
'-' Unordered list element starts with hyphen '-'
'*' Alternately Unordered list element can start with an asterisk

Representation in EHANDBOOK-NAVIGATOR:

  • Unordered list can have a list title followed by list elements in separate lines.

  • Unordered list element starts with hyphen '-'

    • Alternately Unordered list element can start with an asterisk

A blank line is required before and after a list to separate it from other blocks.

More information can be found at https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists

Only basic ordered and unordered lists without nesting are supported in EHANDBOOK.

Description Lists

A description list is an association list that consists of one or more terms (or sets of terms) that each have a description.

Basic description list

Each entry in a description list is composed of a term or phrase followed by a separator.

Basic Description List Syntax: utilizing the '::'

 Terms :: Description or definition of the item

Example for Basic description list

Term1::
Description with line break.
Term2:: Description without line break.

Representation in EHANDBOOK-NAVIGATOR:

Term1

Description with line break.

Term2

Description without line break.

Nested or mixing lists

The content of a description list in AsciiDoc can include various elements, such as description, ordered, and unordered lists. Note that the term delimiter changes from '::' to ':::' to create a nested description list.

Term1::
  * List element 1
  * List element 2
Term2::
  Nested Term:::
    . List element 1 of Nested Term
      * Nested list element 1
      * Nested list element 2
    . List element 2 of Nested Term
      * Nested list element 1
Term3::
  NOTE: Description mixed with NOTE block.

Representation in EHANDBOOK-NAVIGATOR:

Term1

  • List element 1

  • List element 2

Term2
Nested Term

  1. List element 1 of Nested Term

    • Nested list element 1

    • Nested list element 2

  2. List element 2 of Nested Term

    • Nested list element 1

Term3

NOTE: Description mixed with NOTE block.

Tables

Table with title has the following syntax:

.Table title

|===
|TableHead1 |TableHead2 |TableHead3

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

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

Representation in EHANDBOOK-NAVIGATOR:

Table 1. Table title
TableHead1 TableHead2 TableHead3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

More information can be found at https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#tables

Only simple tables are supported in EHANDBOOK (equal columns and rows, no nesting). The sortable headers and the filter line is added by EHANDBOOK-NAVIGATOR automatically.

Images

Images can be embedded in AsciiDoc documentation. In EHANDBOOK, model screen-shots can be linked to interactive models by providing the link to model path.

Embed pre-generated images

Image must be placed in the same folder as the AsciiDoc documentation or in a subfolder of the AsciiDoc documentation. In either case path relative to AsciiDoc documentation is expected.

Syntax: image::VectorImage.svg[]
VectorImage

Pre-generated images in svg, jpg and png formats are supported.

Pre-generated Images linked with Model

Pre-generated image can also be linked to its corresponding hierarchy of the interactive model in EHANDBOOK NAVIGATOR.

Syntax: image::image_name.svg[]
VectorImage

EHANDBOOK generated model screenshots linked with interactive models

EHANDBOOK Container-Build can generate screenshots of model layers (i.e., ASCET diagrams or hierarchies, Simulink subsystems) and link them to the interactive model in EHANDBOOK NAVIGATOR.

Syntax: ehbmodelref::model_path[image_title]

EHB generated Function Overview Image

Syntax for one Function only: ehbfunctionoverview::function_name[title]

ehbfunctionoverview::Documentation[Title Name]

Syntax for multiple functions: ehbfunctionoverview::function1_name[title],function2_name[title]

Syntax for all the functions of the container: ehbfunctionoverview-all::[title]

If target (function1_name,function2_name) contains leading, trailing or in between white spaces, then target has to be enclosed within quotes.

Syntax for multiple functions: ehbfunctionoverview::" function1_name,function2_name "[title]

Include Files

Inclusion of other AsciiDoc or source files

Contents from another AsciiDoc file or other file formats can be inlined within this AsciiDoc document.

  • The file to be inlined must be placed in the same folder as the AsciiDoc documentation or in a subfolder of the AsciiDoc documentation. In either case path relative to AsciiDoc documentation is expected.

  • To inline the content from another AsciiDoc file into the main AsciiDoc file, the name of the file to be inlined should start with an underscore '_'.

  • If multiple AsciiDoc files are used without '_', the content of each file is appended in EHB in alphabetical order of the file names.

Syntax for inlining files: include::_fileName.extension[]

include::./../../include/_anotherFile.asciidoc[]

This content comes from the adoc file _anotherFile.asciidoc:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec,

Inclusion of formatted Source Code, e.g. C-Code

Syntax for inlining source files:

[source,c]
----
include::filename.extension[]
----

Representation in EHANDBOOK-NAVIGATOR:

/*****************************************************************************************************
 * Header File #includes
 ****************************************************************************************************/
#include "adb.h"

/*****************************************************************************************************
 * Function:	DECU
 * Description: Filter ECU-internal ambient air pressure value
 ****************************************************************************************************/
void DFiltered(void)
{
	int a = 0;
	int b = 4;
	int c = a + b;
}

Syntax highlighting is not supported in EHB.

AutoLink

AsciiDoc recognizes the following common URL schemes without the help of any markup:

  1. http/https

  2. file

  3. mailto

  4. ftp

  5. irc

So the below https URL automatically turn it into a hyperlink:

The EHANDBOOK homepage at https://www.etas.com/ehandbook

A link to an external file works like this:

file://../input/Documentation/AsciiDocUserDocument.adoc

A link to a network file works like this:

file://sample.com/sample/sample/sample.adoc

By clicking on any of the above links, the file will be opened with the associated tool outside of EHB-NAV.

AsciiDoc also detects and autolinks standard email addresses:

Email us at sales.de@etas.com for any inquiries.

Only absolute file paths are supported in EHANDBOOK.

Cutomize Link Text

The appearance of the link can be configured. This happens by appending text or parameters, enclosed by a pair of square brackets.

Customize URL and File Link Text

Instead of the link itself, an alternative text can be displayed. Insert that text between the square brackets at the end of the URL.

https://etas.com/ehandbook[Show Homepage]

will be shown as:

Show Homepage

Since the text is subject to normal substitutions, you can apply formatting to it.

Show Homepage in bold

And out of this

file://../input/Documentation/AsciiDocUserDocument.adoc[AsciiDoc Source]

the following is shown:

AsciiDoc Source

Customize Mailto Text

For mailto, two parameters are used inside the brackets. The first parameter defines the text, which is shown as the link. The second parameter defines the text, which will appear in the subject field of your mail program.

mailto:sales.de@etas.com[Contact ETAS,Request for Quotation]

Contact ETAS

If you want to leave the linked text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.

mailto:sales.de@etas.com[,Request for Quotation]

sales.de@etas.com

Link Macro

The general link syntax is link:<target>[<attrlist>].

The link macro is required, if the link does not start with a scheme recognized by AsciiDoc. This also happens, if the link contains any space characters. in this case, the space must be URL encoded by %20 or &#32.

Customize <target> to support model or function overview link.

Support model link

Syntax for support model linking.

ehb:model:://FCName/model_path
Key Description

ehb:

Mandatory

model:

Mandatory for model link

FCName

Optional, and used for inter FC model link

model_path

model hierarchy path starting from project to a hierarchy

Example for inter FC model link:

link:ehb:model://A_C_Afr/AirFuelRatio_Project/Main/AirFuelRatio/Main[link to ASET Afr model]

The above target link contains FC name. So this link can be used across FC documentation.

Example for intra FC model link:

link:ehb:model:/AirFuelRatio_Project/Main/AirFuelRatio/Main[link to ASET Afr model]

The above target link doesn’t contain FC name. So this link can be used within FC documentation for linking.

Support function overview link using link macro

Syntax for function overview linking.

ehb:functionoverview:/?functions=function1,function2
Key Description

ehb:

Mandatory

functionoverview:

Mandatory for function overview link

?functions=(key)

Mandatory

function1,function2(values)

Allowed valid single or multiple functions

Example for single FC function overview link:

link:ehb:functionoverview:/?functions=CPT_Amf[link CPT_Amf]

Example for multiple FC function overview link:

link:ehb:functionoverview:/?functions=CPT_Amf,CPT_Afr[link CPT_Amf and CPT_Afr]

Note: If multiple function names are provided as input, they must be separated with comma (,).

link:../input/Documentation/AsciiDocUserDocument.adoc[AsciiDoc Source]

becomes:

AsciiDoc Source

Support cross references

A cross reference is a link to another location within the current AsciiDoc document or in another AsciiDoc document. To create a cross reference, it is required to define the location where the reference will point. Use inline xref macro to create a reference to the location.

Intra FC linking

The shorthand xref is used to create a cross reference to an section that has a title within the same document.

Syntax for Inter FC Linking

xref:#Section_title[link text]

Example, an AsciiDoc document has a section called Introduction. The reference to that section can be written as

xref:#Introduction[Introduction]
Inter FC Linking

The shorthand xref is also used to create cross reference to an section that has a title in another AsciiDoc document.

xref:#Fc_name/Section_title[link text]

Example, an AsciiDoc document has a section called Variables in the FC named Sensor. This section is referenced in another AsciiDoc document in the FC named Actuator. Reference can be written as,

xref:#Sensor/Variables[Variables]

Link text can also be customized based on requirement in both intra and inter FC linking. Example,

xref:#Introduction[Overview]
xref:#ETAS/EHANDBOOK[FC Overview]

If no link text is provided, default section title is displayed.

Diagrams

Support for Asciidoctor Diagrams in the EHANDBOOK enables rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process. Following types of Diagrams are supported in EHANDBOOK

  • Formulas

  • UML Graphics

Formulas

Simple formula

[plantuml,default]
....
@startmath
f(t)=(a_0)/2 + sum_(n=1)^ooa_ncos((npit)/L)+sum_(n=1)^oo b_n\ sin((npit)/L)
@endmath
....
default

Scale formula with 1.5

[plantuml,scale1_5]
....
@startmath
scale 1.5
f(t)=(a_0)/2 + sum_(n=1)^ooa_ncos((npit)/L)+sum_(n=1)^oo b_n\ sin((npit)/L)
@endmath
....
scale1 5

Changing formula images to SVG

[plantuml,latex_svg,svg]
....
@startlatex
\sum_{i=0}^{n-1} (a_i + b_i^2)
@endlatex
....
latex svg

UML Graphics

Sequence Diagram

[plantuml,sequence1]

....
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
....
sequence

Use Case Diagram

[plantuml,usecase2]
....
@startuml
!pragma layout smetana

(First usecase)
(Another usecase) as (UC2)
usecase UC3
usecase (Last\nusecase) as UC4

@enduml
....
usecase

Class Diagram

[plantuml,Class3]

....
@startuml
!pragma layout smetana

abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection

List <|-- AbstractList
Collection <|-- AbstractCollection

Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList

class ArrayList {
  Object[] elementData
  size()
}

enum TimeUnit {
  DAYS
  HOURS
  MINUTES
}

annotation SuppressWarnings

@enduml
....
class

Components Diagram

[plantuml,components]

....
@startuml
!pragma layout smetana

[AA] <<static lib>>
[BB] <<shared lib>>
[CC] <<static lib>>

node node1
node node2 <<shared node>>
database Production

skinparam component {
    backgroundColor<<static lib>> DarkKhaki
    backgroundColor<<shared lib>> Green
}

skinparam node {
borderColor Green
backgroundColor Yellow
backgroundColor<<shared node>> Magenta
}
skinparam databaseBackgroundColor Aqua

@enduml
....
components

Object Diagram

[plantuml,object]

....
@startuml
!pragma layout smetana


object Object01
object Object02
object Object03
object Object04
object Object05
object Object06
object Object07
object Object08

Object01 <|-- Object02
Object03 *-- Object04
Object05 o-- "4" Object06
Object07 .. Object08 : some labels

@enduml
....
object

Deployment Diagram

[plantuml,deployment]

....
@startuml
!pragma layout smetana

artifact Foo1 {
  folder Foo2
}

folder Foo3 {
  artifact Foo4
}

frame Foo5 {
  database Foo6
}

cloud vpc {
  node ec2 {
    stack stack
  }
}

@enduml
....
deployment

Timing Diagram

[plantuml,timing]

....
@startuml
!pragma layout smetana

robust "Web Browser" as WB
concise "Web User" as WU

@0
WU is Idle
WB is Idle

@100
WU -> WB : URL
WU is Waiting
WB is Processing

@300
WB is Waiting

@enduml
....
timing

More information can be found on https://asciidoctor.org/docs/asciidoctor-diagram/, https://plantuml.com/guide

Admonition Blocks

Admonitions are certain statements which draws reader’s attentions out of content’s flow. Following Admonitions supported by EHANDBOOK documentation:

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

Admonition Paragraph Syntax

  1. The label must be uppercase and immediately followed by a colon (:).

  2. Separate the first line of the paragraph from the label by a single space.

Examples for Admonition Paragraph Syntax

NOTE: This is an example for *Note*.
TIP: This is an example for *Tip*.
IMPORTANT: This is an example for *Important*.
CAUTION: This is an example for *Caution*.
WARNING: This is an example for *Warning*.

Admonition Block Syntax

[NOTE]
.This is an example for *Admonition Block Syntax*.

====
Following rules are to be followed for creating a Adomonition Block Syntax.

.Set the label in an attribute list on a delimited block. The label must be uppercase.
.Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs (====).
====

More delimited block

Any block can have a title. A block title is defined using a line of text above the block that starts with a dot. That dot cannot be followed by a space. For block images, the title is displayed below the block. For all other blocks, the title is typically displayed above it. Following Delimited Blocks are supported in EHANDBOOK:

  • Sidebar Block

.Sidebar title
****
example to check sidebar block
****

  • Example Block

.Example block Title
====
example of example block
====

  • Quote Block

[quote, Albert Einstein, Citation if any]
A person who never made a mistake never tried anything new.

Important Notices

NOTICE

Incomplete container content due to defective or inconsistent input data

Content of the generated EHANDBOOK Container may be missing, if the input data used for generating the container is defective or inconsistent. Affected container contents cannot be displayed or will be displayed incorrectly in the EHANDBOOK-NAVIGATOR. Therefore, always check the log file of the EHANDBOOK Container-Build. Defective or inconsistent input data that have led to errors when converting will be tracked in the log file.

The content consistency is in the responsibility of the data supplier (documentation publisher). We recommend that the data supplier develop a standard procedure for pre-processing the input data outside the EHANDBOOK Container-Build tool chain to ensure the data consistency and to reduce the workload for reviewing the input data. In addition, the pre-processing should be properly documented to ensure transparency.

After generating a new container:

  1. Check the entries in the log file of the EHANDBOOK Container-Build indicating defective or inconsistent input data.

  2. If necessary, fix the incorrect or inconsistent input data.

  3. Re-build the EHANDBOOK Container.

  4. Only provide containers for further usage in the EHANDBOOK-NAVIGATOR, if the log file contains no entries, indicating any defective or inconsistent input data.