commit 89efd6e3b9d3a6f1ed0e9216c7ffb190b9d23482
parent 34483e94917ebb265e8e6b975e5e7f380dae1538
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 29 Jan 2024 14:47:47 -0500
Overview: Lots of semantic markup.
Diffstat:
1 file changed, 56 insertions(+), 54 deletions(-)
diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo
@@ -285,8 +285,8 @@ The formal syntax of Scheme is described in section 7.1.
Every identifier defined in this report appears in one or more of several libraries.
Identifiers defined in the base library are not marked specially in the body of the report.
This library includes the core syntax of Scheme and generally useful procedures that
-manipulate data. For example, the variable abs is bound to a procedure of one argument
-that computes the absolute value of a number, and the variable + is bound to a procedure
+manipulate data. For example, the variable @code{abs} is bound to a procedure of one argument
+that computes the absolute value of a number, and the variable @code{+} is bound to a procedure
that computes sums. The full list all the standard libraries and the identifiers they export
is given in Appendix A.
@@ -318,22 +318,22 @@ Must support portable code by providing a mode of operation in which the lexical
When speaking of an error situation, this report uses the phrase ``an error is signaled'' to
indicate that implementations must detect and report the error. An error is signaled by
-raising a non-continuable exception, as if by the procedure raise as described in section
+raising a non-continuable exception, as if by the procedure @code{raise} as described in section
6.11. The object raised is implementation-dependent and need not be distinct from
objects previously used for the same purpose. In addition to errors signaled in situations
described in this report, programmers can signal their own errors and handle signaled
errors.
-The phrase ``an error that satisfies predicate is signaled'' means that an error is signaled as
+The phrase ``an error that satisfies @var{predicate} is signaled'' means that an error is signaled as
above. Furthermore, if the object that is signaled is passed to the specified predicate (such
-as file-error? or read-error?), the predicate returns #t.
+as @code{file-error?} or @code{read-error?}), the predicate returns @code{#t}.
If such wording does not appear in the discussion of an error, then implementations are
not required to detect or report the error, though they are encouraged to do so. Such a
situation is sometimes, but not always, referred to with the phrase ``an error.'' In such a
situation, an implementation may or may not signal an error; if it does signal an error, the
-object that is signaled may or may not satisfy the predicates error-object?, file-error?, or
-read-error?. Alternatively, implementations may provide non-portable extensions.
+object that is signaled may or may not satisfy the predicates @code{error-object?}, @code{file-error?}, or
+@code{read-error?}. Alternatively, implementations may provide non-portable extensions.
For example, it is an error for a procedure to be passed an argument of a type that the
procedure is not explicitly specified to handle, even though such domain errors are seldom
@@ -363,6 +363,8 @@ programmer or program behavior.
@node Entry format
@subsection Entry format
+@c To what extent should the Texinfo version follow the PDF's
+@c formatting?
Chapters 4 and 6 are organized into entries. Each entry describes one language feature
or a group of related features, where a feature is either a syntactic construct or a
@@ -419,12 +421,12 @@ italicized. Thus the header line
procedure: (vector-ref vector k)
-indicates that the procedure bound to the vector-ref variable takes two arguments, a
+indicates that the procedure bound to the @code{vector-ref} variable takes two arguments, a
vector
-vector and an exact non-negative integer
+@var{vector} and an exact non-negative integer
-k (see below). The header lines
+@var{k} (see below). The header lines
procedure: (make-vector k)
@@ -432,14 +434,14 @@ procedure: (make-vector k)
procedure: (make-vector k fill)
-indicate that the make-vector procedure must be defined to take either one or two
+indicate that the @code{make-vector} procedure must be defined to take either one or two
arguments.
It is an error for a procedure to be presented with an argument that it is not specified to
handle. For succinctness, we follow the convention that if an argument name is also the
name of a type listed in section 3.2, then it is an error if that argument is not of the named
-type. For example, the header line for vector-ref given above dictates that the first
-argument to vector-ref is a vector. The following naming conventions also imply type
+type. For example, the header line for @code{vector-ref} given above dictates that the first
+argument to @code{vector-ref} is a vector. The following naming conventions also imply type
restrictions:
alist association list
@@ -505,33 +507,33 @@ restrictions:
The names
-start and
+@var{start} and
-end are used as indexes into strings, vectors, and bytevectors. Their use implies the
+@var{end} are used as indexes into strings, vectors, and bytevectors. Their use implies the
following:
@itemize
@item
-It is an error if start is greater than end.
+It is an error if @var{start} is greater than @var{end}.
@item
-It is an error if end is greater than the length of the string,
+It is an error if @var{end} is greater than the length of the string,
vector, or bytevector.
@item
-If start is omitted, it is assumed to be zero.
+If @var{start} is omitted, it is assumed to be zero.
@item
-If end is omitted, it assumed to be the length of the string, vector,
+If @var{end} is omitted, it assumed to be the length of the string, vector,
or bytevector.
@item
-The index start is always inclusive and the index
-end is always exclusive. As an example, consider a string. If
-start and
-end are the same, an empty substring is referred to, and if
-start is zero and
-end is the length of
+The index @var{start} is always inclusive and the index
+@var{end} is always exclusive. As an example, consider a string. If
+@var{start} and
+@var{end} are the same, an empty substring is referred to, and if
+@var{start} is zero and
+@var{end} is the length of
string, then the entire string is referred to.
@end itemize
@@ -544,28 +546,28 @@ The symbol ``@result{}'' used in program examples is read ``evaluates to.'' For
@code{(* 5 8) @result{} 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
+by the sequence of characters ``@code{40}.'' See section 3.3 for a discussion of external
representations of objects.
@node Naming conventions
@subsection Naming conventions
-By convention, ? is the final character of the names of procedures that always return a
-boolean value. Such procedures are called predicates. Predicates are generally understood
+By convention, @samp{?} is the final character of the names of procedures that always return a
+boolean value. Such procedures are called @dfn{predicates}. Predicates are generally understood
to be side-effect free, except that they may raise an exception when passed the wrong
type of argument.
-Similarly, ! is the final character of the names of procedures that store values into
-previously allocated locations (see section 3.4). Such procedures are called mutation
-procedures. The value returned by a mutation procedure is unspecified.
+Similarly, @samp{!} is the final character of the names of procedures that store values into
+previously allocated locations (see section 3.4). Such procedures are called @dfn{mutation
+procedures}. The value returned by a mutation procedure is unspecified.
-By convention, ``->'' appears within the names of procedures that take an object of one
-type and return an analogous object of another type. For example, list->vector takes a list
+By convention, ``@samp{->}'' appears within the names of procedures that take an object of one
+type and return an analogous object of another type. For example, @code{list->vector} takes a list
and returns a vector whose elements are the same as those of the list.
-A command is a procedure that does not return useful values to its continuation.
+A @dfn{command} is a procedure that does not return useful values to its continuation.
-A thunk is a procedure that does not accept arguments.
+A @dfn{thunk} is a procedure that does not accept arguments.
@node Lexical conventions
@chapter Lexical conventions
@@ -593,15 +595,15 @@ characters:
@code{! $ % & * + - . / : < = > ? @ ^ _ ~}
Alternatively, an identifier can be represented by a sequence
-of zero or more characters enclosed within vertical lines (|), analogous to string literals.
+of zero or more characters enclosed within vertical lines (@samp{|}), 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
specified using either an <inline hex escape> or the same escapes available in strings.
-For example, the identifier |H\x65;llo| is the same identifier as Hello, and in an
-implementation that supports the appropriate Unicode character the identifier |\x3BB;|
-is the same as the identifier λ. What is more, |\t\t| and |\x9;\x9;| are the same. Note
-that || is a valid identifier that is different from any other identifier.
+For example, the identifier @code{|H\x65;llo|} is the same identifier as @code{Hello}, and in an
+implementation that supports the appropriate Unicode character the identifier @code{|\x3BB;|}
+is the same as the identifier @math{\lambda}. What is more, @code{|\t\t|} and @code{|\x9;\x9;|} are the same. Note
+that @code{||} is a valid identifier that is different from any other identifier.
Here are some examples of identifiers:
@@ -629,7 +631,7 @@ Any identifier can be used as a variable or as a syntactic keyword
@item
When an identifier appears as a literal or within a literal (see
-section 4.1.2), it is being used to denote a symbol (see section 6.5).
+section 4.1.2), it is being used to denote a @dfn{symbol} (see section 6.5).
@end itemize
@@ -652,15 +654,15 @@ The following directives give explicit control over case folding.
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
+the reading of subsequent data from the same port. The @code{#!fold-case} directive causes
subsequent identifiers and character names to be case-folded as if by string-foldcase (see
-section 6.7). It has no effect on character literals. The #!no-fold-case directive causes a
+section 6.7). It has no effect on character literals. The @code{#!no-fold-case} directive causes a
return to the default, non-folding behavior.
@node Whitespace and comments
@section Whitespace and comments
-Whitespace characters include the space, tab, and newline characters. (Implementations
+@dfn{Whitespace} characters include the space, tab, and newline characters. (Implementations
may provide additional whitespace characters such as page break.) Whitespace is used
for improved readability and as necessary to separate tokens from each other, a token
being an indivisible lexical unit such as an identifier or number, but is otherwise
@@ -671,13 +673,13 @@ significant.
The lexical syntax includes several comment forms. Comments are treated exactly like
whitespace.
-A semicolon (;) indicates the start of a line comment.The comment continues to the end
+A semicolon (@samp{;}) indicates the start of a line comment.The comment continues to the end
of the line on which the semicolon appears. Another way to indicate a comment is to
-prefix a <datum> (cf. section 7.1.2) with #;and optional <whitespace>. The comment
+prefix a <datum> (cf. section 7.1.2) with @code{#;} and optional <whitespace>. The comment
consists of the comment prefix #;, the space, and the <datum> together. This notation is
useful for ``commenting out'' sections of code.
-Block comments are indicated with properly nested #|and |# pairs.
+Block comments are indicated with properly nested @code{#|} and @code{|#} pairs.
@example
@@ -766,11 +768,11 @@ For a description of the notations used for numbers, see section 6.2.
lexical syntax: #<n>=<datum>
lexical syntax: #<n>#
-The lexical syntax #<n>=<datum> reads the same as <datum>, but also results in <datum>
+The lexical syntax @code{#}<n>@code{=}<datum> reads the same as <datum>, but also results in <datum>
being labelled by <n>. It is an error if <n> is not a sequence of digits.
-The lexical syntax #<n># serves as a reference to some object labelled by #<n>=; the
-result is the same object as the #<n>= (see section 6.1). Together, these syntaxes permit
+The lexical syntax @code{#}<n>@code{#} serves as a reference to some object labelled by @code{#}<n>@code{=}; the
+result is the same object as the @code{#}<n>@code{=} (see section 6.1). Together, these syntaxes permit
the notation of structures with shared or circular substructure.
@example
@@ -782,10 +784,10 @@ the notation of structures with shared or circular substructure.
@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
-reference appears as the labelled object itself (as in #<n>= #<n>#), because the object
-labelled by #<n>= is not well defined in this case.
+is to the right of the label. Consequently, a reference @code{#}<n>@code{#} can occur only after a label
+@code{#}<n>@code{=}; it is an error to attempt a forward reference. In addition, it is an error if the
+reference appears as the labelled object itself (as in @code{#}<n>@code{=} @code{#}<n>@code{#}), because the object
+labelled by @code{#}<n>@code{=} 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.
