You can start a new, future, potential book project by simply copying the directory structure of the setup4book-doconce repository on GitHub. Then you can follow the instructions below to start writing and adapting the structure to your project's needs.
Under doc/src/chapters
you find the chapters in this "sample book" as well as a script
doc/chapters/mkdir.sh that creates a new directory for you with the
typical files needed for a new chapter. You can either edit existing
chapters, or make a brand new empty chapter by running
Terminal> sh mkdir.sh mychap
This command makes
a directory mychap for a new chapter with nickname mychap.
Files from the template directory are used to populate mychap. You get
an empty mychap.do.txt where the text is supposed to go, or this file
can just include a series of smaller .do.txt files, and you get the
wrapper file main_mychap.do.txt such that you can compile this chapter
as a stand-alone document. You also get make.sh which calls ../make.sh
with the chapter main document (main_mychap) as argument. Optional
arguments for running doconce format pdflatex can be given to
../make.sh in make.sh if needed (e.g., --encoding=utf8).
To make a stand-alone document of a chapter, by compiling to LaTeX and PDF,
we propose the convention to have a make.sh in each chapter directory.
This make.sh can in most cases just call up a common ../make.sh
script,
bash -x ../make.sh main_mychap
or optionally with some command-line arguments,
bash -x ../make.sh main_mychap --encoding=utf-8
The doc/src/chapters/make.sh script is quite general and may be edited
according to your layout preferences of the LaTeX documents.
The present make.sh script creates two PDF files: one for printing and
one for electronic viewing. The difference is that all URLs in the
version for printing appear as footnotes (and just hyperlinks with
a dark blue color in the electronic version). The two files are
named mychap.pdf and mychap-4print.pdf, respectively, and
copied to doc/pub/mychap/pdf for publishing.
When compiling a document to LaTeX for printing on paper (--device=paper),
URLs in hyperlinks will appear as footnotes. Very long URLs may then exceed
the line width, or worse, extend beyond the physical paper size.
Replace such long URLs with short forms using tinyurl.com.
I recommend tinyurl.com rather than competitors like goo.gl and bit.ly
because
if you have some URL http://tinyurl.com/oul3xhn you can easily
add more to the path, e.g., http://tinyurl.com/oul3xhn/index.html,
and this new URL works (goo.gl and bit.ly do not allow such extensions).
In particular, you can define the tinyurl.com URL as a Mako variable
(see doc/mako_code.txt for example) and use it as a quick and logical
name in the text for the URL and extend its path as appropriate. For example,
I always have a Mako variable for the URL of the repository directory for
the software associated with a chapter and can then easily add
/myprog.py to the variable to create a link to the file at GitHub.
Readers can then just click to read or download the file.
Remark about LaTeX typesetting of computer code.
The suggested make.sh file
applies the --latex_code_style= option to doconce format
for specifying the typesetting of blocks of computer code in LaTeX.
Originally, DocOnce applied the ptex2tex program to select such
typesetting, but the new method is more flexible and simpler in that
it gives cleaner LaTeX code. (With ptex2tex one would need a common
configuration file .ptex2tex.cfg in
doc/chapters to be copied by
doc/chapters/make.sh to the chapter directory prior to running
`ptex2tex.)
The make*.sh files generate a lot of files that can easily
be regenerated and that are normally removed from the chapter
directories. The script sh ../clean.sh can be run in any
chapter directory to clean up redundant files.
The make.sh first runs a spell check using doconce spellcheck.
The first time you run this command there will be many "misspellings"
because of unregistered (scientific) words in the dictionary and maybe
also because some words are actually misspelled. Invoke the
misspellings.txt file to see a list of all misspellings. Correct
mistakes in the original documents and run the make.sh script again.
When misspellings.txt at some point contains acceptable words only,
you update the dictionary by
cp new_dictionary.txt~ .dict4spell.txt
Make sure .dict4spell.txt is version controlled by Git.
The make.sh script will not proceed with compilation of the documents
before the spell check is run without errors.
Finding misspellings can sometimes be a challenge. For a document named
mydoc.do.txt, the spell check is carried out on a stripped version,
named tmp_stripped_mydoc.do.txt. Look into this file for misspellings
that are not obvious. Strange misspellings such as APlu or similar
usually arise from missing dollar sign around mathematical formulas.
Formulas are stripped away in tmp_stripped_mydoc.do.txt, but if a
dollar sign is missing, mathematical formulas become words subject
to spell checking. To find the relevant file containing
a particular misspelling listed in misspellings.txt , you may look
into the file-wise list of misspellings: the misspellings in mydoc.do.txt
are listed in tmp_misspelled_mydoc.do.txt .
There is also a script doc/src/chapters/make_html.sh for making
HTML versions of the chapter. Just call this as
Terminal> bash ../make_html.sh main_mychap
to make HTML versions of the mychap chapter.
The current version of make_html.sh creates four types of HTML
layouts and an index.html file with a list of links to these three files:
1) HTML plain Bootstrap style, 2) HTML Bootswatch readable style,
3) plain HTML solarized color style, and 4) Sphinx pyramid style.
(Note that the latter document is a true Sphinx document,
made by doconce format sphinx, and from which one
could make other formats too.)
It is easy to go into the make_html.sh script and generate other
HTML or Sphinx styles.
The index.html file generated by make_html.sh is made from the
DocOnce source file index_html_files.do.txt. This is a
file utilizing Mako programming
(see
the document Use of Mako to aid book writing).
There is also a similar file, index_files.do.txt, listing all
the published documents in various formats associated with a complete
book projects (to go to doc/pub/index.html).
The index_html_files.do.txt and index_files.do.txt files rely much
on a Mako dictionary chapters, defined in mako_code.txt. This
dictionary maps nicknames to chapter titles. We can then specify a
nickname and easily get the corresponding full chapter title. For
example, in index_files.do.txt we defined a Mako list published
holding the nicknames of the chapters we want to publish. With a Mako
for loop we can then run through these selected chapters and generate
the corresponding DocOnce lists with all the formats that is offered
for a chapter and its associated slides. This is a nice example on
how a potentially quite large DocOnce document with much repetitive
constructions can be written with very compact code.
One can imagine that for a large books under constant development with
different states of different chapters, this setup makes it easy to
take chapters in and out of the book. In addition, with Mako variables
in the chapters one can easily defined different state of maturity of
the text. With minor Mako programming in index_files.do.txt and
extension of the make*.sh files, authors can generate the various
states of the book, e.g., a quality controlled version approved for
students and a complete "work-in-progress" version for authors only
with all available text and lots of DocOnce square-bracket comments.
The index_files.do.txt file gives a table of contents of all documents,
so you will normally compile this manually now and then as
Terminal> doconce format html index_files \
--html_style=bootstrap \
--html_links_in_new_window \
--html_bootstrap_navbar=off
and publish it in doc/pub/index.html.
Although there is no benefit from interactive computing and visualization in the present document, we may produce an IPython notebook for the fun of it:
Terminal> doconce format ipynb main_rules \
CHAPTER=document BOOK=document APPENDIX=document
There will be <img src=fig-ch2/fig1.png> type of tags in HTML code
produced by DocOnce, so it is very important to ensure that the
published .html files have access to a subdirectory
fig-ch2. Normally, one needs to copy fig-ch2 from the ch2
chapter source directory to some publishing directory that stores all
the files necessary for accessing the entire HTML document on the web.
Go to doc/src/book and run make.sh to compile the book. This requires
that book.do.txt performs the right include of chapters, table of
contents, and bibliography.
There are many other tools in doc/src/book too, e.g., the mentioned
library of handy scripts in scripts.py, and an example on how to
pack all files of the entire book projects for publishing with Springer
(pack_Springer.sh).
The current book layout created by make.sh makes use of a (now outdated)
Springer T4 style for textbooks (requires the .cls and .sty files in
the book directory). Other Springer styles supported by DocOnce
are Lecture Notes in Computational Science and Engineering (monographs
and proceedings),
Lecture Notes in Computer Science (proceedings), and Undergraduate Texts
in Physics. Other book styles will require some manual work, either
working out a LaTeX preamble for a special style and use that when
compiling book.do.txt or actually extending the DocOnce source code.
It is easy to make a standard HTML version of the book.do.txt
manuscript, but for large books, Sphinx is usually a better
alternative since it supports navigation, searching, and has an
index. There is a script doc/src/book/make_html.sh that creates a
Sphinx version of the book. Actually, it generates two versions