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 | ||
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 | ||
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 | ||
91 | Title should be `Tip:` for a tip and `Note:` for a note. | |
92 | ||
93 | ||
e70fc4f4 PP |
94 | |
95 | #### External links | |
5e0cbfb0 PP |
96 | |
97 | Internal links should always use Markdown | |
98 | (`[caption](#doc-section)`). External links, however, need a special | |
99 | style and must use the `<a>` tag with the `ext` CSS class: | |
100 | ||
101 | ```html | |
102 | The LTTng Documentation is | |
103 | <a href="https://github.com/lttng/lttng-docs" class="ext">public</a>. | |
104 | ``` | |
105 | ||
cc3ab47f PP |
106 | Sometimes, however, it is necessary to write internal links in plain |
107 | HTML, for example in tip blocks, since Markdown code is not processed. | |
108 | In these cases, add the `int` CSS class as a hint to prevent the static | |
109 | analyzer from complaining (`tools/checkdocs.py`). | |
110 | ||
5e0cbfb0 | 111 | |
e70fc4f4 | 112 | #### Abbreviations |
5e0cbfb0 PP |
113 | |
114 | Use `<abbr>` for describing abbreviations. This should only be used | |
115 | for the first use of the abbreviation: | |
116 | ||
117 | ```html | |
118 | The <abbr title="Linux Trace Toolkit: next generation">LTTng</abbr> | |
119 | project is an open source system software package [...] | |
120 | ``` | |
121 | ||
122 | ||
e70fc4f4 | 123 | #### Non-breaking spaces |
5e0cbfb0 PP |
124 | |
125 | Sometimes, a non-breaking space HTML entity (` `) needs to be | |
126 | explicitly written. | |
127 | ||
128 | Examples: | |
129 | ||
130 | ```html | |
131 | The size of this file is 1039 bytes. | |
132 | ||
133 | This integer is displayed in base 16. | |
134 | ||
135 | A check is performed every 3000 ms. | |
136 | ``` | |
137 | ||
138 | ||
e70fc4f4 | 139 | #### Placeholders in inline code |
5e0cbfb0 PP |
140 | |
141 | You must use `<em>` to emphasize a placeholder within a `<code>` tag | |
142 | because Markdown backticks (<code>`</code>) always render their | |
143 | content literally: | |
144 | ||
145 | ```html | |
146 | Name your file <code>something_<em>sys</em>.c</code>, where | |
147 | <code><em>sys</em></code> is your system name. | |
148 | ``` | |
149 | ||
150 | ||
e70fc4f4 | 151 | #### Terminal boxes |
5e0cbfb0 PP |
152 | |
153 | A terminal box, where command lines are shown, is a simple `<pre>` | |
154 | with the `term` class: | |
155 | ||
156 | ```html | |
157 | <pre class="term"> | |
158 | echo This is a terminal box | |
159 | </pre> | |
160 | ``` | |
161 | ||
162 | Do not prefix command lines with prompts (`$`/`#`) since this makes | |
163 | copy/paste operations painful. | |
164 | ||
165 | You may use `<strong>` tags to emphasize a part of the command line: | |
166 | ||
167 | ```html | |
168 | <pre class="term"> | |
169 | echo This is a <strong>terminal</strong> box | |
170 | </pre> | |
171 | ``` | |
172 | ||
173 | Results of commands, if needed, should be presented in a simple | |
174 | `text` kramdown code block: | |
175 | ||
176 | <pre> | |
177 | ~~~ text | |
178 | [15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
179 | [15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" } | |
180 | [15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
181 | ~~~ | |
182 | </pre> | |
183 | ||
184 | ||
e70fc4f4 | 185 | #### Images |
5e0cbfb0 PP |
186 | |
187 | Use | |
188 | ||
189 | ```html | |
190 | <div class="img img-70"> | |
4280f592 | 191 | <img src="/images/docs26/image-name.png" alt="Short description"> |
5e0cbfb0 PP |
192 | </div> |
193 | ``` | |
194 | ||
195 | to display an image. Change `img-70` to `img-` followed by the | |
196 | width percentage you wish. | |
197 | ||
198 | The SVG format is preferred. In this case, use the `<object>` tag to | |
199 | render an interactive SVG, with an inner raster image fallback for | |
200 | basic browsers: | |
201 | ||
202 | ```html | |
203 | <div class="img img-90"> | |
4280f592 PP |
204 | <object data="/images/docs26/image-name.svg" type="image/svg+xml"> |
205 | <img src="/images/docs26/image-name.png" alt="Short description"> | |
5e0cbfb0 PP |
206 | </object> |
207 | </div> | |
208 | ``` | |
209 | ||
210 | An interactive SVG object allows its text to be selected, amongst other | |
211 | features. | |
212 | ||
213 | ||
e70fc4f4 | 214 | Convention |
5e0cbfb0 PP |
215 | ---------- |
216 | ||
217 | A few rules to comply with in order to keep the text as | |
218 | consistent as possible: | |
219 | ||
220 | * Use _user space_, not _userspace_ nor _user-space_. | |
221 | (neither _user land_). | |
222 | * Use _file system_, not _filesystem_. | |
223 | * Use _use case_, not _use-case_ nor _usecase_. | |
224 | * Use _the C standard library_, not _libc_. | |
225 | * Use _log level_, not _loglevel_. | |
226 | * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and | |
227 | _LTTng-tools_, not _modules_, _UST_ and _tools_. | |
228 | * All code snippets should use 4 spaces for indentation (even C) | |
229 | so that they are not too large. | |
230 | * Prefer emphasis (Markdown: `_something_`, HTML: `<em>something</em>`) | |
231 | to strong (Markdown: `**something**`, HTML: `<strong>something</strong>`) | |
232 | for emphasizing text. | |
233 | * Try to stay behind the 72th column mark if possible, and behind | |
234 | the 80th column otherwise. | |
235 | * Do not end directory paths with a forward slash | |
236 | (good: `include/trace/events`, bad: `include/trace/events/`). | |
237 | * Keep the text as impersonal as possible (minimize the use of | |
238 | _I_, _we_, _us_, etc.), except for user guides/tutorials where | |
239 | _we_ have an ongoing example. | |
7d603874 PP |
240 | |
241 | ||
e70fc4f4 | 242 | Committing |
7d603874 PP |
243 | ---------- |
244 | ||
245 | If you make a change to a single contents file, prefix your Git commit | |
246 | message's first line with the file ID followed by `: `, e.g: | |
247 | ||
248 | archlinux: minor fix |