% SPDX-License-Identifier: MIT
% Copyright (c) 2026 import-citation-cff contributors
%
% The import-citation-cff manual. Typeset it with `l3build doc`, or with
% `lualatex import-citation-cff.tex` next to import-citation-cff.sty, its
% built-in style .def files, cfflatex.lua, cfflatex-data.lua, and CITATION.cff.
\documentclass{l3doc}
\usepackage{import-citation-cff}
\usepackage{authblk}

% l3doc strips two characters from each verbatim line, which in .dtx files
% are "% "; this file is plain LaTeX.
\fvset{gobble=0}

% The manual is its own example: its title, abstract, and author come from the
% CITATION.cff file of this package.
\includecff{CITATION.cff}
\title{\cff{title}}
% The authors, with authblk: marks for their affiliations, which authblk lists
% below them, and email footnotes for the contacts of the citation.
\cffsetauthors[style=authblk]
% hyperref cannot take the PDF author from the \author of authblk.
\hypersetup{pdfauthor={\cffauthornames}}

% The version and date of import-citation-cff.sty, unless the build defines
% others: CI shows the commit or the release that the manual was built from. See
% CFFLATEX_DOC_VERSION in build.lua.
\GetFileInfo{import-citation-cff.sty}
\providecommand\cfflatexdocversion{\fileversion}
\providecommand\cfflatexdocdate{\filedate}
\date{Version \cfflatexdocversion\ (\cfflatexdocdate)}

\begin{document}
\maketitle

\begin{abstract}
  \cff{abstract}
\end{abstract}

\tableofcontents

\section{Introduction}

Software is a product of research and should be cited like one~\cite{smith2016}.
The Citation File Format (CFF)~\cite{druskat2021} makes this practical by
keeping a YAML-format file with |cff| extension, typically named |CITATION.cff|,
in the software repository. The CFF file holds the metadata needed to cite the
software which an be read by both people and programs. This practice allows
automated tools to easily discover and use the citation metadata.

The CFF file and the cited manuscript are often kept and developed together in a
single repository, the latter usually written in \LaTeX{}. Developers need to
keep duplicate metadata in sync between the CFF file and the manuscript, which
can be tedious and error-prone. This complication is even more pronounced when
the software and the manuscript are developed in parallel, the former metadata
being kept in the top level of the CFF file while the latter metadata being kept
in the subsection of the CFF file such as \texttt{preferred-citation}.

\pkg{import-citation-cff} relieves this burden by keeping the CFF file as the
single source of metadata and importing it into the \LaTeX{} document. The
metadata, such as the title, abstract, and authors, are imported as \LaTeX{}
macros that dynamically expand whenever the CFF file changes. This ensures that
the metadata are synced across the repository, allowing for easier maintenance
and automation of the development process.

\section{Requirements}

\pkg{import-citation-cff} parses the CFF file in Lua using the
\pkg{lt3luabridge} and \pkg{lua-tinyyaml} packages. It needs either
\begin{itemize}
  \item Lua\LaTeX{}, which runs the Lua code directly, or
  \item pdf\LaTeX{} with unrestricted shell escape (|--shell-escape|), which
        runs the Lua code with |texlua|.
\end{itemize}
It supports \TeX{} Live 2025 and later.

\section{Usage}

This manuscript itself is an example of using \pkg{import-citation-cff}. Its
|CITATION.cff| is
\VerbatimInput{CITATION.cff}

The \LaTeX{} manuscript then imports and accesses the metadata by
\begin{Verbatim}
\documentclass{l3doc}
\usepackage{import-citation-cff}
\includecff{CITATION.cff}
\title{\cff{title}}
\author{\cffauthor{1}{given-names}~\cffauthor{1}{family-names}}

\begin{document}
\maketitle
\begin{abstract}
  \cff{abstract}
\end{abstract}
\end{document}
\end{Verbatim}

\subsection{Specifying the source level}

By default, \cs{includecff} reads the top level of the CFF file. The
|source=|\meta{key} option selects another citation under the top-level
\meta{key}, such as \texttt{preferred-citation}. Any other top-level key is read
in the same way. Note that CFF~1.2.0 defines \texttt{preferred-citation} as the
only such key and allows no others, so a file with another key fails CFF
validation.

\subsection{Reading CFF fields}
\label{sec:any-field}

