From 8c8728337eab05e6e64d2379bfdfde1b18c67703 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 22 Dec 2008 21:17:07 +0000 Subject: [PATCH] new guide chapter on Scheme dialects, and small clean-up for some other docs svn: r12926 --- collects/frtime/frtime.scrbl | 2 +- collects/planet/planet.scrbl | 97 ++++++++------ collects/r5rs/r5rs.scrbl | 2 +- collects/r6rs/scribblings/r6rs.scrbl | 36 +++++ collects/scribblings/guide/compile.scrbl | 2 +- collects/scribblings/guide/dialects.scrbl | 155 ++++++++++++++++++++++ collects/scribblings/guide/guide.scrbl | 23 +--- collects/scribblings/guide/other.scrbl | 25 ++++ collects/scribblings/guide/welcome.scrbl | 8 +- 9 files changed, 287 insertions(+), 63 deletions(-) create mode 100644 collects/scribblings/guide/dialects.scrbl create mode 100644 collects/scribblings/guide/other.scrbl diff --git a/collects/frtime/frtime.scrbl b/collects/frtime/frtime.scrbl index 5e379bd9c9..d88278bf7e 100644 --- a/collects/frtime/frtime.scrbl +++ b/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: diff --git a/collects/planet/planet.scrbl b/collects/planet/planet.scrbl index 6e6c8cd782..25a91acd5f 100644 --- a/collects/planet/planet.scrbl +++ b/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 -@secref{finding-a-package} can also be written using a new shorter syntax: +As of PLT Scheme version 4.0, the code snippet above can also be +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 , 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} - -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. +@subsection{Client Configuration} @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 diff --git a/collects/r5rs/r5rs.scrbl b/collects/r5rs/r5rs.scrbl index fb36a9caaf..f500cae2e0 100644 --- a/collects/r5rs/r5rs.scrbl +++ b/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). diff --git a/collects/r6rs/scribblings/r6rs.scrbl b/collects/r6rs/scribblings/r6rs.scrbl index 0417d768e4..1958fe569c 100644 --- a/collects/r6rs/scribblings/r6rs.scrbl +++ b/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 diff --git a/collects/scribblings/guide/compile.scrbl b/collects/scribblings/guide/compile.scrbl index c5a2b037da..0950f5d7e8 100644 --- a/collects/scribblings/guide/compile.scrbl +++ b/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.} ] diff --git a/collects/scribblings/guide/dialects.scrbl b/collects/scribblings/guide/dialects.scrbl new file mode 100644 index 0000000000..e76b24edf4 --- /dev/null +++ b/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. diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl index 8cb705429f..f75f2a94c6 100644 --- a/collects/scribblings/guide/guide.scrbl +++ b/collects/scribblings/guide/guide.scrbl @@ -58,28 +58,9 @@ precise details to @|MzScheme| and other reference manuals. @include-section["compile.scrbl"] -@; ---------------------------------------------------------------------- -@section{More Libraries} +@include-section["other.scrbl"] -@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. +@include-section["dialects.scrbl"] @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/guide/other.scrbl b/collects/scribblings/guide/other.scrbl new file mode 100644 index 0000000000..998a37aaee --- /dev/null +++ b/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. diff --git a/collects/scribblings/guide/welcome.scrbl b/collects/scribblings/guide/welcome.scrbl index ca68a82a1c..63954205ae 100644 --- a/collects/scribblings/guide/welcome.scrbl +++ b/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[]