Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | Contributor's guide |
2 | =================== | |
3 | ||
4 | This guide presents the structure and conventions of the LTTng | |
5 | Documentation's source. Make sure you read it thoroughly before | |
6 | contributing a change. | |
7 | ||
8 | ||
e70fc4f4 | 9 | Branches |
89415a66 PP |
10 | -------- |
11 | ||
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 | |
15 | LTTng release. | |
16 | ||
17 | ||
e70fc4f4 | 18 | Structure of sources |
89415a66 | 19 | -------------------- |
5e0cbfb0 PP |
20 | |
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. | |
24 | ||
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. | |
31 | ||
32 | Each Markdown file begins with a YAML front matter which only contains | |
33 | the unique ID of this chapter/section: | |
34 | ||
35 | ```yaml | |
36 | --- | |
37 | id: unique-id-goes-here | |
38 | --- | |
39 | ||
40 | First paragraph goes here. | |
41 | ``` | |
42 | ||
43 | Editable image sources are placed in `images/src` and their rendered | |
44 | equivalents are located in `images/export`. | |
45 | ||
60757f4b PP |
46 | `tools/docs2json.py` is a Python 3 script which may be used to get |
47 | the graph of internal and external links and to find | |
48 | typical errors in the whole documentation, like dead internal links. | |
49 | It needs the | |
50 | [`termcolor`](https://pypi.python.org/pypi/termcolor) Python 3 package. | |
51 | Run it from the repository's root and ignore its standard output | |
52 | to view the warnings and errors: | |
53 | ||
54 | tools/docs2json.py > /dev/null | |
5e0cbfb0 PP |
55 | |
56 | ||
e70fc4f4 | 57 | Format of sources |
5e0cbfb0 PP |
58 | ----------------- |
59 | ||
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 | |
65 | paragraph! | |
66 | ||
67 | ||
68 | ### HTML specifics | |
69 | ||
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. | |
73 | ||
74 | ||
e70fc4f4 | 75 | #### Tip/note/warning/error blocks |
5e0cbfb0 PP |
76 | |
77 | Tip/note block: | |
78 | ||
79 | ```html | |
80 | <div class="tip"> | |
81 | <p> | |
82 | <span class="t">Title goes here followed by colon:</span>Text goes | |
83 | here; plain HTML. | |
84 | </p> | |
85 | <p> | |
86 | Multiple paragraphs is allowed. | |
87 | </p> | |
88 | </div> | |
89 | ``` | |
90 | ||
1c13c8bd PP |
91 | Replace the `tip` class with `warn` for a warning block, and with `err` |
92 | for an error message block (when JavaScript is needed but is disabled, etc.). | |
5e0cbfb0 | 93 | |
1c13c8bd PP |
94 | Title should be `Tip:` for a tip, `Note:` for a note, `Warning:` for a |
95 | warning, and `Error:` for an error. | |
5e0cbfb0 | 96 | |
e70fc4f4 PP |
97 | |
98 | #### External links | |
5e0cbfb0 PP |
99 | |
100 | Internal links should always use Markdown | |
101 | (`[caption](#doc-section)`). External links, however, need a special | |
102 | style and must use the `<a>` tag with the `ext` CSS class: | |
103 | ||
104 | ```html | |
105 | The LTTng Documentation is | |
106 | <a href="https://github.com/lttng/lttng-docs" class="ext">public</a>. | |
107 | ``` | |
108 | ||
cc3ab47f PP |
109 | Sometimes, however, it is necessary to write internal links in plain |
110 | HTML, for example in tip blocks, since Markdown code is not processed. | |
111 | In these cases, add the `int` CSS class as a hint to prevent the static | |
112 | analyzer from complaining (`tools/checkdocs.py`). | |
113 | ||
5e0cbfb0 | 114 | |
e70fc4f4 | 115 | #### Abbreviations |
5e0cbfb0 PP |
116 | |
117 | Use `<abbr>` for describing abbreviations. This should only be used | |
118 | for the first use of the abbreviation: | |
119 | ||
120 | ```html | |
121 | The <abbr title="Linux Trace Toolkit: next generation">LTTng</abbr> | |
122 | project is an open source system software package [...] | |
123 | ``` | |
124 | ||
125 | ||
e70fc4f4 | 126 | #### Non-breaking spaces |
5e0cbfb0 PP |
127 | |
128 | Sometimes, a non-breaking space HTML entity (` `) needs to be | |
129 | explicitly written. | |
130 | ||
131 | Examples: | |
132 | ||
133 | ```html | |
134 | The size of this file is 1039 bytes. | |
135 | ||
136 | This integer is displayed in base 16. | |
137 | ||
138 | A check is performed every 3000 ms. | |
139 | ``` | |
140 | ||
141 | ||
e70fc4f4 | 142 | #### Placeholders in inline code |
5e0cbfb0 PP |
143 | |
144 | You must use `<em>` to emphasize a placeholder within a `<code>` tag | |
145 | because Markdown backticks (<code>`</code>) always render their | |
146 | content literally: | |
147 | ||
148 | ```html | |
149 | Name your file <code>something_<em>sys</em>.c</code>, where | |
150 | <code><em>sys</em></code> is your system name. | |
151 | ``` | |
152 | ||
153 | ||
e70fc4f4 | 154 | #### Terminal boxes |
5e0cbfb0 PP |
155 | |
156 | A terminal box, where command lines are shown, is a simple `<pre>` | |
157 | with the `term` class: | |
158 | ||
159 | ```html | |
160 | <pre class="term"> | |
161 | echo This is a terminal box | |
162 | </pre> | |
163 | ``` | |
164 | ||
165 | Do not prefix command lines with prompts (`$`/`#`) since this makes | |
166 | copy/paste operations painful. | |
167 | ||
168 | You may use `<strong>` tags to emphasize a part of the command line: | |
169 | ||
170 | ```html | |
171 | <pre class="term"> | |
172 | echo This is a <strong>terminal</strong> box | |
173 | </pre> | |
174 | ``` | |
175 | ||
176 | Results of commands, if needed, should be presented in a simple | |
177 | `text` kramdown code block: | |
178 | ||
179 | <pre> | |
180 | ~~~ text | |
181 | [15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
182 | [15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" } | |
183 | [15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
184 | ~~~ | |
185 | </pre> | |
186 | ||
187 | ||
e70fc4f4 | 188 | #### Images |
5e0cbfb0 PP |
189 | |
190 | Use | |
191 | ||
192 | ```html | |
18729dbb | 193 | <figure class="img img-70"> |
4280f592 | 194 | <img src="/images/docs26/image-name.png" alt="Short description"> |
18729dbb | 195 | </figure> |
5e0cbfb0 PP |
196 | ``` |
197 | ||
18729dbb PP |
198 | Replace `docs26` with the appropriate version tag depending on the |
199 | checked out branch. | |
200 | ||
5e0cbfb0 PP |
201 | to display an image. Change `img-70` to `img-` followed by the |
202 | width percentage you wish. | |
203 | ||
5e0cbfb0 | 204 | |
e70fc4f4 | 205 | Convention |
5e0cbfb0 PP |
206 | ---------- |
207 | ||
208 | A few rules to comply with in order to keep the text as | |
209 | consistent as possible: | |
210 | ||
211 | * Use _user space_, not _userspace_ nor _user-space_. | |
212 | (neither _user land_). | |
213 | * Use _file system_, not _filesystem_. | |
214 | * Use _use case_, not _use-case_ nor _usecase_. | |
215 | * Use _the C standard library_, not _libc_. | |
216 | * Use _log level_, not _loglevel_. | |
217 | * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and | |
218 | _LTTng-tools_, not _modules_, _UST_ and _tools_. | |
219 | * All code snippets should use 4 spaces for indentation (even C) | |
220 | so that they are not too large. | |
221 | * Prefer emphasis (Markdown: `_something_`, HTML: `<em>something</em>`) | |
222 | to strong (Markdown: `**something**`, HTML: `<strong>something</strong>`) | |
223 | for emphasizing text. | |
224 | * Try to stay behind the 72th column mark if possible, and behind | |
225 | the 80th column otherwise. | |
226 | * Do not end directory paths with a forward slash | |
227 | (good: `include/trace/events`, bad: `include/trace/events/`). | |
228 | * Keep the text as impersonal as possible (minimize the use of | |
229 | _I_, _we_, _us_, etc.), except for user guides/tutorials where | |
89325d86 PP |
230 | _we_ have an ongoing example with _you_. |
231 | * Minimize the use of the future tense (_will_). | |
c4e2d038 | 232 | * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._). |
7d603874 PP |
233 | |
234 | ||
e70fc4f4 | 235 | Committing |
7d603874 PP |
236 | ---------- |
237 | ||
238 | If you make a change to a single contents file, prefix your Git commit | |
239 | message's first line with the file ID followed by `: `, e.g: | |
240 | ||
241 | archlinux: minor fix |