Extension:XGlossary/Doc/fr

=Aide de l’extension xGlossary (v0.1.3)= Cette page documente l’ensemble de l’extension xGlossary (licence GPL 3).
 * Note : Cette page ne documente que les fonctions d’extension, et pas les templates additionnels que vous pourriez définir (comme ceux que nous définirons peut-être pour blenderwiki), pour faciliter/améliorer ces fonctionnalités de base. Cependant, vous trouverez à la fin de cette page quelques suggestions…

Cette extension définit les fonctions suivantes :
 * – La fonction glossaire principale.
 * – La fonction de définition d’entrée.
 * – La fonction de lien au glossaire.
 * – La fonction affichant cette page d’aide !
 * – Une fonction effectuant quelques tests basiques (uniquement utile pour le développement/débogage).
 * Il y a également des paramètres globaux qui contrôlent certains aspects de son comportement général…

À propos des paramètres des fonctions-wiki :
 * Certains sont s, d’autres sont  s ; en général, ces paramètres ne sont pas “wiki-parsés” par l’extension xGlossary, mais il y a quelques exceptions importantes, notées comme   ou  . Des paramètres obligatoires absents ou vides produiront des messages d’erreur dans le xhtml résultant.
 * Certains paramètres sont en fait une collection de valeurs. Dans ce cas, ils utilisent la syntaxe commune suivante : un ou plusieurs ensembles d’options entourés de parenthèses, chaque ensemble constitué d’une ou plusieurs paires “clé=valeur” séparées par des points-virgule “;”. Cela implique que si vous voulez utiliser l’un des caractères “(”, “)” ou “;” au sein d’une valeur, vous devrez l’échapper avec un backslash “\”.
 * Tous les paramètres non-“wiki-parsés” sont bien évidemment échappés – ni xhtml ni code wiki ne sont permis, ce sont des bouts de texte brut !

Introduction
Comme l’avez sans doute deviné, cette extension a été conçue et codée pour implémenter un simple “glossaire” pour les sites utilisant MediaWiki comme moteur de documentation de projet. Voici les principes généraux :
 * Vous créez une ou plusieurs pages en tant que glossaires, en y plaçant l’appel de fonction . Chaque glossaire contient des “entrées”, triées et regroupées au sein de “groupes”.
 * Ensuite, vous créez plusieurs sous-pages (c-à-d des pages dont le nom débute exactement comme celui de leur page de glossaire), qui contiennent les entrées (en tant qu’appels ). Par défaut, chaque sous-page définit un groupe. Cependant, les entrées contenues dans une sous-page donnée ne se retrouveront pas forcément dans le groupe définit par cette page (voyez ci-dessous pour plus de détails).
 * Chaque entrée est constituée de divers paramètres. Encore une fois, voyez plus loin pour les détails.
 * Ensuite, n’importe où dans le wiki, vous pouvez utiliser  pour créer des liens vers une entrée donnée (c’est à vous de lui fournir un chemin-wiki valide – “embarquer” cette fonction dans un template-wiki peut se révéler fort pratique !). Ces liens peuvent contenir la partie “shortdesc” de l’entrée, pour être affichée par ex. dans une “info-bulle”…

Important : Actuellement, les pages mises en cache ne sont pas invalidées, quand vous modifiez par exemple une entrée dans une sous-page, celle du glossaire ne sera pas immédiatement mise à jour en conséquence, à moins que vous ne la purgiez explicitement (c’est également valable pour les textes “shortdesc” des liens de glossaire).

Les pages de glossaire
Vous créez une page de glossaire en y insérant un appel à la fonction. Ce “tag” sera remplacé par le contenu (les entrées) de toutes ses sous-pages, regroupées et triées.

Par défaut, chaque sous-page définit automatiquement un groupe, mais cela peut être modifié par le paramètre optionnel “groups”, voyez ci-dessous. Il est important de comprendre que la sous-page dans laquelle est définie une entrée n’a aucune importance dans la résultat produit par  ! Vous pouvez donc définir vos entrées où vous voulez – cependant, vous devriez évidemment les garder bien arrangées, pour le bénéfice des futurs éditeurs !

