Bonjour tout le monde 
Bonne année à tous (pour ceux qui ne sont pas sur PHPFrance
).
Bien commençons.
Je suis en train (du moins, j'aimerais bien commencer) de rédiger la documentation de mon projet. J'ai besoin que la documentation soit exportable dans différents formats, comme HTML, Tex, PDF, DVI, PS, Unix Man, Eclipse doc et CHM (oui il faut penser à Eclipse et Windows ...). La seule solution est de partir d'XML. Heureusement, le groupe OASIS a déjà tout prévu en pondant ce qu'on appelle DocBook. OASIS a écrit des DTD précises qui permettent à travers un ensemble de feuilles XSLT d'exporter vers tous ces formats.
Bien, ça c'est pour la partie historique.
Tout fonctionne (presque) bien, à l'exception que le code HTML est dégueulasse. On peut exporter vers XHTML, c'est déjà mieux. En bidouillant dans les sources, on peut tenter d'activer le chunk-mode, c'est à dire qu'il y ai des sauts de lignes de temps à autre, ça aide pour la clarté quand même (par défaut, se mode est désactivé). On arrive à quelque chose de presque potable. Mais là encore, le code est sémantiquement pas bien beau. On préfère utiliser <p><b>Table des matières</b></p> plutôt que <h2>, ou des choses du genre. J'aimerais également utiliser em et strong à la place de i et b, et également enlever toutes les balises u etc. Enfin bon, il faut refaire toutes les feuilles XSLT, car le résultat est sémantiquement incorrect. Le choix des balises n'est jamais judicieux par exemple. Je peux tolérer que ce ne soit pas équivalent à si ça avait été fait à la main, c'est normal et on comprend, mais quand même.
Là est ma question. Y a-t-il des feuilles XSLT qui ont été faites pour respecter notre bon vieux XHTML de manière plus propre et plus judicieuse ? La dernière version de DocBook XSL Stylesheet est la 1.73.2, elle date du 30 aout 2007.
J'espérais qu'un groupe de fous de la sémantique aurait fait ça, ou je ne sais quoi d'autres. Je n'ai pas la motivation, ni le courage de réécrire toutes les feuilles. Déjà, parce que c'est très complexe, que c'est un travail de titan, et qu'il va falloir le maintenir par la suite (si on arrive à le finir).
Ou sinon, connaissez-vous autre chose pour écrire des documentations exportables ? J'étais parti sur DocBook car c'est le système qu'a choisit PHP pour écrire son manuel, ce qui me semblait une bonne idée.
Modifié par HyWaN (08 Jan 2008 - 16:48)
Bonne année à tous (pour ceux qui ne sont pas sur PHPFrance
).Bien commençons.
Je suis en train (du moins, j'aimerais bien commencer) de rédiger la documentation de mon projet. J'ai besoin que la documentation soit exportable dans différents formats, comme HTML, Tex, PDF, DVI, PS, Unix Man, Eclipse doc et CHM (oui il faut penser à Eclipse et Windows ...). La seule solution est de partir d'XML. Heureusement, le groupe OASIS a déjà tout prévu en pondant ce qu'on appelle DocBook. OASIS a écrit des DTD précises qui permettent à travers un ensemble de feuilles XSLT d'exporter vers tous ces formats.
Bien, ça c'est pour la partie historique.
Tout fonctionne (presque) bien, à l'exception que le code HTML est dégueulasse. On peut exporter vers XHTML, c'est déjà mieux. En bidouillant dans les sources, on peut tenter d'activer le chunk-mode, c'est à dire qu'il y ai des sauts de lignes de temps à autre, ça aide pour la clarté quand même (par défaut, se mode est désactivé). On arrive à quelque chose de presque potable. Mais là encore, le code est sémantiquement pas bien beau. On préfère utiliser <p><b>Table des matières</b></p> plutôt que <h2>, ou des choses du genre. J'aimerais également utiliser em et strong à la place de i et b, et également enlever toutes les balises u etc. Enfin bon, il faut refaire toutes les feuilles XSLT, car le résultat est sémantiquement incorrect. Le choix des balises n'est jamais judicieux par exemple. Je peux tolérer que ce ne soit pas équivalent à si ça avait été fait à la main, c'est normal et on comprend, mais quand même.
Là est ma question. Y a-t-il des feuilles XSLT qui ont été faites pour respecter notre bon vieux XHTML de manière plus propre et plus judicieuse ? La dernière version de DocBook XSL Stylesheet est la 1.73.2, elle date du 30 aout 2007.
J'espérais qu'un groupe de fous de la sémantique aurait fait ça, ou je ne sais quoi d'autres. Je n'ai pas la motivation, ni le courage de réécrire toutes les feuilles. Déjà, parce que c'est très complexe, que c'est un travail de titan, et qu'il va falloir le maintenir par la suite (si on arrive à le finir).
Ou sinon, connaissez-vous autre chose pour écrire des documentations exportables ? J'étais parti sur DocBook car c'est le système qu'a choisit PHP pour écrire son manuel, ce qui me semblait une bonne idée.
Modifié par HyWaN (08 Jan 2008 - 16:48)