Scroll to navigation

PolyglotMan(1) General Commands Manual PolyglotMan(1)

NOM

PolyglotMan, rman – Décompilation des pages de manuel depuis la forme formatée vers un certain nombre de formats source : ASCII, roff, TkMan, Tk, Sections, HTML, SGML, MIME, LaTeX, LaTeX2e, RTF, POD.

SYNOPSIS

rman [options] [fichier]

DESCRIPTION

Des instructions mises à jour sont disponibles sur http://polyglotman.sourceforge.net/rman.html

PolyglotMan accepte les pages de manuel de la plupart des versions populaires d’UNIX et les transforme dans n’importe quel format textuel source. PolyglotMan était connu auparavant sous le nom RosettaMan. Le nom du binaire est toujours appelé rman pour les scripts qui dépendent de ce nom. De manière mnémotechnique, penser à « reverse man ». Anciennement, PolyglotMan nécessitait que les pages soient formatées par nroff(1) avant leur traitement. Depuis la version 3.0, il préfère une source [tn]roff et produit habituellement des résultats encore meilleurs, et le traitement de source est le seul moyen de traduire des tables. La traduction en format source n’est pas aussi aboutie que celle en formaté ; donc, essayez la traduction du texte formaté comme solution de repli.

Lors de l'analyse du source [tn]roff, il est possible de mettre en œuvre un sous-ensemble arbitrairement grand de [tn]roff, ce que je n’ai pas fait et ne ferai pas, de sorte que les résultats peuvent ne pas être adéquats. J’ai toutefois implémenté un sous-ensemble significatif de macros utilisées dans les pages de manuel, y compris tbl (mais pas eqn), les conditions if et les définitions de macros générales, de sorte que les résultats sont généralement excellents. Si ce n’est pas le cas, formatez la page avec nroff(1) avant de l’envoyer à PolyglotMan. Si celui-ci ne reconnaît pas une macro clé utilisée pour une large catégorie de pages, envoyez-moi par courriel la source et une page formatée en nroff et encodée en uuencode(1), et je verrai ce que je peux faire. Lors de l’exécution de PolyglotMan pour une source de page de manuel qui inclut ou redirige vers une autre source [tn]roff à l'aide de la macro .so (source ou inclusion), vous devez être dans le répertoire parent de la page, car les pages sont écrites en partant de cette hypothèse. Par exemple, si vous traduisez /usr/share/man/man1/ls.1, commencez par vous placer dans le répertoire /usr/share/man.

PolyglotMan accepte les pages de manuel de SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System V, OSF/1 (alias Digital UNIX), DEC Ultrix, SGI IRIX, Linux, FreeBSD et SCO. Le traitement de source fonctionne pour SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System V, OSF/1 (alias Digital UNIX), DEC Ultrix. Il peut produire des fichiers imprimables en ASCII uniquement (suppression des caractères de contrôle), des « headers-only » de section, pour Tk, TkMan, [tn]roff (source de page de manuel traditionnelle), XML, HTML, MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD. Son architecture modulaire permet d’ajouter facilement d’autres formats de sortie.

La dernière version de PolyglotMan est disponible sur http://polyglotman.sourceforge.net/ .

OPTIONS

Les options suivantes ne doivent pas être utilisées avec n’importe quelle autre option sinon PolyglotMan quitte sans traiter aucune entrée.

Afficher un résumé des options de la ligne de commande, puis quitter.
Afficher la version du programme puis quitter.

Le filtre doit être défini en premier, car cela règle un certain nombre de paramètres, avant les autres options.

Déterminer le filtre de sortie. Par défaut, ASCII.
PolyglotMan essaie de déterminer automatiquement si l’entrée est un fichier de source ou un fichier formaté. Utiliser cette option pour déclarer une entrée source.
PolyglotMan essaie de déterminer automatiquement si l’entrée est un fichier source ou un fichier formaté. Utiliser cette option pour déclarer une entrée formatée.
En mode HTML cette option définit le TITRE de la page de manuel, en donnant les mêmes paramètres que l’option -r.
En mode HTML et XML, cette option définit la forme de l’URL à l’aide duquel retrouver les autres pages de manuel. La chaine peut prendre deux paramètres : le nom de la page de manuel et sa section (consulter la section Exemples). Si la chaine est NULL (comme si définie à partir de l’interpréteur de commandes par « -r ” »), « - » ou « off », alors les références de page de manuel ne seront pas des hyperliens (HREF), mais seront simplement en italique. Si votre printf(1) gère le spécificateur de positions d’XPG3, cela peut être assez flexible.
Cette option définit la liste des volumes valables à prendre en compte lors de la recherche de références croisées vers d'autres pages de manuel. La valeur par défaut est 1:2:3:4:5:6:7:8:9:o:l:n:p (les noms de volume peuvent être multicaractères). Si une chaîne autre qu’un blanc dans la page est immédiatement suivie d’une parenthèse gauche, puis d’un des volumes valables et se termine par d’autres caractères facultatifs et enfin par une parenthèse droite, alors cette chaîne est rapportée comme une référence à une autre page de manuel. Si « -V chaine » commence par un signe égale, alors aucun caractère facultatif n'est autorisé entre la correspondance avec la liste des valeurs valables et la parenthèse droite (cette option est nécessaire pour l’UNIX de SCO).

