af83

Le retour des pages de man ?

Book Holder

Les pages de man sont un ensemble de manuels pour les commandes UNIX. Elles sont très utiles pour les personnes qui travaillent régulièrement avec la ligne de commande sous un UNIX, car elles permettent d'accéder facilement aux informations utiles. En effet, celles-ci sont placées dans une dizaine de sections et respectent toujours la même structure.

Par exemple, man 1 ls va afficher la page de man de la commande ls, le 1 servant à indiquer la section, en l'occurence les commandes utilisateur. On y trouve bien entendu des informations générales comme une courte description de la commande et le synopsis (ie comment l'appeler), mais également des informations beaucoup plus détaillées comme la liste des options et ce que fait chaque option.

Dans l'ensemble, les pages de man sont une solide source de documentation qui permet de retrouver très efficacement une information quand on sait se servir de man. Pourtant, les pages de man sont restées très liées aux commandes UNIX et n'ont jamais réussies à s'imposer dans d'autres domaines comme les gems Ruby ou les applications web. Il y a plusieurs raisons à ça :

  • La syntaxe Troff est relativement difficile et obscure, surtout quand on la compare à markdown ou textile.
  • Les développeurs ne connaissent pas forcément très bien la culture UNIX, et n'ont même pas envisagé la possibilité d'utiliser les pages de man pour leur documentation.
  • Les pages de man ne sont pas forcément très jolies et se lisent surtout dans des terminaux. Par exemple, l'absence d'une application graphique pour lire des page de man sous Mac OSX a peut-être repoussé certaines personnes.
  • L'export vers du HTML pour mettre cette documentation en ligne n'est pas toujours très concluant.

Mais il semblerait que les pages de man aient un regain d'activité. On voit ainsi surgir un certain nombre de projets visant à simplifier l'accès aux pages de man et leur écriture. Je voudrais mettre en avant 2 programmes qui me semblent particulièrement pertinents.

Le premier est gem-man : il permet d'accompagner les gem Ruby d'une page de man et fournit un moyen simple de les afficher. Par exemple, gem man 1 mustache affiche la page de man de la commande mustache fournit par le gem du même nom.

Le second, ronn, simplifie l'écriture d'une page de man en fournissant une syntaxe proche de Markdown. Il offre également la possibilité d'exporter la page de man en hTML pour la mettre en ligne. Je vous laisse comparer la version ronn de ronn(1) avec son équivalent troff, et regarder le résultat de l'export HTML.

Ça ne vous donne pas envie d'écrire de jolies pages de man ?

Mise à jour : Chris Wanstrath, aka defunkt, a publié un article sur le même sujet (en anglais) : man what.

blog comments powered by Disqus