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