Bib-place: control the placement of a citeproc bibliography in a Pandoc template

bib-place/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Julien Dutant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bib-place/Makefile

@@ -0,0 +1,35 @@
+DIFF ?= diff --strip-trailing-cr -u
+
+.PHONY: test
+
+test: latex html
+
+latex: sample.md expected_filtered.tex expected_unfiltered.tex bib-place.lua
+	@pandoc -s --citeproc --to latex --template template $< \
+		| $(DIFF) expected_unfiltered.tex -
+	@pandoc -s --citeproc --lua-filter bib-place.lua --to=latex \
+		--template template $< | $(DIFF) expected_filtered.tex -
+
+html: sample.md expected_filtered.html expected_unfiltered.html
+	@pandoc -s --citeproc --to=html --template template $< \
+		| $(DIFF) expected_unfiltered.html -
+	@pandoc -s --citeproc --lua-filter bib-place.lua --to=html \
+		--template template $< | $(DIFF) expected_filtered.html -
+
+expected_filtered.html : sample.md bib-place.lua
+	@pandoc -s --citeproc --lua-filter bib-place.lua \
+	--output expected_filtered.html \
+	--template template $< \
+
+expected_filtered.tex : sample.md bib-place.lua
+	@pandoc -s --citeproc --lua-filter bib-place.lua \
+	--output expected_filtered.tex \
+	--template template $<
+
+expected_unfiltered.html : sample.md bib-place.lua
+	@pandoc -s --citeproc --output expected_unfiltered.html \
+	--template template $<
+
+expected_unfiltered.tex : sample.md bib-place.lua
+	@pandoc -s --citeproc --output expected_unfiltered.tex \
+	--template template $<

bib-place/README.md

