contribuer à dtdocs

Cette page définit le guide de style pour dtdocs et donne des informations sur la manière de contribuer au projet.

La page est incluse dans le manuel de l’utilisateur afin que vous puissiez voir comment elle est écrite et rendue. Veuillez aller sur GitHub pour voir la source de cette page.

The manual structure and content have been carefully considered based on the following critera:

  1. The manual should be comprehensive – it should describe all of the functionality available in darktable
  2. It should have a consistent and logical structure and every piece of functionality should have its own logical place within that structure
  3. It should be as long as necessary but as short as possible – brevity is a must
  4. It should be objective
  5. Functionality should be explained once and only once (with the exception of the basic workflow guidelines in the overview section)
  6. Images should be included only where necessary to improve understanding of key principles and should not contain text unless it is unavoidable

We are generally not interested in:

  1. Restructuring the manual
  2. Switching markup languages
  3. Detailed workflow tutorials (though we are interested in publishing those on the blogs of either darktable.org or pixls.us)

We are interested in

  1. Spelling and grammar corrections
  2. Clarification of text
  3. Documentation for new features

We are always extremely interested in hearing about which sections of the manual did not make sense to you and why, so that we can improve the documentation.

In general, if you wish to make a major change, please open an issue and discuss it with the maintainers first. This is to avoid doing work that wouldn’t be accepted.

🔗format

This website is authored in pure markdown, using some extensions. It is initially designed to work with the Hugo SSG but intended to be portable enough that it can be easily rendered with another application if required.

Files should be rendered in UTF-8 and should not include any column wrapping.

🔗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 notes 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: Sub Section 1 Title
id: subsection1
weight: 10
---
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)

🔗contenu

🔗conseils généraux de style

  • Tout le contenu doit être rédigé en clair sans code abrégé et le HTML doit être réduit au minimum absolu, 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

  • Follow the naming and capitalization norms present in the GUI of the application – namely all headers and titles are in lower case, except for the very top-level chapter names

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

  • La langue de création principale est l’anglais

  • 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

  • Your submissions will be copy-edited – don’t take it personally

🔗listes de définitions

La méthode standard de présentation des informations concernant les contrôles des modules de 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 EV”

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

active-icon 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 et ajoutez-le avant le nom du contrôle
nom de la zone de liste déroulante de l’interface
Les 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.

🔗images

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

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](./contributing/contributing.png#icon) affiche ce qui suit : squirrel icon
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](./contributing/squirrel.png#w25) affiche
squirrel
![squirrel](./contributing/squirrel.png#w75) affiche
squirrel
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](./contributing/squirrel.png#w25#inline) affiche squirrel
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](./contribution/squirrel.png#w100) et ![squirrel](./contribution/squirrel.png) sont équivalents et les deux produisent ce qui suit :
squirrel

Translations