Support used-defined keywords (in prettified code).
Mooffie
9 years ago
1274 | 1274 | - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments. |
1275 | 1275 | - `template_escape` overrides the usual '#' used for Lua code in templates. |
1276 | 1276 | This needs to be changed if the output format is Markdown, for instance. |
1277 | - `user_keywords` A list of keywords that will be marked in "prettified" code. Useful if | |
1278 | you want to display your own functions in a special way. Each keyword may be styled differently | |
1279 | (using CSS). Only works when `pretty` is set to 'lua' (the default). | |
1277 | 1280 | |
1278 | 1281 | _Available functions are:_ |
1279 | 1282 |
303 | 303 | pre .operator { color: #2239a8; font-weight: bold; } |
304 | 304 | pre .preprocessor, pre .prepro { color: #a33243; } |
305 | 305 | pre .global { color: #800080; } |
306 | pre .user-keyword { color: #800080; } | |
306 | 307 | pre .prompt { color: #558817; } |
307 | 308 | pre .url { color: #272fc2; text-decoration: underline; } |
308 | 309 | ]==] |
311 | 311 | pre .operator { color: #2239a8; font-weight: bold; } |
312 | 312 | pre .preprocessor, pre .prepro { color: #a33243; } |
313 | 313 | pre .global { color: #800080; } |
314 | pre .user-keyword { color: #800080; } | |
314 | 315 | pre .prompt { color: #558817; } |
315 | 316 | pre .url { color: #272fc2; text-decoration: underline; } |
316 | 317 | ]] |
279 | 279 | pre .operator { color: #2239a8; font-weight: bold; } |
280 | 280 | pre .preprocessor, pre .prepro { color: #a33243; } |
281 | 281 | pre .global { color: #800080; } |
282 | pre .user-keyword { color: #800080; } | |
282 | 283 | pre .prompt { color: #558817; } |
283 | 284 | pre .url { color: #272fc2; text-decoration: underline; } |
284 | 285 | ]==] |
302 | 302 | pre .operator { color: #2239a8; font-weight: bold; } |
303 | 303 | pre .preprocessor, pre .prepro { color: #a33243; } |
304 | 304 | pre .global { color: #800080; } |
305 | pre .user-keyword { color: #800080; } | |
305 | 306 | pre .prompt { color: #558817; } |
306 | 307 | pre .url { color: #272fc2; text-decoration: underline; } |
307 | 308 | ]] |
318 | 318 | end |
319 | 319 | |
320 | 320 | |
321 | function markup.create (ldoc, format, pretty) | |
321 | function markup.create (ldoc, format, pretty, user_keywords) | |
322 | 322 | local processor |
323 | 323 | markup.plain = true |
324 | 324 | if format == 'backtick' then |
328 | 328 | backtick_references = ldoc.backtick_references |
329 | 329 | global_context = ldoc.package and ldoc.package .. '.' |
330 | 330 | prettify.set_prettifier(pretty) |
331 | prettify.set_user_keywords(user_keywords) | |
331 | 332 | |
332 | 333 | markup.process_reference = function(name,istype) |
333 | 334 | if local_context == 'none.' and not name:match '%.' then |
3 | 3 | -- A module reference to an example `test-fun.lua` would look like |
4 | 4 | -- `@{example:test-fun}`. |
5 | 5 | local List = require 'pl.List' |
6 | local tablex = require 'pl.tablex' | |
6 | 7 | local globals = require 'ldoc.builtin.globals' |
7 | 8 | local prettify = {} |
9 | ||
10 | local user_keywords = {} | |
8 | 11 | |
9 | 12 | local escaped_chars = { |
10 | 13 | ['&'] = '&', |
57 | 60 | if globals.functions[val] or globals.tables[val] then |
58 | 61 | t = 'global' |
59 | 62 | end |
60 | if spans[t] then | |
63 | if user_keywords[val] then | |
64 | res:append(span('user-keyword keyword-' .. val,val)) | |
65 | elseif spans[t] then | |
61 | 66 | if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..` |
62 | 67 | val = prettify.resolve_inline_references(val,error_reporter) |
63 | 68 | end |
110 | 115 | end |
111 | 116 | end |
112 | 117 | |
118 | function prettify.set_user_keywords(keywords) | |
119 | if keywords then | |
120 | user_keywords = tablex.makeset(keywords) | |
121 | end | |
122 | end | |
123 | ||
113 | 124 | return prettify |
114 | 125 |
232 | 232 | 'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler', |
233 | 233 | 'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles', |
234 | 234 | 'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references', |
235 | 'dont_escape_underscore','global_lookup','prettify_files','convert_opt' | |
235 | 'dont_escape_underscore','global_lookup','prettify_files','convert_opt', 'user_keywords', | |
236 | 236 | } |
237 | 237 | ldoc_contents = tablex.makeset(ldoc_contents) |
238 | 238 | |
503 | 503 | -- (this also will initialize the code prettifier used) |
504 | 504 | override ('format','plain') |
505 | 505 | override 'pretty' |
506 | ldoc.markup = markup.create(ldoc, args.format,args.pretty) | |
506 | ldoc.markup = markup.create(ldoc, args.format, args.pretty, ldoc.user_keywords) | |
507 | 507 | |
508 | 508 | ------ 'Special' Project-level entities --------------------------------------- |
509 | 509 | -- Examples and Topics do not contain code to be processed for doc comments. |