Règles d’écriture du plugin.xml

, par _Eric_

Une première liste de recommandations et/ou de règles pour écrire le contenu des balises XML du fichier plugin.xml.

La plupart de ces réflexions ont été intégrées dans les articles SVP, objectifs et mise en oeuvre et Des DTD pour décrire et archiver les plugins. Les conclusions sont repérées en rouge dans le texte : DTD indique une prise en compte par la DTD de paquet.xml, SVP une prise en compte par la fonction de lecture du fichier xml de SVP.

Les balises propres à l’entité Plugin

Ces balises alimentent la table spip_plugins de SVP et les deux règles suivantes s’appliquent :

  • Règle RPLUG-0, erreur : toutes les balises propres à l’entité Plugin sont obligatoires. DTD
  • Règle RPLUG-1, erreur : elles sont identiques pour tous les paquets d’un même plugin. SVP

Balise <prefix>
Pas de recommandation particulière si ce n’est l’application des règles RPLUG.

Balise <nom>
L’idée générale est que le nom doit être un repère simple et unique pour le plugin :

  • Règle RNOM-1, avertissement : le nom doit être court (80 caractères ?) et ne pas comporter de slogan comme, par exemple, CFG : moteur de configuration. Utiliser dans ce cas la nouvelle balise <slogan>. DTD ou SVP ?
  • Règle RNOM-2, erreur : pas de caractères 2, 3.0 en fin de nom pour désigner une branche, le nom est unique SVP
  • Règle RNOM-3, erreur : pas de multi-langues pour le nom qui doit toujours être lu de la même façon. « Mes fichiers » n’est jamais connu sous le nom « My files » et comment traduire « Social Tags » ? DTD

Balise <categorie>

  • Règle RCAT-1, erreur : alias de la catégorie devant appartenir à la liste prédéfinie. DTD

Balise <slogan>
Cette nouvelle balise a pour but de donner une explication courte et pertinente sur l’objet du plugin. Elle est utilisée dans la plupart des affichages pour compléter le nom. Le slogan peut/doit être multi-langues.

  • Règle RSLOG-1, avertissement : le slogan doit être court (150-200 caractères ?).
    DTD ou SVP ?

Balise <icon>
Pas de recommandation particulière si ce n’est l’application des règles RPLUG. Pourtant, j’aurais bien aimé la renommer en <logo> pour éviter de se poser la question “avec ou sans e ?” par amalgame avec la balise <icone> des boutons. Renommée logo dans la DTD

Les balises propres à l’entité Paquet

Ces balises alimentent la table spip_paquets de SVP. Aucune règle générale ne peut être énoncée.

Balises <version> et <version_base>
Ne peut-on pas simplifier la nomenclature et le processus de transition ?

  • x.y pour la version de base,
  • x.y.z pour la version du plugin en se limitant à un digit pour chaque numéro : donc pas de 1.925 ni de 1.9.12.
  • ne pas utiliser de suffixe type dev, alpha... qui sont quand même superflus pour un plugin sachant en plus que l’on dispose de la balise <etat> pour compléter l’information de version.
  • augmenter chaque fois que cela est nécessaire x, y ou z d’une unité en considérant qu’une nouvelle branche incrémente forcément x
    Abandonnée

Balise <etat>

  • Règle RETAT-1, erreur : alias de l’état du plugin devant appartenir à la liste prédéfinie dans SPIP. DTD

Balise <branche>
C’est une nouvelle balise qui permet d’éviter de changer le nom du plugin comme dans Accès restreint 3.0 ou Mes fichiers 2, par exemple. Il me parait préférable de conserver le nom « Accès restreint » et de créer un balise branche égale à « 3.0 » ce qui est en général le cas sur le dépôt SVN.

La branche pourrait contenir de préférence un numéro ou un numéro de version mais pourquoi pas imaginer un libellé court comme « Kiss » pour distinguer « Tickets » et « Tickets Kiss » (balise troll ?) !

Abandonnée

Balises <auteur> et <licence>
La balise <auteur> est souvent l’expression de crédits divers, de licence voire de copyright. Il serait intéressant de la muer vraiment en liste d’auteurs en utilisant des liens vers un annuaire afin de favoriser les contacts entre développeurs. Ces liens pourraient être les id ou emails d’auteurs d’un site SPIP pris pour référence... ou d’un autre annuaire ? DTD

Pour ne pas perdre les informations de type crédits, licence et copyright, je proposerais de créer ces balises explicitement et de rendre obligatoire la balise <licence> (Règle RLIC-1, erreur).

Création de la balise crédit mais licence reste non obligatoire dans la DTD

Balise <lien>
A priori il est possible d’en mettre plusieurs mais je ne me rappelle pas l’avoir déjà vu. Cette balise est utilisée pour le lien vers la documentation du paquet bien que cela ne soit pas explicite ni dans la spécification du plugin.xml ni dans son nom !

Alors on pourrait limiter à une unité cette balise et la considérer explicitement comme le lien vers la documentation ? La renommer aurait été un plus...

En outre, il me semble qu’on avait recommandé l’écriture d’une url stricte sans raccourci pour le contenu de cette balise. Je propose de l’édicter en règle (RLIEN-1, erreur). DTD

Balise <necessite>
Cette balise appliquée à SPIP est indispensable aujourd’hui pour choisir le bon paquet. A ce titre, je propose donc les règles suivantes :

  • Règle RNEC-1, erreur : balise obligatoire.
  • Règle RNEC-2, erreur : les versions SPIP doivent appartenir à une liste prédéfinie (définie où ?).
  • Règle RNEC-3, avertissement : écrire et mettre à jour correctement cette balise pour qu’elle décrive exactement la compatibilité SPIP (min et max, rarement utilisé actuellement).
    Voir la DTD

Balise <description>
Aucune règle ne peut être définie mais une recommandation est de traduire le plus possible cette balise comme la balise <slogan> afin de diffuser le plugin le plus largement possible. Maintenant il est vrai que les <multi> ne sont pas soumis à Trad-Lang même pour les plugins sous Salvatore ce qui est un handicap certain. DTD

Les balises non utilisées par SVP

Toutes les autres balises ne sont utilisées que par les mécanismes du plugin lui-même et ne contribuent pas à sa diffusion. Elles sont donc vérifiées formellement par le code du plugin. Là aussi une seule recommandation : utiliser des items de langues pour les titres des boutons et onglets afin de favoriser la traduction du plugin.
DTD