3

I am about to start writing my thesis, which will be a fairly long document.

I would like to organize the project in a clean and maintainable way using.

This is what I came up with, is it good, or is there a better way?

main.tex

\documentclass{report}
\usepackage{geometry}
\usepackage{lipsum}

\usepackage[backend=biber,style=ieee]{biblatex}
\addbibresource{bib.bib}

\usepackage[colorlinks]{hyperref}

\begin{document}

\input{titlepage/titlepage}

\tableofcontents

\input{1.a/a}
\input{2.b/b}

\printbibliography[heading=bibintoc]
\listoffigures
\addcontentsline{toc}{chapter}{List of Figures}
\listoftables
\addcontentsline{toc}{chapter}{List of Tables}

\appendix

\input{appendix/appendixA}
\input{appendix/appendixB}

\end{document}

titlepage.tex

\lipsum[1-2]

a.tex

\chapter{First}

\input{1.a/a1}
\input{1.a/a2}

a1.tex

\section{section}

\cite{knuth1984texbook}
\begin{figure}
    \caption{fig}
\end{figure}
\begin{table}[]
    \caption{tab}
\end{table}
\lipsum[1-2]

a2.tex

\section{section}

\lipsum[1-2]

b.tex

\chapter{Second}

\input{2.b/b1}
\input{2.b/b2}

b1.tex

\section{section}

\lipsum[1-2]

b2.tex

\section{section}

\lipsum[1-2]

appendixA.tex

\chapter*{Appendix A}
\addcontentsline{toc}{chapter}{Appendix A}

\lipsum[1-2]

appendixB.tex

\chapter*{Appendix B}
\addcontentsline{toc}{chapter}{Appendix B}

\lipsum[1-2]

bib.bib

