Re: [Caml-list] Documentation tools

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

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

[Caml-list] Re: Documentation tools

[Joseph R. Kiniry]

I've used dozens of source processing, documentation, and literate
programming tools over the years.

I think that a simple, but extensible, javadoc-like document processor
is the right way to go.  The inclusion of a standard set of document
tags with *well-defined* semantics is a must.  

My research group and companies use an extensive code standard(1) with
complementary tools for documentation(2) and test code generation(3)
for exactly this purpose and we and our customers been very happy with
this solution.  My only regret is that we are generating renderable
formats (e.g. HTML) directly rather than indirectly.  This leads me to
the following suggestion.

I *strongly* suggest the powers that be look into the Linux
Documentation Project(4) tools, namely sgml-tools and related(5).
>From a single, very simple SGML source the following formats can all
be generated: HTML, info, LaTeX, LyX, RTF, txt, man pages.

I've been very happy with both the use of these tools as well as their
output for the past couple of years.

Best,
Joe Kiniry
-- 
Joseph R. Kiniry                    http://www.cs.caltech.edu/~kiniry/
California Institute of Technology        ID 78860581      ICQ 4344804

(1) http://www.infospheres.caltech.edu/resources/code_standards/java_standard.html
(2) http://www.cs.caltech.edu/~kiniry/papers/JPP/JPP.brief
(3) http://semantik.informatik.uni-oldenburg.de/~jass/
    http://www.cs.iastate.edu/~leavens/JML.html
(4) http://www.linuxdoc.org/
(5) http://www.linuxdoc.org/LDP/LDP-Author-Guide/

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