[Caml-list] CDK binary release

[Caml-list] CDK binary release

[Fabrice Le Fessant]

We are pleased to announce a first (beta) binary release of the CDK for
Linux. This release can be downloaded from:

http://pauillac.inria.fr/cdk/

>From this page, you can also have access to the documentation and the
 mailing-list.

The CDK gathers a large set of libraries and programs implemented for
Ocaml from different sources. Moreover, it provides an easy access to
these libraries (using the cdk_config tool) and documentation (in
particular, WEB and MAN pages).

Best regards,

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

Re: [Caml-list] CDK binary release

[Miles Egan]

On Mon, May 07, 2001 at 11:06:18AM +0200, Fabrice Le Fessant wrote:
> 
> We are pleased to announce a first (beta) binary release of the CDK for
> Linux. This release can be downloaded from:

This is a very nice package.  Thanks!

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

Re: [Caml-list] CDK binary release

[John Max Skaller]

Fabrice Le Fessant wrote:
> 
> We are pleased to announce a first (beta) binary release of the CDK for
> Linux. This release can be downloaded from:
> 
> http://pauillac.inria.fr/cdk/

	Please allow me to thank you profusely for 
the magnificent effort which has gone into the boring
task of packaging a large set of libraries from all over
the place into a single coherent whole.

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Markus Mottl]

On Mon, 07 May 2001, Fabrice Le Fessant wrote:
> We are pleased to announce a first (beta) binary release of the CDK
> for Linux.

Many thanks for your work!

> The CDK gathers a large set of libraries and programs implemented for
> Ocaml from different sources. Moreover, it provides an easy access
> to these libraries (using the cdk_config tool) and documentation
> (in particular, WEB and MAN pages).

I have just taken a look at the way documentation is handled. It would
be fine if there were some kind of standard way to prepare documentation
for OCaml-sources in general. It's otherwise a tremendous effort to
maintain various formats (and who likes writing documentation anyway? ;)

Is there any specific reason for inventing a new documentation tool? Why
not use e.g. Jean-Christophe Filliatre's ocamlweb?

