[Caml-list] Documentation tools

[Caml-list] Documentation tools

[Xavier Leroy]

I'm catching up with this interesting discussion between two meetings.
I fully agree with the need for a "standard" documentation tool for
OCaml interfaces, and the Caml team at INRIA is about to start working
on such a tool.  My initial plan was to do something in the style of
"javadoc", that is:

- Put documentation in .mli files, inside special comments
  e.g. (** This is part of the documentation *)
       (* but this is a regular comment *)

- Documentation is written in a subset of HTML plus special tags to
  do cross-referencing ("see also ...") and other stuff.

- The primary output format is HTML with a lot of cross-references
  and automatically-generated indices and tables of contents.

Many good points have been raised in this discussion, and actually
there are plenty other documentation systems that we should look at
before starting.  

Concerning LaTeX, I agree that a LaTeX output (possibly with PDFLaTeX
hyperlinks and folding tables of contents) would also be very nice,
e.g. for the OCaml manual itself.  However, I think HTML output is
even more important, and while Hevea does wonders at LaTeX->HTML
conversion, I believe HTML->LaTeX conversion is much easier *for the
subset of HTML that we need in documentation strings*.  We certainly
do not need full HTML 4.0 to document one function!  All we need is
font changes (e.g. <code>...</code>), line and paragraph breaking,
basic enumerations, hyperlinks, and perhaps tables.

Man pages and Info documents are also useful in some situations,
although in the long run I believe they will disappear and be replaced
by HTML or XML documentation.  Still, if the tool could output these
formats without too much efforts, that would be nice.

Some of you mentioned the interface documentation tool we use for the
Caml manuals.  It's really awful: the input format lacks both
expressiveness and flexibility, the tool itself is very basic
(used to be a 50-line Perl script until one of us took mercy and
rewrote it in Caml), and the output is truly ugly LaTeX.  It needs to
be replaced urgently by something better!

Now, I understand there are other documentation needs.  One is
literate programming (for those who are into that kind of things), but
there are already some pretty good tools for this, e.g. ocamlweb or
Norman Ramsey's noweb.  Another is writing full user's manuals
(and not just library documentation), but there I think LaTeX does a
decent job, and I'm not convinced by the Info format nor the
SGML-based tools used in the Linuxdoc project.

Suggestions and pointers to existing documentation systems are most
welcome.

- Xavier Leroy
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Sven LUTHER]

On Mon, May 14, 2001 at 10:11:44AM +0200, Xavier Leroy wrote:
> Suggestions and pointers to existing documentation systems are most
> welcome.

Xavier, ...

Why do you feel the sgml or some XML based thing is not adequate. As i see it,
but i have never really used it myself, just seen how it is used, it seems
that it is much easier, when using sgml, or the XML variant of it, to generate
either html stuff, latex files, info pahes, and do on. Why limit yourself if
with a bit more effort you can generate files in all of the above formats ?
While, altough HTML is easy to write (well most people are already familiar
with it) there isn't much you can do with it once you have it. I know of only
one tool who generate latex from html, and it's not a free tool, ...

Juts my opinion, ...

Friendly,

Sven Luther
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Benjamin C. Pierce]

I'd like to add one small point to the discussion of interface
documentation tools:

Being able to quickly get to texinfo files, man pages, or html docs for
interfaces is great, but there is another way that is often even quicker,
especially for the interfaces in the very project you're working on at
the moment: just read the source!  No matter how fancy our programming
environments and support tools become, we're still going to spend a lot
of time dealing directly with source files for interfaces -- not just
writing, but reading them.  

So I would not like to see us decide on a documentation tool that
requires *every* entry in every interface file to be annotated with some
kind of heavy markup like a big pile of html/docbook tags.  A small
amount of extra cruft in interfaces is acceptable, but please let's not
make all our .mli files totally unreadable for the sake of generating
fancy docs.

This is one thing that I think ocamlweb gets right: documentation
comments can usually be just straight text, with embedded ML fragments
enclosed in [...] so that the tool knows to change the font (and a more
sophisticated tool might know to cross-reference known identifiers,
etc.).  I hope whatever tool the OCaml community chooses or designs will
maintain this philosophy.

   -- B

-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Peter Ronnquist]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=us-ascii, Size: 470 bytes --]


> Suggestions and pointers to existing documentation
> systems are most
> welcome.

Doxygen is an alternative for use of javadoc style
comments:

http://www.stack.nl/~dimitri/doxygen/

Best Regards
Peter Rönnquist


__________________________________________________
Do You Yahoo!?
Yahoo! Auctions - buy the things you want at great prices
http://auctions.yahoo.com/
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Christian Lindig]

> Suggestions and pointers to existing documentation systems are most
> welcome.

Lesser known markup languages:

    Perl's POD:  http://www.perldoc.com/perl5.6/pod/perlpod.html
    Can be translated to man, HTML, LaTeX, plain text.
    
    WikiWiki syntax: http://www.c2.com/cgi/wiki?TextFormattingRules
    Many Wiki implementations use more advanced markup but this is the
    original. 
    
    Python's Structured Text: http://www.cis.upenn.edu/~edloper/pydoc/stminus-001.html
    
All three markup languages aim to use as feq special syntax as
possible.  Structured Text seems to be the most advanced using
indentation to denote structure.  This is in a sharp contrast to the
SGML/XML approach which is quite verbose at the source level.  LaTeX
seems to have found a middle ground.  Personally I'd prefer something
like Structured Text or LaTeX for OCaml.

