From 5e6b5ce6b9cd03d92d8e1b23bd28e7d617a011d0 Mon Sep 17 00:00:00 2001
From: Ricardo Wurmus <rekado@elephly.net>
Date: Sun, 3 Jan 2021 15:57:07 +0100
Subject: Document text.

---
 doc/images/text.svg.scm   |  3 +++
 doc/picture-language.texi | 23 +++++++++++++++++++++--
 2 files changed, 24 insertions(+), 2 deletions(-)
 create mode 100644 doc/images/text.svg.scm

(limited to 'doc')

diff --git a/doc/images/text.svg.scm b/doc/images/text.svg.scm
new file mode 100644
index 0000000..93b1428
--- /dev/null
+++ b/doc/images/text.svg.scm
@@ -0,0 +1,3 @@
+(hc-append (text "hello" #:color "blue" #:font-family "serif")
+           (text "bye" #:color "orange")
+           (text "! " #:color "lime"))
diff --git a/doc/picture-language.texi b/doc/picture-language.texi
index c3005da..448203c 100644
--- a/doc/picture-language.texi
+++ b/doc/picture-language.texi
@@ -403,8 +403,27 @@ drawn by the @code{rectangle} procedure, except that it does not have
 an outline and is filled with the provided @var{COLOR}.
 @end deffn
 
-There are more primitive shapes that still need to be documented:
-@code{text}.
+
+@cindex text, simple shape
+@deffn {Scheme Procedure} text @
+  @var{TXT} @
+  [#:color @var{"black"} #:font-family @var{"sans-serif"} #:font-size @var{32} @
+  #:font-style @var{"normal"} #:font-weight @var{"normal"}]
+
+This procedure renders the text @var{TXT}.  The height of the text is
+always a full line height, which depends on the selected
+@var{FONT-FAMILY} and is generally larger than the provided
+@var{FONT-SIZE}.  The keys @var{FONT-STYLE} (a string),
+@var{FONT-WEIGHT} (a string), and @var{COLOR} (also a string) are
+also accepted.
+@end deffn
+
+@cindex text, example
+Here are a few snippets of text, combined horizontally (see below).
+@example
+@verbatiminclude images/text.svg.scm
+@image{images/text.svg.scm,,,A few snippets of text.}
+@end example
 
 @c *********************************************************************
 @node Modifiers
-- 
cgit v1.2.3