PAaSO/_extensions/rchaput/acronyms/acronyms_styles.lua

--[[

    This file defines the "styles" to replace acronyms.

    Such styles control how to use the acronym's short name,
    long name, whether one should be between parentheses, etc.

    Styles are largely inspired from the LaTeX package "glossaries"
    (and "glossaries-extra").
    A gallery of the their styles can be found at:
    https://www.dickimaw-books.com/gallery/index.php?label=sample-abbr-styles
    A more complete document (rather long) can be found at:
    https://mirrors.chevalier.io/CTAN/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf

    More specifically, this file defines a table of functions.
    Each function takes an acronym, and return one or several Pandoc elements.
    These elements will replace the original acronym call in the Markdown 
    document.

    Most styles will depend on whether this is the acronym's first occurrence,
    ("first use") or not ("next use"), similarly to the LaTeX "glossaries".

    For example, a simple (default) style can be to return the acronym's
    long name, followed by the short name between parentheses.
    When the parser encounters `\acr{RL}`, assuming that `RL` is correctly
    defined in the acronyms database, the corresponding function would 
    return a Pandoc Link, where the text is "Reinforcement Learning (RL)",
    and pointing to the definition of "RL" in the List of Acronyms.
    
    Note: the acronym's key MUST exist in the acronyms database.
    Functions to replace a non-existing key must be handled elsewhere.

--]]

local Helpers = require("acronyms_helpers")


-- The table containing all styles, indexed by the style's name.
local styles = {}


-- Local helper function to create either a Str or a Link,
-- depending on whether we want to insert links.
local function create_element(content, key, insert_links)
    if insert_links then
        return pandoc.Link(content, Helpers.key_to_link(key))
    else
        return pandoc.Str(content)
    end
end


-- First use: long name (short name)
-- Next use: short name
styles["long-short"] = function(acronym, insert_links)
    local text
    if acronym:isFirstUse() then
        text = acronym.longname .. " (" .. acronym.shortname .. ")"
    else
        text = acronym.shortname
    end

    return create_element(text, acronym.key, insert_links)
end


-- First use: short name (long name)
-- Next use: short name
styles["short-long"] = function(acronym, insert_links)
    local text
    if acronym:isFirstUse() then
        text = acronym.shortname .. " (" .. acronym.longname .. ")"
    else
        text = acronym.shortname
    end

    return create_element(text, acronym.key, insert_links)
end

-- First use: long name
-- Next use: long name
styles["long-long"] = function(acronym, insert_links)
    local text
    text = acronym.longname

    return create_element(text, acronym.key, insert_links)
end

-- First use: short name [^1]
-- [^1]: short name: long name
-- Next use: short name
styles["short-footnote"] = function(acronym, insert_links)
    if acronym:isFirstUse() then
        -- The inline text (before the footnote)
        local text = pandoc.Str(acronym.shortname)
        -- We create a footnote, which must contain a Block with a Link and
        -- the longname (as a simple text).
        -- So we create a Pandoc Plain object to hold the link and text.
        -- Directly using a list inside the Note seems not to work.
        local note = pandoc.Note(
                pandoc.Plain({
                    create_element(acronym.shortname, acronym.key, insert_links),
                    pandoc.Str(": " .. acronym.longname)
                })
        )
        -- We want to insert both the text and the footnote
        return { text, note }
    else
        -- Simply return the shortname
        return create_element(acronym.shortname, acronym.key, insert_links)
    end
end


-- The "public" API of this module, the function which is returned by
-- require.
return function(acronym, style_name, insert_links)
    -- Check that the requested strategy exists
    assert(style_name ~= nil,
        "style_name must not be nil!")
    assert(styles[style_name] ~= nil,
        "Style " .. style_name .. " does not exist!")

    -- Check that the acronym exists
    assert(acronym ~= nil,
        "acronym must not be nil!")

    -- Call the style on this acronym
    return styles[style_name](acronym, insert_links)
end