styles & conventions

Ce qui suit détaille le style d’écriture et les conventions de documentation utilisés dans ce manuel.

🔗Format

Ce site Web est créé en pure markdown, en utilisant certaines extensions. Il est initialement conçu pour fonctionner avec Hugo SSG, mais il est suffisamment portable pour pouvoir être facilement rendu avec une autre application si nécessaire.

Les fichiers doivent être rendu en UTF-8 et ne doivent pas inclure de retour à la ligne automatique.

🔗Structure

Ce qui suit montre la structure d’un exemple de chapitre principal avec des sous-sections sur le site Web dtdocs.

example-chapter/
   _index.md
   section1-with-subsections/
      subsection1/
         image.png
      _index.md
      subsection1.md
      subsection2.md
   section2.md
   section3.md

Quelques remarques sur la structure ci-dessus :

  • Les fichiers _index.md ne contiennent aucun contenu (ils contiennent uniquement des métadonnées) et sont utilisés pour rendre les en-têtes de section et les entrées de la table des matières. Dans l’exemple ci-dessus, example-chapter/_index.md définit le titre de l’exemple de chapitre et l’ordre dans lequel il apparaît dans la table des matières principale. De même, example-chapter/section1-with-subsections/_index.md définit les métadonnées pour la première section du chapitre.

  • Les fichiers multimédias doivent être contenus dans un répertoire portant le même nom que la page à laquelle ils se rapportent. Dans cet exemple, example-chapter/section1-with-subsections/subsection1 contient un média lié à la page subsection1.md.

🔗Métadonnées

Les métadonnées des fichiers markdown sont présentées en tête de page à l’aide de yaml. Toutes les métadonnées peuvent être définies - les sections de référence du module contiennent beaucoup de métadonnées spécifiques - cependant ce qui suit définit quelques métadonnées minimales pour la page d’exemple example-chapter/section1-with-subsections/subsection1.md.

---
title: Titre Sous-Section 1
id: subsection1
weight: 10
include_toc: true
---
title
Cela doit contenir le titre rendu de votre page. Pour inclure un deux-points dans un titre, placez le titre entre guillemets.
id
C’est l’identifiant utilisé pour identifier la page par Hugo. Il doit généralement avoir le même nom que le fichier (pour les fichiers de contenu) ou le répertoire parent (pour les fichiers _index.md).
weight
Il s’agit d’un champ de métadonnées facultatif utilisé pour définir l’ordre dans lequel les sections sont présentées dans la table des matières. Si le champ weight n’est pas inclus, les pages seront rendues dans l’ordre alphabétique par défaut. Par exemple, pour définir les sections et sous-sections de l’exemple ci-dessus dans l’ordre inverse, les métadonnées suivantes doivent être définies :
   example-chapter/
      section1-with-subsections/
         _index.md               # weight : 30 (place la page section1 à la fin de example-chapter)
         subsection1.md             # weight : 20 (place la  page subsection1 à la fin de la section1)
         subsection2.md             # weight : 10 (place la page subsection2 à la fin de la section1)
      section2.md                # weight : 20 (place la section2 au milieu de example-chapter)
      section3.md                # weight : 10 (place la section3 au début de example-chapter)
include_toc
Facultatif ; active ou désactive la table des matières repliable. À n’utiliser que sur des pages volumineuses et complexes.

🔗Contenu

🔗Conseils généraux de style

  • Tout le contenu doit être rédigé en Markdown simple sans codes courts et le HTML doit être réduit au strict minimum, s’il est utilisé

  • Le minimalisme est un must absolu. Le moins de mots possible est préféré

  • Les fichiers Markdown doivent être aussi courts que possible

  • Suivez les normes de dénomination et de capitalisation présentes dans l’interface graphique de l’application – à savoir que tous les en-têtes et titres sont en minuscules, à l’exception des noms de chapitre de très haut niveau. De même, utilisez uniquement des minuscules lorsque vous faites référence aux noms de module et aux contrôles.

  • Les en-têtes dans un fichier ne doivent pas dépasser le niveau trois (###)

  • La langue de rédaction principale est l’anglais. Évitez le langage idiomatique dans la mesure du possible car la version anglaise de la documentation peut être lue par des personnes dont l’anglais n’est pas la langue maternelle

  • Supposez que le lecteur a ouvert l’application lors de la lecture du manuel d’utilisation et n’incluez que des images où elles contribuent à l’explication de fonctionnalités complexes

  • Utilisez des références si vous avez besoin d’annoter une image (c.-à-d. Marquez des parties de l’image avec une lettre ou un chiffre, puis expliquez la signification dans un texte suivant l’image). Ne placez pas de mots directement dans l’image pour les annotations, car cela rend la localisation difficile. Voir cette page pour un exemple.

  • Les modifications du contenu doivent être proposées via une pull request ou un mécanisme similaire

  • Vos soumissions seront modifiées – ne le prenez pas mal

🔗informations techniques pour le traitement des modules

Pour chaque module de traitement, un bloc spécifique (repliable) contenant des informations techniques figure en haut de la page :

{{< details summary="Informations techniques" class="technical-info" >}}

Description
: applique une courbe de tone mapping. Inspiré du tone mapper AgX de Blender.

Objectif
: correctif et créatif.

Entrée
: linéaire, RVB, relatif à la scène.

Traitement
: non linéaire, RVB.

Sortie
: linéaire, RVB, relatif à l'affichage

{{< /details >}}

Ces informations devraient correspondre à celles qui s’affichent sous forme d’info-bulle lorsque l’on passe la souris sur un module de traitement..

🔗Raccourcis clavier et souris

  • Référencez les touches du clavier nommées à l’aide de CamelCase (Ctrl, Maj, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)

  • Reference single letter keys in upper case. Quotation marks might help with clarification (press “H” to see a list of active shortcuts)

  • Référencez les actions de la souris en minuscules, avec plusieurs mots reliés par un trait d’union (défilement, clic, clic-simple, double-clic, clic-droit)

  • Connect combinations of keys/actions with a plus sign (Ctrl+Shift+H, Shift+double-click)

🔗Listes de définitions

The standard method of presenting information about darktable module controls is with the use of definition lists.

Nom d’un contrôle de l’interface graphique
Une déclaration de ce que fait le contrôle. Par exemple “Réglez l’exposition en unités IL”

Vous pouvez inclure autant de paragraphes que vous le souhaitez, mais essayez de limiter leur nombre à 2 ou 3 si possible.

active-icon a control accessed through a button with an icon
When a control is activated using an icon, take a screenshot of the icon using the standard darktable theme (darktable-elegant-grey) and add it before the name of the control
Nom de la zone de liste déroulante de l’interface
Les zones de liste déroulante ont souvent plusieurs options qui doivent toutes être affichées avec des définitions séparées. Utilisez des listes à puces avec italiques pour les valeurs de la zone de liste déroulante.
  • la première valeur : ce que signifie la première valeur
  • la seconde valeur : ce que signifie la seconde valeur

Definition lists are also used throughout the document, wherever a named piece of functionality needs to be defined. See, for example, darktable-cli.

🔗Remarques

Si vous souhaitez présenter une remarque importante à l’utilisateur, utilisez le format suivant :

Remarque : Ceci est une remarque importante.

🔗Polices à largeur fixe et blocs de code

Les polices à largeur fixe (utilisant le caractère `) ne doivent normalement être utilisées que pour les blocs de code et lors du référencement des noms de fichiers et des paramètres de la ligne de commande.

🔗Liens

Les liens internes doivent être relatifs au fichier actuel et doivent pointer vers un fichier markdown (.md) valide. Commencez les liens avec soit ./ Pour représenter le répertoire courant ou ../ pour représenter le répertoire parent.

🔗Images

Lorsque vous prenez des captures d’écran de l’application darktable elle-même, utilisez le thème darktable-elegant-grey.

Plusieurs suffixes de nom de fichier peuvent être utilisés pour contrôler la façon dont une image est rendue.

icon
To insert an image as an icon, include #icon after the image name in the link. The markdown ![squirrel icon](./styles-conventions/contributing.png#icon) outputs the following: squirrel icon
image width
You can set the image width to 25, 33, 50, 66, 75 or 100 per cent of the rendered page width by including #wxx after the image name in the link, where xx is the desired width. For example:
![squirrel](./styles-conventions/squirrel.png#w25) outputs
squirrel
![squirrel](./styles-conventions/squirrel.png#w75) outputs
squirrel
inline
With the exception of icons, images are included as block elements by default. You can override this by including #inline after the image name. This can be combined with the width setting as follows.
![squirrel](./styles-conventions/squirrel.png#w25#inline) outputs squirrel
default
By default images are presented as block elements with 100% width. So ![squirrel](./styles-conventions/squirrel.png#w100) and ![squirrel](./styles-conventions/squirrel.png) are equivalent and both output the following:
squirrel

translations