The following typographic conventions are used in this Reference Manual.
Subheading (Level 1)
Longer chapters can be structured using subheadings. This text is written beneath a level 1 sub heading 'Subheading (Level 1)'
Subheading (Level 2)
2nd level subheadings can also be used to structure longer chapters.
Terms
When we introduce a new term we put that term in italic letters to distinguish the term from the surrounding text. If the usage of the term in the rest of the chapter is unambiguous only the first occurrence of the term will be put in italic letters.
This is an example term.
Captions and references
Figures, tables, code listings etc have a caption. Captions within one chapter are numbered sequentially and when the chapter text refers to a figure the number of the figure is used. E.g. for details see figure 1.
If figures contain numbered annotations we refer to these annotation like Figure 1:1. In Figure 1 you see two numbered annotations.
Figure 1: This is the caption to an image
User provided data
Whenever we give examples of data the user specifies, this date is shown in a mono-space font like: the data you type
Do distinguish user provided text from punctuation following it punctuations after user provided text are separated by a blank, as you can see in the following example:
The following text is an an example text provided by the user: example 1 . The point is not part of the example.
In many case we use variables in these texts e.g. <firstname>, <lastname> the text in <> should then be replaced by the text you provide.
Keyboard shortcuts
Carets and special formatting are used to identify keys on the keyboard E.g. Hit <Del> to delete the entry.
Mathematical formulas
Simple mathematical formulas are formatted like this: a^2 + b^2 = c^2 .
Code listings
For longer formulas or algorithms we use separate listing blocks like shown in Listing 1.
For longer formulas pseudo algorithms or listings of code, text files etc. we use code listing formatting. |
Listing 1: Code listings always have a caption, in text we refer to the number of the listing.
Important information
Note: Important information is specially highlighted by this formatting, it is only used when we think that the enclosed text is really important for understanding how the system works or for preventing problems with the system.
References to user interface elements
When documenting graphic user interfaces (GUI) we often refer to elements on that graphical user interface. To distinguish the name of the graphical element from the text the element the name is shown like this: GUI element.
