sile-typesetter / sile / 14335207249

local function loadCslLocale (name)

   end

   end

end

local function loadCslStyle (name)

   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

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

-- The citation key is taken from the options, or from the content if not provided.

-- @tparam table options Options

-- @tparam table content Content

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

-- @treturn table Bibliography entry

   end

   end

   -- Keep track of cited entries

      end

      -- Make it cited

   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)

   -- LEGACY COMMANDS

   end)

      end

      end

      end

      end

      end

         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

            end

            end

         end

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

               end

            end

         end

      end

      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}