sile-typesetter / sile / 14510870853

local function loadCslLocale (name)

   end

   end

end

local function loadCslStyle (name)

   end

   end

end

local function resolveEntry (bib, key)

   end

   end

end

   end)

end

   -- Formerly we used a SILE.scratch variable, but these expose too much of the internals to the outer world.

   -- So we now use a private member instead.

      bib = {},

         keys = {}, -- Cited keys in the order they are cited (ordered set)

         refs = {}, -- Table of cited keys with their first citation number, last locator and last position (table)

         lastkey = nil, -- Last entry key used in a citation, to track ibid/ibid-with-locator (string)

      },

   }

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

         -- Fake more or less ad hoc superscripting

         end)

      end)

   end

end

      parameter = "bibtex.style",

      type = "string",

      default = "csl",

      help = "BibTeX style",

   })

   -- For CSL hanging-indent or second-field-align

      parameter = "bibliography.indent",

      type = "measurement",

      default = SILE.types.measurement("3em"),

      help = "Left indentation for bibliography entries when the citation style requires it.",

   })

end

--- Retrieve the CSL engine, creating it if necessary.

-- @treturn CslEngine CSL engine instance

   end

end

--- Retrieve an entry and mark it as cited if it is not already.

-- @tparam string key Citation key

-- @tparam boolean warn_uncited Warn if the entry is not cited yet

-- @treturn table Bibliography entry

-- @treturn number Citation number

-- @treturn string|nil Locator value

   end

   -- Keep track of cited entries

      end

      -- Make it cited

   end

end

--- Track the position of a citation acconrding to the CSL rules.

-- @tparam string key Citation key

-- @tparam table locator Locator (label and value)

-- @tparam boolean is_single Single or multiple citation

-- @treturn string Position of the citation (first, subsequent, ibid, ibid-with-locator)

      -- This method is assumed to be invoked only for cited entries

      -- (i.e. after a call to getEntryForCite).

   end

   local pos

   else

      -- CSL 1.0.2 for "ibid" and "ibid-with-locator":

      --    a. the current cite immediately follows on another cite, within the same citation,

      --       that references the same item

      --  or

      --    b. the current cite is the first cite in the citation, and the previous citation consists

      --       of a single cite referencing the same item.

         -- CSL 1.0.2 rule when preceding cite does have a locator:

         --    If the current cite has the same locator, the position of the current cite is “ibid”.

         --    If the locator differs the position is “ibid-with-locator”.

         --    If the current cite lacks a locator its only position is “subsequent”."

         else

         end

      else

         -- CSL 1.0.2 rule when preceding cite does not have a locator:

         --    If the current cite has a locator, the position of the current cite is “ibid-with-locator”.

         --    Otherwise the position is “ibid”."

      end

   end

end

--- Get the citation key from the options or content (of a command).

-- @tparam table options Options

-- @tparam table content Content

-- @treturn string Citation key

   end

end

--- Retrieve a locator from the options.

-- @tparam table options Options

-- @treturn table Locator

   local locator

         else

            else

            end

         end

      end

   end

end

   end)

      -- Just mark the entry as cited.

   -- LEGACY COMMANDS

   end)

      end

      end

      -- Ensure the key is set in the options as this was the legacy behavior

      end

      end

      end

      -- Ensure the key is set in the options as this was the legacy behavior

         end

      end

   -- CSL IMPLEMENTATION COMMANDS

   -- Hooks for CSL processing

      -- To avoid attributes in the CSL-processed content

   end)

      -- Superscripted content from CSL may contain characters that are not

      -- available in the font even with +sups.

      -- E.g. ACS style uses superscripted numbers for references, but also

      -- comma-separated lists of numbers, or ranges with an en-dash.

      -- We want to be consistent between all these cases, so we always

      -- use fake superscripts.

   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)

      end)

   end)

      else

      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)

      end

      end

      -- We need no count cites to properly handle ibid/ibid-with-locator, as these depend

      -- on the previous citation being a single cite.

            end

         end

         -- Silently ignore other content (normally only blank lines)

      end

      -- Now we can collect the citations

         end

      end

      end

      end

      local bib

         end

      else

      end

               local citnum

                  -- 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 practice 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 unpredictable order anyway).

               else

               end

            end

         end

      end

      -- Reset the list of cited entries after having build the entries

      end

            -- Respective to the fixed part of the current lskip, all lines are indented

            -- but the first one.

         else

            -- Fixed part of the current lskip, and no paragraph indentation

         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 Bib(La)TeX \code{.bib} files and output citations and full text references.

\smallskip

\noindent

\em{Loading a bibliography}

\novbreak

\indent

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

You can load multiple files, and the entries will be merged into a single bibliography database.

\smallskip

\noindent

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

\novbreak

\indent

The CSL (Citation Style Language) implementation is more powerful and flexible than the former legacy solution available in earlier versions of this package (see below).

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{\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>}}. 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 mark an entry as cited without actually producing a citation, use \autodoc:command{\nocite{<key>}}.

This is useful when you want to include an entry in the bibliography without citing it in the text.

To generate multiple citations grouped correctly, use \autodoc:command{\cites{\cite{<key1>} \cite{<key2>}, …}}.

This wrapper command only accepts \autodoc:command{\cite} elements following their standard syntax.

Any other element triggers an error, and any text content is silently ignored.

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{\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{Producing citations and references (legacy commands)}

\novbreak

\indent

The “legacy” implementation is based on a custom rendering system.

The plan is to eventually deprecate and remove it, as the CSL implementation covers more use cases and is more powerful.

The \autodoc:setting[check=false]{bibtex.style} setting controls the style of the bibliography.

It may be set, for instance, to \code{chicago}, the only style supported out of the box.

(By default, it is set to \code{csl} to enforce the use of the CSL implementation.)

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.

(Actually, you can use the \autodoc:command{\printbibliography} introduced above, but then it always uses the CSL implementation for rendering the bibliography, differing from the output of the \autodoc:command{\reference} command.)

\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}