Previous week Up Next week

Hello

Here is the latest Caml Weekly News, for the week of February 14 to 21, 2012.

  1. interval trees
  2. browsing the code while reading the doc
  3. Some utilities about camlp4
  4. Other Caml News

interval trees

Archive: https://sympa-roc.inria.fr/wws/arc/caml-list/2012-02/msg00114.html

Continuing the thread from last week, Francois Berenger announced:
I did a naive implementation of interval trees for float intervals.

It is available here:
https://github.com/HappyCrow/interval-tree
      

browsing the code while reading the doc

Archive: https://sympa-roc.inria.fr/wws/arc/caml-list/2012-02/msg00116.html

Francois Berenger asked and bluestorm replied:
> It would be really cool when while looking at the HTML doc
> it would be possible to click somewhere so that the implementation
> code unrolls under the doc text.
> 
> Because sometimes the text is not explicit enough,
> some other times there is no text.
> 
> Hoogle has such feature and it was pretty useful when
> I was coding in Haskell (maybe especially useful
> because I was a beginner in that language), for example:
> 
> http://www.haskell.org/hoogle/?hoogle=map
> 
> Just click on map to have a look at the corresponding implementation.

We delegate documentation production to the standard ocamldoc tool,
which doesn't have this feature, so that is not really in the game
zone of batteries developers. That said, it *could* be possible to
make that feature available without changing ocamldoc upstream, by
implementing it as a custom documentation formatter -- ocamldoc has a
flexible architecture in this regard.
  http://caml.inria.fr/pub/docs/manual-ocaml/manual029.html#toc120

Xavier Clerc has some experience tuning ocamldoc (
http://argot.x9c.fr/ ;), maybe he could comment on the feasibility of
this. You could ask on the caml-list, maybe cc-ing him. If you wished
to have a try at it directly, looking at how Argot is implemented
would be a good source of inspiration.

(There used to be a custom documentation generator for Batteries, but
afaik. we mostly ditched it because, while it was nice, it made
documentation generation time impossibly slow...)
      
Maxence Guesdon suggested:
If you provide the .ml files to ocamldoc and use the -keep-code option,
generated html pages will give a link on each value to display the
corresponding code.

Another solution would be to adapt the odoc_literate custom generator you
can find here:
  https://gitorious.org/ocamldoc-generators
This generator provide an expand/collpase button for each value, useful when
writing doc in a literate programming way.

At last, since Dynlink now allows loading native code, ocamldoc now
supports loading custom generators compiled to native code, which may be
fast enough to use the batteries legacy generator.
      
Gerd Stolpmann also suggested:
Before you start writing a total new custom formatter (which probably
breaks with every major OCaml version because of new syntactic elements),
consider to extend/override the standard formatter. I did that quite
successfully for the PXP documentation. The derived formatter is here:

https://godirepo.camlcity.org/svn/lib-pxp/trunk/tools/src/odoc/chtml.ml

(Note that for current OCaml you need to remove the "{" from the matched
strings in html_of_custom_text.)

When I developed this, I found the documentation in the OCaml manual as
insufficient. You really need to dive into the sources of ocamldoc,
especially odoc_html.ml (which is lengthy but easy to get). I guess for
the effect you want you have to override
create_fully_qualified_{module_}idents_links. The location of a definition
in the source code seems to be in deed available, in the m_loc.loc_impl
values that are stored with the records for the various syntactic
elements. Don't know whether it is easy to do, though.
      

Some utilities about camlp4

Archive: https://sympa-roc.inria.fr/wws/arc/caml-list/2012-02/msg00153.html

bob zhang announced:
  the meta filter distributed with camlp4 is buggy and unmodular, I
put a modular one here
  http://seas.upenn.edu/~hongboz/meta_filter.zip

 building with syntax extension is really easy provided this file
  http://www.seas.upenn.edu/~hongboz/myocamlbuild.ml
It works with .inferred.mli, .pp.ml as well
      
Gabriel Scherer asked and Hongbo Zhang replied:
> I had trouble being sure what "meta filter" you were talking about.
> Here's what I found out, in case other people on the list wondered the
> same: the "meta" part of Camlp4 is about turning a value into a piece
> of OCaml AST representing the syntax of this value. The "meta" filter
> is a kind of type-conv plugin -- anterior to type-conv -- that reads
> the declarations of algebraic datatypes and adds declarations for
> functions doing that "meta" work on this datatype, taking values at
> this type and returning pieces of Camlp4 AST.

yes.

> If I understand correctly, here is the change you did -- maybe you
> should put this information in a README somewhere:
> instead of reading the type declarations in the whole file being
> filtered, you only read those contained in a so-called "trash module",
> whose name is configurable by the user (default Camlp4Trash). You then
> produce declarations for metafunctions on demand, as in the old code,
> but you *do not* reproduce the content of the "trash module" -- the
> type declarations.

Yes, so generally you will combined it with INCLUDE like this
module Trash = struct
  INCLUDE "xx.ml"
end
This could avoid linking camlp4 (very big) when you don't need it.
It will find all type definitions in xx.ml(not the last one). It's pretty
easy to mix with other syntax extensions now.

> Are there other notable differences between the two implementations?
> You said that the upstream one is "buggy", what kind of bugs did you
> encounter? It could be interesting to fix them upstream.

the meta_float, meta_int never compiles in the original distribution

> It looks like you are doing this new implementation to be able to have
> the meta-functions defined in a different module than the original
> type declaration. What are the advantages of doing this? Could you
> tell us a bit more about your initial motivations?

another piece, the original file Camlp4FiltersMetaFilter was quite
unreadable, and impossible to modify according to custom needs(at least
I found it hard to read and modify...)
      

Other Caml News

From the ocamlcore planet blog:
Thanks to Alp Mestan, we now include in the Caml Weekly News the links to the
recent posts from the ocamlcore planet blog at http://planet.ocamlcore.org/.

lablGtkOSXApplication:
  https://forge.ocamlcore.org/projects/lablgtkosx/

Spotlight on Opa app: OpaDo by Tristan Sloughter:
  http://blog.opalang.org/2012/02/spotlight-on-opa-app-opado-by-tristan.html

jingoo:
  https://forge.ocamlcore.org/projects/jingoo/

A work in progress: whenjobs - another cron replacement:
  http://rwmj.wordpress.com/2012/02/18/a-work-in-progress-whenjobs-another-cron-replacement/

New release: Opa 0.9.0 (S4):
  http://blog.opalang.org/2012/02/new-release-opa-090-s4.html
      

Old cwn

If you happen to miss a CWN, you can send me a message and I'll mail it to you, or go take a look at the archive or the RSS feed of the archives.

If you also wish to receive it every week by mail, you may subscribe online.


Alan Schmitt