AsciiDoc Specification

AsciiDoc Support in EHANDBOOK

This document provides a brief information on the AsciiDoc functionality in general and the supported features and special meanings within EHANDBOOK.

The ETAS AsciiDoc converter is an add-on for the directory based EHANDBOOK Container-Build Tool-Chain and generates textual and graphical content for EHANDBOOK containers out of AsciiDoc files.

AsciiDoc is a lightweight markup language for authoring documentation in plain text. So any kind of text editor can be used to create the files. There are a lot of ASCII characters, which become a special meaning in the context of AsciiDoc.

EHANDBOOK: File extension must be *.adoc or *.asciidoc for EHB. EHB supports only a subset of the AsciiDoc functionality. Other features than described below may also work, but not guaranteed by ETAS.

Now let’s have a look into some of these magic ASCII characters and start with a header:

Document Header and Section Titles

A document header represents the title of the document. Document header can be followed then by texts, images, lists, table or section titles

Document title syntax: using '=' character(s) at the very beginning of a new line:

= Document Header Text (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

== Another Level 1 Section Title

will look in EHB like:

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Another Level 1 Section Title

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

EHANDBOOK: For EHB, the document header is expected as the very first line in the document. If document header is not present, then name of the folder in which AsciiDoc file resides will be considered as document title. Each sub section title appears as a sub chapter in the TOC in EHB-NAVIGATOR.

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.

Will look in EHB like:

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

Will look in EHB like:

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

Will look in EHB like:

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

EHANDBOOK: 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
|===

Will look in EHB like:

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

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

Images in EHANDBOOK

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

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

EHB generated Images linked with Model

Model hierachy screenshot made by EHB and linked 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.

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

Will look in EHB like:

/*****************************************************************************************************
 * 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;
}

EHANDBOOK: 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

By click on the link, 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.

EHANDBOOK: Only absolute file paths are supported in EHB.

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