Mis à part les paramètres globaux, décrits ci-dessous, cette fonction prend trois paramètres optionnels :
 * (optionnel)
 * Si non-vide, il écrase les groupes découverts d’après les sous-pages, voyez ci-dessous pour plus de détails.


 * (optionnel)
 * Le code ISO de la langue que vous souhaitez utiliser (cela peut affecter les messages, ou même l’ensemble du résultat, voyez les paramètres globaux). S’il est vide, la valeur pour l’utilisateur courant est utilisée.


 * (optionnel)
 * S’il faut afficher les groupes vides (“yes”) ou pas (“no”). Notez que cela écrase également un paramètre global.

Il y a une chose importante à savoir à propos de cette fonction : actuellement, elle se fiche de regrouper/trier de “vraies” entrées, ou d’autres éléments ! Elle “parse” simplement le xhtml résultant des sous-pages, pour extraire et ordonner tout élément xhtml contenant un attribut nommé “ ”. Donc n’importe quoi contenant un tel attribut devrait être (sera) affiché et trié par cette fonction – et rien d’autre (c-à-d que tout ce qui se trouve en-dehors de ces éléments est ignoré/inutilisé).

Les groupes de glossaire
Comme annoncé ci-dessus, les groupes d’un glossaire regroupent les entrées. Ils peuvent être automatiquement détectés d’après les noms des sous-pages, ou explicitement spécifiés dans un des paramètres de l’appel, en utilisant la syntaxe suivante :

Chaque groupe est entouré de parenthèses (comme “ ”), contenant les paramètres suivants :
 * (obligatoire)
 * Le nom du groupe (ce qui sera affiché).


 * (obligatoire)
 * La clé de référence du groupe (ce qui sera utilisé par les liens).


 * (optionnel)
 * La clé de tri du groupe (ce qui sera utilisé lors de l’ordonnancement des groupes). Si vide, la valeur de  sera utilisée.

Les groupes ont un nom (ce qui est affiché), une référence (leur id de lien), et une clé de tri (utilisée lors de leur ordonnancement dans le glossaire). Lorsqu’ils sont auto-générés, nom, référence et clé de tri sont tous créés à partir du nom de la sous-page (moins la “racine”, le nom de la page de glossaire).

Il y a une subtilité avec les groupes : vous pouvez avoir des sortes de “sous-groupes” – pas sous une forme “arborescente”, mais des sous-groupes “affinés”. Par ex., vous pouvez avoir un groupe général “m”, et un groupe plus spécifique “mesh”, qui se retrouvera juste après le groupe “m”, et regroupera toutes les entrées dont la clé de tri commence par “mesh”.

Comme pour les entrées, les clés de référence et de tri devraient uniquement contenir des caractères alpha-numériques en minuscule (cela facilite les manipulations d’url).

Il y a deux clés de tri spéciales et prédéfinies : “__first” et “__last” – pour les anglophobes absolus, elles placent le groupe respectivement en tête et en queue de liste…

Pour finir, vous vous demandez peut-être “qu’est ce que vous faites des entrées ne trouvant place dans aucun groupe ?” Eh bien, il y a un groupe spécial, appelé par défaut “Misc” (ou “Divers” en français, avec pour id “__misc” et pour clé de tri “__last”), qui se chargera de toutes ces pauvres entrées orphelines !

Les entrées de glossaire
est la fonction “rendant” une entrée en xhtml. Elle devrait être un simple template-wiki, si ces templates pouvaient produire directement du xhtml ! Cependant, elle effectue également des opérations plus avancées, comme avec l’option des synonymes…

Elle est conçue pour être utilisée dans les sous-pages de glossaire. Elle attend un “template” avec les paramètres suivants :
 * (optionnel)
 * Le code iso de la langue à utiliser pour les templates/messages/… (langue de l’utilisateur courant, par défaut).


 * (obligatoire)
 * Une liste, séparée par des virgules, de codes de langue, par ex. “EN, FR”. Il peut évidemment n’y en avoir qu’une !


 * (obligatoire)
 * Le titre de l’entrée.


 * (obligatoire)
 * La référence utilisée dans le liens (devrait être une simple valeur alpha-numérique, sans fioritures comme les accents…).


 * (optionnel)
 * La clé de tri (utilisée par  pour trier les entrées !), vaut   si vide.


 * (optionnel)
 * Des (sous-)entrées “dictionnaire”, surtout utiles pour les auteurs/traducteurs, voyez ci-dessous.


 * (optionnel)
 * Définit des entrées “synonymes”, qui ne contiendront qu’un lien vers la “vraie” entrée. Particulièrement utiles pour les glossaires traduits, voyez ci-dessous.


 * (obligatoire[wiki])
 * Une courte description de cette entrée, “parsée” comme texte wiki. Elle sera incluse dans l’info bulle des liens de glossaire.


 * (optionnel[wiki])
 * Une description plus longue de cette entrée, si nécessaire (elle sera aussi “wiki-parsée” !).

