diff --git a/collects/scribblings/scribble/layers.scrbl b/collects/scribblings/scribble/layers.scrbl index ab313015..fc0fe6cf 100644 --- a/collects/scribblings/scribble/layers.scrbl +++ b/collects/scribblings/scribble/layers.scrbl @@ -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 diff --git a/collects/scribblings/scribble/reader-internals.scrbl b/collects/scribblings/scribble/reader-internals.scrbl index 45fc40f6..81ca17d3 100644 --- a/collects/scribblings/scribble/reader-internals.scrbl +++ b/collects/scribblings/scribble/reader-internals.scrbl @@ -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[ diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl index 680df5dc..2bd426c4 100644 --- a/collects/scribblings/scribble/reader.scrbl +++ b/collects/scribblings/scribble/reader.scrbl @@ -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 diff --git a/collects/scribblings/scribble/text.scrbl b/collects/scribblings/scribble/text.scrbl index 7bb4b224..3b4fd69a 100644 --- a/collects/scribblings/scribble/text.scrbl +++ b/collects/scribblings/scribble/text.scrbl @@ -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