Principles and conventions

When starting a bigger project like one or more book projects, alone or with others, it is wise to sit down and agree upon some basic principles and conventions. This note is about a technical infrastructure for writing books as an assembly of chapter components, but much more infrastructure is needed to achieve an efficient work flow in the project. One simply needs rules to make the work flow and end product coherent. This means one must agree upon

  • mathematical notation
  • conventions for labels in cross referencing
  • programming style
  • degree of modularization
  • writing style
  • student guide (slides) style
  • style in exercises, problems, and projects

The suggestions here have grown out of the author’s own experience with writing books and must be taken as just one possible example on how to deal with the bullet list above.

Observation: LaTeX-based writing styles are very private

Most authors develop very private ways of using LaTeX in their projects. They often have a vast amount of newcommands and a collection of special LaTeX packages they rely upon. The result is that it might be quite a challenge to combine two LaTeX-based writing projects, because of all the special commands floating around.

With DocOnce and other quite simple markup languages, there are not so many ways to do it and the source code becomes much simpler and easier to integrate across projects and authors.

Note. DocOnce applies a lot of fancy LaTeX packages and HTML CSS styles, but the associated LaTeX/HTML code is automatically generated and steered via command-line options such that the complexity of fancy admonitions or syntax highlighting is not visible in the document the authors are writing on.

Mathematical notation and newcommands

Use a common mathematical notation

