anchor.diff:  
   [[doc-guidelines-writing]]
   == Writing
  -
  -Put one sentence on each line.
  -This makes it easy to move content around, and also easy to spot (too) long sentences.
  -It helps also to assign comments on a sentence in GitHub and allows easier merging.
  -
  -NOTE: Other than writing documentation, you can help out by providing comments about improvements or reporting bugs - head over to the http://issues.opennms.org/browse/NMS/component/10011[issue tracker for documentation] to do that!
  +The following rules wil help you to commit correctly formatted and prepared documentation for inclusion in the OpenNMS project.
  +It is important that we maintain a level of consistency across all of our commiters and the documentation they produce.
  +
  +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.
  +
  +NOTE: 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: http://issues.opennms.org/browse/NMS/component/10011[issue tracker for documentation]!
   
   [[doc-guidelines-conventions]]
   === Conventions for text formatting
  -To give the documentation a consistent layout the following conventions are used:
  -
  -* File names and path is written in `'poller-configuration.xml'` and will be rendered as: 'poller-configuration.xml'
  -* Names which indicates special attention, e.g. this configuration matches \*any* entry: which is rendered as: this configuration matches *any* entry
  -* \_Italics_ is rendered as _Italics_ and used for emphasis and indicate internal names and abbreviations.
  -* \*Bold* is rendered as *Bold* and used sparingly, for strong emphasis only.
  -* \+methodName()+ is rendered as +methodName()+ and is used for literals as well
  -  (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).
  -* Mono\+\+space\++d is rendered as Mono++space++d and is used for monospaced letters.
  -* \'my/path/' is rendered as 'my/path/' which is used for file names and paths.
  -* \\``Double quoted'' (that is two grave accents to the left and two acute accents to the right) renders as ``Double quoted''.
  -* \`Single quoted' (that is a single grave accent to the left and a single acute accent to the right) renders as `Single quoted'.
  +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 indicate 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);
  +* Mono\+\+space\++d is rendered as Mono++space++d and is used for monospaced letters;
  +* \'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'.
   
   [[doc-guidelines-gotchas]]
   === 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
  -* Always leave a blank line at the end of documents
  +It might be the title ends up in the last paragraph of the document;
  +* Always leave a blank line at the end of documents;
   * As +{}+ are used for Asciidoc attributes, everything inside will be treated as an attribute.
  -  What you have to do is to escape the opening brace: +\\{+.
  -  If you don't, the braces and the text inside them will be removed without any warning being issued!
  -* Forcing line breaks can be achieved with ` +` at the end of the line followed by a line break
  +  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 being issued!;
  +* Forcing line breaks can be achieved with ` +` at the end of the line followed by a line break.
   
   .Example in source force line break
   [source]
  
positive.code: = The Document Title
  ----
  
  To push the headings down to the right level in the output, the +leveloffset+
  attribute is used when including the document inside of another document.
  
  Subsequent headings in a document should use the following syntax:
  
  
negative.code: [[doc-guidelines-links]]
  == Links
  
  When you need to link to other parts of the manual you use the target id.
  To use a target id you follow this syntax:
  
  [source]
  ----
  <<doc-guidelines-links>>
  ----
  
  This will render as: <<doc-guidelines-links>>
  
  [NOTE]
  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, then follow this procedure:
  
  [source]
  ----
  <<target-id, link text that fits in the context>>
  ----
  
  NOTE: Having lots of linked text may work well in a web context but is a distracting in print. 
  The documentation we are creating is intended for both mediums so be considerate of this in your usage.
  
  If you wish to use an external link, they are are added as:
  
  [source]
  ----
  http://www.opennms.org/[Link text here]
  ----
  
  This will render in the output as: http://www.opennms.org/[Link text here]
  
  For short links it may be benificial not to use accompanying link text:
  
  [source]
  ----
  http://www.opennms.org/
  ----
  
  Which renders as: http://www.opennms.org/
  
  NOTE: It is acceptable to have a period trailing after the URL, it will not render as a part of the link.
  
  [[doc-guideline-admonitions-notes]]
  == Admonitions and usefull notes
  
  These are useful for defining specific sections, such as Notes, Tips and Important information.
  We encourage the use of them in the documenatation as long as they are used appropriately.
  Choose from the following:
  
  .Source template for making a note for additional hints
  [source]
  