@@ -0,0 +1,82 @@
+---
+title: "Bib-place"
+author: "Julien Dutant"
+---
+
+Bib-place
+=======
+
+Control the placement of a `citeproc`-generated bibliography
+via Pandoc templates. Only works with a single-bibliography
+document.
+
+The filter does not affect biblatex / natbib outputs, so it can be
+used with a custom template that caters for all bibliography engines.
+
+Introduction
+------------
+
+In Pandoc templates the main text is contained in the variable
+`$body$`. Suppose you want your document template to add something
+just below the body, such as the author's name and affiliation:
+
+```
+$body$
+
+$for(author)$$author$$endfor$
+$if(institute)$
+$for(institute)$$institute$$endfor$
+$endif$
+
+```
+
+When using `citeproc` to generate a bibliography you will not get
+the desired result, because `citeproc`-generated bibliographies
+are inserted at the end of the `$body$`` variable. The template
+above will print the author's name and institute after the
+bibliography.
+
+This filter takes the `citeproc` bibliography out of `$body$` and
+places it in a `$referencesblock$` variable instead.
+
+Usage
+----
+
+Call the filter at the command line or in a defaults file (see Pandoc's
+manual for detail). **Important**: the filter must be called after *citeproc*. From the command line:
+
+```
+pandoc -s --citeproc -L bib-place.lua sample.md -t html
+
+pandoc -s --citeproc --lua-filter bib-place.lua sample.md -t html
+```
+
+In a default file:
+
+```
+filters:
+- citeproc
+- bib-place.lua
+```
+
+In you custom Pandoc template you can then place the references block with the `referencesblock` variable:
+
+```
+$body$
+
+$for(author)$$author$$endfor$
+$if(institute)$
+$for(institute)$$institute$$endfor$
+$endif$
+
+$if(referencesblock)$$referencesblock$$endif$
+```
+
+Notes
+-----
+
+The template can be agnostic on which bibliography engine your run. If you process the document with other bibliography engines (natbib, biblatex) the filter will leave them untouched and you can place them by moving the
+`\printbibliography` commands in the template.
+
+If you use the filter with the default pandoc templates or with a template
+that does not use `$referencesblock$` your bibliography will not be printed.

bib-place/bib-place.lua

@@ -0,0 +1,77 @@
+--- # bib-place: template-controlled bibliography
+--    placement in Pandoc.
+--
+-- This Lua filter for Pandoc allows placement of the bibliography
+-- to be controlled in pandoc templates.
+--
+-- @author Julien Dutant <[email protected]>
+-- @author Albert Krewinkel
+-- @copyright 2021 Julien Dutant, Albert Krewinkel
+-- @license MIT - see LICENSE file for details.
+-- @release 0.1
+
+local references = pandoc.List({})
+
+--- Filter for the document's blocks
+-- Extract the Div with identifer 'refs' if present, as well as
+-- any heading that immediately precedes it, and stores them in
+-- the variable `references`. To find a heading that precedes
+-- the `refs` Div it needs to walk through the document
+-- backwards, element by element.
+-- @param element a Div element
+-- @return an empty list if Div has identifier `refs`
+local blocks_filter = {
+
+  Pandoc = function (doc)
+
+    local previous_was_refs = false
+
+    for i = #doc.blocks, 1, -1 do
+
+      -- if we have already found the Div `refs` we check
+      --  whether we have a heading and end the loop
+      if previous_was_refs then
+        if doc.blocks[i].t == 'Header' then
+          references:insert(1, pandoc.MetaBlocks( { doc.blocks[i] } ))
+          doc.blocks:remove(i) -- remove the heading
+          break
+        else
+          break
+        end
+
+      elseif doc.blocks[i].identifier == 'refs'
+          or ( doc.blocks[i].classes and
+            doc.blocks[i].classes:includes('csl-bib-body') ) then
+
+        references:insert(pandoc.MetaBlocks( { doc.blocks[i] } ))
+        doc.blocks:remove(i) -- remove the Div
+        previous_was_refs = true
+
+      end
+
+    end
+
+    return(doc)
+
+  end
+}
+
+--- Metadata filter.
+-- Places the references block (as string) in the `references`
+-- field of the document's metadata. The template can
+-- print it by using `$meta.references$`.
+-- @param meta the document's metadata block
+-- @return the modified metadata block
+local metadata_filter = {
+  Meta = function (meta)
+    meta.referencesblock = references
+    return meta
+  end
+}
+
+--- Main code
+-- Returns the filters in the desired order of execution
+return {
+  blocks_filter,
+  metadata_filter
+}

bib-place/expected_filtered.html

@@ -0,0 +1,22 @@
+<html>
+<head>
+  <title>Sample document</title>
+</head>
+<body>
+
+<p>I enjoyed <span class="citation" data-cites="Doe">Doe (1979)</span>.</p>
+
+Seymour Butz
+School of Studies
+
+<!-- Refs should be below this -->
+
+<h2 id="works-cited" class="unnumbered refs">Works cited</h2><div id="refs" class="references csl-bib-body hanging-indent" role="doc-bibliography">
+<div id="ref-Doe" class="csl-entry" role="doc-biblioentry">
+Doe, John. 1979. <em>Short Stories</em>.
+</div>
+</div>
+
+
+</body>
+</html>

bib-place/expected_filtered.tex

@@ -0,0 +1,53 @@
+% A minimal template
+
+% Preamble commands for each bibliography engine
+%   These are included in Pandoc's default template
+%
+\newlength{\cslhangindent}
+\setlength{\cslhangindent}{1.5em}
+\newlength{\csllabelwidth}
+\setlength{\csllabelwidth}{3em}
+\newenvironment{CSLReferences}[2] % #1 hanging-ident, #2 entry spacing
+ {% don't indent paragraphs
+  \setlength{\parindent}{0pt}
+  % turn on hanging indent if param 1 is 1
+  \ifodd #1 \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces\fi
+  % set entry spacing
+  \ifnum #2 > 0
+  \setlength{\parskip}{#2\baselineskip}
+  \fi
+ }%
+ {}
+\usepackage{calc}
+\newcommand{\CSLBlock}[1]{#1\hfill\break}
+\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{#1}}
+\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{#1}\break}
+\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
+
+\begin{document}
+
+I enjoyed Doe (1979).
+
+Seymour Butz
+School of Studies
+
+% Refs should be below this
+
+\hypertarget{works-cited}{%
+\subsection*{Works cited}\label{works-cited}}
+\addcontentsline{toc}{subsection}{Works cited}\hypertarget{refs}{}
+\begin{CSLReferences}{1}{0}
+\leavevmode\vadjust pre{\hypertarget{ref-Doe}{}}%
+Doe, John. 1979. \emph{Short Stories}.
+
+\end{CSLReferences}
+
+
+%
+% From pandoc's template: placement
+%   of bibliography with natbib and biblatex
+
+
+
+
+\end{document}

bib-place/expected_unfiltered.html

@@ -0,0 +1,24 @@
+<html>
+<head>
+  <title>Sample document</title>
+</head>
+<body>
+
+<p>I enjoyed <span class="citation" data-cites="Doe">Doe (1979)</span>.</p>
+<h2 class="unnumbered refs" id="works-cited">Works cited</h2>
+<div id="refs" class="references csl-bib-body hanging-indent" role="doc-bibliography">
+<div id="ref-Doe" class="csl-entry" role="doc-biblioentry">
+Doe, John. 1979. <em>Short Stories</em>.
+</div>
+</div>
+
+Seymour Butz
+School of Studies
+
+<!-- Refs should be below this -->
+
+
+
+
+</body>
+</html>

bib-place/expected_unfiltered.tex

@@ -0,0 +1,57 @@
+% A minimal template
+
+% Preamble commands for each bibliography engine
+%   These are included in Pandoc's default template
+%
+\newlength{\cslhangindent}
+\setlength{\cslhangindent}{1.5em}
+\newlength{\csllabelwidth}
+\setlength{\csllabelwidth}{3em}
+\newenvironment{CSLReferences}[2] % #1 hanging-ident, #2 entry spacing
+ {% don't indent paragraphs
+  \setlength{\parindent}{0pt}
+  % turn on hanging indent if param 1 is 1
+  \ifodd #1 \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces\fi
+  % set entry spacing
+  \ifnum #2 > 0
+  \setlength{\parskip}{#2\baselineskip}
+  \fi
+ }%
+ {}
+\usepackage{calc}
+\newcommand{\CSLBlock}[1]{#1\hfill\break}
+\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{#1}}
+\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{#1}\break}
+\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
+
+\begin{document}
+
+I enjoyed Doe (1979).
+
+\hypertarget{works-cited}{%
+\subsection*{Works cited}\label{works-cited}}
+\addcontentsline{toc}{subsection}{Works cited}
+
+\hypertarget{refs}{}
+\begin{CSLReferences}{1}{0}
+\leavevmode\vadjust pre{\hypertarget{ref-Doe}{}}%
+Doe, John. 1979. \emph{Short Stories}.
+
+\end{CSLReferences}
+
+Seymour Butz
+School of Studies
+
+% Refs should be below this
+
+
+
+
+%
+% From pandoc's template: placement
+%   of bibliography with natbib and biblatex
+
+
+
+
+\end{document}

bib-place/sample.bib

@@ -0,0 +1,5 @@
+@book{Doe,
+  title = "Short Stories",
+  author = "Doe, John",
+  year = 1979,
+}

bib-place/sample.md

@@ -0,0 +1,11 @@
+---
+title: Sample document
+author: Seymour Butz
+institute: School of Studies
+bibliography: sample.bib
+...
+
+I enjoyed @Doe.
+
+## Works cited {.refs}
+