How about the tool that INRIA uses? - Unfortunately, nobody has answered
may recent question on this here yet... :(

Best regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

[Caml-list] About documentation tools

[David Mentre]

Markus Mottl <mottl@miss.wu-wien.ac.at> writes:

>  Why not use e.g. Jean-Christophe Filliatre's ocamlweb?

ocamlweb intents to be a tool to document source code as Knuth's WEB
tool. In other words, it's more for internal code documentation than for
user manual and reference guide.

> How about the tool that INRIA uses? - Unfortunately, nobody has answered
> may recent question on this here yet... :(

As far as I know (despite my @inria.fr email, I'm not part of the Caml
team), the tool used by the Caml team is specific and not ready for a
public release, i.e. some shortcomings are solved in ad-hoc manner. 

But I agree that a recommended documentation tool would be a plus. It
does not mean that such a tool should be very elaborated. The simpler,
the better. And I also think that such a tool should be close to
standard tool in other languages, mostly javadoc. It would help the
transition from other languages (and multi-language developments).

My 2 cents,
Best regards,
david
-- 
 David.Mentre@inria.fr -- http://www.irisa.fr/prive/dmentre/
 Opinions expressed here are only mine.
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

[Caml-list] Re: About documentation tools

[Markus Mottl]

On Wed, 09 May 2001, David Mentre wrote:
> ocamlweb intents to be a tool to document source code as Knuth's WEB
> tool. In other words, it's more for internal code documentation than
> for user manual and reference guide.

It can also be used to extract information about interfaces. The nice
thing about it is that it allows you to fully exploit the power of Latex
(and therefore Hevea). I think it's a good idea to support such features
if one wants to have flexible ways of generating documentation.

> the tool used by the Caml team is specific and not ready for a public
> release, i.e. some shortcomings are solved in ad-hoc manner.

But it wouldn't hurt either to make it available as alpha software on
some CVS-server, would it? Maybe some voluntary hero (not me ;) would
go about making it "ready for public use"...

> But I agree that a recommended documentation tool would be a plus.

I still see a lack of "social" standard tools. Documentation tools
are one thing, packaging tools another. Wouldn't this be exactly the
right thing that the new OCaml-consortium would want to fund? - It's a
reasonable assumption that Xavier and the others prefer hacking away on
new compiler features rather than such things and would need engineers
for more earthly tasks.

How are things developing in the Consortium? Are there already plans to
fund specific projects, possibly of this kind?

> It does not mean that such a tool should be very elaborated. The
> simpler, the better.

I find ocamlweb fairly easy to use (not really much more difficult than
your tool, I think). It still gives you the option to drop to Latex
if required.

> And I also think that such a tool should be close to standard tool
> in other languages, mostly javadoc. It would help the transition from
> other languages (and multi-language developments).

I don't know Java (and therefore javadoc) well enough to judge this
(maybe at least javadoc is well-designed), but I'd surely argue against
taking up inferior approaches if we can do things the right way right
from the start.

Best regards,
Markus

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[John Max Skaller]

Markus Mottl wrote:

> I have just taken a look at the way documentation is handled. It would
> be fine if there were some kind of standard way to prepare documentation
> for OCaml-sources in general. It's otherwise a tremendous effort to
> maintain various formats (and who likes writing documentation anyway? ;)

	But the CDK generates documentation is a way that clearly
defines such a 'standard'. So what's needed is a description
of this for people preparing packages for inclusion in CDK.

	I'd also suggest that every package be allowed a 
'native html documentation directory'. If present,
a link in the generated documentation to it would allow the
reader to go the suppliers original html documentation.

	[For example, if there is a 'doc' directory
in the package, the CDK summary could include a link
to 'doc/index.html']

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] Re: About documentation tools

[John Max Skaller]

Markus Mottl wrote:

> It's a
> reasonable assumption that Xavier and the others prefer hacking away on
> new compiler features rather than such things and would need engineers
> for more earthly tasks.

	I don't think this is as reasonable as you say.
In principle, an Ocaml module interface should specify semantics.
However, Ocaml doesn't include language constructs to specify
the axioms the interface obeys: they have to be given as comments.

	Some languages, like Eiffel, actually support constructions
for specifying function preconditions.

	So it actually makes sense to allow axioms to be
specifed in a module interface _as part of the language_,
even if it is only a special form of comment containing
vague natural language text.

	I'm not suggesting this, only that Xavier may be more
interested than you think in formalising a documentation
protocol designed to supply the missing information.

> I don't know Java (and therefore javadoc) well enough to judge this
> (maybe at least javadoc is well-designed), but I'd surely argue against
> taking up inferior approaches if we can do things the right way right
> from the start.

	Ocamlweb -- and Javadoc -- are 'inferior' approaches.
A fully fledged literate programming tool is a better solution.
But it requires a 'heavy' committment to literate programming
many are not willing to make. So a more lightweight approach
is a reasonable compromise.

	I note that many Java programmers I have talked to
think Javadoc is one of the best things about Java. :-)
I also note that perldoc has served Perl users well.
Python's doc strings do not work as well. A C++ system I have
worked on used a convention suitable for generating 'man' pages.

	Unlike proper LP tools, these things never generate
enough of the right documentation. But at least they generate
_some_, which is better than none at all. Even though I use
a powerful LP tool, I'd adhere to an ocaml convention,
and I'd also use the standard ocamldoc tool in addition 
to the LP tool I use.

	One comment though: a modern tool must generate
HTML, _directly_. It is not good enough to generate LaTeX,
and then translate it into HTML. Please, I want _one_ tool,
not a long complicated error prone chain to add to my
existing chain :-)

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Markus Mottl]

On Thu, 10 May 2001, John Max Skaller wrote:
> 	But the CDK generates documentation is a way that clearly
> defines such a 'standard'.

Right, 'a' standard, not 'the' standard... ;)

> So what's needed is a description of this for people preparing packages
> for inclusion in CDK.

But what if I want to e.g. convert my documentation to PostScript, too?

