1 files changed, 43 insertions, 9 deletions

diff --git a/notYetAnotherWiki.lua b/notYetAnotherWiki.lua
index 1343739..3bcc7d9 100755
--- a/notYetAnotherWiki.lua
+++ b/notYetAnotherWiki.lua
@@ -1,9 +1,12 @@
 #!/usr/bin/env luajit
 
-local lcmark = require("lcmark")
+-- Read the README file for what this is all about.  If there is no README or similar, then you can find the link to the source below.
 
+local lcmark = require("lcmark")        -- https://github.com/jgm/lcmark
 
 
+
+-- Some global data.
 local globalData = {
     ['_'] = ' ', ['dlr'] = '$', ['karenpurple'] = '#8800ff',
     favicon = 'nYAW_icon.png', logo = 'nYAW.png', header = '', --menu = '',
@@ -12,15 +15,18 @@ local globalData = {
 local Sites, Files, Subs = {}, {}, {}
 
 
+
+-- Useful functions, part 0.
+
+-- A simple table.subtable = subtable wont work, you end up with a reference so that changes to the later get applaid to the former.
 local copyTable = function(t, strip)
-    -- A simple table.subtable = subtable wont work, you end up with a reference so that changes to the later get applaid to the former.
     local argh = {}
-    for l, y in ipairs(t) do
-        if (l ~= y.name) and strip then table.insert(argh, y) end
-    end
+    for l, y in ipairs(t) do    if (l ~= y.name) and strip then table.insert(argh, y) end       end
     return argh
 end
 
+
+-- String together the bits array into a path string.
 local stringBits = function(l)
     local bits = {}
     local last = 1
@@ -35,6 +41,9 @@ end
 
 
 
+-- Actually start doing things.
+
+-- Scan the subdirectories looking for .md files.
 local directory = arg[1]
 if nil == directory then directory = '.' end
 if '.' ~= directory then
@@ -42,6 +51,7 @@ if '.' ~= directory then
         Files[string.gsub(l, '%.md$', '')] = {}
     end
 end
+-- Can add in a distant directory to, for putting it's results in the current directory.
 for l in io.popen('find ' .. directory .. ' -name "*.md" -type f,l -printf "%P\n"'):lines() do
     local n = string.gsub(l, '%.md$', '')
     if nil == Files[n] then Files[n] = {} end
@@ -54,6 +64,7 @@ for name, file in pairs(Files) do
     local bits, bit = stringBits(name)
     local ln = #bits
 
+    -- Go through our bits, construct Subs with bits.
     Files[name].bits = bits
     Files[name].bit = bit
     if ln > 0 then bitter = bits[1] end
@@ -67,16 +78,20 @@ for name, file in pairs(Files) do
         if i < ln               then table.remove(Subs[path].bits, #bits) end
     end
 
+    -- Start the file parsing here, coz we need it's metadata.
     print('Parsing ' .. name .. '.md')
     local h = io.open(name  .. '.md', 'r')
 -- TODO - should bail here on error?
     if nil ~= h then file.cm = h:read('*a') ; h:close() else print('oops! No such name ' .. name) end
+    -- Convert the CommonMark to HTML, including the metadata.
     local body, metadata, err = lcmark.convert(file.cm, "html", {smart = true, yaml_metadata = true, columns = 0})
     if    nil == body then print('oops! ' .. err)
     elseif '' == body then
+        -- This is a metadata only file, no content, stash the matadata in it's directory.
         Subs[path].metadata = metadata
         Files[name] = nil
     else
+        -- Ordinary md file, stash it's metadata and parsed body.
         file.metadata = metadata
         file.body = body
         table.insert(Subs[path].files, bit)
@@ -86,10 +101,13 @@ end
 
 
 -- These functions assume the above file and sub scan has completed.
+
+-- Which page in this directory should we show?
 local whichPage = function(f)
     local fl = ''
     if (nil ~= Subs[f]) then
         if 1 == #(Subs[f].files) then   fl = Subs[f].files[1] .. '.HTML' else
+            -- Standard files to search for.
             for i, v in ipairs{'README', 'readme', 'INDEX', 'index'} do
                 for j, w in ipairs(Subs[f].files) do
                     if v == w then
@@ -106,6 +124,7 @@ local whichPage = function(f)
 end
 
 
+-- Calculate a link from the source directory to the destination directory.
 local linkFrom = function(source, dest)
     local depth = 0
     local link = ''
@@ -133,6 +152,9 @@ end
 
 
 
+-- More of this actually doing things nonsense.
+
+-- Loop through the files we found and actually create their HTML files.
 for name, file in pairs(Files) do
     local path, result = '', ''
     local body, metadata = Files[name].body, Files[name].metadata
@@ -142,6 +164,7 @@ for name, file in pairs(Files) do
     path = table.concat(bits, '/', 1, ln)
 
     if '' ~= body then
+    -- Continue the parsing and conversion.  Start by turning our parsed body into something the lcmark template system can grock.
         local bod, err = lcmark.compile_template(body)
         if nil == bod then print('oops! ' .. err) else
             local templateFile = metadata.template
@@ -149,6 +172,7 @@ for name, file in pairs(Files) do
             file.template = templateFile .. '.template'
         end
 
+        -- Copy any metadata found in parent directories.
         local pth = ''
         for i, d in ipairs(bits) do
             if '' ~= pth then pth = pth .. '/' end
@@ -158,17 +182,19 @@ for name, file in pairs(Files) do
                     for m, x in pairs(Subs[pth].metadata) do
                         if nil == metadata[m] then
                             metadata[m] = x
-                        else
+                        end
                     end
-                 end
+                end
             end
         end
-    end
-
+        -- Root directory needs to be handled separately, for now.
         if nil ~= Subs[''].metadata then
             for m, x in pairs(Subs[''].metadata)        do if nil == metadata[m] then metadata[m] = x end end
         end
+
         for             m, x in pairs(globalData)               do if nil == metadata[m] then metadata[m] = x end end
+
+        -- Inherit these images from most recent parent directory that defines them.
         for n, y in ipairs{'favicon', 'logo'} do
             local pith = ''
             if nil ~= metadata[y] then
@@ -185,6 +211,7 @@ for name, file in pairs(Files) do
             end
         end
 
+        -- Figure out this pages header links.
         metadata.header = ''
         local pth = ''
         for i, f in pairs(Subs[path].subs) do
@@ -204,6 +231,7 @@ for name, file in pairs(Files) do
 --          end
         end
 
+        -- Figure out this pages menu links.
         metadata.menu = ''
         if nil ~= Subs[path].files then table.sort(Subs[path].files) end
         for i, f in ipairs(Subs[path].files) do
@@ -214,6 +242,7 @@ for name, file in pairs(Files) do
             end
         end
 
+        -- Figure out this pages trail links.
         metadata.trail = ''
         for i, b in ipairs(bits) do
             if i < #bits then
@@ -225,14 +254,17 @@ for name, file in pairs(Files) do
         end
 --      if '' == metadata.trail then metadata.trail = '<a href="' .. string.rep('../', ln) .. '/' .. whichPage('') .. '">home</a> &nbsp; ' end
 
+        -- Figure out this pages footer links.
         if nil ~= metadata.pagehistory then metadata.history = '<p>Page&nbsp;<a href="' .. metadata.pagehistory .. '">history</a></p>' end
         if nil ~= metadata.sourcecode   then metadata.footer = '<a href="' .. metadata.sourcecode       .. '">source code</a> &nbsp; &nbsp; ' .. metadata.footer    end
         if nil ~= metadata.feedatom             then metadata.footer = '<a href="' .. metadata.feedatom         ..   '">atom feed</a> &nbsp; &nbsp; ' .. metadata.footer    end
         if metadata.footer ~= globalData.footer then metadata.footer = 'Web site ' .. metadata.footer end
         metadata.footer = '<p>' .. metadata.footer .. '</p>'
 
+        -- Apply the template to the body.
         metadata.body = lcmark.apply_template(bod, metadata)
 
+        -- Put it all in the template.
         local tm = ''
         if nil ~= file.template then
             local h = io.open(file.template, 'r')
@@ -243,6 +275,7 @@ for name, file in pairs(Files) do
                 print('oops! No such file ' .. file.template)
             end
 
+-- TODO - Um not sure why this is here AND at the top of the loop.  Here makes more sense.
             local template, err = lcmark.compile_template(tm)
             if nil == template then print('oops! ' .. err) else
                 result = lcmark.apply_template(template, metadata)
@@ -251,6 +284,7 @@ for name, file in pairs(Files) do
             result = body
         end
 
+        -- Write the file.
         if '' ~= result then
             local base = name .. '.HTML'
             print('From ' .. name .. '.md -> ' .. base)