I. Qu'est-ce qu'une page de manuel ?

Tout système d'exploitation de type UNIX, s'accompagne d'une documentation riche et abondante appelée man pages (abréviation de « manual pages ») qui signifie dans la langue de Molière, pages de manuel. Le manuel, c'est votre bible. Ne vous contentez pas de l'observer, lisez! Familiarisez-vous avec l'anglais. L'anglais étant la langue dans laquelle sont publiées les pages de manuel et présente l'avantage d'être constamment à jour.

II. Comment puis-je lire une page de manuel ?

La commande utilisée pour lire une page de manuel est man. Son utilisation est relativement simple :

 
Sélectionnez
$ man <nom_page>

Par exemple, pour lire le manuel de la commande time :

 
Sélectionnez
$ man time

Pour faire défiler le texte, utiliser les flèches de direction de votre clavier et pour quitter l'aide, appuyer sur la touche q.

Les pages de manuel sont citées à l'aide de la notation "()", par exemple, TIME(1) et sont structurées en sections:

  1. General Commands
    Les commandes usuelles (utilisateur).
  2. System Calls
    Les appels systèmes (fonctions uname, chmod, etc et tout ce qui est lié à la gestion des erreurs - errno).
  3. Subroutines
    La documentation des fonctions des librairies (libc, openssl, perl, etc.).
  4. Special Files
    Fichiers spéciaux, périphériques via le répertoire /dev.
  5. File Formats
    Syntaxe et description des fichiers de configuration.
  6. Games
    Les jeux.
  7. Macros and Conventions
    Spécificités du système et divers (lien symbolique, ports/packages, etc.).
  8. Maintenance Commands
    Les commandes administrateur.
  9. Kernel Interface
    Fonctionnement interne du noyau (s'adresse plutôt aux développeurs).
  10. New Commands
    Les nouvelles commandes.

Le même nom d'une page de manuel peut apparaître dans plusieurs sections, c'est le cas de la commande, chmod.

Exemple :

 
Sélectionnez
$ man 1 chmod

ou

 
Sélectionnez
$ man 2 chmod

L'une affichera la documentation relative à la commande de shell, chmod(1) et l'autre concerne les appels systèmes, chmod(2).

III. À quoi ressemble une page de manuel formatée ?

A titre d'exemple, voici comment se présente la page de manuel de la commande time :

 
Sélectionnez
    TIME(1)                      OpenBSD Reference Manual                  TIME(1)

    NAME
        time - time command execution

    SYNOPSIS
         time [-lp] utility

    DESCRIPTION
         time executes and times utility. After the utility finishes, time writes
         the total time elapsed, the time consumed by system overhead, and the
         time used to execute utility to the standard error stream. Times are re-
         ported in seconds.

         The options are as follows:

         -l      The contents of the rusage structure are printed.

         -p      The output is formatted as specified by IEEE Std 1003.2-1992
                 (``POSIX.2'').

         The time utility exists as a built-in to most shells, although they may
         be syntactically different.  The utility described here is available as
         /usr/bin/time.

         The time utility shall exit with one of the following values:

         1-125   An error occurred in the time utility.
         126     The utility was found but could not be invoked.
         127     The utility could not be found.

         Otherwise, the exit status of time shall be that of utility.

    FILES
         /usr/include/sys/resource.h

    SEE ALSO
         csh(1), sh(1), getrusage(2)

    STANDARDS
         The time utility conforms to IEEE Std 1003.2-1992 (``POSIX.2'').

    HISTORY
         A time command appeared in Version 3 AT&T UNIX.

    BUGS
         The granularity of seconds on microprocessors is crude and can result in
         times being reported for CPU usage which are too large by a second.

    OpenBSD 4.1                      June 6, 1993                                1
    

Toutes les pages de manuels suivent une disposition commune structurée sous la forme de chapitres dont voici les principaux:

  • NAME
    Section concernant le nom de la fonction ou de la commande.
  • SYNOPSIS
    Usage.
  • DESCRIPTION
    Description générale.
  • EXAMPLES
    Exemples et suggestions.
  • SEE ALSO
    Références croisées et citations.

D'autres chapitres peuvent être présents, notamment:

  • RETURN VALUES
    Prototypes et descriptions des fonctions que l'on trouvent dans les sections deux et trois.
  • ENVIRONMENT
    Décrit les variables d'environnement.
  • FILES
    Fichiers associés au sujet.
  • DIAGNOSTICS
    Normalement utilisé pour la section 4, diagnostic des interfaces de périphériques.
  • ERRORS
    Sections deux et trois gestion d'erreur et de signal.
  • STANDARDS
    Conformité aux standards, si c'est applicable.
  • HISTORY
    Indique les dates importantes dans le développement du programme.
  • AUTHORS
    Les personnes ayant écrit le code et/ou la documentation.
  • CAVEATS
    Explications concernant des fonctionnalités souvent détournées, c'est-à-dire des conseils de sécurité vis-à-vis de certaines bibliothèques de fonctions.
  • BUGS
    Pièges et avertissements.
  • other
    Des entêtes personnalisés peuvent être ajoutés, à la discrétion de l'auteur.

Pour générer la page de manuel de time, voici le fichier source, time.1: (Source: OpenBSD source code)

 
Sélectionnez
    .\"	$OpenBSD: time.1,v 1.15 2007/05/31 19:20:17 jmc Exp $
    .\"	$NetBSD: time.1,v 1.5 1994/12/08 09:36:57 jtc Exp $
    .\"
    .\" Copyright (c) 1980, 1991, 1993
    .\"	The Regents of the University of California.  All rights reserved.
    .\"
    .\" Redistribution and use in source and binary forms, with or without
    .\" modification, are permitted provided that the following conditions
    .\" are met:
    .\" 1. Redistributions of source code must retain the above copyright
    .\"    notice, this list of conditions and the following disclaimer.
    .\" 2. Redistributions in binary form must reproduce the above copyright
    .\"    notice, this list of conditions and the following disclaimer in the
    .\"    documentation and/or other materials provided with the distribution.
    .\" 3. Neither the name of the University nor the names of its contributors
    .\"    may be used to endorse or promote products derived from this software
    .\"    without specific prior written permission.
    .\"
    .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
    .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    .\" SUCH DAMAGE.
    .\"
    .\"     @(#)time.1	8.1 (Berkeley) 6/6/93
    .\"
    .Dd $Mdocdate$
    .Dt TIME 1
    .Os
    .Sh NAME
    .Nm time
    .Nd time command execution
    .Sh SYNOPSIS
    .Nm time
    .Op Fl lp
    .Ar utility
    .Sh DESCRIPTION
    .Nm
    executes and
    times
    .Ar utility .
    After the
    .Ar utility
    finishes,
    .Nm
    writes the total time elapsed,
    the time consumed by system overhead,
    and the time used to execute
    .Ar utility
    to the standard error stream.
    Times are reported in seconds.
    .Pp
    The options are as follows:
    .Bl -tag -width Ds
    .It Fl l
    The contents of the
    .Em rusage
    structure are printed.
    .It Fl p
    The output is formatted as specified by
    .St -p1003.2-92 .
    .El
    .Pp
    The
    .Nm
    utility exists as a built-in to most shells,
    although they may be syntactically different.
    The utility described here is available as
    .Pa /usr/bin/time .
    .Pp
    The
    .Nm
    utility shall exit with one of the following values:
    .Pp
    .Bl -tag -width indent -compact
    .It 1\-125
    An error occurred in the
    .Nm
    utility.
    .It 126
    The
    .Ar utility
    was found but could not be invoked.
    .It 127
    The
    .Ar utility
    could not be found.
    .El
    .Pp
    Otherwise, the exit status of
    .Nm
    shall be that of
    .Ar utility .
    .Sh FILES
    .Bl -tag -width /usr/include/sys/resource.h -compact
    .It Pa /usr/include/sys/resource.h
    .El
    .Sh SEE ALSO
    .Xr csh 1 ,
    .Xr sh 1 ,
    .Xr getrusage 2
    .Sh STANDARDS
    The
    .Nm
    utility is compliant with the
    .St -p1003.1-2004
    specification.
    .Pp
    The flag
    .Op Fl l
    is an extension to that specification.
    .Sh HISTORY
    A
    .Nm
    command appeared in
    .At v3 .
    .Sh BUGS
    The granularity of seconds on microprocessors is crude and
    can result in times being reported for CPU usage which are too large by
    a second.
    

IV. Quelles macros puis-je utiliser ?

OpenBSD possède son propre ensemble de macros utilisé pour formater les pages de manuels appelé -mdoc.

Vu le nombre important de macros, je vous invite à lire:

 
Sélectionnez

    .\"	$OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
    .\"
    .\" The following requests are required for all man pages.
    .\"
    .\" Remove `\&' from the line below.
    .Dd $\&Mdocdate$
    .Dt NAME SECTION#
    .Os
    .Sh NAME
    .Nm program
    .Nd one line about what it does
    .Sh SYNOPSIS
    .\" For a program:  program [-abc] file ...
    .Nm program
    .Op Fl abc
    .Ar
    .Sh DESCRIPTION
    The
    .Nm
    utility processes files ...
    .\" The following requests should be uncommented and used where appropriate.
    .\" This next request is for sections 2, 3, and 9 function return values only.
    .\" .Sh RETURN VALUES
    .\" This next request is for sections 1, 6, 7 & 8 only.
    .\" .Sh ENVIRONMENT
    .\" .Sh FILES
    .\" .Sh EXAMPLES
    .\" This next request is for sections 1, 4, 6, and 8 only.
    .\" .Sh DIAGNOSTICS
    .\" The next request is for sections 2, 3, and 9 error and signal handling only.
    .\" .Sh ERRORS
    .\" .Sh SEE ALSO
    .\" .Xr foobar 1
    .\" .Sh STANDARDS
    .\" .Sh HISTORY
    .\" .Sh AUTHORS
    .\" .Sh CAVEATS
    .\" .Sh BUGS
	

V. Quelle présentation dois-je adopter ?

Quelques conseils incontournables pour obtenir une documentation de qualité :

  • Tester au fur et à mesure votre manuel surtout s'il est conséquent.

    Pour cela, utiliser la commande :

     
    Sélectionnez
    $ nroff -Tascii -mandoc time.1 | more
    

    ou

     
    Sélectionnez
    $ groff -Tascii -mandoc time.1 | more
    
  • Relisez-vous.
  • Vérifier l'orthographe.
  • Faites-vous relire.

VI. Comment puis-je obtenir ma page de manuel dans différents formats ?

Format texte :

 
Sélectionnez
$ nroff -mdoc time.1 | col -b > time.txt

Format PostScript :

 
Sélectionnez
$ nroff -Tps -mandoc time.1 > time.ps

ou

 
Sélectionnez
$ groff -Tps -mandoc time.1 > time.ps

Format HTML :

 
Sélectionnez
$ groff -Thtml -mandoc time.1 > time.html

Format TeX/LaTeX DVI :

 
Sélectionnez
$ groff -Tdvi -mandoc time.1 > time.dvi

VII. Remerciements

Je tiens à remercier Julp et Ovh pour la relecture attentive de cet article.