Issue #174: @include tag for including processed documentation file into output; last item now has a distinct line number, and some nasty tabs have been removed

ldoc/doc.lua

@@ -16,6 +16,7 @@ local TAG_MULTI,TAG_ID,TAG_SINGLE,TAG_TYPE,TAG_FLAG,TAG_MULTI_LINE = 'M','id','S
 
 -- these are the basic tags known to ldoc. They come in several varieties:
 --  - 'M' tags with multiple values like 'param' (TAG_MULTI)
+--  - 'ML' tags which have a single multi-lined value like 'usage' (TAG_MULTI_LINE)
 --  - 'id' tags which are identifiers, like 'name' (TAG_ID)
 --  - 'S' tags with a single value, like 'release' (TAG_SINGLE)
 --  - 'N' tags which have no associated value, like 'local` (TAG_FLAG)
@@ -25,7 +26,7 @@ local known_tags = {
    class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
    copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
    fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
-   ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N';
+   ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N',include = 'S',
    -- project-level
    module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T', file='T',
    -- module-level
@@ -41,7 +42,7 @@ known_tags._project_level = {
    topic = true,
    submodule = true,
    classmod = true,
-	file = true,
+   file = true,
 }
 
 known_tags._code_types = {

ldoc/html.lua

@@ -152,16 +152,24 @@ function html.generate_output(ldoc, args, project)
       end
       return base..name..'.html'
    end
-	
-	-- these references are never from the index...?
-	function ldoc.source_ref (fun)
-		local modname = fun.module.name
-		local pack,name = tools.split_dotted_name(modname)
-		if not pack then
-			name = modname
-		end
-		return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno
-	end
+   
+   function ldoc.include_file (file)
+      local text,e = utils.readfile(file)
+      if not text then quit("unable to include "..file)
+      else
+         return text
+      end
+   end
+
+-- these references are never from the index...?
+function ldoc.source_ref (fun)
+      local modname = fun.module.name
+      local pack,name = tools.split_dotted_name(modname)
+      if not pack then
+         name = modname
+      end
+      return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno
+   end
 
    function ldoc.use_li(ls)
       if #ls > 1 then return '<li>','</li>' else return '','' end
@@ -242,18 +250,18 @@ function html.generate_output(ldoc, args, project)
       end
       return names
    end
-	
-	-- the somewhat tangled logic that controls whether a type appears in the
-	-- navigation sidebar. (At least it's no longer in the template ;))
-	function ldoc.allowed_in_contents(type,module)
-		local allowed = true
-		if ldoc.kinds_allowed then
-			allowed = ldoc.kinds_allowed[type]
-		elseif ldoc.prettify_files and type == 'file' then
-			allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file')
-		end
-		return allowed
-	end
+
+   -- the somewhat tangled logic that controls whether a type appears in the
+   -- navigation sidebar. (At least it's no longer in the template ;))
+   function ldoc.allowed_in_contents(type,module)
+      local allowed = true
+      if ldoc.kinds_allowed then
+         allowed = ldoc.kinds_allowed[type]
+      elseif ldoc.prettify_files and type == 'file' then
+         allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file')
+      end
+      return allowed
+   end
 
    local function set_charset (ldoc,m)
       m = m or ldoc.module

ldoc/html/ldoc_ltp.lua

@@ -87,6 +87,9 @@ return [==[
 <h1>$(ldoc.module_typename(module)) <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
+#   if module.tags.include then
+        $(M(ldoc.include_file(module.tags.include)))
+#   end
 #   if module.usage then
 #     local li,il = use_li(module.usage)
     <h3>Usage:</h3>

ldoc/parse.lua

@@ -354,7 +354,7 @@ local function parse_file(fname, lang, package, args)
 
          -- end of a block of document comments
          if ldoc_comment and tags then
-            local line = t ~= nil and lineno()
+            local line = lineno()
             if t ~= nil then
                if item_follows then -- parse the item definition
                   local err = item_follows(tags,tok)

tests/styles/opt.ld

@@ -0,0 +1,6 @@
+-- must have explicit optchain!
+convert_opt=true
+format = 'markdown'
+-- want to include project source as well.
+prettify_files='show'
+

tests/styles/opt.lua

@@ -0,0 +1,18 @@
+------------
+-- Functions with options.
+-- @include opt.md
+
+---- testing [opt]
+-- @param one
+-- @param[opt] two
+-- @param[opt]three
+-- @param[opt] four
+function use_opt (one,two,three,four)
+end
+
+--- an explicit table.
+-- Can now use tparam aliases in table defns
+-- @string name
+-- @int[opt=0] age
+-- @table person2
+

tests/styles/opt.md

@@ -0,0 +1,9 @@
+By default, an unbroken series of opt modifiers is converted to
+'opt','optchain','optchain', so you get `(a[,b[,c])`.
+
+If `convert_opt` is specified, then no such conversion takes place; you then 
+must explicitly use `optchain`.
+
+The `@include` tag is only meaningful for project-level items like modules,
+scripts, etc. The file is inserted into the document after being formatted.
+In this case, you would usually specify `format="markdown"`.