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 | ||
89415a66 PP |
9 | branches |
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 | ||
18 | structure of sources | |
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 | ||
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: | |
51 | ||
52 | tools/checkdocs.py | |
53 | ||
54 | and it will potentially output a list of errors and warnings. | |
55 | ||
56 | ||
57 | format of sources | |
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 | ||
75 | #### tip/note block | |
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 | ||
91 | Title should be `Tip:` for a tip and `Note:` for a note. | |
92 | ||
93 | ||
94 | #### external links | |
95 | ||
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: | |
99 | ||
100 | ```html | |
101 | The LTTng Documentation is | |
102 | <a href="https://github.com/lttng/lttng-docs" class="ext">public</a>. | |
103 | ``` | |
104 | ||
cc3ab47f PP |
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`). | |
109 | ||
5e0cbfb0 PP |
110 | |
111 | #### abbreviations | |
112 | ||
113 | Use `<abbr>` for describing abbreviations. This should only be used | |
114 | for the first use of the abbreviation: | |
115 | ||
116 | ```html | |
117 | The <abbr title="Linux Trace Toolkit: next generation">LTTng</abbr> | |
118 | project is an open source system software package [...] | |
119 | ``` | |
120 | ||
121 | ||
122 | #### non-breaking spaces | |
123 | ||
124 | Sometimes, a non-breaking space HTML entity (` `) needs to be | |
125 | explicitly written. | |
126 | ||
127 | Examples: | |
128 | ||
129 | ```html | |
130 | The size of this file is 1039 bytes. | |
131 | ||
132 | This integer is displayed in base 16. | |
133 | ||
134 | A check is performed every 3000 ms. | |
135 | ``` | |
136 | ||
137 | ||
138 | #### placeholders in inline code | |
139 | ||
140 | You must use `<em>` to emphasize a placeholder within a `<code>` tag | |
141 | because Markdown backticks (<code>`</code>) always render their | |
142 | content literally: | |
143 | ||
144 | ```html | |
145 | Name your file <code>something_<em>sys</em>.c</code>, where | |
146 | <code><em>sys</em></code> is your system name. | |
147 | ``` | |
148 | ||
149 | ||
150 | #### terminal boxes | |
151 | ||
152 | A terminal box, where command lines are shown, is a simple `<pre>` | |
153 | with the `term` class: | |
154 | ||
155 | ```html | |
156 | <pre class="term"> | |
157 | echo This is a terminal box | |
158 | </pre> | |
159 | ``` | |
160 | ||
161 | Do not prefix command lines with prompts (`$`/`#`) since this makes | |
162 | copy/paste operations painful. | |
163 | ||
164 | You may use `<strong>` tags to emphasize a part of the command line: | |
165 | ||
166 | ```html | |
167 | <pre class="term"> | |
168 | echo This is a <strong>terminal</strong> box | |
169 | </pre> | |
170 | ``` | |
171 | ||
172 | Results of commands, if needed, should be presented in a simple | |
173 | `text` kramdown code block: | |
174 | ||
175 | <pre> | |
176 | ~~~ text | |
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" } | |
180 | ~~~ | |
181 | </pre> | |
182 | ||
183 | ||
184 | #### images | |
185 | ||
186 | Use | |
187 | ||
188 | ```html | |
189 | <div class="img img-70"> | |
4280f592 | 190 | <img src="/images/docs26/image-name.png" alt="Short description"> |
5e0cbfb0 PP |
191 | </div> |
192 | ``` | |
193 | ||
194 | to display an image. Change `img-70` to `img-` followed by the | |
195 | width percentage you wish. | |
196 | ||
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 | |
199 | basic browsers: | |
200 | ||
201 | ```html | |
202 | <div class="img img-90"> | |
4280f592 PP |
203 | <object data="/images/docs26/image-name.svg" type="image/svg+xml"> |
204 | <img src="/images/docs26/image-name.png" alt="Short description"> | |
5e0cbfb0 PP |
205 | </object> |
206 | </div> | |
207 | ``` | |
208 | ||
209 | An interactive SVG object allows its text to be selected, amongst other | |
210 | features. | |
211 | ||
212 | ||
213 | convention | |
214 | ---------- | |
215 | ||
216 | A few rules to comply with in order to keep the text as | |
217 | consistent as possible: | |
218 | ||
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. | |
7d603874 PP |
239 | |
240 | ||
241 | committing | |
242 | ---------- | |
243 | ||
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: | |
246 | ||
247 | archlinux: minor fix |