'plain=true' when format is set but you do not want doc comments treated specially. Backticks are now expanded in usage blocks

ldoc.lua

@@ -184,7 +184,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', 'pretty', 'charset',
+   'one','style','template','description','examples', 'pretty', 'charset', 'plain',
    'readme','all','manual_url', 'ignore', 'colon','boilerplate','merge', 'wrap',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
 }

ldoc/html/ldoc_ltp.lua

@@ -24,7 +24,8 @@ return [==[
 # local use_li = ldoc.use_li
 # local display_name = ldoc.display_name
 # local iter = ldoc.modules.iter
-# local M = ldoc.markup
+# ---local M = ldoc.markup
+# local function M(txt,item) return ldoc.markup(txt,item,ldoc.plain) end
 # local nowrap = ldoc.wrap and '' or 'nowrap'
 
 <!-- Menu -->

ldoc/lexer.lua

@@ -17,16 +17,12 @@
 -- iden    n
 -- keyword do
 -- </pre>
--- See the Guide for further <a href="../../index.html#lexer">discussion</a> <br>
--- @class module
--- @name pl.lexer
+--
+-- Based on pl.lexer from Penlight
 
 local strfind = string.find
 local strsub = string.sub
 local append = table.insert
---[[
-module ('pl.lexer',utils._module)
-]]
 
 local function assert_arg(idx,val,tp)
     if type(val) ~= tp then
@@ -70,6 +66,14 @@ local function sdump(tok,options)
     return "string",tok
 end
 
+-- strings enclosed in back ticks
+local function bdump(tok,options)
+    if options and options.string then
+        tok = tok:sub(2,-2)
+    end
+    return "backtick",tok
+end
+
 -- long Lua strings need extra work to get rid of the quotes
 local function sdump_l(tok,options)
     if options and options.string then
@@ -298,6 +302,7 @@ function lexer.lua(s,filter,options)
             {STRING3,sdump},
             {STRING1,sdump},
             {STRING2,sdump},
+            {'^`[^`]+`',bdump},
             {'^%-%-%[(=*)%[.-%]%1%]',cdump},
             {'^%-%-.-\n',cdump},
             {'^%[(=*)%[.-%]%1%]',sdump_l},

ldoc/markup.lua

@@ -233,7 +233,6 @@ local function get_formatter(format)
    end
 end
 
-
 local function text_processor(ldoc)
    return function(txt,item)
       if txt == nil then return '' end
@@ -243,10 +242,17 @@ local function text_processor(ldoc)
    end
 end
 
+local plain_processor
 
 local function markdown_processor(ldoc, formatter)
-   return function (txt,item)
+   return function (txt,item,plain)
       if txt == nil then return '' end
+      if plain then
+         if not plain_processor then
+            plain_processor = text_processor(ldoc)
+         end
+         return plain_processor(txt,item)
+      end
       if utils.is_type(item,doc.File) then
          txt = process_multiline_markdown(ldoc, txt, item)
       else
@@ -258,7 +264,6 @@ local function markdown_processor(ldoc, formatter)
    end
 end
 
-
 local function get_processor(ldoc, format)
    if format == 'plain' then return text_processor(ldoc) end
 

ldoc/prettify.lua

@@ -24,7 +24,7 @@ local function span(t,val)
    return ('<span class="%s">%s</span>'):format(t,val)
 end
 
-local spans = {keyword=true,number=true,string=true,comment=true,global=true}
+local spans = {keyword=true,number=true,string=true,comment=true,global=true,backtick=true}
 
 function prettify.lua (fname, code, initial_lineno, pre)
    local res = List()
@@ -47,7 +47,7 @@ function prettify.lua (fname, code, initial_lineno, pre)
          t = 'global'
       end
       if spans[t] then
-         if t == 'comment' then -- may contain @{ref}
+         if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..`
             val = prettify.resolve_inline_references(val,error_reporter)
          end
          res:append(span(t,val))

tests/styles/one.lua

@@ -2,7 +2,9 @@
 A non-doc comment
 multi-line
 probably containing license information!
-Doesn't use module(), but module name is inferred from file name
+Doesn't use module(), but module name is inferred from file name.
+If you have initial licence comments that look like doc comments,
+then set `boilerplate=true`
 ]]
 ------------
 -- Test module,