Re: [Maitretarot-devel-fr] Documentation

[Yves Mettier]

>> Dans l'etat actuel des choses, je pense qu'il est preferable que ce soit
>> cardgame_server
>> la reference car cela fait moins de boulot. Les structures ont juste a etre
>> implementees, meme si le code de traitement des donnees n'y est pas. 
>> Ensuite, si le
>> besoin s'en fait sentir, on fera un fork de la doc genereee par 
>> cardgame_server et on
>> la
>> maintiendra a jour a la main.
>>
> Personnelement, je prefere un document central mis dans le repertoire 
> documentation
> du CVS et maintenu a jour independament d'une implementation parce que ca 
> permet de
> faire en sorte que n'importe quel client discute avec n'importe quelle 
> implementation
> du serveur => la doc est un fichier sur lequel tout le monde se met d'accord.
>
> Ce qui me gene en particulier, c'est quand tu ecris dans guide.sgml :
>
> "Les actions et ordres sont définis dans la documentation sgml générée 
> automatiquement
> par:
>         cardgame_server --print-protocol
> Cette documentation est, si les programmeurs font bien leur travail, par 
> définition
> toujours à jour."
>                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> je fais bien mon travail dans cl_game_server (cl_game_server genere 
> automatiquement
> la doc) et bien on se retrouve avec un beau bordel parce que le protocole que 
> va generer
> cl_game_server ne sera pas le meme que celui genere par cardgame_server.

OK, je ne savais pas que cl_game_server generait aussi la doc :)
Du coup, dans ce que tu dis plus bas, ca correspond a ce que je dis en parlant 
de fork
de la doc, sauf que je suis en retard: t'as une etape d'avance.

> Donc, on dit que cardgame_server est la reference => je fais en sorte que 
> cl_game_server
> utilise le meme protocole que cardgame_server (pourquoi pas) et ce n'est pas 
> a lui
> de generer la doc (ce qu'il ne fait de toute facon pas pour l'instant).

Non, cardgame_server et cl_game_server generent une doc correspondant a leur 
etat
d'implementation du protocole. Cela est et sera: je doute qu'on puisse 
critiquer ce
fait.
Par contre, la ou je suis en retard: je croyais que seul cardgame_server etait 
capable
de generer sa doc, doc qui du coup pouvait servir de reference.

Etant donne que nous avons deux implementations du protocole, il faut 
effectivement
faire ce fork: generer la doc la plus complete et la plus adaptee a ce que l'on 
veut, a
l'aide de cl_game_server ou de cardgame_server, et appeler ce fichier 
protocole.sgml
(pas guide.sgml).
Puis tant qu'on y est, ce qui fait office de documentation technique du 
protocole dans
guide.sgml, le passer de guide.sgml a protocole.sgml avec ce qui y est deja.

> Mais, la je trouve qu'il y a un probleme : comment faire si je veux coder un 
> autre
> jeu independament de cardgame_server (par exemple le tarot a 5 ou la belotte) 
> ?
> Il faut que j'attende que ce soit implemente dans cardgame_server pour avoir 
> la
> doc qui me dis comment coder le protocole ?

Non, et tu l'as deja fait: cl_game_server.
cardgame_server etait, dans mon idee, la reference, en l'absence d'autre 
documentation.
Maintenant qu'il y a deja cl_game_server, cardgame_server ne peut plus etre la
reference. il peut, au mieux, generer une doc correspondant a son 
implementation du
protocole.

>
> Je prefere que celui qui veux coder un jeu de bellote developpe son propre 
> serveur,
> ecrive la doc du protocole qui lui a permis de jouer et en discute avec tout 
> le
> monde jusqu'a ce que le protocole soit accepte.
> Ensuite libre a cardgame_server d'implemente le jeu de belotte ou a n'importe 
> qui
> d'autre qui veut juste coder un serveur de bellote.
>
> Et pour ca, il faut que la doc soit independante de toute implementation du 
> serveur!

On est sur la meme longueur d'onde. Faut juste le faire.

>
>> >
>> > Surtout que le protocole dans guide.sgml a fait un sacré bon en arriere:
>> > - utilisation de virgules pour separer les champs d'une commande, alors 
>> > qu'un
>> > espace est largement suffisent
>> > - Les commandes ne sont pas de la forme INFO_order comme indique au debut 
>> > de la doc.
>> > - manque INFO_king_in_chien...
>>
>> En fait, la, c'est moi qui ai laisse le texte tel quel. Je n'ai pas regarde 
>> si c'etait
>> a
>> jour. Et je suis presque persuade que c'est pas a jour du tout !!!
>>
> Oui, et c'est ca qui me fais peur :
> chaque fois que le code de cardgame_server va changer, la doc va changer 
> aussi.

