Hello,

Le dim. 29 sept. 2019 à 02:22, Ybbet SPIP <teddy.s...@gmail.com> a écrit :

> J’ai parlé du plugin Insérer Modèles car c’est le seul plugin à ma
> connaissance centré sur les modèles. La mécanique mis en place par ledit
> plugin est le couple html/yaml. Ce couple a été adopté par des plugins
> « helpers » de la communauté :
> - Saisies ;
> - Vérifier.
> J’ai parlé à ce moment là de la nomenclature mis en place par ce plugin
> qui demande une icone, un titre, etc. C’était aussi, si on adopte le
> fichier yaml, pour ne pas casser le fonctionnement qui a été mis en place
> par ce plugin en changeant le contenu de ce fichier YAML.
> C’est le même principe par exemple pour le fichier saisies/auteurs.yaml du
> plugin Saisies. ET, il indique les paramètres de la saisie. (Autre exemple
> : saisies/choix_grille.yaml)
> Le plugin Insérer Modèles apporte la documentation IN SITU abordée par
> Rasta.
>
> Le choix du couple html/yaml n’a pas été remis en question dans ces
> plugins largement plébiscités-utilisés par la communauté. ;-)
>
>
Soit mais je pense qu'on mélange les choses.
Dans ces plugins le YAML apporte de la configuration avant tout.
L'utilisation du YAML est donc légitime à mon sens et le langage permet
d'être assez compréhensible même si je pense qu'on devrait plutôt utiliser
du JSON.
A ce propos, les YAML ne sont jamais expliqués au travers d'un schéma ce
qui est possible aujourd'hui et donc on ne sait jamais ce qu'il est
possible d'y mettre. J'ai corrigé ça dans le noiZetier mais ça devrait être
pratique plus régulière.



> Eric, il ne faut pas prendre strictosensus le terme « documentation » ici.
> La page que je pense est plus une mise en forme lisible et compréhensible
> humainement et sans outil de développement (PHPStorm, Sublime Text,
> Netbeans, etc.).
>

Soit, je ne suis pas totalement abruti ;-)


> Les fichiers YAML de saisies sont utilisés pour construire la page
> /ecrire/?exec=saisies_doc et c’est compréhensible.
>

Ca c'est toi qui le dit.


> Ces fichiers YAML sont des données structurées. Il nous suffit d’en faire
> ce que nous voulons.
> Le PHPDoc est documentation pour développeurs. Pas pour utilisateurs
> lambda.
>

Tu plaisantes là franchement. Mais j'y reviendrais plus bas.


> Pourquoi mettre en place une nouvelle écriture dans les fichiers html ?
> Même une « pseudo » écriture YAML. Pseudo dans le sens où ce n’est pas dans
> un fichier yaml. Je comprends l’alerte de Rasta sur le fait d’avoir « 2 »
> fichiers à maintenir. C’est sûr. Mais on le fait déjà tous pour les
> saisies. Ça ne choque personne. On enfonce pour moi ici des portes ouvertes.
>

Mais non on le fait pas tous pour les saisies.
Y a rien de systématique et ce n'est pas obligatoire.
Et franchement si je dois aller voir dans un YAML la liste des paramètres
sans explication, je ne vois pas l'intérêt.
Donc ton postulat de départ est faux.


>
> Je rejoins l’avis de Rasta : du PHPDoc, c’est un parser supplémentaire.
> Par contre… Mon but n’est pas de faire mon truc dans mon coin. Mais
> d’amener une solution qui pourra être utile à l’ensemble des utilisateurs
> de SPIP.
>
>
Oui si on veut.
Remarque ça nous arrive parfois de faire des plugins et de développer des
trucs nouveaux...
Mais j'ai déjà répondu à ça et je trouve qu'on pourrait éviter d'avoir deux
fichiers et intégrer le YAML dans le HTML.
Parce que ce YAML N'EST PAS de la configuration.
Le vrai souci qu'à exprimé Rasta c'est la traduction.

Maintenant, me dire que la doc utilisateur et dévelopeur est différente
pour ce cas, ça me fait doucement rire : c'est quoi la différence pour
décrire le but de l'inclusion et l'utilisation de ses paramètres quand on
est "rédacteur dans le privé" et "développeur"  ?
Aucune.
Donc on est dans un cas un peu particulier où une seule documentation
pourrait suffire.

Après il faut être pragmatique :
- ce besoin est au moins aussi important pour les développeurs que pour les
rédacteurs.
- que ça pourrait s'appliquer aussi aux inclusions hors modèles
- que l'on pourrait réfléchir in fine à rajouter ces informations à
l'autodoc
- que la traduction n'est surement pas le souci le plus critique pour les
utilisateurs et que donc du texte en français suffirait, sans chaines de
langue inutiles qui donnent encore du travail aux traducteurs pour une
utilité plus que douteuse.

C'est pourquoi je ferais plutôt :
- une balise #REM reconnaissable comme une doc
- une description type phpdoc pour l'inclusion avec du YAML qui serait
extrait de la balise avec des textes sans chaines de langue.
- je ferais disparaitre les YAML externes à terme pour Insérer Modèles car
il servirait plus à rien, le plugin pouvant extraire les données du HTML.



> Le fait de mettre en place le couple html/yaml permet d’apporter de
> nouvelles possibilités d’utilisation. Oui, on est d’accord, il faut
> installer le plugin YAML. Mais ça devient une habitude pour tout le monde,
> non ? :-D
> (Je ne crée plus de sites sans l’ajout des plugins Saisies, Vérifier,
> YAML, SPIP Bonux et… Info SPIP)
>
>
Je ne sais pas d'où tu sors ça.
Le YAML est bancal dans SPIP aujourd'hui.
Le Core ne le procure pas, ce qui est pour moi une erreur à partir du
moment où on pense que ce format est important comme le XML ou le JSON.
Textwheel fournit un morceau de librairie bien dépassé.
Et j'ai refait le plugin YAML pour utiliser les différentes librairies afin
in fine de choisir une voie qu'on a jamais choisi.
Je pense qu'on pourrait faire mieux :p.

Et franchement, le JSON est au moins natif en PHP, possède un schéma qui
permettrait à terme de valider les formats et peut être fabriqué à partir
d'un YAML pour ceux qui sont plus à l'aise avec ce format.
J'avais d'ailleurs fourni un patch de Textwheel en JSON presque fonctionnel
et qui nous permettrait de nous passer du YAML dans Textwheel.

++
Eric
----
spip-zone@rezo.net - https://listes.rezo.net/mailman/listinfo/spip-zone

Répondre à