suzanne.soy/hyper-literate
1
0
Fork 0
Code Issues 4 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

updated screibble reader docs

Browse Source 
svn: r6865

original commit: 6355ad12f4eaaf9816643837fa560eb4f2395a76
This commit is contained in:
Eli Barzilay 2007-07-09 05:12:59 +00:00
parent 1de817fdf8
commit 5175a23e64
4 changed files with 564 additions and 397 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
collects/scribble/doc.txt
View File

@ -113,7 +113,7 @@ use Scheme's `quote'.
'@foo{bar} '@foo{bar}
** Concrete Syntax: The Command Part ** The Command Part
Besides being a Scheme identifier, the <cmd> part of an @-form can Besides being a Scheme identifier, the <cmd> part of an @-form can
have Scheme punctuation prefixes, which will end up wrapping the have Scheme punctuation prefixes, which will end up wrapping the
@ -145,7 +145,7 @@ contains, say, just strings:
If the command part begins with a ";" (with no newline between the "@" If the command part begins with a ";" (with no newline between the "@"
and the ";"), then the construct is a comment. There are two comment and the ";"), then the construct is a comment. There are two comment
forms, one for arbitrary-text and possibly nested comments, and forms, one for arbitrary-text and possibly nested comments, and
another one for a line comments: another one for line comments:
@;{<anything> ...} @;{<anything> ...}
@ -156,8 +156,9 @@ the description of the body syntax below. In the second form, all
text from the "@;" to the end of the line *and* all following spaces text from the "@;" to the end of the line *and* all following spaces
(or tabs) are part of the comment (similar to "%" comments in TeX). (or tabs) are part of the comment (similar to "%" comments in TeX).
@foo{bar @; comment --reads-as--> (foo "bar baz") @foo{bar @; comment --reads-as--> (foo "bar bazblah")
baz} baz@;
blah}
Tip: if you're editing in a Scheme-aware editor (like DrScheme or Tip: if you're editing in a Scheme-aware editor (like DrScheme or
Emacs), it is useful to comment out blocks like this: Emacs), it is useful to comment out blocks like this:
@ -183,7 +184,7 @@ in the command itself, which can lead to things like:
@@foo{bar}{baz} --reads-as--> ((foo "bar") "baz") @@foo{bar}{baz} --reads-as--> ((foo "bar") "baz")
** Concrete Syntax: The Datum Part ** The Datum Part
The datum part can contains arbitrary Scheme expressions, which are The datum part can contains arbitrary Scheme expressions, which are
simply stacked before the body text arguments: simply stacked before the body text arguments:
@ -211,14 +212,14 @@ keyword-value arguments that precede the body of text arguments.
@foo[#:style 'big]{bar} --reads-as--> (foo #:style 'big "bar") @foo[#:style 'big]{bar} --reads-as--> (foo #:style 'big "bar")
** Concrete Syntax: The Body Part ** The Body Part
The syntax of the body part is intended to be as convenient as The syntax of the body part is intended to be as convenient as
possible for free text. It can contain almost any text -- the only possible for free text. It can contain almost any text -- the only
characters with special meaning is "@" for sub forms, and "}" for the characters with special meaning is "@" for sub-@-forms, and "}" for
end of the text. In addition, a "{" is allowed as part of the text, the end of the text. In addition, a "{" is allowed as part of the
and it makes the matching "}" be part of the text too -- so balanced text, and it makes the matching "}" be part of the text too -- so
braces are valid text. balanced braces are valid text.
@foo{f{o}o} --reads-as--> (foo "f{o}o") @foo{f{o}o} --reads-as--> (foo "f{o}o")
@foo{{{}}{}} --reads-as--> (foo "{{}}{}") @foo{{{}}{}} --reads-as--> (foo "{{}}{}")
@ -269,19 +270,19 @@ of the text. This works for "@" too:
--reads-as--> --reads-as-->
(foo "@foo{bar} reads as (foo \"bar\")") (foo "@foo{bar} reads as (foo \"bar\")")
* Concrete Syntax: Alternative Body Syntax * Alternative Body Syntax
In addition, there is an alternative syntax for the body, one that In addition to the above, there is an alternative syntax for the body,
specifies a new marker for its end: use "|{" for the opening marker to one that specifies a new marker for its end: use "|{" for the opening
have the text terminated by a "}|". marker to have the text terminated by a "}|".
@foo|{...}| @foo|{...}|
--reads-as--> --reads-as-->
(foo "...") (foo "...")
@foo|{close with "}", open with "{"}| @foo|{"}" closes, "{" opens}|
--reads-as--> --reads-as-->
(foo "close with \"}\", open with \"{\"") (foo "\"}\" closes, \"{\" opens")
@foo|{Nesting |{is}| ok}| @foo|{Nesting |{is}| ok}|
--reads-as--> --reads-as-->
@ -325,7 +326,7 @@ string for confusing situations. This works well when you only need
to quote short pieces, and the above works well when you have larger to quote short pieces, and the above works well when you have larger
multi-line body texts. multi-line body texts.
* Concrete Syntax: Scheme Expression Escapes * Scheme Expression Escapes
In some cases, you may want to use a Scheme identifier (or a number or In some cases, you may want to use a Scheme identifier (or a number or
a boolean etc.) in a position that touches the following text; in a boolean etc.) in a position that touches the following text; in
@ -344,7 +345,7 @@ or datum part when you use this form.
@foo{foo@|(f 1)|{bar}} --reads-as--> (foo "foo" (f 1) "{bar}") @foo{foo@|(f 1)|{bar}} --reads-as--> (foo "foo" (f 1) "{bar}")
@foo{foo@|bar|[1]{baz}} --reads-as--> (foo "foo" bar "[1]{baz}") @foo{foo@|bar|[1]{baz}} --reads-as--> (foo "foo" bar "[1]{baz}")
This works for string expressions too, but not that unlike the above, This works for string expressions too, but note that unlike the above,
the string is (intentionally) not merged with the rest of the text: the string is (intentionally) not merged with the rest of the text:
@foo{x@"y"z} --reads-as--> (foo "xyz") @foo{x@"y"z} --reads-as--> (foo "xyz")
@ -370,7 +371,7 @@ is little point in Scheme code that uses braces.
@|{blah}| --reads-as--> ("blah") @|{blah}| --reads-as--> ("blah")
* Concrete Syntax: Comments * Comments
As noted above, there are two kinds of Scribble comments: "@;{...}" is As noted above, there are two kinds of Scribble comments: "@;{...}" is
a (nestable) comment for a whole body of text (following the same a (nestable) comment for a whole body of text (following the same
@ -396,7 +397,7 @@ get further control of the subforms.
Note how this is different from using "@||"s in that strings around it Note how this is different from using "@||"s in that strings around it
are not merged. are not merged.
* Concrete Syntax: Spaces, Newlines, and Indentation * Spaces, Newlines, and Indentation
The Scribble syntax treats spaces and newlines in a special way is The Scribble syntax treats spaces and newlines in a special way is
meant to be sensible for dealing with text. As mentioned above, meant to be sensible for dealing with text. As mentioned above,
@ -410,9 +411,9 @@ for spaces between a "{" and text, or between text and a "}".
@foo{ bar --reads-as--> (foo " bar" "\n" "baz ") @foo{ bar --reads-as--> (foo " bar" "\n" "baz ")
baz } baz }
A single newline that follows an open brace or precedes a closing brace is A single newline that follows an open brace or precedes a closing
discarded, unless there are only newlines in the body; other newlines brace is discarded, unless there are only newlines in the body; other
are read as a "\n" string newlines are read as a "\n" string
@foo{bar --reads-as--> (foo "bar") @foo{bar --reads-as--> (foo "bar")
} }
@ -603,3 +604,4 @@ Here is an example of this.
foo foo
bar bar
} }
--> "foo\n bar"

844
collects/scribblings/scribble/reader.scrbl
View File

@ -68,72 +68,79 @@ identifier with bars (@schemefont["|@foo|"]).
Of course, @litchar["@"] is not treated specially in Scheme strings, Of course, @litchar["@"] is not treated specially in Scheme strings,
character constants, etc. character constants, etc.
Roughly, a form matching the grammar above is read as Roughly, a form matching the above grammar is read as
@schemeblock[ @schemeblock[
(#, @nonterm{cmd} #, @kleenestar{@nonterm{datum}} #, @kleenestar{@nonterm{parsed-body}}) (#, @nonterm{cmd}
#, @kleenestar{@nonterm{datum}}
#, @kleenestar{@nonterm{parsed-body}})
] ]
where @nonterm{parsed-body} is the translation of each where @nonterm{parsed-body} is the translation of each
@nonterm{text-body} in the input. @nonterm{text-body} in the input. Thus, the initial @nonterm{cmd}
determines the Scheme code that the input is translated into. The
common case is when @nonterm{cmd} is a Scheme identifier, which
generates a plain Scheme form.
Thus, the initial @nonterm{cmd} determines the Scheme code that A @nonterm{text-body} is made of text, newlines, and nested
the input is translated into. The common case is when @nonterm{cmd} is a @"@"-forms. Note that the syntax for @"@"-forms is the same in a
Scheme identifier, which generates a plain Scheme form. @nonterm{text-body} context as in a Scheme context. A
@nonterm{text-body} that isn't an @"@"-form is converted to a string
expression for its @nonterm{parsed-body}, and newlines are converted
to @scheme["\n"] expressions.
A @nonterm{text-body} is either a sequence of characters without @scribble-examples|==={
@litchar["@"] or newlines, a newline by itself, or the translation of a @foo{bar baz
@at form. Note that the syntax for @at forms is the same in a blah}
@nonterm{text-body} context as in a Scheme context. A @foo{bar @baz[3]
@nonterm{text-body} that isn't a @at form is converted to a string for blah}
its @nonterm{parsed-body}: @foo{bar @baz{3}
blah}
@foo{bar @baz[2 3]{4 5}
blah}
}===|
@scribble-examples[ Note that spaces are not allowed before a @litchar["["] or a
#<<EOS @litchar["{"], or they will be part of the following text (or Scheme
@foo{bar baz code). (More on using braces in body texts below.)
blah}
EOS
#f @scribble-examples|==={
@foo{bar @baz[2 3] {4 5}}
}===|
#<<EOS When the above @"@"-forms appear in a Scheme expression context, the
@foo{bar @baz[3] lexical environment must provide bindings for @scheme[foo] (as a procedure or
blah} a macro).
EOS
#f
#<<EOS
@foo{bar @baz{3}
blah}
EOS
#f
#<<EOS
@foo{bar @baz[2 3]{4 5}
blah}
EOS
@; FIXME: need to show evaluation here (with the scribble syntax)
@schemeblock[
(let* ([formatter (lambda (fmt)
(lambda args (format fmt (apply string-append args))))]
[bf (formatter "*~a*")]
[it (formatter "/~a/")]
[ul (formatter "_~a_")]
[text string-append])
@text{@it{Note}: @bf{This is @ul{not} a pipe}.})
--> "/Note/: *This is _not_ a pipe*."
] ]
When the above @at forms appear in a Scheme expression context, If you want to see the expression that is actually being read, you can
the surrounding context must provide a binding for @scheme[foo] use Scheme's @scheme[quote].
(either as a procedure or macro). To just see the read result for a
@at form, you can always use Scheme's @scheme[quote]:
@scribble-examples[(list @litchar["'@foo{bar}"] @scheme['(foo "bar")])] @scribble-examples|==={
'@foo{bar}
}===|
@; - - - - - - - - - - - - - - - - - - - - - - - - @; - - - - - - - - - - - - - - - - - - - - - - - -
@subsection{The Command Part} @subsection{The Command Part}
Besides being a Scheme identifier, the @nonterm{cmd} part of an @at Besides being a Scheme identifier, the @nonterm{cmd} part of an
form can have Scheme punctuation prefixes, which will end up wrapping @"@"-form can have Scheme punctuation prefixes, which will end up
the @italic{whole} expression. wrapping the @italic{whole} expression.
@scribble-examples[ @scribble-examples|==={
"@`',@foo{blah}" @`',@foo{blah}
] }===|
When writing Scheme code, this means that @litchar["@`',@foo{blah}"] When writing Scheme code, this means that @litchar["@`',@foo{blah}"]
is exactly the same as @litchar["`@',@foo{blah}"] and is exactly the same as @litchar["`@',@foo{blah}"] and
@ -141,30 +148,24 @@ is exactly the same as @litchar["`@',@foo{blah}"] and
construct can appear in body texts with the same meaning, whereas the construct can appear in body texts with the same meaning, whereas the
other two would not work (see below). other two would not work (see below).
Even after Scheme punctuation, the @nonterm{cmd} itself is not limited After the optional punctuation prefix, the @nonterm{cmd} itself is not
to a Scheme identifier; it can be any Scheme expression. limited to identifiers; it can be @italic{any} Scheme expression.
@scribble-examples[ @scribble-examples|==={
"@(lambda (x) x){blah}" @(lambda (x) x){blah}
] @`(unquote foo){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 from the translation, resulting in an S-expression that usually
contains, say, just strings: contains, say, just strings:
@scribble-examples[ @scribble-examples|==={
#<<EOS
@{foo bar @{foo bar
baz} baz}
EOS
#f
#<<EOS
@'{foo bar @'{foo bar
baz} baz}
EOS }===|
]
If the command part begins with a @litchar{;} (with no newline between If the command part begins with a @litchar{;} (with no newline between
the @litchar["@"] and the @litchar{;}), then the construct is a the @litchar["@"] and the @litchar{;}), then the construct is a
@ -172,332 +173,489 @@ comment. There are two comment forms, one for arbitrary-text and
possibly nested comments, and another one for line comments: possibly nested comments, and another one for line comments:
@schemeblock[ @schemeblock[
#, @BNF-seq[@litchar["@;"] @kleenestar{@nonterm{whitespace}} @litchar["{"] @kleenestar{@nonterm{any}} @litchar["@"]] #, @BNF-seq[@litchar["@;{"] @kleenestar{@nonterm{any}} @litchar["}"]]
#, @BNF-seq[@litchar["@;"] @kleenestar{@nonterm{anythign-else-without-newline}}] #, @BNF-seq[@litchar["@;"] @kleenestar{@nonterm{anything-else-without-newline}}]
] ]
In the first form, the commented body must still parse correctly; see In the first form, the commented body must still parse correctly; see
the description of the body syntax below. the description of the body syntax below. In the second form, all
text from the @litchar["@;"] to the end of the line @italic{and} all
following spaces (or tabs) are part of the comment (similar to
@litchar["%"] comments in TeX).
Tip: if you're editing in some Scheme-mode, it is useful to comment out @scribble-examples|==={
blocks like this: @foo{bar @; comment
baz@;
blah}
}===|
@verbatim[#<<EOS Tip: if you're editing in a Scheme-aware editor (like DrScheme or
@; Emacs), it is useful to comment out blocks like this:
{
...
}
EOS
]
or @verbatim["
@verbatim[#<<EOS
@;{ @;{
... ...
;} ;}
EOS "]
]
otherwise you will probably confuse the editor into treating the file as so the editor does not treat the file as having unbalanced
having imbalanced parenthesis. parenthesis.
If only the @nonterm{cmd} part is specified of an @at form, then the If only the @nonterm{cmd} part of an @"@"-form is specified, then the
result is the command part only, without an extra set of parenthesis. result is the command part only, without an extra set of parenthesis.
This makes it suitable for Scheme escapes in body texts. More below, This makes it suitable for Scheme escapes in body texts. (More on this
in the description of the body part. below, in the description of the body part.)
@scribble-examples|==={
@foo{x @y z}
@foo{x @(* y 2) z}
@{@foo bar}
}===|
Finally, note that there are currently no special rules for using Finally, note that there are currently no special rules for using
@litchar["@"] in the command itself, which can lead to things like: @litchar["@"] in the command itself, which can lead to things like:
@scribble-examples[ @scribble-examples|==={
"@@foo{bar}{baz}" @@foo{bar}{baz}
] }===|
You should not rely on such behavior, since @litchar["@@"] might be used
differently in the future (e.g., making @litchar["@@"] be ``@at'' in a
body text).
@subsection{The Datum Part} @subsection{The Datum Part}
The datum part can contains arbitrary Scheme expressions, which The datum part can contains arbitrary Scheme expressions, which
are simply stacked before the body text arguments: are simply stacked before the body text arguments:
@scribble-examples[ @scribble-examples|==={
"@foo[1 (* 2 3)]{bar}" @foo[1 (* 2 3)]{bar}
"@foo[@bar{...}]{blah}" @foo[@bar{...}]{blah}
] }===|
@italic{This following is going to be removed, I think...} The body part can still be omitted, which is essentially an
alternative syntax for plain (non-textual) S-expressions:
But there is one change that makes it easy to use for keyword/values: @scribble-examples|==={
@litchar{=} is a terminating character in the textual scope, and it if @foo[bar]
there is a @BNF-seq[@nonterm{identifier} @litchar{=} @nonterm{expr}] @foo{bar @f[x] baz}
sequence (spaces optional), then it is converted to }===|
@schemefont{#:}@nonterm{identifier} @nonterm{expr}.
@scribble-examples[ The datum part can be empty, which makes no difference, except when
"@foo[(* 2 3) a=b]{bar}" the body is omitted. It is more common, however, to use an empty body
] for the same purpose.
@scribble-examples|==={
@foo[]{bar}
@foo[]
@foo
@foo{}
}===|
The most common use of the datum part is for Scheme forms that expect
keyword-value arguments that precede the body of text arguments.
@scribble-examples|==={
@foo[#:style 'big]{bar}
}===|
@subsection{The Body Part} @subsection{The Body Part}
The syntax of the body part is intended to be as convenient as The syntax of the body part is intended to be as convenient as
possible for writing free text. It can contain almost any text---the possible for free text. It can contain almost any text---the only
only character with special meaning is @litchar["@"]. In addition, characters with special meaning is @litchar["@"] for sub-@"@"-forms,
@litchar["{"], @litchar["}"], @litchar["|"], and @litchar["\\"] can and @litchar["}"] for the end of the text. In addition, a
have special meanings, but only in a few contexts. As described @litchar["{"] is allowed as part of the text, and it makes the
above, the text turns to a sequence of string arguments for the matching @litchar["}"] be part of the text too---so balanced braces
resulting form. Spaces at the beginning of lines are discarded (but are valid text.
see the information about indentation below), and newlines turn to
individual @scheme["\n"] strings. (Spaces are preserved on a
single-line text.) As part of trying to do the ``right thing,'' an
empty line at the beginning and at the end are discarded, so:
@scribble-examples[ @scribble-examples|==={
#<<EOS @foo{f{o}o}
@foo{{{}}{}}
}===|
As described above, the text turns to a sequence of string arguments
for the resulting form. Spaces at the beginning and end of lines are
discarded, and newlines turn to individual @scheme["\n"] strings
(i.e., they are not merged with other body parts). (See also the
information about newlines and indentation below.) Spaces are
@italic{not} discarded if they appear after the open @litchar["{"]
(before the closing @litchar["}"]) when there is also text that
follows (precedes) it; specifically, they are preserved in a
single-line body.
@scribble-examples|==={
@foo{bar}
@foo{ bar }
@foo[1]{ bar }
}===|
If @litchar["@"] appears in a body, then it is interpreted as Scheme
code, which means that the @"@"-reader is applied recursively, and the
resulting syntax appears as part of the S-expression, among other
string contents.
@scribble-examples|==={
@foo{a @bar{b} c}
}===|
If the nested @"@" construct has only a command---no body or datum
parts---it will not appear in a subform. Given that the command part
can be any Scheme expression, this makes @"@" a general escape to
arbitrary Scheme code.
@scribble-examples|==={
@foo{a @bar c}
@foo{a @(bar 2) c}
}===|
This is particularly useful with strings, which can be used to include
arbitrary text.
@scribble-examples|==={
@foo{This @"}" is a closing brace}
}===|
Note that the escaped string is (intentionally) merged with the rest
of the text. This works for @litchar["@"] too:
@scribble-examples|==={
@foo{The command prefix is @"@".}
@foo{@"@foo{bar}" reads as (foo "bar")}
}===|
@subsubsub*section{Alternative Body Syntax}
In addition to the above, there is an alternative syntax for the body,
one that specifies a new marker for its end: use @litchar["|{"] for
the opening marker to have the text terminated by a @litchar["}|"].
@scribble-examples|==={
@foo|{...}|
@foo|{"}" closes, "{" opens}|
@foo|{Nesting |{is}| ok}|
}===|
This applies to sub-@"@"-forms too---the @litchar["@"] must be
prefixed with a @litchar["|"]:
@scribble-examples|==={
@foo|{Maze
|@bar{is}
Life!}|
@foo|{Works for |@bar|{subforms}| too}|
}===|
Note that the subform uses its own delimiters, @litchar["{...}"] or
@litchar["|{...}|"]. This means that you can copy and paste Scribble
text with @"@"-forms freely, just prefix the @litchar["@"] if the
immediate surrounding text has a prefix.
For even better control, you can add characters in the opening
delimiter, between the @litchar["|"] and the @litchar["{"].
Characters that are put there (non alphanumeric ASCII characters only,
excluding @litchar["{"] and @litchar["@"]) should also be used for
sub-@"@"-forms, and the end-of-body marker should have these characters
in reverse order with paren-like characters (@litchar["("],
@litchar["["], @litchar["<"]) mirrored.
@scribble-examples|==={
@foo|<<<{Some @x{more} |@{text}|.}>>>|
@foo|!!{Blah |!!@bold{blah}...}!!|
}===|
Finally, remember that you can use an expression escape with a Scheme
string for confusing situations. This works well when you only need
to quote short pieces, and the above works well when you have larger
multi-line body texts.
@subsubsub*section{Scheme Expression Escapes}
In some cases, you may want to use a Scheme identifier (or a number or
a boolean etc.) in a position that touches the following text; in
these situations you should surround the escaped Scheme expression by
a pair of @litchar["|"] characters. The text inside the bars is
parsed as a Scheme expression.
@scribble-examples|==={
@foo{foo@bar.}
@foo{foo@|bar|.}
@foo{foo@3.}
@foo{foo@|3|.}
}===|
This form is a generic Scheme expression escape, there is no body text
or datum part when you use this form.
@scribble-examples|==={
@foo{foo@|(f 1)|{bar}}
@foo{foo@|bar|[1]{baz}}
}===|
This works for string expressions too, but note that unlike the above,
the string is (intentionally) not merged with the rest of the text:
@scribble-examples|==={
@foo{x@"y"z}
@foo{x@|"y"|z}
}===|
Expression escapes also work with @italic{any} number of expressions,
@scribble-examples|==={
@foo{x@|1 (+ 2 3) 4|y}
@foo{x@|*
*|y}
}===|
It seems that @litchar["@||"] has no purpose---but remember that these escapes
are never merged with the surrounding text, which can be useful when
you want to control the sub expressions in the form.
@scribble-examples|==={
@foo{Alice@||Bob@|
|Carol}
}===|
Note that @litchar["@|{...}|"] can be parsed as either an escape expression or
as a no-command @"@"-form. The latter is used in this case (since there
is little point in Scheme code that uses braces.
@scribble-examples|==={
@|{blah}|
}===|
@subsubsub*section{Comments}
As noted above, there are two kinds of Scribble comments: @litchar["@;{...}"] is
a (nestable) comment for a whole body of text (following the same
rules for @"@"-forms), and @litchar["@;..."] is a line-comment.
@scribble-examples|==={
@foo{First line@;{there is still a
newline at this point;}
Second line}
}===|
One useful property of line-comments is that they continue to the end
of the line @italic{and} all following spaces (or tabs). Using this,
you can get further control of the subforms.
@scribble-examples|==={
@foo{This is @;
a pretty long @;
single string-@;
argument.}
}===|
Note how this is different from using @litchar["@||"]s in that strings
around it are not merged.
@subsubsub*section{Spaces, Newlines, and Indentation}
The Scribble syntax treats spaces and newlines in a special way is
meant to be sensible for dealing with text. As mentioned above,
spaces at the beginning and end of body lines are discarded, except
for spaces between a @litchar["{"] and text, or between text and a
@litchar["}"].
@scribble-examples|==={
@foo{bar}
@foo{ bar }
@foo{ bar
baz }
}===|
A single newline that follows an open brace or precedes a closing
brace is discarded, unless there are only newlines in the body; other
newlines are read as a @scheme["\n"] string
@;FIXME empty lines are ignored in generated HTML output
@scribble-examples|==={
@foo{bar
}
@foo{ @foo{
bar bar
} }
EOS @foo{
#f bar
"@foo{bar}" }
"@foo{ bar }" @foo{
] bar
If @litchar["@"] appears in a body, then it is interpreted as Scheme
code, which means that the @|at|-reader will be applied recursively,
and the resulting syntax will appear as an argument, among other
string contents.
@scribble-examples[
"@foo{a @bar{b} c}"
]
If the nested @at construct has only a command---no body part---then
it does not appear in a subform. Given that the command part can be
any Scheme expression, this makes @at a general escape to arbitrary
Scheme code.
@scribble-examples[
"@foo{a @bar c}"
"@foo{a @(bar 2) c}"
]
In some cases, you may want to use a Scheme identifier (or a number or
a boolean) in a position that touches other text that can make an
identifier; in these situations you should surround the Scheme
identifier (or number or boolean) by a pair of @litchar["|"]. The
text inside the bars is parsed as a Scheme expression, but if that
fails, it is used as a quoted identifier; do not rely on this
behavior, and avoid using whitespace inside the bars. Also, if bars
are used, then no body text is used even if they are followed by
braces (see the next paragraph).
@scribble-examples[
"@foo{foo @bar foo}"
"@foo{foo@bar.}"
"@foo{foo@|bar|.}"
"@foo{foo@3.}"
"@foo{foo@|3|.}"
"@foo{foo@|(f 1)|{bar}.}"
]
Braces are only problematic because a @litchar["}"] is used to mark
the end of the text. They are therefore allowed, as long as they are
balanced.
@scribble-examples[
"@foo{f{o}o}"
]
There is also an alternative syntax for the body, one that specifies a
new marker for the end: use @litchar["|{"] for the openning marker,
optionally with additional characters between them (excluding
@litchar["{"], whitespace, and alphanumerics); the matching closing
marker should be the mirrored form of the openning marker (reverse the
characters and swap round, square, curly, and angle parentheses).
@scribble-examples[
"@foo|{...}|"
"@foo|{foo{{{bar}|"
"@foo|<{{foo{{{bar}}>|"
]
More simply, if you get into too much trouble with special characters
in a body, then it's often a good idea to use the Scheme part,
instead.
@scribble-examples[
"@foo[\"}\"]"
"@foo[\"@literally{}\"]"
]
@; - - - - - - - - - - - - - - - - - - - - - - - -
@subsubsub*section{Quoting in Body Texts}
To quote braces or @at, precede them with a backslash. Note that this
is an irregular use of backslash quoting! To use @litchar["\\@"] in
your text, simply precede it with a backslash. The general rule is
that to use N backslashes-and-a-special-character, you should precede
it with one extra backslash. Any other use of a backslash (one that
is not followed by more back-slashes and a special character) is
preserved in the text as usual.
@scribble-examples[
"@foo{b\\@ar}"
"@foo{b\\\\@ar}"
"@foo{b\\\\\\@ar}"
"@foo{b\\@\\@ar}"
"@foo{b\\ar}"
"@foo{b\\\\ar}"
]
@; - - - - - - - - - - - - - - - - - - - - - - - -
@subsubsub*section{Newlines and Indentation}
When indentation is used, all-space indentation string syntaxes are
perpended to the beginning of each line. The rule for adding these
string is:
@itemize{
@item{A spaces-string is added to each line according to its distance from
the leftmost syntax object;}
@item{The first string is not prepended with indentation if it appears on
the first line of output.}
}
@scribble-examples[
#<<EOS
@foo{
bar
baz baz
bbb} }
EOS @foo{
}
@foo{
#f }
@foo{ bar
baz }
}===|
#<<EOS In the parsed S-expression syntax, a single newline string is used for
@foo{bar all newlines; you can use @scheme[eq?] to identify this line. This
baz can be used to identify newlines in the original @nonterm{text-body}.
@; FIXME: need to show printout here (with the scribble syntax)
@schemeblock[
(let ([nl (car @'{
})])
(for-each (lambda (x) (display (if (eq? x nl) "\n... " x)))
@`{foo
@,@(list "bar" "\n" "baz")
blah})
(newline))
--prints-->
foo
... bar
baz
... blah
]
Spaces at the beginning of body lines do not appear in the resulting
S-expressions, but the column of each line is noticed, and all-space
indentation strings are added so the result has the same indentation.
A indentation string is added to each line according to its distance
from the leftmost syntax object (except for empty lines). (Note: if
you try these examples on a mzscheme REPL, you should be aware that
the reader does not know about the "@litchar["> "]" prompt.)
@scribble-examples|==={
@foo{
bar
baz
blah
}
@foo{
begin
x++;
end}
@foo{
a
b
c}
}===|
If the first string came from the openning @litchar["{"] line, it is
not prepended with an indentation (but it can affect the leftmost
syntax object used for indentation). This makes sense when formatting
structured code as well as text (see the last example in the following
block).
@;FIXME: last example too long, messes up output
@scribble-examples|==={
@foo{bar
baz
bbb}
@foo{ bar
baz
bbb}
@foo{bar
baz
bbb} bbb}
EOS
#f
#<<EOS
@foo{ bar
baz
bbb}
EOS
#f
#<<EOS
@foo{bar
baz
bbb}
EOS
#f
#<<EOS
@foo{ bar @foo{ bar
baz baz
bbb} bbb}
EOS @foo{ bar
baz
bbb}
@text{Some text@footnote{And a
footnote comment.}. More text.}
}===|
#f Note that each @"@"-form is parsed to an S-expression that has its own
indentation. This means that Scribble source can be indented like
code, but if indentation matters then you may need to apply
indentation of the outer item to all lines of the inner one. For
example, in
#<<EOS @litchar/lines|==={
@foo{ bar @code{
baz begin
bbb} i = 1, r = 1
EOS @bold{while i < n do
] r *= i++
done}
Additional notes: end
}
@itemize{ }===|
@item{You can identify indentation strings at the syntax level by the fact a formatter will need to apply the 2-space indentation to the
that they have the same location information as the following syntax rendering of the @scheme[bold] body.
object.}
Note that to get a first-line text to be counted as a leftmost line,
@item{This mechanism depends on line and column number information line and column accounting should be on for the input port
(@scheme[use-at-readtable] turns them on for the current input port);} (@scheme[use-at-readtable] turns them on for the current input port).
Without this,
@item{To use this mechanism with nested commands that should preserve
indentation, you will need to do some additional work since the nested @litchar/lines|==={
use will have only its own indentation;} @foo{x1
x2
@item{When using it on a command-line, you note that the reader is not aware x3}
of the ``> '' prompt, which might lead to confusing results.} }===|
} will not have 2-space indentations in the parsed S-expression if
source accounting is not on, but
@italic{The following is likely to change.}
@litchar/lines|==={
For situations where spaces at the beginning of lines matter (various @foo{x1
verbatim environments), you should begin a line with a @litchar["|"]. x2
It has no other special meaning -- so to use a @litchar["|"] as the x3}
first character in the text, simply use another before it. }===|
@scribble-examples[ will (due to the last line). Pay attention to this, as it can be a
#<<EOS problem with Scheme code, for example:
@code{
|(define (foo x) @litchar/lines|==={
| |error|) @code{(define (foo x)
} (+ x 1))}
EOS }===|
]
For rare situations where spaces at the beginning (or end) of lines
In other situations, newlines matter; you might want to avoid a matter, you can begin (or end) a line with a "@||".
newline token in some place. To avoid a newline and still break the
source line, use a line comment. As in TeX, these will consume text @scribble-examples|==={
up-to and including the end of the line and all following whitespace. @foo{
@|| bar @||
@bold{@italic{The following examples from the original docs didn't @|| baz}
work. They have been changed!}} }===|
@scribble-examples[ Finally, you might be need a verbatim-like environment, where the
#<<EOS parsed body matches exactly the textual source. To make this
@foo{bar @; possible, the @"@"-parser uses syntax properties on the resulting
baz@; syntax values. All items that are not physically in the Scribble
!} source---newlines and indentation-spaces---have a 'scribble property.
EOS An indentation string will have @scheme['indentation] as the value of
] @bold{The "!" above used to be a "."} this property, and a newline will have a @scheme['(newline S)] value
where S is the original newline string including spaces that precede
A @litchar["|"] that follows this is still used for marking the and follow it (which includes the indentation for the following item).
beginning of the text: To implement a verbatim environment you need to drop indentation
strings, and use the original newline strings instead of the
@scribble-examples[ single-newline string. Here is an example of this.
#<<EOS
@foo{bar @; @; FIXME: need to show evaluation here (with the scribble syntax)
baz@; @schemeblock[
? .} (define-syntax (verb stx)
EOS (syntax-case stx ()
] @bold{The "?" above used to be a "|", which is surely part of the point.} [(_ cmd item ...)
;;FIXME: show a "#`" in the rendering of the following line
#`(cmd .
@; ------------------------------------------------------------------------ ;;FIXME: the next line should begin with a #,
@subsection{How To Use the Reader} ,(let loop ([items (syntax->list #'(item ...))])
(if (null? items)
The reader can be used in any way you want. All you need is to use '()
function names that you bind. You can even use quasi-quotes, skipping (let* ([fst (car items)]
the need for functions, for example: [prop (syntax-property fst 'scribble)]
[rst (loop (cdr items))])
@verbatim[ (cond [(not prop) (cons fst rst)]
#<<EOS [(eq? prop 'indentation) rst]
> (define (important . text) @`b{@u{@big{@,@text}}}) [else (cons (datum->syntax-object
> (important @`p{An important announcement! fst (cadr prop) fst)
Read it!}) rst)])))))]))
(b (u (big (p "An important announcement!" "\n" "Read it!")))) @verb[string-append]{
EOS foo
bar
}
--> "foo\n bar"
] ]

2
collects/scribblings/scribble/scribble.scrbl
View File

@ -23,7 +23,7 @@ The layers are:
@itemize{ @itemize{
@item{@file{reader.ss}: a reader that extends the syntax of Scheme @item{@file{reader.ss}: a reader that extends the syntax of Scheme
with @at forms for conveniently embedding a mixin of text and with @"@"-forms for conveniently embedding a mixin of text and
escapes. See @secref["reader"].} escapes. See @secref["reader"].}
@item{@file{struct.ss}: a set of document datatypes, which define the @item{@file{struct.ss}: a set of document datatypes, which define the

67
collects/scribblings/scribble/utils.ss
View File

@ -6,21 +6,17 @@
(prefix scribble: (lib "reader.ss" "scribble")) (prefix scribble: (lib "reader.ss" "scribble"))
(lib "string.ss")) (lib "string.ss"))
(provide at (provide scribble-examples litchar/lines)
litchar/lines
scribble-examples)
(define at "@") (define (litchar/lines . strs)
(let ([strs (regexp-split #rx"\n" (apply string-append strs))])
(define (litchar/lines s)
(let ([strs (regexp-split #rx"\n" s)])
(if (= 1 (length strs)) (if (= 1 (length strs))
(litchar s) (litchar (car strs))
(make-table (make-table
#f #f
(map (lambda (s) (map (lambda (s)
(list (make-flow (list (make-paragraph (list (litchar s))))))) (list (make-flow (list (make-paragraph (list (litchar s)))))))
strs))))) strs)))))
(define (as-flow e) (define (as-flow e)
(make-flow (list (if (flow-element? e) (make-flow (list (if (flow-element? e)
@ -72,20 +68,31 @@
p)])) p)]))
(define (scribble-examples . lines) (define (scribble-examples . lines)
(make-table (define reads-as (make-paragraph (list spacer "reads as" spacer)))
#f (let* ([lines (apply string-append lines)]
(map (lambda (line) [p (open-input-string lines)])
(let ([line (if (string? line) (port-count-lines! p)
(list (litchar/lines line) (let loop ([r '()] [newlines? #f])
(scheme:to-paragraph (regexp-match? #px#"^[[:space:]]*" p)
(let ([p (open-input-string line)]) (let* ([p1 (file-position p)]
(port-count-lines! p) [stx (scribble:read-syntax #f p)]
(if (regexp-match? #rx"\n" line) [p2 (file-position p)])
((norm-spacing 0) (scribble:read-syntax #f p)) (if (not (eof-object? stx))
(scribble:read p))))) (let ([str (substring lines p1 p2)])
line)]) (loop (cons (list str stx) r)
(list (as-flow spacer) (or newlines? (regexp-match? #rx#"\n" str))))
(as-flow (if line (car line) "")) (let* ([r (reverse! r)]
(as-flow (if line (make-paragraph (list spacer "reads as" spacer)) "")) [r (if newlines?
(as-flow (if line (cadr line) ""))))) (cdr (apply append! (map (lambda (x) (list #f x)) r)))
lines)))) r)])
(make-table
#f
(map (lambda (x)
(let ([@expr (if x (litchar/lines (car x)) "")]
[sexpr (if x
(scheme:to-paragraph
((norm-spacing 0) (cadr x)))
"")]
[reads-as (if x reads-as "")])
(map as-flow (list spacer @expr reads-as sexpr))))
r)))))))))