Tant que cardgame_server etait la seule implementation du serveur, et donc du 
protocole,
c'etait une bonne chose car ca nous permettait d'avoir toujours une doc a jour 
tout en
testant des nouveaux elements de protocole. Maintenant qu'il y a plusieurs
implementation du protocole, il faut mettre la doc sur papier de maniere 
independante
des implementations.

> => impossible a suivre pour les clients.

Mauvais argument: a chaque changement de protocole, meme si c'est sur le papier 
et pas
dans une doc auto-generee, on change le serveur, quel qu'il soit. Le resultat 
est le
meme: il faut changer le client aussi.
Argument rejete, votre honneur :)

> Alors qu'avec une doc commune (fichier central) la doc ne depend plus de 
> cardgame_server
> ou d'une quelconque implementation.

Tout a fait.

> => on peut coder les clients avant meme que le code (et surtout la doc) soit 
> ecrit dans
> cardgame_server.

A nouveau, non. Quand tu as l'idee de faire un changement dans le protocole, 
qu'il soit
centralise dans une doc commune ou qu'il soit dans un serveur de reference, il 
est
preferable de changer le serveur avant le client pour pouvoir tester le client 
apres. Et
si tu preferes changer les clients avant, rien ne t'en empeche, puisque tu as 
l'idee: ce
n'est pas la doc qui va t'en empecher. Mais tant que le serveur ne sera pas 
modifie, le
client ne pourra pas fonctionner correctement.

>
>> > Enfin, bon ce serait une bonne idee de remettre protocole.sgml sur le CVS
>> > ou alors d'integrer un protocole a jour dans guide.sgml.
>>
>> Moi, je n'y suis pas favorable pour les raisons qui precedent. J'etais meme 
>> a deux
>> doigts de prendre la partie protocole qui se trouve dans guide.sgml et de la 
>> coder
>> dans
>> cardgame_server pour que cardgame_server soit capable de generer la totalite 
>> du
>> document
>> de reference.
>>
> Mouai, la je trouve que ca verrouille trop le developement de maitretarot.

Pareil, c'est pour ca que je ne l'ai pas fait :)))
Qu'un logiciel genere la doc, oui, pourquoi pas, tant que tout le monde peut y 
avoir
acces. Que ce logiciel soit une implementation du serveur, non: ca devient un 
monopole
de l'implementation, et ca, c'est pas bon.

> Perso, je suis pres a coder le jeu de tarot a 3 et 5 et le jeu de belotte,
> j'aimerai coder aussi le jeu de Nyout.
> Il faut que j'attende que tu es coder tout ca dans cardgame_server pour avoir
> la doc du protocole ?

Ah, non, sans revenir a tout ce qui s'est dit plus haut et ce sur quoi on est 
d'accord
(j'espere) maintenant, non, y'a pas a revenir.
Dans cardgame_server, il y a des tableaux contenant ce qu'il faut pour generer 
la doc.
Il est tout a fait possible de modifier ces tableaux sans pour autant modifier 
le
fonctionnement du serveur. Tant que l'utilisation de ces tableaux n'est pas 
faite, rien
ne change. Et niveau doc, y'a juste a rajouter des lignes a ces tableaux.

Cela revient donc a ce que je dis juste au dessus: on peut tout a fait avoir un 
logiciel
qui genere la doc. Sauf que si ce logiciel est le serveur, c'est pas bon.
Par contre, pour enfoncer le clou, tant que cardgame_server etait le seul a 
generer
cette doc, on pouvait tout a fait le considerer comme doc de reference. Ce 
n'est plus le
cas maintenant.

>
> Je prefere faire une doc qui indique quel est le protocole a suivre pour
> jouer au differents jeux (le plus simple : un fichier texte au debut).
> Et ensuite, libre au serveur de l'implementer ou pas. Mais dans tout les cas,
> les clients et le serveur qui respecte la doc commune pourront toujours
> dialoguer ensemble.

Oui, tout a fait. Sauf pour le format du fichier que je prefere en format 
docbook (sgml
ou xml) car cela evite de tout refaire ensuite en docbook pour generer du txt, 
html, ps
ou pdf.

> PS: pour Nico : j'ai fini le lanceur :
>
>         http://hocwp.free.fr/maitretarot/screenshot/img_starter1.png
>         http://hocwp.free.fr/maitretarot/screenshot/img_starter2.png

\o/

> PS2: j'ai mis a jour le CVS pour lib_mt_client => mt_dolphin_ia se connecte.

\o/

Yves
-- 
- Homepage    - http://ymettier.free.fr - http://www.logicacmg.com -
- GPG key     - http://ymettier.free.fr/gpg.txt                    -
- Maitretarot - http://www.nongnu.org/maitretarot/                 -
- GTKtalog    - http://www.nongnu.org/gtktalog/                    -