7.8.1 Help file format

Help files are now simply defined in Markdown a lightweight markup language for creating formatted text using a plain-text editor and are stored in .md files.

We are supporting the standard Markdown as described at https://commonmark.org/.

If you want to have your own help files included into the online help system, please provide the new driver definition and your help files to SatService GmbH and we will automatically build the new online help with your additional files.

Attention! The old sat-nms help file format was replaced by this standardized Markdown files.

For your reference please find below this deprecated information:

So the following chapter describes the format of the source files the online manual of the software is built from.

Topic Definitions

The online manual divides the complete text into topics, where each topic is compiles to one web page. A topic is identified by it's unique four digit topic number. This number is used to build the file name of the web page and also to reference the page in hyper links.

In the source text a topic starts with a topic definition line and ends where the next topic starts. The topic definition looks like this:

.topic TTTT L The title of this topic

The keyword '.topic' must start at the very first column of the line. Further on, TTTT is the for topic number of the topic to define. L is a number in the range 1..4 defining the level of this heading in the table of contents. The remaining part of the line defines the title of the topic.

Paragraphs

The HTML text is shown by the browser as left justified text, made up to the width of the browser window. Line breaks and paragraphs do not appear where you type them in the source code, you have explicitly to insert line break or paragraph break commands into the source text to get these breaks in the output.

Both commands may appear anywhere in the line, however, usually they are placed either at the line end or in the own line.

Formatted Lists

You may typeset ordered (numbered) lists and unordered (bullet) lists in the text. Browsers usually display each list item as a paragraph, preceded by either the paragraph number or a list item symbol. You may nest lists of both types to any depth. The help compiler simply translates the list formatting commands to HTML, it does not check if each list is properly terminated. If you produce invalid HTML code because of missing list end marks, some browsers will give strange results.

Although these commands are recognized everywhere in the line, formatting lists as shown in the example below makes the source well readable.

    .ol
      .li This is the first list item
      .li This is the second one, it contains a lot of text which does not fit in one line.
      .li The third item is a short one again.
    .eol

Tables

Help pages may contain tables consisting of an almost arbitrary number of columns. Tables appear with a pale blue background. You have no control over the precise layout of the table, it is shown as the browser likes to display plain HTML tables with a cell background set. Because no geometry must be specified, it is very simple to define the table in the source text:

With the commands shown above, the table gets defined cell by cell, row by row. Table definitions are translated by the help compiler one by one to HTML tags. When defining a table, be careful to define the same number of cells in each row and to terminate each row properly by a .te command. The example below shows in which way a simple table definition should be formatted in the source:

    .tl
    .ts cell 1/1   .tc cell 1/2   .tc cell 1/3   .te
    .ts cell 2/1   .tc cell 2/2   .tc cell 2/3   .te
    .ts cell 3/1   .tc cell 3/2   .tc cell 3/3   .te
    .etl

Images / Pictures

The user manual also contains images and diagrams. Files in GIF or JPG format may be included. The image files must be located in the same directory as the other files of the online help. You find already a bunch of image files there, most of them are copies of the tool bar icons used by the software.

If this is the only command in the line, be sure to add a single space character after the file name. This is due to a flaw of the help compiler which does not recognize the file name properly if it ends at the line end.

Pre-formatted Text

The text may include segments of 'pre-formatted' text, which the browser displays using a mono-spaced font with line breaks at the same positions as in the source. Pre-formatted text is used to include for example excerpts of configuration files.

The .pre and .epre commands must appear as single commands in a line, starting at the first column.

Emphasizing Text

Portions of text may be emphasized , bold printed or set in a typewriter font. To do this, enclose the text to highlight in curly braces and insert a letter e for emphasized, b for bold or t for typewrite directly after the opening brace. There must no be a space character between the opening brace and the code character. The opening and closing braces must be in the same line, nesting different hi-lighting styles is not allowed.

Cross-references / Hyper-links

You may include HTML hyper-links into the text to permit the reader to jump directly from one topic to another by a single mouse click. To insert a hyper-link, To do this, enclose the text to hi-light in braces and insert the sequence h#### directly after the opening brace. #### is to be replaced by the topic number to link to. Like with the character formatting codes above, there must no be a space character between the opening brace and the h. The opening and closing braces must be in the same line, no nesting of braces is allowed.

Paragraph Headings

There is no special command to insert paragraph headings. The topic title is the only heading for a help page. Only this will appear in the table of contents in the printed version.

To introduce headings on a paragraph level, use a bold printed, one line paragraph instead.

Escaping Dot Commands

Words in the help text containing dots (e.g. file names) may be confused with a dot command sequence by the help compiler. Example: MyDevice.proto in the source file will be printed as MyDevice at the end of one paragraph and roto at the beginning of the next one. This is because the .p sequence in the file name is translated to a paragraph break.

The .dot sequence is used to escape the dot command in such a situation. Spelling the file name MyDevice.proto in the source produces the desired output.

Comments

You may add comments or annotations to the source text of the document which later are not shown in the manual. Lines which start with a double percent character %% at the first column are skipped when the file is processed by the help compiler.

Conditional Compilation

The help compiler implements a mechanism to include or skip parts of the source text depending on a couple of environment information here called features. The conditional compilation mechanism closely follows that one used with common programming language compilers:

The %if , %else and %endif statements must appear singly in a line and must start at the first column in the line.

The following 'features' may be tested in an %if clause (testing other features, always results in not present):