# SOP 000-Documentation

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

* Documents

* Présentations

* Wikis

{{lastupdated_at}} {{lastupdated_by}}

---

{{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

Il existe deux type de documentation avec chacun leur outils :

* « stand-alone » : fichier XeTeX

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

* « live » : wiki (Redmine)

L’écriture se fait :

* Redmine : Écrit en format *Markdown*

# Description

> Explication supplémentaires (si nécessaires)

{{lastupdated_at}} {{lastupdated_by}}

----

{{toc}}

## 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 |_.  Textile |

| *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 : «class» étant :  *c*, *bash*, *latex*, *php* (voir [[Redmine:wiki#Redmine-Rouge|Redmine Rouge]])

<pre>

<pre><code class="c">

...

</code></pre>

</pre>

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

<pre><code class="latex">

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

    ssh serveur

\end{lstlisting}

</code></pre>

#### 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 : Elle 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*)

* Textile : *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 :

* Textile : (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 :

* Redemine : Un lien sur un « issue »

* XeTex (_todonotes_ est utilisé)

<pre><code class="latex">

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

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

</code></pre>

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

<pre><code class="latex">

\newpage

\section{Todo}

\listoftodos[]

</code></pre>

### 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 <notextile>></notextile>

<pre><code class="text">

item

> Texte

</code></pre>

* XeTeX

<pre><code class="latex">

\paragraph{item :}

Texte

</code></pre>

_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

Les 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 :

<pre><code class="latex">

\SI{10000.01}{\micro\A}

</code></pre>

### Symboles

Les symboles sont fait de la façon suivantes : 

|_. Symbole |_. Signification |_. HTML |_. Textile |_. XeTex |

| &#8776; | Approximativement | <notextile>&#8776;</notextile> | | \approx |

| &plusmn; | Plus ou moins (tolérance) | <notextile> &plusmn; </notextile> | | |

| &gt; | Plus grand | <notextile> &gt; </notextile> | | |

| &ge; | Plus grand ou égale | <notextile> &ge; </notextile> | | |

| &lt; | Plus petit | <notextile> &lt; </notextile> | | |

| &le; | Plus petit ou égale | <notextile> &le; </notextile> | | |

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

| &Omega; | Ohm (unité) | <notextile> &Omega; </notextile> | | \si{\ohm} |

| &micro; | micro (préfixe) | <notextile>&micro;</notextile> | | \si{\micro} |

### Unité de mesure

Les unités de mesure à utiliser :

> "Le _byte_ n'est pas une unité officielle.":http://en.wikipedia.org/wiki/Octet_%28computing%29

|_. 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

|_. Préfixe |_. Symbole |_. Notation |_. Représentation |

| tera | T | 10<notextile></notextile>^12^ | 1 000 000 000 000 |

| giga | G | 10<notextile></notextile>^9^ | 1 000 000 000 |

| mega | M | 10<notextile></notextile>^6^ | 1 000 000 |

| kilo | k | 10<notextile></notextile>^3^ | 1 000 |

| deci | d | 10<notextile></notextile>^1^ | 0.1 |

| milli | m | 10<notextile></notextile>^-3^ | 0.001 |

| micro | &micro; | 10<notextile></notextile>^-6^  | 0.000 001 |

| nano | n | 10<notextile></notextile>^-9^ | 0.000 000 001 |

| pico | p| 10<notextile></notextile>^-12^ | 0.000 000 000 001 |

<table>

         <tr>

             <td style="text-align:center;"> Préfixe </td>

         </tr>

</table>

             <td> Symbole </td>

             <td> Notation </td>

             <td> Représentation</td>

         </tr>

</table>

        <tr>

            <td> tera | T | 10<notextile></notextile>^12^ | 1 000 000 000 000 | </td>

| giga | G | 10<notextile></notextile>^9^ | 1 000 000 000 |

| mega | M | 10<notextile></notextile>^6^ | 1 000 000 |

| kilo | k | 10<notextile></notextile>^3^ | 1 000 |

| deci | d | 10<notextile></notextile>^1^ | 0.1 |

| milli | m | 10<notextile></notextile>^-3^ | 0.001 |

| micro | &micro; | 10<notextile></notextile>^-6^  | 0.000 001 |

| nano | n | 10<notextile></notextile>^-9^ | 0.000 000 001 |

| pico | p| 10<notextile></notextile>^-12^ | 0.000 000 000 001 |

      </tr>

</table>

#### 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/

"8e édition de la brochure du Système international d’unités":http://www.bipm.org/utils/common/pdf/si_brochure_8_fr.pdf

"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