\documentclass{ltxdockit}[2011/03/25]
\usepackage{btxdockit}
\usepackage{fontspec}
\usepackage[mono=false]{libertine}
\usepackage{microtype}
\usepackage[american]{babel}
\usepackage[strict]{csquotes}
\setmonofont[Scale=MatchLowercase]{DejaVu Sans Mono}
\usepackage{shortvrb}
\usepackage{pifont}
\usepackage{minted}
\setminted{breaklines}
\hypersetup{citecolor=black}
% Usefull commands
\newcommand{\biblatex}{\emph{biblatex}\xspace}
\newcommand{\claves}{\emph{claves}\xspace}
\newcommand{\clavis}{\emph{clavis}\xspace}
\pretocmd{\bibfield}{\sloppy}{}{}
\pretocmd{\bibtype}{\sloppy}{}{}
\newcommand{\namebibstyle}[1]{\texttt{#1}}
% Meta-datas
\titlepage{%
  title={Manage \claves with \biblatex},
  subtitle={New fields},
  email={maieul <at> maieul <dot> net},
  author={Maïeul Rouquette},
  revision={1.2.0},
  date={2017/04/09},
  url={https://git.framasoft.org/maieul/biblatex-claves}}

\usepackage[citestyle=verbose,bibstyle=claves]{biblatex}
\bibliography{biblatex-claves.bib}
\bibliography{biblatex-claves-ref.bib}
\AddBiblatexClavis{BHG}
\AddBiblatexClavis{CANT}
\begin{document}

\printtitlepage
\tableofcontents


\section{Aim of the package}

When studying antic and medieval literature, we may find many different texts published with the same title, or, in contrary, the same text published with different titles.
To avoid confusion, scholars have published \claves, which are books listing ancient texts, identifying them by an identifier --- a number or a string of text.
For example, for early Christianity, we have the \citetitle{BHG_3} (BHG),\footcites{BHG_3}{BHG_auctarium}{BHG_novum_auctarium}, the \citetitle{CANT} (CANT),\footcite{CANT} and other \claves.
 
It could be useful to print the identifier of a texts in one specific \clavis, or in many \claves.

This package allows us to create new field for different \claves, and to present all these fields in a consistent way.
 
Considering this example:
\inputminted{tex}{biblatex-claves.bib}

It will be typeset as:
\begin{quotation}
\cite{BHG225}
\end{quotation}

Here, we can see the \enquote{BHG} and \enquote{CANT} identifiers.
 
\section{Use}

\subsection{Requirement}

The package requires \biblatex~3.5 or later.

\subsection{Loading the package}

As the package defines new fields, it must be loaded as a bibliography style:
\begin{minted}{latex}
\usepackage[bibstyle=claves,citestyle=<your-citestyle>]{biblatex}
\end{minted}
The \emph{verbose} bibliography style is automatically loaded.

If you must load an other bibliography style, or if you need to load package which requires to be loaded as bibliography style, like \emph{biblatex-bookinother}, you must use the \emph{biblatex-multiple-dm} package.
 For example:
\begin{minted}{latex}
\usepackage[tools={claves,bookinther},bibstyle=verbose]{biblatex-multiple-dm}
\usepackage[bibstyle=multiple-dm,citestyle=<your-citestyle>]{biblatex}
\end{minted}

Read the \emph{biblatex-multiple-dm} handbook for more details.

\subsection{Defining the \claves}

You must define which \claves\  you want to use, using \cs{AddBiblatexClavis} \textbf{in your preamble}. 
This command takes on argument, which is the abbreviated form of the concerned \clavis.
 For example, in this handbook, the preamble contains:
\begin{minted}{latex}
\AddBiblatexClavis{BHG}
\AddBiblatexClavis{CANT}
\end{minted}
Note the following points:
\begin{itemize}
  \item The order of \cs{AddBiblatexClavis} determines in which order will be typeset the \claves\ in bibliographic entries.
 \item The case of the argument will be used for typesetting the \claves in bibliographic entries.
\end{itemize}
 
After that, you just have to add the fields in the concerned entry of the \verb+.bib+ file.
Notes that if you don't call the concerned \cs{AddBiblatexClavis}, the \clavis\  won't be typeset.
 That allows you to decide, in the last time of your work, which \claves you will use.

 \subsection{Customizing style}
You can  redefine:
\begin{itemize}
  \item The \cs{multiclavesseparator} macro, which defines which character will be typeset between the different \claves\ identifiers. By default, a semicolon.
  \item The \cs{clavisseparator} macro, which defines which character will be typeset between the \clavis abbreviated form and the \clavis identifier. By default, just a space.
  \item The \verb+claves+ fieldformat, which defines the way all the \claves and identifier will be typeset. By default, in brackets.
  \item The \cs{clavisformat} macro, which defines the way individual clavis abbreviation will by typse. For example, if you want italic/emphaze, use:
  \begin{minted}{latex}
\renewcommand{\clavisformat}[1]{\emph{#1}}
  \end{minted}
 By default, between parenthesis.
\end{itemize}
Note that you must use the \biblatex\ punctuation macro.
Here, the default definition:
\begin{minted}{latex}
\newcommand{\multiclavesseparator}{\addsemicolon\ifpunct{\addspace}{}}
\newcommand{\clavisseparator}{\addspace}
\DeclareFieldFormat{claves}{\mkbibparens{#1}}
\end{minted}
\subsection{Printing the list of \claves}

You could want to print the list of the \claves used, with the bibliographic reference.
 To do, you must define some entries in your \verb+.bib+ file corresponding to the \claves:
\inputminted{tex}{biblatex-claves-ref.bib}

As you can see, the \citetitle{BHG_3} claves is in reality composed by one book in three volumes and two supplements (\enquote{auctarium}).
 We could define a \bibtype{set} entry directly in the \verb+.bib+ file.
 However, it could happen that you need to cite each entry individually, and a global \bibtype{set} entry does not allow it.\footnote{Cf. \url{https://github. com/plk/biblatex/issues/470}.}

 That's why the best way is to define locally entry set in a \verb+refsection+ environment.\footnote{Read the \biblatex\ handbook about this environment, which allow you to have a local bibliography.} Consequently, we provide a \cs{citeallclaves} macro, which automatically add a \cs{nocite} for all the \claves\ defined by the \cs{AddBiblatexClavis} macros in your preamble.

 We also provide a \verb+claves+ sorting scheme, and a \verb+claves+ bibliographic environment. So to print the concerning \claves, while defining local \bibtype{set} entry, you must do something like this:
\begin{minted}{latex}
\begin{refsection}
  \begin{refcontext}[sorting=claves]
    \setlength{\shorthandwidth}{3em}
    \defbibentryset{BHG}{BHG_3,BHG_auctarium,BHG_novum_auctarium}
    \citeallclaves% Be careful on the order
    \printbibliography[env=claves,title=List of \emph{claves}]
  \end{refcontext}
\end{refsection}
\end{minted}

That produces the following output:
\begin{quotation}
\begin{refsection}
  \begin{refcontext}[sorting=claves]
    \setlength{\shorthandwidth}{3em}
    \defbibentryset{BHG}{BHG_3,BHG_auctarium,BHG_novum_auctarium}
    \citeallclaves
    \printbibliography[env=claves,title=List of \emph{claves}]
  \end{refcontext}
\end{refsection}
\end{quotation}

Note the following points:
\begin{itemize}
  \item The bibliographic keys are used as label. Consequently, be careful with case, as \emph{biber} is sensitive to it.
  \item Many time, \claves have a shorter former too long for the default label size defined by \biblatex.
    That why, in our example, we have redefined the \cs{shorthandwidth} length.
  \item Contrary to the default style, all the entry of a \bibtype{set} are in there own paragraph, and we use dashes when citing many times the same author. If you want to define your own bibliographic environment devoted to the \claves, you can use the following lines insides:
    \begin{minted}{latex}
\renewcommand{\entrysetpunct}{\endgraf}
\clavesadddashinset
    \end{minted}
\end{itemize}

\section{Knowing if an entry is used as \emph{clavis}}

You may want to know if an entry is a \emph{clavis}, that is its entrykey was added to \cs{AddBiblatexClavis}. To test it, you must use

\begin{minted}{latex}
\iffieldundef{claves_definition}%
  {<If not a clavis>}%
  {<If a clavis>}%
\end{minted}

\section{Notes about inheritance}

The \bibfield{claves} field are not inherited from the main entry when a subentry is an \bibtype{inbook} entry.
\section{Credits}

This package was created for Maïeul Rouquette's phd dissertation\footnote{\url{http://apocryphes.hypothese.org}.} in 2016. 
It is licensed on the \emph{\LaTeX\ Project Public License}.\footnote{\url{http://latex-project.org/lppl/lppl-1-3c.html}.}.


All issues can be submitted, in French or English, in the Framasoft issues page.\footnote{\url{https://git.framasoft.org/maieul/biblatex-claves/issues}.}


\section{Change history}

\begin{changelog}

\begin{release}{1.2.0}{2017-04-09}
\item Mark the entries used as \emph{claves} with \bibfield{claves\_definition} field.
\item Add \cs{clavisformat} macro, for more customization.
\end{release}

\begin{release}{1.1.0}{2016-09-25}
\item Prevent inheritance of the \bibfield{claves} field for \bibtype{inbook} entries.
\end{release}

\begin{release}{1.0.0}{2016-09-11}
\item First public release.
\end{release}

\end{changelog}
\end{document}
