Organisation des fichiers - POD

[Jean-Mi]

Le fichier POD est séparé du script pour des raison de facilité d'édition, il est ensuite concaténé automatiquement lors du lancement du Makefile
Pour que cette tâche s'effectue correctement il faut que les deux fichiers aient le même nom et se trouve dans le même répertoire
monscript.sh
monscript.pod

Lors de l'installation du paquet le script va dans /usr/bin

Le script fait partie d'une catégorie ufrs-xxxx qui est installée dans /usr/share
Cette catégorie contient les fichiers textes, html, ... des différents scripts

 /usr/share/ufrs-xxxx
 /usr/share/ufrs-xxxx/html
 /usr/share/ufrs-xxxx/text

Voila pour ce qui est de l'organisation actuelle et qui fonctionne

-------------
Le reste est forké sur Bug #352298

[Matthias Hawran (jahwork)]

Je suis contre la séparation du script et de son POD.
Je ne trouve pas que cela facilite l'édition, au contraire.
Avoir le code et la doc dans un même fichier encourage plus a avoir les 2 bien synchronisés

Je ne comprends pas ce choix.

En plus ça complique le process: besoin de merger les 2...

Et quid d'un script avec le même nom, mais dans des langages différents ?
script.pl
script.sh
script.pod <= c'est le pod de qui ? script.pl ou script.sh ?

[Jean-Mi (jeanmi)]

La colirisation de la syntaxe ne fonctionne pas avec les éditeurs (gvim,
kate) c'est pour cela que j'ai optée pour la séparation

de plus 2 scripts avec le même nom cela n'est pas possible car quand le
script est installé en tant que paquet il n'a plus d'extension
voir le paquet toolbox dans le ppa
https://launchpad.net/~ubuntu-fr-scripts/+archive/ppa

Matthias Hawran a écrit :
> Je suis contre la séparation du script et de son POD.
> Je ne trouve pas que cela facilite l'édition, au contraire.
> Avoir le code et la doc dans un même fichier encourage plus a avoir les 2 bien synchronisés
>
> Je ne comprends pas ce choix.
>
> En plus ça complique le process: besoin de merger les 2...
>
> Et quid d'un script avec le même nom, mais dans des langages différents ?
> script.pl
> script.sh
> script.pod <= c'est le pod de qui ? script.pl ou script.sh ?
>
>

[Matthias Hawran (jahwork)]

Coloration syntaxique... hmmm... pas convaincu
c'est seulement de la doc...

Je n'y connais rien en création de paquet, mais pourquoi l'extension disparait ?

En tout cas ça ne vaut pas le coup de séparer les 2.
Il y a beaucoup plus de risque de désynchronisation code/doc
plus le besoin d'un post-process de concaténation inutile...

enfin bon...

au fait pourquoi est-on dans un bug report ? c'est quoi le bug ?

[Jean-Mi (jeanmi)]

Si tu ouvres le .pod avec gvim ou kate tu verras que le code est coloré
ce qui permet par exemple de voir rapidement les erreurs ainsi que les
différentes partie code/texte ce qui permet une lecture et une rédaction
plus aisée

c'est didrocks il me semble qui m'a dit qu'il ne fallait pas d'extension
pour la mise en paquet
de plus il est plus sympa de taper toolbox que toolbox.sh (je sais la
complétion existe ;-) )

je suis consciente du problème de post-process mais comme cette
opération est faite par les mainteneurs et packageurs
elle doit être faite avec tout le soin nécessaire ainsi que les tests
d'usage

C'est une wishlist suite à la problématique de l'installation du paquet
actuellement quand on écrit un script les fichiers annexes sont dans le
même répertoire ce qui n'est pas le cas une fois installé
seul le script va dans /usr/bin

Matthias Hawran a écrit :
> Coloration syntaxique... hmmm... pas convaincu
> c'est seulement de la doc...
>
> Je n'y connais rien en création de paquet, mais pourquoi l'extension
> disparait ?
>
>
> En tout cas ça ne vaut pas le coup de séparer les 2.
> Il y a beaucoup plus de risque de désynchronisation code/doc
> plus le besoin d'un post-process de concaténation inutile...
>
> enfin bon...
>
> au fait pourquoi est-on dans un bug report ? c'est quoi le bug ?
>
>

