Nom

jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt - (Jade Wrapper) assurent la conversion de documents SGML vers d'autres formats (masquant l'action de Jade).

Résumé

jw [ -f frontend | --frontend frontend ] [ -b backend | --backend backend ] [ -c fichier | --cat fichier ] [ -n | --nostd ] [ -d fichier|default|none | --dsl fichier|default|none ] [ -l fichier | --dcl fichier ] [ -s chemin | --sgmlbase chemin ] [ -p programme | --parser programme ] [ -o répertoire | --output répertoire ] [ -V variable[=valeur] ] [ -u | --nochunks ] [ -i section | --include section ] [ -w type|list | --warning type|list ] [ -e type|list | --error type|list ] [ -h | --help ] [ -v | --version ] fichier-SGML docbook2dvi fichier-SGML docbook2html fichier-SGML docbook2man fichier-SGML docbook2pdf fichier-SGML docbook2ps fichier-SGML docbook2rtf fichier-SGML docbook2tex fichier-SGML docbook2texi fichier-SGML docbook2txt fichier-SGML

Description


Le script shell jw permet de convertir un fichier DocBook (ou tout autre format basé sur le SGML) vers d'autres formats (incluant HTML, RTF, PS et PDF) avec une syntaxe facile à comprendre. Il masque la part complexe de Jade ou d'OpenJade et apporte de confortables fonctionnalités.

D'autres scripts comme docbook2html, docbook2rtf ou docbook2ps fournissent des manières différentes d'appeler jw qui peuvent être plus aisées à retenir.

Pour le moment, jw ne traite pas le XML, seulement le SGML.

Cet utilitaire présume que plusieurs autres composants soient installés. La liste inclut :

