Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005533OCamlOCamldocpublic2012-03-12 09:242012-03-13 17:40
ReporterHendrik Tews 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0005533: Please provide an option for cross-referencing independent libraries
DescriptionPlease provide a way for cross-referencing the standard library
or other libraries. For instance, for

    (** Uses {!print_endline} *)
    let f () = print_endline "Hello"

    (** The toplevel {!GWindow} *)
    let top_window = GWindow.window ()

ocamldoc should capable of generating hypertext links to the
standard library and to the documentation of lablgtk2.

One way to solve this would be an option

   -xref mod1,...,modn url

where mod1, ..., modn are module identifiers whose ocamldoc
generated documentation is accessible at url.

Or

   -Idoc path url

where path is that location of the standard library or any other
library referenced with -I and url is its ocamldoc generated
documentation.
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0007044)
gasche (developer)
2012-03-12 10:16

I suppose a reasonable first step (or does it already work in some way?) would be to generate a link to a pathological-looking URL for references to modules that ocamldoc does not know about, such as XDOC(GWindow)#VALwindow, and let the user run a script over the generated HTML files to replace the XDOC(foo) by a convenient address.
(0007048)
guesdon (manager)
2012-03-12 16:33

I would be more in favor of loading a custom generator defining a new custom text, like

  method html_of_custom_text b s t =
      match s with
      | "{perv" -> self#print_link_to_pervasives b t
      | _ -> ()

Method print_link_to_pervasives could use the available functions to forge the correct url. An additional option created by the plugin could allow to choose the base url for the documentation to link to.

By now, the user can load only one custom generator, that is the custom generator can inherit only from the generators predefined in ocamldoc.

But in next release of OCaml, ocamldoc will allow to load various custom generators, each one being able to inherit not only from the basic predefined generator, but from the last generator previously loaded. That is it will be possible to combine various custom generators. Thanks to first class modules.

With this improvment, adding the required feature in a custom generator seems to me the better way to go (I may do it as an exercise to perform some test before the next release).
(0007049)
Hendrik Tews (reporter)
2012-03-12 17:09

custom text elements ... they are not documented, aren't they?

So if I understand right, a custom generator that inherits from
the builtin html generator can output crossreferences to other
libraries. One only has to use custom text elements for these
cross-library references, for instance

    (** Uses {xref stdlib !print_endline} *)
    let f () = print_endline "Hello"

and override html_of_custom_text appropriately.
(0007050)
guesdon (manager)
2012-03-12 17:26

That's it. And indeed, in this case "the doc is the code" :-/
You can find an example in
  https://gitorious.org/ocamldoc-generators/ocamldoc-generators/blobs/master/odoc_bib.ml [^]

In your case, you may not need to put '!' in front of prerr_endline. But you will have to pattern match on the text (here "stdlib prerr_endline") to find the elements you need to forge the correct url. You may use the syntax
  {xref [Stdlib] prerr_endline}
so that the text will be represented as something like
 [Odoc_info.Code "Stdlib" ; Odoc_info.Raw "prerr_endline"]
.
(0007056)
Hendrik Tews (reporter)
2012-03-13 16:34

Overriding html_of_custom_text works well for creating links
inside the documentation.

But how about

   type t = Int32.t

? Is there a similarly simple way to tell ocamldoc to link
"Int32.t" to its description in the documentation of the standard
library?
(0007057)
guesdon (manager)
2012-03-13 16:44

You can try to hack a new
      create_fully_qualified_module_idents_links
method to find "external" modules and add link to them.

- Issue History
Date Modified Username Field Change
2012-03-12 09:24 Hendrik Tews New Issue
2012-03-12 10:16 gasche Note Added: 0007044
2012-03-12 16:33 guesdon Note Added: 0007048
2012-03-12 17:09 Hendrik Tews Note Added: 0007049
2012-03-12 17:26 guesdon Note Added: 0007050
2012-03-13 16:34 Hendrik Tews Note Added: 0007056
2012-03-13 16:44 guesdon Note Added: 0007057
2012-03-13 17:40 doligez Reproducibility have not tried => N/A
2012-03-13 17:40 doligez Status new => acknowledged
2012-03-13 17:40 doligez Category OCaml documentation => OCamldoc


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker