Background: From PowerPoint to Plain Text and Sphinx

Introduction

Since 2008 I’m into publishing. Sounds more serious than it actually is. It all started in 2008 when I still was a medical student and member of a volounteer emergency medical service agency. Back then I started teaching in EMT (emergency medical technicians) courses. Of course there were the ubiquous powerpoint slides, accompanied by a 300 page textbook.

From Powerpoint to a text document

Thus said – I hate presentation slides, and I hate teaching by them. I started to extract the texts and pictures on the slides and create an OpenOffice text document. I structured them, started to add real text passages and prepared an self-written chapter concerning general patient management (a topic I’m very fond off and which I regard as a key element in EMT training). At first the Training Depatment did’nt care much about my efforts, they were more or less satisfied with the status quo, not quite happy, but it worked. Then the new edition of the texbook arrived and we quickly discovered that, apart from actual errors and accidential ommissions, some key elements of the curriculum were missing in this “revised” edition. That was the point were we decided: We could do better. The Training Department officially endorsed my project, so I went on and began to produce the first chapters to be used in actual courses, resulting in the creation of the Arbeits- und Ausbildungsstandards für den Sanitätsdienst (AASS).

From text documents to LaTeX

However, soon I realised that using OpenOffice documents was quite limiting. In fact, using standard office software to create a bigger publication, including the layout etc., ist quite a pain nowadays, and this was more than true back than in 2009. That’s when I started to seriously experiment with LaTeX. LaTeX is a powerful typesetting system, that can produce splendid publications intented for print – if you know what you are doing. It is source code based and uses a compiler to create the output PDF files.

Fig. 84 LaTeX uses a compiler to create PDF files

LaTeX itself would be worth an article, so I dont want to go into details at this point. In short, I had much fun the following years, extending the work into a full-blown book and creating and tuning a great and effective layout.

… and version management

Since LaTeX uses plain-text source code I soon realized that using version control systems as known as in software development can be a great advantage, enabling group collaboration and tracking (and reviewing!) of changes. At first I tried my luck with Subversion (SVN), but soon Git became popular throughout the software development community and the advantages of distributed version control, local committing and the ease to set up a Git server quickly motivated me to switch to Git.

Looking for ways to improve

In 2016 the book covered about 650 pages, complete with inline references, bibliography, index etc. and was printed and soft-covered for the EMT courses of three Training Departments in Vienna and Lower Austria, using a Creative Commons License. So in this nische the project was quite succesful. Well, there was one catch, two actually:

• First, LaTeX isn’t very end-user friendly, espacially if you are working with a complicated layout. You can hide much of the complexity from the author, but there is a point where it get’s quit unintuitive for a non-techie-person. You can somehow reduce the pain by creating good documentation and cheatsheets, but it can realy slow down the development process and increase the burden oft he guy who is doing the “backroom magic”.

• Second, there is the fact that LaTeX is great for print. Period.

  Creating output for another medium is difficult at best and nearly impossible in practical terms. (Yes, there are tools like latex2html, but as soon as you use the simpliest modifications like definig custom commands or using special packages will render the output unuseable.)

  So the creation of an e-book or a web-based book, which would be great an the context of the book, was simply not possible.

This limitation nagged me. I was looking for a solution that would allow for a creation of online content but while not jepoardizing the high qulaity print output at the same time.

To sum it up, my requirements were:

• Create high quality print output

• Create e-books

• Create web-based output

• Use the same source for all output mediums

• Ease of use

• Semantic markup

• Support for index, table of contents, bibliography, cross-references.

• Preferably ource code/plain text based and thus compatible with version control systems

• Compatible with Linux, Windows and MacOS

• Preferably a migration path

Sphinx Toolchain

The solution to my requirements caught my attention in 2017 in form of the Sphinx toolchain.

Sphinx is a documentation generator and has it’s roots in the Python programming language community and was primarily used for documentation of Python software projects. Since it’s introduction it has gained much attention from the software development community in general, thus many projects switching their documentation workflow to Sphinx. One of the prominest would be the Linux kernel project, migrating their DocBook-based workflow to Sphinx in 2016 (starting with the 4.7 release cycle) ^{1 1}https://lwn.net/Articles/705224/ .

Although Sphinx earned it’s merrits in the field of technical documentation it’s also a powerful tool for general publishing needs. What does it make so great? Well, let’s first talk about what Sphinx actually is:

Sphinx uses a plain text format for the text content. Originally this has been Restructuredtext ^{2 2}https://en.wikipedia.org/wiki/ReStructuredText. However in recent years Sphinx started supporting the MyST extension to the very popular (or ubiquitous) Markdown format thus making it interoperable with a vast collection of tools and frameworks.

Fig. 85 Sphinx can create different formats

---