Add support for citations in PDFs/LaTeX

Co-authored-by: Sukera <[email protected]>

Makefile

@@ -36,6 +36,10 @@ docs: test/Manifest.toml ## Build the documentation
 	$(JULIA) --project=test docs/make.jl
 	@echo "Done. Consider using 'make devrepl'"
 
+pdf: test/Manifest.toml ## Build the documentation in PDF format
+	$(JULIA) --project=test docs/makepdf.jl
+	@echo "Done. Consider using 'make devrepl'"
+
 servedocs: test/Manifest.toml  ## Build (auto-rebuild) and serve documentation at PORT=8000
 	$(JULIA) --project=test -e 'include("devrepl.jl"); servedocs(port=$(PORT), verbose=true)'
 

NEWS.md

@@ -17,6 +17,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * In general (depending on the style and citation syntax), citation links may now render to arbitrarily complex expressions.
 * Citation comments can now have inline markdown elements, e.g., `[GoerzQ2022; definition of $J$ in section *Running costs*](@cite)`
 * When running in non-strict mode, missing bibliographic references (either because the `.bib` file does not contain an entry with a specific BibTeX key, or because of a missing `@biblography` block) are now handled similarly to missing references in LaTeX: They will show as (unlinked) question marks.
+* Support for bibliographies in PDFs generate via LaTeX (`format=Documenter.LaTeX()`). Citations and references are rendered exactly as in the HTML version. Specifically, the support does not depend on `bibtex`/`biblatex` and supports any style (including custom styles). [[#18][]]
+* Functions `DocumenterCitations.set_latex_options` and `DocumenterCitations.reset_latex_options` to tweak the rendering of bibliographies in PDFs.
+
 
 ### Internal Changes
 
@@ -31,6 +34,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Exposed the internal function `format_labeled_bibliography_reference` that implements `format_bibliography_reference` for the built-in styles `:numeric` and `:alpha`.
 * Exposed the internal function `format_authoryear_bibliography_reference` that implements `format_bibliography_reference` for the built-in style `:authoryear:`.
 * The example custom styles `:enumauthoryear` and `:keylabels` have been rewritten using the above internal functions, illustrating that custom styles will usually not have to rely on the undocumented and even more internal functions like `format_names` and `tex2unicode`.
+* Any `@bibliography` block is now internally expanded into an internal `BibliographyNode` instead of a raw HTML node. This `BibliographyNode` can then be translated into the desired output format by `Documenter.HTMLWriter` or `Documenter.LaTeXWriter`. This is how support for bibliographies with `format=Documenter.LaTeX()` can be achieved.
+* The routine `format_bibliography_reference` must now return a markdown string instead of an HTML string.
 
 
 ## [Version 1.2.1][1.2.1] - 2023-09-22
@@ -118,6 +123,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#31]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/31
 [#20]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/20
 [#19]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/19
+[#18]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/18
 [#16]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/16
 [#14]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/14
 [#6]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/6

docs/makepdf.jl

@@ -1,2 +1,46 @@
-# In a future version, this script will generate a PDF version of the package
-# documentation
+using DocumenterCitations
+using Documenter
+using Pkg
+
+
+# Note: Set environment variable `DOCUMENTER_LATEX_DEBUG=1` in order get a copy
+# of the generated tex file (or, add `platform="none"` to the
+# `Documenter.LaTeX` call)
+
+
+PROJECT_TOML = Pkg.TOML.parsefile(joinpath(@__DIR__, "..", "Project.toml"))
+VERSION = PROJECT_TOML["version"]
+NAME = PROJECT_TOML["name"]
+AUTHORS = join(PROJECT_TOML["authors"], ", ") * " and contributors"
+GITHUB = "https://github.com/JuliaDocs/DocumenterCitations.jl"
+
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "refs.bib");
+    style=:numeric  # default
+)
+
+println("Starting makedocs")
+
+include("custom_styles/enumauthoryear.jl")
+include("custom_styles/keylabels.jl")
+
+withenv("DOCUMENTER_BUILD_PDF" => "1") do
+    makedocs(
+        authors=AUTHORS,
+        linkcheck=true,
+        warnonly=[:linkcheck,],
+        sitename="DocumenterCitations.jl",
+        format=Documenter.LaTeX(; version=VERSION),
+        pages=[
+            "Home"                   => "index.md",
+            "Syntax"                 => "syntax.md",
+            "Citation Style Gallery" => "gallery.md",
+            "CSS Styling"            => "styling.md",
+            "Internals"              => "internals.md",
+            "References"             => "references.md",
+        ],
+        plugins=[bib],
+    )
+end
+
+println("Finished makedocs")

docs/src/assets/preamble.tex

@@ -0,0 +1,36 @@
+\documentclass[oneside]{memoir}
+\usepackage{./documenter}
+\usepackage{./custom}
+
+\renewcommand{\part}[1]{}
+
+
+\AfterPreamble{\hypersetup{
+  pdfauthor={Michael H. Goerz and Contributors},
+  pdftitle={\DocMainTitle{} v\DocVersion{}},
+  pdfsubject={Documentation of Julia package \DocMainTitle{}}
+}}
+
+
+%% Title Page
+\title{%
+    {\HUGE\DocMainTitle{}}\\
+    \vspace{16pt}
+    {\Large version \DocVersion{}}
+}
+\author{Michael H. Goerz and Contributors}
+
+
+\settocdepth{section}
+
+
+%% Main document begin
+\begin{document}
+\frontmatter
+\maketitle
+%\clearpage
+\tableofcontents
+\widowpenalty10000
+\clubpenalty10000
+\raggedright%
+\mainmatter

docs/src/gallery.md

@@ -88,6 +88,10 @@ Style = :alpha
 Canonical = false
 ```
 
+```@raw latex
+Compared to the HTML version of the documentation, the hanging indent in the above list of references is too small for the longer labels of the \texttt{:alpha} style. This can be remedied by adjusting the \texttt{dl\_hangindent} and \texttt{dl\_labelwidth} parameters with \hyperlinkref{sec:customizing_latex_output}{\texttt{DocumenterCitations.set\_latex\_options}}.
+```
+
 Note that the `:alpha` style is able to automatically disambiguate labels:
 
 ```@bibliography
@@ -179,3 +183,7 @@ Pages = ["gallery.md"]
 Style = :keylabels
 Canonical = false
 ```
+
+```@raw latex
+As with the \texttt{:alpha} style, for \LaTeX{} output, the \texttt{dl\_hangindent} and \texttt{dl\_labelwidth} parameters should be adjusted with \hyperlinkref{sec:customizing_latex_output}{\texttt{DocumenterCitations.set\_latex\_options}} to obtain a more suitable hanging indent that matches the HTML version of this documentation.
+```

docs/src/index.md

@@ -10,7 +10,20 @@ github_badge = "[![Github](https://img.shields.io/badge/JuliaDocs-DocumenterCita
 
 version_badge = "![v$VERSION](https://img.shields.io/badge/version-v$(replace("$VERSION", "-" => "--"))-green.svg)"
 
-Markdown.parse("$github_badge $version_badge")
+if get(ENV, "DOCUMENTER_BUILD_PDF", "") == ""
+    Markdown.parse("$github_badge $version_badge")
+else
+    Markdown.parse("""
+    -----
+
+    On Github: [JuliaDocs/DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl)
+
+    Version: $VERSION
+
+    -----
+
+    """)
+end
 ```
 
 [DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl#readme) uses [Bibliography.jl](https://github.com/Humans-of-Julia/Bibliography.jl) to add support for BibTeX citations in documentation pages generated by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).
@@ -104,6 +117,10 @@ makedocs(;
 deploydocs(; repo="github.com/JuliaDocs/DocumenterCitations.jl.git")
 ```
 
+Bibliographies are also supported in [PDFs generated via LaTeX](https://documenter.juliadocs.org/stable/man/other-formats/#pdf-output). All that is required is to replace `format=Documenter.HTML(…)` in the above code with `format=Documenter.LaTeX()`.  See [`docs/makepdf.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/makepdf.jl) for an example. The resulting PDF files for the `DocumenterCitations` package are available as attachments to the [Releases](https://github.com/JuliaDocs/DocumenterCitations.jl/releases).
+
+The rendering of the documentation may be fine-tuned using the [`DocumenterCitations.set_latex_options`](@ref) function. Note that the bibliography in LaTeX is directly rendered for the [different styles](@ref gallery) from the same internal representation as the HTML version. In particular, `bibtex`/`biblatex` is not involved in producing the PDF.
+
 
 ## How to cite references in your documentation
 

docs/src/internals.md

@@ -51,6 +51,17 @@ format_labeled_bibliography_reference
 format_authoryear_bibliography_reference
 ```
 
+### Customizing LaTeX output
+
+```@raw latex
+\hypertarget{sec:customizing_latex_output}{}
+```
+
+```@docs
+set_latex_options
+reset_latex_options
+```
+
 ### Citation links
 
 The standard citation links described in [Syntax](@ref) are internally parsed into the [`DocumenterCitations.CitationLink`](@ref) data structure:

src/DocumenterCitations.jl

@@ -186,6 +186,8 @@ include("md_ast.jl")
 include("citation_link.jl")
 include("collect_citations.jl")
 include("expand_citations.jl")
+include("latex_options.jl")
+include("bibliography_node.jl")
 include("expand_bibliography.jl")
 include("formatting.jl")
 include("labeled_styles_utils.jl")
@@ -202,6 +204,7 @@ function __init__()
             push!(Documenter.ERROR_NAMES, errname)
         end
     end
+    reset_latex_options()
 end