Astuces pour la mise en page de la documentation MuseScore

Vue d’ensemble

Ce "tutoriel" a pour objet de traduire, simplifier et mettre à jour le document source Compose tips. Il complète les informations de publication fournies dans Éditer le Manuel de MuseScore 4 en précisant quelques trucs et astuces concernant l'emploi des deux langages principaux pouvant être utilisés pour la rédaction des documents de présentation (manuel, tutoriel...) de MuseScore : MarkDown et Full HTML.

MarkDown

Le langage MarkDown est celui utilisé par défaut dans les pages du manuel. Il comprend quelques balises HTML autorisées.

Pour pour d'informations complètes sur la syntaxe Markdown, allez voir le tutoriel Un guide pour bien commencer avec markdown ou la page Markdown sur Wikipédia.

Balises HTML autorisées

Les pages en MarkDown autorisent l’utilisation d’un petit nombre de balises HTML communes qu’il est très facile de mémoriser : <kbd class="button"> <samp class="button"> <code language> <img src width height alt>. La table suivante en montre quelques exemples.

.

Description de balise	Vous tapez	Vous obtenez
Balise em pour accentuer le texte	<em>Accentué</em>	Accentué
Balise kbd pour afficher les touches de clavier.	<kbd><kbd>A<kbd><kbd>	A
Balise code pour afficher le code source de programmation	<code>Code HTML</code>	Code HTML
Balise img pour afficher une image (voir également les balises spéciales Markdown inline, file et attachement plus bas)	<img src="https://musescore.org/sites/musescore.org/files/2023-06/partition.jpg" alt="Image partition" width="100" height="">

Pour plus d’informations, allez voir le site Le langage HTML ou utilisez votre moteur de recherche favori pour trouver d’autres sites expliquant le code HTML.

Caractères spéciaux

La plupart des caractères non usuels peuvent être saisis directement au clavier sans le moindre problème. Si vous rencontrez des problèmes, essayez d’utiliser des entités de caractère HTML. Un exemple classique est d’utiliser l’entité &amp; pour le caractère esperluette &. Pour voir une liste complète de ces entités, voir la page Le langage HTML/Entités. Parmi les caractères disponibles fréquemment utilisés :

Exemples pratiques de syntaxe MarkdDown