I want to have 'a' standard that covers most important aspects and is
supported by a significant group of users (when I was younger I never
managed to abide by my mum's rule: Don't say "I want ..."! You cannot
have everything - you have to learn how to do without!" ;)

Regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[John Max Skaller]

Markus Mottl wrote:

> I want to have 'a' standard that covers most important aspects and is
> supported by a significant group of users (when I was younger I never
> managed to abide by my mum's rule: Don't say "I want ..."! You cannot
> have everything - you have to learn how to do without!" ;)

	I agree. But I think an important point is to start somewhere.
If I could see a specification -- even an inadequate one -- there
would be a starting point for discussion. I could try it out,
even write a tool, and report my findings, and so could you.

	Fabrice already has a tool and has used it. 
It seems like a good place to start as a proposal for a standard
 -- without assuming it is final. It would at least allow authors 
to clean up their interfaces so the existing CDK tools 
could produce a better synopsis of the interfaces 
(the existing description, for say, pcre, is quite unusable).

	The other good place to start is the internal INRIA
standard use to generate the library documentation.
[Or, are these the same?]

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Fabrice Le Fessant]

The CDK documentation tool has still many problems, but it is
currently the only tool which produces man pages for Ocaml modules and
functions. Moreover, LaTeX is not used by all Ocaml users (some are
using Windows and its wonderful editors). For now, I think the best
language is a specific language, for example, a subset of HTML.
This would have the benefit of being easily translatable to LaTex(ie PS),
HTML and MAN (I think HTML --> LaTeX is easier than LaTeX --> HTML,
even with HeVea). Note that the current language used by cdk_doc is
documented in the HTML documentation of the CDK (cdk_doc.html).

cdk_doc was not designed for being used by everybody, but to generate
immediatly some documentation for the CDK with a minimal effort. Now,
we have to think about how to change Sebastien's tool in a more
general documentation tool. But, we have the same problem with
cdk_config (and findlib). 

Another approach I used a few years ago was to generate HTML
documentation using the compiler, which can add cross-links between
modules (and even between types in the same module). This could be
another good idea ... 


- Fabrice

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

[Caml-list] CDK Documentation format

[Dave Mason]

>>>>> On Thu, 10 May 2001 11:19:40 +0200 (CEST), Fabrice Le Fessant <fabrice.le_fessant@inria.fr> said:

> The CDK documentation tool has still many problems, but it is
> currently the only tool which produces man pages for Ocaml modules
> and functions. Moreover, LaTeX is not used by all Ocaml users (some
> are using Windows

LaTeX runs fine on MS-Windows.

> and its wonderful editors).

(I don't know if this was meant as sarcastic.  Probably not, although
it doesn't match my experience with MS-Windows.  For me, there is only
one decent editor for MS-Windows; it's called emacs.)

> For now, I think the
> best language is a specific language, for example, a subset of HTML.
> This would have the benefit of being easily translatable to LaTex(ie
> PS), HTML and MAN (I think HTML --> LaTeX is easier than LaTeX -->
> HTML, even with HeVea).

Unless you are providing (or pointing to) a translator from HTML-->
LaTeX, this is an iffy argument.  Simple LaTeX, understandable by
HeVea, isn't very difficult to write even if you never feed it to
LaTeX and only produce HTML.  And as a bonus, you can get rather nice
output from LaTeX!

> Note that the current language used by cdk_doc is documented in the
> HTML documentation of the CDK (cdk_doc.html).

I haven't had a chance to look at this yet, but wanted to make the
point that there is an open-source formatting system that produces
good output (LaTeX), already available, and it would be good to use it.

> cdk_doc was not designed for being used by everybody, but to
> generate immediatly some documentation for the CDK with a minimal
> effort. Now, we have to think about how to change Sebastien's tool
> in a more general documentation tool.

It shouldn't be very difficult to have it spit out LaTeX for HeVea.

> Another approach I used a few years ago was to generate HTML
> documentation using the compiler, which can add cross-links between
> modules (and even between types in the same module). This could be
> another good idea ...

Sounds interesting, but why not generate LaTeX?

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

Re: [Caml-list] CDK binary release

[Sven LUTHER]

On Thu, May 10, 2001 at 11:19:40AM +0200, Fabrice Le Fessant wrote:
> 
> The CDK documentation tool has still many problems, but it is
> currently the only tool which produces man pages for Ocaml modules and
> functions. Moreover, LaTeX is not used by all Ocaml users (some are
> using Windows and its wonderful editors). For now, I think the best
> language is a specific language, for example, a subset of HTML.

What about sgml, most project use that, and they can then transform it in many
different format afterward.

Also if windows people don't use latex (there is a tex suite for windows
available anyway), you just need to transform the latex files into something
they can use, like html, with one of the latex2html tools available (hevea for
example).

Releasing html documentation only is not a nice thing.

Friendly,

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

Re: [Caml-list] CDK binary release

[Markus Mottl]

On Thu, 10 May 2001, Sven LUTHER wrote:
> On Thu, May 10, 2001 at 11:19:40AM +0200, Fabrice Le Fessant wrote:
> > The CDK documentation tool has still many problems, but it is
> > currently the only tool which produces man pages for Ocaml modules and
> > functions. Moreover, LaTeX is not used by all Ocaml users (some are
> > using Windows and its wonderful editors). For now, I think the best
> > language is a specific language, for example, a subset of HTML.

I agree with Dave and Sven that producing LaTeX should be supported in
some way or the other. HTML alone is not good enough, and translating
from HTML to LaTeX definitely doesn't seem to be so much easier than the
other way round. It's usually better to translate from more powerful to
less powerful languages.

Also, I don't need man page support, though this could be surely added
to hevea (it already supports texinfo). Man pages are really just text
beefed up with some formatting (no cross-references and such). The
following bash function probably produces more readable output:

  function ocdoc () { command vim -R `ocamlc -where`/$1; }

To summarize, I'd prefer a tool that produces Latex and also allows
Latex-code within the documentation. Ocamlweb could surely be improved
(more features, more beautiful formatting, etc.), but I think it gets
the ideas of simplicity + expressiveness basically right. Why not take
this tool and make it ready for wide-spread public use? I was a bit
surprised that cdk_doc doesn't build on ocamlweb + hevea.

Best regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[David Mentre]

Sven LUTHER <luther@dpt-info.u-strasbg.fr> writes:

> What about sgml, most project use that, and they can then transform it in many
> different format afterward.

Or XML? (yes, I know, yet another buzzword)

In the Linux Documentation Project, they use heavily SGML or XML with
the DocBook DTD. From that format, they have tools to generate to LaTeX,
info, text, HTML, and RTF. From that you can generate MS Word,
PostScript, PDF, etc.

Ok, maybe an ocaml file is not a whole DocBook document, but using
DocBook tags would be a plus I think. From the files of a project, the
CDK doc tool could generate the whole XML DocBook document.

One problem against that solution is that DocBook tags are a bit
verbose:
 http://linuxdoc.org/LDP/LDP-Author-Guide/writing-docbook.html

Of course, I've not developed anything, so feel free to delete those
remarks. :)

