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

[Xingzhi Pan]

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!

Pan, Xingzhi

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
> 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
>
> ________________________________________________________________
> erlang-questions mailing list. See http://www.erlang.org/faq.html
> erlang-questions (at) erlang.org
>
>