Scribble: The Racket Documentation Tool阅读笔记
2 @ Syntax
scribble使用@在文本中插入s-表达式。选用@是因为它在正常的代码中很少出现。
在scribble/base或者其他类似语言中，@自动可得。使用at-exp元语言也可以添加对@的支持：
#lang at-exp racket
(define v '@op{str})
等同于：
#lang racket
(define v '(op "str"))
2.1 The Scribble Syntax at a Glance
@构造的格式：
@ ‹cmd› [ ‹datum›* ] { ‹text-body›* }
@后面的三个部分都是可选的，但至少要出现一个。部分之间不能出现空格。
#lang at-exp racket
'@foo{blah blah blah}
会被翻译成
(foo "blah blah blah")
更多例子：
@foo{blah "blah" (blah'?)}读成(foo “blah "blah" (blah'?)")@foo[1 2]{3 4}读成(foo 1 2 "3 4")@foo[1 2 3 4]读成(foo 1 2 3 4)@foo[#:width 2]{blah blah}读成(foo #:width 2 "blah blah")
@foo{blah blah
yada yada}
会被翻译成
(foo "blah blah" "\n"
"yada yada")
@foo{
blah blah
yada yada
}
会被翻译成
(foo
"blah blah" "\n"
"yada yada")
可以看到，‹text-body›中的缩进不一定会被保留，但是换行则会被保留。
更方便的是，可以在‹text-body›中嵌套@构造：
@foo{bar @baz{3}
blah}
会被翻译为
(foo "bar " (baz "3") "\n"
"blah")
如果不使用datum和text部分，那么：
@foo读成 foo@{blah @foo: blah}读成("blah " foo: " blah")@{blah @|foo|: blah}读成("blah " foo ": blah")
命令部分可以是任意表达式，只要不以{，[，或者|开头：
@foo{(+ 1 2) -> @(+ 1 2)!}读成(foo "(+ 1 2) -> " (+ 1 2) "!")@foo{A @"string" escape}读成(foo "A string escape")@"@"读成 “@”
转义的”@“会与环绕的字符串融合：
@foo{eli@"@"barzilay.org}读成(foo "eli@barzilay.org")
像{这种，除非在text-body中成对出现，否则也需要转义。
可以使用|{和}|来禁止默认的@构造：
@foo|{bar |@x|{@}| baz}|读成(foo "bar " (x "@") " baz")
如果上面的方法还不够，则可以使用下面的：
@foo|--{bar}@|{baz}--|读成(foo "bar}@|{baz")@foo|<<{bar}@|{baz}>>|读成(foo "bar}@|{baz")
可否将@用作标识符名字的一部分？可以，不出现在首字母即可，若出现在首字母，则要用转义的办法：
(define \@email "foo@bar.com")读成(define @email "foo@bar.com")(define |@atchar| #\@)读成(define @atchar #\@)
值得注意的是，@构造只是书写s-表达式的另一种形式而已，运算s-表达式时所需要的环境在运算@构造的时候也需要。
2.2 The Command Part
2.3 The Datum Part
2.4 The Body Part
2.4.1 Alternative Body Syntax
2.4.2 Racket Expression Escapes
2.4.3 Comments
可以使用@;{...}以及@;...来添加注释。前者可以嵌套，并且里面的换行算数；后者不可以嵌套，但会吃掉行尾的换行。
2.4.4 Spaces, Newlines, and Indentation
@-构造对换行和空白有特定的处理方式。例如
{之后或者}之前的纯换行会被丢弃，除非{和}之间的内容只有换行。
正文竖标线之前的空白会被忽略，竖标线的位置由具有最小缩进的非空行决定。
如果首行紧随{之后，那么它不会被缩进，但是它的位置会被竖标线参考。
每个@-构造都按自己的缩进来解析。嵌套的@-构造可以有自己的缩进。
如果输入端口的的行列计数没有打开，那么计算竖标线的时候不会参考正文中的首行。
极端情况下，如果行首空白很重要，可以使用@||插入空白：
@foo{
@|| bar @||
@|| baz}
上面的代码翻译成：
(foo
" bar " "\n"
" baz"
（未完待续）