My 2 cents,
d.
-- 
 David.Mentre@inria.fr -- http://www.irisa.fr/prive/dmentre/
 Opinions expressed here are only mine.
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Patrick M Doane]

On Thu, 10 May 2001, Fabrice Le Fessant wrote:

> The CDK documentation tool has still many problems, but it is
> currently the only tool which produces man pages for Ocaml modules and
> functions.

Out of curiosity, who wants to be reading Ocaml documentation through man
pages?  I would think HTML and texinfo would both be nicer formats to work
with. Is there some advantage that I'm missing?

Patrick


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

Re: [Caml-list] CDK binary release

[Patrick M Doane]

On Thu, 10 May 2001, Sven LUTHER wrote:

> On Thu, May 10, 2001 at 11:19:40AM +0200, Fabrice Le Fessant wrote:
> > 
> > The CDK documentation tool has still many problems, but it is
> > currently the only tool which produces man pages for Ocaml modules and
> > functions. Moreover, LaTeX is not used by all Ocaml users (some are
> > using Windows and its wonderful editors). For now, I think the best
> > language is a specific language, for example, a subset of HTML.
> 
> What about sgml, most project use that, and they can then transform it in many
> different format afterward.

I agree.  I posted recently about any experiences users have with SGML
documentation linked with Ocaml programs so this seems to be coming up at
a good time.  I would like to have a good framework in place for writing
the documentation for FORT and would prefer an SGML approach.

> Also if windows people don't use latex (there is a tex suite for windows
> available anyway), you just need to transform the latex files into something
> they can use, like html, with one of the latex2html tools available (hevea for
> example).
> 
> Releasing html documentation only is not a nice thing.

Good points again.  One advantage worth mentioning about sgml/xml
representation of the documentation is that transformations will be much
easier to implement than if the native output format is latex.

Patrick

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

Re: [Caml-list] CDK binary release

[Jean-Christophe Filliatre]

