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