.. !split

Use of variables
================

.. index:: variables in mako

.. index::
   single: mako; 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}``:

.. code-block:: doconce

         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,

.. code-block:: text

        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):

.. code-block:: doconce

        <%
        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.,

.. code-block:: doconce

        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"
---------------------------------

.. index:: CHAPTER

.. index:: BOOK

.. index:: APPENDIX

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

.. code-block:: doconce

        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:

.. code-block:: text

        Terminal> doconce format pdflatex ch2 --latex_code_style=pyg \
                  CHAPTER=document BOOK=document APPENDIX=document

When the book is compiled, you do

.. code-block:: text

        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``.