Nom

docbook2man-spec.pl - convertit des « RefEntries » DocBook vers des pages de manuel

Résumé

sgmlspl docbook2man-spec.pl nsgmls [ document_sgml ]| sgmlspl docbook2man-spec.pl

Description


docbook2man est un fichier de spécifications sgmlspl qui produit des pages de manuel (en utilisant les macros -man) à partir du marquage « RefEntry » DocBook.

Le programme lit les données « ESIS » produit par nsgmls (ou tout autre analyseur syntaxique SGML) à partir de l'entrée standard. Le marquage non trouvé dans « RefEntry » est ignoré.

Les pages de manuel converties résultantes sont écrites dans le répertoire courant. Si l'information « RefMeta » n'est pas spécifiée dans une « RefEntry », alors la page de manuel sera écrite sur la sortie standard.

Le fichier manpage.links sera également créé, il contient tous les alias des pages de manuel générées. Ce fichier obéit au format : .nf <man page> <alias manpage> .fi

Le fichier manpage.refs garde trace des références croisées. Notez que si le document d'entrée a des références en aval, alors docbook2man doit être invoqué deux fois (la première fois mettant à jour manpage.refs) pour les résoudre.

PrÉ-requis

Le paquetage SGMLSpm du CPAN. Ce paquetage inclut le script sgmlspl qui est également nécessaire.

Limitations


Essayer docbook2man sur des fichiers qui ne sont pas des fichiers DocBook ou pas conformes au SGML provoque un comportement indéfini.

Ce programme est un script Perl lent et « vite fait, mal fait ».

Ce programme ne prétend pas accepter tous les marquages possibles de DocBook, et peut produire des sorties erronées, dans certains cas, avec le marquage supporté.

À faire


Des évidences :

(bu Corriger les plantages de docbook2man sur les documents de test, spécialement weird.sgml&.

(bu Ajouter une nouvelle manipulation d'élément et corriger les manipulations existantes. Être solide.

(bu Produire autant que possible une sortie man plus propre et lisible (pas comme certains convertisseurs). Suivre la convention man(7) pour Linux. Comme la conversion vers des pages de manuel n'est généralement pas effectuée très souvent, il est mieux qu'elle soit plus lente/plus compliquée que de produire une sortie erronée. Aussi, si quelqu'un veut cesser d'utiliser DocBook quelqu'en soit la raison, les pages de manuel dernièrement converties peuvent être maintenues manuellement.

(bu Le rendre plus rapide. Je pense que la plupart des problèmes de rapidité jusqu'ici sont dus à l'analyse syntaxique d'ESIS. Réécrire SGMLS.pm en C et/ou récupérer directement l'entrée à partir de SP&.

(bu Supporter d'autres langues. Mais que faire des ensembles de caractères non-ASCII ? SGMLSpm ne les rapporte pas et roff ne les connaît pas. [Commentaire : le texte après des listes protégées (et des blocs SS) font interrompre docbook2man] Si nous faisons cela, plus de monde pourra utiliser DocBook.

Copyright


Copyright (C) 1998-1999 Steve Cheng <steve@ggi-project.org>

Ce programme est libre, vous pouvez le redistribuer et/ou le modifier selon les termes de la Licence Publique Générale GNU telle que publiée par la Free Software Foundation ; soit la version 2 de cette licence, soit (à vous de voir...) toute autre version ultérieure.

Vous devez avoir reçu une copie de la Licence Publique Générale GNU avec ce programme ; voir le fichier COPYING&. Si ce n'est pas le cas, écrivez à la Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

Traduction


Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> 12 février 2003 et révisée le 19 novembre 2004.

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 : « LANG=en man 1 docbook2man-spec.pl ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.