Hello,

Le dim. 29 sept. 2019 à 12:56, Eric Lupinacci <e...@smellup.net> a écrit :

> 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.e
>

Certes


>
>
>
>> 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 ;-)
>

Je ne me permettrais pas! :-*


>
>
>> 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.
>

Je n'ai pas dit que c'était parfait :-D
J'ai dit que c'était compréhensible. Perfectible ? Très certainement!


>
>
>> 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.
>

Oui, je sais la documentation de PHP est faite essentiellement à base de
PHPDoc. Tout comme autodoc de SPIP.


>
>> 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 n'ai pas dit qu'il fallait aller dans le fichier YAML pour voir les
paramètres. Je dis que le développeur mettant à disposition un modèle crée
le fichier YAML indiquant comme réagis son modèle. Son nom, ses paramètres,
etc.
Puis dans une page du privé, on affiche la "documentation" générée à partir
de ce YAML.
Pas la peine d'aller dans le YAML. C'est d'ailleurs de ce constat là que
j'ai créé les pages ?exec=saisies_doc et ?exec=verifier_doc.


>
>
>>
>> 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.
>

Oui si on reste dans le fichier YAML, c'est sûr qu'une chaine de langue
n'est pas explicite. Encore si des IDE comprenaient comment SPIP
construisait ses chaines de langue et qu'un simple clic permettrait d'avoir
une lecture humaine (un peu comme les fonctions ayant son PHPDoc), ça
serait une autre histoire.


>
> 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.
>

On est d'accord. Il faut que cela soit compréhensible. Pour ma part, je
faisais la différence entre ces 2 profils du fait que l'un va pouvoir lire
du code source et l'autre n'a aucune idée de ce qu'est un code source.


> Donc on est dans un cas un peu particulier où une seule documentation
> pourrait suffire.
>

Oui.


>
> 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.
>

Oui.


>
> 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.
>

Je ne suis pas séduit par cette écriture là… Le mélange de #REM + écriture
YAML et je ne sais quoi d'autre… Je trouve que cela complexifie la lecture.
Mais à la lumière de tout cela, ton idée de simili-PHPdoc est plus adaptée
que du code YAML


>
>
>> 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.
>

On est nombreux à utiliser le plugin Saisies. Il semble qu'il y ait 48,2%
des sites SPIP (reconnus/identifiés) qui ont installé le plugin Saisies. Il
n'y a que 4,2% qui ont installé le plugin Insérer Modèles.

Le YAML est bancal dans SPIP aujourd'hui.
>

Peut-être. Mais il est fonctionnel actuellement.


> 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.
>

Oui mais c'est aussi une des particularités du découpage par plugins de
SPIP. Le Core n'est pas obligé de TOUT fournir.


> 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.
>

C'est pas faux. Mais comment ? :-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.
>

J'aime pas le Json! Mais c'est une préférence personnelle. Je l'utilise
quand j'en ai besoin (pour du javascript la plus part du temps).


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

Répondre à