Projet:Infobox/Lua/Documentation

Ce sous-projet de documentation a pour objectif d'améliorer la documentation des infobox développées en Lua. Cette première phase du projet se limite à la description des paramètres de chaque Infobox.

La section Autres phases du projet décrit sommairement les autres phases envisagées. Elles peuvent être entreprises indépendamment et en parallèle de ce sous-projet.

Pourquoi ?Modifier

À plusieurs reprises le manque de documentation des infobox développées en Lua a été critiqué[1],[2],[3],[4],[5], mais aucun progrès sensible n'a été enregistré pour le moment.

Ce problème récurrent provient en grande partie de la décorrélation entre les infobox et les modules. Chaque fonction Lua étant potentiellement utilisable dans plus de 70 infobox, il y a une difficulté à diffuser la documentation dans toutes les infobox utilisatrices de la fonction.

Quel principe ?Modifier

La structure de la documentation doit correspondre à la structure du code — c’est-à-dire, être répartie dans les modules spécialisés — mais néanmoins être utilisable par les contributeurs de toutes les infobox.

  1. dans un premier temps, rédiger pour chaque fonction Lua une documentation utilisateur structurée pour être réutilisée facilement. Cette documentation se trouve au niveau du module Lua, comme dans l'exemple de la fonction website(localparam).
  2. dans un second temps, réutiliser dans les pages de documentation des modèles, comme pour le paramètre site web ou la propriété wikidata P856 (« site officiel ») dans l'exemple simple Infobox Observatoire ou l'exemple plus complet Infobox Organisation2.

Mais surtout maintenir cette réutilisation même lorsqu'une fonction est modifiée alors qu'elle est utilisée par plusieurs infobox. La simple copie n'est donc pas une solution viable à long terme.

Comment faire ?Modifier

Techniquement la réutilisation se fait en :

  1. définissant les sections à réutiliser dans la documentation des fonctions à l'aide des balises <section begin=Nom du fragment/> et <section end=Nom du fragment/>,
  2. puis à insérer les passages dans la documentation des infobox avec le modèle {{Extrait}}.

Le découpage de la documentation des paramètres d'une fonction est un compromis entre la recherche de simplicité et l'insertion dans une documentation existante très disparate d'une infobox à l'autre.

Le principe de nommage des fragments est le suivant :
<nom du paramètre>_<colonne de la table de description des paramètres>

  • Le nom du paramètre, correspond au nom du paramètre lorsqu'il n'est constitué que d'un seul mot, par contre lorsqu'il y a plusieurs mots les espaces sont supprimées et remplacées par une majuscule au mot suivant. Exemple : logo, légendeLogo
  • L'extrait, en général une colonne de la table de description des paramètres
Code de l'extrait Utilisation
libellé Libellé de l'information dans l'infobox. Il n'est pas utilisé pour les images qui s'affichent sur toute la largeur de l'infobox. Le libellé correspond généralement au nom du paramètre avec un majuscule au début avec éventuellement une forme plurielle, lorsqu'il y a plusieurs noms de paramètre c'est généralement le premier, mais il existe de nombreuses exceptions à ces principes généraux.
paramètre Nom du paramètre pour l'infobox. Il peut y avoir éventuellement plusieurs paramètres.
wikidata Nom de la propriété wikidata, ou éventuellement des propriétés. Pour certaines informations, les propriétés peuvent être enrichies de qualificatifs.
description Description de la fonction du paramètre. Lorsqu'il y a une ou des propriétés wikidata, cette description doit être proche de la description des propriétés. Mais il est néanmoins nécessaire de préciser le fonctionnement lorsqu'il y a plusieurs valeurs.
exemples Cet extrait est affiché dans la même colonne que la description. En fonction du paramètre, les exemples peuvent être génériques ou au contraire doivent être spécifique à l'infobox.

Qui peut participer ?Modifier

L'objectif de ce projet est que chacun puisse travailler en fonction de ces besoins et de ces connaissances. Il n'est donc pas nécessaire d'être développeur Lua pour y participer.

Où en est la mise en œuvre ?Modifier

Le tableau suivant permet de visualiser l'avancement de ce projet.

