Point sur l'aide en ligne intégr ée

 >> Le 30/04/2021 à 20:18, Matthieu Marcillaud a écrit :
 >>> Aide

[...]

 > On va a priori intégrer cette proposition (en fr uniquement pour
 > l'instant) dans l'alpha 4.0… histoire que les gens puissent tester et
 > faire des retours.


(désolé c'est un peu en vrac)

Un point sur ça : la version 4.0.0-alpha a donc cette première version 
d'une aide en ligne intégrée à SPIP, dont le contenu est puisé dans des 
fichiers inclus du plugin Aide. Le contenu des fichiers peut donc suivre 
la version de SPIP associée au plugin. Un pipeline "aide_index" permet 
de compléter la liste des pages d'aides (et donc des plugins peuvent 
ajouter du contenu dedans)

Langues intégrées
-----------------

J'ai juste intégré les langues [fr] et [en], en copiant / collant en 
gros le textes des articles d'aides de spip.net et en le découpant en 
différentes parties. C'est une première approximation qui sera 
certainement à améliorer.

Il faudra donc réintégrer les autres langues sur le même principe.


Réécritures & traductions
-------------------------

À mon avis, certains textes pourraient être réécris dedans. Aussi les 
extraits de code dans l'aide devraient être écrits avec <pre><code> 
plutôt que <cadre> actuellement, mais c'est à faire (vu que <cadre> ne 
fait pas ça tout seul).


Cependant il va être un peu plus difficile de suivre tout ça pour les 
personnes traductrices : vu que ça ne passe ni par traduire.spip.net, ni 
par un article SPIP standard, mais un fichier 
"aide/[lang]/raccourcis/lien.spip". Ceci dit le résultat est directement 
visible dans les pages ?exec=aide&aide=raccourcis ce qui est moindre mal.


Enfin j'ai ajouté un "Résumé" des raccourcis typo les plus courants, 
avant le reste de l'aide. Il pourrait être amélioré aussi. Je trouve ça 
beaucoup plus succinct et parlant. Je n'ai pas traduit ce résumé en [en] 
par contre.


Groupes d'aide
--------------

Afin de rendre l'aide extensible, on a considéré les aides en terme de 
groupes. Seul actuellement le groupe des "Raccourcis typographiques" est 
présent. Il contient différentes entrées et peut contenir (c'est même 
conseillé) une introduction (un fichier "aide/[lang]/[groupe]/_intro.spip")

Il peut donc y avoir d'autres groupes d'aide. On pourrait remettre 
certaines parties : par exemple la description des articles virtuels ou 
des dates de publication, si c'est souhaitable / souhaité... dans un 
groupe "article" par exemple…

La page ?exec=aide de l'espace privé liste l'ensemble des groupes d'aide 
avec leur texte introductif.


Technique
---------

- #AIDER{raccourcis} met l'icone et le lien pour charger le groupe 
d'aide des raccourcis typographiques.
- aide_generer_url('raccourcis') génère aussi l'url (en php).


Images
------

La question se pose si une aide souhaite présenter des images. Pour le 
moment on botte en touche.

Il y a plusieurs questionnement et/ou inconvénients aux images :

a) c'est plus difficile à maintenir (il faut refaire les capture d'écran 
régulièrement)
b) est-ce que les images sont "traduites" ? (et donc dupliquées pour 
chaque langue ou pas)
c) ça peut prendre un poids non négligeable dans le plugin, et donc sur 
l'hébergement
d) comment lier l'image au texte d'article d'aide ?

Pour le dernier point d), la solution d'un modèle (intégré au plugin 
d'aide) serait peut être le plus simple. On ne peut pas utiliser <docXX> 
où XX est un document. Mais on pourrait avoir 
<doc_aide|raccourcis/lien.svg> qui chercherait 
"aide/[lang]/raccourcis/lien.svg". L'image serait cherchée en suivant le 
même chemin de fallback de langue que les traductions. Si l'image 
"aide/en/raccourcis/lien.svg" n'existe pas, on prendrait 
"aide/fr/raccourcis/lien.svg"...

Ça pourrait résoudre b) comme ça. Par contre b) avec traductions d'image 
n'est pas hyper compatible avec a) …

À voir.

Voilou.

MM.



_______________________________________________
liste: https://listes.rezo.net/mailman/listinfo/spip-dev
doc: https://www.spip.net/
dev: https://core.spip.net/
irc://irc.freenode.net/spip