Once the CFF file is included, \cs{cff} reads any value of the citation by its
path. The keys and the indices, counting from~1, that lead to it, are separated
by slashes. \cs{cffcount} gives the length of a list. With the |CITATION.cff| of
this manual,
\begin{center}
  \begin{tabular}{ll}
    |\cff{title}|                  & \cff{title}                  \\
    |\cff{authors/1/family-names}| & \cff{authors/1/family-names} \\
    |\cff{keywords/2}|             & \cff{keywords/2}             \\
    |\cffcount{keywords}|          & \cffcount{keywords}          \\
  \end{tabular}
\end{center}
The path is expanded first, so |\cff{authors/\cffauthorindex/email}| reads the
email address of the current author in \cs{cffforeachauthor}.

\subsection{Iterating over authors}

\cs{cffforeachauthor} runs its argument once for each author of the citation,
and \cs{cffauthorindex} gives the index of the current author. A document can
thus list the authors without knowing how many there are. The following sets the
author list of \cs{maketitle}, with \cs{and} between the authors:
\begin{Verbatim}
\author{\cffforeachauthor{%
  \ifnum\cffauthorindex>1 \and\fi
  \cffauthor{\cffauthorindex}{given-names}~%
  \cffauthor{\cffauthorindex}{family-names}}}
\end{Verbatim}

\subsection{Multiple affiliations}
\label{sec:affiliations}

CFF gives each person one \texttt{affiliation} which is a nonempty string, and
does not natively support multiple affiliations per author.
\pkg{import-citation-cff}, allows multiple affiliations per author by separating
them with semicolons in the \texttt{affiliation} field of the author.
Affiliations of each author can be accessed individually by
\cs{cffauthoraffiliation} and related commands. Refer to
Section~\ref{sec:reference} for details.

\subsection{Author style}
\label{sec:setauthors}

\cs{cffsetauthors} declares the authors of the citation for the title page in an
author style, which |\cffsetauthors[style=|\meta{name}|]| selects. It marks each
author with their affiliations, numbered among the distinct affiliations of the
citation, and with a footnote for each contact of the citation that has the same
names. Section~\ref{sec:builtin-styles} lists the styles that come with
\pkg{import-citation-cff}, and Section~\ref{sec:author-styles} explains how to
write others. The other keys of \cs{cffsetauthors} change how a name is made,
how the authors and the affiliations are declared, and the marks and the
footnotes (Section~\ref{sec:reference}).

\subsection{Text in the metadata}

Values are inserted as text. The \TeX{} special characters
\verb+\ { } % # $ & _ ~ ^+ are printed as themselves, so \LaTeX{} markup in the
CFF file is not interpreted. Line breaks inside a value become spaces, so the
paragraphs of a multi-paragraph abstract run together, and spaces at either end
are dropped. Non-ASCII characters are kept. With pdf\LaTeX{}, use a font
encoding that has them, such as \texttt{T1}.

\subsection{Recording the CFF file}

\cs{includecff} records the CFF file as an input in the |.fls| file that the
|-recorder| option writes. Build tools that read it, such as latexmk and the
LaTeX Workshop extension of Visual Studio Code, therefore rebuild the document
when the CFF file changes.

\subsection{Checking the title page}
\label{sec:check}

By default, \pkg{import-citation-cff} checks that \cs{maketitle} typesets the
metadata of the citation. The \cs{title} command should use |\cff{title}|, and
the \cs{author} command should use \cs{cffauthor}, or \cs{cff} with a path such
as |authors/1/family-names|, for every author of the citation. The check cannot
see metadata that is expanded before \cs{maketitle}, such as an author list
built with \cs{xdef} in the preamble, and it needs a class that keeps the title
and the authors in \cs{@title} and \cs{@author}, as the standard classes do.

What the check looks for, and where, depends on the author style of the
document. A style for a journal template that typesets its title block without
\cs{maketitle} can check other fields in that block
(Section~\ref{sec:check-styles}). The |style| option of the package names the
author style of the document, and also makes it the default style of
\cs{cffsetauthors}:
\begin{Verbatim}
\usepackage[style=authblk]{import-citation-cff}
\end{Verbatim}
The check uses this style even if \cs{cffsetauthors} selects another one.
Without the option, the check uses the style of the last \cs{cffsetauthors} in
the preamble, or else |standard|. Section~\ref{sec:builtin-styles} tells what
each built-in style checks.

