Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Please provide an option for cross-referencing independent libraries #5533

Closed
vicuna opened this issue Mar 12, 2012 · 7 comments
Closed

Please provide an option for cross-referencing independent libraries #5533

vicuna opened this issue Mar 12, 2012 · 7 comments

Comments

@vicuna
Copy link

vicuna commented Mar 12, 2012

Original bug ID: 5533
Reporter: Hendrik Tews
Status: acknowledged (set by @damiendoligez on 2012-03-13T16:40:20Z)
Resolution: open
Priority: normal
Severity: feature
Category: ocamldoc
Monitored by: @gasche @hcarty @dbuenzli

Bug description

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

@vicuna
Copy link
Author

vicuna commented Mar 12, 2012

Comment author: @gasche

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 ..., and let the user run a script over the generated HTML files to replace the XDOC(foo) by a convenient address.

@vicuna
Copy link
Author

vicuna commented Mar 12, 2012

Comment author: @zoggy

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

@vicuna
Copy link
Author

vicuna commented Mar 12, 2012

Comment author: Hendrik Tews

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.

@vicuna
Copy link
Author

vicuna commented Mar 12, 2012

Comment author: @zoggy

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

@vicuna
Copy link
Author

vicuna commented Mar 13, 2012

Comment author: Hendrik Tews

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?

@vicuna
Copy link
Author

vicuna commented Mar 13, 2012

Comment author: @zoggy

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

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant