Débutons notre apprentissage par un petit exemple. Cela vous permettra de vous familiariser avec l’interface de mdown. mdown se présente comme un petit programme à lancer en ligne de commande. Dans sa forme la plus simple, mdown traduit ce qui lui est fourni en entrée dans le format que vous lui aurez spécifié, par défaut, le XHTML.
Effectuons donc un premier test. Dans un terminal textuel, entrez la
commande suivante (dans tous les exemples de commandes à taper dans un
terminal, le symbole $ en début de ligne désigne l’invite et n’est
pas à reproduire) :
$ mdown
Le terminal ne devrait rien afficher de plus qu’une nouvelle
ligne. Vous pouvez entrer votre texte mdown directement ainsi ; si
vous n’avez pas l’habitude de ce genre d’interaction, retenez que vous
devez indiquer la fin de votre document avec le caractère de fin de
fichier (EOF) qui est traditionnellement ^D
(touches Ctrl et D simultanément) sous unixoïdes et ^Z
(touches Ctrl et Z simultanément) sous Windows.
Essayez d’écrire une phrase naturellement (sans ponctuation ou espacement bizarre). Si rien ne vous vient à l’esprit, je peux vous suggérer « Bonjour ! ». Allez à la ligne et terminez la saisie. mdown devrait produire la sortie suivante :
Bonjour !
L’entité XML   mise à part,
rien ne vous indique que le texte généré est en fait du XHTML.
Recommencez donc l’opération en entrant cette fois-ci le texte :
/Bonjour/ !
mdown devrait vous répondre :
<em>Bonjour</em> !
La présence de balises <em> indique une mise en valeur (ou
emphase). C’est donc bien du XHTML !
Si vous avez ne serait-ce qu’une vague idée de la structure d’un document XHTML, vous remarquerez sans peine que le code produit ne constitue pas une page XHTML valide. Il manque toutes sortes de déclarations. Ceci est le comportement normal. En effet, mdown est destiné à produire des bouts de code faciles à insérer dans des constructions plus élaborées.
Un moyen simple (mais limité) de remédier à ce problème est d’utiliser
les options -H et -F qui permettent respectivement d’ajouter le
contenu d’un fichier avant et après le code produit. La distribution
sous forme de sources contient deux fichiers header.sample.html et
footer.sample.html, en guise d’exemple. Essayez par exemple :
$ mdown -H $SRC/header.sample.html -F $SRC/footer.sample.html
Dans cette commande, $SRC est à remplacer par le chemin menant au
dossier des sources de mdown.
Pour des besoins plus évolués, je conseille l’usage d’un script extérieur. Toutefois, cette pratique sort du cadre de cette introduction.
Jusqu’ici, nous avons fourni le texte à traduire à mdown directement, sur son entrée standard. Bien sûr, ce mode de fonctionnement n’est guère pratique. Les habitués de la console pensent sûrement déjà à utiliser une redirection. Vous pouvez effectivement utiliser cette méthode. mdown accepte également un nom de fichier en argument, placé de préférence à la suite des options.
L’option -o, quant à elle, prend en paramètre le nom du fichier de
sortie à utiliser, à la place de la sortie standard.
Une invocation typique de mdown ressemble à :
$ mdown -o monfichier.html monfichier.text
mdown connaît plusieurs formats de sortie différents, autant en
profiter ! L’option -f permet de sélectionner un format. Elle attend
en paramètre le nom du format. Le tableau suivant liste les formats
d’intérêt pour le rédacteur généraliste.
xhtml | XHTML 1.0 Strict, format par défaut |
latex | LaTeX, tout comme pour le XHTML, la sortie est nue |
zcode | pour le Site du Zero |
Il existe également un format man permettant d’écrire simplement des
pages man ; toutefois, des contraintes partiulières s’appliquent à cet
usage, qui n’est pas couvert par cette introduction.
Après ce rapide aperçu de l’utilisation du programme, il est temps de nous intéresser au langage en lui-même. À travers une série d’exemples et de cas d’usage, vous allez apprendre à rédiger un document avec les constructions basiques de mdown.
La majeure partie d’un document mdown est bien évidemment constituée de texte. Les caractères usuels servant à former les mots et les phrases ne sont aucunement spéciaux à mdown. Plusieurs lignes de textes successives forment un paragraphe. Les paragraphes sont séparés par des lignes vides.
Par exemple :
Ceci est un paragraphe.
Ceci en est un autre.
À l’intérieur d’un paragraphe, les retours à la ligne ne sont pas significatifs et sont traités comme de simples espaces. Vous pouvez cependant forcer un retour à la ligne en terminant une ligne par des espaces supplémentaires.
Dans l’exemple suivant, l’espace importante est représentée par le
glyphe ␣.
Cette ligne s'arrêtera ici :␣
La suite du paragraphe poursuivra sur la ligne suivante.
Vous pouvez ajouter des effets sémantiques à certaines portions du texte en les entourant d’une ponctuation spéciale. En règle générale, il faut éviter de les utiliser à outrance ou de manière inadaptée.
Le tableau suivant liste les différentes décorations disponibles :
/emphase/ | mise en valeur du texte |
*forte emphase* | forte mise en valeur du texte |
`verbatim` | texte verbatim |
.acronyme.(Nom Complet) | acronyme avec définition |
.acronyme.(Nom Complet)(langue) | acronyme avec définition |
.acronyme. | acronyme sans définition |
+locution latine+ | locution latine |
+locution étrangère+(langue) | locution étrangère |
Il n’est pas possible de mélanger plusieurs effets. Vous ne pouvez pas avoir, par exemple, une locution latine en emphase. En pratique, cela ne constitue guère un facteur limitant.
Les acronymes obéissent de plus à quelques restrictions supplémentaires : le premier caractère de l’acronyme ne doit pas être un caractère blanc ou de ponctuation.
Pour empêcher mdown de voir un caractère comme étant spécial, il
suffit de le précéder d’un antislash \. Cette règle fonctionne pour
toutes les mises en forme, excepté le texte verbatim. Par exemple
*\** produira une astérisque * à laquelle sera appliquée une forte
emphase, comme ceci : *.
La règle est différente pour le texte verbatim. En effet, il est
possible d’insérer n’importe quel texte entre deux marqueurs
verbatim. Ceux-ci ne sont pas limités à une seule apostrophe gauche ` ; vous pouvez utiliser autant d’apostrophes pourvu que leur
nombre soit égal de part et d’autre du texte : si vous placez trois
apostrophes gauches avant le texte, il vous faudra en placer trois
après celui-ci. Cette fonctionnalité est utile si le texte à insérer
contient lui-même des caractères ` ; il vous suffit alors de
l’encercler avec une apostrophe de plus qu’il n’en contient
consécutivement. De plus, le premier et le dernier caractères blancs,
s’ils sont présents, sont ignorés, de sorte à ce que vous puissiez
écrire du code débutant ou se terminant par un caractère `.
Sur un petit exemple, cela donne :
| Code | Résultat |
``a`b`` | a`b
|
`` ` `` | `
|
```a``b`c``` | a``b`c
|
| avec n apostrophes… | … |
Les références qu’elles soient internes ou entre documents constituent un élément important de la mise en page, en particulier des articles destinés à une publication en ligne. Ainsi, mdown dispose de toute une panoplie de constructions pour rendre l’usage de ceux-ci plus aisé et plus flexible.
Un lien a généralement la forme [TEXTE](ADRESSE) où TEXTE est le
texte qui sera visible par le lecteur et ADRESSE peut prendre
diverses formes selon le type de lien.
Les liens les plus simples sont les liens externes : ADRESSE est
alors simplement une URL. Par
exemple : [foo](http://foo.bar) produira
foo. Celle-ci peut également être relative ; par
exemple : [foo](bar) produira foo.
Si ADRESSE débute par un symbole #, le lien est une référence
interne au document et doit correspondre à une ancre définie quelque
part ailleurs dans le document. Une ancre s’écrit [NOM], où NOM
est l’identifiant qui devra être reporté à la suite du symbole #
dans les liens.
Les noms d’ancres acceptables dépendent du format de sortie choisi. Actuellement, les deux seuls formats acceptant des liens internes sont le LaTeX et le XHTML ; il semblerait donc que le jeu de caractères utilisable soit formé les lettres non accentuées, chiffres, tirets, points et deux-points. De plus, il est nécessaire que le nom débute par une lettre.
Plus généralement, afin d’assurer une compatibilité maximale avec d’éventuels futurs formats, l’usage d’identifiants composés uniquement de lettres latines non accentuées minuscules est conseillé.
Il est possible de combiner une URL avec une référence
interne. L’adresse obtenue prend alors la forme URL#NOM. À l’heure
actuelle, aucun format ne traite ce type d’adresses de manière
spécifique : elles sont simplement considérées comme des
URL à particule. L’interprétation exacte dépend du client et du type
de document visé. Les pages web supportent naturellement cette
syntaxe.
Il possible de donner un nom, à la manière d’un nom d’ancre, à une adresse particulière en plaçant une définition de la forme suivante, seule, sur ligne débutant par une espace :
␣[NOM] ADRESSE
Un lien pourra réutiliser cette adresse simplement en faisant
référence au nom sous la forme [TEXTE][NOM]. Le comportement est le
même que si vous aviez directement écrit [TEXTE](ADRESSE).
Un titre est créé en préfixant une ligne de signes =. Chaque signe
correspond à un niveau supplémentaire, un signe étant le niveau le
plus important, cinq, le niveau le moins significatif. Si un titre
occupe plus d’une ligne, les lignes suivantes doivent être préfixées
de deux espaces. De plus, un titre ne peut contenir que du texte.
Voici un exemple de structure de document, à l’aide de titres :
= Titre de premier niveau
== Titre de second niveau
...
== Un autre titre de second niveau
...
Une liste est obtenue simplement en préfixant la première ligne de
chaque élément par -␣ (un tiret suivi d’une espace) et en décalant
le corps de l’élément de deux espaces vers la droite, comme ceci :
- Premier élément.
Suite du premier élément.
- Second élément.
Le code précédent produira :
De même, il est possible d’obtenir des listes numérotées en préfixant la première ligne de chaque élément par un nombre suivi d’un point, comme ceci :
1. Premier élément.
Suite du premier élément.
2. Second élément.
Ce code produira :
Veuillez prendre note du fait que le décalage est toujours de deux espaces et non de trois.
Une étiquette de la forme : NOM : peut également être utilisée en
tant que préfixe pour produire des listes descriptives. Par exemple :
: Premier : Le premier.
: Second : Le Second.
Et la sortie correspondante :
Les tableaux en mdown sont très limités ; ils sont prévus pour présenter des informations succinctes, ligne par ligne. Les listes descriptives leur sont préférables lorsque le contenu dépasse une ligne de texte par ligne de tableau.
À l’heure actuelle, le format LaTeX ne supporte qu’une seule ligne de texte par ligne de tableau, et le format man ne reconnaît pas les tableaux du tout.
La syntaxe des tableaux est similaire à celle d’une liste simple en
substituant le tiret du preéfixe - par une barre verticale
|. Chaque élément représente alors une ligne du tableau. Les
cellules sont également séparées par des barres verticales.
Par exemple :
| L1C1 | L1C2 | L1C3
| L2C1 | L2C2 | L2C3
| L3C1 | L3C2 | L3C3
Ce code sera converti en un tableau comportant trois lignes et trois colonnes :
| L1C1 | L1C2 | L1C3 |
| L2C1 | L2C2 | L2C3 |
| L3C1 | L3C2 | L3C3 |
Vous pouvez également placer des paragraphes entiers ou d’autres éléments (y compris d’autres listes) dans une liste. Ceci ne s’applique pas aux tableaux.
Souvenez-vous que les paragraphes sont séparés par des lignes blanches. Si vous espacez vos éléments par des lignes vides, votre liste se traduira par une liste de paragraphes (et non simplement une liste d’éléments textuels).
Comparez l’exemple de liste numérotée précédent à celui-ci :
1. Premier élément.
Suite du premier élément.
2. Second élément.
Le code précédent produira :
Premier élément. Suite du premier élément.
Second élément.
Selon le format dans lequel vous lisez actuellement cette page, vous pourrez observer ou non l’espacement visuel supplémentaire entre les éléments. C’est principalement une caractéristique de la sortie XHTML.
Pour conclure sur les listes, examinons un exemple de liste complexe :
1. Un élément numéroté contenant une liste.
- La liste en question.
- Avec deux éléments.
2. Le second élément de la première liste.
Il contient deux paragraphes.
Ce code correspond à la liste suivante :
Un élément numéroté contenant une liste.
Le second élément de la première liste.
Il contient deux paragraphes.
Vous pouvez citer un autre document mdown en précédant chaque ligne du
texte à inclure de >␣ (un signe « supérieur à » suivi d’une espace).
Par exemple, ma maman a dit :
Manger des légumes, c’est bon pour la santé !
Pour inclure un bloc verbatim, il suffit de précéder chaque ligne par deux espaces. À l’intérieur d’un tel bloc, aucune syntaxe mdown n’est reconnue.
Vous reconnaîtrez par exemple le célèbre hello world ci-dessous :
#include <stdio.h>
int main(void)
{
printf("hello world\n");
return 0;
}
La dernière petite chose qu’il vous reste à connaître pour bien
commencer avec mdown est la syntaxe des commentaires. Les commentaires
sont des lignes débutant par le caractère %.
Pour des raisons de compatibilité, sachez cependant qu’un véritable
commentaire devrait débuter par %- et non simplement %. En effet,
% suivi d’un autre caractère est une séquence réservée au passage de
programmes tiers. De cette façon, il est possible d’inscrire dans un
fichier mdown des informations supplémentaires, utiles à la
publication ou la mise en page dans divers contextes.
Si vous avez le curiosité de regarder les sources de ce document, vous remarquerez la présence de telles directives tout au début ; celles-ci sont essentielles au bon fonctionnement de mon site internet.
Les commentaires sont entièrement ignorés par mdown, à partir du
caractère %. Cependant, le reste de la ligne, la marge sur la
gauche, n’est pas ignoré. Vous vous demandez sans doute ce que cela
apporte. Rappelez-vous que mdown reconnaît la limite des blocs par le
décalage de leurs lignes. Vous pouvez ainsi forcer mdown à terminer un
bloc en lui indiquant un décalage inférieur par un commentaire.
Comparez les deux codes suivants. Le premier produira une liste dont le second élément comporte deux paragraphes, tandis que le second en produira une liste suivie d’un bloc verbatim ! En effet, le commentaire qui s’est glissé entre les deux listes force mdown à mettre fin à l’élément de liste et considérer le texte qui suit par rapport au niveau du commentaire (qui n’est pas décalé).
Premier code :
- Pierre
- Paul
Jean
Second code :
- Pierre
- Paul
%-
Jean
Premier résultat :
Pierre
Paul
Jean
Second résultat :
Pierre
Paul
Jean
Un cas typique d’utilisation de cette astuce intervient lorsqu’une construction requérant que son contenu soit décalé (titre, liste, etc.) est suivi d’un bloc verbatim. Par exemple, le code suivant montre un titre suivi immédiatement d’un bloc verbatim :
= Un titre ici
%-
Du code ici.
Cette introduction touche maintenant à sa fin. Avec ce que vous avez appris, vous devriez être capable de rédiger des documents basiques. La syntaxe vous deviendra, je l’espère, rapidement familière ; si toutefois vous êtes pris d’un doute, n’hésitez pas à consulter la fiche de référence pour mdown.
D’autres articles à venir aborderons des thèmes plus spécifiques et des éléments plus avancés tels que les environnements. En attendant, vous pouvez lire la page man si l’anglais et un peu de théorie ne vous rebutent pas.