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

[Mazen Harake]

I just realised that you might be thinking I was commenting on Your 
implementation?!? :-) I'm not, I'm commenting the official documentation 
:-) Your implementation just made me bring up something I had been 
meaning to bring up about the official one.

Btw, create links from your implementation so that when you click on the 
function name it takes you straight to the function.

Also, if I may ask, what does "-1" mean.... why are you using it? :P

/Mazen

Dave Pawson wrote:
> 2009/8/11 Mazen Harake <mazen.harake@REDACTED>:
>
>   
>>>> * 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.
>>     
>
> Sorry, I don't do javascript. If you can write it and host it... and update it?
>
>
>
>
>   
>>>       
>>>> * 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... :)
>>     
>
> -1, space constraints again. You have that in the current documentation.
>
>
>   
>>>       
>>>> * 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
>>     
>
> None to me. Could you write it?
>
>  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
>>     
>
> Proposal then please.
>
>
>
>
>   
>>>> * 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.
>>     
>
> Not from me.
>
>
>   
>>>       
>>>> * 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.
>>     
>
> I'm at home here. It isn't. It's namespaced.
> 'properly formatted'? I do provide well formed XML, which happens
> to be html (i.e. SGML to the html DTD), which may suite.
>
>
>
>   
>>>       
>>>> * More visually appealing.
>>>>         
>
>   
>>> Only if you can define 'appealing'. CSS decoration?
>>>
>>>
>>>       
>> Yes. No need for images etc, but perhaps a theme... The good'ol "scratch" is
>> ugly.
>>     
>
> ?? Not understood.
>
>
> regards
>
>
>
>