MDOC(7)

NOM
mdoc - Guide de référence rapide pour l'ensemble de macros -mdoc

SYNOPSIS
groff -mdoc fichiers ...

DESCRIPTION
-mdoc est un ensemble de macros utilisées pour formater les pages de manuel BSD et basées sur le contenu et sur le domaine. Les noms des macros et leur signification sont listés ci-dessous pour une référence rapide ; pour une explication détaillée de l'utilisation du paquet, voir la page groff_mdoc(7).

Notez que ceci n'est pas l'ensemble de macros usuel pour la documentation sous Linux, bien qu'il soit utilisé pour la documentation de nombreux programmes largement utilisés ; voir man(7).

Les macros sont décrites en deux groupes. Le premier inclut les macros de mise en page structurelle et physique. Le second contient les macros de domaine manuel et texte qui différencient le paquet -mdoc d'autre systèmes de formatage troff.

DOMAINE DE STRUCTURE DE PAGES

  Macros de titre
Pour créer une page de manuel valide, les trois macros suivantes sont nécessaires, dans cet ordre :
.Dd   mois jour, année
    Date du document.
.Dt   TITRE_DOCUMENT [section] [volume]
    Titre, en majuscules.
.Os   SYSTÈME_D_EXPLOITATION [version/release]
    Système d'exploitation (BSD).

  Macros de mise en page
En-têtes de section, changements de paragraphe, listes, affichage.
.Sh En-têtes de section. En-têtes valides, par ordre de présentation :
    NAME
        Section de nom, doit en général inclure les macros ‘.Nm’ ou ‘.Fn’ ainsi que ‘.Nd’ (N.d.T. : à ce jour, le titre de cette section ne doit pas être traduit, sinon les en-têtes et pieds de page ne seront pas affichés).
    SYNOPSIS
        Utilisation.
    DESCRIPTION
        Description générale, devrait inclure les options et paramètres.
    RETURN VALUE (VALEUR DE RETOUR)
        Sections 2 et 3, appels de fonctions.
    ENVIRONMENT (ENVIRONNEMENT)
        Décrit les variables d'environnement.
    FILES (FICHIERS)
        Les fichiers associés au thème de la page.
    EXAMPLES (EXEMPLES)
        Exemples et suggestions.
    DIAGNOSTICS (DIAGNOSTIQUE)
        Utilisé en général pour la section 4, interface avec les périphérique.
    ERRORS (ERREURS)
        Sections 2 et 3, gestion des erreurs et signaux.
    SEE ALSO (VOIR AUSSI)
        Références croisées et citations.
    CONFORMING TO (CONFORMITÉ)
        Conformité aux normes, quand c'est le cas.
    HISTORY (HISTORIQUE)
        Si une norme n'est pas applicable, un historique du sujet devrait être donné.
    BUGS (BOGUES)
        Bogues et difficultés d'utilisation.
    autres
        Des en-têtes personnalisés peuvent être ajoutés, au choix des auteurs.
.Ss En-têtes de sous-section.
.Pp Coupure de paragraphe. Espace vertical d'une ligne.
.D1 (D-un) « Display-one ». Indenter et afficher une ligne de texte.
.Dl (D-ell) « Display-one literal ». Indenter et afficher une ligne de texte verbatim.
.Bd Début de bloc d'affichage. Options d'affichage :
    -ragged
        Non justifié.
    -filled
        Justifié.
    -literal
        Texte ou code verbatim.
    -file nom
        Lire dans le fichier indiqué, et afficher le contenu.
    -offset chaîne
        Afficher avec un décalage. Valeurs de chaîne autorisées :
        left
            Aligner le bloc à gauche (par défaut)
        center
            Marge centrale.
        indent
            Indentation de six espaces (une tabulation).
        indent-two
            Deux tabulations.
        right
            Bloc aligné à gauche, à deux pouces de la limite droite.
        xxn Où xx est un nombre entre 4n à 99n.
        Aa  Où Aa est le nom d'une macro appelable.
        chaîne
            La largeur de la string est utilisée.
.Ed Fin de bloc d'affichage (correspond à .Bd).
.Bl Début de liste. Crée des listes ou des colonnes. Options :
    Types de liste
        -bullet | Liste Énumération par puces
        -item | Liste sans étiquette
        -enum | Énumération
        -tag | Liste avec étiquette
        -diag | Liste pour le diagnostique
        -hang | Liste avec étiquette suspendue
        -ohang | Liste avec étiquette surplombante
        -inset | Liste avec étiquette incrustée
    Paramètres de liste
        -offset
            (Toutes les listes.) Consultez ‘.Bd’ ci-dessus.
        -width
            (Listes -tag et -hang seulement.) Consultez ‘.Bd’.
        -compact
            (Toutes les listes.) Supprimer les lignes blanches.
.El Fin de liste.
.It Élément de liste.

MACROS DES DOMAINES MANUEL ET TEXTE GÉNÉRIQUE
Les macros de manuel et de texte générique sont spéciales, dans le sens où la plupart d'entre elles sont analysée à la recherche d'autres macros « appelables », par exemple :

.Op Fl s Ar fichier
    Produit [-s fichier]

Dans cet exemple, la macro d'option ‘.Op’ est parsée, et appelle la macro de contenu appelable ‘-’ qui s'applique à l'argument ‘s’, puis appelle la macro de contenu appelable ‘file ...’ qui s'applique à l'argument ‘fichier’. Certaines macros sont appelables mais ne sont pas analysée, et vice-versa. Ces macros sont indiquées dans les colonnes analysée et appelable ci-dessous.

Sauf exception notée, les macros de manuels ont toutes la même syntaxe :

    .Va argument [ . , ; : ( ) [ ] argument ... ]

Note : Les caractères de ponctuation ouvrants et fermants ne sont reconnus que s'ils sont présents un à la fois. La chaîne ‘),’ n'est pas reconnue comme un signe de ponctuation, et est donc affichée précédée d'un espace, et dans la fonte utilisée par la macro appelante. La liste d'arguments ‘] ) ,’ est reconnue comme trois caractères de ponctuation fermants, et n'est donc pas précédée d'un espace. La signification particulière d'un signe de ponctuation peut être supprimée en le précédant par ‘\&’. Par exemple, la chaîne suivante

.Ar fichier1 , fichier2 , fichier3 ) .
    Donne fichier1, fichier2, fichier3).

  Macros du domaine manuel
Nom | Analysée | Appelable | Description
 | Oui | Oui | Adresse (cette macro peut être obsolète).
 | Oui | Oui | Nom de l'auteur.
file ... | Oui | Oui | Argument de ligne de commande.
 | Non | Non | Déclaration de configuration (uniquement section 4).
 | Oui | Oui | Modificateur d'argument de ligne de commande.
 | Oui | Oui | Variable définie (code source).
 | Oui | Oui | Code d'erreur (code source).
 | Oui | Oui | Variable d'environnement.
 | Oui | Oui | Argument d'une fonction.
Fd | Oui | Oui | Déclaration de fonction.
 | Oui | Oui | Appel de fonction (également .Fo et .Fc).
 | Oui | Oui | Commande interactive.
 | Oui | Oui | Texte verbatim.
mdoc | Oui | Oui | Nom de commande.
[| Oui | Oui | Option (également .Oo et .Oc).]
 | Oui | Oui | Type de fonction, ancien style (Fortran uniquement).
~ | Oui | Oui | Nom de fichier ou chemin.
 | Oui | Oui | Normes (-p1003.2, -p1003.1 ou -ansiC)
 | Oui | Oui | Nom de variable.
 | Oui | Oui | Type de variable (Fortran).
 | Oui | Oui | Référence à une page de manuel.

  Macros de texte génériques
