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

Add link to the syntax of the @-reader.

Browse Source 
Also defines the "@-form" term in the @-syntax section due to its
frequency.

Closes PR-12589.

original commit: 61db1d64058214426343bb50d0dfa5c5300a0d29
This commit is contained in:
Danny Yoo 2013-02-21 14:31:04 -07:00
parent 77d079a3ed
commit 903e0a62ed
4 changed files with 31 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/scribblings/scribble/layers.scrbl
View File

@ -40,7 +40,7 @@ the document body. Using @racketmodname[scribble/base] after
Besides making the file a module, each of the @hash-lang[]
declarations selects the Scribble reader (instead of the usual Racket
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.
A module written as
@ -165,7 +165,7 @@ Working roughly from the bottom up, the Scribble layers are:
@itemize[
@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"].}
@item{@racketmodname[scribble/core]: A set of document datatypes

10
collects/scribblings/scribble/reader-internals.scrbl
View File

@ -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
@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
the usual way: use Racket functions, define your functions, or require
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]
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)"}
@ -145,7 +145,7 @@ is an example of this.
@section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language}
@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
@racketmodname[at-exp].}
@ -216,7 +216,7 @@ resulting reader in several ways:
@item{@racket[readtable] --- a readtable to base the @"@"-readtable
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
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
each resulting syntax value after it has been parsed (but before it
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:
@racketblock[

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

@ -40,7 +40,7 @@ in this chapter.
@;--------------------------------------------------------------------
@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
@racketblock[
@ -103,7 +103,7 @@ prints the output
@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}}
Here are more examples of @"@"-forms:
Here are more examples of @tech{@"@"-forms}:
@scribble-examples|==={
@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
separate them are parsed to multiple Racket strings. More generally,
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
@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
indentations are converted to @racket["\n"] and all-space string
expressions.
@ -137,8 +137,8 @@ expressions.
*p = '\n';}
}===|
The command part of an @"@"-form is optional as well. In that case,
the @"@" form is read as a list, which usually counts as a function
The command part of an @tech{@"@"-form} is optional as well. In that case,
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
@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
alternative syntax: A block of text can begin 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["|@"]''.
@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
S-expressions. Identifiers still get their meaning, as in any
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
@racket[foo] as a procedure or a macro; it can be defined, required,
or bound locally (with @racket[let], for example).
@ -264,7 +264,7 @@ or bound locally (with @racket[let], for example).
@section{The Command Part}
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.
@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
@"@"-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
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
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.
This makes it suitable for Racket escapes in body texts. (More on this
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
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
@litchar["{"] is allowed as part of the text, and it makes the
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}|
}===|
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{|}:
@scribble-examples|==={
@ -480,14 +480,14 @@ prefixed with a @litchar{|}:
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
text with @tech{@"@"-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
sub-@tech{@"@"-forms}, and the end-of-body marker should have these characters
in reverse order with paren-like characters (@litchar{(},
@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
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.
@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
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|==={
@foo{First line@;{there is still a

14
collects/scribblings/scribble/text.scrbl
View File

@ -259,14 +259,14 @@ The separator can be set to any value.
@section{Defining Functions and More}
(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
expression where it is more convenient. (By convention, we use a
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.)
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
@(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
consumes a number of ``text arguments'' rathen than a single
``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
@(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.
}-|
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
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
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
@(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
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
@racket[(require scribble/text)], which will get all of the bindings
that are available in the @racket[scribble/text] language. Using