contributing a change.
-structure
----------
+Branches
+--------
+
+The online documentation published at <http://lttng.org/docs/> 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
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
preserve the document's visual consistency.
-#### tip/note block
+#### Tip/note/warning/error blocks
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
<a href="https://github.com/lttng/lttng-docs" class="ext">public</a>.
```
+Sometimes, however, it is necessary to write internal links in plain
+HTML, for example in tip blocks, since Markdown code is not processed.
+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:
```
-#### non-breaking spaces
+#### Non-breaking spaces
Sometimes, a non-breaking space HTML entity (` `) needs to be
explicitly written.
```
-#### 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
```
-#### terminal boxes
+#### Terminal boxes
A terminal box, where command lines are shown, is a simple `<pre>`
with the `term` class:
</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
(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
+----------
+
+If you make a change to a single contents file, prefix your Git commit
+message's first line with the file ID followed by `: `, e.g:
+
+ archlinux: minor fix