Exemples de syntaxe	Vous tapez	Vous obtenez
Titres avec # (le niveau est précisé par le nombre de # qui précèdent le titre)	## Titre 2 ### Titre 3	Titre 2 Titre 3
Listes à puces avec * (ajouter un espace avant * pour indiquer une puce de niveau supérieur)	* Premier niveau * Deuxième niveau	Premier niveau Deuxième niveau
Listes numérotées : utiliser un numéros à la place des astérisques	1. Premier item de la liste 2. Deuxième item 1. Premier sous-item	Premier item de la liste Deuxième item Premier sous-item
Texte en italique à faire précéder et suivre par un astérisque * ou un trait de soulignement _)	*Ce texte est en italique* _Celui-ci aussi_	Ce texte est en italique Celui-ci aussi
Texte en gras à faire précéder et suivre par deux astérisques * ou deux traits de soulignement _)	**Ce texte est en gras* __Celui-ci aussi__	Ce texte est en gras Celui-ci aussi
Texte en gras et italique à faire précéder et suivre par trois astérisques * ou trois traits de soulignement _)	***Ce texte est en italique gras*** ___Celui-ci aussi___	Ce texte est en italique gras Celui-ci aussi
Mots barrés avec un double tilde ~	Il faut supprimer ~~cette partie~~	Il faut supprimer cette partie
Lien vers un document externe	[Texte associé au lien](http://lien.exemple.com "titre optionnel")	Texte associé au lien
Lien vers un document interne en utilisant le numéro de nœud et éventuellement la balise de titre interne à la page (voir le lien suggéré dans les exemples)	[node:329210,title="Éditer le Manuel"] [node:329210,title="Utiliser la bonne syntaxe",fragment="Utiliser_la_bonne_syntaxe"]	Éditer le manuel Utiliser la bonne syntaxe
Affichage d'un fichier téléchargé avec la page à l'aide des balises spéciales inline, file ou attachement. Si les trois fichiers suivants ont été téléchargés dans cet ordre chronologique (ce qui est le cas, par exemple, dans cette page) : Abeille.png (référencé comme fichier n° 1) Notes.pdf (référencé comme fichier n° 2) Chat.png (référencé comme fichier n° 3)	[inline:1=Bzzz] ou [inline:Abeille.png=Bzzz] [file:3=Miaou] ou [file:Chat.png=Miaou] [attachment:2=Si Si Ré La] ou [attachment:Notes.pdf=Si Si Ré La]
Afficher du code en l'encadrant avec un accent grave `	`ceci est du code`	Ceci est du code
Afficher un bloc de code en l'encadrant avec trois accents graves ` (remarque : le bloc assure la mise en relief syntaxique évoquée au chapitre Full HTML)	```<samp class="button">Annuler</samp>```	<samp class="button">Annuler</samp>

Full HTML

Il est possible d’opter pour la rédaction de pages en Full HTML lorsqu’il est nécessaire d’utiliser des balises spécifiques à ce langage qui ne sont pas disponibles dans MarkDown.
Les lignes et les paragraphes sont automatiquement reconnus. Les balises <br /> saut de ligne, <p> début de paragraphe and </p> fin de paragraphe sont insérées automatiquement. Si les paragraphes ne sont pas reconnus, ajoutez simplement quelques lignes vides
Les adresses web et email sont automatiquement converties en liens.

Pour plus d’informations, allez voir les spécifications HTML du W3C (en anglais) or W3C ou utilisez votre moteur de recherche favori pour trouver d’autres sites expliquant le code HTML.

Exemples de balises HTML fréquentes

Préformaté

Afficher des caractères spéciaux

La plupart des caractères non usuels peuvent être saisis directement sans le moindre problème.
Si vous rencontrez des problèmes, essayez d’utiliser des éléments HTML. Un exemple classique est d’utiliser &amp; pour le caractère esperluette &. Pour voir une liste complète de ces éléments, voir la page des entités HTML (en anglais).
Exemples de caractères disponibles :

Mise en relief syntaxique d'un bloc de code

La mise en relief colorée de la syntaxe d’un langage informatique utilisé dans un bloc de code peut être obtenue en utilisant les balises suivantes :

• Balises génériques : <code>, <pre>.
• Balises spécifiques à certains codes : <bash> pour Bash, <cmake> pour CMake, <cpp> pour C++, <html> pour HTML5, <js> pour Javascript, <php> pour PHP, <python> pour Python, <qml> pour QML, <xml> pour XML.
• Options et astuces :
• Le langage de codage peut être spécifié pour les balises génériques en utilisant un des attributs suivants : type, lang, language, class. Les valeurs possibles sont : "bash" (pour Bash), "cmake" (pour CMake), "cpp" (pour C++), "html" (pour HTML5), "html5" (pour HTML5), "javascript" (pour Javascript), "js" (pour Javascript), "php" (pour PHP), "python" (pour Python), "qml" (pour QML), "xml" (pour XML).
• La numérotation des lignes peut être activée/désactivée avec l'attribut "linenumbers". Les valeurs possibles sont : "off" pour aucun numéro de ligne, "normal" pour des numéros de ligne normaux et "fancy" pour des numéros de ligne fantaisie (tous les n^ièmes numéros de ligne mis en exergue). Le numéro de ligne de départ peut être spécifié avec l'attribut "start", qui active implicitement la numérotation normale des lignes. Pour la numérotation fantaisie, l'intervalle pour les numéros de ligne en surbrillance peut être spécifié avec l'attribut "fancy", qui active implicitement la numérotation de ligne fantaisie.
• Si le code source entre les balises contient une nouvelle ligne (par exemple immédiatement après la balise d'ouverture), le code mis en relief sera affiché sous forme de bloc de code. Sinon, il sera affiché en ligne.
• Un titre peut être ajouté à un bloc de code avec l'attribut "title".
• Valeurs par défaut :
• Coloration par défaut de la mise en relief du code pour les balises génériques : lorsqu'aucun attribut de langage n'est spécifié, le bloc de code n’est pas traité par le filtre GeSHi.
• Numérotation des lignes par défaut : aucune numérotation.