commit 527ecf828e5f3dd1b23c35bf6538e1655ff321d2 parent 8fe3534593002d1bebe163f9331695604307e911 Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz> Date: Thu, 8 Feb 2024 13:24:19 -0500 Use a custom @define instead of @dfn throughout. This is pedantic, but it's annoying that @dfn produces emphasized (<em>...</em>) text in HTML output. Diffstat:
20 files changed, 87 insertions(+), 72 deletions(-)
diff --git a/STYLE.md b/STYLE.md @@ -5,7 +5,9 @@ These are a few style guidelines for the Texinfo version of R7RS. ## Names Use the usual Texinfo `@var`, `@code`, and `@samp` macros whenever -appropriate. Use our `@svar` macro for syntactic variables. +appropriate. Use our `@svar` macro for syntactic variables. Use +`@define{}` (custom macro) rather than `@dfn{}` for definitions; it +produces better HTML output. Use semantic markup! No font (@r, @tt, etc.) nonsense. diff --git a/doc/r7rs-small/basic-concepts.texinfo b/doc/r7rs-small/basic-concepts.texinfo @@ -21,11 +21,11 @@ An identifier can name either a type of syntax or a location where a value can be stored. An identifier that names a type of syntax is -called a @dfn{syntactic keyword} and is said to be @dfn{bound} to +called a @define{syntactic keyword} and is said to be @define{bound} to a transformer for that syntax. An identifier that names a location -is called a @dfn{variable} and is said to be @dfn{bound} to that +is called a @define{variable} and is said to be @define{bound} to that location. The set of all visible bindings in effect at some point -in a program is known as the @dfn{environment} in effect at that +in a program is known as the @define{environment} in effect at that point. The value stored in the location to which a variable is bound is called the variable's value. By abuse of terminology, the variable is sometimes said to name the value or to be bound to the value. This @@ -36,7 +36,7 @@ is not quite accurate, but confusion rarely results from this practice. Certain expression types are used to create new kinds of syntax and to bind syntactic keywords to those new syntaxes, while other expression types create new locations and bind variables to those locations. These -expression types are called @dfn{binding constructs}. Those +expression types are called @define{binding constructs}. Those that bind syntactic keywords are listed in @ref{Macros}. The most fundamental of the variable binding constructs is the @code{lambda} expression, because all other variable binding constructs (except @@ -49,7 +49,7 @@ expressions. The other variable binding constructs are @code{let}, @cindex bound Scheme is a language with block structure. To each place where an -identifier is bound in a program there corresponds a @dfn{region} +identifier is bound in a program there corresponds a @define{region} of the program text within which the binding is visible. The region is determined by the particular binding construct that establishes the binding; if the binding is established by a @code{lambda} @@ -60,7 +60,7 @@ containing the use. If there is no binding of the identifier whose region contains the use, then the use refers to the binding for the variable in the global environment, if any (@ref{Expressions} and @ref{Standard procedures}); if there is no binding for the identifier, -it is said to be @dfn{unbound}. +it is said to be @define{unbound}. @node Disjointness of types @section Disjointness of types @@ -114,10 +114,10 @@ and all predicates created by @code{define-record-type}. @cindex empty list -These predicates define the types @dfn{boolean}, @dfn{bytevector}, -@dfn{character}, the empty list object, @dfn{eof-object}, @dfn{number}, -@dfn{pair}, @dfn{port}, @dfn{procedure}, @dfn{string}, @dfn{symbol}, -@dfn{vector}, and all record types. +These predicates define the types @define{boolean}, @define{bytevector}, +@define{character}, the empty list object, @define{eof-object}, @define{number}, +@define{pair}, @define{port}, @define{procedure}, @define{string}, @define{symbol}, +@define{vector}, and all record types. @cindex true @cindex false @@ -131,7 +131,7 @@ value except @code{#f}, and the word ``false'' to refer to @code{#f}. @node External representations basic @section External representations (basic) -An important concept in Scheme (and Lisp) is that of the @dfn{external +An important concept in Scheme (and Lisp) is that of the @define{external representation} of an object as a sequence of characters. For example, an external representation of the integer 28 is the sequence of characters @samp{28}, and an external representation of a list @@ -234,11 +234,11 @@ immutable objects. @cindex proper tail recursion @cindex tail call -Implementations of Scheme are required to be @dfn{properly +Implementations of Scheme are required to be @define{properly tail-recursive}. Procedure calls that occur in certain syntactic -contexts defined below are @dfn{tail calls}. A Scheme implementation +contexts defined below are @define{tail calls}. A Scheme implementation is properly tail-recursive if it supports an unbounded number of active -tail calls. A call is @dfn{active} if the called procedure might still +tail calls. A call is @define{active} if the called procedure might still return. Note that this includes calls that might be returned from either by the current continuation or by continuations captured earlier by @code{call-with-current-continuation} that are later invoked. In @@ -268,7 +268,7 @@ Steele and Sussman later observed that in their interpreter the code for dealing with actors was identical to that for functions and thus there was no need to include both in the language. -A @dfn{tail call} is a procedure call that occurs in a @dfn{tail +A @define{tail call} is a procedure call that occurs in a @define{tail context}. Tail contexts are defined inductively. Note that a tail context is always determined with respect to a particular lambda expression. diff --git a/doc/r7rs-small/derived/delayed-evaluation.texinfo b/doc/r7rs-small/derived/delayed-evaluation.texinfo @@ -6,9 +6,9 @@ @deffn {lazy library syntax} delay @svar{expression} The @code{delay} construct is used together with the procedure @code{force} to -implement @dfn{lazy evaluation} or @dfn{call by need}. +implement @define{lazy evaluation} or @define{call by need}. @code{(delay} @svar{expression}@code{)} returns an object called a -@dfn{promise} which at some point in the future can be asked (by +@define{promise} which at some point in the future can be asked (by the @code{force} procedure) to evaluate @svar{expression}, and deliver the resulting value. The effect of @svar{expression} returning multiple values diff --git a/doc/r7rs-small/lexical-conventions.texinfo b/doc/r7rs-small/lexical-conventions.texinfo @@ -67,7 +67,7 @@ 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} +@ref{Literal expressions}), it is being used to denote a @define{symbol} (see @ref{Symbols}). @end itemize @@ -101,7 +101,7 @@ to the default, non-folding behavior. @node Whitespace and comments @section Whitespace and comments -@dfn{Whitespace} characters include the space, tab, and newline +@define{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, diff --git a/doc/r7rs-small/macros.texinfo b/doc/r7rs-small/macros.texinfo @@ -2,7 +2,7 @@ @section Macros Scheme programs can define and use new derived expression types, called -@dfn{macros}. Program-defined expression types have the syntax +@define{macros}. Program-defined expression types have the syntax @display @code{(}@svar{keyword} @svar{datum} @dots{}@code{)} @@ -13,16 +13,16 @@ Scheme programs can define and use new derived expression types, called @cindex macro keyword where @svar{keyword} is an identifier that uniquely determines the -expression type. This identifier is called the @dfn{syntactic keyword}, or -simply @dfn{keyword}, of the macro. The number of the @svar{datum}s, and +expression type. This identifier is called the @define{syntactic keyword}, or +simply @define{keyword}, of the macro. The number of the @svar{datum}s, and their syntax, depends on the expression type. @cindex macro use @cindex macro transformer -Each instance of a macro is called a @dfn{use} of the macro. The set of +Each instance of a macro is called a @define{use} of the macro. The set of rules that specifies how a use of a macro is transcribed into a more -primitive expression is called the @dfn{transformer} of the macro. +primitive expression is called the @define{transformer} of the macro. The macro definition facility consists of two parts: @@ -225,7 +225,7 @@ to the template. An identifier appearing within a @svar{pattern} can be an underscore (@code{_}), a literal identifier listed in the list of @svar{pattern literal}s, or the @svar{ellipsis}. All other identifiers appearing within -a @svar{pattern} are @dfn{pattern variables}. +a @svar{pattern} are @define{pattern variables}. The keyword at the beginning of the pattern in a @svar{syntax rule} is not involved in the matching and is considered neither a pattern diff --git a/doc/r7rs-small/overview.texinfo b/doc/r7rs-small/overview.texinfo @@ -95,7 +95,7 @@ The formal syntax of Scheme is described in @ref{Formal syntax}. @subsection Base and optional features Every identifier defined in this report appears in one or more of -several @dfn{libraries}. Identifiers defined in the @dfn{base library} +several @define{libraries}. Identifiers defined in the @define{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 @code{abs} is bound to a @@ -335,13 +335,13 @@ a discussion of external representations of objects. 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 +called @define{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, @samp{!} is the final character of the names of procedures that store values into previously allocated locations (@ref{Storage -model}). Such procedures are called @dfn{mutation procedures}. The +model}). Such procedures are called @define{mutation procedures}. The value returned by a mutation procedure is unspecified. By convention, @samp{->} appears within the names of procedures that @@ -349,7 +349,7 @@ 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 @dfn{command} is a procedure that does not return useful values to +A @define{command} is a procedure that does not return useful values to its continuation. -A @dfn{thunk} is a procedure that does not accept arguments. +A @define{thunk} is a procedure that does not accept arguments. diff --git a/doc/r7rs-small/primitive-expressions.texinfo b/doc/r7rs-small/primitive-expressions.texinfo @@ -141,7 +141,7 @@ remembered as part of the procedure. When the procedure is later called with some actual arguments, the environment in which the @code{lambda} expression was evaluated will be extended by binding the variables in the formal argument list to fresh locations, and the corresponding actual argument -values will be stored in those locations. (A @dfn{fresh} location is one +values will be stored in those locations. (A @define{fresh} location is one that is distinct from every previously existing location.) Next, the expressions in the body of the @code{lambda} expression (which, if it contains definitions, represents a @code{letrec*} form---@xref{Binding diff --git a/doc/r7rs-small/procedures/bytevectors.texinfo b/doc/r7rs-small/procedures/bytevectors.texinfo @@ -1,16 +1,16 @@ @node Bytevectors @section Bytevectors -@dfn{Bytevectors} represent blocks of binary data. They are fixed-length -sequences of bytes, where a @dfn{byte} is an exact integer in the range +@define{Bytevectors} represent blocks of binary data. They are fixed-length +sequences of bytes, where a @define{byte} is an exact integer in the range from 0 to 255 inclusive. A bytevector is typically more space-efficient than a vector containing the same values. @cindex valid indexes -The @dfn{length} of a bytevector is the number of elements that it +The @define{length} of a bytevector is the number of elements that it contains. This number is a non-negative integer that is fixed when -the bytevector is created. The @dfn{valid indexes} of a bytevector are +the bytevector is created. The @define{valid indexes} of a bytevector are the exact non-negative integers less than the length of the bytevector, starting at index zero as with vectors. diff --git a/doc/r7rs-small/procedures/control-features.texinfo b/doc/r7rs-small/procedures/control-features.texinfo @@ -307,7 +307,7 @@ fact @code{call-with-current-continuation} is useful for implementing a wide variety of advanced control structures. In fact, @code{raise} and @code{guard} provide a more structured mechanism for non-local exits. -Whenever a Scheme expression is evaluated there is a @dfn{continuation} +Whenever a Scheme expression is evaluated there is a @define{continuation} wanting the result of the expression. The continuation represents an entire (default) future for the computation. If the expression is evaluated at the REPL, for example, then the continuation might take diff --git a/doc/r7rs-small/procedures/equivalence-predicates.texinfo b/doc/r7rs-small/procedures/equivalence-predicates.texinfo @@ -1,8 +1,8 @@ @node Equivalence predicates @section Equivalence predicates -A @dfn{predicate} is a procedure that always returns a boolean value -(@code{#t} or @code{#f}). An @dfn{equivalence predicate} is the +A @define{predicate} is a procedure that always returns a boolean value +(@code{#t} or @code{#f}). An @define{equivalence predicate} is the computational analogue of a mathematical equivalence relation; it is symmetric, reflexive, and transitive. Of the equivalence predicates described in this section, @code{eq?} is the finest or most diff --git a/doc/r7rs-small/procedures/exceptions.texinfo b/doc/r7rs-small/procedures/exceptions.texinfo @@ -6,7 +6,7 @@ exception-raising procedures. For the concept of Scheme exceptions, see @ref{Error situations and unspecified behavior}. See also @ref{Exception handling} for the @code{guard} syntax. -@dfn{Exception handlers} are one-argument procedures that determine +@define{Exception handlers} are one-argument procedures that determine the action the program takes when an exceptional situation is signaled. The system implicitly maintains a current exception handler in the dynamic environment. @@ -103,7 +103,7 @@ the call to @code{raise-continuable}. Raises an exception as if by calling @code{raise} on a newly allocated implementation-defined object which encapsulates the information provided by @var{message}, as well as any @var{obj}s, -known as the @dfn{irritants}. The procedure @code{error-object?} +known as the @define{irritants}. The procedure @code{error-object?} must return @code{#t} on such objects. @lisp diff --git a/doc/r7rs-small/procedures/input-and-output.texinfo b/doc/r7rs-small/procedures/input-and-output.texinfo @@ -17,9 +17,9 @@ a Scheme object that can deliver data upon command, while an output port is a Scheme object that can accept data. Whether the input and output port types are disjoint is implementation-dependent. -Different @dfn{port types} operate on different data. Scheme -implementations are required to support @dfn{textual ports} and -@dfn{binary ports}, but may also provide other port types. +Different @define{port types} operate on different data. Scheme +implementations are required to support @define{textual ports} and +@define{binary ports}, but may also provide other port types. A textual port supports reading or writing of individual characters from or to a backing store containing characters using @code{read-char} diff --git a/doc/r7rs-small/procedures/numbers.texinfo b/doc/r7rs-small/procedures/numbers.texinfo @@ -62,14 +62,14 @@ of inexact numbers where exact numbers are required, Scheme explicitly distinguishes exact from inexact numbers. This distinction is orthogonal to the dimension of type. -A Scheme number is @dfn{exact} if it was written as an exact constant +A Scheme number is @define{exact} if it was written as an exact constant or was derived from exact numbers using only exact operations. A number -is @dfn{inexact} if it was written as an inexact constant, if it was -derived using @dfn{inexact} ingredients, or if it was derived using -@dfn{inexact} operations. Thus inexactness is a contagious property of -a number. In particular, an @dfn{exact complex number} has an exact +is @define{inexact} if it was written as an inexact constant, if it was +derived using @define{inexact} ingredients, or if it was derived using +@define{inexact} operations. Thus inexactness is a contagious property of +a number. In particular, an @define{exact complex number} has an exact real part and an exact imaginary part; all other complex numbers are -@dfn{inexact complex numbers}. +@define{inexact complex numbers}. If two implementations produce exact results for a computation that did not involve inexact intermediate results, the two ultimate results @@ -345,8 +345,8 @@ In systems with inexact numbers of varying precisions it can be useful to specify the precision of a constant. For this purpose, implementations may accept numerical constants written with an exponent marker that indicates the desired precision of the inexact representation. If so, the -letter @code{s}, @code{f}, @code{d}, or @code{l}, meaning @dfn{short}, -@dfn{single}, @dfn{double}, or @dfn{long} precision, respectively, can +letter @code{s}, @code{f}, @code{d}, or @code{l}, meaning @define{short}, +@define{single}, @define{double}, or @define{long} precision, respectively, can be used in place of @code{e}. The default precision has at least as much precision as double, but implementations may allow this default to be set by the user. @@ -359,7 +359,7 @@ set by the user. @end display The numbers positive infinity, negative infinity, and NaN are written -@code{+inf.0}, @code{-inf.0} and @dfn{+nan.0} respectively. NaN may +@code{+inf.0}, @code{-inf.0} and @define{+nan.0} respectively. NaN may also be written @code{-nan.0}. The use of signs in the written representation does not necessarily reflect the underlying sign of the NaN value, if any. Implementations are not required to support these @@ -369,9 +369,9 @@ signaling NaNs, nor to provide a way to distinguish between different NaNs. There are two notations provided for non-real complex numbers: the -@dfn{rectangular notation} @var{a}@code{+}@var{b}@code{i}, where +@define{rectangular notation} @var{a}@code{+}@var{b}@code{i}, where @var{a} is the real part and @var{b} is the imaginary part; and the -@dfn{polar notation} @var{r}@code{@@}@var{@greektheta{}} where @var{r} +@define{polar notation} @var{r}@code{@@}@var{@greektheta{}} where @var{r} is the magnitude and @var{@greektheta{}} is the phase (angle) in radians. These are related by the equation @math{a + bi = r \cos\theta + (r \sin\theta)i}. All of @var{a}, diff --git a/doc/r7rs-small/procedures/pairs-and-lists.texinfo b/doc/r7rs-small/procedures/pairs-and-lists.texinfo @@ -1,7 +1,7 @@ @node Pairs and lists @section Pairs and lists -A @dfn{pair} (sometimes called a @dfn{dotted pair}) is a record +A @define{pair} (sometimes called a @define{dotted pair}) is a record structure with two fields called the car and cdr fields (for historical reasons). Pairs are created by the procedure @code{cons}. The car and cdr fields are accessed by the procedures @code{car} and @code{cdr}. The @@ -10,7 +10,7 @@ and @code{set-cdr!}. @cindex empty list -Pairs are used primarily to represent lists. A @dfn{list} can be defined +Pairs are used primarily to represent lists. A @define{list} can be defined recursively as either the empty list or a pair whose cdr is a list. More precisely, the set of lists is defined as the smallest set @var{X} such that @@ -66,7 +66,7 @@ and are equivalent notations for a list of symbols. A chain of pairs not ending in the empty list is called an -@dfn{improper list}. Note that an improper list is not a list. The list +@define{improper list}. Note that an improper list is not a list. The list and dotted notations can be combined to represent improper lists: @lisp diff --git a/doc/r7rs-small/procedures/strings.texinfo b/doc/r7rs-small/procedures/strings.texinfo @@ -69,9 +69,9 @@ Examples: @cindex valid indexes -The @dfn{length} of a string is the number of characters that it +The @define{length} of a string is the number of characters that it contains. This number is an exact, non-negative integer that is fixed -when the string is created. The @dfn{valid indexes} of a string are the +when the string is created. The @define{valid indexes} of a string are the exact non-negative integers less than the length of the string. The first character of a string has index 0, the second has index 1, and so on. diff --git a/doc/r7rs-small/procedures/system-interface.texinfo b/doc/r7rs-small/procedures/system-interface.texinfo @@ -93,7 +93,7 @@ system in the same manner as @code{exit}. @deffn {process-context library procedure} get-environment-variable name Many operating systems provide each running process with an -@dfn{environment} consisting of @dfn{environment variables}. (This +@define{environment} consisting of @define{environment variables}. (This environment is not to be confused with the Scheme environments that can be passed to @code{eval}: see @ref{Environments and evaluation}.) Both the name and value of an environment variable are strings. @@ -139,7 +139,7 @@ As of 2018, a TAI-UTC offset table can be found at [@ref{TAI}]. @deffn {time library procedure} current-jiffy -Returns the number of @dfn{jiffies} as an exact integer that have +Returns the number of @define{jiffies} as an exact integer that have elapsed since an arbitrary, implementation-defined epoch. A jiffy is an implementation-defined fraction of a second which is defined by the return value of the @code{jiffies-per-second} procedure. The starting diff --git a/doc/r7rs-small/procedures/vectors.texinfo b/doc/r7rs-small/procedures/vectors.texinfo @@ -6,9 +6,9 @@ integers. A vector typically occupies less space than a list of the same length, and the average time needed to access a randomly chosen element is typically less for the vector than for the list. -The @dfn{length} of a vector is the number of elements that it contains. +The @define{length} of a vector is the number of elements that it contains. This number is a non-negative integer that is fixed when the vector is -created. The @dfn{valid indexes} of a vector are the exact non-negative +created. The @define{valid indexes} of a vector are the exact non-negative integers less than the length of the vector. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector. diff --git a/doc/r7rs-small/program-structure.texinfo b/doc/r7rs-small/program-structure.texinfo @@ -198,7 +198,7 @@ the body of a @code{lambda}, @code{let}, @code{let*}, @code{letrec}, @code{letrec-syntax}, @code{parameterize}, @code{guard}, or @code{case-lambda}). Note that such a body might not be apparent until after expansion of other syntax. Such definitions are known as -@dfn{internal definitions} as opposed to the global definitions described +@define{internal definitions} as opposed to the global definitions described above. The variables defined by internal definitions are local to the @svar{body}. That is, @svar{variable} is bound rather than assigned, and the region of the binding is the entire @svar{body}. For example, @@ -277,7 +277,7 @@ definitions can appear at the outermost level or nested within a body. If the @code{define-syntax} occurs at the outermost level, then the global syntactic environment is extended by binding the @svar{keyword} to the specified transformer, but previous expansions of any global binding -for @svar{keyword} remain unchanged. Otherwise, it is an @dfn{internal +for @svar{keyword} remain unchanged. Otherwise, it is an @define{internal syntax definition}, and is local to the @svar{body} in which it is defined. Any use of a syntax keyword before its corresponding definition is an error. In particular, a use that precedes an inner definition will @@ -325,10 +325,10 @@ are errors: @node Record type definitions @section Record-type definitions -@dfn{Record-type definitions} are used to introduce new data types, called -@dfn{record types}. Like other definitions, they can appear either at the +@define{Record-type definitions} are used to introduce new data types, called +@define{record types}. Like other definitions, they can appear either at the outermost level or in a body. The values of a record type are called -@dfn{records} and are aggregations of zero or more @dfn{fields}, each of +@define{records} and are aggregations of zero or more @define{fields}, each of which holds a single location. A predicate, a constructor, and field accessors and mutators are defined for each record type. @@ -665,7 +665,7 @@ into a REPL, it is not necessary to import the base library. @node The REPL @section The REPL -Implementations may provide an interactive session called a @dfn{REPL} +Implementations may provide an interactive session called a @define{REPL} (Read-Eval-Print Loop), where import declarations, expressions and definitions can be entered and evaluated one at a time. For convenience and ease of use, the global Scheme environment in a REPL must not be diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo @@ -246,7 +246,7 @@ are available at @url{http://srfi.schemers.org}. @node Expressions @chapter Expressions -Expression types are categorized as @dfn{primitive} or @dfn{derived}. +Expression types are categorized as @define{primitive} or @define{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 @@ -325,7 +325,7 @@ of any procedure defined in this report or imported from a library 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, +When a procedure is said to return a @define{newly allocated} object, it means that the locations in the object are fresh. @menu diff --git a/doc/r7rs-small/r7rs-texinfo-macros.texinfo b/doc/r7rs-small/r7rs-texinfo-macros.texinfo @@ -1,3 +1,16 @@ +@c Like @dfn, but correctly produces <dfn>...</dfn> in HTML +@c output. (Why does @dfn produce <em>...</em>?) +@macro define {text} +@dfn{\text\} +@end macro + +@ifhtml +@unmacro define +@macro define {text} +@inlineraw{html, <dfn>\text\</dfn>} +@end macro +@end ifhtml + @c Report names. @macro rsevenrs