-- Christian
    
-- 
Christian Lindig          Harvard University - DEAS
lindig@eecs.harvard.edu   33 Oxford St, MD 242, Cambridge MA 02138
phone: +1 (617) 496-7157  http://www.eecs.harvard.edu/~lindig/
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Stefan Monnier]

>>>>> "Xavier" == Xavier Leroy <Xavier.Leroy@inria.fr> writes:
> Man pages and Info documents are also useful in some situations,
> although in the long run I believe they will disappear and be replaced
> by HTML or XML documentation.

After all these years, HTML still has no good support for navigating
with the keyboard, for full-document searches or for indices.
The best you can get is "look for the `next' button" or "reach for
the search engine" or "look around for the `index' page".

These are the three reasons why I find `info' much more usable.
Maybe `info' will be replaced in the long run, but I have the distinct
impression that this run is going to be mighty long.

> Still, if the tool could output these formats without too much efforts,
> that would be nice.

Given the added functionality offered by Info (even though many people
dislike Info browsers and even though HTML also offers its own added
functionality) I think that Info (or better yet TeXinfo) output shouldn't
be left in the "would be nice" category.


	Stefan "who also finds SGML tags overly verbose"
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[markus.kliegl]

On Mon, 14 May 2001, Xavier Leroy wrote:

...

> 
> Suggestions and pointers to existing documentation systems are most
> welcome.

Well, besides the documentation generation stuff, I also like the
documentation strings of lisp (i.e. (describe 'xyz) and the comments of
objects in smalltalk (i.e. Integer comment printnl!). Something similar
to this in Ocaml would be great. Perhaps a let...with_comment...
construct? As in:
let f x y = ...
with_comment "f takes two arguments..."

This could also easily be used for the documentation generation.

But I'm rather new to Ocaml, so I'm not sure if anything I just said
made sense :-)

> 
> - Xavier Leroy
> -------------------
> To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr
> 

Markus Kliegl

-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Emmanuel LEDINOT]

Xavier Leroy a écrit :

>
> Suggestions and pointers to existing documentation systems are most
> welcome.

http://www.literateprogramming.com/ftools.html

contains 6 links to freeware documentation tools, and 14 links to commercial ones.
It should give some ideas to start with.

--
Emmanuel LEDINOT
Dassault Aviation
DGT/DPR/DESA
78 Quai Marcel Dassault
92552 Saint-Cloud Cedex
Tel: 01.47.11.53.05
Fax: 01.47.11.57.23


-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Markus Mottl]

I fully agree with Benjamin and Damien. Some light annotations as opposed
to heavy markup would be ok, but at least for me it's really important
that I can also easily cross-reference to "real" documentation, which
currently only leaves Latex as viable alternative.

Difficult algorithmic stuff is better explained in separate documents,
and heavy-weight literate programming is too cumbersome for me if I want
to maintain code. For simple library interface documentation, something
as "light" as the current documentation style used in the OCaml standard
libraries would suffice for me.

There is also the psychological issue that if we allow advanced
annotations, people will really use them. This is not unlikely to produce
good looking but completely incomprehensible documentation, not even to
mention the difficulty of reading the source comments. It's the contents
that matters...

Regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl

On Tue, 15 May 2001, Damien Doligez wrote:
> >From: "Benjamin C. Pierce" <bcpierce@saul.cis.upenn.edu>
> >
> >So I would not like to see us decide on a documentation tool that
> >requires *every* entry in every interface file to be annotated with some
> >kind of heavy markup like a big pile of html/docbook tags.  A small
> >amount of extra cruft in interfaces is acceptable, but please let's not
> >make all our .mli files totally unreadable for the sake of generating
> >fancy docs.
> 
> I couldn't agree more !!  I would absolutely hate to be forced to
> write my comments in some non-human-readable language such as HTML (or
> any other instance of SGML/XML).  In my opinion, unobtrusiveness is a
> lot more important than any fancy feature like <blink> or
> <img src="http://cristal.inria.fr/~harley/ecdl7/pics/planar.gif">.
> </blink>
> 
> You want titles and subtitles, font change for code, enumerations,
> maybe some escape mechanism to write formulas in LaTeX, a way of
> producing cross-references, and that's it.  Everything else is
> overhead.
> 
> -- Damien
> -------------------
> To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Documentation tools

[Damien Doligez]

>From: "Benjamin C. Pierce" <bcpierce@saul.cis.upenn.edu>
>
>So I would not like to see us decide on a documentation tool that
>requires *every* entry in every interface file to be annotated with some
>kind of heavy markup like a big pile of html/docbook tags.  A small
>amount of extra cruft in interfaces is acceptable, but please let's not
>make all our .mli files totally unreadable for the sake of generating
>fancy docs.

I couldn't agree more !!  I would absolutely hate to be forced to
write my comments in some non-human-readable language such as HTML (or
any other instance of SGML/XML).  In my opinion, unobtrusiveness is a
lot more important than any fancy feature like <blink> or
<img src="http://cristal.inria.fr/~harley/ecdl7/pics/planar.gif">.
</blink>

You want titles and subtitles, font change for code, enumerations,
maybe some escape mechanism to write formulas in LaTeX, a way of
producing cross-references, and that's it.  Everything else is
overhead.

-- Damien
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr