Document text modules.

6 files changed, 213 insertions, 0 deletions

diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi
index e8464edf..d9cad0af 100644
--- a/doc/ref/calp.texi
+++ b/doc/ref/calp.texi
@@ -65,6 +65,7 @@ text @footnote{Improvements welcome}
 @c @end menu
 
 @include guile.texi
+@include text.texi
 
 @node Index
 @unnumbered Index
diff --git a/doc/ref/text.texi b/doc/ref/text.texi
new file mode 100644
index 00000000..ec7074ae
--- /dev/null
+++ b/doc/ref/text.texi
@@ -0,0 +1,9 @@
+@node Text Procedures
+@chapter Text Procedures
+
+Various utilities for formatting text in various ways.
+
+@include text/utilities.texi
+@include text/flow.texi
+@include text/markup.texi
+@include text/numbers.texi
diff --git a/doc/ref/text/flow.texi b/doc/ref/text/flow.texi
new file mode 100644
index 00000000..0613d78f
--- /dev/null
+++ b/doc/ref/text/flow.texi
@@ -0,0 +1,23 @@
+@node Reflowing Text
+@section Reflowing Text
+
+@code{(text flow)}
+
+@defun flow-text str [width=70]
+Reflow and justify @var{str} to @var{width} columns.
+
+Each newline is as a newline, so each paragraph needs to be on its own
+line. The output will look something like the following:
+
+@example
+muck calendar's Hobart's Kendall's  lighthouse wooziest  knot's swanky
+Ghats's   witless   heftiness's   hailstorm's  ladybugs   abridgment's
+whispered  Willemstad's  ludo  stewardess  photostatic  potshot ninety
+perfected  Potsdam  asinine  swings   Valiums  Adrenalin's   contralto
+emigration's    besmears    finessing    resorption's   literariness's
+verbalize   maximums   Bjork   diverticulitis    cascaras   implacably
+overeager deepen funeral's  Edwardian Calvinistic  seawards microlight
+palatial Shaun fungus's unmounted armrests Culbertson's lineage
+@end example
+
+@end defun
diff --git a/doc/ref/text/markup.texi b/doc/ref/text/markup.texi
new file mode 100644
index 00000000..bec33557
--- /dev/null
+++ b/doc/ref/text/markup.texi
@@ -0,0 +1,71 @@
+@node Markup
+@section Markup
+
+@defun sxml->ansi-text tree
+Takes an HTML-like document in SXML format, and produces a formatted
+string with embedded ANSI-escapes suitable to print to a terminal.
+
+Supported tags are:
+
+@table @samp
+@item group
+@item block
+Groups elements, concatenating their format. Mainly here for helper
+procedres and the like. Also used for the root node.
+
+@item header
+Centers and bolds its content. Attributes will be sent along to the
+inner @code{<center/>} tag.
+
+@item center
+Center its contents on the line. The output is undefined if the body
+serializes to a multiline string.
+
+@item p
+A text paragraph. Justifies the content inside.
+
+Ends with a double newline, unless the parameter @code{inline} is set.
+
+@item b
+Make content bold.
+
+@item i
+@item em
+Make content italics.
+
+@item code
+Format content as code.
+
+(currently does nothing since we only support output to terminal)
+
+@item blockquote
+Justifies content, and sets it slightly indented.
+
+@item ws
+Forces horizontal whitespace. Use the parameter @code{minwidth} to
+specify how many spaces should be inserted.
+
+@item br
+Forces a linebreak.
+
+@item hr
+Generates a horrizontal line.
+
+@item dl
+Declares a description list.
+
+@item dt
+A key in a description list, only valid inside @code{dl}.
+
+@item dd
+A value of a description list, only valid inside @code{dl}.
+
+@item scheme
+Set content as Scheme code. The content will be passed through Guile's
+pretty-print.
+@end table
+
+
+Almost all of the block environments accept the attribute @var{width},
+which specifies the desired output width.
+@end defun
diff --git a/doc/ref/text/numbers.texi b/doc/ref/text/numbers.texi
new file mode 100644
index 00000000..fce5c9fa
--- /dev/null
+++ b/doc/ref/text/numbers.texi
@@ -0,0 +1,42 @@
+@node Spelled out Numbers
+@section Spelled out Numbers
+
+Numbers writtens as word. The usual interface is through
+@code{(text numbers)} which uses the current locale for translations.
+However, @code{(text numbers @var{<lang-code>})} can also be imported
+directly with the exact same interface. Language codes should be two
+letter ISO language codes (e.g. ``se'', ``en'', ...)
+
+When resolving the current language, first the environment variable
+@env{LC_MESSAGES} is checked, followed by @env{LC_ALL}, and finaly
+falls back to ``en''.
+
+English is also chosen if no implementation for the chosen language
+exists.
+
+Note that English uses the term cardinal and ordinal @emph{numeral},
+rather than @emph{number}.
+
+
+@defun number->string-ordinal n [language=(resolve-language)]
+Convert a string into an ordinal number. These are the ``ranking''
+numbers, e.g. ``first'', ``second'', ...
+@end defun
+
+@defun number->string-cardinal n [language=(resolve-language)]
+Convert a string into a cardinal number. These are the ``ordinary''
+counting numbers, e.g. ``one'', ``two'', ...
+@end defun
+
+@defun resolve-language
+Return the current language.
+@end defun
+
+@defun each-string count args ...
+Return a (locale dependant) string indicating which elements of a set
+are targeted, such as ``each'', ``every other'', ...
+
+@var{args} is reserved for locale specific extensions, such as in
+Swedish where both ``var tredje'' and ``vart tredje'' (meaning ``every
+third'') exists, and is chosen depending on the following noun.
+@end defun
diff --git a/doc/ref/text/utilities.texi b/doc/ref/text/utilities.texi
new file mode 100644
index 00000000..175b8f60
--- /dev/null
+++ b/doc/ref/text/utilities.texi
@@ -0,0 +1,67 @@
+@node Text Utilities
+@section Text Utilities
+
+@code{(text util)}
+
+Various general utilities for basic text manipulation.
+
+Some of these procedures claim to use ``true'' text width. These
+calculate text width in unicode code-points, but with (some) ANSI
+escape sequences omitted. In a perfect world, these would show exactly
+how many characters wide the outputed string is when printed to a
+(sufficiently advanced) terminal.
+
+@defun words str
+Split string on spaces. No space merging is done.
+@end defun
+
+@defun unwords list
+Join list with spaces.
+@end defun
+
+@defun lines str
+Split string on newlines.
+@end defun
+
+@defun unlines list
+Join string with newlines.
+@end defun
+
+@defun true-string-length word
+@anchor{true-string-length}
+Alternative string-length whith counts ANSI escapes as 0-length.
+@end defun
+
+@defun true-string-pad str len [chr=#\space]
+Works like the regular @code{string-pad}, but uses the ``true''
+length. @ref{true-string-length}
+@end defun
+
+@defun trim-to-width str len
+Forces @var{str} to be exactly @var{len} characters long.
+
+This is done by either right padding the string, or by drop
+characters from the right until the string is one shorter than length,
+then an ellipsis character is added.
+
+@example
+(trim-to-width "Hello, World!" 6)
+⇒ "Hello…"
+
+(trim-to-width "Hello" 10)
+⇒ "Hello     "
+@end example
+@end defun
+
+@defun add-enumeration-punctuation list [final-delim=``&'']
+Intersperse punctuation into @var{list}, preparing it to be formatted
+as a inline list in the body of the document. The sequence ``, ''
+inserted between each element, except the last which will use
+@var{final-delim}. An oxford comma is not used.
+
+@example
+(string-concatenate (add-enumeration-punctuation
+                        '("Pasta" "Hamburgers" "Hotdog and Mash")))
+⇒ "Pasta, Hamburgers & Hotdog and Mash"
+@end example
+@end defun