Markus Mottl writes:
 > On Thu, 10 May 2001, Sven LUTHER wrote:
 > > On Thu, May 10, 2001 at 11:19:40AM +0200, Fabrice Le Fessant wrote:
 > > > The CDK documentation tool has still many problems, but it is
 > > > currently the only tool which produces man pages for Ocaml modules and
 > > > functions. Moreover, LaTeX is not used by all Ocaml users (some are
 > > > using Windows and its wonderful editors). For now, I think the best
 > > > language is a specific language, for example, a subset of HTML.
 > 
 > I agree with Dave and Sven that producing LaTeX should be supported in
 > some way or the other. HTML alone is not good enough, and translating
 > from HTML to LaTeX definitely doesn't seem to be so much easier than the
 > other way round. It's usually better to translate from more powerful to
 > less powerful languages.
 > 
 > To summarize, I'd prefer a tool that produces Latex and also allows
 > Latex-code within the documentation. Ocamlweb could surely be improved
 > (more features, more beautiful formatting, etc.), but I think it gets
 > the ideas of simplicity + expressiveness basically right. Why not take
 > this tool and make it ready for wide-spread public use? I was a bit
 > surprised that cdk_doc doesn't build on ocamlweb + hevea.

As the (co)author of ocamlweb, I  think I should say something at that
point.

First, I agree that ocamlweb could be improved, and in particular that
its  HTML output  is  rather ugly.  But  the purposes  of cdk_doc  and
ocamlweb are clearly different:

 - cdk_doc is nice to produce  HTML documentations of libraries, to be
   browsed when developping. Personally, I find these pages quite nice
   and useful.

 - ocamlweb is a  literate programming tool; it means  that it is used
   to produce  a document describing  the all code i.e.  interface but
   also implementation,  explaining the algorithms,  giving complexity
   analysis, scientific references, etc.  This document is intended to
   be read  as an article (not to  be quickly browsed to  find out the
   name and/or spec of a function) and, for that purpose, it has to be
   *beautiful*, especially if it involves mathematical material. Knuth
   invented   TeX  to  support   literate  programming   (among  other
   applications   like   scientific   publishing),  because   literate
   programming *needs*  a complex typographic  tool. HTML is  not (and
   will probably never be) such a tool.

I hope  this will help  clarifying the difference between  cdk_doc and
ocamlweb.

-- 
Jean-Christophe FILLIATRE
  mailto:Jean-Christophe.Filliatre@lri.fr
  http://www.lri.fr/~filliatr
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[John Max Skaller]

Fabrice Le Fessant wrote:
 
> Another approach I used a few years ago was to generate HTML
> documentation using the compiler, which can add cross-links between
> modules (and even between types in the same module). This could be
> another good idea ...

	The best approach is probably to
generate an intermediate language, and then convert THAT to
documents.  And the obvious choice for an intermediate language
is a fixed subset of XML. :-(

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Thorsten Ohl]

Jean-Christophe Filliatre writes:

> But  the purposes  of cdk_doc and ocamlweb are clearly different:
>
>  - cdk_doc is nice to produce  HTML documentations of libraries, to be
>    browsed when developping.
> 
>  - ocamlweb is a  literate programming tool; it means  that it is used
>    to produce  a document describing  the all code i.e.  interface but
>    also implementation,

Yes, but it would be very useful if the markup could serve both
purposes simultaneously.  I'm using ocamlweb extensively and I find
myself writing *.mli files that could be turned into online
documentation (see
http://heplix.ikp.physik.tu-darmstadt.de/~ohl/omega/omega.pdf for an
extended example).  Navigating a hyperlinked PDF version of the woven
file is easy enough, but quick online documentation generated from the
_same_ *.mli files (ignoring the implementation files) would also be a
very welome addition.

It's not entirely trivial to design something doesn't constrain
ocamlweb too much, in particula in the math arena, but it could be
done.

A first step would be for ocamlweb to ignore the cdk_doc markup and
for cdk_doc to map TeX commands to a ``under construction'' tag.
-- 
Thorsten Ohl, Physics Department, TU Darmstadt -- ohl@hep.tu-darmstadt.de
http://heplix.ikp.physik.tu-darmstadt.de/~ohl/ [<=== PGP public key here]
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[John Max Skaller]

Jean-Christophe Filliatre wrote:

> As the (co)author of ocamlweb, I  think I should say something at that
> point.

