keep a table of globals; used for ldoc -m and for resolving @see references to Lua standard library functions and tables

builtin/globals.lua

@@ -0,0 +1,80 @@
+-------
+-- global functions and tables
+local tools = require 'ldoc.tools'
+
+
+
+local functions = {
+   assert = true,
+   collectgarbage = true,
+   dofile = true,
+   setfenv = true,
+   getfenv = true,
+   getmetatable = true,
+   setmetatable = true,
+   pairs = true,
+   ipairs = true,
+   load = true,
+   loadfile = true,
+   loadstring = true,
+   next = true,
+   pcall = true,
+   print = true,
+   rawequal = true,
+   rawget = true,
+   rawset = true,
+   select = true,
+   tonumber = true,
+   tostring = true,
+   type = true,
+   unpack = true,
+   xpcall = true,
+   module = true,
+   require = true,
+}
+
+local tables = {
+   io = '5.7',
+   package = '5.3',
+   math = '5.6',
+   os = '5.8',
+   string = '5.4',
+   table = '5.5',
+   coroutine = '5.2',
+   debug = '5.9'
+}
+
+local manual = 'http://www.lua.org/manual/5.1/manual.html#'
+local fun_ref = manual..'pdf-'
+
+local function function_ref (name)
+   return {href = fun_ref..name}
+end
+
+local function module_ref (name)
+   return {href = manual..tables[name]}
+end
+
+
+local function lua_manual_ref (name)
+   local tbl,fname = tools.split_dotted_name(name)
+   if not tbl then -- plain symbol
+      if functions[name] then
+         return function_ref(name)
+      end
+      if tables[name] then
+         return module_ref(name)
+      end
+   else
+      if tables[tbl] then
+         return function_ref(name)
+      end
+   end
+   return nil
+end
+
+return {
+   functions = functions,
+   tables = tables,
+   lua_manual_ref = lua_manual_ref
+}

html/ldoc.ltp

@@ -142,12 +142,17 @@
     </ol>
 #   end -- if returns
 
+#   local function href(see)
+#       if see.href then return see.href
+#       else return see.mod..'.html#'..see.name
+#       end
+#   end
 #   if item.see then
 #     local li,il = use_li(item.see)
     <h3>see also:</h3>
     <ul>
 #     for see in iter(item.see) do
-         $(li)<a href="$(see.mod).html#$(see.name)">$(see.label)</a>$(il)
+         $(li)<a href="$(href(see))">$(see.label)</a>$(il)
 #    end -- for
     </ul>
 #   end -- if see

ldoc/doc.lua

@@ -5,7 +5,7 @@
 require 'pl'
 
 local doc = {}
-
+local global = require 'builtin.globals'
 local tools = require 'ldoc.tools'
 local split_dotted_name = tools.split_dotted_name
 
@@ -100,7 +100,7 @@ function File:finish()
             mname = this_mod.name
             package = ''
          else
-            package = package .. '.'
+            package = package
          end
          self.modules:append(this_mod)
          this_mod.package = package
@@ -277,6 +277,7 @@ function Item:warning(msg)
    if type(name) == 'table' then pretty.dump(name); name = '?' end
    name = name or '?'
    io.stderr:write(name,':',self.lineno or '?',' ',msg,'\n')
+   return nil
 end
 
 function Item:error(msg)
@@ -295,20 +296,36 @@ end
 function Module:resolve_references(modules)
    local found = List()
 
+   local function hunt_for_reference (packmod)
+      local mod_ref
+      local package = self.package
+      repeat -- same package?
+         local nmod = package..'.'..packmod
+         mod_ref = modules.by_name[nmod]
+         if mod_ref then break end -- cool
+         package = split_dotted_name(package)
+      until not package
+      return mod_ref
+   end
+
    local function process_see_reference (item,see,s)
       local mod_ref,fun_ref,name,packmod
       -- is this a fully qualified module name?
       local mod_ref = modules.by_name[s]
       if mod_ref then return mod_ref,nil end
+      -- module reference?
+      mod_ref = hunt_for_reference(s)
+      if mod_ref then return mod_ref end
       local packmod,name = split_dotted_name(s) -- e.g. 'pl.utils','split'
       if packmod then -- qualified name
          mod_ref = modules.by_name[packmod] -- fully qualified mod name?
          if not mod_ref then
-            mod_ref = modules.by_name[self.package..packmod]
+            mod_ref = hunt_for_reference(packmod)
-         end
             if not mod_ref then
-            item:warning("module not found: "..packmod)
+               local ref = global.lua_manual_ref(s)
-            return nil
+               if ref then return ref end
+               return item:warning("module not found: "..packmod)
+            end
          end
          fun_ref = mod_ref.items.by_name[name]
          if fun_ref then
@@ -317,11 +334,13 @@ function Module:resolve_references(modules)
             item:warning("function not found: "..s.." in "..mod_ref.name)
          end
       else -- plain jane name; module in this package, function in this module
-         mod_ref = modules.by_name[self.package..s]
+         mod_ref = modules.by_name[self.package..'.'..s]
          if mod_ref then return mod_ref,nil end
          fun_ref = self.items.by_name[s]
          if fun_ref then return self,fun_ref
          else
+            local ref = global.lua_manual_ref (s)
+            if ref then return ref end
             item:warning("function not found: "..s.." in this module")
          end
       end
@@ -334,12 +353,18 @@ function Module:resolve_references(modules)
          for s in see:iter() do
             local mod_ref, item_ref = process_see_reference(item,see,s)
             if mod_ref then
+               local href
+               if mod_ref.name then
                   local name = item_ref and item_ref.name or ''
                   -- this is deeply hacky; classes have 'Class ' prepended.
                   if item_ref and item_ref.type == 'type' then
                      name = 'Class_'..name
                   end
-               item.see:append {mod=mod_ref.name,name=name,label=s}
+                  href = {mod=mod_ref.name,name=name,label=s}
+               else
+                  href = {href = mod_ref.href,label=s}
+               end
+               item.see:append (href)
                found:append{item,s}
             end
          end

ldoc/tools.lua

@@ -195,6 +195,7 @@ function M.this_module_name (basename,fname)
       basename = basename..path.sep
    end
    local lpath,cnt = fname:gsub('^'..utils.escape(basename),'')
+   --print('deduce',lpath,cnt,basename)
    if cnt ~= 1 then quit("module(...) name deduction failed: base "..basename.." "..fname) end
    lpath = lpath:gsub(path.sep,'.')
    return M.name_of(lpath):gsub('%.init$','')