Dict
“Dict” est un petit morceau d’information à propos d’un terme spécifique, similaire à une entrée de dictionnaire simplifiée. Il est conçu pour contenir des données surtout utiles pour les auteurs/traducteurs de la documentation (ça ne devrait pas être une définition, mais plutôt pointer un synonyme de l’entrée, ou une traduction dans une autre langue, …).

Chaque élément “dict” est entouré de parenthèses, suivant la même syntaxe que les définitions de groupes, et attend les paramètres suivants :
 * (obligatoire)
 * La(les) langue(s) du terme (liste séparée par des virgules).


 * (obligatoire)
 * Le terme définit ici…


 * (optionnel)
 * Est-il approximatif (donnera un “~” si “yes”, rien sinon) ?


 * (optionnel)
 * Est-il incertain (donnera un “(?)” si “yes”, rien sinon) ?


 * (optionnel)
 * Valeur d’“usage”, entre 1 (utilisation fortement découragée) et 5 (utilisation fortement encouragée). Produira autant d’étoiles que la valeur.


 * (optionnel[wiki])
 * Un court commentaire, qui sera “wiki-parsé” (attention aux “(”, “)” et “;”, qui doivent être échappés…).

Synonymes
Les “synonymes” sont des entrées générées automatiquement, qui se contentent de se lier à leur entrée “créatrice” – donc comme son nom le suggère, c’est un raccourcis pour créer des synonymes à une entrée ! Le message de redirection peut être personnalisé et traduit, voyez la description du paramètre global.

Comme avec les éléments “dict”, chaque synonyme est entouré de parenthèses, suivant la même syntaxe que les définitions de groupes, et attend les paramètres suivants :
 * (obligatoire)
 * Les langues du synonyme, comme ci-dessus.


 * (obligatoire)
 * Le titre du synonyme…


 * (obligatoire)
 * La référence de lien du synonyme.


 * (optionnel)
 * La clé de tri du synonyme, vaut  si vide.

Notez que dans les sous-pages, les entrées-synonymes apparaissent juste sous leurs créatrices. Cependant, dans la page principale du glossaire, elles seront correctement regroupées et triées comme attendu !

Les liens de glossaire
Les liens xGlossary sont un type “spécialisé” de lien pointant vers des entrées dans les pages de glossaire.

L’une de leur fonctionnalités clé est qu’ils peuvent retourner le contenu de la “shortdesc” de l’entrée liée, ce qui, avec un peu de JavaScript, peut être transformé en une info bulle apparaissant quand la souris survole le lien, par exemple.

Notez que quand vous utilisez la référence d’une entrée synonyme générée automatiquement, vous aurez la shortdesc de la “vraie” entrée, pas le “texte de redirection” de l’entrée synonyme !

