mdown est un petit programme écrit en C, dont je suis l’auteur. Il permet de convertir des documents écrits dans une syntaxe proche du texte naturel en divers formats, dont le XHTML et le LaTeX.
Il sait aussi générer du ZCode, utilisé sur le Site du Zéro. Si vous en venez et souhaitez découvrir mdown, je vous invite à lire ce bref comparatif ZCode / mdown.
Il est utilisé pour l’écriture de l’intégralité des pages de ce site ; c’est même là sa raison première d’existence. Vous pouvez voir la source de chaque page, écrite en mdown, en suivant le lien « source » dans la rubrique « Formats alternatifs », en bas de celle-ci.
mdown est né d’un besoin tout à fait personnel d’un langage qui pourrait me servir dans la rédaction de documents aussi divers que des pages web et des pages man. Le langage est donc établi sur une base purement utilitaire. Il ne se fonde sur aucun concept général et n’est pas uniforme pour deux sous ; ses points forts sont d’être simple et pratique.
Bien sûr, de tels langages existent déjà. Pourquoi donc me suis-je donné la peine d’en créer encore un autre ? La raison, toute simple, est que je ne souhaitais dépendre que du C (de l’ANSI-C, pas du GNU C ou autre fantaisie que certains appellent injustement C). De plus, je voulais pouvoir aisément modifier par moi-même la mécanique interne afin d’y introduire les fonctionnalités désirées et la prise en charge de formats spécifiques (tels que le ZCode).
Vous pouvez télécharger la dernière version de mdown sous forme de sources (révision no 1.144). Comme précisé plus haut, les sources sont écrites en pur ANSI-C. N’importe quel compilateur à peu près récent fera donc l’affaire.
Une fois l’archive récupérée, décompressez la dans un dossier, avec, par exemple :
$ tar xzf mdown-1.144.tgz
Déplacez vous dans le dossier ainsi créé :
$ cd mdown-144
L’installation en elle-même se fait en utilisant make :
$ make install
Cette étape requiert un compilateur ANSI-C ainsi que l’utilitaire install (disponible entre autres avec les divers utilitaires GNU ou BSD).
Par défaut, l’installation tentera de placer les fichiers dans
/usr/local. Vous pouvez spécifier un autre préfixe (par exemple
$HOME/local) en affectant un chemin à la variable make PREFIX. Par
exemple :
$ make PREFIX=$HOME/local install
N’oubliez pas de vous connecter en root (avec su ou sudo,
traditionnellement) pour installer dans des dossiers réservés tels
que /usr/local.
Mac OS X se comporte à peu près comme les autres dérivés du monde Unix, mais la configuration de base diffère légèrement. Pour compiler, tout d’abord, il vous faudra GCC et un make, que vous pouvez obtenir par le biais d’XCode.
Ensuite, suivez la démarche expliquée ci-dessus pour les unixoïdes. La
dernière étape consiste à ajouter le dossier où le binaire a été
installé à votre PATH, si ce n’est pas déjà fait.
Si vous ne le savez pas, PATH est la variable d’environnement (en
quelque sorte globale à votre système) qui contient les dossiers des
exécutables directement accessibles sous forme de commande, dans
votre shell. En d’autre, terme, lorsque vous tapez une
commande dans le shell, celui-ci recherchera un binaire avec
ce nom dans l’un des dossiers indiqué dans PATH.
Les chemins sont séparés par des ':', dans cette variable. Par
exemple :
/usr/local/bin:/usr/bin:/bin
Tout d’abord, faites afficher le contenu de la variable PATH comme
ceci :
$ echo $PATH
Si vous pouvez y lire /usr/local/bin à un endroit ou un autre,
vous n’avez plus rien à faire.
Sinon, il s’agit de modifier la valeur de la variable PATH au
démarrage de votre session ; c’est au shell de s’en
charger. Le shell par défaut étant bash, il faut éditer le
fichier .bashrc situé dans votre dossier personnel.
Rajoutez dans votre .bashrc, en fin de fichier, la ligne
suivante :
PATH="/usr/local/bin:$PATH"
N’oubliez pas de rafraîchir votre environnement en rechargeant le
fichier .bashrc :
. $HOME/.bashrc
Les informations d’installation concernant Mac OS X ont été fournies par Metzgermeister et testées par Vinchz.
Pour les plateformes ne possédant ni de shell ni de make décent,
ou si pour une raison ou pour une autre vous voulez compiler mdown
manuellement, vous devez compiler le fichier mdown.c vous-même
à l’aide du compilateur de votre choix.
N’oubliez pas ensuite de placer le binaire à un endroit accessible par
la ligne de commandes, c’est-à-dire référencé par la variable
d’environnement PATH.
Pour obtenir la page man au format XHTML, exécutez ensuite, dans une console l’équivalent de la commande suivante :
$ mdown -o man.html man.text
Le fichier à produire se nomme ici man.html et, quoique incomplet
dans sa structure XHTML, il est tout à fait lisible par un
navigateur moyen.
Il est recommandé de commencer par lire cette introduction à mdown. Vous pouvez également vous reporter à la fiche de référence pour un aperçu rapide de la syntaxe.
La documentation complète, présente sous forme de page man n’est disponible qu’en anglais. Elle est générée sous plusieurs formats lors de l’installation, et, si vous êtes sous un unixoïde, une copie au format *roff/man est automatiquement installée sur votre système, sous le préfixe spécifié.
mdown-mode pour Emacs
Un mode mdown pour Emacs est en cours de développement par
Asgeir. Vous pouvez trouver les sources et la documentation propre au
mode à l’adresse suivante :
http://hommetrebar.free.fr/divers/mdown-mode.html
Voici le message d’annonce, par delroth, le créateur de ces scripts, reproduit verbatim avec son autorisation :
Bonjour tout le monde !
Je crée ce topic ici pour vous présenter un script, ou plutôt un ensemble de script, nommé TutoSuite. Cet outil a pour vocation de rassembler plusieurs outils existants pour créer des tutoriels sur le Site du Zéro, et de les uniformiser de manière très simple.
Bien entendu, venant de moi, les outils présents sont pour la plupart écrits en Python et sous licence GNU GPLv3, qui vous permet ainsi de les modifier et de les adapter à vos besoins ;) .
Voyons maintenant les fonctionnalités de TutoSuite : tout d’abord, le langage zCode n’étant clairement pas adapté à l’écriture de longs textes comme des tutoriels, les tutoriels seront écrits en langage mdown, dont un traducteur vers le zCode a été programmé par rz0. Ces textes mdown étant traduits en zCode, il est nécessaire de les convertir en un fichier .tuto XML exportable vers le Site du Zéro, vers ZAP ou vers le site des zCorrecteurs. Pour cela, on utilise l’outil maketuto.py, très facilement configurable via le fichier .mktutrc. Ensuite, le tutoriel pourra être envoyé vers le Site du Zéro via l’utilisation de mon script tutoimporter.py pour ainsi éviter les copier-coller longs et fastidieux. J’ai également programmé un utilitaire générant un fichier Makefile automatisant la compilation des fichiers mdown en zCode et des fichiers zCode en tutoriel :) .
Pour l’utiliser, c’est très simple : il vous suffit de récupérer l’archive disponible ici : http://home.delroth.eu/tutosuite.tar.gz, et d’y placer les fichiers dans le répertoire où vous voulez créer votre tutoriel. Ensuite, modifiez le fichier .mktutrc pour l’adapter à vos besoins (la syntaxe est très simple, je n’ai pas pris le temps de la documenter). Vous pouvez ensuite lancer le script makefile.py, qui vous générera un fichier Makefile. Lancez ensuite
makepour récupérer un joli tutoriel en sortie :) .Il est cependant nécessaire d’avoir mdown installé pour utiliser ce script. Les instructions d’installation et d’utilisation de mdown peuvent être trouvées sur le site de rz0 qui a une page consacrée à la question : http://rzpages.ovh.org/mdown.php5 . Python est aussi nécessaire, et GNU make est un plus si vous voulez pouvoir utiliser le Makefile (ce qui n’est pas en soi obligatoire, mais tellement plus pratique).
L’utilisation de ce script permet un gain de temps énorme au niveau du temps de rédaction d’un tutoriel sachant que le mdown est un langage se prenant très rapidement en main et très proche de la syntaxe naturelle. Il permet également un gain de productivité énorme par rapport à la syntaxe XML du zCode. De plus, la séparation en plusieurs fichier permet très facilement d’utiliser un gestionnaire de version et d’écrire un tutoriel à plusieurs de manière très aisée :) .
Have fun en utilisant TutoSuite, et oubliez pas qu’un petit mot de remerciement en bas d’un tutoriel ne fais jamais de mal ;) .
Le site IUWT, maintenu par asmanur et Haveo, utilise mdown. Récemment, ils ont ouvert un wiki. Indépendamment de l’intérêt que vous pourrez porter à Urban Terror, il constitue un bon endroit où tester mdown en ligne, en attendant que j’aie le temps de coder mdown-2 et sa version CGI.
Meilleur support du ZCode : notamment, les espacements verticaux entre les puces sont maintenant semblables à ceux entre les autres blocs.
J’ai également inclus un fichier tags tutozcode.tags que
vous pouvez utiliser (en le passant en argument à l’option -T)
pour produire des fichiers en ZCode plus adaptés à un tutoriel ; le
changement principal est que les niveaux de titres sont décalés (le
second niveau vaut <titre1>, etc.), ce qui vous permet
d’utiliser les titres de niveau 1 pour délimiter les parties de
votre tuto.
Je ferai sûrement un fichier tags pour produire un fichier XML conforme à ce que le SdZ attend dans Vos Tutos, lorsque celui-ci acceptera à nouveau les uploads et que j’aurai le temps.
Correction de bogues mineurs. Support d’environnements intrinsèques supplémentaires pour la sortie ZCode.
Correction d’un bogue qui faisait que mdown ne prenait pas en compte les environnements intrinsèques correctement. Modification légère de la syntaxe des acronymes : ceux-ci doivent maintenant débuter par un caractère non blanc qui n’est pas un caractère de ponctuation.
Support du ZCode amélioré (au niveau des espacements verticaux).
Petite mise à jour qui corrige un bogue qui faisait que mdown ne transformait pas les URL des images selon les règles d’URL personnalisées.
Changements de syntaxe incompatibles avec les versions
précédentes : ajout d’un support pour les acronymes/sigles et d’un
marquage pour les locutions étrangères et latines ; suppression de
la sémantique de ' et " qui sont maintenant des caractères
normaux. Pour plus de détails sur les raisons, voyez la page man.
Et bien sûr, comme toutes les autres versions, elle apporte son lot de corrections de bogues (principalement des implantations incomplètes de fonctionnalités dans certaines parties du programme).
Corrections de bogues. Régularisation des espaces pour la sortie LaTeX.
Ajout du support des liens personnalisés, un peu à la
manière des environnements. Il est maintenant possible d’écrire
[](wpfr:article) pour faire référence à un article de la
Wikipédia. Cette fonctionnalité n’est bien sûr pas limitée aux liens
vers la Wikipédia, c’est, en vérité, un module de réécriture des
liens simple qui vous permettra d’implanter les raccourcis qui
conviennent à votre travail.
Cette version corrige également un problème qui estropiait un paragraphe débutant par un nombre en le méprenant pour le début d’un élément de liste ordonnée.
Première distribution disponible sur l’Internet.