Re: [Maitretarot-devel-fr] Documentation

[Philippe Brochard]

"Yves Mettier" <address@hidden> writes:

> Coucou !
> 
> J'ai un peu retouche la documentation de maitretarot, celle se trouvant dans 
> le module
> "documentation" nouvellement cree par Philippe.
> 
> - ajout de guide.sgml qui reprend toute la documentation a jour
>
Oui c'est une bonne idee de tout centraliser dans un seul fichier.

> - suppression de protocol.sgml qui prete a confusion avec le code sgml genere 
> par
> "cardgame_server --print-protocol".
> - suppression de tous les fichiers texte sauf le fichier readme.
> 
Bonne idee aussi, c'est fichiers etaient en trop et la version sgml
est mieux presentee.


Par contre, je trouve l'idee de virer protocol.sgml assez mauvaise.
Je pense qu'il nous faut un document de reference qui ne depende pas
d'une implementation particuliere (ici "cardgame_server --print-protocol"),
mais qui soit au contraire facile d'acces.

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


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.



> C'est la documentation de reference qui devrait nous servir pour noter tout 
> ce qu'on peut.
> En toute logique, l'evolution de ce document devrait etre d'etre par la suite 
> decoupe en
> au moins trois fichiers sgml: faq.sgml, reference.sgml et guide.sgml. En 
> attendant, il
> est preferable d'avoir des chapitres distincts.
> 
Ce decoupage me semble coherent.

> Comme explique dans le fichier readme, la generation de la doc dans un format 
> lisible se
> fait avec docbook2html, docbook2pdf, docbook2ps et autres commandes du meme 
> style.
> 
Oui, il faut laisser cette info accessible pour que tout le monde puisse
construire la doc au format qu'il veut.


Philippe

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

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