new feature: prettify_files makes per-item links to source; unless this field is 'show', don't put in index

ldoc.lua

@@ -150,6 +150,7 @@ local function setup_kinds ()
    ProjectMap:add_kind(lookup('classmod','Classes'))
    ProjectMap:add_kind(lookup('topic','Topics'))
    ProjectMap:add_kind(lookup('example','Examples'))
+   ProjectMap:add_kind(lookup('file','Source'))
 
    for k in pairs(kind_names) do
       if not known_types[k] then
@@ -232,7 +233,7 @@ local ldoc_contents = {
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
    'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
    'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references',
-   'dont_escape_underscore','global_lookup',
+   'dont_escape_underscore','global_lookup','prettify_files'   
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
 
@@ -526,27 +527,49 @@ local function add_special_project_entity (f,tags,process)
    return item, F
 end
 
-if type(ldoc.examples) == 'string' then
+local function prettify_source_files(files,class,linemap) 
-   ldoc.examples = {ldoc.examples}
-end
-if type(ldoc.examples) == 'table' then
    local prettify = require 'ldoc.prettify'
 
-   process_file_list (ldoc.examples, '*.*', function(f)
+   process_file_list (files, '*.*', function(f)
       local ext = path.extension(f)
       local ftype = file_types[ext]
       if ftype then
          local item = add_special_project_entity(f,{
-            class = 'example',
+            class = class,
          })
          -- wrap prettify for this example so it knows which file to blame
          -- if there's a problem
          local lang = ext:sub(2)
-         item.postprocess = function(code) return prettify.lua(lang,f,code,0,true) end
+         item.postprocess = function(code)
+            return '<h2>'..path.basename(f)..'</h2>\n' ..
+                prettify.lua(lang,f,code,0,true,linemap and linemap[f])
+         end
       end
    end)
 end
 
+if type(ldoc.examples) == 'string' then
+   ldoc.examples = {ldoc.examples}
+end
+if type(ldoc.examples) == 'table' then
+   prettify_source_files(ldoc.examples,"example")
+end
+
+if ldoc.prettify_files then
+   local files = List()
+   local linemap = {}
+   for F in file_list:iter() do
+      files:append(F.filename)
+      local mod = F.modules[1]
+      local ls = List()
+      for item in mod.items:iter() do
+         ls:append(item.lineno)
+      end
+      linemap[F.filename] = ls
+   end
+   prettify_source_files(files,"file",linemap)
+end
+
 if args.simple then
     ldoc.no_return_or_parms=true
     ldoc.no_summary=true

ldoc/doc.lua

@@ -27,7 +27,7 @@ local known_tags = {
    fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
    ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N';
    -- project-level
-   module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T',
+   module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T', file='T',
    -- module-level
    ['function'] = 'T', lfunction = 'T', table = 'T', section = 'T', type = 'T',
    annotation = 'T', factory = 'T';
@@ -41,6 +41,7 @@ known_tags._project_level = {
    topic = true,
    submodule = true,
    classmod = true,
+	file = true,
 }
 
 known_tags._code_types = {

ldoc/html.lua

@@ -153,6 +153,16 @@ function html.generate_output(ldoc, args, project)
       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.use_li(ls)
       if #ls > 1 then return '<li>','</li>' else return '','' end
    end
@@ -233,6 +243,18 @@ function html.generate_output(ldoc, args, project)
       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
+
    local function set_charset (ldoc,m)
       m = m or ldoc.module
       ldoc.doc_charset = (m and m.tags.charset) or ldoc.charset

ldoc/html/ldoc_ltp.lua

@@ -63,7 +63,7 @@ return [==[
 # -------- contents of project ----------
 # local this_mod = module and module.name
 # for kind, mods, type in ldoc.kinds() do
-#  if not ldoc.kinds_allowed or ldoc.kinds_allowed[type] then
+#  if ldoc.allowed_in_contents(type,module) then
 <h2>$(kind)</h2>
 <ul class="$(kind=='Topics' and '' or 'nowrap'">
 #  for mod in mods() do local name = ldoc.module_name(mod)
@@ -145,6 +145,9 @@ return [==[
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
+#   if ldoc.prettify_files then
+    <a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
+#  end
     </dt>
     <dd>
     $(M(ldoc.descript(item),item))

ldoc/prettify.lua

@@ -26,9 +26,10 @@ local spans = {keyword=true,number=true,string=true,comment=true,global=true,bac
 
 local cpp_lang = {c = true, cpp = true, cxx = true, h = true}
 
-function prettify.lua (lang, fname, code, initial_lineno, pre)
+function prettify.lua (lang, fname, code, initial_lineno, pre, linenos)
    local res, lexer, tokenizer = List(), require 'ldoc.lexer'
    local tnext = lexer.skipws
+	local ik = 1
    if not cpp_lang[lang] then
       tokenizer = lexer.lua
    else
@@ -50,6 +51,10 @@ function prettify.lua (lang, fname, code, initial_lineno, pre)
    if not t then return nil,"empty file" end
    while t do
       val = escape(val)
+      if linenos and tok:lineno() == linenos[ik] then
+      res:append('<a id="'..linenos[ik]..'"></a>')
+         ik = ik + 1
+      end
       if globals.functions[val] or globals.tables[val] then
          t = 'global'
       end