Initiale releaseHEADmaster

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 (&lt; 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)