(bu l'entité caractère ISO pour SGML

(bu le moteur DSSSL de James Clark, jade, ou un analyseur syntaxique comme OpenJade

(bu la DTD DocBook du consortium OASIS

(bu les feuilles de style modulaires DocBook de Norman Walsh (ou d'autres jeux de feuilles de style DSSSL)

(bu l'ensemble jadetex, de Sebastian Rahtz, de macros TeX pour jade (pour les backends prévus pour des formats d'« impression » comme PDF, RTF ou PostScript)

(bu un interpréteur perl (pour les backends qui utilisent perl)

(bu le module perl SGMLSpm du CPAN (pour les backends qui utilisent sgmls)

(bu le navigateur HTML Lynx (pour le backend txt)

le script jw se lance essentiellement comme ceci : .nf jw mon_doc.sgml .fi

où mon_doc.sgml est un fichier SGML.

La ligne de commande ci-dessus utilise les options par défaut : elle convertit à partir de DocBook (le frontend par défaut) vers HTML (le backend par défaut), ne met pas le résultat dans un sous-répertoire (à moins que cela ne soit spécifié autrement dans les feuilles de style), etc.

Dans cet exemple, le nom de fichier « mon_doc » aussi bien que l'extension « .sgml » peuvent être remplacés par n'importe quoi d'autre. Les extensions actuelles pour les fichiers DocBook SGML incluent « .sgml », « .sgm », « .docbook », et « .db ». Le fichier traité mon_doc.sgml peut se trouver dans tout autre répertoire que le répertoire courant.

Ici, nous avons choisi de générer une sortie HTML. En fait, nous pouvons utiliser n'importe lequel des backends stockés dans le sous-répertoire du répertoire de la distribution DocBook-utils (habituellement /usr/share/sgml/docbook/utils-0.6.14). De la même manière, vous pouvez utiliser chacun des frontends définis dans le sous-répertoire frontends/ pour convertir à partir d'un autre format d'entrée.

Cette commande échantillon crée un ou plusieurs fichiers HTML avec des noms de fichier arbitraires dans le répertoire courant. Ce fonctionnement par défaut peut être modifié à travers des options de la ligne de commande et/ou une personnalisation des feuilles de style.

Options


Les options suivantes sont applicables au script de conversion :

-f frontend | --frontend frontend Permet de spécifier un autre frontend que celui par défaut docbook&. La liste des frontends actuellement disponible est :      docbook Convertit docbook avec les feuilles de style de Norman Walsh. Ce frontend cherche, dans les sous-répertoires du répertoire SGML de base, un fichier nommé html/docbook.dsl ou print/docbook.dsl (suivant le type de backend : html ou print).

-b backend | --backend backend Permet de spécifier un autre backend que celui par défaut HTML&. La liste des backends actuellement disponible est :      dvi Convertit vers DVI (fichier DeVice Independant) en appelant Jade ou OpenJade&.      html Convertit vers HTML (HyperText Markup Language) en appelant Jade ou OpenJade&.      man Convertit une « refentry » vers une page de manuel Unix en appelant docbook2man. Ne fonctionne pas avec des types de documents SGML autres que DocBook.      pdf Convertit vers PDF (Portable Document Format) en appelant Jade ou OpenJade&.      ps Convertit vers PostScript en appelant Jade ou OpenJade&.      rtf Convertit vers RTF (Rich Text Format) en appelant Jade ou OpenJade&. Le fichier résultant peut être ensuite importé dans MS Word ou un de ses programmes de remplacement sous Linux.      tex Convertit vers TeX en appelant Jade ou OpenJade&.      texi Convertit vers des pages GNU TeXinfo en appelant docbook2texi. Ne fonctionne pas avec des types de documents SGML autres que DocBook.      txt Convertit vers un fichier texte nu en appelant Jade ou OpenJade, puis Lynx&.

-c fichier | --cat fichier Permet d'utiliser un Catalogue Ouvert SGML supplémentaire qui listera d'autres fichiers comme des feuilles de styles personnalisées, des adaptations de la Définition de Type de Document DocBook (NdT : DocBook Document Type Definition ou DocBook DTD), des entités de caractères spéciaux, etc. Ce catalogue est ajouté à la liste des catalogues déterminée par le script (voir l'option --nostd ci-dessous)

-n | --nostd Ne pas utiliser les Catalogues Ouverts SGML standards. Normalement, la liste des catalogues standards est déterminée comme suit :      (bu si le catalogue centralisé existe, alors l'utiliser. Le catalogue centralisé est une liste de tous les catalogues qui peuvent être nécessaires et qui se situent habituellement dans /etc/sgml&. Son nom est fourni par le frontend, par exemple le frontend docbook renvoie /etc/sgml/sgml-docbook.cat&.      (bu Autrement, prend tous les fichiers nommés catalog dans les sous-répertoires du répertoire de base SGML (habituellement /usr/share/sgml). Cette option est utile conjointement avec l'option --cat pour utiliser seulement les catalogues spécifiés sur la ligne de commande

-d fichier|default|none | --dsl fichier|default|none Permet d'utiliser une feuille de style personnalisée à la place de celle par défaut. Une « cible », débutant par un signe dièse « # », peut être ajoutée au nom du fichier. Le résultat sera que seule la partie correspondante de la feuille de style sera exécutée (la « spécification de style » dont l'« identificateur » est égal au nom de la cible). Une utilisation ordinaire de ce mécanisme est de définir les cibles « #html » et « #print » pour déclencher la partie correspondante d'une feuille de style de remplacement qui est commune aux conversions HTML et sortie d'impression. En remplaçant le nom du fichier par « default », la feuille de style fournie avec le frontend est utilisée. Par exemple, le frontend docbook renvoie &./docbook.dsl#html (ou &./docbook.dsl#print) dans le répertoire de base SGML. En remplaçant le nom du fichier par « none », aucune feuille de style de remplacement n'est utilisée, pas même la feuille de style par défaut. La feuille de style qui sera utilisée est alors déterminée par le frontend. Par exemple, le frontend docbook renvoie le html/docbook.dsl (ou print/docbook.dsl) de Norman Walsh trouvé quelque part dans le répertoire de base SGML. Si aucune option --dsl n'est spécifiée, alors « --dsl default » est utilisée.

-l fichier | --dcl fichier Permet d'utiliser une déclaration SGML personnalisée plutôt que celle par défaut. Le nom du fichier de la déclaration SGML par défaut n'est pas fixé pour les fichiers SGML, mais est fixé à xml.dcl dans le répertoire de base SGML pour les fichiers XML.

-s chemin | --sgmlbase chemin Permet d'utiliser une autre localisation pour le répertoire de base SGML. C'est dans ce répertoire que sont installées toutes les DTDs SGML, feuilles de style, entités, etc. La valeur par défaut est /usr/share/sgml.

-p programme | --parser programme Spécifie l'analyseur syntaxique à utiliser (Jade ou OpenJade) si plusieurs sont installés. Si cette option n'est pas spécifiée, le script essaie d'abord d'utiliser Jade, ensuite il essaie OpenJade&.

-o répertoire | --output répertoire Fixe le répertoire de sortie où tous les fichiers résultants seront enregistrés. Si les feuilles de style définissent également un sous-répertoire où les fichiers résultants doivent être enregistrés, alors le sous-répertoire défini par les feuilles de style sera placé dans le sous-répertoire défini par cette option.

-V variable=[valeur] Fixe une variable (à une valeur, si celle-ci est spécifiée).

-u | --nochunks Produit un gros fichier unique. Cette option est utile seulement pour générer du HTML, car la sortie peut être partagée dans plusieurs fichiers. Cette option annule la configuration qui a pu être réalisée dans les feuilles de style.

-i section | --include section Déclare une section marquée SGML comme « include ». Une section marquée SGML est une sorte de partie conditionnelle d'un document. Si elle est déclarée « ignore », elle sera ignorée, autrement, elle sera traitée. Un exemple de telle section marquée peut être :

.nf <DOCTYPE mon_doc [ <!ENTITY % confidentiel "ignore"> ]> <mon_doc> ... <![ %confidentiel [ Du texte confidentiel... ]]> ... </mon_doc> .fi

-w type|list | --warning type|list Active ou désactive l'affichage de types donnés d'avertissements. Plusieurs options -w peuvent être entrées sur la ligne de commande. Les types d'avertissements qui commencent par « no- » désactivent les avertissements correspondants, les autres types les activent. Si le type d'avertissement est remplacé par « list », alors une liste des types d'avertissements autorisés est affichée.

-e type|list | --error type|list Désactive les types donnés d'erreurs. Plusieurs options -e peuvent être entrées sur la ligne de commande. Tous les types d'erreurs commencent par « no- ». Si le type d'erreur est remplacé par « list », alors une liste des types d'erreurs autorisées est affichée.

-h | --help Affiche un court message d'aide et quitte.

-v | --version Affiche l'identificateur de version et quitte.

Fichiers

/etc/sgml/sgml-docbook.cat Le catalogue ouvert SGML centralisé. Ce nom de fichier peut varier si un autre frontend que docbook est utilisé.

/usr/share/sgml/docbook/utils-0.6.14/backends Les différents backends.

/usr/share/sgml/docbook/utils-0.6.14/frontends Les différents frontends.

/usr/share/sgml/docbook/utils-0.6.14/helpers Les différents scripts assistants comme docbook2man ou docbook2texi.

Auteurs


Éric Bischoff (le script shell jw et quelques backends), Jochem Huhmann (les backends man et texi)

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 jw ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

Voir aussi


docbook2man-spec.pl(1), docbook2texi-spec.pl(1), install-catalog(8), nsgmls(1), page d'accueil docbook-utils <URL:http://sources.redhat.com/docbook-tools/>.