Ce tableau n'est pas exhaustif, mais présente le principe de fonctionnement de la visualisation de l'avance de ce projet :

  • en colonnes les fonctions réutilisables par plusieurs infobox. Cette liste incomplète est à enrichir avec les fonctions des modules déjà listés ou par d'autres modules.
  • en lignes les infobox utilisatrices des fonctions. La colonne Transclusions reste à compléter avec le nombre de transclusions de l'infobox dans des articles. L'idéal étant que ces valeurs soient mises à jour dynamiquement, si c'est possible. Cette première liste est basée sur les infobox utilisant des fonctions du module Infobox/Fonctions (obtenus par une recherche du type : \"Module:Infobox/Fonctions\" "website(" -intitle:Document), complétée par la catégorie Modèle infobox Lua utilisant Wikidata. Certaines infobox ne figurent pas dans le tableau, car elles obéissent à une logique différente pour leur documentation (Cycling race/*, Databox, ), sont obsolètes (Infobox Descriptif course cycliste, ) ou trop spécifiques (Infobox Région électorale pour l'assemblée nationale du pays de Galles, ). Les infobox avec des liens rouges correspondent à des infobox existantes mais sans pages de documentation.
  • dans chaque cellule l'état d'avancement qui peut prendre les valeurs suivantes :
    •  À faire lorsqu'on ignore si la fonction est utilisée par l'infobox
    • ✔️ lorsque la fonction est utilisée et la documentation de la fonction est complètement transcluse dans la page de documentation de l'infobox.
    • Vide lorsque la fonction n'est pas utilisée par l'infobox
    •  « action restant à réaliser » lorsque la transclusion n'a pas été réalisée pour tous les paramètres, mais surtout lorsqu'il y a l'ajout ou la suppression d'un paramètre dans une fonction. C'est le point le plus délicat, un développeur qui modifie les paramètres d'une fonction doit notifier dans ce tableau la modification à propager dans les infobox. Même si c'est plus simple à réaliser qu'actuellement ce n'est pas « naturel ».

Conseils aux documentaristes de fonctionsModifier

Même si vous ignorez le fonctionnement fin de la fonction que vous décrivez, la mise en place de la liste des paramètres permet d'initier la réutilisation. Certaines infobox peuvent avoir des descriptions assez précises des paramètres qui peuvent être réutilisées au niveau de la fonction.

Colonne Conseils
Libellé Le ou les libellés qui apparaissent à la gauche de la valeur. Afin de simplifier la lecture, chaque libellé est sur une ligne. Le libellé n'existe pas pour les images et reste donc vide dans le tableau des paramètres. Lorsque le libellé est modifiable par un paramètre c'est indiqué par l'utilisation du modèle {{Libellé modifiable}} qui permet d'afficher l'icône Font Awesome 5 solid cog.svg et ce paramètre est décrit à la ligne suivante du tableau.
Paramètre Nom du paramètre pour l'infobox. Il peut y avoir éventuellement plusieurs paramètres. Le nom du paramètre est mis en forme avec la syntaxe :<code></code>. Le nom de paramètre à utiliser de préférence est affiché en gras.
Wikidata La ou les propriétés wikidata utilisables et leurs qualificatifs utilisée pour l'affichage de l'infobox. Chaque paramètre ou qualificatif est listé en utilisant le modèle {{WD P}}. Les qualificatifs temporels permettent de préciser la validité temporelle des informations, leur utilisation étant fréquente, il est préférable :
  • d'utiliser le modèle {{Qualificatifs temporels}} qui affiche l'icône Font Awesome 5 solid calendar-alt.svg
  • de renvoyer vers un paragraphe standard ayant pour titre « Qualificatifs temporels ». Son contenu est :

« Certaines valeurs ne sont valables qu'à une certaine date ou pour une période donnée. Ces informations sont ajoutées aux propriétés de l'élément en tant que qualificateurs. Ces informations :
* apparaîtrons, éventuellement, entre parenthèse après la valeur de la propriété,
* permettront de trier chronologiquement les valeurs affichées,
* de n'afficher que la valeur actuelle d'une propriété.

Les qualificatifs temporels sont : P585 (« date »), P580 (« date de début ») et P582 (« date de fin »). »

