Re: more ideas (Re: [Caml-list] how could the community help with Oasis-DB;) towards a CPAN for OCaml?

[oliver <oliver@first.in-berlin.de>]

On Wed, Dec 14, 2011 at 04:37:26PM +0100, Gerd Stolpmann wrote:
> Am Mittwoch, den 14.12.2011, 15:55 +0100 schrieb oliver:
> > On Wed, Dec 14, 2011 at 01:14:57PM +0100, Gerd Stolpmann wrote:
> > > Am Dienstag, den 13.12.2011, 21:22 +0100 schrieb oliver:
> > > > Hello,
> > > > 
> > > > 
> > > > I again want to mention R.
> > > > 
> > > > The installation procdure for users is very easy.
> > > > What I also like there, is that the documentation
> > > > includes references to books, which explain the algorithms
> > > > or other background information.
> > > > Maybe thats too much of what is needed for OCaml.
> > > > 
> > > > But it's what I do like there.
> > > > 
> > > > Also R-packages necessarily need to be documented,
> > > > have a manpage / package description.
> > > > 
> > > > Not sure if this is necessary with OCaml stuff,
> > > > because *.mli files are there, and ocamlc -i could
> > > > print the interfaces of the modules, if nothing else is there
> > > > to rely on.
> > > > But maybe these kinds of minimalistic documentation-generation
> > > > could be created automatically by the installing tools.
> > > > 
> > > > Nicely printed html-docs for interfaces are very helpful.
> > > > 
> > > > And also nice would be, to have such nicely printed documentation
> > > > also available at the server, even before downloading any packages.
> > > > So, browsing a package documentation online could be done
> > > > before downloading the package.
> > > 
> > > docs.camlcity.org
> > [...]
> > 
> > Yes, I see.
> > There are these nice htmlized-docs.
> > 
> > But I meant that this kind of docs also should also be on
> > a CPAN-like server for OCaml.
> > So every package that is available there should also be
> > documented in this way.
> 
> Yes, it's a third party server. What's the problem?
[...]

if it offers a shell and the possibility to install OCaml
(or maybe the admin could od that), then there is no problem.

ocamlc -i   and  caml2html  can be used then to create the docs
automotically.


> 
> My thinking here is different: We should lower the barriers for packages
> as far as possible. We are not in the position of CPAN who can reject
> packages not conforming to a relatively high standard.

People who are able to program in OCaml also might be able to
add some additional simple textfiles for further informations,
if necessary. Some more docs would be fine.
But maybe that not even is necessary for a minmal set of docs.

The creation of the interface docs can be done as mentioned above.
Additionally there was a module (forgot the name, but could look for it),
which also displays the hierrchy of modules (which module uses which other modules).

All this could be deon automatically, if the server at least offers a shell
and OCaml.

Unpacking an archive, applying ocamlc and caml2html could be done automatically.

And if one looks at CTAN, there are some additional simple text files (package descriptions)
which help organizing this.

I think overengineering is not a good idea, but a minimal helping text file should be
possible for people who claim to program in OCaml.

For example there was/is the Linux Software Map; it's already forgotten by most
people, but once was a very useful tool... it doies exist today, but maybe not very
frequently used.
But there it was a simple text file with some informations about the software,
that was added and had a very simple format.
It was parsed automatically and created the data dfor the search catalog.

Thats btw. a lot less effort than clikcing around in so many menues
in the modern web driven software hosting possibilities.

I think it should be possible to add such a simple textfile.

If that is too much for OCaml programmrs, I doubt that any person ever will want
to use the software that will be hosted there.

I think there are enough very knowledgable people hacking in OCaml.

So this little barrier should be able to cross.




> 
> docs.camlcity.org does the best in this situation: If there is a manual,
> you can look at this. But if not, there is at least a pretty-printed
> interface, and you can search these interfaces.

That's what I meant.
Is this doc generated automatically?

That's what I was looking for.

And the module-hierarchy of a program could also be added.

But the people who upload their stuff should be encouraged to add documentation.
Maybe some tools could help there.

I like it that C-extensions to R necessarily need a documentation file.
I would not insist on such a thing for OCaml, but if you look at what
the result is, when looking at R-package documentation, this is convincing.
It uses - like classical unix manpages - certain topics, which will be checked
if they are used.

If OCaml stands for quality, why not insisting at least on  a minimal
kind of documentation?

Ciao,
   Oliver