Literate programming with Quarto

Psicometria per le Neuroscienze Cognitive

Filippo Gambarota, PhD

Literate Programming

Literate Programming1

Donald Knuth first defined literate programming as a script, notebook, or computational document that contains an explanation of the program logic in a natural language, interspersed with snippets of macros and source code, which can be compiled and rerun

For example jupyter notebooks, R Markdown and now Quarto are literate programming frameworks to integrate code and text.

Literate Programming, the markup language

Beyond the coding part, the markup language is the core element of a literate programming framework. The idea of a markup language is separating the result from what you actually write. Some examples are:

  • LaTeX
  • HTML
  • Markdown
  • XML
  • …

LaTeX 1

HTML

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>

Lorem Ipsum è un testo segnaposto utilizzato nel settore della tipografia e della stampa. Lorem Ipsum è considerato il testo segnaposto standard sin dal sedicesimo secolo, quando un anonimo tipografo prese una cassetta di caratteri e li assemblò per preparare un testo campione. È sopravvissuto non solo a più di cinque secoli, ma anche al passaggio alla videoimpaginazione, pervenendoci sostanzialmente inalterato. Fu reso popolare, negli anni ’60, con la diffusione dei fogli di caratteri trasferibili “Letraset”, che contenevano passaggi del Lorem Ipsum, e più recentemente da software di impaginazione come Aldus PageMaker, che includeva versioni del Lorem Ipsum.

<h2>My Second Heading</h2>

Lorem Ipsum è un testo segnaposto utilizzato nel settore della tipografia e della stampa. 

Lorem Ipsum è considerato il testo segnaposto standard sin dal sedicesimo secolo, quando un anonimo 

tipografo prese una cassetta di caratteri e li assemblò per preparare un testo campione. 

È sopravvissuto non solo a più di cinque secoli, ma anche al passaggio alla videoimpaginazione, pervenendoci sostanzialmente inalterato. 

Fu reso popolare, negli anni ’60, con la diffusione dei 

fogli di caratteri trasferibili “Letraset”, che contenevano passaggi del Lorem Ipsum

più recentemente da software di impaginazione come Aldus PageMaker, che includeva versioni del Lorem Ipsum.

</body>
</html>

Markdown1

Markdown

Markdown is one of the most popular markup languages for several reasons:

  • easy to write and read compared to Latex and HTML
  • easy to convert from Markdown to basically every other format using pandoc
  • easy to implement new features

Markdown (source code)

## Markdown

Markdown is one of the most popular markup languages for several reasons:

- easy to write and read compared to Latex and HTML
- easy to convert from Markdown to basically every other format using `pandoc`
- easy to implement new features

Also the source code can be used, compared to Latex or HTML, to take notes and read. Latex and HTML need to be compiled otherwise they are very hard to read.

What’s wrong about Microsoft Word?

MS Word is a WYSIWYG (what you see is what you get editor) that force users to think about formatting, numbering, etc. Markup languages receive the content (plain text) and the rules and creates the final document.

What’s wrong about Microsoft Word?

Beyond the pure writing process, there are other aspects related to research data.

  • writing math formulas
  • reporting statistics in the text
  • producing tables
  • producing plots

In MS Word (or similar) we need to produce everything outside and then manually put figures and tables.

The solution… Quarto

Quarto (https://quarto.org/) is the evolution of R Markdown that integrate a programming language with the Markdown markup language. It is very simple but quite powerful.

Basic Markdown

Markdown can be learned in minutes. You can go to the following link https://quarto.org/docs/authoring/markdown-basics.html and try to understand the syntax.

Let’s see a practical example!

More about Quarto and R Markdown

The topic is extremely vast. You can do everything in Quarto, a website, thesis, your CV, etc.

Writing papers, papaja

https://github.com/crsh/papaja

Writing papers, apaquarto

https://github.com/wjschne/apaquarto

Collaborating! (TBH not so easy)

The trackdown package can be used to collaborate on Rmd or qmd documents using Google Docs.

https://github.com/ClaudioZandonella/trackdown

Collaborating! Overleaf

With Overleaf you can collaborate on .tex documents but also .Rnw documents. No Rmd or qmd unfortunately. See an example document.