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
Formatted Text
Lists
Tables
Images
Include Files
Links

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:

Ordered list can have a list title followed by list elements in separate lines
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.

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[]

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[]

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

Links

AutoLink

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

http/https
file
mailto
ftp
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

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]

Note: 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]

Note: The above target link doesn’t contain FC name. So this link can be used within FC documentation 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

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

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:

Check the entries in the log file of the EHANDBOOK Container-Build indicating defective or inconsistent input data.
If necessary, fix the incorrect or inconsistent input data.
Re-build the EHANDBOOK Container.
Only provide containers for further usage in the EHANDBOOK-NAVIGATOR, if the log file contains no entries, indicating any defective or inconsistent input data.