The _Scribble_ Collection ========================= The Scribble collection is a few libraries that can be used to create documents from Scheme. It is made of independently usable parts. For example, the reader can be used in any situation that requires lots of free-form text, or you can use the rendering portion directly to generate documents. Running Scribble ---------------- To process a Scribble document, use the `scribble' command-line utility (use `scribble -h' to see usage information). This is implemented by the "run-scribble.ss" module, which can be used directly: > (render-file input output format) Renders the given `input' file to the `output' file using the given format specification. The input and output files are used as is (no suffixes are added). The `output' argument can be #f, which will render the input to the current output port. `format' is a symbol that specifies the kind of output rendering (use the `scribble' commad to find the list of available formatters). A Scribble document is a MzScheme module file, which provides a `content' binding. The Scribble Reader ------------------- *** Introduction The @-reader is designed to be a convenient facility for using free-form text in Scheme code. "@" is chosen as one of the least-used characters in Scheme code (reasonable options are: "&" (969 uses in the collects hierarchy), "|" (1676), "@" (2105) "^" (2257) "$" (2259)). To use this file, you can use MzScheme's #reader form: #reader(lib "reader.ss" "scribble") but note that this will only do the concrete-level translation, and not give you any useful bindings. Alternatively, you can start MzScheme and use the `use-at-readtable' function to switch the current readtable to the at-readtable. You can do this in a single command line: mzscheme -Le reader.ss scribble "(use-at-readtable)" In addition to `read' and `read-syntax', which are used by #reader, the "reader.ss" library provides the procedures `read-inside' and `read-inside-syntax'; these `-inner' variants parse as if inside a "@{}", and they return a (syntactic) list. *** Concrete Syntax The *concrete* syntax of @-commands is (informally, more details below): "@" "[" ... "]" "{" ... "}" where all parts are optional, but at least one should be present. (Note: since the reader will try to see if there is a "{...body...}" in the input, it can be awkward to use body-less constructs on an interactive REPL since reading an expression succeeds only when there is a new expression available.) "@" is set as a terminating reader macro, so if you want to use it in Scheme code, you need to quote it with `\@' or the whole identifier with `|ba@rs|'. All of this has no effect on occurrences of "@" in Scheme strings, character constants etc. Roughly speaking, such a construct is read as: (

... ...) so the part determines what Scheme code the whole construct is translated into. The common case is when is a Scheme identifier, which generates a plain Scheme form with keyword-values and the body text. The body is given as a sequence of strings, with a separate "\n" string for each end of line. For example: @foo{bar baz --is-read-as--> (foo "bar baz" "\n" "blah") blah} It is your responsibility to make sure that `foo' is bound (in any way: it can be either a function or a macro). To see the forms, you can use quote as usual, for example: '@foo{bar} ** Concrete Syntax: the command part 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 (see below). 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 from the translation, resulting in an s-expression that usually contains just strings: @{foo bar --is-read-as--> ("foo bar" "\n" "baz") baz} @'{foo bar --is-read-as--> '("foo bar" "\n" "baz") baz} If the command part begins with a ";" (with no newline between the "@" and the ";"), then the construct is a comment. There are two comment forms, one for arbitrary-text and possibly nested comments, and another one for a -to-the-end-of-the-line comment: @; * { ...any-text-including-newlines... } @; Note that the first form is analogous to a "#;" comment: the commented body must still parse correctly. Also note that in the second form all text from the "@;" to the end of the line an all following (non-newline) whitespaces are part of the comment. For example: @foo{bar @; comment --is-read-as--> (foo "bar baz") baz} Tip: if you're editing in a Scheme-aware editor, it is useful to comment out blocks like this: @; { ... } or @;{ ... ;} otherwise you will probably confuse the editor into treating the file as having imbalanced parenthesis. If only the command part is specified, then the result is the command part only, without an extra set of parenthesis. This makes it suitable for Scheme escapes in body texts. More below, in the description of the body part. Finally, note that there are no special rules for using "@" in the command itself, which can lead to things like: @@foo{bar}{baz} --is-read-as--> ((foo "bar") "baz") To use "@" as in plain Scheme code, you need to quote it as you would quote other characters, for example: (define |@foo| '\@bar) ** Concrete Syntax: the body part 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 only character with special meaning is "@", in addition, braces, "|", and backslash can have special meanings but only in a few contexts. As described above, the text turns to a sequence of string arguments for the resulting form. Spaces at the beginning of lines are discarded (but see the information about indentation below), and newlines turn to individual "\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 @foo{ bar --is-read-as--> (foo "bar") <--is-read-as-- @foo{bar} } @foo{ bar } --is-read-as--> (foo " bar ") If an "@" appears in the input, 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. For example: @foo{a @bar{b} c} --is-read-as--> (foo "a " (bar "b") " c") If the nested "@" 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 "@" a general escape to arbitrary Scheme code: @foo{a @bar c} --is-read-as--> (foo "a " bar " c") @foo{a @(bar 2) c} --is-read-as--> (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 (/number/boolean) by a pair of bar characters. 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). Examples: @foo{foo @bar foo} --is-read-as--> (foo "foo " bar " foo") @foo{foo@bar.} --is-read-as--> (foo "foo" bar.) @foo{foo@|bar|.} --is-read-as--> (foo "foo" bar ".") @foo{foo@3.} --is-read-as--> (foo "foo" 3.0) @foo{foo@|3|.} --is-read-as--> (foo "foo" 3 ".") @foo{foo@|(f 1)|{bar}.} --is-read-as--> (foo "foo" (f 1) "{bar}.") Braces are only problematic because a "}" is used to mark the end of the text. They are therefore allowed, as long as they are balanced. For example: @foo{f{o}o} --is-read-as--> (foo "f{o}o") There is also an alternative syntax for the body, one that specifies a new marker for the end. To do this, use "|{" for the openning marker, optionally with additional characters between them (excluding "{", 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). For example: @foo|{...}| --is-read-as--> (foo "...") @foo|{foo{{{bar}| --is-read-as--> (foo "foo{{{bar") @foo|<{{foo{{{bar}}>| --is-read-as--> (foo "{foo{{{bar}") * Concrete Syntax: quoting in body texts To quote braces or "@", precede them with a backslash. Note that this is an irregular use of backslash quoting! To use "\@" 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. Examples: @foo{b\@ar} --is-read-as--> (foo "b@ar") @foo{b\\@ar} --is-read-as--> (foo "b\\@ar") @foo{b\\\@ar} --is-read-as--> (foo "b\\\\@ar") @foo{b\{\@\@ar} --is-read-as--> (foo "b{@@ar") @foo{b\ar} --is-read-as--> (foo "b\\ar") @foo{b\\ar} --is-read-as--> (foo "b\\\\ar") * Concrete Syntax: 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: - A spaces-string is added to each line according to its distance from the leftmost syntax object; - The first string is not prepended with indentation if it appears on the first line of output. Examples: @foo{ --is-read-as--> (foo "bar" "\n" bar " " "baz" "\n" baz "bbb") bbb} @foo{bar --is-read-as--> (foo "bar" "\n" baz " " "baz" "\n" bbb} "bbb") @foo{ bar --is-read-as--> (foo " bar" "\n" baz " " "baz" "\n" bbb} " " "bbb") @foo{bar --is-read-as--> (foo "bar" "\n" baz "baz" "\n" bbb} "bbb") @foo{ bar --is-read-as--> (foo " bar" "\n" baz "baz" "\n" bbb} "bbb") @foo{ bar --is-read-as--> (foo " bar" "\n" baz "baz" "\n" bbb} " " "bbb") Additional notes: - You can identify indentation strings at the syntax level by the fact that they have the same location information as the following syntax object; - This mechanism depends on line and column number information (`use-at-readtable' turns them on for the current input port); - To use this mechanism with nested commands that should preserve indentation, you will need to do some additional work since the nested use will have only its own indentation; - When using it on a command-line, you note that the reader is not aware of the "> " prompt, which might lead to confusing results. [The following is likely to change.] For situations where spaces at the beginning of lines matter (various verbatim environments), you should begin a line with a "|". It has no other special meaning -- so to use a "|" as the first character in the text, simply use another before it. @code{ |(define (foo x) --is-read-as--> (code "(define (foo x)" "\n" | |error|) " |error|)") } In other situations, newlines matter -- you might want to avoid 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 up-to and including the end of the line and all following whitespace. Example: @foo{bar @; baz@; --is-read-as--> (foo "bar baz.") .} A "|" that follows this is still used for marking the beginning of the text: @foo{bar @; baz@; --is-read-as--> (foo "bar baz .") | .} ** Concrete Syntax: the keyword-value part The keyword-value part can contain arbitrary Scheme expressions, which are simply stacked before the body text arguments: @foo[1 (* 2 3)]{bar} --is-read-as--> (foo 1 (* 2 3) "bar") @foo[@bar{...}]{blah} --is-read-as--> (foo (bar "...") "blah") But there is one change that makes it easy to use for keyword/values: (a) "=" is a terminating character in the textual scope, (b) if there is a "=" sequence (spaces optional), then it is converted to "#:identifier ": @foo[(* 2 3) a=b]{bar} --is-read-as--> (foo (* 2 3) #:a b "bar") *** How should this be used? This facility 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 the need for functions, for example: > (define (important . text) @`b{@u{@big{@,@text}}}) > (important @`p{This is an important announcement! Read it!}) (b (u (big (p "This is an important announcement!" "\n" "Read it!"))))