Add dotlinks.py

[lttng-docs.git] / contrib-guide.md

diff --git a/contrib-guide.md b/contrib-guide.md
index f3cd76b646926826b75b652b4c36e7eae0446f26..3c2c25c5b4a2477b481b6c1dfa46c25d044d235a 100644 (file)
--- a/contrib-guide.md
+++ b/contrib-guide.md
@@ -6,7 +6,7 @@ Documentation's source. Make sure you read it thoroughly before
 contributing a change.
 
 
-branches
+Branches
 --------
 
 The online documentation published at <http://lttng.org/docs/> is always
@@ -15,7 +15,7 @@ The `master` branch contains the current documentation of the upcoming
 LTTng release.
 
 
-structure of sources
+Structure of sources
 --------------------
 
 `toc/docs.yml` is a YAML tree of all chapters, sections and subsections.
@@ -43,18 +43,18 @@ First paragraph goes here.
 Editable image sources are placed in `images/src` and their rendered
 equivalents are located in `images/export`.
 
-`tools/checkdocs.py` is a Python 3 script which may be used to find
-typical errors in the whole documentation (dead internal links,
-common grammar mistakes, etc.). It needs the
-[`termcolor`](https://pypi.python.org/pypi/termcolor) Python package.
-Run it from the repository's root:
+`tools/docs2json.py` is a Python 3 script which may be used to get
+the graph of internal and external links and to find
+typical errors in the whole documentation, like dead internal links.
+It needs the
+[`termcolor`](https://pypi.python.org/pypi/termcolor) Python 3 package.
+Run it from the repository's root and ignore its standard output
+to view the warnings and errors:
 
-    tools/checkdocs.py
+    tools/docs2json.py > /dev/null
 
-and it will potentially output a list of errors and warnings.
 
-
-format of sources
+Format of sources
 -----------------
 
 The sources are made of a fusion of Markdown and HTML processed by
@@ -72,7 +72,7 @@ document. If you need to contribute, please use them when needed to
 preserve the document's visual consistency.
 
 
-#### tip/note block
+#### Tip/note/warning/error blocks
 
 Tip/note block:
 
@@ -88,10 +88,14 @@ Tip/note block:
 </div>
 ```
 
-Title should be `Tip:` for a tip and `Note:` for a note.
+Replace the `tip` class with `warn` for a warning block, and with `err`
+for an error message block (when JavaScript is needed but is disabled, etc.).
+
+Title should be `Tip:` for a tip, `Note:` for a note, `Warning:` for a
+warning, and `Error:` for an error.
 
 
-#### external links
+#### External links
 
 Internal links should always use Markdown
 (`[caption](#doc-section)`). External links, however, need a special
@@ -108,7 +112,7 @@ In these cases, add the `int` CSS class as a hint to prevent the static
 analyzer from complaining (`tools/checkdocs.py`).
 
 
-#### abbreviations
+#### Abbreviations
 
 Use `<abbr>` for describing abbreviations. This should only be used
 for the first use of the abbreviation:
@@ -119,7 +123,7 @@ project is an open source system software package [...]
 ```
 
 
-#### non-breaking spaces
+#### Non-breaking spaces
 
 Sometimes, a non-breaking space HTML entity (`&nbsp;`) needs to be
 explicitly written.
@@ -135,7 +139,7 @@ A check is performed every 3000&nbsp;ms.
 ```
 
 
-#### placeholders in inline code
+#### Placeholders in inline code
 
 You must use `<em>` to emphasize a placeholder within a `<code>` tag
 because Markdown backticks (<code>`</code>) always render their
@@ -147,7 +151,7 @@ Name your file <code>something_<em>sys</em>.c</code>, where
 ```
 
 
-#### terminal boxes
+#### Terminal boxes
 
 A terminal box, where command lines are shown, is a simple `<pre>`
 with the `term` class:
@@ -181,36 +185,24 @@ Results of commands, if needed, should be presented in a simple
 </pre>
 
 
-#### images
+#### Images
 
 Use
 
 ```html
-<div class="img img-70">
-    <img src="/images/docs/image-name.png" alt="Short description">
-</div>
+<figure class="img img-70">
+    <img src="/images/docs26/image-name.png" alt="Short description">
+</figure>
 ```
 
+Replace `docs26` with the appropriate version tag depending on the
+checked out branch.
+
 to display an image. Change `img-70` to `img-` followed by the
 width percentage you wish.
 
-The SVG format is preferred. In this case, use the `<object>` tag to
-render an interactive SVG, with an inner raster image fallback for
-basic browsers:
-
-```html
-<div class="img img-90">
-  <object data="/images/docs/image-name.svg" type="image/svg+xml">
-    <img src="/images/docs/image-name.png" alt="Short description">
-  </object>
-</div>
-```
-
-An interactive SVG object allows its text to be selected, amongst other
-features.
-
 
-convention
+Convention
 ----------
 
 A few rules to comply with in order to keep the text as
@@ -235,10 +227,12 @@ consistent as possible:
     (good: `include/trace/events`, bad: `include/trace/events/`).
   * Keep the text as impersonal as possible (minimize the use of
     _I_, _we_, _us_, etc.), except for user guides/tutorials where
-    _we_ have an ongoing example.
+    _we_ have an ongoing example with _you_.
+  * Minimize the use of the future tense (_will_).
+  * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
 
 
-committing
+Committing
 ----------
 
 If you make a change to a single contents file, prefix your Git commit