Note(book)s to Documents

Jon Reades

Markdown and Notebooks can be used for a lot more than just code!

In conjunction with Pandoc and/or LaTeX they become platforms for publication.

Recall: Tangled Workflows

It’s not just about mixing code and comment, we also want:

  • To separate content from presentation
  • To define mappings between presentation styles
  • To produce the best-quality output for the format chosen

Pandoc

Tool for converting documents between formats, including:

  • Plain Text/YAML
  • Markdown
  • LaTeX/PDF
  • HTML/Reveal.js
  • Jupyter Notebook
  • XML/ODT/DOCX
  • EPUB/DocBook
  • BibTeX/JSON

LaTeX

LaTeX in Practice

You write LaTeX in any text editor, but specialist apps like Texpad or Overleaf make it easier.

\documentclass[11pt,article,oneside]{memoir}
\newcommand{\bl}{\textsc{bl}~\/}
\usepackage{tabularx}

\begin{document}
\maketitle 

This report provides an overview of activities ...

\section{Applications}
A primary objective was the submission...

BibTeX

Provides bilbiographic support for LaTeX but widely used by other utilities as is also plain-text.

@article{Lavin:2019,
        Author = {Lavin, Matthew J.},
        Doi = {10.46430/phen0082},
        Journal = {The Programming Historian},
        Number = {8},
        Title = {Analyzing Documents with TF-IDF},
        Year = {2019},
        Bdsk-Url-1 = {https://doi.org/10.46430/phen0082}}

@incollection{Kitchin:2016,
        Author = {Kitchin, R. and Lauriault, T.P. and McArdie, G.},
        Booktitle = {Smart Urbanism},
        Chapter = {2},
        Editor = {Marvin, Luque-Ayala, McFarlane},
        Title = {Smart Cities and the Politics of Urban Data},
        Year = {2016}}

BibTeX in Practice

To reference a document we then need to tell LaTeX or Pandoc where to look:

\bibliographystyle{apacite} # LaTeX
\bibliography{Spatial_Data_Chapter.bib} # LaTeX

With citations following formats like:

\citep[p.22]{Reades2018} # LaTeX

Or:

[@dignazio:2020, chap. 4] # Markdown

Reveal.js

JavaScript-based presentation framework. Can use Markdown to generate portable interactive slides including references/bibliographies.

How this presentation was created.

Compare:

From Markdown…

pandoc Syllabus.md \
  -H ./bib/head.tex \
  -H ./bib/chapter.tex \
  -H ./bib/refs.tex \
  -V documentclass=memoir \
  --pdf-engine=xelatex \
  --filter=pandoc-citeproc \
  --metadata-file=metadata.yml \
  --highlight-style=pygments \
  -o Syllabus.pdf

To PDF!

Pros

  • Simplicity (while writing)
  • Flexibility of Form
  • Version Control
  • High-Quality Outputs
  • Enforced Structure

Cons

  • Complexity (when formatting)
  • Collaboration (can be harder)

Recap of Formatting

Headings

Markdown LaTeX
# Heading Level 1 \section{Heading Level 1}
## Heading Level 2 \subsection{Heading Level 2}
### Heading Level 3 \subsubsection{Heading Level 3}

Inline Elements

Markdown LaTeX
1. Numbered item 1 \begin{enumerate} \n \item ... \end{enumerate}
- Bulleted list item 1 \begin{itemize} \n \item ... \n \end{itemize}
_italics_ or *italics* \emph{italics} or \textit{italics}
**bold** \textbf{bold}
> blockquote \begin{quote} \n blockquote \end{quote}
Some `code` is here Some \texttt{code} is here
[Link Text](URL) \href{Link Text}{URL}
![Alt Text](Image URL) \begin{figure}\n \includegraphics[opts]{...}\n \end{figure}

Mathematics

Markdown LaTeX
Same, but either 1 or 2 $’s $x=5$
Same, but either 1 or 2 $’s $\pi$
Same, but either 1 or 2 $’s $e = mc^{2}$

We can show all this directly in the Notebook! \(\pi\); \(e = mc^{2}\); \(\int_{0}^{\inf} x^2 \,dx\); \(\sum_{n=1}^{\infty} 2^{-n} = 1\)

You will need to Google most things to do with laying out LaTeX.

Resources

Note(book)s to Documents • Jon Reades