Merge pull request #2281 from myk002/myk_helpdb_wrap

[helpdb] dynamically wrap long help text, preserving block indents

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 = '=-~`+"*'

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)``
 

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

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'],