generalizations: <ref> can also be used w/out Markdown. Options to switch off various parts of the template

html/ldoc.ltp

@@ -22,7 +22,10 @@
 #   if item.type == 'function' then return item.name..' '..item.args
 #   else return item.name end
 #  end
-# local function no_spaces(s) return s:gsub('%s','_') end
+# local function no_spaces(s) return (s:gsub('%s','_')) end
+# local function title(s) return (s:gsub('(%a)(%a*)',function(f,r)
+#     return f:upper()..r
+# end)) end
 
 <div id="main">
 
@@ -33,7 +36,7 @@
 
 <div id="navigation">
 <h1>$(ldoc.project)</h1>
-# if not ldoc.single then
+# if not ldoc.single then -- reference back to project index
 <ul>
   <li><a href="../$(ldoc.output).html">Index</a></li>
 </ul>
@@ -84,11 +87,10 @@
 
 <div id="content">
 
-# if module then
+# if ldoc.body then -- verbatim HTML as contents
-
+    $(ldoc.body)
-<h1>Module <code>$(module.name)</code></h1>
+# elseif module then -- module documentation
-
+<h1>$(title(module.type)) <code>$(module.name)</code></h1>
-
 <p>$(M(module.summary))</p>
 <p>$(M(module.description))</p>
 
@@ -113,11 +115,13 @@
 
 # --- currently works for both Functions and Tables. The params field either contains
 # --- function parameters or table fields.
+# local show_return = not ldoc.no_return_or_parms
+# local show_parms = show_return
 # for kind, items in module.kinds() do
     <h2><a name="$(no_spaces(kind))"></a>$(kind)</h2>
     $(M(module.kinds:get_section_description(kind)))
     <dl class="function">
-#  for item in items() do
+#  for item in items() do ldoc.item = item -- provides context for M()
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
@@ -126,7 +130,7 @@
     $(M(item.summary))
     $(M(item.description))
 
-#  if item.params and #item.params > 0 then
+#  if show_parms and item.params and #item.params > 0 then
     <h3>$(module.kinds:type_of(item).subnames):</h3>
     <ul>
 #   for p in iter(item.params) do
@@ -145,7 +149,7 @@
     </ul>
 #   end -- if usage
 
-#   if item.ret then
+#   if show_return and item.ret then
 #     local li,il = use_li(item.ret)
     <h3>Returns:</h3>
     <ol>
@@ -169,7 +173,7 @@
 </dl>
 # end -- for kinds
 
-# else -- if module
+# else -- if module; project-level contents
 
 # if ldoc.description then
   <p>$(M(ldoc.description))</p>
@@ -192,6 +196,7 @@
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
+<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 0.5</a></i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

ldoc.lua

@@ -552,6 +552,7 @@ if args.filter ~= 'none' then
          item.file = nil
          item.formal_args = nil
          item.tags['return'] = nil
+         item.see = nil
       end
       mod.items.by_name = nil
    end
@@ -612,13 +613,8 @@ if not module_template then
    quit("template not found. Use -l to specify directory containing ldoc.ltp")
 end
 
-if args.format ~= 'plain' then
+-- create the function that renders text (descriptions and summaries)
-   ldoc.markup = markup.create(ldoc, args.format)
+ldoc.markup = markup.create(ldoc, args.format)
-else
-   ldoc.markup = function (txt)
-      return txt
-   end
-end
 
 -- this generates the internal module/function references; strictly speaking,
 -- it should be (and was) part of the template, but inline references in

ldoc/markup.lua

@@ -8,51 +8,71 @@ local utils = require 'pl.utils'
 local quit = utils.quit
 local markup = {}
 
-function markup.create (ldoc, format)
+-- workaround Markdown's need for blank lines around indented blocks
-   local ok,markup = pcall(require,format)
+-- (does mean you have to keep indentation discipline!)
-   if not ok then quit("cannot load formatter: "..format) end
+function markup.insert_markdown_lines (txt)
-   return function (txt)
+   local res, append = {}, table.insert
-      if txt == nil then return '' end
+   local last_indent, start_indent, skip = -1, -1, false
-      -- inline <references> use same lookup as @see
+   for line in stringx.lines(txt) do
-      txt = txt:gsub('<([%w_%.]-)>',function(name)
+      if not line:match '^%s*$' then --ignore blank lines
-         local ref = ldoc.module:process_see_reference(name,ldoc.modules)
+         local indent = #line:match '^%s*'
-         if not ref then print("could not find '"..name.."'"); return '' end
+         if start_indent < 0 then -- initialize indents at start
-         local label = ref.label:gsub('_','\\_')
+            start_indent = indent
-         local res = ('[%s](%s)'):format(label,ldoc.href(ref))
+            last_indent = indent
-         return res
-      end)
-      -- workaround Markdown's need for blank lines around indented blocks
-      -- (does mean you have to keep indentation discipline!)
-      if txt:find '\n' and not ldoc.classic_markdown then -- multiline text
-         local res, append = {}, table.insert
-         local last_indent, start_indent, skip = -1, -1, false
-         for line in stringx.lines(txt) do
-            if not line:match '^%s*$' then --ignore blank lines
-               local indent = #line:match '^%s*'
-               if start_indent < 0 then -- initialize indents at start
-                  start_indent = indent
-                  last_indent = indent
-               end
-               if indent < start_indent then -- end of indented block
-                  append(res,'')
-                  skip = false
-               end
-               if not skip and indent > last_indent then -- start of indent
-                  append(res,'')
-                  skip = true
-                  start_indent = indent
-               end
-               append(res,line)
-               last_indent = indent
-            else
-               append(res,'')
-            end
          end
-         txt =  table.concat(res,'\n')
+         if indent < start_indent then -- end of indented block
+            append(res,'')
+            skip = false
+         end
+         if not skip and indent > last_indent then -- start of indent
+            append(res,'')
+            skip = true
+            start_indent = indent
+         end
+         append(res,line)
+         last_indent = indent
+      else
+         append(res,'')
+      end
+   end
+   return table.concat(res,'\n')
+end
+
+-- inline <references> use same lookup as @see
+function markup.resolve_inline_references (ldoc, txt)
+   return (txt:gsub('<([%w_%.]-)>',function(name)
+      local ref,err = ldoc.module:process_see_reference(name,ldoc.modules)
+      if not ref then
+         if ldoc.item then ldoc.item:warning(err)
+         else io.stderr:write(err,'\n')
+         end
+         return ''
+      end
+      local label = ref.label:gsub('_','\\_')
+      local res = ('<a href="%s">%s</a>'):format(ldoc.href(ref),label)
+      return res
+   end))
+end
+
+function markup.create (ldoc, format)
+   if format == 'plain' then
+      return function(txt)
+         if txt == nil then return '' end
+         return markup.resolve_inline_references(ldoc, txt)
+      end
+   else
+      local ok,formatter = pcall(require,format)
+      if not ok then quit("cannot load formatter: "..format) end
+      return function (txt)
+         if txt == nil then return '' end
+         txt = markup.resolve_inline_references(ldoc, txt)
+         if txt:find '\n' and not ldoc.classic_markdown then -- multiline text
+            txt = markup.insert_markdown_lines(txt)
+         end
+         txt = formatter   (txt)
+         -- We will add our own paragraph tags, if needed.
+         return (txt:gsub('^%s*<p>(.+)</p>%s*$','%1'))
       end
-      txt = markup(txt)
-      -- We will add our own paragraph tags, if needed.
-      return (txt:gsub('^%s*<p>(.+)</p>%s*$','%1'))
    end
 end