X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=contrib-guide.md;h=5728a5ddaf0844254bfc2ea525896c469028643a;hb=3375e5b0d830be87b1ce045f6435900e17e63cf1;hp=0293c4d83c899824e5c8255ddbb3866f7d337e59;hpb=cc3ab47f680b518a95b2f4e862537124b0d2c4e2;p=lttng-docs.git
diff --git a/contrib-guide.md b/contrib-guide.md
index 0293c4d..5728a5d 100644
--- a/contrib-guide.md
+++ b/contrib-guide.md
@@ -6,8 +6,17 @@ Documentation's source. Make sure you read it thoroughly before
contributing a change.
-structure
----------
+Branches
+--------
+
+The online documentation published at is always
+compiled from the sources of this repository's latest stable branch.
+The `master` branch contains the current documentation of the upcoming
+LTTng release.
+
+
+Structure of sources
+--------------------
`toc/docs.yml` is a YAML tree of all chapters, sections and subsections.
It indicates which unique ID is linked to which position in the
@@ -45,7 +54,7 @@ Run it from the repository's root:
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
@@ -63,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:
@@ -79,10 +88,14 @@ Tip/note block:
```
-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
@@ -99,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 `` for describing abbreviations. This should only be used
for the first use of the abbreviation:
@@ -110,7 +123,7 @@ project is an open source system software package [...]
```
-#### non-breaking spaces
+#### Non-breaking spaces
Sometimes, a non-breaking space HTML entity (` `) needs to be
explicitly written.
@@ -126,7 +139,7 @@ A check is performed every 3000 ms.
```
-#### placeholders in inline code
+#### Placeholders in inline code
You must use `` to emphasize a placeholder within a `` tag
because Markdown backticks (`) always render their
@@ -138,7 +151,7 @@ Name your file something_sys.c, where
```
-#### terminal boxes
+#### Terminal boxes
A terminal box, where command lines are shown, is a simple `
`
with the `term` class:
@@ -172,36 +185,24 @@ Results of commands, if needed, should be presented in a simple
-#### images
+#### Images
Use
```html
-
-
-
+
+
+
```
+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 `