diff options
Diffstat (limited to '')
-rw-r--r-- | RFC_7991_The_xml2rfc_Version_3_Vocabulary.txt | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/RFC_7991_The_xml2rfc_Version_3_Vocabulary.txt b/RFC_7991_The_xml2rfc_Version_3_Vocabulary.txt new file mode 100644 index 0000000..6a3aa14 --- /dev/null +++ b/RFC_7991_The_xml2rfc_Version_3_Vocabulary.txt @@ -0,0 +1,271 @@ +Titre: RFC 7991: The "xml2rfc" Version 3 Vocabulary +Auteur: +Date: Fri 16 Dec 2016 01:00:00 +0100 +Lien: https://www.bortzmeyer.org/7991.html + +Contrairement à beaucoup de SDO, l'IETF n'avait pas de format standard pour +l'écriture de ses documents. Désormais, avec le nouveau cadre décrit dans le +RFC 7990, c'est fait. XML, avec le vocabulaire décrit dans ce nouveau RFC, est +le format canonique des RFC. + +Vous voulez écrire un RFC ? Il est fortement recommandé d'utiliser dès le début +le format standard XML, fondé sur un vocabulaire spécifique aux RFC, et mis en +œuvre dans la future version de l'outil xml2rfc[1]. Voici donc le vocabulaire +« XML2RFC version 3 », succédant à deux versions qui n'étaient pas +officiellement standard (les changements depuis la v2, spécifiée dans le RFC +7749, ne sont pas énormes). Notez que le vocabulaire XML et les outils +continuent à évoluer, donc ce RFC n'est pas éternel. Et que la version 2 +restera sans doute en service pendant encore des années : cela prend du temps +de changer les habitudes ! + +Voici le squelette d'un Internet-Draft écrit avec ce XML : + + + +<>?xml version="1.0" encoding="utf-8"?> +<>rfc docName="draft-ietf-dnsop-qname-minimisation-09" submissionType="IETF" + ipr="trust200902"> +<>front> +<>title abbrev="Qname minimisation">DNS query name minimisation to improve privacy<>/title> +... +<>middle> +<>section anchor="intro" title="Introduction and background"> +<>t>The problem statement is described in <>xref +target="RFC7626"/>. [...] +... +<>/back> +<>/rfc> + +Sur ce squelette simple, on voit l'élément racine (<>rfc>), l'utilisation des +attributs (comme submissionType qui indique la voie prise par le document, ici, +l'IETF, cf. RFC 7841), la séparation en trois parties, <>front>, qui regroupe +les métadonnées, <>middle>, qui est le texte principal, et <>back>, où se +trouvent la bibliographie, les annexes, etc. + +Parmi les attributs de cet élément racine <>rfc>, notez ipr, qui indique les +conditions légales d'utilisation de ce RFC. Dans cet example, la valeur est la +plus couramment utilisée : trust200902 (cf. l'annexe A.1) indique les règles de +l'IETF Trust[2] datant de 2009 (qui disent en gros que le texte du RFC peut +être librement copié, reproduit, distribué et mis en œuvre dans des +programmes). L'annexe A de notre RFC détaille ce qu'on appelle le boilerplate, +ces textes juridiques obligatoires qui sont ajoutés automatiquement par le +logiciel xml2rfc. Ainsi, si on met ipr="trust200902" dans l'élément <>rfc>, +xml2rfc va automatiquement ajouter « Copyright (c) 2015 IETF Trust and the +persons identified as the document authors. All rights reserved. \ This +document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to +IETF Documents [...] »... + +Le gros morceau du RFC est la section 2, qui donne la liste des éléments XML +acceptés. Je ne vais pas reproduire ici cette liste, juste parler de quelques +éléments qui me semblent rigolos. + +<>section> contient une partie du RFC. Cet élément est hiérarchique : on crée +des sous-sections en les mettant sous les sections existantes, et ainsi de +suite, récursivement. (Contrairement à ce qui se passe avec HTML, où on indique +explicitement le niveau de la section, <>h1>, <>h2>, etc.) On a aussi +<>abstract>, qui indique le résumé au début du RFC. + +<>t> contient un paragraphe et est donc l'équivalent du <>p> de HTML. + +<>artwork> permet de spécifier du texte qui sera représenté comme tel, sans +aucune justification, mise à la ligne, etc. (Les tabulations sont interdites, +ce qui règle le vieux débat « tabs vs. spaces[3] ».) <>artwork> permet de +mettre de l'art ASCII dans un RFC, mais la méthode préférée pour les images est +désormais SVG, voir le RFC 7996. Le SVG peut être mis directement dans le +source XML ou bien inclus par différentes méthodes, dont l'attribut src. Cet +attribut src permet de spécifier un fichier externe, l'art ASCII ne servant +alors que de solution de secours, pour le format en texte seul. Un attribut +type permet d'indiquer le type du dessin (par exemple svg pour les images en +SVG). La liste des types possibles sera en ligne. Voici un exemple d'art +ASCII : + + +<>artwork type="ascii-art"> + +--------------+ +----------------+ + | Alice |------------------------------------| Bob | + | 2001:db8::1 | | 2001:db8::2 | + +--------------+ +----------------+ +<>/artwork> + +Le code source, lui, se fait avec l'élément <>sourcecode>, un attribut type +permettant d'indiquer le langage utilisé (une liste des valeurs possibles sera +en ligne). Voici un exemple : + + +<>sourcecode type="python"> + print("Hello, world") +<>/sourcecode> + +Comme le langage utilisé peut utiliser des caractères qui sont spéciaux pour +XML (comme <> ou &), il est souvent préférable de mettre le code source dans +une section CDATA. + +<>eref> permet de faire un lien hypertexte vers l'extérieur : + + + <>t>More text and a <>eref + target="http://www.rfc-editor.org/">lien vers le site du RFC Editor<>/eref>.<>/t> + + +<>ul> permet de représenter les traditionnelles listes à puces : + + +<>t>There are three sorts of DNS requests being issued:<>/t> +<>ul> +<>li>Primary request: [...]<>/li> +<>li>Secondary requests: [...]<>/li> +<>li>Tertiary requests: [...]<>/li> +<>/ul> + + +<>references> permet d'indiquer une bibliographie. Il y en a typiquement deux +dans un RFC (cf. la section 4.8.6 du RFC 7322), la bibliographie normative (ce +qu'il faut absolument avoir lu et compris car le RFC en dépend) et +l'informative (ce qu'on peut sauter si on est pressé). Pour aider, le RFC +Editor distribue des fichiers XML contenant les références aux RFC publiés, +comme http://www.rfc-editor.org/refs/bibxml/reference.RFC.7626.xml[4]. + +Le nom d'un auteur de RFC se met avec l'attribut <>author>. Comme il peut être +en caractères non-ASCII, des attributs permettent d'indiquer une variante en +ASCII seul. Par exemple : + + +<>author fullname="Patrik Fältström" asciiFullname="Patrik Faltstrom"> + <>organization>Netnod<>/organization> +<>/author> + +Ce format de RFC s'appuie sur XML et il faut donc suivre les règles de XML, +notamment sur les caractères spéciaux. Ainsi, le chevron ouvrant doit être +remplacé par une séquence d'échappement (< au lieu de <>). Si cette +contrainte est trop forte, on peut aussi enclore les parties à « échapper » +dans une section CDATA. + +Le format des RFC permet d'autres caractères que ceux du jeu ASCII, mais avec +certaines restrictions (voir RFC 7997). + +Le format actuel permet l'inclusion d'autres documents, via des attributs comme +l'attribut src pour le code source : + + +<>sourcecode type="python" src="hello.py"/> + +On peut aussi utiliser les mécanismes génériques d'inclusion de XML, comme +XInclude (cf. annexe B.1) ou les entités, et c'est souvent utilisé pour la +bibliographie : + + + <>!DOCTYPE rfc [ + <>!ENTITY rfc7830 PUBLIC + "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7830.xml"> + ]> + +[...] + <>references> + &rfc7830; + <>/references> + + +À noter qu'il existe un type MIME pour les sources XML de RFC, +application/rfc+xml (section 8 de notre RFC). + +Si vous voulez voir le schéma XML complet, il est en annexe C (j'en ai exporté +une version utilisable telle quelle, sans les sauts de page des RFC, en +rfc-v3.rnc[5]). Comme il est écrit en Relax NG, il permet l'utilisation de tous +les outils Relax NG, comme le mode emacs nxml-mode[6] et comme rnv[7]. Ainsi, +une fois le fichier rfc-v3.rnc chargé dans emacs (menus XML puis Set schema +puis File), on dispose de fonctions d'édition bien pratiques (par exemple, on +tape un <> puis une tabulation et emacs propose de compléter uniquement avec +les éléments autorisés à cet endroit). Cela évite bien des erreurs. + +À noter que ce RFC ne décrit que les éléments et attributs XML, pas de +processing instructions (PI), qui ne sont plus acceptées. + +Avec un logiciel comme rnv[7], on peut tester la syntaxe (uniquement la +syntaxe : certaines contraintes dans le RFC ne sont pas exprimables dans le +schéma, il a fallu les formuler en langue naturelle dans le texte du RFC) : + +% rnv rfc-v3.rnc rfc-v3-sample.xml +rfc-v3-sample.xml +Parfait, ici, tout est bon. S'il y avait eu une erreur : + +% rnv rfc-v3.rnc rfc-v3-sample-wrong.xml +rfc-v3-sample-wrong.xml +rfc-v3-sample-wrong.xml:9:6: error: element ^t not allowed +required: + element ^section +rfc-v3-sample-wrong.xml:11:2: error: unfinished content of element ^middle +required: + element ^section +error: some documents are invalid +Si le RFC contient des références externes (que rnv ne sait pas traiter), on +peut utiliser xmllint pour les remplacer : + +% xmllint --dropdtd --noent draft-dupont-my-protocol.xml | rnv rfc-v3.rnc + +On peut aussi utiliser Jing[8] (annexe C.1). Mode d'emploi très court, on +télécharge[9] : + +% wget https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/jing-trang/jing-20091111.zip +% unzip jing-20091111.zip +% java -jar ./jing-20091111/bin/jing.jar -c rfc-v3.rnc draft-dupont-my-protocol.xml +% + +Les changements depuis le texte précédent, le RFC 7749, qui décrivait la +version 2 (notre RFC est la version 3), sont décrits dans l'annexe D et résumés +en section 1.3. L'idée était notamment d'avoir un vocabulaire plus facile à +utiliser, sans pour autant trop changer par rapport au format v2, qui était +bien connu des auteurs. + +Le changement le plus spectaculaire concerne les listes, qui sont désormais +faites, comme en HTML, avec des <>dl>, <>ul> et <>ol>. Dans une liste, le +contenu est marqué par <>li> et plus <>t>. Autre inspiration HTML, l'apparition +des tables, avec <>table> (et éléments associés comme <>tr> et <>td>). D'autre +part, de nouveaux éléments apparaissent pour marquer du texte, par exemple s'il +est important (<>em>, qui n'avait pas d'équivalent en v2, dont le seul format +de sortie était le texte brut). Il y a aussi un <>blockquote> pour les +citations. Bien que l'IETF se vante souvent de pratiquer le culte du « running +code », il n'y avait pas d'élément XML particulier pour indiquer du code source +dans un RFC (on se contentait d'<>artwork>). C'est désormais fait avec +<>sourcecode>. Quelques autres éléments XML nouveaux (je ne les cite pas tous, +le RFC fait 159 pages !) : <>displayreference> pour associer un chouette texte +aux références, <>link> pour les liens externes (contrairement à <>eref>, qui +existait déjà, <>link> est spécifique à certains types de documents, par +exemple les Internet-Drafts) ou encore <>br> pour forcer des sauts de ligne +(mauvaise idée que de mettre des éléments de présentation, si vous voulez mon +avis). + +Il y a aussi de nouveaux attributs XML aux éléments existants. Pour remplacer +les PI (processing instructions comme <>?rfc toc="yes"?>), on a tocInclude et +tocDepth dans l'élément <>rfc>, afin de contrôler la table des matières. De +même, pour gérer l'internationalisation, il y a désormais un attribut ascii +pour les éléments qui acceptent du contenu non-ASCII, afin de fournir une +alternative pour les anglophones. Il y a aussi des attributs plus orientés +présentation comme keepWithNext ou keepWithPrevious, attributs de <>t>, qui +expriment un souhait de garder ce paragraphe avec le suivant ou le précédent, +pour mieux contrôler la pagination. + +En revanche, certains éléments et attributs sont retirés de la circulation. Ils +seront encore acceptés par les outils, mais temporairement. <>list> subit ce +trist sort (remplacé par les éléments HTMLisant comme <>ul> et <>ol>). +<>facsimile> disparait également, victime des évolutions technologiques. Parmi +les attributs, title disparait (il était utilisé dans des éléments comme +<>section>) au profit de name (changement assez gratuit, je trouve). + +Les autres changements sont bien sûr l'acceptation de caractères non-ASCII, et +plein de modifications de détail. + +Question mise en œuvre, il faudra patienter. S'il y a déjà eu des mises en +œuvre expérimentales[10] et partielles, les vrais logiciels officiels ne sont +pas encore, en octobre 2016, développés. + +Liens: +[1]: http://xml2rfc.ietf.org/ (lien) +[2]: https://trustee.ietf.org/ (lien) +[3]: https://opensourcehacker.com/2012/05/13/never-use-hard-tabs/ (lien) +[4]: http://www.rfc-editor.org/refs/bibxml/reference.RFC.7626.xml (lien) +[5]: http://www.bortzmeyer.org/files/rfc-v3.rnc (lien) +[6]: https://www.emacswiki.org/emacs/NxmlMode (lien) +[7]: http://www.davidashen.net/rnv.html (lien) +[8]: http://www.thaiopensource.com/relaxng/jing.html (lien) +[9]: https://github.com/relaxng/jing-trang (lien) +[10]: http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#v3 (lien) |