Re: [sdx-developers] RE : Systeme de documentation

[Pierrick Brihaye]

Salut,

Martin Sévigny wrote:

> Website-full utilise tout Docbook. Website-custom est basé sur
> Simplified Docbook. Website.dtd est une version "automatique" obtenue
> par l'une ou l'autre des "customization" de Docbook.


Ca commence mal : l'url fournie 
(http://www.oasis-open.org/docbook/xml/simple/1.0b2/sdocbook-custom.dtd) 
pour la sdocbook ne répond pas :-(


> Pas que l'on veut, tout de même. Comme toute DTD normalisée, il y a du
> générique et du flou, mais tout a une définition...


J'ai le manuel (il en existe même une version française sous le tire 
"docbook, la référence". Cher... :-). Je suis néanmoins *très* surpris 
par le manque d'exemples *réels* sur le WWW. C'est en ce sens que 
j'aurais voulu comparer pplusieurs expériences pour voir les tendances 
générales...

Suivant le suggestion de Patrice, j'ai également regardé *le* site de 
Norman Walsh. Cela ne fait que confirmer ma crainte, à savoir que des 
projets docbook *coopératifs*, il n'y en a pas beaucoup sur le WWW :-)

> J'opterais pour la simplifier, on commence les documents par "article"?

J'avais commencé (avec la "website") par
webpage
  head
  section

à l'instar de ce que j'avais vu dans la doc website... Je recommence 
comment ?

> Sgmltag est un inline, les autres sont des blocs (de méméoire). Un bout
> de fichier XML sur plusieurs lignes devrait être du programlisting selon
> moi. Le literal est plus générique.


On est d'accord. A la bonne heure :-)


> > 4ème point : quel format pour les ID utilisées dans les fichiers ?
>
> Ils doivent être uniques dans une collection. J'aurais tendance à donner
> des identifiants alphanumériques significatifs en minuscules. Du genre
> tech_intro, peu importe. 


Ca devrait aller. On préfixe tout de même : version de sdx (si 
nécessaire) ? langue ? id = nom de fichier ?

> Je pense que oui. L'idée de faire sdx_v1 et sdx_v2 (pour répondre à
> Patrice) est issue du fait que SDX 2 sera une réécriture de SDX 1, pas
> une mise à jour.


Ca se défend.


Le mieux, c'est encore d'avoir un document test sur lequel s'appuyer... 

il semblerait que j'aie eu tort de rpendre ceux de website :-)


A+

--
Pierrick Brihaye, informaticien
Service régional de l'Inventaire
DRAC Bretagne
mailto:address@hidden