[erlang-questions] Erlang documentation cleanup (PREV: R13B01 modules, quick reference)

[Dave Pawson]

Just picking up on one point Fred.
The XML source:

2009/8/11 Fred Hebert (MononcQc) <mononcqc@REDACTED>:

> I believe usability should come before beauty when talking about
> technical and formal documentation. An example of nice things to have
> would include links to other modules when they are mentioned and
> anchors for 'global' types in function signatures. Take the io:read/3
> function as an example: http://erlang.org/doc/man/io.html#read/3
>
> The io_device() type is defined on top of the page, but assuming
> you're coming from an anchor to the function, the type won't mean much
> to the reader. Most people, rather than scrolling up, would probably
> start a new search to find what 'io_device()' is about. Adding an
> internal anchor of the kind io.html#type-io_device could probably fix
> that. Then when the function 'file:open/2' is mentioned, no link is
> provided. The user is expected to go through the URLs or a new search
> to follow documentation. In ideal circumstances, reading the
> documentation should require no effort past trying to understand what
> is written.


The xml source has no 'inter module' linking.
A link base, some sort of standard xref or similar
would be a feature request for the current authors.
http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5UnivLinking
describes such a system.

That would be easy, once implemented.

regards







-- 
Dave Pawson
XSLT XSL-FO FAQ.
Docbook FAQ.
http://www.dpawson.co.uk