Re: [Maitretarot-devel-fr] Documentation

[Philippe Brochard]

"Yves Mettier" <address@hidden> writes:

> >> 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 :)
>
Non, il ne genere pas la doc. Et je ne pense pas qu'il le fasse un jour :
c'est pas son boulot.

Par contre la doc que j'avais mis sur le CVS, elle etait a jour (avec ce qui
est utilise dans cl_game_server). Et je pense qu'elle n'a plus de raison de
bouger : tout fonctionne impec avec les nouveaux client/ia.

C'est pour ca que je me suis remis a libmt_client : le protocole est robuste
=> on peut l'implementer. 

> 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.
> 
Yep, ca correspond :)

> > 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.
> 
oui, vu sous ce plan je suis tout a fait d'accord :)

mais le seul probleme c'est que la doc de cardgame_server ne peut
plus servir de reference d'ou le protocole.sgml.

> 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.
> 
\o/ tout a fait d'accord !

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

> >
> > 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.
> 
y a deja le protocole.sgml que j'avais mis dans documentation
(le chapitre 3 est a jour).

> >
> >> >
> >> > 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.
> 
Oui, tout a fait d'accord :)

> > => 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 :)
> 
argument accepte : c'est ce qui s'est passe quand on a change de
protocole sur le papier.

> > 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.
> 
ouais, reaccepte :)

> >
> >> > 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 :)))
>
ouf :))

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

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

> 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.
> 
ah, ok, je n'ai pas ete voir comment etait genere la doc.
Comment ca ce passe si on veux documente un nouveau jeu ?
Ce serai bien que ce soit facile d'acces dans un logiciel a
par.

> 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.
> 
Oui, tout a fait! pour l'instant ca me semble plus simple de
maintenir la doc sous format text puis sgml (meme si ca devient
lourd a gerer) et si on avait un logiciel qui permet de genere
automatiquement la doc, je serais preneur (a condition qu'il soit
indpendant du serveur) :)

> >
> > 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.
> 
oui, je trouve aussi que docbook est pratique pour ca.



Bon, ben on est d'accord :)


Philippe

-- 
Philippe Brochard    <address@hidden>
                      http://hocwp.free.fr

-=-= http://www.gnu.org/home.fr.html =-=-