> -------- 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.d...@gmail.com> > To: Francois Berenger <beren...@riken.jp> > CC: batteries-de...@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 <beren...@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-de...@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 g...@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. -- 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
