Setup4book-DocOnce

Flexible setup for writing a book as an assembly of chapters in DocOnce markup.

View project on GitHub
The purpose of this "book project" is to demonstrate a minimalistic setup for making books in the DocOnce format. The setup contains several useful features:

  1. Chapters can exist as stand-alone documents in different formats:

    • traditional LaTeX-style PDF report,

    • web pages with various various fancy stylings (e.g., Sphinx, Bootstrap) and possibility for multi-media elements,

    • IPython notebooks,

    • blog posts (not exemplified here, but straightforward),

    • wiki (if you do not need mathematical typesetting).

  2. Chapters can be flexibly assembled into a traditional LaTeX-based PDF book for a traditional publisher, or a fancy ebook.

  3. The book and the individual chapter documents may have different layouts.

  4. Active use of preprocessors (Preprocess and Mako) makes it easy to have different versions of the chapters, e.g., a specialized version for a course and a general version for the world book market).

  5. DocOnce has support for important elements in teaching material: eye-catching boxes (admonitions), quizzes, interactive code, videos, structured exercises, quotes.

  6. Study guides or slides can easily be developed from the running text and stored along with the chapters. These can be published as LaTeX Beamer slides, reveal.js slides, and IPython notebooks.

These features have the great advantage that a book can evolve from small documents, thereby making the barrier for book writing much smaller. Also, several appealing ebook formats can be produced, both for the book and the individual chapter documents. The chances that your students read a chapter on the bus becomes larger if the chapter is available as attractive, screen-fit Bootstrap pages on the smart phone than if you just offer the classic LaTeX PDF which actually requires a big screen or a printer.

Implementation of point 1 and 2 is not trivial and requires some rules that might not feel natural at first sight in the setup. Writing a book soon becomes a technically and mentally complex task, just like developing a software system. For the latter people have invented a lot of sophisticated technologies and best practices to deal with the complexity. The present setup for books is a similar collection of my own technologies and best practices, developed from writing thousands of pages. In particular, the setup has been successfully used for the large-scale 900-page Springer book "A Primer on Scientific Programming with Python" by the author (individual chapters of this book can be examined online in "various ebook formats": "http://hplgit.github.io/primer.html/doc/pub/looplist/index.html") as well as for books in the works.

To use this setup, just clone the repository and you have the directory structure, the scripts, and example files to get started with a book project at once! The source files for this book (especially in doc/src/chapters/rules) constitute nice demonstrations for learning about basic and advanced DocOnce writing techniques.

Documents describing the setup

Table of contents for all documentation