Add link to the syntax of the @-reader.
Also defines the "@-form" term in the @-syntax section due to its frequency. Closes PR-12589. original commit: 61db1d64058214426343bb50d0dfa5c5300a0d29
This commit is contained in:
parent
77d079a3ed
commit
903e0a62ed
|
@ -40,7 +40,7 @@ the document body. Using @racketmodname[scribble/base] after
|
||||||
Besides making the file a module, each of the @hash-lang[]
|
Besides making the file a module, each of the @hash-lang[]
|
||||||
declarations selects the Scribble reader (instead of the usual Racket
|
declarations selects the Scribble reader (instead of the usual Racket
|
||||||
reader), and it starts the body of the file in ``text'' mode. The
|
reader), and it starts the body of the file in ``text'' mode. The
|
||||||
reader layer mostly leaves text alone, but @litchar["@"] forms escape
|
reader layer mostly leaves text alone, but @tech{@"@"-forms} escape
|
||||||
to S-expression mode.
|
to S-expression mode.
|
||||||
|
|
||||||
A module written as
|
A module written as
|
||||||
|
@ -165,7 +165,7 @@ Working roughly from the bottom up, the Scribble layers are:
|
||||||
@itemize[
|
@itemize[
|
||||||
|
|
||||||
@item{@racketmodname[scribble/reader]: A reader that extends the
|
@item{@racketmodname[scribble/reader]: A reader that extends the
|
||||||
syntax of Racket with @"@"-forms for conveniently embedding a
|
syntax of Racket with @tech{@"@"-forms} for conveniently embedding a
|
||||||
mixin of text and escapes. See @secref["reader"].}
|
mixin of text and escapes. See @secref["reader"].}
|
||||||
|
|
||||||
@item{@racketmodname[scribble/core]: A set of document datatypes
|
@item{@racketmodname[scribble/core]: A set of document datatypes
|
||||||
|
|
|
@ -22,7 +22,7 @@ You can use the reader via Racket's @racketfont{#reader} form:
|
||||||
or use the @racket[at-exp] meta-language as described in
|
or use the @racket[at-exp] meta-language as described in
|
||||||
@secref["at-exp-lang"].
|
@secref["at-exp-lang"].
|
||||||
|
|
||||||
Note that the Scribble reader reads @"@"-forms as S-expressions. This
|
Note that the Scribble reader reads @tech{@"@"-forms} as S-expressions. This
|
||||||
means that it is up to you to give meanings for these expressions in
|
means that it is up to you to give meanings for these expressions in
|
||||||
the usual way: use Racket functions, define your functions, or require
|
the usual way: use Racket functions, define your functions, or require
|
||||||
functions. For example, typing the above into @exec{racket} is likely
|
functions. For example, typing the above into @exec{racket} is likely
|
||||||
|
@ -44,7 +44,7 @@ into a document using @racketmodname[scribble/decode]. See
|
||||||
|
|
||||||
Another way to use the reader is to use the @racket[use-at-readtable]
|
Another way to use the reader is to use the @racket[use-at-readtable]
|
||||||
function to switch the current readtable to a readtable that parses
|
function to switch the current readtable to a readtable that parses
|
||||||
@"@"-forms. You can do this in a single command line:
|
@tech{@"@"-forms}. You can do this in a single command line:
|
||||||
|
|
||||||
@commandline{racket -ile scribble/reader "(use-at-readtable)"}
|
@commandline{racket -ile scribble/reader "(use-at-readtable)"}
|
||||||
|
|
||||||
|
@ -145,7 +145,7 @@ is an example of this.
|
||||||
@section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language}
|
@section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language}
|
||||||
|
|
||||||
@defmodulelang[at-exp]{The @racketmodname[at-exp] language installs
|
@defmodulelang[at-exp]{The @racketmodname[at-exp] language installs
|
||||||
@"@"-reader support in the readtable, and then chains to the reader of
|
@seclink["reader"]{@"@"-reader} support in the readtable, and then chains to the reader of
|
||||||
another language that is specified immediately after
|
another language that is specified immediately after
|
||||||
@racketmodname[at-exp].}
|
@racketmodname[at-exp].}
|
||||||
|
|
||||||
|
@ -216,7 +216,7 @@ resulting reader in several ways:
|
||||||
@item{@racket[readtable] --- a readtable to base the @"@"-readtable
|
@item{@racket[readtable] --- a readtable to base the @"@"-readtable
|
||||||
on.}
|
on.}
|
||||||
|
|
||||||
@item{@racket[command-char] --- the character used for @"@"-forms.}
|
@item{@racket[command-char] --- the character used for @tech{@"@"-forms}.}
|
||||||
|
|
||||||
@item{@racket[datum-readtable] --- determines the readtable used for
|
@item{@racket[datum-readtable] --- determines the readtable used for
|
||||||
reading the datum part. A @racket[#t] values uses the
|
reading the datum part. A @racket[#t] values uses the
|
||||||
|
@ -229,7 +229,7 @@ resulting reader in several ways:
|
||||||
@item{@racket[syntax-post-proc] --- function that is applied on
|
@item{@racket[syntax-post-proc] --- function that is applied on
|
||||||
each resulting syntax value after it has been parsed (but before it
|
each resulting syntax value after it has been parsed (but before it
|
||||||
is wrapped quoting punctuations). You can use this to further
|
is wrapped quoting punctuations). You can use this to further
|
||||||
control uses of @"@"-forms, for example, making the command be the
|
control uses of @tech{@"@"-forms}, for example, making the command be the
|
||||||
head of a list:
|
head of a list:
|
||||||
|
|
||||||
@racketblock[
|
@racketblock[
|
||||||
|
|
|
@ -40,7 +40,7 @@ in this chapter.
|
||||||
@;--------------------------------------------------------------------
|
@;--------------------------------------------------------------------
|
||||||
@section{The Scribble Syntax at a Glance}
|
@section{The Scribble Syntax at a Glance}
|
||||||
|
|
||||||
To review @secref["how-to:reader"], the concrete syntax of @"@"-forms
|
To review @secref["how-to:reader"], the concrete syntax of @deftech{@"@"-forms}
|
||||||
is roughly
|
is roughly
|
||||||
|
|
||||||
@racketblock[
|
@racketblock[
|
||||||
|
@ -103,7 +103,7 @@ prints the output
|
||||||
|
|
||||||
@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}}
|
@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}}
|
||||||
|
|
||||||
Here are more examples of @"@"-forms:
|
Here are more examples of @tech{@"@"-forms}:
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
@foo{blah "blah" (`blah'?)}
|
@foo{blah "blah" (`blah'?)}
|
||||||
|
@ -121,9 +121,9 @@ Here are more examples of @"@"-forms:
|
||||||
As seen in the last example, multiple lines and the newlines that
|
As seen in the last example, multiple lines and the newlines that
|
||||||
separate them are parsed to multiple Racket strings. More generally,
|
separate them are parsed to multiple Racket strings. More generally,
|
||||||
a @nonterm{text-body} is made of text, newlines, and nested
|
a @nonterm{text-body} is made of text, newlines, and nested
|
||||||
@"@"-forms, where the syntax for @"@"-forms is the same whether it's
|
@tech{@"@"-forms}, where the syntax for @tech{@"@"-forms} is the same whether it's
|
||||||
in a @nonterm{text-body} context as in a Racket context. A
|
in a @nonterm{text-body} context as in a Racket context. A
|
||||||
@nonterm{text-body} that isn't an @"@"-form is converted to a string
|
@nonterm{text-body} that isn't an @tech{@"@"-form} is converted to a string
|
||||||
expression for its @nonterm{parsed-body}; newlines and following
|
expression for its @nonterm{parsed-body}; newlines and following
|
||||||
indentations are converted to @racket["\n"] and all-space string
|
indentations are converted to @racket["\n"] and all-space string
|
||||||
expressions.
|
expressions.
|
||||||
|
@ -137,8 +137,8 @@ expressions.
|
||||||
*p = '\n';}
|
*p = '\n';}
|
||||||
}===|
|
}===|
|
||||||
|
|
||||||
The command part of an @"@"-form is optional as well. In that case,
|
The command part of an @tech{@"@"-form} is optional as well. In that case,
|
||||||
the @"@" form is read as a list, which usually counts as a function
|
the @tech{@"@"-form} is read as a list, which usually counts as a function
|
||||||
application, but it also useful when quoted with the usual Racket
|
application, but it also useful when quoted with the usual Racket
|
||||||
@racket[quote]:
|
@racket[quote]:
|
||||||
|
|
||||||
|
@ -191,7 +191,7 @@ In some cases, a text contains many literal @"@"s, which can be
|
||||||
cumbersome to quote individually. For such case, braces have an
|
cumbersome to quote individually. For such case, braces have an
|
||||||
alternative syntax: A block of text can begin with a
|
alternative syntax: A block of text can begin with a
|
||||||
``@litchar["|{"]'' and terminated accordingly with a
|
``@litchar["|{"]'' and terminated accordingly with a
|
||||||
``@litchar["}|"]''. Furthermore, any nested @"@" forms must begin
|
``@litchar["}|"]''. Furthermore, any nested @tech{@"@"-forms} must begin
|
||||||
with a ``@litchar["|@"]''.
|
with a ``@litchar["|@"]''.
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
|
@ -236,7 +236,7 @@ code). (More on using braces in body texts below.)
|
||||||
Finally, remember that the Scribble is just an alternate for
|
Finally, remember that the Scribble is just an alternate for
|
||||||
S-expressions. Identifiers still get their meaning, as in any
|
S-expressions. Identifiers still get their meaning, as in any
|
||||||
Racket code, through the lexical context in which they appear.
|
Racket code, through the lexical context in which they appear.
|
||||||
Specifically, when the above @"@"-form appears in a Racket expression
|
Specifically, when the above @tech{@"@"-form} appears in a Racket expression
|
||||||
context, the lexical environment must provide bindings for
|
context, the lexical environment must provide bindings for
|
||||||
@racket[foo] as a procedure or a macro; it can be defined, required,
|
@racket[foo] as a procedure or a macro; it can be defined, required,
|
||||||
or bound locally (with @racket[let], for example).
|
or bound locally (with @racket[let], for example).
|
||||||
|
@ -264,7 +264,7 @@ or bound locally (with @racket[let], for example).
|
||||||
@section{The Command Part}
|
@section{The Command Part}
|
||||||
|
|
||||||
Besides being a Racket identifier, the @nonterm{cmd} part of an
|
Besides being a Racket identifier, the @nonterm{cmd} part of an
|
||||||
@"@"-form can have Racket punctuation prefixes, which will end up
|
@tech{@"@"-form} can have Racket punctuation prefixes, which will end up
|
||||||
wrapping the @italic{whole} expression.
|
wrapping the @italic{whole} expression.
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
|
@ -321,7 +321,7 @@ following spaces (or tabs) are part of the comment (similar to
|
||||||
}===|
|
}===|
|
||||||
|
|
||||||
Tip: if you use an editor in some Scheme mode without support for
|
Tip: if you use an editor in some Scheme mode without support for
|
||||||
@"@"-forms, balanced comments can be confusing, since the open brace
|
@tech{@"@"-forms}, balanced comments can be confusing, since the open brace
|
||||||
looks commented out, and the closing one isn't. In such cases it is
|
looks commented out, and the closing one isn't. In such cases it is
|
||||||
useful to ``comment'' out the closing brace too:
|
useful to ``comment'' out the closing brace too:
|
||||||
|
|
||||||
|
@ -334,7 +334,7 @@ useful to ``comment'' out the closing brace too:
|
||||||
so the editor does not treat the file as having unbalanced
|
so the editor does not treat the file as having unbalanced
|
||||||
parentheses.
|
parentheses.
|
||||||
|
|
||||||
If only the @nonterm{cmd} part of an @"@"-form is specified, then the
|
If only the @nonterm{cmd} part of an @tech{@"@"-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 Racket escapes in body texts. (More on this
|
This makes it suitable for Racket escapes in body texts. (More on this
|
||||||
below, in the description of the body part.)
|
below, in the description of the body part.)
|
||||||
|
@ -394,7 +394,7 @@ keyword-value arguments that precede the body of text arguments.
|
||||||
|
|
||||||
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 @litchar["@"] for sub-@"@"-forms,
|
characters with special meaning is @litchar["@"] for sub-@tech{@"@"-forms},
|
||||||
and @litchar["}"] for the end of the text. In addition, a
|
and @litchar["}"] for the end of the text. In addition, a
|
||||||
@litchar["{"] is allowed as part of the text, and it makes the
|
@litchar["{"] is allowed as part of the text, and it makes the
|
||||||
matching @litchar["}"] be part of the text too---so balanced braces
|
matching @litchar["}"] be part of the text too---so balanced braces
|
||||||
|
@ -468,7 +468,7 @@ the opening marker to have the text terminated by a @litchar["}|"].
|
||||||
@foo|{Nesting |{is}| ok}|
|
@foo|{Nesting |{is}| ok}|
|
||||||
}===|
|
}===|
|
||||||
|
|
||||||
This applies to sub-@"@"-forms too---the @litchar["@"] must be
|
This applies to sub-@tech{@"@"-forms} too---the @litchar["@"] must be
|
||||||
prefixed with a @litchar{|}:
|
prefixed with a @litchar{|}:
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
|
@ -480,14 +480,14 @@ prefixed with a @litchar{|}:
|
||||||
|
|
||||||
Note that the subform uses its own delimiters, @litchar{{...}} or
|
Note that the subform uses its own delimiters, @litchar{{...}} or
|
||||||
@litchar{|{...}|}. This means that you can copy and paste Scribble
|
@litchar{|{...}|}. This means that you can copy and paste Scribble
|
||||||
text with @"@"-forms freely, just prefix the @litchar["@"] if the
|
text with @tech{@"@"-forms} freely, just prefix the @litchar["@"] if the
|
||||||
immediate surrounding text has a prefix.
|
immediate surrounding text has a prefix.
|
||||||
|
|
||||||
For even better control, you can add characters in the opening
|
For even better control, you can add characters in the opening
|
||||||
delimiter, between the @litchar{|} and the @litchar["{"].
|
delimiter, between the @litchar{|} and the @litchar["{"].
|
||||||
Characters that are put there (non alphanumeric ASCII characters only,
|
Characters that are put there (non alphanumeric ASCII characters only,
|
||||||
excluding @litchar["{"] and @litchar["@"]) should also be used for
|
excluding @litchar["{"] and @litchar["@"]) should also be used for
|
||||||
sub-@"@"-forms, and the end-of-body marker should have these characters
|
sub-@tech{@"@"-forms}, and the end-of-body marker should have these characters
|
||||||
in reverse order with paren-like characters (@litchar{(},
|
in reverse order with paren-like characters (@litchar{(},
|
||||||
@litchar{[}, @litchar{<}) mirrored.
|
@litchar{[}, @litchar{<}) mirrored.
|
||||||
|
|
||||||
|
@ -551,7 +551,7 @@ you want to control the sub expressions in the form.
|
||||||
}===|
|
}===|
|
||||||
|
|
||||||
Note that @litchar["@|{...}|"] can be parsed as either an escape expression or
|
Note that @litchar["@|{...}|"] can be parsed as either an escape expression or
|
||||||
as the Racket command part of a @"@"-form. The latter is used in this case
|
as the Racket command part of an @tech{@"@"-form}. The latter is used in this case
|
||||||
(since there is little point in Racket code that uses braces.
|
(since there is little point in Racket code that uses braces.
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
|
@ -563,7 +563,7 @@ as the Racket command part of a @"@"-form. The latter is used in this case
|
||||||
|
|
||||||
As noted above, there are two kinds of Scribble comments: @litchar|{@;{...}}| is
|
As noted above, there are two kinds of Scribble comments: @litchar|{@;{...}}| 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
|
||||||
rules for @"@"-forms), and @litchar|{@;...}| is a line-comment.
|
rules for @tech{@"@"-forms}), and @litchar|{@;...}| is a line-comment.
|
||||||
|
|
||||||
@scribble-examples|==={
|
@scribble-examples|==={
|
||||||
@foo{First line@;{there is still a
|
@foo{First line@;{there is still a
|
||||||
|
|
|
@ -259,14 +259,14 @@ The separator can be set to any value.
|
||||||
@section{Defining Functions and More}
|
@section{Defining Functions and More}
|
||||||
|
|
||||||
(Note: most of the tips in this section are applicable to any code
|
(Note: most of the tips in this section are applicable to any code
|
||||||
that uses the Scribble @"@"-form syntax.)
|
that uses the Scribble @tech{@"@"-form} syntax.)
|
||||||
|
|
||||||
Because the Scribble reader is uniform, you can use it in place of any
|
Because the Scribble reader is uniform, you can use it in place of any
|
||||||
expression where it is more convenient. (By convention, we use a
|
expression where it is more convenient. (By convention, we use a
|
||||||
plain S-expression syntax when we want a Racket expression escape, and
|
plain S-expression syntax when we want a Racket expression escape, and
|
||||||
an @"@"-form for expressions that render as text, which, in the
|
an @tech{@"@"-form} for expressions that render as text, which, in the
|
||||||
@racket[scribble/text] language, is any value-producing expression.)
|
@racket[scribble/text] language, is any value-producing expression.)
|
||||||
For example, you can use an @"@"-form for a function that you define.
|
For example, you can use an @tech{@"@"-form} for a function that you define.
|
||||||
|
|
||||||
@example|-{#lang scribble/text
|
@example|-{#lang scribble/text
|
||||||
@(define @bold[text] @list{*@|text|*})
|
@(define @bold[text] @list{*@|text|*})
|
||||||
|
@ -280,7 +280,7 @@ will need to accept a variable number of arguments. In fact, this
|
||||||
leads to a common problem: what if we want to write a function that
|
leads to a common problem: what if we want to write a function that
|
||||||
consumes a number of ``text arguments'' rathen than a single
|
consumes a number of ``text arguments'' rathen than a single
|
||||||
``rest-like'' body? The common solution for this is to provide the
|
``rest-like'' body? The common solution for this is to provide the
|
||||||
separate text arguments in the S-expression part of an @"@"-form.
|
separate text arguments in the S-expression part of an @tech{@"@"-form}.
|
||||||
|
|
||||||
@example|-{#lang scribble/text
|
@example|-{#lang scribble/text
|
||||||
@(define (choose 1st 2nd)
|
@(define (choose 1st 2nd)
|
||||||
|
@ -292,7 +292,7 @@ separate text arguments in the S-expression part of an @"@"-form.
|
||||||
Either you're with us, or against us.
|
Either you're with us, or against us.
|
||||||
}-|
|
}-|
|
||||||
|
|
||||||
You can even use @"@"-forms with a Racket quote or quasiquote as the
|
You can even use @tech{@"@"-forms} with a Racket quote or quasiquote as the
|
||||||
``head'' part to make it shorter, or use a macro to get grouping of
|
``head'' part to make it shorter, or use a macro to get grouping of
|
||||||
sub-parts without dealing with quotes.
|
sub-parts without dealing with quotes.
|
||||||
|
|
||||||
|
@ -319,7 +319,7 @@ sub-parts without dealing with quotes.
|
||||||
|
|
||||||
Yet another solution is to look at the text values and split the input
|
Yet another solution is to look at the text values and split the input
|
||||||
arguments based on a specific token. Using @racket[match] can make it
|
arguments based on a specific token. Using @racket[match] can make it
|
||||||
convenient --- you can even specify the patterns with @"@"-forms.
|
convenient --- you can even specify the patterns with @tech{@"@"-forms}.
|
||||||
|
|
||||||
@example|-{#lang scribble/text
|
@example|-{#lang scribble/text
|
||||||
@(require racket/match)
|
@(require racket/match)
|
||||||
|
@ -1000,7 +1000,7 @@ it, it is easy to include a lot of textual content.
|
||||||
}-|
|
}-|
|
||||||
|
|
||||||
Of course, the extreme side of this will be to put all of your content
|
Of course, the extreme side of this will be to put all of your content
|
||||||
in a plain Racket module, using @"@"-forms for convenience. However,
|
in a plain Racket module, using @tech{@"@"-forms} for convenience. However,
|
||||||
there is no need to use the text language in this case; instead, you can
|
there is no need to use the text language in this case; instead, you can
|
||||||
@racket[(require scribble/text)], which will get all of the bindings
|
@racket[(require scribble/text)], which will get all of the bindings
|
||||||
that are available in the @racket[scribble/text] language. Using
|
that are available in the @racket[scribble/text] language. Using
|
||||||
|
|
Loading…
Reference in New Issue
Block a user