diff --git a/doc/doc.md b/doc/doc.md index f1aa206..1174666 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -1275,6 +1275,9 @@ function tagged with a certain tag: - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments. - `template_escape` overrides the usual '#' used for Lua code in templates. This needs to be changed if the output format is Markdown, for instance. + - `user_keywords` A list of keywords that will be marked in "prettified" code. Useful if +you want to display your own functions in a special way. Each keyword may be styled differently +(using CSS). Only works when `pretty` is set to 'lua' (the default). _Available functions are:_ diff --git a/ldoc.lua b/ldoc.lua index b6d57d9..8930c46 100644 --- a/ldoc.lua +++ b/ldoc.lua @@ -233,7 +233,7 @@ local ldoc_contents = { 'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler', 'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles', 'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references', - 'dont_escape_underscore','global_lookup','prettify_files','convert_opt' + 'dont_escape_underscore','global_lookup','prettify_files','convert_opt', 'user_keywords', } ldoc_contents = tablex.makeset(ldoc_contents) @@ -504,7 +504,7 @@ end -- (this also will initialize the code prettifier used) override ('format','plain') override 'pretty' -ldoc.markup = markup.create(ldoc, args.format,args.pretty) +ldoc.markup = markup.create(ldoc, args.format, args.pretty, ldoc.user_keywords) ------ 'Special' Project-level entities --------------------------------------- -- Examples and Topics do not contain code to be processed for doc comments. diff --git a/ldoc/html/ldoc_css.lua b/ldoc/html/ldoc_css.lua index 7a5a929..96a7c76 100644 --- a/ldoc/html/ldoc_css.lua +++ b/ldoc/html/ldoc_css.lua @@ -304,6 +304,7 @@ pre .number { color: #f8660d; } pre .operator { color: #2239a8; font-weight: bold; } pre .preprocessor, pre .prepro { color: #a33243; } pre .global { color: #800080; } +pre .user-keyword { color: #800080; } pre .prompt { color: #558817; } pre .url { color: #272fc2; text-decoration: underline; } ]==] diff --git a/ldoc/html/ldoc_fixed_css.lua b/ldoc/html/ldoc_fixed_css.lua index d710f8d..7eca9b3 100644 --- a/ldoc/html/ldoc_fixed_css.lua +++ b/ldoc/html/ldoc_fixed_css.lua @@ -312,6 +312,7 @@ pre .number { color: #f8660d; } pre .operator { color: #2239a8; font-weight: bold; } pre .preprocessor, pre .prepro { color: #a33243; } pre .global { color: #800080; } +pre .user-keyword { color: #800080; } pre .prompt { color: #558817; } pre .url { color: #272fc2; text-decoration: underline; } ]] diff --git a/ldoc/html/ldoc_one_css.lua b/ldoc/html/ldoc_one_css.lua index 567cf0d..b7267ac 100644 --- a/ldoc/html/ldoc_one_css.lua +++ b/ldoc/html/ldoc_one_css.lua @@ -280,6 +280,7 @@ pre .number { color: #f8660d; } pre .operator { color: #2239a8; font-weight: bold; } pre .preprocessor, pre .prepro { color: #a33243; } pre .global { color: #800080; } +pre .user-keyword { color: #800080; } pre .prompt { color: #558817; } pre .url { color: #272fc2; text-decoration: underline; } ]==] diff --git a/ldoc/html/ldoc_pale_css.lua b/ldoc/html/ldoc_pale_css.lua index e30f83f..44038f7 100644 --- a/ldoc/html/ldoc_pale_css.lua +++ b/ldoc/html/ldoc_pale_css.lua @@ -303,6 +303,7 @@ pre .number { color: #f8660d; } pre .operator { color: #2239a8; font-weight: bold; } pre .preprocessor, pre .prepro { color: #a33243; } pre .global { color: #800080; } +pre .user-keyword { color: #800080; } pre .prompt { color: #558817; } pre .url { color: #272fc2; text-decoration: underline; } ]] diff --git a/ldoc/markup.lua b/ldoc/markup.lua index fcfc9d8..fde440e 100644 --- a/ldoc/markup.lua +++ b/ldoc/markup.lua @@ -319,7 +319,7 @@ local function get_processor(ldoc, format) end -function markup.create (ldoc, format, pretty) +function markup.create (ldoc, format, pretty, user_keywords) local processor markup.plain = true if format == 'backtick' then @@ -329,6 +329,7 @@ function markup.create (ldoc, format, pretty) backtick_references = ldoc.backtick_references global_context = ldoc.package and ldoc.package .. '.' prettify.set_prettifier(pretty) + prettify.set_user_keywords(user_keywords) markup.process_reference = function(name,istype) if local_context == 'none.' and not name:match '%.' then diff --git a/ldoc/prettify.lua b/ldoc/prettify.lua index bb7239a..06727e5 100644 --- a/ldoc/prettify.lua +++ b/ldoc/prettify.lua @@ -4,9 +4,12 @@ -- A module reference to an example `test-fun.lua` would look like -- `@{example:test-fun}`. local List = require 'pl.List' +local tablex = require 'pl.tablex' local globals = require 'ldoc.builtin.globals' local prettify = {} +local user_keywords = {} + local escaped_chars = { ['&'] = '&', ['<'] = '<', @@ -58,7 +61,9 @@ function prettify.lua (lang, fname, code, initial_lineno, pre, linenos) if globals.functions[val] or globals.tables[val] then t = 'global' end - if spans[t] then + if user_keywords[val] then + res:append(span('user-keyword keyword-' .. val,val)) + elseif spans[t] then if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..` val = prettify.resolve_inline_references(val,error_reporter) end @@ -111,5 +116,11 @@ function prettify.set_prettifier (pretty) end end +function prettify.set_user_keywords(keywords) + if keywords then + user_keywords = tablex.makeset(keywords) + end +end + return prettify