Add support for citations in PDFs/LaTeX

Author: goerz

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,40 @@
-# In a future version, this script will generate a PDF version of the package
-# documentation
+using DocumenterCitations
+using Documenter
+using Pkg
+
+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{Michel 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
 
 

src/bibliography_node.jl

@@ -0,0 +1,177 @@
+"""Representation of a reference within a [`BibliographyNode`}(@ref).
+
+# Properties
+
+* `anchor_key`: the anchor key for the link target as a string (generally the
+  BibTeX key), or `nothing` if the item is in a non-canonical bibliography
+  block.
+* `label`: `MarkdownAST.Node` for the label of the entry. Usually a simple
+  `Text` node, as labels in the default styles do not have inline formatting.
+    or `nothing` if the style does not use labels
+  the rendered bibliography.
+* `reference`: `MarkdownAST.Node` for the paragraph for the fully rendered
+  reference.
+"""
+struct BibliographyItem
+    anchor_key::Union{Nothing,String}
+    label::Union{Nothing,MarkdownAST.Node{Nothing}}
+    reference::MarkdownAST.Node{Nothing}
+end
+
+
+"""Node in `MarkdownAST` corresponding to a `@bibliography` block.
+
+# Properties
+
+* `list_style`: One of `:dl`, `:ul`, `:ol`, cf. [`bib_html_list_style`](@ref)
+* `canonical`: Whether or not the references in the `@bibliography` block are
+  link targets.
+* `items`: A list of [`BibliographyItem`](@ref) objects, one for each reference
+in the block
+"""
+struct BibliographyNode <: Documenter.AbstractDocumenterBlock
+    list_style::Symbol  # one of :dl, :ul, :ol
+    canonical::Bool
+    items::Vector{BibliographyItem}
+end
+
+
+function Documenter.MDFlatten.mdflatten(io, ::MarkdownAST.Node, b::BibliographyNode)
+    for item in b.items
+        Documenter.MDFlatten.mdflatten(io, item.reference)
+        print(io, "\n\n\n\n")
+    end
+end
+
+
+function Documenter.HTMLWriter.domify(
+    dctx::Documenter.HTMLWriter.DCtx,
+    node::Documenter.Node,
+    bibliography::BibliographyNode
+)
+    @assert node.element === bibliography
+    return domify_bib(dctx, bibliography)
+end
+
+
+function domify_bib(dctx::Documenter.HTMLWriter.DCtx, bibliography::BibliographyNode)
+    Documenter.DOM.@tags dl ul ol li div dt dd
+    list_tag = dl
+    if bibliography.list_style == :ul
+        list_tag = ul
+    elseif bibliography.list_style == :ol
+        list_tag = ol
+    end
+    html_list = list_tag()
+    for item in bibliography.items
+        anchor_key = isnothing(item.anchor_key) ? "" : "#$(item.anchor_key)"
+        html_reference = Documenter.HTMLWriter.domify(dctx, item.reference.children)
+        if bibliography.list_style == :dl
+            html_label = Documenter.HTMLWriter.domify(dctx, item.label.children)
+            push!(html_list.nodes, dt(html_label))
+            push!(html_list.nodes, dd(div["$(anchor_key)"](html_reference)))
+        else
+            push!(html_list.nodes, li(div["$(anchor_key)"](html_reference)))
+        end
+    end
+    class = ".citation"
+    if bibliography.canonical
+        class *= ".canonical"
+    else
+        class *= ".noncanonical"
+    end
+    return div[class](html_list)
+end
+
+
+_hash(x) = string(hash(x))
+
+
+function _wrapblock(f, io, env)
+    if !isnothing(env)
+        println(io, "\\begin{", env, "}")
+    end
+    f()
+    if !isnothing(env)
+        println(io, "\\end{", env, "}")
+    end
+end
+
+
+function _labelbox(f, io; width="0in")
+    try
+        if parse(Float64, string(match(r"[\d.]+", width).match)) == 0.0
+            # do not use a makebox if width in zero
+            print(io, "{")
+            f()
+            print(io, "} ")
+            return
+        end
+    catch
+        throw(ArgumentError("width $(repr(width)) must be a valid LaTeX width"))
+    end
+    print(
+        io,
+        "\\makebox[{\\ifdim$(width)<\\dimexpr\\width+1ex\\relax\\dimexpr\\width+1ex\\relax\\else$(width)\\fi}][l]{"
+    )
+    f()
+    print(io, "}")
+end
+
+
+function Documenter.LaTeXWriter.latex(
+    lctx::Documenter.LaTeXWriter.Context,
+    node::MarkdownAST.Node,
+    bibliography::BibliographyNode
+)
+
+    if bibliography.list_style == :ol
+        texenv = "enumerate"
+    elseif bibliography.list_style == :ul
+        if _LATEX_OPTIONS[:ul_as_hanging]
+            texenv = nothing
+        else
+            texenv = "itemize"
+        end
+    else
+        @assert bibliography.list_style == :dl
+        # We emulate a definition list manually with hangindent and labelwidth
+        texenv = nothing
+    end
+
+    io = lctx.io
+
+    function tex_item(n, item)
+        if bibliography.list_style == :ul
+            if _LATEX_OPTIONS[:ul_as_hanging]
+                print(io, "\\hangindent=$(_LATEX_OPTIONS[:ul_hangindent]) ")
+            else
+                print(io, "\\item ")
+            end
+        elseif bibliography.list_style == :ol  # enumerate
+            print(io, "\\item ")
+        else
+            @assert bibliography.list_style == :dl
+            print(io, "\\hangindent=$(_LATEX_OPTIONS[:dl_hangindent]) {")
+            _labelbox(io; width=_LATEX_OPTIONS[:dl_labelwidth]) do
+                Documenter.LaTeXWriter.latex(lctx, item.label.children)
+            end
+            print(io, "}")
+        end
+    end
+
+    println(io, "{$(_LATEX_OPTIONS[:bib_blockformat])% @bibliography\n")
+    _wrapblock(io, texenv) do
+        for (n, item) in enumerate(bibliography.items)
+            tex_item(n, item)
+            if !isnothing(item.anchor_key)
+                id = _hash(item.anchor_key)
+                print(io, "\\hypertarget{", id, "}{}")
+            end
+            Documenter.LaTeXWriter.latex(lctx, item.reference.children)
+            print(io, "\n\n")
+        end
+    end
+    println(io, "}% end @bibliography")
+
+end