new guide chapter on Scheme dialects, and small clean-up for some other docs

svn: r12926

collects/frtime/frtime.scrbl

@@ -14,7 +14,7 @@
 
 @author["Greg Cooper"]
 
-The @scheme[frtime.ss] language supports declarative construction of
+The @schememodname[frtime] language supports declarative construction of
 reactive systems in a syntax very similar to that of MzScheme.  To
 interact with FrTime, select FrTime from the "Choose Language" menu.
 You can also make FrTime the language for a module:

collects/planet/planet.scrbl

@@ -16,10 +16,6 @@
 
 @author["Jacob Matthews"]
 
-@PLaneT is PLT Scheme's centralized package repository. It consists of
-two parts: , which contains packages contributed by users, and
-the @PLaneT client, which is built in to PLT Scheme.
-
 The @PLaneT system is a method for automatically sharing code packages,
 both as libraries and as full applications, that gives every user of a
 @PLaneT client the illusion of having a local copy of every code
@@ -60,7 +56,7 @@ package (a library for interacting with the
 @link["http://www.postgresql.org/"]{PostgresQL} database), as of this
 writing you would copy and paste the line:
 
-@scheme[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
+@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
 
 into your program. This line requires the file @filepath{spgsql.ss} in package
 version 2.3 of the @filepath{spgsql.plt} package written by
@@ -72,7 +68,7 @@ installed. Second, it requires the module in file @filepath{spgsql.ss}
 from that package, making all of its exported bindings available for use.
 
 Unlike with most package-distribution systems, package downloading and
-installation in PLaneT is @italic{transparent} --- there's no need for
+installation in PLaneT is @emph{transparent}: there's no need for
 you to do anything special the first time you want to use a package,
 and there's no need for you to even know whether or not a particular
 package is installed on your computer or the computers where your code
@@ -80,10 +76,10 @@ will be deployed.
 
 @subsection{Shorthand Syntax}
 
-As of PLT Scheme version 4.0, the code snippet in section
+As of PLT Scheme version 4.0, the code snippet above can also be
-@secref{finding-a-package} can also be written using a new shorter syntax:
+written using a new shorter syntax:
 
-@scheme[(require (planet schematics/spgsql:2:3/spgsql))]
+@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))]
 
 The two forms behave identically. In the abbreviated syntax, however,
 it is illegal to write the trailing @scheme{.ss} suffix on the file
@@ -108,11 +104,11 @@ number that encodes backwards-compatibility information.}
 
 The most basic planet require line, which is what is used in the form
 
-@scheme[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
+@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
 
 in longhand notation, or 
 
-@scheme[(require (planet schematics/spgsql:2:3/spgsql))]
+@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))]
 
 in shorthand notation, should be read ``Require from PLaneT
 @italic{any} release of Schematics' @filepath{spgsql.plt} package that
@@ -121,11 +117,11 @@ package version used is determined by @seclink["search-order"]{the
 PLaneT search order}.) To signal this explicitly, it is possible to
 write
 
-@scheme[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 (+ 3))))]
+@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 (+ 3))))]
 
 or
 
-@scheme[(require (planet schematics/spgsql:2:>=3/spgsql))]
+@schemeblock[(require (planet schematics/spgsql:2:>=3/spgsql))]
 
 both of which mean the same thing as the first pair of require lines.
 
@@ -148,11 +144,12 @@ in third-party libraries was already working around. In those cases,
 it may help to make use of the ``upper bound'' form of the planet
 require, in longhand form:
 
-@scheme[(require (planet "reduction-semantics.ss" ("robby" "redex.plt" 4 (- 3))))]
+@schemeblock[(require (planet "reduction-semantics.ss" 
+                              ("robby" "redex.plt" 4 (- 3))))]
 
 and using shorthand notation:
 
