From 23994d4f4c59d32a10b952d1419a4e92152394fe Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Sun, 11 Sep 2022 13:41:20 -0700
Subject: [PATCH 1/2] dynamically wrap helpdb long help text (default 80)

---
 conf.py                |  6 +++++-
 docs/Lua API.rst       |  6 ++++--
 library/lua/helpdb.lua | 38 +++++++++++++++++++++++++++++++++++---
 3 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/conf.py b/conf.py
index 924da1577..68d11f0f9 100644
--- a/conf.py
+++ b/conf.py
@@ -347,6 +347,10 @@ latex_toplevel_sectioning = 'part'
 
 from sphinx.writers import text
 
-text.MAXWIDTH = 52
+# this value is arbitrary. it just needs to be bigger than the number of
+# characters in the longest paragraph in the DFHack docs
+text.MAXWIDTH = 1000000000
 
+# this is the order that section headers will use the characters for underlines
+# they are in the order of (subjective) text-mode readability
 text_sectionchars = '=-~`+"*'
diff --git a/docs/Lua API.rst b/docs/Lua API.rst
index 71094414f..cc80dd92d 100644
--- a/docs/Lua API.rst	
+++ b/docs/Lua API.rst	
@@ -3114,9 +3114,11 @@ Each entry has several properties associated with it:
 
   Returns the short (~54 character) description for the given entry.
 
-* ``helpdb.get_entry_long_help(entry)``
+* ``helpdb.get_entry_long_help(entry[, width])``
 
-  Returns the full help text for the given entry.
+  Returns the full help text for the given entry. If ``width`` is specified, the
+  text will be wrapped at that width, preserving block indents. The wrap width
+  defaults to 80.
 
 * ``helpdb.get_entry_tags(entry)``
 
diff --git a/library/lua/helpdb.lua b/library/lua/helpdb.lua
index 2f41bbb2c..805b56db9 100644
--- a/library/lua/helpdb.lua
+++ b/library/lua/helpdb.lua
@@ -432,6 +432,37 @@ local function ensure_db()
     index_tags()
 end
 
+local function parse_blocks(text)
+    local blocks = {}
+    for line in text:gmatch('[^\n]*') do
+        local _,indent = line:find('^ *')
+        table.insert(blocks, {line=line:trim(), indent=indent})
+    end
+    return blocks
+end
+
+local function format_block(line, indent, width)
+    local wrapped = line:wrap(width - indent)
+    if indent == 0 then return wrapped end
+    local padding = (' '):rep(indent)
+    local indented_lines = {}
+    for line in wrapped:gmatch('[^\n]*') do
+        table.insert(indented_lines, padding .. line)
+    end
+    return table.concat(indented_lines, '\n')
+end
+
+-- wraps the unwrapped source help at the specified width, preserving block
+-- indents
+local function rewrap(text, width)
+    local formatted_blocks = {}
+    for _,block in ipairs(parse_blocks(text)) do
+        table.insert(formatted_blocks,
+                     format_block(block.line, block.indent, width))
+    end
+    return table.concat(formatted_blocks, '\n')
+end
+
 ---------------------------------------------------------------------------
 -- get API
 ---------------------------------------------------------------------------
@@ -482,9 +513,10 @@ function get_entry_short_help(entry)
     return get_db_property(entry, 'short_help')
 end
 
--- returns the full help documentation associated with the entry
-function get_entry_long_help(entry)
-    return get_db_property(entry, 'long_help')
+-- returns the full help documentation associated with the entry, optionally
+-- wrapped to the specified width (80 if not specified).
+function get_entry_long_help(entry, width)
+    return rewrap(get_db_property(entry, 'long_help'), width or 80)
 end
 
 -- returns the set of tags associated with the entry

From 49798f6412e6f3e1181efe7ad5942365ced9aaad Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Sun, 11 Sep 2022 13:51:57 -0700
Subject: [PATCH 2/2] add unit test for wrapping

---
 test/library/helpdb.lua | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/test/library/helpdb.lua b/test/library/helpdb.lua
index 6c2ef2e9b..96dcbbce0 100644
--- a/test/library/helpdb.lua
+++ b/test/library/helpdb.lua
@@ -398,8 +398,25 @@ function test.get_entry_short_help()
 end
 
 function test.get_entry_long_help()
+    local expected = [[
+basic
+*****
+
+**Tags:** map
+
+**Command:**
+"basic"
+
+Documented
+basic.
+
+Documented
+full help.
+    ]]
+    expect.eq(expected, h.get_entry_long_help('basic', 13))
+
     -- long help for plugins/commands that have doc files should match the
-    -- contents of those files exactly
+    -- contents of those files exactly (test data is already wrapped)
     expect.eq(files['hack/docs/docs/tools/hascommands.txt'],
         h.get_entry_long_help('hascommands'))
     expect.eq(files['hack/docs/docs/tools/hascommands.txt'],