Document text modules.

8 files changed, 221 insertions, 1 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
diff --git a/module/text/markup.scm b/module/text/markup.scm
index a7a905df..62f93b0c 100644
--- a/module/text/markup.scm
+++ b/module/text/markup.scm
@@ -65,6 +65,7 @@
                    (map (lambda (line) (sxml->ansi-text `(group (ws (@ (minwidth 4))) ,line (br))))
                         (flow-text
                          (string-concatenate (map sxml->ansi-text body))
+                         ;; TODO shouldn't this use (- width 4)?
                          width: 66)))]
     [(ws) (make-string  (aif (assoc-ref args 'minwidth)
                              (car it) 1)
diff --git a/module/text/numbers.scm b/module/text/numbers.scm
index c45016bc..7909573b 100644
--- a/module/text/numbers.scm
+++ b/module/text/numbers.scm
@@ -2,10 +2,16 @@
   :use-module (srfi srfi-88)
   :export (number->string-cardinal
            number->string-ordinal
+           resolve-language
            each-string))
 
 (define (get mod-symb proc-symb)
-  (module-ref (resolve-interface `(text numbers ,mod-symb))
+  (module-ref (catch 'misc-error
+                (lambda () (resolve-interface `(text numbers ,mod-symb)))
+                (lambda (err proc fmt args data)
+                  ;; Possibly check if the err message starts with
+                  ;; "no code for module"
+                  (resolve-interface '(text numbers en))))
               proc-symb))
 
 ;; "sv_SE.UTF-8"