Formatting tools

Formatting tools#

Formatting tools take input artefacts produced by authoring tools and produce publishable formatted output. While many of the authoring tools discussed in the previous section are well-known, there have been many recent developments in formatting tools that deserve to be better known in the academic community as they take opportunities for publishing training material to the next level. In the previous section we described the two paradigms Single-In-Single-Out (SISO) and Single-In-Multi-Out (SIMO). In this section we describe some formatting tools that can be used for the SIMO paradigm.

        flowchart LR
  
    E1("External resources"):::external -.-> A1
    A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input
    subgraph "Quarto, pdflatex, xelatex, pandoc, ..." 
      direction LR
      I1 --> P1{{"Formatting tool"}}
      P1 --> O1["Formatted\nOutput"]:::output
    end
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;

Pandoc#

Pandoc is a tool to convert files between multiple markup formats. Pandoc is used within more generic tools such as Quarto. It is customizable thanks to a Haskell library and a template system to feet your needs. It is able to generate bibliographies, footnotes, LaTeX math, tables, definitions, and most common publication assets. Some supported formats are lightweight markup (Markdown, reStructuredText, AsciiDoc, Textile, Emacs Org-Mode, …), HTML, Ebooks, TeX, word processing (docx, rtf, odt), wiki markup, slide show (LaTeX Beamer, reveal.js, Microsoft PowerPoint, …), and even PDF (via pdflatex, lualatex, xelatex, latexmk and others).

Sphinx#

Sphinx is an open-source documentation engine that is based on Docutils; extending it to multi-page documentation. Docutils is an open-source text processing system that uses the plain text easy-to-read reStructuredText to create documentation in multiple formats, such as HTML, LaTeX, Linux man pages, OpenDocument, or XML. Sphinx supports reStructuredText and MyST markdown as input files and can generate multiple output formats including HTML, LaTeX, PDF, ePub, and Texinfo (the official documentation format of the GNU project).

Jupyter Book#

Jupyter Book is one of the main projects of the Executable Books Project, together with the other project MyST Markdown. The Executable Books Project is an international collaboration to build open-source tools for publishing computational documents based on the Jupyter ecosystem. Jupyter Book can read markdown, MyST Markdown, Jupyter notebooks and reStructuredText. It is based on the Sphinx documentation engine being able to produce html websites, pdf, and computational narratives. It supports multiple programming languages in the Jupyter notebooks provided that a Jupyter kernel exist (e.g. Python, Julia, Rubi, Haskell, and many other languages).

Websites that include computational narratives can also benefit from live environments thanks to the integration of Binder, Thebe and Google Colab. It supports multiple types of narrative content like highlighted notes, code cells, quotations, epigraphs, glossaries, index of terms, footnotes, references, grids, cards, dropdown menus, tab content, maths, equations, proofs, theorems, algorithms, and more. The Jupyter Book system has been used in multiple ocasions to publish online material, an extensive gallery can be found at https://executablebooks.org/en/latest/gallery/. This roadmap has been created with Jupyter Book and serves as an example of some of its functionalities. Another great example of a collaboratively authored Jupyter Book is the TAILOR Handbook of Trustworthy AI.

R markdown#

R markdown is a flavoured markdown type with special focus on the R programming language and a publishing system. The publishing system uses R markdown files (with extension .rmd) or standard markdown and can produce various output formats including HTML, PDFs, Microsoft Word documents, Beamer presentations, HTML5 slides, scientific articles and books (with the the help of the bookdown R package. It also support other programming languages including Python, SQL and others with a language engine. R markdown is also integrated in Rstudio.

Bookdown#

Bookdown is an open-source R package that facilitates the creation of books from R Markdown documents. It is an extension for R Markdown to work with long documents. The rest of the functionalities are shared with R Markdown. A list of books written with Bookdown can be found at https://bookdown.org/home/archive/.

Quarto#

Quarto is another open-source publishing system with the objective of facilitating the collaboration to create scientific content. Quarto is sponsored by Posit, and follows the development of the R Markdown publishing system extending the focus from the programming language R to Python, R, Julia and Observable. It supports Jupyter notebooks, markdown and their own extension Quarto markdown. The conversion to different output formats is done with pandoc, which is able to produce presentations (Reveal.js), dashboards, websites, blogs, books, PDFs, Microsoft Word, ePub and more. Quarto is integrated into multiple authoring environments like Microsoft Visual Studio, Jupyter Lab, Rstudio, and Atlassian Confluence among others.

Reveal.js#

Reveal.js is an open-source framework for in-browser presentations. It supports features like animations, export to PDF, an intuitive navigation of the slides, speaker notes, Markdown support, LaTeX support, laser-like pointer, and drawing tools. reveal.js presentations can be authored in markdown, HTML or a mix using any text editor and served locally using the Jekyll static website generator. The following HTML code is a fully working reveal.js presentation

<html>
  <head>
    <link rel="stylesheet" href="dist/reveal.css" />
    <link rel="stylesheet" href="dist/theme/white.css" />
  </head>
  <body>
    <div class="reveal">
      <div class="slides">
        <section>Slide 1</section>
        <section>Slide 2</section>
      </div>
    </div>
    <script src="dist/reveal.js"></script>
    <script>
      Reveal.initialize();
    </script>
  </body>
</html>

reveal.js is directly supported by formatting tools inclusing Quarto, Jupyter Notebook, and pandoc.

D2L-Book: A Toolkit for Hands-on Books

Building on several of these formatting tools, d2l-book is a Python package and a toolkit to build online and printed books, in support of the Dive into Deep Learning book [ZLLS23]. The authoring formats are mainly MyST markdown and Jupyter Notebooks. Formatting is done with pandoc and Sphinx.

Contents