diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lua-filters.md | 234 |
1 files changed, 145 insertions, 89 deletions
diff --git a/doc/lua-filters.md b/doc/lua-filters.md index fda74c06f..a78455577 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -4099,18 +4099,22 @@ Usage: print('type of metavalue `author`:', pandoc.utils.type(meta.author)) end +<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.mediabag --> + # Module pandoc.mediabag The `pandoc.mediabag` module allows accessing pandoc's media storage. The "media bag" is used when pandoc is called with the `--extract-media` or (for HTML only) `--embed-resources` option. -The module is loaded as part of module `pandoc` and can either -be accessed via the `pandoc.mediabag` field, or explicitly -required, e.g.: +The module is loaded as part of module `pandoc` and can either be +accessed via the `pandoc.mediabag` field, or explicitly required, +e.g.: local mb = require 'pandoc.mediabag' +## Functions {#pandoc.mediabag-functions} + ### delete {#pandoc.mediabag.delete} `delete (filepath)` @@ -4120,8 +4124,10 @@ Removes a single entry from the media bag. Parameters: `filepath` -: filename of the item to be deleted. The media bag will be - left unchanged if no entry with the given filename exists. +: Filename of the item to deleted. The media bag will be left + unchanged if no entry with the given filename exists. (string) + +*Since: 2.7.3* ### empty {#pandoc.mediabag.empty} @@ -4129,50 +4135,88 @@ Parameters: Clear-out the media bag, deleting all items. +*Since: 2.7.3* + +### fetch {#pandoc.mediabag.fetch} + +`fetch (source)` + +Fetches the given source from a URL or local file. Returns two +values: the contents of the file and the MIME type (or an empty +string). + +The function will first try to retrieve `source` from the +mediabag; if that fails, it will try to download it or read it +from the local file system while respecting pandoc's "resource +path" setting. + +Usage: + + local diagram_url = 'https://pandoc.org/diagram.jpg' + local mt, contents = pandoc.mediabag.fetch(diagram_url) + +Parameters: + +`source` +: path to a resource; either a local file path or URI (string) + +Returns: + +- The entry's MIME type, or `nil` if the file was not found. + (string) +- Contents of the file, or `nil` if the file was not found. + (string) + +*Since: 2.0* + ### fill {#pandoc.mediabag.fill} `fill (doc)` -Fills the mediabag with the images in the given document. An -image that cannot be retrieved will be replaced with a Span of -class "image" that contains the image description. +Fills the mediabag with the images in the given document. An image +that cannot be retrieved will be replaced with a Span of class +"image" that contains the image description. -Images for which the mediabag already contains an item will -not be processed again. +Images for which the mediabag already contains an item will not be +processed again. Parameters: `doc` -: document from which to fill the mediabag ([Pandoc](#type-pandoc)) +: document from which to fill the mediabag ([Pandoc]) Returns: -- modified document ([Pandoc](#type-pandoc)) +- modified document ([Pandoc]) + +*Since: 2.19* ### insert {#pandoc.mediabag.insert} -`insert (filepath, mime_type, contents)` +`insert (filepath, mimetype, contents)` Adds a new entry to pandoc's media bag. Replaces any existing -mediabag entry with the same `filepath`. +media bag entry the same `filepath`. + +Usage: + + local fp = 'media/hello.txt' + local mt = 'text/plain' + local contents = 'Hello, World!' + pandoc.mediabag.insert(fp, mt, contents) Parameters: `filepath` -: filename and path relative to the output folder. +: filename and path relative to the output folder. (string) -`mime_type` -: the file's MIME type; use `nil` if unknown or unavailable. +`mimetype` +: the item's MIME type; omit if unknown or unavailable. (string) `contents` -: the binary contents of the file. +: the binary contents of the file. (string) -Usage: - - local fp = "media/hello.txt" - local mt = "text/plain" - local contents = "Hello, World!" - pandoc.mediabag.insert(fp, mt, contents) +*Since: 2.0* ### items {#pandoc.mediabag.items} @@ -4185,15 +4229,7 @@ processed one-by-one to avoid excessive memory use. This function should be used only when full access to all items, including their contents, is required. For all other cases, -[`list`](#pandoc.mediabag.list) should be preferred. - -Returns: - -- The iterator function; must be called with the iterator - state and the current iterator value. -- Iterator state -- an opaque value to be passed to the - iterator function. -- Initial iterator value. +[`list`] should be preferred. Usage: @@ -4201,17 +4237,24 @@ Usage: -- print(fp, mt, contents) end +Returns: + +Iterator triple: + +- The iterator function; must be called with the iterator state + and the current iterator value. +- Iterator state -- an opaque value to be passed to the iterator + function. +- Initial iterator value. + +*Since: 2.7.3* + ### list {#pandoc.mediabag.list} `list ()` Get a summary of the current media bag contents. -Returns: A list of elements summarizing each entry in the media -bag. The summary item contains the keys `path`, `type`, and -`length`, giving the filepath, MIME type, and length of contents -in bytes, respectively. - Usage: -- calculate the size of the media bag. @@ -4222,55 +4265,40 @@ Usage: end print(sum) -### lookup {#pandoc.mediabag.lookup} - -`lookup (filepath)` +Returns: -Lookup a media item in the media bag, and return its MIME type -and contents. +- A list of elements summarizing each entry in the media bag. + The summary item contains the keys `path`, `type`, and + `length`, giving the filepath, MIME type, and length of + contents in bytes, respectively. (table) -Parameters: +*Since: 2.0* -`filepath` -: name of the file to look up. +### lookup {#pandoc.mediabag.lookup} -Returns: +`lookup (filepath)` -- the entry's MIME type, or nil if the file was not found. -- contents of the file, or nil if the file was not found. +Lookup a media item in the media bag, and return its MIME type and +contents. Usage: - local filename = "media/diagram.png" + local filename = 'media/diagram.png' local mt, contents = pandoc.mediabag.lookup(filename) -### fetch {#pandoc.mediabag.fetch} - -`fetch (source)` - -Fetches the given source from a URL or local file. Returns two -values: the contents of the file and the MIME type (or an empty -string). - -The function will first try to retrieve `source` from the -mediabag; if that fails, it will try to download it or read it -from the local file system while respecting pandoc's "resource -path" setting. - Parameters: -`source` -: path to a resource; either a local file path or URI +`filepath` +: name of the file to look up. (string) Returns: -- the entries MIME type, or nil if the file was not found. -- contents of the file, or nil if the file was not found. +- The entry's MIME type, or nil if the file was not found. + (string) +- Contents of the file, or nil if the file was not found. + (string) -Usage: - - local diagram_url = "https://pandoc.org/diagram.jpg" - local mt, contents = pandoc.mediabag.fetch(diagram_url) +*Since: 2.0* ### write {#pandoc.mediabag.write} @@ -4290,7 +4318,9 @@ Parameters: `fp` : canonical name (relative path) of resource (string) -Since: *3.0* +*Since: 3.0* + +<!-- END: AUTOGENERATED CONTENT --> # Module pandoc.List @@ -4493,13 +4523,15 @@ Parameters: `comp` : Comparison function as described above. +<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.format --> + # Module pandoc.format Information about the formats supported by pandoc. ## Functions {#pandoc.format-functions} -### all_extensions {#pandoc.format.default_extensions} +### all_extensions {#pandoc.format.all_extensions} `all_extensions (format)` @@ -4515,7 +4547,10 @@ Parameters: Returns: -- all extensions supported for `format` (FormatExtensions) +- all extensions supported for `format` + ([FormatExtensions]{unknown-type="FormatExtensions"}) + +*Since: 3.0* ### default_extensions {#pandoc.format.default_extensions} @@ -4532,15 +4567,20 @@ Parameters: Returns: -- default extensions enabled for `format` (FormatExtensions) +- default extensions enabled for `format` + ([FormatExtensions]{unknown-type="FormatExtensions"}) + +*Since: 3.0* ### extensions {#pandoc.format.extensions} -Returns the extension configuration for the given format. -The configuration is represented as a table with all supported -extensions as keys and their default status as value, with -`true` indicating that the extension is enabled by default, -while `false` marks a supported extension that's disabled. +`extensions (format)` + +Returns the extension configuration for the given format. The +configuration is represented as a table with all supported +extensions as keys and their default status as value, with `true` +indicating that the extension is enabled by default, while `false` +marks a supported extension that's disabled. This function can be used to assign a value to the `Extensions` global in custom readers and writers. @@ -4552,7 +4592,13 @@ Parameters: Returns: -- extensions config +- extensions config (table) + +*Since: 3.0* + +<!-- END: AUTOGENERATED CONTENT --> + +<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.json --> # Module pandoc.json @@ -4562,7 +4608,7 @@ JSON module to work with JSON; based on the Aeson Haskell package. ### null {#pandoc.json.null} -Value used to represent the `null` JSON value. (userdata) +Value used to represent the `null` JSON value. (light userdata) ## Functions {#pandoc.json-functions} @@ -4574,7 +4620,7 @@ Creates a Lua object from a JSON string. The function returns an [Inline], [Block], [Pandoc], [Inlines], or [Blocks] element if the input can be decoded into represent any of those types. Otherwise the default decoding is applied, using tables, booleans, numbers, -and [null](#pandoc.json.null) to represent the JSON value. +and [null] to represent the JSON value. The special handling of AST elements can be disabled by setting `pandoc_types` to `false`. @@ -4591,6 +4637,8 @@ Returns: - decoded object (any) +*Since: 3.1.1* + ### encode {#pandoc.json.encode} `encode (object)` @@ -4609,7 +4657,11 @@ Parameters: Returns: -- JSON encoding of the given object (string) +- JSON encoding of the given `object` (string) + +*Since: 3.1.1* + +<!-- END: AUTOGENERATED CONTENT --> <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.path --> @@ -4840,8 +4892,8 @@ objects. # Module pandoc.structure -Access to the higher-level document structure, -includinghierarchical sections and the table of contents. +Access to the higher-level document structure, including +hierarchical sections and the table of contents. ## Functions {#pandoc.structure-functions} @@ -6032,11 +6084,15 @@ Returns: <!-- BEGIN: GENERATED REFERENCE LINKS --> - [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html + [Pandoc]: #type-pandoc + [`list`]: #pandoc.mediabag.list + [Inline]: Inline + [Block]: #type-block + [Inlines]: Inlines [Blocks]: #type-blocks + [null]: #pandoc.json.null + [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html [WriterOptions]: #type-writeroptions - [Pandoc]: #type-pandoc [ChunkedDoc]: #type-chunkeddoc - [Block]: #type-block [zip.Entry]: #type-pandoc.zip.Entry [zip.Archive]: #type-pandoc.zip.Archive |