Study Guide: Directory and file structure

Hans Petter Langtangen [1, 2]

[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo

Dec 20, 2015










Table of contents

Directory structure for a book project
      Overview of the directory structure
      Directory structure within a chapter
      The total directory structure
      The book directory
Newcommands
Assembling different pieces to a book
      Organization of DocOnce chapter files
      Compiling a chapter requires a wrapper file with title, author, ...
      Figures and source code
      Assembly of chapters to a book
      A book.do.txt file
      The book file relies much on running preprocessors
      The book directory must be coupled to source and figure directories
      About figures when publishing HTML
Tools
      Making a new chapter
      Compiling a chapter
      Compiling the book
Study guides and slides
      Why is it so challenging to convert a chapter to slides?
      Slide directory
      The lectures_ch2.do.txt file
      The requirements to a slide collection









Directory structure for a book project









Overview of the directory structure

Can have lots of chapters and more than one book directory if multiple books are relevant.









Directory structure within a chapter

Each chapter has a short nickname used in file and directory names.

The directories src-ch2, fig-ch2, mov-ch2, and similar may have any subdirectory structure, but the names should as indicated here since the setup for DocOnce books has many tools relying on the naming convention.









The total directory structure

Here is a big project: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
doc
  src
    chapters
      ch2
        fig-ch2
        src-ch2
        mov-ch2
        exer-ch2
      ch3
        fig-ch3
        src-ch3
        mov-ch3
        exer-ch3
    book1
    book2
  pub
    chapters
      ch2
        html
        pdf
        ipynb
      ch3
        html
        pdf
        ipynb
    book









The book directory









Newcommands

Example on doc/chapters/newcommands.p.tex: 

1
2
3
4
5
6
7
%% #if FORMAT in ("latex", "pdflatex")
%% Use footnotesize in subscripts
\newcommand{\subsc}[2]{#1_{\mbox{\footnotesize #2}}}
%% #else
%% In MathJax, a different construction is used
\newcommand{\subsc}[2]{#1_{\small\mbox{#2}}}
%% #endif

make.sh runs typically 

1
2
3
4
5
preprocess -DFORMAT=pdflatex ../newcommands.p.tex > newcommands.tex
# make latex versions

preprocess -DFORMAT=html ../newcommands.p.tex > newcommands.tex
# make html versions

DocOnce newcommands are for mathematics only!

Do not use newcommands for general typesetting commands, use Mako functions instead - they work for all output formats.









Assembling different pieces to a book









Organization of DocOnce chapter files

ch2.do.txt: 

1
2
3
4
5
# #include "part1.do.txt"

# #include "part2.do.txt"

# #include "part3.do.txt"









Compiling a chapter requires a wrapper file with title, author, ...

To compile a stand-alone document for the chapter, create main_ch2.do.txt: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
TITLE: Some chapter title
AUTHOR: A. Name Email:somename@someplace.net at Institute One
AUTHOR: A. Two at Institute One & Institute Two
DATE: today

TOC: on

# Externaldocuments: ../ch3/main_ch3, ../ch4/main_ch4

# #include "ch2.do.txt"

======= References =======

BIBFILE: ../papers.pub









Figures and source code

Important that figure and source code files have chapter-unique names when combining all files into a book. Use fig-nickname and src-nickname.

Optional directories:









Assembly of chapters to a book

Recall:

DocOnce = Document Once, Include Anywhere









A book.do.txt file 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
TITLE: This is a book title
AUTHOR: A. Name Email:somename@someplace.net at Institute One
AUTHOR: A. Two at Institute One & Institute Two
DATE: today

TOC: on

========= Preface =========
label{ch:preface}

# #include "../chapters/preface/preface.do.txt"

========= Heading of a chapter =========
label{ch:ch2}

# #include "../chapters/ch2/ch2.do.txt"

# Similar inclusion of other chapters

========= Appendix: Heading of an appendix =========
label{ch:somename}

# #include "../chapters/nickname/nickname.do.txt"

======= References =======

BIBFILE: ../papers.pub









The book file relies much on running preprocessors









The book directory must be coupled to source and figure directories

Running 

1
Terminal> doconce format pdflatex book [options]

will most likely involve constructs like 

1
@@@CODE src-ch2/myprog.py  fromto: def test1@def test2

but pdflatex sees no book/src-ch2 directory! A local link resolves the problem: 

1
Terminal> ln -s ../chapters/ch2/src-ch2 src-ch2

Similar problems for figures! 

1
Terminal> ln -s ../chapters/ch2/fig-ch2 fig-ch2

Auto-generation of all links (if chapters= is set correctly in scripts.py): 

1
2
>>> import scripts
>>> scripts.make_links()









About figures when publishing HTML









Tools









Making a new chapter









Compiling a chapter

To LaTeX/PDF: 

1
Terminal> bash make.sh

To HTML: 

1
Terminal> bash ../make_html.sh main_nickname.do.txt

The doc/src/chapters/make.sh script is quite general and can be edited according to your layout preferences of the LaTeX documents.

There is also a script doc/src/chapters/make_html.sh for making HTML versions of the chapter. Just call this as 

1
Terminal> bash ../make_html.sh main_mychap

Three HTML versions with an index.html table of contents are generated.









Compiling the book

Go to book directory and produce LaTeX/PDF book by 

1
2
Terminal> bash make.sh
Terminal> bash make.sh nospell   # turn off spell checking

About book styles and tools:









Study guides and slides









Why is it so challenging to convert a chapter to slides?

Balance:

Many iterations and use of slides in teaching over and over again are needed!









Slide directory

For a chapter ch2,

Compile slides: 

1
Terminal> bash ../make_lectures.sh lectures_ch2.do.txt

Note the possibility to turn the TOC on and off: Beamer has its own table of contents, while HTML5 slides may benefit from having one.









The lectures_ch2.do.txt file 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
TITLE: Study Guide: Some title
AUTHOR: Author Name Email:somename@someplace.net at Institute One
DATE: today

# #ifdef WITH_TOC
!split
TOC: on
# #endif

# #include "lec-ch2/part1.do.txt"

# #include "lec-ch2/part2.do.txt"

# #include "lec-ch2/part3.do.txt"









The requirements to a slide collection

Tree purposes:

  1. Read as a study guide to get overview before reading the full text of chapter

  2. Watch as slides during an oral presentation

  3. Read as a study guide to repeat and enforce overview of the material
Rules: