2. Informations pour les auteurs et les traducteurs du manuel d’utilisation de Mahara

Il s’agit d’une liste en développement. Pour un grande nombre de choses dans Mahara, des conventions ont été fixées. Ici est l’emplacement pour conserver chacune d’entre elles afin que chacun puisse y s’y référer.

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

2.1. Installer Sphinx

Le manuel Mahara nécessite que Sphinx soit installé sur votre ordinateur. Vous pouvez trouver des informations sur la façon d’installer Sphinx sur le site 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 » : cd code

5. Faites un « checkout » du code pour the manual :

   • 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 » : 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 le fichier HTML du manuel : make html

    Note

    Cela créera toutes les traductions disponibles pour le manuel et prendra un peu de temps. Si vous ne voulez créer que le manuel en anglais, vous pouvez le compiler avec make preview MAHARA=18.10

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

11. Ouvrez le fichier index.html``dans un navigateur web afin d'afficher le manuel. Vous le trouverez dans le dossier ``build/en/19.04.

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

2.2. Faire des modifications dans le manuel

Une fois que vous avez installé le manuel sur votre ordinateur, vous pouvez effectuer des modifications. Les actions suivantes sont effectuées dans le terminal.

1. Allez dans le dossier du 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. Compiler un aperçu du manuel en langue anglaise : make preview MAHARA=19.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és à l’aide de 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 comporter le moins d’instructions possible sur les étapes à suivre. De préférence, seuls les numéros des étapes peuvent être échangés et le texte des étapes est traduisible car il s’agit d’un texte et non d’une partie de l’image. Cela pourrait également signifier que les traducteurs peuvent traduire les étapes mais ne doivent pas immédiatement modifier les captures d’écran.

• 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é.

   Pour le manuel Mahara, nous utilisons des fichiers .png en général, car nous travaillons avec des captures d’écran. Il est toujours bon d’utiliser l’extension * au lieu de .png au cas où le format du fichier serait modifié à un moment donné.

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, …)

Avertissement

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.

Voir aussi

La Documentation Sphinx est un excellent endroit pour approfondir vos connaissances et votre compréhension de l’utilisation de rST avec Sphinx. Si vous avez des questions, vous pouvez également consulter le groupe de discussion Sphinx.

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

2.5. Conventions

Note

Langues qui n’utilisent pas d’espaces entre les mots

Sphinx suppose qu’il y a toujours un espace avant le début de la commande et à la fin de celle-ci. C’est la seule manière pour que Sphinx puisse faire la différence entre les caractères de mise en page et les commandes du langage.

Ceci pose alors un problème dans les langues comme le Japonais dans lesquelles il n’y a pas d’espace entre les mots.

Vous devez mettre des espaces dans le texte, sinon la mise en page ne se fera pas, les index ne seront pas créés et les substitution ne seront pas effectuées. Vous devez alors répliquer les espaces qui existent dans la version anglaise. Par exemple, mettez un espace :

• avant et après les marques de substitution comme |edit|,

• avant :index: et :ref: et à la fin de l’entrée d’index ou quand la référence est terminée.

• avant * lorsqu’il est suivi d’un mot et après le * fermant; par exemple : *mot*, car ceci est une marque de formatage qui permet de mettre mot en gras. Il en va de même avec le formatage **.

• Chaque section qui est liée à un élément du menu de navigation devrait voir le chemin indiqué; par exemple : Menu principal → Créer → Fichier. Il vaut mieux copier-coller la flèche depuis le texte anglais pour être certain d’utiliser la bonne.

• Les boutons comme Enregistrer ou Copier la page, ainsi que les sections du portfolio comme Créer, Partager, etc. sont mises en évidence en gras à l’aide de la commande *.

• De petits boutons peuvent être inclus dans le texte comme , . Ils sont ajoutés par le biais d’une substitution. Tous les remplacements sont conservés dans le fichier shortcuts.rstext qui est inclus dans chaque fichier dans lequel une substitution est utilisée en plaçant « .. include: : /shortcuts.rstext » dans la première ligne du fichier. Les substitutions sont référencées dans le texte sous la forme « *Edit* button |edit| », ce qui indique par exemple l’action que vous effectuez avec elles. Les traducteurs ne doivent pas modifier la substitution « |edit| » elle-même, mais seulement changer « *Edit* button » en prenant soin de réintroduire le `` sans placer d’espace entre le `` et le texte pour s’assurer que le mot apparaît en surbrillance.

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

• Les nouvelles fonctionnalités font également l’objet d’une entrée dans l’index sous la forme « single: Nouveauté Mahara x, [la fonctionnalité qui est nouvelle] ». Les entrées d’index peuvent être placées soit au-dessus d’une section entière, soit en ligne. L’insertion en ligne est préférable pour les petits changements fonctionnels afin que les lecteurs soient directement dirigés vers la nouvelle fonctionnalité. Cela peut être fait comme suit :

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

  Avertissement

  S’il n’y a pas de signe de ponctuation juste avant « :index: » et/ou après « >` », vous devez insérer un espace juste avant « :index: » et/ou après « >`».

• 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 lié] <URL>`_ » — Les traducteurs doivent uniquement remplacer « [texte lié] ».

• Les références internes qui peuvent être liées à partir d’un autre endroit du manuel sont créées en plaçant « .... [reference_text]: » dans une ligne juste avant un titre. Je laisse généralement une ligne vide entre la référence et le titre.

• Lien vers une référence interne : « :ref:`[texte lié] <la référence interne> » — Les traducteurs doivent uniquement remplacer « [texte lié] ».

• 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 traduisez les captures d’écran et autres images, veillez à conserver la structure du dossier « images » telle qu’elle apparaît dans la branche respective de la version du manuel que vous éditez dans Git, par exemple pour Mahara 18.10.

• Vous pouvez trouver les images originales utilisées pour le manuel dans le dossier « images_original » et ensuite dans leurs sous-dossiers respectifs. Vous pouvez les utiliser pour vos propres traductions si vous souhaitez uniquement échanger l’arrière-plan mais conserver les légendes.

• Vous ne devez pas refaire les images que vous ne traduisez pas, par exemple les icônes des blocs, les boutons généraux de Mahara et les boutons de l’éditeur de texte. Toutes les images qui ne sont pas dans votre traduction seront prises de l’original anglais.

• Le manuel est mis à jour une fois par jour. Les nouvelles chaînes de traduction sont extraites de Launchpad et les images sont téléchargées vers Git avant la compilation du manuel si des modifications sont apportées.

Note

Si vous souhaitez mentionner les noms des principaux traducteurs du manuel dans votre langue, vous pouvez ajouter une phrase juste après « Le manuel Mahara est écrit par des membres de la communauté Mahara ». Ce paragraphe apparaît avant la table des matières. Il n’y a pas de phrase équivalente dans le manuel anglais car il ne s’agit pas d’une traduction.