Directory structure

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

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.

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 Assembling different pieces to a book 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.