Issue #174: @include tag for including processed documentation file into output; last item now has a distinct line number, and some nasty tabs have been removed
steve donovan
9 years ago
| 15 | 15 | |
| 16 | 16 | -- these are the basic tags known to ldoc. They come in several varieties: |
| 17 | 17 | -- - 'M' tags with multiple values like 'param' (TAG_MULTI) |
| 18 | -- - 'ML' tags which have a single multi-lined value like 'usage' (TAG_MULTI_LINE) | |
| 18 | 19 | -- - 'id' tags which are identifiers, like 'name' (TAG_ID) |
| 19 | 20 | -- - 'S' tags with a single value, like 'release' (TAG_SINGLE) |
| 20 | 21 | -- - 'N' tags which have no associated value, like 'local` (TAG_FLAG) |
| 24 | 25 | class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id', |
| 25 | 26 | copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S', |
| 26 | 27 | fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S', |
| 27 | ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N'; | |
| 28 | ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N',include = 'S', | |
| 28 | 29 | -- project-level |
| 29 | 30 | module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T', file='T', |
| 30 | 31 | -- module-level |
| 40 | 41 | topic = true, |
| 41 | 42 | submodule = true, |
| 42 | 43 | classmod = true, |
| 43 | file = true, | |
| 44 | file = true, | |
| 44 | 45 | } |
| 45 | 46 | |
| 46 | 47 | known_tags._code_types = { |
| 86 | 86 | <h1>$(ldoc.module_typename(module)) <code>$(module.name)</code></h1> |
| 87 | 87 | <p>$(M(module.summary,module))</p> |
| 88 | 88 | <p>$(M(module.description,module))</p> |
| 89 | # if module.tags.include then | |
| 90 | $(M(ldoc.include_file(module.tags.include))) | |
| 91 | # end | |
| 89 | 92 | # if module.usage then |
| 90 | 93 | # local li,il = use_li(module.usage) |
| 91 | 94 | <h3>Usage:</h3> |
| 151 | 151 | end |
| 152 | 152 | return base..name..'.html' |
| 153 | 153 | end |
| 154 | ||
| 155 | -- these references are never from the index...? | |
| 156 | function ldoc.source_ref (fun) | |
| 157 | local modname = fun.module.name | |
| 158 | local pack,name = tools.split_dotted_name(modname) | |
| 159 | if not pack then | |
| 160 | name = modname | |
| 161 | end | |
| 162 | return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno | |
| 163 | end | |
| 154 | ||
| 155 | function ldoc.include_file (file) | |
| 156 | local text,e = utils.readfile(file) | |
| 157 | if not text then quit("unable to include "..file) | |
| 158 | else | |
| 159 | return text | |
| 160 | end | |
| 161 | end | |
| 162 | ||
| 163 | -- these references are never from the index...? | |
| 164 | function ldoc.source_ref (fun) | |
| 165 | local modname = fun.module.name | |
| 166 | local pack,name = tools.split_dotted_name(modname) | |
| 167 | if not pack then | |
| 168 | name = modname | |
| 169 | end | |
| 170 | return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno | |
| 171 | end | |
| 164 | 172 | |
| 165 | 173 | function ldoc.use_li(ls) |
| 166 | 174 | if #ls > 1 then return '<li>','</li>' else return '','' end |
| 241 | 249 | end |
| 242 | 250 | return names |
| 243 | 251 | end |
| 244 | ||
| 245 | -- the somewhat tangled logic that controls whether a type appears in the | |
| 246 | -- navigation sidebar. (At least it's no longer in the template ;)) | |
| 247 | function ldoc.allowed_in_contents(type,module) | |
| 248 | local allowed = true | |
| 249 | if ldoc.kinds_allowed then | |
| 250 | allowed = ldoc.kinds_allowed[type] | |
| 251 | elseif ldoc.prettify_files and type == 'file' then | |
| 252 | allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file') | |
| 253 | end | |
| 254 | return allowed | |
| 255 | end | |
| 252 | ||
| 253 | -- the somewhat tangled logic that controls whether a type appears in the | |
| 254 | -- navigation sidebar. (At least it's no longer in the template ;)) | |
| 255 | function ldoc.allowed_in_contents(type,module) | |
| 256 | local allowed = true | |
| 257 | if ldoc.kinds_allowed then | |
| 258 | allowed = ldoc.kinds_allowed[type] | |
| 259 | elseif ldoc.prettify_files and type == 'file' then | |
| 260 | allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file') | |
| 261 | end | |
| 262 | return allowed | |
| 263 | end | |
| 256 | 264 | |
| 257 | 265 | local function set_charset (ldoc,m) |
| 258 | 266 | m = m or ldoc.module |
| 353 | 353 | |
| 354 | 354 | -- end of a block of document comments |
| 355 | 355 | if ldoc_comment and tags then |
| 356 | local line = t ~= nil and lineno() | |
| 356 | local line = lineno() | |
| 357 | 357 | if t ~= nil then |
| 358 | 358 | if item_follows then -- parse the item definition |
| 359 | 359 | local err = item_follows(tags,tok) |
| 0 | -- must have explicit optchain! | |
| 1 | convert_opt=true | |
| 2 | format = 'markdown' | |
| 3 | -- want to include project source as well. | |
| 4 | prettify_files='show' | |
| 5 |
| 0 | ------------ | |
| 1 | -- Functions with options. | |
| 2 | -- @include opt.md | |
| 3 | ||
| 4 | ---- testing [opt] | |
| 5 | -- @param one | |
| 6 | -- @param[opt] two | |
| 7 | -- @param[opt]three | |
| 8 | -- @param[opt] four | |
| 9 | function use_opt (one,two,three,four) | |
| 10 | end | |
| 11 | ||
| 12 | --- an explicit table. | |
| 13 | -- Can now use tparam aliases in table defns | |
| 14 | -- @string name | |
| 15 | -- @int[opt=0] age | |
| 16 | -- @table person2 | |
| 17 |
| 0 | By default, an unbroken series of opt modifiers is converted to | |
| 1 | 'opt','optchain','optchain', so you get `(a[,b[,c])`. | |
| 2 | ||
| 3 | If `convert_opt` is specified, then no such conversion takes place; you then | |
| 4 | must explicitly use `optchain`. | |
| 5 | ||
| 6 | The `@include` tag is only meaningful for project-level items like modules, | |
| 7 | scripts, etc. The file is inserted into the document after being formatted. | |
| 8 | In this case, you would usually specify `format="markdown"`. |