-@scheme[(require (planet robby/redex:4:<=3/reduction-semantics))]
+@schemeblock[(require (planet robby/redex:4:<=3/reduction-semantics))]
 
 In this require line, any version of the package @filepath{redex.plt}
 from package version 4.0 to package version 4.3 will match the require
@@ -163,11 +160,11 @@ which package is actually loaded).
 It is also possible to specify both an upper and a lower bound, using
 the planet require's ``range'' form:
 
-@scheme[(require (planet "test.ss" ("schematics" "schemeunit.plt" 2 (9 10))))]
+@schemeblock[(require (planet "test.ss" ("schematics" "schemeunit.plt" 2 (9 10))))]
 
 or
 
-@scheme[(require (planet schematics/schemeunit:2:9-10/test))]
+@schemeblock[(require (planet schematics/schemeunit:2:9-10/test))]
 
 This form matches any package in the specified range (inclusive on
 both ends), in this example the specifications match either package
@@ -180,11 +177,11 @@ a package as a special case (choosing the upper and lower bounds to be
 equal), but this is a common enough case that it has special support
 with the ``exact-match'' form:
 
-@scheme[(require (planet "unzip.ss" ("dherman" "zip.plt" 2 (= 1))))]
+@schemeblock[(require (planet "unzip.ss" ("dherman" "zip.plt" 2 (= 1))))]
 
 or
 
-@scheme[(require (planet dherman/zip:2:=1/unzip))]
+@schemeblock[(require (planet dherman/zip:2:=1/unzip))]
 
 match only the exact package version 2.1 of the @filepath{zip.plt} package.
 
@@ -384,25 +381,39 @@ within the PLaneT archive named by <plt-file>, to the standard output port.
 
 This command does not unpack or install the named .plt file.
 
