commit 9727a03590d31fd2e6e2a426ece3f44d9eb28dbf
parent a05b2aeed721a75c852923c8db1430b9e9cb442e
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Sun, 4 Feb 2024 15:54:32 -0500
Strings: Texify.
Diffstat:
2 files changed, 172 insertions(+), 158 deletions(-)
diff --git a/doc/r7rs-small/procedures/strings.texinfo b/doc/r7rs-small/procedures/strings.texinfo
@@ -3,10 +3,13 @@
Strings are sequences of characters. Strings are written as sequences of characters
enclosed within quotation marks (@code{"}). Within a string literal, various escape
-sequencesrepresent characters other than themselves. Escape sequences always start
+sequences represent characters other than themselves. Escape sequences always start
with a backslash (@code{\}):
-@itemize
+@c We can't use a two-column table here because user-defined macros
+@c are apparently "unreliable" in tables.
+@itemize @bullet
+
@item
@code{\a} : alarm, U+0007
@@ -38,108 +41,101 @@ with a backslash (@code{\}):
@item
@code{\x}@svar{hex scalar value}@code{;} : specified character
(note the terminating semi-colon).
+
@end itemize
The result is unspecified if any other character in a string occurs after a backslash.
Except for a line ending, any character outside of an escape sequence stands for itself in
-the string literal. A line ending which is preceded by \@svar{intraline whitespace} expands to
+the string literal. A line ending which is preceded by @code{\}@svar{intraline whitespace} expands to
nothing (along with any trailing intraline whitespace), and can be used to indent strings
-for improved legibility. Any other line ending has the same effect as inserting a \n
+for improved legibility. Any other line ending has the same effect as inserting a @code{\n}
character into the string.
Examples:
+@example
"The word \"recursion\" has many meanings."
"Another example:\ntwo lines of text"
"Here's text \
containing just one line"
-"\x03B1; is named GREEK SMALL LETTER ALPHA." The length of a string is the number of
+"\x03B1; is named GREEK SMALL LETTER ALPHA."
+@end example
+
+The @dfn{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 valid indexes of a string are the exact non-negative
+when the string is created. The @dfn{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.
Some of the procedures that operate on strings ignore the difference between upper
-and lower case. The names of the versions that ignore case end with ``-ci'' (for ``case
+and lower case. The names of the versions that ignore case end with @samp{-ci} (for ``case
insensitive'').
-Implementations may forbid certain characters from appearing in strings. However, with
-the exception of #\null, ASCII characters must not be forbidden. For example, an
-implementation might support the entire Unicode repertoire, but only allow characters
-U+0001 to U+00FF (the Latin-1 repertoire without #\null) in strings.
-
-It is an error to pass such a forbidden character to make-string, string, string-set!, or
-string-fill!, as part of the list passed to list->string, or as part of the vector passed to
-vector->string (see section 6.8), or in UTF-8 encoded form within a bytevector passed to
-utf8->string (see section 6.9). It is also an error for a procedure passed to string-map
-(see section 6.10) to return a forbidden character, or for read-string (see section 6.13.2)
+Implementations may forbid certain characters from appearing in strings.
+However, with the exception of @code{#\null}, ASCII characters must
+not be forbidden.
+For example, an implementation might support the entire Unicode repertoire,
+but only allow characters U+0001 to U+00FF (the Latin-1 repertoire
+without @code{#\null}) in strings.
+
+It is an error to pass such a forbidden character to
+@code{make-string}, @code{string}, @code{string-set!}, or @code{string-fill!},
+as part of the list passed to @code{list->string},
+or as part of the vector passed to @code{vector->string}
+(see @ref{Vectors}),
+or in UTF-8 encoded form within a bytevector passed to
+@code{utf8->string} (see @ref{Bytevectors}).
+It is also an error for a procedure passed to @code{string-map}
+(see @ref{Control features}) to return a forbidden character,
+or for @code{read-string} (see @ref{Input})
to attempt to read one.
@deffn procedure string? obj
-Returns #t if
+Returns @code{#t} if @var{obj} is a string, otherwise returns @code{#f}.
-obj is a string, otherwise returns #f.
@end deffn
@deffn procedure make-string k
@deffnx procedure make-string k char
-The make-string procedure returns a newly allocated string of length
-
-k. If
-
-char is given, then all the characters of the string are initialized to
+The @code{make-string} procedure returns a newly allocated string of
+length @var{k}. If @var{char} is given, then all the characters of the string
+are initialized to @var{char}, otherwise the contents of the
+string are unspecified.
-char, otherwise the contents of the string are unspecified.
@end deffn
-@deffn procedure string char @dots{}
+@deffn procedure string char@dots{}
+
+Returns a newly allocated string composed of the arguments. It is analogous to @code{list}.
-Returns a newly allocated string composed of the arguments. It is analogous to list.
@end deffn
@deffn procedure string-length string
-Returns the number of characters in the given
+Returns the number of characters in the given @var{string}.
-string.
@end deffn
@deffn procedure string-ref string k
+It is an error if @var{k} is not a valid index of @var{string}.
-It is an error if
-
-k is not a valid index of
-
-string.
-
-The string-ref procedure returns character
-
-k of
-
-string using zero-origin indexing.
+The @code{string-ref} procedure returns character @var{k} of @var{string}
+using zero-origin indexing.
There is no requirement for this procedure to execute in constant time.
+
@end deffn
@deffn procedure string-set! string k char
-It is an error if
-
-k is not a valid index of
-
-string.
-
-The string-set! procedure stores
-
-char in element
-
-k of
+It is an error if @var{k} is not a valid index of @var{string}.
-string. There is no requirement for this procedure to execute in constant time.
+The @code{string-set!} procedure stores @var{char} in element @var{k} of @var{string}.
+There is no requirement for this procedure to execute in constant time.
@lisp
(define (f) (make-string 3 #\*))
@@ -152,83 +148,97 @@ string. There is no requirement for this procedure to execute in constant time.
@end lisp
@end deffn
-@deffn procedure string=? string1 string2 string3 @dots{}
+@deffn procedure string=? @vari{string} @varii{string} @variii{string}@dots{}
+
+Returns @code{#t} if all the @var{string}s are the same length and contain
+exactly the same characters in the same positions, otherwise returns
+@code{#f}.
-Returns #t if all the strings are the same length and contain exactly the same characters
-in the same positions, otherwise returns #f.
@end deffn
-@deffn {char library procedure} string-ci=? string1 string2 string3 @dots{}
+@deffn {char library procedure} string-ci=? @vari{string} @varii{string} @variii{string}@dots{}
+
+Returns @code{#t} if, after case-folding, all the @var{string}s are the same
+length and contain the same characters in the same positions, otherwise
+returns @code{#f}. Specifically, these procedures behave as if
+@code{string-foldcase} were applied to their arguments before comparing them.
-Returns #t if, after case-folding, all the strings are the same length and contain the same
-characters in the same positions, otherwise returns #f. Specifically, these procedures
-behave as if string-foldcase were applied to their arguments before comparing them.
@end deffn
-@deffn procedure string<? string1 string2 string3@dots{}
-@deffnx {char library procedure} string-ci<? string1 string2 string3@dots{}
-@deffnx procedure string>? string1 string2 string3@dots{}
-@deffnx {char library procedure} string-ci>? string1 string2 string3@dots{}
-@deffnx procedure string<=? string1 string2 string3@dots{}
-@deffnx {char library procedure} string-ci<=? string1 string2 string3@dots{}
-@deffnx procedure string>=? string1 string2 string3@dots{}
-@deffnx {char library procedure} string-ci>=? string1 string2 string3@dots{}
+@deffn procedure string<? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx {char library procedure} string-ci<? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx procedure string>? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx {char library procedure} string-ci>? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx procedure string<=? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx {char library procedure} string-ci<=? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx procedure string>=? @vari{string} @varii{string} @variii{string}@dots{}
+@deffnx {char library procedure} string-ci>=? @vari{string} @varii{string} @variii{string}@dots{}
-These procedures return #t if their arguments are (respectively): monotonically
+These procedures return @code{#t} if their arguments are (respectively): monotonically
increasing, monotonically decreasing, monotonically non-decreasing, or monotonically
non-increasing.
These predicates are required to be transitive.
-These procedures compare strings in an implementation-defined way. One approach is
-to make them the lexicographic extensions to strings of the corresponding orderings on
-characters. In that case, string<? would be the lexicographic ordering on strings induced
-by the ordering char<? on characters, and if the two strings differ in length but are the
-same up to the length of the shorter string, the shorter string would be considered to be
-lexicographically less than the longer string. However, it is also permitted to use the
-natural ordering imposed by the implementation's internal representation of strings, or
-a more complex locale-specific ordering.
-
-In all cases, a pair of strings must satisfy exactly one of string<?, string=?, and
-string>?,
-and must satisfy string<=? if and only if they do not satisfy string>? and string>=? if and
-only if they do not satisfy string<?.
-
-The ``-ci'' procedures behave as if they applied string-foldcase to their arguments before
-invoking the corresponding procedures without ``-ci''.
+These procedures compare strings in an implementation-defined way.
+One approach is to make them the lexicographic extensions to strings of
+the corresponding orderings on characters. In that case, @code{string<?}
+would be the lexicographic ordering on strings induced by the ordering
+@code{char<?} on characters, and if the two strings differ in length but
+are the same up to the length of the shorter string, the shorter string
+would be considered to be lexicographically less than the longer string.
+However, it is also permitted to use the natural ordering imposed by the
+implementation's internal representation of strings, or a more complex locale-specific
+ordering.
+
+In all cases, a pair of strings must satisfy exactly one of
+@code{string<?}, @code{string=?}, and @code{string>?}, and must satisfy
+@code{string<=?} if and only if they do not satisfy @code{string>?} and
+@code{string>=?} if and only if they do not satisfy @code{string<?}.
+
+The @samp{-ci} procedures behave as if they applied
+@code{string-foldcase} to their arguments before invoking the corresponding
+procedures without @samp{-ci}.
+
@end deffn
@deffn {char library procedure} string-upcase string
@deffnx {char library procedure} string-downcase string
@deffnx {char library procedure} string-foldcase string
-These procedures apply the Unicode full string uppercasing, lowercasing, and
-case-folding algorithms to their arguments and return the result. In certain cases, the
-result differs in length from the argument. If the result is equal to the argument in the
-sense of string=?, the argument may be returned. Note that language-sensitive
-mappings and foldings are not used. The Unicode Standard prescribes special
-treatment of the Greek letter Σ, whose normal lower-case form is σ but which becomes ς
-at the end of a word. See UAX #44 [11] (part of the Unicode Standard) for details.
-However, implementations of string-downcase are not required to provide this
-behavior, and may choose to change Σ to σ in all cases.
+These procedures apply the Unicode full string uppercasing, lowercasing,
+and case-folding algorithms to their arguments and return the result.
+In certain cases, the result differs in length from the argument.
+If the result is equal to the argument in the sense of @code{string=?},
+the argument may be returned.
+Note that language-sensitive mappings and foldings are not used.
+
+The Unicode Standard prescribes special treatment of the Greek letter
+@greekcapitalsigma{}, whose normal lower-case form is @greeksmallsigma{} but which becomes
+@greekfinalsigma at the end of a word. See UAX #29 (part of
+the Unicode Standard) for details. However, implementations of
+@code{string-downcase} are not required to provide this behavior, and may
+choose to change @greekcapitalsigma{} to @greeksmallsigma{} in all cases.
+@c cite{uax29}
+
@end deffn
@deffn procedure substring string start end
-The substring procedure returns a newly allocated string formed from the characters of
-
-string beginning with index
+The @code{substring} procedure returns a newly allocated string formed from the characters of
+@var{string} beginning with index @var{start} and ending with index
+@var{end}.
+This is equivalent to calling @code{string-copy} with the same arguments,
+but is provided for backward compatibility and
+stylistic flexibility.
-start and ending with index
-
-end. This is equivalent to calling string-copy with the same arguments, but is provided
-for backward compatibility and stylistic flexibility.
@end deffn
-@deffn procedure string-append string @dots{}
+@deffn procedure string-append string@dots{}
Returns a newly allocated string whose characters are the concatenation of the
-characters in the given strings.
+characters in the given @var{string}s.
+
@end deffn
@deffn procedure string->list string
@@ -236,67 +246,44 @@ characters in the given strings.
@deffnx procedure string->list string start end
@deffnx procedure list->string list
-It is an error if any element of
-
-list is not a character.
-
-The string->list procedure returns a newly allocated list of the characters of
-
-string between
-
-start and
+It is an error if any element of @var{list} is not a character.
-end. list->string returns a newly allocated string formed from the elements in the list
+The @code{string->list} procedure returns a newly allocated list of the
+characters of @var{string} between @var{start} and @var{end}.
+@code{list->string}
+returns a newly allocated string formed from the elements in the list
+@var{list}.
+In both procedures, order is preserved.
+@code{string->list}
+and @code{list->string} are
+inverses so far as @code{equal?} is concerned.
-list. In both procedures, order is preserved. string->list and list->string are inverses so
-far as equal? is concerned.
@end deffn
@deffn procedure string-copy string
@deffnx procedure string-copy string start
@deffnx procedure string-copy string start end
-Returns a newly allocated copy of the part of the given
+Returns a newly allocated copy of the part of the given @var{string}
+between @var{start} and @var{end}.
-string between
-
-start and
-
-end.
@end deffn
@deffn procedure string-copy! to at from
@deffnx procedure string-copy! to at from start
@deffnx procedure string-copy! to at from start end
-It is an error if
-
-at is less than zero or greater than the length of
-
-to. It is also an error if (- (string-length
-
-to)
-
-at) is less than (-
+It is an error if @var{at} is less than zero or greater than the length of @var{to}.
+It is also an error if @code{(- (string-length }@var{to}@code{) }@var{at}@code{)}
+is less than @code{(- }@var{end} @var{start}@code{)}.
-end
-
-start).
-
-Copies the characters of string
-
-from between
-
-start and
-
-end to string
-
-to, starting at
-
-at. The order in which characters are copied is unspecified, except that if the source and
-destination overlap, copying takes place as if the source is first copied into a temporary
-string and then into the destination. This can be achieved without allocating storage by
-making sure to copy in the correct direction in such circumstances.
+Copies the characters of string @var{from} between @var{start} and @var{end}
+to string @var{to}, starting at @var{at}. The order in which characters are
+copied is unspecified, except that if the source and destination overlap,
+copying takes place as if the source is first copied into a temporary
+string and then into the destination. This can be achieved without
+allocating storage by making sure to copy in the correct direction in
+such circumstances.
@lisp
(define a "12345")
@@ -304,23 +291,17 @@ making sure to copy in the correct direction in such circumstances.
(string-copy! b 1 a 0 2)
b @result{} "a12de"
@end lisp
+
@end deffn
@deffn procedure string-fill! string fill
@deffnx procedure string-fill! string fill start
@deffnx procedure string-fill! string fill start end
-It is an error if
-
-fill is not a character.
-
-The string-fill! procedure stores
-
-fill in the elements of
-
-string between
+It is an error if @var{fill} is not a character.
-start and
+The @code{string-fill!} procedure stores @var{fill}
+in the elements of @var{string}
+between @var{start} and @var{end}.
-end.
@end deffn
diff --git a/doc/r7rs-small/r7rs-texinfo-macros.texinfo b/doc/r7rs-small/r7rs-texinfo-macros.texinfo
@@ -101,3 +101,36 @@ R@sup{6}RS
@math{\\theta}
@end macro
@end iftex
+
+@c Insert a capital sigma.
+@macro greekcapitalsigma
+@U{03a3}
+@end macro
+
+@iftex
+@unmacro greekcapitalsigma
+@math{\\Sigma}
+@end macro
+@end iftex
+
+@c Insert a lower-case sigma.
+@macro greeksmallsigma
+@U{03c3}
+@end macro
+
+@iftex
+@unmacro greeksmallsigma
+@math{\\igma}
+@end macro
+@end iftex
+
+@c Insert a lower-case final sigma.
+@macro greekfinalsigma
+@U{03c2}
+@end macro
+
+@iftex
+@unmacro greekfinalsigma
+@math{\\varsigma}
+@end macro
+@end iftex
