pretty field can be set to 'lxsh'; github-flavoured Markdown fenced code blocks; if lxsh, can also highlight c, sh and bib

ldoc.lua

@@ -183,7 +183,7 @@ end
 local ldoc_contents = {
    'alias','add_language_extension','new_type','add_section', 'tparam_alias',
    'file','project','title','package','format','output','dir','ext', 'topics',
-   'one','style','template','description','examples',
+   'one','style','template','description','examples', 'pretty',
    'readme','all','manual_url', 'ignore', 'colon','boilerplate','merge', 'wrap',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
 }
@@ -394,8 +394,10 @@ else
 end
 
 -- create the function that renders text (descriptions and summaries)
+-- (this also will initialize the code prettifier used)
 override 'format'
-ldoc.markup = markup.create(ldoc, args.format)
+override 'pretty'
+ldoc.markup = markup.create(ldoc, args.format,args.pretty)
 
 ------ 'Special' Project-level entities ---------------------------------------
 -- Examples and Topics do not contain code to be processed for doc comments.
@@ -431,7 +433,7 @@ if type(ldoc.examples) == 'table' then
       })
       -- wrap prettify for this example so it knows which file to blame
       -- if there's a problem
-      item.postprocess = function(code) return prettify.lua(f,code) end
+      item.postprocess = function(code) return prettify.lua(f,code,0,true) end
    end)
 end
 

ldoc/html.lua

@@ -61,7 +61,7 @@ function html.generate_output(ldoc, args, project)
    end
 
    function ldoc.prettify(str)
-      return prettify.lua('tmp',str,0,true)
+      return prettify.code('lua','usage',str,0,false)
    end
 
    -- this generates the internal module/function references

ldoc/html/ldoc_css.lua

@@ -81,7 +81,7 @@ span.types:after { content:")"; }
 
 body, p, td, th { font-size: .95em; line-height: 1.2em;}
 
-p, ul { margin: 10px 0 0 10px;}
+p, ul { margin: 10px 0 0 0px;}
 
 strong { font-weight: bold;}
 
@@ -283,12 +283,26 @@ 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; }
 .global { color: #800080; }
+*/
+pre .comment { color: #558817; }
+pre .constant { color: #a8660d; }
+pre .escape { color: #844631; }
+pre .keyword { color: #2239a8; font-weight: bold; }
+pre .library { color: #0e7c6b; }
+pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
+pre .string { color: #a8660d; }
+pre .number { color: #a8660d; }
+pre .operator { color: #2239a8; font-weight: bold; }
+pre .preprocessor, pre .prepro { color: #a33243; }
+pre .prompt { color: #558817; }
+pre .url { color: #272fc2; text-decoration: underline; }
 ]==]
 
 

ldoc/markup.lua

@@ -111,18 +111,46 @@ local function process_multiline_markdown(ldoc, txt, F)
       L = L + 1
       return get()
    end
-   local line = getline()
-   local indent,code,start_indent
+   local function pretty_code (code, lang)
+      code = concat(code,'\n')
+      if code ~= '' then
+         local err
+         code, err = prettify.code(lang,filename,code..'\n',L,false)
+         append(res,'<pre>')
+         append(res, code)
+         append(res,'</pre>')
+      else
+         append(res,code)
+      end
+   end
+   local indent,start_indent
    local_context = nil
+   local line = getline()
    while line do
       local name = line:match '^@lookup%s+(%S+)'
       if name then
          local_context = name .. '.'
          line = getline()
       end
+      local fence = line:match '^```(.*)'
+      if fence then
+         local plain = fence==''
+         line = getline()
+         local code = {}
+         while not line:match '^```' do
+            if not plain then
+               append(code, line)
+            else
+               append(res, '     '..line)
+            end
+            line = getline()
+         end
+         pretty_code (code,fence)
+         line = getline() -- skip fence
+      end
       indent, line = indent_line(line)
       if indent >= 4 then -- indented code block
-         code = {}
+         local code = {}
          local plain
          while indent >= 4 or not non_blank(line) do
             if not start_indent then
@@ -135,7 +163,7 @@ local function process_multiline_markdown(ldoc, txt, F)
             if not plain then
                append(code,line:sub(start_indent))
             else
-               append(res, line)
+               append(res,line)
             end
             line = getline()
             if line == nil then break end
@@ -143,16 +171,7 @@ local function process_multiline_markdown(ldoc, txt, F)
          end
          start_indent = nil
          if #code > 1 then table.remove(code) end
-         code = concat(code,'\n')
-         if code ~= '' then
-            local err
-            code, err = prettify.lua(filename,code..'\n',L)
-            code = resolve_inline_references(ldoc, code, err_item)
-            append(res, code)
-            append(res,'</pre>')
-         else
-            append(res ,code)
-         end
+         pretty_code (code,'lua')
       else
          local section = F.sections[L]
          if section then
@@ -245,11 +264,12 @@ local function get_processor(ldoc, format)
 end
 
 
-function markup.create (ldoc, format)
+function markup.create (ldoc, format, pretty)
    local processor
    markup.plain = true
    backtick_references = ldoc.backtick_references
    global_context = ldoc.package and ldoc.package .. '.'
+   prettify.set_prettifier(pretty)
 
    markup.process_reference = function(name)
       if local_context == 'none.' and not name:match '%.' then

ldoc/prettify.lua

@@ -26,9 +26,9 @@ end
 
 local spans = {keyword=true,number=true,string=true,comment=true,global=true}
 
-function prettify.lua (fname, code, initial_lineno, no_pre)
+function prettify.lua (fname, code, initial_lineno, pre)
    local res = List()
-   if not no_pre then
+   if pre then
       res:append '<pre>\n'
    end
    initial_lineno = initial_lineno or 0
@@ -60,8 +60,44 @@ function prettify.lua (fname, code, initial_lineno, no_pre)
    if last:match '\n$' then
       res[#res] = last:gsub('\n+','')
    end
+   if pre then
+      res:append '<pre/>\n'
+   end
    return res:join ()
 end
 
+local lxsh
+
+local lxsh_highlighers = {bib=true,c=true,lua=true,sh=true}
+
+function prettify.code (lang,fname,code,initial_lineno,pre)
+   if not lxsh then
+      return prettify.lua (fname, code, initial_lineno, pre)
+   else
+      if not lxsh_highlighers[lang] then
+         lang = 'lua'
+      end
+      code = lxsh.highlighters[lang](code, {
+         formatter = lxsh.formatters.html,
+         external = true
+      })
+      if not pre then
+         code = code:gsub("^<pre*.->(.*)</pre>$", '%1')
+      end
+      return code
+   end
+end
+
+function prettify.set_prettifier (pretty)
+   local ok
+   if pretty == 'lxsh' then
+      ok,lxsh = pcall(require,'lxsh')
+      if not ok then
+         print('pretty: '..pretty..' not found, using built-in Lua')
+         lxsh = nil
+      end
+   end
+end
+
 return prettify