When the check does not fit the document, load the package with the
|check=false| option:
\begin{Verbatim}
\usepackage[check=false]{import-citation-cff}
\end{Verbatim}

\subsection{Expanding metadata}

The Lua command-line tool \texttt{cfflatexpand} replaces metadata commands with
their values and removes the \pkg{import-citation-cff} package load and
\cs{includecff}. The resulting source can be compiled without
\pkg{import-citation-cff} or the CFF file. Install the command as described in
the README, then run either
\begin{Verbatim}
cfflatexpand manuscript.tex > submission.tex
cfflatexpand manuscript.tex --output submission.tex
cfflatexpand manuscript.tex -o submission.tex
\end{Verbatim}
From a source checkout, use \texttt{./cfflatexpand} instead. The command runs
with \texttt{texlua}. Converting \cs{cffsetauthors} also requires LuaLaTeX,
which runs with shell escape disabled.

\texttt{cfflatexpand} also converts \cs{cffsetauthors} with the keys of
Section~\ref{sec:setauthors}, the built-in styles of
Section~\ref{sec:builtin-styles}, and author style plugins that follow the rules
of Section~\ref{sec:export-styles}. The |style| option of the package is its
default style, as when compiling. The output still needs the class or package
that provides its declarations.

For a manuscript split into several TeX files, first merge it with latexpand.
Keep the merged file beside the root manuscript and keep the literal CFF
filename valid there:
\begin{Verbatim}
latexpand manuscript.tex > manuscript-flat.tex
cfflatexpand manuscript-flat.tex --output submission.tex
\end{Verbatim}

\section{Built-in author styles}
\label{sec:builtin-styles}

\pkg{import-citation-cff} comes with the following author styles. A document
selects one with the |style| key of \cs{cffsetauthors} or the |style| option of
the package (Sections~\ref{sec:setauthors} and~\ref{sec:check}). The other keys
of \cs{cffsetauthors} override the defaults of the style.

\subsection{\texttt{standard}}
\label{sec:style-standard}

The default style collects the authors in one \cs{author} of the standard
classes, separated by \cs{and}, without the affiliations. The footnotes of the
contacts and the notes are typeset by \cs{maketitle}, like those of \cs{thanks}.
The check looks for the title in \cs{title} and every author in \cs{author}.

\subsection{\texttt{authblk}}

The style declares each author with \cs{author} and each distinct affiliation
with \cs{affil} of the \pkg{authblk} package, which lists the affiliations below
the authors. The marks of an author are the letters of their affiliations and
the footnotes of the contacts and the notes. Load \pkg{authblk} before
\cs{cffsetauthors}. The check is that of |standard|
(Section~\ref{sec:style-standard}). The title page of this manual is made by
\begin{Verbatim}
\usepackage{authblk}
\includecff{CITATION.cff}
\title{\cff{title}}
\cffsetauthors[style=authblk]
\hypersetup{pdfauthor={\cffauthornames}}
\end{Verbatim}

\subsection{\texttt{rsc}}
\label{sec:style-rsc}

The style is for the article template of the Royal Society of
Chemistry~\cite{rsc2019}, which typesets its title block by hand in a
|@twocolumnfalse| environment, without \cs{maketitle}. It defines two commands
for the template: \cs{rscauthors}, the line of the authors, and
\cs{rscfootnotes}, the footnotes that the template lists after the block.
\begin{Verbatim}
\usepackage[style=rsc]{import-citation-cff}
\includecff{CITATION.cff}
\cffsetauthors[
  note = {1}{These authors contributed equally to this work.},
  note = {2}{These authors contributed equally to this work.},
]
...
 & \noindent\large{\rscauthors} \\
...
%%%FOOTNOTES%%%
\rscfootnotes
\end{Verbatim}
The authors are separated by commas, with ``and'' before the last. Their marks
are $\ast$ for a contact, the letters of the affiliations, and ${\ddag}$, \S,
and \P{} for the notes. The template keeps ${\dag}$ for the electronic
supplementary information. Authors with the same note share its symbol, and with
one affiliation, no letter is needed. \cs{rscfootnotes} lists the contacts, then
the affiliations, then the notes, each as
|\footnotetext{\textit{$^{|\meta{mark}|}$~|\meta{text}|}}|. The default contact
template is |Corresponding author. E-mail: #1{email}|.

