Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc

["Gerd Stolpmann" <info@gerd-stolpmann.de>]

> -------- Original Message --------
> Subject: Re: [Batteries-devel] browsing the code while reading the doc
> Date: Wed, 15 Feb 2012 08:47:42 +0100
> From: bluestorm <bluestorm.dylc@gmail.com>
> To: Francois Berenger <berenger@riken.jp>
> CC: batteries-devel@lists.forge.ocamlcore.org
>
> 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

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.

Gerd


>
> 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...)
>
> On Wed, Feb 15, 2012 at 6:01 AM, Francois Berenger <berenger@riken.jp>
> wrote:
>> Hello,
>>
>> 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.
>>
>> Regards,
>> F.
>>
>>
>> _______________________________________________
>> Batteries-devel mailing list
>> Batteries-devel@lists.forge.ocamlcore.org
>> https://lists.forge.ocamlcore.org/cgi-bin/listinfo/batteries-devel
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa-roc.inria.fr/wws/info/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>
>
>


-- 
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
*** Searching for new projects! Need consulting for system
*** programming in Ocaml? Gerd Stolpmann can help you.