Nom | Analysée | Appelable | Description
%A | Oui | Non | Auteur de la référence.
%B | Oui | Oui | Titre du livre référencé.
%C | Non | Non | Lieu (ville) de publication de la référence.
%D | Non | Non | Date de la référence.
%J | Oui | Oui | Titre du journal de la référence.
%N | Non | Non | Numéro de la référence.
%O | Non | Non | Information optionnelle sur la référence.
%P | Non | Non | Numéro(s) de page de la référence.
%R | Non | Non | Nom du rapport référencé.
%T | Oui | Oui | Titre de l'article référencé.
%V | Non | Non | Volume de la référence.
> | Oui | Oui | Angle fermant.
<| Oui | Oui | Angle ouvrant.
'| Oui | Oui | Apostrophe.
<| Oui | Oui | Met ses arguments entre deux angles.>
AT&T UNIX | Non | Non | UNIX AT&T
] | Oui | Oui | Crochet fermant.
Bf | Non | Non | Début de mode de police.
[| Oui | Oui | Crochet ouvrant.
[| Oui | Oui | Met ses arguments entre crochets.]
BSD | Oui | Oui | BSD.
Db | Non | Non | Débogage (par défaut, off)
” | Oui | Oui | Guillemet double fermant.
“| Oui | Oui | Guillemet double ouvrant.
“| Oui | Oui | Guillemet double.”
 | Oui | Oui | Fin d'entourage de chaîne.
Ef | Non | Non | Fin du mode police.
 | Oui | Oui | Emphase (anglais traditionnel).
 | Oui | Oui | Début d'entourage de chaîne.
FreeBSD | Non | Non | Système d'exploitation FreeBSD
 | Oui | Oui | Texte normal (no-op).
 | Oui | Oui | Pas d'espace.
) | Oui | Oui | Fermeture de parenthèse.
 | Oui | Non | Chaîne préfixe.
(| Oui | Oui | Ouverture de parenthèse.
(| Oui | Oui | Parenthèses.)
" | Oui | Oui | Guillemet double droit fermant.
‘| Oui | Oui | Texte verbatim entre guillemets.’
"| Oui | Oui | Guillemet double droit ouvrant.
"| Oui | Oui | Guillemets doubles droits."
Re | Non | Non | Fin de référence.
Rs | Non | Non | Début de référence.
Rv | Non | Non | Valeurs renvoyées (sections 2 et 3).
’ | Oui | Oui | Guillemet simple fermant.
‘| Oui | Oui | Guillemet simple ouvrant.
‘| Oui | Oui | Guillemet simple.’
Sm | Non | Non | Mode espace (par défaut, on)
 | Oui | Oui | Référence de section.
 | Oui | Oui | Symbolique (anglais traditionnel).
 | Oui | Oui | Nom de marque ou de type (petites majuscules).
UNIX | Oui | Oui | UNIX
 | Oui | Oui | Fin de liste d'arguments.
 | Oui | Oui | Début de liste d'arguments.

Les macros dont le nom finit par ‘q’ entourent les éléments restants dans la liste d'arguments. Les macros dont le nom finit par ‘o’ commencent une citation qui peut prendre plusieurs lignes, et qui est terminée par la macro correspondante dont le nom finit par ‘c’. Les macros de ce type peuvent être imbriquées et sont limitées à huit arguments.

Note : les macros de liste d'arguments étendues (‘.Xo’, ‘.Xc’) et les macros de fonction (‘.Fo’, ‘.Fc’) sont spéciales. Les macros de liste d'arguments étendues servent à dépasser la limite à neuf arguments imposée par troff.

Les macros UR (qui ouvre une référence hypertexte vers un URI ou URL), UE (qui la ferme) et UN (qui identifie la cible d'une référence) sont également disponibles. Consultez man(7) pour plus d'informations sur ces macros.

FICHIERS
doc.tmac
    Macros des domaines manuel et texte générique.
tmac/doc-common
    Macros et définitions structurelles communes.
tmac/doc-nroff
    Fichier de style nroff local.
tmac/doc-ditroff
    Fichier de style troff local.
tmac/doc-syms
    Définitions spéciales (comme les macros courantes).

VOIR AUSSI
groff_mdoc(7), mdoc.samples(7), man(7), man-pages(7)

COLOPHON
Cette page fait partie de la publication 3.40 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION
Cette traduction est maintenue à l'aide de l'outil po4a <URL:http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <URL:http://perkamon.alioth.debian.org/>.

Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».