5-example.adoc

Example Clause

Note	Instructions This section explains some concepts frequently required by Asciidoc novices. Please use this file as a template for your own clauses.

Headlines

All headlines are marked by "=" signs. The top level in each each file starts with level 2 ("=="). Important: For whatever strange reason, headings in annexes are marked differently.

Figures

If you want to reference a figure by using a figure number, it is important to use the following syntax. The figure identifier for Figure 1 is the first statement of the header. Please adapt the width as appropriate, but generally a width of 800 is good for landscape-shaped figures and 400 is good for portrait-shaped ones.

Figure 1. This is an example figure

It is important that you use the same syntax for all images, otherwise the automatic numbering is corrupted!

Tables

Tables are easy to deal with as long as you keep them simple! To add a table, please use the following syntax.

Table 1. Countries in Europe

Country	Population	Size
Monaco	36371	1.98
Gibraltar	29431	6.8

The first line is used for referencing. You can reference Table 1 in your text. The only thing you should change in that line is the table id, which is "table_countries" in this case. Please do not remove the "#", please do not change anything else in that line.

You can define the style and width of each column. In our example, the first column takes 50% of the entire width, the second and third column take 25% each. The total width of the table is 75% of the text width.

The letters after the width percentage indicate if the column is e=emphasis, m=monospaced, a=asciidoc, s=strong. The d=default does not need to be set.

Cell alignment: If you need to align a column, you may indicate this by setting ^,<, or >. Examples:

• ^25m = centered, 25% width, monospaced.

• >25e = aligned right, 25% width, emphasised

• <25 = aligned left, 25% width, asciidoc

In any case, please make sure that your table fit on a piece of A4 or letter-size paper!!

Recommended Asciidoc Environment

We recommend to use asciidoctor and asciidoctor-pdf in combination with the Atom editor.

Installation on MacOS and Linux

1. Please follow the steps on https://asciidoctor.org/#installation.

2. Install the bibtex extension: gem install asciidoctor-bibtex

Installation on Windows

We have made best experiences with the following steps:

1. Install ruby for windows: https://rubyinstaller.org/downloads/. If you experience any issues, the following link may help: stackoverflow

2. Open command prompt and install two gems:

   1. Execute: "gem install asciidoctor"

   2. Execute: "gem install asciidoctor-bibtex"

3. Text your installation

   1. Open a folder that contains your Engineering Report asciidoc source files, including the er.adoc file.

   2. Execute the following command: asciidoctor -r asciidoctor-bibtex er.adoc

Using Asciidoctor with Atom

In Atom, you should install the following packages:

• asciidoc-preview

• autocomplete-asciidoc

• language-asciidoc

• markdown-writer: requires changing of key-map to allow for keyboard shortcuts such as e.g. bold

• platformio-IDE-terminal

This environment allows you to use keyboard shortcuts, autocomplete, syntax highlighting and a rendered preview for asciidoc; and provides you an terminal window within the editor to convert your asciidoc to html and pdf.

Asciidoc Conversion

In order to achieve a uniform look-and-feel of all ERs in both HTML and PDF, we have provided a css and theme file. The following commands can be used to convert the ER:

Command for PDF output: asciidoctor-pdf -r asciidoctor-bibtex -a pdf-stylesdir=resources -a pdf-style=ogc -a pdf-fontsdir=resources/fonts er.adoc

Command for HTML output: asciidoctor -r asciidoctor-bibtex -a linkcss -a stylesheet=rocket-panda.css -a stylesdir=./stylesheets er.adoc

Source Code

You can add code snippets using the following syntax:

Code Example XML

<section>
  <title>Section Title</title> <!--(1)-->
</section>

1. This notation allows to reference particular sections within the code.

You can alternatively use line numbers to reference a specific section in your code.

Code Example JSON

{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

As shown in line 2, the value of "id" is "File".

Asciidoc(tor) Syntax Help

Is available e.g. here: http://asciidoctor.org/docs/

Citations

Please use the following syntax to insert citations anywhere in the text:

cite:[VanZyl2009]

or, if it is more than one citation that should be added at the same location, use

cite:[Pross2018,OGCTechTrends2018]

which will create links in the compiled HTML/PDF that look as follows: cite:[VanZyl2009], of for the second example given above, it results in cite:[Pross2018,OGCTechTrends2018]

Then you need to provide all citation information in the file resources/bibtex-file.bib. This file uses the bibtex file format, which is defined in full detail here. The bibtex-style file shall remain untouched.

The conversion of cite:[] takes place at the time of asciidoc-to-pdf/html conversion and requires two things:

1. The definition of the bibtex-file and the bibtex-style attributes. This is done in this template in file er.adoc. Please make sure that both files are available at their defined locations.

Examples of bibtex attributes as set in file er.adoc

:bibtex-file: resources/bibtex-file.bib
:bibtex-style: resources/lncs.csl

2. Adding a flag to the asciidoctor conversion command

asciidoctor -r asciidoctor-bibtex er.adoc

A full conversion command could look as in the following example:

asciidoctor -r asciidoctor-bibtex -a linkcss -a s tylesheet=rocket-panda.css -a stylesdir=./resources/stylesheets er.adoc

For further information, please consult https://github.com/asciidoctor/asciidoctor-bibtex.