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
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.
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
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}}
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.
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 [1] 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.
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.
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.
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.
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.
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:
The DocOnce exercise format has several useful features:
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.