[erlang-questions] Erlang documentation cleanup (PREV: R13B01 modules, quick reference)
Tue Aug 11 08:56:35 CEST 2009
As a beginner in Erlang, I have to say that the strangest thing in Erlang
doc is that there is no index! I can't even look up a function by name!
2009/8/11 Dave Pawson <dave.pawson@REDACTED>
> 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
> > are:
> > * Proper documentation search (please don't insult this by saying
> > that's just stupid)
> Define 'proper'?
> Some sort of hierarchy?
> > * Function overview in each module
> Is http://erlang.org/doc/man/lists.html the 'description' section
> 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
> > but frankly I have spoken to beginners in Erlang that say that when
> > 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
> > 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.
> Dave Pawson
> XSLT XSL-FO FAQ.
> Docbook FAQ.
> erlang-questions mailing list. See http://www.erlang.org/faq.html
> erlang-questions (at) erlang.org
More information about the erlang-questions