Merging from stevedonovan-master

doc/doc.md

@@ -722,7 +722,7 @@ See @{mylib.c} for the full example.
 
 1.4 introduces basic support for [Moonscript](http://moonscript.org). Moonscript module
 conventions are just the same as Lua, except for an explicit class construct.
-@{list.moon} shows how **@classmod** can declare modules that export one class, with metamethods
+@{List.moon} shows how **@classmod** can declare modules that export one class, with metamethods
 and methods put implicitly into a separate section.
 
 ## Basic Usage
@@ -1247,16 +1247,16 @@ then also index the source files.
 when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
   - `plain` set to true if `format` is set but you don't want code comments processed
   - `wrap` set to true if you want to allow long names to wrap in the summaries
-  -  `manual_url` point to an alternative or local location for the Lua manual, e.g.
-'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
+  -  `manual_url(url)` point to an alternative or local location for the Lua manual, e.g.
+'manual_url file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'.  Remember it is a function!
   - `no_summary` suppress the Contents summary
   -  `custom_tags` define some new tags, which will be presented after the function description.
 The format is `{<name>,[title=<name>,}{hidden=false,}{format=nil}}`.  For instance
 `custom_tags={'remark',title='Remarks'}` will add a little `Remarks` section to the docs for any function
 containing this tag.  `format` can be a function - if not present the default formatter will be used,
 e.g. Markdown
-  - `custom_see_handler` function that filters see-references
-  - `custom_display_name_handler` function that formats an item's name. The arguments are the item
+  - `custom_see_handler(pat,handler)` function that filters see-references
+  - `custom_display_name_handler(item, default_handler)` function that formats an item's name. The arguments are the item
 and the default function used to format the name. For example, to show an icon or label beside any
 function tagged with a certain tag:
 

ldoc.lua

@@ -61,6 +61,7 @@ ldoc, a documentation generator for Lua, vs 1.4.3
   -M,--merge allow module merging
   -S,--simple no return or params, no summary
   -O,--one one-column output layout
+  --date (default system) use this date in generated doc
   --description (default none) project description
   --dump                debug output dump
   --filter (default none) filter output as Lua data (e.g pl.pretty.dump)
@@ -558,6 +559,8 @@ if type(ldoc.examples) == 'table' then
    prettify_source_files(ldoc.examples,"example")
 end
 
+ldoc.is_file_prettified = {}
+
 if ldoc.prettify_files then
    local files = List()
    local linemap = {}
@@ -570,6 +573,23 @@ if ldoc.prettify_files then
       end
       linemap[F.filename] = ls
    end
+
+   if type(ldoc.prettify_files) == 'table' then
+      files = tools.expand_file_list(ldoc.prettify_files, '*.*')
+   elseif type(ldoc.prettify_files) == 'string' then
+      -- the gotcha is that if the person has a folder called 'show', only the contents
+      -- of that directory will be converted.  So, we warn of this amibiguity
+      if ldoc.prettify_files == 'show' then
+         -- just fall through with all module files collected above
+         if path.exists 'show' then
+            print("Notice: if you only want to prettify files in `show`, then set prettify_files to `show/`")
+         end
+      else
+         files = tools.expand_file_list({ldoc.prettify_files}, '*.*')
+      end
+   end
+
+   ldoc.is_file_prettified = tablex.makeset(files)
    prettify_source_files(files,"file",linemap)
 end
 
@@ -784,7 +804,12 @@ ldoc.title = ldoc.title or args.title
 ldoc.description = ldoc.description or utils.choose(args.description ~= "none", args.description);
 ldoc.project = ldoc.project or args.project
 ldoc.package = args.package:match '%a+' and args.package or nil
-ldoc.updatetime = os.date("%Y-%m-%d %H:%M:%S")
+
+if args.date == 'system' then
+   ldoc.updatetime = os.date("%Y-%m-%d %H:%M:%S")
+else
+   ldoc.updatetime = args.date
+end
 
 local html = require 'ldoc.html'
 

ldoc/html/ldoc_ltp.lua

@@ -65,7 +65,7 @@ return [==[
 # for kind, mods, type in ldoc.kinds() do
 #  if ldoc.allowed_in_contents(type,module) then
 <h2>$(kind)</h2>
-<ul class="$(kind=='Topics' and '' or 'nowrap'">
+<ul class="$(kind=='Topics' and '' or 'nowrap')">
 #  for mod in mods() do local name = display_name(mod)
 #   if mod.name == this_mod then
   <li><strong>$(name)</strong></li>
@@ -153,7 +153,7 @@ return [==[
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
-#   if ldoc.prettify_files then
+#   if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
     <a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
 #  end
     </dt>

tests/styles/opt.lua

@@ -1,19 +1,20 @@
 ------------
--- Functions with options and custom tags
+-- ### Functions with options and custom tags.
+-- (use `ldoc -c opt.ld opt.lua` for converting.)
 --
 -- @include opt.md
 
 ---- testing [opt]
 -- @param one
 -- @param[opt] two
--- @param[opt]three
+-- @param[opt] three
 -- @param[opt] four
 -- @remark use with caution!
 function use_opt (one,two,three,four)
 end
 
 --- an explicit table.
--- Can now use tparam aliases in table defns
+-- Can use tparam aliases in table defns
 -- @string name
 -- @int[opt=0] age
 -- @table person2