From 42cb80be255eb35b92f857eb9888eeb9e597af30 Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Sun, 10 Jul 2011 19:12:35 +0200
Subject: [PATCH] examples starting to work: factoring looking-up addresses out
 of template

---
 html/ldoc.css  | 563 +++++++++++++++++++++++++------------------------
 html/ldoc.ltp  |  29 +--
 ldoc.lua       | 101 ++++++---
 ldoc/tools.lua |   4 +-
 4 files changed, 374 insertions(+), 323 deletions(-)

diff --git a/html/ldoc.css b/html/ldoc.css
index ce59081..56663ff 100644
--- a/html/ldoc.css
+++ b/html/ldoc.css
@@ -1,278 +1,285 @@
-/* BEGIN RESET
-
-Copyright (c) 2010, Yahoo! Inc. All rights reserved.
-Code licensed under the BSD License:
-http://developer.yahoo.com/yui/license.html
-version: 2.8.2r1
-*/
-html {
-    color: #000;
-    background: #FFF;
-}
-body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
-    margin: 0;
-    padding: 0;
-}
-table {
-    border-collapse: collapse;
-    border-spacing: 0;
-}
-fieldset,img {
-    border: 0;
-}
-address,caption,cite,code,dfn,em,strong,th,var,optgroup {
-    font-style: inherit;
-    font-weight: inherit;
-}
-del,ins {
-    text-decoration: none;
-}
-li {
-    list-style: bullet;
-    margin-left: 20px;
-}
-caption,th {
-    text-align: left;
-}
-h1,h2,h3,h4,h5,h6 {
-    font-size: 100%;
-    font-weight: bold;
-}
-q:before,q:after {
-    content: '';
-}
-abbr,acronym {
-    border: 0;
-    font-variant: normal;
-}
-sup {
-    vertical-align: baseline;
-}
-sub {
-    vertical-align: baseline;
-}
-legend {
-    color: #000;
-}
-input,button,textarea,select,optgroup,option {
-    font-family: inherit;
-    font-size: inherit;
-    font-style: inherit;
-    font-weight: inherit;
-}
-input,button,textarea,select {*font-size:100%;
-}
-/* END RESET */
-
-body {
-    margin-left: 1em;
-    margin-right: 1em;
-    font-family: arial, helvetica, geneva, sans-serif;
-    background-color: #ffffff; margin: 0px;
-}
-
-code, tt { font-family: monospace; }
-
-body, p, td, th { font-size: .95em; line-height: 1.2em;}
-
-p, ul { margin: 10px 0 0 10px;}
-
-strong { font-weight: bold;}
-
-em { font-style: italic;}
-
-h1 {
-    font-size: 1.5em;
-    margin: 0 0 20px 0;
-}
-h2, h3, h4 { margin: 15px 0 10px 0; }
-h2 { font-size: 1.25em; }
-h3 { font-size: 1.15em; }
-h4 { font-size: 1.06em; }
-
-a:link { font-weight: bold; color: #004080; text-decoration: none; }
-a:visited { font-weight: bold; color: #006699; text-decoration: none; }
-a:link:hover { text-decoration: underline; }
-
-hr {
-    color:#cccccc;
-    background: #00007f;
-    height: 1px;
-}
-
-blockquote { margin-left: 3em; }
-
-ul { list-style-type: disc; }
-
-p.name {
-    font-family: "Andale Mono", monospace;
-    padding-top: 1em;
-}
-
-pre.example {
-    background-color: rgb(245, 245, 245);
-    border: 1px solid silver;
-    padding: 10px;
-    margin: 10px 0 10px 0;
-    font-family: "Andale Mono", monospace;
-    font-size: .85em;
-}
-
-pre {
-    background-color: rgb(245, 245, 245);
-    border: 1px solid silver;
-    padding: 10px;
-    margin: 10px 0 10px 0;
-    font-family: "Andale Mono", monospace;
-}
-
-
-table.index { border: 1px #00007f; }
-table.index td { text-align: left; vertical-align: top; }
-
-#container {
-    margin-left: 1em;
-    margin-right: 1em;
-    background-color: #f0f0f0;
-}
-
-#product {
-    text-align: center;
-    border-bottom: 1px solid #cccccc;
-    background-color: #ffffff;
-}
-
-#product big {
-    font-size: 2em;
-}
-
-#main {
-    background-color: #f0f0f0;
-    border-left: 2px solid #cccccc;
-}
-
-#navigation {
-    float: left;
-    width: 18em;
-    vertical-align: top;
-    background-color: #f0f0f0;
-    overflow: visible;
-}
-
-#navigation h2 {
-    background-color:#e7e7e7;
-    font-size:1.1em;
-    color:#000000;
-    text-align: left;
-    padding:0.2em;
-    border-top:1px solid #dddddd;
-    border-bottom:1px solid #dddddd;
-}
-
-#navigation ul
-{
-    font-size:1em;
-    list-style-type: none;
-    margin: 1px 1px 10px 1px;
-}
-
-#navigation li {
-    text-indent: -1em;
-    display: block;
-    margin: 3px 0px 0px 22px;
-}
-
-#navigation li li a {
-    margin: 0px 3px 0px -1em;
-}
-
-#content {
-    margin-left: 18em;
-    padding: 1em;
-    border-left: 2px solid #cccccc;
-    border-right: 2px solid #cccccc;
-    background-color: #ffffff;
-}
-
-#about {
-    clear: both;
-    padding: 5px;
-    border-top: 2px solid #cccccc;
-    background-color: #ffffff;
-}
-
-@media print {
-    body {
-        font: 12pt "Times New Roman", "TimeNR", Times, serif;
-    }
-    a { font-weight: bold; color: #004080; text-decoration: underline; }
-
-    #main {
-        background-color: #ffffff;
-        border-left: 0px;
-    }
-
-    #container {
-        margin-left: 2%;
-        margin-right: 2%;
-        background-color: #ffffff;
-    }
-
-    #content {
-        padding: 1em;
-        background-color: #ffffff;
-    }
-
-    #navigation {
-        display: none;
-    }
-    pre.example {
-        font-family: "Andale Mono", monospace;
-        font-size: 10pt;
-        page-break-inside: avoid;
-    }
-}
-
-table.module_list {
-    border-width: 1px;
-    border-style: solid;
-    border-color: #cccccc;
-    border-collapse: collapse;
-}
-table.module_list td {
-    border-width: 1px;
-    padding: 3px;
-    border-style: solid;
-    border-color: #cccccc;
-}
-table.module_list td.name { background-color: #f0f0f0; }
-table.module_list td.summary { width: 100%; }
-
-
-table.function_list {
-    border-width: 1px;
-    border-style: solid;
-    border-color: #cccccc;
-    border-collapse: collapse;
-}
-table.function_list td {
-    border-width: 1px;
-    padding: 3px;
-    border-style: solid;
-    border-color: #cccccc;
-}
-table.function_list td.name { background-color: #f0f0f0; }
-table.function_list td.summary { width: 100%; }
-
-dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
-dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
-dl.table h3, dl.function h3 {font-size: .95em;}
-
-/* stop sublists from having initial vertical space */
-ul ul { margin-top: 0px; }
-ol ul { margin-top: 0px; }
-ol ol { margin-top: 0px; }
-ul ol { margin-top: 0px; }
-
-
-
+/* BEGIN RESET
+
+Copyright (c) 2010, Yahoo! Inc. All rights reserved.
+Code licensed under the BSD License:
+http://developer.yahoo.com/yui/license.html
+version: 2.8.2r1
+*/
+html {
+    color: #000;
+    background: #FFF;
+}
+body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
+    margin: 0;
+    padding: 0;
+}
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+fieldset,img {
+    border: 0;
+}
+address,caption,cite,code,dfn,em,strong,th,var,optgroup {
+    font-style: inherit;
+    font-weight: inherit;
+}
+del,ins {
+    text-decoration: none;
+}
+li {
+    list-style: bullet;
+    margin-left: 20px;
+}
+caption,th {
+    text-align: left;
+}
+h1,h2,h3,h4,h5,h6 {
+    font-size: 100%;
+    font-weight: bold;
+}
+q:before,q:after {
+    content: '';
+}
+abbr,acronym {
+    border: 0;
+    font-variant: normal;
+}
+sup {
+    vertical-align: baseline;
+}
+sub {
+    vertical-align: baseline;
+}
+legend {
+    color: #000;
+}
+input,button,textarea,select,optgroup,option {
+    font-family: inherit;
+    font-size: inherit;
+    font-style: inherit;
+    font-weight: inherit;
+}
+input,button,textarea,select {*font-size:100%;
+}
+/* END RESET */
+
+body {
+    margin-left: 1em;
+    margin-right: 1em;
+    font-family: arial, helvetica, geneva, sans-serif;
+    background-color: #ffffff; margin: 0px;
+}
+
+code, tt { font-family: monospace; }
+
+body, p, td, th { font-size: .95em; line-height: 1.2em;}
+
+p, ul { margin: 10px 0 0 10px;}
+
+strong { font-weight: bold;}
+
+em { font-style: italic;}
+
+h1 {
+    font-size: 1.5em;
+    margin: 0 0 20px 0;
+}
+h2, h3, h4 { margin: 15px 0 10px 0; }
+h2 { font-size: 1.25em; }
+h3 { font-size: 1.15em; }
+h4 { font-size: 1.06em; }
+
+a:link { font-weight: bold; color: #004080; text-decoration: none; }
+a:visited { font-weight: bold; color: #006699; text-decoration: none; }
+a:link:hover { text-decoration: underline; }
+
+hr {
+    color:#cccccc;
+    background: #00007f;
+    height: 1px;
+}
+
+blockquote { margin-left: 3em; }
+
+ul { list-style-type: disc; }
+
+p.name {
+    font-family: "Andale Mono", monospace;
+    padding-top: 1em;
+}
+
+pre.example {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    font-family: "Andale Mono", monospace;
+    font-size: .85em;
+}
+
+pre {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    overflow: auto;
+    font-family: "Andale Mono", monospace;
+}
+
+
+table.index { border: 1px #00007f; }
+table.index td { text-align: left; vertical-align: top; }
+
+#container {
+    margin-left: 1em;
+    margin-right: 1em;
+    background-color: #f0f0f0;
+}
+
+#product {
+    text-align: center;
+    border-bottom: 1px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#product big {
+    font-size: 2em;
+}
+
+#main {
+    background-color: #f0f0f0;
+    border-left: 2px solid #cccccc;
+}
+
+#navigation {
+    float: left;
+    width: 18em;
+    vertical-align: top;
+    background-color: #f0f0f0;
+    overflow: visible;
+}
+
+#navigation h2 {
+    background-color:#e7e7e7;
+    font-size:1.1em;
+    color:#000000;
+    text-align: left;
+    padding:0.2em;
+    border-top:1px solid #dddddd;
+    border-bottom:1px solid #dddddd;
+}
+
+#navigation ul
+{
+    font-size:1em;
+    list-style-type: none;
+    margin: 1px 1px 10px 1px;
+}
+
+#navigation li {
+    text-indent: -1em;
+    display: block;
+    margin: 3px 0px 0px 22px;
+}
+
+#navigation li li a {
+    margin: 0px 3px 0px -1em;
+}
+
+#content {
+    margin-left: 18em;
+    padding: 1em;
+    border-left: 2px solid #cccccc;
+    border-right: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#about {
+    clear: both;
+    padding: 5px;
+    border-top: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+@media print {
+    body {
+        font: 12pt "Times New Roman", "TimeNR", Times, serif;
+    }
+    a { font-weight: bold; color: #004080; text-decoration: underline; }
+
+    #main {
+        background-color: #ffffff;
+        border-left: 0px;
+    }
+
+    #container {
+        margin-left: 2%;
+        margin-right: 2%;
+        background-color: #ffffff;
+    }
+
+    #content {
+        padding: 1em;
+        background-color: #ffffff;
+    }
+
+    #navigation {
+        display: none;
+    }
+    pre.example {
+        font-family: "Andale Mono", monospace;
+        font-size: 10pt;
+        page-break-inside: avoid;
+    }
+}
+
+table.module_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.module_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.module_list td.name { background-color: #f0f0f0; ; min-width: 200px; }
+table.module_list td.summary { width: 100%; }
+
+
+table.function_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.function_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.function_list td.name { background-color: #f0f0f0; ; min-width: 200px; }
+table.function_list td.summary { width: 100%; }
+
+dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
+dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
+dl.table h3, dl.function h3 {font-size: .95em;}
+
+/* stop sublists from having initial vertical space */
+ul ul { margin-top: 0px; }
+ol ul { margin-top: 0px; }
+ol ol { margin-top: 0px; }
+ul ol { margin-top: 0px; }
+
+/* styles for prettification of source */
+.keyword {font-weight: bold; color: #6666AA; }
+.number  { color: #AA6666; }
+.string  { color: #8888AA; }
+.comment { color: #666600; }
+.prepro { color: #006666; }
+
+
diff --git a/html/ldoc.ltp b/html/ldoc.ltp
index 5ff8a33..2b8c0e9 100644
--- a/html/ldoc.ltp
+++ b/html/ldoc.ltp
@@ -35,7 +35,9 @@
 <!-- Menu -->
 
 <div id="navigation">
+
 <h1>$(ldoc.project)</h1>
+
 # if not ldoc.single then -- reference back to project index
 <ul>
   <li><a href="../$(ldoc.output).html">Index</a></li>
@@ -44,7 +46,8 @@
 <p>$(ldoc.description)</p>
 # end
 
-# if module and not ldoc.no_summary and not ldoc.no_contents then
+# --------- contents of module -------------
+# if module and not ldoc.no_summary and #module.items > 0 then
 <h2>Contents</h2>
 <ul>
 # for kind,items in module.kinds() do
@@ -53,23 +56,18 @@
 </ul>
 # end
 
+# -------- contents of project ----------
 # if not ldoc.no_summary then
+# local this_mod = module and module.name
 # for kind, mods, type in ldoc.kinds() do
 <h2>$(kind)</h2>
 <ul>
-# local this_mod = module and module.name
-# local base = ""
-# kind = kind:lower()
-# if module then
-#   if module.type ~= type then base = "../"..kind.."/" end
-# else base = kind.."/"
-# end
 # for mod in mods() do
-#  if mod.name == this_mod then
+#  if mod.name == this_mod then -- highlight current module, link to others
   <li><strong>$(mod.name)</strong></li>
-# else
-  <li><a href="$(base..mod.name).html">$(mod.name)</a></li>
-# end
+#  else
+  <li><a href="$(ldoc.ref_to_module(mod,module,kind)).html">$(mod.name)</a></li>
+#  end
 # end
 #end
 </ul>
@@ -87,10 +85,13 @@
 
 <div id="content">
 
-# if ldoc.body then -- verbatim HTML as contents
+#if module then
+<h1>$(title(module.type)) <code>$(module.name)</code></h1>
+# end
+
+# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
     $(ldoc.body)
 # elseif module then -- module documentation
-<h1>$(title(module.type)) <code>$(module.name)</code></h1>
 <p>$(M(module.summary))</p>
 <p>$(M(module.description))</p>
 
diff --git a/ldoc.lua b/ldoc.lua
index 55055bd..deb2bdf 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -322,7 +322,6 @@ end
 local F
 local file_list,module_list = List(),List()
 module_list.by_name = {}
-local multiple_files
 local config_dir
 
 
@@ -442,24 +441,6 @@ local function process_file_list (list, mask, operation, ...)
    end
 end
 
-local prettify = require 'ldoc.prettify'
-
-function process_example (f, file_list)
-   local F = File(f)
-   local tags = {
-      name = path.basename(f),
-      class = 'example',
-      description = prettify.lua(f)
-   }
-   local item = F:new_item(tags,1)
-   F:finish()
-   item.not_code = true
-   file_list:append(F)
-end
-
-if type(ldoc.examples) == 'table' then
-   process_file_list (ldoc.examples, '*.lua', process_example, file_list)
-end
 
 if type(args.file) == 'table' then
    -- this can only be set from config file so we can assume it's already read
@@ -503,12 +484,34 @@ end
 
 setup_package_base()
 
-multiple_files = #file_list > 1
+local multiple_files = #file_list > 1
+local first_module
+
+if type(ldoc.examples) == 'table' then
+   local prettify = require 'ldoc.prettify'
+
+   local function process_example (f, file_list)
+      local F = File(f)
+      local tags = {
+         name = path.basename(f),
+         class = 'example',
+         description = prettify.lua(f)
+      }
+      local item = F:new_item(tags,1)
+      F:finish()
+      item.not_code = true
+      file_list:append(F)
+   end
+
+   process_file_list (ldoc.examples, '*.lua', process_example, file_list)
+end
+
 
 local project = ProjectMap()
 
 for F in file_list:iter() do
    for mod in F.modules:iter() do
+      if not first_module then first_module = mod end
       module_list:append(mod)
       module_list.by_name[mod.name] = mod
    end
@@ -653,6 +656,41 @@ function ldoc.href(see)
    end
 end
 
+-- this is either called from the 'root' (index or single module) or
+-- from the 'modules' etc directories. If we are in one of those directories,
+-- then linking to another kind is `../kind/name`; to the same kind is just `name`.
+-- If we are in the root, then it is `kind/name`.
+
+function ldoc.ref_to_module (mod,module,kind)
+   local base = "" -- default: same directory
+   local name = mod.name -- default: name of module
+   local single_mod = ldoc.single and ldoc.root
+   kind = kind:lower()
+   if not ldoc.single then
+      if module then -- we are in kind/
+         if module.type ~= type then -- cross ref to ../kind/
+            base = "../"..kind.."/"
+         end
+      else -- we are in root: index
+         base = kind..'/'
+      end
+   else -- single module
+      --print('mod',mod.name,mod.type,module.type,first_module.type)
+      if mod == first_module then
+         name = ldoc.output
+         if not ldoc.root then base = '../' end
+      elseif ldoc.root then -- ref to other kinds (like examples)
+         base = kind..'/'
+      else
+         if module.type ~= type then -- cross ref to ../kind/
+            base = "../"..kind.."/"
+         end
+      end
+   end
+   print('res',base..name)
+   return base..name
+end
+
 
 local function generate_output()
    local check_directory, check_file, writefile = tools.check_directory, tools.check_file, tools.writefile
@@ -664,33 +702,38 @@ local function generate_output()
    ldoc.title = ldoc.title or args.title
    ldoc.project = ldoc.project or args.project
 
-   ldoc.module = ldoc.single and ldoc.modules[1] or nil
+   -- in single mode there is one module and the 'index' is the
+   -- documentation for that module.
+   ldoc.module = ldoc.single and first_module or nil
+   ldoc.root = true
    local out,err = template.substitute(module_template,{
       ldoc = ldoc,
       module = ldoc.module
     })
+   ldoc.root = false
    if not out then quit("template failed: "..err) end
 
-   check_directory(args.dir)
+   check_directory(args.dir) -- make sure output directory is ok
 
    args.dir = args.dir .. path.sep
 
-   check_file(args.dir..css, path.join(args.style,css))
+   check_file(args.dir..css, path.join(args.style,css)) -- has CSS been copied?
 
    -- write out the module index
    writefile(args.dir..args.output..args.ext,out)
 
    -- write out the per-module documentation
-   if not ldoc.single then
-      ldoc.css = '../'..css
-      ldoc.output = args.output
-      for kind, modules in project() do
-         kind = kind:lower()
+   -- in single mode, we exclude any modules since the module has been done;
+   -- this step is then only for putting out any examples or topics
+   ldoc.css = '../'..css
+   ldoc.output = args.output
+   for kind, modules in project() do
+      kind = kind:lower()
+      if not ldoc.single or ldoc.single and kind ~= 'modules' then
          check_directory(args.dir..kind)
          for m in modules() do
             ldoc.module = m
             ldoc.body = m.not_code and m.description or nil
-            ldoc.no_contents = ldoc.body ~= nil
             out,err = template.substitute(module_template,{
                module=m,
                ldoc = ldoc
diff --git a/ldoc/tools.lua b/ldoc/tools.lua
index f0f7d1e..e36e215 100644
--- a/ldoc/tools.lua
+++ b/ldoc/tools.lua
@@ -130,7 +130,7 @@ end
 function M.expand_comma_list (ls)
    local new_ls = List()
    for s in ls:iter() do
-      s = s:gsub('[^%.:%w_]*$','')
+      s = s:gsub('[^%.:%-%w_]*$','')
       if s:find ',' then
          new_ls:extend(List.split(s,'%s*,%s*'))
       else
@@ -156,7 +156,7 @@ end
 
 
 function M.extract_identifier (value)
-   return value:match('([%.:_%w]+)')
+   return value:match('([%.:%-_%w]+)')
 end
 
 function M.strip (s)