Use of variables

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.

How to speak about “this chapter”

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.