Re: [Caml-list] CDK binary release

[Patrick M Doane <patrick@watson.org>]

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