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 Branches
  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
  18 Structure of sources
  19 --------------------
  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
  57 Format of sources
  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
  75 #### Tip/note/warning/error blocks
  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
  94
  95 #### External links
  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
 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
 111
 112 #### Abbreviations
 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
 123 #### Non-breaking spaces
 124
 125 Sometimes, a non-breaking space HTML entity (`&nbsp;`) needs to be
 126 explicitly written.
 127
 128 Examples:
 129
 130 ```html
 131 The size of this file is 1039&nbsp;bytes.
 132
 133 This integer is displayed in base&nbsp;16.
 134
 135 A check is performed every 3000&nbsp;ms.
 136 ```
 137
 138
 139 #### Placeholders in inline code
 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
 151 #### Terminal boxes
 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
 185 #### Images
 186
 187 Use
 188
 189 ```html
 190 <div class="img img-70">
 191     <img src="/images/docs26/image-name.png" alt="Short description">
 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">
 204   <object data="/images/docs26/image-name.svg" type="image/svg+xml">
 205     <img src="/images/docs26/image-name.png" alt="Short description">
 206   </object>
 207 </div>
 208 ```
 209
 210 An interactive SVG object allows its text to be selected, amongst other
 211 features.
 212
 213
 214 Convention
 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.
 240
 241
 242 Committing
 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