documentation automatique

documentation automatique

[Vincent Poirriez]

Bonjour a tous,

 Je viens de lire le manuel html de ocaml 2.0, qui fait apparaitre la
couleur dans le code
 caml.
 Il serait très agréable d'avoir un outil de documentation automatique
qui produise à
 partir d'un source .ml et/ou .mli correctement commenté, correctement
signifie éventuellement avec une prise en compte des commentaires
utilisant des délimiteurs
spécifiques (simples), une mise en page latex/html (modulo hevea ?)
agréable.

Je soupsone que cela existe quelque part.

Amicalement

Vincent

Short english version
Hello every body,

I am just reading the new html manual for ocaml 2.0. I appreciate the
introduction
of colours in ocaml presentation.

It should be nice if an automatic documentation tool could be provided
for ocaml.
It should take .ml and/or .mli files correctly documented and return a
nice latex/html
(eventually via HeVeA) docummentation.

I guess this exists somewhere.

Vincent

Re: documentation automatique

[Jae-Youn Chung]

* Vincent Poirriez <poirriez@univ-valenciennes.fr>, 8/27/1998 - 14:39
| I am just reading the new html manual for ocaml 2.0. I appreciate the
| introduction of colours in ocaml presentation.

  let me just ask for a favor of me to html version of manual
  distributors. I believe that emacs with caml mode and html manual is
  a perfect combination for programming in caml.
  In many cases, I really miss for the tools like HyperSpec in common
  lisp community provided from Harlequin which can be browsed directly
  from emacs with small pieces of codes (called hyperspec.el).
  This is possible because HyperSpec html document has
  <a name="blablah"> xx</a> every identifiers so that we can easily
  extract that attributes and write down small elisp code with
  browse-url feature.

  I've tried to extract every function and type and exceptions in O'caml
  manual by observing the patterns but which is not so accurate and in
  some cases failed :(.

  I think html version must been made from latex or something like
  that version. Can anybody add some <a name=XXX> identifiers </a> tag
  during the translations so that emacs users can easily adopt it to
  his/her tastes?

  And one more:
  In common lisp, there's nice manual browsing program, not to mention
  HyperSpec which is really an good job, something like clman which is
  unix *man* like interfaces for lisp functions.
  I believe caml manual can easily convert like that way.

| It should be nice if an automatic documentation tool could be provided
| for ocaml. It should take .ml and/or .mli files correctly documented
| and return a nice latex/html (eventually via HeVeA) docummentation.

  I don't know what you exactly want, but if you want to convert your
  caml code to html with syntax coloring and the like, I'd suggest you
  the htmlize.el in emacs which is written by Hrvoje Niksic <hniksic@srce.hr>.
  I believe that converting to latex format is not so hard anyway.
  (Isn't there many packages which converts program code to latex file?)

-- 
Chung jay youn
mailto:jay@pllab.kaist.ac.kr
http://pllab.kaist.ac.kr/~jay

RE: documentation automatique

[Adam P. Jenkins]

> | It should be nice if an automatic documentation tool could be provided
> | for ocaml. It should take .ml and/or .mli files correctly documented
> | and return a nice latex/html (eventually via HeVeA) docummentation.
>
>   I don't know what you exactly want, but if you want to convert your
>   caml code to html with syntax coloring and the like, I'd suggest you

I think he means something like Javadoc, but for O'Caml instead of Java.
With Javadoc, you put a comment in front of every function or class in your
code, using some special format for the comments, and then run Javadoc with
the source code as input.  It extracts the special comments and generates an
HTML document for your code.  I've seen several programs like this for C++
also, but not for Caml yet.

Adam

RE: documentation automatique

[Jan Skibinski]

On Sat, 29 Aug 1998, Adam P. Jenkins wrote:

> I think he means something like Javadoc, but for O'Caml instead of Java.
> With Javadoc, you put a comment in front of every function or class in your
> code, using some special format for the comments, and then run Javadoc with
> the source code as input.  It extracts the special comments and generates an
> HTML document for your code.  I've seen several programs like this for C++
> also, but not for Caml yet.

	And soon all sources would be obfuscated by all
	sorts of tags, and hardly directly readable by
	a programmer. Unless we have built powerful tools,
	where original source is no longer important
	-- as in Smalltalk or Eiffel -- this does not look
	to me as a good idea. 

	See http://www.numeric-quest.com/news/NQ-comments.html

	Jan

	

Re: documentation automatique

[Francois Pessaux]

Bonjour,

>  Je viens de lire le manuel html de ocaml 2.0, qui fait apparaitre la
> couleur dans le code
>  caml.
> ...
> Je soupsone que cela existe quelque part.
Il y a bien ml2html qui essaye d'approcher ce genre de travail. Il traite du
Caml Light et non du Ocaml. Mais peut-etre que ca pourra faire l'affaire...

On peut trouver la distrib sur ma homepage:
	http://pauillac.inria.fr/~pessaux/ml2html.tgz

Amicalement,

-- 
(*                      Francois PESSAUX (Francois.Pessaux@inria.fr) *)
(*                               INRIA Rocquencourt - Projet CRISTAL *)
(*                               (http://pauillac.inria.fr/~pessaux) *)
;;

RE: documentation automatique

[Sven]

(* about producing doc for your ocaml code *)


is there not something similar that already exists ? 

i have seen it mentionned together with the ocaml xlib thing some while ago on the list, or was it for ocamltk ?

Friendly,

Sven LUTHER

RE: documentation automatique

[Fabrice Le Fessant]

  There is a patch, called mli2html, which generates .HTML files from
.ml and .mli files. The HTML file produced contains the same
information as generated with the -i option, plus some comments which
can be added by the syntax (*[name] comments for name *). HTML links
are also produced between each usage of a type and its definition..

  This patch is quite simple, and should be improved a lot to be
really useful. It is available for Ocaml-2.00 at:

http://pauillac.inria.fr/~lefessan/src/mli2html-2.00.tar.gz



- Fabrice Le Fessant

RE: documentation automatique

[Ken Wakita]

-----Original Message-----
From: Jae-Youn Chung <jay@compiler.kaist.ac.kr>
To: Vincent Poirriez <poirriez@univ-valenciennes.fr>
Cc: caml-list@inria.fr <caml-list@inria.fr>
Date: Sunday, August 30, 1998 1:49 AM
Subject: Re: documentation automatique


>* Vincent Poirriez <poirriez@univ-valenciennes.fr>, 8/27/1998 - 14:39
>| I am just reading the new html manual for ocaml 2.0. I appreciate the
>| introduction of colours in ocaml presentation.
>
>  let me just ask for a favor of me to html version of manual
>  distributors. I believe that emacs with caml mode and html manual is
>  a perfect combination for programming in caml.
>  In many cases, I really miss for the tools like HyperSpec in common
>  lisp community provided from Harlequin which can be browsed directly
>  from emacs with small pieces of codes (called hyperspec.el).
>  This is possible because HyperSpec html document has
>  <a name="blablah"> xx</a> every identifiers so that we can easily
>  extract that attributes and write down small elisp code with
>  browse-url feature.
>
>  I've tried to extract every function and type and exceptions in
O'caml
>  manual by observing the patterns but which is not so accurate and in
>  some cases failed :(.


A few months ago I made a small program which I call "ocamlman".  It is
a graphical browsing system of the Ocaml manual.  Ocaml man retrieves
from the TEXT version of the ocaml manual all the types, functions,
functors.  Its menu contains a contents index and module indices.  The
look and
feel is like the on-line manual of Gambit originally developed on the
Macintosh platform.  I can contribute the code to this list if people
are interested.  A small hurdle is that you need OlablTk 1.07 to make it
work.

Ken