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

[Mazen Harake]

Comments inline:

/Mazen

Dave Pawson wrote:
> 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?
>   
hierarchy would help in my manual search sure. I was thinking in lines 
of; I want to get a function that does this or that so I search the 
module/function names and descriptions and get results directly related 
to the documentation, not erlang-mailing list stuff etc. To get an idea 
of what I want go to http://docs.python.org/3.1/search.html and enter 
"read" (wo quotes) and then press search.
>
>   
>> * 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?
>   
I want in that part of the page a list of functions (much like edoc) 
which says "foo/1      | blablabla" if this can't be done then skip the 
"blablabla" part, but just please give me an overview of the functions 
in the module... :)
>
>   
>> * 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.
>   
No, I meant more like: "1 File system modules > 1.1 filelib 1.2 filename 
1.3 file" etc. so that If I am looking (manually) for a function that 
has to do with say tracing then I know in which category I can look in. 
I don't know to what extent this makes sense but it feels like it would 
shorten the time to search for a specific function. One huge list of 
modules that really don't say anything (except for hint in name) until 
you click on the page is very annoying in the sense that my browser's 
back button is getting worn out :D
>   
>> * 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?
>
>   
well... I just want anchors inside the HTML document itself so that me 
personally (or anyone else) linking to it can link straight to the 
function in question.
>   
>> * Make HTML XHTML
>>     
>
> :-)  Mmm. Less keen here. ns declaration buggers up some browsers.
> Valid HTML I will agree with though.
>   
Well... XHTML is just properly formed HTML... afaik... more or less anyway.
>
>   
>> * 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?
>
>   
Yes. No need for images etc, but perhaps a theme... The good'ol 
"scratch" is ugly.
>   
>> 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
>
>