Description La description commence par un paragraphe général du paramètre, qui s'il y a une propriété wikidata s'appuie sur sa description. Il est souvent utile de faire une distinction entre l'utilisation d'un paramètre et l'utilisation des propriétés wikidata.

Il peut être utile de fournir :

  • soit la liste des valeurs possibles,
  • des sources utilisables pour trouver la valeur
Exemples

Conseils aux documentaristes d'infoboxModifier

Lorsque le paramètre est déjà décrit de manière classique dans la documentation, examinez attentivement si l'existant n'est pas meilleur, au moins partiellement, que la documentation que vous comptez transclure. Dans ce cas testez si le comportement est conforme à la description existante. Si vous avez la confirmation, vous pouvez « remonter » cette amélioration au niveau de la documentation de la fonction pour que toutes les infobox en profitent.

Lorsqu'une fonction a déjà été réutilisée dans une autre infobox, il suffit de recopier l'ensemble des paramètres pour l'injecter dans la nouvelle infobox, en modifiant éventuellement les exemples.

Tableau de suivi de l'avancementModifier

Infobox de personnalitésModifier

Module Infobox/Fonctions/Personne
Documentation de l'infobox Transclusions title() mainimage() officialposition() nobilitytitle() birth() death() placeofburial() floruit() othernames() nationality() education() occupation() contacts() movement() patron() influencedby() influenced() family() awards() archivesat() website() works() signature()
Infobox Artiste 24 756 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️  À faire
Infobox Catch (personnalité) 1 332  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Auteur de livre-jeu 41  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Biographie2 323 059 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️  À faire  À faire  À faire  À faire  ébauche à titre de démonstration  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire ✔️  À faire
Infobox Cycliste 14 889  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Philosophe 654  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire

Autres infoboxModifier

Module Infobox/Fonctions Infobox/Fonctions/Géolocalisation Infobox/Fonctions/Bâtiment Matériau
Documentation de l'infobox Transclusions title() mainimage() interior() logo() blason() flag() sign() icon() bathymetricmap() prononciation() website() coordinates() mainimage() website() coordinates() formatFromItem() À compléter  À compléter
Infobox Observatoire 394 ✔️ ✔️ ✔️  Ajouter nom site ✔️  À faire
Infobox Hôtel 777 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️  À faire
Infobox Cimetière 1 708 ✔️ ✔️  À faire  À faire
Infobox Grotte 730 ✔️ ✔️ ✔️ ✔️  À faire
Infobox Organisation2 14 736 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️  À faire
Infobox Art 9 311 ✔️ ✔️  Voir la page de discussion.  À faire
Infobox Musée 5 777  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Centre commercial 434  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Technopôle  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Modèle:Infobox Abbaye/Lua 0  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Périodique  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Jeu de données  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Plage  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Télescope  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Temple hindouiste  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Gratte-ciel  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Université  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Temple bouddhiste  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Point de vue panoramique  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Catch (spectacle)  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Catch (spectacles)  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Commanderie  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Monument  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Sentier 557  À faire  À faire  À faire  À faire  À faire  À faire ✔️  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Aire protégée  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Combiné nordique 2  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Appareil informatique  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Algorithme  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Format de données  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Localité  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Ouvrage  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Cheminée  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Stade  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Chute d'eau  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Phare  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Plan d'eau 416  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire ✔️  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Rivière  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Ouvrage d'art  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Barrage  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Bilan sportif  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Concert du nouvel an 84  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Discipline 203  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Équipe cycliste  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Espace vert2  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Feu de forêt  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Fromage  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Indice boursier  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Centrale  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Centrale nucléaire 287  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Lieu de fiction  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Matériaux 13  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Métier 760  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Mine  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Nœud  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Nuage  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Objet 396  À faire  À faire  À faire  À faire  À faire  À faire  À faire ✔️  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Parlement  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Poème  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Port  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Relief terrestre  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Saison d'équipe cycliste  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Style architectural  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Vaccin  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Variété de houblon  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Vêtement  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire
Infobox Volcan2  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire  À faire

Autres phases du projetModifier

RéférencesModifier