Utilisateur:Hexasoft/Test taxobox/Documentation/Modifications

Description de quelques modifications courantes sur les taxobox.

Modifier une catégorie ou un texte de la taxobox

La plupart des données sont dans le module Module:Taxobox données. Le plus simple est de chercher le texte à modifier dans cette page puis de modifier la partie concernée.

Si l'élément recherché n'est pas dans ce module il est probablement généré par les fonctions de traitement des lignes des taxobox. Celles-ci se trouvent dans Module:Taxobox fonctions. Suivre le même principe.

Note : pensez à chercher toutes les occurrences du texte à modifier. Il est en effet possible qu'un même texte se trouve à plusieurs endroits (pour des choses différentes), ceci afin d'être certain de bien modifier le bon.

Modifier le comportement par défaut de la taxobox

Dans les options des taxobox on peut choisir le comportement à adopter pour divers entités : titre, sous-titre, catégories, catégories d'erreur, messages d'erreur.
Il existe deux moyens pour « forcer » l'un de ces éléments à une valeur donnée :

fixer le ou les options au niveau du modèle (user:Hexasoft/Taxobox2). En effet tous les paramètres nommés de la taxobox sont d'abord lu en provenance du modèle, et un paramètre non présent à ce niveau est ensuite testé en provenance de l'appel au modèle (dans l'article). Ceci permet de « forcer » la valeur d'un paramètre quelque soit le choix fait par l'utilisateur ou les valeurs par défaut.
dans Module:Taxobox2, au début de la fonction taxobox(), celle-ci lit les valeurs des différents paramètres (appels à la fonction lit_parametre()). Le dernier paramètre de cette fonction est la valeur par défaut ("auto" la plupart du temps), attribuée si le paramètre n'est pas fournit lors de l'appel. Il suffit donc de changer cette valeur par défaut par l'une des valeurs possibles (pour chaque paramètre ciblé) pour modifier le comportement par défaut.

Note : la première solution impose de façon fixe un choix, quelque soit la volonté de celui qui appelle le modèle. Son utilisation semble pertinente si l'on fait le choix de forcer un comportement. Par exemple si on décide de ne jamais inclure les sous-titres, de façon à ce qu'on ne puisse pas les ajouter (mais qu'on ne veut pas supprimer le code correspondant, ce qui serait la solution la plus propre à long terme si l'option ne devait pas être utilisé dans le futur).
La seconde solution est plus adaptée pour laisser une certaine liberté aux rédacteurs tout en modifiant le choix par défaut fait actuellement.

Note bis : tous les modificateurs de comportement sont traités dans la fonction taxobox(), à la fin, avant de retourner le résultat. S'il faut modifier les critères de décision s'appliquant aux différents modes possibles ("auto" typiquement) c'est là qu'il faut changer le code.
Exemple sans signification particulière : décider que le mode "auto" pour le sous-titre est "appliquer le sous-titre quand on est dans l'espace encyclopédique pour tous les règne sauf le règne « virus » pour lesquel on désactive les sous-titres". Il faudrait alors modifier les tests de la partie « sous-titre » afin de prendre en compte ce cas de figure.

Modifier une charte (règne)

Tout ce qui définit une charte est présent dans Module:Taxobox données. Cherchez la table p.regnes, repérez la ligne indexée par le nom de la charte à modifier.

S'il s'agit de modifier son nom, changez-le dans l'index et dans le premier champs de la ligne. S'il s'agit de modifier son « comportement » il faut éditer les autres champs. Voici la syntaxe de ces lignes :

    ["animal"] = {
        ["nom"] = "animal", ["convention"] = "CINZ",
        ["classe"] = "animal", ["règne auto"] = { { "règne", "Animalia"} },
        ["cat auteur"] = "[[:Catégorie:Auteur incomplet ou manquant|— auteur incomplet —]], {{Date à préciser}} [[Catégorie:Auteur manquant-animal]]"
    },

Le premier ["animal"] est l'index. ["nom"] = "animal" doit contenir le même nom.
Le champs ["convention"] = doit contenir "CINZ" si la charte suit la convention zoologique, "CIN" sinon.
Le champs ["classe"]] = contient le nom de la classe CSS qui correspond à cette charte (voir MediaWiki:Common.css).
Le champs ["règne auto"] = doit contenir une liste ({ … }). Chaque élément de cette liste doit être une liste de paires de textes ({ "texte1", "texte2" }). Ces paires définissent les premières lignes de classification à ajouter en début de taxobox. Ces paires doivent comporter un rang puis le nom du rang (comme passé en paramètre à une ligne de classification). S'il ne doit pas y avoir de premières lignes mettre nil à la place de l'ensemble (["règne auto"] = nil,)
Le champs ["cat auteur"] = contient un texte qui est inséré dans taxon si le champs « auteur » est vide. Celui-ci peut contenir des catégories. Note : il faudrait que j'éclate cette information en deux parties (texte + catégories) afin de pouvoir traiter les catégories de manière indépendante comme le sont les autres.

