From: Philippe Proulx Date: Mon, 21 Mar 2016 20:27:05 +0000 (-0400) Subject: Rename contrib-guide.md -> CONTRIBUTING.md X-Git-Url: http://git.lttng.org./?a=commitdiff_plain;h=d7fb92a37fa5fbcf787e2c6d98d4f347d5787fe8;p=lttng-docs.git Rename contrib-guide.md -> CONTRIBUTING.md Signed-off-by: Philippe Proulx --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3c2c25c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,241 @@ +Contributor's guide +=================== + +This guide presents the structure and conventions of the LTTng +Documentation's source. Make sure you read it thoroughly before +contributing a change. + + +Branches +-------- + +The online documentation published at is always +compiled from the sources of this repository's latest stable branch. +The `master` branch contains the current documentation of the upcoming +LTTng release. + + +Structure of sources +-------------------- + +`toc/docs.yml` is a YAML tree of all chapters, sections and subsections. +It indicates which unique ID is linked to which position in the +hierarchy and its true title. + +In the `contents` directory, the `preface.md` file is the preface contents. +Each chapter has its own directory (directory names are not significant). +Within those, `intro.md` files are partial introductions and then each +section has its own directory, and so on, unless a section has no +subsections, in which case all its contents is in a single Markdown file +named _more or less_ like its ID. + +Each Markdown file begins with a YAML front matter which only contains +the unique ID of this chapter/section: + +```yaml +--- +id: unique-id-goes-here +--- + +First paragraph goes here. +``` + +Editable image sources are placed in `images/src` and their rendered +equivalents are located in `images/export`. + +`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/docs2json.py > /dev/null + + +Format of sources +----------------- + +The sources are made of a fusion of Markdown and HTML processed by +[kramdown](http://kramdown.gettalong.org/). Markdown is preferred, +HTML being only used for specific cases that need special formatting +not available using plain Markdown. The kramdown processor is clever +enough to support both languages in the same file, even in the same +paragraph! + + +### HTML specifics + +Here's a list of HTML blocks and inline code used throughout the +document. If you need to contribute, please use them when needed to +preserve the document's visual consistency. + + +#### Tip/note/warning/error blocks + +Tip/note block: + +```html +
+

+ Title goes here followed by colon:Text goes + here; plain HTML. +

+

+ Multiple paragraphs is allowed. +