[Jean-Mi (jeanmi)]

Voila une copie d'écran assez parlante
http://img1.imagilive.com/0309/podgvim57b.png

[Matthias Hawran (jahwork)]

Comme je disais c'est de la doc, donc c'est très simple.
AMHA la coloration syntaxique n'apporte rien.
Plutôt la séparation apporte de la complexité (merge...)

Mon soucis est la synchro code/doc, plus facile si dans le même fichier.

Pour le bug report, on a donc 2 sujets ici: POD et problème d'installation paquet,
donc il faut 2 bug report séparés.
Plutôt la discussion du POD n'a pas a être dans un bug report, mais bon en l'absence de ML pour l'instant.

[Jean-Mi (jeanmi)]

Pour statuer sur cette séparation, il faudrait que d'autres se prononcent

j'ai ajoutée Jonathan au bug vu qu'il est le seul a avoir passé l'étape
du pod pour l'instant

c'est pas moi qui ai mélangée les sujets ;-)
ceci dit mon bug report n'est pas très clair je te l'accorde

Matthias Hawran a écrit :
> Comme je disais c'est de la doc, donc c'est très simple.
> AMHA la coloration syntaxique n'apporte rien.
> Plutôt la séparation apporte de la complexité (merge...)
>
> Mon soucis est la synchro code/doc, plus facile si dans le même fichier.
>
>
> Pour le bug report, on a donc 2 sujets ici: POD et problème d'installation paquet,
> donc il faut 2 bug report séparés.
> Plutôt la discussion du POD n'a pas a être dans un bug report, mais bon en l'absence de ML pour l'instant.
>
>

[Matthias Hawran (jahwork)]

[quote]c'est pas moi qui ai mélangée les sujets ;-)[/quote]

C'est qui alors ? C'est bien toi qui a créé le bug report non ?
Bon je fais un fork...

[Jean-Mi (jeanmi)]

J'ai créée une FAQ sur comment sont organisés les projets
https://answers.launchpad.net/ubuntu-fr-scripts/+faq/478

concernant la séparation du script et du fichier POD un autre argument en faveur de la séparation en deux fichiers
si quelqu'un souhaite prendre en charge la rédaction, corrections, mise en page, cela évite de compromettre l'intégrité du script.
S'il s'agit d'un seul fichier il faudra à chaque fois tester ou faire un diff pour vérifier que le script n'a pas été modifié

[Matthias Hawran (jahwork)]

prendre en charge la rédaction... sans connaître le code ?
Je ne vois pas comment on peut faire ça.

Je ne vois pas en quoi ça compromet l'intégrité du code.
La doc est a la fin du fichier.

On a pas les mêmes manières de scripter ;-)
(perso c'est mon quotidien au taf: perl, bash)
Par expérience la doc a plus de chance d'être a jour si elle est dans le même fichier que le code.

J'ajoute Skippy au débat.

Les autres merci de donner votre avis. :-)

[Jean-Mi (jeanmi)]

Encore une fois je précise que je parle pas pour moi, mais pour ceux qui
vont rejoindre le projet.
Et comme je te l'ai déjà dit pour ma part quelque soit la méthode cela
m'est égale

Ce que je constate en revanche c'est qu'après mon post dans le forum
script utiles il n'y quasiment personne qui s'est inscrit et qui à
proposé des scripts. De plus seul pour l'instant Jonathan a passé
l'étape du pod.
Je vois, mais je me trompe peut être...
 * surmonter la difficulté de l'inscription et l'utilisation de launchpad
 * difficulté à utiliser bzr
 * difficulté à se conformer aux spécifications du projet
 * difficulté à comprendre et à utiliser le format pod

