commit 4fb71faaaf6cce91f2e7634317992401331475b3
parent ec957027fc89690a1589a1dbcd78fa2cd67fbb96
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 5 Feb 2024 02:00:55 -0500
I & O: Texify, part 2.
Diffstat:
1 file changed, 60 insertions(+), 66 deletions(-)
diff --git a/doc/r7rs-small/procedures/input-and-output.texinfo b/doc/r7rs-small/procedures/input-and-output.texinfo
@@ -412,94 +412,97 @@ If no bytes are available, an end-of-file object is returned.
@node Output
@subsection Output
-If
-
-port is omitted from any output procedure, it defaults to the value returned by
-(current-output-port). It is an error to attempt an output operation on a closed port.
+If @var{port} is omitted from any output procedure, it defaults to the
+value returned by @code{(current-output-port)}.
+It is an error to attempt an output operation on a closed port.
@deffn {write library procedure} write obj
@deffnx {write library procedure} write obj port
-Writes a representation of
-
-obj to the given textual output
-
-port. Strings that appear in the written representation are enclosed in quotation marks,
-and within those strings backslash and quotation mark characters are escaped by
-backslashes. Symbols that contain non-ASCII characters are escaped with vertical lines.
-Character objects are written using the #\ notation.
-
-If
-
-obj contains cycles which would cause an infinite loop using the normal written
-representation, then at least the objects that form part of the cycle must be represented
-using datum labels as described in section 2.4. Datum labels must not be used if there
+Writes a representation of @var{obj} to the given textual output
+@var{port}. Strings
+that appear in the written representation are enclosed in quotation marks, and
+within those strings backslash and quotation mark characters are
+escaped by backslashes. Symbols that contain non-ASCII characters
+are escaped with vertical lines.
+Character objects are written using the @code{#\} notation.
+
+If @var{obj} contains cycles which would cause an infinite loop using
+the normal written representation, then at least the objects that form
+part of the cycle must be represented using datum labels as described
+in @ref{Datum labels}. Datum labels must not be used if there
are no cycles.
-Implementations may support extended syntax to represent record types or other types
-that do not have datum representations.
+Implementations may support extended syntax to represent record types or
+other types that do not have datum representations.
+
+The @code{write} procedure returns an unspecified value.
-The write procedure returns an unspecified value.
@end deffn
@deffn {write library procedure} write-shared obj
@deffnx {write library procedure} write-shared obj port
-The write-shared procedure is the same as write, except that shared structure must be
-represented using datum labels for all pairs and vectors that appear more than once in
-the output.
+The @code{write-shared} procedure is the same as @code{write}, except that
+shared structure must be represented using datum labels for all pairs
+and vectors that appear more than once in the output.
+
@end deffn
@deffn {write library procedure} write-simple obj
@deffnx {write library procedure} write-simple obj port
-The write-simple procedure is the same as write, except that shared structure is never
-represented using datum labels. This can cause write-simple not to terminate if
+The @code{write-simple} procedure is the same as @code{write}, except that shared structure is
+never represented using datum labels. This can cause @code{write-simple} not to
+terminate if @var{obj} contains circular structure.
-obj contains circular structure.
@end deffn
@deffn {write library procedure} display obj
@deffnx {write library procedure} display obj port
-Writes a representation of
+Writes a representation of @var{obj} to the given textual output @var{port}.
+Strings that appear in the written representation are output as if by
+@code{write-string} instead of by @code{write}.
+Symbols are not escaped. Character
+objects appear in the representation as if written by @code{write-char}
+instead of by @code{write}.
-obj to the given textual output
+The @code{display} representation of other objects is unspecified.
+However, @code{display} must not loop forever on
+self-referencing pairs, vectors, or records. Thus if the
+normal @code{write} representation is used, datum labels are needed
+to represent cycles as in @code{write}.
-port. Strings that appear in the written representation are output as if by write-string
-instead of by write. Symbols are not escaped. Character objects appear in the
-representation as if written by write-char instead of by write.
+Implementations may support extended syntax to represent record types or
+other types that do not have datum representations.
-The display representation of other objects is unspecified. However, display must not
-loop forever on self-referencing pairs, vectors, or records. Thus if the normal write
-representation is used, datum labels are needed to represent cycles as in write.
+The @code{display} procedure returns an unspecified value.
-Implementations may support extended syntax to represent record types or other types
-that do not have datum representations.
+@subheading Rationale:
-The display procedure returns an unspecified value.
+The @code{write} procedure is intended
+for producing machine-readable output and @code{display} for producing
+human-readable output.
-Rationale: The write procedure is intended for producing machine-readable output
-and display for producing human-readable output.
@end deffn
@deffn procedure newline
@deffnx procedure newline port
Writes an end of line to textual output
-
-port. Exactly how this is done differs from one operating system to another. Returns an
+@var{port}. Exactly how this is done differs from one operating system to another. Returns an
unspecified value.
+
@end deffn
@deffn procedure write-char char
@deffnx procedure write-char char port
Writes the character
+@var{char} (not an external representation of the character) to the given textual output
+@var{port} and returns an unspecified value.
-char (not an external representation of the character) to the given textual output
-
-port and returns an unspecified value.
@end deffn
@deffn procedure write-string string
@@ -507,25 +510,19 @@ port and returns an unspecified value.
@deffnx procedure write-string string port start
@deffnx procedure write-string string port start end
-Writes the characters of
-
-string from
-
-start to
-
-end in left-to-right order to the textual output
+Writes the characters of @var{string}
+from @var{start} to @var{end}
+in left-to-right order to the
+textual output @var{port}.
-port.
@end deffn
@deffn procedure write-u8 byte
@deffnx procedure write-u8 byte port
-Writes the
+Writes the @var{byte} to
+the given binary output @var{port} and returns an unspecified value.
-byte to the given binary output
-
-port and returns an unspecified value.
@end deffn
@deffn procedure write-bytevector bytevector
@@ -533,20 +530,17 @@ port and returns an unspecified value.
@deffnx procedure write-bytevector bytevector port start
@deffnx procedure write-bytevector bytevector port start end
-Writes the bytes of
-
-bytevector from
-
-start to
+Writes the bytes of @var{bytevector}
+from @var{start} to @var{end}
+in left-to-right order to the
+binary output @var{port}.
-end in left-to-right order to the binary output
-
-port.
@end deffn
@deffn procedure flush-output-port
@deffnx procedure flush-output-port port
-Flushes any buffered output from the buffer of output-port to the underlying file or
+Flushes any buffered output from the buffer of @var{port} to the underlying file or
device and returns an unspecified value.
+
@end deffn
