From 5117dd03d989be95beca043ceb5ce28b48b5752e Mon Sep 17 00:00:00 2001 From: Eli Barzilay Date: Tue, 10 Jul 2007 03:54:33 +0000 Subject: [PATCH] update doc.txt and tests to match docs svn: r6881 --- collects/scribble/doc.txt | 48 +++++++++++++++----------------- collects/scribble/test-reader.ss | 48 +++++++++++++++----------------- 2 files changed, 46 insertions(+), 50 deletions(-) diff --git a/collects/scribble/doc.txt b/collects/scribble/doc.txt index 9e18b4bc74..a725296edd 100644 --- a/collects/scribble/doc.txt +++ b/collects/scribble/doc.txt @@ -255,20 +255,20 @@ arbitrary Scheme code. This is particularly useful with strings, which can be used to include arbitrary text. - @foo{This @"}" is a closing brace} + @foo{A @"}" marks the end} --reads-as--> - (foo "This } is a closing brace") + (foo "A } marks the end") Note that the escaped string is (intentionally) merged with the rest of the text. This works for "@" too: - @foo{The command prefix is @"@".} + @foo{The prefix: @"@".} --reads-as--> - (foo "The command prefix is @.") + (foo "The prefix: @.") - @foo{@"@foo{bar}" reads as (foo "bar")} + @foo{@"@x{y}" --> (x "y")} --reads-as--> - (foo "@foo{bar} reads as (foo \"bar\")") + (foo "@x{y} --> (x \"y\")") * Alternative Body Syntax @@ -280,9 +280,9 @@ marker to have the text terminated by a "}|". --reads-as--> (foo "...") - @foo|{"}" closes, "{" opens}| + @foo|{"}" follows "{"}| --reads-as--> - (foo "\"}\" closes, \"{\" opens") + (foo "\"}\" follows \"{\"") @foo|{Nesting |{is}| ok}| --reads-as--> @@ -297,9 +297,9 @@ This applies to sub-@-forms too -- the "@" must be prefixed with a --reads-as--> (foo "Maze" "\n" (bar "is") "Life!") - @foo|{Works for |@bar|{subforms}| too}| + @t|{In |@i|{sub|@"@"s}| too}| --reads-as--> - (foo "Works for " (bar "subforms") " too") + (t "In " (i "sub@s") " too") Note that the subform uses its own delimiters, "{...}" or "|{...}|". This means that you can copy and paste Scribble text with @-forms @@ -313,13 +313,13 @@ also be used for sub-@-forms, and the end-of-body marker should have these characters in reverse order with paren-like characters ("(", "[", "<") mirrored. - @foo|<<<{Some @x{more} |@{text}|.}>>>| + @foo|<<<{@x{foo} |@{bar}|.}>>>| --reads-as--> - (foo "Some @x{more} |@{text}|.") + (foo "@x{foo} |@{bar}|.") - @foo|!!{Blah |!!@bold{blah}...}!!| + @foo|!!{X |!!@b{Y}...}!!| --reads-as--> - (foo "Blah " (bold "blah") "...") + (foo "X " (b "Y") "...") Finally, remember that you can use an expression escape with a Scheme string for confusing situations. This works well when you only need @@ -378,7 +378,7 @@ a (nestable) comment for a whole body of text (following the same rules for @-forms), and "@;..." is a line-comment. @foo{First line@;{there is still a - newline at this point;} + newline here;} Second line} --reads-as--> (foo "First line" "\n" "Second line") @@ -387,12 +387,11 @@ One useful property of line-comments is that they continue to the end of the line *and* all following spaces (or tabs). Using this, you can get further control of the subforms. - @foo{This is @; - a pretty long @; - single string-@; - argument.} + @foo{A long @; + single-@; + string arg.} --reads-as--> - (foo "This is a pretty long single string-argument.") + (foo "A long single-string arg.") Note how this is different from using "@||"s in that strings around it are not merged. @@ -511,12 +510,11 @@ block). baz "baz" "\n" bbb} " " "bbb") - @text{Some text@footnote{And a - footnote comment.}. More text.} + @text{Some @b{bold + text}, and + more text.} --reads-as--> - (text "Some text" - (footnote "And a" "\n" "footnote comment.") - ". More text.") + (text "Some " (b "bold" "\n" "text") ", and" "\n" "more text.") Note that each @-form is parsed to an S-expression that has its own indentation. This means that Scribble source can be indented like diff --git a/collects/scribble/test-reader.ss b/collects/scribble/test-reader.ss index 4762149325..ef66ff26f1 100755 --- a/collects/scribble/test-reader.ss +++ b/collects/scribble/test-reader.ss @@ -181,20 +181,20 @@ exec mzscheme -r "$0" "$@" [@foo{a @(bar 2) c} (foo "a " (bar 2) " c")] - [@foo{This @"}" is a closing brace} - (foo "This } is a closing brace")] + [@foo{A @"}" marks the end} + (foo "A } marks the end")] - [@foo{The command prefix is @"@".} - (foo "The command prefix is @.")] + [@foo{The prefix: @"@".} + (foo "The prefix: @.")] - [@foo{@"@foo{bar}" reads as (foo "bar")} - (foo "@foo{bar} reads as (foo \"bar\")")] + [@foo{@"@x{y}" --> (x "y")} + (foo "@x{y} --> (x \"y\")")] [@foo|{...}| (foo "...")] - [@foo|{"}" closes, "{" opens}| - (foo "\"}\" closes, \"{\" opens")] + [@foo|{"}" follows "{"}| + (foo "\"}\" follows \"{\"")] [@foo|{Nesting |{is}| ok}| (foo "Nesting |{is}| ok")] @@ -204,14 +204,14 @@ exec mzscheme -r "$0" "$@" Life!}| (foo "Maze" "\n" (bar "is") "\n" "Life!")] - [@foo|{Works for |@bar|{subforms}| too}| - (foo "Works for " (bar "subforms") " too")] + [@t|{In |@i|{sub|@"@"s}| too}| + (t "In " (i "sub@s") " too")] - [@foo|<<<{Some @x{more} |@{text}|.}>>>| - (foo "Some @x{more} |@{text}|.")] + [@foo|<<<{@x{foo} |@{bar}|.}>>>| + (foo "@x{foo} |@{bar}|.")] - [@foo|!!{Blah |!!@bold{blah}...}!!| - (foo "Blah " (bold "blah") "...")] + [@foo|!!{X |!!@b{Y}...}!!| + (foo "X " (b "Y") "...")] [@foo{foo@bar.} (foo "foo" bar.)] @@ -255,15 +255,14 @@ exec mzscheme -r "$0" "$@" ("blah")] [@foo{First line@;{there is still a - newline at this point;} + newline here;} Second line} (foo "First line" "\n" "Second line")] - [@foo{This is @; - a pretty long @; - single string-@; - argument.} - (foo "This is a pretty long single string-argument.")] + [@foo{A long @; + single-@; + string arg.} + (foo "A long single-string arg.")] [@foo{bar} (foo "bar")] @@ -369,11 +368,10 @@ exec mzscheme -r "$0" "$@" bbb} (foo " bar" "\n" "baz" "\n" " " "bbb")] - [@text{Some text@footnote{And a - footnote comment.}. More text.} - (text "Some text" - (footnote "And a" "\n" "footnote comment.") - ". More text.")] + [@text{Some @b{bold + text}, and + more text.} + (text "Some " (b "bold" "\n" "text") ", and" "\n" "more text.")] [@code{ begin