+@section[#:tag "hash-lang-planet"]{The @schememodname[planet] Language}
+
+@defmodulelang[planet]
+
+When used with @hash-lang[], @schememodname[planet] must be followed
+by a short-form PLaneT path. The path is used in the same way that
+@hash-lang[] uses plain identifiers: @schemeidfont{/lang/reader} is
+added to the given path to determine a module that supplies a module
+reader.
+
+The @schememodname[planet] module (as opposed to the reader used with
+@hash-lang[]) implements the @exec{planet} command-line tool.
+
 @section{Utility Libraries}
 
 The planet collection provides configuration and utilities for using PLaneT. 
 
-@subsection{config.ss: Client Configuration}
+@subsection{Client Configuration}
-
-The config.ss library provides several parameters useful for configuring how
-PLaneT works. 
-
-Note that while these parameters can be useful to modify
-programmatically, PLaneT code runs at module-expansion time and so
-most user programs cannot set them until PLaneT has already
-run. Therefore to meaningfully change these settings it is best to
-manually edit the config.ss file.
 
 @defmodule[planet/config]
 
+The @schememodname[planet/config] library provides several parameters
+useful for configuring how PLaneT works.
+
+Note that while these parameters can be useful to modify
+programmatically, PLaneT code runs at module-expansion time, so
+most user programs cannot set them until PLaneT has already
+run. Therefore, to meaningfully change these settings, it is best to
+manually edit the config.ss file.
+
 @defparam[PLANET-DIR dir path-string?]{
-The root PLaneT directory. If the environment variable PLTPLANETDIR is
+The root PLaneT directory. If the environment variable 
+@indexed-envvar{PLTPLANETDIR} is
 set, default is its value; otherwise the default is the directory in
 which @filepath{config.ss} is found.}
 
@@ -455,33 +466,42 @@ The port on the server the client should connect to if
 @scheme[USE-HTTP-DOWNLOADS?] is @scheme[#f]. The default value for this parameter is
 @scheme[270].}
 
-@subsection[#:tag "util.ss"]{util.ss: Utilities}
+@subsection[#:tag "util.ss"]{Utilities}
 
-The @filepath{util.ss} library supports examination of the pieces of
+@defmodule[planet/util]
+
+The @schememodname[planet/util] library supports examination of the pieces of
 PLaneT. It is meant primarily to support debugging and to allow easier
 development of higher-level package-management tools. The
 functionality exposed by @seclink["cmdline"]{the @exec{planet} command-line tool} is
 also available programmatically through this library.
 
-@defmodule[planet/util]
-
 @defproc[(download/install-pkg [owner string?]
 			       [pkg string?]
 			       [maj natural-number/c]
 			       [min natural-number/c])
-         (or/c pkg? false/c)]{
+         (or/c pkg? #f)]{
 Downloads and installs the package specifed by the given owner name,
 package name, major and minor version number. Returns false if no such
 package is available; otherwise returns a package structure for the
 installed package.}
 
 @defparam[current-cache-contents contents
-          ((string? ((string? ((natural-number/c (natural-number/c ...)) ...)) ...)) ...)]{
+          (listof
+           (list/c string? 
+                   (listof 
+                    (list/c string? 
+                            (cons/c natural-number/c 
+                                    (listof natural-number/c))))))]{
 Holds a listing of all package names and versions installed in the
 local cache.}
 
 @defproc[(current-linkage)
-         ((path-string? (string? (string?) natural-number/c natural-number/c) ...) ...)]{
+         (listof (list/c path-string? 
+                         (list/c string?
+                                 (list/c string?) 
+                                 natural-number/c
+                                 natural-number/c)))]{
 Returns the current linkage table.
 
 The linkage table is an association between file locations (encoded as path strings)
@@ -489,7 +509,8 @@ and concrete planet package versions. If a require line in the associated file r
 this table is consulted to determine a particular concrete package to satisfy the request.}
 
 @defproc[(make-planet-archive [directory path-string?]
-                              [output-file (or/c path? path-string?) (string-append (path->string name) ".plt")]) 
+                              [output-file (or/c path? path-string?) 
+                                           (string-append (path->string name) ".plt")]) 
          path-string?]{
 Makes a .plt archive file suitable for PLaneT whose contents are all
 files in the given directory and returns that file's name.  If the

collects/r5rs/r5rs.scrbl

@@ -161,7 +161,7 @@ containing the bindings of @schememodname[r5rs].  Procedure values are
 installed into the namespace using @scheme[namespace-require/copy], so
 that they can be redefined.
 
-The @scheme[scheme-null-environment] function returns a namespace
+The @scheme[null-environment] function returns a namespace
 containing the syntactic forms of @schememodname[r5rs], not including
 @scheme[#%module-begin] (which is not useful outside of a module).
 

collects/r6rs/scribblings/r6rs.scrbl

@@ -9,6 +9,7 @@
                      rnrs/conditions-6
                      rnrs/io/simple-6
                      rnrs/r5rs-6
+                     r6rs
                      (only-in scheme/base
                               lib
                               current-library-collection-paths
@@ -167,6 +168,41 @@ are searched in order, and before the installation's collections.
 
 @; ----------------------------------------
 
+@section[#:tag "r6rs-mod"]{@|r6rs| Module Language}
+
+@defmodulelang[r6rs]
+
+The @schememodname[r6rs] language is usually used in the form
+@schememetafont{#!}@schememodname[r6rs], which is equivalent to
+@scheme[#, @hash-lang[] #, @schememodname[r6rs]] and is also valid
+@|r6rs| syntax.
+
+The @schememodname[r6rs] module language provides only a
+@schemeidfont{#%module-begin} binding, which is used to process the
+entire module body (see @scheme[module]). It allows the body of a
+module to use the syntax of either a @|r6rs| library or a @|r6rs|
+top-level program.
+
+@defform*[#:literals (library import export)
+          [(#%module-begin 
+            (library library-name 
+              (export export-spec ...)
+              (import import-spec ...)
+              library-body ...))
+           (#%module-begin
+            (import import-spec ...)
+            program-body ...)]]{
+
+An @schememodname[r6rs] module that contains a single @scheme[library]
+form defines an @|r6rs| library, while a module body that starts with
+an @scheme[import] form defined an @|r6rs| top-level program.
+
+The @scheme[library], @scheme[export], and @scheme[import] identifiers
+are not exported by the @schememodname[r6rs] library; they are
+recognized through equivalence to unbound identifiers.}
+
+@; ----------------------------------------
+
 @section[#:tag "libpaths"]{Libraries and Collections}
 
 An @|r6rs| library name is sequence of symbols, optionally followed by

collects/scribblings/guide/compile.scrbl

@@ -14,7 +14,7 @@ So far, we have talked about three main PLT Scheme executables:
        running PLT Scheme programs (and that can be used as a
        development environment in interactive mode);}
 
- @item{@exec{mred}, which is like @scheme{mzscheme}, but for GUI
+ @item{@exec{mred}, which is like @exec{mzscheme}, but for GUI
        applications.}
 
 ]

collects/scribblings/guide/dialects.scrbl

@@ -0,0 +1,155 @@
+#lang scribble/doc
+@(require scribble/manual
+          "guide-utils.ss")
+
+@(define r6rs @elem{R@superscript{6}RS})
+@(define r5rs @elem{R@superscript{5}RS})
+
+@title[#:tag "dialects" #:style 'toc]{Dialects of Scheme}
+
+PLT Scheme is one dialect of the Scheme programming language, and
+there are many others. Indeed, ``Scheme'' is perhaps more of an idea
+than a specific language.
+
+The @hash-lang[] prefix on modules is a particular feature of PLT
+Scheme, and programs that start with @hash-lang[] are unlikely to run
+in other implementations of Scheme. At the same time, programs that do
+not start with @hash-lang[] (or another PLT Scheme module form) do not
+work with the default mode of most PLT Scheme tools.
+
+``PLT Scheme'' is not, however, the only dialect of Scheme supported
+by PLT Scheme tools. On the contrary, PLT Scheme tools are designed to
+support multiple dialects of Scheme and even multiple languages, which
+allows the PLT Scheme tool suite to serve multiple communities. PLT
+Scheme also gives programmers and researchers the tools they need to
+create new and improved languages.
+
+@local-table-of-contents[]
+
+@; --------------------------------------------------
+
+@section[#:tag "standards"]{Standards}
+
+Standard dialects of Scheme include the ones defined by @|r5rs| and
+@|r6rs|.
+
+@subsection{@|r5rs|}
+
+``@|r5rs|'' stands for @link["../r5rs-std/index.html"]{The
+Revised@superscript{5} Report on the Algorithmic Language Scheme}, and
+it is currently the most widely implemented Scheme standard.
+
+PLT Scheme tools in their default modes do not conform to @|r5rs|,
+mainly because PLT Scheme tools generally expect modules, and @|r5rs|
+does not define a module system. Typical single-file @|r5rs| programs
+can be converted to PLT Scheme programs by prefixing them with
+@scheme[#, @hash-lang[] #, @schememodname[r5rs]], but other Scheme
+systems do not recognize @scheme[#, @hash-lang[] #,
+@schememodname[r5rs]] (which is not part of the @|r5rs| standard). The
+@exec{plt-r5rs} executable more directly conforms to the @|r5rs|
+standard.
+
+Aside from the module system, the syntactic forms and functions of
+@|r5rs| and PLT Scheme differ. Only simple @|r5rs| become PLT Scheme
+programs when prefixed with @scheme[#, @hash-lang[] scheme], and
+relatively few PLT Scheme programs become @|r5rs| programs when a
+@hash-lang[] line is removed. Also, when mixing ``@|r5rs| modules''
+with PLT Scheme modules, beware that @|r5rs| pairs correspond to PLT
+Scheme mutable pairs (as constructed with @scheme[mcons]).
+
+See @other-manual['(lib "r5rs/r5rs.scrbl")] for more
+information about running @|r5rs| programs with PLT Scheme.
+
+@subsection{@|r6rs|}
+
+``@|r6rs|'' stands for @link["../r6rs-std/index.html"]{The
+Revised@superscript{6} Report on the Algorithmic Language Scheme},
+which extends @|r5rs| with a module system that is similar to the PLT
+Scheme module system.
+
+When an @|r6rs| library or top-level program is prefixed with
+@schememetafont{#!}@schememodname[r6rs] (which is valid @|r6rs|
+syntax), then it can also be used as a PLT Scheme program. This works
+because @schememetafont{#!} in PLT Scheme is treated as a shorthand
+for @hash-lang[] followed by a space, so
+@schememetafont{#!}@schememodname[r6rs] selects the
+@schememodname[r6rs] module language. As with @|r5rs|, however, beware
+that the syntactic forms and functions of @|r6rs| differ from PLT
+Scheme, and @|r6rs| pairs are mutable pairs.
+
+See @other-manual['(lib "r6rs/scribblings/r6rs.scrbl")] for more
+information about running @|r6rs| programs with PLT Scheme.
+
+@; --------------------------------------------------
+
+@section[#:tag "more-hash-lang"]{More PLT Schemes}
+
+Like ``Scheme'' itself, even ``PLT Scheme'' is more of an idea about
+programming languages than a language in the usual sense. Macros can
+extend a base language (as described in @secref["macros"]), but macros
+and alternate parsers can construct an entirely new language from the
+ground up.
+
+The @hash-lang[] line that starts a PLT Scheme module declares the
+base language of the module. By ``PLT Scheme,'' we usually mean
+@hash-lang[] followed by the base language @schememodname[scheme] or
+@schememodname[scheme/base] (of which @schememodname[scheme] is an
+extension). The PLT Scheme distribution provides additional languages,
+including the following:
+
+@itemize[
+
+ @item{@schememodname[typed-scheme] --- like
+       @schememodname[scheme/base], but statically typed; see
+       @other-manual['(lib "typed-scheme/ts-guide.scrbl")]}
+
+ @item{@schememodname[lazy] --- like @schememodname[scheme/base], but
+       avoids evaluating an expression until its value is needed; see
+       @other-manual['(lib "lazy/lazy.scrbl")]}
+
+ @item{@schememodname[frtime] --- changes evaluation in an even more
+       radical way to support reactive programming; see
+       @other-manual['(lib "frtime/frtime.scrbl")]}
+       
+ @item{@schememodname[scribble/doc] --- a language, which looks more
+       like Latex than Scheme, for writing documentation; see
+       @other-manual['(lib "scribblings/scribble/scribble.scrbl")]}
+
+]
+
+Each of these languages is used by starting module with the language
+name after @hash-lang[]. For example, this source of this very
+document starts with @scheme[#, @hash-lang[] scribble/doc].
+
+PLT Scheme users can define their own languages.  A language name maps
+to its implementation through a module path by adding
+@schemeidfont{/lang/reader}. For example, the language name
+@schememodname[scribble/doc] is expanded to
+@scheme[scribble/doc/lang/reader], which is the module that implements
+the surface-syntax parser. The parser, in turn, generates a
+@scheme[module] form, which determines the base language at the level
+of syntactic forms an functions.
+
+Some language names act as language loaders. For example,
+@schememodname[s-exp] as a language uses the usual PLT Scheme parser
+for surface-syntax reading, and then it uses the module path after
+@schememodname[s-exp] for the language's syntactic forms. Thus,
+@scheme[#, @hash-lang[] #, @schememodname[s-exp] "mylang.ss"] parses
+the module body using the normal PLT Scheme reader, by then imports
+the initial syntax and functions for the module body from
+@scheme["mylang.ss"]. Similarly, @scheme[#, @hash-lang[] #,
+@schememodname[planet] _planet-path] loads a language via
+@seclink["top" #:doc '(lib "planet/planet.scrbl")]{@|PLaneT|}.
+
+@; --------------------------------------------------
+
+@section[#:tag "teaching-langs"]{Teaching}
+
+The @|HtDP| textbook relies on pedagogic variants of Scheme that
+smooth the introduction of programming concepts for new programmers.
+The languages are documented in @other-manual['(lib
+"scribblings/htdp-langs/htdp-langs.scrbl")].
+
+The @|HtDP| languages are typically not used with @hash-lang[]
+prefixes, but are instead used within DrScheme by selecting the
+language from the @onscreen{Choose Language...} dialog.

collects/scribblings/guide/guide.scrbl

@@ -58,28 +58,9 @@ precise details to @|MzScheme| and other reference manuals.
 
 @include-section["compile.scrbl"]
 
-@; ----------------------------------------------------------------------
+@include-section["other.scrbl"]
-@section{More Libraries}
 
-@other-manual['(lib "scribblings/gui/gui.scrbl")] describes the PLT
+@include-section["dialects.scrbl"]
-Scheme graphics toolbox, whose core is implemented by the @exec{mred}
-executable.
-
-@other-manual['(lib "scribblings/foreign/foreign.scrbl")] describes
-tools for using Scheme to access libraries that are normally used by C
-programs.
-
-@other-manual['(lib "web-server/scribblings/web-server.scrbl")]
-describes the PLT Scheme web server, which supports servlets
-implemented in Scheme.
-
-@link["../index.html"]{PLT Scheme Documentation} lists documentation
-for many other installed libraries. Run @exec{plt-help} to find
-documentation for libraries that are installed on your system and
-specific to your user account.
-
-@link["http://planet.plt-scheme.org/"]{@|PLaneT|} offers even more
-downloadable packages contributed by PLT Scheme users.
 
 @; ----------------------------------------------------------------------
 

collects/scribblings/guide/other.scrbl

@@ -0,0 +1,25 @@
+#lang scribble/doc
+@(require scribble/manual
+          "guide-utils.ss")
+
+@title{More Libraries}
+
+@other-manual['(lib "scribblings/gui/gui.scrbl")] describes the PLT
+Scheme graphics toolbox, whose core is implemented by the @exec{mred}
+executable.
+
+@other-manual['(lib "scribblings/foreign/foreign.scrbl")] describes
+tools for using Scheme to access libraries that are normally used by C
+programs.
+
+@other-manual['(lib "web-server/scribblings/web-server.scrbl")]
+describes the PLT Scheme web server, which supports servlets
+implemented in Scheme.
+
+@link["../index.html"]{PLT Scheme Documentation} lists documentation
+for many other installed libraries. Run @exec{plt-help} to find
+documentation for libraries that are installed on your system and
+specific to your user account.
+
+@link["http://planet.plt-scheme.org/"]{@|PLaneT|} offers even more
+downloadable packages contributed by PLT Scheme users.

collects/scribblings/guide/welcome.scrbl

@@ -13,7 +13,10 @@ Depending on how you look at it, @bold{PLT Scheme} is
 @itemize{
 
  @item{a @defterm{programming language}---a descendant of Scheme, which
-       is a dialect of Lisp;}
+       is a dialect of Lisp;
+
+       @margin-note{See @secref["dialects"] for more information on
+       other dialects of Scheme and how they relate to PLT Scheme.}}
 
  @item{a @defterm{family} of programming languages---variants of
        Scheme, and more; or}
@@ -54,6 +57,9 @@ that's above the text area. DrScheme then understands that you mean to
 work in the normal variant of Scheme (as opposed to the smaller
 @schememodname[scheme/base], or many other possibilities).
 
+@margin-note{@secref["more-hash-lang"] describes some of the other
+             possibilities.}
+
 If you've used DrScheme before with something other than a program
 that starts @hash-lang[], DrScheme will remember the last language
 that you used, instead of inferring the language from the @hash-lang[]