1 This is help2man-fr.info.tmp, produced by makeinfo version 6.5 from
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’.
8 Copyright © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
9 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
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.
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.
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
26 * help2man-fr: (help2man-fr). Création automatique de page de manuel.
30 File: help2man-fr.info.tmp, Node: Top, Next: Vue d’ensemble, Up: (dir)
35 ‘help2man’ produit de simples pages de manuel à partir de la sortie
36 d’autres commandes avec les options ‘--help’ et ‘--version’.
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
44 * Texte inclus:: Inclusion de texte supplémentaire dans
46 * Utilisation de Makefile:: Utilisation de ‘help2man’ avec‘make’.
47 * Pages de manuel traduites:: Production de pages de manuel dans la
49 * Exemple:: Exemple de sortie de ‘help2man’.
50 * Signalements:: Signaler des bogues ou des
52 * Disponibilité:: Obtention de ‘help2man’.
55 File: help2man-fr.info.tmp, Node: Vue d’ensemble, Next: Appeler help2man, Prev: Top, Up: Top
57 1 Vue d’ensemble de ‘help2man’
58 ******************************
60 ‘help2man’ est un outil pour créer automatiquement de simples pages de
61 manuel à partir de la sortie d’un programme.
63 Bien que les pages de manuel soient facultatives pour les programmes
64 GNU, d’autres projets comme Debian les exigent (*note (standards)Man
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.
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.
76 File: help2man-fr.info.tmp, Node: Appeler help2man, Next: Recommandations pour --help, Prev: Vue d’ensemble, Up: Top
78 2 Façons d’exécuter ‘help2man’
79 ******************************
81 La forme pour exécuter le programme ‘help2man’ est :
83 help2man [OPTION]... EXÉCUTABLE
85 ‘help2man’ reconnaît les options suivantes :
89 Utiliser CHAÎNE comme description du paragraphe ‘NOM’ de la page de
92 Par défaut (en absence de mieux), ce paragraphe contient ‘Page de
93 manuel de PROGRAMME VERSION’.
95 Cette option écrase une section ‘[name]’ de fichier d’inclusion
96 (*note Texte inclus::).
100 Utiliser SECTION comme section de la page de manuel. La section
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.
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
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::).
125 Inclure le matériel du FICHIER (*note Texte inclus::).
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.
134 Envoyer la sortie vers FICHIER au lieu de ‘stdout’.
138 Nom du manuel Texinfo.
142 Supprimer l’inclusion d’un paragraphe ‘VOIR AUSSI’ dirigeant le
143 lecteur vers la documentation Texinfo.
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
154 Afficher l’aide ou des informations de version.
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.
161 ‘--help-option=OPTION’
162 Chaîne pour l’option d’aide.
165 ‘--version-option=OPTION’
166 Chaîne pour l’option de version.
168 ‘--version-string=CHAÎNE’
171 ‘--no-discard-stderr’
172 Inclure la sortie d’erreur standard lors de l’analyse de la sortie
176 File: help2man-fr.info.tmp, Node: Recommandations pour --help, Next: Texte inclus, Prev: Appeler help2man, Up: Top
178 3 Recommandations pour ‘--help’
179 *******************************
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.
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.
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é
195 Utilisation : cp [OPTION]... SOURCE DEST
196 ou : cp [OPTION]... SOURCE... DIRECTORY
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’.
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
208 Copier la SOURCE vers DEST, ou plusieurs SOURCEs vers DIRECTORY.
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
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 :
224 -a, --archive identique à -dR…
225 --backup[=CONTROL] archiver chaque…
226 -b comme --backup mais…
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.
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.
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é.
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.
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
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.
264 File: help2man-fr.info.tmp, Node: Texte inclus, Next: Utilisation de Makefile, Prev: Recommandations pour --help, Up: Top
266 4 Inclusion de texte supplémentaire dans la sortie
267 **************************************************
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’.
275 Le format des fichiers inclus avec ces options est simple :
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
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.).
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.
297 L’ordre des sections produites est :
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).
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.
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.
328 File: help2man-fr.info.tmp, Node: Utilisation de Makefile, Next: Pages de manuel traduites, Prev: Texte inclus, Up: Top
330 5 Utilisation de ‘help2man’ avec ‘make’
331 ***************************************
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’
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.
342 Une règle d’exemple pour le programme ‘prog’ pourrait être :
344 prog.1: $(srcdir)/main.c
345 -$(HELP2MAN) --output=$@ --name='Programme d’exemple' ./prog
347 La valeur de ‘HELP2MAN’ peut être définie dans ‘configure.in’ en
350 AM_MISSING_PROG(HELP2MAN, help2man)
352 pour ‘automake’, ou quelque chose comme :
354 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
356 pour ‘autoconf’ seul.
359 File: help2man-fr.info.tmp, Node: Pages de manuel traduites, Next: Exemple, Prev: Utilisation de Makefile, Up: Top
361 6 Production de pages de manuel dans la langue maternelle
362 *********************************************************
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’).
368 help2man -L fr_FR.UTF-8 -o cp.fr.1 cp
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.
374 6.1 Modifier l’emplacement des catalogues de messages
375 =====================================================
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.
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’.
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" \
394 help2man -L fr_FR.UTF-8 -i PROG.fr.h2m -o PROG.fr.1 PROG
397 forcera PROG à charger le catalogue de messages à partir de ‘tmp’ au
398 lieu de ‘/usr/share/locale’.
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.
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::).
410 File: help2man-fr.info.tmp, Node: Exemple, Next: Signalements, Prev: Pages de manuel traduites, Up: Top
412 7 Exemple de sortie de ‘help2man’
413 *********************************
415 À partir d’un programme hypothétique ‘toto’ qui produit la sortie
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.
426 Écrit par C. Programmeurs.
428 « toto » de GNU ne fait rien d’intéressant à part servir d’exemple pour
431 Utilisation : toto [OPTION] ...
434 -a, --option une option
435 -b, --another-option[=VALEUR]
438 -h, --help afficher l'aide-mémoire
439 -v, --version afficher le nom et la version du logiciel
443 toto --option la même chose, avec « --option »
445 Signaler toute anomalie à <bug-gnu-utils@gnu.org>.
447 ‘help2man’ produira une entrée ‘nroff’ pour une page de manuel qui
448 sera formatée en quelque chose comme ceci :
450 TOTO(1) Commandes TOTO(1)
453 toto - Page de manuel de toto 1.1
459 « toto » de GNU ne fait rien d’intéressant à part servir d’exemple
466 -b, --another-option[=VALEUR]
469 --help afficher l'aide-mémoire
472 afficher le nom et la version du logiciel
478 la même chose, avec « --option »
481 Écrit par C. Programmeurs.
484 Signaler toute anomalie à <bug-gnu-utils@gnu.org>.
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
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
500 devrait donner accès au manuel complet (en anglais).
502 toto 1.1 mai 2011 TOTO(1)
505 File: help2man-fr.info.tmp, Node: Signalements, Next: Disponibilité, Prev: Exemple, Up: Top
507 8 Signaler des bogues ou des suggestions
508 ****************************************
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>.
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
519 File: help2man-fr.info.tmp, Node: Disponibilité, Prev: Signalements, Up: Top
521 9 Obtention de ‘help2man’
522 *************************
524 La dernière version de cette distribution est disponible en ligne sur
527 <http://ftpmirror.gnu.org/help2man/>
529 Si la redirection automatique échoue, la liste des miroirs est
532 <http://www.gnu.org/order/ftp.html>
534 Si nécessaire, vous pouvez utiliser le serveur FTP principal de GNU :
535 <http://ftp.gnu.org/gnu/help2man/>
540 Node: Vue d’ensemble
\7f2363
541 Node: Appeler help2man
\7f3209
542 Node: Recommandations pour --help
\7f6392
543 Node: Texte inclus
\7f10890
544 Node: Utilisation de Makefile
\7f13348
545 Node: Pages de manuel traduites
\7f14470
546 Node: Exemple
\7f16713
547 Node: Signalements
\7f19693
548 Node: Disponibilité
\7f20240