%title          mdown
%keywords       projets/index
%groups         projets/mdown/index
%comment        Projet actif. Langage de rédaction léger.
%id             $Id: index.text,v 1.11 2008/09/13 10:39:29 minh Exp $


*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.(Extensible HyperText
Markup Language)(en) et le LaTeX.

Il sait aussi générer du ZCode, utilisé sur le [Site du
Zéro](http://siteduzero.com). Si vous en venez et souhaitez découvrir
mdown, je vous invite à lire [ce bref comparatif ZCode /
mdown](a:compar-zcode).

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.


%tableofcontents


= Une petite histoire    [hist]

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).


= Téléchargement et installation       [inst]

Vous pouvez télécharger la dernière version de mdown sous forme de
[sources](f:mdown-1.146.tgz) (révision n^o 1.146). 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.


== Installation sous unixoïde  [installunix]

Une fois l'archive récupérée, décompressez la dans un dossier, avec,
par exemple :

  $ tar xzf mdown-1.146.tgz

Déplacez vous dans le dossier ainsi créé :

  $ cd mdown-1.146

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

# Remarque

  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`.


== Installation sous Mac OS X   [installosx]

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.

# Remarque : La variable PATH

  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). En d'autre, terme, lorsque vous tapez une
  commande dans le +shell+(en), 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+(en) de s'en
  charger. Le +shell+(en) 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

# Remarque : Remerciements

  Les informations d'installation concernant Mac OS X ont été fournies
  par Metzgermeister et testées par Vinchz.


== Installation manuelle ou sur d'autres plateformes    [installautre]

Pour les plateformes ne possédant ni de +shell+(en) 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.


= Documentation et ressources   [doc]

Il est recommandé de commencer par lire cette [introduction
à mdown](a:intro). Vous pouvez également vous reporter à la [fiche de
référence](a:fiche) 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é.

%index


== `mdown-mode` pour Emacs        [mdownmode]

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)


== Des outils facilitant la publication sur le Site du Zéro     [pubsdz]

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 `make` pour 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 ;) .
>
> - [Lien de téléchargement](http://home.delroth.eu/tutosuite.tar.gz)
> - [Page officielle de mdown](http://rzpages.ovh.org/mdown.php5)


== Un Wiki utilisant mdown      [wiki]

*Mise à jour* : On dirait que le Wiki est mort...

Le site [IUWT](http://iuwt.fr/), maintenu par asmanur et Haveo,
utilise mdown. Récemment, ils ont ouvert un
[wiki](http://iuwt.fr/wiki/). Indépendamment de l'intérêt que vous
pourrez porter à +Urban Terror+(en), 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.(Common Gateway Interface)(en).

- [le site](http://iuwt.fr/) ;
- [le wiki](http://iuwt.fr/wiki/)
- [le bac à sable](http://www.iuwt.fr/wiki/Bac_%C3%80_Sable).


== Un projet de +blog+(en) utilisant mdown      [blog]

Le +Blog+(en) de l'Homme Moderne, codé en Erlang par Dark-Side &
lasts, utilisant mdown pour la rédaction et l'affichage des billets.

- [BHM](http://bhm.no-ip.org)


= Historique   [histo]

: [mdown 1.146](f:mdown-1.146.tgz) : +Bugfix release+(en) : juste un
  petit problème avec les flottants du ZCode. La doc a été mise à jour
  aussi, toujours pour le ZCode.

: [mdown 1.144](f:mdown-1.144.tgz) : 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+(en) `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+(en) pour produire un fichier
  .XML. conforme à ce que le .SdZ. attend dans Vos Tutos, lorsque
  celui-ci acceptera à nouveau les +uploads+(en) et que j'aurai le
  temps.

: [mdown 1.141](f:mdown-1.141.tgz) : Correction de bogues
  mineurs. Support d'environnements intrinsèques supplémentaires pour
  la sortie ZCode.

: [mdown 1.135](f:mdown-1.135.tgz) : 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.

: [mdown 1.134](f:mdown-1.134.tgz) : Support du ZCode
  amélioré (au niveau des espacements verticaux).

: [mdown 1.132](f:mdown-1.132.tgz) : 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.

: mdown 1.131 : 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).

: mdown 1.122 : Corrections de bogues.  Régularisation des espaces
  pour la sortie LaTeX.

: mdown 1.119 : 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.

: mdown 1.111 : Première distribution disponible sur l'Internet.

%-