Writing

When writing place a single sentence on each line. This makes it easy to move content around, and also easy to spot long, or fragmented, sentences. This will also allow us to assign comments on a sentence in GitHub which will facilitate easier merging.

Other than writing documentation, you can help out by providing comments on documentation, reviewing, suggesting improvements or reporting bugs. To do this head over to GitHub.

Conventions for Text Formatting

The following conventions are used:

  • File names and path are written in `poller-configuration.xml` they will be rendered in: poller-configuration.xml;

  • Names that indicate special attention, e.g., this configuration matches *any* entry: this is rendered as: this configuration matches any entry;

  • _Italics_ is rendered as Italics and used for emphasis and indicates internal names and abbreviations;

  • *Bold* is rendered as Bold and should be used sparingly, for strong emphasis only;

  • +methodName()+ is rendered as methodName() and is also used for literals, (note: the content between the + signs will be parsed);

  • `command` is rendered as command (typically used for command-line or parts used in configuration files) (note: the content between the ` signs will not be parsed);

  • `my/path/` is rendered as my/path/. This is used for file names and paths;

  • \``double quote'' (which is two grave accents to the left and two acute accents to the right) renders as ``double quote'';

  • \`single quote' (which is a single grave accent to the left and a single acute accent to the right) renders as `single quote'.

Gotchas

  • Always leave a blank line at the top of the documents section. It might be the title ends up in the last paragraph of the document.

  • Start in line 2 setting a relative path to the images directory to picture rendering on GitHub:

// Allow image rendering
:imagesdir: relative/path/to/images/dir
  • Always leave a blank line at the end of documents.

  • As {} are used for Asciidoc attributes, everything inside will be treated as an attribute. To avoid this you have to escape the opening brace: \\{. If you do not escape the opening brace, the braces and the text inside them will be removed without any warning.

  • Force line breaks with ` +` at the end of the line followed by a line break.

Example in source: force line break
This is the first line +
and this a forced 2nd line
Rendered output with forced line break

This is the first line
and this a forced 2nd line

Headings and document structure

Each document starts with headings from level zero (the document title). Each document should have an ID. In some cases sections in the document also need to have ID’s; this depends on where they fit in the overall structure. If you wish to have a link to specific content that content has to have an ID. A missing ID in a mandatory place will cause the build to fail.

To start a document:

[[unique-id-verbose-is-ok]]
= The Document Title

If you are including the document inside another document and you need to push the headings down to the right level in the output, use the leveloffset attribute.

Subsequent headings in a document should use the following syntax:

== Subheading

... content here ...

=== Subsubheading

content here ...

Use the target ID to link to other parts of the manual. To use a target ID, use this syntax:

<<doc-guidelines-links>>

This will render as: Links

To use the target ID in you document simply write the target ID in your text, for example:

see <<target-id>>

this should suffice for most cases.

If you need to link to another document with your own link text, use this syntax:

<<target-id, link text that fits in the context>>
Having a lot of linked text may work well in a web context but is distracting in print. The documentation is intended for both media so be considerate of this in your usage.

To use an external link, use this syntax:

http://www.opennms.org/[Link text here]

This will render in the output as: Link text here

For short links it may be beneficial not to use accompanying link text:

http://www.opennms.org/

Which renders as: http://www.opennms.org/

It is acceptable to have a period trailing after the URL, it will not render as a part of the link.

Admonitions and Useful Notes

Use to define specific sections, such as Notes, Tips and Important information. We encourage their use in the documentation as long as they are used appropriately. Choose from the following:

Source template for making a note for additional hints
NOTE: This is my note.

This is how its rendered:

This is my note.
Source for giving a tip
TIP: This is my tip.

This is how its rendered:

This is my tip.
Source for giving a important hint
IMPORTANT: This is my important hint.

This is how its rendered:

This is my important hint.
Source for giving a caution
CAUTION: This is my caution.

This is how its rendered:

This is my caution.
Source for giving a warning
WARNING: This is my warning.

This is how its rendered:

This is my warning.

A multiline variation:

TIP: Tiptext. +
     Line 2.

Which is rendered as:

Tiptext.
Line 2.
Remember to write these in full caps. There is no easy way to add new admonition types; do not create your own.

Attributes

Common attributes you can use in documents:

  • \{\opennms-version} - rendered as "{\opennms-version}"

These can substitute part of URLs that point to, for example, APIdocs or source code. Note that opennms-git-tag also handles the case of snapshot/master.

Sample Asciidoc attributes you can use:

  • {docdir} - root directory of the documents

  • {nbsp} - non-breaking space

Comments

There’s a separate build that includes comments. When the comments are used they show up with a yellow background. This build doesn’t run by default, but after a normal build, you can use make annotated to create a build yourself. You can use the resulting 'annotated' page to search for content as the full manual is a single page.

To write a comment:

// this is a comment

Comments are not visible in the standard build. Comment blocks won’t be included in the output of any build. The syntax for a comment block is:

////
Note included in here will still be processed, but not make it into the output.
That is, missing includes here will still break the build!
////

Tables

Use tables to represent structured information. A table is constructed in the following manner:

[options="header, %autowidth"]
|===
| Parameter     | Description                | Required | Default value
| `myFirstParm` | my first long description  | required | `myDefault`
| `myScndParm`  | my second long description | required | `myDefault`
|===

This is rendered as:

Parameter Description Required Default value

myFirstParm

my first long description

required

myDefault

myScndParm

my second long description

required

myDefault

Please align your columns in the AsciiDoc source for better readability when editing in text view. If you have a very long description, break at 120 characters and align the text to improve source readability.
01 long table formatting
Figure 1. Example in AsciiDoc source for very long table descriptions

this is rendered as:

Parameter Description Required Default value

basic-authentication

Authentication credentials to perform basic authentication. Credentials should comply to RFC1945 section 11.1, without the Base64 encoding part. That’s: be a string made of the concatenation of:
1- the user ID;
2- a colon;
3- the password.
basic-authentication takes precedence over the user and password parameters.

optional

-

header[0-9]+

Additional headers to be sent along with the request. Example of valid parameter’s names are header0, header1 and header180. header is not a valid parameter name.

optional

-