donc, et je me trompe encore peut être une fois de plus, je pense que
gérer deux fichiers distinct est plus abordable actuellement
Ceci dit ça n'est pas bien grave, ce qui m'importe surtout pour
l'instant c'est que les scripts arrivent dans les projets.

Matthias Hawran a écrit :
> prendre en charge la rédaction... sans connaître le code ?
> Je ne vois pas comment on peut faire ça.
>
> Je ne vois pas en quoi ça compromet l'intégrité du code.
> La doc est a la fin du fichier.
>
> On a pas les mêmes manières de scripter ;-)
> (perso c'est mon quotidien au taf: perl, bash)
> Par expérience la doc a plus de chance d'être a jour si elle est dans le même fichier que le code.
>
> J'ajoute Skippy au débat.
>
> Les autres merci de donner votre avis. :-)
>
>

[Skippy le Grand Gourou (lecotegougdelaforce)]

> J'ajoute Skippy au débat.

Je comprends mieux pourquoi je n'ai reçu que le premier et le dernier post… :-P

Mes avis, donc :

1/ Je ne comprends pas bien la wishlist, une wishlist c'est censé être une demande, or là tout est présenté comme un fait. Qu'en est-il exactement ?

2/ Perso je préfère de loin que le script et la doc soient séparés. Quand j'ai récupéré la toolbox pour mettre AptOff aux normes, le choix d'un seul fichier contenant également la doc m'avait étonné, et pas séduit du tout. Le problème de synchronisation est un faux problème, les rapports de bugs sont là pour prendre ça en charge. La synchro n'est pas plus facile si tout est dans le même fichier, puisque la partie pod est de toute façon (si je me souviens bien) séparée du script.

3/ C'est quoi cette histoire de post-process ? Je ne vois toujours pas l'intérêt de merger les fichiers, si quelqu'un a une explication…

4/ Je suis assez d'accord avec les difficultés évoquées par fidji dans le dernier post, mais il faut voir qu'on vient de démarrer, laissons-nous le temps de prendre nous-même nos marques (comment l'interaction avec le projet peut sembler claire pour un contributeur lambda quand elle ne l'est pas encore pour les admins du projet…), ça sert à rien de se précipiter à rajouter 50000 scripts alors que l'organisation n'est pas encore figée et son efficacité démontrée.

