asciidoc vs. docutils

Le
Alain BARTHE
Je suis en train de créer des sites WEB, sous Linux et Solaris 10,
contenant une grosse partie de documentation.

Je voulais saisir mes contenus de pages en utilisant le format
reStructuredText, puis générer l'HTML avec rst2html.py, puis ajouter un
peu de PHP et javascript pour améliorer l'affichage (menus, navigation,
recherche)

J'ai déjà fait des essais assez concluants avec docutils, mais je trouve
le format Asciidoc plus riche par défaut, au niveau de sa syntaxe.

Je vais bientôt devoir passer en exploitation, et j'hésite entre les
deux formats. Il faut que je fasse mon choix rapidement, et un retour en
arrière sera de plus en plus pénalisant, puisque les deux formats texte
ne sont pas compatibles.

J'aurais aimé avoir vos avis sur les deux formats (maitenance,
évolutions, richesse, facilité d'ajouter des extensions, .).

De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.

Merci d'avance.
Vidéos High-Tech et Jeu Vidéo
Téléchargements
Vos réponses
Gagnez chaque mois un abonnement Premium avec GNT : Inscrivez-vous !
Trier par : date / pertinence
PIGUET Bruno
Le #20691271
Le Fri, 04 Dec 2009 10:24:44 +0100, Alain BARTHE a écrit :

Je suis en train de créer des sites WEB, sous Linux et Solaris 10,
contenant une grosse partie de documentation.

Je voulais saisir mes contenus de pages en utilisant le format
reStructuredText, puis générer l'HTML avec rst2html.py, puis ajouter un
peu de PHP et javascript pour améliorer l'affichage (menus, navigation,
recherche...)




De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.



<mode bavardage on>
Les dernières version de la doc python sont faites en ReST, traité par
Sphinx (http://sphinx.pocoo.org/).
Je n'ai pas pratiqué, mais u as déjà du pouvoir juger sur pièces :
http://docs.python.org/index.html
<mode bavardage off>

Bruno.
Bruno Desthuilliers
Le #20691261
Alain BARTHE a écrit :

(snip - guère d'avis sur la question)

De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.



Markup, Textile....

J'aime bien Textile en ce qui me concerne.
Alain BARTHE
Le #20691511
Bruno Desthuilliers a écrit :
Alain BARTHE a écrit :

(snip - guère d'avis sur la question)

De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.



Markup, Textile....

J'aime bien Textile en ce qui me concerne.



Je viens de jeter un coup d'oeil a MarkDown, qui a l'air pas mal non plus.

Un des avantages de asciidoc et docutils est de pouvoir passer dans
d'autres formats que html, et notamment xml docbook, ce qui permettre,
même si ce n'est surement pas si simple de faire une éventuelle
traduction asciidoc <=> docutils le jour où on décide de changer.

Je ne sais pas si les autres outils (Markdown, Textile, ...) ont une
chaine de traitement aussi développée.

Le problème comme souvent c'est qu'il y a trop de solutions possibles et
qu'il est difficile de choisir la "meilleure" sans les avoir essayées
toutes.

Merci pour ton avis.
Alain BARTHE
Le #20691591
PIGUET Bruno a écrit :
Le Fri, 04 Dec 2009 10:24:44 +0100, Alain BARTHE a écrit :

Je suis en train de créer des sites WEB, sous Linux et Solaris 10,
contenant une grosse partie de documentation.

Je voulais saisir mes contenus de pages en utilisant le format
reStructuredText, puis générer l'HTML avec rst2html.py, puis ajouter un
peu de PHP et javascript pour améliorer l'affichage (menus, navigation,
recherche...)



De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.



<mode bavardage on>
Les dernières version de la doc python sont faites en ReST, traité par
Sphinx (http://sphinx.pocoo.org/).
Je n'ai pas pratiqué, mais u as déjà du pouvoir juger sur pièces :
http://docs.python.org/index.html
<mode bavardage off>

Bruno.



J'avais effectivement regardé de ce coté et Sphinx a l'air parfait pour
gérer les docs.

Le problème c'est que je dois ensuite rajouter des applis (PHP, MySql,
appel traitements scientifiques Fortan/IDL) et j'ai peur qu'elles soient
difficiles à intégrer avec Sphinx, sauf à désolidariser les deux parties.

Je préfère me créer une appli complète, en intégrant juste des facilités
pour générer mes pages et en gérant moi-même ma navigation, mes index,
etc... pour pouvoir y intégrer ensuite mes applis.

C'est un sujet polémique (réinventer la roue, etc...) mais ce n'est pas
le sujet de ma question.

Merci pour ton aide.
Bruno Desthuilliers
Le #20692671
Alain BARTHE a écrit :
Bruno Desthuilliers a écrit :
Alain BARTHE a écrit :

(snip - guère d'avis sur la question)

De même si vous connaissez un autre format (syntaxe wiki par exemple)
qui puisse faire l'affaire.



Markup, Textile....

J'aime bien Textile en ce qui me concerne.



Je viens de jeter un coup d'oeil a MarkDown,



J'ai écrit Markup ? Bon, c'est vendredi, hein - je voulais bien sûr dire
Markdown !-)

Un des avantages de asciidoc et docutils est de pouvoir passer dans
d'autres formats que html, et notamment xml docbook, ce qui permettre,
même si ce n'est surement pas si simple de faire une éventuelle
traduction asciidoc <=> docutils le jour où on décide de changer.

Je ne sais pas si les autres outils (Markdown, Textile, ...) ont une
chaine de traitement aussi développée.



Je ne pense pas, non. Ce sont avant tout des outils destinés à générer
du html.

Le problème comme souvent c'est qu'il y a trop de solutions possibles et
qu'il est difficile de choisir la "meilleure" sans les avoir essayées
toutes.



Disons qu'il y a deux aspects ici: les fonctionnalités (formats
possibles etc), et le confort d'utilisation pour le rédacteur - et
clairement, le second aspect nécessite un peu d'expérience directe.


Merci pour ton avis.



De rien.
Publicité
Poster une réponse
Anonyme