[erlang-questions] edoc: cross-referencing standard Erlang functions

[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@REDACTED>
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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20080717/bb811dfd/attachment.htm>