Editable image sources are placed in `images/src` and their rendered
equivalents are located in `images/export`.
-`tools/checkdocs.py` is a Python 3 script which may be used to find
-typical errors in the whole documentation (dead internal links,
-common grammar mistakes, etc.). It needs the
-[`termcolor`](https://pypi.python.org/pypi/termcolor) Python package.
-Run it from the repository's root:
+`tools/docs2json.py` is a Python 3 script which may be used to get
+the graph of internal and external links and to find
+typical errors in the whole documentation, like dead internal links.
+It needs the
+[`termcolor`](https://pypi.python.org/pypi/termcolor) Python 3 package.
+Run it from the repository's root and ignore its standard output
+to view the warnings and errors:
- tools/checkdocs.py
-
-and it will potentially output a list of errors and warnings.
+ tools/docs2json.py > /dev/null
Format of sources
Use
```html
-<div class="img img-70">
+<figure class="img img-70">
<img src="/images/docs26/image-name.png" alt="Short description">
-</div>
+</figure>
```
+Replace `docs26` with the appropriate version tag depending on the
+checked out branch.
+
to display an image. Change `img-70` to `img-` followed by the
width percentage you wish.
-The SVG format is preferred. In this case, use the `<object>` tag to
-render an interactive SVG, with an inner raster image fallback for
-basic browsers:
-
-```html
-<div class="img img-90">
- <object data="/images/docs26/image-name.svg" type="image/svg+xml">
- <img src="/images/docs26/image-name.png" alt="Short description">
- </object>
-</div>
-```
-
-An interactive SVG object allows its text to be selected, amongst other
-features.
-
Convention
----------
(good: `include/trace/events`, bad: `include/trace/events/`).
* Keep the text as impersonal as possible (minimize the use of
_I_, _we_, _us_, etc.), except for user guides/tutorials where
- _we_ have an ongoing example.
+ _we_ have an ongoing example with _you_.
+ * Minimize the use of the future tense (_will_).
+ * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
Committing