sile-typesetter / sile / 10866173456

local function loadCslLocale (name)

   end

   end

end

local function loadCslStyle (name)

   end

   end

end

local Bibliography

local function sanitize (str)

      -- TeX special characters:

      -- Backslash-escaped tilde is a tilde,

      -- but standalone tilde is a non-breaking space

         "(.?)~",

         function (prev)

            end

         end

      )

      -- Other backslash-escaped characters are skipped

      -- TODO FIXME:

      -- This ok for \", \& etc. which we want to unescape,

      -- BUT what should we do with other TeX-like commands?

         "\\",

         ""

      )

      -- We will wrap the content in <sile> tags so we need to XML-escape

      -- the input.

end

-- luacheck: push ignore

-- stylua: ignore start

---@diagnostic disable: undefined-global, unused-local, lowercase-global

      -- ignore both @comment and @preamble

   end)

   START "document"

end)

-- luacheck: pop

-- stylua: ignore end

---@diagnostic enable: undefined-global, unused-local, lowercase-global

local months =

local function consolidateEntry (entry, label)

   -- BibLaTeX aliases for legacy BibTeX fields

         else

         end

      end

   end

   -- Names field split and parsed

         -- FIXME Check our corporate names behave, we are probably bad currently

         -- with nested braces !!!

         -- See biblatex manual v3.20 §2.3.3 Name Lists

         -- e.g. editor = {{National Aeronautics and Space Administration} and Doe, John}

         end

      end

   end

   -- Month field in either number or string (3-letter code)

      else

      end

   end

   -- Extended date fields

         else

         end

      end

   end

end

--- Parse a BibTeX file and populate a bibliography table.

-- @tparam string fn Filename

-- @tparam table biblio Table of entries

local function parseBibtex (fn, biblio)

   end

   end

         end

      end

   end

end

--- Copy fields from the parent entry to the child entry.

-- BibLaTeX/Biber have a complex inheritance system for fields.

-- This implementation is more naive, but should be sufficient for reasonable

-- use cases.

-- @tparam table parent Parent entry

-- @tparam table entry Child entry

local function fieldsInherit (parent, entry)

      -- @xdata and any other unknown types: inherit all missing fields

         end

      end

   end

      end

         end

      end

   end

end

--- Resolve the 'crossref' and 'xdata' fields on a bibliography entry.

-- (Supplementing the entry with the attributes of the parent entry.)

-- Once resolved recursively, the crossref and xdata fields are removed

-- from the entry.

-- So this is intended to be called at first use of the entry, and have no

-- effect on subsequent uses: BibTeX does seem to mandate cross references

-- to be defined before the entry that uses it, or even in the same bibliography

-- file.

-- Implementation note:

-- We are not here to check the consistency of the BibTeX file, so there is

-- no check that xdata refers only to @xdata entries

-- Removing the crossref field implies we won't track its use and implicitly

-- cite referenced entries in the bibliography over a certain threshold.

-- @tparam table bib Bibliography

-- @tparam table entry Bibliography entry

local function crossrefAndXDataResolve (bib, entry)

   local refs

   end

   end

   end

      else

      end

   end

end

local function resolveEntry (bib, key)

   end

   end

end

   end)

end

   -- For DOI, PMID, PMCID and URL support.

   -- For underline styling support

   -- For TeX-like math support (extension)

   -- For superscripting support in number formatting

   -- Play fair: try to load 3rd-party optional textsubsuper package.

   -- If not available, fallback to raiselower to implement textsuperscript

         end)

      end)

   end

end

      parameter = "bibtex.style",

      type = "string",

      default = "chicago",

      help = "BibTeX style",

   })

end

   end)

   -- LEGACY COMMANDS

   end)

      end

      end

   end)

      end

      end

      end

   end)

   -- NEW CSL IMPLEMENTATION

   -- Internal commands for CSL processing

      -- To avoid attributes in the CSL-processed content

   end)

   -- CSL 1.0.2 appendix VI

   -- "If the bibliography entry for an item renders any of the following

   -- identifiers, the identifier should be anchored as a link, with the

   -- target of the link as follows:

   --   url: output as is

   --   doi: prepend with “https://doi.org/”

   --   pmid: prepend with “https://www.ncbi.nlm.nih.gov/pubmed/”

   --   pmcid: prepend with “https://www.ncbi.nlm.nih.gov/pmc/articles/”

   -- NOT IMPLEMENTED:

   --   "Citation processors should include an option flag for calling

   --   applications to disable bibliography linking behavior."

   -- (But users can redefine these commands to their liking...)

      })

   end)

         -- Play safe

      end

   end)

      end

   end)

      end

   end)

      end

   end)

   -- Style and locale loading

      -- FIXME: lang is mandatory until we can map document.lang to a resolved

      -- BCP47 with region always present, as this is what CSL locales require.

         -- Pick the default locale from the style, if any

      end

         localizedPunctuation = SU.boolean(options.localizedPunctuation, false),

         italicExtension = SU.boolean(options.italicExtension, true),

         mathExtension = SU.boolean(options.mathExtension, true),

      })

   end)

      -- TODO:

      -- - multiple citation keys (but how to handle locators then?)

      local locator

            else

               else

               end

            end

         end

      end

      end

      end

      end

      -- Keep track of cited entries

   end)

      end

      end

      end

         -- Make it cited

      end

   end)

      end

      local bib

         end

      else

      end

                  -- This is just to make happy CSL styles that require a citation number

                  -- However, table order is not guaranteed in Lua so the output may be

                  -- inconsistent across runs with styles that use this number for sorting.

                  -- This may only happen for non-cited entries in the bibliography, and it

                  -- would be a bad practive to use such a style to print the full bibliography,

                  -- so I don't see a strong need to fix this at the expense of performance.

                  -- (and we can't really, some styles might have several sorting criteria

                  -- leading to impredictable order anyway).

               end

            end

         end

      end

   end)

end

package.documentation = [[

\begin{document}

BibTeX is a citation management system.

It was originally designed for TeX but has since been integrated into a variety of situations.

This experimental package allows SILE to read and process BibTeX \code{.bib} files and output citations and full text references.

To load a BibTeX file, issue the command \autodoc:command{\loadbibliography[file=<whatever.bib>]}

\smallskip

\noindent

\em{Producing citations and references (legacy commands)}

\novbreak

\indent

To produce an inline citation, call \autodoc:command{\cite{<key>}}, which will typeset something like “Jones 1982”.

If you want to cite a particular page number, use \autodoc:command{\cite[page=22]{<key>}}.

To produce a bibliographic reference, use \autodoc:command{\reference{<key>}}.

This implementation doesn’t currently produce full bibliography listings, and the only supported bibliography style is Chicago referencing.

\smallskip

\noindent

\em{Producing citations and references (CSL implementation)}

\novbreak

\indent

While an experimental work-in-progress, the CSL (Citation Style Language) implementation is more powerful and flexible than the legacy commands.

You should first invoke \autodoc:command{\bibliographystyle[style=<style>, lang=<lang>]}, where \autodoc:parameter{style} is the name of the CSL style file (without the \code{.csl} extension), and \autodoc:parameter{lang} is the language code of the CSL locale to use (e.g., \code{en-US}).

The command accepts a few additional options:

\begin{itemize}

\item{\autodoc:parameter{localizedPunctuation} (default \code{false}): whether to use localized punctuation – this is non-standard but may be useful when using a style that was not designed for the target language;}

\item{\autodoc:parameter{italicExtension} (default \code{true}): whether to convert \code{_text_} to italic text (“à la Markdown”);}

\item{\autodoc:parameter{mathExtension} (default \code{true}): whether to recognize \code{$formula$} as math formulae in (a subset of the) TeX-like syntax.}

\end{itemize}

The locale and styles files are searched in the \code{csl/locales} and \code{csl/styles} directories, respectively, in your project directory, or in the Lua package path.

For convenience and testing, SILE bundles the \code{chicago-author-date} and \code{chicago-author-date-fr} styles, and the \code{en-US} and \code{fr-FR} locales.

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).

If you want to include all entries in the bibliography, not just those that have been cited, set the option \autodoc:parameter{cited} to false.

To produce a bibliographic reference, use \autodoc:command{\csl:reference{<key>}}.

Note that this command is not intended for actual use, but for testing purposes.

It may be removed in the future.

\smallskip

\noindent

\em{Notes on the supported BibTeX syntax}

\novbreak

\indent

The BibTeX file format is a plain text format for bibliographies.

The \code{@type\{…\}} syntax is used to specify an entry, where \code{type} is the type of the entry, and is case-insensitive.

Any content outside entries is ignored.

The \code{@preamble} and \code{@comment} special entries are ignored.

The former is specific to TeX-based systems, and the latter is a comment (everything between the balanced braces is ignored).

The \code{@string\{key=value\}} special entry is used to define a string or “abbreviation,” for use in other subsequent entries.

The \code{@xdata} entry is used to define an entry that can be used as a reference in other entries.

Such entries are not printed in the bibliography.

Normally, they cannot be cited directly.

In this implementation, a warning is raised if they are; but as they have no known type, their formatting is not well-defined, and might not be meaningful.

Regular bibliography entries have the following syntax:

\begin[type=autodoc:codeblock]{raw}

@type{key,

  field1 = value1,

  field2 = value2,

  …

}

\end{raw}

The entry key is a unique identifier for the entry, and is case-sensitive.

Entries consist of fields, which are key-value pairs.

The field names are case-insensitive.

Spaces and line breaks are not important, except for readability.

On the contrary, commas are compulsory between any two fields of an entry.

String values shall be enclosed in either double quotes or curly braces.

The latter allows using quotes inside the string, while the former does not without escaping them with a backslash.

When string values are not enclosed in quotes or braces, they must not contain any whitespace characters.

The value is then considered to be a reference to an abbreviation previously defined in a \code{@string} entry.

If no such abbreviation is found, the value is considered to be a string literal.

(This allows a decent fallback for fields where curly braces or double quotes could historically be omitted, such as numerical values, and one-word strings.)

String values are assumed to be in the UTF-8 encoding, and shall not contain (La)TeX commands.

Special character sequences from TeX (such as \code{`} assumed to be an opening quote) are not supported.

There are exceptions to this rule.

Notably, the \code{~} character can be used to represent a non-breaking space (when not backslash-escaped), and the \code{\\&} sequence is accepted (though this implementation does not mandate escaping ampersands).

With the CSL renderer, see also the non-standard extensions above.

Values can also be composed by concatenating strings, using the \code{#} character.

Besides using string references, entries have two other \em{parent-child} inheritance mechanisms allowing to reuse fields from other entries, without repeating them: the \code{crossref} and \code{xdata} fields.

The \code{crossref} field is used to reference another entry by its key.

The \code{xdata} field accepts a comma-separated list of keys of entries that are to be inherited.

Some BibTeX implementations automatically include entries referenced with the \code{crossref} field in the bibliography, when a certain threshold is met.

This implementation does not do that.

Depending on the types of the parent and child entries, the child entry may inherit some or all fields from the parent entry, and some inherited fields may be reassigned in the child entry.

For instance, the \code{title} in a \code{@collection} entry is inherited as the \code{booktitle} field in a \code{@incollection} child entry.

Some BibTeX implementations allow configuring the data inheritance behavior, but this implementation does not.

It is also currently quite limited on the fields that are reassigned, and only provides a subset of the mappings defined in the BibLaTeX manual, appendix B.

Here is an example of a BibTeX file showing some of the abovementioned features:

\begin[type=autodoc:codeblock]{raw}

@string{JIT = "Journal of Interesting Things"}

...

This text is ignored

...

@xdata{jit-vol1-iss2,

  journal = JIT # { (JIT)},

  year    = {2020},

  month   = {jan},

  volume  = {1},

  number  = {2},

}

@article{my-article,

  author  = {Doe, John and Smith, Jane}

  title   = {Theories & Practices},

  xdata   = {jit-1-2},

  pages   = {100--200},

}

\end{raw}

Some fields have a special syntax.

The \code{author}, \code{editor} and \code{translator} fields accept a list of names, separated by the keyword \code{and}.

The legacy \code{month} field accepts a three-letter abbreviation for the month in English, or a number from 1 to 12.

The more powerful \code{date} field accepts a date-time following the ISO 8601-2 Extended Date/Time Format specification level 1 (such as \code{YYYY-MM-DD}, or a date range \code{YYYY-MM-DD/YYYY-MM-DD}, and more).

\end{document}