Aide en ligne : fonctionnalités attendues d'un nouveau système - commentaires

Aide en ligne : fonctionnalités attendues d'un nouveau système

En ce qui concerne les liens internes et l'outil d'édition, il faut d'abord remarquer que l'existant est très insatisfaisant. Par exemple l'aide sur les rubrique est un article dont le source est fourni ici par www.spipnet. Ce source contient un libellé logo d'un article pour un lien exécutant l'aide en ligne (exec=aide_index), ce qui fait que cliquer dessus dans le cadre du processus d'édition fait quitter ce processus.

Si l'aide en ligne était gérée par un squelette, on peut imaginer qu'un rédacteur écrive ce squelette avec du texte brut, puis utilise Langonet en version 0.7 minimum, qui repère dans un squelette du texte brut et l'évacue dans un fichier de langue.

On est donc ramené à la question de l'édition de squelette, pas forcément bien traitée aujourd'hui mais dont on s'accommode depuis toujours. Et ça serait une raison plus pour l'améliorer, comme proposé dans Des squelettes SPIP en XML, est-ce possible ?.

Aide en ligne : fonctionnalités attendues d'un nouveau système

En ce qui concerne l'ordre des entrées, il serait fourni sous la forme d'un squelette qui, au minimum, serait constitué d'une suite de chaînes de langue, certaines référençant des textes bruts (les titres de section), d'autres les mini-squelettes évoqués (donnant le corps de la section). Un squelette plus élaboré pourrait provoquer le parcours des modules de langues des plugins installés, pour trouver les items d'un nom donné (par exemple l'item « raccourci » dans les fichiers de langues de tous les plugins). Ca me paraît beaucoup plus souple que le systéme actuel qui code cet ordre en dur dans les textes d'aide,

Aide en ligne : fonctionnalités attendues d'un nouveau système

[je réponds en plusieurs fois à cause de la limitation du nombre de caractères]

Qui peut le plus peut le moins : a priori il n'y a effectivement pas lieu d'utiliser une boucle SPIP pour calculer un libellé de langue, en revanche la notion de contexte est commune à l'application d'un squelette et au calcul d'un libellé ayant des @ dedans, ainsi qu'à la news-letter comme le rappelle fort à propos JLuc. Ce que je déplore énormément dans SPIP c'est la quantité d'opérations semblables qu'on trouve à tous les coins de code sans jamais qu'il y ait une vision unifiée. De même, est commun le besoin de référencer des images et d'insérer des hyper-liens. A partir du moment où ce libellé n'est donc plus du texte brut insérable tel quel dans un article mais un cadre à remplir avant insertion, c'est qu'on est en présence de ce que SPIP appelle un squelette, et je ne vois que des désavantages à ne pas le traiter comme tel.

Maintenant introduire cette nouvelle fonctionnalité n'oblige pas à l' utiliser pour l'aide en ligne. Je dis seulement que si on l'adopte, alors il devient possible de rédiger la doc sous forme de chaînes de langues sans rien perdre de la puissance de mise en page de SPIP, et ce faisant on résout sans frais la gestion de versions puisque c'est Subversion qui s'en charge.

Aide en ligne : fonctionnalités attendues d'un nouveau système

Concernant les chaines-squelettes

Voici une situation en rapport qui pourrait bénéficier d'éventuels développements dans la direction de chaines interprétables : les envois de news letter. Celles ci ont un texte fixe, calculé par un squelette selon le contexte global, mais paramétrable toutefois en fonction du destinataire. Dans spip-lettres, il y a une couche d'interprétation supplémentaire du #TEXTE récupéré, pour injecter les variables d'environnement non issus du contexte de calcul du squelette, mais celles issues de l'application de la lettre à son destinataire, avec des traitements similaires aux raccourcis SPIP. Je me demande si il n'y a pas un concept un peu plus général et commun aux 2 situations.

Concernant une aide versionnée