I strongly recommend to spend considerable time on constructing a set of newcommands in LaTeX that defines a common mathematical notation for the project (and future projects). Think about newcommands for vectors (arrows or boldface), matrices (uppercase slanted or bold?, tensors, gradient, divergence, curl, etc.

Files with names newcommands*.tex are treated by DocOnce as files with definition of newcommands for LaTeX mathematics. These files must reside in the same directory as the DocOnce source files. However, for a book project, I recommend to have a single newcommands file shared by all chapters. This file is placed in doc/src/chapters/newcommands.p.tex and copied to a specific chapter by the make script for that chapter. The extension of the file is .p.tex, indicating that the file has to be preprocessed by preprocess prior to being copied. The reason is that one occasionally wants the definitions of the newcommands to depend on the output format: standard LaTeX or MathJax. For example, subscripts in mbox font look best with footnotesize font in plain LaTeX, while the larger small font is more appropriate for MathJax. We can then put the following definitions in newcommands.p.tex:

% #if FORMAT in ("latex", "pdflatex")
% Use footnotesize in subscripts
\newcommand{\subsc}[2]{#1_{\mbox{\footnotesize #2}}}
% #else
% In MathJax, a different construction is used
\newcommand{\subsc}[2]{#1_{\small\mbox{#2}}}
% #endif

The make script will then run preprocess on this file, typically

preprocess -DFORMAT=pdflatex ../newcommands.p.tex > newcommands.tex
# or
preprocess -DFORMAT=html ../newcommands.p.tex > newcommands.tex

DocOnce newcommands are for mathematics only

Note that newcommands in DocOnce context are only used for mathematics, rendered by LaTeX or MathJax. Newcommands for other LaTeX constructions (such as section or boxes) should not be used in the DocOnce source code as these are confined to the LaTeX format. Use instead Mako functions.

Here is an example on some useful constructs in a newcommands.p.tex file:

\newcommand{\halfi}{{1/2}}
\newcommand{\half}{\frac{1}{2}}
\newcommand{\tp}{\thinspace .}  % right space after equations

% Operators
\newcommand{\Ddt}[1]{\frac{D #1}{dt}}
\newcommand{\E}[1]{\hbox{E}\lbrack #1 \rbrack}
\newcommand{\Var}[1]{\hbox{Var}\lbrack #1 \rbrack}
\newcommand{\Std}[1]{\hbox{Std}\lbrack #1 \rbrack}
\newcommand{\Oof}[1]{\mathcal{O}(#1)}

% Boldface vectors/tensors
\newcommand{\x}{\boldsymbol{x}}
\newcommand{\X}{\boldsymbol{X}}
\renewcommand{\u}{\boldsymbol{u}}
\renewcommand{\v}{\boldsymbol{v}}
\newcommand{\w}{\boldsymbol{w}}
\newcommand{\V}{\boldsymbol{V}}
\newcommand{\e}{\boldsymbol{e}}
\newcommand{\f}{\boldsymbol{f}}
\newcommand{\F}{\boldsymbol{F}}
\newcommand{\stress}{\boldsymbol{\sigma}}
\newcommand{\strain}{\boldsymbol{\varepsilon}}
\newcommand{\stressc}{{\sigma}}
\newcommand{\strainc}{{\varepsilon}}
\newcommand{\normalvec}{\boldsymbol{n}}

% Unit vectors
\newcommand{\ii}{\boldsymbol{i}}
\newcommand{\jj}{\boldsymbol{j}}
\newcommand{\kk}{\boldsymbol{k}}
\newcommand{\ir}{\boldsymbol{i}_r}
\newcommand{\ith}{\boldsymbol{i}_{\theta}}
\newcommand{\iz}{\boldsymbol{i}_z}

% Number sets
\newcommand{\Real}{\mathbb{R}}
\newcommand{\Integerp}{\mathbb{N}}
\newcommand{\Integer}{\mathbb{Z}}

Label conventions

Books usually contain large amounts of cross referencing using labels (logical names) for sections, equations, exercises, and literature references. I strongly recommend to introduce conventions for how to construct labels as it makes it much easier to find the name of a new label and understand what a given label refers to.

My chapter names are of the form ch:name, where name is the nickname of the chapter (this nickname is used for many other purposes also, see the section Organization of a chapter). Section and subsection names are of the form

projectname:chaptername:sectionname:subsectionname

where the names are short nicknames. Each short name may contain underscores to separate words. For example, the present section has label setup:rules:conv:labels, where setup is the nickname of the project (this book), rules is the nickname of the present chapter, conv is the nickname of the present section, and label is the nickname of the subsection. The section Organization of a chapter has label setup:rules:book_assembly:org, where book_assembly is the nickname of the section using underscore to separate two words. Sometimes I leave out the project name.

Equations may start with the current subsection label and continued with eq:name, where name is some logical name for the equation. Figures are given the same type of name, except that the postfix is fig:name. For exercises I use exer:name as postfix in the labels. Equations and figures within an exercise have extended names such as setup:rules:exer:eq:uv_relation.

Bibliographic references can take the forms author_year, author1_author2_year, author1_etal_year. An alternative is to use names that reflect the topic: topic:paper or topic:url, e.g., IPython:paper for a ]paper on IPython or IPython:url for the IPython website.

You can run doconce list_labels *.do.txt to get a list of labels, categorized under the various section headings, in your DocOnce documents. This command quickly reveals if a clean-up of label names is necessary. You can redirect the output of the command to a file and then add a second column with new label names. This file can be used with the command doconce replace_from_file to perform substitutions from old to new labels.

Compilation of DocOnce files can make use of the option --latex_labels_in_margin to get the label names of equations and sections to be printed in the margin.

Programming style

It is fundamental for a book project to stick to one well-defined programming style. I recommend to adopt the most widely accepted style and adapt that to the project. For example, in the world of Python programming, there is a style, referred to as PEP8. Personally, I am not fond of all the rules in this style, and I intentionally break some of them, especially rules that forces unnecessary vertical space in a book (although vertical space in electronic books is for free, there is a strong tradition of minimizing the vertical length of programs in books). Fortunately, for Python there is are nice tools for checking that a code follows the PEP8 rules, e.g., Flake8 (see [Ref1] for an intro).

For any programming language it is key to agree on how to use white space in indentation, style of loops, identifier names (my_funtcion vs myFunction vs MyFunction), white space in function argument lists, etc.

Tip: make a 1-1 mapping between mathematics and code

Computer code is very much easier to understand if you have defined the problem it is going to solve in mathematics first. Reuse terms and notation in the program, and try to make the key statements in the code as close as possible to the mathematical formulation.

Typesetting of computer code in DocOnce makes use of the !bc construction and a named environment, e.g., pycod for a Python snippet and pypro for a complete Python program. Users are often confused if a set of statements in a text can be executed as they stand or not. That is why we have introduced the cod and pro environments: cod is for just some code, while pro is for a complete program that will run. You may choose the typesetting to be different for the cod and pro environments.

When preparing text for IPython/Jupyter notebooks, a code snippet cannot run unless previous snippets contain the necessary code. Sometimes this forces you to include more code than would be natural in a book. There is a third type of environment, hid, that can be used to insert code segments that are to be hidden in text, but present in notebooks to enable execution of future snippets. For example,

# Need to import to run next snippet
!bc pyhid
from numpy import *
from matplotlib.pyplot import *
!ec

We can now generate coordinates by

!bc pycod
x = linspace(0, 1, 101)
y = sin(x)
plot(x, y)
!ec

The import statements will only be visible in the notebook output and not in any other format.

Degree of modularization

My recommendation is to divide the project into as small modules as possible and to make these modules as independent as possible. This is a very difficult optimization problem. There is some kind of gravity force towards big chapters and lots of cross-references internally and to other chapters. For book composition and even more for course composition, smaller modules give much higher degree of flexibility.

To make modules independent, the degree of cross-referencing between modules must be modest, which forces a need to repeat material. Repetition breaks a strong tradition in book writing. However, moving away from a strictly linear chapter-by-chapter book to a more flexible set of modules connected in a graph, will induce repetition. Readers also appreciate repetition, perhaps slightly differently phrased with purpose, rather than being served with lots of references to equations and codes in other chapters.

Tip: Define input-output of modules

Ideally, modules should start with a well-defined list of required background knowledge and a set of learning outcomes. This information makes it easier to place the module in the knowledge landscape.

Books with widely different writing styles among authors tend to be confusing for readers. If the styles differ much, and it is difficult to converge to a more coherent style, listing the authors together with the chapter title is an idea to point explicitly out that a different team is behind the present chapter.

Student guide (slides) style

This note suggests to develop a book together with a study guide, i.e., a summarizing version of the material. An effective format of a study guide is a set of slides, ideally a set that can be used both for teaching and for self-study. The section Study guides and slides explains some infrastructure for producing DocOnce slides.

Some prefer to develop slides for a study guide first and then use this as a skeleton for writing the running text of a chapter. Others prefer to produce the slides from the running text.

The style of slides is even more important than the style of running text. Slides for reading are not so sensitive to the style, but if the slides are also intended to be used in teaching, the style becomes key. Some comments on style are provided in the box in the introduction to the section Study guides and slides. Rather than having boring headings a la Assumptions, followed by a bullet list of assumptions, I recommend to summarize the most important information in a 1-2 line heading, e.g., We assume a homogeneous material and no external forcing. The headings will then form a collection of the most important information from each slide and be a very effective table of contents of the material. The most important thing, though, is that different authors stick to the same slide style.

Style in exercises, problems, and projects

A central part of the writing style in a book is the division of material between running text and exercises. DocOnce features three types of exercises which can be effectively used in this context:

  • Exercise: smaller exercises tightly coupled to the text
  • Problem: smaller exercise that live its own life (without references to the text)
  • Project: large problem

Exercises are then used to repeat and train the material in the book. Problems are used to explore new problem settings, while projects are collections of closely related problems. (The term “exercise” means in DocOnce context either an exercise in the restricted sense or a common term for what we call exercise, problem, and project above.)

The DocOnce exercise format has several useful features:

  • hints
  • multiple-choice questions (quiz)
  • remarks
  • short answers
  • (longer) complete solutions

Many students struggle with identifying the problem setting (question) when too much information comes at once. Hints can be effectively used to separate the question from additional information that is just supposed to help the reader. Remarks fulfill a similar purpose and can separate fun facts or information that puts the problem into a wider perspective. Short answers and full solutions can be taken out of the document at compile time. (HTML Bootstrap styles can fold/unfold hints and solutions/answers.)

Multiple-choice questions are typeset with the quiz environment in DocOnce. All quizzes can be extracted and uploaded as online Kahoot games where students can participate via their smart phones.

It is possible to extract all exercises in a DocOnce document as a separate document.