From BlenderWiki

Jump to: navigation, search

Pages concernant l’édition du wiki :

Guide d’écriture | Guide de style | Templates | Guide de traduction | Tâches de traduction (guide)

Avertissement
Bien que je fasse mon possible pour maintenir cette traduction à jour, la version de référence reste celle en anglais. Il se peut que certains des conseils/règles donné(e)s ci-dessous ne soient plus d’actualité – en dernier recours, référez-vous toujours à la version anglaise (sauf éventuellement en ce qui concerne une partie de la page sur l’internationalisation).

Pour maintenir l’uniformité de l’ensemble de la documentation de Blender, les auteurs sont priés de se conformer au présent guide de style.

Les personnes totalement étrangères à la syntaxe de MediaWiki sont priées de se référer à la documentation officielle de MediaWiki.

Règles générales

La documentation de Blender doit être écrite dans un anglais (et pour la traduction, un français) correct, clair, concis et explicite. Elle doit être découpée en chapitres, sections, et sous-sections.

La subdivision logique de la documentation est dictée par le Documentation Board. Aucune page ne peut y être ajoutée sans avoir été approuvée au préalable.

La subdivision logique des tutoriels des contributeurs est laissée à leur propre appréciation.

Les tutoriels devraient contenir une introduction (un résumé) de 300 mots maximum, en décrivant brièvement le sujet, les objectifs et le contenu, afin de faciliter la navigation.

Chaque page devrait avoir un template approprié comme première ligne, pour montrer les aides à la navigation, et pour indiquer à quelle version de Blender la page correspond. Ceci est fait par l’intermédiaire de :

{{Page/Header|2.4|pageprécédente|pagesuivante}}

(où, bien évidemment, “2.49” est le numéro de la version correspondante).

Cela donne :

Notez que le templatePage/Header” a des options supplémentaires quand il est utilisé dans des pages de traduction, comme décrit à la page sur l’internationalisation.

En outre, pour de longues pages présentant plusieurs sections – dont certaines sont relatives à une version différente de Blender – un template différent est disponible :

{{version|2.32}}

Il devrait être placé juste après le titre de section ou de sous-section, comme montré dans la section ci-dessous.

En bas de chaque page, il devrait y avoir un pied de page comportant une aide à la navigation :

{{Page/Footer|pageprécédente|pagesuivante}}

Ce qui donne :




La pageprécédente et la pagesuivante doivent bien évidemment être des liens valides !

“Templates”

Blender 2.32+

L’équipe de documentation a créé une série limitée de templates (“patrons”), comme des boîtes de note, les Touches de clavier, et d’autres encore. Vous êtes prié de n’utiliser que ces seuls templates.

La liste des templates disponibles est ici (en).

Insistons simplement sur le template <code>{{Literal|}}</code>, qui devrait être utilisé pour “envelopper” toutes les références aux éléments de l’interface (noms des contrôles, entrées des menus, …).

Documentation de référence

Quand vous écrivez de la documentation de référence (que ce soit dans le manuel ou les références…), utilisez le template RefBox, et la structure de sous-en-tête associée. Cela aide à garder le manuel cohérent, avec des informations communes placées à un endroit bien défini et facilement identifiable, afin que les gens puissent rapidement parcourir le texte jusqu’à l’information qu’ils cherchent. Voyez le guide de la “Reference Box” (en) pour plus d’informations sur cette structure. Voici un exemple de ReferenceBox :

Mode: Mode Edit (mesh)

Raccourci clavier: CtrlR

Menu: MeshEdgesLoop Subdivide...

Vous gagnerez, vous et vos lecteurs, du temps si vous utilisez ce template autant que faire ce peut. Cela vous évite d’avoir à expliquer en longueur des choses du genre “pour utiliser cet outil, vous pouvez presser la touche X de votre clavier”, puisqu’il y a une jolie image de raccourci clavier dans la refbox, à un endroit cohérent où les lecteurs savent pouvoir le trouver rapidement. Le manuel n’est pas un roman – garder votre texte concis et collez au sujet !

Typographie

Voici quelques règles de base de la typographie française. Notez que je ne suis pas un spécialiste, alors s’il y a des erreurs/corrections à apporter, n’hésitez pas… Un complet dictionnaire typographique, aux définitions rarement dénuées d'humour, est disponible en ligne.

  • Utilisez des majuscules accentuées (cela semble maintenant l’usage, à défaut d’être la règle) : “Éditer” et non “Editer”, “À faire” et non “A faire”, …
  • Utilisez les apostrophes et guillemets courbes de préférence aux droits (’ et pas ', “/”, «/» et pas "). Rappelons que les guillemets simples (‘ et ’, ou '), utilisés par les anglo-saxons, ne sont pas vraiment corrects en français… Toujours à propos des guillemets, les chevrons (« et ») sont plutôt utilisés pour les citations longues (au minimum pour une phrase complète), alors que les courbes (“ et ”) sont plutôt réservés pour les très courts passages (quelques mots).
  • Les points de suspension sont aussi un caractère à part entière (“…”), ne les insultez pas en alignant trois vulgaires points simples... heu, … je veux dire !
  • Ajoutez une espace (insécable, voyez le point suivant) entre les signes de ponctuation suivants, et le mot qui les précède : “!”, “?”, “:”, “;”, “«”, “»” (d’autres encore ?).
  • N’ajoutez pas d’espace (insécable ou normale) entre les guillemets courbes (“, ”) et le passage qu‍’ils enserrent, ni avant une virgule ou un point !
  • Pour obtenir une espace insécable (qui ne permet pas un retour à la ligne, par ex.), il existe un caractère unicode (facilement accessible au clavier sous GNU/Linux, notamment), mais qui semble malheureusement poser quelques problèmes. Utilisez donc de préférence l’entité xhtml “ ”.
  • Les tirets d’encart (terme exact ?), comme dans “cet exemple – qui n’est pas très intéressant – n’est qu’un exemple”, sont de longueur moyenne (“–”, ni “-” ni “—”), et utilisent le schéma suivant : “texte principal [espace normale] [tiret entrant] [espace insécable] texte d’encart [espace insécable] [tiret sortant] [espace normale] texte principal”.
  • (Autres règles pertinentes ?).


Recommandations sur les images

L’utilisation d’images dans la documentation est essentielle. Les formats PNG et JPG sont hautement préférés. L’utilisation du format GIF et d’autres formats non libres est fortement déconseillée. Utiliser des formats non compressés comme le TGA est également découragé.

Les images sont “uploadées” sur le wiki en utilisant le lien suivant : http://wiki.blender.org/index.php/Special:Upload .

Les images flottantes

Les images flottantes doivent avoir une légende et être référencées dans le texte. Essayez de ne pas vous y référer par des “l’image suivante” ou “la capture d’écran qui suit”. Utilisez des références croisées, décrites ici.

L’utilisation d’images non référencées est déconseillée. Si vous avez une image que vous ne savez pas comment référencer, soit l’image n’est pas nécessaire, soit votre texte n’est pas clair.

La documentation (à la fois la documentation principale et les tutoriels) doit être cohérente. Les dimensions devraient être, au maximum, de 800×600. L’utilisation d’images plus larges que 800 pixels est fortement déconseillée, puisqu’elles sont trop grandes pour être vues confortablement dans un navigateur web.

La fonction la plus notable de l’interface de Blender est qu’elle est rendue entièrement en OpenGl, et peut complètement changer d’échelle. Ceci peut causer des problèmes d’uniformité dans les illustrations, si différents utilisateurs font des captures d’écran (pour montrer différentes configurations comme des options de matériaux, de textures, etc.).

Pour permettre d’avoir des captures d’écran à la fois claires et homogènes avec le reste de la documentation, vous devriez changer les dimensions de l’interface pour que le curseur du rouge dans la fenêtre des matériaux fasse 18 pixels de haut. C’est ce que fait Blender si vous choisissez une résolution d’écran de 1024×768 dans la configuration d’écran de Blender par défaut, et si vous pressez la touche home (avec le curseur dans la fenêtre des boutons) pour avoir la taille des boutons par défaut.

Si vous utilisez une résolution plus élevée, veuillez revenir en 1024×768 pour vos captures d’écran. Espérons que personne n’a d’écran plus petit ! Une méthode pour prendre des copies d’écran avec une résolution de 1024×768, quand votre affichage est à une résolution supérieure, est de lancer Blender non en plein écran mais dans une fenêtre, grâce aux options suivantes dans la ligne de commande :

./blender -w -p 0 0 1024 768

Blender se lancera alors dans une fenêtre de 1024×768 pixels. Le contour de l’application sera plus grand à cause des ajouts du système de fenêtre (le cadre). Pour capturer la partie “Blender” de l’affichage, vous pouvez utiliser The Gimp avec une taille de sélection de région fixe (de 1024×768), et cela capturera automatiquement la “zone Blender”, sans le contour de la fenêtre créé par votre système de fenêtre.

Les copies d’écran doivent être dans un format non destructif, donc utilisez le PNG.

Si vous devez mettre en valeur une partie d’une image (un bouton, une valeur, ou un groupe de boutons/valeurs), veuillez l’entourer d’un cadre jaune (R=255, G=255, B=0) de 2 pixels d’épaisseur.

Utilisez le style (thème) d’interface par défaut de Blender.

Images en ligne

Les images en ligne montrant des icônes de Blender sont bienvenues et rendent les descriptions beaucoup plus claires. Puisque ces images sont standard, veuillez éviter de créer les vôtres et utilisez celles mises à disposition par l’équipe de documentation.

Les smileys et autres

Les smileys n’ont pas leur place dans la documentation officielle (ce qui ne veut pas dire que vous ne pouvez pas faire preuve d’humour !).

Les tableaux

Les tableaux sont un bon moyen d’afficher beaucoup de données dans un format clair et structuré. Ils peuvent être une bonne alternative aux captures d’écran, pour montrer différentes configurations.

Les tableaux, comment les images flottantes, doivent avoir une légende et doivent être référencés dans le texte.

Le code

Ce Wiki permet d’afficher du code Python/C/etc. de façon lisible.

Les bouts de code, comme les images flottantes, doivent avoir une légende et être référencés dans le texte.

Style de la documentation en pratique

Cette partie donne un exemple détaillé de ce que votre page wiki devrait être.

Exemples d’images

Voici comment insérer des images dans vos pages, une fois que vous les avez mises sur le serveur.

Images normales

C’est la méthode la plus facile pour mettre des images dans votre texte, et aussi la plus sûre car vous n’avez pas à vous soucier des images flottantes : [[Image:DemoImage1.png|none|frame|Image de démonstration 1.]]

…affiche l’image sur une nouvelle ligne, débarrassée de tout texte :

Image de démonstration 1.


Images flottantes

Image de test.

C’est un peu plus compliqué car vous devez tenir compte du fait que la présentation peut être différente en fonction de la résolution de l’affichage, la taille de la fenêtre et la taille de la police de caractères de l’utilisateur.

Pour obtenir une image flottante à la droite du texte, utilisez la syntaxe suivante : [[Image:Dummy.jpg|right|thumb|200px|Image de test.]]

Mettez ce code devant la première ligne d’un texte pour que l’image s’affiche à côté du paragraphe.

Pour ne plus avoir de texte jusqu’à la fin de l’image, taper le code suivant : {{clr}}

Images en ligne