Fil rêve depuis longtemps d'un non-CMS dont les textes seraient stockés et versionnés en 100% collaboratifs sur un serveur git ou svn, github par exemple. Il y a d'autres personnes qui ont commencé à travailler sur ce concept.
Il faudrait intégrer cette possibilité aux réflexions, et éviter de réinventer l'eau chaude, pour se concentrer plus sur l'intégration et l'interface, l'adaptation fine au projet SPIP.

Rédaction de la doc

Enfin, avoir un top - outil de doc ne suffira pas à multiplier la doc, même s'il peut y inviter, ou le favoriser.
Comment faire en sorte que la doc soit plus complètement rédigée en temps réel avec les développements ?

Aide en ligne : fonctionnalités attendues d'un nouveau système

Quelques éléments de compléments :

doit-on considérer que la chaine de langue est un morceau de squelette ou un morceau d'article ? Dans le second cas, c'est propre qui serait appliqué à la chaine de langue. On n'a pas besoin de faire tourner des boucles dans un article d'aide, mais de bénéficier des outils rédactionnels de SPIP. Il me semble qu'il y a là une confusion.
restera le cas des images à traiter de manière particulière (un modèle n'ayant de sens que dans un contexte local, ainsi que les raccourcis vers d'autres entrées d'aide et/ou des pages de l'espace privé (voir les remarques contenues dans cet article).
Dans tous les cas, la question d'une interface de rédaction / tractuction restera nécessaire. Autrement dit, si utilisation des chaines de langue, cela voudrait dire faire évoluer trad_lang. Dans tous les cas, il faudra pouvoir maintenir en parallèle plusieurs versions / branches d'une aide en ligne.
Dans le cas d'un passage par des chaines de langues, il faudrait voir comment stocker à la fois les titres des articles d'aide mais également leur organisation (en rubriques et leur ordre) et voir comment gérer une structuration partagée entre plusieurs plugins. Cela fait partie des éléments évoqués également dans le présent article.

Aide en ligne : fonctionnalités attendues d'un nouveau système

Sur la question de l'aide disponible sur les serveurs, mon idée est en fait double.

Je dis qu'il ne faut pas réécrire une partie de Subversion, et donc qu'il faut lui déléguer la gestion des versions de l'aide, en la mettant dans des fichiers de langues. A partir de là, on peut décider ou non de copier les fichiers de langues dans une installation de SPIP. Si on le fait, ça résout en effet le problème des serveurs sans sortie vers Internet. Si on ne le fait pas, la fonction charger_langue, au lieu de postuler qu'il doit exister au moins la version française du fichier cherché, pourrait automatiquement aller chercher ce fichier sur le serveur Subversion. Je trouve en effet bien coûteux que chaque version de SPIP trimbale toute ses traductions possibles, alors qu'aucun site n'utilise simultanément tous ces fichiers.

Aide en ligne : fonctionnalités attendues d'un nouveau système

Pour la parade à #TRUC, c'est comme dans un squelette : il faut passer par les entités XML : #TRUC

Aide en ligne : fonctionnalités attendues d'un nouveau système

Cela dépendra de la solution adoptée. Si on s'oriente vers l'idée d'Emmanuel, oui ; si on s'oriente vers l'idée exprimée dans cet article, la réponse est non, pas plus qu'actuellement.

Aide en ligne : fonctionnalités attendues d'un nouveau système

Et est il possible de gérer le cas d'un site intranet dont le serveur n'a pas la possibilité d'aller chercher l'aide sur internet ?

Aide en ligne : fonctionnalités attendues d'un nouveau système

Ingénieux cette idée de pouvoir brancher le compilateur sur les chaînes de langues. Il faudra peut être avant trouver une parade pour une doc disant : « Fournit la balise #TRUC » : dans ce cas là, il faut afficher #TRUC :)

Aide en ligne : fonctionnalités attendues d'un nouveau système

La fonction _T, qui remplace une chaîne de langue par son libellé trouvé dans un des fichiers de langue, n'applique pas à ce libellé la fonction « propre », laquelle gère les raccourcis et les modèles (en particulier « img »). Mais elle ne le fait pas par souci d'efficacité uniquement. Remarque que néanmoins elle ne considère pas qu'un tel libellé est du texte brut, car elle repère les motifs « @.*@ » et les remplace par les valeurs données en 2^e argument de _T. Bref, un libellé de langue est une espèce de squelette minimal où on écrit « @nom@ » là au lieu de « #NOM » (ici le 2^e argument de _T joue le même rôle que le tableau ENV pour un squelette : c'est le contexte d'appel).

Si on postule qu'un libellé de langue est un squelette (je veux dire le texte d'un squelette, pas un nom de fichier à trouver), on récupère toute la puissance de mise en page de SPIP dans les chaînes de langue. Ca paraît dispendieux, mais il suffit de tester dans la fonction _T si ce libellé possède les caractères < ou # pour éviter de sortir cette grosse artillerie quand ce n'est pas nécessaire. Ca ne serait pas plus coûteux que la recherche actuelle des « @.*@ », et cela unifierait les mécanismes utilisés dans SPIP.

