Tools

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.

Making a new chapter

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

Compiling the chapter to LaTeX and PDF

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.

Tip: use tinyurl.com for shortening long URLs

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

Cleaning Files

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.

Automatic spell checking

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 |nbsp| `` 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 |nbsp| ``, you may look into the file-wise list of misspellings: the misspellings in ``mydoc.do.txt are listed in ``tmp_misspelled_mydoc.do.txt ``.

Compiling the chapter to HTML

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.

You need to edit the index file

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 appendix Appendix: 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.

Compiling the chapter to a notebook

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

About figures when publishing HTML

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.

Compiling the book

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.

HTML/Sphinx versions of the book

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