Créer une page de manuel simple
Vous avez écrit un petit script ou une petite application bien pratique pour votre usage quotidien ? Si vous voulez partager cet utilitaire, ou tout simplement vous rappeler la manière dont on l'utilise, il va falloir écrire la documentation qui va avec. Et qui dit documentation sous UNIX, dit manuel !
Cet article vous aidera justement dans la conception de votre première page de manuel. Cependant, ne vous attendez pas à connaître les tenants et les aboutissants du manuel et du langage Troff (voir ici pour en savoir plus) : cet article a pour but de vous initier, mais ne va pas plus loin. Cependant, nous vous proposerons des liens en fin de page pour aller plus loin.
Une page de manuel
Avant de nous lancer tête baissée dans l'écriture d'un page de manuel, intéressons nous plutôt à quelques caractéristiques.
Une page de manuel appartient à une des huit sections suivantes :
1. Les commandes utilisateurs
2. les appels systèmes
3. les fonctions bibliothèques
4. les fichiers périphériques
5. les fichiers d'administrations
6. les jeux (ah !)
7. divers
8. les commandes d'administration
Une page de manuel est divisée en plusieurs parties : NAME, SYNOPSIS, DESCRIPTION, OPTIONSman <commande> pour s'en convaincre.
Pareillement, les caractéristiques d'un page de manuel abondent : mots en gras, mots soulignés, caractères entre crochets....
pour les principales. Mais sachez qu'il y a en bien d'autres, il suffit d'un
Notre première page
Voici en gros,à quoi ressemble une page de manuel.Nous reviendrons sur les éléments qui composent cette page après sa lecture.
Code : Autre
.Dd Date
.Dt TITRE_DU_DOCUMENT 1
.Sh NOM
nom - description tres courtes
.Sh SYSNOPSIS
commande [--option | --autre_option] cible
.Sh DESCRIPTION
C'est ici que nous decrirons en detail la commande.
Essayez d'être le plus clair possible.
.Pp
Pour cela nous pouvons utiliser plusieurs paragraphes
séparés par la balise que voyez au dessus.
.Sh AUTRES
Comme nous l'avons vu tout a l'heure,
une page peut contenir toutes sortes de parties.
Ceux qui utilisent LaTeX ne devraient pas trop être dépaysés !
Comme vous le voyez, la page est écrite à l'aide de balises qu'on appellent des macros troff.
Expliquons rapidement les quatre macros utilisées ici:
.Dd pour la date
Dt pour le titre du document. Le « 1 signifie que cette page de man appartient à la première section (Les commandes utilisateurs)
.Sh pour diviser en sections
.Pp pour diviser en paragraphes
Pour lire du texte en langage Troff, nous utiliseront l'utilitaire GNU-Troff:
« groff -Tascii -man fichier» générera la page fichier et permettra sa lecture.
A noter que groff est aussi capable de générer des pages dans d'autres formats.
Par exemple, « groff -Tps -man fichier » générera un fichier PostScript.
Un cas concret
J'ai pour l'occasion écrit un petit script Bash dont l'utilité est de lister dans un répertoire, les noms de fichiers qui contiennent des espaces, et de remplacer ces espaces par un «_».
Attention ce script mériterait d'être revu et amélioré, mais, il sera bien suffisant pour notre exemple.
Vous pouvez l'utiliser, le partager et le modifier comme bon vous semble !
Enregistrez ce script sous le nom : $HOME/bin/espace (créer le dossier bin au besoin)
Code : Bash
#!/bin/bash
# espace - supprime les espaces dans les noms de fichiers
# usage : espace [-l|-f|-c] direction
########################LES OPTIONS#########################
#-l : liste les noms de fichier avec au moins un espace #
#-c : pareil que l'option -l, puis demande si l'on remplace#
#les espaces par des "_" #
#-f :remplace sans confirmation #
#pas d'option = -l #
#############################################################
# David LEGRAND : david.legrand.charente@gmail.com
##Gestion des erreurs
erreur_1()
{
echo "Je ne comprends pas ce que vous voulez !"
echo "Usage : espace [-l|-f|-c] direction"
echo
exit 1
}
erreur_2()
{
echo "le chemin n'est pas bon"
echo
exit 2
}
## vérification des paramètres
echo
case $# in
0)
erreur_1 ;;
1)
dir="$1"
option="liste" ;;
2)
case $1 in
"-l") option="liste";;
"-c") option="confirme";;
"-f") option="force";;
*) erreur_1;;
esac
dir="$2" ;;
*) erreur_1 ;;
esac
[ -d $dir ] || erreur_2
##La commande s'exécute
case $option in
liste)
ls $dir | sed -n -e '/ /p'
echo ;;
confirme)
ls $dir | sed -n -e '/ /p'
echo "On remplace ?"
read reponse
case $reponse in
O | o | Y | y)
rename "s/ /_/g" $dir/*
# il faudra gérer les erreurs (ex: nom deja pris,...)
echo ;;
*) ;;
esac ;;
force)
rename "s/ /_/g" $dir/*
echo
# il faudra gérer les erreurs
;;
esac
exit 0
Écrivons sur le champ la page Troff qui va bien :
Code : Autre
.Dd 11 mars 2009
.Dt ESPACE 1
.Sh NOM
espace - gere les espaces dans les noms de fichiers
.Sh SYNOPSIS
espace [-l | -c | -f] dossier
.Sh DESCRIPTION
espace permet de lister et/ou de supprimer les espaces dans
le nom des fichiers du dossier cible.
.Sh OPTIONS
-l
Liste dans un dossier, les noms de fichiers contenants au moins
un espace.
.Pp
-c
Liste dans un dossier, les noms de fichiers contenant un espace,
puis propose de les remplacer par un '_'
.Pp
-f
Remplace les espaces sans confirmation.
.Sh FICHIERS
$HOMES/bin/espace
.Sh AUTHEUR
David LEGRAND : david.legrand.charente@gmail.com
Enregistrez ce fichier sous le nom : /usr/local//man/man1/espace.1
Maintenant pour tester son accès :
Code : Console
# gzip /usr/local/man/man1/espace.1
# MANPATH=/usr/share/man:/usr/local/man
# export MANPATH
$ man espace
NOM
espace - gere les espaces dans les noms de fichiers
SYNOPSIS
espace [-l | -c | -f] dossier
DESCRIPTION
espace permet de lister et/ou de supprimer les espace
dans le nom des fichiers du dossier cible.
OPTIONS
-l Liste dans un dossier, les noms de fichiers contenant
un espace.
-c Liste dans un dossier, les noms de fichiers contenant
un espace, puis propose de les remplacer par un '_'
-f Remplace les espaces sans confirmation.
FICHIERS
$HOMES/bin/espace
AUTHEUR
David LEGRAND : david.legrand.charente@gmail.com
Si cette page vous convient, ajoutez la à l'index avec la commande (makewhatis /usr/local/man) sous Fedora par exemple et avec mandb sous Ubuntu/Debian.
Quelques macros de mise en forme :
Mettre le texte en gras : .B
En gras et en roman : .BR
Mettre le texte en italique : .I
En italique et en roman : .IR
Un commentaire : ."
Pour aller plus loin
Les pages de man : man(1), man(7), man2htlm(1), mdoc.samples(7), mandb(8), makewhatis(8), groff(1), groff_tmac(5), groff_man(7), groff_mdoc(7)
Commentaires