[Tex/LaTex] How to organize large documents in small nested folders

best practicesbooksstandalone

Preamble

I am writing a large document and I would like to keep it well structured not only in terms of source code (I am aware of commands like \input and include, as well as the standalone package), but also in terms of folder(s) containing the actual source files.

Following How to work with large projects, I have structured my project as follows:

/my_project
    |-main.tex
    |-... % other directories
    |-/contents 
        |-chap01/ % more than one chapter
            |-chap01.tex
            |/img
                |-img01.tex % more than one image

The key point is that each chapter folder has an inner folder containing the images to be typeset in that chapter. Now, the problem is that the images (usually TikZ figures and PGFplots to be compiled) placed in the lowest level of directories and included through standalone, throw an error and the document doesn't get compiled.

The actual question

So my question is: If the proposed structure is sensible, how can I make it work? And if you think it is not the best way to organize and manage a project, could you advise (or point to references about) another way?

How to reproduce the problem

main.tex

\documentclass{scrbook}
\usepackage{standalone}
\standaloneconfig{mode=buildnew}
\usepackage{graphicx}

\begin{document}
\include{./contents/chap01/chap01}
\end{document}

chap01.tex

\chapter{Test A}
\includestandalone{./img/img01}

img01.tex

\documentclass{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
  \fill [red] (0,0) circle (2cm);
\end{tikzpicture}
\end{document}

And here is a small script to help reduce the hassle of the setup for GNU/Linux users. (Place the files main.tex, chap01.tex and img01.tex in a folder and run it.)

#!/bin/bash

# Build folders
mkdir ./contents ./contents/chap01 ./contents/chap01/img

# Place files in their respective directory
cp chap01.tex ./contents/chap01
cp img01.tex ./contents/chap01/img

# Remove files from root directory
rm ./chap01.tex ./img01.tex

# Compile main.tex
pdflatex -shell-escape main.tex

Related questions (with comments)

Best Answer

I am not sure if i can answer the question as posted in a precise way, but here we go.

From the LaTeX point of view, the current working directory is ./ as a unix guy would say. In order to find the image, you have to go down into the contents directory (./contents/), then further down into chapter01 (./contents/chap01/) and finally change into the image folder (./contents/chap01/img/). This is a bit tediuos to write everytime, but there are thing like $TEXINPUTS or \graphicspath. This would be the pure LaTeX side.

Look at it from a different angle, changing directories in a shell can be a lot of fun, or pure hell. If you are working with a file manager, you are clicking your way through.

In my point of view (see, this is opinion based) the best practice is to have just unique filenames, not only for figures, but for all files; tex-files, image-files, pdf-files.

I was once collaborating with a human being, who saved all journal articles as is, meaning with a strange number. The person had quite a system, you had to go at least 4 levels down to see a pdf file (remember, all file names were random numbers). If you were looking for the article written by Jones in 2011, it could take you 15 minutes to find it, as you cannot know where exactly the person had put it.

What do i want to say with that?
If you take care in naming the filenames in a precise and unique way, you will not loose oversight of your files and your supervisor/studentes/colleuges won't go crazy.

You can have a database of a thousand pdf files, looking for jones2011 is not difficult. coffeemakerInit.jpg is different from coffeemakerExploded.jpg but without opening the image file, you know what it contains. Do the same with tex-files and especially Labels. The minute you may decide what a good label is is a minute saved later in searching for the label (or the image), or saving 15 minutes in searching for a journal article ;-)

Keep it simple ;-)

Related Question