-
Notifications
You must be signed in to change notification settings - Fork 42
Conventions
À discuter dans ce fil.
- Code
- Titres
- Typographie
- Noms de logiciels
- Mots étrangers
- Packages R
- Fonctions R
- Objets, variables, arguments
- Valeurs manquantes
- Encadrés
- Figures
- Concepts
Pour tout ce qui concerne le style du code R, on peut se fixer comme objectif de suivre le guide de Hadley Wickham : http://adv-r.had.co.nz/Style.html
A l'intérieur d'un chapitre, on utilisera des titres de niveau 2 ou inférieur,
le niveau h1 étant réservé pour le titre de chapitre.
Ne pas inclure de numérotation, et n'utiliser que du texte simple (pas de markup pour les fonctions, packages, etc.), pour ne pas interférer avec la table des matières.
La fonction 'smart punctuation' est limitée pour le français : il importera donc d'insérer en caractères UTF-8 les guillemets français ainsi que les espaces insécables avant les ponctuations.
Le nom sera indiqué en gras.
Exemple :
**Word** a planté
Le mot sera indiqué en italique.
Exemple :
un mot en _English_
Le nom sera indiqué en code avec une classe "pkg".
Exemples :
`questionr`{.pkg}
Le nom sera indiqué dans une balise <code> ou l'équivalent Markdown (backticks).
Le package dont est issu cette fonction sera précisé dans un attribut "data-pkg". Exemples :
`freq`{data-pkg="questionr"}
Un lien vers la page de documentation sur rdocumentation.org sera généré automatiquement, dans le cas présent vers http://www.rdocumentation.org/packages/questionr/functions/freq
Le cas échéant (pour une méthode par exemple ou si plusieurs fonctions sont dcoumentées sur une même page),
on précisera dans un attribut "data-rdoc" le nom utilisé sur http://www.rdocumentation.org
(après /functions/ dans l'URL de la page de doc).
Ainsi pour la méthode kde des objets prevR, documentée sur http://www.rdocumentation.org/packages/prevR/functions/kde-prevR-method on fera :
méthode `kde`{data-pkg="prevR" data-rdoc="kde-prevR-method"}
Pour la fonction tail de l'extension utils qui est documentée sur la même page que head :
la fonction `tail`{data-pkg="utils" data-rdoc="head"}
Balise <code> ou équivalent Markdown (backticks).
<var>nom</var> pour les noms de variables (colonnes d'un tableau)
Exemples :
l'argument `showWarnings` permet de ...
l'objet `hdv2003` contient ...
la variable <var>diplome</var> mesure...
`NA`
Une saisie clavier sera mentionnée avec <kbd> :
Appuyez sur <kbd>CTRL</kbd> et <kbd>Enter</kbd>
Le titre d'un ouvrage / document avec <cite> :
Voir <cite>Introduction à R</cite> de Julien
Une courte citation dans le texte avec <q>.
Une longue citation avec <blockquote> ou les chevrons markdown. On précisera la source dans <footer> :
> L'âge est une des caractéristiques fondamentales de la structure des populations.
> On l'exprime généralement en années, ou en années et mois, voire en mois et jours.
>
> <footer>Source : [<cite>Demopædia</cite> (322)](http://fr-ii.demopaedia.org/wiki/32#322)</footer>
Les encadrés sont précisés avec une balise <div> et la classe CSS appropriée. Les différentes classes disponibles sont :
- note (bleu)
- important (rouge)
Elles doivent être présentées au sein de balises <figure>.
Le titre de la figure est précisé avec une balise <figcaption> situé sous la figure.
La numérotation est automatique.
Sont indiqués avec <dfn> ... </dfn>. Permettent de produire un index des concepts.
On peut contrôler l'entrée d'index avec
<dfn data-index="package">packages</dfn>
Pour saisir une entrée secondaire, on utilisera un vide
<dfn data-index="entrée secondaire"></dfn>
On utilisera <dfn lang="en">... </dfn> pour spécifier une entrée en anglais.