Écrire ma propre page de manuel sous OpenBSD

L'auteur

Olivier Regnier

L'article

Publié le 12 octobre 2007

Version PDF Version hors-ligne

ePub, Azw et Mobi

Liens sociaux

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.

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

Sélectionnez

$ man 2 chmod

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

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

À 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 trouve dans les sections 2 et 3.
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 2 et 3 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ées pour formater les pages de manuels appelées -mdoc.

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

Guide de référence dans mdoc(7) ;
Tutoriel dans mdoc.samples(7) ;
Template, dont voici le contenu : (Source: OpenBSD source code)

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é :

testez au fur et à mesure votre manuel surtout s'il est volumineux ;
Pour cela, utilisez 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

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.

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants :

Copyright © 2007 Olivier Regnier. Aucune reproduction, même partielle, ne peut être faite de ce site ni de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.