Enhance the bibliography options

Closes #7
se2p · Feb 22, 2024 · 8109e75 · 8109e75
1 parent dfc5c38
commit 8109e75
Show file tree

Hide file tree

Showing 4 changed files with 122 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,25 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- Enhance the options for bibliography styles, one can now choose between
+  `alphabetic` and `numeric` style.  The former loads the default BibLaTeX
+  `alphabetic` style, the latter uses ACM's numeric style.
+- For the new numeric style, we support an enhanced `\autocite` macro, which
+  typesets the citation in the margin column for the first appearance per
+  chapter.
+
+### Changed
+
+- The default citation style, when setting `biblatex=true` while loading the
+  `se2packages` package is now `numeric` based on the ACM numeric style instead
+  of `alphabetic`.  The latter can now be chosen explicitly.
+  See [issue #7](https://github.com/se2p/se2thesis/issues/7) for a discussion
+  on the general decision.
+
+### Changed
+
 ## [v3.2.0] – 2023–09–12
 
 ### Changed

diff --git a/examples/se2thesis-master-thesis-example.pdf b/examples/se2thesis-master-thesis-example.pdf
diff --git a/examples/se2thesis-master-thesis-example.tex b/examples/se2thesis-master-thesis-example.tex
@@ -3,7 +3,7 @@
   open=right,%
   twoside=true,%
   paper=a4,%
-  logofile={logo.png},%
+  logofile={logo.pdf},%
   thesistype=master,%
   UKenglish,%
 ]{se2thesis}
@@ -18,7 +18,7 @@
   selnolig=true,%
   widowcontrol=false,%
   microtype=true,%
-  biblatex=true,%
+  biblatex=numeric,%
   cleveref=true,%
 ]{se2packages}
 
@@ -72,7 +72,7 @@
 
 \section{Further Examples}
 
-We could reference the \TeX{} book~\cite{Knu86}.
+We could reference the \TeX{} book~\autocite{Knu86}.
 
 \begin{resq}
     What is \(41 + 1\)?
@@ -82,6 +82,8 @@ \section{Further Examples}
    It's 42, obviously!
 \end{summary}
 
+And using the auto-cite functionality to cite Knuth~\autocite{Knu86}.
+
 \backmatter
 
 \printbibliography

diff --git a/se2packages.dtx b/se2packages.dtx
@@ -324,11 +324,23 @@
 % We provide a load-time option to load and configure \pkg{biblatex}.
 % \begin{function}{biblatex}
 %   \begin{syntax}
-%     |biblatex| = \meta{true,false}
+%     |biblatex| = \meta{true,false,alphabetic,numeric}
 %   \end{syntax}
 %   Decides whether the package loads \pkg{biblatex}
 %   and sets the options for \pkg{biblatex} to the values we recommend.
 %   The default value is |false|, set it to |true| to load \pkg{biblatex}.
+%
+%   By setting the value to |alphabetic|, \pkg{se2packages} sets the citation
+%   style for \pkg{biblatex} to its alphabetic one; selecting |numeric| loads
+%   the numeric style as provided by the \pkg{acmart} bundle of the ACM.  The
+%   value |true| also loads the latter style as a default.
+%
+%   Note that for the |numeric| style, we provide an enhanced \cs{autocite}
+%   command, which does not only print the citation mark in the text but also
+%   a short entry listing of the bibliography entry in the margin column of the
+%   page.  This entry is only printed for the first occurence of a citation per
+%   chapter to not clutter the margin column too much.  The other citation
+%   commands from \pkg{biblatex} work as usual.
 % \end{function}
 %
 % Additionally,
@@ -475,10 +487,10 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\l_@@_biblatex_bool}
+% \begin{macro}{\l_@@_biblatex_tl}
 %   Whether or not to load and configure \pkg{biblatex}.
 %    \begin{macrocode}
-\bool_new:N \l_@@_biblatex_bool
+\tl_new:N \l_@@_biblatex_tl
 %    \end{macrocode}
 % \end{macro}
 %
@@ -538,7 +550,7 @@
     listings .bool_gset:N = \l_@@_listings_bool,
     listings .initial:n = false,
 
-    biblatex .bool_gset:N = \l_@@_biblatex_bool,
+    biblatex .tl_gset:N = \l_@@_biblatex_tl,
     biblatex .initial:n = false,
 
     selnolig .bool_gset:N = \l_@@_selnolig_bool,