Voici les paramètres de cette fonction :
 * (optionnel)
 * Le code iso de la langue à utiliser pour les templates/messages/… (par défaut, la langue de l’utilisateur courant).


 * (obligatoire)
 * Le chemin-wiki complet vers l’entrée liée (c-à-d nom/de/page#“ref”_de_l’entrée). Voyez ci-dessous pour des idées d’automatisation de la création de ce chemin à partir de la seule référence de l’entrée…


 * (obligatoire[wiki])
 * Le texte du lien.


 * (optionnel)
 * Si réglé à “yes” ou “no”, cela écrasera la valeur du paramètre global mLinkShowShortDesc.

Notez que vous pouvez empêcher la récupération automatique de la “shortdesc” en mettant le mLinkShowShortDesc global à “false”…

L’aide du glossaire
Eh bien, cela affiche cette page d’aide ! Créez simplement une page vide avec l’appel à  (et éventuellement un paramètre disp_lang) pour la voir.

Les tests du glossaire
va lancer quelques tests basiques, et afficher leurs résultats. Elle ne peut tester toutes les fonctionnalités, mais c’est un bon point de départ à vérifier si vous rencontrez des problèmes…

Paramètres globaux
Ce sont les réglages que vous pouvez définir dans votre fichier, après avoir importé  . Notez que nous utilisons une seule variable globale,, qui contient tous les réglages !


 * $wgxGlossarySettings->mKeepEmptyGroups
 * (par défaut : )
 * S’il faut conserver les groupes vides dans la page de glossaire principale. Cela peut être re-défini par chaque appel, voyez ci-dessus.


 * $wgxGlossarySettings->mMiscGroupName
 * (par défaut : )
 * Le nom du groupe “__misc”, dans toutes les langues nécessaires (celle par défaut est l’anglais ; seules les valeurs anglaises et françaises sont définies actuellement).


 * $wgxGlossarySettings->mMiscGroupSortKey
 * (par défaut : )
 * La clé qui sera utilisée pour trier le groupe “__misc” (utilisez “__first” pour le mettre en tête, “__last” pour le mettre en queue… Faites attention à ne pas utiliser une même clé de tri que l’un de vos groupes “normaux” !).


 * $wgxGlossarySettings->mEnsynRedirMsg
 * (par défaut : )
 * Les messages de “redirection” dans les entrées synonymes générées automatiquement.


 * $wgxGlossarySettings->mLinkShowShortDesc
 * (par défaut : )
 * S’il faut ou non montrer la partie “shortdesc” de l’entrée dans les liens de glossaire. Cela peut être re-défini par chaque appel, voyez ci-dessus.


 * $wgxGlossarySettings->mLinkShowShortDescInGlossary
 * (par défaut : )
 * S’il faut ou non montrer la partie “shortdesc” de l’entrée dans les liens de glossaire, au sein des pages de glossaire. Les afficher implique deux rendus de ces pages de glossaire, vous pourriez donc désactiver cela pour des raisons de performance…


 * $wgxGlossarySettings->mShowPerfs
 * (par défaut : )
 * S’il faut ou non afficher les infos de performance (i.e. les temps d’exécution de certaines fonctions clé)…

Templates
Tous les éléments du système de glossaire sont rendus à travers un système de “template” simplifié, ce qui signifie que vous pouvez personnaliser de façon assez avancée le code xhtml produit par les fonctions de xGlossary. Ces templates sont égalements i18n-ables.

Attention :Nous parlons ici de templates xGlossary, pas de templates MediaWiki ! Il y a deux options dans $wgxGlossarySettings qui contrôlent ces templates::


 * $wgxGlossarySettings->mTemplateVarsNames
 * La définition des noms des variables des templates. Voici son contenu actuel :

array(	// The place holder for syntax-errors messages.	"xg_err"        => "",	// General glossary index and content.	"xg_idx"         => "",	"xg_content"     => "",	// The glossary group reference, name and content.	"xg_grname"      => "",	"xg_grref"       => "",	"xg_grcontent"   => "",	// The glossary entry elements.	"xg_enref"       => "",        // The reference of the entry.	"xg_enediturl"   => "",    // The “edit” url of owner sub-page.	"xg_enlangs"     => "",      // The languages of the entry.	"xg_entitle"     => "",      // The title of the entry.	"xg_ensort"      => "",       // The sort key of the entry.	"xg_enshortdesc" => "",  // The short description.	"xg_endict"      => "",       // The dict content.	"xg_enlongdesc"  => "",   // The long description.	// The synonym entry specificities.	"xg_ensynorgref" => "",  // The reference to the org entry.	"xg_ensynmsg"    => "",     // The message of the “redirection”. // The dict elements. "xg_dctlangs"   => "",     // The languages of this def. "xg_dctterm"    => "",      // The term of this def. "xg_dctapprox"  => "",    // The approx state ("" or "?"). "xg_dctuncrt"   => "",     // The uncertain state ("" or "~"). "xg_dctusage"   => "",     // The usage value ("*" to "*****"). "xg_dctnote"    => "",      // The notes about this def. // The link elements. "xg_lnkpath"    => "",      // The wiki-path to the entry. "xg_lnktext"    => "",      // The text used by the link. "xg_lnkshortdesc"=> "", // The shortdesc of the linked entry. );
 * Les clés (chaînes de gauche) ne devraient jamais être modifiées.
 * Les chaînes de droite sont les chaînes qui serviront comme “tenant-lieu” pour les variables de templates. Vous ne devriez quasiment jamais avoir besoin de les modifier, de toute façon.


 * $wgxGlossarySettings->mTemplates
 * Les templates eux-mêmes, qui sont des morceaux de code xhtml, avec les “tenant-lieu” à être remplacés par les variables calculées.
 * Il s’agit d’un tableau 2D, avec au premier niveau, les codes ISO de chaque langue («en”, “fr”, etc.), puis les templates i18n.
 * Voici un exemple simplifié :

array(	"en" =&gt; array( /*		 * A “template” for warning the user about errors (lacking parameters, etc.). * will be replaced by the error message. */		xGlossaryI18n::TMPL_ERROR =&gt; '&lt;span class="xg_error"&gt;&lt;/span&gt;', /*		 * A “template” for the glossary page. * will be replaced by an unordered list of links to all known groups. * will be replaced by all generated groups. */		xGlossaryI18n::TMPL_GLOSSARY =&gt; '&lt;div class="xg_glossary"&gt;&lt;!-- --&gt;&lt;div class="xg_index"&gt;&lt;!-- --&gt;&lt;!-- --&gt;&lt;/div&gt;&lt;!-- --&gt;&lt;div class="xg_content"&gt;&lt;!-- --&gt;&lt;!-- --&gt;&lt;/div&gt;&lt;!-- --&gt;&lt;/div&gt;,' ), );
 * Vous noterez dans le code ci-dessus que les “tenant-lieu” utilisent les clés de, et pas ses valeurs. Elles seront remplacées au moment de l’initialisation par les bonnes valeurs, pour vous permettre de définir d’autres noms de “tenant-lieu”, sans avoir à toucher aux templates proprement dit…
 * Notez également que tous les retours à la ligne sont commentés en xhtml, pour éviter que MediaWiki rajoute des &lt;p&gt;&lt;/p&gt; partout (Grrr !).
 * sont des constantes pour chaque templates :

// Templates “id”. const TMPL_ERROR         = "xg_tmpl_error"; const TMPL_GLOSSARY      = "xg_tmpl_glossary"; const TMPL_GROUP         = "xg_tmpl_group"; const TMPL_ENTRY         = "xg_tmpl_entry"; const TMPL_ENTRYSYN      = "xg_tmpl_entrysyn"; const TMPL_DICT          = "xg_tmpl_dict"; const TMPL_LINK          = "xg_tmpl_link";

Pour plus d’informations et d’exemples sur les templates xGlossary, lisez le code du fichier  – de toute façon, si vous prévoyez de modifier ces réglages, vous êtes sans aucun doute un “site admin” ;).

Même si c’est évident, mentionnons également la feuille de style CSS comme moyen de personnaliser la partie graphique de cette extension !

À propos de JS
xGlossary utilise Java Script à deux endroits (les groupes d’entrées repliables des pages de glossaire, et l‘info bulle des liens de glossaire) – mais JS n’est absolument pas nécessaire au bon fonctionnement de xGlossary !

Le code Java Script fourni avec cette extension utilise jQuery, vous devrez donc inclure cette librairie dans vos pages si vous voulez l’utiliser “tel quel”. Cependant, j’ai essayé de bien préparer la production de xGlossary afin qu’elle soit utilisable par n’importe quel code JS, en utilisant des classes “xg_js_xxx” pour marquer les éléments pour JS, il devrait donc être assez facile d’adapter tout ça pour une autre “boîte à outil” JS…

Suggestions de templates
Voici quelques suggestions de templates (MediaWiki, cette fois !) utilisant des fonctions xGlossary, et automatisant certaines actions :


 * Afficher la sélection de langue
 * Si vous avez un site multilingue avec une façon standard de nommer les pages pour les différents langages, vous pourriez vouloir créer un glossaire pour chacune. Par ex. avec le wiki de Blender, nous utilisons {espace_de_nom}:{langue/}{nom_de_page}, vous pouvez donc créer un template qui détecte la langue de la page de glossaire courante, et règle en conséquence le paramètre “disp_lang” de l’appel  qu’il contient. La même chose est valable pour les entrées et liens de glossaire, évidemment !


 * Définir le bon chemin pour un lien de glossaire
 * En supposant que vous avez une page bien déterminée de glossaire, vous pouvez créer un template Glossary/Link qui, avec juste la référence d’une entrée, va créer le bon chemin vers la page de glossaire, avec la référence comme “fragment” url.