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

[Dave Pawson]

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



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