commit 5029ab36f96e6d8caedd796149b94d961b5ae4a7
parent 62f82a8840896770ad411249f743c2a5c802d247
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Wed, 7 Feb 2024 12:43:56 -0500
Reflow intro, etc.
Diffstat:
1 file changed, 180 insertions(+), 145 deletions(-)
diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo
@@ -48,39 +48,47 @@ December 19, 2022
@majorheading Summary
-The report gives a defining description of the programming language Scheme. Scheme is
-a statically scoped and properly tail recursive dialect of the Lisp programming language
-[@ref{McCarthy}] invented by Guy Lewis Steele Jr. and Gerald Jay Sussman. It was designed to have
-exceptionally clear and simple semantics and few different ways to form expressions. A
-wide variety of programming paradigms, including imperative, functional, and
-object-oriented styles, find convenient expression in Scheme.
-
-The introduction offers a brief history of the language and of the report.
-
-The first three chapters present the fundamental ideas of the language and describe the
-notational conventions used for describing the language and for writing programs in the
-language.
-
-@ref{Expressions} and @ref{Program structure} describe the syntax and semantics of expressions, definitions,
-programs, and libraries.
-
-@ref{Standard procedures} describes Scheme's built-in procedures, which include all of the language's data
-manipulation and input/output primitives.
-
-@ref{Formal syntax and semantics} provides a formal syntax for Scheme written in extended BNF, along with a
-formal denotational semantics. An example of the use of the language follows the formal
+The report gives a defining description of the programming language
+Scheme. Scheme is a statically scoped and properly tail recursive
+dialect of the Lisp programming language [@ref{McCarthy}] invented by
+Guy Lewis Steele Jr. and Gerald Jay Sussman. It was designed to have
+exceptionally clear and simple semantics and few different ways to
+form expressions. A wide variety of programming paradigms, including
+imperative, functional, and object-oriented styles, find convenient
+expression in Scheme.
+
+The introduction offers a brief history of the language and of
+the report.
+
+The first three chapters present the fundamental ideas of the language
+and describe the notational conventions used for describing the
+language and for writing programs in the language.
+
+@ref{Expressions} and @ref{Program structure} describe the syntax
+and semantics of expressions, definitions, programs, and libraries.
+
+@ref{Standard procedures} describes Scheme's built-in procedures,
+which include all of the language's data manipulation and input/output
+primitives.
+
+@ref{Formal syntax and semantics} provides a formal syntax for
+Scheme written in extended BNF, along with a formal denotational
+semantics. An example of the use of the language follows the formal
syntax and semantics.
-@ref{Appendix A,, Appendix A} provides a list of the standard libraries and the identifiers that they export.
+@ref{Appendix A,, Appendix A} provides a list of the standard libraries
+and the identifiers that they export.
-@ref{Appendix B,, Appendix B} provides a list of optional but standardized implementation feature names.
+@ref{Appendix B,, Appendix B} provides a list of optional but
+standardized implementation feature names.
The report concludes with a list of references and an alphabetic index.
-Note: The editors of the @rfivers{} and @rsixrs{} reports are listed as authors of this report in
-recognition of the substantial portions of this report that are copied directly from
-@rfivers{} and @rsixrs{}. There is no intended implication that those editors, individually or
-collectively, support or do not support this report.
+Note: The editors of the @rfivers{} and @rsixrs{} reports are
+listed as authors of this report in recognition of the substantial
+portions of this report that are copied directly from @rfivers{}
+and @rsixrs{}. There is no intended implication that those editors,
+individually or collectively, support or do not support this report.
@menu
* Introduction::
@@ -101,107 +109,132 @@ collectively, support or do not support this report.
@node Introduction
@chapter Introduction
-Programming languages should be designed not by piling feature on top of feature, but
-by removing the weaknesses and restrictions that make additional features appear
-necessary. Scheme demonstrates that a very small number of rules for forming
-expressions, with no restrictions on how they are composed, suffice to form a practical
-and efficient programming language that is flexible enough to support most of the major
-programming paradigms in use today.
-
-Scheme was one of the first programming languages to incorporate first-class
-procedures as in the lambda calculus, thereby proving the usefulness of static scope rules
-and block structure in a dynamically typed language. Scheme was the first major dialect
-of Lisp to distinguish procedures from lambda expressions and symbols, to use a single
-lexical environment for all variables, and to evaluate the operator position of a procedure
-call in the same way as an operand position. By relying entirely on procedure calls to
-express iteration, Scheme emphasized the fact that tail-recursive procedure calls are
-essentially GOTOs that pass arguments, thus allowing a programming style that is both
-coherent and efficient. Scheme was the first widely used programming language to
-embrace first-class escape procedures, from which all previously known sequential
-control structures can be synthesized. A subsequent version of Scheme introduced the
-concept of exact and inexact numbers, an extension of Common Lisp's generic
-arithmetic. More recently, Scheme became the first programming language to support
-hygienic macros, which permit the syntax of a block-structured language to be extended
-in a consistent and reliable manner.
+Programming languages should be designed not by piling feature on top
+of feature, but by removing the weaknesses and restrictions that make
+additional features appear necessary. Scheme demonstrates that a very
+small number of rules for forming expressions, with no restrictions
+on how they are composed, suffice to form a practical and efficient
+programming language that is flexible enough to support most of the
+major programming paradigms in use today.
+
+Scheme was one of the first programming languages to incorporate
+first-class procedures as in the lambda calculus, thereby proving the
+usefulness of static scope rules and block structure in a dynamically
+typed language. Scheme was the first major dialect of Lisp to
+distinguish procedures from lambda expressions and symbols, to use
+a single lexical environment for all variables, and to evaluate the
+operator position of a procedure call in the same way as an operand
+position. By relying entirely on procedure calls to express iteration,
+Scheme emphasized the fact that tail-recursive procedure calls are
+essentially GOTOs that pass arguments, thus allowing a programming
+style that is both coherent and efficient. Scheme was the first widely
+used programming language to embrace first-class escape procedures,
+from which all previously known sequential control structures can be
+synthesized. A subsequent version of Scheme introduced the concept
+of exact and inexact numbers, an extension of Common Lisp's generic
+arithmetic. More recently, Scheme became the first programming
+language to support hygienic macros, which permit the syntax of a
+block-structured language to be extended in a consistent and reliable
+manner.
@heading Background
-The first description of Scheme was written in 1975 [@ref{Scheme75}]. A revised report [@ref{Scheme78}] appeared in
-1978, which described the evolution of the language as its MIT implementation was
-upgraded to support an innovative compiler [@ref{Rabbit}]. Three distinct projects began in 1981
-and 1982 to use variants of Scheme for courses at MIT, Yale, and Indiana University
-[@ref{Rees82}, @ref{MITScheme}, @ref{Scheme311}]
-An introductory computer science textbook using Scheme was published in 1984
-[@ref{SICP}].
-
-As Scheme became more widespread, local dialects began to diverge until students and
-researchers occasionally found it difficult to understand code written at other sites.
-Fifteen representatives of the major implementations of Scheme therefore met in
-October 1984 to work toward a better and more widely accepted standard for Scheme.
-Their report, the RRRS [@ref{RRRS}], was published at MIT and Indiana University in the summer of
-1985. Further revision took place in the spring of 1986, resulting in the R3RS [@ref{R3RS}]. Work in
-the spring of 1988 resulted in R4RS [@ref{R4RS}], which became the basis for the IEEE Standard for
-the Scheme Programming Language in 1991 [@ref{IEEEScheme}]. In 1998, several additions to the IEEE
-standard, including high-level hygienic macros, multiple return values, and eval, were
-finalized as the @rfivers{} [@ref{@rfivers{}}].
-
-In the fall of 2006, work began on a more ambitious standard, including many new
-improvements and stricter requirements made in the interest of improved portability. The
-resulting standard, the @rsixrs{}, was completed in August 2007 [@ref{@rsixrs{}}], and was organized as a
-core language and set of mandatory standard libraries. Several new implementations of
-Scheme conforming to it were created. However, most existing @rfivers{} implementations
-(even excluding those which are essentially unmaintained) did not adopt @rsixrs{}, or adopted
+The first description of Scheme was written in 1975 [@ref{Scheme75}]. A
+revised report [@ref{Scheme78}] appeared in 1978, which described
+the evolution of the language as its MIT implementation was upgraded
+to support an innovative compiler [@ref{Rabbit}]. Three distinct
+projects began in 1981 and 1982 to use variants of Scheme for courses
+at MIT, Yale, and Indiana University [@ref{Rees82}, @ref{MITScheme},
+@ref{Scheme311}] An introductory computer science textbook using
+Scheme was published in 1984 [@ref{SICP}].
+
+As Scheme became more widespread, local dialects began to diverge
+until students and researchers occasionally found it difficult to
+understand code written at other sites. Fifteen representatives of
+the major implementations of Scheme therefore met in October 1984 to
+work toward a better and more widely accepted standard for Scheme.
+Their report, the RRRS [@ref{RRRS}], was published at MIT and Indiana
+University in the summer of 1985. Further revision took place in
+the spring of 1986, resulting in the R3RS [@ref{R3RS}]. Work in the
+spring of 1988 resulted in R4RS [@ref{R4RS}], which became the basis
+for the IEEE Standard for the Scheme Programming Language in 1991
+[@ref{IEEEScheme}]. In 1998, several additions to the IEEE standard,
+including high-level hygienic macros, multiple return values, and eval,
+were finalized as the @rfivers{} [@ref{@rfivers{}}].
+
+In the fall of 2006, work began on a more ambitious standard, including
+many new improvements and stricter requirements made in the interest
+of improved portability. The resulting standard, the @rsixrs{}, was
+completed in August 2007 [@ref{@rsixrs{}}], and was organized as a
+core language and set of mandatory standard libraries. Several new
+implementations of Scheme conforming to it were created. However,
+most existing @rfivers{} implementations (even excluding those which
+are essentially unmaintained) did not adopt @rsixrs{}, or adopted
only selected parts of it.
-In consequence, the Scheme Steering Committee decided in August 2009 to divide the
-standard into two separate but compatible languages---a ``small'' language, suitable for
-educators, researchers, and users of embedded languages, focused on @rfivers{}
-compatibility, and a ``large'' language focused on the practical needs of mainstream
-software development, intended to become a replacement for @rsixrs{}. The present report
-describes the ``small'' language of that effort: therefore it cannot be considered in
-isolation as the successor to @rsixrs{}.
-
-We intend this report to belong to the entire Scheme community, and so we grant
-permission to copy it in whole or in part without fee. In particular, we encourage
-implementers of Scheme to use this report as a starting point for manuals and other
-documentation, modifying it as necessary.
+In consequence, the Scheme Steering Committee decided in August 2009
+to divide the standard into two separate but compatible languages---a
+``small'' language, suitable for educators, researchers, and users
+of embedded languages, focused on @rfivers{} compatibility, and a
+``large'' language focused on the practical needs of mainstream
+software development, intended to become a replacement for
+@rsixrs{}. The present report describes the ``small'' language of
+that effort: therefore it cannot be considered in isolation as the
+successor to @rsixrs{}.
+
+We intend this report to belong to the entire Scheme community, and
+so we grant permission to copy it in whole or in part without fee. In
+particular, we encourage implementers of Scheme to use this report
+as a starting point for manuals and other documentation, modifying
+it as necessary.
@heading Acknowledgments
-We would like to thank the members of the Steering Committee, William Clinger, Marc
-Feeley, Chris Hanson, Jonathan Rees, and Olin Shivers, for their support and guidance.
-
-This report is very much a community effort, and we'd like to thank everyone who
-provided comments and feedback, including the following people: David Adler, Eli
-Barzilay, Taylan Ulrich Bay@dotless{i}rl@dotless{i}/Kammer, Marco Benelli, Pierpaolo Bernardi, Peter Bex, Per
-Bothner, John Boyle, Taylor Campbell, Raffael Cavallaro, Ray Dillinger, Biep Durieux,
-Sztefan Edwards, Helmut Eller, Justin Ethier, Jay Reynolds Freeman, Tony Garnock-Jones,
-Alan Manuel Gloria, Steve Hafner, Sven Hartrumpf, Brian Harvey, Moritz Heidkamp,
-Jean-Michel Hufflen, Aubrey Jaffer, Takashi Kato, Shiro Kawai, Richard Kelsey, Oleg
-Kiselyov, Pjotr Kourzanov, Jonathan Kraut, Daniel Krueger, Christian Stigen Larsen, Noah
-Lavine, Stephen Leach, Larry D. Lee, Kun Liang, Thomas Lord, Vincent Stewart Manis, Perry
-Metzger, Michael Montague, Mikael More, Vitaly Magerya, Vincent Manis, Vassil Nikolov,
-Joseph Wayne Norton, Yuki Okumura, Daichi Oohashi, Jeronimo Pellegrini, Jussi
-Piitulainen, Alex Queiroz, Jim Rees, Grant Rettke, Andrew Robbins, Devon Schudy, Bakul
-Shah, Robert Smith, Arthur Smyles, Michael Sperber, John David Stone, Jay Sulzberger,
-Malcolm Tredinnick, Sam Tobin-Hochstadt, Andre van Tonder, Daniel Villeneuve, Denis
-Washington, Alan Watson, Mark H. Weaver, G@"oran Weinholt, David A. Wheeler, Andy
-Wingo, James Wise, J@"org F. Wittenberger, Kevin A. Wortman, Sascha Ziemann.
-
-In addition we would like to thank all the past editors, and the people who helped them in
-turn: Hal Abelson, Norman Adams, David Bartley, Alan Bawden, Michael Blair, Gary
-Brooks, George Carrette, Andy Cromarty, Pavel Curtis, Jeff Dalton, Olivier Danvy, Ken
-Dickey, Bruce Duba, Robert Findler, Andy Freeman, Richard Gabriel, Yekta G@"ursel, Ken
-Haase, Robert Halstead, Robert Hieb, Paul Hudak, Morry Katz, Eugene Kohlbecker, Chris
-Lindblad, Jacob Matthews, Mark Meyer, Jim Miller, Don Oxley, Jim Philbin, Kent Pitman,
-John Ramsdell, Guillermo Rozas, Mike Shaff, Jonathan Shapiro, Guy Steele, Julie Sussman,
-Perry Wagle, Mitchel Wand, Daniel Weise, Henry Wu, and Ozan Yigit. We thank Carol
-Fessenden, Daniel Friedman, and Christopher Haynes for permission to use text from the
-Scheme 311 version 4 reference manual. We thank Texas Instruments, Inc. for permission
-to use text from the TI Scheme Language Reference Manual [@ref{TImanual85}]. We gladly acknowledge the
-influence of manuals for MIT Scheme [@ref{MITScheme}], T [@ref{Rees84}], Scheme 84 [@ref{Scheme84}], Common Lisp [@ref{CLtL}], and
-Algol 60 [@ref{Naur63}], as well as the following SRFIs: 0, 1, 4, 6, 9, 11, 13, 16, 30, 34, 39, 43, 46, 62, and
-87, all of which are available at @url{http://srfi.schemers.org}.
+We would like to thank the members of the Steering Committee, William
+Clinger, Marc Feeley, Chris Hanson, Jonathan Rees, and Olin Shivers,
+for their support and guidance.
+
+This report is very much a community effort, and we'd like to
+thank everyone who provided comments and feedback, including
+the following people: David Adler, Eli Barzilay, Taylan Ulrich
+Bay@dotless{i}rl@dotless{i}/Kammer, Marco Benelli, Pierpaolo Bernardi,
+Peter Bex, Per Bothner, John Boyle, Taylor Campbell, Raffael Cavallaro,
+Ray Dillinger, Biep Durieux, Sztefan Edwards, Helmut Eller, Justin
+Ethier, Jay Reynolds Freeman, Tony Garnock-Jones, Alan Manuel
+Gloria, Steve Hafner, Sven Hartrumpf, Brian Harvey, Moritz Heidkamp,
+Jean-Michel Hufflen, Aubrey Jaffer, Takashi Kato, Shiro Kawai,
+Richard Kelsey, Oleg Kiselyov, Pjotr Kourzanov, Jonathan Kraut,
+Daniel Krueger, Christian Stigen Larsen, Noah Lavine, Stephen Leach,
+Larry D. Lee, Kun Liang, Thomas Lord, Vincent Stewart Manis, Perry
+Metzger, Michael Montague, Mikael More, Vitaly Magerya, Vincent Manis,
+Vassil Nikolov, Joseph Wayne Norton, Yuki Okumura, Daichi Oohashi,
+Jeronimo Pellegrini, Jussi Piitulainen, Alex Queiroz, Jim Rees, Grant
+Rettke, Andrew Robbins, Devon Schudy, Bakul Shah, Robert Smith, Arthur
+Smyles, Michael Sperber, John David Stone, Jay Sulzberger, Malcolm
+Tredinnick, Sam Tobin-Hochstadt, Andre van Tonder, Daniel Villeneuve,
+Denis Washington, Alan Watson, Mark H. Weaver, G@"oran Weinholt,
+David A. Wheeler, Andy Wingo, James Wise, J@"org F. Wittenberger,
+Kevin A. Wortman, Sascha Ziemann.
+
+In addition we would like to thank all the past editors, and the people
+who helped them in turn: Hal Abelson, Norman Adams, David Bartley, Alan
+Bawden, Michael Blair, Gary Brooks, George Carrette, Andy Cromarty,
+Pavel Curtis, Jeff Dalton, Olivier Danvy, Ken Dickey, Bruce Duba,
+Robert Findler, Andy Freeman, Richard Gabriel, Yekta G@"ursel, Ken
+Haase, Robert Halstead, Robert Hieb, Paul Hudak, Morry Katz, Eugene
+Kohlbecker, Chris Lindblad, Jacob Matthews, Mark Meyer, Jim Miller,
+Don Oxley, Jim Philbin, Kent Pitman, John Ramsdell, Guillermo Rozas,
+Mike Shaff, Jonathan Shapiro, Guy Steele, Julie Sussman, Perry Wagle,
+Mitchel Wand, Daniel Weise, Henry Wu, and Ozan Yigit. We thank Carol
+Fessenden, Daniel Friedman, and Christopher Haynes for permission
+to use text from the Scheme 311 version 4 reference manual. We
+thank Texas Instruments, Inc. for permission to use text from the
+TI Scheme Language Reference Manual [@ref{TImanual85}]. We gladly
+acknowledge the influence of manuals for MIT Scheme [@ref{MITScheme}],
+T [@ref{Rees84}], Scheme 84 [@ref{Scheme84}], Common Lisp [@ref{CLtL}],
+and Algol 60 [@ref{Naur63}], as well as the following SRFIs: 0, 1,
+4, 6, 9, 11, 13, 16, 30, 34, 39, 43, 46, 62, and 87, all of which
+are available at @url{http://srfi.schemers.org}.
@include overview.texinfo
@@ -213,15 +246,16 @@ Algol 60 [@ref{Naur63}], as well as the following SRFIs: 0, 1, 4, 6, 9, 11, 13,
@chapter Expressions
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 @ref{Derived expression types formal}.
+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 @ref{Derived expression
+types formal}.
The procedures @code{force}, @code{promise?}, @code{make-promise}, and
-@code{make-parameter} are also described in this chapter because they are
-intimately associated with the @code{delay}, @code{delay-force}, and
-@code{parameterize} expression types.
+@code{make-parameter} are also described in this chapter because they
+are intimately associated with the @code{delay}, @code{delay-force},
+and @code{parameterize} expression types.
@menu
* Primitive expression types::
@@ -234,9 +268,11 @@ intimately associated with the @code{delay}, @code{delay-force}, and
@node Derived expression types
@section Derived expression types
-The constructs in this section are hygienic, as discussed in @ref{Macros}. For reference
-purposes, @ref{Derived expression types formal} gives syntax definitions that will convert most of the constructs
-described in this section into the primitive constructs described in the previous section.
+The constructs in this section are hygienic, as discussed in
+@ref{Macros}. For reference purposes, @ref{Derived expression types
+formal} gives syntax definitions that will convert most of the
+constructs described in this section into the primitive constructs
+described in the previous section.
@menu
* Conditionals derived::
@@ -269,19 +305,20 @@ described in this section into the primitive constructs described in the previou
This chapter describes Scheme's built-in procedures.
-The procedures @code{force}, @code{promise?}, and @code{make-promise} are intimately associated
-with the expression types @code{delay} and @code{delay-force}, and are described
-with them in @ref{Delayed evaluation}. In the same way, the procedure
-@code{make-parameter} is intimately associated with the expression type
-@code{parameterize}, and is described with it in @ref{Dynamic bindings}.
-
-A program can use a global variable definition to bind any variable. It may
-subsequently alter any such binding by an assignment (@xref{Assignments}).
-These operations do not modify the behavior of
-any procedure defined in this report or imported from a library
-(@xref{Libraries}). Altering any global binding that has
-not been introduced by a definition has an unspecified effect on the
-behavior of the procedures defined in this chapter.
+The procedures @code{force}, @code{promise?}, and @code{make-promise}
+are intimately associated with the expression types @code{delay}
+and @code{delay-force}, and are described with them in @ref{Delayed
+evaluation}. In the same way, the procedure @code{make-parameter} is
+intimately associated with the expression type @code{parameterize},
+and is described with it in @ref{Dynamic bindings}.
+
+A program can use a global variable definition to bind any
+variable. It may subsequently alter any such binding by an assignment
+(@xref{Assignments}). These operations do not modify the behavior
+of any procedure defined in this report or imported from a library
+(@xref{Libraries}). Altering any global binding that has not been
+introduced by a definition has an unspecified effect on the behavior
+of the procedures defined in this chapter.
When a procedure is said to return a @dfn{newly allocated} object,
it means that the locations in the object are fresh.
@@ -356,6 +393,4 @@ described informally in previous chapters of this report.
@include references.texinfo
-@c Alphabetic index of definitions of concepts, keywords, and procedures
-
@bye
