SOP 000-Documentation » Historique » Révision 60
Révision 59 (Patrice Nadeau, 2023-01-29 12:20) → Révision 60/67 (Patrice Nadeau, 2023-01-29 12:22)
# 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] "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)
{{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 | 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 :
* 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
------ | ----- | -------
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/)
[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)