[Chicken-users] RFC: documentation lookup utility

[Toby Butzon]

Hi all,

My own tendancy when working with Chicken is to have a web browser
open with the R5RS index, the Chicken manual, relevant eggs, et cetera,
in separate tabs (in firefox), so lookups in the various documents are
(somewhat) convenient.

I've got some plans for a simplification of the above -- along the lines
of what I would personally find useful -- that I would make generally
available online. (It would be, after all, just a way of finding pointers
to the information that's already online.) I'll outline the idea below;
what I'm really interested in is (a) would you personally find the service
useful and (b) if this idea doesn't fit the way you work and and wouldn't
make things easier for you, I'm interested in hearing how you work -- I
personally can't code very long before I have to go lookup what arguments
a certain function takes, or to find a function that already exists to
accomplish some task.

So if you have a few minutes, I'd appreciate whatever feedback you could
send me. Feel free to reply off list (or on, but I'd rather not hijack
chicken-users :)).

The details of what I'm thinking now follow...

I've registered callcc.org, and it currently provides very rudimentary
shortcuts to the documents I mentioned before. For example,
<http://callcc.org/> redirects to Chicken's home page;
<http://callcc.org/r5rs/> redirects to the HTML R5RS on schemers.org;
<http://callcc.org/wiki/> redirects to galinha;
<http://callcc.org/wiki/users> redirects to galinha/users; and so on.
Some of these (/wiki/ for example) serve as wildcards: /wiki/ takes you
to / on galinha, while /wiki/users takes you to /users on galinha.

Now, my goal is this: Any callcc.org URL should try to take me
to something relevant. So I could use <http://callcc.org/apply>
and be taken directly to the R5RS blurb on apply (and likewise
everything indexed in the R5RS index would work). Similarly,
functions specific to Chicken should be made available:
<http://callcc.org/print> would take me to the Chicken manual on print
<http://galinha.ucpel.tche.br:8080/Unit%20library#print>. URLs that
don't exactly match (or don't return exactly 1 result) might instead
return a page of search results. (This is all inspired by php.net's
similarly functionality. Try <http://php.net/echo> to see an exact match
and <http://php.net/hex> for an example of search results related to
"hex".)

The Chicken manual part will probably require some indexing, which I
haven't quite decided how to do yet. (AFAICT, unlike R5RS, there isn't
an existing "index" of all of Chicken's functions that link into the
appropriate portions of the manual. A machine-generated index might be
sufficient, but I haven't decided exactly how yet. For instance, "print"
should always take me straight to the print function, but the print
function is no doubt mentioned in many places in the manual, and the
word "print" (not necessarily referring to the function) even more, so
the machine indexer would be lead to believe multiple results ought to
be displayed in a case where one result is clearly "correct".) I would
like to have eggs and any other relevant documentation included, too.

It all comes down to generating and maintaining the index, though; and
that's where I was hoping to gather some feedback. I'm considering
approaching this sequentially, as follows:
  * index functions first (R5RS, Chicken, eggs, ...)
  * maybe other somewhat structured things, like read syntax (#>! etc)
  * and finally a full-text index of R5RS, Chicken manual, egg
    documentation, and so on, to be consulted when a query doesn't
    exactly match the before-mentioned indexen.

The main difficulties I foresee are:
  * Is there any existing document with sufficient metadata as to give
    me a way to machine-generate the index of all of Chicken's
    functions? If not, I expect I will spend a little time manually
    generating this sort of data; it may be beneficial to embed it in
    the existing manual (sexprs in HTML comments?) or otherwise (a) make
    it generally available and (b) keep it up-to-date.
  * For eggs, the eggdoc source files might be enough (or come close; I
    haven't done enough research yet). It may be easy enough to pull
    out, e.g., foo from (procedure "(foo BAR BAZ)"), but HTML anchors will
    need to be added to the autogenerated output to make this be
    useful. Further, at least some of the eggs don't mention all of
    the functions they provide in the eggodc; but perhaps this
    shortcoming should rightly be fixed on their end.

Anyway, there's the gist of it.

Comments?

-- 
Toby Butzon