OPML 2.0

OPML 2.0
	Outline Processor Markup Language

22/11/07 DW - Il s'agit d'un document publié, à mettre en oeuvre s'il vous plaît, le format OPML 2.0 est figé.

Traduction française par Denis Sureau pour Scriptol.fr.

Spécification en anglais - OPML 1.0

Objectifs du format OPML

Ce document décrit un format pour stocker des plans en XML 1.0 nommé Outline Processor Markup Language ou OPML (en français Langage à Balises de Processeur de Plan).

Le but de ce format est de fournir un moyen pour échanger de l'information entre des logiciels de plans et les services Internet qui puisse être consultée ou controlée par un logiciel de plan.

OPML est aussi le format de fichier pour une application de plan, ce qui explique pourquoi les fichiers OPML peuvent contenir des informations sur la taille, la position et l'état d'expansion de la fenêtre dans laquelle le plan est affiché.

OPML est également devenu populaire comme format d'échange de listes de souscription entre lecteurs de flux et agrégateurs.

L'objectif dans la conception est d'avoir un format simple dans la transparence, l'auto-documentation, extensible et lisible par l'homme, qui soit capable de représenter une grande variété de données, que l'on puisse facilement parcourir et éditer.

C'est un format ouvert, ce qui signifie que d'autres développeurs de logiciels plans et de services sont invités à utiliser ce format pour être compatibles avec Radio Userland, l'Editeur OPML, ou pour toute autre fin.

Qu'est-ce qu'un plan?

Un plan est une arborescence, où chaque noeud contient un ensemble d'attributs nommés avec des valeurs qui sont des chaînes de caractères.

Qu'est-ce qu'un <opml>?

<opml> est un élément XML, avec un seul attribut requis, version; un élément <head> et un élément <body>, tous deux étant requis.

L'attribut version est une chaîne de caractère de version de la forme x.y, où x et y sont des chaînes numériques.

La valeur de version peut être 1.0, si elle est conforme à la version précédente de cette spécification, publiée en 2000; ou 2.0 si elle est conforme à la présente spécification.

Si vous voyez un fichier avec la version 1.1, traitez là comme si c'était un fichier de version 1.0.

Qu'est-ce qu'un <head>?

Un <head> contient zéro éléments optionnels ou plus, décrits ci-dessous.

<title> est le titre du document.

<dateCreated> est une date-heure, indiquant quand le document a été créé.

<dateModified> est une date-heure, indiquant quand le document a été modifié pour la dernière fois.

<ownerName> est une chaîne de caractères, le propriétaire du document.

<ownerEmail> est une chaîne de caractères, l'adresse du propriétaire du document.

<ownerId> est l'adresse http de la page web qui contient l'information permettant à un lecteur humain de communiquer avec l'auteur du document par email ou autre moyen. Il peut être aussi utilisé pour identifier l'auteur. Deux auteurs ne peuvent pas avoir le même ownerID.

<docs> est l'adresse http de la documentation pour le format utilisé dans le fichier OPML. C'est probablement un pointeur sur cette page pour les gens qui pourraient tomber sur le fichier dans 25 ans de là et qui se demanderaient ce que c'est.

<expansionState> est une liste séparée par des virgules des numéros des lignes qui sont développées. Le numéro de ligne dans la liste vous dit quels titres développer. L'ordre est important. Pour chaque élément dans la liste, X, démarrant au premier sommet, on se déplace X fois et on développe. On répète pour chaque élément dans la liste.

<vertScrollState> est un nombre, disant quelle ligne du plan est affichée sur la première ligne de la fenêtre. Ce nombre est calculé en prenant en compte l'état de développement déjà appliqué.

<windowTop> est un nombre, la position du pixel du bord supérieur de la fenêtre.

<windowLeft> est un nombre, la position du pixel du bord gauche de la fenêtre.

<windowBottom> est un nombre, la position du pixel du bord inférieur de la fenêtre.

<windowRight> est un nombre, la position du pixel du bord droit de la fenêtre.

Qu'est-ce qu'un <body>?

Un <body> contient un élément <outline> ou plus.

Qu'est-ce qu'un <outline>?

Un <outline> est un élément XML, contenant au moins un attribut requis, texte et zéro attributs supplémentaire ou plus. Un <outline> peut contenir zéro sous-éléments <outline> ou plus. Aucun attribut ne peut être répété dans le même élement <outline>.

Attribut text

Chaque élément outline doit avoir au moins un attribut text, qui est ce qu'on affiche que un logiciel de plan ouvre le fichier OPML. Omettre l'attribut text rendrait l'affichage du plan inutile dans un logiciel de plan. C'est ce que l'utilisateur devrait voir -- clairement une situation inacceptable.

Un attribut text manquant dans un plan est une erreur.

