* [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
@ 2012-02-15 7:58 Francois Berenger
2012-02-15 8:44 ` Maxence Guesdon
2012-02-15 9:55 ` Gerd Stolpmann
0 siblings, 2 replies; 6+ messages in thread
From: Francois Berenger @ 2012-02-15 7:58 UTC (permalink / raw)
To: caml-list
-------- 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
2012-02-15 7:58 [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc Francois Berenger
@ 2012-02-15 8:44 ` Maxence Guesdon
2012-02-15 10:51 ` Gabriel Scherer
2012-02-15 9:55 ` Gerd Stolpmann
1 sibling, 1 reply; 6+ messages in thread
From: Maxence Guesdon @ 2012-02-15 8:44 UTC (permalink / raw)
To: Francois Berenger; +Cc: caml-list
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
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
2012-02-15 7:58 [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc Francois Berenger
2012-02-15 8:44 ` Maxence Guesdon
@ 2012-02-15 9:55 ` Gerd Stolpmann
2012-02-15 11:20 ` Daniel Bünzli
1 sibling, 1 reply; 6+ messages in thread
From: Gerd Stolpmann @ 2012-02-15 9:55 UTC (permalink / raw)
To: Francois Berenger; +Cc: caml-list
> -------- 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
2012-02-15 8:44 ` Maxence Guesdon
@ 2012-02-15 10:51 ` Gabriel Scherer
0 siblings, 0 replies; 6+ messages in thread
From: Gabriel Scherer @ 2012-02-15 10:51 UTC (permalink / raw)
To: Maxence Guesdon, Vincent HUGOT; +Cc: Francois Berenger, caml-list
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
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
2012-02-15 9:55 ` Gerd Stolpmann
@ 2012-02-15 11:20 ` Daniel Bünzli
2012-02-16 2:11 ` Francois Berenger
0 siblings, 1 reply; 6+ messages in thread
From: Daniel Bünzli @ 2012-02-15 11:20 UTC (permalink / raw)
To: caml-list
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc
2012-02-15 11:20 ` Daniel Bünzli
@ 2012-02-16 2:11 ` Francois Berenger
0 siblings, 0 replies; 6+ messages in thread
From: Francois Berenger @ 2012-02-16 2:11 UTC (permalink / raw)
To: caml-list
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2012-02-16 2:12 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2012-02-15 7:58 [Caml-list] Fwd: Re: [Batteries-devel] browsing the code while reading the doc Francois Berenger
2012-02-15 8:44 ` Maxence Guesdon
2012-02-15 10:51 ` Gabriel Scherer
2012-02-15 9:55 ` Gerd Stolpmann
2012-02-15 11:20 ` Daniel Bünzli
2012-02-16 2:11 ` Francois Berenger
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).