From e9d6798e9cf79d54f64171eda6fa9102fffe1f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Mon, 11 Sep 2023 20:45:45 +0200 Subject: Document text modules. --- doc/ref/calp.texi | 1 + doc/ref/text.texi | 9 ++++++ doc/ref/text/flow.texi | 23 +++++++++++++++ doc/ref/text/markup.texi | 71 +++++++++++++++++++++++++++++++++++++++++++++ doc/ref/text/numbers.texi | 42 +++++++++++++++++++++++++++ doc/ref/text/utilities.texi | 67 ++++++++++++++++++++++++++++++++++++++++++ module/text/markup.scm | 1 + module/text/numbers.scm | 8 ++++- 8 files changed, 221 insertions(+), 1 deletion(-) create mode 100644 doc/ref/text.texi create mode 100644 doc/ref/text/flow.texi create mode 100644 doc/ref/text/markup.texi create mode 100644 doc/ref/text/numbers.texi create mode 100644 doc/ref/text/utilities.texi 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{
} 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{})} 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" -- cgit v1.2.3