The Scheme SRFIs are a collection of useful and portable Scheme code meant to provide commonly used functionality not included in the specification. The standard documentation format is HTML. For example, here is SRFI 1. While this format works fine, I am wondering if a Scribbled version would be a useful addition. Scribble is the tool used to document PLT Scheme. Here is an example of how their documentation looks.
Doing so would be pretty easy by implementing it as a PLaneT package; the documentation itself could be distributed via PLaneT or a simple file download for anyone interested.
What do you think?
While I do think it could be useful in certain situations, I also think that it’s important for the HTML at srfi.schemers.org to remain the official documentation. If SRFIs become too ingrained in PLaneT, then they just become more PLT-specific extensions rather than portable semi-official Scheme libraries. It’s important for the SRFI system to avoid even the appearance of favoring PLT over other Schemes.
Of course, given that the SRFI submission process requires that proposals conform to HTML 3.2, it’s unlikely that the SRFI editors would officially adopt something as newfangled as Scribble. So there probably isn’t much danger of new SRFI reference implementations being written in scribble/lp rather than vanilla Scheme.
Now, if someone were to submit Scribble itself as a new SRFI, that would be different (though I don’t know whether Scribble lends itself to a portable implementation; I have the impression that it’s pretty closely tied to PLT’s language system). It’d be nice for Scheme to have a standard method of documentation more sophisticated than comments. At the very least, something akin to Javadoc/Doxygen would be handy (Scribble might fill this role); CL-style docstrings available at runtime would be nice, too.
So… go for it, make Scribbled versions of the SRFI docs. Just make sure they clearly state that they’re not the authoritative versions of the text.
+1
A scribbled version of the SRFI docs would be very nice, provided, as Jamie pointed out, that it did not pretend to be the authoritative version. I wonder how easy it would be to autogenerate from the SRFI text?
Jamie:
A Scribble SRFI would be interesting; but no one seems to be promoting Scribble, nor are other implementers jumping on it. That SRFI would definitely be a prerequisite for the official docs cutting over, but I’m not imagining anything near that scope. Rather, something supplementary at best. They would include a clear disclaimer/warning as to their role.
Alexey:
Looking at the source code for SRFI 1:
http://srfi.schemers.org/srfi-1/srfi-1.html
Autogeneration looks very possible.
Based on looking at 3 other final SRFIs not written by Olin, though, it seems less likely.
Grant:
Actually, Scribble was just brought up a week or so ago on the Clozure Common Lisp mailing list as a potential tool to improve the CCL manual. So perhaps the Schemers have been ignoring it, but the Lispers have taken notice.
Hi Jamie:
Interesting.
Aziz did add preliminary support for Scribble to Ikarus but I’m not sure where it went from there:
http://groups.google.com/group/ikarus-users/browse_thread/thread/ab28d2b823ce812/51622fe5ee56e4f7?lnk=gst&q=Scribble