| 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. |