Unix - Lire le synopsis d'un man

Le synopsis d'un man, c'est la partie d'une page de manuel appelée avec la commande man qui décrit l'usage d'une ligne de commande sur un shell.

Ce n'est pas toujours évident de lire le synopsis d'un man. Tous n'expliquent pas de la même façon l'organisation des options.
Heureusement, on leur trouve des points communs majeurs.

Généralement, les pages de man utilisent les crochets pour délimiter un bloc optionnel.

Exemple avec le synopsis de "man lynx" :

Lynx [options] [path or URL]

Au moins, celui-ci est clair et intuitif, et vous épargnera des grognements devant l'écran ... En fait, ce synopsis s'apparente plutôt à la partie "usage" d'un man.
On indique donc d'abord les options (qui sont signalées plus loin dans le man), puis le chemin vers un fichier ou répertoire, ou bien une url. Par exemple:

lynx -color [www.commentcamarche.net]

pour afficher la page d'acceuil de CCM en couleur.

A priori, jusque là, tout va bien.
Maintenant, on retrouve souvent les options possibles dans le synopsis. Et on a souvent le choix entre plusieurs alternatives pour un même argument :
_Une option courte de type -f ou -a etc...
_Une option longue de type "--force"

Donc dans un même bloc, vous pourrez trouver ces deux alternatives séparées par un "pipe", c'est à dire le caractère | qui signifie "ou".
Donc par exemple :

commande [-f | --force] [filename]

Pour dire que vous pouvez taper -f ou --force, au choix car ces deux arguments auront le même sens. Puis vous pouvez faire suivre cette option par un espace puis le chemin vers un fichier.

Avec ça, le synopsis de "man mysql" devrait être clair par exemple

Vous remarquerez quelques exceptions :
Pour [-p[pwd]] vous avez un bloc à l'intérieur d'un bloc, et sans espace pour les séparer.
Ca signifie que vous pouvez taper le mot de passe (optionnel, vous pouvez ne pas en avoir) juste après l'argument -p (optionnel lui aussi) sans espace.
Exemple pour une connexion à une base mysql locale avec l'utilisateur root, et le password bidule :

mysql -u root -pbidule -h localhost

Puis il y'a des synopsis un peu plus compliqués comme celui de tar

Là, les | pour signifier "ou" sont parfois remplacés par des virgules.
Les commandes majeures sont signalées au début, commençant par un [-] pour préciser que les arguments courts peuvent (optionnel) prendre un tiret, puis vient le gros bloc.
Vous avez le choix entre -A (que vous pouvez remplacer par --catenate ou --concatenate) ou -c ou -x etc.... Ce sont les commandes majeures de tar qui sont "extraire", "créer une archive" ... Donc vous devez choisir une seule commande majeure, c'est pourquoi il ya un | entre chaque.

Ensuite vous êtes libre d'ajouter une option, puis vous devez mettre un fichier (ou plusieurs) ou bien un repertoire.
Grossièrement ça ressemble à ceci pour extraire un fichier .tar.gz:

tar -zxvf machin.tar.gz

x est l'option majeure (extraire), les options sont z, v et f, respectivement: compressé avec gzip, verbal (afficher les détails), et f pour fichier (le flux à extraire sera un fichier).

Source et informations plus complètes Ce document intitulé « Unix - Lire le synopsis d'un man » issu de CommentCaMarche (www.commentcamarche.net) est mis à disposition sous les termes de la licence Creative Commons. Vous pouvez copier, modifier des copies de cette page, dans les conditions fixées par la licence, tant que cette note apparaît clairement.