[erlang-questions] edoc hack to cross-reference standard Erlang OTP docs

[Edwin Fine]

I have hacked together a modification to edoc_lib.erl that takes the list of
directories returned by code:get_path() and adds the corresponding HTML
directories to the list of apps that edoc will create cross-reference links
for. This seems to work well for my needs, which are explained in the
earlier posts I made. I don't claim that my hack is production ready or
works in all situations, but it could be a basis to modify edoc if someone,
who may or may not be named Richard, likes the approach. I've attached the
edoc_lib.erl source code, which is from R12B-3, in case anyone who builds
Erlang from source wants to try it out.


On Thu, Jul 17, 2008 at 6:44 PM, Edwin Fine <erlang-questions_efine@REDACTED>
wrote:

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



-- 
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/20080719/bccf36a7/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: edoc_lib_mod.tar.gz
Type: application/x-gzip
Size: 9120 bytes
Desc: not available
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20080719/bccf36a7/attachment.bin>