Les attributs text peuvent contenir du balisage codé en HTML.

Autres attributs spéciaux

type est une chaîne de caractères, il dit comment les autres attributs du <outline> sont interprétés.

isComment est une chaîne de caractères, soit "true" ou "false" (vrai ou faux), indiquant si le plan est commenté ou non. Par convention si un plan est commenté, tous les plans subordonnés sont considérés également comme commentés. S'il n'est pas présent, la valeur est faux.

isBreakpoint est une chaîne de caractères, soit "true" ou "false", indiquant si un point d'arrêt est placé sur le plan. Cet attribut est surtout nécessaire pour les plans utilisés pour éditer des scripts. S'il n'est pas présent la valeur est faux.

created est la date-heure où le noeud du plan a été créé.

category est une chaîne de caractères composée de chaînes délimitées par des slashs et séparées par des virgules, dans le format définit par une élément de catégorie RSS 2.0. Pour représenter une "étiquette", la chaîne de catégorie ne doit pas contenir de slashs.
Exemples:
1. category="/Boston/Weather".
2. category="/Harvard/Berkman,/Politics".

Listes de souscription

Une liste de souscription peut être un liste à plusieurs niveaux de souscriptions à des flux. Chaque sous-élément du corps du document OPML est un noeud de type rss ou un élément de plan qui contient des noeuds de type rss.

De nos jours, la plupart des listes de souscription sont de simples séquences de noeuds rss, mais certains aggrégateurs permettent de catégoriser des listes de souscription qui sont structurées arbitrairement. Un valideur pourrait signaler ces fichiers, en prévenant que des processeurs peuvent ne pas comprendre ni préserver la structure.

Les attributs requis sont: type, text, xmlUrl. Pour les éléments de plan dont le type est rss, l'attribut text devrait initialement être l'élément de titre de plus haut niveau du flux qui est pointé, toutefois, puisque cela est éditable par l'utilisateur, les processeurs ne devraient pas toujours dépendre de ce qui contient le titre du flux.
xmlUrl est l'adresse http du flux.

Les attributs optionnels sont description, htmlUrl, language, title, version. Ces attributs sont utiles pour présenter une liste de souscription à un utilisateur. Sauf pour version ils sont tous dérivés de l'information venant du flux lui-même.

description est l'élément de description de plus haut niveau du flux.
htmlUrl est l'élément lien de plus haut niveau.
language est la valeur de l'élément language de plus haut niveau.
title est probablement la même chose que text, il ne devrait pas être omis, title contient l'élément titre de plus haut niveau du flux.

version varie selon la version du flux RSS qui a été fournie. Cela a été inventé à une époque où l'on pensait qu'il pourrait y avoir des processeurs qui traiteraient seulement certaines versions, mais ce n'est plus devenu un problème important. Les valeurs que cela peut avoir sont RSS1 pour RSS 1.0; RSS pour 0.91, 0.92 or 2.0; scriptingNews pour le format scriptingNews. Il n'y a pas de valeur connus pour les flux Atom, mais ils pourraient certainement être fournis.

Inclusion

Un élément de plan dont les type est link doit avoir un attribut url dont la valeur est une adresse http. L'élément text est, comme de coutume, ce qui est affiche par un logiciel de plan; c'est aussi ce qui est affiché par un moteur de rendu HTML.

Quand un link est développé par un logiciel de plan, si l'adresse finit par ".opml", le plan se développe sur place. C'est ce qu'on appelle inclusion.

Si l'adresse ne se termine pas par ".opml" le lien est supposé pointer sur quelque chose que le navigateur ne peut pas afficher.

En OPML 2.0 un nouveau type est introduit. Un élément de plan dont le type est include doit avoir un attribut url qui pointe sur le fichier OPML à inclure.

La différence entre link et include est que link peut pointer sur quelque chose qui s'affiche dans un navigateur, et include pointe toujours sur un fichier OPML.

Directories

Un directory (répertoire) peut contenir une structure arbitraire d'éléments de plan de type include, link ou rss et éventuellement autres types. Une grande variété de logiciels peut être utilisée pour afficher des répertoires, incluant un logiciel de plan tel que OPML Editor.

Etendre OPML

Un fichier OPML peut contenir des éléments et attributs non décrits dans cette page, seulement si ces éléments sont définis dans un espace de nom comme spécifié par le W3C.

OPML peut aussi être étendu par l'ajout de nouvelles valeurs pour le type attribut. Quand on spécifie une telle extension, en suivant l'exemple de cette spécification, on dit quels attributs sont requis et lesquels sont optionnels, et on explique le rôle que jouent chaque attributs, leurs relations, et à quelles règles ils doivent se conformer. Il y a un mécanisme dans OPML Editor qui est basé sur cette forme d'extension.

