commit 551be470fd8197963ec57c10a1baae49d184769d
parent 131ebe804c60fbcf44d99aa905994a0179b463a6
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 29 Jan 2024 18:46:11 -0500
More semantic markup; tidy examples.
Diffstat:
1 file changed, 93 insertions(+), 52 deletions(-)
diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo
@@ -397,11 +397,15 @@ variables, which are written using angle brackets, for example <expression> and
example, <expression> stands for any string of characters which is a syntactically valid
expression. The notation
-<thing1> @dots{}
+@display
+<thing@sub{1}> @dots{}
+@end display
indicates zero or more occurrences of a <thing>, and
-<thing1> <thing2> @dots{}
+@display
+<thing@sub{1}> <thing@sub{2}> @dots{}
+@end display
indicates one or more occurrences of a <thing>.
@@ -553,7 +557,11 @@ string, then the entire string is referred to.
The symbol ``@result{}'' used in program examples is read ``evaluates to.'' For example,
-@code{(* 5 8) @result{} 40} means that the expression @code{(* 5 8)} evaluates to the object @code{40}. Or, more
+@example
+(* 5 8) @result{} 40
+@end example
+
+means that the expression @code{(* 5 8)} evaluates to the object @code{40}. Or, more
precisely: the expression given by the sequence of characters ``@code{(* 5 8)}'' evaluates, in an
environment containing the base library, to an object that can be represented externally
by the sequence of characters ``@code{40}.'' See section 3.3 for a discussion of external
@@ -602,7 +610,9 @@ single period) used in the list syntax is not an identifier.
All implementations of Scheme must support the following extended identifier
characters:
-@code{! $ % & * + - . / : < = > ? @ ^ _ ~}
+@example
+! $ % & * + - . / : < = > ? @ ^ _ ~
+@end example
Alternatively, an identifier can be represented by a sequence
of zero or more characters enclosed within vertical lines (@samp{|}), analogous to string literals.
@@ -789,7 +799,7 @@ the notation of structures with shared or circular substructure.
(let ((x (list 'a 'b 'c)))
(set-cdr! (cddr x) x)
- x) @result{} #0=(a b c . #0#)
+ x) @result{} #0=(a b c . #0#)
@end example
@@ -804,8 +814,7 @@ In particular, it is an error for quasiquote (section 4.2.8) to contain them.
@example
-#1=(begin (display #\x) #1#)
- @result{} error
+#1=(begin (display #\x) #1#) @result{} @error{}
@end example
@@ -856,16 +865,46 @@ for the identifier, it is said to be unbound.
No object satisfies more than one of the following predicates:
-@example
+@c Yes, this is a table in the PDF, but it's semantically a list.
+@itemize
+
+@item
+@code{boolean?}
-boolean? bytevector?
-char? eof-object?
-null? number?
-pair? port?
-procedure? string?
-symbol? vector?
+@item
+@code{bytevector?}
-@end example
+@item
+@code{char?}
+
+@item
+@code{eof-object?}
+
+@item
+@code{null?}
+
+@item
+@code{number?}
+
+@item
+@code{pair?}
+
+@item
+@code{port?}
+
+@item
+@code{procedure?}
+
+@item
+@code{string?}
+
+@item
+@code{symbol?}
+
+@item
+@code{vector?}
+
+@end itemize
and all predicates created by define-record-type.
@@ -1079,7 +1118,7 @@ calls. The reference to x is in a tail context, but it is not a call and thus is
@node Expressions
@chapter Expressions
-Expression types are categorized as primitive or derived. Primitive expression types include
+Expression types are categorized as @dfn{primitive} or @dfn{derived}. Primitive expression types include
variables and procedure calls. Derived expression types are not semantically primitive,
but can instead be defined as macros. Suitable syntax definitions of some of the derived
expressions are given in section 7.3.
@@ -1119,7 +1158,7 @@ error to reference an unboundvariable.
@example
(define x 28)
-x @result{} 28
+x @result{} 28
@end example
@@ -1136,9 +1175,9 @@ Scheme code.
@example
-(quote a) @result{} a
-(quote #(a b c)) @result{} #(a b c)
-(quote (+ 1 2)) @result{} (+ 1 2)
+(quote a) @result{} a
+(quote #(a b c)) @result{} #(a b c)
+(quote (+ 1 2)) @result{} (+ 1 2)
@end example
@@ -1147,12 +1186,12 @@ notations are equivalent in all respects.
@example
-'a @result{} a
-'#(a b c) @result{} #(a b c)
-'() @result{} ()
-'(+ 1 2) @result{} (+ 1 2)
-'(quote a) @result{} (quote a)
-''a @result{} (quote a)
+'a @result{} a
+'#(a b c) @result{} #(a b c)
+'() @result{} ()
+'(+ 1 2) @result{} (+ 1 2)
+'(quote a) @result{} (quote a)
+''a @result{} (quote a)
@end example
@@ -1162,18 +1201,18 @@ they need not be quoted.
@example
-'145932 @result{} 145932
-145932 @result{} 145932
-'"abc" @result{} "abc"
-"abc" @result{} "abc"
-'#\a @result{} #\a
-#\a @result{} #\a
-'#(a 10) @result{} #(a 10)
-#(a 10) @result{} #(a 10)
-'#u8(64 65) @result{} #u8(64 65)
-#u8(64 65) @result{} #u8(64 65)
-'#t @result{} #t
-#t @result{} #t
+'145932 @result{} 145932
+145932 @result{} 145932
+'"abc" @result{} "abc"
+"abc" @result{} "abc"
+'#\a @result{} #\a
+#\a @result{} #\a
+'#(a 10) @result{} #(a 10)
+#(a 10) @result{} #(a 10)
+'#u8(64 65) @result{} #u8(64 65)
+#u8(64 65) @result{} #u8(64 65)
+'#t @result{} #t
+#t @result{} #t
@end example
@@ -1192,8 +1231,8 @@ is passed the resulting arguments.
@example
-(+ 3 4) @result{} 7
-((if #f + *) 3 4) @result{} 12
+(+ 3 4) @result{} 7
+((if #f + *) 3 4) @result{} 12
@end example
@@ -1238,19 +1277,21 @@ contains definitions, represents a letrec* form---see section 4.2.2) will be eva
sequentially in the extended environment. The results of the last expression in the body
will be returned as the results of the procedure call.
+@c TODO: "a procedure" should not appear in typewriter font. The
+@c same goes for "unspecified" results throughout the file.
@example
-(lambda (x) (+ x x)) @result{} a procedure
-((lambda (x) (+ x x)) 4) @result{} 8
+(lambda (x) (+ x x)) @result{} a procedure
+((lambda (x) (+ x x)) 4) @result{} 8
(define reverse-subtract
(lambda (x y) (- y x)))
-(reverse-subtract 7 10) @result{} 3
+(reverse-subtract 7 10) @result{} 3
(define add4
(let ((x 4))
(lambda (y) (+ x y))))
-(add4 6) @result{} 10
+(add4 6) @result{} 10
@end example
@@ -1281,9 +1322,9 @@ It is an error for a <variable> to appear more than once in <formals>.
@example
-((lambda x x) 3 4 5 6) @result{} (3 4 5 6)
+((lambda x x) 3 4 5 6) @result{} (3 4 5 6)
((lambda (x y . z) z)
- 3 4 5 6) @result{} (5 6)
+ 3 4 5 6) @result{} (5 6)
@end example
@@ -1306,11 +1347,11 @@ value and no <alternate> is specified, then the result of the expression is unsp
@example
-(if (> 3 2) 'yes 'no) @result{} yes
-(if (> 2 3) 'yes 'no) @result{} no
+(if (> 3 2) 'yes 'no) @result{} yes
+(if (> 2 3) 'yes 'no) @result{} no
(if (> 3 2)
(- 3 2)
- (+ 3 2)) @result{} 1
+ (+ 3 2)) @result{} 1
@end example
@@ -1327,9 +1368,9 @@ unspecified.
@example
(define x 2)
-(+ x 1) @result{} 3
-(set! x 4) @result{} unspecified
-(+ x 1) @result{} 5
+(+ x 1) @result{} 3
+(set! x 4) @result{} unspecified
+(+ x 1) @result{} 5
@end example
