Petite question facile : Quel outil utilisez-vous / conseillez-vous pour
générer de la documentation à la facon de la javadoc ? . J'entends par là
qu'une série de commentaire (@parm, @return, ...) rajoutée au header
permet à un parser de générer une doc html plus lisible.
J'ai deja genere du HTML a partir de LaTeX (voir par exemple http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de le regarder source mais j'utilise cela pour des documents que je concois comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>, mais il semble mort :-(
Falk
Jean-Marc Bourguet wrote:
J'ai deja genere du HTML a partir de LaTeX (voir par exemple
http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu
avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de
le regarder source mais j'utilise cela pour des documents que je concois
comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>,
mais il semble mort :-(
J'ai deja genere du HTML a partir de LaTeX (voir par exemple http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de le regarder source mais j'utilise cela pour des documents que je concois comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>, mais il semble mort :-(
Falk
Jean-Marc Bourguet
Falk Tannhäuser writes:
Jean-Marc Bourguet wrote: > J'ai deja genere du HTML a partir de LaTeX (voir par exemple > http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu > avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de > le regarder source mais j'utilise cela pour des documents que je concois > comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>, mais il semble mort :-(
Si j'ai bonne memoire, il fonctionnait suivant un autre principe que TeX4ht. Ce dernier interprete le dvi (et donc n'a a priori pas de problemes avec les macros TeX, mais utilise des specials ou qqch du genre pour marquer ce qu'il doit traiter specialement), latex2html avait une connaissance de LaTeX, mais avait des problemes des qu'on utilisait une macro dont il n'avait pas connaissance.
Il y a bien sur aussi la methode inverse, utiliser un autre markup et generer du html ou du LaTeX a partir de ca.
A+
-- Jean-Marc FAQ de fclc++: http://www.cmla.ens-cachan.fr/~dosreis/C++/FAQ C++ FAQ Lite en VF: http://www.ifrance.com/jlecomte/c++/c++-faq-lite/index.html Site de usenet-fr: http://www.usenet-fr.news.eu.org
Jean-Marc Bourguet wrote:
> J'ai deja genere du HTML a partir de LaTeX (voir par exemple
> http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu
> avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de
> le regarder source mais j'utilise cela pour des documents que je concois
> comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>,
mais il semble mort :-(
Si j'ai bonne memoire, il fonctionnait suivant un autre principe que
TeX4ht. Ce dernier interprete le dvi (et donc n'a a priori pas de
problemes avec les macros TeX, mais utilise des specials ou qqch du genre
pour marquer ce qu'il doit traiter specialement), latex2html avait une
connaissance de LaTeX, mais avait des problemes des qu'on utilisait une
macro dont il n'avait pas connaissance.
Il y a bien sur aussi la methode inverse, utiliser un autre markup et
generer du html ou du LaTeX a partir de ca.
A+
--
Jean-Marc
FAQ de fclc++: http://www.cmla.ens-cachan.fr/~dosreis/C++/FAQ
C++ FAQ Lite en VF: http://www.ifrance.com/jlecomte/c++/c++-faq-lite/index.html
Site de usenet-fr: http://www.usenet-fr.news.eu.org
Jean-Marc Bourguet wrote: > J'ai deja genere du HTML a partir de LaTeX (voir par exemple > http://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu > avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de > le regarder source mais j'utilise cela pour des documents que je concois > comme a imprimer).
Dans le temps il y avait aussi LaTeX2HTML <http://www.latex2html.org/>, mais il semble mort :-(
Si j'ai bonne memoire, il fonctionnait suivant un autre principe que TeX4ht. Ce dernier interprete le dvi (et donc n'a a priori pas de problemes avec les macros TeX, mais utilise des specials ou qqch du genre pour marquer ce qu'il doit traiter specialement), latex2html avait une connaissance de LaTeX, mais avait des problemes des qu'on utilisait une macro dont il n'avait pas connaissance.
Il y a bien sur aussi la methode inverse, utiliser un autre markup et generer du html ou du LaTeX a partir de ca.
A+
-- Jean-Marc FAQ de fclc++: http://www.cmla.ens-cachan.fr/~dosreis/C++/FAQ C++ FAQ Lite en VF: http://www.ifrance.com/jlecomte/c++/c++-faq-lite/index.html Site de usenet-fr: http://www.usenet-fr.news.eu.org
James Kanze
On Nov 2, 9:35 am, Jean-Marc Bourguet wrote:
James Kanze writes: > On Nov 1, 8:34 am, qdii wrote: > > >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
[...]
> En fait, où j'aurais des doutes (peut-être), c'est « Produce > state-of-the-art documentation ». State-of-the-art > documentation, c'est du HTML, non du LaTeX. (En revanche, si > le but est lisibilité et compréhensibilité, plutôt que > d'être state-of-the-art à tout prix, LaTeX n'est pas > forcément un mauvais choix pour l'ensemble.)
J'ai deja genere du HTML a partir de LaTeX (voir par exemplehttp://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de le regarder source mais j'utilise cela pour des documents que je concois comme a imprimer).
En effet. D'après mes expériences (très limitées), ça peut servir pour donner une prévue sur le Web d'un document imprimé, mais l'orientation reste imprimé. Actuellement, ou bien j'utilise plutôt pdflatex, pour générer du PDF, et je laisse tomber l'HTML, ou bien, j'écris directement en HTML.
Je suis quasiment certain que CWEB ne genere pas du LaTeX, ce doit etre du plain TeX si ce n'est pas un format expres fait par DEK.
Peut-être bien. Je n'ai jamais eu l'occasion de l'utiliser réelement.
Il doit aussi etre possible de generer du HTML, mais je ne sais pas au prix de quel effort d'adaptation de TeX4ht
Au fond, on doit pouvoir développer quelque chose de semblable directement en HTML ou XML, a peu d'efforts si on dispose déjà d'un parseur XML. Mais éditer l'XML ou le HTML directement dans un éditeur, c'est encore plus pénible que d'éditer le LaTeX.
Sur le fond, j'ai deja experimente avec quelques variantes d'outils de programmation litteraire et genere du HTML avec certains d'entre eux. Ca me semble bien dans un objectif de publication d'algorithme ou de cours de programmation, mais pas particulierement pour un gros programme destine a la production. Je prefere doxygen pour cela. Si j'ai bonne memoire, ma preference allais a noweb.
Le problème de base, quelque soit le système (y compris Doxygen), c'est que tu es obligé de t'occuper du balisage au même temps que tu saisis le texte, et que le balisage apparaît (et distrait) dans les fichiers source. Et que quand tu fais de la maintenance, c'est en fin de compte les fichiers source que tu as devant les yeux. Pour la saisie initiale, j'ai d'assez bonne expérience avec vim en mode texte, avec un programme filtre qui convertit en commentaires Doxygen par la suite. (C'est le programme « comment » sur ma site. Sous vim, je me mets dans une mode texte, sans indentation automatique, pour saisir le texte, puis je le passe par « comment », et je me mets en mode C++ pour saisir le code. Mais c'est une solution d'assez bas niveau ; ça marche bien plur les bibliothèques qui sont pratiquement une collection des classes plus ou moins indépendantes, mais ça ne suffit pas du tout pour l'application, où il faut documenter les relations entre les classes.)
-- James Kanze
On Nov 2, 9:35 am, Jean-Marc Bourguet <j...@bourguet.org> wrote:
James Kanze <james.ka...@gmail.com> writes:
> On Nov 1, 8:34 am, qdii <q...@reblochon.be> wrote:
> > >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
[...]
> En fait, où j'aurais des doutes (peut-être), c'est « Produce
> state-of-the-art documentation ». State-of-the-art
> documentation, c'est du HTML, non du LaTeX. (En revanche, si
> le but est lisibilité et compréhensibilité, plutôt que
> d'être state-of-the-art à tout prix, LaTeX n'est pas
> forcément un mauvais choix pour l'ensemble.)
J'ai deja genere du HTML a partir de LaTeX (voir par
exemplehttp://www.bourguet.org/v2/cs/charset/, il y a un lien
vers un PDF obtenu avec la meme source -- comme beaucoup de
HTML genere, on n'a pas envie de le regarder source mais
j'utilise cela pour des documents que je concois comme a
imprimer).
En effet. D'après mes expériences (très limitées), ça peut
servir pour donner une prévue sur le Web d'un document imprimé,
mais l'orientation reste imprimé. Actuellement, ou bien
j'utilise plutôt pdflatex, pour générer du PDF, et je laisse
tomber l'HTML, ou bien, j'écris directement en HTML.
Je suis quasiment certain que CWEB ne genere pas du LaTeX, ce
doit etre du plain TeX si ce n'est pas un format expres fait
par DEK.
Peut-être bien. Je n'ai jamais eu l'occasion de l'utiliser
réelement.
Il doit aussi etre possible de generer du HTML, mais je ne
sais pas au prix de quel effort d'adaptation de TeX4ht
Au fond, on doit pouvoir développer quelque chose de semblable
directement en HTML ou XML, a peu d'efforts si on dispose déjà
d'un parseur XML. Mais éditer l'XML ou le HTML directement dans
un éditeur, c'est encore plus pénible que d'éditer le LaTeX.
Sur le fond, j'ai deja experimente avec quelques variantes
d'outils de programmation litteraire et genere du HTML avec
certains d'entre eux. Ca me semble bien dans un objectif de
publication d'algorithme ou de cours de programmation, mais
pas particulierement pour un gros programme destine a la
production. Je prefere doxygen pour cela. Si j'ai bonne
memoire, ma preference allais a noweb.
Le problème de base, quelque soit le système (y compris
Doxygen), c'est que tu es obligé de t'occuper du balisage au
même temps que tu saisis le texte, et que le balisage apparaît
(et distrait) dans les fichiers source. Et que quand tu fais de
la maintenance, c'est en fin de compte les fichiers source que
tu as devant les yeux. Pour la saisie initiale, j'ai d'assez
bonne expérience avec vim en mode texte, avec un programme
filtre qui convertit en commentaires Doxygen par la suite.
(C'est le programme « comment » sur ma site. Sous vim, je me
mets dans une mode texte, sans indentation automatique, pour
saisir le texte, puis je le passe par « comment », et je me mets
en mode C++ pour saisir le code. Mais c'est une solution d'assez
bas niveau ; ça marche bien plur les bibliothèques qui sont
pratiquement une collection des classes plus ou moins
indépendantes, mais ça ne suffit pas du tout pour l'application,
où il faut documenter les relations entre les classes.)
James Kanze writes: > On Nov 1, 8:34 am, qdii wrote: > > >http://www-cs-faculty.stanford.edu/~knuth/cweb.html
[...]
> En fait, où j'aurais des doutes (peut-être), c'est « Produce > state-of-the-art documentation ». State-of-the-art > documentation, c'est du HTML, non du LaTeX. (En revanche, si > le but est lisibilité et compréhensibilité, plutôt que > d'être state-of-the-art à tout prix, LaTeX n'est pas > forcément un mauvais choix pour l'ensemble.)
J'ai deja genere du HTML a partir de LaTeX (voir par exemplehttp://www.bourguet.org/v2/cs/charset/, il y a un lien vers un PDF obtenu avec la meme source -- comme beaucoup de HTML genere, on n'a pas envie de le regarder source mais j'utilise cela pour des documents que je concois comme a imprimer).
En effet. D'après mes expériences (très limitées), ça peut servir pour donner une prévue sur le Web d'un document imprimé, mais l'orientation reste imprimé. Actuellement, ou bien j'utilise plutôt pdflatex, pour générer du PDF, et je laisse tomber l'HTML, ou bien, j'écris directement en HTML.
Je suis quasiment certain que CWEB ne genere pas du LaTeX, ce doit etre du plain TeX si ce n'est pas un format expres fait par DEK.
Peut-être bien. Je n'ai jamais eu l'occasion de l'utiliser réelement.
Il doit aussi etre possible de generer du HTML, mais je ne sais pas au prix de quel effort d'adaptation de TeX4ht
Au fond, on doit pouvoir développer quelque chose de semblable directement en HTML ou XML, a peu d'efforts si on dispose déjà d'un parseur XML. Mais éditer l'XML ou le HTML directement dans un éditeur, c'est encore plus pénible que d'éditer le LaTeX.
Sur le fond, j'ai deja experimente avec quelques variantes d'outils de programmation litteraire et genere du HTML avec certains d'entre eux. Ca me semble bien dans un objectif de publication d'algorithme ou de cours de programmation, mais pas particulierement pour un gros programme destine a la production. Je prefere doxygen pour cela. Si j'ai bonne memoire, ma preference allais a noweb.
Le problème de base, quelque soit le système (y compris Doxygen), c'est que tu es obligé de t'occuper du balisage au même temps que tu saisis le texte, et que le balisage apparaît (et distrait) dans les fichiers source. Et que quand tu fais de la maintenance, c'est en fin de compte les fichiers source que tu as devant les yeux. Pour la saisie initiale, j'ai d'assez bonne expérience avec vim en mode texte, avec un programme filtre qui convertit en commentaires Doxygen par la suite. (C'est le programme « comment » sur ma site. Sous vim, je me mets dans une mode texte, sans indentation automatique, pour saisir le texte, puis je le passe par « comment », et je me mets en mode C++ pour saisir le code. Mais c'est une solution d'assez bas niveau ; ça marche bien plur les bibliothèques qui sont pratiquement une collection des classes plus ou moins indépendantes, mais ça ne suffit pas du tout pour l'application, où il faut documenter les relations entre les classes.)
