SOP 000-Documentation » Historique » Révision 49
Révision 48 (Patrice Nadeau, 2018-03-31 15:47) → Révision 49/67 (Patrice Nadeau, 2018-03-31 15:48)
# 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><code class="c">
...
</code></pre>
* 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*)
* 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 :
* 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](http://en.wikipedia.org/wiki/Octet_%28computing%29).
|_. Mesure | |_. Unité |_. Symbole | 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
<table>
<tr>
<td style="text-align:center;"> Préfixe </td>
<td> Symbole </td>
<td> Notation </td>
<td> Représentation</td>
</tr>
</table>
| 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 | µ | 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 |
#### 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)