>  - ocamlweb is a  literate programming tool; it means  that it is used
>    to produce  a document describing  the all code i.e.  interface but
>    also implementation,  explaining the algorithms,  giving complexity
>    analysis, scientific references, etc.  This document is intended to
>    be read  as an article (not to  be quickly browsed to  find out the
>    name and/or spec of a function) and, for that purpose, it has to be
>    *beautiful*, especially if it involves mathematical material. Knuth
>    invented   TeX  to  support   literate  programming   (among  other
>    applications   like   scientific   publishing),  because   literate
>    programming *needs*  a complex typographic  tool. HTML is  not (and
>    will probably never be) such a tool.

	As the author of a powerful LP tool myself ..
I don't have exactly the same view (although I'm not 
disagreeing entirely either).

	My tool is intended to be able to produce the kind of
document Jean-Christophe described. But it is _also_ capable
of a lot more. It can be used to produce interface summaries,
to generate tables of test results, to generate
code and documentation from compressed specifications,
to produce hyperlinked cross references .. and a whole host
of other kinds of useful 'documents'.

	While I agree that LaTeX is often the only choice
for documenting theory or complex algorithms, a large amount
of software doesn't need such sophisticated documentation.
I personally find LaTeX output very difficult to read,
since my Linux system is hopeless at rendering fonts 
at screen resolution (and I don't own a working printer).

	So I have a strong preference for HTML, since
both my Linux and Windows boxes render the fonts quite well.
It is also much easier to cross reference than a screen
image of paper.

	Interscript produces _both_ HTML and LaTeX (and plain
text as well), from the same source. It hyperlinks HTML
cross references, and uses LaTeX cross-reference for LaTeX.
[And line numbers for plain text!]

	It is also possible to include 'typesetter native' sections,
which only get output to that typesetter: it is ugly, but possible,
to generate nice category theory diagrams with XYpic for LaTeX,
and then 'capture' the image into a JPG file and glue it into
the HTML document. (I wish this could be automated).

	HTML can do some things that LaTeX cannot, apart
from cross-referencing interactively: it can resize and adjust
according to your screen size, and it supports colour on every
system I've seen. And, if you have IE5+, interscript produces
a folding table of contents -- which is kind of hard to do
with LaTeX. :-)

	And of course, you can post your HTML program
on the Web, so others can read annotated versions of your
code without downloading the code .. or installing LaTeX,
DVI viewers, or even a postscript viewer.

	My point is that Literate Programming is a paradigm
in which code and documentation are co-developed, but that
doesn't necessarily imply production of a fine quality
journal quality article, although that should be possible.
It should also be possible to LP commerical programs, or
Ocaml bindings of some C interface, which may be better
served by interactive hyperlinking than nice print.

	I think that means: I see no reason why a tool
like Ocamlweb couldn't _also_ output interface summaries,
and in HTML too, if it were suitably modified to do so.
And this might be a good path, since it would then
'also' be able to produce nice scientific documents.
For most applications, that would be an added bonus,
rather than the main reason to use it...but that ability
is a good incentive to make a deeper committment to LP.

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Markus Mottl]

Thorsten Ohl schrieb am Thursday, den 10. May 2001:
> Yes, but it would be very useful if the markup could serve both purposes
> simultaneously.  I'm using ocamlweb extensively and I find myself
> writing *.mli files that could be turned into online documentation

The same is true for me: the documentation of interfaces is the same
for users of some module and for developers. Only the latter usually
also want to see the documentation of the implementation. Being able
to generate both kinds of documentations without having to write extra
annotations would be a big help! That's why I am a bit reluctant about
cdk_doc, because it only addresses the library user's point of view.

Ocamlweb could probably (please correct me if I am wrong) be turned into
a general tool much more easily than the other approaches I have seen.

Any chance that it (or something similar) could ever get the status of
a standard tool (which cdk_doc seems to be targeting)?

Best regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Fabrice Le Fessant]

>  On Thu, 10 May 2001, Fabrice Le Fessant wrote:
>  
>  > The CDK documentation tool has still many problems, but it is
>  > currently the only tool which produces man pages for Ocaml modules and
>  > functions.
>  
>  Out of curiosity, who wants to be reading Ocaml documentation through man
>  pages?  I would think HTML and texinfo would both be nicer formats to work
>  with. Is there some advantage that I'm missing?

