0005533: Please provide an option for cross-referencing independent libraries

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

Relationships