From d020ba57a0907fdfd7924d0ef29c9791d1be788b Mon Sep 17 00:00:00 2001
From: Omikhleia <didier.willis@gmail.com>
Date: Thu, 12 Sep 2024 22:04:02 +0200
Subject: [PATCH] refactor(packages): Support CSL locators

---
 csl/core/engine.lua                  |  7 +++--
 packages/bibtex/init.lua             | 26 ++++++++++++----
 packages/bibtex/support/locators.lua | 46 ++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 8 deletions(-)
 create mode 100644 packages/bibtex/support/locators.lua

diff --git a/csl/core/engine.lua b/csl/core/engine.lua
index da26aa24e..d1b7f21a3 100644
--- a/csl/core/engine.lua
+++ b/csl/core/engine.lua
@@ -990,13 +990,16 @@ function CslEngine:_if (options, content, entry)
       end
    end
    if options.locator then
-      local cond = entry.locator and entry.locator.label == options.locator
-      table.insert(conds, cond)
+      for _, loc in ipairs(pl.stringx.split(options.locator, " ")) do
+         local cond = entry.locator and entry.locator.label == loc or false
+         table.insert(conds, cond)
+      end
    end
    -- FIXME TODO other conditions: position, disambiguate
    for _, v in ipairs({ "position", "disambiguate" }) do
       if options[v] then
          SU.warn("CSL if condition " .. v .. " not implemented yet")
+         table.insert(conds, false)
       end
    end
    -- Apply match
diff --git a/packages/bibtex/init.lua b/packages/bibtex/init.lua
index a494d7ccb..faa073013 100644
--- a/packages/bibtex/init.lua
+++ b/packages/bibtex/init.lua
@@ -42,6 +42,7 @@ local nbibtex = require("packages.bibtex.support.nbibtex")
 local namesplit, parse_name = nbibtex.namesplit, nbibtex.parse_name
 local isodatetime = require("packages.bibtex.support.isodatetime")
 local bib2csl = require("packages.bibtex.support.bib2csl")
+local locators = require("packages.bibtex.support.locators")
 
 local Bibliography
 
@@ -453,8 +454,22 @@ function package:registerCommands ()
 
    self:registerCommand("csl:cite", function (options, content)
       -- TODO:
-      -- - locator support
-      -- - multiple citation keys
+      -- - multiple citation keys (but how to handle locators then?)
+      local locator
+      for k, v in pairs(options) do
+         if k ~= "key" then
+            if not locators[k] then
+               SU.warn("Unknown option '" .. k .. "' in \\csl:cite")
+            else
+               if not locator then
+                  local label = locators[k]
+                  locator = { label = label, value = v }
+               else
+                  SU.warn("Multiple locators in \\csl:cite, using the first one")
+               end
+            end
+         end
+      end
       if not SILE.scratch.bibtex.engine then
          SILE.call("bibliographystyle", { lang = "en-US", style = "chicago-author-date" })
       end
@@ -473,10 +488,7 @@ function package:registerCommands ()
       SILE.scratch.bibtex.cited.citnums[options.key] = citnum
 
       local csljson = bib2csl(entry, citnum)
-      -- csljson.locator = { -- EXPERIMENTAL
-      --    label = "page",
-      --    value = "123-125"
-      -- }
+      csljson.locator = locator
       local cite = engine:cite(csljson)
 
       SILE.processString(("<sile>%s</sile>"):format(cite), "xml")
@@ -602,6 +614,8 @@ For convenience and testing, SILE bundles the \code{chicago-author-date} and \co
 If you don’t specify a style or locale, the author-date style and the \code{en-US} locale will be used.
 
 To produce an inline citation, call \autodoc:command{\csl:cite{<key>}}, which will typeset something like “(Jones 1982)”.
+If you want to cite a particular page number, use \autodoc:command{\csl:cite[page=22]{<key>}}. Other “locator”  options are available (article, chapter, column, line, note, paragraph, section, volume, etc.) – see the CSL documentation for details.
+Some frequent abbreviations are also supported (art, chap, col, fig…)
 
 To produce a bibliography of cited references, use \autodoc:command{\printbibliography}.
 After printing the bibliography, the list of cited entries will be cleared. This allows you to start fresh for subsequent uses (e.g., in a different chapter).
diff --git a/packages/bibtex/support/locators.lua b/packages/bibtex/support/locators.lua
new file mode 100644
index 000000000..cca2bc507
--- /dev/null
+++ b/packages/bibtex/support/locators.lua
@@ -0,0 +1,46 @@
+--- Mappings for known CSL 1.0.2 locator types
+--
+-- For use as option in citation commands, e.g. `\cite[key=doe2022, page=5]`.
+-- Note that some CSL locators have '-locator' in their name, to use the
+-- corresponding term in the CSL locale file.
+--
+return {
+   act = "act",
+   appendix = "appendix",
+   app = "appendix", -- Convenience alias
+   article = "article-locator", -- See note
+   art = "article-locator", -- Convenience alias
+   book = "book",
+   canon = "canon",
+   chapter = "chapter",
+   ch = "chapter", -- Convenience alias
+   chap = "chapter", -- Convenience alias
+   column = "column",
+   col = "column", -- Convenience alias
+   elocation = "elocation",
+   equation = "equation",
+   figure = "figure",
+   fig = "figure", -- Convenience alias
+   folio = "folio",
+   fol = "folio", -- Convenience alias
+   issue = "issue",
+   line = "line",
+   note = "note",
+   opus = "opus",
+   page = "page",
+   paragraph = "paragraph",
+   part = "part",
+   rule = "rule",
+   scene = "scene",
+   section = "section",
+   ['sub-verbo'] = "sub-verbo",
+   svv = "sub-verbo", -- Convenience alias
+   supplement = "supplement",
+   table = "table",
+   timestamp = "timestamp",
+   title = "title-locator", -- See note
+   verse = "verse",
+   version = "version",
+   volume = "volume",
+   vol = "volume", -- Convenience alias
+}