Les développeurs devraient, tant que possible, utiliser les possibilités déjà utilisées par les autres, ou incluses dans cette spec, ou les recommandations ou les règles.

Exemples

subscriptionList.opml
states.opml
simpleScript.opml
placesLived.opml
directory.opml
category.opml

Notes

1. Toutes les dates-heure doivent être conformes à la Spécification RFC 822 de Date et Heure, à l'exception de l'année qui peut être exprimée sur deux ou quatre caractères (quatre est préférable).

2. La page dans <ownerId> peut contenir des éléments links pointant sur d'autres documents contenant des informations sur le propriétaire. Par exemple, vous pouvez avoir un élément link pointant sur un document FOAF décrivant le/la propriétaire et son réseau d'amis; ou un flux RSS avec des nouvelles du propriétaire, éventuellement même relatifs par des éléments de catégorie RSS 2.0 à des parties du document OPML. En d'autre mots, tous les mécanismes d'extension de HTML peuvent entrer en jeu.

3. La valeur des attributs type ne sont pas sensibles à la casse, ce qui fait que type="LINK" représente la même chose que type="link".

4. Les attributs de plan ne contiennent généralement pas de code de balisage HTML, à moins qu'ils ne disent explicitement d'inclure un balisage.

5. Les processeurs devraient tous les attributs qu'ils ne reconnaissent pas.

6. Il n'y a pas de limite documentée pour le nombre d'attributs qu'un élément <outline> puisse avoir, ou le nombre d'éléments <outline> qu'il puisse contenir ou la taille de tout attribut.

7. Chaque sous-élément de <head> peut apparaître une fois ou pas du tout. Aucun sous-élément de <head> ne peut être répété.

8. Si une page HTML est générée à partir d'un document OPML, vous pouvez utiliser un élément link HTML pour permettre une "auto-découverte" du OPML. La valeur d'attribut rel est "outline", le type "text/x-opml", et bien sûr l'attribut href contient l'adresse du document OPML.

9. Vous pouvez inclure des éléments de OPML 2.0 dans d'autres formats basés sur XML. L'URI pour l'espace de nom est http://opml.org/spec2. La déclaration d'espace de nom devrait ressembler à ceci: xmlns:opml="http://opml.org/spec2".
Toutefois, pour la compatibilité ascendante, les éléments fondamentaux (ceux définis par cette spec) d'un document OPML 2.0 ne sont pas dans un espace de nom. Voici un exemple d'un fichier RSS 2.0 qui contient un plan dans un de ses éléments.

Feuille de route

La version 2.0 est la dernière version de OPML. Tous développements futurs se feront pas le biais des espaces de nom, de nouveau types de plans, selon la section Etendre OPML de cette spécification; ou dans des formats dérivés de OPML portant des noms différents.

Copyright et autorisation

© Copyright 2000 UserLand Software, Inc. Tous Droits Réservés.
© Copyright 2006-2007 Scripting News, Inc. Tous Droits Réservés.

Ce document et ses traductions peuvent être copiées et fournies à autrui, et les oeuvres dérivées pour le commenter ou pour l'expliquer ou assister à sont implémentation peuvent être rédigées, copiées, publiées et distribuées, entièrement ou en partie, sans restriction d'aucune sorte, pourvu que la notice de copyright ci-dessus et ces paragraphes soient inclus dans ces copies ou oeuvres dérivées.

Ce document ne peut en aucune façon être modifié par la suppression de la notice de copyright ou les références à UserLand ou autres organisations. Par ailleurs, puisque ces restrictions de copyright s'appliquent à l'écrit de la spécification de OPML , aucune revendication de propriété n'est faite par UserLand quand au format qu'il décrit. N'importe qui peut, pour des motifs commerciaux ou non commerciaux, implémenter ce protocole sans droits de licence ou royalties dus à UserLand. Les permissions limitées garanties ci-dessus sont perpétuelles et ne seront pas révoquées par UserLand ou ses successeurs ou représentants.

Le document et les informations ci-dessus sont fournies sur une base "tel quel" et USERLAND DECLINE TOUTES GARANTIES, EXPRESSES OU IMPLIQUEES, INCLUANT SANS S'Y LIMITER A TOUTE GARANTIE QUE L'UTILISATION DE L'INFORMATION CI-DESSUS N'ENFREINDRA AUCUN DROIT OU TOUTE GARANTIE IMPLIQUEE DE COMMERCIALISATION OU D'APPLICABILITE POUR UNE UTILISATION QUELCONQUE.

Licence de la traduction française: Cette traduction peut être imprimée et utilisée librement à condition que les notices de copyright, dont le copyright de traduction ci-dessus, soient conservés. Ce document ne peut être placé sur un autre site Web, on doit plutôt placer un lien sur l'URL ci-dessus - Traduction mise en ligne le 7 Mai 2008.