[HS : Pourquoi une partie du README est en français et l'autre en anglais ?]

[Matthias Hawran (jahwork)]

ok pour le wishlist.

[Matthias Hawran (jahwork)]

La synchro n'est pas un faux problème et n'a rien a voir avec les rapports de bug.
Je le redis, d'expérience (je fais du perl/bash 80% de la journée au taf),
la doc a (beaucoup) plus de chance d'être a jour si elle est dans le même fichier.
C'est humain. point.
La doc a la base c'est pas intéressant, donc si elle est ailleurs dans un autre fichier
qu'il faut ouvrir, etc...

Le post-process c'est une conséquence du split ;-)

100% d'accord avec 4/
Rien a ajouter, tu as tout dis la dessus.
Rien ne sert de courir...

README: c'est qu'il est pas a jour.

[Jonathan Michalon (johndescs)]

Matthias Hawran a écrit :
> La synchro n'est pas un faux problème et n'a rien a voir avec les rapports de bug.
> Je le redis, d'expérience (je fais du perl/bash 80% de la journée au taf),
> la doc a (beaucoup) plus de chance d'être a jour si elle est dans le même fichier.
> C'est humain. point.
> La doc a la base c'est pas intéressant, donc si elle est ailleurs dans un autre fichier
> qu'il faut ouvrir, etc...
>

Par contre pardon pour les traduction LP et l'internationalisation ;-)

[Matthias Hawran (jahwork)]

> Par contre pardon pour les traduction LP et l'internationalisation ;-)

??
J'ai pas compris ta phrase...

[Jonathan Michalon (johndescs)]

Matthias Hawran a écrit :
>> Par contre pardon pour les traduction LP et l'internationalisation ;-)
>
> ??
> J'ai pas compris ta phrase...
>

En français : comment tu vois les traductions LP et des man en différentes
langues en collant le tout à la fin du script ? Je pense (et j'ai mis du temps à
le comprendre moi-même) que la programmation modulaire, c'est vraiment
important. En tous cas je ne mettrai pas plus à jour le bout du script qu'un
autre fichier, personnellement (et pas moins non plus).

[Matthias Hawran (jahwork)]

OK je vois.
Je ne sais pas du tout comment seront/seraient géré les traductions LP dans le man
doc séparée ou jointe.
Comment s'interface le module traduction de LP avec les fichiers.. ? aucune idée.

S'il faut des fichiers séparé alors ça se justifie.

Mais comme dit autre part, pour moi la traduction n'est pas (du tout) prioritaire.

Je crois qu'on a vraiment besoin de définir ce que l'on veut pour ces sujets:
- quel format de doc ?
- en impose t-on vraiment un ?
- si oui comment ?
- le process dans le makefile.

Ces débats (qui sont bons et nécessaires) me font pencher pour:
- chacun fait comme il veut
- le makefile devrait prendre en compte cette liberté
(if POD exist do this, if roff exist do this...)

Car c'est vrai qu'on a tous nos préférences, qu'il faut respecter.

Fidji ?

[Skippy le Grand Gourou (lecotegougdelaforce)]

Matthias Hawran a écrit :
> OK je vois.
> Je ne sais pas du tout comment seront/seraient géré les traductions LP dans le man
> doc séparée ou jointe.
> Comment s'interface le module traduction de LP avec les fichiers.. ? aucune idée.
>
> S'il faut des fichiers séparé alors ça se justifie.
>
> Mais comme dit autre part, pour moi la traduction n'est pas (du tout)
> prioritaire.

Sans doute, mais si un jour ça le devient, on s'en voudra de ne pas y avoir
réfléchi plus tôt et de devoir corriger des centaines de fichiers pour que ça
colle. À mon avis, il vaut mieux prendre nos précautions dès maintenant.

Quant au « les anglophones ont déjà plein de scripts », je ne saisis pas bien la
pertinence de l'argument. J'ai envie de dire « et alors ? » Quand j'ai posé le
script AptOff sur le forum anglais, il me semble qu'il a eu un public pas
beaucoup moins important que sur le site francophone. Mieux : il a été repris
(pas par moi) dans la doc anglaise, dans la doc chinoise (!) et sur un blog italien.

Je dis pas ça pour me la péter, ce que je veux juste dire, c'est que c'est pas
parce qu'un script est écrit par un francophone qu'il n'y a pas une demande pour
le même script ailleurs. Donc pour moi l'internationalisation est importante.

> Je crois qu'on a vraiment besoin de définir ce que l'on veut pour ces sujets:
> - quel format de doc ?
> - en impose t-on vraiment un ?
> - si oui comment ?
> - le process dans le makefile.
>
> Ces débats (qui sont bons et nécessaires) me font pencher pour:
> - chacun fait comme il veut
> - le makefile devrait prendre en compte cette liberté
> (if POD exist do this, if roff exist do this...)

Le point le plus important est que cette doc existe. Le reste… Après, encore une
fois, c'est plus simple à gérer si tout le monde utilise les mêmes conventions,
donc personnellement je penche pour un choix affiché. Lequel, peu m'importe.

--
    ~~
   |Oo| La banquise fond !!! Adoptez un pingouin...
  /|\/|\ => http://www.passeralinux.fr/
   |__| => http://www.ecrans.fr/Linux-Le-journal-d-un-novice-4,4710.html
   ^__^ => http://www.whylinuxisbetter.net/index_fr.php
~~~| |~~~ => http://doc.ubuntu-fr.org/

[Jonathan Michalon (johndescs)]

Matthias Hawran a écrit :
> OK je vois.
> Je ne sais pas du tout comment seront/seraient géré les traductions LP dans le man
> doc séparée ou jointe.
> Comment s'interface le module traduction de LP avec les fichiers.. ? aucune idée.
>
> S'il faut des fichiers séparé alors ça se justifie.
>
> Mais comme dit autre part, pour moi la traduction n'est pas (du tout)
> prioritaire.
>
> Je crois qu'on a vraiment besoin de définir ce que l'on veut pour ces sujets:
> - quel format de doc ?
> - en impose t-on vraiment un ?
> - si oui comment ?
> - le process dans le makefile.
>
> Ces débats (qui sont bons et nécessaires) me font pencher pour:
> - chacun fait comme il veut
> - le makefile devrait prendre en compte cette liberté
> (if POD exist do this, if roff exist do this...)
>
> Car c'est vrai qu'on a tous nos préférences, qu'il faut respecter.
>
> Fidji ?
>

+1 pour tout, on est enfin d'acc ! (cf mon autre mail, envoyé un peu tôt)

[Matthias Hawran (jahwork)]

> Sans doute, mais si un jour ça le devient, on s'en voudra de ne pas y avoir
> réfléchi plus tôt et de devoir corriger des centaines de fichiers pour que ça
> colle. À mon avis, il vaut mieux prendre nos précautions dès maintenant.

> Quant au « les anglophones ont déjà plein de scripts », je ne saisis pas bien la
> pertinence de l'argument. J'ai envie de dire « et alors ? » Quand j'ai posé le
> script AptOff sur le forum anglais, il me semble qu'il a eu un public pas
> beaucoup moins important que sur le site francophone. Mieux : il a été repris
> (pas par moi) dans la doc anglaise, dans la doc chinoise (!) et sur un blog italien.

> Je dis pas ça pour me la péter, ce que je veux juste dire, c'est que c'est pas
> parce qu'un script est écrit par un francophone qu'il n'y a pas une demande pour
> le même script ailleurs. Donc pour moi l'internationalisation est importante.

Oh comme il se la pète ;-P (je te charie...)

Ton expérience (sympa au passage) me pousserait alors a plutôt coder/documenter en anglais
qui est, AMHA, la langue international pour tous ce qui est code, non ?

Maintenant les "précautions" peuvent être un frein a la participation au projet.
Je dis bien "peuvent".
Oui on peut y réfléchir, mais peut être qu'il ne faut pas être trop rigide sur le sujet
et y passer trop de temps maintenant.
On peut toujours le faire dans un 2e temps et/ou en parallèle.

[Skippy le Grand Gourou (lecotegougdelaforce)]

Matthias Hawran a déclaré :
> Oh comme il se la pète ;-P (je te charie...)

Mince, je savais bien que les chaussures déformées par mes chevilles enflées, ça
se verrait… :-P

> Ton expérience (sympa au passage) me pousserait alors a plutôt coder/documenter en anglais
> qui est, AMHA, la langue international pour tous ce qui est code, non ?

Oui, mais en même tant on s'adresse avant tout à un public francophone, qui ne
maîtrise pas forcément l'anglais. Pis l'hégémonie de l'anglais n'a pas besoin de
nous pour se nourrir… ;-)

> Maintenant les "précautions" peuvent être un frein a la participation au projet.
> Je dis bien "peuvent".
> Oui on peut y réfléchir, mais peut être qu'il ne faut pas être trop rigide sur le sujet
> et y passer trop de temps maintenant.
> On peut toujours le faire dans un 2e temps et/ou en parallèle.

Ou alors, on peut se renseigner rapidement sur la façon dont fonctionne la
traduction LP, s'organiser en fonction, et laisser ensuite le libre choix de la
langue au contributeur.

J'essaie de regarder si ça prend pas trop de temps, je vous tiens au courant.

--
     ~~
    |Oo| La banquise fond !!! Adoptez un pingouin...
   /|\/|\ => http://www.passeralinux.fr/
    |__| => http://www.ecrans.fr/Linux-Le-journal-d-un-novice-4,4710.html
    ^__^ => http://www.whylinuxisbetter.net/index_fr.php
~~~| |~~~ => http://doc.ubuntu-fr.org/

[Skippy le Grand Gourou (lecotegougdelaforce)]

Skippy le Grand Gourou a déclaré :
>> Ton expérience (sympa au passage) me pousserait alors a plutôt coder/documenter en anglais
>> qui est, AMHA, la langue international pour tous ce qui est code, non ?
>
> Oui, mais en même tant on s'adresse avant tout à un public francophone, qui ne
> maîtrise pas forcément l'anglais. Pis l'hégémonie de l'anglais n'a pas besoin de
> nous pour se nourrir… ;-)
>
>
>> Maintenant les "précautions" peuvent être un frein a la participation au projet.
>> Je dis bien "peuvent".
>> Oui on peut y réfléchir, mais peut être qu'il ne faut pas être trop rigide sur le sujet
>> et y passer trop de temps maintenant.
>> On peut toujours le faire dans un 2e temps et/ou en parallèle.
>
> Ou alors, on peut se renseigner rapidement sur la façon dont fonctionne la
> traduction LP, s'organiser en fonction, et laisser ensuite le libre choix de la
> langue au contributeur.
>
> J'essaie de regarder si ça prend pas trop de temps, je vous tiens au
> courant.

