commit 8345dea969042d169f00d392611783ad7bcb9806
parent dd120c63da5b337fc905b2ffd495d2d3700d87ed
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 5 Feb 2024 13:11:26 -0500
System interface: Texify.
Also, add a @rationale macro to our macros file.
Diffstat:
2 files changed, 77 insertions(+), 69 deletions(-)
diff --git a/doc/r7rs-small/procedures/system-interface.texinfo b/doc/r7rs-small/procedures/system-interface.texinfo
@@ -7,48 +7,46 @@ However, the following operations are important enough to deserve description he
@deffn {load library procedure} load filename
@deffnx {load library procedure} load filename environment-specifier
-It is an error if
-
-filename is not a string.
+It is an error if @var{filename} is not a string.
An implementation-dependent operation is used to transform
+@var{filename} into the name of an existing file
+containing Scheme source code. The @code{load} procedure reads
+expressions and definitions from the file and evaluates them
+sequentially in the environment specified by @var{environment-specifier}.
+If @var{environment-specifier} is omitted, @code{(interaction-environment)}
+is assumed.
-filename into the name of an existing file containing Scheme source code. The load
-procedure reads expressions and definitions from the file and evaluates them
-sequentially in the environment specified by
-
-environment-specifier. If
+It is unspecified whether the results of the expressions
+are printed. The @code{load} procedure does not affect the values
+returned by @code{current-input-port} and @code{current-output-port}.
+It returns an unspecified value.
-environment-specifier is omitted, (interaction-environment) is assumed.
+@rationale{}
-It is unspecified whether the results of the expressions are printed. The load procedure
-does not affect the values returned by current-input-port and current-output-port. It
-returns an unspecified value.
-
-Rationale: For portability, load must operate on source files. Its operation on other
-kinds of files necessarily varies among implementations.
-@end deffn
+For portability, @code{load} must operate on source files.
+Its operation on other kinds of files necessarily varies among
+implementations.
@deffn {file library procedure} file-exists? filename
-It is an error if
+It is an error if @var{filename} is not a string.
-filename is not a string.
-
-The file-exists? procedure returns #t if the named file exists at the time the procedure is
-called, and #f otherwise.
+The @code{file-exists?} procedure returns
+@code{#t} if the named file exists at the time the procedure is called,
+and @code{#f} otherwise.
@end deffn
@deffn {file library procedure} delete-file filename
-It is an error if
+It is an error if @var{filename} is not a string.
-filename is not a string.
+The @code{delete-file} procedure deletes the
+named file if it exists and can be deleted, and returns an unspecified
+value. If the file does not exist or cannot be deleted, an error
+that satisfies @code{file-error?} is signaled.
-The delete-file procedure deletes the named file if it exists and can be deleted, and
-returns an unspecified value. If the file does not exist or cannot be deleted, an error that
-satisfies file-error? is signaled.
@end deffn
@deffn {process-context library procedure} command-line
@@ -56,54 +54,54 @@ satisfies file-error? is signaled.
Returns the command line passed to the process as a list of strings. The first string
corresponds to the command name, and is implementation-dependent. It is an error to
mutate any of these strings.
+
@end deffn
@deffn {process-context library procedure} exit
@deffnx {process-context library procedure} exit obj
-Runs all outstanding dynamic-wind
-
-after procedures, terminates the running program, and communicates an exit value to
-the operating system. If no argument is supplied, or if
-
-obj is #t, the exit procedure should communicate to the operating system that the
-program exited normally. If
+Runs all outstanding dynamic-wind @var{after} procedures, terminates the
+running program, and communicates an exit value to the operating system.
+If no argument is supplied, or if @var{obj} is @code{#t}, the
+@code{exit} procedure should communicate to the operating system that the
+program exited normally. If @var{obj} is @code{#f}, the @code{exit}
+procedure should communicate to the operating system that the program
+exited abnormally. Otherwise, @code{exit} should translate @var{obj} into
+an appropriate exit value for the operating system, if possible.
-obj is #f, the exit procedure should communicate to the operating system that the
-program exited abnormally. Otherwise, exit should translate
-
-obj into an appropriate exit value for the operating system, if possible.
-
-The exit procedure must not signal an exception or return to its continuation.
+The @code{exit} procedure
+must not signal an exception or return to its continuation.
Note: Because of the requirement to run handlers, this procedure is not just the
operating system's exit procedure.
+
@end deffn
@deffn {process-context library procedure} emergency-exit
@deffnx {process-context library procedure} emergency-exit obj
-Terminates the program without running any outstanding dynamic-wind
-
-after procedures and communicates an exit value to the operating system in the same
-manner as exit.
+Terminates the program without running any
+outstanding dynamic-wind @var{after} procedures
+and communicates an exit value to the operating system
+in the same manner as @code{exit}.
-Note: The emergency-exit procedure corresponds to the _exit procedure in Windows
-and Posix.
@end deffn
@deffn {process-context library procedure} get-environment-variable name
-Many operating systems provide each running process with an environment consisting of
-environment variables. (This environment is not to be confused with the Scheme
-environments that can be passed to eval: see section 6.12.) Both the name and value of
-an environment variable are strings. The procedure get-environment-variable returns
-the value of the environment variable
-
-name, or #f if the named environment variable is not found. It may use locale information
-to encode the name and decode the value of the environment variable. It is an error if
-get-environment-variable can't decode the value. It is also an error to mutate the
-resulting string.
+Many operating systems provide each running process with an
+@dfn{environment} consisting of @dfn{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.
+The procedure @code{get-environment-variable} returns the value
+of the environment variable @var{name},
+or @code{#f} if the named
+environment variable is not found. It may
+use locale information to encode the name and decode the value
+of the environment variable. It is an error if
+@code{get-environment-variable} can't decode the value.
+It is also an error to mutate the resulting string.
@lisp
(get-environment-variable "PATH")
@@ -138,19 +136,23 @@ As of 2018, a TAI-UTC offset table can be found at [40].
@deffn {time library procedure} current-jiffy
-Returns the number of 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 jiffies-per-second procedure. The starting
-epoch is guaranteed to be constant during a run of the program, but may vary between
-runs.
-
-Rationale: Jiffies are allowed to be implementation-dependent so that current-jiffy
-can execute with minimum overhead. It should be very likely that a compactly
-represented integer will suffice as the returned value. Any particular jiffy size will be
-inappropriate for some implementations: a microsecond is too long for a very fast
-machine, while a much smaller unit would force many implementations to return
-integers which have to be allocated for most calls, rendering current-jiffy less
-useful for accurate timing measurements.
+Returns the number of @dfn{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 epoch is guaranteed to be
+constant during a run of the program, but may vary between runs.
+
+@rationale{}
+
+Jiffies are allowed to be implementation-dependent so that
+@code{current-jiffy} can execute with minimum overhead. It
+should be very likely that a compactly represented integer will suffice
+as the returned value. Any particular jiffy size will be inappropriate
+for some implementations: a microsecond is too long for a very fast
+machine, while a much smaller unit would force many implementations to
+return integers which have to be allocated for most calls, rendering
+@code{current-jiffy} less useful for accurate timing measurements.
+
@end deffn
@deffn {time library procedure} jiffies-per-second
@@ -171,7 +173,7 @@ an implementation-specified constant.
@deffn procedure features
Returns a list of the feature identifiers which cond-expand treats as true. It is an error to
-modify this list. Here is an example of what features might return:
+modify this list. Here is an example of what @code{features} might return:
@lisp
(features) @result{}
diff --git a/doc/r7rs-small/r7rs-texinfo-macros.texinfo b/doc/r7rs-small/r7rs-texinfo-macros.texinfo
@@ -134,3 +134,9 @@ R@sup{6}RS
@math{\\varsigma}
@end macro
@end iftex
+
+@c Produce a header for a Rationale section. We may want to adjust
+@c the heading level of this.
+@macro rationale
+@subheading Rationale:
+@end macro
