music-encoding · felix-commits · Oct 18, 2023 · Oct 24, 2023 · Oct 24, 2023 · Oct 24, 2023
diff --git a/_tutorials-FR/199_tutorials/just-a-name.xml b/_tutorials-FR/199_tutorials/just-a-name.xml
@@ -0,0 +1,3 @@
+<this is="a" confusing="value">
+    <for a="prefill!"/>
+</this>
diff --git a/_tutorials-FR/199_tutorials/tutorials.json b/_tutorials-FR/199_tutorials/tutorials.json
@@ -5,7 +5,7 @@
         "descFile": "writingTutorials-01.html"
     },
     {
-        "label":"Mise en route",
+        "label":"Configuration du site web",
         "descFile": "writingTutorials-02.html"
     },
     {

diff --git a/_tutorials-FR/199_tutorials/tutorials.xml b/_tutorials-FR/199_tutorials/tutorials.xml
@@ -0,0 +1,34 @@
+<mei xmlns="http://www.music-encoding.org/ns/mei">
+    <meiHead>
+        <fileDesc>
+            <titleStmt>
+                <title/>
+            </titleStmt>
+            <pubStmt/>
+        </fileDesc>
+    </meiHead>
+    <music>
+        <body>
+            <mdiv>
+                <score>
+                    <scoreDef>
+                        <staffGrp>
+                            <staffDef clef.shape="G" clef.line="2" n="1" lines="5"/>
+                        </staffGrp>
+                    </scoreDef>
+                    <section>
+                        <measure>
+                            <staff n="1">
+                                <layer>
+                                    <?snippet-start?>
+                                    <note pname="c" oct="4" dur="4"/>
+                                    <?snippet-end?>
+                                </layer>
+                            </staff>
+                        </measure>
+                    </section>
+                </score>
+            </mdiv>
+        </body>
+    </music>
+</mei>
diff --git a/_tutorials-FR/199_tutorials/writingTutorials-01.html b/_tutorials-FR/199_tutorials/writingTutorials-01.html
@@ -0,0 +1,34 @@
+<div>
+  <h1>Un tutoriel tout particulier...</h1>
+  <p>
+    Manifestement, vous vous intéressez à la MEI, et c'est merveilleux ! Une
+    bonne façon de vous assurer de bien comprendre ce format pourrait être de
+    rédiger un tutoriel à ce sujet, ce qui, par là même, aidera les autres à
+    mieux comprendre.
+  </p>
+  <p>
+    Rédiger de la documentation est généralement une tâche ingrate. Peu importe
+    la quantité que vous écrivez, il y a toujours besoin de plus, et quoi que
+    vous fassiez, vous ne pourrez jamais répondre aux besoins et aux attentes de
+    tout le monde. Nous pensons que la meilleure façon de résoudre ce problème
+    est de répartir la tâche sur de nombreuses épaules, en réduisant la charge
+    de travail de chacun. En plus, en approchant la MEI sous différents angles
+    et niveaux d'expertise, il devient plus facile d'apporter une aide précise à
+    chacun.
+  </p>
+  <p>
+    Donc, lorsque vous avez appris quelque chose sur la MEI et que vous pensez
+    que d'autres pourraient en bénéficier, s'il vous plaît,
+    <i>n'hésitez pas</i> à contribuer. Ce tutoriel vous expliquera ce qui est
+    nécessaire. Pas de souci, vous n'avez pas besoin d'être un programmeur pour
+    écrire votre propre tutoriel, une introduction à un répertoire spécifique ou
+    des recommandations de bonnes pratiques générales. La communauté MEI est là
+    pour vous
+    <a href="/community/community-contacts.html" target="_blank">aider</a>, et
+    l'équipe
+    <a href="/community/technical-team.html" target="_blank">Technique</a>
+    veillera à ce que tout ce que vous écrivez soit techniquement correct - rien
+    ne peut mal tourner, promis. Alors suivez-nous à la page suivante en
+    cliquant sur <b>continuer</b> ci-dessous.
+  </p>
+</div>
diff --git a/_tutorials-FR/199_tutorials/writingTutorials-02.html b/_tutorials-FR/199_tutorials/writingTutorials-02.html
@@ -0,0 +1,60 @@
+<div>
+  <p>
+    Comme le reste de notre site web, tous les tutoriels sont directement
+    publiés à partir d'un
+    <a
+      href="https://github.com/music-encoding/music-encoding.github.io"
+      target="_blank"
+      >dépôt GitHub</a
+    >. Cela offre à la fois des avantages et des inconvénients. Un énorme
+    avantage est que la création d'un nouveau tutoriel est aussi simple que de
+    commit un dossier dans le dépôt (nous expliquerons cela plus tard, pas
+    d'inquiétude). Les inconvénients majeurs sont que l'interaction requise pour
+    un tutoriel n'est pas très bien prise en charge par cette configuration
+    technique, et que nous ne pouvons pas systématiquement valider
+    automatiquement le schéma MEI fourni par l'utilisateur. Ces deux aspects ont
+    été pris en compte par nous, et nous espérons que nos solutions équilibrent
+    bien entre le besoin d'orientation de l'utilisateur et l'effort nécessaire
+    pour préparer un tutoriel. Nous y reviendrons plus tard également.
+  </p>
+  <p>
+    Maintenant, <b>commençons</b>. Nos pages sont construites et générées par
+    <a href="https://jekyllrb.com/" target="_blank">Jekyll</a>. Pour nos
+    tutoriels, cela signifie que nous avons besoin d'un fichier
+    <a href="https://en.wikipedia.org/wiki/Markdown" target="_blank"
+      >Markdown</a
+    >
+    avec les détails sur notre tutoriel que le site web environnant doit
+    connaître pour l'intégrer correctement. Jetons un coup d'œil au fichier
+    Markdown de ce tutoriel :
+  </p>
+  <pre class="codeblock">
+---
+---
+layout: tutorials-FR
+type: tutorial-FR
+name: "Écrire des tutoriels"
+fullname: "Une introduction à l'écriture des tutoriels sur la MEI"
+data: "tutorials.json"
+---</pre
+  >
+  <label>tutorials.md (Fichier Markdown)</label>
+  <p>
+    Alors que les deux premières lignes, <code>layout: tutorials-FR</code> et
+    <code>type: tutorial-FR</code> doivent toujours rester de cette manière pour
+    les tutoriels en fraçais, les deux lignes suivantes peuvent changer. Ce que
+    vous écrivez ici est affiché dans la liste des tutoriels, par exemple. Notez
+    que la toute première et la dernière ligne, chacune contenant trois tirets,
+    doivent rester de cette manière pour que le tutoriel fonctionne
+    correctement.
+  </p>
+  <p>
+    Comme cela a été mentionné précédemment, nous devons travailler dans une
+    certaine mesure autour des limitations de notre configuration technique.
+    Pour cette raison, nous faisons référence à un fichier appelé
+    <code>tutorials.json</code>, qui se trouve dans le même dossier. Le nom du
+    fichier n'a pas d'importance, tant qu'il peut être trouvé dans le même
+    dossier que le fichier Markdown. Passons maintenant au contenu de ce fichier
+    JSON.
+  </p>
+</div>
diff --git a/_tutorials-FR/199_tutorials/writingTutorials-03.html b/_tutorials-FR/199_tutorials/writingTutorials-03.html
@@ -0,0 +1,124 @@
+<div>
+  <p>
+    Le fichier
+    <a href="https://en.wikipedia.org/wiki/JSON" target="_blank">JSON</a>
+    représente la table des matières du tutoriel. Il contient un objet avec
+    plusieurs propriétés. Jetons un coup d'œil à (une version simplifiée) du
+    tutoriel actuel :
+  </p>
+  <pre class="codeblock">{
+  "steps": [
+    {
+        "label":"Bienvenue",
+        "descFile": "writingTutorials-01.html"
+    },
+    {
+        "label":"Configuration du site web",
+        "descFile": "writingTutorials-02.html"
+    },
+
+    <span class="text-gray"><i>… plus d'étapes à ajouter ici …</i></span>
+
+  ],
+  "end":"writingTutorials-end.html",
+  "resp":[
+    {
+        "name":"Johannes Kepper",
+        "affiliation":"Beethovens Werkstatt | Universität Paderborn"
+    }
+  ]
+}</pre>
+  <label>tutorials.json</label>
+  <p>
+    Il y a trois propriétés importantes ici. La première, <code>"steps"</code>,
+    est utilisée pour décrire les différentes étapes d'un tutoriel. Nous y
+    reviendrons dans un instant. Ensuite, <code>"end"</code> spécifie un fichier
+    dans lequel la page finale du tutoriel est fournie. Enfin, il y a
+    <code>"resp"</code>. Dans cet ensemble, vous devez indiquer votre nom et
+    votre affiliation. Cela permet d'identifier l'auteur et d'être en mesure de
+    le contacter pour des questions, mais aussi de vous donner une
+    reconnaissance publique pour le travail que vous faites sur la MEI. Si vous
+    avez travaillé sur un tutoriel avec un groupe de personnes, vous pouvez bien
+    sûr les inclure tous. Alors pourquoi ne pas demander à certains de vos
+    étudiants de travailler sur ces tutoriels ?
+  </p>
+  <h1>Étapes</h1>
+  <p>
+    Revenons à la propriété <code>"steps"</code>. Il s'agit d'un tableau d'objets,
+    décrivant chacun une étape du tutoriel. La seule propriété qui est
+    obligatoire est <code>"descFile"</code>. Ici, vous devez fournir le nom du
+    fichier HTML qui correspond au contenu de cette étape. Par exemple le texte que vous
+    lisez actuellement provient de l'un de ces fichiers. Ce fichier n'est pas un
+    fichier HTML complet ; il doit commencer par un élément racine
+    <code>&lt;div&gt;</code> et contenir du HTML simple. La propriété suivante,
+    <code>"label"</code>, est facultative. Si vous ne la fournissez pas, l'étape
+    sera étiquetée en fonction de sa position (c'est-à-dire "Étape 3" ou
+    similaire).
+  </p>
+  <p>
+    Évidemment, un tutoriel n'est pas censé être uniquement du texte (cela ne
+    justifierait guère toute cette configuration...). Parfois, vous voudrez
+    peut-être que l'utilisateur encode réellement des éléments MEI. Regardons la
+    définition d'une telle étape :
+  </p>
+  <pre class="codeblock">{
+    <span class="text-gray">"label":"Une Étape Exemple",</span>
+    <span class="text-gray">"descFile": "instructions-etape.html",</span>
+    "xmlFile": "encodage.xml",
+    "xpaths": [
+        {
+            "rule":"count(//mei:note) = 1",
+            "renderanyway":false
+        },
+        {
+            "rule":"//mei:note/@pname = 'g'",
+            "renderanyway":true,
+            "hint":"Vous avez besoin d'un attribut @pname avec une valeur de g."
+        }
+    ],
+    "editorLines":3,
+    "prefillFile":"remplissage.xml"
+}</pre>
+  <label
+    >Définition d'une étape de tutoriel qui comprend un composant éditeur, à
+    insérer dans le tableau "étapes" de tutorials.json</label
+  >
+  <p>
+    Les deux propriétés que nous connaissons déjà sont en gris, nous n'avons pas
+    besoin d'y revenir. Si une étape contient à la fois une propriété
+    <code>"xmlFile"</code> et une propriété <code>"xpaths"</code>, un éditeur
+    sera affiché. En même temps, le bouton "Continuer" en bas à droite
+    disparaîtra. Pour avancer, l'utilisateur doit maintenant suivre vos
+    instructions et entrer le code MEI dans l'éditeur. Pour décider si
+    l'utilisateur a réussi ou non, vous devez fournir un certain nombre de
+    règles
+    <a href="https://en.wikipedia.org/wiki/XPath" target="_blank">XPath</a>.
+    L'expression XPath elle-même est stockée dans une propriété
+    <code>"rule"</code>. Elle doit renvoyer une valeur booléenne, c'est-à-dire
+    <i>true</i> ou <i>false</i>. Si vous souhaitez guider l'utilisateur, vous
+    pouvez fournir une propriété <code>"hint"</code>. Si le contenu de l'éditeur
+    ne correspond pas à une règle XPath, son indication sera affichée comme une
+    boîte d'avertissement en dessous de l'éditeur. Les règles XPath sont
+    vérifiées dans l'ordre, et la vérification s'arrête dès qu'une règle est
+    fausse. Si toutes les règles sont satisfaites, le tutoriel passera
+    automatiquement à l'étape suivante.
+  </p>
+  <p>
+    La propriété <code>"renderanyway"</code> d'une règle XPath est utile lorsque
+    vous souhaitez que l'utilisateur manipule l'encodage. Normalement, la
+    saisie de l'utilisateur n'est rendue que lorsque toutes les règles XPath
+    sont satisfaites. Cependant, vous pourriez demander à l'utilisateur
+    d'essayer différentes hauteurs, en indiquant que le tour continue lorsqu'une
+    hauteur spécifique est entrée. Ensuite, vous pouvez définir
+    <code>"renderanyway"</code> sur <code>true</code>, et Verovio fera de son
+    mieux pour rendre la saisie actuelle de l'utilisateur. Ce comportement est
+    implémenté dans la deuxième règle XPath ci-dessus.
+  </p>
+  <p>
+    La propriété <code>"xmlfile"</code> spécifie un fichier qui sert de contexte
+    pour l'éditeur. Dans la prochaine étape de ce tutoriel, nous expliquerons
+    cela en détail. Il existe deux autres propriétés qui peuvent être utiles.
+    Avec la propriété <code>"editorLines"</code>, vous pouvez spécifier la
+    hauteur
+  </p>
+</div>
diff --git a/_tutorials-FR/199_tutorials/writingTutorials-04.html b/_tutorials-FR/199_tutorials/writingTutorials-04.html
@@ -0,0 +1,68 @@
+<div>
+  <p>
+    Lorsque vous réalisez un tutoriel par vous-même, vous vous êtes peut-être
+    demandé comment Verovio parvient à rendre le MEI de l'utilisateur, même si
+    l'utilisateur n'entre pas un fichier MEI complet. Cela est permis grâce à la
+    propriété <code>"xmlFile"</code> introduite à la dernière page. Cette
+    propriété fait référence à un fichier MEI complet, qui fournit le contexte
+    nécessaire pour encadrer la saisie de l'utilisateur en vue d'un rendu
+    correct. Regardons un exemple simple :
+  </p>
+  <pre
+    class="codeblock"
+  >&lt;mei xmlns="http://www.music-encoding.org/ns/mei"&gt;
+    &lt;meiHead&gt;
+        &lt;fileDesc&gt;
+            &lt;titleStmt&gt;
+                &lt;title/&gt;
+            &lt;/titleStmt&gt;
+            &lt;pubStmt/&gt;
+        &lt;/fileDesc&gt;
+    &lt;/meiHead&gt;
+    &lt;music&gt;
+        &lt;body&gt;
+            &lt;mdiv&gt;
+                &lt;score&gt;
+                    &lt;scoreDef&gt;
+                        &lt;staffGrp&gt;
+                            &lt;staffDef clef.shape="G" clef.line="2" n="1" lines="5"/&gt;
+                        &lt;/staffGrp&gt;
+                    &lt;/scoreDef&gt;
+                    &lt;section&gt;
+                        &lt;measure&gt;
+                            &lt;staff n="1"&gt;
+                                &lt;layer&gt;
+                                    <span class="text-error">&lt;?snippet-start?&gt;</span>
+                                    &lt;note pname="c" oct="4" dur="4"/&gt;
+                                    <span class="text-error">&lt;?snippet-end?&gt;</span>
+                                &lt;/layer&gt;
+                            &lt;/staff&gt;
+                        &lt;/measure&gt;
+                    &lt;/section&gt;
+                &lt;/score&gt;
+            &lt;/mdiv&gt;
+        &lt;/body&gt;
+    &lt;/music&gt;
+&lt;/mei&gt;</pre>
+  <label
+    >Un fichier MEI simple, à utiliser comme contexte pour la saisie de
+    l'utilisateur.</label
+  >
+  <p>
+    Il s'agit simplement d'un fichier MEI classique, mais qui contient deux
+    <i>instructions de traitement</i> importantes (marquées en rouge). Le
+    contenu de ce fichier est lu en mémoire. Chaque fois que la saisie de
+    l'utilisateur dans l'éditeur est bien formée en XML, elle est insérée
+    <i>entre</i> les deux instructions de traitement, et le fichier complet
+    (incluant désormais la saisie de l'utilisateur) est validé et (le cas
+    échéant) envoyé à Verovio pour le rendu.
+  </p>
+  <p>
+    Ce qui est stocké entre les deux <i>instructions de traitement</i> est
+    destiné à servir de solution d'exemple. Cette fonctionnalité n'est pas
+    encore implémentée, mais le sera bientôt. Il est déjà possible de
+    télécharger le fichier complet (incluant le contexte), de sorte que les
+    utilisateurs puissent les utiliser comme référence future ou comme modèle
+    pour leur propre travail.
+  </p>
+</div>
diff --git a/_tutorials-FR/199_tutorials/writingTutorials-05.html b/_tutorials-FR/199_tutorials/writingTutorials-05.html
@@ -0,0 +1,51 @@
+<div>
+  <p>
+    Cela va sans dire, la validation correcte de la saisie est importante pour
+    un apprentissage efficace et durable. Cependant, parce que notre site web
+    est basé sur Jekyll, nous devons compter sur la validation côté client (se
+    fier uniquement à un service externe pour la validation n'est probablement
+    pas fiable, c'est pourquoi nous avons opté pour cette approche). À ce jour,
+    la validation côté client (c'est-à-dire, en utilisant JavaScript) ne prend
+    pas en charge correctement le
+    <a href="https://en.wikipedia.org/wiki/RelaxNG" target="_blank">RelaxNG</a>,
+    le langage de schéma utilisé en bout de chaine pour valider les instances
+    MEI dans de vrais projets. Pour cette raison, nous devons utiliser
+    l'approche basée sur XPath mentionnée précédemment.
+  </p>
+  <p>
+    La propriété <code>"xpaths"</code> de l'étape actuelle contient un tableau
+    de règles auxquelles la saisie de l'utilisateur doit se conformer pour
+    accomplir cette étape. Ces règles sont spécifiées sous la forme d'objets
+    JSON avec trois propriétés :
+  </p>
+  <pre class="codeblock">
+{
+    "rule":"//mei:note/@pname = 'g'",
+    "renderanyway":true,
+    "hint":"Vous avez besoin d'un attribut @pname, avec une valeur de g."
+}</pre
+  >
+  <p>
+    La propriété <code>"rule"</code> contient une expression
+    <a href="https://en.wikipedia.org/wiki/XPath" target="_blank">XPath 1</a>,
+    qui doit se résoudre en une déclaration booléenne : elle doit être soit
+    <i>true</i> soit <i>false</i>. La propriété <code>"renderanyway"</code> est
+    utilisée pour décider si l'éditeur actuel peut être rendu par Verovio même
+    si le XPath n'est pas respecté. Le contenu de la propriété
+    <code>"hint"</code> est censé aider l'utilisateur à réussir son encodage.
+    Seule la première règle XPath qui échoue est affichée, guidant l'utilisateur
+    pas à pas à travers les différentes erreurs. Cependant, toutes les étapes
+    n'ont pas besoin d'une aide – parfois, il est préférable de laisser
+    l'utilisateur explorer un peu par lui-même.
+  </p>
+  <p>
+    Pour la validation, la saisie de l'utilisateur sera insérée entre les
+    marqueurs <code>&lt;?snippet-start?&gt;</code> et
+    <code>&lt;?snippet-end?&gt;</code> dans le fichier XML actuel, puis les
+    règles XPath seront vérifiées par rapport à ce fichier complet. Dès qu'une
+    de ces règles échoue (c'est-à-dire, renvoie <i>false</i>), l'astuce
+    correspondante sera affichée. Lorsque toutes les règles renvoient
+    <i>true</i>, le bouton "continuer" sera activé et l'utilisateur pourra
+    passer à l'étape suivante.
+  </p>
+</div>