commit ded2cdb286d6516cad54df4d19379b403390c557
parent 9a79284b02d34a4cfb44df8bc69067f272146dea
Author: Yuval Langer <yuval.langer@gmail.com>
Date: Sun, 28 Jan 2024 21:36:13 +0200
Put some code examples in @example blocks and @code.
Diffstat:
1 file changed, 99 insertions(+), 11 deletions(-)
diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo
@@ -553,8 +553,8 @@ following:
The symbol “⟹” used in program examples is read “evaluates to.” For example,
-(* 5 8) ⟹ 40 means that the expression (* 5 8) evaluates to the object 40. Or, more
-precisely: the expression given by the sequence of characters “(* 5 8)” evaluates, in an
+@code{(* 5 8) ⟹ 40} 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 “ 40.” See section 3.3 for a discussion of external
representations of objects.
@@ -602,7 +602,9 @@ single period) used in the list syntax is not an identifier.
All implementations of Scheme must support the following extended identifier
characters:
-! $ % & * + - . / : < = > ? @ ^ _ ~ Alternatively, an identifier can be represented by a sequence
+@code{! $ % & * + - . / : < = > ? @ ^ _ ~}
+
+Alternatively, an identifier can be represented by a sequence
of zero or more characters enclosed within vertical lines (|), analogous to string literals.
Any character, including whitespace characters, but excluding the backslash and vertical
line characters, can appear verbatim in such an identifier. In addition, characters can be
@@ -615,13 +617,19 @@ that || is a valid identifier that is different from any other identifier.
Here are some examples of identifiers:
+@example
+
... +
+soup+ <=?
->string a34kTMNs
lambda list->vector
q V17a
|two words| |two\x20;words|
-the-word-recursion-has-many-meanings See section 7.1.1 for the formal syntax of
+the-word-recursion-has-many-meanings
+
+@end example
+
+See section 7.1.1 for the formal syntax of
identifiers.
Identifiers have two uses within Scheme programs:
@@ -642,9 +650,13 @@ sentence.
The following directives give explicit control over case folding.
+@example
+
#!fold-case
#!no-fold-case
+@end example
+
These directives can appear anywhere comments are permitted (see section 2.2) but
must be followed by a delimiter. They are treated as comments, except that they affect
the reading of subsequent data from the same port. The #!fold-case directive causes
@@ -674,6 +686,8 @@ useful for “commenting out” sections of code.
Block comments are indicated with properly nested #|and |# pairs.
+@example
+
#|
The FACT procedure computes the factorial
of a non-negative integer.
@@ -685,6 +699,8 @@ Block comments are indicated with properly nested #|and |# pairs.
1 ;Base case: return 1
(* n (fact (- n 1))))))
+@end example
+
@node Other notations
@section Other notations
@@ -741,7 +757,7 @@ For a description of the notations used for numbers, see section 6.2.
@item @t{#u8(}
This introduces a bytevector constant (section 6.9). Bytevector constants are
- terminated by ) .
+ terminated by @code{)} .
@item @t{#e #i #b #o #d #x}
These are used in the notation for numbers (section 6.2.5).
@@ -764,9 +780,14 @@ The lexical syntax #<n># serves as a reference to some object labelled by #<n>=;
result is the same object as the #<n>= (see section 6.1). Together, these syntaxes permit
the notation of structures with shared or circular substructure.
+@example
+
(let ((x (list 'a 'b 'c)))
(set-cdr! (cddr x) x)
x) ⟹ #0=(a b c . #0#)
+
+@end example
+
The scope of a datum label is the portion of the outermost datum in which it appears that
is to the right of the label. Consequently, a reference #<n># can occur only after a label
#<n>=; it is an error to attempt a forward reference. In addition, it is an error if the
@@ -776,9 +797,13 @@ labelled by #<n>= is not well defined in this case.
It is an error for a <program> or <library> to include circular references except in literals.
In particular, it is an error for quasiquote (section 4.2.8) to contain them.
+@example
+
#1=(begin (display #\x) #1#)
⟹ error
+@end example
+
@node Basic concepts
@chapter Basic concepts
@@ -826,12 +851,17 @@ for the identifier, it is said to be unbound.
No object satisfies more than one of the following predicates:
+@example
+
boolean? bytevector?
char? eof-object?
null? number?
pair? port?
procedure? string?
symbol? vector?
+
+@end example
+
and all predicates created by define-record-type.
These predicates define the types boolean, bytevector, character, the empty list object,
@@ -955,10 +985,14 @@ lambda expression.
below, occurs in a tail context. The same is true of all the bodies of case-lambda
expressions.
+@example
+
(lambda <formals>
<definition>* <expression>* <tail expression>)
(case-lambda (<formals> <tail body>)*)
+@end example
+
* If one of the following expressions is in a tail context, then the subexpressions shown
as <tail expression> are in a tail context. These were derived from rules in the grammar
given in chapter 7 by replacing some occurrences of <body> with <tail body>, some
@@ -966,6 +1000,8 @@ lambda expression.
<sequence> with <tail sequence>. Only those rules that contain tail contexts are shown
here.
+@example
+
(if <expression> <tail expression> <tail expression>)
(if <expression> <tail expression>)
(cond <cond clause>+)
@@ -998,6 +1034,8 @@ lambda expression.
<tail body> ⟶<definition>* <tail sequence>
<tail sequence> ⟶<expression>* <tail expression>
+@end example
+
* If a cond or case expression is in a tail context, and has a clause of the form
(<expression1> => <expression2>) then the (implied) call to the procedure that results
from the evaluation of <expression2> is in a tail context. <expression2> itself is not in a
@@ -1011,12 +1049,16 @@ evaluate its first argument as if it were in tail position within the eval proce
In the following example the only tail call is the call to f. None of the calls to g or h are tail
calls. The reference to x is in a tail context, but it is not a call and thus is not a tail call.
+@example
+
(lambda ()
(if (g)
(let ((x (h)))
x)
(and (g) (f))))
+@end example
+
Note: Implementations may recognize that some non-tail calls, such as the call to h
above, can be evaluated as though they were tail calls. In the example above, the let
expression could be compiled as a tail call to h. (The possibility of h returning an
@@ -1063,9 +1105,13 @@ An expression consisting of a variable(section 3.1) is a variable reference. The
variable reference is the value stored in the location to which the variable is bound. It is an
error to reference an unboundvariable.
+@example
+
(define x 28)
x ⟹ 28
+@end example
+
@node Literal expressions
@subsection Literal expressions
@@ -1077,20 +1123,34 @@ syntax: <constant>
Scheme object (see section 3.3). This notation is used to include literal constants in
Scheme code.
+@example
+
(quote a) ⟹ a
(quote #(a b c)) ⟹ #(a b c)
-(quote (+ 1 2)) ⟹ (+ 1 2) (quote <datum>) can be abbreviated as '<datum>. The two
+(quote (+ 1 2)) ⟹ (+ 1 2)
+
+@end example
+
+@code{(quote <datum>)} can be abbreviated as @code{'<datum>}. The two
notations are equivalent in all respects.
+@example
+
'a ⟹ a
'#(a b c) ⟹ #(a b c)
'() ⟹ ()
'(+ 1 2) ⟹ (+ 1 2)
'(quote a) ⟹ (quote a)
-''a ⟹ (quote a) Numerical constants, string constants, character constants,
+''a ⟹ (quote a)
+
+@end example
+
+Numerical constants, string constants, character constants,
vector constants, bytevector constants, and boolean constants evaluate to themselves;
they need not be quoted.
+@example
+
'145932 ⟹ 145932
145932 ⟹ 145932
'"abc" ⟹ "abc"
@@ -1102,7 +1162,11 @@ they need not be quoted.
'#u8(64 65) ⟹ #u8(64 65)
#u8(64 65) ⟹ #u8(64 65)
'#t ⟹ #t
-#t ⟹ #t As noted in section 3.4, it is an error to attempt to alter a constant (i.e. the value
+#t ⟹ #t
+
+@end example
+
+As noted in section 3.4, it is an error to attempt to alter a constant (i.e. the value
of a literal expression) using a mutation procedure like set-car! or string-set!.
@node Procedure calls
@@ -1115,8 +1179,14 @@ be called followed by expressions for the arguments to be passed to it. The oper
operand expressions are evaluated (in an unspecified order) and the resulting procedure
is passed the resulting arguments.
+@example
+
(+ 3 4) ⟹ 7
-((if #f + *) 3 4) ⟹ 12 The procedures in this document are available as the values of
+((if #f + *) 3 4) ⟹ 12
+
+@end example
+
+The procedures in this document are available as the values of
variables exported by the standard libraries. For example, the addition and multiplication
procedures in the above examples are the values of the variables + and * in the base
library. New procedures are created by evaluating lambda expressions (see section 4.1.4).
@@ -1157,6 +1227,8 @@ contains definitions, represents a letrec* form — see section 4.2.2) will be e
sequentially in the extended environment. The results of the last expression in the body
will be returned as the results of the procedure call.
+@example
+
(lambda (x) (+ x x)) ⟹ a procedure
((lambda (x) (+ x x)) 4) ⟹ 8
@@ -1167,7 +1239,11 @@ will be returned as the results of the procedure call.
(define add4
(let ((x 4))
(lambda (y) (+ x y))))
-(add4 6) ⟹ 10 <Formals> have one of the following forms:
+(add4 6) ⟹ 10
+
+@end example
+
+<Formals> have one of the following forms:
* (<variable1> …): The procedure takes a fixed number of arguments; when the
procedure is called, the arguments will be stored in fresh locations that are bound to
@@ -1186,10 +1262,14 @@ will be returned as the results of the procedure call.
It is an error for a <variable> to appear more than once in <formals>.
+@example
+
((lambda x x) 3 4 5 6) ⟹ (3 4 5 6)
((lambda (x y . z) z)
3 4 5 6) ⟹ (5 6)
+@end example
+
Each procedure created as the result of evaluating a lambda expression is (conceptually)
tagged with a storage location, in order to make eqv? and eq? work on procedures (see
section 6.1).
@@ -1207,12 +1287,16 @@ true value(see section 6.3), then <consequent> is evaluated and its values are r
Otherwise <alternate> is evaluated and its values are returned. If <test> yields a false
value and no <alternate> is specified, then the result of the expression is unspecified.
+@example
+
(if (> 3 2) 'yes 'no) ⟹ yes
(if (> 2 3) 'yes 'no) ⟹ no
(if (> 3 2)
(- 3 2)
(+ 3 2)) ⟹ 1
+@end example
+
@node Assignments
@subsection Assignments
@@ -1223,11 +1307,15 @@ which <variable> is bound. It is an error if <variable> is not bound either in s
regionenclosing the set! expression or else globally. The result of the set! expression is
unspecified.
+@example
+
(define x 2)
(+ x 1) ⟹ 3
(set! x 4) ⟹ unspecified
(+ x 1) ⟹ 5
+@end example
+
@node Inclusion
@subsection Inclusion
@@ -1964,7 +2052,7 @@ the list are then “stripped away” and the elements of the list are inserted
comma at-sign expression sequence. A comma at-sign normally appears only within a list
or vector <qq template>.
- Note: In order to unquote an identifier beginning with @, it is necessary to use either
+ Note: In order to unquote an identifier beginning with @code{,} it is necessary to use either
an explicit unquote or to put whitespace after the comma, to avoid colliding with the
comma at-sign sequence.
