[plt-scheme] scribblings on PLT Scheme 4.0

Can we get some information on scribble?  Does it make sense for
developers to migrate our own documentation to get ready for PLT Scheme
4.0?

Doug

-----Original Message-----
From: plt-scheme-bounces at list.cs.brown.edu
[mailto:plt-scheme-bounces at list.cs.brown.edu] On Behalf Of Matthew Flatt
Sent: Wednesday, May 23, 2007 9:02 PM
To: plt-scheme at list.cs.brown.edu
Subject: [plt-scheme] scribblings on PLT Scheme 4.0

For those who use the SVN trunk, you'll see a new collection called
"scribblings". Running Setup PLT will install new "doc" sub-directories
called "reference", "guide", "quick", and "scribble".

These new pieces are the first steps toward PLT Scheme 4.0, which will
be about new documentation more than anything else.

  *** The draft documents aren't ready to read, yet! ***

But we're going to work on them in the SVN trunk, anyway, so you can
see what's happening. And, here's what's happening, so far:

 * The "quick" introduction is the most complete as a draft (but, I
   emphasize again, it's a draft), because it's short.

 * The "guide" is intended as a starting point for new PLT Scheme
   users, as well as the (long-missing) high-level overview of
   everything in PLT Scheme. (Did I mention that it's a draft?)

 * The "reference" manual is not really there, yet, other than as a
   target for some hyperlinks, and as experiment to see how much we
   have to write to make the specification self-contained.

 * The "scribble" manual is a rough start at documenting the new
   documentation system.


At the language level, we are considering a few changes for version
4.0. The most significant are:

 * Pairs will become immutable by default. This is the big change that
   will break backward compatibility. We can provide a compatibility
   `mzscheme' library, but we can't do that for all the libraries whose
   public interface mentions lists.

 * We'll re-organize the libraries. This may affect
   backward-compatibility, too, but we should be able to leave
   compatability libraries in place for a while. Most likely, there
   will be "small", "medium", and "large" base languages to replace the
   current `mzscheme' language.

 * As a mater of style, we switch to `#module' instead of `(module
   ...)'.

That last bullet is a topic on its own. We imagine writing source files
that contain

  #module <language>
  ...

instead of

 (module <modname> <language>
   ...)

At the `read' level, `#module' is a new reader form that takes the
content of the file (and wraps it with a suitable `(module ...)', where
the module name is derived from the enclosing file.

The <language> will somehow specify the read syntax, the `module'-level
language, the printer (to use at run time when this module is the main
program module), and perhaps even syntax coloring and indentation rules
for an editor.

Whatever the syntax of the <language> that follows #module, we want it
to be so lightweight that you'd never think of using the "MzScheme",
"MrEd", or "Pretty Big" languages in DrScheme ever again. Instead,
you'd write

  #module large
  (define (my-simple-program x) x)
  (my-simple-program 5)

or

  #module large-gui
  (message-box "Number" "Five!")

even in the simplest of scripts. 


In general, v4.0 will be more compatible with the v300 series than v300
was with v200 (which was a smaller jump than v100 to v200, and so on).
The parenthesized `module' form always work, and a lot of code that
doesn't try to mutate pairs should run fine.

My best guess is that we'll start making backward-incompatible changes
to PLT Scheme in an SVN branch in August, and that branch will move to
the trunk in September or October. We'll work on the docs, meanwhile,
and they'll tend to describe the planned 4.0 instead of 370.x.

Matthew

_________________________________________________
  For list-related administrative tasks:
  http://list.cs.brown.edu/mailman/listinfo/plt-scheme