Projet

Général

Profil

SOP 000-Documentation » Historique » Version 61

Patrice Nadeau, 2023-01-29 12:23

1 17 Patrice Nadeau
# SOP 000-Documentation
2 1 Patrice Nadeau
3
Établir un style de documentation unifié pour les items suivants :
4 41 Patrice Nadeau
5 1 Patrice Nadeau
* Documents
6
* Présentations
7
* Wikis
8
9
---
10
11
{{toc}}
12
13 17 Patrice Nadeau
## Termes
14 1 Patrice Nadeau
15 61 Patrice Nadeau
Les termes français équivalents au document [RFC2119](http://tools.ietf.org/html/rfc2119) seront utilisés dans les documents :
16 42 Patrice Nadeau
17 1 Patrice Nadeau
* MUST, SHALL, REQUIRED : DOIT, REQUIS
18
* MUST NOT, SHALL NOT : NE DOIT (DOIVENT) PAS
19
* SHOULD, RECOMMENDED : DEVRAIS, RECOMMANDÉ
20
* SHOULD NOT : NE DEVRAIS PAS, NON RECOMMANDÉ
21
* MAY, OPTIONAL : PEUX (PEUVENT), OPTIONNEL
22
23
Ces termes sont utilisés pour indiquer un choix quand plusieurs options sont disponibles.
24
25 17 Patrice Nadeau
## Généralités
26 1 Patrice Nadeau
27
La documentation DOIT être générée avec des outils « open-source ».
28
29 17 Patrice Nadeau
### Formats utilisés
30 1 Patrice Nadeau
31 52 Patrice Nadeau
Chaque format est fait avec un langage de balisage différents :
32 19 Patrice Nadeau
33 52 Patrice Nadeau
* Manuels et présentations : fichiers XeTeX (**.tex**)
34 1 Patrice Nadeau
35
    > Ils DOIVENT être exportés en format PDF.
36 52 Patrice Nadeau
* Documents locaux : fichiers [GitHub Flavored Markdown](https://github.github.com/gfm/) (**.markdown**)
37
* Redmine : [GitHub Flavored Markdown](https://github.github.com/gfm/)
38 19 Patrice Nadeau
39
40 17 Patrice Nadeau
# Description
41 1 Patrice Nadeau
42
> Explication supplémentaires (si nécessaires)
43
44
{{lastupdated_at}} {{lastupdated_by}}
45
46
----
47
48
{{toc}}
49
50 17 Patrice Nadeau
## Premier titre
51 1 Patrice Nadeau
52 17 Patrice Nadeau
### Sous-titre
53 20 Patrice Nadeau
54 1 Patrice Nadeau
* XeTeX : Le contenu du fichier _tex_ DOIT être fait de la manière suivante :
55 20 Patrice Nadeau
    * Format : Lettre.
56
    * Orientation : Portrait.
57
    * Langue : Français
58
    * Type : Article
59
    * Format : UTF-8
60
    * Lignes : longueur de 80 caractères
61
    * Retrait : de 4 espaces dans les sections _\begin{} ... \end(}_
62
    * Les gabarits déjà établis DOIVENT être utilisés.
63 1 Patrice Nadeau
64 17 Patrice Nadeau
### Typographie
65 1 Patrice Nadeau
66 17 Patrice Nadeau
#### Type de caractères
67 1 Patrice Nadeau
68 56 Patrice Nadeau
| Effet | Signification | XeTeX | Markdown |
69 55 Patrice Nadeau
|-|-|-|-|
70 57 Patrice Nadeau
| **Gras** | doit être indiqué comme tel | \textbf{...} | \*\* ... ** |
71
| *Italique* | doit être substitué par la bonne valeur | \textit{...} | \* ... \* |
72
| *Emphase* | emphase | \emph{...} | \* ... \* |
73 56 Patrice Nadeau
| -Barré- | non valide | \sout{...} | |
74 1 Patrice Nadeau
75 17 Patrice Nadeau
#### Code source 
76 1 Patrice Nadeau
77
Le code source doit toujours être mis en évidence avec un outil de «syntax highlight»
78
79 53 Patrice Nadeau
* Redmine : Les langages supportés sont ceux de [CodeRay](http://coderay.rubychan.de/)
80 1 Patrice Nadeau
81 53 Patrice Nadeau
    <code>
82 34 Patrice Nadeau
83 53 Patrice Nadeau
        ```c
84
        code to display
85
        ```
86 1 Patrice Nadeau
87 53 Patrice Nadeau
    </code>
88
89 1 Patrice Nadeau
* XeTeX : Le module _lstlisting_ est utilisé. Des titres et emphases peuvent être utilisées.
90
91 53 Patrice Nadeau
    ```
92
    \begin{lstlisting}[language=xxx, title=yyy, emph=serveur]
93
        ssh serveur
94
    \end{lstlisting}
95
    ```
96 1 Patrice Nadeau
97
#### Guillemets
98 18 Patrice Nadeau
99 1 Patrice Nadeau
Les [guillemets](http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks#French) (« & ») DOIVENT être utilisés dans les document français.
100 30 Patrice Nadeau
> Il DOIT y avoir un espace entre les guillemets et le mot.
101 1 Patrice Nadeau
102 34 Patrice Nadeau
Ils sont faits de cette façon :
103 1 Patrice Nadeau
104 34 Patrice Nadeau
* Redmine : Unicode U+00AB (171), U+00BB (187)
105
    > 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).
106 1 Patrice Nadeau
107 34 Patrice Nadeau
* XeTeX :
108 1 Patrice Nadeau
Ils DOIVENT être faits avec **\enquote{}**
109 18 Patrice Nadeau
110 1 Patrice Nadeau
#### Police
111
112
La police de caractère et son poids sont générés par Redmine et XeTeX.
113 18 Patrice Nadeau
114 1 Patrice Nadeau
### Images
115
116
Les images DOIVENT être de format PNG
117 39 Patrice Nadeau
118 1 Patrice Nadeau
* XeTeX : Elles DOIVENT être enregistrées dans le même dossier que le fichier _.tex_.
119 18 Patrice Nadeau
120 1 Patrice Nadeau
## Documents
121
122
Conventions utilisées dans les documents.
123 18 Patrice Nadeau
124 1 Patrice Nadeau
## Découpage du document
125
126 31 Patrice Nadeau
Sections minimum pour différents type de documents :
127 1 Patrice Nadeau
128 31 Patrice Nadeau
* Documentation de logiciel (guides) :
129
    * Introduction.
130
    * Installation.
131
    * Configuration.
132
    * Utilisation.
133
    * Problèmes connus.
134 1 Patrice Nadeau
    * Todo (XeTeX).
135
136 18 Patrice Nadeau
### Style
137 31 Patrice Nadeau
138
Le document est séparés au moyen de :
139 1 Patrice Nadeau
140
* XeTeX : *section*, *subsection* et *subsubsection* (*\section{}* DOIT être précédée de *\newpage*)
141 58 Patrice Nadeau
* Markdown : *h2* @ *h3* (suivie d'une ligne vide)
142 1 Patrice Nadeau
143
La table des matières seras faites automatiquement avec ces items.
144
145 18 Patrice Nadeau
Chaque section DOIT commencer par une brève description.
146 1 Patrice Nadeau
147
### Listes
148
149
Les listes sont faites avec : 
150
151 31 Patrice Nadeau
* Redmine :
152
    * *<notextile>*</notextile>* : pour des items ayant une description.
153 1 Patrice Nadeau
    * *<notextile>#</notextile>* : pour des « étapes ».
154 31 Patrice Nadeau
* XeTeX :
155 35 Patrice Nadeau
    * \begin{xxx} ... \end{xxx}, xxx représentant:
156
        * **description** : pour des items ayant une description.
157
        * **enumerate** : pour des «étapes».
158 1 Patrice Nadeau
        * **itemize** : le type le plus fréquent.
159
160
### Hyperliens
161
162 31 Patrice Nadeau
L’utilisation des hyperliens ce fait avec :
163 1 Patrice Nadeau
164 35 Patrice Nadeau
* Textile : (voir http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting)
165 31 Patrice Nadeau
    * _Documents_ : **document\#nb**
166 35 Patrice Nadeau
    * _Files_ : *<notextile>"titre":/attachments/do </notextile>*
167 31 Patrice Nadeau
* XeTeX : **\label{}**, **\ref{}**, **\pageref{}** 
168 35 Patrice Nadeau
    * Les étiquettes sont faites selon cette convention (_xxx_:étiquette), _xxx_ étant un des choix :
169
        * **chap:** : chapitre
170
        * **sec:** : section
171
        * **subsec:** : sous-section
172
        * **fig:** : figure
173
        * **tab:** : table
174
        * **eq:** : équation
175
        * **lst:** : code
176
        * **itm:** : liste énumérée
177 1 Patrice Nadeau
        * **app:** : sous-section d’appendice
178
179
### Items à faire
180
181 31 Patrice Nadeau
Les notes pour les items à faire plus tard DOIVENT être décrites comme suit :
182 40 Patrice Nadeau
183
* Redmine : Un lien sur un « issue »
184 1 Patrice Nadeau
* XeTex (**todonotes** est utilisé)
185 35 Patrice Nadeau
186
        \todo[inline]{Texte de ce qu'il y a à faire}
187
188
        \todo\missingfigure{Texte de l'image manquante}
189
190
191
    > Une section DOIT aussi êtres ajoutée avant la toute fin du document :
192
193
        \newpage
194
        \section{Todo}
195 1 Patrice Nadeau
        \listoftodos[]
196
197
### Paragraphes spéciaux
198 32 Patrice Nadeau
199
Les items nécessitant une attention particulière de la part du lecteur, sont identifiés avec :
200
201
* Redmine : un retrait fait avec **>** :
202
203
        item
204
        > Texte
205 1 Patrice Nadeau
206
* XeTeX
207 32 Patrice Nadeau
208
        \paragraph{item :}
209
        Texte
210
211 1 Patrice Nadeau
212 32 Patrice Nadeau
_item_ étant une des valeurs :
213 18 Patrice Nadeau
214 7 Patrice Nadeau
* *Note* : explications non critiques sur un point
215 18 Patrice Nadeau
* *Avertissement* : un point qui mérite une grande attention
216 8 Patrice Nadeau
* *Ex.* : un exemple
217
218 26 Patrice Nadeau
## Standards
219 8 Patrice Nadeau
220
### Tableau
221
222 25 Patrice Nadeau
Un tableau est fait de la manière suivante :
223
224
* La tableau et les cellules DOIVENT avoir une bordure
225 8 Patrice Nadeau
* Les données DOIVENT être en ordre (alphabétique ou numérique, selon le cas)
226 18 Patrice Nadeau
* La première ligne DOIT 
227 1 Patrice Nadeau
    * contenir le nom des colonnes
228 9 Patrice Nadeau
    * être centrées 
229 1 Patrice Nadeau
    * en caractères gras
230
231
### Couleurs
232 36 Patrice Nadeau
233 1 Patrice Nadeau
Abréviations selon [IEC 60757](https://webstore.iec.ch/publication/3406)
234
235
* *BK* : Noir
236
* *BU* : Bleu
237 16 Patrice Nadeau
* *BN* : Brun
238 27 Patrice Nadeau
* *RD* : Rouge
239
* *YE* : Jaune
240
* *VT* : Violet
241 1 Patrice Nadeau
* *GR* : Gris
242 18 Patrice Nadeau
* *WH* : Blanc
243 1 Patrice Nadeau
* *CL* : Transparent 
244
245
    > Ne fait pas partie du standard
246 28 Patrice Nadeau
247
### Dates et heures
248 1 Patrice Nadeau
249
L’heure des documents généraux est inscrite en format français (xx h yy.)
250
251 18 Patrice Nadeau
Les documents technique eux sont inscrits dans le format [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) :
252 1 Patrice Nadeau
253
* Date : 2014-08-24
254
* Heure : 13:28
255
256
### Notation
257 37 Patrice Nadeau
258 1 Patrice Nadeau
Règles d’affichage des nombres et des unités.
259
260 36 Patrice Nadeau
Les règles suivantes DOIVENT être utilisées :
261 1 Patrice Nadeau
262
* le séparateur décimal DOIT être un point,
263
* le séparateur pour les milliers DOIT être un (demi-)espace,
264 29 Patrice Nadeau
* le nombre est suivit d’un (demi-)espace et du préfixe et de l’unité de mesure 
265
266
Sous _XeTex_, l’utilisation de _siunitx_ EST requise.
267 1 Patrice Nadeau
Ex. : 
268 18 Patrice Nadeau
> Pour avoir 10 000.01 μA :
269 1 Patrice Nadeau
270
    \SI{10000.01}{\micro\A}
271
272
### Symboles
273
274
Les symboles sont fait de la façon suivantes : 
275 48 Patrice Nadeau
276
**Symbole** | **Signification** | **HTML** | **XeTex**
277
----------- | ----------------- | -------- | ---------
278
&#8776; | Approximativement | `&asymp;` |`\approx`
279
&plusmn; | Plus ou moins (tolérance) | `&plusmn;` 
280
&gt; | Plus grand | `&gt;`
281
&ge; | Plus grand ou égale | `&ge;`
282
&lt; | Plus petit | `&lt;`
283
&le; | Plus petit ou égale | `&le;`
284
o | octet (unité) | | o | \octet
285
&Omega; | Ohm (unité) | `&Omega;` | \si{\ohm}
286 4 Patrice Nadeau
&micro; | micro (préfixe) | `&micro;` | \si{\micro}
287 1 Patrice Nadeau
288
### Unité de mesure
289 15 Patrice Nadeau
290 38 Patrice Nadeau
Les unités de mesure à utiliser :
291 15 Patrice Nadeau
> [Le _byte_ n'est pas une unité officielle](http://en.wikipedia.org/wiki/Octet_%28computing%29).
292 49 Patrice Nadeau
293
Mesure | Unité | Symbole
294
------ | ----- | -------
295
Longueur | mètre | m
296
Masse | kilogramme | kg
297
Courant électrique | ampère | A
298
Donnés | bit | bit
299
Donnés | octet | o
300
Résistance | ohm | &#937;
301
Capacitance | farad | F
302
Voltage | volt | V
303
Fréquence | hertz | Hz
304 1 Patrice Nadeau
Puissance | watt | W
305
306 24 Patrice Nadeau
### Préfixes
307
308
#### Base 10
309 50 Patrice Nadeau
310
Symbole | Notation | Représentation
311 51 Patrice Nadeau
------- | -------- | --------------
312
tera | T | 10^12 | 1 000 000 000 000
313
giga | G | 10^9 | 1 000 000 000
314
mega | M | 10^6 | 1 000 000
315
kilo | k | 10^3 | 1 000
316
deci | d | 10^1 | 0.1
317
milli | m | 10^-3 | 0.001
318
micro | &micro; | 10^-6  | 0.000 001
319
nano | n | 10^-9 | 0.000 000 001
320 5 Patrice Nadeau
pico | p| 10^-12 | 0.000 000 000 001
321 1 Patrice Nadeau
322
323
#### Base 2
324
325
Pour les données informatiques (1024).
326 50 Patrice Nadeau
327
Préfixe | Symbole | Représentation
328
------- | ------- | --------------
329
tebi | Ti | 1 099 511 627 776 octets
330
gibi | Gi | 1 073 741 824 octets
331
mebi | Mi | 1 048 576 octets
332 1 Patrice Nadeau
kibi | Ki | 1024 octets
333
334 33 Patrice Nadeau
## Référence
335 1 Patrice Nadeau
336 33 Patrice Nadeau
[How To Read Command Syntax](http://pcsupport.about.com/od/commandlinereference/a/command-syntax.htm)
337 1 Patrice Nadeau
338 33 Patrice Nadeau
[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)
339 1 Patrice Nadeau
340 33 Patrice Nadeau
[Office québécois de la langue française](http://www.oqlf.gouv.qc.ca/)
341 1 Patrice Nadeau
342 33 Patrice Nadeau
[8e édition de la brochure du Système international d’unités](http://www.bipm.org/utils/common/pdf/si_brochure_8_fr.pdf)
343 1 Patrice Nadeau
344 33 Patrice Nadeau
[Date et heures en français](http://servicesdedition.com/fr/langue/chroniques/coordonnees.html)
345 1 Patrice Nadeau
346 33 Patrice Nadeau
[IEC_80000-13](http://en.wikipedia.org/wiki/IEC_80000-13)
347 1 Patrice Nadeau
348
[IEEE 1541-2002](http://en.wikipedia.org/wiki/IEEE_1541-2002)