You mean that, because you don't like man pages, nobody like them ?

HTML is already supported, I have nothing against texinfo. But, do you
know a tool to generate it from all the mli files from the CDK (that
use different formatting conventions) ? Can you send me a patch to the
CDK to use it ? Are you sure it is installed on all computers that
will compile the CDK documentation ?

For LaTeX, we will not force people to use LaTeX to document their
interfaces: most comments are simple text lines including some pieces
of code (in cdk_doc, they simply have to be between brackets). Only
section titles have to be handled differently. cdk_doc is enough for
that. New output formats have to be added, and all interfaces have to
be completely translated to the input format ... We are not writting a
book, but only a reference manual, thus, we don't need SGML or
complicated formatting tool for that !

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

Re: [Caml-list] CDK binary release

[John Max Skaller]

Fabrice Le Fessant wrote:

> >  Out of curiosity, who wants to be reading Ocaml documentation through man
> >  pages?  I would think HTML and texinfo would both be nicer formats to work
> >  with. Is there some advantage that I'm missing?
> 
> You mean that, because you don't like man pages, nobody like them ?

	Actually, it would be nice to have man pages for each
Ocaml module. It is faster to say:

	man  ocaml-list

to check the order of arguments to List.fold_left (newbie, aren't I :-)
or the names (if using label mode) than fiddle around with a browser:
and doesn't need a mouse. 

	I have the C standard on paper and online.
but I often use 'man memcpy' when I forget the order
of arguments :-)

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Fabrice Le Fessant]

>  	Actually, it would be nice to have man pages for each
>  Ocaml module. It is faster to say:
>  
>  	man  ocaml-list

In the CDK, you have a man page for List and for fold_left. So you can
write:

# man List

or

# man fold_left

and this is done for all modules in the CDK (the 'fold_left' man page
contains all the 'fold_left' functions defined in the CDK (List,
Array, etc ...))

- Fabrice

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

Re: [Caml-list] CDK binary release

[Patrick M Doane]

On Fri, 11 May 2001, Fabrice Le Fessant wrote:

> >  Out of curiosity, who wants to be reading Ocaml documentation through man
> >  pages?  I would think HTML and texinfo would both be nicer formats to work
> >  with. Is there some advantage that I'm missing?
> 
> You mean that, because you don't like man pages, nobody like them ?

I like man pages, it just surprised me to see this as an output for
documentation.  I guess I would say that it doesn't seem consistent with
current programming trends. AFAIK, man pages for programming APIs seem to
only be produced for C libraries.

> HTML is already supported, I have nothing against texinfo. But, do you
> know a tool to generate it from all the mli files from the CDK (that
> use different formatting conventions) ? Can you send me a patch to the
> CDK to use it ? Are you sure it is installed on all computers that
> will compile the CDK documentation ?

ocamlweb/hevea generate info files nicely. Regarding the other questions,

  - In the long term, the .mli files in the CDK should use the same
formatting conventions.  I assume that the current differences exist
because the effort is just getting started.  Consistency, aside from
documentation, is perhaps the weakest area of CDK right now.  This is to
be expected of course, designing a good library is hard!

  - If you would find it useful for me to patch CDK to work with
ocamlweb/hevea, then let me know.  I'll do the work over the weekend. To
go a step further, if there's work that can be farmed out for CDK
development, I'm sure many of us would want to help out. 

  - I don't know what machines will be used to compile CDK documentation,
but there is an easy solution which will guarantee that ocamlweb/hevea are
present on those machines:  add them to the CDK.  This is similar to
the current setup with cdk_doc.

I'm not trying to advocate ocamlweb/hevea over cdk_doc. It is a tool
combination that support info files though.

> For LaTeX, we will not force people to use LaTeX to document their
> interfaces: most comments are simple text lines including some pieces
> of code (in cdk_doc, they simply have to be between brackets). Only
> section titles have to be handled differently. cdk_doc is enough for
> that. New output formats have to be added, and all interfaces have to
> be completely translated to the input format ... We are not writting a
> book, but only a reference manual, thus, we don't need SGML or
> complicated formatting tool for that !

I think that the discussion thread for LaTeX/SGML is in a larger context
than the needs of CDK.  I will echo Markus's desire for there to be a
documentation standard.  This standard should be simple enough to meet the
CDK needs, but also meet more complex formatting needs. 

