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)
Référence de touche correspondant à une seule lettre en majuscules. Les guillemets peuvent aider à clarifier (appuyez sur « H » pour voir une liste de raccourcis actifs)
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)
Connectez les combinaisons de touches/actions avec un signe plus (Ctrl+Maj+H, Maj+double-clic)

🔗Listes de définitions

La méthode standard de présentation des informations sur les contrôles des modules darktable consiste à utiliser des listes de définitions.

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.

Un contrôle accessible via un bouton avec une icône

Lorsqu’un contrôle est activé à l’aide d’une icône, prenez une capture d’écran de l’icône en utilisant le thème standard de darktable (darktable-elegant-grey) et ajoutez-le avant le nom du contrôle

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

Les listes de définitions sont également utilisées dans tout le document, partout où une fonctionnalité nommée doit être définie. Voir, par exemple, 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.

Les liens vers un module de traitement doivent être en italique, par ex. Exposition
Les liens vers un module utilitaire doivent être en texte brut, par exemple Historique
Lien vers une section de niveau supérieur en référençant le fichier _index.md, par ex. Référence des modules
Lien vers un onglet dans la boîte de dialogue des préférences : Préférences > Général
Lien vers un paramètre spécifique des préférences : Préférences > Général > Langue de l’interface
Chaque en-tête d’une page peut être lié directement avec un lien d’ancrage : contribution/remarques

🔗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.

Icône: Pour insérer une image sous forme d’icône, incluez #icon après le nom de l’image dans le lien. Le markdown ![squirrel icon](./styles-conventions/contributing.png#icon) affiche ce qui suit : 
Largeur de l’image: Vous pouvez définir la largeur de l’image à 25, 33, 50, 66, 75 ou 100% de la largeur de la page rendue en incluant #wxx après le nom de l’image dans le lien, où xx est la largeur souhaitée. Par exemple :; ![squirrel](./styles-conventions/squirrel.png#w25) affiche : ; ![squirrel](./styles-conventions/squirrel.png#w75) affiche : 
En ligne: À l’exception des icônes, les images sont incluses en tant qu’éléments de bloc par défaut. Vous pouvez remplacer cela en incluant #inline après le nom de l’image. Cela peut être combiné avec le paramètre de largeur comme suit.; ![squirrel](./styles-conventions/squirrel.png#w25#inline) affiche 
Défaut: Par défaut, les images sont présentées sous forme d’éléments de bloc avec une largeur de 100%. Donc ![squirrel](./styles-conventions/squirrel.png#w100) et ![squirrel](./styles-conventions/squirrel.png) sont équivalents et les deux produisent ce qui suit : :