Dans le cadre de la réflexion autour de la restructuration de l’aide en ligne de SPIP, deux articles ont déjà été rédigés sur ce site :
- Aide en ligne : situation actuelle et limites
- Aide en ligne : fonctionnalités attendues d’un nouveau système
La proposition qui avait été faite reposait, comme l’aide actuelle, sur des fichiers d’aide gérés sur un serveur distant, SPIP téléchargeant à la demande les fichiers d’aide nécessaires. Les discussions qui ont suivi cette première proposition ont évoqué un certain nombre de points durs inhérents à la solution :
- Comment gérer une aide versionnée qui corresponde bien à la version de SPIP et des plugins qui sont installées sur le site ? Est-il nécessaire de recréer la roue alors que l’on utilise déjà SVN/GIT pour le versioning ?
- Faut-il recréer un système de gestion des traductions alors qu’il existe déjà http://trad.spip.net/ ?
- Quid des sites locaux qui n’ont pas d’accès distants ?
- Pourquoi ne pas utiliser les mécanismes déjà en place dans SPIP ?
La présente proposition est donc une alternative reposant pour une aide en ligne embarquée dans le core ou les plugins et s’appuyant sur des squelettes.
Concepts
L’aide en ligne sera composée de différentes entrées d’aide organisées en rubriques d’aide [1].
Les rubriques d’aide auront simplement un identifiant et un titre et n’ont d’autres vocations que d’organiser les différentes entrées.
Plusieurs rubriques d’aide génériques seront proposées par défaut, telles que [2] :
- Raccourcis typographiques
- Modèles
- Configuration
Un plugin pourra déclarer des rubriques d’aide additionnelles, par exemple le plugin mots pourra déclarer une nouvelle section Mots-Clés pour y ranger les entrées d’aide relatives aux mots-clés.
Chaque entrée d’aide sera rattachée à une rubrique d’aide (afin d’organiser les différentes entrées), aura un identifiant [3], un titre et un squelette associé qui contiendra le contenu de l’entrée d’aide.
L’ensemble du système de gestion d’aide sera implémenté dans un plugin dédié qui devra à terme intégrer la distribution standard de SPIP. L’aide en ligne correspondant au core sera livré par le core lui-même et non par le plugin de gestion de l’aide.
Squelettes des entrées d’aide
Chaque plugin intégrera donc sa propre aide. Dès lors, l’aide en ligne sera disponible localement, y compris pour les sites sans accès distant. L’aide disponible correspondra bien à la version du plugin actuellement installée et le versionning de l’aide sera gérée comme le reste du plugin.
À chaque entrée d’aide correspondra un squelette ayant pour nom l’identifiant de l’entrée d’aide et rangé dans un sous-répertoire aide/. Il s’agira d’un squelette comme un autre et donc l’ensemble des mécanismes de SPIP pourront y être utilisés. Par exemple, on pourra utiliser la balise #AUTORISER ou la balise #CONFIG pour afficher certains passages uniquement aux personnes pour qui c’est pertinent ou adapter l’aide en fonction de la configuration.
Par exemple, l’entrée d’aide décrivant le champs titre d’un article pourra ne mentionner le rôle du surtitre et/ou du sous-titre uniquement si ces derniers ont été activés. Il n’est pas nécessaire en effet de « polluer » l’aide adressée aux rédacteurs avec des informations non pertinentes. La même entrée pourrait afficher, uniquement pour les admins, un court texte expliquant que les surtitres et sous-titres sont activables/désactivables dans la configuration du site.
Les squelettes des entrées d’aide auront recours, classiquement, à des chaînes de langue. Afin d’organiser ses dernières, elles pourront être rassemblées préférentiellement dans un fichier aide-{$prefixe_plugin}_{$lang}.php. La traduction de l’aide sera donc assurée, pour les plugins sur la zone, via http://trad.spip.net/ au même titre que les autres chaînes de langues.
Les entrées pourront au besoin inclure des images (par exemple des captures d’écran), qui seront rangées dans un sous-répertoire aide/images. Il y a le cas particulier des captures d’écran qui pourraient être différentes selon la langue. On peut tout à fait envisager une nouvelle balise #CHEMIN_LANG{image.png} qui rechercherait l’existence d’un fichier image-lg.png (où lg est le code de la langue actuelle et se rabattrait sinon sur image.png [4].
Exemple de squelette d’aide
Il s’agit de l’aide portant sur le surtitre, le titre et le soustitre d’un article. Le fichier aide/spip-arttitre.html contiendrait :
Avec les chaines de langue suivantes déclarées dans le fichier lange/aide-spip_fr.php :
| Code | Valeur |
|---|---|
| titre_article | Titre de l’article |
| explication_surtitre | Optionnel, le <strong>surtitre</strong> est un titre complémentaire placé au-dessus du titre principal de l’article. Dans la presse écrite, le surtitre sert le plus souvent à indiquer le type d’article (éditorial, chronique, opinion...). |
| explication_titre | <strong>Titre :</strong> rien de bien compliqué, il s’agit du titre de l’article. Ce dernier est <strong>obligatoire</strong>. Pensez à le rédiger en respectant les règles usuelles d’emploi des majuscules. Surtout, ne l’écrivez pas tout en capitales. La mise en forme finale du titre sera effectuée par le squelette.<br />Les titres peuvent être numérotés pour un indiquer un ordre de tri des articles au sein de la rubrique. Voir <a href="@lien@">Numérotation des titres</a>. |
| explication_soustitre | Optionnel, le <strong>sous-titre</strong> est un titre complémentaire placé au-dessous du titre principal de l’article. Dans la presse écrite, le sous-titre sert le plus souvent à fournir des éléments factuels permettant de mieux situer le sujet de l’article. |
| spip:explication_configurer_article_titre | Les administrateurs du site peuvent configurer l’utilisation ou non du surtitre et/ou du sous-titre sur la page « <a href="@lien@">Contenu du site<a/> ». |
Exemple 2
Voici ce que pourrait être le squelette d’une entrée d’aide expliquant le gras et l’italique [5]. Cette entrée d’aide sera fournie par le plugin textwheel puisque c’est ce dernier qui implémente les raccourcis typographiques.
Avec les chaines de langue suivantes déclarées dans le fichier lange/aide-textwheel_fr.php :
| Code | Valeur |
|---|---|
| gras_italique | Gras et italique |
| explication_gras_italique | L’<em>italique</em> s’indique en plaçant le texte concerné entre simples accolades. Pour du texte en <strong>gras, utilisez des doubles accolades. |
| exemple_gras_italique | Du texte {en italique} et du texte {{en gras}}. |
| produira | produira : |
Déclarer les rubriques et les entrées d’aide
Les rubriques et les entrées d’aide seront déclarées à SPIP via un pipeline declarer_aide. Cette déclaration est nécessaire pour produire le sommaire de l’aide et organiser les entrées d’aide en sections.
Pour déclarer une nouvelle rubrique :
Pour déclarer une entrée :
Le sommaire sera construit selon l’ordre du tableau.
Le recours à un pipeline plutôt qu’à une déclaration xml permet une plus grande souplesse. On pourra ainsi afficher dans le sommaire que les entrées pertinentes. Par exemple, le plugin brèves pourrait n’afficher l’aide éditoriale sur les brèves que si ces dernières sont activées sur le site et une entrée sur la configuration des brèves seulement aux admins. Encore une fois, il s’agit de n’afficher que les informations utiles à l’utilisateur. Un pipeline permet par ailleurs aux plugins une plus grande souplesse de surcharge au besoin.
Compléter une entrée existante
Dans les quelques cas où il serait plus pertinent pour un plugin de compléter une entrée d’aide plutôt que d’en ajouter une, il sera possible de passer par le pipeline affiche_milieu, à moins de mettre en place un pipeline dédié affiche_aide.
Balise #AIDER
#AIDER{id_entree} produira l’icone d’aide avec un lien sur l’entrée demandée.
La balise sera par ailleurs étendue avec #AIDER{rubrique/id_rubrique} pour afficher une rubrique d’aide et la liste de ses entrées (par exemple la section Raccourcis typographiques). #AIDER{''} affichera le sommaire de l’aide.
Avantages d’une aide embarquée
- Repose sur les mécanismes déjà existants dans SPIP.
- Aisée à mettre en œuvre.
- Traductions facilitées car possibles via http://trad.spip.net => Les traducteurs n’ont pas besoin d’apprendre un nouvel outil.
- Aide accessible y compris pour un intranet.
- Facilité de surcharge / extension.
- Versionnage de l’aide intégrée au versionnage du plugin => il y a cohérence entre l’aide affichée et les fonctions implémentées, plus historique via SVN/GIT.
- Peut prendre aisément en compte la configuration du site pour n’afficher que les éléments pertinents.
- Facile à mettre en place également pour les plugins non développé sur la zone (inutile d’avoir à créer et gérer un serveur d’aide en ligne).
- En intégrant l’aide dans le code, il est plus aisé de rédiger/modifier une aide en parallèle du code.
Inconvénients
En premier lieu, une intégration de l’aide directement dans les plugins devrait aboutir un poids (taille en octets) plus élevés de ces derniers. Reste à savoir si cela représente un problème majeur ou non. En effet, les hébergements proposent plus d’espace disque de nos jours que par le passé. Par ailleurs, il est assez difficile de mesurer le poids additionnels que représenterait une aide intégrée. Si cela s’avère vraiment nécessaire, il serait assez facile de produire automatiquement des zips des plugins sans aide intégrée (en excluant le répertoire aide et les fichiers de langue commençant par aide). Mais cela est-il nécessaire ?
Le second élément concerne la rédaction de l’aide en ligne (dans la langue d’origine) qui nécessite dès lors de savoir écrire un fichier de langue, éditer un squelette et commiter sous SVN alors que le système actuel repose sur des articles SPIP. De plus, cela implique d’avoir à découper le texte de l’aide en plusieurs chaines de langue, ce qui n’est pas toujours aisé. Enfin, la rédaction en PHP du texte est moins aisée que celle d’un article SPIP.
Il est à noter que ce problème ne concerne que la langue de base de l’aide en ligne puisque la traduction serait gérée pour sa part via http://trad.spip.net. Cependant, sur spip.net, les contributions en matière de rédaction de l’aide en ligne sont peu nombreuses. L’aide n’a que très peu évolué depuis 2006-2008. De plus, bien qu’il s’agisse d’articles SPIP, ils utilisent des conventions spécifiques, notamment avec des titres en H2 et les images insérées en HTML et non joignables classiquement. Le recours à des squelettes et des chaînes de langue, bien que plus connu par un public de « développeurs », reposent quant à lui sur des mécanismes génériques de SPIP.
RSS 2.0