From 87d63bc0a00e29d44f29346e5276263670ae0930 Mon Sep 17 00:00:00 2001 From: Odin Kroeger Date: Sun, 30 May 2021 13:19:35 +0200 Subject: [PATCH] docs: Updated source code documentation. --- docs/index.html | 1057 +++++++++++++++++++--------- docs/scripts/pandoc-zotxt.lua.html | 1057 +++++++++++++++++++--------- docs/topics/README.md.html | 30 +- 3 files changed, 1488 insertions(+), 656 deletions(-) diff --git a/docs/index.html b/docs/index.html index 5b67649..5921ca2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -34,9 +34,9 @@

Contents

  • Warnings
  • Table manipulation
  • Networking
    • +
  • Bibliography files
  • Converters
  • zotxt
    • -
  • Bibliography files
  • Document parsing
  • Main
    • @@ -222,19 +222,23 @@

    Warnings

    Print a message to STDERR. - warnf ([msg], ...) + warnf (...) Print a warning to STDERR.

    Table manipulation

    + + + + - + @@ -248,38 +252,12 @@

    Networking

    rmap (func, data)Recursively apply a function to every value of a tree.
    keys (tab) Return the keys and the length of a table.
    lower_keys (tab)Convert table keys to lowercase recursively.Recursively convert table keys to lowercase.
    sorted_pairs (tab[, func]) Retrieve data from a URL via an HTTP GET request.
    -

    Converters

    - - - - - - - - - -
    rconv_nums_to_strs (data)Convert numbers to strings recursively.
    yamlify (data[, ind=4[, sort_f]])Generate a YAML representation of some data.
    -

    zotxt

    +

    Bibliography files

    - - - - - - - - - - - - - - + + -
    ZOTXT_BASE_URLThe URL to lookup citation data.
    ZOTXT_KEYTYPESTypes of citation keys.
    zotxt_get_item_csl (id)Retrieve a CSL item (for use in bibliography files).
    zotxt_get_item (id)Retrieve a CSL item (for use in the references metadata field).CSL_KEYS_FORMATTABLEThe list of CSL fields that can be formatted.
    -

    Bibliography files

    - @@ -290,15 +268,19 @@

    Bibliography files

    - + - + - + + + + + @@ -345,8 +327,62 @@

    Bibliography files

    CSL_KEY_ORDER The preferred order of keys in YAML bibliography files.
    BIBLIO_TYPES.bibRead BibTeX/BibLaTeX files.Parse BibLaTeX.
    BIBLIO_TYPES.bib.decode (str)Collect item IDs from the content of a BibTeX/BibLaTeX file.Parse the content of a BibLaTeX file.
    BIBLIO_TYPES.bibtexAlternative suffix for BibTeX/BibLaTeX files.Parse BibTeX.
    BIBLIO_TYPES.bibtex.decode (str)Parse the content of a BibTeX file
    BIBLIO_TYPES.json Add items from Zotero to a bibliography file.
    +

    Converters

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    esc_md (str)Escape Markdown.
    markdownify (elem)Convert a Pandoc element to Markdown text.
    yamlify (data[, ind=4[, sort_f]])Generate a YAML representation of some data.
    conv_html_to_md (html)Convert pseudo-HTML to Markdown.
    rconv_html_to_md (item)Recursively convert pseudo-HTML to Markdown.
    rconv_nums_to_strs (data)Recursively convert numbers to strings.
    +

    zotxt

    + + + + + + + + + + + + + + + + + +
    ZOTXT_BASE_URLThe URL to lookup citation data.
    ZOTXT_KEYTYPESTypes of citation keys.
    zotxt_get_item_csl (id)Retrieve a CSL item (for use in bibliography files).
    zotxt_get_item (id)Retrieve a CSL item (for use in the references metadata field).

    Document parsing

    + + + + + + + + @@ -645,8 +681,8 @@

    Or

    nilnil if the file could not be found.
  • - An - error message.
    • + string + An error message. @@ -762,7 +798,7 @@

    Parameters:

    string A template for the filename. 'X's are replaced with random alphanumeric characters. - Cannot be the empty string (''). + Must contain at least six 'X's. (default 'tmp_XXXXXX') @@ -840,7 +876,8 @@

    Usage:

    @@ -870,7 +910,7 @@

    Warnings

    Print a message to STDERR.

    -

    Prefixes the message with PRINTF_PREFIX' and appends EOL`. +

    Prefixes the message with PRINTF_PREFIX and appends EOL.

    Parameters:

    @@ -892,7 +932,7 @@

    Parameters:

    - warnf ([msg], ...) + warnf (...)
    Print a warning to STDERR.

    @@ -903,13 +943,8 @@

    Parameters:

    Parameters:

    @@ -922,6 +957,41 @@

    Parameters:

    Table manipulation

    +
    + + rmap (func, data) +
    +
    + Recursively apply a function to every value of a tree.

    + +

    The function is applied to every node of the data tree. + If a node is a table, the function is applied after recursion. + + +

    Parameters:

    +
      +
    • func + func + A function that takes a value and returns a new one. + Receives the value's key as second argument, if applicable. +
      • +
    • data + A data tree. +
      • +
    + +

    Returns:

    +
      + + data with func applied. +
    + +

    Raises:

    + An error if the data is nested too deeply. + + + +
    keys (tab) @@ -957,7 +1027,7 @@

    Returns:

    lower_keys (tab)
    - Convert table keys to lowercase recursively. + Recursively convert table keys to lowercase.

    Parameters:

    @@ -974,6 +1044,8 @@

    Returns:

    A copy of tab with keys in lowercase. +

    Raises:

    + An error if the data is nested too deeply. @@ -1049,248 +1121,98 @@

    Raises:

    -

    Converters

    +

    Bibliography files

    - - rconv_nums_to_strs (data) + + CSL_KEYS_FORMATTABLE
    - Convert numbers to strings recursively.

    - -

    Also converts floating point numbers to integers. This is needed - because all numbers are floating point numbers in JSON, but some - versions of Pandoc expect integers. - - -

    Parameters:

    -
      -
    • data - tab - The data. -
      • -
    - -

    Returns:

    -
      - - A copy of data with numbers converted to strings. -
    + The list of CSL fields that can be formatted.

    -

    Raises:

    - An error if the data is nested too deeply. - - - -
    -
    - - yamlify (data[, ind=4[, sort_f]]) -
    -
    - Generate a YAML representation of some data.

    +

    This list is a guess!

    -

    Uses EOL to end lines. +

    Appendix IV + of the CSL specification lists all field names. -

    Parameters:

    +

    Fields:

      -
    • data - The data. +
    • abstract + The abstract.
      • -
    • ind - int - How many spaces to indent blocks. - (default 4) +
    • collection-title + E.g., a series.
      • -
    • sort_f - func - A function to sort keys of mappings. - Defaults to sorting them lexically. - (optional) +
    • collection-title-short + A short version of the title. +
      • +
    • container-title + Publication the item was published in. +
      • +
    • container-title-short + A short version of that title. +
      • +
    • original-publisher + Original publisher. +
      • +
    • original-publisher-place + Place the item was originally published in. +
      • +
    • original-title + Original title. +
      • +
    • publisher + Publisher. +
      • +
    • publisher-place + The city/cities the item was published in. +
      • +
    • reviewed-title + Title reviewed in the item. +
      • +
    • title + The title. +
      • +
    • title-short + A short version of the title. +
      • +
    • short-title + Ditto.
    -

    Returns:

    -
      - - string - A YAML string. -
    -

    Or

    -
      -
    1. - nil - nil if the data cannot be represented in YAML.
      2. -
    2. - An - error message.
      3. -
    - -

    Raises:

    - An error if if the data is nested too deeply. - - - -
    -
    -

    zotxt

    - -
    -
    - - ZOTXT_BASE_URL -
    -
    - The URL to lookup citation data.

    - -

    See https://github.com/egh/zotxt for details. - - - +

    See also:

    +
    - - ZOTXT_KEYTYPES + + CSL_KEY_ORDER
    - Types of citation keys.

    + The preferred order of keys in YAML bibliography files.

    -

    See https://github.com/egh/zotxt for details. +

    Appendix IV + of the CSL specification lists all field names.

    Fields:

      -
    • key - Zotero item ID +
    • id + Item ID.
      • -
    • betterbibtexkey - Better BibTeX citation key +
    • type + For example, 'paper', 'book'.
      • -
    • easykey - zotxt easy citekey -
      • -
    - - - - - -
    -
    - - zotxt_get_item_csl (id) -
    -
    - Retrieve a CSL item (for use in bibliography files).

    - -

    Returns bibliographic data as a Lua table. The retrieved item can be - passed to biblio_write; it should not be used in the references - metadata field (unless you are using Pandoc prior to v2.11). - - -

    Parameters:

    -
      -
    • id - string - An item ID, e.g., 'name:2019word', 'name2019TwoWords'. -
      • -
    - -

    Returns:

    -
      - - table - A CSL item. -
    -

    Or

    -
      -
    1. - nil - nil if an error occurred.
      2. -
    2. - string - An error message.
      3. -
    - -

    Raises:

    - See zotxt_get_item. - - - -
    -
    - - zotxt_get_item (id) -
    -
    - Retrieve a CSL item (for use in the references metadata field).

    - -

    Returns bibliographic data as Pandoc metadata. That retrieved item - can be used in the references metadata field; it should not be - passed to biblio_write. - - -

    Parameters:

    -
      -
    • id - string - An item ID, e.g., 'name:2019word', 'name2019TwoWords'. -
      • -
    - -

    Returns:

    -
      - - pandoc.MetaMap - A CSL item. -
    -

    Or

    -
      -
    1. - nil - nil if an error occurred.
      2. -
    2. - string - An error message.
      3. -
    - -

    Raises:

    - See zotxt_get_item. - - - -
    -
    -

    Bibliography files

    - -
    -
    - - CSL_KEY_ORDER -
    -
    - The preferred order of keys in YAML bibliography files.

    - -

    See appendix IV - of the CSL specification and csl_keys_sort for details. - - -

    Fields:

    -
      -
    • id - Item ID. -
      • -
    • type - For example, 'paper', 'book'. -
      • -
    • author - Author(s). +
    • author + Author(s).
    • recipient Recipient of the document. @@ -1304,16 +1226,19 @@

      Fields:

    • title The title.
      • -
    • short-title +
    • title-short A short version of the title.
      • -
    • abstract - The abstract. +
    • short-title + Ditto. +
      • +
    • original-title + Original title.
    • translator Translator(s).
      • -
    • collection-editor +
    • editor Editor(s).
    • container-title @@ -1322,6 +1247,15 @@

      Fields:

    • container-title-short A short version of that title.
      • +
    • collection-editor + E.g., series editor(s). +
      • +
    • collection-title + E.g., a series. +
      • +
    • collection-title-short + A short version of the title. +
    • edition Container's edition.
      • @@ -1341,7 +1275,13 @@

      Fields:

      Publisher.
    • publisher-place - The city/cities the item was published in. + City/cities the item was published in. +
      • +
    • original-publisher + Original publisher. +
      • +
    • original-publisher-place + Place the item was originally published in.
    • doi The DOI. @@ -1370,10 +1310,17 @@

      Fields:

    • language Language the item is in.
      • +
    • abstract + The abstract. +
    +

    See also:

    +
    @@ -1398,7 +1345,7 @@

    Fields:

    BIBLIO_TYPES.bib
    - Read BibTeX/BibLaTeX files. + Parse BibLaTeX. @@ -1412,22 +1359,30 @@

    Fields:

    BIBLIO_TYPES.bib.decode (str)
    - Collect item IDs from the content of a BibTeX/BibLaTeX file. + Parse the content of a BibLaTeX file.

    Parameters:

    • str string - The content of a BibTeX/BibLaTeX file. + The content of a BibLaTeX file.

    Returns:

      + {table,...} + A list of CSL items + if you use Pandoc v2.11 or later. +
    +

    Or

    +
      + {{id=string},...} - A list of item IDs. + A list of item IDs + if you use an earlier version of Pandoc.
    @@ -1439,10 +1394,45 @@

    Returns:

    BIBLIO_TYPES.bibtex
    - Alternative suffix for BibTeX/BibLaTeX files. + Parse BibTeX. + + + + + + + +
    +
    + + BIBLIO_TYPES.bibtex.decode (str) +
    +
    + Parse the content of a BibTeX file + + +

    Parameters:

    +
      +
    • str + string + The content of a BibTeX file. +
      • +
    +

    Returns:

    +
      + {table,...} + A list of CSL items + if you use Pandoc v2.11 or later. +
    +

    Or

    +
      + {{id=string},...} + A list of item IDs + if you use an earlier version of Pandoc. +
    @@ -1787,35 +1777,34 @@

    Raises:

    -

    Document parsing

    +

    Converters

    - - meta_get_sources (meta) + + esc_md (str)
    - Collect sources from the document's metadata block.

    + Escape Markdown.

    -

    Reads the references metafata field and every bibliography file - referenced by the bibliography metadata field.

    +

    Only escapes Markdown that Pandoc recognises in bibliographic data.

    -

    Prints errors to STDERR if it cannot parse a bibliography file. +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data.

    Parameters:

      -
    • meta - tab - A metadata block. +
    • str + string + A string.

    Returns:

      - pandoc.List - A list of CSL items. + string + str with Markdown escaped.
    @@ -1823,26 +1812,60 @@

    Returns:

    - - doc_get_ckeys (doc[, flags]) + + markdownify (elem)
    - Collect the citation keys used in a document.

    + Convert a Pandoc element to Markdown text.

    -

    Prints errors to STDERR if it cannot parse a bibliography file. +

    Only recognises elements that are permitted in bibliographic data.

    + +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data.

    Parameters:

      -
    • doc - tab - A document. +
    • elem + pandoc.AstElement + A Pandoc AST element.
      • -
    • flags - string - If the flag 'u' is given, collects only citation keys - of sources that are neither defined in the references metadata field - nor in any bibliography file. +
    + +

    Returns:

    +
      + + string + Markdown text. +
    + + + + +
    +
    + + yamlify (data[, ind=4[, sort_f]]) +
    +
    + Generate a YAML representation of some data.

    + +

    Uses EOL to end lines. + + +

    Parameters:

    +
      +
    • data + The data. +
      • +
    • ind + int + How many spaces to indent blocks. + (default 4) +
      • +
    • sort_f + func + A function to sort keys of mappings. + Defaults to sorting them lexically. (optional)
    @@ -1850,52 +1873,444 @@

    Parameters:

    Returns:

      - {string,...} - A list of citation keys. + string + A YAML string. +
    +

    Or

    +
      +
    1. + nil + nil if the data cannot be represented in YAML.
      2. +
    2. + string + An error message.

    Raises:

    - An error if an item ID is of an illegal data type. + An error if the data is nested too deeply.
    -
    -

    Main

    - -
    - - add_biblio (meta, ckeys) + + conv_html_to_md (html)
    - Add sources to a bibliography file and the file to the document's metadata.

    + Convert pseudo-HTML to Markdown.

    -

    Updates the bibliography file as needed and adds it to the bibliography - metadata field. Interpretes a relative filename as relative to the - directory of the first input file passed to pandoc, not as relative - to the current working directory (unless no input files are given). +

    Only supports the HTML tags that Zotero and Pandoc support.

    + +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data + and https://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields.

    Parameters:

      -
    • meta - tab - A metadata block, with the field - zotero-bibliography set to the filename of the bibliography file. -
      • -
    • ckeys - tab - The citaton keys of the items that should be added, - e.g., {'name:2019word', 'name2019WordWordWord'}. - Citation keys are just item IDs. +
    • html + string + Text that contains pseudo-HTML tags.

    Returns:

      - table + string + Text formatted in Markdown. +
    + + + + +
    +
    + + rconv_html_to_md (item) +
    +
    + Recursively convert pseudo-HTML to Markdown.

    + +

    Only changes fields listed in CSL_KEYS_FORMATTABLE. + + +

    Parameters:

    +
      +
    • item + tab + A CSL item. +
      • +
    + +

    Returns:

    +
      + + tab + The CSL item, with pseudo-HTML replaced with Markdown. +
    + + +

    See also:

    + + + +
    +
    + + rconv_nums_to_strs (data) +
    +
    + Recursively convert numbers to strings.

    + +

    Also converts floating point numbers to integers. This is needed + because all numbers are floating point numbers in JSON, but some + versions of Pandoc expect integers. + + +

    Parameters:

    +
      +
    • data + tab + The data. +
      • +
    + +

    Returns:

    +
      + + A copy of data with numbers converted to strings. +
    + +

    Raises:

    + An error if the data is nested too deeply. + + + +
    +
    +

    zotxt

    + +
    +
    + + ZOTXT_BASE_URL +
    +
    + The URL to lookup citation data.

    + +

    See https://github.com/egh/zotxt for details. + + + + + + + +

    +
    + + ZOTXT_KEYTYPES +
    +
    + Types of citation keys.

    + +

    See https://github.com/egh/zotxt for details. + + +

    Fields:

    +
      +
    • key + Zotero item ID +
      • +
    • betterbibtexkey + Better BibTeX citation key +
      • +
    • easykey + zotxt easy citekey +
      • +
    + + + + + +
    +
    + + zotxt_get_item_csl (id) +
    +
    + Retrieve a CSL item (for use in bibliography files).

    + +

    Returns bibliographic data as a Lua table. The retrieved item can be + passed to biblio_write; it should not be used in the references + metadata field (unless you are using Pandoc prior to v2.11). + + +

    Parameters:

    +
      +
    • id + string + An item ID, e.g., 'name:2019word', 'name2019TwoWords'. +
      • +
    + +

    Returns:

    +
      + + table + A CSL item. +
    +

    Or

    +
      +
    1. + nil + nil if an error occurred.
      2. +
    2. + string + An error message.
      3. +
    + +

    Raises:

    + See zotxt_get_item. + + + +
    +
    + + zotxt_get_item (id) +
    +
    + Retrieve a CSL item (for use in the references metadata field).

    + +

    Returns bibliographic data as Pandoc metadata. That retrieved item + can be used in the references metadata field; it should not be + passed to biblio_write. + + +

    Parameters:

    +
      +
    • id + string + An item ID, e.g., 'name:2019word', 'name2019TwoWords'. +
      • +
    + +

    Returns:

    +
      + + pandoc.MetaMap + A CSL item. +
    +

    Or

    +
      +
    1. + nil + nil if an error occurred.
      2. +
    2. + string + An error message.
      3. +
    + +

    Raises:

    + See zotxt_get_item. + + + +
    +
    +

    Document parsing

    + +
    +
    + + elem_type (elem) +
    +
    + The type of a Pandoc AST element. + + +

    Parameters:

    +
      +
    • elem + pandoc.AstElement + A Pandoc AST element. +
      • +
    + +

    Returns:

    +
      +
    1. + string + The type + (e.g., 'MetaMap', 'Plain').
      2. +
    2. + string + The high-order kind + (i.e., 'Block', 'Inline', or 'MetaValue').
      3. +
    3. + string + The literal 'AstElement'.
      4. +
    +

    Or

    +
      + + nil + nil if elem is not a Pandoc AST element. +
    + + + + +
    +
    + + walk (elem, filter) +
    +
    + Walk the AST and apply functions to matching elements.

    + +

    Differs from pandoc.walk_block and pandoc.walk_inline by accepting + AST elements of any type (i.e., including documents as a whole, the + metadata block, and metadata fields), by applying the filter to the + given element itself, by walking the AST bottom-up (which implies that + the filter is applied to every node, regardless of whether any of that + node's ancestors matches it), and by allowing the functions in the + filter to return arbitrary data (as opposed to either a Pandoc AST + element type or nil). Use with caution. + + +

    Parameters:

    +
      +
    • elem + pandoc.AstElement + A Pandoc AST element. +
      • +
    • filter + {string=func,...} + A filter. +
      • +
    + +

    Returns:

    +
      + + The element, with the filter applied. +
    + + + + +
    +
    + + meta_get_sources (meta) +
    +
    + Collect sources from the document's metadata block.

    + +

    Reads the references metafata field and every bibliography file + referenced by the bibliography metadata field.

    + +

    Prints errors to STDERR if it cannot parse a bibliography file. + + +

    Parameters:

    +
      +
    • meta + tab + A metadata block. +
      • +
    + +

    Returns:

    +
      + + pandoc.List + A list of CSL items. +
    + + + + +
    +
    + + doc_get_ckeys (doc[, flags]) +
    +
    + Collect the citation keys used in a document.

    + +

    Prints errors to STDERR if it cannot parse a bibliography file. + + +

    Parameters:

    +
      +
    • doc + tab + A document. +
      • +
    • flags + string + If the flag 'u' is given, collects only citation keys + of sources that are neither defined in the references metadata field + nor in any bibliography file. + (optional) +
      • +
    + +

    Returns:

    +
      + + {string,...} + A list of citation keys. +
    + +

    Raises:

    + An error if an item ID is of an illegal data type. + + + +
    +
    +

    Main

    + +
    +
    + + add_biblio (meta, ckeys) +
    +
    + Add sources to a bibliography file and the file to the document's metadata.

    + +

    Updates the bibliography file as needed and adds it to the bibliography + metadata field. Interpretes a relative filename as relative to the + directory of the first input file passed to pandoc, not as relative + to the current working directory (unless no input files are given). + + +

    Parameters:

    +
      +
    • meta + tab + A metadata block, with the field + zotero-bibliography set to the filename of the bibliography file. +
      • +
    • ckeys + tab + The citaton keys of the items that should be added, + e.g., {'name:2019word', 'name2019WordWordWord'}. + Citation keys are just item IDs. +
      • +
    + +

    Returns:

    +
      + + tab An updated metadata block, with the field bibliography added if needed.
    @@ -2009,7 +2424,7 @@

    Raises:

    generated by LDoc 1.4.6 -Last updated 2021-05-15 22:05:07 +Last updated 2021-05-30 13:19:10
    diff --git a/docs/scripts/pandoc-zotxt.lua.html b/docs/scripts/pandoc-zotxt.lua.html index fec3aa3..878b323 100644 --- a/docs/scripts/pandoc-zotxt.lua.html +++ b/docs/scripts/pandoc-zotxt.lua.html @@ -34,9 +34,9 @@

    Contents

  • Warnings
  • Table manipulation
  • Networking
    • +
  • Bibliography files
  • Converters
  • zotxt
    • -
  • Bibliography files
  • Document parsing
  • Main
    • @@ -222,19 +222,23 @@

    Warnings

    - +
    elem_type (elem)The type of a Pandoc AST element.
    walk (elem, filter)Walk the AST and apply functions to matching elements.
    meta_get_sources (meta) Collect sources from the document's metadata block. Print a message to STDERR.
    warnf ([msg], ...)warnf (...) Print a warning to STDERR.

    Table manipulation

    + + + + - + @@ -248,38 +252,12 @@

    Networking

    rmap (func, data)Recursively apply a function to every value of a tree.
    keys (tab) Return the keys and the length of a table.
    lower_keys (tab)Convert table keys to lowercase recursively.Recursively convert table keys to lowercase.
    sorted_pairs (tab[, func]) Retrieve data from a URL via an HTTP GET request.
    -

    Converters

    - - - - - - - - - -
    rconv_nums_to_strs (data)Convert numbers to strings recursively.
    yamlify (data[, ind=4[, sort_f]])Generate a YAML representation of some data.
    -

    zotxt

    +

    Bibliography files

    - - - - - - - - - - - - - - + + -
    ZOTXT_BASE_URLThe URL to lookup citation data.
    ZOTXT_KEYTYPESTypes of citation keys.
    zotxt_get_item_csl (id)Retrieve a CSL item (for use in bibliography files).
    zotxt_get_item (id)Retrieve a CSL item (for use in the references metadata field).CSL_KEYS_FORMATTABLEThe list of CSL fields that can be formatted.
    -

    Bibliography files

    - @@ -290,15 +268,19 @@

    Bibliography files

    - + - + - + + + + + @@ -345,8 +327,62 @@

    Bibliography files

    CSL_KEY_ORDER The preferred order of keys in YAML bibliography files.
    BIBLIO_TYPES.bibRead BibTeX/BibLaTeX files.Parse BibLaTeX.
    BIBLIO_TYPES.bib.decode (str)Collect item IDs from the content of a BibTeX/BibLaTeX file.Parse the content of a BibLaTeX file.
    BIBLIO_TYPES.bibtexAlternative suffix for BibTeX/BibLaTeX files.Parse BibTeX.
    BIBLIO_TYPES.bibtex.decode (str)Parse the content of a BibTeX file
    BIBLIO_TYPES.json Add items from Zotero to a bibliography file.
    +

    Converters

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    esc_md (str)Escape Markdown.
    markdownify (elem)Convert a Pandoc element to Markdown text.
    yamlify (data[, ind=4[, sort_f]])Generate a YAML representation of some data.
    conv_html_to_md (html)Convert pseudo-HTML to Markdown.
    rconv_html_to_md (item)Recursively convert pseudo-HTML to Markdown.
    rconv_nums_to_strs (data)Recursively convert numbers to strings.
    +

    zotxt

    + + + + + + + + + + + + + + + + + +
    ZOTXT_BASE_URLThe URL to lookup citation data.
    ZOTXT_KEYTYPESTypes of citation keys.
    zotxt_get_item_csl (id)Retrieve a CSL item (for use in bibliography files).
    zotxt_get_item (id)Retrieve a CSL item (for use in the references metadata field).

    Document parsing

    + + + + + + + + @@ -645,8 +681,8 @@

    Or

    nilnil if the file could not be found.
  • - An - error message.
    • + string + An error message. @@ -762,7 +798,7 @@

    Parameters:

    string A template for the filename. 'X's are replaced with random alphanumeric characters. - Cannot be the empty string (''). + Must contain at least six 'X's. (default 'tmp_XXXXXX') @@ -840,7 +876,8 @@

    Usage:

    @@ -870,7 +910,7 @@

    Warnings

    Print a message to STDERR.

    -

    Prefixes the message with PRINTF_PREFIX' and appends EOL`. +

    Prefixes the message with PRINTF_PREFIX and appends EOL.

    Parameters:

    @@ -892,7 +932,7 @@

    Parameters:

    - warnf ([msg], ...) + warnf (...)
    Print a warning to STDERR.

    @@ -903,13 +943,8 @@

    Parameters:

    Parameters:

    @@ -922,6 +957,41 @@

    Parameters:

    Table manipulation

    +
    + + rmap (func, data) +
    +
    + Recursively apply a function to every value of a tree.

    + +

    The function is applied to every node of the data tree. + If a node is a table, the function is applied after recursion. + + +

    Parameters:

    +
      +
    • func + func + A function that takes a value and returns a new one. + Receives the value's key as second argument, if applicable. +
      • +
    • data + A data tree. +
      • +
    + +

    Returns:

    +
      + + data with func applied. +
    + +

    Raises:

    + An error if the data is nested too deeply. + + + +
    keys (tab) @@ -957,7 +1027,7 @@

    Returns:

    lower_keys (tab)
    - Convert table keys to lowercase recursively. + Recursively convert table keys to lowercase.

    Parameters:

    @@ -974,6 +1044,8 @@

    Returns:

    A copy of tab with keys in lowercase. +

    Raises:

    + An error if the data is nested too deeply. @@ -1049,248 +1121,98 @@

    Raises:

    -

    Converters

    +

    Bibliography files

    - - rconv_nums_to_strs (data) + + CSL_KEYS_FORMATTABLE
    - Convert numbers to strings recursively.

    - -

    Also converts floating point numbers to integers. This is needed - because all numbers are floating point numbers in JSON, but some - versions of Pandoc expect integers. - - -

    Parameters:

    -
      -
    • data - tab - The data. -
      • -
    - -

    Returns:

    -
      - - A copy of data with numbers converted to strings. -
    + The list of CSL fields that can be formatted.

    -

    Raises:

    - An error if the data is nested too deeply. - - - -
    -
    - - yamlify (data[, ind=4[, sort_f]]) -
    -
    - Generate a YAML representation of some data.

    +

    This list is a guess!

    -

    Uses EOL to end lines. +

    Appendix IV + of the CSL specification lists all field names. -

    Parameters:

    +

    Fields:

      -
    • data - The data. +
    • abstract + The abstract.
      • -
    • ind - int - How many spaces to indent blocks. - (default 4) +
    • collection-title + E.g., a series.
      • -
    • sort_f - func - A function to sort keys of mappings. - Defaults to sorting them lexically. - (optional) +
    • collection-title-short + A short version of the title. +
      • +
    • container-title + Publication the item was published in. +
      • +
    • container-title-short + A short version of that title. +
      • +
    • original-publisher + Original publisher. +
      • +
    • original-publisher-place + Place the item was originally published in. +
      • +
    • original-title + Original title. +
      • +
    • publisher + Publisher. +
      • +
    • publisher-place + The city/cities the item was published in. +
      • +
    • reviewed-title + Title reviewed in the item. +
      • +
    • title + The title. +
      • +
    • title-short + A short version of the title. +
      • +
    • short-title + Ditto.
    -

    Returns:

    -
      - - string - A YAML string. -
    -

    Or

    -
      -
    1. - nil - nil if the data cannot be represented in YAML.
      2. -
    2. - An - error message.
      3. -
    - -

    Raises:

    - An error if if the data is nested too deeply. - - - -
    -
    -

    zotxt

    - -
    -
    - - ZOTXT_BASE_URL -
    -
    - The URL to lookup citation data.

    - -

    See https://github.com/egh/zotxt for details. - - - +

    See also:

    +
    - - ZOTXT_KEYTYPES + + CSL_KEY_ORDER
    - Types of citation keys.

    + The preferred order of keys in YAML bibliography files.

    -

    See https://github.com/egh/zotxt for details. +

    Appendix IV + of the CSL specification lists all field names.

    Fields:

      -
    • key - Zotero item ID +
    • id + Item ID.
      • -
    • betterbibtexkey - Better BibTeX citation key +
    • type + For example, 'paper', 'book'.
      • -
    • easykey - zotxt easy citekey -
      • -
    - - - - - -
    -
    - - zotxt_get_item_csl (id) -
    -
    - Retrieve a CSL item (for use in bibliography files).

    - -

    Returns bibliographic data as a Lua table. The retrieved item can be - passed to biblio_write; it should not be used in the references - metadata field (unless you are using Pandoc prior to v2.11). - - -

    Parameters:

    -
      -
    • id - string - An item ID, e.g., 'name:2019word', 'name2019TwoWords'. -
      • -
    - -

    Returns:

    -
      - - table - A CSL item. -
    -

    Or

    -
      -
    1. - nil - nil if an error occurred.
      2. -
    2. - string - An error message.
      3. -
    - -

    Raises:

    - See zotxt_get_item. - - - -
    -
    - - zotxt_get_item (id) -
    -
    - Retrieve a CSL item (for use in the references metadata field).

    - -

    Returns bibliographic data as Pandoc metadata. That retrieved item - can be used in the references metadata field; it should not be - passed to biblio_write. - - -

    Parameters:

    -
      -
    • id - string - An item ID, e.g., 'name:2019word', 'name2019TwoWords'. -
      • -
    - -

    Returns:

    -
      - - pandoc.MetaMap - A CSL item. -
    -

    Or

    -
      -
    1. - nil - nil if an error occurred.
      2. -
    2. - string - An error message.
      3. -
    - -

    Raises:

    - See zotxt_get_item. - - - -
    -
    -

    Bibliography files

    - -
    -
    - - CSL_KEY_ORDER -
    -
    - The preferred order of keys in YAML bibliography files.

    - -

    See appendix IV - of the CSL specification and csl_keys_sort for details. - - -

    Fields:

    -
      -
    • id - Item ID. -
      • -
    • type - For example, 'paper', 'book'. -
      • -
    • author - Author(s). +
    • author + Author(s).
    • recipient Recipient of the document. @@ -1304,16 +1226,19 @@

      Fields:

    • title The title.
      • -
    • short-title +
    • title-short A short version of the title.
      • -
    • abstract - The abstract. +
    • short-title + Ditto. +
      • +
    • original-title + Original title.
    • translator Translator(s).
      • -
    • collection-editor +
    • editor Editor(s).
    • container-title @@ -1322,6 +1247,15 @@

      Fields:

    • container-title-short A short version of that title.
      • +
    • collection-editor + E.g., series editor(s). +
      • +
    • collection-title + E.g., a series. +
      • +
    • collection-title-short + A short version of the title. +
    • edition Container's edition.
      • @@ -1341,7 +1275,13 @@

      Fields:

      Publisher.
    • publisher-place - The city/cities the item was published in. + City/cities the item was published in. +
      • +
    • original-publisher + Original publisher. +
      • +
    • original-publisher-place + Place the item was originally published in.
    • doi The DOI. @@ -1370,10 +1310,17 @@

      Fields:

    • language Language the item is in.
      • +
    • abstract + The abstract. +
    +

    See also:

    +
    @@ -1398,7 +1345,7 @@

    Fields:

    BIBLIO_TYPES.bib
    - Read BibTeX/BibLaTeX files. + Parse BibLaTeX. @@ -1412,22 +1359,30 @@

    Fields:

    BIBLIO_TYPES.bib.decode (str)
    - Collect item IDs from the content of a BibTeX/BibLaTeX file. + Parse the content of a BibLaTeX file.

    Parameters:

    • str string - The content of a BibTeX/BibLaTeX file. + The content of a BibLaTeX file.

    Returns:

      + {table,...} + A list of CSL items + if you use Pandoc v2.11 or later. +
    +

    Or

    +
      + {{id=string},...} - A list of item IDs. + A list of item IDs + if you use an earlier version of Pandoc.
    @@ -1439,10 +1394,45 @@

    Returns:

    BIBLIO_TYPES.bibtex
    - Alternative suffix for BibTeX/BibLaTeX files. + Parse BibTeX. + + + + + + + +
    +
    + + BIBLIO_TYPES.bibtex.decode (str) +
    +
    + Parse the content of a BibTeX file + + +

    Parameters:

    +
      +
    • str + string + The content of a BibTeX file. +
      • +
    +

    Returns:

    +
      + {table,...} + A list of CSL items + if you use Pandoc v2.11 or later. +
    +

    Or

    +
      + {{id=string},...} + A list of item IDs + if you use an earlier version of Pandoc. +
    @@ -1787,35 +1777,34 @@

    Raises:

    -

    Document parsing

    +

    Converters

    - - meta_get_sources (meta) + + esc_md (str)
    - Collect sources from the document's metadata block.

    + Escape Markdown.

    -

    Reads the references metafata field and every bibliography file - referenced by the bibliography metadata field.

    +

    Only escapes Markdown that Pandoc recognises in bibliographic data.

    -

    Prints errors to STDERR if it cannot parse a bibliography file. +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data.

    Parameters:

      -
    • meta - tab - A metadata block. +
    • str + string + A string.

    Returns:

      - pandoc.List - A list of CSL items. + string + str with Markdown escaped.
    @@ -1823,26 +1812,60 @@

    Returns:

    - - doc_get_ckeys (doc[, flags]) + + markdownify (elem)
    - Collect the citation keys used in a document.

    + Convert a Pandoc element to Markdown text.

    -

    Prints errors to STDERR if it cannot parse a bibliography file. +

    Only recognises elements that are permitted in bibliographic data.

    + +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data.

    Parameters:

      -
    • doc - tab - A document. +
    • elem + pandoc.AstElement + A Pandoc AST element.
      • -
    • flags - string - If the flag 'u' is given, collects only citation keys - of sources that are neither defined in the references metadata field - nor in any bibliography file. +
    + +

    Returns:

    +
      + + string + Markdown text. +
    + + + + +
    +
    + + yamlify (data[, ind=4[, sort_f]]) +
    +
    + Generate a YAML representation of some data.

    + +

    Uses EOL to end lines. + + +

    Parameters:

    +
      +
    • data + The data. +
      • +
    • ind + int + How many spaces to indent blocks. + (default 4) +
      • +
    • sort_f + func + A function to sort keys of mappings. + Defaults to sorting them lexically. (optional)
    @@ -1850,52 +1873,444 @@

    Parameters:

    Returns:

      - {string,...} - A list of citation keys. + string + A YAML string. +
    +

    Or

    +
      +
    1. + nil + nil if the data cannot be represented in YAML.
      2. +
    2. + string + An error message.

    Raises:

    - An error if an item ID is of an illegal data type. + An error if the data is nested too deeply.
    -
    -

    Main

    - -
    - - add_biblio (meta, ckeys) + + conv_html_to_md (html)
    - Add sources to a bibliography file and the file to the document's metadata.

    + Convert pseudo-HTML to Markdown.

    -

    Updates the bibliography file as needed and adds it to the bibliography - metadata field. Interpretes a relative filename as relative to the - directory of the first input file passed to pandoc, not as relative - to the current working directory (unless no input files are given). +

    Only supports the HTML tags that Zotero and Pandoc support.

    + +

    See https://pandoc.org/MANUAL.html#specifying-bibliographic-data + and https://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields.

    Parameters:

      -
    • meta - tab - A metadata block, with the field - zotero-bibliography set to the filename of the bibliography file. -
      • -
    • ckeys - tab - The citaton keys of the items that should be added, - e.g., {'name:2019word', 'name2019WordWordWord'}. - Citation keys are just item IDs. +
    • html + string + Text that contains pseudo-HTML tags.

    Returns:

      - table + string + Text formatted in Markdown. +
    + + + + +
    +
    + + rconv_html_to_md (item) +
    +
    + Recursively convert pseudo-HTML to Markdown.

    + +

    Only changes fields listed in CSL_KEYS_FORMATTABLE. + + +

    Parameters:

    +
      +
    • item + tab + A CSL item. +
      • +
    + +

    Returns:

    +
      + + tab + The CSL item, with pseudo-HTML replaced with Markdown. +
    + + +

    See also:

    + + + +
    +
    + + rconv_nums_to_strs (data) +
    +
    + Recursively convert numbers to strings.

    + +

    Also converts floating point numbers to integers. This is needed + because all numbers are floating point numbers in JSON, but some + versions of Pandoc expect integers. + + +

    Parameters:

    +
      +
    • data + tab + The data. +
      • +
    + +

    Returns:

    +
      + + A copy of data with numbers converted to strings. +
    + +

    Raises:

    + An error if the data is nested too deeply. + + + +
    +
    +

    zotxt

    + +
    +
    + + ZOTXT_BASE_URL +
    +
    + The URL to lookup citation data.

    + +

    See https://github.com/egh/zotxt for details. + + + + + + + +

    +
    + + ZOTXT_KEYTYPES +
    +
    + Types of citation keys.

    + +

    See https://github.com/egh/zotxt for details. + + +

    Fields:

    +
      +
    • key + Zotero item ID +
      • +
    • betterbibtexkey + Better BibTeX citation key +
      • +
    • easykey + zotxt easy citekey +
      • +
    + + + + + +
    +
    + + zotxt_get_item_csl (id) +
    +
    + Retrieve a CSL item (for use in bibliography files).

    + +

    Returns bibliographic data as a Lua table. The retrieved item can be + passed to biblio_write; it should not be used in the references + metadata field (unless you are using Pandoc prior to v2.11). + + +

    Parameters:

    +
      +
    • id + string + An item ID, e.g., 'name:2019word', 'name2019TwoWords'. +
      • +
    + +

    Returns:

    +
      + + table + A CSL item. +
    +

    Or

    +
      +
    1. + nil + nil if an error occurred.
      2. +
    2. + string + An error message.
      3. +
    + +

    Raises:

    + See zotxt_get_item. + + + +
    +
    + + zotxt_get_item (id) +
    +
    + Retrieve a CSL item (for use in the references metadata field).

    + +

    Returns bibliographic data as Pandoc metadata. That retrieved item + can be used in the references metadata field; it should not be + passed to biblio_write. + + +

    Parameters:

    +
      +
    • id + string + An item ID, e.g., 'name:2019word', 'name2019TwoWords'. +
      • +
    + +

    Returns:

    +
      + + pandoc.MetaMap + A CSL item. +
    +

    Or

    +
      +
    1. + nil + nil if an error occurred.
      2. +
    2. + string + An error message.
      3. +
    + +

    Raises:

    + See zotxt_get_item. + + + +
    +
    +

    Document parsing

    + +
    +
    + + elem_type (elem) +
    +
    + The type of a Pandoc AST element. + + +

    Parameters:

    +
      +
    • elem + pandoc.AstElement + A Pandoc AST element. +
      • +
    + +

    Returns:

    +
      +
    1. + string + The type + (e.g., 'MetaMap', 'Plain').
      2. +
    2. + string + The high-order kind + (i.e., 'Block', 'Inline', or 'MetaValue').
      3. +
    3. + string + The literal 'AstElement'.
      4. +
    +

    Or

    +
      + + nil + nil if elem is not a Pandoc AST element. +
    + + + + +
    +
    + + walk (elem, filter) +
    +
    + Walk the AST and apply functions to matching elements.

    + +

    Differs from pandoc.walk_block and pandoc.walk_inline by accepting + AST elements of any type (i.e., including documents as a whole, the + metadata block, and metadata fields), by applying the filter to the + given element itself, by walking the AST bottom-up (which implies that + the filter is applied to every node, regardless of whether any of that + node's ancestors matches it), and by allowing the functions in the + filter to return arbitrary data (as opposed to either a Pandoc AST + element type or nil). Use with caution. + + +

    Parameters:

    +
      +
    • elem + pandoc.AstElement + A Pandoc AST element. +
      • +
    • filter + {string=func,...} + A filter. +
      • +
    + +

    Returns:

    +
      + + The element, with the filter applied. +
    + + + + +
    +
    + + meta_get_sources (meta) +
    +
    + Collect sources from the document's metadata block.

    + +

    Reads the references metafata field and every bibliography file + referenced by the bibliography metadata field.

    + +

    Prints errors to STDERR if it cannot parse a bibliography file. + + +

    Parameters:

    +
      +
    • meta + tab + A metadata block. +
      • +
    + +

    Returns:

    +
      + + pandoc.List + A list of CSL items. +
    + + + + +
    +
    + + doc_get_ckeys (doc[, flags]) +
    +
    + Collect the citation keys used in a document.

    + +

    Prints errors to STDERR if it cannot parse a bibliography file. + + +

    Parameters:

    +
      +
    • doc + tab + A document. +
      • +
    • flags + string + If the flag 'u' is given, collects only citation keys + of sources that are neither defined in the references metadata field + nor in any bibliography file. + (optional) +
      • +
    + +

    Returns:

    +
      + + {string,...} + A list of citation keys. +
    + +

    Raises:

    + An error if an item ID is of an illegal data type. + + + +
    +
    +

    Main

    + +
    +
    + + add_biblio (meta, ckeys) +
    +
    + Add sources to a bibliography file and the file to the document's metadata.

    + +

    Updates the bibliography file as needed and adds it to the bibliography + metadata field. Interpretes a relative filename as relative to the + directory of the first input file passed to pandoc, not as relative + to the current working directory (unless no input files are given). + + +

    Parameters:

    +
      +
    • meta + tab + A metadata block, with the field + zotero-bibliography set to the filename of the bibliography file. +
      • +
    • ckeys + tab + The citaton keys of the items that should be added, + e.g., {'name:2019word', 'name2019WordWordWord'}. + Citation keys are just item IDs. +
      • +
    + +

    Returns:

    +
      + + tab An updated metadata block, with the field bibliography added if needed.
    @@ -2009,7 +2424,7 @@

    Raises:

    generated by LDoc 1.4.6 -Last updated 2021-05-15 22:05:07 +Last updated 2021-05-30 13:19:10
    diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html index 2ebf610..33677f6 100644 --- a/docs/topics/README.md.html +++ b/docs/topics/README.md.html @@ -66,7 +66,8 @@

    pandoc-zotxt.lua

    Requirements

    pandoc-zotxt.lua requires Pandoc v2.0 or later, -Zotero, and zotxt. +Zotero, zotxt, and +Better BibTeX for Zotero. It should work under any POSIX-compliant operating system (e.g., Linux, macOS, FreeBSD, OpenBSD, NetBSD) as well as under Windows. It has not been tested under Windows, however.

    @@ -83,15 +84,17 @@

    Installation

  • Unpack the repository.
  • Move it to the filters sub-directory of your Pandoc data directory \ (pandoc --version tells you where that is).
    • -
  • Move the file pandoc-zotxt.lua from the repository directory +
  • Symlink or move the file pandoc-zotxt.lua from the repository directory up into the filters directory.
    • +
  • You may also want to copy the manual page from the man directory in + the repository to wherever your operating system searches for manual pages + (e.g., /usr/local/share/man/man1, /usr/share/man/man1).
    • -

    If you are using a POSIX-compliant system and have -curl or -wget, you can -install pandoc-zotxt.lua by copy-pasting the -following commands into a bourne shell:

    +

    If you are using a POSIX-compliant system (e.g., Linux or macOS) and have +curl or wget, +you can install pandoc-zotxt.lua by copy-pasting the following commands +into a Bourne-compatible shell:

    @@ -107,9 +110,8 @@ 
    Installation
    -

    You may also want to copy the manual page from the man directory in the -repository to wherever your operating system searches for manual pages -(e.g., /usr/local/share/man/man1, /usr/share/man/man1).

    +

    You also need to install zotxt and +Better BibTeX for Zotero.

    @@ -127,13 +129,13 @@

    Requirements

    1. A POSIX-compliant operating system.
      2. -
    2. Pandoc v2.7.2.
      3. +
    3. Pandoc v2.7.2 or later.
    4. pandoc-citeproc v0.16.1.3 (for Pandoc prior to v2.11).

    The test suite may or may not work with other versions of -Pandoc and pandoc-citeproc.

    +Pandoc (and pandoc-citeproc).

    Assumptions

    @@ -184,7 +186,7 @@

    Contact

    License

    -

    Copyright 2018, 2019, 2020 Odin Kroeger

    +

    Copyright 2018, 2019, 2020, 2021 Odin Kroeger

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -215,7 +217,7 @@

    Further Information

    generated by LDoc 1.4.6 -Last updated 2021-05-15 22:05:07 +Last updated 2021-05-30 13:19:10
    elem_type (elem)The type of a Pandoc AST element.
    walk (elem, filter)Walk the AST and apply functions to matching elements.
    meta_get_sources (meta) Collect sources from the document's metadata block.