Bon, j'ai regardé rapidement les liens donnés ici :
https://help.launchpad.net/Translations

À première vue, les deux points importants sont les suivants :

1/ La langue de départ, qui DOIT être l'anglais
(https://answers.launchpad.net/rosetta/+faq/394). Comme ça, au moins, c'est clair.

2/ La structure :
 > Launchpad uses GNU GetText's file formats to import and and export translations:
 > * .pot: a template that includes the English text that you want people to
translate.
 > * .po: translations for one language in a human-readable and editable form.
 > * .mo: a compiled binary form of a .po file.
(https://help.launchpad.net/Translations/YourProject)

Ensuite j'ai pas approfondi le sujet, mais j'ai l'impression que les traductions
ne concernent que ce qui est affiché (et non les commentaires), et je sais pas
trop comment.

--
     ~~
    |Oo| La banquise fond !!! Adoptez un pingouin...
   /|\/|\ => http://www.passeralinux.fr/
    |__| => http://www.ecrans.fr/Linux-Le-journal-d-un-novice-4,4710.html
    ^__^ => http://www.whylinuxisbetter.net/index_fr.php
~~~| |~~~ => http://doc.ubuntu-fr.org/

[Matthias Hawran (jahwork)]

Oui quand on parle de traduction, on parle bien des textes affichés.
Ce qui fera que l'utilisateur du programme aura les textes dans sa langue.
La FAQ est clair pour le choix de ces textes en anglais.

Maintenant le code et les commentaires, libre a chacun, hein ;-)

[Jean-Mi (jeanmi)]

Pour donner à traduire à rosetta il faut des fichiers au format .po

Skippy le Grand Gourou a écrit :
> Matthias Hawran a déclaré :
>
>> Oh comme il se la pète ;-P (je te charie...)
>>
>
> Mince, je savais bien que les chaussures déformées par mes chevilles enflées, ça
> se verrait… :-P
>
>
>
>> Ton expérience (sympa au passage) me pousserait alors a plutôt coder/documenter en anglais
>> qui est, AMHA, la langue international pour tous ce qui est code, non ?
>>
>
> Oui, mais en même tant on s'adresse avant tout à un public francophone, qui ne
> maîtrise pas forcément l'anglais. Pis l'hégémonie de l'anglais n'a pas besoin de
> nous pour se nourrir… ;-)
>
>
>
>> Maintenant les "précautions" peuvent être un frein a la participation au projet.
>> Je dis bien "peuvent".
>> Oui on peut y réfléchir, mais peut être qu'il ne faut pas être trop rigide sur le sujet
>> et y passer trop de temps maintenant.
>> On peut toujours le faire dans un 2e temps et/ou en parallèle.
>>
>
> Ou alors, on peut se renseigner rapidement sur la façon dont fonctionne la
> traduction LP, s'organiser en fonction, et laisser ensuite le libre choix de la
> langue au contributeur.
>
> J'essaie de regarder si ça prend pas trop de temps, je vous tiens au
> courant.
>
>
>
>