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

[Dave Pawson]

2009/8/11 Mazen Harake <mazen.harake@REDACTED>:
> This brings up a subject I've been meaning to bring up for a while. The
> online documentation needs modernisation... A few things that come to mind
> are:
>
> * Proper documentation search (please don't insult this by saying Google...
> that's just stupid)

Define 'proper'?
Some sort of hierarchy?
  root/module/function?


> * Function overview in each module


Is http://erlang.org/doc/man/lists.html the 'description' section sufficient
or would you like to write more than that? Is that what you mean by
an overview?


> * Module summary on the modules page (and categorized) much like
> http://docs.python.org/3.1/library/index.html

This might match my definition of the 'description' above.

> * Add anchors to the HTML so that a link can go straight to a function

-1 on the grounds of size? Suggest go from module list to
the module itself, then have a toc in the module listing and linked
to the function itself?


> * Make HTML XHTML

:-)  Mmm. Less keen here. ns declaration buggers up some browsers.
Valid HTML I will agree with though.


> * More visually appealing. Probably this won't go very well with old-timers
> but frankly I have spoken to beginners in Erlang that say that when looking
> at the documentation it looks like something created 20 years ago and it
> doesn't look very... well... "appealing". The fact they are right about the
> age is not the point now is it ;) ?

Only if you can define 'appealing'. CSS decoration?


>
> Probably many more issues exist.... just saying.

I now have a 'process' whereby I have full access in one stylesheet to
all the module XML. (One file is broken, I've reported this to Joe).

So none of the above is difficult.
Once we have a clear definition of what's wanted.


HTH

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