From 166b92f9c8e72ddc4a074b961cd266751e512c3b Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 2 May 2010 11:04:48 -0600 Subject: [PATCH] replace mzc and setup-plt docs with raco doc (which refers to the still-separate planet doc) --- collects/make/make.scrbl | 16 +- collects/planet/planet.scrbl | 335 ++++--- collects/r5rs/r5rs.scrbl | 2 +- collects/r6rs/scribblings/r6rs.scrbl | 194 ++--- collects/scribblings/guide/compile.scrbl | 2 +- collects/scribblings/guide/futures.scrbl | 2 +- collects/scribblings/guide/performance.scrbl | 2 +- collects/scribblings/guide/running.scrbl | 5 +- collects/scribblings/guide/welcome.scrbl | 2 +- collects/scribblings/mzc/c-mods.scrbl | 17 - collects/scribblings/mzc/dist.scrbl | 83 -- collects/scribblings/mzc/exe.scrbl | 56 -- collects/scribblings/mzc/info.rkt | 3 - collects/scribblings/mzc/launcher.scrbl | 312 ------- collects/scribblings/mzc/make.scrbl | 316 ------- collects/scribblings/mzc/mzc.scrbl | 75 -- collects/scribblings/mzc/plt.scrbl | 146 ---- collects/scribblings/mzc/sa.scrbl | 18 - collects/scribblings/mzc/zo.scrbl | 58 -- collects/scribblings/{mzc => raco}/api.scrbl | 18 +- .../{mzc => raco}/bundle-api.scrbl | 24 +- collects/scribblings/raco/c-mods.scrbl | 17 + collects/scribblings/{mzc => raco}/cc.scrbl | 42 +- collects/scribblings/{mzc => raco}/common.rkt | 5 +- collects/scribblings/raco/ctool.scrbl | 18 + .../scribblings/{mzc => raco}/decompile.scrbl | 89 +- .../scribblings/{mzc => raco}/dist-api.scrbl | 22 +- collects/scribblings/raco/dist.scrbl | 83 ++ .../scribblings/{mzc => raco}/exe-api.scrbl | 257 +++--- collects/scribblings/raco/exe.scrbl | 63 ++ collects/scribblings/{mzc => raco}/ext.scrbl | 22 +- collects/scribblings/raco/info.rkt | 3 + .../{setup-plt => raco}/info.scrbl | 40 +- collects/scribblings/raco/launcher.scrbl | 392 +++++++++ collects/scribblings/raco/make.scrbl | 371 ++++++++ collects/scribblings/raco/planet.scrbl | 9 + collects/scribblings/raco/plt.scrbl | 318 +++++++ collects/scribblings/raco/raco.scrbl | 26 + .../setup-plt.scrbl => raco/setup.scrbl} | 823 +++++++----------- .../scribblings/{mzc => raco}/zo-parse.scrbl | 332 +++---- collects/scribblings/reference/startup.scrbl | 2 +- collects/scribblings/setup-plt/info.rkt | 4 - collects/test-box-recovery/info.rkt | 2 +- 43 files changed, 2326 insertions(+), 2300 deletions(-) delete mode 100644 collects/scribblings/mzc/c-mods.scrbl delete mode 100644 collects/scribblings/mzc/dist.scrbl delete mode 100644 collects/scribblings/mzc/exe.scrbl delete mode 100644 collects/scribblings/mzc/info.rkt delete mode 100644 collects/scribblings/mzc/launcher.scrbl delete mode 100644 collects/scribblings/mzc/make.scrbl delete mode 100644 collects/scribblings/mzc/mzc.scrbl delete mode 100644 collects/scribblings/mzc/plt.scrbl delete mode 100644 collects/scribblings/mzc/sa.scrbl delete mode 100644 collects/scribblings/mzc/zo.scrbl rename collects/scribblings/{mzc => raco}/api.scrbl (96%) rename collects/scribblings/{mzc => raco}/bundle-api.scrbl (58%) create mode 100644 collects/scribblings/raco/c-mods.scrbl rename collects/scribblings/{mzc => raco}/cc.scrbl (62%) rename collects/scribblings/{mzc => raco}/common.rkt (64%) create mode 100644 collects/scribblings/raco/ctool.scrbl rename collects/scribblings/{mzc => raco}/decompile.scrbl (58%) rename collects/scribblings/{mzc => raco}/dist-api.scrbl (56%) create mode 100644 collects/scribblings/raco/dist.scrbl rename collects/scribblings/{mzc => raco}/exe-api.scrbl (62%) create mode 100644 collects/scribblings/raco/exe.scrbl rename collects/scribblings/{mzc => raco}/ext.scrbl (58%) create mode 100644 collects/scribblings/raco/info.rkt rename collects/scribblings/{setup-plt => raco}/info.scrbl (59%) create mode 100644 collects/scribblings/raco/launcher.scrbl create mode 100644 collects/scribblings/raco/make.scrbl create mode 100644 collects/scribblings/raco/planet.scrbl create mode 100644 collects/scribblings/raco/plt.scrbl create mode 100644 collects/scribblings/raco/raco.scrbl rename collects/scribblings/{setup-plt/setup-plt.scrbl => raco/setup.scrbl} (52%) rename collects/scribblings/{mzc => raco}/zo-parse.scrbl (65%) delete mode 100644 collects/scribblings/setup-plt/info.rkt diff --git a/collects/make/make.scrbl b/collects/make/make.scrbl index 205073f1ce..2f16fb91cf 100644 --- a/collects/make/make.scrbl +++ b/collects/make/make.scrbl @@ -12,7 +12,7 @@ dynext/file-sig compiler/sig)) -@(define mzc-manual @other-manual['(lib "scribblings/mzc/mzc.scrbl")]) +@(define raco-manual @other-manual['(lib "scribblings/raco/raco.scrbl")]) @title{@bold{Make}: Dependency Manager} @@ -27,8 +27,8 @@ syntax of @exec{make}, only in Scheme. @section[#:tag "overview"]{Overview} @margin-note{If you want to build Scheme modules with automatic -dependency tracking, just use @exec{mzc} as described in -@|mzc-manual|.} +dependency tracking, just use @exec{raco make} as described in +@|raco-manual|.} If you are already familiar with @exec{make}, skip to the precise details of the @schememodname[make] library in @secref["make"]. This @@ -238,8 +238,8 @@ A unit that imports nothing and exports @scheme[make^].} The @schememodname[make/setup-extension] library helps compile C code via Setup PLT's ``pre-install'' phase (triggered by a -@schemeidfont{pre-install-collection} item in @filepath{info.ss}; see -also @secref[#:doc '(lib "scribblings/setup-plt/setup-plt.scrbl") +@schemeidfont{pre-install-collection} item in @filepath{info.rkt}; see +also @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "setup-info"]). The @scheme[pre-install] function takes a number of arguments that @@ -361,7 +361,7 @@ The arguments are as follows: AIX-specific compile flag in this step when compiling under AIX.} @item{@scheme[3m-too?]--- a boolean. If true, when the 3m variant is - installed, use the equivalent to @exec{mzc --xform} to transform + installed, use the equivalent to @exec{raco ctool --xform} to transform the source file and then compile and link for 3m. Otherwise, the extension is built only for CGC when the CGC variant is installed.} @@ -384,8 +384,8 @@ managing dependencies. Supply @scheme['#("zo")] as @scheme[argv] to compile all files. The @scheme[collection-name] argument is used only for printing status information. -Compilation is performed as with @exec{mzc --make} (see -@|mzc-manual|).} +Compilation is performed as with @exec{raco make} (see +@|raco-manual|).} @subsection{Signature} diff --git a/collects/planet/planet.scrbl b/collects/planet/planet.scrbl index 511b4f1b05..d5123da4b2 100644 --- a/collects/planet/planet.scrbl +++ b/collects/planet/planet.scrbl @@ -3,7 +3,7 @@ @(require scribble/manual scribble/bnf scribble/eval - (for-label scheme) + (for-label racket) (for-label planet/config) (for-label planet/util)) @@ -20,9 +20,9 @@ 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 package on the server. It -consists of @link["http://planet.plt-scheme.org/"]{the central @PLaneT +consists of @link["http://planet.racket-lang.org/"]{the central @PLaneT package repository}, a server that holds all PLaneT packages, and -the PLaneT client, built into PLT Scheme, which transparently +the PLaneT client, built into Racket, which transparently interacts with the server on your behalf when necessary. @table-of-contents[] @@ -30,41 +30,41 @@ interacts with the server on your behalf when necessary. @section{Using PLaneT} To use a @PLaneT package in a program, require it using the -@scheme[planet] @scheme[require] form (see @(secref "require" #:doc +@racket[planet] @racket[require] form (see @(secref "require" #:doc '(lib "scribblings/reference/reference.scrbl")) for a full reference -on the features of the @scheme[require] statement in general and the +on the features of the @racket[require] statement in general and the exact allowed grammar of PLaneT require statements). Here we explain how to use PLaneT by example. @subsection[#:tag "finding-a-package"]{Finding a Package} If you are new to PLaneT, the first thing to do is visit -@link["http://planet.plt-scheme.org/"]{the PLaneT repository web site} +@link["http://planet.racket-lang.org/"]{the PLaneT repository web site} and see what packages are available. People contribute new PLaneT packages all the time --- if you want to be notified whenever a new or updated package is released, you can subscribe to the (announcement-only) @link["http://mailman.cs.uchicago.edu/mailman/listinfo/planet-announce"]{PLaneT-announce mailing list} or use an RSS reader to subscribe to -@link["http://planet.plt-scheme.org/300/planet.rss"]{PLaneT's RSS feed}. +@link["http://planet.racket-lang.org/300/planet.rss"]{PLaneT's RSS feed}. To use a package from PLaneT in your program, the easiest thing to do -is copy the @scheme[require] code snippet off of that package's page +is copy the @racket[require] code snippet off of that package's page and paste it ino your program. For instance, to use Schematics' -@link["http://planet.plt-scheme.org/users/schematics/spgsql.plt"]{spgsql.plt} +@link["http://planet.racket-lang.org/users/schematics/spgsql.plt"]{spgsql.plt} 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: -@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))] +@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 3)))] -into your program. This line requires the file @filepath{spgsql.ss} in package +into your program. This line requires the file @filepath{spgsql.rkt} in package version 2.3 of the @filepath{spgsql.plt} package written by @filepath{schematics}. That does two things: first, it downloads and installs a version of @filepath{spgsql.plt} that is compatible with -package version 2.3 from @link["http://planet.plt-scheme.org/"]{the +package version 2.3 from @link["http://planet.racket-lang.org/"]{the central PLaneT repository} if a compatible version hasn't already been -installed. Second, it requires the module in file @filepath{spgsql.ss} +installed. Second, it requires the module in file @filepath{spgsql.rkt} from that package, making all of its exported bindings available for use. Unlike with most package-distribution systems, package downloading and @@ -76,17 +76,16 @@ will be deployed. @subsection{Shorthand Syntax} -As of PLT Scheme version 4.0, the code snippet above can also be -written using a new shorter syntax: +The code snippet above can also be written using a new shorter syntax: -@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))] +@racketblock[(require (planet schematics/spgsql:2:3/spgsql))] The two forms behave identically. In the abbreviated syntax, however, -it is illegal to write the trailing @filepath{.ss} suffix on the file +it is illegal to write the trailing @filepath{.rkt} suffix on the file name to be required or the trailing @filepath{.plt} on the package file name. (They are mandatory for the long-form syntax.) It is also legal in the abbreviated syntax to omit a filename to be required entirely; -in that case, PLaneT requires the file @filepath{main.ss} in the given +in that case, PLaneT requires the file @filepath{main.rkt} in the given package. @subsection{Networking troubles} @@ -94,15 +93,15 @@ package. Sometimes, when PLaneT tries to download and install a package for the first time, your operating system may block it from access to the network. If you are uncomfortable -giving DrScheme free access to the network (or if your +giving DrRacket free access to the network (or if your attempts to do so do not seem to work), then you can use your browser to manually install a planet package. To see how this works, lets assume you want to install the PLAI package -and @schemeblock[(require (planet plai/plai:1))] is not working for you. +and @racketblock[(require (planet plai/plai:1))] is not working for you. @itemize[ @item{First, -fire up a command-line window and use @tt{planet url} to +fire up a command-line window and use @tt{raco planet url} to determine the url for downloading the package. To find the url for version @tt{(1 1)} of the plai package, do this: @@ -111,7 +110,7 @@ do this: and get this as a response: -@tt{http://planet.plt-scheme.org/servlets/planet-servlet.ss?lang=%224.1.5.3%22&name=%22plai.plt%22&maj=1&min-lo=1&min-hi=%23f&path=%28%22plai%22%29}} +@tt{http://planet.racket-lang.org/servlets/planet-servlet.rkt?lang=%224.1.5.3%22&name=%22plai.plt%22&maj=1&min-lo=1&min-hi=%23f&path=%28%22plai%22%29}} @item{Copy and paste that url into your browser, which should trigger the dowload of a file called @@ -130,7 +129,7 @@ repeat the above steps for that package first, and then continue with the @tt{fileinject} command for PLAI.} @item{Finally, to check that the installation is successful, -run @tt{planet show}. You should see output like this +run @tt{raco planet show}. You should see output like this (possibly with slightly different version numbers, if the packages have been updated since this was written): @verbatim{ @@ -141,7 +140,7 @@ Normally-installed packages: ] Once that is complete, PLaneT will use that version of the -package for any subsequent @scheme[require]s and won't try +package for any subsequent @racket[require]s and won't try to use the network. @subsection{Fine-Grained Control Over Package Imports} @@ -159,11 +158,11 @@ number that encodes backwards-compatibility information.} The most basic planet require line, which is what is used in the form -@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))] +@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 3)))] in longhand notation, or -@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))] +@racketblock[(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 @@ -172,11 +171,11 @@ package version used is determined by @seclink["search-order"]{the PLaneT search order}.) To signal this explicitly, it is possible to write -@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 (+ 3))))] +@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 (+ 3))))] or -@schemeblock[(require (planet schematics/spgsql:2:>=3/spgsql))] +@racketblock[(require (planet schematics/spgsql:2:>=3/spgsql))] both of which mean the same thing as the first pair of require lines. @@ -199,12 +198,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: -@schemeblock[(require (planet "reduction-semantics.ss" +@racketblock[(require (planet "reduction-semantics.rkt" ("robby" "redex.plt" 4 (- 3))))] and using shorthand notation: -@schemeblock[(require (planet robby/redex:4:<=3/reduction-semantics))] +@racketblock[(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 @@ -215,11 +214,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: -@schemeblock[(require (planet "test.ss" ("schematics" "schemeunit.plt" 2 (9 10))))] +@racketblock[(require (planet "test.rkt" ("schematics" "schemeunit.plt" 2 (9 10))))] or -@schemeblock[(require (planet schematics/schemeunit:2:9-10/test))] +@racketblock[(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 @@ -232,11 +231,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: -@schemeblock[(require (planet "unzip.ss" ("dherman" "zip.plt" 2 (= 1))))] +@racketblock[(require (planet "unzip.rkt" ("dherman" "zip.plt" 2 (= 1))))] or -@schemeblock[(require (planet dherman/zip:2:=1/unzip))] +@racketblock[(require (planet dherman/zip:2:=1/unzip))] match only the exact package version 2.1 of the @filepath{zip.plt} package. @@ -247,9 +246,9 @@ match only the exact package version 2.1 of the @filepath{zip.plt} package. @subsection{Monitoring PLaneT's progress} PLaneT logs information about what it is doing to the @tt{info} -log (via @scheme[log-info]). -In DrScheme, you can view the logs from the @onscreen{Show Log} -menu item in the @onscreen{View} menu, and MzScheme's logging output +log (via @racket[log-info]). +In DrRacket, you can view the logs from the @onscreen{Show Log} +menu item in the @onscreen{View} menu, and Racket's logging output can be controlled via command-line options and via environment variables. See @secref["logging" #:doc '(lib "scribblings/reference/reference.scrbl")] @@ -292,22 +291,22 @@ it to satisfy the original requirement. If the remote server cannot be contacted (or fails in any way to deliver an acceptable package), the PLaneT client consults the uninstalled-packages cache, a cache of all previously-downloaded -packages, even those that are not currently installed. PLT Scheme +packages, even those that are not currently installed. Racket users who frequently upgrade their installations may have many packages downloaded but not installed at any given time; this step is intended to ensure that these users can still run programs even if they temporarily lose network connection. -@section[#:tag "cmdline"]{The @exec{planet} Command-Line Tool} +@section[#:tag "cmdline"]{The @exec{raco planet} Command-Line Tool} -The @exec{planet} command-line tool allows a command-line interface to +The @exec{raco planet} command-line tool allows a command-line interface to the most commonly-performed PLaneT tasks. It is invoked from the command line as -@commandline{planet @italic{subcommand} arg ...} +@commandline{raco planet @italic{subcommand} @italic{arg} ...} -where @italic{command} is a subcommand from the following list, and -@exec{arg} is a sequence of arguments determined by that subcommand: +where @italic{subcommand} is a subcommand from the following list, and +@exec{@italic{arg}} is a sequence of arguments determined by that subcommand: @(define (cmd name desc) @item{@(seclink name (exec name)): @desc}) @@ -329,31 +328,31 @@ where @italic{command} is a subcommand from the following list, and Each of these commands is described in more detail below. All the functionality of the command-line tool is also provided with a programmatic interface by -@seclink["util.ss"]{the @filepath{util.ss} library}. +@seclink["util.rkt"]{the @filepath{util.rkt} library}. @subsection[#:tag "create"]{@exec{create}} Usage: -@commandline{planet create [