Note : il y a une exception : dans taxon si "charte=virus" et "rang=espèce" on affiche "Espèce" et non "Nom binomial". Ceci est fait par un test direct dans Module:Taxobox fonctions, fonction p.cmd_taxon(). La raison en est que c'est la seule exception et je n'ai donc pas créé de champs de données pour ça. Si votre modification implique le nom de la charte "virus" ou si vous voulez changer ce comportement (ou en ajouter un) c'est là qu'il faut aller.

Attention : ce sont des champs internes, le module considère qu'ils sont écrits correctement. En particulier doivent être en minuscule : l'index des entrées ; le champs "nom" ; la partie "rang" de "règne auto". La partie "convention" doit-être exactement "CIN" ou "CINZ". La "classe" doit exactement correspondre au nom définit dans le CSS de wikipédia.

Ajouter une charte

Le plus simple est de copier-coller une ligne de charte existante et proche de ce qu'on veut puis de renommer le nom de la charte et appliquer les modifications nécessaires (voir section précédente).

Note : pensez à respecter les "," qui séparent les différentes entrées, en particulier si vous ajoutez une charte à la fin (le dernier n'a pas de "," qu'il faudra donc ajouter entre l'ancien dernier et le nouveau dernier).

Ajouter/modifier un rang

Tous les rangs sont définis dans Module:Taxobox données. Cherchez la table p.rangs. Le plus simple pour créer un nouveau rang est de copier-coller un rang existant.

Le format d'un rang est :

  ["famille"] = {
    ["nom"] = "famille", ["wikif"] = "[[Famille (biologie)|Famille]]",
    ["wikif long"] = "[[Famille (biologie)|Famille]]",
    ["infgenre"] = false, ["ordre"] = 23
  },

Les champs :

["famille"] = { : l'index. Mettre le nom (en minuscule) du rang tel qu'il sera donné en paramètre lors de son utilisation
["nom"] : doit contenir la même valeur que l'index
["wikif"] : la forme wikifiée courte pour affichage (dans les lignes de classification)
["wikif long"] : la forme wikifiée longue pour affichage (dans taxon)
["infgenre"] : indique si le taxon est considéré comme inférieur au genre. Mettre true si c'est le cas, false sinon.
["ordre"] : non utilisé à l'heure actuelle. Un entier unique pour chaque rang, théoriquement classé dans l'ordre croissant des rangs.

Penser à vérifier les "," qui séparent les champs et les entrées entre elles.

Ajouter/modifier une classification

Chercher dans Module:Taxobox données la table p.classifications. Sont format est :

["sibley"] = { ["nom"] = "sibley", ["texte"] = "[[Classification de Sibley-Ahlquist]]" },

On retrouve le nom de la classification (telle qu'utilisée en paramètre, en minuscule) en index, ainsi qu'à l'identique dans le champs "nom". Ensuite la forme wikifiée telle qu'affichée.

Il suffit de modifier l'index (sans oublier le nom) et/ou la partie wikifiée. Un ajout se fait classiquement par copier-coller puis modification.

Note : à l'heure actuelle la taxobox modulaire ne gère pas l'ajout dans les rangs de classifications d'alternatives selon les classifications (comportement de {{Taxobox conflit}}). Un exemple existe dans le code précédent mais n'est pas encore reporté dans ces taxobox.
Lorsque ce sera fait il y aura également − comme pour taxobox conflit une liste des références permettant de sélectionner les diverses classifications, les données seront dans Module:Taxobox données. Me dire s'il est « urgent » de l'implémenter.

Modifier UICN

À moins que l'UICN ajoute de nouveaux critères il y a peu de chance d'avoir à modifier ça. Toutefois tout est dans la table p.uicn, table contenant simplement l'index du critère (forme courte) répétée dans le champs "nom", suivi de la forme longue du critère.

Modification du traitement des italiques des noms scientifiques

Il y a plusieurs fonctions traitant de divers aspects des noms scientifiques pour leur mise en forme.
Coté données hhercher dans Module:Taxobox données la table p.exclusion. Celle-ci contient une liste dont chaque élément est une liste contenant deux textes.

Le premier est la partie à rechercher dans le nom scientifique.
Le second est par quoi remplacer cette partie dans le nom scientifique.

L'idée est que la partie de remplacement contient l'annulation de l'italique (présence de deux apostrophes droites avant et après). Note : ce traitement n'est appliqué qu'à des noms scientifique qui sont en italiques, il n'y a donc pas de risque de passage en italique non voulu.
Notez plusieurs choses :

il s'agit de regex (dans la partie gauche). Certains caractères ont un sens particulier. C'est le cas du point (".") qui est donc protégé entre crochets.
pour éviter qu'on détecte un sous-texte d'un autre texte ("var." compris dans "convar.") certains éléments sont précédés d'une espace (" var.") pour lever l'ambiguité. Il faut alors impérativement que l'espace se retrouve également dans la partie droite.

Pour le reste tout est traité dans les fonctions de gestion des italiques :

p.italiques(regne, rang) : retourne vrai si le règne+rang doit être en italique
p.italiques_ns(nom, cible, regne, rang, lien) : retourne nom avec la mise en forme nécessaire (si besoin) en fonction du règne et du rang. lien indique qu'il faut retourner un wikilien. cible indique la cible du wikilien (ou nil).
p.italique_cultivar(nom) : retourne nom mis en italiques selon les conventions des cultivars
p.italiques_titre(titre, ns, rang) : retourne l'action à faire sur le titre de l'article (DISPLAYTITLE) à partir du titre de l'article (titre), du nom scientifique du taxon concerné (ns) et du rang de celui-ci (rang)

En général on n'appelle que les fonctions p.italiques_titre(titre, ns, rang) (pour gérer la mise en italique éventuelle du titre) et p.italiques_ns(nom, cible, regne, rang, lien) (pour gérer la mise en italique éventuelle d'un nom scientifique).
Voir leur code pour modifier leur comportement.

Modifier/ajouter une ligne de taxobox

Une ligne de taxobox est définie (au niveau des données) à deux endroits :

Module:Taxobox données, table p.p.df_<nom de la ligne> pour la syntaxe de la ligne
Module:Taxobox fonctions, table p.syntaxe pour le regroupement des mot-clés, syntaxe et fonctions.

Une ligne de taxobox est donc définie par trois éléments, et est référencé (index) par le mot-clé :

la criticité d'une erreur sur cette ligne (entier). 0 indique que la ligne ne produit pas d'erreur taxobox en cas de problème. 1 indique que la ligne produit une erreur non fatale (l'erreur est indiquée mais le traitement se poursuit). 2 indique qu'une erreur est fatale (la taxobox n'est pas affichée, une boîte d'erreur est affichée à la place).
la table qui définit la syntaxe des paramètres de la ligne
la fonction qui va traiter les paramètres trouvés pour générer la sortie wiki correspondante

Ces trois éléments sont regroupés dans la table p.syntaxe.

Si on veut modifier les paramètres d'une ligne il suffit de changer la ligne de syntaxe associée (voir plus bas le détail des syntaxes).
Si cette modification ajoute, enlève ou modifie un ou plusieurs paramètres il faut répercuter la prise en compte de ces changements dans la fonction de traitement (dans Module:Taxobox fonctions, à la fin, les fonctions ayant toutes la forme p.cmd_<mot-cle>().

Si on veut ajouter une nouvelle ligne il faut :

créer la syntaxe associée en ajoutant une ligne de syntaxe dans Module:Taxobox données
ajouter un élément à la table p.syntaxe (Module:Taxobox fonctions) avec pour index le mot-clé choisi pour la ligne, et contenant la criticité (entier valant 0, 1 ou 2), le nom de la table de syntaxe, le nom de la fonction de traitement associée
créer une fonction p.cmd_<mot-cle>(params) dans Module:Taxobox fonctions, de préférence au même endroit que les autres fonctions de traitement de ligne.

Cette dernière fonction doit respecter les contraintes / fonctionnalités suivantes :

elle reçoit une table contenant les paramètres présents sur la ligne de commande (voir plus bas le fonctionnement)
elle doit retourner du wikitexte correspondant à la ligne à produire
en cas de problème elle doit retourner un texte quand même, même vide ("")
pour insérer une erreur il existe deux fonctions dédiées accessibles : p.erreur_normale(message, type) et p.erreur_fatale(message, type). Ces deux fonctions enregistrent le message indiqué (descriptif de l'erreur), "type" indiquant la catégorie de l'erreur (interne, syntaxe, structure). La seconde fonction (comme son nom l'indique) génère une erreur fatale → la taxobox ne sera pas générée et l'erreur en question sera affichée comme indication.
pour insérer une catégorie (pas une catégorie d'erreur, gérée ci-dessus, une catégorie d'information) il faut utiliser la fonction p.ajoute_categorie(cat) et ne pas l'insérer directement dans le wikitexte retourné (la gestion des catégories est effectuée à la fin des traitements, selon les options choisies).
si la fonction ouvre ou ferme une table il faut obligatoirement incrémenter ou décrémenter la valeur de donnees.defauts.etat.tbl (utilisé pour valider à la fin de la taxobox que tout est bien fermé). Ce champs est accessible pour les fonctions de ce module.
il existe plusieurs fonctions utilitaires disponibles. Se référer à Utilisateur:Hexasoft/Test taxobox/Documentation/Fonctions pour la liste des fonctions. Les plus courantes sont :
- p.tb_ligne_mixte(rang, nom) : insert une ligne de table de type "champs / valeur" (il faut être dans une table)
- p.tb_bloc(texte) : insert au sous-titre de taxobox
- p.tb_texte : insert une zone "normale" de taxobox
- p.italiques_ns(nom, cible, regne, rang, lien) : retourne le "nom" pour le "regne" et le "rang" indiqué avec mise en italique si besoin. "lien" indique qu'il faut retourner un wikilien. Dans ce dernier cas si "cible" est différent de nil il est utilisé comme cible du lien.
- p.insert_image(image, legende, complet) : insert l'image indiquée. La légende sert ici uniquement pour mettre un champs de description correct. "complet" indique que l'image est déjà sous la forme "Fichier:XXX", sinon suppose que c'est "XXX"
- p.lien_en_minuscule(lien) : retourne "lien" avec la première lettre en minuscule (pour insérer un lien dans une phrase)

Notez qu'il peut être nécessaire de modifier le code principal (fonction taxobox(frame) dans Module:Taxobox2 dans la boucle de traitement des lignes de commandes. Cette boucle parcours chaque ligne, analyse les paramètres, appelle la fonction de traitement et ajoute le résultat à la taxobox en cours (en gérant les erreurs). En plus de cette action cette boucle gère certaines actions nécessaires et que les fonctions de traitement des commandes ne peuvent effectuer. Par exemple : fermer la table en cours si l'entrée précédente était un rang et que l'entrée courante n'est pas un rang, ou au contraire ouvrir une table si l'entrée courante est un rang mais qu'il n'y a pas de table ouverte (ce qui est par ailleurs un cas de structure de taxobox invalide, qui est signalé par une erreur non critique).

La syntaxe

Chaque ligne possède sa syntaxe qui définit les paramètres attendus. Ces lignes suivent une convention un peu compliquée mais cohérente. Les paramètres possibles sont divisés en trois types :

les paramètres nommés : paramètre du type "champs=valeur"
les paramètres "drapeaux" : la seule présence du paramètre suffit à valider sa présence
les paramètres non nommés : ils sont reçus dans l'ordre (comme les {{{1}}}, {{{2}}}… des modèles)

La ligne de syntaxe est une table contenant une table pour chacun de ces types (un ou plusieurs types peuvent être absents, indiquant l'absence de paramètre de cette catégorie).
Dans l'ordre le nom des ces trois parties est : values, flags, noname. Ainsi une ligne de syntaxe contiendra : { ["noname"] = … , ["flags"] = … , ["values"] = … }

noname

Les plus simples. Il s'agit juste de fournir une liste de noms de champs dans lesquels seront rangés les valeurs des paramètres non nommés, dans l'ordre de leur apparition.
Par exemple la ligne "taxon" d'une taxobox accepte les paramètres non nommés "rang", "nom" et "auteur". Il faudra donc que la partie ["noname"] contienne { "rang", "nom", "auteur" }.

Le premier paramètre non nommé sera affecté au champs "nom" de la table résultat (la table params qui est passée à chaque fonction de traitement d'une ligne, accessible donc avec params.nom ou params["nom"], les deux formes sont identiques mais la seconde permet d'accéder à des champs contenant des espaces ou des caractères accentués). Le second sera affecté au champs "rang", etc.
Si l'on fournit moins de paramètres que possible les paramètres restants valent nil (absence de valeur). Si l'on fournit plus de paramètres que possible cela génère une erreur.

flags

Il s'agit ici de fournir le nom du paramètre "drapeau" et d'indiquer le nom du champs correpsondant dans la table résultat. Exemple : ["flags"] = { { { "séparateur", "separateur" }, "separateur" } }
La partie flags contient une liste. Chaque élément de cette liste définit un « drapeau ». Un drapeau commence par une liste de texte (qui peut n'avoir qu'un élément) : si le module rencontre l'un de ces textes il est considéré comme étant ce drapeau (la liste permet d'avoir plusieurs alternatives au même drapeau, ici la version avec et sans accent). L'élément suivant un un texte correspondant au nom du champs où mettre le résultat.
Donc dans cet exemple il n'y a qu'un seul flag, et si on rencontre "separateur" ou "séparateur" le champs résultat "separateur" vaudra true.
On peut mieux se rendre compte de la syntaxe si on respecte une indentation correcte :

  ["flags"] = { -- contenu de 'flags'
    {  -- premier drapeau
      { "toto", "titi" },  -- liste des textes qui correspondent à ce flag
      "toto"     -- nom du champs résultat
    },
    {  -- second drapeau
      { "foo" },  -- pas d'alternative, juste "foo"
      "foo"    -- nom du champs
    }
  }

values

Les values suivent exactement la même syntaxe que les flags. La seule différence est que lorsque le module reconnaît un values il va lire le paramètre suivant et donne sa valeur au champs résultat indiqué plutôt que true. Note : l'absence de valeur est une erreur.

Exemple concret et remarques

La syntaxe de début est la suivante : { ["noname"] = { "image", "legende" }, ["flags"] = { { {"phylo" }, "phylo" } }, ["values"] = { { {"classification", "classif" }, "classification" } } }
Ceci signifie que l'on attend :

un drapeau éventuel appelé "phylo". S'il est présent le champs "phylo" vaudra true dans le résultat
un paramètre nommé qui peut être "classification" ou "classif". S'il est présent la valeur qui le suit sera rangée dans le champs "classification" dans le résultat
deux paramètres non nommés qui (s'ils sont présents) seront rangés dans les champs "image" et "legende" dans le résultat

Si on appelle la fonction d'analyse de cette ligne avec les données suivantes :
|début | image.jpg | classification|reptiledb
la table résultat − qui sera passée à la fonction de traitement de cette ligne, ici cmd_debut() − contiendra les champs suivant :

image valant "image.jpg"
legende valant nil (ne valant rien, donc)
classification valant "reptiledb"
phylo valant nil (ou false)

Remarques :

tout paramètre qui n'est pas reconnu comme un flag ou un value sera traité comme un paramètre noname
la fonction d'analyse des lignes génère une erreur s'il y a trop de paramètres non nommés par rapport à la syntaxe décrite
la fonction d'analyse ne définit pas de paramètre obligatoire. C'est aux fonctions de traitement des lignes (qui reçoivent le résultat de l'analyse des lignes) de faire ces vérifications)