.. !split
.. _setup:rules:conv:
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.
.. As most others, I developed a very private
.. style for writing books in LaTeX
.. admonition:: 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.
.. _setup:rules:conv:newcommands:
Mathematical notation and newcommands
-------------------------------------
.. index:: newcommands
.. admonition:: 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``:
.. code-block:: latex
% #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
.. code-block:: bash
preprocess -DFORMAT=pdflatex ../newcommands.p.tex > newcommands.tex
# or
preprocess -DFORMAT=html ../newcommands.p.tex > newcommands.tex
.. admonition:: 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:
.. code-block:: latex
\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}}
.. _setup:rules:conv:labels:
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 :ref:`setup:rules:book_assembly:org`).
Section and subsection names are of the form
.. code-block:: text
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 :ref:`setup:rules:book_assembly:org`
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.
.. admonition:: 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,
.. code-block:: doconce
# 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.
.. admonition:: 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 :ref:`setup:rules: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 :ref:`setup:rules: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.