commit 0d662e5757ede77432510634b53002016aa61bc8
parent 294b56c6e0de9bd023ad56c16fd5e91223a0c533
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 5 Feb 2024 14:26:54 -0500
Lexical: Tidy & reflow text.
Diffstat:
1 file changed, 118 insertions(+), 89 deletions(-)
diff --git a/doc/r7rs-small/lexical-conventions.texinfo b/doc/r7rs-small/lexical-conventions.texinfo
@@ -1,8 +1,9 @@
@node Lexical conventions
@chapter Lexical conventions
-This section gives an informal account of some of the lexical conventions used in writing
-Scheme programs. For a formal syntax of Scheme, see @ref{Formal syntax}.
+This section gives an informal account of some of the lexical
+conventions used in writing Scheme programs. For a formal syntax of
+Scheme, see @ref{Formal syntax}.
@menu
* Identifiers::
@@ -14,27 +15,32 @@ Scheme programs. For a formal syntax of Scheme, see @ref{Formal syntax}.
@node Identifiers
@section Identifiers
-An identifier is any sequence of letters, digits, and ``extended identifier characters''
-provided that it does not have a prefix which is a valid number. However, the @code{.} token (a
-single period) used in the list syntax is not an identifier.
+An identifier is any sequence of letters, digits, and ``extended
+identifier characters'' provided that it does not have a prefix which
+is a valid number. However, the @code{.} token (a single period) used
+in the list syntax is not an identifier.
-All implementations of Scheme must support the following extended identifier
-characters:
+All implementations of Scheme must support the following extended
+identifier characters:
@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.
-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 @svar{inline hex escape} or the same escapes available in strings.
-
-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 @theultimate{}. 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.
+Alternatively, an identifier can be represented by a sequence 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 @svar{inline hex escape} or the same
+escapes available in strings.
+
+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 @theultimate{}. 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:
@@ -48,8 +54,7 @@ q V17a
the-word-recursion-has-many-meanings
@end example
-@xref{Formal syntax} for the formal syntax of
-identifiers.
+@xref{Formal syntax} for the formal syntax of identifiers.
Identifiers have two uses within Scheme programs:
@@ -61,17 +66,20 @@ and @ref{Macros}).
@item
When an identifier appears as a literal or within a literal (see
-@ref{Literal expressions}), it is being used to denote a @dfn{symbol} (see @ref{Symbols}).
+@ref{Literal expressions}), it is being used to denote a @dfn{symbol}
+(see @ref{Symbols}).
@end itemize
-In contrast with earlier revisions of the report [20], the syntax distinguishes between
-upper and lower case in identifiers and in characters specified using their names.
-However, it does not distinguish between upper and lower case in numbers, nor in @svar{inline
-hex escapes} used in the syntax of identifiers, characters, or strings. None of the
-identifiers defined in this report contain upper-case characters, even when they appear to
-do so as a result of the English-language convention of capitalizing the first word of a
-sentence.
+In contrast with earlier revisions of the report [20], the syntax
+distinguishes between upper and lower case in identifiers and in
+characters specified using their names. However, it does not
+distinguish between upper and lower case in numbers, nor in
+@svar{inline hex escapes} used in the syntax of identifiers,
+characters, or strings. None of the identifiers defined in this report
+contain upper-case characters, even when they appear to do so as a
+result of the English-language convention of capitalizing the first
+word of a sentence.
The following directives give explicit control over case folding.
@@ -80,36 +88,42 @@ The following directives give explicit control over case folding.
#!no-fold-case
@end lisp
-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
-@ref{Strings}). It has no effect on character literals. The @code{#!no-fold-case} directive causes a
-return to the default, non-folding behavior.
+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 @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
@section Whitespace and comments
-@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
-insignificant. Whitespace can occur between any two tokens, but not within a token.
-Whitespace occurring inside a string or inside a symbol delimited by vertical lines is
-significant.
+@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 insignificant. Whitespace can occur between
+any two tokens, but not within a token. Whitespace occurring inside
+a string or inside a symbol delimited by vertical lines is significant.
-The lexical syntax includes several comment forms. Comments are treated exactly like
-whitespace.
+The lexical syntax includes several comment forms. Comments are
+treated exactly like 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.
+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. @ref{External representations formal}) with @code{#;} and optional @svar{whitespace}. The comment
-consists of the comment prefix @code{#;}, the space, and the @svar{datum} together. This notation is
-useful for ``commenting out'' sections of code.
+Another way to indicate a comment is to prefix a @svar{datum}
+(cf. @ref{External representations formal}) with @code{#;} and
+optional @svar{whitespace}. The comment consists of the comment prefix
+@code{#;}, the space, and the @svar{datum} together. This notation
+is useful for ``commenting out'' sections of code.
-Block comments are indicated with properly nested @code{#|} and @code{|#} pairs.
+Block comments are indicated with properly nested @code{#|} and
+@code{|#} pairs.
@lisp
#|
@@ -132,61 +146,69 @@ For a description of the notations used for numbers, see @ref{Numbers}.
@table @t
@item @code{. + -}
- 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 (@ref{Pairs and lists}), and to
- indicate a rest-parameter in a formal parameter list (@ref{Procedures}). Note that a
- sequence of two or more periods is an identifier.
+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 (@ref{Pairs and lists}),
+and to indicate a rest-parameter in a formal parameter list
+(@ref{Procedures}). Note that a sequence of two or more periods is an
+identifier.
@item @code{( )}
- Parentheses are used for grouping and to notate lists (@ref{Pairs and lists}).
+Parentheses are used for grouping and to notate lists (@ref{Pairs and
+lists}).
@item @code{'}
- The apostrophe (single quote) character is used to indicate literal data
- (@ref{Literal expressions}).
+The apostrophe (single quote) character is used to indicate literal
+data (@ref{Literal expressions}).
@item @code{`}
- The grave accent (backquote) character is used to indicate partly constant data
- (@ref{Quasiquotation}).
+The grave accent (backquote) character is used to indicate partly
+constant data (@ref{Quasiquotation}).
@item @code{, ,@@}
- The character comma and the sequence comma at-sign are used in conjunction with
- quasiquotation (@ref{Quasiquotation}).
+The character comma and the sequence comma at-sign are used in
+conjunction with quasiquotation (@ref{Quasiquotation}).
@item @code{"}
- The quotation mark character is used to delimit strings (@ref{Strings}).
+The quotation mark character is used to delimit strings
+(@ref{Strings}).
@item @code{\}
- Backslash is used in the syntax for character constants (@ref{Characters}) and as an escape
- character within string constants (@ref{Strings}) and identifiers (@ref{Lexical structure}).
+Backslash is used in the syntax for character constants
+(@ref{Characters}) and as an escape character within string constants
+(@ref{Strings}) and identifiers (@ref{Lexical structure}).
@item @code{[ ] @@ |}
- Left and right square and curly brackets (braces) are reserved for possible future
- extensions to the language.
+Left and right square and curly brackets (braces) are reserved for
+possible future extensions to the language.
@item @code{#}
- The number sign is used for a variety of purposes depending on the character that
- immediately follows it:
+The number sign is used for a variety of purposes depending on the
+character that immediately follows it:
@item @code{#t #f}
- These are the boolean constants (@ref{Booleans}), along with the alternatives @code{#true} and
- @code{#false}.
+These are the boolean constants (@ref{Booleans}), along with the
+alternatives @code{#true} and @code{#false}.
@item @code{#\}
- This introduces a character constant (@ref{Characters}).
+This introduces a character constant (@ref{Characters}).
@item @code{#(}
- This introduces a vector constant (@ref{Vectors}). Vector constants are terminated by @code{)}.
+This introduces a vector constant (@ref{Vectors}). Vector constants are
+terminated by @code{)}.
@item @code{#u8(}
- This introduces a bytevector constant (@ref{Bytevectors}). Bytevector constants are
- terminated by @code{)} .
+This introduces a bytevector constant (@ref{Bytevectors}). Bytevector
+constants are terminated by @code{)} .
@item @code{#e #i #b #o #d #x}
- These are used in the notation for numbers (@ref{Syntax of numerical constants}).
+These are used in the notation for numbers
+(@ref{Syntax of numerical constants}).
@item @code{#@r{@svar{n}}= #@r{@svar{n}}#}
- These are used for labeling and referencing other literal data (@ref{Datum labels}).
+These are used for labeling and referencing other literal data
+(@ref{Datum labels}).
@end table
@@ -196,12 +218,15 @@ For a description of the notations used for numbers, see @ref{Numbers}.
@deffn {lexical syntax} #@svar{n}=@svar{datum}
@deffnx {lexical syntax} #@svar{n}#
-The lexical syntax @code{#}@svar{n}@code{=}@svar{datum} reads the same as @svar{datum}, but also results in @svar{datum}
-being labelled by @svar{n}. It is an error if @svar{n} is not a sequence of digits.
+The lexical syntax @code{#}@svar{n}@code{=}@svar{datum} reads the same
+as @svar{datum}, but also results in @svar{datum} being labelled by
+@svar{n}. It is an error if @svar{n} is not a sequence of digits.
-The lexical syntax @code{#}@svar{n}@code{#} serves as a reference to some object labelled by @code{#}@svar{n}@code{=}; the
-result is the same object as the @code{#}@svar{n}@code{=} (see @ref{Equivalence predicates}). Together, these syntaxes permit
-the notation of structures with shared or circular substructure.
+The lexical syntax @code{#}@svar{n}@code{#} serves as a reference to
+some object labelled by @code{#}@svar{n}@code{=}; the result is the
+same object as the @code{#}@svar{n}@code{=} (see
+@ref{Equivalence predicates}). Together, these syntaxes permit the
+notation of structures with shared or circular substructure.
@lisp
(let ((x (list 'a 'b 'c)))
@@ -209,14 +234,18 @@ the notation of structures with shared or circular substructure.
x) @result{} #0=(a b c . #0#)
@end lisp
-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 @code{#}@svar{n}@code{#} can occur only after a label
-@code{#}@svar{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{#}@svar{n}@code{=} @code{#}@svar{n}@code{#}), because the object
-labelled by @code{#}@svar{n}@code{=} is not well defined in this case.
-
-It is an error for a @svar{program} or @svar{library} to include circular references except in literals.
-In particular, it is an error for quasiquote (@ref{Quasiquotation}) to contain them.
+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 @code{#}@svar{n}@code{#} can occur only after a label
+@code{#}@svar{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{#}@svar{n}@code{=}
+@code{#}@svar{n}@code{#}), because the object labelled by
+@code{#}@svar{n}@code{=} is not well defined in this case.
+
+It is an error for a @svar{program} or @svar{library} to include
+circular references except in literals. In particular, it is an error
+for quasiquote (@ref{Quasiquotation}) to contain them.
@lisp
#1=(begin (display #\x) #1#) @result{} @r{error}
