% \iffalse meta-comment
%
% Copyright (C) 2024 Christian Schreinemachers
%
% This work may be distributed and/or modified under the conditions
% of the LaTeX Project Public License, either version 1.3c of this
% license or (at your option) any later version. The latest version
% of this license is in
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008-05-04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The current maintainer of this work is Christian Schreinemachers.
%
% This work consists of the files
%    README.md
%    bib2qr.dtx
%    bib2qr.ins
% and the derived files
%    bib2qr.sty
%    bib2qr.pdf
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \fi
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{bib2qr}
%<package>         [2024-07-31 v0.2 Cite BibTeX entries with QR codes]
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage[toc]{multitoc}
\usepackage{geometry}
\usepackage{fancyvrb}
% Declare example reference entries
\begin{filecontents}[overwrite]{example-references.bib}
  @software{bib2qr,
    author  = {Schreinemachers, Christian},
    title   = {bib2qr - A LaTeX package for citing BibTeX entries with QR codes},
    url     = {https://codeberg.org/Cs137/bib2qr/releases/tag/v0.2},
    version = {v0.2},
    date    = {2024-07-31}
  }
  @article{Doe2024,
    author  = {Doe, Jane},
    title   = {A comprehensive study on example generation},
    journal = {Journal of Examples},
    year    = {2024},
    volume  = {42},
    pages   = {1982--2024},
    doi     = {10.1234/example.2024.001}
  }
  @article{Mustermann2023,
    author  = {Mustermann, Erika},
    title   = {Limitations in including electronic references in articles},
    journal = {Journal of Examples},
    year    = {2023},
    volume  = {23},
    pages   = {624--666}
  }
\end{filecontents}
\usepackage[style=authoryear,sorting=none]{biblatex}
\addbibresource{example-references.bib}
\usepackage[%
  pdfusetitle,%
  hyperindex=false,%
  pdfsubject={LaTeX package documentation},%
  pdfkeywords={bib2qr, biblatex, latex, qrcode, documentation}%
]{hyperref}
\usepackage{scrextend}
\usepackage{cleveref}
\usepackage[qrwidth=1.25cm]{bib2qr}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\DoNotIndex{\begin,\DeclareBibliographyDriver,\DeclareCiteCommand,\DeclareFieldFormat,
            \DeclareKeys,\dimexpr,\edef,\end,\equal,\fullcite,\hspace,\IfBeginWith,
            \ifboolexpr,\iffieldundef,\ifthenelse,\linewidth,\multicitedelim,
            \NewDocumentCommand,\newcommand,\noindent,\par,\parindent,\printfield,
            \ProcessKeyOptions,\qrcode,\RequirePackage,\relax,\SetKeys,\space,
            \thefield,\usebibmacro,\usedriver}
\setcounter{IndexColumns}{2}
\setlength{\IndexMin}{40ex}
\setlength{\columnseprule}{.4pt}
\addtolength{\oddsidemargin}{2cm}
\addtolength{\textwidth}{-2cm}
\begin{document}
  \DocInput{bib2qr.dtx}
\end{document}
%</driver>
% \fi
%
%  \pagestyle{headings}
%
%  \newcommand*{\package}[1]{\textsf{#1}}
%  \newcommand*{\ctanpkg}[1]{\href{https://ctan.org/pkg/#1}{\package{#1}}}
%  \newcommand*{\opt}[1]{\texttt{#1}}
%  \newcommand*{\default}[1]{(default: \opt{#1})}
%
%
% ^^A -----------------------------
%
%  \changes{v0.2}{2024-07-31}{%
%    Initial release,
%    convert into dtx,
%    add documentation,
%    rename internal macros,
%    add \opt{qrdelimiter} option
%  }
%  \changes{v0.1}{2024/06/16}{Initial version}
%
%  \GetFileInfo{bib2qr.sty}
%
%
% ^^A -----------------------------
%
%  \title{The \package{bib2qr} package}
%  \author{Christian Schreinemachers}
%  \date{%
%    Released \filedate\thanks{%
%      \package{bib2qr}~\fileversion
%      ~(\href{https://codeberg.org/Cs137/bib2qr/releases/tag/\fileversion}{source code})}%
%  }
%  \maketitle
%
%
% ^^A -----------------------------
%
%  \begingroup
%    \hypersetup{
%        linkcolor=.,
%        citecolor=.,
%        urlcolor=.,
%    }
%    \begin{abstract}
%      The \package{bib2qr} package provides functionality to cite BibTeX entries
%      with QR codes for easy sharing and referencing. The target of the QR code
%      is the entry's digital object identifier (DOI), or URL if no DOI exists.
%      It is realised in the \cs{qrcite} macro, via the \LaTeX{} packages
%      \package{biblatex} and \package{qrcode}. In addition to the \cs{qrcite}
%      command, the package contains the \cs{qrfullcite} macro, which requires
%      only a BibTeX key as argument and allows to generate output that might
%      look as follows:\\
%      \textcolor{red}{\qrfullcite[noindent]{bib2qr}}
%    \end{abstract}
%  \endgroup
%
%
% ^^A -----------------------------
%
%  \tableofcontents
%
%
% ^^A -----------------------------
%
%  \section{Introduction}
%  ^^A
%  I like to include \href{https://en.wikipedia.org/wiki/QR_code}{quick-response (QR) codes}
%  of references on slides created with \LaTeX{} \ctanpkg{beamer}. Previously,
%  I did this by using the \ctanpkg{qrcode} package and manually declaring the
%  URL of the reference's digital object identifier (DOI). Occasionally, I also
%  add human-readable information generated via \cs{fullcite} from the
%  \ctanpkg{biblatex} package.
%
%  To avoid manually declaring the URL and calling two separate commands for QR
%  codes and human-readable citations, I developed this \LaTeX{} package. It
%  automates the inclusion of QR codes by a \package{biblatex} bibliography
%  driver\footnote{%
%    \href{http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf\#page=166}
%    {\package{biblatex} documentation p.\,166 (v3.20)}%
%  },
%  which uses field formats to display QR codes for the entry's \opt{doi}
%  and \opt{url} fields with the \package{qrcode} package. You can cite any
%  reference from your bibliography with this driver by declaring its \meta{key}
%  to the \cs{qrcite} command. The latter is a cite command\footnote{%
%    \href{http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf\#page=186}%
%    {\package{biblatex} documentation p.\,186 (v3.20)}%
%    \label{biblatexCiteCommand}%
%  },
%  which ensures that any referenced QR code is also listed in the reference list.
%
%  For the inclusion of both, QR codes and human-readable citation information
%  in a single step, I introduced the \cs{qrfullcite} command. It applies the
%  \cs{qrcite} command and the \cs{fullcite} command from the \package{biblatex}
%  package, ensuring clarity and ease of reference not only on \package{beamer}
%  slides, but in any \LaTeX{} document.
%
%
% ^^A -----------------------------
%
%  \section{Usage}
%  ^^A
%    Load the package in your document's preamble and specify any of the
%    options described in the next subsection as follows:
%
%    \begin{quote}
%      \cs{usepackage}\oarg{option(s)}\{bib2qr\}
%    \end{quote}
%
%
% ^^A -----------------------------
%
%    \subsection{Options}
%    ^^A
%    In order to change the default behaviour of this package, declare one
%    or more of the options described in this subsection with your desired
%    value.
%
%    \begin{description}
%
%    \item[\opt{doiurlbase=\meta{string}}] \default{https://doi.org/}
%      specifies the prefix to convert a DOI string into its URL. If the DOI
%      string starts with \meta{doiurlbase}, it is used as is to generate a
%      QR code. Otherwise, the DOI string is appended to \meta{doiurlbase} to
%      form the DOI's URL, which is then used to generate the QR code.
%      In normal use cases this option does not require any adjustment.
%
%    \item[\opt{qrdelimiter=\meta{sepcode}}] \default{\cs{space}}
%      specifies the delimiter of QR codes generated by \cs{qrcite} in multicite
%      mode. It is shown between the individual QR codes of multiple references
%      created by \cs{qrcite}\marg{key1,key2,\dots keyN} and \emph{``\dots is
%      arbitrary code to be executed after each iteration...''}\,\footref{biblatexCiteCommand}.
%      The examples shown in this document were generated considering the
%      default \opt{qrdelimiter}.
%
%    \item[\opt{qrversion=\meta{version specification}}] \default{0}
%      sets the version of the QR code. Consult the \package{qrcode} documentation
%      for details about the \meta{version specification}\footnote{%
%        \href{http://mirrors.ctan.org/macros/latex/contrib/qrcode/qrcode.pdf\#page=3}
%        {\package{qrcode} documentation p.\,3 (v1.51)}%
%      }.
%      The examples shown in this document were generated considering the
%      default \opt{qrversion}.
%
%    \item[\opt{qrwidth=\meta{dimen}}] \default{2cm}
%      sets the width of the QR code. The value is used to determine the
%      width for the output of the \cs{fullcite} macro and is passed to
%      \package{qrcode} as \opt{height} option. The default value is quite
%      suitable for usage in \LaTeX{} \package{beamer} slides, but in such
%      documents as this one, a smaller width might be desired. The examples
%      shown in this document were generated using \opt{qrwidth=1.25cm}.
%
%    \end{description}
%
%
% ^^A -----------------------------
%
%  \subsection{Macros}
%   ^^A
%    \subsubsection*{\cs{qrcite}\marg{key(s)}}
%
%    \DescribeMacro{\qrcite}
%    QR code(s) with a link to the reference's DOI or URL can be generated
%    using the \cs{qrcite} command. The target of the QR code is the entry's
%    DOI converted into a URL, or the URL iteself. In case the BibTeX entry has
%    no DOI and no URL, it does nothing besides raising a warning.
%   ^^A
%    The output for some example entries is shown underneath. If you
%    would like to replicate the examples, you can find the entries
%    sources as \cref{ssec:example_bib}. The colours are defined in the
%    examples, as this functionality is out of scope of the package
%    \package{bib2qr}. Moreover, \package{hyperlink} is configured in such
%    a way that the links in the following examples consider the font colour,
%    usually links would be presented in the colour defined as \opt{linkcolor}.
%
%    The example displayed in blue was created via \textcolor{blue}{%
%    \cs{qrcite\{bib2qr\}}}. The QR code in red next to it was generated
%    via \textcolor{red}{\cs{qrcite\{Doe2024\}}}. The entry of the latter has a
%    DOI, while the entry of the blue example represents a BibTeX entry without
%    a DOI, but there is a value assigned to its URL field.
%   ^^A
%    The macro \cs{qrcite} is a cite command, thus it can be used to cite multiple
%    references, as shown in black (\cs{qrcite\{bib2qr,Doe2024\}}), and entries
%    cited via \cs{qrcite} are included in the document's bibliography
%    (cf. \cref{ssec:example_ref}).
%
%    \begingroup
%      \hypersetup{
%          linkcolor=.,
%          citecolor=.,
%          urlcolor=.,
%      }
%
%      \par\smallskip%
%      \noindent%
%      \textcolor{blue}{\qrcite{bib2qr}}
%      \textcolor{red}{\qrcite{Doe2024}}
%      \qrcite{bib2qr,Doe2024}
%      \par\medskip%
%
%      \subsubsection*{\cs{qrfullcite}\marg{key}}
%
%      \DescribeMacro{\qrfullcite}
%      This command displays the QR code of a BibTeX entry's DOI link or URL and
%      a full citation. The QR code is generated by \cs{qrcite} and the full
%      citation by \cs{fullcite}, provided by the package \package{biblatex}.
%      Each output is presented in individual minipages which are placed next to
%      each other, as shown in the examples underneath
%      (\textcolor{blue}{\cs{qrfullcite\{bib2qr\}}},
%      \textcolor{red}{\cs{qrfullcite[noindent]\{Doe2024\}}}).
%
%      Please note that \cs{qrfullcite} does \textbf{not} support group
%      citations and accepts only a single \meta{key} as argument.
%
%      \textcolor{blue}{\qrfullcite{bib2qr}}%
%      \medskip%
%      \textcolor{red}{\qrfullcite[noindent]{Doe2024}}%
%      \medskip%
%    \endgroup
%
%    The output of \cs{qrfullcite} is considered as its own paragraph, thus it
%    may be indented, like in this document (see blue example). You can prevent
%    the latter by providing the \opt{noindent} option when calling the macro,
%    as done in the red example.
%
%    The first minipage has the width of the package option \opt{qrwidth}
%    and displays the output of \cs{qrcite}\marg{key}. The second minipage
%    occupies the remaining width of \cs{linewidth} considering a gap of
%    \opt{0.5em} and \cs{parindent}, if the latter is not deactivated via the
%    \opt{noindent} option. It shows the output of \cs{fullcite}\marg{key}.
%
%
% ^^A -----------------------------
%
%  \subsection{Hints}
%  ^^A
%  If the \package{hyperref} package is loaded, not only the DOI/URL strings,
%  but also the QR codes are presented as links. It was modified in this
%  document to allow you to distinguish the output of the individual macro calls
%  in a better way. The previous example without any modifications of the
%  document settings and without deactivating the indentation looks as follows:\\
%
%  \qrfullcite{Doe2024}%
%
%
% ^^A -----------------------------
%
%  \subsection{Known limitations}
% ^^A
%  In case no QR code can be generated by \cs{qrcite} called via \cs{qrfullcite},
%  the output of \cs{fullcite} is nevertheless indented by the width assigned to
%  the \opt{qrwidth} package option and the length of the gap of \opt{0.5em}),
%  as shown in orange below (\textcolor{orange}{\cs{qrcite\{Mustermann2023\}}}).
%
%  \textcolor{orange}{\qrfullcite{Mustermann2023}}%
%
%
% ^^A -----------------------------
%
%  \MaybeStop{
%
%    \IndexPrologue{%
%      \section{Index}
%      Numbers written in italic refer to the page where the corresponding entry
%      is described; numbers underlined refer to the code line of the definition;
%      numbers in roman refer to the code lines where the entry is used.
%    }
%    \PrintIndex
%
%    \GlossaryPrologue{%
%      \section{Change History}
%      The changes listed in this section aim to provide a brief overview of the
%      changes introduced into the package \package{bib2qr}. The
%      \href{https://codeberg.org/Cs137/bib2qr/}{package repository on Codeberg}
%      contains a
%      \href{https://codeberg.org/Cs137/bib2qr/src/branch/main/CHANGELOG.md}{changelog file},
%      consult it to read a detailed description of the changes introduced into
%      this package.
%    }
%    \PrintChanges
%
%   ^^A -----------------------------
%
%    \newpage
%    \appendix
%
%    \section{Appendix}
%
%    The examples presented in this document are based on the
%    BibTeX entries listed in \ref{ssec:example_bib} and result
%    in the bibliography shown as \ref{ssec:example_ref} (\package{biblatex}
%    options: \opt{style=authoryear}, \opt{sorting=none}).
%
%    \subsection{Example BibTeX entries}
%    \label{ssec:example_bib}
%    \small{%
%      \VerbatimInput[firstline=5]{example-references.bib}
%    }
%
%    \subsection{Example bibliography}
%    \label{ssec:example_ref}
%    \printbibliography[heading=none]
%
%  }
%
%
% ^^A -----------------------------
%
%  \section{Implementation}
%  ^^A
%
%  \subsection{Dependencies}
%  ^^A
%    In order to use \package{bib2qr}, the \LaTeX{} packages
%      \ctanpkg{biblatex},
%      \ctanpkg{ifthen},
%      \ctanpkg{qrcode}, and
%      \ctanpkg{xstring}
%    are required as package dependencies.
% \iffalse
%<*package>
% \fi
%    \begin{macrocode}
\RequirePackage{biblatex}
\RequirePackage{ifthen}
\RequirePackage{qrcode}
\RequirePackage{xstring}
%    \end{macrocode}
%
%
%  \subsection{Options}
%   ^^A
%  The package options are internally available as \cs{@bibiiqr@}\meta{option}.
%    \begin{macrocode}
\DeclareKeys[@bibiiqr]{
  doiurlbase.store = \@bibiiqr@doiurlbase,
  doiurlbase.usage = load,
  qrdelimiter.store = \@bibiiqr@qrdelimiter,
  qrdelimiter.usage = load,
  qrversion.store = \@bibiiqr@qrversion,
  qrversion.usage = load,
  qrwidth.store = \@bibiiqr@qrwidth,
  qrwidth.usage = load,
}%
%    \end{macrocode}
%
%  \subsubsection*{Assignement of default values}
%    \begin{macrocode}
\SetKeys[@bibiiqr]{
  doiurlbase=https://doi.org/,
  qrdelimiter=\space,
  qrversion=0,
  qrwidth=2cm,
}%
%    \end{macrocode}
%
%  \subsubsection*{Processing of package options}
%    \begin{macrocode}
\ProcessKeyOptions[@bibiiqr]\relax
%    \end{macrocode}
%
%  \subsection{Macros}
%
%  \begin{macro}{\@bibiiqr@showqr}
%    \marg{string}\\
%    Display a string as QR code considering the package options \opt{qrversion}
%    and \opt{qrwidth}.
%    \begin{macrocode}
\newcommand\@bibiiqr@showqr[1]{%
  \qrcode[height=\@bibiiqr@qrwidth,version=\@bibiiqr@qrversion]{#1}%
}%
%    \end{macrocode}
%  \end{macro}
%
%
%  \subsubsection{Field formats}
%
%  Custom field formats are defined to display a QR code of an entry's
%  \texttt{doi} and \texttt{url}.
%
%  \begin{macro}{@bibiiqr@fldFmtDoi}
%    Field format to display a DOI field's value (converted into an URL
%    considering the option \opt{@bibiiqr@doiurlbase}) as QR code using
%    macro \cs{@bibiiqr@showqr}.
%    \begin{macrocode}
\DeclareFieldFormat{@bibiiqr@fldFmtDoi}{%
  \IfBeginWith{#1}{\@bibiiqr@doiurlbase}%
    {\@bibiiqr@showqr{#1}}%
    {\@bibiiqr@showqr{\@bibiiqr@doiurlbase#1}}%
}%
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{@bibiiqr@fldFmtUrl}
%    Field format to display an URL field's value as QR code using \cs{@bibiiqr@showqr}.
%    \begin{macrocode}
\DeclareFieldFormat{@bibiiqr@fldFmtUrl}{\@bibiiqr@showqr{#1}}
%    \end{macrocode}
%  \end{macro}
%
%
%  \subsubsection{Bibliography driver}
%
%  \begin{macro}{@bibiiqr@bibDrvQR}
%    This bibliography driver
%    allows to display the QR code of an entry's DOI-, or URL field.
%    It applies the \cs{printfield}\oarg{format}\marg{field} macro, which is
%    provided by the \package{biblatex} package to displpay a QR code using the
%    \texttt{@bibiiqr@fldFmtDoi} or \texttt{@bibiiqr@fldFmtUrl} field format and
%    the corresponding field, respectively.
%
%    The DOI is preferred and the URL is only used if no value is assigned to
%    the DOI field. If neither the DOI, nor the URL field contains a value, a
%    package warning is raised.
%
%    \begin{macrocode}
\DeclareBibliographyDriver{@bibiiqr@bibDrvQR}{%
  \usebibmacro{begentry}%
  \ifboolexpr{test{\iffieldundef{doi}}}
    {%
      \ifboolexpr{test{\iffieldundef{url}}}%
%    \end{macrocode}
%    The entry has no DOI and no URL: Raise a warning.
%    \begin{macrocode}
      {%
        \PackageWarning{bib2qr}%
          {BibTeX entry without DOI or URL: \thefield{entrykey}}{}%
      }%
%    \end{macrocode}
%    The entry has no DOI but an URL: Display the \texttt{url} field's
%    value using the \texttt{@bibiiqr@fldFmtUrl} field format.
%    \begin{macrocode}
      {\printfield[@bibiiqr@fldFmtUrl]{url}}%
    }%
%    \end{macrocode}
%    The entry has a DOI: Display the \texttt{doi} field's value using
%    the \texttt{@bibiiqr@fldFmtDoi} field format.
%    \begin{macrocode}
    {\printfield[@bibiiqr@fldFmtDoi]{doi}}%
  \usebibmacro{finentry}%
}
%    \end{macrocode}
%  \end{macro}
%
%  \subsubsection{Author commands}
%
%  \begin{macro}{\qrcite}
%    \marg{key(s)}\\
%    Display the QR code of a BibTeX entry's DOI link or URL by introducing the
%    cite command \cs{qrcite}\marg{key}, which makes use of the previously
%    defined bibliography driver \texttt{@bibiiqr@bibDrvQR}. It requires at least
%    one BibTeX \marg{key} as argument.
%    \begin{macrocode}
\DeclareCiteCommand{\qrcite}
  {\usebibmacro{prenote}}%
  {\usedriver{}{@bibiiqr@bibDrvQR}}%
  {\@bibiiqr@qrdelimiter}%
  {\usebibmacro{postnote}}%
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\qrfullcite}
%    \changes{v0.2}{2024-07-31}{Add \opt{noindent} option}
%    \oarg{option(s)}\marg{key}\\
%    Display the QR code of a singe BibTeX entry's DOI link or URL and a full
%    citation of it. Specify \opt{noindent} as option, if the output should not
%    be indented.
%    \begin{macrocode}
\NewDocumentCommand{\qrfullcite}{O{}m}{%
  \par%
  \ifthenelse{\equal{#1}{noindent}}{%
    \noindent%
    \edef\@bibiiqr@mpiiwidth{\dimexpr\linewidth-\@bibiiqr@qrwidth-0.5em}%
  }{%
    \edef\@bibiiqr@mpiiwidth{%
      \dimexpr\linewidth-\parindent-\@bibiiqr@qrwidth-0.5em}%
  }%
  \begin{minipage}[t]{\@bibiiqr@qrwidth}
    \qrcite{#2}%
  \end{minipage}
  \hspace{0.5em}%
  \begin{minipage}{\@bibiiqr@mpiiwidth}
    \fullcite{#2}%
  \end{minipage}
  \par%
}%
%    \end{macrocode}
%  \end{macro}
%
% \iffalse
%</package>
% \fi
%
%
% ^^A -----------------------------
%
% \Finale