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 | ||
9 | structure | |
10 | --------- | |
11 | ||
12 | `toc/docs.yml` is a YAML tree of all chapters, sections and subsections. | |
13 | It indicates which unique ID is linked to which position in the | |
14 | hierarchy and its true title. | |
15 | ||
16 | In the `contents` directory, the `preface.md` file is the preface contents. | |
17 | Each chapter has its own directory (directory names are not significant). | |
18 | Within those, `intro.md` files are partial introductions and then each | |
19 | section has its own directory, and so on, unless a section has no | |
20 | subsections, in which case all its contents is in a single Markdown file | |
21 | named _more or less_ like its ID. | |
22 | ||
23 | Each Markdown file begins with a YAML front matter which only contains | |
24 | the unique ID of this chapter/section: | |
25 | ||
26 | ```yaml | |
27 | --- | |
28 | id: unique-id-goes-here | |
29 | --- | |
30 | ||
31 | First paragraph goes here. | |
32 | ``` | |
33 | ||
34 | Editable image sources are placed in `images/src` and their rendered | |
35 | equivalents are located in `images/export`. | |
36 | ||
37 | `tools/checkdocs.py` is a Python 3 script which may be used to find | |
38 | typical errors in the whole documentation (dead internal links, | |
39 | common grammar mistakes, etc.). It needs the | |
40 | [`termcolor`](https://pypi.python.org/pypi/termcolor) Python package. | |
41 | Run it from the repository's root: | |
42 | ||
43 | tools/checkdocs.py | |
44 | ||
45 | and it will potentially output a list of errors and warnings. | |
46 | ||
47 | ||
48 | format of sources | |
49 | ----------------- | |
50 | ||
51 | The sources are made of a fusion of Markdown and HTML processed by | |
52 | [kramdown](http://kramdown.gettalong.org/). Markdown is preferred, | |
53 | HTML being only used for specific cases that need special formatting | |
54 | not available using plain Markdown. The kramdown processor is clever | |
55 | enough to support both languages in the same file, even in the same | |
56 | paragraph! | |
57 | ||
58 | ||
59 | ### HTML specifics | |
60 | ||
61 | Here's a list of HTML blocks and inline code used throughout the | |
62 | document. If you need to contribute, please use them when needed to | |
63 | preserve the document's visual consistency. | |
64 | ||
65 | ||
66 | #### tip/note block | |
67 | ||
68 | Tip/note block: | |
69 | ||
70 | ```html | |
71 | <div class="tip"> | |
72 | <p> | |
73 | <span class="t">Title goes here followed by colon:</span>Text goes | |
74 | here; plain HTML. | |
75 | </p> | |
76 | <p> | |
77 | Multiple paragraphs is allowed. | |
78 | </p> | |
79 | </div> | |
80 | ``` | |
81 | ||
82 | Title should be `Tip:` for a tip and `Note:` for a note. | |
83 | ||
84 | ||
85 | #### external links | |
86 | ||
87 | Internal links should always use Markdown | |
88 | (`[caption](#doc-section)`). External links, however, need a special | |
89 | style and must use the `<a>` tag with the `ext` CSS class: | |
90 | ||
91 | ```html | |
92 | The LTTng Documentation is | |
93 | <a href="https://github.com/lttng/lttng-docs" class="ext">public</a>. | |
94 | ``` | |
95 | ||
cc3ab47f PP |
96 | Sometimes, however, it is necessary to write internal links in plain |
97 | HTML, for example in tip blocks, since Markdown code is not processed. | |
98 | In these cases, add the `int` CSS class as a hint to prevent the static | |
99 | analyzer from complaining (`tools/checkdocs.py`). | |
100 | ||
5e0cbfb0 PP |
101 | |
102 | #### abbreviations | |
103 | ||
104 | Use `<abbr>` for describing abbreviations. This should only be used | |
105 | for the first use of the abbreviation: | |
106 | ||
107 | ```html | |
108 | The <abbr title="Linux Trace Toolkit: next generation">LTTng</abbr> | |
109 | project is an open source system software package [...] | |
110 | ``` | |
111 | ||
112 | ||
113 | #### non-breaking spaces | |
114 | ||
115 | Sometimes, a non-breaking space HTML entity (` `) needs to be | |
116 | explicitly written. | |
117 | ||
118 | Examples: | |
119 | ||
120 | ```html | |
121 | The size of this file is 1039 bytes. | |
122 | ||
123 | This integer is displayed in base 16. | |
124 | ||
125 | A check is performed every 3000 ms. | |
126 | ``` | |
127 | ||
128 | ||
129 | #### placeholders in inline code | |
130 | ||
131 | You must use `<em>` to emphasize a placeholder within a `<code>` tag | |
132 | because Markdown backticks (<code>`</code>) always render their | |
133 | content literally: | |
134 | ||
135 | ```html | |
136 | Name your file <code>something_<em>sys</em>.c</code>, where | |
137 | <code><em>sys</em></code> is your system name. | |
138 | ``` | |
139 | ||
140 | ||
141 | #### terminal boxes | |
142 | ||
143 | A terminal box, where command lines are shown, is a simple `<pre>` | |
144 | with the `term` class: | |
145 | ||
146 | ```html | |
147 | <pre class="term"> | |
148 | echo This is a terminal box | |
149 | </pre> | |
150 | ``` | |
151 | ||
152 | Do not prefix command lines with prompts (`$`/`#`) since this makes | |
153 | copy/paste operations painful. | |
154 | ||
155 | You may use `<strong>` tags to emphasize a part of the command line: | |
156 | ||
157 | ```html | |
158 | <pre class="term"> | |
159 | echo This is a <strong>terminal</strong> box | |
160 | </pre> | |
161 | ``` | |
162 | ||
163 | Results of commands, if needed, should be presented in a simple | |
164 | `text` kramdown code block: | |
165 | ||
166 | <pre> | |
167 | ~~~ text | |
168 | [15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
169 | [15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" } | |
170 | [15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" } | |
171 | ~~~ | |
172 | </pre> | |
173 | ||
174 | ||
175 | #### images | |
176 | ||
177 | Use | |
178 | ||
179 | ```html | |
180 | <div class="img img-70"> | |
181 | <img src="/images/docs/image-name.png" alt="Short description"> | |
182 | </div> | |
183 | ``` | |
184 | ||
185 | to display an image. Change `img-70` to `img-` followed by the | |
186 | width percentage you wish. | |
187 | ||
188 | The SVG format is preferred. In this case, use the `<object>` tag to | |
189 | render an interactive SVG, with an inner raster image fallback for | |
190 | basic browsers: | |
191 | ||
192 | ```html | |
193 | <div class="img img-90"> | |
194 | <object data="/images/docs/image-name.svg" type="image/svg+xml"> | |
195 | <img src="/images/docs/image-name.png" alt="Short description"> | |
196 | </object> | |
197 | </div> | |
198 | ``` | |
199 | ||
200 | An interactive SVG object allows its text to be selected, amongst other | |
201 | features. | |
202 | ||
203 | ||
204 | convention | |
205 | ---------- | |
206 | ||
207 | A few rules to comply with in order to keep the text as | |
208 | consistent as possible: | |
209 | ||
210 | * Use _user space_, not _userspace_ nor _user-space_. | |
211 | (neither _user land_). | |
212 | * Use _file system_, not _filesystem_. | |
213 | * Use _use case_, not _use-case_ nor _usecase_. | |
214 | * Use _the C standard library_, not _libc_. | |
215 | * Use _log level_, not _loglevel_. | |
216 | * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and | |
217 | _LTTng-tools_, not _modules_, _UST_ and _tools_. | |
218 | * All code snippets should use 4 spaces for indentation (even C) | |
219 | so that they are not too large. | |
220 | * Prefer emphasis (Markdown: `_something_`, HTML: `<em>something</em>`) | |
221 | to strong (Markdown: `**something**`, HTML: `<strong>something</strong>`) | |
222 | for emphasizing text. | |
223 | * Try to stay behind the 72th column mark if possible, and behind | |
224 | the 80th column otherwise. | |
225 | * Do not end directory paths with a forward slash | |
226 | (good: `include/trace/events`, bad: `include/trace/events/`). | |
227 | * Keep the text as impersonal as possible (minimize the use of | |
228 | _I_, _we_, _us_, etc.), except for user guides/tutorials where | |
229 | _we_ have an ongoing example. | |
7d603874 PP |
230 | |
231 | ||
232 | committing | |
233 | ---------- | |
234 | ||
235 | If you make a change to a single contents file, prefix your Git commit | |
236 | message's first line with the file ID followed by `: `, e.g: | |
237 | ||
238 | archlinux: minor fix |