[racket] Standard references in the docs

On 26 Jan 2013 15:44, "Matthias Felleisen" <matthias at ccs.neu.edu> wrote:
>
> We don't quite understand what exactly you mean. We believe you have a
> "related work" section in mind. Perhaps it would be best to mock up a
> few pages from the documentation so that we can see what exactly you have
> in mind.

I've sometimes wondered about this (although I've never _really_ needed to
know when a form was introduced); if you have an opportunity, Sun's C
manuals always had a table at the bottom with the C/posix standard that the
call came from; along with its MT safety and other attributes.

I have had to port software between so-called UNIX systems (SCO, HPUX,
Solaris, Linux); and it is very useful to know what to expect from which
standard, where.

This is from an environment where the behaviour of the software hinges
around a single #define. Brittle doesn't even begin to describe it!

> Having said that, I wonder whether what you really want some kind of
> "compatibility tool" that would help you check how "easy" it is to
> port programs to CL, R6RS, R5RS or other related languages. In principle,
> you can write R6RS code in DrRacket and Racket (using some incantation
> that I have forgotten) and then the program is guaranteed to be portable
> to that language.

In my experience above, just having the documentation is useful when
something goes wrong (either at build or, more often, run-time). Solaris
(the last target I ported to), which did a very good job of documenting the
API "on paper", did not have the automated tools need to warn/inform anyone
involved in working across standards.

Given a choice between tools and documentation, I'd vote "tools"on this
one! Although I fail to see how one could write the tools without making
the effort of gathering the history and compatibility of forms. It'd also
not be difficult, with the right tools, to embellish the documentation. So
it all falls out in the wash.

Tim

(Whenever I say "Sun", of course I mean Oracle. That's me living either in
the past, our in denial)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20130127/a926204f/attachment.html>