Mon blog

Comme pour toute série de documents, il vaut mieux que les RFC soient cohérents dans leur style. Si certains RFC mettent les références entre parenthèses et d'autres entre crochets, la tâche du lecteur qui doit lire plusieurs RFC sera plus pénible. D'où cette série de règles, que le RFC Editor impose aux auteurs de RFC.

Rappelons que les RFC et leur RFC Editor sont décrits dans le RFC 8729, et que l'organisation du travail dudit RFC Editor est décrite dans le RFC 6635. L'actuel éditeur est Heather Flanagan, une des auteures de ce RFC 7322.

Les auteurs de RFC sont typiquement des ingénieurs informaticiens, qui n'ont pas forcément eu une formation en écriture et ignorent souvent les règles de base. La section 1 leur rappelle d'abord que le guide de style n'est pas là pour les embêter, mais pour que les RFC soient clairs et cohérents, à la fois en interne et entre eux. Le premier RFC Editor, Jon Postel, avait défini des règles s'imposant à tous les auteurs. Elles sont, en moyenne, bien plus souples que celles qu'imposent les journaux scientifiques ou les conférences et ne devraient donc pas trop gêner les participants à l'IETF.

Ce RFC 7322 est prévu pour être plutôt stable (une des fonctions du système des RFC est de garder les documents disponibles pendant de nombreuses années) et ne contient donc que des règles très solides, qui ont peu de chances de bouger avant de nombreuses années. Il a un inséparable compagnon en ligne, qui le complète avec les règles tout aussi importantes mais peut-être moins stables ou plus récentes.

Les règles de style des RFC ne sont pas spécialement extraordinaires : elles suivent avant tout le CMOS, le Chicago Manual of Style, la référence largement reconnue chez les auteurs anglophones, notamment dans les domaines scientifiques et techniques (mais très traditionaliste, et pas disponible en ligne). Le guide complète le CMOS, notamment pour les questions que ce dernier traite mal, comme la présence de codes informatiques au milieu du texte en anglais.

Enfin, comme tous les RFC commencent comme Internet-Drafts, la lecture du guide d'écriture des ID est également nécessaire à l'auteur débutant.

Armé de ce guide et des bons principes, le (enfin, actuellement, la) RFC Editor va alors (section 2) relire le document, corriger les erreurs, signaler aux auteurs les problèmes que le RFC Editor ne peut pas corriger seul, réparer les incohérences... Le but est qu'il y ait une forte cohérence à l'intérieur du document, presque aussi forte entre les RFC d'un même cluster et un peu moindre entre tous les RFC. (Les clusters sont des groupes de RFC portant sur une norme technique commune, et publiés en même temps, comme par exemple le cluster HTTP/1.1. On trouve une discussion plus détaillée en ligne.)

Attention, le travail du RFC Editor n'est pas technique (au sens de l'informatique). Les problèmes techniques doivent être traités par les auteurs et l'exactitude technique doit toujours avoir le pas sur le style. En aucun cas, le RFC Editor ne doit changer le sens du texte. (En pratique, toute activité éditoriale implique des frictions entre auteurs et éditeurs. L'un des buts du guide est de les minimiser, en expliquant clairement les règles.)

Après la philosophie, les règles (section 3). La première est la langue : pas le choix, les RFC doivent être en anglais. Mais lequel ? Celui de quel côté de la mare ? Britannique ou états-unien ? Faut-il écrire minimisation ou minimization ? meter ou metre ? Sur ce point, comme sur pas mal d'autres, le guide est ouvert : l'auteur fait comme il veut mais doit être cohérent. S'il ne l'est pas, le RFC Editor passera tout en orthographe états-unienne.

