# SOP 000-Documentation

Établir un style de documentation unifié pour les items suivants :

* Documents

* Présentations

* Wikis

---

{{toc}}

## Termes

Les termes français équivalents au document [RFC2119](http://tools.ietf.org/html/rfc2119) seront utilisés dans les documents :

* MUST, SHALL, REQUIRED : DOIT, REQUIS

* MUST NOT, SHALL NOT : NE DOIT (DOIVENT) PAS

* SHOULD, RECOMMENDED : DEVRAIS, RECOMMANDÉ

* SHOULD NOT : NE DEVRAIS PAS, NON RECOMMANDÉ

* MAY, OPTIONAL : PEUX (PEUVENT), OPTIONNEL

Ces termes sont utilisés pour indiquer un choix quand plusieurs options sont disponibles.

## Généralités

La documentation DOIT être générée avec des outils « open-source ».

### Formats utilisés

Chaque format est fait avec un langage de balisage différents :

* Manuels et présentations : fichiers XeTeX (**.tex**)

    > Ils DOIVENT être exportés en format PDF.

* Documents locaux : fichiers [GitHub Flavored Markdown](https://github.github.com/gfm/) (**.markdown**)

* Redmine : [GitHub Flavored Markdown](https://github.github.com/gfm/)

# Description

> Explication supplémentaires (si nécessaires)

----

## Premier titre

### Sous-titre

* XeTeX : Le contenu du fichier _tex_ DOIT être fait de la manière suivante :

    * Format : Lettre.

    * Orientation : Portrait.

    * Langue : Français

    * Type : Article

    * Format : UTF-8

    * Lignes : longueur de 80 caractères

    * Retrait : de 4 espaces dans les sections _\begin{} ... \end(}_

    * Les gabarits déjà établis DOIVENT être utilisés.

### Typographie

#### Type de caractères

| Effet | Signification | XeTeX | Markdown |

|-|-|-|-|

| **Gras** | doit être indiqué comme tel | \textbf{...} | \*\* ... ** |

| *Italique* | doit être substitué par la bonne valeur | \textit{...} | \* ... \* |

| *Emphase* | emphase | \emph{...} | \* ... \* |

| -Barré- | non valide | \sout{...} |\~...\~|

#### Code source 

Le code source doit toujours être mis en évidence avec un outil de «syntax highlight»

* Redmine : Les langages supportés sont ceux de [CodeRay](http://coderay.rubychan.de/)

    <code>

        ```c

        code to display

        ```

    </code>

* XeTeX : Le module _lstlisting_ est utilisé. Des titres et emphases peuvent être utilisées.

    ```

    \begin{lstlisting}[language=xxx, title=yyy, emph=serveur]

        ssh serveur

    \end{lstlisting}

    ```

#### Guillemets

Les [guillemets](http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks#French) (« & ») DOIVENT être utilisés dans les document français.

> Il DOIT y avoir un espace entre les guillemets et le mot.

Ils sont faits de cette façon :

* Redmine : Unicode U+00AB (171), U+00BB (187)

    > Sous GNU/Linux, il peuvent être fait avec la combinaison *ALT-z* et *ALT-x* en mode français (utiliser la touche ALT de droite).

* XeTeX :

Ils DOIVENT être faits avec **\enquote{}**

#### Police

La police de caractère et son poids sont générés par Redmine et XeTeX.

### Images

Les images DOIVENT être de format PNG

* XeTeX : Elles DOIVENT être enregistrées dans le même dossier que le fichier _.tex_.

## Documents

Conventions utilisées dans les documents.

## Découpage du document

Sections minimum pour différents type de documents :

* Documentation de logiciel (guides) :

    * Introduction.

    * Installation.

    * Configuration.

    * Utilisation.

    * Problèmes connus.

    * Todo (XeTeX).

### Style

Le document est séparés au moyen de :

* XeTeX : *section*, *subsection* et *subsubsection* (*\section{}* DOIT être précédée de *\newpage*)

* Markdown : *h2* @ *h3* (suivie d'une ligne vide)

La table des matières seras faites automatiquement avec ces items.

Chaque section DOIT commencer par une brève description.

### Listes

Les listes sont faites avec : 

* Redmine :

    * *<notextile>*</notextile>* : pour des items ayant une description.

    * *<notextile>#</notextile>* : pour des « étapes ».

* XeTeX :

    * \begin{xxx} ... \end{xxx}, xxx représentant:

        * **description** : pour des items ayant une description.

        * **enumerate** : pour des «étapes».

        * **itemize** : le type le plus fréquent.

### Hyperliens

L’utilisation des hyperliens ce fait avec :

* Redmine : (voir http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting)

    * _Documents_ : **document\#nb**

    * _Files_ : *<notextile>"titre":/attachments/do </notextile>*

* XeTeX : **\label{}**, **\ref{}**, **\pageref{}** 

    * Les étiquettes sont faites selon cette convention (_xxx_:étiquette), _xxx_ étant un des choix :

        * **chap:** : chapitre

        * **sec:** : section

        * **subsec:** : sous-section

        * **fig:** : figure

        * **tab:** : table

        * **eq:** : équation

        * **lst:** : code

        * **itm:** : liste énumérée

        * **app:** : sous-section d’appendice

### Items à faire

Les notes pour les items à faire plus tard DOIVENT être décrites comme suit :

* Redmine : Un lien sur un « issue »

* XeTex (**todonotes** est utilisé)

        \todo[inline]{Texte de ce qu'il y a à faire}

        \todo\missingfigure{Texte de l'image manquante}

    > Une section DOIT aussi êtres ajoutée avant la toute fin du document :

        \newpage

        \section{Todo}

        \listoftodos[]

### Paragraphes spéciaux

Les items nécessitant une attention particulière de la part du lecteur, sont identifiés avec :

* Redmine : un retrait fait avec **>** :

        item

        > Texte

* XeTeX

        \paragraph{item :}

        Texte

_item_ étant une des valeurs :

* *Note* : explications non critiques sur un point

* *Avertissement* : un point qui mérite une grande attention

* *Ex.* : un exemple

## Standards

### Tableau

Un tableau est fait de la manière suivante :

* La tableau et les cellules DOIVENT avoir une bordure

* Les données DOIVENT être en ordre (alphabétique ou numérique, selon le cas)

* La première ligne DOIT 

    * contenir le nom des colonnes

    * être centrées 

    * en caractères gras

### Couleurs

Abréviations selon [IEC 60757](https://webstore.iec.ch/publication/3406)

* *BK* : Noir

* *BU* : Bleu

* *BN* : Brun

* *RD* : Rouge

* *YE* : Jaune

* *VT* : Violet

* *GR* : Gris

* *WH* : Blanc

* *CL* : Transparent 

    > Ne fait pas partie du standard

### Dates et heures

L’heure des documents généraux est inscrite en format français (xx h yy.)

Les documents technique eux sont inscrits dans le format [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) :

* Date : 2014-08-24

* Heure : 13:28

### Notation

Règles d’affichage des nombres et des unités.

Les règles suivantes DOIVENT être utilisées :

* le séparateur décimal DOIT être un point,

* le séparateur pour les milliers DOIT être un (demi-)espace,

* le nombre est suivit d’un (demi-)espace et du préfixe et de l’unité de mesure 

Sous _XeTex_, l’utilisation de _siunitx_ EST requise.

Ex. : 

> Pour avoir 10 000.01 μA :

    \SI{10000.01}{\micro\A}

### Symboles

Les symboles sont fait de la façon suivantes : 

**Symbole** | **Signification** | **HTML** | **XeTex**

----------- | ----------------- | -------- | ---------

≈ | Approximativement | `≈` |`\approx`

± | Plus ou moins (tolérance) | `±` 

> | Plus grand | `>`

≥ | Plus grand ou égale | `≥`

< | Plus petit | `<`

≤ | Plus petit ou égale | `≤`

o | octet (unité) | | o | \octet

Ω | Ohm (unité) | `Ω` | \si{\ohm}

µ | micro (préfixe) | `µ` | \si{\micro}

### Unité de mesure

Les unités de mesure à utiliser :

> [Le _byte_ n'est pas une unité officielle](https://fr.wikipedia.org/wiki/Octet).

Mesure | Unité | Symbole

------ | ----- | -------

Longueur | mètre | m

Masse | kilogramme | kg

Courant électrique | ampère | A

Donnés | bit | bit

Donnés | octet | o

Résistance | ohm | Ω

Capacitance | farad | F

Voltage | volt | V

Fréquence | hertz | Hz

Puissance | watt | W

### Préfixes

#### Base 10

Symbole | Notation | Représentation

------- | -------- | --------------

tera | T | 10^12 | 1 000 000 000 000

giga | G | 10^9 | 1 000 000 000

mega | M | 10^6 | 1 000 000

kilo | k | 10^3 | 1 000

deci | d | 10^1 | 0.1

milli | m | 10^-3 | 0.001

micro | µ | 10^-6  | 0.000 001

nano | n | 10^-9 | 0.000 000 001

pico | p| 10^-12 | 0.000 000 000 001

#### Base 2

Pour les données informatiques (1024).

Préfixe | Symbole | Représentation

------- | ------- | --------------

tebi | Ti | 1 099 511 627 776 octets

gibi | Gi | 1 073 741 824 octets

mebi | Mi | 1 048 576 octets

kibi | Ki | 1024 octets

## Référence

[How To Read Command Syntax](http://pcsupport.about.com/od/commandlinereference/a/command-syntax.htm)

[Les unités de mesure du système métrique - Le français sans secrets - Portail linguistique du Canada](http://www.noslangues-ourlanguages.gc.ca/bien-well/fra-eng/typographie-typography/metrique-metric-fra.html)

[Office québécois de la langue française](http://www.oqlf.gouv.qc.ca/)

[9e édition de la brochure du Système international d’unités](https://www.bipm.org/documents/20126/41483022/SI-Brochure-9.pdf/fcf090b2-04e6-88cc-1149-c3e029ad8232?version=1.21&t=1671101063858&download=true)

[Date et heures en français](http://servicesdedition.com/fr/langue/chroniques/coordonnees.html)

[IEC_80000-13](http://en.wikipedia.org/wiki/IEC_80000-13)

[IEEE 1541-2002](http://en.wikipedia.org/wiki/IEEE_1541-2002)