Skip to content

Latest commit

 

History

History
141 lines (100 loc) · 5.34 KB

5-example.adoc

File metadata and controls

141 lines (100 loc) · 5.34 KB

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.

t14MindMap
Figure 1. High-Level Mind Map of Testbed-14

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:

cite:[VanZyl2009] cite:[Pross2018]

Then you need to provide all citation information in the file resources/bibtex-file.bib. Everything else is done automatically.

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