lexgrog

Autres langues

Langue: fr

Version: 2009-03-14 (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

NOM

lexgrog - analyse l'information contenue dans l'en-tête des pages de manuel

SYNOPSIS

lexgrog [-m|-c] [-fhwV] fichier ...

DESCRIPTION

lexgrog est une implémentation de l'utilitaire traditionnel « groff guess » de lex. Il exploite chacun des fichiers indiqués sur sa ligne de commande, soit en tant que fichiers source de page de manuel, soit en tant que page « cat » préformatée. Il affiche leur nom et leur description selon le format employé par apropos et whatis. La liste des filtres de prétraitement, exigés par la page de manuel avant cela, est passée à nroff ou à troff, ou aux deux.

Si les données en entrée sont mal formatées, lexgrog affichera « parse failed ». Cela peut être utile pour les programmes externes qui doivent vérifier les pages de manuel. Si l'un des fichiers d'entrée de lexgrog est « - », le programme lira l'entrée standard. Si un des fichiers analysé est compressé, une version décompressée sera exploitée automatiquement.

OPTIONS

-m, --man
Analyse l'entrée en tant que fichier source de page de manuel. C'est le comportement par défaut si ni --man ni --cat ne sont indiquées.
-c, --cat
Analyse l'entrée en tant que page de manuel préformatée (page « cat ») --man et --cat ne peuvent pas être indiquées simultanément.
-w, --whatis
Affiche le nom et la description, tirés de l'en-tête de la page de manuel, selon le format employé par apropos et par whatis. C'est le comportement par défaut si ni --whatis ni --filters ne sont indiquées.
-f, --filters
Affiche la liste des filtres requis pour prétraiter la page de manuel avant sa mise en forme par nroff ou troff.
-h, --help
Affiche un message d'aide et s'arrête.
-V, --version
Affiche le numéro de version.

VALEUR DE RETOUR

0
Programme exécuté sans erreur.
1
Erreur d'exécution.
2
lexgrog n'a pas réussi à analyser un ou plusieurs des fichiers d'entrée.

EXEMPLES

  $ lexgrog man.1
  man.1: "man - Interface de consultation des manuels de référence en ligne"
  $ lexgrog -fw man.1
  man.1 (t): "man - Interface de consultation des manuels de référence en ligne"
  $ lexgrog -c whatis.cat1
  whatis.cat1: "whatis - Affiche la description des pages de manuel"
  $ lexgrog broken.1
  broken.1: parse failed
 

ANALYSE WHATIS

mandb (qui emploie le même code que lexgrog) analyse la section NAME en tête de chaque page de manuel et recherche le nom et la description de chaque fonction documentée. Bien que l'analyseur soit très tolérant, car il doit faire face aux différentes formes qui ont été historiquement employées, il peut parfois ne pas arriver à extraire l'information recherchée.

Pour que les macros de man fonctionnent correctement, la section NAME doit ressembler à ceci :

 .SH NAME
 toto \- programme qui fait quelque chose
 

Certains afficheurs de pages de manuel exigent « \- » exactement comme indiqué. mandb est plus tolérant, mais pour assurer la compatibilité avec d'autres systèmes c'est une bonne idée de conserver la contre-oblique (antislash).

À gauche, il peut y avoir plusieurs noms, séparés par des virgules. Le texte à droite n'a pas de structure imposée et peut être écrit sur plusieurs lignes. Si plusieurs fonctions, avec des descriptions différentes sont documentées dans la même page de manuel, la forme suivante sera employée :

 .SH NAME
 toto, titi \- programmes qui font quelque chose
 .br
 tutu \- programme qui ne fait pas grand chose
 

Une macro, marquant le début d'un nouveau paragraphe, comme .PP, peut être employée à la place de la macro de rupture .br.

Pour être utilisée avec les macros mdoc, dérivées de BSD, la section NAME doit ressembler à ceci :

 .Sh NAME
 .Nm toto
 .Nd programme qui fait quelque chose
 

Il y a plusieurs raisons habituelles pour lesquelles l'analyse whatis échoue. Parfois les auteurs des pages de manuel remplacent « .SH NAME » par « .SH MYPROGRAM ». De ce fait mandb ne peut pas trouver la section dont il a besoin pour extraire l'information. Parfois les auteurs incluent une section NAME, mais y placent le texte descriptif sans respecter le format « nom \- description ». Cependant, n'importe quelle syntaxe ressemblant à ce qui précède devrait être acceptée.

VOIR AUSSI

man(1), mandb(8), apropos(1), whatis(1).

NOTA BENE

lexgrog essaie d'analyser les fichiers contenant des requêtes .so, mais il ne pourra le faire efficacement que si les fichiers sont correctement installés dans une structure hiérarchique de pages de manuel.

AUTEUR

Le code utilisé dans lexgrog pour analyser les pages de manuel a été écrit par :
 Wilf. (G.Wilford@ee.surrey.ac.uk).
 Fabrizio Polacco (fpolacco@debian.org).
 Colin Watson (cjwatson@debian.org).
 

Colin Watson a écrit l'interface de la ligne de commande actuelle ainsi que cette page de manuel.

TRADUCTION

Valéry Perrin <valery.perrin.debian@free.fr> le 2 janvier 2006. L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité.

La version anglaise la plus à jour de ce document est toujours consultable via la commande « man -L en nom_de_la_page ».

N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.