Commit | Line | Data |
---|---|---|
f0287ae1 PP |
1 | The LTTng Documentation: Contributor's guide |
2 | ============================================ | |
3 | Philippe Proulx | |
7adf7ee2 | 4 | v1.0, 26 October 2016 |
f0287ae1 PP |
5 | |
6 | This guide presents the structure and conventions of the LTTng | |
7 | Documentation's source. Make sure you read it thoroughly before | |
8 | you contribute a change. | |
9 | ||
10 | ||
11 | [[principles]] | |
12 | == Principles | |
13 | ||
14 | The LTTng Documentation exists to make the | |
15 | https://lttng.org/[LTTng project] useable. | |
16 | Without such a complete documentation consolidating the various | |
17 | concepts, features, and procedures of LTTng-tools, LTTng-UST, and | |
18 | LTTng-modules, most of the project would only be useable by | |
19 | its authors. | |
20 | ||
21 | Why not simply read the man pages? While the LTTng man pages are | |
22 | complementary to the LTTng Documentation, they remain formal | |
23 | references: they lack the introductory quality and procedural user | |
24 | guides found in this documentation. | |
25 | ||
26 | The core principle of the LTTng Documentation is to make the text as | |
27 | cleverly organized, easy to follow, precise, and consistent as possible. | |
28 | This involves keeping a high level of rigor as to such things as the | |
29 | document's style, voice, grammar, and layout. | |
30 | ||
31 | Of course, those guidelines are not new to the technical writing realm, | |
32 | and it would be bold to devise a brand new manual of style for the sole | |
33 | existence of the LTTng Documentation when so many have already proven | |
34 | their value. This is why the LTTng Documentation (especially starting | |
35 | from version 2.7) does its best to follow the rules of the | |
36 | https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual | |
37 | of Style (4th edition)], a landmark work in its field. Of particular | |
38 | interest in this book are: | |
39 | ||
40 | * Chapter 1, _Microsoft style and voice_. | |
41 | * Chapter 6, _Procedures and technical content_. | |
42 | * Chapter 7, _Practical issues of style_. | |
43 | * Chapter 8, _Grammar_. | |
44 | * Chapter 9, _Punctuation_. | |
45 | * Chapter 11, _Acronyms and other abbreviations_. | |
46 | ||
47 | The <<terminology,Terminology>> section of this contributor's guide | |
48 | adds terms to or overrides terms of Part 2, _Usage Dictionary_. | |
49 | ||
50 | ||
51 | == Organization of the repository and format | |
52 | ||
53 | The Git repository of the LTTng Documentation contains all the official | |
54 | versions of the documentation as separate source files. Each source file | |
55 | is in its own +2.__x__+ directory, along with documentation resources | |
56 | specific to this version of LTTng. You can find common source files in | |
57 | the `common` directory. | |
58 | ||
59 | The source files are written in | |
60 | http://www.methods.co.nz/asciidoc/[AsciiDoc], a rich, lightweight markup | |
61 | language with all the blocks and inline elements needed to write | |
62 | backend-agnostic content. | |
63 | ||
64 | Although the official LTTng website uses a custom script to generate | |
65 | its own HTML version of the LTTng Documentation, it is possible to | |
66 | generate an autonomous HTML preview (see | |
67 | link:README.adoc[`README.adoc`]). The `asciidoc.html5.conf` AsciiDoc | |
68 | configuration file sets a few attributes and implements the required | |
69 | macros for this preview target. | |
70 | ||
71 | ||
72 | == Validation script | |
73 | ||
74 | Before you submit any change, make sure that the check script passes. | |
75 | This is a Python script which validates some elements of a specific | |
76 | document. | |
77 | ||
78 | You need the following dependencies to run the check script: | |
79 | ||
80 | * http://www.methods.co.nz/asciidoc/[AsciiDoc] | |
81 | * Python 3 | |
82 | * http://lxml.de/[lxml] Python 3 package | |
83 | * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package | |
84 | ||
85 | Run the check script: | |
86 | ||
87 | ---- | |
88 | python3 tools/check.py 2.7/lttng-docs-2.7.txt | |
89 | ---- | |
90 | ||
91 | Replace `2.7` by the version of the document to validate in the previous | |
92 | command line. | |
93 | ||
94 | ||
95 | == Style considerations | |
96 | ||
97 | As stated in <<principles,Principles>>, the LTTng Documentation follows | |
98 | the Microsoft Manual of Style (4th edition). We encourage you to read | |
99 | this work before contributing a major change to the document. | |
100 | ||
101 | You also need to consider the following rules, often specific to the | |
102 | AsciiDoc format used to write the LTTng Documentation, when you edit | |
103 | existing content or when you create new sections. | |
104 | ||
105 | ||
106 | === Macros | |
107 | ||
108 | * **Man page references**: Always use the +man:__command__(__section__)+ | |
7adf7ee2 | 109 | macro when you refer to a man page. |
f0287ae1 PP |
110 | + |
111 | .Using the `man` macro. | |
112 | ==== | |
113 | ---- | |
114 | See man:lttng-ust(3) for more details about ... | |
115 | ---- | |
116 | ==== | |
117 | ||
7adf7ee2 PP |
118 | * [[opt-macro]] **LTTng command-line options**: Starting from v2.8, |
119 | always use the +opt:__command__(__section__):__option__+ macro when | |
120 | you refer to a command-line option described in an LTTng man page. | |
121 | + | |
122 | .Using the `opt` macro. | |
123 | ==== | |
124 | ---- | |
125 | You can use the opt:lttng-enable-event(1):--filter option to set the | |
126 | filter expression of an event rule. | |
127 | ---- | |
128 | ==== | |
129 | ||
130 | * **File names**: Always use the +path:{__path__}+ macro when you need | |
131 | to write a file name. | |
f0287ae1 PP |
132 | + |
133 | .Using the `path` macro. | |
134 | ==== | |
135 | ---- | |
136 | Load the configuration file path:{hello.lttng} directory by default. | |
137 | ---- | |
138 | ==== | |
139 | ||
7adf7ee2 PP |
140 | * **Directory names**: Always use the +dir:{__path__}+ macro when you |
141 | need to write a directory name. | |
f0287ae1 PP |
142 | + |
143 | .Using the `dir` macro. | |
144 | ==== | |
145 | ---- | |
146 | Traces are recorded to the dir:{~/lttng-traces} directory by default. | |
147 | ---- | |
148 | ==== | |
149 | ||
7adf7ee2 PP |
150 | * **Environment variable**: Always use the +env:__VAR__+ macro when you |
151 | need to write an environment variable name. +__VAR__+ must not contain | |
152 | the shell's `$` prefix. | |
f0287ae1 PP |
153 | + |
154 | .Using the `env` macro. | |
155 | ==== | |
156 | ---- | |
157 | You can set the env:LTTNG_UST_DEBUG environment variable to `1` to | |
158 | activate LTTng-UST's debug output. | |
159 | ---- | |
160 | ==== | |
161 | ||
7adf7ee2 PP |
162 | * **Command names**: Always use the +cmd:__cmd__+ macro when you need to |
163 | write a command name. | |
f0287ae1 PP |
164 | + |
165 | .Using the `cmd` macro. | |
166 | ==== | |
167 | ---- | |
168 | Run cmd:lttng-sessiond as the root user. | |
169 | ---- | |
170 | ==== | |
171 | ||
172 | ||
173 | === Dashes | |
174 | ||
175 | Em dashes can usually be written using `--` in AsciiDoc, but sometimes | |
176 | the two hyphens are outputted as is, for example if the character at the | |
177 | left or at the right of them is a punctuation. You can avoid this | |
178 | by using the equivalent `—` HTML entity. | |
179 | ||
180 | .Using `--` for an em dash. | |
181 | ==== | |
182 | ---- | |
183 | And yet, when the car was finally delivered--nearly three months after it | |
184 | was ordered--she decided she no longer wanted it, leaving the dealer with | |
185 | an oddly equipped car that would be difficult to sell. | |
186 | ---- | |
187 | ==== | |
188 | ||
189 | .Using `—` for an em dash. | |
190 | ==== | |
191 | ---- | |
192 | As the frequency of recorded events increases--either because the event | |
193 | throughput is actually higher or because you enabled more events than | |
194 | usual—__event loss__ might be experienced. | |
195 | ---- | |
196 | ==== | |
197 | ||
198 | ||
199 | === Non-breaking spaces | |
200 | ||
201 | Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) | |
202 | between a quantity and its unit, or when it would be unnatural to have | |
203 | two related words split on two lines. | |
204 | ||
205 | .Using a non-breaking space between a quantity and its unit. | |
206 | ==== | |
207 | ---- | |
208 | The size of this file is 1039{nbsp}bytes. | |
209 | ---- | |
210 | ==== | |
211 | ||
212 | .Using a non-breaking space to avoid an odd line break. | |
213 | ==== | |
214 | ---- | |
215 | This integer is displayed in base{nbsp}16. | |
216 | ---- | |
217 | ==== | |
218 | ||
219 | ||
220 | === Placeholders in inline code | |
221 | ||
222 | When a section of an inline code element is a placeholder, or variable, | |
223 | use the `+` form of the element (instead of +`+), and place `__` | |
224 | around the placeholder. | |
225 | ||
226 | .Using a placeholder in an inline code element. | |
227 | ==== | |
228 | ---- | |
229 | Name your file +something.__sys__.c+, where +__sys__+ is your system name. | |
230 | ---- | |
231 | ==== | |
232 | ||
233 | ||
234 | === Listing blocks | |
235 | ||
236 | There are two types of listing blocks: | |
237 | ||
238 | * [[term-box]]**Terminal boxes** are used to show commands to be entered in a | |
239 | terminal exclusively, that is, the output of commands must not be | |
240 | written in terminal boxes. A terminal box is an AsciiDoc literal | |
241 | block with the `term` role. | |
242 | + | |
ded02698 PP |
243 | Start a command line with "+${nbsp}+" to indicate that a regular Unix user |
244 | should run it. Start a command line with "+#{nbsp}+" to indicate that a | |
245 | priviledged Unix user should run it. | |
246 | + | |
f0287ae1 PP |
247 | .Using a terminal box. |
248 | ==== | |
249 | [listing] | |
250 | .... | |
251 | [role="term"] | |
252 | ---- | |
ded02698 PP |
253 | $ lttng create my-session |
254 | $ lttng enable-event --kernel --all | |
f0287ae1 PP |
255 | ---- |
256 | .... | |
257 | ==== | |
258 | + | |
259 | The output of a command line can be written using a simple, role-less | |
260 | listing block. | |
261 | ||
262 | * **Source code boxes** are used to show syntax-highlighted snippets of | |
263 | source code. A source code box is an AsciiDoc source code block. | |
264 | + | |
265 | .Using a source code box. | |
266 | ==== | |
267 | [listing] | |
268 | .... | |
269 | [source,c] | |
270 | ---- | |
271 | #include <stdio.h> | |
272 | ||
273 | int main(void) | |
274 | { | |
275 | puts("Hello, World!"); | |
276 | ||
277 | return 0; | |
278 | } | |
279 | ---- | |
280 | .... | |
281 | ==== | |
282 | + | |
283 | The second attribute is the name of the programming language for | |
284 | proper syntax highlighting (for example, `c`, `python`, `make`, `java`). | |
285 | This name must be known to http://pygments.org/[Pygments]. | |
286 | + | |
287 | Always indent source code examples with 4{nbsp}spaces. | |
288 | ||
289 | In any listing block, the lines must not exceed 80 characters (prefer a | |
290 | maximum of 72 characters). | |
291 | ||
292 | ||
293 | === Command-line options | |
294 | ||
295 | When specifying command-line options: | |
296 | ||
297 | * Always use the long form of the option (with two hyphens). | |
7adf7ee2 PP |
298 | * **If the command which accepts this option is an LTTng program**, |
299 | use the <<opt-macro,`opt` macro>>. Otherwise use simple backticks. | |
f0287ae1 PP |
300 | * Always follow the option name by the _option_ word. |
301 | ||
302 | .Using a command-line option. | |
303 | ==== | |
304 | ---- | |
7adf7ee2 PP |
305 | You can use the `lttng` tool's opt:lttng(1):--group option to specify a |
306 | custom tracing group. | |
f0287ae1 PP |
307 | ---- |
308 | ==== | |
309 | ||
310 | In <<term-box,terminal boxes>>, always put `=` between the option name | |
311 | and its argument, if any. | |
312 | ||
313 | .Terminal box. | |
314 | ==== | |
315 | In this example, `provider:'sys_*'` is not the argument of the | |
316 | `--userspace` option: it's the first positional argument, and | |
317 | the `--userspace` option has no arguments. | |
318 | ||
319 | [listing] | |
320 | .... | |
321 | [role="term"] | |
322 | ---- | |
323 | lttng enable-event --userspace provider:'sys_*' --filter='field < 23' | |
324 | --exclude=sys_send,sys_block --loglevel=TRACE_INFO | |
325 | ---- | |
326 | .... | |
327 | ==== | |
328 | ||
329 | ||
330 | === Procedures | |
331 | ||
332 | Use an ordered list to write a procedure. | |
333 | ||
334 | If a step is optional, prepend `**Optional**:` followed by a space to | |
335 | the step's first sentence. Start the first sentence with a capital | |
336 | letter. Do not use an optional step followed by a condition; use a | |
337 | conditional step for this. | |
338 | ||
339 | If a step is conditional, put the condition (_If something_) in bold, | |
340 | followed by a comma, followed by the step itself. | |
341 | ||
342 | ||
343 | === External links | |
344 | ||
345 | When using a hyperlink to an LTTng repository's file or directory, | |
346 | link to the GitHub code browser. Make sure to link to the appropriate | |
347 | Git branch (usually +stable-2.__x__+). You can use the `revision` | |
348 | attribute in the URL. | |
349 | ||
350 | .Link to source file. | |
351 | ==== | |
352 | ---- | |
353 | See the file | |
354 | https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}] | |
355 | for more details about [...] | |
356 | ---- | |
357 | ==== | |
358 | ||
359 | ||
360 | === "Since" sections | |
361 | ||
362 | If a whole section describes a feature which was introduced in LTTng 2.1 | |
363 | or later, add the +since-2.__x__+ role to the section's heading, where | |
364 | +__x__+ is the minor version of the LTTng release which introduced | |
365 | the feature. | |
366 | ||
367 | .Section heading describing a feature introduced in LTTng 2.5. | |
368 | ==== | |
369 | ---- | |
370 | [role="since-2.5"] | |
371 | [[tracef]] | |
372 | ==== Use `tracef()` | |
373 | ---- | |
374 | ==== | |
375 | ||
376 | ||
377 | [[terminology]] | |
378 | == Terminology | |
379 | ||
380 | What follows is an official, partial list of technical terms used by the | |
381 | LTTng Documentation. Other forms of those terms are _not_ permitted. For | |
382 | example, do not write `use-case` or `filesystem`. | |
383 | ||
384 | Autotools:: | |
385 | The GNU Autotools. | |
386 | + | |
387 | Do not use _autotools_. | |
388 | ||
389 | Babeltrace:: | |
390 | The Babeltrace project, which includes the `babeltrace` command, some | |
391 | libraries, and Python bindings. | |
392 | + | |
393 | Use +`babeltrace`+ to refer to the actual `babeltrace` command. | |
394 | ||
395 | Babeltrace Python bindings:: | |
396 | The Python bindings of Babeltrace. | |
397 | + | |
398 | The plural _bindings_ is important. | |
399 | ||
400 | Bash:: | |
401 | The Bash shell. | |
402 | + | |
403 | Do not use _bash_. | |
404 | ||
405 | buffering scheme:: | |
406 | A layout of tracing buffers applied to a given channel. | |
407 | ||
408 | channel:: | |
409 | An LTTng channel. | |
410 | ||
411 | CLI:: | |
412 | Prefer expanding this acronym to _command-line interface_ in the text. | |
413 | ||
414 | clock:: | |
415 | A reference of time for a tracer. | |
416 | + | |
417 | Use _system time_ to refer to the date and time as seen by a user. | |
418 | ||
419 | command-line:: | |
420 | Adjective version of _command line_: _command-line option_, | |
421 | _command-line interface_. | |
422 | ||
423 | command-line interface:: | |
424 | An interface in which the user enters command lines to instruct the | |
425 | system what to do. | |
426 | + | |
427 | Prefer using _command_ or _command-line tool_ to refer to a | |
428 | specific command. | |
429 | ||
430 | command line:: | |
431 | An actual line of command entered by the user in a terminal, at a | |
432 | command prompt. | |
433 | + | |
434 | Write _command-line_ when used as an adjective. | |
435 | ||
436 | consumer daemon:: | |
437 | The LTTng consumer daemon. | |
438 | + | |
439 | Do not use _consumerd_. | |
440 | + | |
441 | Use +`lttng-consumerd`+ to refer to the consumer daemon | |
442 | executable. | |
443 | ||
444 | domain:: | |
445 | Do not use when referring to a _tracing domain_. | |
446 | ||
447 | event:: | |
448 | Occurrence recognised by software, emitted by a tracer when specific | |
449 | conditions are met, at a given time. An event _occurs_ at a specific | |
450 | time, after which a tracer can record its payload. | |
451 | ||
452 | event loss mode:: | |
453 | The mechanism by which event records of a given channel are lost | |
454 | (not recorded) when there is no sub-buffer space left to store them. | |
455 | ||
456 | event name:: | |
457 | The name of an event, which is also the name of the event record. | |
458 | This is different from a _tracepoint name_, which is only the name | |
459 | of the instrumentation point, not necessarily equal to the event | |
460 | name. | |
461 | ||
462 | event record:: | |
463 | Record, in a trace, of the payload of an event which occured. | |
464 | ||
465 | event rule:: | |
466 | Set of conditions which must be satisfied for one or more events | |
467 | to occur. The `lttng enable-event` command creates and enables | |
468 | _event rules_, not _events_. | |
469 | ||
470 | file system:: | |
471 | Contains directories, files, and links in an organized structure. | |
472 | + | |
473 | Do not use _filesystem_ or _file-system_. | |
474 | ||
475 | +`java.util.logging`+:: | |
476 | Even though the `--jul` command-line option is an acronym for this | |
477 | term, there is no such thing as _Java Util Logging_. The only | |
478 | correct form is the name of the Java package, | |
479 | +`java.util.logging`+. | |
480 | ||
481 | instrumentation:: | |
482 | The use of LTTng probes to make a software traceable. | |
483 | ||
484 | libc:: | |
485 | Do not use. | |
486 | + | |
487 | Use _the C standard library_ to refer to the standard library for | |
488 | the C programming language, or _glibc_ to refer to the GNU C Library | |
489 | specifically. | |
490 | ||
491 | log4j:: | |
492 | LTTng-UST supports Java logging using Apache _log4j_, not Apache | |
493 | Log4j 2. | |
494 | ||
495 | log level:: | |
496 | Level of severity of a log statement. | |
497 | + | |
498 | Do not hyphenate. | |
499 | ||
500 | kernel:: | |
501 | In general, do not use _kernel_ to refer to the _Linux kernel_: use | |
502 | the whole _Linux kernel_ term, because other operating system kernels | |
503 | exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng | |
504 | kernel modules_. | |
505 | ||
506 | Linux Trace Toolkit: next generation:: | |
507 | The expansion of the _LTTng_ acronym. | |
508 | + | |
509 | The colon and the lowercase _n_ and _g_ are important. | |
510 | ||
511 | LTTng-analyses:: | |
512 | The LTTng-analyses project. | |
513 | ||
514 | LTTng-modules:: | |
515 | The LTTng-modules project. | |
516 | ||
517 | LTTng-tools:: | |
518 | The LTTng-tools project. | |
519 | ||
520 | LTTng-UST:: | |
521 | The LTTng-UST project. | |
522 | ||
523 | LTTng-UST Java agent:: | |
524 | LTTng-UST Python agent:: | |
525 | An LTTng user space agent. | |
526 | + | |
527 | Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_. | |
528 | ||
529 | LTTng Documentation:: | |
530 | The name of this project. | |
531 | + | |
532 | Do not use _LTTng documentation_. | |
533 | + | |
534 | When referring to the project, the _the_ determiner can be lowercase: | |
535 | _Welcome to the LTTng Documentation!_. | |
536 | ||
537 | LTTng live:: | |
538 | The name of a communication protocol between Babeltrace and the | |
539 | relay daemon which makes it possible to see events "live", | |
540 | as they are received by the relay daemon. | |
541 | + | |
542 | Do not hyphenate. | |
543 | ||
544 | the +`lttng`+ tool:: | |
545 | the +`lttng`+ command line tool:: | |
546 | The `lttng` command line tool. | |
547 | + | |
548 | When _tool_ has been mentioned in the previous sentences, you can use | |
549 | +`lttng`+ alone. | |
550 | ||
551 | Makefile:: | |
552 | An input for the make tool. | |
553 | + | |
554 | Do not use _makefile_ or _make file_. | |
555 | ||
556 | man page:: | |
557 | Unix-style reference manual page. | |
558 | + | |
559 | Do not hyphenate. | |
560 | ||
561 | per-process buffering:: | |
562 | A buffering scheme in which each process has its own buffer for a | |
563 | given user space channel. | |
564 | + | |
565 | Do not use _per-PID buffering_. | |
566 | ||
567 | per-user buffering:: | |
568 | A buffering scheme in which all the processes of a user share the same | |
569 | buffer for a given user space channel. | |
570 | + | |
571 | Do not use _per-UID buffering_. | |
572 | ||
573 | probe:: | |
574 | An instrumentation point. | |
575 | + | |
576 | Prefer _tracepoint_ when referring to a user space or Linux kernel | |
577 | LTTng tracepoint. | |
578 | ||
579 | real-time clock:: | |
580 | A clock which keeps track of the current time, including eventual | |
581 | time corrections. | |
582 | + | |
583 | Do not use _realtime clock_ or _real time clock_. | |
584 | ||
585 | relay daemon:: | |
586 | The LTTng relay daemon. | |
587 | + | |
588 | Do not use _relayd_. | |
589 | + | |
590 | Use +`lttng-relayd`+ to refer to the relay daemon executable. | |
591 | ||
592 | root user:: | |
593 | A superuser of a Linux system. | |
594 | + | |
595 | Do not use +`root`+. | |
596 | ||
597 | session:: | |
598 | Do not use when referring to a _tracing session_. | |
599 | ||
600 | session daemon:: | |
601 | The LTTng session daemon. | |
602 | + | |
603 | Do not use _sessiond_. | |
604 | + | |
605 | Use +`lttng-sessiond`+ to refer to the session daemon | |
606 | executable. | |
607 | ||
608 | snapshot:: | |
609 | Copy of the current data of all the buffers of a given tracing | |
610 | session, saved as a trace. | |
611 | ||
612 | sub-buffer:: | |
613 | One part of an LTTng ring buffer. | |
614 | + | |
615 | Do not use _subbuffer_ since it's harder to read with the two | |
616 | contiguous b's. | |
617 | ||
618 | timestamp:: | |
619 | Time information attached to an event when it is emitted. This is not | |
620 | necessarily a _Unix timestamp_. | |
621 | + | |
622 | Do not use _time stamp_. | |
623 | ||
624 | trace:: | |
625 | As a verb: a user or a tracer can _trace_ an application. | |
626 | ||
627 | Trace Compass:: | |
628 | The Trace Compass project and application. | |
629 | + | |
630 | Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or | |
631 | _Tracecompass_. | |
632 | ||
633 | tracepoint:: | |
634 | An instrumentation point using the tracepoint mechanism of | |
635 | the Linux kernel or of LTTng-UST. | |
636 | + | |
637 | Do not use _trace point_ or _trace-point_. | |
638 | ||
639 | tracepoint definition:: | |
640 | The definition of a single tracepoint. | |
641 | ||
642 | tracepoint name:: | |
643 | The name of a _tracepoint_. | |
644 | + | |
645 | Not to be confused with an _event name_. | |
646 | ||
647 | tracepoint provider:: | |
648 | A set of functions providing tracepoints to an instrumented user | |
649 | application. | |
650 | + | |
651 | Not to be confused with a _tracepoint provider package_: many tracepoint | |
652 | providers can exist within a tracepoint provider package. | |
653 | ||
654 | tracepoint provider package:: | |
655 | One or more tracepoint providers compiled as an object file or as | |
656 | a shared library. | |
657 | ||
658 | tracing domain:: | |
659 | An LTTng tracing domain. | |
660 | + | |
661 | Always use the complete _tracing domain_ term, not _domain_ alone, | |
662 | unless _tracing domain_ has been used in the few preceding sentences. | |
663 | ||
664 | tracing group:: | |
665 | The Unix group in which a user can be to be allowed to trace the | |
666 | Linux kernel. | |
667 | + | |
668 | Do not use _`tracing` group_, as the name of the tracing | |
669 | group is configurable. | |
670 | ||
671 | tracing session:: | |
672 | An LTTng tracing session. | |
673 | + | |
674 | Always use the complete _tracing session_ term, not _session_ alone. | |
675 | ||
676 | Unix:: | |
677 | Unix operating system or philosophy. | |
678 | + | |
679 | Do not use _UNIX_. | |
680 | ||
681 | Unix epoch:: | |
682 | Absolute reference of a real-time clock. | |
683 | + | |
684 | Use the term as a proper noun: do not precede it with _the_. | |
685 | + | |
686 | Do not use _Epoch_ alone. | |
687 | ||
688 | Unix timestamp:: | |
689 | Timestamp represented as the number of seconds since Unix epoch. | |
690 | ||
691 | use case:: | |
692 | According to Wikipedia: List of actions or event steps, typically | |
693 | defining the interactions between a role and a system, to | |
694 | achieve a goal. | |
695 | + | |
696 | Do not hyphenate. | |
697 | ||
698 | user application:: | |
699 | An application running in user space, as opposed to a Linux kernel | |
700 | module, for example. | |
701 | + | |
702 | Do not use _user space application_, as this is redundant. | |
703 | ||
704 | user space:: | |
705 | User processes. | |
706 | + | |
707 | Do not hyphenate. |