edoc: cross-referencing standard Erlang functions

[Edwin Fine]

I am documenting an application using edoc,  and I want to cross-reference a function in a standard Erlang application, say, //stdlib/gen_server:start_link/3, without hard-coding a URL like file:///usr/local/lib/erlang/lib/stdlib-1.15.3/doc/html/gen_server.html#start_link-3.

When I do this in edoc using the syntax //Application/Module:Function/Arity, it cross references gen_server within my application's directory, so the generated link does not work. I saw a reference to using edoc-info files, but couldn't find more detailed information other than edoc would use all edoc-info files on the path. I could find very few edoc-info files in the Erlang distro. I got the impression that all the existing Erlang docs would have to be generated using edoc to generate the appropriate edoc-info files, but they aren't.

I looked at the edoc docs and source code for 0.7.6 with no further enlightenment.

Is there some way to do this in edoc that I've missed?

--
The great enemy of the truth is very often not the lie -- deliberate, contrived and dishonest, but the myth, persistent, persuasive, and unrealistic. Belief in myths allows the comfort of opinion without the discomfort of thought.
John F. Kennedy 35th president of US 1961-1963 (1917 - 1963)
_______________________________________________
erlang-questions mailing list
erlang-questions@...
http://www.erlang.org/mailman/listinfo/erlang-questions

[Edwin Fine]

I am replying to my own question.

I did some more looking through the edoc code. It appears that the edoc documentation provided with the Erlang distribution uses some JavaScript tricks to make cross-app references work properly. There's a file named erlresolvelinks.js in the $ERLANG_HOME/doc directory. It appears to have been generated by a program, and maps the names of applications and modules to the correct documentation file. erlresolvelinks.js provides a single function named erlhref, which is called as follows:

javascript:erlhref(ups, appName, htmlFile);

Example:

{@link //kernel/file:read_file/1} in a .erl file corresponds to javascript:erlhref('../../../../', 'kernel', 'file.html#read_file-1');
in the the generated Erlang HTML for that .erl file - but not using the edoc that comes with the standard Erlang/OTP distribution (I am using R12B-3).

I searched the entire R12B-3 source distro and did not find the word "erlhref" in any of its files.

~/erlang/otp_src_R12B-3$ find . | xargs grep erlhref
~/erlang/otp_src_R12B-3$

I searched the installed release, just in case:

/usr/local/lib/erlang$ find . -name "*.html" -prune -o -print | xargs grep erlhref
./doc/erlresolvelinks.js:function erlhref(ups, app, rest) {
/usr/local/lib/erlang$

I added the option [{app_default, "/usr/local/lib/erlang/lib"}] to the call to edoc:application/3, but the generated cross references did not contain the version of the application and were therefore incorrect.

Example:

In edoc, //stdlib/gen_server:code_change/3 generates the link file:///usr/local/lib/erlang/lib/stdlib/doc/gen_server.html#code_change-3, which is incorrect (it should have been stdlib-1.15.3).

I don't know how the OTP team generated the Erlang docs, but it would be nice if I could have access to the same features.

Any ideas on this?

On Thu, Jul 17, 2008 at 3:16 PM, Edwin Fine <erlang-questions_efine@...> wrote:

I am documenting an application using edoc,  and I want to cross-reference a function in a standard Erlang application, say, //stdlib/gen_server:start_link/3, without hard-coding a URL like file:///usr/local/lib/erlang/lib/stdlib-1.15.3/doc/html/gen_server.html#start_link-3.

When I do this in edoc using the syntax //Application/Module:Function/Arity, it cross references gen_server within my application's directory, so the generated link does not work. I saw a reference to using edoc-info files, but couldn't find more detailed information other than edoc would use all edoc-info files on the path. I could find very few edoc-info files in the Erlang distro. I got the impression that all the existing Erlang docs would have to be generated using edoc to generate the appropriate edoc-info files, but they aren't.

I looked at the edoc docs and source code for 0.7.6 with no further enlightenment.

Is there some way to do this in edoc that I've missed?

--
The great enemy of the truth is very often not the lie -- deliberate, contrived and dishonest, but the myth, persistent, persuasive, and unrealistic. Belief in myths allows the comfort of opinion without the discomfort of thought.
John F. Kennedy 35th president of US 1961-1963 (1917 - 1963)

--
The great enemy of the truth is very often not the lie -- deliberate, contrived and dishonest, but the myth, persistent, persuasive, and unrealistic. Belief in myths allows the comfort of opinion without the discomfort of thought.
John F. Kennedy 35th president of US 1961-1963 (1917 - 1963)
_______________________________________________
erlang-questions mailing list
erlang-questions@...
http://www.erlang.org/mailman/listinfo/erlang-questions