commit d12c7f172615623202b2d69bbd037d194821a64f
parent 7b2752c3d8d1949a5d8e0dff67d1ccc22143ef44
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 5 Feb 2024 13:42:22 -0500
Overview, Lexical: Cross-references.
Diffstat:
2 files changed, 40 insertions(+), 39 deletions(-)
diff --git a/doc/r7rs-small/lexical-conventions.texinfo b/doc/r7rs-small/lexical-conventions.texinfo
@@ -48,7 +48,7 @@ q V17a
the-word-recursion-has-many-meanings
@end lisp
-See section 7.1.1 for the formal syntax of
+@xref{Formal syntax} for the formal syntax of
identifiers.
Identifiers have two uses within Scheme programs:
@@ -56,11 +56,12 @@ Identifiers have two uses within Scheme programs:
@itemize
@item
Any identifier can be used as a variable or as a syntactic keyword
-(see sections 3.1 and 4.3).
+(see @ref{Variables - syntactic keywords - and regions,, Variables, syntactic keywords, and regions}
+and @ref{Macros}).
@item
When an identifier appears as a literal or within a literal (see
-section 4.1.2), it is being used to denote a @dfn{symbol} (see section 6.5).
+@{Literal expressions}), it is being used to denote a @dfn{symbol} (see @ref{Symbols}).
@end itemize
@@ -79,11 +80,11 @@ The following directives give explicit control over case folding.
#!no-fold-case
@end lisp
-These directives can appear anywhere comments are permitted (see section 2.2) but
+These directives can appear anywhere comments are permitted (see @ref{Whitespace and comments}) 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 @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 @code{#!no-fold-case} directive causes a
+@ref{Strings}). 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
@@ -102,7 +103,7 @@ whitespace.
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 @svar{datum} (cf. section 7.1.2) with @code{#;} and optional @svar{whitespace}. The comment
+prefix a @svar{datum} (cf. @ref{External representations}) with @code{#;} and optional @svar{whitespace}. The comment
consists of the comment prefix #;, the space, and the @svar{datum} together. This notation is
useful for ``commenting out'' sections of code.
@@ -124,38 +125,38 @@ Block comments are indicated with properly nested @code{#|} and @code{|#} pairs.
@node Other notations
@section Other notations
-For a description of the notations used for numbers, see section 6.2.
+For a description of the notations used for numbers, see @ref{Numbers}.
@table @t
@item @t{. + -}
These are used in numbers, and can also occur anywhere in an identifier. A delimited
plus or minus sign by itself is also an identifier. A delimited period (not occurring
- within a number or identifier) is used in the notation for pairs (section 6.4), and to
- indicate a rest-parameter in a formal parameter list (section 4.1.4). Note that a
+ within a number or identifier) is used in the notation for pairs (@ref{Pairs and lists}), and to
+ indicate a rest-parameter in a formal parameter list (@{Procedures}). Note that a
sequence of two or more periods is an identifier.
@item @t{( )}
- Parentheses are used for grouping and to notate lists (section 6.4).
+ Parentheses are used for grouping and to notate lists (@ref{Pairs and lists}).
@item @t{'}
- The apostrophe (single quote) character is used to indicate literal data (section
- 4.1.2).
+ The apostrophe (single quote) character is used to indicate literal data
+ (@ref{Literal expressions}).
@item @t{`}
The grave accent (backquote) character is used to indicate partly constant data
- (section 4.2.8).
+ (@ref{Quasiquotation}).
@item @t{, ,@@}
The character comma and the sequence comma at-sign are used in conjunction with
- quasiquotation (section 4.2.8).
+ quasiquotation (@ref{Quasiquotation}).
@item @t{"}
- The quotation mark character is used to delimit strings (section 6.7).
+ The quotation mark character is used to delimit strings (@ref{Strings}).
@item @t{\}
- Backslash is used in the syntax for character constants (section 6.6) and as an escape
- character within string constants (section 6.7) and identifiers (section 7.1.1).
+ Backslash is used in the syntax for character constants (@ref{Characters}) and as an escape
+ character within string constants (@{Strings}) and identifiers (@ref{Lexical structure}).
@item @t{[ ] @{ @} |}
Left and right square and curly brackets (braces) are reserved for possible future
@@ -166,24 +167,24 @@ For a description of the notations used for numbers, see section 6.2.
immediately follows it:
@item @t{#t #f}
- These are the boolean constants (section 6.3), along with the alternatives #true and
+ These are the boolean constants (@ref{Booleans}), along with the alternatives #true and
#false.
@item @t{#\}
- This introduces a character constant (section 6.6).
+ This introduces a character constant (@ref{Characters}).
@item @t{#(}
- This introduces a vector constant (section 6.8). Vector constants are terminated by ) .
+ This introduces a vector constant (@ref{Vectors}). Vector constants are terminated by ) .
@item @t{#u8(}
- This introduces a bytevector constant (section 6.9). Bytevector constants are
+ This introduces a bytevector constant (@ref{Bytevectors}). Bytevector constants are
terminated by @code{)} .
@item @t{#e #i #b #o #d #x}
- These are used in the notation for numbers (section 6.2.5).
+ These are used in the notation for numbers (@ref{Syntax of numerical constants}).
@item @t{#<n>= #<n>#}
- These are used for labeling and referencing other literal data (section 2.4).
+ These are used for labeling and referencing other literal data (@{Datum labels}).
@end table
@@ -197,7 +198,7 @@ The lexical syntax @code{#}<n>@code{=}<datum> reads the same as <datum>, but als
being labelled by <n>. It is an error if <n> is not a sequence of digits.
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
+result is the same object as the @code{#}<n>@code{=} (see @ref{Equivalence predicates}). Together, these syntaxes permit
the notation of structures with shared or circular substructure.
@lisp
@@ -213,7 +214,7 @@ reference appears as the labelled object itself (as in @code{#}<n>@code{=} @code
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.
+In particular, it is an error for quasiquote (@ref{Quasiquotation}) to contain them.
@lisp
#1=(begin (display #\x) #1#) @result{} @r{error}
diff --git a/doc/r7rs-small/overview.texinfo b/doc/r7rs-small/overview.texinfo
@@ -11,7 +11,7 @@
@section Semantics
This section gives an overview of Scheme's semantics. A detailed informal semantics is the
-subject of chapters 3 through 6. For reference purposes, section 7.2 provides a formal
+subject of chapters @ref{Basic concepts} through @ref{Standard procedures}. For reference purposes, @ref{Formal semantics} provides a formal
semantics of Scheme.
Scheme is a statically scoped programming language. Each use of a variable is associated
@@ -30,14 +30,14 @@ required to be properly tail-recursive. This allows the execution of an iterativ
computation in constant space, even if the iterative computation is described by a
syntactically recursive procedure. Thus with a properly tail-recursive implementation,
iteration can be expressed using the ordinary procedure-call mechanics, so that special
-iteration constructs are useful only as syntactic sugar. See section 3.5.
+iteration constructs are useful only as syntactic sugar. @xref{Proper tail recursion}.
Scheme procedures are objects in their own right. Procedures can be created
dynamically, stored in data structures, returned as results of procedures, and so on. One
distinguishing feature of Scheme is that continuations, which in most other languages
only operate behind the scenes, also have ``first-class'' status. Continuations are useful for
implementing a wide variety of advanced control constructs, including non-local exits,
-backtracking, and coroutines. See section 6.10.
+backtracking, and coroutines. @xref{Control features}.
Arguments to Scheme procedures are always passed by value, which means that the
actual argument expressions are evaluated before the procedure gains control,
@@ -61,9 +61,9 @@ programs. For example, the eval procedure evaluates a Scheme program expressed a
data.
The read procedure performs syntactic as well as lexical decomposition of the data it
-reads. The read procedure parses its input as data (section 7.1.2), not as program.
+reads. The read procedure parses its input as data (@ref{External representations formal,, External representations}), not as program.
-The formal syntax of Scheme is described in section 7.1.
+The formal syntax of Scheme is described in @ref{Formal syntax}.
@node Notation and terminology
@section Notation and terminology
@@ -85,7 +85,7 @@ This library includes the core syntax of Scheme and generally useful procedures
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.
+is given in @ref{Appendix A}.
All implementations of Scheme:
@@ -115,8 +115,8 @@ 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 @code{raise} as described in section
-6.11. The object raised is implementation-dependent and need not be distinct from
+raising a non-continuable exception, as if by the procedure @code{raise} as described in
+@{Exceptions}. 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.
@@ -163,7 +163,7 @@ programmer or program behavior.
@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
+Chapters @ref{Expressions} and @{Standard procedures} 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
procedure. An entry begins with one or more header lines of the form
@@ -183,7 +183,7 @@ template
where
-name is the short name of a library as defined in Appendix A.
+name is the short name of a library as defined in @ref{Appendix A}.
If
@@ -242,7 +242,7 @@ 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
+name of a type listed in @ref{Disjointness of types}, then it is an error if that argument is not of the named
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:
@@ -273,7 +273,7 @@ exact non-negative integer
alphabetic character
@item @var{list}, @var{list}@sub{1}, @dots{} @var{list}@sub{@var{j}}, @dots{}
-list
+list (see @{Pairs and lists})
@item @var{n}, @var{n}@sub{1}, @dots{} @var{n}@sub{@var{j}}, @dots{}
integer
@@ -363,7 +363,7 @@ The symbol ``@result{}'' used in program examples is read ``evaluates to.'' For
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
+by the sequence of characters ``@code{40}.'' @xref{External representations basic,, External representations} for a discussion of external
representations of objects.
@node Naming conventions
@@ -375,7 +375,7 @@ to be side-effect free, except that they may raise an exception when passed the
type of argument.
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
+previously allocated locations (@ref{Storage model}). Such procedures are called @dfn{mutation
procedures}. The value returned by a mutation procedure is unspecified.
By convention, ``@samp{->}'' appears within the names of procedures that take an object of one
