Documentation style and format recommendation for the project

Documentation provided and maintained as part of the project SHALL NOT use file formats that require non-FOSS software for processing. Plaintext files are preferred for text documentation, PNG for raster graphics and SVG for vector graphics. Project SHOULD consider that the build farm hosts MAY not have installed the graphical environment and desktop/GUI document processing software, so optional generation of documentation in formats comfortable for end-user consumption SHOULD rely on common processing tools outlined in the "Dependencies" section of CLASS.

Committed text and documentation files SHOULD use asciidoc markup if they are structured (including sources for "man" pages, project standards and contracts, user or developer instructions, etc.)

Texts MAY be in other markups (e.g. plain ASCII, or markdown) only if they were originally imported from other sources or projects, and if regular subsequent synchronisation, re-import or other comparison to origin of these files is anticipated (e.g. a copy of the standard text of a license chosen by the project, or third party project sources co-distributed as a dependency — where such projects encourage co-distribution rather than release/package dependencies with a clean separation of borders), or if the text file is unstructured (e.g. a line-by-line list of authors without categories… note that almost anything else is inherently structured).

Project building recipes MAY assume by default that asciidoc program is the proper tool for processing of committed (or interim generated) text files into other end-user formats, such as MAN, HTML or PDF variants of the documentation. Any other cases should be specifically handled by the recipes as exceptions to the common rule.

It is RECOMMENDED that source text files using asciidoc-compatible markup be named with an .asciidoc or .adoc extension (consistently for the whole project), rather than the common indeterminate .txt extension or lack of any extension.

It is RECOMMENDED that text files in non-asciidoc compatible markups use their appropriate extensions (e.g. .md for MarkDown), rather than a common indeterminate .txt extension or lack of any extension.

Paragraphs, separate lists of items, code example blocks and other similar groupings of content lines processed specially by the rendering tools SHALL be separated (preceded and followed) by at least one blank line. Section headers MAY be visibly stressed by preceding or surrounding them with two blank lines; if picked, this formatting option should be applied consistently to the whole document.

Trailing whitespace characters (SPACE, TAB) and lines fully consisting of whitespace SHOULD be avoided.

Sequences of more than one whitespace (e.g. two or more SPACE characters in a row) SHOULD be avoided, wherever such sequences are not part of indentation or do not carry other contextual meaning.

If a style is picked to separate sentences in a paragaph with a period . followed by two SPACE characters, this style SHALL be used consistenly in the whole document.

Lines of bulleted or numbered lists SHALL have the same style regarding a final punctuation character, consistent within at least the list itself — usually semicolon ; for relatively short entries, period . for full sentences (especially when there are several sentences per list item), and a comma , optionally with trailing conjunctions (and/or) for shortest entries that can be read together as parts of a larger sentence; and the last line of the list SHALL end with a period . character.

An alternative style is to have no trailing punctuation for list items which otherwise are each a single regular sentence. For lists represented with such choice of style, the consistent option is that the last line also has no punctuation (no period .) as its last character.

If an explanatory (semi-)sentence or paragraph precedes such a list, that sentence SHOULD end with a colon : followed by a blank line (for asciidoc markup). If the preceding sentence or paragraph is not an introduction into the contents of the list, it SHOULD be formatted as a usual paragraph, ending with a period . character.

Nested lists are considered as separate lists; the last line of each such list at the same level of indentation SHALL end with a period . character (if any punctuation is used to terminate preceding lines of this list).

three period characters ... over an an ellipsis character "…", or

the numerous ways to type a single or double quote, or

the use of plain "minus" - or double-minus -- characters over different long-dash characters, and

use of asciidoc (or equivalent) plaintext markup like (TM) or (C) instead of singular characters like ™ or ©.

It is RECOMMENDED to precede documentation examples of command-line usage of Unix shell constructs with the colon+semicolon :; as the placeholder of interactive shell prompt at start of a line followed by a single space character (this allows for easy copying and pasting of multi-line examples from documentation into command line, since the sequence would be interpreted by most shells as a non-fatal and non-consequential operation, running or short-circuiting the true command in place of the colon : character).

For similar reasons it is RECOMMENDED to parametrize the probable variables in the example shell code snippets (such as URLs or filenames), especially if they are repeated more than once.

Likewise, it is RECOMMENDED to organize logical chains (where the subsequent command should only be executed if a previous one did not fail) using the && shell sequence.

If the example command-line is longer than 70 characters, it SHOULD be split into multiple lines "concatenated" by trailing backslash as is common in shell scripts; continuation lines SHOULD be indented by at least the length of the shell prompt placeholder (3 spaces for the :; recommended prompt and separator that follows).

If the command-line example block includes output from the command to be entered by the reader, the example command SHOULD be separated by a blank line from the sample (or expected) output.

If multiple related but separate example code lines follow each other in the same example code block, they MAY be presented without blank lines in between. However, if there is also sample output, the rule above applies, and if the example commands continue after the sample output, it is additionally RECOMMENDED to separate the output from next commands by two blank lines.

If an explanatory (semi-)sentence or paragraph precedes example code, that sentence SHOULD end with a colon : followed by a blank line (for asciidoc markup). If the preceding sentence or paragraph is not an introduction into the contents of the example, it SHOULD be formatted as a usual paragraph, ending with a period . character.

If the sentence after a source-code example effectively continues the sentence interjected by the block with source-code example, that continuation line SHOULD start with triple-dots and a lower-case character in the first word. For clarity, it is RECOMMENDED to phrase the text in such a manner that singular sentences are not "interrupted" by large blocks of example code.

Line lengths SHOULD NOT exceed 78 characters, and SHOULD NOT vary greatly in the middle of a paragraph (the RECOMMENDED line length ranges from 66 to 76 characters).

Long paragraphs broken into several lines SHALL use whole-word wrapping.

In-line short ranges of "verbatim" text, such as filenames and keywords, SHALL be enclosed in backticks `` (for asciidoc markup, or its equivalent for other formats). Verbatim text SHALL NOT be decorated otherwise (italic, bold, underline) if the surrounding text in the paragraph is not decorated so.

Introduction or other stressing of terminology SHOULD be enclosed in double quotes.

Sentences separated by a tiree (long-dash) SHALL use a sequence of two "minus" characters -- surrounded by single SPACE characters; if such separation happens at end of a line, then the two minuses preceded by a SPACE character SHALL be the last characters in the line (no trailing SPACE, and no lines starting with a carried-over double-minus).

Words joined by a dash, mathematical negative numbers and substrations SHALL use a single "minus" - character without surrounding whitespace. If such separation happens at end of a line, then the "minus" character SHALL be the last characters in the line (no trailing SPACE, and no lines starting with a carried-over minus).