contrib-guide.md

   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 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
 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 (`&nbsp;`) needs to be
 116 explicitly written.
 117
 118 Examples:
 119
 120 ```html
 121 The size of this file is 1039&nbsp;bytes.
 122
 123 This integer is displayed in base&nbsp;16.
 124
 125 A check is performed every 3000&nbsp;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.
 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