4 This guide presents the structure and conventions of the LTTng
5 Documentation's source. Make sure you read it thoroughly before
12 The online documentation published at <http://lttng.org/docs/> is always
13 compiled from the sources of this repository's latest stable branch.
14 The `master` branch contains the current documentation of the upcoming
21 `toc/docs.yml` is a YAML tree of all chapters, sections and subsections.
22 It indicates which unique ID is linked to which position in the
23 hierarchy and its true title.
25 In the `contents` directory, the `preface.md` file is the preface contents.
26 Each chapter has its own directory (directory names are not significant).
27 Within those, `intro.md` files are partial introductions and then each
28 section has its own directory, and so on, unless a section has no
29 subsections, in which case all its contents is in a single Markdown file
30 named _more or less_ like its ID.
32 Each Markdown file begins with a YAML front matter which only contains
33 the unique ID of this chapter/section:
37 id: unique-id-goes-here
40 First paragraph goes here.
43 Editable image sources are placed in `images/src` and their rendered
44 equivalents are located in `images/export`.
46 `tools/checkdocs.py` is a Python 3 script which may be used to find
47 typical errors in the whole documentation (dead internal links,
48 common grammar mistakes, etc.). It needs the
49 [`termcolor`](https://pypi.python.org/pypi/termcolor) Python package.
50 Run it from the repository's root:
54 and it will potentially output a list of errors and warnings.
60 The sources are made of a fusion of Markdown and HTML processed by
61 [kramdown](http://kramdown.gettalong.org/). Markdown is preferred,
62 HTML being only used for specific cases that need special formatting
63 not available using plain Markdown. The kramdown processor is clever
64 enough to support both languages in the same file, even in the same
70 Here's a list of HTML blocks and inline code used throughout the
71 document. If you need to contribute, please use them when needed to
72 preserve the document's visual consistency.
82 <span class="t">Title goes here followed by colon:</span>Text goes
86 Multiple paragraphs is allowed.
91 Title should be `Tip:` for a tip and `Note:` for a note.
96 Internal links should always use Markdown
97 (`[caption](#doc-section)`). External links, however, need a special
98 style and must use the `<a>` tag with the `ext` CSS class:
101 The LTTng Documentation is
102 <a href="https://github.com/lttng/lttng-docs" class="ext">public</a>.
105 Sometimes, however, it is necessary to write internal links in plain
106 HTML, for example in tip blocks, since Markdown code is not processed.
107 In these cases, add the `int` CSS class as a hint to prevent the static
108 analyzer from complaining (`tools/checkdocs.py`).
113 Use `<abbr>` for describing abbreviations. This should only be used
114 for the first use of the abbreviation:
117 The <abbr title="Linux Trace Toolkit: next generation">LTTng</abbr>
118 project is an open source system software package [...]
122 #### non-breaking spaces
124 Sometimes, a non-breaking space HTML entity (` `) needs to be
130 The size of this file is 1039 bytes.
132 This integer is displayed in base 16.
134 A check is performed every 3000 ms.
138 #### placeholders in inline code
140 You must use `<em>` to emphasize a placeholder within a `<code>` tag
141 because Markdown backticks (<code>`</code>) always render their
145 Name your file <code>something_<em>sys</em>.c</code>, where
146 <code><em>sys</em></code> is your system name.
152 A terminal box, where command lines are shown, is a simple `<pre>`
153 with the `term` class:
157 echo This is a terminal box
161 Do not prefix command lines with prompts (`$`/`#`) since this makes
162 copy/paste operations painful.
164 You may use `<strong>` tags to emphasize a part of the command line:
168 echo This is a <strong>terminal</strong> box
172 Results of commands, if needed, should be presented in a simple
173 `text` kramdown code block:
177 [15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
178 [15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" }
179 [15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
189 <div class="img img-70">
190 <img src="/images/docs/image-name.png" alt="Short description">
194 to display an image. Change `img-70` to `img-` followed by the
195 width percentage you wish.
197 The SVG format is preferred. In this case, use the `<object>` tag to
198 render an interactive SVG, with an inner raster image fallback for
202 <div class="img img-90">
203 <object data="/images/docs/image-name.svg" type="image/svg+xml">
204 <img src="/images/docs/image-name.png" alt="Short description">
209 An interactive SVG object allows its text to be selected, amongst other
216 A few rules to comply with in order to keep the text as
217 consistent as possible:
219 * Use _user space_, not _userspace_ nor _user-space_.
220 (neither _user land_).
221 * Use _file system_, not _filesystem_.
222 * Use _use case_, not _use-case_ nor _usecase_.
223 * Use _the C standard library_, not _libc_.
224 * Use _log level_, not _loglevel_.
225 * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
226 _LTTng-tools_, not _modules_, _UST_ and _tools_.
227 * All code snippets should use 4 spaces for indentation (even C)
228 so that they are not too large.
229 * Prefer emphasis (Markdown: `_something_`, HTML: `<em>something</em>`)
230 to strong (Markdown: `**something**`, HTML: `<strong>something</strong>`)
231 for emphasizing text.
232 * Try to stay behind the 72th column mark if possible, and behind
233 the 80th column otherwise.
234 * Do not end directory paths with a forward slash
235 (good: `include/trace/events`, bad: `include/trace/events/`).
236 * Keep the text as impersonal as possible (minimize the use of
237 _I_, _we_, _us_, etc.), except for user guides/tutorials where
238 _we_ have an ongoing example.
244 If you make a change to a single contents file, prefix your Git commit
245 message's first line with the file ID followed by `: `, e.g: