2. Information pour les auteurs et les traducteurs du manuel pour les utilisateurs de Mahara

par Kristina D.C. Hoeppner

Je fais cette liste au fur et à mesure que je travaille sur ce manuel. Elle se prête donc à évoluer. Il y a un certain nombre de points pour lesquels j’ai créé des conventions, des normes. Je désire qu’elles restent établies et utilisées dans les différentes traductions et autre documents créés autour de Mahara. Je souhaite les laisser dans un endroit central, accessible par toutes et tous, afin que chacune et chacun puisse s’y référer.

Les points de la liste ne font pas référence à un ordre particulier

2.1. Installer Sphinx

La rédaction du manuel d’utilisateur de Mahara nécessite Sphinx sur votre ordinateur. Vous pouvez accéder à des l’information sur l’installation de Sphinx directement sur le site officiel de Sphinx.

Les instructions suivantes sont basées sur une installation Unix Debian / Ubunbtu et nécessitent que vous utilisiez le terminal.

1. Installez l’environnement virtuel Python : sudo apt-get install python-virtualenv

2. Si vous désirez générer des PDF, vous devez installer toute la suite LaTeX : sudo apt-get install texlive-xetex texlive-lang-all texlive-fonts-extra

3. Créez un dossier sur votre ordinateur (si vous n’en n’avez pas déjà un) dans lequel vous placez le répertoire git. Nommez-le, par exemple code.

4. Dans le Terminal, allez dans le dossier « code » avec la commande cd code

5. Faites un « checkout » pour le code du manuel de l’utilisateur :

   • via SSH: git clone git@git.mahara.org:user-manual/manual.git OU

   • via HTTS: git clone https://git.mahara.org/user-manual/manual.git

6. Dans le Terminal, allez dans le dossier « manual » à l’aide de la commande : cd manual

7. Installez l’environnement de travail virtuel pour ce dossier : virtualenv venv

8. Activez l’environnement virtuel : . venv/bin/activate

9. Installez toutes les ressources nécessaires : pip install -r requirements.txt

10. Créez la version HTML du manuel : make html

    Note

    Ceci va créer le manuel dans toutes les langues pour lesquelles il existe une traduction, donc ceci peut prendre un peu de temps. Si vous ne désirez que la version anglaise du manuel, vous pouvez lancer la compilation avec la commande : make preview MAHARA=17.04

    Si vous désirez compiler une version PDF, vous utilisez la commande : make latexpdf

11. Ouvrez le fichier index.html dans un navigateur web pour afficher et lire le manuel. Vous trouvez ce fichier dans le dossier build/en/17.04.

12. Une fois que vous avez fini de modifier le manuel, vous pouvez désactiver l’environnement virtuel avec la commande deactivate dans le terminal.

2.2. Modifier le manuel de l’utilislateur

Une fois que vous avez installé le manuel de l’utilisateur sur votre ordinateur, vous pouvez effectuer les modification que vous désirez. Les actions suivantes sont effectuées directement dans le terminal.

1. Accédez au dossier où se trouve le manuel : cd code/manual

2. Lancez l’environnement virtuel afin de pouvoir compiler le manuel à l’aide de Sphinx : .venv/bin/activate.

3. Effectuez ensuite toutes les modifications que vous souhaitez dans l’éditeur de votre choix.

4. Compilez une préversion du manuel en langue anglaise : make preview MAHARA=17.04

   Note

   Modifiez le numéro de la version en fonction de celle que vous êtes en train de compiler.

5. Désactivez l’environnement virtuel une fois les modifications apportées : deactivate

2.3. Réaliser les captures d’écran

• sont placées dans le texte en utilisant la commande « figure ».

• toujours inclure un texte alternatif (alt) et une description de la figure. Ceci permet de placer ces figures hors du texte.

• sont généralement placées au-dessus de la liste à puces si elles font partie d’une instruction pas à pas.

• doivent faire référence à un minimum d’instructions, autant que possible, dans la démarche pas à pas. Il est même préférable qu’elles fassent référence qu’à un seul point, afin qu’elles puissent être échangées facilement contre un texte explicatif. Ce dernier pourra être traduit dans d’autres langues. Cela permettra donc aux traducteurs de traduire le texte, dans un premier temps, sans devoir éditer les copies d’écran immédiatement.

• utilises les patilles numérotées pré-fabriquée qui peuvent être trouvées dans le fichier Gimp /images_originals/z_callouts.xcf.

• ne placez une flèche que si un item doit être pointé et qu’il ne fait pas partie d’un pas du processus. L’image de la flèche peut être trouvée dans le fichier /images_originals/z_arrow.png.

• doivent contenir des numéros qui font référence aux points que l’on est en train de documenter en dessous de la figure.

• doivent ne montrer que le strict nécessaire, et non pas tout l’écran ou la barre d’adresse, etc. quand ce n’est pas indispensable.

La plupart des captures d’écran sont ajoutées à la documentation avec la directive figure.

Exemple d’inclusion d’une copie d’écran

1. La première ligne indique le chemin vers le fichier image.

   Note

   Le * remplace l’extension du fichier et Sphinx va alors choisir le format d’image le plus approprié. Donc une même copie d’écran peut avoir le même nom avec des extensions différentes afin que le programme puisse choisir le meilleur format en fonction de l’appareil sur lequel le manuel va être lu/imprimé.

   Dans le cadre du projet Mahara, c’est généralement le format .png qui est utilisé. Toutefois la bonne pratique est d’utiliser * au lieu de l’extension .png si un autre format venait à être utilisé dans le futur.

2. La deuxième ligne représente le texte alternatif (alt) qui est affiché lorsque la souris est placé au-dessus l’image, lorsque l’image ne peut pas être affichée, ou lorsque la page est lue à l’aide d’un appareil pour les personnes avec des difficultés visuelles.

3. La troisième ligne doit être placée après une ligne vide. Elle contient la description qui doit être affiché sous la copie d’écran. Lorsque un document PDF est créé à partir de la documentation sur le web, les descriptions seront numérotées de manière continue.

4. Si vous ne désirez pas afficher l’entier de l’écran sur une copie d’écran, mais seulement le haut et la partie du bas, vous pouvez utiliser le fichier /images_originals/z_omission.xcf et le placer dans votre fichier. Les courbes sinusoïdales indique la coupure. Elles ont été réalisées par le plugin Gimp Shape paths avec les paramètres suivants :

   • Sine Wave

   • Start X : 0

   • Start Y : 200 et dès la deuxième vague 215 pour assurer l’espace entre les lignes

   • Amplitude : 3

   • Wavelength : 25

   • Number of cycles : 40 (mais cela dépend avant tout de la largeur de l’image)

   • Activez «Stroke path»

   • Stroke color: CCCCCC

Note

Si vous désirez inclure une image dans le texte au lieu de la placer en dehors de celui-ci, vous devez créer un élément de substitution et le placer dans le fichier shortcuts.rstext. Il existe un grand nombre d’exemples de « shortcuts » dans le fichier afin de vous en inspirer.

2.4. Types d’alertes utilisées dans la documentation

note : pour tout ce qui doit retenir un peu plus l’attention des lecteurs

Note

Les notes peuvent être intégrées directement sous forme de listes à puces. Comme d’habitude, une ligne vide doit précéder et suivre la liste. La note doit être indentée par 3 espaces.

warning : pour tout ce qui doit être effectué et qui peut comporter un risque (par exemple : perte de donnée, impossibilité de revenir en arrière, …)

Warning

Essayez de ne pas mettre trop d’informations dans la note, car l’essentiel risque d’être alors noyé dans la masse.

seealso: pour renvoyer le lecteur vers d’autres parties du manuel ou de documents complémentaire qui devraient être consultés par le lecteur. Les références à ces autres documents peuvent aussi être inclues dans le texte lui-même.

See also

La ´documentation utilisateur de Sphinx <http://www.sphinx-doc.org>`_ est un bon endroit pour apprendre et comprendre plus en détail comment fonction rST avec Sphinx. Si vous avez des questions, vous pouvez aussi consulter le ´groupe de discussion Sphinx <https://groups.google.com/forum/#!forum/sphinx-dev>`_.

todo : pour tenir à jour un liste de tâches à effectuer. Les listes de tâches sont actuellement désactivées.

2.5. Conventions

• Chaque section qui est liée à un item du menu de navigation de Mahara doit faire figurer le chemin pour l’atteindre, par exemple Contenu → Fichiers. Il est préférable que vous copiiez la flèche depuis le texte original, afin de vous assurer que vous utilisez le bon caractère.

• Le nom des boutons, comme Enregistrer ou Copier la page, ainsi que celui des différentes sections du portfolio comme Contenu, Portfolio, etc. sont mis en évidence avec un simple * devant et derrière leur nom.

• Des petits boutons peuvent être inclus dans le texte, comme , . Ils sont ajoutés par substitution de leur code par leur image. Toutes ces images sont placées dans le fichier shortcuts.rstext qui est inclu à chaque fichier dans lequel des substitutions doivent être faites, en plaçant la commande « .. include:: /shortcuts.rstext »i dans la première ligne du fichier. Les substitutions sont créée par le code placé directement dans le texte, par exemple : « *Edit* button |edit| ». Les traducteurs ne doivent pas modifier le code de substitution « |edit|`» mais seulement traduire «*Edit* button » en prenant soin d’ajouter le * sans laisser d’espace entre le * et le texte, pour s’assurer que le mot sera affiché en gras.

• Une entrée d’index doit être créée pour chaque section

• Les nouvelles fonctionnalités sont aussi indexées avec la commande « single: Nouveauté dans Mahara x, [la fonctionnalité nouvelle] ». Les entrées d’index peuvent être placées soit au-dessus de l’ensemble de la section, soit dans le texte. Ce dernière manière de faire est à privilégier quand cela concerne des ajouts ou des modifications légères de fonctionnalités existantes; de cette façon, les lecteurs peuvent se rendre directement à l’explication de cette fonctionnalité. Ceci peut être réalisé de la manière suivante :

  :index:`Décider de l'ordre de tri <single: Nouveauté dans Mahara 15.04; Ordre de tri des fichiers dans le bloc « Dossier »>`

• Les longues sections, comme celles concernant l’administration, sont divisées en plusieurs pages; ce qui rend l’édition du contenu plus agréable.

• reStructuredText ne gère pas la hiérarchie dans le niveau d’en-têtes. Ces derniers dépendent des fichiers individuels. Toutefois, pour être cohérent, la convention suivante existe :

  • Titre 1, par ex. 1.: ===============

  • Titre 2, par ex. 1.1.: —————

  • Titre 3, par ex. 1.1.1.: ~~~~~~~~~~~~~~~

  • Titre 4, par ex. 1.1.1.1.: ^^^^^^^^^^^^^^^

• Une structure à plus de 4 niveaux doit être évitée.

• Les pages d’index n’ont pas d’en-tête en plus de l’en-tête principal. Cela permet d’éviter que la table des matières ainsi que les autres sections qui possèdes des en-têtes soient considérées comme les chapitres principaux du manuel. Gardez l’apparence des en-têtes de l’index en gras en utilisant **.

2.6. Formattage du texte

• Chaque item d’une liste à puce comment par le symbole *.

• Chaque élément d’une liste numérotée commence par #.

• Si vous désirez créer des listes à puces à plusieurs niveaux, laissez une ligne vide entre chaque niveau et placez 3 espaces devant chaque ligne. Il n’est pas nécessaire de laisser un ligne vide lorsque vous arrivez à la fin d’une sous-liste.

• La mise en évidence d’une partie d’un texte se fait en débutant et terminant celui-ci par 1 *, comme par exemple : *cela*. Ce qui vous donnerait quelque chose comme cela.

• La mise en gras d’un texte commence et se termine avec 2 *, comme **cela** ce qui donne cela.

2.7. Les hyperliens

• Liens externes: « `[texte du lien] <URL>`_ » - Les traducteurs du présent manuel ne doivent traduire QUE ce qu’il y a entre crochets soit le « [texte du lien] ».

• Les références internes pour lier un texte avec une autre partie de ce manuel s’effectuent en plaçant « .. [reference_text]: » dans une ligne juste avant en en-tête. Je laisse généralement une ligne vide entre la référence et l’en-tête.

• Liens vers des références internes : « :ref:`[texte du lien] <référence interne>` » - Les traducteurs du présent manuel ne doivent traduire QUE ce qu’il y a entre crochets soit le « [texte du lien] ».

• Le caractère ` est bien l’accent grâve et non une marque de citation simple ou une apostrophe.

• Une cible dans le texte peut être réalisée en place le texte à lier avec un accent grâve précédant un tiret de soulignement : _`une référence interne`. Le référencement est le suivant :ref:`[text that is linked] <the internal reference>`.

2.8. Traducteurs, prêtez attention

• Ne modifiez pas la cible des liens internes qui sont placés entre < >. Si vous le faites, les références ne seront plus trouvées. Il y a toujours un texte d’explication avant les < >, c’est ce texte que vous devez traduire.

• De manière similaire, vous pouvez modifier le texte d’un URL mais pas l’URL lui-même, à moins que vous ne le remplaciez pour pointer sur un texte écrit dans votre langue de traduction.

• Si vous traduisiez et adaptez les illustration dans votre langage, assurez-vous de conserver la structure du dossier « images » comme celle présente dans la branche git du manuel que vous êtes entrain d’éditer; par exemple pour Mahara 15.10.

• Vous pouvez accéder aux images originales du manuel dans le dossier « images_original » et dans les sous-dossiers correspondants. Vous pouvez les utiliser pour effectuer les traductions nécessaires si vous désirez modifier le fond en gardant la numérotation.

• Vous n’avez pas besoin de placer dans la traduction les images que vous ne souhaitez pas traduire, par exemple les icônes des blocs, les boutons généraux et les boutons d’édition. Toute image manquante dans les dossiers de traduction sera automatiquement remplacée par la version originale en anglais.

• Le manuel de l’utilisateur est mis à jour une fois par jour et les nouvelles traductions des chaînes de caractères sont envoyées depuis le système Launchpad dans la nouvelle version du manuel. Il en est de même des images sur le Git qui sont compilées avec la création journalière du manuel.

• A l’heure actuelle, toutes les chaînes de caractères ne peuvent pas être traduites dans Sphinx. Il est donc normal que certaines traces du manuel original en anglais apparaissent ici ou là. Avec un peu de chance, les versions ultérieures permettront de corriger cela.

Note

Si vous désirez mentionner les noms des traducteurs qui ont participé à la traduction du manuel de l’utilisateur de Mahara dans votre langue, vous pouvez le faire en ajoutant une phrase après « Le manuel de l’utilisateur de Mahara a été écrit par les membres de la communauté ». Ce paragraphe apparaît avant la table des matières. Il n’y a pas d’équivalent à ce phrase dans la version originale anglaise, car il ne s’agit pas d’une traduction.