+
+``` + +Replace the `tip` class with `warn` for a warning block, and with `err` +for an error message block (when JavaScript is needed but is disabled, etc.). + +Title should be `Tip:` for a tip, `Note:` for a note, `Warning:` for a +warning, and `Error:` for an error. + + +#### External links + +Internal links should always use Markdown +(`[caption](#doc-section)`). External links, however, need a special +style and must use the `` tag with the `ext` CSS class: + +```html +The LTTng Documentation is +public. +``` + +Sometimes, however, it is necessary to write internal links in plain +HTML, for example in tip blocks, since Markdown code is not processed. +In these cases, add the `int` CSS class as a hint to prevent the static +analyzer from complaining (`tools/checkdocs.py`). + + +#### Abbreviations + +Use `` for describing abbreviations. This should only be used +for the first use of the abbreviation: + +```html +The LTTng +project is an open source system software package [...] +``` + + +#### Non-breaking spaces + +Sometimes, a non-breaking space HTML entity (` `) needs to be +explicitly written. + +Examples: + +```html +The size of this file is 1039 bytes. + +This integer is displayed in base 16. + +A check is performed every 3000 ms. +``` + + +#### Placeholders in inline code + +You must use `` to emphasize a placeholder within a `` tag +because Markdown backticks (`) always render their +content literally: + +```html +Name your file something_sys.c, where +sys is your system name. +``` + + +#### Terminal boxes + +A terminal box, where command lines are shown, is a simple `
`
+with the `term` class:
+
+```html
+
+echo This is a terminal box
+

+```
+
+Do not prefix command lines with prompts (`$`/`#`) since this makes
+copy/paste operations painful.
+
+You may use `` tags to emphasize a part of the command line:
+
+```html
+
+echo This is a terminal box
+

+```
+
+Results of commands, if needed, should be presented in a simple
+`text` kramdown code block:
+
+
+~~~ text
+[15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
+[15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" }
+[15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
+~~~
+

+
+
+#### Images
+
+Use
+
+```html
+

+    Short description
+

+```
+
+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.
+
+
+Convention
+----------
+
+A few rules to comply with in order to keep the text as
+consistent as possible:
+
+  * Use _user space_, not _userspace_ nor _user-space_.
+    (neither _user land_).
+  * Use _file system_, not _filesystem_.
+  * Use _use case_, not _use-case_ nor _usecase_.
+  * Use _the C standard library_, not _libc_.
+  * Use _log level_, not _loglevel_.
+  * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
+    _LTTng-tools_, not _modules_, _UST_ and _tools_.
+  * All code snippets should use 4 spaces for indentation (even C)
+    so that they are not too large.
+  * Prefer emphasis (Markdown: `_something_`, HTML: `something`)
+    to strong (Markdown: `**something**`, HTML: `something`)
+    for emphasizing text.
+  * Try to stay behind the 72th column mark if possible, and behind
+    the 80th column otherwise.
+  * Do not end directory paths with a forward slash
+    (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 with _you_.
+  * Minimize the use of the future tense (_will_).
+  * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
+
+
+Committing
+----------
+
+If you make a change to a single contents file, prefix your Git commit
+message's first line with the file ID followed by `: `, e.g:
+
+    archlinux: minor fix
diff --git a/README.md b/README.md
index c42cc38..59a0eab 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ To contribute:
 
   1. Fork this repo
   2. Checkout the appropriate branch (`stable-2.x` or `master`)
-  3. Make your change, following the [contributor's guide](contrib-guide.md)
+  3. Make your change, following the [contributor's guide](CONTRIBUTING.md)
   4. Create a pull request
 
 Thanks for your contributions and fixes!
diff --git a/contrib-guide.md b/contrib-guide.md
deleted file mode 100644
index 3c2c25c..0000000
--- a/contrib-guide.md
+++ /dev/null
@@ -1,241 +0,0 @@
-Contributor's guide
-===================
-
-This guide presents the structure and conventions of the LTTng
-Documentation's source. Make sure you read it thoroughly before
-contributing a change.
-
-
-Branches
---------
-
-The online documentation published at  is always
-compiled from the sources of this repository's latest stable branch.
-The `master` branch contains the current documentation of the upcoming
-LTTng release.
-
-
-Structure of sources
---------------------
-
-`toc/docs.yml` is a YAML tree of all chapters, sections and subsections.
-It indicates which unique ID is linked to which position in the
-hierarchy and its true title.
-
-In the `contents` directory, the `preface.md` file is the preface contents.
-Each chapter has its own directory (directory names are not significant).
-Within those, `intro.md` files are partial introductions and then each
-section has its own directory, and so on, unless a section has no
-subsections, in which case all its contents is in a single Markdown file
-named _more or less_ like its ID.
-
-Each Markdown file begins with a YAML front matter which only contains
-the unique ID of this chapter/section:
-
-```yaml
----
-id: unique-id-goes-here
----
-
-First paragraph goes here.
-```
-
-Editable image sources are placed in `images/src` and their rendered
-equivalents are located in `images/export`.
-
-`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/docs2json.py > /dev/null
-
-
-Format of sources
------------------
-
-The sources are made of a fusion of Markdown and HTML processed by
-[kramdown](http://kramdown.gettalong.org/). Markdown is preferred,
-HTML being only used for specific cases that need special formatting
-not available using plain Markdown. The kramdown processor is clever
-enough to support both languages in the same file, even in the same
-paragraph!
-
-
-### HTML specifics
-
-Here's a list of HTML blocks and inline code used throughout the
-document. If you need to contribute, please use them when needed to
-preserve the document's visual consistency.
-
-
-#### Tip/note/warning/error blocks
-
-Tip/note block:
-
-```html
-

-    

-        Title goes here followed by colon:Text goes
-        here; plain HTML.
-    

-    

-        Multiple paragraphs is allowed.
-    

-

-```
-
-Replace the `tip` class with `warn` for a warning block, and with `err`
-for an error message block (when JavaScript is needed but is disabled, etc.).
-
-Title should be `Tip:` for a tip, `Note:` for a note, `Warning:` for a
-warning, and `Error:` for an error.
-
-
-#### External links
-
-Internal links should always use Markdown
-(`[caption](#doc-section)`). External links, however, need a special
-style and must use the `` tag with the `ext` CSS class:
-
-```html
-The LTTng Documentation is
-public.
-```
-
-Sometimes, however, it is necessary to write internal links in plain
-HTML, for example in tip blocks, since Markdown code is not processed.
-In these cases, add the `int` CSS class as a hint to prevent the static
-analyzer from complaining (`tools/checkdocs.py`).
-
-
-#### Abbreviations
-
-Use `` for describing abbreviations. This should only be used
-for the first use of the abbreviation:
-
-```html
-The LTTng
-project is an open source system software package [...]
-```
-
-
-#### Non-breaking spaces
-
-Sometimes, a non-breaking space HTML entity (` `) needs to be
-explicitly written.
-
-Examples:
-
-```html
-The size of this file is 1039 bytes.
-
-This integer is displayed in base 16.
-
-A check is performed every 3000 ms.
-```
-
-
-#### Placeholders in inline code
-
-You must use `` to emphasize a placeholder within a `` tag
-because Markdown backticks (`) always render their
-content literally:
-
-```html
-Name your file something_sys.c, where
-sys is your system name.
-```
-
-
-#### Terminal boxes
-
-A terminal box, where command lines are shown, is a simple `
`
-with the `term` class:
-
-```html
-
-echo This is a terminal box
-

-```
-
-Do not prefix command lines with prompts (`$`/`#`) since this makes
-copy/paste operations painful.
-
-You may use `` tags to emphasize a part of the command line:
-
-```html
-
-echo This is a terminal box
-

-```
-
-Results of commands, if needed, should be presented in a simple
-`text` kramdown code block:
-
-
-~~~ text
-[15:30:34.835895035] (+?.?????????) hostname hello_world: { cpu_id = 1 }, { my_int = 8, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
-[15:30:42.262781421] (+7.426886386) hostname hello_world: { cpu_id = 1 }, { my_int = 9, char0 = 80, char1 = 97, product = "Patriot Memory" }
-[15:30:48.175621778] (+5.912840357) hostname hello_world: { cpu_id = 1 }, { my_int = 10, char0 = 68, char1 = 97, product = "DataTraveler 2.0" }
-~~~
-

-
-
-#### Images
-
-Use
-
-```html
-

-    Short description
-

-```
-
-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.
-
-
-Convention
-----------
-
-A few rules to comply with in order to keep the text as
-consistent as possible:
-
-  * Use _user space_, not _userspace_ nor _user-space_.
-    (neither _user land_).
-  * Use _file system_, not _filesystem_.
-  * Use _use case_, not _use-case_ nor _usecase_.
-  * Use _the C standard library_, not _libc_.
-  * Use _log level_, not _loglevel_.
-  * Use complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
-    _LTTng-tools_, not _modules_, _UST_ and _tools_.
-  * All code snippets should use 4 spaces for indentation (even C)
-    so that they are not too large.
-  * Prefer emphasis (Markdown: `_something_`, HTML: `something`)
-    to strong (Markdown: `**something**`, HTML: `something`)
-    for emphasizing text.
-  * Try to stay behind the 72th column mark if possible, and behind
-    the 80th column otherwise.
-  * Do not end directory paths with a forward slash
-    (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 with _you_.
-  * Minimize the use of the future tense (_will_).
-  * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
-
-
-Committing
-----------
-
-If you make a change to a single contents file, prefix your Git commit
-message's first line with the file ID followed by `: `, e.g:
-
-    archlinux: minor fix