Also, you are already using SGML to build the CDK documentation by using
HTML. It's not a very good DTD to represent the content for style
transformations, but it's a start. Defining a DTD for Caml documentation
would be a very nice intermediate representation.

Patrick

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

Re: [Caml-list] CDK binary release

[Brian Rogoff]

On Fri, 11 May 2001, Fabrice Le Fessant wrote:
> For LaTeX, we will not force people to use LaTeX to document their
> interfaces: most comments are simple text lines including some pieces
> of code (in cdk_doc, they simply have to be between brackets). Only
> section titles have to be handled differently. cdk_doc is enough for
> that. New output formats have to be added, and all interfaces have to
> be completely translated to the input format ... We are not writting a
> book, but only a reference manual, thus, we don't need SGML or
> complicated formatting tool for that !

I think that's the main point of disagreement. I'd like a source documentation
tool which will scale up to writing books (unlikely) or at least magazine
or journal article like things. I'd also prefer not to have a separate
tool and source of embedded comment information just for documenting
interfaces, like JavaDoc. Latex seems to be able to fill that role, there
is a wealth of experience using it, and now there is hevea, ocamlweb, and mldoc. 

I don't know enough about the state of SGML or XML tools to know how they
fare against my desires. I'm leaning to the Latex approach now.

-- Brian


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

Re: [Caml-list] CDK binary release

[Fabrice Le Fessant]

The main problem with CDK documentation is that the CDK is not
intented to develop the libraries it contains. This development is
done by libraries'authors, while the CDK job is to gather these
libraries (by adding common Makefiles and configuration scripts, with
minimal modifications to the files, in particular the interfaces to
allow easy/fast updates). Thus, we cannot force the authors to use
ocamlweb, LaTeX or anything else, nor modify the documentation they
gave. We can of course advise them to use one particular tool, but we
have to be able to support other documentation formats. Since most mli
files have only simple text documentation, cdk_doc is enough for that.

The best approach would probably be to have several documentation tools, and
for each library, to specify in the Makefile the corresponding tool
(ocamlweb + hevea, cdk_doc, ...). However, we need then to be sure
that all these tools have some common output formats (man, html, info,
ps, ...)  and formatting conventions (title colors, etc)

I'm not sure that HeVea should be distributed in the
CDK. It is not really a development tool. However, OcamlWeb could
be in the CDK since it is used for literate programming.

- Fabrice

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

Re: [Caml-list] CDK Documentation format

[Stefan Monnier]

>>>>> "Dave" == Dave Mason <dmason@sarg.Ryerson.CA> writes:
> one decent editor for MS-Windows; it's called emacs.)

I think for anyone using Emacs, documentation should be available in the
`info' format.  The best way to get that is to make sure that the original
format can be translated into TeXinfo.

What that format should be, I don't really care, but I think that a TeXinfo
output should be supported at least as well as an HTML output.


	Stefan "who has suffered enough with Perl's lack of `info' support."
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr

Re: [Caml-list] CDK binary release

[Stefan Monnier]

>>>>> "John" == John Max Skaller <skaller@ozemail.com.au> writes:
> 	Actually, it would be nice to have man pages for each
> Ocaml module. It is faster to say:
> 	man  ocaml-list
> to check the order of arguments to List.fold_left (newbie, aren't I :-)
> or the names (if using label mode) than fiddle around with a browser:
> and doesn't need a mouse.

But if you're working inside Emacs already, having the documentation in
info format would allow you to just do C-h TAB <funname> RET.


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

Re: [Caml-list] CDK binary release

[Olivier Andrieu]

 Fabrice Le Fessant [Monday 7 May 2001] :
 > We are pleased to announce a first (beta) binary release of the CDK for
 > Linux. This release can be downloaded from:
 > 
 > http://pauillac.inria.fr/cdk/
 > 
 > From this page, you can also have access to the documentation and the
 >  mailing-list.

... but the public CVS access doen't seem to work : 

$ cvs -d :pserver:anoncvs@camlcvs.inria.fr:/caml login
(Logging in to anoncvs@camlcvs.inria.fr)
CVS password: 
$ cvs -d :pserver:anoncvs@camlcvs.inria.fr:/caml -z3 co cdk
cvs server: cannot find module `cdk' - ignored
cvs [checkout aborted]: cannot expand modules
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr