feat(docgen): typeset links as footnotes in PDF

When reading a PDF printed on paper or on a reMarkable tablet, it's
not possible to see that there even is a link in a PDF. Make this more
visible by typesetting the link URL as a footnote.

This is not done on HTML output as web pages are read on browsers that
make links easy to see.

This is the first time the AST is transformed by docgen differently
based on the output format. The decision of what should be done is a
policy decision, best done at the topmost level: in the main function
of docgen.

The result of that decidion (turn links into footnotes or not) is
communicated from docgen main into the ast.rs module via a new Style
struct. This mechanism can later be extended for other typesetting
style decisions (e.g., what fonts to use).

1 files changed, 12 insertions, 0 deletions

diff --git a/src/typeset.rs b/src/typeset.rs
index 32956c6..40cbef6 100644
--- a/src/typeset.rs
+++ b/src/typeset.rs
@@ -9,6 +9,7 @@ use crate::{DotMarkup, GraphMarkup, PlantumlMarkup};
 use pandoc_ast::Attr;
 use pandoc_ast::Block;
 use pandoc_ast::Inline;
+use pandoc_ast::Target;
 
 /// Typeset an error as a Pandoc AST Block element.
 pub fn error(err: SubplotError) -> Block {
@@ -121,6 +122,17 @@ fn captured(s: &str) -> Inline {
     Inline::Strong(vec![inlinestr(s)])
 }
 
+/// Typeset a link as a note.
+pub fn link_as_note(attr: Attr, text: Vec<Inline>, target: Target) -> Inline {
+    let (url, _) = target.clone();
+    let url = Inline::Code(attr.clone(), url);
+    let link = Inline::Link(attr.clone(), vec![url], target);
+    let note = Inline::Note(vec![Block::Para(vec![link])]);
+    let mut text = text;
+    text.push(note);
+    Inline::Span(attr, text)
+}
+
 // Take a dot graph, render it as SVG, and return an AST Block
 // element. The Block will contain the SVG data. This allows the graph
 // to be rendered without referending external entities.