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.

Organization of a chapter

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

# #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 [1], with the content

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
[1]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

As described in the section Directory structure, 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

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:

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 [2] (!). 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.

[2]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!

Say we want to produce a LaTeX document:

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

Terminal> ln -s ../chapters/ch2/src-ch2 src-ch2

Similarly, the LaTeX code in book.tex for inclusion of a figure may contain

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

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

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

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.

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