From dfa301d6c0659e437ae66d72787a23b4393b33f2 Mon Sep 17 00:00:00 2001
From: Jaro <jaro@argonaut-constellation.org>
Date: Thu, 11 May 2023 16:10:31 +0200
Subject: [PATCH] Expose piecewise paragraph construction.

---
 lib/Data/Text/ParagraphLayout/Rich.hs         |  1 +
 .../Internal/Rich/Paragraph.hs                | 22 +++++++++++++++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/lib/Data/Text/ParagraphLayout/Rich.hs b/lib/Data/Text/ParagraphLayout/Rich.hs
index 5a3ca15..45236ad 100644
--- a/lib/Data/Text/ParagraphLayout/Rich.hs
+++ b/lib/Data/Text/ParagraphLayout/Rich.hs
@@ -4,6 +4,7 @@
 module Data.Text.ParagraphLayout.Rich
     -- * Input paragraph
     ( Paragraph (Paragraph)
+    , constructParagraph
     , BoxSpacing (BoxSpacingLeftRight)
     , LineHeight (Absolute, Normal)
     , ParagraphOptions
diff --git a/src/Data/Text/ParagraphLayout/Internal/Rich/Paragraph.hs b/src/Data/Text/ParagraphLayout/Internal/Rich/Paragraph.hs
index 6a52ae5..8270b24 100644
--- a/src/Data/Text/ParagraphLayout/Internal/Rich/Paragraph.hs
+++ b/src/Data/Text/ParagraphLayout/Internal/Rich/Paragraph.hs
@@ -24,6 +24,8 @@ import Data.Text.ParagraphLayout.Internal.Tree
 -- You may need to use "Data.Text.Internal" in order to determine the byte
 -- array and the necessary offsets to construct the paragraph without copying
 -- data.
+--
+-- Alternatively, you can use `constructParagraph` with piecewise text.
 data Paragraph d = Paragraph
 
     Array
@@ -49,8 +51,24 @@ data Paragraph d = Paragraph
     ParagraphOptions
     -- ^ Options applying to the paragraph as a whole.
 
-constructParagraph :: Text -> RootNode Text d -> Text -> ParagraphOptions ->
-    Paragraph d
+-- | Construct a `Paragraph` from a tree containing individual pieces of text,
+-- plus an optional prefix and suffix, all encoded as UTF-8.
+--
+-- This internally concatenates all input text into one contiguous byte array.
+--
+-- Alternatively, you can construct a `Paragraph` directly to avoid copying
+-- data.
+constructParagraph
+    :: Text
+    -- ^ Optional prefix. Will not be laid out but may affect the output.
+    -> RootNode Text d
+    -- ^ Parts of the text to be laid out, represented as a tree.
+    -> Text
+    -- ^ Optional suffix. Will not be laid out but may affect the output.
+    -> ParagraphOptions
+    -- ^ Options to apply to the paragraph as a whole.
+    -> Paragraph d
+    -- ^ Constructed paragraph that can be passed to `layoutRich`.
 constructParagraph prefix root suffix = Paragraph arr afterPrefix root'
     where
         (Text arr beforePrefix _) = txt
-- 
2.30.2