Commit | Line | Data |
---|---|---|
81f5f33d | 1 | = The LTTng Documentation: Contributor's guide |
f0287ae1 | 2 | Philippe Proulx |
81f5f33d | 3 | 14 June 2021 |
f0287ae1 | 4 | |
81f5f33d PP |
5 | This guide presents the structure and conventions of the source of the |
6 | LTTng Documentation. Make sure you read it thoroughly before you | |
7 | contribute a change. | |
f0287ae1 PP |
8 | |
9 | ||
10 | [[principles]] | |
11 | == Principles | |
12 | ||
81f5f33d PP |
13 | The LTTng Documentation exists to make the https://lttng.org/[LTTng |
14 | project] useable. Without such a complete documentation consolidating | |
15 | the various concepts, features, and procedures of LTTng-tools, | |
16 | LTTng-UST, and LTTng-modules, most of the project would only be useable | |
17 | by its authors. | |
f0287ae1 | 18 | |
81f5f33d PP |
19 | Why not simply read the manual pages? While the LTTng manual pages are |
20 | complementary to the LTTng Documentation, they remain formal references: | |
21 | they lack the introductory quality and many procedural user guides found | |
22 | in this documentation. | |
f0287ae1 PP |
23 | |
24 | The core principle of the LTTng Documentation is to make the text as | |
25 | cleverly organized, easy to follow, precise, and consistent as possible. | |
81f5f33d PP |
26 | This involves keeping a high level of rigor to such things as the style, |
27 | voice, grammar, and layout of the document. | |
f0287ae1 PP |
28 | |
29 | Of course, those guidelines are not new to the technical writing realm, | |
30 | and it would be bold to devise a brand new manual of style for the sole | |
31 | existence of the LTTng Documentation when so many have already proven | |
32 | their value. This is why the LTTng Documentation (especially starting | |
81f5f33d | 33 | from version{nbsp}2.7) does its best to follow the rules of the |
f0287ae1 PP |
34 | https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual |
35 | of Style (4th edition)], a landmark work in its field. Of particular | |
36 | interest in this book are: | |
37 | ||
81f5f33d PP |
38 | * Chapter 1: _Microsoft style and voice_. |
39 | * Chapter 6: _Procedures and technical content_. | |
40 | * Chapter 7: _Practical issues of style_. | |
41 | * Chapter 8: _Grammar_. | |
42 | * Chapter 9: _Punctuation_. | |
43 | * Chapter 11: _Acronyms and other abbreviations_. | |
f0287ae1 PP |
44 | |
45 | ||
46 | == Organization of the repository and format | |
47 | ||
48 | The Git repository of the LTTng Documentation contains all the official | |
49 | versions of the documentation as separate source files. Each source file | |
81f5f33d PP |
50 | is in its own `2.__x__` directory, along with documentation resources |
51 | specific to this version of LTTng. The `common` directory contains | |
52 | common source files. | |
f0287ae1 PP |
53 | |
54 | The source files are written in | |
81f5f33d PP |
55 | http://www.methods.co.nz/asciidoc/[AsciiDoc] (the original, Python |
56 | version), a rich, lightweight markup language with all the blocks and | |
57 | inline elements needed to write backend-agnostic content. | |
f0287ae1 | 58 | |
81f5f33d PP |
59 | Although the official LTTng website uses a custom script to generate its |
60 | own HTML version of the LTTng Documentation, you can generate a | |
61 | self-contained HTML preview (see link:README.adoc[`README.adoc`]). The | |
62 | `asciidoc.html5.conf` AsciiDoc configuration file sets a few attributes | |
63 | and implements the required macros for this preview target. | |
f0287ae1 PP |
64 | |
65 | ||
66 | == Validation script | |
67 | ||
68 | Before you submit any change, make sure that the check script passes. | |
69 | This is a Python script which validates some elements of a specific | |
70 | document. | |
71 | ||
72 | You need the following dependencies to run the check script: | |
73 | ||
74 | * http://www.methods.co.nz/asciidoc/[AsciiDoc] | |
75 | * Python 3 | |
76 | * http://lxml.de/[lxml] Python 3 package | |
77 | * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package | |
78 | ||
79 | Run the check script: | |
80 | ||
81 | ---- | |
81f5f33d | 82 | $ python3 tools/check.py 2.12/lttng-docs-2.12.txt |
f0287ae1 PP |
83 | ---- |
84 | ||
81f5f33d | 85 | Replace `__2.12__` with the version of the document to validate. |
f0287ae1 PP |
86 | |
87 | ||
88 | == Style considerations | |
89 | ||
81f5f33d PP |
90 | As stated in "`<<principles,Principles>>`", the LTTng Documentation |
91 | follows the Microsoft Manual of Style (4th edition). We encourage you to | |
92 | read this work before you contribute a major change to the document. | |
f0287ae1 PP |
93 | |
94 | You also need to consider the following rules, often specific to the | |
95 | AsciiDoc format used to write the LTTng Documentation, when you edit | |
96 | existing content or when you create new sections. | |
97 | ||
98 | ||
99 | === Macros | |
100 | ||
81f5f33d PP |
101 | * **Manual page reference**: Always use the |
102 | `man:__PAGE__(__SECTION__)` macro when you refer to a manual page. | |
f0287ae1 | 103 | + |
81f5f33d | 104 | .Using the `manual` macro. |
f0287ae1 PP |
105 | ==== |
106 | ---- | |
81f5f33d | 107 | See man:lttng-ust(3) to learn more about [...] |
f0287ae1 PP |
108 | ---- |
109 | ==== | |
110 | ||
81f5f33d PP |
111 | * [[opt-macro]] **LTTng command-line option**: Starting from |
112 | LTTng{nbsp}2.8, always use the `opt:__PAGE__(__SECTION__):__OPTION__` | |
113 | macro when you refer to a command-line option described in an LTTng | |
114 | manual page. | |
7adf7ee2 PP |
115 | + |
116 | .Using the `opt` macro. | |
117 | ==== | |
118 | ---- | |
81f5f33d PP |
119 | Use the opt:lttng-enable-event(1):--filter option to set the |
120 | filter expression of a recording event rule. | |
7adf7ee2 PP |
121 | ---- |
122 | ==== | |
123 | ||
81f5f33d | 124 | * **File name**: Always use the `path:{__PATH__}` macro when you need |
7adf7ee2 | 125 | to write a file name. |
f0287ae1 PP |
126 | + |
127 | .Using the `path` macro. | |
128 | ==== | |
129 | ---- | |
130 | Load the configuration file path:{hello.lttng} directory by default. | |
131 | ---- | |
132 | ==== | |
133 | ||
81f5f33d | 134 | * **Directory name**: Always use the `dir:{__PATH__}` macro when you |
7adf7ee2 | 135 | need to write a directory name. |
f0287ae1 PP |
136 | + |
137 | .Using the `dir` macro. | |
138 | ==== | |
139 | ---- | |
140 | Traces are recorded to the dir:{~/lttng-traces} directory by default. | |
141 | ---- | |
142 | ==== | |
143 | ||
81f5f33d PP |
144 | * **Environment variable**: Always use the `env:__VAR__` macro when you |
145 | need to write an environment variable name. `__VAR__` must _not_ | |
146 | contain the `$` shell prefix. | |
f0287ae1 PP |
147 | + |
148 | .Using the `env` macro. | |
149 | ==== | |
150 | ---- | |
81f5f33d PP |
151 | Set the env:LTTNG_UST_DEBUG environment variable to `1` to activate the |
152 | debug mode of LTTng-UST. | |
f0287ae1 PP |
153 | ---- |
154 | ==== | |
155 | ||
81f5f33d PP |
156 | * **Command name**: Always use the `cmd:__COMMAND__` macro when you |
157 | need to write a command name. | |
f0287ae1 PP |
158 | + |
159 | .Using the `cmd` macro. | |
160 | ==== | |
161 | ---- | |
81f5f33d | 162 | Run cmd:lttng-sessiond as the `root` Unix user. |
f0287ae1 PP |
163 | ---- |
164 | ==== | |
165 | ||
166 | ||
81f5f33d | 167 | === Dash |
f0287ae1 | 168 | |
81f5f33d PP |
169 | You can usually write an em dash with `--` in AsciiDoc, but sometimes |
170 | the AsciiDoc processor keeps them as is, for example if the character at | |
171 | the left or at the right of them is a punctuation. In this case, use the | |
172 | equivalent `—` HTML entity twice. | |
f0287ae1 PP |
173 | |
174 | .Using `--` for an em dash. | |
175 | ==== | |
176 | ---- | |
81f5f33d PP |
177 | And yet, when the car was finally delivered--nearly three months after |
178 | it was ordered--she decided she no longer wanted it, leaving the dealer | |
179 | with an oddly equipped car that would be difficult to sell. | |
f0287ae1 PP |
180 | ---- |
181 | ==== | |
182 | ||
183 | .Using `—` for an em dash. | |
184 | ==== | |
185 | ---- | |
186 | As the frequency of recorded events increases--either because the event | |
81f5f33d PP |
187 | throughput is actually higher or because you enabled more recording |
188 | event rules than usual—__event record loss__ might be experienced. | |
f0287ae1 PP |
189 | ---- |
190 | ==== | |
191 | ||
192 | ||
81f5f33d | 193 | === Non-breaking space |
f0287ae1 PP |
194 | |
195 | Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) | |
196 | between a quantity and its unit, or when it would be unnatural to have | |
197 | two related words split on two lines. | |
198 | ||
199 | .Using a non-breaking space between a quantity and its unit. | |
200 | ==== | |
201 | ---- | |
81f5f33d | 202 | The size of this C{nbsp}source file is 1039{nbsp}bytes. |
f0287ae1 PP |
203 | ---- |
204 | ==== | |
205 | ||
206 | .Using a non-breaking space to avoid an odd line break. | |
207 | ==== | |
208 | ---- | |
209 | This integer is displayed in base{nbsp}16. | |
210 | ---- | |
211 | ==== | |
212 | ||
213 | ||
81f5f33d | 214 | === Placeholder in inline code |
f0287ae1 PP |
215 | |
216 | When a section of an inline code element is a placeholder, or variable, | |
81f5f33d PP |
217 | use the ``+`` form of the element (instead of +`+), and place `__` |
218 | around the (preferably uppercase) placeholder. | |
f0287ae1 PP |
219 | |
220 | .Using a placeholder in an inline code element. | |
221 | ==== | |
222 | ---- | |
81f5f33d PP |
223 | Name your file +something.__SYS__.c+, where +__SYS__+ is the name of |
224 | your system. | |
f0287ae1 PP |
225 | ---- |
226 | ==== | |
227 | ||
228 | ||
81f5f33d | 229 | === Listing block |
f0287ae1 PP |
230 | |
231 | There are two types of listing blocks: | |
232 | ||
81f5f33d PP |
233 | * [[term-box]]A **terminal box** shows commands to be entered in a |
234 | terminal exclusively. In other words, you must _not_ write the output | |
235 | of commands in a terminal box. | |
236 | + | |
237 | A terminal box is an AsciiDoc literal block with the `term` role. | |
f0287ae1 | 238 | + |
81f5f33d PP |
239 | Start a command line with "```${nbsp}```" to indicate that a regular |
240 | Unix user should run it. Start a command line with "```#{nbsp}```" to | |
241 | indicate that the `root` Unix user should run it. | |
ded02698 | 242 | + |
f0287ae1 PP |
243 | .Using a terminal box. |
244 | ==== | |
245 | [listing] | |
246 | .... | |
247 | [role="term"] | |
248 | ---- | |
ded02698 PP |
249 | $ lttng create my-session |
250 | $ lttng enable-event --kernel --all | |
f0287ae1 PP |
251 | ---- |
252 | .... | |
253 | ==== | |
254 | + | |
81f5f33d PP |
255 | Write the output of a command line with a simple, role-less listing |
256 | block. | |
f0287ae1 | 257 | |
81f5f33d PP |
258 | * A **source code box** shows syntax-highlighted snippets of |
259 | source code. | |
260 | + | |
261 | A source code box is an AsciiDoc source code block. | |
f0287ae1 PP |
262 | + |
263 | .Using a source code box. | |
264 | ==== | |
265 | [listing] | |
266 | .... | |
267 | [source,c] | |
268 | ---- | |
269 | #include <stdio.h> | |
270 | ||
271 | int main(void) | |
272 | { | |
273 | puts("Hello, World!"); | |
f0287ae1 PP |
274 | return 0; |
275 | } | |
276 | ---- | |
277 | .... | |
278 | ==== | |
279 | + | |
280 | The second attribute is the name of the programming language for | |
281 | proper syntax highlighting (for example, `c`, `python`, `make`, `java`). | |
282 | This name must be known to http://pygments.org/[Pygments]. | |
283 | + | |
284 | Always indent source code examples with 4{nbsp}spaces. | |
285 | ||
286 | In any listing block, the lines must not exceed 80 characters (prefer a | |
81f5f33d | 287 | maximum of 72{nbsp}characters). |
f0287ae1 PP |
288 | |
289 | ||
81f5f33d | 290 | === Command-line option |
f0287ae1 | 291 | |
81f5f33d | 292 | When you specify a command-line option: |
f0287ae1 PP |
293 | |
294 | * Always use the long form of the option (with two hyphens). | |
81f5f33d | 295 | |
7adf7ee2 | 296 | * **If the command which accepts this option is an LTTng program**, |
81f5f33d PP |
297 | use the <<opt-macro,`opt` macro>>. Otherwise, use simple backticks. |
298 | ||
299 | * Always follow the option name with the _option_ word. | |
f0287ae1 PP |
300 | |
301 | .Using a command-line option. | |
302 | ==== | |
303 | ---- | |
81f5f33d PP |
304 | You can use the opt:lttng(1):--group option of the cmd:lttng tool to |
305 | specify your custom tracing group. | |
f0287ae1 PP |
306 | ---- |
307 | ==== | |
308 | ||
81f5f33d | 309 | In a <<term-box,terminal box>>, always put `=` between the option name |
f0287ae1 PP |
310 | and its argument, if any. |
311 | ||
312 | .Terminal box. | |
313 | ==== | |
314 | In this example, `provider:'sys_*'` is not the argument of the | |
81f5f33d PP |
315 | `--userspace` option: it's the first non-option argument, and the |
316 | `--userspace` option has no arguments. | |
f0287ae1 PP |
317 | |
318 | [listing] | |
319 | .... | |
320 | [role="term"] | |
321 | ---- | |
65344bcd | 322 | $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \ |
81f5f33d | 323 | --exclude=sys_send,sys_block --loglevel=INFO |
f0287ae1 PP |
324 | ---- |
325 | .... | |
326 | ==== | |
327 | ||
328 | ||
81f5f33d | 329 | === Procedure |
f0287ae1 PP |
330 | |
331 | Use an ordered list to write a procedure. | |
332 | ||
81f5f33d PP |
333 | If a step is optional, prepend `+**Optional**:+` followed with a space |
334 | to the first sentence of the step. | |
335 | ||
336 | Start the first sentence with a capital letter. | |
337 | ||
338 | Don't use an optional step followed with a condition; use a conditional | |
339 | step for this. | |
f0287ae1 PP |
340 | |
341 | If a step is conditional, put the condition (_If something_) in bold, | |
81f5f33d | 342 | followed with a comma, followed with the step itself. |
f0287ae1 PP |
343 | |
344 | ||
81f5f33d | 345 | === External link |
f0287ae1 | 346 | |
81f5f33d PP |
347 | When using a hyperlink to a file/directory of an LTTng repository, link |
348 | to the GitHub code browser. Make sure to link to the appropriate Git | |
349 | branch (usually `stable-2.__x__`). You can use the `revision` AsciiDoc | |
f0287ae1 PP |
350 | attribute in the URL. |
351 | ||
352 | .Link to source file. | |
353 | ==== | |
354 | ---- | |
355 | See the file | |
356 | https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}] | |
357 | for more details about [...] | |
358 | ---- | |
359 | ==== | |
360 | ||
361 | ||
81f5f33d | 362 | === "`Since`" sections |
f0287ae1 PP |
363 | |
364 | If a whole section describes a feature which was introduced in LTTng 2.1 | |
81f5f33d PP |
365 | or later, assign the `since-2.__x__` role to the section, where `__x__` |
366 | is the minor version of the LTTng release which introduced the feature. | |
f0287ae1 PP |
367 | |
368 | .Section heading describing a feature introduced in LTTng 2.5. | |
369 | ==== | |
370 | ---- | |
371 | [role="since-2.5"] | |
372 | [[tracef]] | |
81f5f33d | 373 | ==== Use `lttng_ust_tracef()` |
f0287ae1 PP |
374 | ---- |
375 | ==== |