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

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

[Francois Berenger]

-------- 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

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

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

[Maxence Guesdon]

Hello,

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.

Hope this helps,

Maxence

On Wed, 15 Feb 2012 16:58:49 +0900
Francois Berenger <berenger@riken.jp> wrote:

> -------- 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
> 
> 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
> 

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

[Gabriel Scherer]

My mistake, I wasn't aware or had forgotten this -- very useful indeed
-- feature.

Thanks, Vincent and Maxence, for the correction.

(Gabriel; sometimes "bluestorm", for historical reasons, and often "gasche".)

On Wed, Feb 15, 2012 at 9:44 AM, Maxence Guesdon
<maxence.guesdon@inria.fr> wrote:
> Hello,
>
> 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.
>
> Hope this helps,
>
> Maxence
>
> On Wed, 15 Feb 2012 16:58:49 +0900
> Francois Berenger <berenger@riken.jp> wrote:
>
>> -------- 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
>>
>> 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
>>
>
>
> --
> 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
>

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

[Gerd Stolpmann]

> -------- 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.

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

[Daniel Bünzli]

Le mercredi, 15 février 2012 à 10:55, Gerd Stolpmann a écrit :
> 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.  

It seems then that the best option for everyone would be to have a good standard formatter in the distribution per se. These days css is on the verge of becoming Turing complete (if not already) and if the right data's here a little bit of javascript may cater most needs.  

However currently, the html generated by the standard formatter is invalid and the content littered with presentational elements (e.g. br) or inconsistent markup which makes it a nightmare to process and style with css.

Best,

Daniel

P.S.  
With respect to the original request, I once asked to turn ocamldoc into a full html code browser. But the wish was not granted :
http://caml.inria.fr/mantis/view.php?id=4443

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

[Francois Berenger]

On 02/15/2012 08:20 PM, Daniel Bünzli wrote:
> [...]
> Best,
>
> Daniel
>
> P.S.
> With respect to the original request, I once asked to turn ocamldoc
 > into a full html code browser. But the wish was not granted :
> http://caml.inria.fr/mantis/view.php?id=4443

That's too bad.
doxygen can do this, for C++ code for example, and that's extremely
useful when discovering a large code base (not everybody has the
patience to run Eclipse).

Regards,
F.