@@ -609,7 +621,7 @@
     \bool_gset_true:N \l_@@_selnolig_bool
     \bool_gset_true:N \l_@@_luawidowcontrol_bool
     \bool_gset_true:N \l_@@_microtype_bool
-    \bool_gset_true:N \l_@@_biblatex_bool
+    \tl_gset:Nn \l_@@_biblatex_bool {true}
     \bool_gset_true:N \l_@@_cleveref_bool
   }
 %    \end{macrocode}
@@ -756,7 +768,7 @@
 %
 % Conditionally load and configure the \pkg{biblatex} package.
 %    \begin{macrocode}
-\bool_if:NT \l_@@_biblatex_bool
+\tl_if_eq:NnT \l_@@_biblatex_tl {alphabetic}
   {
     \msg_info:nnn { seiipackages } { load-package } { biblatex }
     \PassOptionsToPackage
@@ -782,6 +794,86 @@
         license=true,
       }
   }
+
+\bool_new:N \l_@@_biblatex_numeric_variants_bool
+\tl_if_eq:NnT \l_@@_biblatex_tl {true}
+  {
+    \bool_gset_true:N \l_@@_biblatex_numeric_variants_bool
+  }
+\tl_if_eq:NnT \l_@@_biblatex_tl {numeric}
+  {
+    \bool_gset_true:N \l_@@_biblatex_numeric_variants_bool
+  }
+
+\bool_if:NT \l_@@_biblatex_numeric_variants_bool
+  {
+    \msg_info:nnn { seiipackages } { load-package } { biblatex }
+    \PassOptionsToPackage
+      {
+        backend=biber,
+        backref=true,
+        citereset=chapter+,
+        citetracker=context,
+        giveninits=true,
+        hyperref=auto,
+        sorting=nyt,
+        datamodel=acmdatamodel,
+        style=acmnumeric,
+      } { biblatex }
+      \RequirePackage{biblatex}
+      \RequirePackage{ragged2e}
+      \RequirePackage[mark=arabic,shape=up]{sidenotesplus}
+
+      \newbibmacro{cite:authoryear}{%
+        \printtext[labelnumberwidth]{%
+          \usebibmacro{cite}%
+        }%
+        \setunit{\addspace}%
+        \printnames{labelname}%
+        \setunit{\printdelim{nameyeardelim}}%
+        \begingroup
+        \DeclareFieldFormat{date}{\mkbibparens{##1}}%
+        \printdate
+        \endgroup
+        \setunit*{\addcomma\space}%%% NEW
+        \printfield[title]{labeltitle}%%% NEW
+      }
+
+      \newrobustcmd*{\makebibmarginnote}[1]{%
+        \sidenote*{\blxmkbibnote{foot}{#1}}}
+
+      \DeclareCiteCommand{\maycite}[\makebibmarginnote]
+        {\usebibmacro{prenote}}
+        {\usebibmacro{citeindex}%
+         \usebibmacro{cite:authoryear}}
+        {\multicitedelim}
+        {\usebibmacro{postnote}}
+
+      \newcommand*{\cbx@savedcites}{}
+
+      \newcommand*{\cbx@margcitewrap}[1]{%
+        \global\let\cbx@savedcites\empty
+        \mkbibbrackets{#1}%
+        \cbx@savedcites
+      }
+
+      \DeclareCiteCommand{\margincite}[\cbx@margcitewrap]
+        {\usebibmacro{prenote}}
+        {\usebibmacro{citeindex}%
+         \usebibmacro{cite}%
+         \ifciteseen
+           {}
+           {\xappto\cbx@savedcites{\noexpand\maycite{\thefield{entrykey}}}}}
+        {\multicitedelim}
+        {\usebibmacro{postnote}}
+
+      \DeclareMultiCiteCommand{\margincites}[\cbx@margcitewrap]{\margincite}{\multicitedelim}
+
+      \DeclareAutoCiteCommand{margin}{\margincite}{\margincites}
+      \ExecuteBibliographyOptions{autocite=margin}
+      \newcommand{\bibliofont}{\footnotesize}
+      \DeclareFieldFormat{titlecase}{#1}% Preserve capitalisation of titles
+  }
 %    \end{macrocode}
 %
 % Conditionally load the \pkg{cleveref} package as the last of the preamble.