Les règles de ponctuation sont celles du CMOS (deux espaces après le point, la virgule avant le dernier élément d'une énumération, etc).

Les noms de domaine utilisés doivent être ceux du RFC 2606 pour éviter toute collision avec des noms réels. Les URI doivent être entre chevrons, comme le demande l'annexe C du RFC 3986. Notez bien que cette règle sur les URI ne s'applique qu'au texte seul (ce qui est le cas des RFC), et c'est pour cela que je ne l'applique pas sur ce blog (où j'écris https://www.example.org/parici).

La capitalisation n'est pas imposée mais elle doit être cohérente, selon les règles de cohérence du document sur les termes. Les mots importants d'un titre ou d'une section sont tous capitalisés, donc on écrit Extension for Named Searches (RFC 5466) et pas Extension for named searches ou Extension For Named Searches.

Et les citations ? Là encore, contrairement à ce qu'on voit souvent dans les revues scientifiques ou les actes des colloques, pas de règle impérative, à part le fait que la citation est entre crochets. Autrement, on peut citer en indiquant un court identificateur, comme « [TRILL-OAM] » (exemple pris dans le RFC 7276), ou en indiquant un numéro comme « [2] » (ce que fait par exemple le RFC 6410).

Et les abréviations ? Elle doivent être détaillées à leur première occurrence (avec l'abréviation entre parenthèses), par exemple « JavaScript Object Notation (JSON) » (vu dans le RFC 7072). On a évidemment le droit à une exception pour les abréviations que tout participant à l'IETF connaît certainement comme TCP ou HTTP. En cas d'oubli, vous avez une liste d'abréviations en ligne.

Enfin, la section 4 de notre RFC décrit la structure normale d'un RFC. Un RFC comporte un certain nombre d'éléments, pas forcément obligatoires. La première page a un contenu obligatoire, avec les avertissements juridiques (« boilerplates ») normalisés par le RFC 7841 (voir aussi le site de l'IETF trust). Elle indique aussi le ou les auteurs et leur organisation. On répète souvent que les participants à l'IETF ne représentent qu'eux-mêmes et pas leur employeur. Mais c'est largement faux, sauf pour la minorité assez riche pour se payer elle-même le temps de participation (et les voyages aux réunions). D'ailleurs, justement, l'employeur de l'auteur est indiqué dans le RFC. À noter que, si plusieurs auteurs ont le même employeur, on ne mentionne parfois ce dernier qu'une fois. Cela rend le texte ambigu : dans le RFC 6382, D. McPherson et R. Donnelly sont-ils au chômage ou bien sont-ils, comme le troisième auteur F. Scalzo, des employés de Verisign ?

La première page indique aussi le numéro ISSN des RFC, 2070-1721 et quelques autres métadonnées.

Le RFC doit aussi contenir un résumé, pour les lecteurs paresseux ou pressés. Publié seul (par exemple dans les catalogues des RFC), il doit être lisible en lui-même, sans faire appel au RFC (donc, sans citations faisant référence à la bibliographie). Souvent, il est simplement fait avec un copier/coller des premiers paragraphes de l'introduction, ce qui est autorisé mais pas forcément optimum.

Il y a parfois aussi une note, qui n'a pas été écrite par les auteurs, mais ajoutée par une des autorités qui a examiné le RFC. Par exemple, le RFC 4408 avait une note de l'IESG exprimant sa prudence vis-à-vis du problème, alors très controversé, d'authentification du courrier électronique. On peut aussi citer le RFC 4776, qui contient une note du RFC Editor expliquant que ce RFC a été publié uniquement pour corriger une erreur dans la valeur du code d'une option DHCP.

Ensuite, le corps du RFC. Il y a des parties qui dépendent du sujet du RFC. Ainsi, les RFC décrivant une MIB incluent en général le texte standard présentant les MIB (voir par exemple le RFC 4898, section 2). Et il y a des parties qu'on trouve dans tous les RFC. Certains termes ont un sens particulier dans les RFC. Ainsi, le lecteur anglophone mais non habitué aux RFC s'étonnera peut-être des MUST ou SHOULD écrits en majuscules. Ils sont définis dans le RFC 2119, l'écriture en majuscules signifiant un sens plus spécifique que le sens vague qu'ils peuvent avoir en anglais.

Les auteurs envoient parfois au RFC Editor un document pas complètement fini, notamment parce que les affectations de codes spécifiques par l'IANA n'ont pas encore été faites (RFC 5226). Par exemple, l'Internet-Draft sur le protocole Babel, draft-chroboczek-babel-routing-protocol, contenait le texte « IANA has registered the UDP port number TBD, called "babel", for use by the Babel protocol. » Une fois un port réservé officiellement, le « TBD » (To Be Done) a été remplacé et le RFC 6126 dit « IANA has registered the UDP port number 6697, called "babel", for use by the Babel protocol. ».

À la fin du RFC, se trouvent des sections plus ou moins standardisées, comme la fameuse (et obligatoire) « Security Considerations » (RFC 3552), qui doit permettre de s'assurer que les auteurs du RFC ont pensé aux problèmes de sécurité éventuels. Facultative, en revanche, la section sur les questions liées à l'internationalisation du protocole (RFC 2277).

Reste la bibliographie : elle comporte deux parties, une avec les références normatives et une avec le reste. Une des conséquences est que, si une référence normative est un Internet-Draft pas encore publié, la publication du futur RFC devra attendre. Une référence non-normative, elle, peut être un Internet-Draft non publié. Dans ce cas, il est marqué comme « Work in Progress » pour bien indiquer son manque de stabilité. Quand un RFC est cité, c'est parfois via son numéro de norme ou de BCP (Best Current Practice) car une telle référence est plus stable. Les URI sont autorisés dans la bibliographie, à condition qu'ils soient raisonnablement stables. Ainsi, BCP47 désignait au début le RFC 4646 et le RFC 4647 (oui, un BCP peut correspondre à plusieurs RFC) et, lorsque le RFC 4646 a été remplacé par le RFC 5646, le numéro de BCP n'a pas changé, pointant toujours vers la version la plus récente des bonnes pratiques.

Le RFC se termine aussi par des remerciements aux contributeurs. Le guide note qu'il n'y a pas de règles précises concernant qui est noté comme contributeur. C'est à l'initiative des auteurs. Par exemple, je suis cité comme contributeur dans dix-sept RFC mais cela correspond à des niveaux de participation très différents, d'une vraie participation à juste quelques corrections de détail. Et certains auteurs ont choisi de régler le problème des contributeurs avec une formule attrape-tout comme dans le RFC 4408 « The authors would also like to thank the literally hundreds of individuals who have participated in the development of this design. They are far too numerous to name [...] ».

Un dernier détail, les adresses de courrier électronique dans les RFC doivent être intactes (pas de modification comme rfc-editor (at) rfc-editor.org). Le but des adresses est de pouvoir contacter les auteurs et cela implique de ne pas faire de modifications.

Voilà, c'est fini. Ah, que faire en cas de conflit insoluble entre un auteur et le RFC Editor ? Comme rappelé par l'annexe A, on suit les procédures du RFC 6635.