Les images en ligne, comme DemoImage2.png, sont encore plus faciles à faire. Tapez simplement : [[Image:DemoImage2.png]]

Images dans un tableau

Quand vous avez une série de petites images qui ont un thème commun, vous pouvez les mettre dans un tableau, comme ceci :

{|
 |valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|Pas de “rampe d’ombrage”.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample05.png|thumb|200px|none|Rampe de couleur.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample06.png|thumb|200px|none|Rampes de couleur et spéculaire.]]
 |}
Pas de “rampe d’ombrage”.
Rampe de couleur.
Rampes de couleur et spéculaire.


Plus d’aide sur les images

Voyez cette page pour les informations complètes sur l’utilisation des images : Images et fichiers importés.

Les tableaux

Les tableaux peuvent être codés en HTML, ou bien plus proprement (et simplement !) avec la syntaxe Wiki :

{|border="1" cellpadding="2"
 |+Table de multiplication
 |-
 ! × !! 1 !! 2 !! 3
 |-
 ! 1
 | 1 || 2 || 3
 |-
 ! 2
 | 2 || 4 || 6
 |-
 ! 3
 | 3 || 6 || 9
 |-
 ! 4
 | 4 || 8 || 12
 |-
 ! 5
 | 5 || 10 || 15
 |}

Ce qui donne :

Table de multiplication
× 1 2 3
1 1 2 3
2 2 4 6
3 3 6 9
4 4 8 12
5 5 10 15

Pour faciliter le formatage, il y a un templateUM/prettytable” prédéfini :

{|{{Css/prettytable|50%}}
 |align=center| 1
 |align=center| 2
 |align=center| 3
 |-
 |align=center| 4
 |align=center| 5
 |align=center| 6
 |}

Ce qui donne :

1 2 3
4 5 6


Plus d’aide sur les tableaux

Voyez cette page pour les informations complètes sur l’utilisation des tableaux : Tableaux.

Code

Tous les exemples de code wiki ci-dessus ont été affichés en les encadrant par <code><nowiki></nowiki></code>.

En mettant un ou plusieurs espaces au début d’une ligne, la ligne s’affichera comme :

ceci

Une autre façon d’obtenir le même résultat (pour un gros morceau de code par exemple) est d’encadrer le code avec <pre></pre>.

De la même façon, si vous n’avez pas besoin d’afficher beaucoup de code, vous pouvez utiliser <code></code>, ce qui donne le résultat suivant : Ceci est un exemple de code

Références croisées

Les références croisées sont gérées par le wiki, alors que dans les documentations précédentes nous utilisions des “étiquettes” (“labels”) pour pointer vers un objet. Le wiki utilise le nom de l’objet ; donc chaque image/tableau/morceau de code doit avoir un nom unique.

Noms de fichier

Les noms de fichiers sont une affaire délicate, en ce qu’ils doivent être uniques pour toute la documentation, et suffisamment explicites, pour permettre des références croisées entre chapitres, etc.

Il vous est donc vivement recommandé de vous conformer au standard suivant :

  • Pour la documentation principale :
Doc:Manual/nom-suffisamment-explicite
Rappelons que pour la traduction, il faut utiliser le nom de la page anglaise, en ajoutant le code de langue entre l’espace de nom et le nom de la page :
Doc:FR/Manual/le-même_nom-que-la-page-anglaise
  • Pour les images de la documentation principale, le schéma de dénomination est similaire, mais malheureusement les “/” ne sont pas acceptés par le wiki – vous devez donc utiliser “-” au lieu de “/” :
Manual-nom-suffisamment-explicite.ext
(Rappelons que les images n’ont généralement pas besoin d’être “traduites” – ce qui signifie que le schéma “FR-Manual-xxx” sera très rarement rencontré/utilisé…).
L’auteur est responsable du nom qui est défini, qui doit être unique et servira d’étiquette à l’objet.


Voyez aussi

D’autres “tags” pour Blender (en).