openjade [-vCegG2s] [-b encodage] [-f fichier_erreur]
[-c catalog_sysid] [-D répertoire] [-a type_lien]
[-A arch] [-E erreurs_max] [-i entité]
[-w type_avertissement] [-d dsssl_spec] [-V variable=valeur]
[-t type_sortie] [-o fichier_sortie] [sysid...]
openjade est une implémentation du langage DSSSL défini par la norme ISO/IEC 10179:1996. Le moteur DSSSL reçoit en entrée un document SGML ou XML et le transforme en des formats tels que :
* la représentation, en XML, du graphe d'objets flux,
* le format RTF, qui peut être rendu et imprimé avec le logiciel gratuit « Word Viewer 97 » de Microsoft,
* le format TeX
* le format MIF, qui peut être rendu et imprimé avec Framemaker,
* le format SGML ou XML. Il est utilisé conjointement avec des classes d'objets flux non-standards pour générer du SGML, permettant ainsi à openjade d'être utilisé pour des transformations SGML/XML.
L'identifiant système du document à traiter est spécifié comme argument à openjade. Si celui-ci est omis, l'entrée standard sera lue.
openjade détermine l'identifiant système pour la spécification DSSSL de la façon suivante :
1. Si l'option -d est spécifiée, il utilisera l'argument comme identifiant système.
2. Autrement, il cherchera les instructions de traitement dans le prologue du document. Deux sortes d'instructions de traitement sont reconnues :
<?stylesheet href="sysid" type="text/dsssl">
La composante système de l'instruction de traitement est analysée comme une balise ouvrante SGML. Elle sera analysée selon la syntaxe concrète de référence, quelle que soit la syntaxe concrète réelle du document. Le nom qui démarre l'instruction de traitement peut être « stylesheet », « xml-stylesheet » ou « xml:stylesheet ». L'instruction de traitement sera ignorée à moins que la valeur de l'attribut « type » ne soit « text/dsssl », « text/x-dsssl », « application/dsssl », ou bien « application/x-dsssl ». La valeur de l'attribut « href » est l'identifiant système de la spécification DSSSL.
<?dsssl sysid>
L'identifiant système est la partie de la composante système de l'instruction de traitement suivant le premier nom et l'espace.
Bien que l'instruction de traitement ne soit seulement reconnue que dans le prologue, il n'est pas nécessaire qu'elle apparaisse dans l'entité document. Par exemple, elle peut se trouver dans une DTD. L'identifiant système sera interprété relativement à l'endroit où l'instruction de traitement apparaît.
3. Autrement, il utilisera l'identifiant système du document avec son extension changée en .dsl.
Un document de spécification DSSSL peut contenir plus d'une spécification de style. Si l'identifiant système de la spécification DSSSL est suivi par « #id », alors openjade utilisera la spécification de style dont l'identifiant unique est « #id ». Ceci est autorisé simultanément avec l'option -d et les instructions de traitement.
La spécification DSSSL doit être un document SGML conforme à l'architecture DSSSL. Pour un exemple, voir dsssl/demo.dsl.
openjade accepte les options suivantes en plus des options OpenSP (voir onsgmls(1)) régulières (notez que toutes les options sont sensibles à la casse, c.-à-d. que -g et -G sont des options différentes) :
fot Une représentation XML du graphe d'objets flux
rtf rtf-95 RTF (utilisée pour des transformations de SGML/XML vers RTF) Rich Text Format de Microsoft. rtf-95 produit une sortie optimisée pour Word 95 plutôt que Word 97.
tex TeX (utilisée pour des transformations de SGML/XML vers TeX)
sgml sgml-raw SGML (utilisée pour des transformations de SGML/XML vers SGML). sgml-raw n'insère pas de sauts de ligne à l'intérieur des balises.
xml xml-raw XML (utilisée pour des transformations de SGML/XML vers XML). xml-raw n'insère pas de sauts de ligne à l'intérieur des balises.
html HTML (utilisée pour des transformations de SGML/XML vers HTML)
mif MIF (utilisée pour des transformations de SGML/XML vers MIF)
xml Avertissement sur les constructions non permises par XML.
mixed Avertissement sur les modèles de contenu mixte qui ne permettent nulle part « #pcdata ».
sgmldecl Avertissement sur différentes constructions douteuses dans la déclaration SGML.
should Avertissement sur différentes recommandations faites dans l'ISO 8879 avec lesquelles le document n'est pas conforme. (Les recommandations sont exprimées avec « should », ce qui est distinct des exigences qui sont généralement exprimées avec « shall »).
default Avertissement sur les références manquantes.
duplicate Avertissement sur les déclarations d'entité doubles.
undefined Avertissement sur les éléments non définis : éléments utilisés dans la DTD mais non définis.
unclosed Avertissement sur les balises ouvrantes et fermantes non appareillées.
empty Avertissement sur les balises ouvrantes et fermantes vides.
net Avertissement sur les balises ouvrantes rendant possible les balises fermantes nulles et sur les balises fermantes nulles (NdT : net=null end tag).
min-tag Avertissement sur les balises ouvrantes et fermantes minimisées. Équivalent à une combinaison des avertissements unclosed, empty et net.
unused-map Avertissement sur la non utilisation d'assignations d'appels abrégés (NdT : short reference map) : ces assignations sont déclarées dans une déclaration d'assignation d'appels abrégés, mais jamais utilisées dans une déclaration d'utilisation d'appels abrégés dans la DTD. (NdT : pour plus d'informations sur les appels abrégés, vous pouvez consulter la page, en anglais, http://www.sgml.u-net.com/book/sgml-7.htm#SHORTREF)
unused-param Avertissement sur les entités paramètres définies mais non utilisées dans une DTD. Les entités paramètres internes non utilisées, dont le texte est INCLUDE ou IGNORE, ne produisent pas d'avertissement.
notation-sysid Avertissement sur les notations pour lesquelles aucun identifiant système ne peut être généré.
all Avertissement sur les conditions qui pourraient être évitées (de l'avis de l'auteur). Équivalent à : mixed, should, default, undefined, sgmldecl, unused-map, unused-param, empty et unclosed.
Un avertissement peut être désactivé en utilisant son nom préfixé par « no- ». Ainsi -wall -wno-duplicate activent tous les avertissements exceptés ceux concernant les déclarations d'entités dupliquées.
Les valeurs suivantes de type_avertissement désactivent les erreurs :
no-idref Ne pas signaler d'erreur lorqu'on fait une référence à un identifiant, alors qu'aucun élément n'a cet identifiant. L'effet en est que chaque attribut déclaré comme une référence à un identifiant se comporte comme un nom ordinaire.
no-significant Ne pas produire d'erreur lorsqu'un caractère, qui n'est pas un caractère significatif dans la syntaxe concrète de référence, apparaît dans un nom de la déclaration SGML. Cela peut être pratique conjointement avec des suites logicielles de test.
no-valid Ne nécessite pas que le document soit de type valide. Cela a pour effet de modifier la déclaration SGML pour spécifier VALIDITY NOASSERT et IMPLYDEF ATTLIST YES ELEMENT YES. Une option -wvalid a pour effet de modifier la déclaration SGML pour spécifier VALIDITY TYPE et IMPLYDEF ATTLIST NO ELEMENT NO. Si ni -wvalid ni -wno-valid ne sont spécifiées, alors VALIDITY et IMPLYDEF, spécifiées dans la déclaration SGML, seront utilisées.
OpenJade ignore les variables d'environnement SP_CHARSET_FIXED et SP_SYSTEM_CHARSET et utilise toujours Unicode comme jeu de caractères interne, comme si SP_CHARSET_FIXED vallait 1 et SP_SYSTEM_CHARSET n'était pas fixée. Par conséquent, seule la variable d'environnement SP_ENCODING joue un rôle dans la gestion des jeux de caractères de OpenJade.
Les procédures externes suivantes sont disponibles. Ces procédures externes sont définies par un prototype de la même manière que dans la norme. Pour utiliser l'une de ces procédures externes, vous devez utiliser la procédure standard « external-procedure », utilisant un identifiant public "UNREGISTERED::James Clark//Procedure::name" où « name » est le nom donné ici, typiquement en incluant ce qui suit dans la spécification DSSSL :
(define name (external-procedure "UNREGISTERED::James Clark//Procedure::name"))
Notez que « external-procedure » retourne « #f » si elle ne connaît pas l'identifiant public spécifié (NdT : dans la syntaxe DSSSL, « #f » signifie « false »). Vous pouvez utiliser ceci pour permettre à vos spécifications DSSSL de travailler gracieusement avec d'autres implémentations qui ne supportent pas ces extensions.
Pour les procédures externes ajoutées par l'équipe d'OpenJade, utilisez un identifiant public de la forme "UNREGISTERED::OpenJade//Procedure::name".
Un moyen facile pour accéder à toutes les procédures externes est d'utiliser la spécification de style dsssl/extensions.dsl#procedures. Le fichier dsssl/extensions.dsl contient également des spécifications de style qui rendent les classes d'objets flux non-standards et les caractéristiques héritées supportables, de manière pratique, par les backends disponibles.
Débogage
(debug obj)
Génère un message incluant la valeur de « obj » et ensuite retourne « obj ».
Contrôle en-tête/pied de page d'une séquence « Simple-page-sequence »
(if-first-page sosofo1 sosofo2)
Ceci ne peut être utilisé que dans la spécification de la valeur de l'une des caractéristiques en-tête/pied de page d'une séquence « simple-page-sequence ». Une séquence « sosofo » est retournée, qui sera rendue en tant que « sosofo1 » si la page est la première page d'une séquence « simple-page-sequence » et « sosofo2 » autrement. (NdT : dans le jargon DSSSL, « sosofo » signifie « specification of a sequence of flow objects »
(if-front-page sosofo1 sosofo2)
Ceci ne peut être utilisé que dans la spécification de la valeur de l'une des caractéristiques en-tête/pied de page d'une séquence « simple-page-sequence ». Une séquence « sosofo » est retournée, qui sera rendue en tant que « sosofo1 » si la page est une page de face (c.-à-d. recto, impaire) et « sosofo2 » si c'est une page de dos (c.-à-d. verso, paire).
Numérotage
(all-element-number)
(all-element-number osnl)
C'est la même chose que « element-number », excepté qu'il compte les éléments avec un identifiant générique. Si « osnl » n'est pas un élément, il retourne #f, autrement il retourne 1 plus le nombre d'éléments qui ont commencé avant « osnl ». Cela fournit un moyen efficace pour créer un identifiant unique pour tous les éléments d'un document.
Accès aux entités externes
(read-entity string)
Elle retourne une chaîne composée du contenu de l'entité externe avec la chaine identifiant système. Ceci ne peut être utilisé qu'avec des entités texte (CDATA et SDATA), pas avec des entités binaires (NDATA).
Accès aux locales POSIX
(language lang country)
Cette procédure retourne un objet de type langue, si le système supporte la langue spécifiée. « lang » est une chaîne de caractères ou un symbole donnant les deux lettres du code de la langue. « country » est une chaîne de caractères ou un symbole donnant les deux lettres du code du pays.
Cette procédure utilise les locales POSIX. C'est un ajout OpenJade. Ceci n'est pas supporté par tous les systèmes d'exploitation.
Procédures standards étendues
(sgml-parse sysid #!key active: parent: architecture:)
Cela vous permet de spécifier une architecture SGML en respect de laquelle le document doit être analysé. C'est un ajout OpenJade.
(expt q k)
Cela vous permet d'élever une quantité à une puissance entière. C'est un ajout OpenJade.
Cette section décrit les limitations de l'interface d'entrée (le moteur DSSSL universel) ; chaque interface de sortie a également ses propres limitations.
openjade ne permet pas de définitions internes au début des corps et dans la variante (test => destinataire) des clauses conditionnelles.
openjade accepte seulement un unique plan « bosquet » fixé qui comprend les modules suivants (NdT : un « bosquet » est un ensemble d'« arbres » de propriétés DSSSL ; la phrase originale cite « a single, fixed grove plan », où grove est l'acronyme de Graph Representation of Property ValuEs) :
* baseabs
* prlgabs0
* prlgabs1
* instabs
* basesds0
* instsds0
* subdcabs
Il n'implémente pas les parties suivantes de SDQL : support HyTime (NdT : Hypermedia/Time-based Structuring Language), analyse auxiliaire, expressions régulières de noeud.
Règles d'interrogation, synchronisation « sosofo », « sosofos » indirectes, valeurs de référence, zones de décoration et propriétés de polices de caractères ne sont pas supportées.
Veuillez noter que seules les caractéristiques héritées, applicables à des objets flux supportés, peuvent être spécifiées.
Gestion des caractères et des glyphes
Il gère seulement un répertoire unique de caractères prédéfinis. Un nom de caractère de la forme U-XXXX, où XXXX sont quatre caractères alphanumériques hexadécimaux majuscules, est reconnu comme se référant au caractère Unicode du code concerné. Pour bien des caractères, il est également possible d'utiliser le nom « ISO/IEC 10646 » en minuscule avec des mots séparés par des traits d'union.
Certains noms courants d'entités SDATA du jeu d'entités ISO sont reconnus et assignés à des caractères. De plus, un nom d'entité SDATA de la forme U-XXXX, où XXXX sont quatre caractères alphanumériques hexadécimaux majuscules, est assigné au caractère Unicode avec ce code.
OpenJade accepte maintenant les formes de déclarations d'éléments « standard-chars », « map-sdata-entity », « add-name-chars », « add-separator-chars » et « char-repertoire », permettant à une feuille de style de définir des noms de caractères, des assignations d'entités « sdata », des caractères de noms (c.-à-d. des caractères autorisés dans les identifiants) et des caractères séparateurs supplémentaires. Actuellement, le seul répertoire de caractères reconnu est le répertoire intégré. Il a un identifiant public "UNREGISTERED::OpenJade//Character Repertoire::OpenJade".
Validation
Plusieurs choses qu'il aurait été souhaitable de vérifier ne le sont pas :
* Quand la valeur autorisée d'une caractéristique héritée est un symbole, OpenJade vérifie seulement que la valeur est un symbole autorisé comme la valeur d'une caractéristique ; #t et #f sont traités, dans ce cas, comme une sorte spéciale de symbole.
* OpenJade ne vérifie pas si un objet flux apparaît dans un contexte où il est autorisé.
* OpenJade n'empêche pas des objets flux d'être attachés au port principal d'un objet quand l'objet flux ne devrait pas avoir de port principal.
* La plupart des vérifications de type sont faites à l'exécution, pas à la compilation.
* OpenJade n'effectue pas de vérifications sur les caractéristiques non héritées qui nécessitent d'être spécifiées.
* Il ne vérifie pas si les fonctionnalités optionelles, qui doivent être utilisées, sont déclarées dans la forme des fonctionnalités.
Autres limitations
Les primitives suivantes ne sont que des squelettes :
char-script-case Retourne toujours le dernier argument.
address-visited? Retourne toujours #f.
Pour un fichier SGML file.sgml donné, utiliser la feuille de style file.dsl et le publier au format rtf.
openjade -t rtf file.sgml
Utiliser une feuille de style différente :
openjade -t rtf -d docbook.dsl file.sgml
Utiliser la spécification de style print contenue dans la feuille de style
openjade -t rtf -d docbook.dsl#print file.sgml
Et utiliser la spécification html de la feuille de style pour convertir vers html
openjade -t sgml -i html -d docbook.dsl#html file.sgml
onsgmls(1)
Je remercie infiniment Éric Bischoff sans lequel cette traduction aurait eu du mal à voir le jour.