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