help2man-fr.info

   1 This is help2man-fr.info.tmp, produced by makeinfo version 6.7 from
   2 help2man-fr.texi.
   3
   4 Ce fichier documente la commande GNU ‘help2man’ qui produit de simples
   5 pages de manuel à partir de la sortie d’autres commandes avec les
   6 options ‘--help’ et ‘--version’.
   7
   8    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
   9 2011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation, Inc.
  10
  11    Produire et distribuer des copies conformes de ce manuel est permis à
  12 condition que la présente notice de droit d’auteur et la présente notice
  13 d’autorisation soient préservées sur toutes les copies.
  14
  15    Copier et distribuer des versions modifiées de ce manuel est permis
  16 selon les conditions d’une copie conforme, à condition que le travail
  17 dérivé résultant soit entièrement distribué selon les termes d’une
  18 notice d’autorisation identique à celle-ci.
  19
  20    Copier et distribuer des traductions de ce manuel dans d’autres
  21 langues est permis, selon les conditions pour versions modifiées
  22 ci-dessus, sauf que cette notice d’autorisation peut être déclarée sous
  23 forme d’une traduction approuvée par la Free Software Foundation.
  24 INFO-DIR-SECTION Développement du logiciel
  25 START-INFO-DIR-ENTRY
  26 * help2man-fr: (help2man-fr).  Création automatique de page de manuel.
  27 END-INFO-DIR-ENTRY
  28
  29 \1f
  30 File: help2man-fr.info.tmp,  Node: Top,  Next: Vue d’ensemble,  Up: (dir)
  31
  32 ‘help2man’
  33 **********
  34
  35 ‘help2man’ produit de simples pages de manuel à partir de la sortie
  36 d’autres commandes avec les options ‘--help’ et ‘--version’.
  37
  38 * Menu:
  39
  40 * Vue d’ensemble::             Vue d’ensemble de ‘help2man’.
  41 * Appeler help2man::             Façons d’exécuter ‘help2man’.
  42 * Recommandations pour --help::  Formatage recommandé pour la sortie
  43                                    avec‘--help’.
  44 * Texte inclus::                 Inclusion de texte supplémentaire dans
  45                                    lasortie.
  46 * Utilisation de Makefile::      Utilisation de ‘help2man’ avec‘make’.
  47 * Pages de manuel traduites::    Production de pages de manuel dans la
  48                                    languematernelle.
  49 * Exemple::                      Exemple de sortie de ‘help2man’.
  50 * Signalements::                 Signaler des bogues ou des
  51                                    suggestions.
  52 * Disponibilité::               Obtention de ‘help2man’.
  53
  54 \1f
  55 File: help2man-fr.info.tmp,  Node: Vue d’ensemble,  Next: Appeler help2man,  Prev: Top,  Up: Top
  56
  57 1 Vue d’ensemble de ‘help2man’
  58 ******************************
  59
  60 ‘help2man’ est un outil pour créer automatiquement de simples pages de
  61 manuel à partir de la sortie d’un programme.
  62
  63    Bien que les pages de manuel soient facultatives pour les programmes
  64 GNU, d’autres projets comme Debian les exigent (*note (standards)Man
  65 Pages::).
  66
  67    Ce programme est destiné aux auteurs de logiciels.  Il a pour but de
  68 simplifier l’inclusion d’une page de manuel dans leur distribution sans
  69 avoir à maintenir ce document.
  70
  71    À partir d’un programme qui produit des sorties pour ‘--help’ et
  72 ‘--version’ suffisamment standard, ‘help2man’ peut réarranger cette
  73 sortie en quelque chose qui ressemble à une page de manuel.
  74
  75 \1f
  76 File: help2man-fr.info.tmp,  Node: Appeler help2man,  Next: Recommandations pour --help,  Prev: Vue d’ensemble,  Up: Top
  77
  78 2 Façons d’exécuter ‘help2man’
  79 ******************************
  80
  81 La forme pour exécuter le programme ‘help2man’ est :
  82
  83      help2man [OPTION]... EXÉCUTABLE
  84
  85    ‘help2man’ reconnaît les options suivantes :
  86
  87 ‘-n CHAÎNE’
  88 ‘--name=CHAÎNE’
  89      Utiliser CHAÎNE comme description du paragraphe ‘NOM’ de la page de
  90      manuel.
  91
  92      Par défaut (en absence de mieux), ce paragraphe contient ‘Page de
  93      manuel de PROGRAMME VERSION’.
  94
  95      Cette option écrase une section ‘[name]’ de fichier d’inclusion
  96      (*note Texte inclus::).
  97
  98 ‘-s SECTION’
  99 ‘--section SECTION’
 100      Utiliser SECTION comme section de la page de manuel.  La section
 101      par défaut est 1.
 102
 103 ‘-m MANUEL’
 104 ‘--manual=MANUEL’
 105      Définir le nom de la section du manuel à SECTION, utilisé comme un
 106      en-tête centré pour la page de manuel.  Par défaut, ‘Commandes’ est
 107      utilisé pour les pages de la section 1, ‘Jeux’ pour la section 6 et
 108      ‘Utilitaires d'administration système’ pour les sections 8 et 1M.
 109
 110 ‘-S SOURCE’
 111 ‘--source=SOURCE’
 112      La source du programme est utilisée en pied de page et contient
 113      souvent le nom de l’organisation ou un ensemble dont le programme
 114      fait partie.  Par défaut, la valeur est le nom du paquet et la
 115      version.
 116
 117 ‘-L LOCALE’
 118 ‘--locale=LOCALE’
 119      Définir les paramètres régionaux (‘C’ par défaut).  À la fois le
 120      programme et ‘help2man’ doivent prendre en charge la LOCALE donnée
 121      (*note Pages de manuel traduites::).
 122
 123 ‘-i FICHIER’
 124 ‘--include=FICHIER’
 125      Inclure le matériel du FICHIER (*note Texte inclus::).
 126
 127 ‘-I FICHIER’
 128 ‘--opt-include=FICHIER’
 129      Une variante de ‘--include’ à utiliser dans les règles de motif
 130      Makefile qui ne doivent pas nécessiter que FICHIER existe.
 131
 132 ‘-o FICHIER’
 133 ‘--output=FICHIER’
 134      Envoyer la sortie vers FICHIER au lieu de ‘stdout’.
 135
 136 ‘-p TEXTE’
 137 ‘--info-page=TEXTE’
 138      Nom du manuel Texinfo.
 139
 140 ‘-N’
 141 ‘--no-info’
 142      Supprimer l’inclusion d’un paragraphe ‘VOIR AUSSI’ dirigeant le
 143      lecteur vers la documentation Texinfo.
 144
 145 ‘-l’
 146 ‘--libtool’
 147      Supprimer le préfixe ‘lt-’ des instances du nom de programme dans
 148      le synopsis (‘libtool’ crée des scripts enveloppe dans le
 149      répertoire de construction qui invoquent ‘toto’ comme
 150      ‘.libs/lt-toto’).
 151
 152 ‘--help’
 153 ‘--version’
 154      Afficher l’aide ou des informations de version.
 155
 156    Par défaut, ‘help2man’ passe les options standards ‘--help’ et
 157 ‘--version’ à l’exécutable, mais des alternatives peuvent être indiquées
 158 en utilisant les options suivantes.
 159
 160 ‘-h OPTION’
 161 ‘--help-option=OPTION’
 162      Chaîne pour l’option d’aide.
 163
 164 ‘-v OPTION’
 165 ‘--version-option=OPTION’
 166      Chaîne pour l’option de version.
 167
 168 ‘--version-string=CHAÎNE’
 169      Chaîne de version.
 170
 171 ‘--no-discard-stderr’
 172      Inclure la sortie d’erreur standard lors de l’analyse de la sortie
 173      d’option.
 174
 175 \1f
 176 File: help2man-fr.info.tmp,  Node: Recommandations pour --help,  Next: Texte inclus,  Prev: Appeler help2man,  Up: Top
 177
 178 3 Recommandations pour ‘--help’
 179 *******************************
 180
 181 Voici quelques recommandations pour ce qui devrait faire partie de la
 182 sortie avec ‘--help’.  Les intégrer augmente la probabilité pour
 183 ‘help2man’ de créer une page de manuel qui se respecte, afin de servir
 184 directement aux utilisateurs.
 185
 186    Consultez *note (standards)Command-Line Interfaces:: et *note
 187 (standards)Man Pages:: pour les normes officielles de GNU à propos de
 188 ‘--help’ et des pages de manuel.
 189
 190    • Un synopsis de la façon d’invoquer le programme.  Si plusieurs
 191      utilisations différentes du programme ont différentes invocations,
 192      alors elles doivent être toutes indiquées.  Par exemple (modifié
 193      par brièveté) :
 194
 195           Utilisation : cp [OPTION]... SOURCE DEST
 196                    ou : cp [OPTION]... SOURCE... DIRECTORY
 197           ...
 198
 199      Utiliser ‘argv[0]’ pour le nom de programme dans ces synopsis,
 200      simplement tel qu’il est, sans supprimer de répertoire.  C’est en
 201      contraste avec le nom canonique (constant) du programme qui est
 202      utilisé dans ‘--version’.
 203
 204    • Une très brève explication de ce que fait ce programme, y compris
 205      les comportements par défaut ou typique.  Par exemple, voici celle
 206      de ‘cp’ :
 207
 208           Copier la SOURCE vers DEST, ou plusieurs SOURCEs vers DIRECTORY.
 209
 210    • Une liste d’options, indentées par deux espaces.  Si le programme
 211      prend en charge les options monocaractères, elle est en premier,
 212      suivie de l’option longue équivalente (s’il y en a).  Si l’option
 213      accepte un argument, l’inclure aussi avec un nom significatif.
 214      Aligner éventuellement la description dans une colonne pratique.
 215      Remarquez que pour être correctement reconnue par ‘help2man’, la
 216      description doit être séparée d’au moins deux espaces et les
 217      descriptions continuant sur les lignes suivantes doivent commencer
 218      sur la même colonne.
 219
 220      Voici encore un extrait (modifié) de ‘cp’, montrant une option
 221      courte avec une option longue équivalente, une option longue seule
 222      et une option courte seule :
 223
 224             -a, --archive                identique à -dR…
 225                 --backup[=CONTROL]       archiver chaque…
 226             -b                           comme --backup mais…
 227
 228      Pour les programmes avec de nombreuses options, séparer la liste
 229      d’options en sections comme ‘Globales’, ‘Contrôle de sortie’ ou
 230      tout ce qui a du sens dans ce cas particulier peut être pratique.
 231      Ordonner alphabétiquement (par nom d’option courte d’abord, puis
 232      long) est généralement préférable à l’intérieur de chaque section
 233      ou pour la liste entière en absence de section.
 234
 235    • Tous les renseignements supplémentaires sur le comportement du
 236      programme, comme les variables d’environnement influentes, des
 237      explications supplémentaires sur les options, etc.  Par exemple,
 238      ‘cp’ discute de ‘VERSION_CONTROL’ et des fichiers dispersés.
 239
 240    • Quelques exemples d’utilisation typique, suivant les cas.  Un bon
 241      exemple vaut souvent un millier de mots de description, donc c’est
 242      sérieusement recommandé.
 243
 244    • Enfin, une ligne déclarant comment envoyer des rapports de bogue.
 245      Typiquement, MAILING-ADDRESS sera ‘bug-PROGRAMME@gnu.org’ ;
 246      veuillez utiliser ce format pour les programmes GNU à chaque fois
 247      que c’est possible.  Mentionner la page d’accueil du programme,
 248      d’autres listes de diffusion, etc., est aussi une bonne idée.
 249
 250    Les interfaces de programmation ‘argp’ et ‘popt’ permettent
 251 d’indiquer des descriptions d’options pour ‘--help’ dans la même
 252 structure que le reste de la définition de l’option ; ces routines
 253 valent la peine d’être considérées pour analyser l’option au lieu de
 254 ‘getopt’.
 255
 256    Par défaut, ‘help2man’ a quelques heuristiques pour identifier les
 257 sections de page de manuel : une ligne constituée d’‘Options :’ par
 258 exemple forcera le texte suivant à apparaître dans la section ‘OPTIONS’,
 259 et une ligne commençant par ‘Copyright’ apparaîtra dans la section
 260 ‘COPYRIGHT’.  Hors de ces heuristiques, une ligne constituée de ‘*Mots*’
 261 commencera une nouvelle section et ‘Mots :’ une nouvelle sous-section.
 262
 263 \1f
 264 File: help2man-fr.info.tmp,  Node: Texte inclus,  Next: Utilisation de Makefile,  Prev: Recommandations pour --help,  Up: Top
 265
 266 4 Inclusion de texte supplémentaire dans la sortie
 267 **************************************************
 268
 269 Du texte statique supplémentaire peut être inclus dans la page de manuel
 270 créée en utilisant les options ‘--include’ et ‘--opt-include’ (*note
 271 Appeler help2man::).  Bien que ces fichiers puissent être nommés
 272 librement, par cohérence, l’utilisation de l’extension ‘.h2m’ est
 273 recommandée pour les fichiers d’inclusion de ‘help2man’.
 274
 275    Le format des fichiers inclus avec ces options est simple :
 276
 277      [section]
 278      texte
 279
 280      /motif/
 281      texte
 282
 283    Les blocs de texte (au format *roff) sont insérés tels quels dans la
 284 sortie, soit au début de la zone désignée par ‘[section]’ (balise
 285 insensible à la casse), soit après un paragraphe correspondant au
 286 ‘/motif/’.
 287
 288    Les motifs obéissent à la syntaxe des expressions rationnelles de
 289 Perl et peuvent être suivis des modificateurs ‘i’, ‘s’ ou ‘m’ (*note
 290 perlre(1): (*manpages*)perlre.).
 291
 292    Les lignes précédant la première section (ou le premier motif) et
 293 commençant par ‘-’ sont traitées comme des options.  Tout le reste est
 294 ignoré sans aucun avertissement, et peut être utilisé pour des
 295 commentaires, des mots clefs RCS ou d’autres éléments.
 296
 297    L’ordre des sections produites est :
 298
 299      NOM
 300      SYNOPSIS
 301      DESCRIPTION
 302      OPTIONS
 303      _autres_
 304      ENVIRONNEMENT
 305      FICHIERS
 306      EXEMPLES
 307      AUTEUR
 308      BOGUES
 309      COPYRIGHT
 310      VOIR AUSSI
 311
 312    Toute section ‘[nom]’ ou ‘[synopsis]’ apparaissant dans le fichier
 313 inclus va remplacer celle qui aurait été créée automatiquement (mais
 314 vous pouvez encore remplacer la première avec ‘--name’ si nécessaire).
 315
 316    Le texte supplémentaire aux autres sections usuelles (celles
 317 apparaissant dans cette liste) est inséré avant la sortie générée
 318 automatiquement pour elles.  Les sections non usuelles sont insérées à
 319 la place marquée _autres_ dans la liste ci-dessus, suivant l’ordre dans
 320 lequel ces sections apparaissent dans le fichier inclus.
 321
 322    Le placement du texte au sein de la section peut être explicitement
 323 indiqué en utilisant la syntaxe ‘[<section]’, ‘[=section]’ ou
 324 ‘[>section]’ pour placer le texte supplémentaire respectivement avant, à
 325 la place de ou après la sortie par défaut.
 326
 327 \1f
 328 File: help2man-fr.info.tmp,  Node: Utilisation de Makefile,  Next: Pages de manuel traduites,  Prev: Texte inclus,  Up: Top
 329
 330 5 Utilisation de ‘help2man’ avec ‘make’
 331 ***************************************
 332
 333 Une suggestion d’utilisation de ‘help2man’ dans les fichiers Makefile
 334 est d’avoir la page de manuel qui ne dépend pas du binaire, mais du ou
 335 des fichiers source dans lesquels la sortie de ‘--help’ et ‘--version’
 336 est définie.
 337
 338    Cette utilisation permet à une page de manuel d’être générée par le
 339 mainteneur et incluse dans la distribution sans nécessiter
 340 l’installation de ‘help2man’ pour l’utilisateur final.
 341
 342    Une règle d’exemple pour le programme ‘prog’ pourrait être :
 343
 344      prog.1: $(srcdir)/main.c
 345              -$(HELP2MAN) --output=$@ --name='Programme d’exemple' ./prog
 346
 347    La valeur de ‘HELP2MAN’ peut être définie dans ‘configure.in’ en
 348 utilisant :
 349
 350      AM_MISSING_PROG(HELP2MAN, help2man)
 351
 352    pour ‘automake’, ou quelque chose comme :
 353
 354      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 355
 356    pour ‘autoconf’ seul.
 357
 358 \1f
 359 File: help2man-fr.info.tmp,  Node: Pages de manuel traduites,  Next: Exemple,  Prev: Utilisation de Makefile,  Up: Top
 360
 361 6 Production de pages de manuel dans la langue maternelle
 362 *********************************************************
 363
 364 Les pages de manuel peuvent être produites pour n’importe quels
 365 paramètres régionaux pris en charge à la fois par le programme et par
 366 ‘help2man’ avec l’option ‘--locale’ (‘-L’).
 367
 368      help2man -L fr_FR.UTF-8 -o cp.fr.1 cp
 369
 370    Consultez <http://translationproject.org/domain/help2man.html> pour
 371 les langues actuellement prises en charge par ‘help2man’ et *note
 372 Signalements:: pour la façon de proposer d’autres traductions.
 373
 374 6.1 Modifier l’emplacement des catalogues de messages
 375 =====================================================
 376
 377 Lors de la création de pages de manuel traduites à partir du répertoire
 378 de construction d’un programme, les traductions installées à l’endroit
 379 standard (si le programme est installé) ne seront probablement pas
 380 correctes pour la version du programme en cours de construction.
 381
 382    Une bibliothèque de préchargement est fournie avec ‘help2man’ pour
 383 intercepter les appels de ‘bindtextdomain’ configurant l’emplacement des
 384 catalogues de messages pour le domaine donné par ‘$TEXTDOMAIN’ et
 385 remplacer l’emplacement vers le chemin donné par ‘$LOCALEDIR’.
 386
 387    Ainsi, par exemple :
 388
 389      mkdir -p tmp/fr/LC_MESSAGES
 390      cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
 391      LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 392        LOCALEDIR=tmp \
 393        TEXTDOMAIN=PROG \
 394        help2man -L fr_FR.UTF-8 -i PROG.fr.h2m -o PROG.fr.1 PROG
 395      rm -rf tmp
 396
 397    forcera PROG à charger le catalogue de messages à partir de ‘tmp’ au
 398 lieu de ‘/usr/share/locale’.
 399
 400    Remarques :
 401    • La généralisation de ‘fr_FR.UTF-8’ en ‘fr’ dans l’exemple précédent
 402      est réalisée par ‘gettext’, si une correspondance plus spécifique
 403      était disponible, elle aurait aussi utilisée.
 404
 405    • Ce préchargement n’a été testé qu’avec ‘eglibc’ 2.11.2 et
 406      ‘gettext’ 0.18.1.1 sur un système GNU/Linux ; veuillez signaler si
 407      cela fonctionne (ou pas) pour vous (*note Signalements::).
 408
 409 \1f
 410 File: help2man-fr.info.tmp,  Node: Exemple,  Next: Signalements,  Prev: Pages de manuel traduites,  Up: Top
 411
 412 7 Exemple de sortie de ‘help2man’
 413 *********************************
 414
 415 À partir d’un programme hypothétique ‘toto’ qui produit la sortie
 416 suivante :
 417
 418      $ toto --version
 419      GNU toto 1.1
 420
 421      Copyright © 2011 Free Software Foundation, Inc
 422      Ce logiciel est libre ; consultez les sources pour les conditions de
 423      reproduction. AUCUNE garantie n'est donnée, pas même la garantie
 424      implicite de COMMERCIALISATION ni l'ADÉQUATION À UN BESOIN PARTICULIER.
 425
 426      Écrit par C. Programmeurs.
 427      $ toto --help
 428      « toto » de GNU ne fait rien d’intéressant à part servir d’exemple pour
 429      « help2man ».
 430
 431      Utilisation : toto [OPTION] ...
 432
 433      Options :
 434        -a, --option      une option
 435        -b, --another-option[=VALEUR]
 436                          une autre option
 437
 438        -h, --help        afficher l'aide-mémoire
 439        -v, --version     afficher le nom et la version du logiciel
 440
 441      Exemples :
 442        toto              ne rien faire
 443        toto --option     la même chose, avec « --option »
 444
 445      Signaler toute anomalie à <bug-gnu-utils@gnu.org>.
 446
 447    ‘help2man’ produira une entrée ‘nroff’ pour une page de manuel qui
 448 sera formatée en quelque chose comme ceci :
 449
 450      TOTO(1)                          Commandes                         TOTO(1)
 451
 452      NOM
 453             toto - Page de manuel de toto 1.1
 454
 455      SYNOPSIS
 456             toto [OPTION] ...
 457
 458      DESCRIPTION
 459            « toto »  de  GNU ne fait rien d’intéressant à part servir d’exemple
 460            pour « help2man ».
 461
 462      OPTIONS
 463             -a, --option
 464                    une option
 465
 466             -b, --another-option[=VALEUR]
 467                    une autre option
 468
 469             --help afficher l'aide-mémoire
 470
 471             --version
 472                    afficher le nom et la version du logiciel
 473
 474      EXEMPLES
 475             toto   ne rien faire
 476
 477             foo --option
 478                    la même chose, avec « --option »
 479
 480      AUTEUR
 481             Écrit par C. Programmeurs.
 482
 483      BOGUES
 484             Signaler toute anomalie à <bug-gnu-utils@gnu.org>.
 485
 486      COPYRIGHT
 487             Copyright © 2011 Free Software Foundation, Inc
 488             Ce logiciel est libre ; consultez les sources pour  les  conditions
 489             de reproduction. AUCUNE garantie n'est donnée, pas même la garantie
 490             implicite   de   COMMERCIALISATION  ni  l'ADÉQUATION  À  UN  BESOIN
 491             PARTICULIER.
 492
 493      VOIR AUSSI
 494             La documentation complète pour toto est mise à jour dans un  manuel
 495             Texinfo   (en  anglais).  Si  les  programmes  info  et  toto  sont
 496             correctement installés sur le système, la commande
 497
 498                    info toto
 499
 500             devrait donner accès au manuel complet (en anglais).
 501
 502      toto 1.1                         mai 2011                          TOTO(1)
 503
 504 \1f
 505 File: help2man-fr.info.tmp,  Node: Signalements,  Next: Disponibilité,  Prev: Exemple,  Up: Top
 506
 507 8 Signaler des bogues ou des suggestions
 508 ****************************************
 509
 510 Si vous trouvez des problèmes ou avez des suggestions sur ce programme
 511 ou ce manuel, veuillez les signaler sur <bug-help2man@gnu.org>.
 512
 513    Remarque pour les traducteurs : les traductions sont gérées à l’aide
 514 du projet de traduction (http://translationproject.org/), consultez
 515 <http://translationproject.org/html/translators.html> pour plus de
 516 précisions.
 517
 518 \1f
 519 File: help2man-fr.info.tmp,  Node: Disponibilité,  Prev: Signalements,  Up: Top
 520
 521 9 Obtention de ‘help2man’
 522 *************************
 523
 524 La dernière version de cette distribution est disponible en ligne sur
 525 les miroirs de GNU :
 526
 527      <http://ftpmirror.gnu.org/help2man/>
 528
 529    Si la redirection automatique échoue, la liste des miroirs est
 530 disponible :
 531
 532      <http://www.gnu.org/order/ftp.html>
 533
 534    Si nécessaire, vous pouvez utiliser le serveur FTP principal de GNU :
 535      <http://ftp.gnu.org/gnu/help2man/>
 536
 537 \1f
 538 Tag Table:
 539 Node: Top\7f1332
 540 Node: Vue d’ensemble\7f2381
 541 Node: Appeler help2man\7f3227
 542 Node: Recommandations pour --help\7f6410
 543 Node: Texte inclus\7f10908
 544 Node: Utilisation de Makefile\7f13366
 545 Node: Pages de manuel traduites\7f14488
 546 Node: Exemple\7f16731
 547 Node: Signalements\7f19711
 548 Node: Disponibilité\7f20258
 549 \1f
 550 End Tag Table
 551
 552 \1f
 553 Local Variables:
 554 coding: utf-8
 555 End: