From 1b21a6d56ed466251dcc6f40a96b9f2b528731e7 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 18 Dec 2007 01:44:09 +0000
Subject: [PATCH] doc tweaks

svn: r8043

original commit: ec3f79cf47d6fa6ff4a5896756eeef683d955efa
---
 collects/scribblings/scribble/scribble.scrbl |  4 ++--
 collects/scribblings/scribble/style.scrbl    | 24 ++++++++++++--------
 collects/scribblings/scribble/xref.scrbl     |  8 +++++--
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
index 1776e664..4de6b665 100644
--- a/collects/scribblings/scribble/scribble.scrbl
+++ b/collects/scribblings/scribble/scribble.scrbl
@@ -6,8 +6,8 @@
 @title[#:tag-prefix '(lib "scribblings/scribble/scribble.scrbl") 
        #:tag "top"]{@bold{Scribble}: PLT Documentation Tool}
 
-The @filepath{scribble} collection provides libraries that can be used to
-create documents from Scheme.
+Scribble is a collection of tools for creating prose documents,
+especially those that document libraries.
 
 @table-of-contents[]
 
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
index e2dee89e..1910ee9d 100644
--- a/collects/scribblings/scribble/style.scrbl
+++ b/collects/scribblings/scribble/style.scrbl
@@ -11,13 +11,16 @@ implicit subject is the form or value being described. Thus, the
 description will often start with ``Produces.'' Refer to arguments by
 name.
 
-Use @schemeidfont{id} or something that ends @schemeidfont{-id} in a
-syntactic form to mean an identifier, not @schemeidfont{identifier},
-@schemeidfont{name}, or @schemeidfont{symbol}. Similarly, use
-@schemeidfont{expr} or something that ends @schemeidfont{-expr} for an
-expression position within a syntactic form. Use @schemeidfont{body}
-for a form (definition or expression) in an internal-definition
-position.
+Use @schemeidfont{id} or something that ends @schemeidfont{-id} in
+@scheme[defform] to mean an identifier, not @schemeidfont{identifier},
+@schemeidfont{variable}, @schemeidfont{name}, or
+@schemeidfont{symbol}. Similarly, use @schemeidfont{expr} or something
+that ends @schemeidfont{-expr} for an expression position within a
+syntactic form. Use @schemeidfont{body} for a form (definition or
+expression) in an internal-definition position. Never use
+@schemeidfont{expr} for something that isn't exactly an expression,
+@scheme[id] for something that isn't exactly an identifier, etc.;
+instead, use @scheme[defform/subs] to define a new non-terminal.
 
 Pay attention to the difference between identifiers and meta-variables
 when using @scheme[scheme], especially outside of @scheme[defproc] or
@@ -36,8 +39,11 @@ typeset as variables. The correct description is
 which produces @scheme[(_rator-expr _rand-expr ...)], where
 @schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as
 meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms
-greatly reduce this burden in description, since they automatically
-set up meta-variable typesetting for non-literal identifiers.
+greatly reduce this burden in descriptions, since they automatically
+set up meta-variable typesetting for non-literal identifiers. In
+@scheme[defform], be sure to include literal identifiers (i.e., those
+not meant as variables, other than the form name being defined) in a
+@scheme[#:literals] clause.
 
 To typeset an identifier with no particular interpretation---syntax,
 variable, meta-variable, etc.---use @scheme[schemeidfont] (e.g., as in
diff --git a/collects/scribblings/scribble/xref.scrbl b/collects/scribblings/scribble/xref.scrbl
index 872fe115..0d01223b 100644
--- a/collects/scribblings/scribble/xref.scrbl
+++ b/collects/scribblings/scribble/xref.scrbl
@@ -3,7 +3,8 @@
           "utils.ss"
           (for-label scribble/xref
                      scribble/base-render
-                     scribble/html-render))
+                     scribble/html-render
+                     setup/xref))
 
 @title[#:tag "xref"]{Cross-Reference Utilities}
 
@@ -30,7 +31,10 @@ serialize-info].
 
 Since the format of serialized information is specific to a rendering
 class, the optional @scheme[using-render%] argument accepts the
-relevant class. It default to HTML rendering.}
+relevant class. It default to HTML rendering.
+
+Use @scheme[load-collections-xref] from @schememodname[setup/xref] to
+get all cross-reference information for installed documentation.}
 
 
 @defproc[(xref-binding->definition-tag [xref xref?]