scribble/text documentation, and a few other fixes and comments

svn: r8821

original commit: 1e32dbd324467349743cde8516dadb4dcbe0dba9

collects/scribblings/scribble/how-to.scrbl

@@ -54,27 +54,35 @@ To document a collection or @|PLaneT| package:
         the whole right-hand side of the definition is already
         quoted).
 
-        As usual, the @filepath{info.ss} module also needs a
+        @; [Eli] `name' is not needed, but I think it's used by planet
-        @schemeidfont{name} field. If you do not already have an
+        As usual, you may want to add a descriptive
-        @filepath{info.ss} module, here's a suitable complete module:
+        @schemeidfont{name} field in your @filepath{info.ss}.  If you
+        do not already have an @filepath{info.ss} module, here's a
+        suitable complete module:
 
+        @; [Eli] "Some documentation" is probably not a good name
+        @;   since this is supposed to be documentation for a library
         @schememod[
           setup/infotab
           (define name "Some documentation")
           (define scribblings '(("manual.scrbl" ())))
         ]}
 
-  @item{Run @exec{setup-plt} to build your documentation. For a
+  @item{@; [Eli] If this is following a planet example, then it should
+        @;   have the correct command line here.  (I don't know what
+        @;   it should be though.)
+        Run @exec{setup-plt} to build your documentation. For a
         collection, optionally supply @Flag{l} followed by the
         collection name to limit the build process to that collection.}
 
   @item{The generated documentation is normally
         @filepath{doc/manual/index.html} within the collection or
-        @|PLaneT| package directory. If the collection in the PLT
+        @; [Eli] I "fixed" the obvious typo in the following sentence,
-        Scheme installation's the main @filepath{collects} directory,
+        @;   but it's still weird and should probably be different.
-        however, then the documentation is generated as
+        @|PLaneT| package directory. If the collection is in PLT
-        @filepath{manual/index.html} in the installation's main
+        Scheme's main @filepath{collects} directory, however, then the
-        @filepath{doc} directory.}
+        documentation is generated as @filepath{manual/index.html} in
+        the installation's main @filepath{doc} directory.}
 
 }
 
@@ -136,6 +144,7 @@ that precede text to typeset.
 Thus,
 
 @verbatim[#:indent 2]|{
+  @(require scribble/manual)
   @title{My Library}
   @scheme[(list 'testing 1 2 3)]
   @section[#:tag "here"]{You Are Here}
@@ -144,6 +153,7 @@ Thus,
 means
 
 @schemeblock[
+(require scribble/manual)
 (title "My Library")
 (scheme (list 'testing 1 2 3))
 (section #:tag "here" "You Are Here")
@@ -153,7 +163,8 @@ For more information on the syntax of @litchar["@"], see
 @secref["reader"].
 
 In a document that starts @hash-lang[] @schememodname[scribble/doc],
-the top level is a text-mode sequence. The parsed sequence is further
+the top level is a text-mode sequence, as the @nonterm{text-body} in a
+@litchar["@"] form.  The parsed sequence is further
 decoded to turn it into a hierarchy of sections and paragraphs. For
 example, a linear sequence of @scheme[section] declarations with
 interleaved text is turned into a list of @scheme[part] instances with
@@ -181,7 +192,7 @@ module. When the document is built, the @scheme[scheme] form detects
 the binding for @scheme[list], and so it generates a reference to the
 specification of @scheme[list]. The setup process detects the
 reference, and it finds the matching specification in the existing
-documentation, and it ultimately directs the hyperlink to that
+documentation, and ultimately directs the hyperlink to that
 specification.
 
 Hyperlinks based on @scheme[for-label] and @scheme[scheme] are the
@@ -257,7 +268,7 @@ The following example illustrates section hyperlinks:
   See @secref{chickens}.
 }|
 
-Since the page is so short, it the hyperlinks in the above example are
+Since the page is so short, the hyperlinks in the above example are
  more effective if you change the @filepath{info.ss} file to add the
  @scheme['multi-file] flag:
 
@@ -287,7 +298,7 @@ manual:
 
 As mentioned in @secref{scheme-hyperlinks}, however, cross-document
 references based on @scheme[(require (for-label ....))] and
-@scheme[scheme] are usually better than to cross-document references
+@scheme[scheme] are usually better than cross-document references
 using @scheme[secref].
 
 @; ----------------------------------------
@@ -307,6 +318,8 @@ to import the binding information of @filepath{helper.ss}. Then add a
 binding with the module path as seen by a reader. Finally, use
 @scheme[defproc] to document the procedure:
 
+@; [Eli] This is also using `my-lib/helper' which doesn't work with
+@; planet libraries
 @verbatim[#:indent 2]|{
   #lang scribble/doc
   @(require scribble/manual
@@ -376,7 +389,7 @@ To use @scheme[examples], the procedures to document must be suitable
 for use at documentation time; in fact, @scheme[examples] uses
 bindings introduced into the document source by
 @scheme[require]. Thus, to generate examples using @scheme[my-helper]
-from the previous section, then @filepath{helper.ss} must be imported both
+from the previous section, @filepath{helper.ss} must be imported both
 via @scheme[require-for-label] and @scheme[require]:
 
 @verbatim[#:indent 2]|{
@@ -494,12 +507,12 @@ The difference between @scheme[table-of-contents] and
 @scheme[local-table-of-contents] is that the latter is ignored for
 Latex output.
 
-When using @scheme[local-table-of-contents], often it makes sense to
+When using @scheme[local-table-of-contents], it often makes sense to
 include introductory text before the call of
 @scheme[local-table-of-contents]. When the introductory text is less
 important and when when local table of contents is short, putting the
 introductory text after the call of @scheme[local-table-of-contents]
-make be appropriate.
+may be appropriate.
 
 @;----------------------------------------
 @include-section["style.scrbl"]

collects/scribblings/scribble/layers.scrbl

@@ -22,8 +22,8 @@ scribble/doc
 
 Besides making the file a module, this declaration selects the
 Scribble reader (instead of the usual Scheme reader), and it starts
-the body of the in ``text'' mode. The reader layer mostly leaves text
+the body of the file in ``text'' mode. The reader layer mostly leaves
-alone, but @litchar["@"] forms can escape to S-expression mode.
+text alone, but @litchar["@"] forms escape to S-expression mode.
 
 A module written as
 
@@ -79,7 +79,7 @@ The @scheme[decode] function produces a @scheme[part] structure
 instance that represents the document. To build the @scheme[part]
 instance, it inspects its arguments to find a @scheme[title-decl]
 value created by @scheme[title] to name the part, @scheme[part-start]
-values created @scheme[section] to designate sub-parts, etc.
+values created by @scheme[section] to designate sub-parts, etc.
 
 A @scheme[part] is the input to a rendering back-end, such as the HTML
 renderer. All renderers recognize a fixed structure hierarchy: the
@@ -105,7 +105,7 @@ The value bound to @scheme[doc] in the example above is something like
 ]
 
 Notice that the @litchar{'} in the input's @litchar{'tis} has turned
-into @scheme['rsquo] (a curly apostrophe). The conversion to use
+into @scheme['rsquo] (rendered as a curly apostrophe). The conversion to use
 @scheme['rsquo] was performed by @scheme[decode] via
 @scheme[decode-flow] via @scheme[decode-paragraph] via
 @scheme[decode-content] via @scheme[decode-string].
@@ -205,6 +205,9 @@ Working roughly from the bottom up, the Scribble layers are:
        for using cross-reference information, typically after a
        document is rendered (e.g., to search). See @secref["xref"].}
 
+ @item{@schememodname[scribble/text]: A language that uses
+       @schememodname[scribble/reader] preprocessing text files.}
+
 }
 
 The @exec{scribble} command-line utility generates output with a

collects/scribblings/scribble/preprocessor.scrbl

@@ -0,0 +1,42 @@
+#lang scribble/doc
+@(require scribble/manual
+          "utils.ss"
+          (for-label scheme/base))
+
+@title[#:tag "preprocessor"]{Text Preprocessor}
+
+@defmodulelang[scribble/text]{The @schememodname[scribble/text]
+language provides everything from @scheme[scheme/base] with a few
+changes that make it suitable as a preprocessor language:
+
+@itemize{
+
+  @item{It uses @scheme[read-inside-syntax] to read the body of the
+        module, similar to @secref["docreader"].}
+
+  @item{It has a custom printer (@scheme[current-print]) that displays
+        all values.  The printer is also installed as the
+        @scheme[port-display-handler] so it can be used through
+        @scheme[display] as well as @litchar{~a} in format strings.
+        The printer displays most values (as is usual for
+        @scheme[display]), except for
+        @itemize{@item{@scheme[void] and @scheme[#f] are not
+                       displayed,}
+                 @item{pairs are displayed recursively (just their
+                       contents, no parentheses),}
+                 @item{promises are forced, thunks are invoked.}}}}
+
+}
+
+This means that to write a text file that has scheme code, you simply
+write it as a module in the @scheme[scribble/text] language, and run
+it through @exec{mzscheme}.  Here is a sample file:
+
+@verbatim[#:indent 2]|{
+  #lang scribble/text
+  @(define (angled . body) (list "<" body ">"))@;
+  @(define (shout . body) @angled[(map string-upcase body)])@;
+  blah @angled{blah @shout{blah} blah} blah
+}|
+
+(Note how @litchar["@;"] is used to avoid empty lines in the output.)

collects/scribblings/scribble/scribble.scrbl

@@ -7,7 +7,10 @@
 
 Scribble is a collection of tools for creating prose documents,
 especially those that document libraries, and especially for HTML and
-PDF (via LaTeX) output.
+PDF (via LaTeX) output.  More generally, it is useful for cases where
+you need to deal with Scheme code that is rich in textual content: it
+has a syntactic extension for writing almost free-form text and a tool
+for using the scribble syntax for preprocessing text files.
 
 This document itself is written using Scribble. At the time that it
 was written, its source was available at
@@ -32,5 +35,6 @@ starting with the @filepath{scribble.scrbl} file.
 @include-section["eval.scrbl"]
 @include-section["bnf.scrbl"]
 @include-section["xref.scrbl"]
+@include-section["preprocessor.scrbl"]
 
 @index-section[]

collects/scribblings/scribble/style.scrbl

@@ -15,6 +15,8 @@ word. Thus, the
 description will often start with ``Produces.'' Refer to arguments and
 sub-forms by name.
 
+@; [Eli] It's probably a good idea to say here that it's better to
+@;   refer to "functions" instead of "procedures".
 Do not use the word ``argument'' to describe a sub-form in a syntactic
 form; use the term ``sub-form'' instead, reserving ``argument'' for
 values or expressions in a function call.  Refer to libraries and
@@ -67,7 +69,7 @@ typeset as variables. The correct description is
 @verbatim[#:indent 2]|{@scheme[(_rator-expr _rand-expr ...)]}|
 
 which produces @scheme[(_rator-expr _rand-expr ...)], where
-@schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as
+@schemeidfont{rator-expr} and @schemeidfont{rand-expr} are typeset as
 meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms
 greatly reduce this burden in descriptions, since they automatically
 set up meta-variable typesetting for non-literal identifiers. In
@@ -83,9 +85,11 @@ specific sequence of characters.
 
 When showing example evaluations, use the REPL-snapshot style:
 
-@interaction[
+@verbatim[#:indent 2]|{
-(+ 1 2)
+  @interaction[
-]
+  (+ 1 2)
+  ]
+}|
 
 See also the @scheme[scribble/eval] library.
 
@@ -98,6 +102,11 @@ In prose, use @litchar{``} and @litchar{''} quotation marks instead of
 @litchar{"}. Use @litchar{---} for an em-dash, and do not include
 spaces on either side, though it will typeset as an en-dash and spaces
 in HTML output. Use American style for quotation marks and punctuation
+@; [Eli] BTW, I've asked several people about this, and the general
+@;   agreement that I've seen is that this is a rather arbitrary rule
+@;   and there's no harm in doing the more logical thing of putting
+@;   the punctuations outside quotations and parens.  Just like you
+@;   did at the end of this sentence...
 at the end of quotation marks (i.e., a sentence-terminating period
 goes inside the quotation marks). Of course, this rule does not apply
 for quotation marks that are part of code.