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 for 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 documentation uses the following conventions:

  • File names and paths are written in `poller-configuration.xml`. Rendered as poller-configuration.xml;

  • Names that indicate special attention, e.g., "this configuration matches *any* entry". Rendered as "this configuration matches any entry";

  • _Italics_ is rendered as Italics and is used for emphasis;

  • *Bold* is rendered as Bold. Use 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/. Use 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. In most cases, the "Description" field should appear in the column immediately following the item being described.

Construct tables as follows:

[options="header", cols="1,3,1"]
|===
| Parameter
| Description
| Default

| myFirstParm
| my first long description
| myDefault

| myScndParm
| my second long description
| myDefault
|===

This is rendered as:

Parameter Description Default

myFirstParm

my first long description

myDefault

myScndParm

my second long description

myDefault

With tables that are more than two columns, please use a separate line for each cell’s content.

For content that has required and optional elements, use the following format:

[options="header", cols="1,3,1"]
|===
| Parameter
| Description
| Default

3+|*Required*

| myFirstParm
| my first long description
| myDefault

| myScndParm
| my second long description
| myDefault

3+| *Optional*

| mythrdParm
| my third long description
| myDefault

| myfourthParm
| my fourth long description
| myDefault

|===

This renders as follows:

Parameter Description Default

Required

myFirstParm

my first long description

myDefault

myScndParm

my second long description

myDefault

Optional

mythrdParm

my third long description

myDefault

myfourthParm

my fourth long description

myDefault