.. |nbsp| unicode:: 0xA0 :trim: .. !split 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 -------------------- .. index:: mkdir.sh 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 .. code-block:: text 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 -------------------------------------- .. index:: make.sh 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, .. code-block:: bash bash -x ../make.sh main_mychap or optionally with some command-line arguments, .. code-block:: bash 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. .. admonition:: 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 |nbsp| `` at some point contains acceptable words only, you update the dictionary by .. code-block:: bash 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 |nbsp| ``. Compiling the chapter to HTML ----------------------------- .. index:: make_html.sh There is also a script ``doc/src/chapters/make_html.sh`` for making HTML versions of the chapter. Just call this as .. code-block:: text 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. .. admonition:: 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 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 .. code-block:: text 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``. .. index:: IPython notebooks .. index:: notebooks .. index:: Jupyter notebooks 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: .. code-block:: text Terminal> doconce format ipynb main_rules \ CHAPTER=document BOOK=document APPENDIX=document .. index:: clean.sh About figures when publishing HTML ---------------------------------- There will be ```` 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: RunestoneInteractive books .. index:: sphinx 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 * standard Sphinx `book `__ * `RunestoneInteractive `__ Sphinx `book `__