Mako is the preprocessor that is always run prior to translating DocOnce documents into a specific format. It means that your DocOnce source is actually a computer program where you can use variables and functions.
Writing chapters that can both live their individual lives and be part of a book faces some challenges for which we have some nice solutions in the coming sections.
The easiest way to utilize Mako is to introduce variables in the text.
For example, one can introduce a variable COPYRIGHT
for the type of copyright desired
for authors. Most Mako variables in this text are upper case, but
any legal variable name in Python is also a legal name in Mako.
In the DocOnce source file we can replace the variable by its content
by writing ${COPYRIGHT}:
AUTHOR: H. P. Langtangen ${COPYRIGHT} at Simula & UiO
The content of the variable can either be set at the command line
as part of the doconce format command,
Terminal> doconce format html mydoc COPYRIGHT='{copyright|CC BY}'
or hardcoded in the DocOnce file (as a standard Python variable) inside
the <%...%> directives (before the first use of the variable):
<%
COPYRIGHT = '{copyright|This work is released under a BSD license.}'
%>
By having the copyright as a variable, we can use this variable for all
authors to ensure consistency of copyrights, and we can easily compile
different versions of the documents with different copyrights by just
changing COPYRIGHT= on the command line.
Mako variables can be used in loops and if tests.
DocOnce always defines a variable FORMAT holding the chosen output
format. This variable is often used for emitting different text depending
on the format, e.g.,
See
% if FORMAT in ('latex', 'pdflatex'):
Section ref{mysec}
% elif FORMAT == 'html':
ref{mysec}
% elif FORMAT == 'sphinx':
ref{mysec}
% else:
the previous section
% endif
for more information.
In a book you will often need the phrase "this chapter", but his is
inappropriate if the chapter is a stand-alone document. Then you would
rather say "this document". Similarly, "this book" must read
"this document" in a stand-alone chapter.
We have resolved this issue by introducing
Mako variables CHAPTER, BOOK, and APPENDIX such that you
write
In this ${BOOK}, the convention is to use boldface for vectors.
For this to work, you need to define CHAPTER, BOOK, and APPENDIX
as variables on the command line as part of the doconce format command:
Terminal> doconce format pdflatex ch2 --latex_code_style=pyg \
CHAPTER=document BOOK=document APPENDIX=document
When the book is compiled, you do
Terminal> doconce format pdflatex ch2 --latex_code_style=pyg \
CHAPTER=chapter BOOK=chapter APPENDIX=appendix
The make*.sh files found in doc/src/chapter/ and
doc/src/book make proper definitions of
CHAPTER, BOOK, and APPENDIX.