Re: [Chicken-users] RFC: documentation lookup utility

[Toby Butzon]

Hi Brandon,

Thanks for the feedback.

On Sat, Aug 12, 2006 at 08:59:19PM -0700, Brandon J. Van Every wrote:
> Typing a word into a URL is not really the kind of documentation I 
> want.  I want to click on a word in the editor I'm using and be taken to 
> relevant documentation.  I don't want to use my brain, I want the 
> computer to do that.

I agree with you that editor-integrated documentation is nice. I haven't
seen anything like that for Chicken yet, and even when it exists, I'll
still find the browser-based approach useful. It'd certainly bring
Chicken bragging rights to have both. :)

The common problem seems to be that both ideas would need an accurrate,
well-maintained index of function names and [a pointer to or actual
content of] the associated documentation. Knocking it out in one swing
for both of us would be really nice. Although... Being able to fetch
a blurb (instead of a link) might actually take a little more work. The
R5RS functions are grouped with many on a single page, so it might be
difficult to determine the appropriate boundaries for the blurb. In my
application, the browser would handle this by starting the user off in
the right place and they can read what they want. In an IDE, it might be
unmanagable to get back more than a paragraph or so -- or you might just
want the (func foo bar baz) synopsis to remind you of the arguments. We
could possibly solve this by adding more metadata during the indexing
process -- mark up not only the procedure and its arguments, but also
give a description of it that would allow programs to know where the
end of the text about each function is. 

Did you have plans for where the data for each function would come from
for your application? And are you planning to provide just the argument
list or also a description of the function? I would be happy to combine
efforts on this indexing/retrieval problem if our needs really do overlap.

-- 
Toby Butzon