edoc - how to set up links?

[Richard Carlsson]

Ulf Wiger (AL/EAB) wrote:
> Looking at some generated edoc files, I'm wondering
> how one is supposed to set up working references to 
> e.g. OTP's html pages.
> 
> Per default, edoc creates references to http://www.erlang.org/edoc/doc/
> etc., but those don't seem to work.

Well, that was just a sort of hopeful guess that I might be able to
convince the OTP folks to generate edoc files for all standard libraries
and put it up at a default location. Come to think about it, it might
have worked better if I had actually told them about this bold and
cunning plan...

> It also has a utility function, 
> edoc_lib:find_doc_dirs(), that searches the code path for doc/ directories
> relative to the ebins. For the doc directories to count, they must contain
> an 'edoc-info' file, but none of the OTP applications, at least in R10B-2
> (or the latest commercial build) have such files, as far as I can tell.
> 
> Is there a generally accepted, or at least recommended, procedure?

Perhaps you can't call it a "procedure", but you can easily generate
the docs for an application, like this:

  Eshell V5.5  (abort with ^G)
  1> edoc:application(kernel).
  2> edoc:application(stdlib).
  3> ...

(Then have a look in lib/<app-dir>/doc/.)

Of course, there's no actual edoc markup in those library files,
but at least you get a list of modules and their functions (and
often you get good usage hints from the parameter names).

If your own source files actually contain cross-references between
applications, you need to generate the docs twice to make sure you
get all the references right.

I meant to automate this even further, together with some nice
index page generation, but I didn't find the time. However,
it should already be somewhat usable as it is.

	/Richard

PS. I've actually done a little edoc hacking lately, so perhaps this
stuff will also be improved in the somewhat near future. One thing is
already done: automatic paragraph breaking - no need for <p>...</p>!