Les options suivantes ne s’appliquent que lorsque des pages formatées sont fournies en entrée. Elles ne s'appliquent pas pour les sources ou sont toujours traitées correctement avec ces dernières.

Cette option essaie de repérer les titres de sous-section en plus des titres de section. Elle peut poser des problèmes pour certaines versions d’UNIX.
Cette option indique que les pages de manuel n’ont pas de saut de page, donc ne pas rechercher de pied de page ou d’en-tête autour d’elles (les anciennes macros « nroff -man » incorporaient toujours des sauts de page, mais, plus tard, certains fournisseurs ont réalisé que les impressions étaient faites à travers troff(1), alors que « nroff -man » était utilisé pour formater les pages pour la lecture sur écran, et ont dont supprimé les sauts de page). PolyglotMan traite habituellement cela correctement même sans cette option.
Cette option conserve les en-têtes et les pieds de page, sous forme de rapport canonique à la fin de la page. « changeleft » déplace vers la gauche les « changebar », telles que celles trouvées dans les pages de manuel de Tcl/Tk. <-- notaggressive désactive l'analyse agressive des pages de manuel. L'analyse agressive des pages de manuel, activée par défaut, élimine les en-têtes et les pieds de page, identifie les sections et plus encore. -->
Cette option définit le nom de la page de manuel (utilisée dans le format roff(7)). Si le nom de fichier est indiqué sous la forme « nom.section », le nom et la section sont automatiquement déterminés. Si la page est analysée à partir d’un source [tn]roff et s’il comporte une ligne .TH, cette information est extraite de cette ligne.
Basculement du mode paragraphe. Ce filtre détermine si les lignes doivent être coupées en fin de ligne comme le faisait nroff(1), ou si elles doivent être regroupées en paragraphes. Principalement destiné à un usage interne.
Cette option définit le numéro de volume (de section) de la page de manuel (utilisé dans le format de roff). <-- table active l’analyse agressive des tables. -->
Pour les ensembles de macros qui utilisent des tabulations à la place des espaces lorsque cela est possible afin de réduire le nombre de caractères utilisés, cette option définit les taquets de tabulation toutes les n colonnes. La valeur par défaut est 8.

NOTES SUR LES TYPES DE FILTRES

ROFF

Certaines versions d’UNIX fournissent des pages de manuel sans le source [tn]roff, ce qui réduit une imprimante laser à peu près au même rôle qu’une imprimante à marguerite alimentée par un laser. Ce filtre tente de deviner les directives [tn]roff d'origine, qui peuvent ensuite être recompilées par [tn]roff.

TkMan

tkman(1), un navigateur avec hypertexte de pages de manuel, utilise PolyglotMan pour afficher les pages de manuel sans les en-têtes et bas de page (en général) inutiles sur chaque page. Il rassemble aussi les titres de sections et (facultativement) les titres de sous-sections pour un accès direct à partir d’un menu déroulant. TkMan et Tcl/Tk, la boîte à outils servant à l’écrire, sont disponibles par ftp(1) anonyme sur ftp://ftp.smli.com/pub/tcl/.

Tk

Cette option affiche le texte sous forme de séries de listes Tcl consistant en des paires balise/texte, où les noms de balise correspondent en gros à celles du HTML. Cette sortie peut être insérée dans un composant graphique de Tcl pour du texte en effectuant une commande eval <composant_graphique> insert end <texte>. Ce format doit être relativement facile à analyser par d’autres programmes qui veulent le texte et les balises. Consulter aussi le paragraphe ASCII.

ASCII

Lorsqu'elles sont imprimées sur une imprimante ligne par ligne, les pages de manuel tentent de produire des effets textuels spéciaux en superposant des caractères sur eux-mêmes (pour créer du gras) et des traits de soulignement. Les autres logiciels de traitement de texte, tels que les éditeurs de texte, les moteurs de recherche et les indexeurs doivent neutraliser cet effet. Le filtre ASCII supprime ce formatage. Le redirection de la sortie de nroff à travers col -b supprime également ce formatage, mais produit des en-têtes et des pieds de page hideux. Consulter le paragraphe Tk.