The check looks for the title, every author, and the abstract in the
|@twocolumnfalse| block, for example through \cs{rscauthors}, and in the whole
document if there is no such block.

\section{Author style plugins}
\label{sec:author-styles}

An author style plugin is a definition file that registers a style for the
|style| key of \cs{cffsetauthors} and the |style| option of the package. The
style declares the authors, and also tells the check of Section~\ref{sec:check}
what to look for. The built-in styles of Section~\ref{sec:builtin-styles} are
plugins written with the same interface.

\subsection{Writing a definition file}

The support files of \pkg{import-citation-cff} share the short prefix
\texttt{cfflatex}. A style named \meta{name} lives in the file
\texttt{cfflatex-style-}\meta{name}\texttt{.def}, beside the manuscript or in a
TeX tree, and registers itself with \cs{cffdeclareauthorstyle}. For example, the
following style uses the \cs{author} and \cs{affil} commands of \pkg{authblk}
with numeric affiliation marks:
\begin{Verbatim}
% cfflatex-style-authblk-arabic.def
\cffdeclareauthorstyle{authblk-arabic}{
  requires = {authblk},
  affiliation-mark = arabic,
  author = {\author[{{}#1}]{#2}},
  affiliation = {\affil[#1]{#2}},
}
\end{Verbatim}
The manuscript selects it by name:
\begin{Verbatim}
\usepackage{authblk}
\usepackage{import-citation-cff}
\includecff{CITATION.cff}
\cffsetauthors[style=authblk-arabic]
\end{Verbatim}

\cs{cffsetauthors}, or the |style| option of the package at
\verb+\begin{document}+, reads the definition file the first time the style is
used, and the file must register the requested name. Names are case-sensitive,
start with an ASCII letter or digit, and contain only ASCII letters, digits,
hyphens, and underscores. Registration is global, and registering a name twice
is an error. Define helper commands that are used outside the file globally.
Definition files are read with normal document catcodes. Put \cs{ExplSyntaxOn}
and \cs{ExplSyntaxOff} around expl3 code.

\subsection{Plugin keys}

A style definition accepts the keys of \cs{cffsetauthors}, except |style|, as
its defaults. Each call of \cs{cffsetauthors} resets every key, then applies the
style definition, then the user's options. User options therefore override the
style even when they appear before |style| in the option list.

The following keys are only useful in a style definition.
\begin{description}
  \item[\texttt{requires}] a comma-separated list of packages that must already
        be loaded. The plugin does not load them.
  \item[\texttt{validate}] code that checks the document, such as the class or
        the fields the style needs.
  \item[\texttt{begin}, \texttt{end}] code run before and after the
        declarations. For example, the |standard| style collects the names and
        declares one \cs{author} in its |end| code.
  \item[\texttt{prepare-author}] code run before each author is declared, with
        |#1| equal to the index of the author. Use the public accessors of
        Section~\ref{sec:reference} to inspect that author.
  \item[\texttt{author-code}, \texttt{affiliation-code}] code run in place of
        the |author| and |affiliation| templates, with the same arguments.
  \item[\texttt{render}] code that replaces the default order of declarations.
        An empty value selects the default.
  \item[\texttt{check-fields}, \texttt{check-region}] what the check looks for
        (Section~\ref{sec:check-styles}). These keys are only allowed in a style
        definition.
\end{description}

The |author| and |affiliation| templates are declarations: \cs{cffsetauthors}
passes each of them to \cs{cffemit} itself. The |author-code| and
|affiliation-code| keys are code instead: they can prepare or accumulate, and
must pass each final declaration to \cs{cffemit}. An empty affiliation template
or code gives no affiliations and no affiliation marks.

\subsection{Rendering order}

\cs{cffsetauthors} runs a style in this order:
\begin{enumerate}
  \item the |requires| check and the |validate| code;
  \item the collection of the names for \cs{cffauthornames};
  \item the |begin| code;
  \item the renderer, which by default calls \cs{cffrenderauthor} for every
        author and then \cs{cffrenderaffiliation} for every distinct
        affiliation;
  \item the |end| code.
\end{enumerate}
\cs{cffauthornames} is available from the |begin| code on, and does not depend
on the order of the renderer. \cs{cffrenderauthor} runs the |prepare-author|
code before the author template. A |render| value can use the loops of
Section~\ref{sec:reference} to change the order. For example, this renderer
declares each author followed by the affiliations of that author, repeating
shared affiliations:
\begin{Verbatim}
render = {
  \cffforeachauthor{
    \cffrenderauthor{\cffauthorindex}
    \cffforeachauthoraffiliation{\cffauthorindex}{
      \cffrenderaffiliation{\cffconvertaffiliationindex
        {\cffauthorindex}{\cffauthoraffiliationindex}}}
  }
},
\end{Verbatim}

\subsection{Checking the title page}
\label{sec:check-styles}

When a style is the author style of the document (Section~\ref{sec:check}), the
check reads two keys of its definition.
\begin{description}
  \item[\texttt{check-fields}] the fields that the title page must use, given as
        paths of \cs{cff}, such as |title| and |abstract|, where |authors|
        stands for every author. The default is |{title, authors}|. A field that
        the citation does not have is not checked.
  \item[\texttt{check-region}] the regions of the document where the fields must
        be used, one or more of
        \begin{description}
          \item[\texttt{maketitle}] \cs{maketitle}, where \cs{title} must use
                the title and \cs{author} every author. This is the default.
          \item[\texttt{hooks=}\textmd{\marg{begin}\marg{end}}] from the
                \LaTeX{} hook \meta{begin} to the hook \meta{end}.
          \item[\texttt{document}] the whole document, as a fallback.
        \end{description}
\end{description}
The first region that ends is checked, and no region is checked after it. If no
other region has ended, |document| is checked at the end of the document, and
the log says so. A use counts when \cs{cff}, \cs{cffauthor}, or
\cs{cffauthornames} is typeset inside the region, also through macros of the
document.

For example, the template of the Royal Society of Chemistry typesets its title
block in a |@twocolumnfalse| environment. Every environment has hooks, so the
|rsc| style (Section~\ref{sec:style-rsc}) checks this block with
\begin{Verbatim}
check-fields = {title, authors, abstract},
check-region = {
  hooks = {env/@twocolumnfalse/begin}{env/@twocolumnfalse/end},
  document,
},
\end{Verbatim}
The check does not run during export, so these keys do not affect
\texttt{cfflatexpand}.

\subsection{Supporting \texttt{cfflatexpand}}
\label{sec:export-styles}

\texttt{cfflatexpand} converts \cs{cffsetauthors} by running the style, not by
reading it. It
\begin{enumerate}
  \item starts a separate Lua\LaTeX{} run of an empty \texttt{article} document
        that loads \pkg{import-citation-cff} and the metadata, but none of the
        manuscript's preamble;
  \item calls \cs{cffsetauthors} there with the options of the manuscript, and
        the |style| option of the package as the default, loading the definition
        file from the directory of the manuscript or the TeX search path, and
        skipping |requires| and |validate|;
  \item records the argument of every \cs{cffemit} as it is, without executing
        it;
  \item replaces \cs{cffsetauthors} in the output with the recorded
        declarations, in which the metadata commands become their values and the
        footnotes of contacts and notes use a self-contained definition.
\end{enumerate}

A style therefore works with \texttt{cfflatexpand} if it follows these rules.
\begin{itemize}
  \item Register the style in a definition file. \cs{cffdeclareauthorstyle} in
        the manuscript works when compiling, but \texttt{cfflatexpand} reports
        an error.
  \item Pass every final declaration to \cs{cffemit}. A declaration that the
        code executes directly, such as \cs{author} in |author-code|, appears
        when compiling but is missing from the output.
  \item Make the preparation code self-contained. The |begin|, |end|,
        |prepare-author|, |author-code|, |affiliation-code|, and |render| code
        also runs in the isolated document, where the class and the packages of
        the manuscript, including those in |requires|, are not loaded.
  \item Use only commands of the final class and its packages in the
        declarations. The output is compiled without \pkg{import-citation-cff}
        and without the definition file, so helper commands of the style are
        undefined there. A declaration can define a command for the document
        with \cs{newcommand}, as the |rsc| style does.
  \item Keep the marks and the names unexpanded. They contain the footnotes and
        the metadata commands, which must run when the title page is typeset. To
        accumulate declarations, append the arguments with \cs{tl_put_right:Nn}
        and insert the result with \cs{exp_not:V}, as
        \texttt{cfflatex-style-standard.def} does, rather than expanding the
        whole declaration with \cs{edef}.
\end{itemize}

\section{Reference}
\label{sec:reference}

The package has two options (Section~\ref{sec:check}).
\begin{description}
  \item[\texttt{check=}\textmd{\meta{boolean}}] checks the title page. The
        default is |true|.
  \item[\texttt{style=}\textmd{\meta{name}}] sets the author style of the
        document, which the check uses and \cs{cffsetauthors} selects by
        default.
\end{description}

\begin{function}{\includecff}
  \begin{syntax}
    \cs{includecff} \oarg{options} \marg{file}
  \end{syntax}
  Reads the citation metadata in \meta{file}. The command can be used in the
  preamble or in the document. Each call replaces the metadata read by the
  previous one.

  \begin{description}
    \item[\texttt{source=}\textmd{\meta{key}}] reads the mapping under the
          top-level \meta{key} instead. Without this option, the citation is the
          top level of the file.
  \end{description}
\end{function}

\begin{function}[EXP]{\cff, \cffcount}
  \begin{syntax}
    \cs{cff} \marg{path}
    \cs{cffcount} \marg{path}
  \end{syntax}
  Expand to the value at \meta{path} in the citation, and to the length of the
  list at \meta{path}. \meta{path} lists the keys and the indices, counting
  from~1, that lead to the value, separated by slashes, such as
  |authors/1/family-names|. A missing path gives nothing for \cs{cff} and 0 for
  \cs{cffcount}. A list or a mapping for \cs{cff}, and a value or a mapping for
  \cs{cffcount}, is an error. |\cff{authors/|\meta{index}|/|\meta{field}|}| is
  \cs{cffauthor}\marg{index}\marg{field} without the check of the index.
  Section~\ref{sec:any-field} shows examples.
\end{function}

\begin{function}{\cffsetauthors, \cffauthornames}
  \begin{syntax}
    \cs{cffsetauthors} \oarg{keys}
    \cs{cffauthornames}
  \end{syntax}
  \cs{cffsetauthors} declares the authors of the citation for \cs{maketitle}, as
  Section~\ref{sec:setauthors} describes. Call this function once after
  \cs{includecff}. \cs{cffauthornames} expands to the names of the authors,
  separated by commas and made by the \texttt{name} template. The \meta{keys}
  are
  \begin{description}
    \item[\texttt{style=}\textmd{\meta{name}}] selects a registered author
          style, loading its definition file if needed. The default is the
          |style| option of the package, or else |standard|.
          Section~\ref{sec:builtin-styles} lists the built-in styles, and
          Section~\ref{sec:author-styles} explains how to write others.
    \item[\texttt{name=}\textmd{\meta{template}}] makes the name of an author.
          |#1| takes a field of the author. The default is
          |#1{given-names}~#1{family-names}|.
    \item[\texttt{affiliation-mark=}\textmd{\meta{style}}] numbers the
          affiliations with |alph| (the default), |Alph|, |arabic|, |roman|, or
          |Roman|.
    \item[\texttt{separator=}\textmd{\meta{text}}] separates the marks of an
          author. The default is a comma.
    \item[\texttt{contact=}\textmd{\meta{template}}] is the footnote of an
          author who is a contact. |#1| takes a field of the contact. The
          default is |E-mail: #1{email}|, and an empty template gives no
          footnotes.
    \item[\texttt{note=}\textmd{\marg{index}\marg{text}}] adds a footnote with
          \meta{text} to the \meta{index}-th author, such as a current
          affiliation. \meta{index} is an integer expression, such as
          |\cffcount{authors}| for the last author. The key can be given several
          times. The footnotes follow those of the contacts, in order.
    \item[\texttt{author=}\textmd{\meta{template}}] declares an author, with the
          marks |#1| and the name |#2|.
    \item[\texttt{affiliation=}\textmd{\meta{template}}] declares an
          affiliation, with the mark |#1| and the name |#2|. An empty template
          gives no affiliations.
  \end{description}
\end{function}

\begin{function}{\cffdeclareauthorstyle}
  \begin{syntax}
    \cs{cffdeclareauthorstyle} \marg{name} \marg{keys}
  \end{syntax}
  Registers an author style globally. See Section~\ref{sec:author-styles} for
  naming rules, definition files, templates, lifecycle hooks, and the keys of
  the check.
\end{function}

\begin{function}{\cffemit, \cffrenderauthor, \cffrenderaffiliation}
  \begin{syntax}
    \cs{cffemit} \marg{declaration}
    \cs{cffrenderauthor} \marg{index}
    \cs{cffrenderaffiliation} \marg{index}
  \end{syntax}
  Plugin code sends a final declaration to \cs{cffemit}, which executes it
  during normal compilation and collects it during export. In a custom renderer,
  \cs{cffrenderauthor} and \cs{cffrenderaffiliation} apply the current templates
  to an author or a distinct affiliation. Their indices are integer expressions
  and use the same numbering as the public field accessors.
\end{function}

\begin{function}[EXP]{\cffauthor}
  \begin{syntax}
    \cs{cffauthor} \marg{index} \marg{field}
  \end{syntax}
  Expands to the \meta{field} of the \meta{index}-th author, counting from~1,
  and reports an error if there is no such author. \meta{field} is a key of the
  author entry in the CFF file, such as \texttt{given-names} or
  \texttt{family-names}. A field that the author does not have expands to
  nothing. |\cffcount{authors}| is the number of authors.
\end{function}

\begin{function}{\cffforeachauthor, \cffauthorindex}
  \begin{syntax}
    \cs{cffforeachauthor} \marg{code}
    \cs{cffauthorindex}
  \end{syntax}
  \cs{cffforeachauthor} runs \meta{code} once for each author of the citation,
  in order, and \cs{cffauthorindex} expands to the index of the current author,
  counting from~1.
\end{function}

\begin{function}[EXP]
  {
    \cffauthoraffiliationcount, \cffauthoraffiliation,
    \cffconvertaffiliationindex
  }
  \begin{syntax}
    \cs{cffauthoraffiliationcount} \marg{index}
    \cs{cffauthoraffiliation} \marg{index} \marg{k}
    \cs{cffconvertaffiliationindex} \marg{index} \marg{k}
  \end{syntax}
  Expand to the number of affiliations of the \meta{index}-th author, which is 0
  if the author has none, to the \meta{k}-th of them, and to its number among
  the distinct affiliations of the citation, which \cs{cffaffiliation} and
  \cs{cffforeachaffiliation} use.
\end{function}

\begin{function}{\cffforeachauthoraffiliation, \cffauthoraffiliationindex}
  \begin{syntax}
    \cs{cffforeachauthoraffiliation} \marg{index} \marg{code}
    \cs{cffauthoraffiliationindex}
  \end{syntax}
  \cs{cffforeachauthoraffiliation} runs \meta{code} once for each affiliation of
  the \meta{index}-th author, in order, and \cs{cffauthoraffiliationindex}
  expands to the index of the current affiliation among those of the author,
  counting from~1.
\end{function}

\begin{function}[EXP]{\cffaffiliationcount, \cffaffiliation}
  \begin{syntax}
    \cs{cffaffiliationcount}
    \cs{cffaffiliation} \marg{n}
  \end{syntax}
  Expand to the number of distinct affiliations of the citation, and to the
  \meta{n}-th of them.
\end{function}

\begin{function}{\cffforeachaffiliation, \cffaffiliationindex}
  \begin{syntax}
    \cs{cffforeachaffiliation} \marg{code}
    \cs{cffaffiliationindex}
  \end{syntax}
  \cs{cffforeachaffiliation} runs \meta{code} once for each distinct affiliation
  of the citation, in order, and \cs{cffaffiliationindex} expands to the number
  of the current affiliation.
\end{function}

\begin{function}[EXP]{\cffcontact}
  \begin{syntax}
    \cs{cffcontact} \marg{index} \marg{field}
  \end{syntax}
  Expands to the \meta{field} of the \meta{index}-th contact, counting from~1.
  As for \cs{cffauthor}, \meta{field} is a key of the contact entry, such as
  \texttt{email}, and a field that the contact does not have expands to nothing.
  |\cffcount{contact}| is the number of contacts, which is 0 if there are none.
\end{function}

\begin{function}{\cffforeachcontact, \cffcontactindex}
  \begin{syntax}
    \cs{cffforeachcontact} \marg{code}
    \cs{cffcontactindex}
  \end{syntax}
  \cs{cffforeachcontact} runs \meta{code} once for each contact of the citation,
  in order, and \cs{cffcontactindex} expands to the index of the current
  contact, counting from~1.
\end{function}

\section{Errors and warnings}

The following errors stop compilation.
\begin{description}
  \item[CFF file `\textmd{\meta{file}}' was not found.] \meta{file} is not in
        the current directory or the \TeX{} search path.
  \item[pdfLaTeX requires unrestricted shell escape \ldots] Use Lua\LaTeX{}, or
        run pdf\LaTeX{} with |--shell-escape|.
  \item[Cannot read CFF file: \textmd{\meta{reason}}.] The file cannot be used.
        For example, it has no top-level key given by \texttt{source}, or that
        key does not hold a mapping, or the selected citation has incorrect
        structure, or an affiliation breaks the rules of
        Section~\ref{sec:affiliations}.
  \item[Install cfflatex.lua alongside import-citation-cff.sty.] \pkg{import-citation-cff}
        is incompletely installed.
\end{description}

The following errors are reported while using the commands of
Section~\ref{sec:reference}.
\begin{description}
  \item[Call \cs{includecff} first.] No CFF file has been read yet.
  \item[style=\textmd{\meta{name}} needs the \textmd{\meta{package}} package.] Load
        \meta{package}, which the |requires| key of the style lists, before
        \cs{cffsetauthors}.
  \item[Invalid author style name `\textmd{\meta{name}}'.] The name breaks the
        rules of Section~\ref{sec:author-styles}.
  \item[Author style `\textmd{\meta{name}}' is not registered \ldots] The
        definition file of the style was not found.
  \item[Author style `\textmd{\meta{name}}' was not registered by its file.] The
        definition file registers another name.
  \item[Author style `\textmd{\meta{name}}' is already registered.] Each name
        can be registered once.
  \item[The key `\textmd{\meta{key}}' is only allowed in an author style definition.] The
        check keys are given to \cs{cffsetauthors}.
  \item[Invalid check region `\textmd{\meta{region}}'.] The |check-region| key
        of the author style of the document lists an unknown region, or hooks
        without exactly two arguments.
  \item[Author index `\textmd{\meta{index}}' is out of range.] The citation has
        fewer than \meta{index} authors.
  \item[Affiliation `\textmd{\meta{k}}' is out of range.] The author or the
        citation has fewer than \meta{k} affiliations.
  \item[Contact `\textmd{\meta{index}}' is out of range.] The citation has fewer
        than \meta{index} contacts.
  \item[Not inside \cs{cffforeachauthor}.] \cs{cffauthorindex} is used outside
        the loop.
  \item[Not inside \cs{cffforeachcontact}.] \cs{cffcontactindex} is used outside
        the loop.
  \item[Not a value: \textmd{\meta{path}}.] \cs{cff} is given the path of a list
        or a mapping.
  \item[Not a list: \textmd{\meta{path}}.] \cs{cffcount} is given the path of a
        value or a mapping.
  \item[Not inside an affiliation loop.] \cs{cffaffiliationindex} is used
        outside the loops over affiliations.
  \item[Not in an author affiliation loop.] The index of an affiliation of an
        author is used outside the loop over the affiliations of the author.
\end{description}

The following warnings are issued by the check of Section~\ref{sec:check}, after
the region it checks, such as \cs{maketitle}.
\begin{description}
  \item[\cs{title} does not use the title of the citation.] The title page does
        not show the title of the citation.
  \item[\cs{author} does not use author(s) \textmd{\meta{indices}} of the citation.] The
        title page does not show these authors.
  \item[The title page does not use `\textmd{\meta{field}}' of the citation.] The
        region does not show this field.
  \item[The title page does not use author(s) \ldots] The region does not show
        these authors.
\end{description}

\section{License}

\pkg{import-citation-cff} is distributed under the MIT License. Its source code
is at \url{https://github.com/JSS95/cfflatex}, where bugs can be reported.

% Long URLs leave ragged lines rather than stretched spaces.
\raggedright
% Number the references in the order they are first cited.
\bibliographystyle{unsrt}
\bibliography{import-citation-cff}

\end{document}