@book{knuth1984texbook,
  title={The texbook},
  author={Knuth, Donald Ervin and Bibby, Duane},
  volume={15},
  year={1984},
  publisher={Addison-Wesley Reading}
}
8
  • 1
    This structure looks fine to me, provided it compiles this way: you didn't explicitly show your directory structure. // I'd like to draw your attention to package `subfiles', which allows you to compile any included file separately, e.g. for checking purposes ... if you can live with an "incorrect" numbering. Find an example here: tex.stackexchange.com/a/688740/245790 , and the package here: ctan.org/pkg/subfiles . Commented 21 hours ago
  • 1
    As an alternative approach you can apply the Refactoring approach to your (main) document: 1) Just start. 2) Review and spot parts, which you now can outsource (via include). 3) Check via compile(s). 4) Repeat. // This way your structure evolves as needed over time. You can start with a predefined structure, but you don't need to: it will kind of "come up by itself", with you as the driving force. // Here I outlined the process a bit more tex.stackexchange.com/a/725090/245790 , though it will look a bit different when splitting documents continuously. Commented 21 hours ago
  • 2
    I think your structure is right; there’s no problem with it at first glance. Commented 19 hours ago
  • 2
    It's not clear if this is your actual naming scheme, but try to avoid numbering your filenames. If you decide to swap introductionChap.tex with preliminariesChap.tex, that's not bad. If you decide to swap file1.a with file2.b, your main file will forever have things out of order. Commented 17 hours ago
  • 1
    @Teepeemm Yes. In retrospect, I agree. Commands within the main \input file that reference sibling files will have to be handled as well. I've offered an answer that should circumvent the problem. Commented 5 hours ago

2 Answers 2

6

Let me illustrate my comment/proposal about continuous refactoring.

1. Step - rebuilding your example - V1

Remember? Don't worry, start somewhere. Here: rebuilding what you posted for compiles. So it's a useful illustration of the process.

Preparations

I took the liberty to:

  • simplify your main.tex a little bit
  • put all your files and folders into folder V1 (see screenshot)
  • add more versions later, which match the numbers/versions in my Refactoring comment (in the main.tex versions)

Refactoring folders

You can use a similar versioning approach (copy folder Vn into V(n+1)), use Git etc. Versioning and backup are certainly on your todo- or done-lists.

So, this is what my main.tex looks like in V1, for a simplified start:

% ~~~ REFACTORING ~~~~~~~~~~~~~~~~~~~
%
%  1. getting copies to compile; introducing some formatting
%     activated 1.x and 2.x, dropped bibliography and appendices

\documentclass{report}
\usepackage{geometry}
\usepackage{lipsum}

%\usepackage[backend=biber,style=ieee]{biblatex}
%\addbibresource{bib.bib}

\usepackage[colorlinks]{hyperref}

% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\begin{document}
    \input{titlepage/titlepage}
    
    \tableofcontents
    
    \input{1.a/a}
    \input{2.b/b}
    %
    %\printbibliography[heading=bibintoc]
    %\listoffigures
    %\addcontentsline{toc}{chapter}{List of Figures}
    %\listoftables
    %\addcontentsline{toc}{chapter}{List of Tables}
    %
    %\appendix
    %
    %\input{appendix/appendixA}
    %\input{appendix/appendixB}

\end{document}

All needed .tex files are as you posted, within this folder structure:

+- main.tex
+- titlepage/
|   +- titlepage.tex
|- 1.a/
|   +- a.tex
|   +- a1.tex
|   +- a2.tex
|- 2.b/
|   +- b.tex
|   +- b1.tex
|   +- b2.tex

MY first refactoring-action

Preferences, tastes, perception etc. do vary from author to author. For me I'd already perceive your main-code as a bit crowded and hard to tell, what goes where. So I followed my addiction, to put some code-formatting, see above.

Now, after enough compiles, looking ahead, my first attention point was the titlepage-file ... it should be different in my view (still just for demo-purposes).

To emphasize, I line out the way of thinking, the self-improving process, and less the code itself.

2. Step - (first) adjustement of titlepage.tex - V2

Well, in main.tex nothing changed, besides my comment/protocol:

% ~~~ REFACTORING ~~~~~~~~~~~~~~~~~~~
%
%  1. getting copies to compile; introducing some formatting
%     activated 1.x and 2.x, dropped bibliography and appendices
%  2. refactoring titlepage

While in titlepage.tex I took the liberty to

  • introduce the titlepage-environement
  • add the folder structure (for fanciness) :
\begin{titlepage}
Fancy title:
\vspace{1cm}

    \lipsum[1-2]

\vspace{2cm}

Folders and files used:\bigskip
    \begin{verbatim}
+- main.tex
+- titlepage/
|   +- titlepage.tex
|- 1.a/
|   +- a.tex
|   +- a1.tex
|   +- a2.tex
|- 2.b/
|   +- b.tex
|   +- b1.tex
|   +- b2.tex
    \end{verbatim}
\end{titlepage}

There are millions other ways to design this one ...

titlepage

3. Step - enabling Chapter 1 to be compiled in two ways:

  1. within main.tex
  2. separately as a.tex

Required changes in main.tex

% ~~~ REFACTORING ~~~~~~~~~~~~~~~~~~~
% V#  changes
% --- -----------------------------------------------------------
%
%  1. getting copies to compile; introducing some formatting
%     activated 1.x and 2.x, dropped bibliography and appendices
%  2. refactoring titlepage
%  3. adding subfiles to chapter-1 file a.tex, so can be compiled alone

\documentclass{report}
\usepackage{subfiles}   % <<< NEW
\usepackage{geometry}
\usepackage{lipsum}

%\usepackage[backend=biber,style=ieee]{biblatex}
%\addbibresource{bib.bib}

\usepackage[colorlinks]{hyperref}

% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\begin{document}
    \input{titlepage/titlepage}
    
    \tableofcontents
    
%   \input{1.a/a}
    \subfile{1.a/a} % <<< CHANGED
    \input{2.b/b}
    %
    %\printbibliography[heading=bibintoc]
    %\listoffigures
    %\addcontentsline{toc}{chapter}{List of Figures}
    %\listoftables
    %\addcontentsline{toc}{chapter}{List of Tables}
    %
    %\appendix
    %
    %\input{appendix/appendixA}
    %\input{appendix/appendixB}

\end{document}

This lets you compile the whole thesis:

thesis

Chapter 1 as a pdf

a.tex:

\documentclass[../main]{subfiles}   % <<< new

\begin{document}        % <<< new
    \chapter{First}
    
    \input{1.a/a1}
    \input{1.a/a2}

\end{document}      % <<< new

Compiles into, which might be useful for separate inspection, review, crtics:

ch1

4. Process review and outlook

The 3 steps I showed here are already refactoring, like doing pottery on content:

  • start simple, with a goal in mind
  • gradually transform and check the outcome(s)

Wrt. your thesis I can think of a number of scenarios, like:

  • splitting some part of say a.1.tex into more subparts (growing, segmenting)
  • consolidating: perhaps later you feel, all b.tex* files should be in one b.tex (growning, merging)
  • you recognize, a separate tikz/ folder with standalone drawings is useful
  • later you do some finer segmentation on it, like tikz/ch1/, tikz/ch2/ etc.
  • and so on

Refactoring in itself has no limits. Above I showed impact on the segmentation into files and folders you presented. You can also do the same with content, i.e. your messages and findings. And as indicated you can refactor the folders. E.g. after some cycles you may have ended up like this:

+- main.tex
+  tikz/
|   +- ch1/
|       +- figure1.tex
|       +- figure2.tex
|   +- ch5/               % look ahead
|       +- figure1.tex
+- titlepage/
|   +- titlepage.tex
|- 1.a/
|   +- a.tex
|   +- a1.tex
|   +- a2.tex
|- 2.b/
|   +- b.tex
|   +- b1.tex
|   +- b2.tex

It's all no big deal: you move intentionally and controlled, like a mountain climber, from save-to-save / safe-to-safe :)

1
  • 1
    Your lesson here is very insightful, and its presentation is well-done. I also appreciate the notice on using \subfiles. I'd struggled with this need for other projects. Thanks!!! Commented 5 hours ago
2

One approach I have used is to collapse common inputs into commands. I rely on a top-level command, here called \theFolder. This defines the location to the files starting at the root (/) level nesting. As needed, I create commands to set, start, close, or do the content .tex files in \theFolder.

\documentclass[12pt]{report}

\newcommand*{\theFolder}{}

%% set the folder location
\newcommand*{\setFolder}[1]{%
    \renewcommand{\theFolder}{#1}
    }
%% start the folder contents
\newcommand{\startFolder}[1]{%
    \renewcommand{\theFolder}{#1}
    \input{\theFolder/toc}
    }
%% end the folder contents
\newcommand{\closeFolder}{%
    %% do what is needed to close
    }
%% do a folder contents
\newcommand{\doFolder}[2][toc]{%
    \setFolder{#2}  
    \input{\theFolder/#1}
    \closeFolder{}
    }

\begin{document}

\setFolder{01 Introduction}
\input{\theFolder/toc}

%% an example of one line to input synopsis.tex from a folder
%\doFolder[synopsis]{02 A Brief History of Time}

\end{document}

An example within the folder 01 Introduction might be as below.

toc.tex

\input{\theFolder/Hello World}
\input{\theFolder/GoodBye World}

Hello World.tex

Hello World!

Goodbye World.tex

\vfill
I wish only to say \textbf{Goodbye World}.

The advantages of this approach are

  • I am assured that all "folders" start, are added, and close in the same way within the document
  • My folder structure at the OS level can be named however I wish (sequentially in this example)
  • I can change the organization of where "folders" appear in the document either by reordering the sequence that they are called or by renaming the folders without needing to worry about also renaming files within the folders themselves

To the last point also, with a command \theFolder doing the administrative work, I retain the independence to configure so as to compile each Folder as its own self-standing "chapter", later plugging in the completed pieces to a larger work as desired.

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.