Sections

Cette option copie les titres de sections et (facultativement) ceux de sous-sections. Cela peut être utile pour un autre programme de traitement de pages de manuel.

HTML

Avec une extension simple pour un serveur HTTP pour Mosaic(1) ou un autre navigateur web, PolyglotMan peut produire du HTML de haute qualité à la volée. Plusieurs de ces extensions et des pointeurs vers plusieurs autres sont inclus dans le répertoire contrib de PolyglotMan.

XML

Ce format se rapproche de la DTD de DocBook, mais j’espère que quelqu’un qui s’y intéresse vraiment peaufinera les balises générées. Essayez-le pour voir à quel point les balises sont proches de celles actuelles.

MIME

MIME (Multipurpose Internet Mail Extensions) tel que défini par la RFCM 1563, bon pour une utilisation par des clients de messagerie gérant MIME ou comme les documents enrichis d’Emacs (>=19.29).

LaTeX et LaTeX2e

Pourquoi pas ?

RTF

Utilisez la sortie sur Mac, NeXT ou tout autre système. Peut-être prendre des pages de manuel au hasard et mieux les intégrer avec le système de documentation de NeXT. Peut-être que NeXT dispose de ses propres macros de page de manuel qui permettent de faire cela.

PostScript et FrameMaker

Pour produire du PostScript, utiliser groff(1) ou psroff. Pour produire du MIF pour FrameMaker, utiliser le filtre interne de FrameMaker. Dans les deux cas, le source [tn]roff est nécessaire, aussi, si une version formatée de la page de manuel est disponible, utiliser d’abord le filtre roff de PolyglotMan.

EXEMPLES

Pour convertir une page de manuel formatée appelée ls.1 vers la forme source [tn]roff :

rman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1

Les pages de manuel longues sont souvent compressées pour économiser de l’espace (la compression est particulièrement efficace pour les pages de manuel formatées car de nombreux caractères sont des espaces). Si elles sont longues, les pages de manuel ont probablement des sous-sections qu’il est possible de séparer (certains ensembles de macros ne distinguent pas suffisamment ces sous-sections pour que PolyglotMan les détecte). Dans l’exemple suivant, nous effectuons une conversion au format LaTeX :

pcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f latex > automount.man

Ou, man 1 automount | rman -b -n automount -s 1 -f latex > automount.man

Pour les utilisateurs de HTML/Mosaic, PolyglotMan peut, sans modification du code source, produire des liens HTML qui pointent vers d’autres pages de manuel en HTML prégénérées ou générées à la volée. Supposons d’abord que des versions HTML prégénérées sont stockées dans /usr/share/man/html. Générons celles-ci une par une avec la forme suivante :
rman -f html -r 'http:/usr/share/man/html/%s.%s.html' /usr/share/man/cat1/ls.1 > /usr/share/man/html/ls.1.html

Si votre client HTML gère la génération de HTML à la volée, quelque chose comme ce qui suit peut être utilisé :
rman -f html -r 'http:~/bin/man2html?%s:%s' /usr/share/man/cat1/ls.1
lors de la génération du HTML.

BOGUES/INCOMPATIBILITÉS

PolyglotMan n’est pas parfait dans tous les cas, mais il fait du bon travail en général, et ne réduit en aucun cas le problème de la conversion de pages de manuel en édition légère.

Les tables dans les pages formatées, particulièrement celles d’HP, ne sont pas bien prises en charge. Assurez-vous de passer en source pour la page de façon à reconnaitre les tables.

Le pageur de manuel woman(1) applique sa propre idée du formatage de page de manuel, ce qui peut embrouiller PolyglotMan. Contournez woman en passant le texte formaté des pages de manuel directement à PolyglotMan.

Le format de sortie de [tn]roff utilise fB pour activer les caractères en gras. Si votre ensemble de macros nécessite .B, la sortie de PolyglotMan doit être post-traitée.

VOIR AUSSI

tkman(1), xman(1), man(1), man(7) ou man(5) selon votre version d’UNIX

AUTEUR

PolyglotMan
de Thomas A. Phelps ( phelps@ACM.org )
développé à
Université de Californie, Berkeley
Computer Science Division

Dernière mise à jour de cette page de manuel $Date: 1998/07/13 09:47:28 $

TRADUCTION

La traduction française de cette page de manuel a été créée par Jean-Paul Guillonneau <guillonneau.jeanpaul@free.fr>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.