suzanne.soy/scribble-enhanced
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

typo

Browse Source 
svn: r6811

original commit: c2be2dd1fa1971a3e513d143ced1397199d6ab10
This commit is contained in:
Eli Barzilay 2007-07-03 17:53:48 +00:00
parent 9b970e0f57
commit 3eb059df5a
1 changed files with 96 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
collects/scribble/doc.txt
View File

@ -1,11 +1,11 @@
The _Scribble_ Collection The _Scribble_ Collection
========================= =========================
The Scribble collection is a few libraries that can be used to create The Scribble collection contains a few libraries that can be used to
documents from Scheme. It is made of independently usable parts. For create documents from Scheme. It is made of independently usable
example, the reader can be used in any situation that requires lots of parts. For example, the reader can be used in any situation that
free-form text, or you can use the rendering portion directly to requires lots of free-form text, or you can use the rendering portion
generate documents. directly to generate documents.
Running Scribble Running Scribble
@ -33,78 +33,123 @@ The Scribble Reader
*** Introduction *** Introduction
The @-reader is designed to be a convenient facility for using free-form The Scribble @-reader is designed to be a convenient facility for
text in Scheme code. "@" is chosen as one of the least-used characters using free-form text in Scheme code, where "@" is chosen as one of
in Scheme code (reasonable options are: "&" (969 uses in the collects the least-used characters in Scheme code.
hierarchy), "|" (1676), "@" (2105) "^" (2257) "$" (2259)).
To use this file, you can use MzScheme's #reader form: You can use the reader via MzScheme's `#reader' form:
#reader(lib "reader.ss" "scribble") #reader(lib "reader.ss" "scribble")@{This is free-form text!}
but note that this will only do the concrete-level translation, and not Note that the reader will only read @-forms as S-expressions. The
give you any useful bindings. Alternatively, you can start MzScheme and meaning of these S-expressions depends on the rest of your own code.
use the `use-at-readtable' function to switch the current readtable to
the at-readtable. You can do this in a single command line: A PLT Scheme manual more likely starts with
#reader(lib "docreader.ss" "scribble")
which installs a reader, wraps the file content afterward into a
MzScheme module, and parses the body into a document using
"decode.ss".
Another way to use the reader is to use the `use-at-readtable'
function to switch the current readtable to a readtable that parses
@-forms. You can do this in a single command line:
mzscheme -Le reader.ss scribble "(use-at-readtable)" mzscheme -Le reader.ss scribble "(use-at-readtable)"
In addition to `read' and `read-syntax', which are used by #reader, In addition to `read' and `read-syntax', which are used by `#reader',
the "reader.ss" library provides the procedures `read-inside' and the "reader.ss" library provides the procedures `read-inside' and
`read-inside-syntax'; these `-inner' variants parse as if inside a `read-inside-syntax'; these `-inner' variants parse as if starting
"@{}", and they return a (syntactic) list. inside a "@{...}", and they return a (syntactic) list.
*** Concrete Syntax *** Concrete Syntax
The *concrete* syntax of @-commands is (informally, more details below): Informally, the concrete syntax of @-forms is:
"@" <cmd> "[" <key-val> ... "]" "{" <body> ... "}" "@" <cmd> "[" <datum> ... "]" "{" <text-body> ... "}"
where all parts are optional, but at least one should be present. where all three parts after "@" are optional, but at least one should
(Note: since the reader will try to see if there is a "{...body...}" in be present. (Note that spaces are not allowed between the three
the input, it can be awkward to use body-less constructs on an parts.) @litchar["@"] is set as a non-terminating reader macro, so it
interactive REPL since reading an expression succeeds only when there is can be used as usual in Scheme identifiers unless you want to use it
a new expression available.) "@" is set as a terminating reader macro, as a first character of an identifier; in this case you need to quote
so if you want to use it in Scheme code, you need to quote it with `\@' with a backslash (`\@foo@') or quote the whole identifier with bars
or the whole identifier with `|ba@rs|'. All of this has no effect (`|@foo|'). Of course, "@" is not treated specially in Scheme
on occurrences of "@" in Scheme strings, character constants etc. strings, character constants, etc.
Roughly speaking, such a construct is read as: Roughly, a form matching the above grammar is read as
(<cmd> <key-val> ... <body> ...) (<cmd> <datum> ... <parsed-body> ...)
so the <cmd> part determines what Scheme code the whole construct is where <parsed-body> is the translation of each <text-body> in the
translated into. The common case is when <cmd> is a Scheme identifier, input. Thus, the initial <cmd> determines the Scheme code that the
which generates a plain Scheme form with keyword-values and the body input is translated into. The common case is when <cmd> is a Scheme
text. The body is given as a sequence of strings, with a separate "\n" identifier, which generates a plain Scheme form.
string for each end of line. For example:
@foo{bar baz --is-read-as--> (foo "bar baz" "\n" "blah") A <text-body> is made of character sequences, newlines, and nested
@-forms. Note that the syntax for @-forms is the same in a
<text-body> context as in a Scheme context. A <text-body> that isn't
an @-form is converted to a string expression for its <parsed-body>,
and newlines are converted to "\n" expressions:
@foo{bar baz
blah} blah}
--is-read-as-->
(foo "bar baz" "\n" "blah")
It is your responsibility to make sure that `foo' is bound (in any way: @foo{bar @baz[3]
it can be either a function or a macro, or in quoted forms). To see the blah}
forms, you can use quote as usual, for example: --is-read-as-->
(foo (baz 3) "\n" "blah")
@foo{bar @baz{3}
blah}
--is-read-as-->
(foo "bar " (baz "3") "\n" "blah")
@foo{bar @baz[2 3]{4 5}
blah}
--is-read-as-->
(foo "bar " (baz 2 3 "4 5") "\n" "blah")
When the above @-forms appear in a Scheme expression context, the
context must provide bindings for `foo' (as a procedure or macro). To
just see the read result for an @-form, you can always a Scheme
`quote':
'@foo{bar} '@foo{bar}
** Concrete Syntax: the command part ** Concrete Syntax: The Command Part
Besides being a Scheme identifier, the <cmd> part of an @-form can be
any Scheme expression. The expression can have Scheme punctuation
prefixes, which will end up wrapping the *whole* expression.
@`',@foo{blah}
--is-read-as-->
`',@(foo "blah")
When writing Scheme code, this means that @`',@foo{blah} is exactly
the same as `@',@foo{blah} and `',@@foo{blah}, but unlike the latter
two, the first construct can appear in body texts with the same
meaning, whereas the other two would not work (see below).
As mentioned above, the command itself is not limited to a Scheme
identifier; it can be any Scheme expression.
@(lambda (x) x){blah}
--is-read-as-->
((lambda (x) x) "blah")
The command can have Scheme punctuation prefixes, which will end up
wrapping the *whole* expression. For example:
@`',@foo{blah} --is-read-as--> `',@(foo "blah")
When writing Scheme code, this means that @`',@foo{blah} is exactly the
same as `@',@foo{blah} and `',@@foo{blah}, but unlike the latter two,
the first construct can appear in @-body texts with the same meaning,
whereas the other two would not work (the punctuations will be taken as
part of the text).
The command itself is not limited to a Scheme identifier -- it can be
any Scheme expression:
@(lambda (x) x){blah} --is-read-as--> ((lambda (x) x) "blah")
In addition, the command can be omitted altogether, which will omit it In addition, the command can be omitted altogether, which will omit it
from the translation, resulting in an s-expression that usually contains from the translation, resulting in an s-expression that usually contains