Pour ce qui est du travail éditorial, il suffit de prévoir un squelette générique, c'est-à-dire en gros < :#ENVnom :> (actuellement incompris du compilateur mais ça peut s'arranger), pour que l'on puisse voir ce que ça va donner.

Aide en ligne : fonctionnalités attendues d'un nouveau système

Salut Emmanuel,

Je reprends ici la discussion de SPIP-Dev afin de pouvoir collecter en un seul endroit les idées sur le sujet.

Tu as noté deux points faibles concernant l'idée de mettre l'aide dans des fichiers de langue. Concernant le point 1, je ne comprends pas en quoi l'écriture en noisettes pourrait apporter une solution aux images. Si tu peux m'éclairer... Et pour les raccourcis ?

Par contre, je crois qu'il y a aussi un troisième handicap à cette solution c'est l'écriture même de l'aide. C'est un travail éditorial qui nécessite de voir aussi le résultat de ce qu'on écrit. A cet égard, l'article insiste bien sur la nécessité de fournir au rédacteur un tel outil. Donc pour moi, c'est incontournable.

Cependant, si on résout les points 1 et 2, on peut imaginer une interface qui génère ces fichiers de langue comme Salvatore le fait, car il est vrai que les concepts de module, rubrique, entrée se rapprochent de ceux des fichiers de langues (en particulier, les identifiants uniques des rubriques et entrées d'un module d'aide).

A creuser donc...

Aide en ligne : fonctionnalités attendues d'un nouveau système

La réorganisation de l'aide en ligne est indispensable, c'est chouette de lire une proposition là-dessus. Néanmoins, je m'interroge sur l'intérêt des serveurs spécifiques. Le gros problème actuel réside dans l'adéquation entre le code qui s'exécute et la documentation qui lui est associée, autrement dit la version de la documentation qui corresponde à la version du code. Or il y a déjà un mécanisme pour ça, savoir les dépôts gérés par Subversion ou autre, qui de plus sont des serveurs.

Il me semble donc plus pertinent d'inclure l'aide en ligne dans les fichiers de langues, ce qui pose deux problèmes :

l'aide en ligne comporte des images, ce que ne peut contenir un fichier de langue ;
une distribution de SPIP sera alourdie par ces nouveaux fichiers.

Pour le point 1, il faudrait réécrire l'aide en ligne sous forme de noisettes. Mais ce n'est pas impossible et ça aurait l'avantage d'unifier la construction de page XHTML en SPIP, l'aide n'ayant aucune raison d'être dérogatoire comme jusqu'à présent.

Pour le point 2, il faudrait introduire la notion de fichiers de langue distants. Cette notion est en fait implicite dans l'aide en ligne actuelle, mais ce serait l'occasion de la généraliser. Ce faisant, on pourrait éliminer tous les fichiers de langues dans une distribution de SPIP, et le mécanisme de mise cache du fichier d'aide serait appliqué pour les fichiers de langues effectivement utilisés par l'instance de SPIP installée.