Add support for citations in PDFs/LaTeX

[goerz]

• 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).
• Functions DocumenterCitations.set_latex_options and DocumenterCitations.reset_latex_options to tweak the rendering of bibliographies in PDFs.

Internal changes:

• 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.

There is now a script docs/makepdf.jl that can be executed with make pdf to produce a PDF of the documentation for DocumenterCitations. This serves as a self-test and showcase. In future releases, we'll attach the PDF as an asset to the release. I didn't add a Github Workflow to produce the PDF, as setting up LaTeX and compiling the PDF would slow down the CI significantly. There are some tests, but they stop after generating the .tex file, which is much more efficient. For releases, I can produce the PDF locally on my laptop.

Closes #18

[goerz]

The documentation preview is at https://juliadocs.org/DocumenterCitations.jl/previews/PR46/

More importantly, the PDF version (generated with make pdf) is DocumenterCitations.jl-1.2.1.pdf

[goerz]

@Seelengrab Can you review this?

If I was your thesis advisor, I'd be totally fine with you handing in something in the format of the generated PDF 😉

Just let me know if this works for you, or if anything should be tweaked.

[Seelengrab]

Just some minor things - I'll see how this works on my thesis in a few hours :)

[Seelengrab]

Something seems to be going wrong when linking down to the reference:

The relevant bibtex that got parsed:

@book{guntheroth2016optimized,
  title={Optimized C++: proven techniques for heightened performance},
  author={Guntheroth, Kurt},
  year={2016},
  publisher={" O'Reilly Media, Inc."}
}

And the TEX that got produced for this section:

This is an additional reference [\hyperlinkref{13874326461024448687}{1}].



{\raggedright% @bibliography

\hangindent=0.33in {\makebox[{\ifdim0.33in<\dimexpr\width+1ex\relax\dimexpr\width+1ex\relax\else0.33in\fi}][l]{[1]}}\hypertarget{13874326461024448687}{}K. Guntheroth. \emph{Optimized C++: proven techniques for heightened performance}. {\textquotedbl} O{\textquotesingle}Reilly Media, Inc.{\textquotedbl} (2016).

}% end @bibliography

The author name actually does contain U+00A0 instead of a regular space in the generated TEX (but not in the bibtex source), which may be related to my comment about space replacement from above? Not sure what's going wrong with the hyperlink though, might be something in my setup 🤔

[goerz]

@Seelengrab Which platform are you running on? Is this a Windows problem? That U+00A0 is supposed to be there, but it certainly shouldn't render like that. I'll look into whether I can replace "\u00a0" with "~" somewhere in the LaTeX writer. Are you having problems with any other unicode symbols?

[Seelengrab]

I'm on linux - my setup is a bit weird though, since I need a preamble from my university and that messes with things a bit 😂 That may be the cause of the wonky ifundefined too.. I think have it set up correctly for unicode support now (e.g. I can use ß and similar just fine, and other unicode like BenchmarkTools.jl output also looks great). So I think this is specific to these lower control characters?

[goerz]

I'll look into whether I can replace "\u00a0" with "~" somewhere in the LaTeX writer.

That will require a patch to Documenter, but is probably a good idea

[goerz]

since I need a preamble from my university and that messes with things a bit

That seems the likely cause for the ifundefined. Not sure if there's anything I can do about that.

Until we find a way to replace \u00a0 with ~, you can probably do that manually in your build script: Let Documenter only produce the .tex file (platform="none"), and search and replace \u00a0 with the ~ (with sed or something), and then compile with lualatex -shell-escape

[Seelengrab]

Sounds good! I'm excited for this, since the reference really does look MUCH nicer now than my previous cobbled together attempt :D Thank you very much!

[goerz]

I opened JuliaDocs/Documenter.jl#2300 about the problem with the non-breaking space.

My best guess is that this is a font problem on your system. It's not that surprising that the LaTeX font you may be using doesn't handle \u00A0 correctly, since ~ is really the expected way to have non-breaking spaces in LaTeX.

I'm going to see how quickly @mortenpi gets around to looking at JuliaDocs/Documenter.jl#2300, and maybe keep this PR open until a new version of Documenter is released with that patch. That's because I have to adjust my tests that check the output of the LaTeXrWiter, depending on what version of Documenter is installed.

[Seelengrab]

Yeah, dealing with unicode & fonts in LaTeX is a bit of a PitA, unfortunately.. It's doubly bad when it shows up like this :/ I'll see if I can fiddle around a bit with the fonts and work out what (if anything) is going wrong on my end.

[goerz]

I'm going to see how quickly @mortenpi gets around to looking at JuliaDocs/Documenter.jl#2300,

I think he was saying on Slack that he was going to be traveling for a few weeks, so maybe I'll just merge later today (unless @Seelengrab has more input) and move on to fixing #22 next. I can always adjust the test on master when there's a new release of Documenter.