more guide clean-up

svn: r9920

collects/scribblings/guide/chars.scrbl

@@ -5,7 +5,7 @@
 
 @title[#:tag "characters"]{Characters}
 
-A Scheme @defterm{character} corresponds to a Unicode @defterm{scalar
+A Scheme @deftech{character} corresponds to a Unicode @defterm{scalar
 value}. Roughly, a scalar value is an unsigned integer whose
 representation fits into 21 bits, and that maps to some notion of a
 natural-language character or piece of a character. Technically, a

collects/scribblings/guide/compile.scrbl

@@ -0,0 +1,60 @@
+#lang scribble/doc
+@(require scribble/manual
+          "guide-utils.ss")
+
+@title[#:tag "compile"]{Compilation and Configuration}
+
+So far, we have talked about three main PLT Scheme executables:
+
+@itemize[
+
+ @item{DrScheme, which is the development environment.}
+
+ @item{@exec{mzscheme}, which is the console-based virtual machine for
+       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
+       applications.}
+
+]
+
+Three more executables help in compiling PLT Scheme programs and in
+maintaining a PLT Scheme installation:
+
+@itemize[
+
+ @item{@exec{mzc} is a command-line tool for miscellaneous tasks, such
+ as compiling Scheme source to bytecode, generating executables, and
+ building distribution packages, and compiling C-implemented
+ extensions to work with the run-time system. The @exec{mzc} is
+ described in @other-manual['(lib
+ "scribblings/mzc/mzc.scrbl")].
+
+ For example, if you have a program @filepath{take-over-world.ss} and
+ you'd like to compile it to bytecode, along with all of its
+ dependencies, so that it loads more quickly, then run
+
+   @commandline{mzc take-over-the-world.ss}}
+
+ @item{@exec{setup-plt} is a command-line tool for managing a PLT
+ Scheme installation, including manually installed packages. The
+ @exec{setup-plt} tool is described in @other-manual['(lib
+ "scribblings/setup-plt/setup-plt.scrbl")].
+
+ For example, if you create your own library @techlink{collection}
+ called @filepath{take-over}, and you'd like to build all bytecode and
+ documentation for the collection, then run
+
+   @commandline{setup-plt -l take-over}}
+
+ @item{@exec{planet} is a command-line tool for managing packages that
+ are normally downloaded automatically, on demand. The @exec{planet}
+ tool is described in @other-manual['(lib "planet/planet.scrbl")].
+
+ For example, if you'd like to see a list of @|PLaneT| packages that
+ are currently installed, then run
+
+    @commandline{planet show}}
+
+]

collects/scribblings/guide/guide.scrbl

@@ -46,64 +46,21 @@ precise details to @|MzScheme| and other reference manuals.
 
 @include-section["unit.scrbl"]
 
-@; ----------------------------------------------------------------------
-@section[#:tag "threads"]{Threads}
-
-@subsection[#:tag "parameters"]{Parameters}
-
-A @deftech{parameter} holds a kind of global option. For example,
-there is a parameter that determines the default destination for
-printed output.
-
-@; ----------------------------------------------------------------------
 @include-section["namespaces.scrbl"]
 
-
-@; ----------------------------------------------------------------------
 @include-section["macros.scrbl"]
 
-@; ----------------------------------------------------------------------
-@section[#:tag "reader"]{Reader Extension}
-
-@; ----------------------------------------------------------------------
-@section[#:tag "security"]{Security}
-
-
-@; ----------------------------------------------------------------------
-@section[#:tag "memory-management"]{Memory Management}
-
-@subsection[#:tag "weakboxes"]{Weak Boxes}
-
-@subsection[#:tag "ephemerons"]{Ephemerons}
-
-@; ----------------------------------------------------------------------
 @include-section["performance.scrbl"]
 
-@; ----------------------------------------------------------------------
 @include-section["running.scrbl"]
 
-@; ----------------------------------------------------------------------
-@section{Configuration and Compilation}
-
-@itemize{
-
- @tool["setup-plt"]{a command-line tool for installation tasks}
-
- @tool["planet"]{a command-line tool for managing packages that are
- normally downloaded automatically, on demand}
-
- @tool["mzc"]{a command-line tool for miscellaneous tasks, such as
- compiling Scheme source, compiling C-implemented extensions to the
- run-time system, generating executables, and building distribution
- packages}
-
-}
+@include-section["compile.scrbl"]
 
 @; ----------------------------------------------------------------------
 @section{More Libraries}
 
 @other-manual['(lib "scribblings/gui/gui.scrbl")] describes the PLT
-Scheme graphics toolbox, whose core is implemented by the MrEd
+Scheme graphics toolbox, whose core is implemented by the @exec{mred}
 executable.
 
 @other-manual['(lib "scribblings/foreign/foreign.scrbl")] describes

collects/scribblings/guide/hash-tables.scrbl

@@ -55,9 +55,9 @@ mapping is retained only so long as the key is retained elsewhere.
 Beware that even a weak hash table retains its values strongly, as
 long as the corresponding key is accessible. This creates a catch-22
 dependency when a value refers back to its key, so that the mapping is
-retained permanently. To break the cycle, map the key to an
-@seclink["ephemerons"]{ephemeron} that pairs the value with its key (in
-addition to the implicit pairing of the hash table).
+retained permanently. To break the cycle, map the key to an ephemeron
+that pairs the value with its key (in addition to the implicit pairing
+of the hash table).
 
 @examples[
 (define ht (make-weak-hasheq))

collects/scribblings/guide/io.scrbl

@@ -188,10 +188,8 @@ stdout in purple, and output written to stderr in red italics.
 (swing-hammer)
 ]
 
-The current-port functions are actually @tech{parameters}, which means
-that their values can be set with @scheme[parameterize].
-
-@moreguide["parameters"]{parameters}
+The current-port functions are actually parameters, which means that
+their values can be set with @scheme[parameterize].
 
 @examples[
 #:eval io-eval

collects/scribblings/guide/module-set.scrbl

@@ -63,7 +63,7 @@ involves the re-definition of a previously immutable binding.
 ]
 
 For exploration and debugging purposes, the Scheme reflective layer
-provides a @scheme[compile-enforce-module-constants] @tech{parameter}
+provides a @scheme[compile-enforce-module-constants] parameter
 to disable the enforcement of constants.
 
 @interaction[

collects/scribblings/guide/performance.scrbl

@@ -23,10 +23,13 @@ and memory performance of Scheme code.
 
 Every definition or expression to be evaluated by Scheme is compiled
 to an internal bytecode format. In interactive mode, this compilation
-occurs automatically and on-the-fly. Tools like @exec{setup-plt} and
-@scheme[compile-file] marshal compiled bytecode to a file. Most of the
-time required to compile a file is actually in macro expansion;
-generating bytecode from fully expanded code is relatively fast.
+occurs automatically and on-the-fly. Tools like @exec{mzc} and
+@exec{setup-plt} marshal compiled bytecode to a file, so that you do
+not have to compile from source every time that you run a
+program. (Most of the time required to compile a file is actually in
+macro expansion; generating bytecode from fully expanded code is
+relatively fast.) See @secref["compile"] for more information on
+generating bytecode files.
 
 The bytecode compiler applies all standard optimizations, such as
 constant propagation, constant folding, inlining, and dead-code
@@ -41,7 +44,7 @@ arithmetic on small integers, and arithmetic on inexact real
 numbers. Currently, @tech{JIT} compilation is supported for x86,
 x86_64 (a.k.a. AMD64), and 32-bit PowerPC processors. The @tech{JIT}
 compiler can be disabled via the @scheme[eval-jit-enabled] parameter
-or the @DFlag{no-jit}/@Flag{j} command-line flag.
+or the @DFlag{no-jit}/@Flag{j} command-line flag for @exec{mzscheme}.
 
 The @tech{JIT} compiler works incrementally as functions are applied,
 but the @tech{JIT} compiler makes only limited use of run-time

collects/scribblings/guide/running.scrbl

@@ -5,15 +5,23 @@
 
 @title[#:tag "running" #:style 'toc]{Running and Creating Executables}
 
+While developing programs, many PLT Scheme programmers use the
+@seclink[#:doc '(lib "scribblings/drscheme/drscheme.scrbl")
+"top"]{DrScheme} programming environment. To run a program without the
+development environment, use @exec{mzscheme} (for console-based
+programs) or @exec{mred} (for GUI program). This chapter mainly
+explains how to run @exec{mzscheme} and @exec{mred}.
+
 @local-table-of-contents[]
 
 @; ----------------------------------------------------------------------
 
-@section[#:tag "mzscheme"]{Running MzScheme and MrEd}
+@section[#:tag "mzscheme"]{Running @exec{mzscheme} and @exec{mred}}
 
-Depending on command-line arguments, MzScheme runs in
-@seclink["start-interactive-mode"]{interactive mode},
-@seclink["start-module-mode"]{module mode}, or @seclink["start-load-mode"]{load mode}.
+Depending on command-line arguments, @exec{mzscheme} or @exec{mred}
+runs in @seclink["start-interactive-mode"]{interactive mode},
+@seclink["start-module-mode"]{module mode}, or
+@seclink["start-load-mode"]{load mode}.
 
 @subsection[#:tag "start-interactive-mode"]{Interactive Mode}
 
@@ -40,7 +48,7 @@ If any command-line arguments are provided (other than configuration
 options), add @Flag{i} or @DFlag{repl} to re-enable the
 @tech{REPL}. For example,
 
-@commandline{mzscheme -e '(display "hi\n")' }
+@commandline{mzscheme -e '(display "hi\n")' -i}
 
 displays ``hi'' on start-up, but still presents a @tech{REPL}.
 
@@ -107,7 +115,14 @@ The @Flag{l} or @DFlag{lib} flag is similar to
 @commandline{mzscheme -l compiler}
 
 is the same as running the @exec{mzc} executable with no arguments,
-since the @scheme[compiler] module is the main @exec{mzc} module.
+since the @scheme[compiler] module is the main @exec{mzc}
+module.
+
+Note that if you wanted to pass command-line flags to
+@scheme[compiler] above, you would need to protect the flags with a
+@Flag{-}, so that @exec{mzscheme} doesn't try to parse them itself:
+
+@commandline{mzscheme -l compiler -- --make prog.ss}
 
 @; ----------------------------------------
 
@@ -147,9 +162,13 @@ instead of @schememodname[scheme/init].
 
 @; ----------------------------------------------------------------------
 
-@section[#:tag "exe"]{Creating Stand-Alone Executables}
+@include-section["scripts.scrbl"]
 
 @; ----------------------------------------------------------------------
 
-@include-section["scripts.scrbl"]
+@section[#:tag "exe"]{Creating Stand-Alone Executables}
 
+@(define mzc-doc '(lib "scribblings/mzc/mzc.scrbl"))
+
+For information on creating and distributing executables, see
+@secref[#:doc mzc-doc "sa"] in @other-manual[mzc-doc].

collects/scribblings/guide/scripts.scrbl

@@ -13,7 +13,7 @@ the first line must be a command to execute the script. For some
 platforms, the total length of the first line is restricted to 32
 characters, and sometimes the space is required.
 
-The simplest script format uses an absolute path to a MzScheme
+The simplest script format uses an absolute path to a @exec{mzscheme}
 executable followed by a module declaration. For example, if
 @exec{mzscheme} is installed in @filepath{/usr/local/bin}, then a file
 containing the following text acts as a ``hello world'' script:

collects/scribblings/guide/welcome.scrbl

@@ -170,6 +170,9 @@ options:
  @item{With Unix or Mac OS X, you can turn the program file into an
        executable script by inserting the line
 
+       @margin-note{See @secref["scripts"] for more information on
+                    script files.}
+
         @verbatim[#:indent 2]{#! /usr/bin/env mzscheme}
 
        at the very beginning of the file. Also, change the file

collects/scribblings/mzc/exe.scrbl

@@ -5,12 +5,12 @@
 
 @title[#:tag "exe"]{Stand-Alone Executables from Scheme Code}
 
-The command-line flag @DFlag{exe} directs @|mzc| to embed a
-module, from source or byte code, into a copy of the MzScheme
+The command-line flag @DFlag{exe} directs @|mzc| to embed a module,
+from source or byte code, into a copy of the @exec{mzscheme}
 executable. (Under Unix, the embedding executable is actually a copy
 of a wrapper executable.)  The created executable invokes the embedded
-module on startup. The @DFlag{gui-exe} flag is similar, but it
-copies the MrEd executable. If the embedded module refers to other
+module on startup. The @DFlag{gui-exe} flag is similar, but it copies
+the @exec{mred} executable. If the embedded module refers to other
 modules via @scheme[require], then the other modules are also included
 in the embedding executable.
 
@@ -20,7 +20,7 @@ For example, the command
 
 produces either @filepath{hello.exe} (Windows), @filepath{hello.app}
 (Mac OS X), or @filepath{hello} (Unix), which runs the same as
-invoking the @filepath{hello.ss} module in MrEd.
+invoking the @filepath{hello.ss} module in @exec{mred}.
 
 Library modules or other files that are referenced
 dynamically---through @scheme[eval], @scheme[load], or
@@ -44,9 +44,9 @@ The @DFlag{exe} and @DFlag{gui-exe} flags work only with
 library provides a more general interface to the embedding mechanism.
 
 A stand-alone executable is ``stand-alone'' in the sense that you can
-run it without starting MzScheme, MrEd, or DrScheme. However, the
-executable depends on MzScheme and/or MrEd shared libraries, and
-possibly other run-time files declared via
+run it without starting @exec{mzscheme}, @exec{mred}, or
+DrScheme. However, the executable depends on PLT Scheme shared
+libraries, and possibly other run-time files declared via
 @scheme[define-runtime-path]. The executable can be packaged with
 support libraries to create a distribution, as described in
 @secref["exe-dist"].

collects/scribblings/mzc/sa.scrbl

@@ -5,7 +5,7 @@
 @title[#:tag "sa" #:style 'toc]{Creating and Distributing Stand-Alone Executables}
 
 Whether bytecode or native code, the compiled code produced by @|mzc|
-relies on MzScheme (or MrEd) to provide run-time support to the
+relies on PLT Scheme executables to provide run-time support to the
 compiled code. However, @|mzc| can also package code together with its
 run-time support to form a complete executable, and then the
 executable can be packaged into a distribution that works on other