commit b3c659f9d98f69f77aca55ce810f7e2677e99fc3
parent e03770064fc9c91b98c750ea92f962effe2d6ba4
Author: Eli Barzilay <eli@racket-lang.org>
Date: Thu, 28 Feb 2008 14:27:37 +0000
scribble/text documentation, and a few other fixes and comments
svn: r8821
original commit: 1e32dbd324467349743cde8516dadb4dcbe0dba9
Diffstat:
5 files changed, 97 insertions(+), 26 deletions(-)
diff --git a/collects/scribblings/scribble/how-to.scrbl b/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
- @schemeidfont{name} field. If you do not already have an
- @filepath{info.ss} module, here's a suitable complete module:
-
+ @; [Eli] `name' is not needed, but I think it's used by planet
+ As usual, you may want to add a descriptive
+ @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
- Scheme installation's the main @filepath{collects} directory,
- however, then the documentation is generated as
- @filepath{manual/index.html} in the installation's main
- @filepath{doc} directory.}
+ @; [Eli] I "fixed" the obvious typo in the following sentence,
+ @; but it's still weird and should probably be different.
+ @|PLaneT| package directory. If the collection is in PLT
+ Scheme's main @filepath{collects} directory, however, then the
+ 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"]
diff --git a/collects/scribblings/scribble/layers.scrbl b/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
-alone, but @litchar["@"] forms can escape to S-expression mode.
+the body of the file in ``text'' mode. The reader layer mostly leaves
+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
diff --git a/collects/scribblings/scribble/preprocessor.scrbl b/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.)
diff --git a/collects/scribblings/scribble/scribble.scrbl b/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[]
diff --git a/collects/scribblings/scribble/style.scrbl b/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[
-(+ 1 2)
-]
+@verbatim[#:indent 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.
