.. !split .. _setup:rules:book_assembly: Assembling different pieces to a book ===================================== Many smaller writings in the DocOnce format can be assembled into a single, large document such as a book or thesis. The recipe for doing this appears below. .. _setup:rules:book_assembly:org: Organization of a chapter ------------------------- .. index:: single: chapter; organization .. index:: single: chapter; files Suppose one chapter of the book has the nickname ``ch2`` and may hold all text or just include text in other DocOnce files, e.g., ``part1.do.txt``, ``part2.do.txt``, and ``part3.do.txt``. In this latter case, ``ch2.do.txt`` has the simple content .. code-block:: doconce # #include "part1.do.txt" # #include "part2.do.txt" # #include "part3.do.txt" Note that the ``ch2.do.txt`` file contains just plain text without any ``TITLE``, ``AUTHOR``, or ``DATE`` lines and without any table of contents (``TOC``) and bibliography (``BIBITEM``). This property makes ``ch2.do.txt`` suitable for being included in other documents like a book. However, to compile ``ch2.do.txt`` to a stand-alone document, we normally want a title, an author, a date, and perhaps a table of contents. We also want a bibliography if any of the included files have ``cite`` tags. To this end, we create a wrapper file, say ``main_ch2.do.txt`` [#name-main]_, with the content .. code-block:: doconce TITLE: Some chapter title AUTHOR: A. Name Email:somename@someplace.net at Institute One AUTHOR: A. Two at Institute One & Institute Two DATE: today TOC: on # Externaldocuments: ../ch3/main_ch3, ../ch4/main_ch4 # #include "ch2.do.txt" ======= References ======= BIBFILE: ../papers.pub .. [#name-main] The prefix ``main_`` is inspired by the main program in computer program: those statements make a program run, like ``main_ch2.do.txt`` defines the surroundings of the "library text" ``ch2.do.txt``. We strip off ``main_`` when publishing the files in ``doc/pub``. Recall that DocOnce relies on the Publish software for handling bibliographies. It is easy to import from BibTeX to Publish and create a database of references (``papers.pub``) to get started (but we recommend to continue working with the Publish database directly and collect new items in the ``papers.pub`` file as Publish is more flexible than BibTeX). Figures and source code ----------------------- .. index:: figure directory .. index:: movie directory .. index:: video directory .. index:: source code directory As described in the section :ref:`setup:rules:dir_struct`, we recommend to put figures and source codes (to be included in the document) in separate directories. Although such directories could have natural names like ``fig`` and ``src``, it will cause trouble if we do not use unique names for these directories, like ``fig-ch2`` and ``src-ch2``. Otherwise, we would need to copy all figures in all pieces into a common ``fig`` directory for the book and all source code files into a ``src`` directory. With unique names, figures and source code files can always reside in their original locations, and we can easily reach them through links. This will be described next. Assembly of chapters to a book ------------------------------ .. index:: assembly (chapters to book) All the files associated with the ``ch2`` document and chapter reside in the ``ch2`` directory. A fundamental principle of DocOnce is to have just one copy of the files ("document once!"). To include the ``ch2`` text in a larger document like a book, we just need to include the ``ch2.do.txt`` file and a chapter heading. Here is an example of a document ``book.do.txt`` for a complete book: .. code-block:: doconce TITLE: This is a book title AUTHOR: A. Name Email:somename@someplace.net at Institute One AUTHOR: A. Two at Institute One & Institute Two DATE: today TOC: on ========= Preface ========= label{ch:preface} # #include "../chapters/preface/preface.do.txt" ========= Heading of a chapter ========= label{ch:ch2} # #include "../chapters/ch2/ch2.do.txt" # Similar inclusion of other chapters ========= Appendix: Heading of an appendix ========= label{ch:somename} # #include "../chapters/nickname/nickname.do.txt" ======= References ======= BIBFILE: ../papers.pub When running ``doconce format`` on ``book.do.txt``, the entire document is contained in *one* big file [#one-file]_ (!). To see exactly what has been included, you can examine the result of running the first preprocessor, ``preprocess``, on ``book.do.txt``. All the includes are handled by this preprocessor. The result is contained in the file ``tmp_preprocess__book.do.txt``, which then contains the entire DocOnce source code of the book. The second preprocessor, ``mako``, is thereafter run (if DocOnce detects that it is necessary). The result of that step is available in ``tmp_mako__book.do.txt``. It is important to examine this file if there are problems with Mako variables or functions. The ``tmp_mako__book.do.txt`` file is thereafter translated to the desired output format. .. [#one-file] A single DocOnce file and consequently a single ``.tex`` file works out well on today's laptops. A book with 900 pages [Ref2]_ has been tested! .. index:: links to fig/src directories Say we want to produce a LaTeX document: .. code-block:: text Terminal> doconce format pdflatex book [options] If the DocOnce source contains copying of source code from files in ``@@@CODE`` constructs, it is important that ``doconce`` finds the files. For example, .. code-block:: doconce @@@CODE src-ch2/myprog.py fromto: def test1@def test2 will try to open the file ``src-ch2/myprog.py``. Since this file is actually located in ``../ch2/src-ch2/myprog.py``, ``pdflatex`` will report an error message. A local link to that directory resolves the problem: .. code-block:: text Terminal> ln -s ../chapters/ch2/src-ch2 src-ch2 Similarly, the LaTeX code in ``book.tex`` for inclusion of a figure may contain .. code-block:: latex \includegraphics[width=0.9\linewith]{fig-ch2/fig1.pdf} For this command to work, it is paramount that there is a link ``fig-ch2`` in the present ``book`` directory where the ``pdflatex`` command is run to the directory ``../chapters/ch2/fig-ch2`` where the figure file ``fig1.pdf`` is located. .. index:: scripts module It is recommended to use the function ``make_links`` in ``scripts.py`` to automatically set up all convenient links from the ``book`` directory to the individual chapter directories. Provided the *list of chapter nicknames* at the top of ``scripts.py`` *is correct*, you can just run .. code-block:: python >>> import scripts >>> scripts.make_links() to automatically set up all links to all ``src-*``, ``fig-*``, and ``mov-*`` directories. You need to rerun this ``make_links`` function after inclusion of a new chapter in the ``chapters`` tree. .. admonition:: Identify LaTeX errors in the original chapter files When you run ``pdflatex book`` and get LaTeX errors, you need to see where they are in ``book.tex`` and use this information to find the appropriate DocOnce source file in some chapter. Usually, there are few errors at the "book level" if each individual chapter has been compiled. To this end, you can use ``scripts.py`` to automatically compile each chapter separately. The process is stopped as soon as a DocOnce or LaTeX error is encountered. .. code-block:: python >>> import scripts >>> scripts.compile_chapters() With heavy use of Mako one can get quite strange error messages. Some ask you to rerun the ``doconce format`` command with ``--mako_strict_undefined`` to see undefined Mako variables. Make sure you run the ``make.sh`` script by ``bash -x`` if the script does not feature the ``set -x`` command in the top of the file (for displaying a command prior to running it). Copy the complete ``doconce format`` with the mouse and add the ``--mako_strict_undefined`` option. Other error messages point to specific lines that Mako struggles with. Go to the file ``tmp_mako__book.do.txt`` to investigate the line.