.. !split

.. _setup:rules:dir_struct:

Directory structure
===================

.. index:: figure directory

.. index:: movie directory

.. index:: video directory

.. index:: source code directory

.. index:: pub directory

We shall outline a directory structure that can be effective when
assembling different DocOnce documents into a book:

.. code-block:: text

        doc
          src
            chapters
              ch2
                fig-ch2
                src-ch2
                mov-ch2
                exer-ch2
            book
          pub
            chapters
            book
          web

The root directory for all documentation is called ``doc``, with two
subdirectories: ``src`` for all the DocOnce source code, and ``pub`` for
compiled (published) documents in various formats. A third
subdirectory, ``web``, is often present as an entry point for the web
pages on GitHub. This directory typically contains the autogenerated
``index.html`` and additional style files on GitHub. The ``index.html``
file should have links to published documents in ``../pub``.

Under ``doc/src`` we may have a directory ``chapters`` for
the individual chapters and a directory ``book`` for the assembly into
a book. One may also think of more than one book directory if a set
of documents (chapters) naturally leads to multiple books. All
chapters can then be put in the ``chapters`` directory.

.. index:: nickname

Each chapter has a short *nickname*, say ``ch2`` for simplicity
for Chapter 2 (a more descriptive name related to the content is obviously
much better!). Figures are placed in subdirectory ``fig-ch2`` and
computer code in subdirectory ``src-ch2``.
These two latter directories may have subdirectories if desired.
We may also include a directory ``mov-ch2`` for video files, ``exer-ch2`` for
answers to exercises, etc.

Under ``book``, we typically have a document ``book.do.txt`` for the complete
book. This is a file with a lot of ``# #include "...do.txt"``
statements for the Preprocess preprocessor for
including the files for the various chapters, see the section :ref:`setup:rules:book_assembly` for details. Additional files
in the ``book`` directory include make files for compiling the book,
scripts for packing the book for publishing, perhaps an errata document, etc.