LaTeX-Templates/York-Thesis/C-Intro/intro.tex

%% intro.tex
%% Copyright 2022 A. Grau
%
% This work may be distributed and/or modified under the conditions of the LaTeX
% Project Public License, either version 1.3 of this license or (at your option)
% any later version, with the exception that distribution of Derived Work is not
% subject to the requirements of section 6.2.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX version
% 2005/12/01 or later.
%
% Inspired by an initial work from A. Pezzoni hosted on https://github.com/donbex/yorkthesis
%
% Current version: v1.0
% Changelog:
% 2022/07/08: Creation of this file serving as an example and documentation
%
% This work has the LPPL maintenance status `maintained`.
%
% The Current Maintainer of this work is A. Grau.
%
% This work consists of all the files listed in the README.md,
% and provides a copy of the original hosted on
% https://git.tigrau.ovh/Ambroise/LaTeX-Templates/York-Thesis.

\documentclass[../main]{subfiles}

%% TOOL: The following command can be used anywhere in the 
%% file. However, it's use in the preamble is fairly useless 
%% since the `else` part will never be run as preambles of 
%% subfiles are ignored since the inclusion in the main gets 
%% rid of all elements that are outside of the body enclosed 
%% in the `\begin{document} ... \end{document}`.
%% This is only here as an example.
\ifSubfilesClassLoaded{ % only do these next lines if compiling this file alone
		}{ % else condition, i.e. if we are compiling the main file
	}

% change title and author when compiling this document on its own
\title{Folder structure of the project} \author{} 
%\myexternaldocument{main} % for overleaf to get the cross references

\begin{document}
\ifSubfilesClassLoaded{ \maketitle \tableofcontents \listoftodos }{} % make title and todolist only if compiling by itself
\chapter{Introduction and documentation}
This serves as an introduction and a documentation to the file structure of this project and to the interaction between the different files present. 
This file hierarchy tree is as follows (only source files are shown, compiled files are hidden):
\begin{verbatim}
[folders are denoted by a *]
* Project    
    |-- main.tex                <- thesis tex file
    |-- yorkthesis.cls          <- the premade class
    |-- thesisoptions.sty       <- package holding the settings for the class
    |-- mypreamble.tex          <- packages and precious macros
    |--* C-Intro             
    |    !-- beg.tex            <- introductory chapter in its folder
    |--* C-Beg
    |    !-- beg.tex            <- another chapter
    |--* C-Middle
    |    !-- mid.tex            <- another chapter
    |--* C-End
    |    !-- end.tex            <- last chapter
    !--* Bibfiles
         |-- firstbib.bib       <- some bib file 
         !-- secondbib.bib      <- another bib file
\end{verbatim}
\todo{add bib files/graphics to examples}

As can be seen on the diagram, the principal file of the thesis is \texttt{main.tex} which lies at the root of the \texttt{Project} folder, together with the class used for the thesis' layout and some helper files (an additional file not listed in the tree for overleaf is described in section \ref{sec:overleaf}).
The actual content of the the thesis is split in subfiles lying in multiple sub-folders.
The next section will describe the role of each file and how they should be used, while section \ref{sec:subfiles} describes the relation to each other and the code they need to work together.

\section{Roles and use of the files}
\subsection{The thesis: \texttt{main.tex}}
Even though the content of this file appears to be very small, this is the file that has to be compiled in order to obtain the full thesis. The motto of the \texttt{main} is ``Divide and conquer'', by means of delegating big tasks to other files and elements and bringing them all together in one place. 
This file calls the \texttt{yorkthesis} class to create the document with only basic options, and then delegates the handling of its options to \texttt{thesisoptions.sty}, with the exception of the title page values which are to be filled in the main document.

The overall structure of the thesis is described in the \verb|\begin{document} ... \end{document}| by first creating the first pages of the thesis corresponding to the title page, abstract, table of contents (and other list of elements), acknowledgment and author's declaration, before calling onto subfiles to fill in the body of the document (selecting the order in which to include the work), and finishing by including the appendices and the bibliography. 

\begin{rem}
The subfiles are called in the example by relative path, but there is a possibility to ignore that and simply use file names by uncommenting a section in the preamble. See the details in section \ref{sec:preamble-file}. 
\end{rem}

\subsection{The class elements: \texttt{yorkthesis.cls} and \texttt{thesisoptions.tex}}
The \texttt{yorkthesis} class is built upon the \texttt{memoir} class and apart from forcing some options by default (such as setting A4), a title page layout is defined to follow the university regulations, giving access to the appropriate commands to do so. 
Additionally, it creates a header for all pages, and gives access to new commands to set the page layout.
In order to use it, you need to call \verb|\documentclass[<options>]{yorkthesis}|, where \texttt{<options>} is a list of options compatible with the \texttt{memoir} class that will be passed to it.
Currently the only option passed is the \texttt{draft} option, which has multiple implications (details in section \ref{sec:draft-option}).
In order to create the title page the following must be called in the \texttt{main.tex}: 
\begin{itemize}
\item \verb|\title{..}|: [required] title of the thesis;
\item \verb|\subtitle{..}|: [optional] subtitle (if appropriate);
\item \verb|\author{..}|: [required] your name;
\item \verb|\department{..}|: [required] department name, according to the list in the ``depositing your thesis'' section of the \href{https://www.york.ac.uk/research/graduate-school/progression/thesis/submit/}{GRS website};
\item \verb|\qualification{..}|: [required] name of the qualification for which this work is submitted (PhD, MSc,...);
\item \verb|\submitdate{..}|: [optional] the month and year of the first submission (if not included, will default to the month and year at compilation).
\end{itemize}
The other options for the class are set in the file \verb|thesisoptions.tex| and concern the following elements: fonts, margins, chapter style, sections style, list spacing and draft version options.

\subsubsection{Margins} 
It is strongly recommended to use the commands provided to set the margins of the document instead of trying to deal with it by calling the \verb|geometry| package (even though it should work too, I cannot insure that the class will react well to that). 
Margins are set by pair of opposite edges, so that the spine and foredge margins will be set in one command, and the upper and lower margins by a second one. 
The sides of reference when setting the margins are the spine (for the binding) and the upper one. 

The horizontal margins can be set either by giving one length, two lengths or a length and a ratio as follows:
\begin{itemize}
    \item \verb|\horizontalmarginsvalue{x}|: [\verb|x| is a length with its unit] sets the spine and foredge margins to the value of \verb|x|;
    \item \verb|\horizontalmarginsvalue[y]{x}|: [\verb|x| and \verb|y| are lengths with their unit] sets the spine margin to the value of \verb|x| and the foredge margin to the value of \verb|y|;
    \item \verb|\horizontalmarginsratio[r]{x}|: [\verb|x| is a length with its unit, \verb|r| is a ratio] sets spine margin to the value of \verb|x| and the foredge margin to the value of $\verb|x|*\verb|r|$;
    \item (\verb|\horizontalmarginsratio{x}| is equivalent to  \verb|\horizontalmarginsratio[1]{x}| and \verb|\horizontalmarginsvalue{x}|).
\end{itemize}
The corresponding commands \verb|\verticalmarginsvalue| and \verb|\verticalmarginsratio| are used to set the upper and lower margins. 

\begin{rem} 
If no command is called for either the horizontal or the vertical margins, the default value for these will be used, which is set to \verb|3cm| for the spine and foredge margins, and to \verb|4cm| for the upper and lower margins, giving the inside frame for the content a similar ratio width/height to the original A4 page. 
\end{rem}

\begin{rem} 
Only one of the horizontal commands and one of the vertical ones should be called to insure an appropriate behaviour. If both \verb|\horizontalmarginsvalue| and \verb|\horizontalmarginsratio| are called, the spine value will be set to the last of the two commands called, whereas the foredge value will be set from the resulting operation of \verb|\horizontalmarginsvalue{x}| (I just didn't want to make another nested condition, so this is what happens when things go wrong). 
\end{rem}

\subsubsection{Chapter and sections style}
The general layout of the sections is set by using the \verb|\headstyles{..}| command, which gives a special format to the headers of each of the \emph{Chapter, Section, Subsection, Subsubsection, Paragraph} and \emph{Subparagraph} subdivisions. 
Examples can be found in the \verb|memoir| documentation in section 6.9. 
It is possible to override such definitions by calling the \verb|\setSheadstyle{..}| command (where \verb|S| is one of the subdivision shortnames), as can be seen in the \verb|thesisoptions.tex| example file.
Additionally, more examples of chapter header exists (see appendix B of the \verb|memoir| documentation), and they can be called upon by using the \verb|\chapterstyle{..}| command. 
Since this only define the style for a chapter, it is necessary to call it after the \verb|\headstyle{..}| command if you do not want this setting to be overridden. 
You can also take the general structure of a chapter style and only redefine the style of the text for the chapter title and number as is done with the \verb|\renewcommand*{\chaptitlefont}{..}| in the option file for this example.

\subsubsection{The \texttt{draft} option}\label{sec:draft-option}
As mentioned earlier, this \texttt{draft} option is given when calling the class in the \texttt{main.tex} document, but is used to determine the behaviour of some other packages. 
This option also allows to take actions conditionally on if it is present or not. 
This is what the conditional operations located at the end of the \texttt{thesisoptions.tex} file are about:
\begin{verbatim}
    \ifdraftdoc
      %% Some actions occurring when `draft` is set
    \else
      %% Other actions if `draft` is not set
    \fi
\end{verbatim}
which is currently used to make a watermark on the front page in draft mode, and call the \texttt{microtype} package otherwise.

Additionally, this example calls the \texttt{hyperref} package with the \texttt{final} option to override the fact that hyperlinks are not created in draft mode; whilst the \texttt{todonotes} package is called with the \texttt{obeyDraft} option which means that the todo notes on the side will only appear if the \texttt{draft} option is set for the class, and they will be disabled otherwise.

\subsection{The personal stuff: \texttt{mypreamble.tex}}\label{sec:preamble-file}
Apart from the important bit at the top of this file, its content is globally up to you. You should put in there all the packages and macros you will want or need to use. 

Since I have decided to use the subfile package to simplify my life (more on that in section \ref{sec:subfiles}), the first thing to do is to include the packages needed to work with that.
We first need to add the \texttt{xr-hyper} package which will take care of cross references and their correct behaviour with the \texttt{hyperref} package, and then add the \texttt{subfiles} package. 
In order to use the references between different files we need an additional command that will make them available to the subfiles (the main file will have them anyway).
After these few inclusions there are two sets of commands that are commented out and serve different purposes.

The first one is as follows:
\begin{verbatim}
    \makeatletter
    \ def\input@path{ {dir1/}{dir2/} } 
    \makeatother
\end{verbatim}
which allows to use file names in inclusion, instead of relative paths as long as all the folders of the project are added to this list by respecting the syntax. It is currently commented out since this slows down the compilation time a lot and provide only small benefit. But if you are lazy, then this can be helpful.
The second part concerns the use of \emph{Overleaf}, as additional commands are needed for cross-referencing purposes (see section \ref{sec:overleaf} for the details). Only uncomment these lines if you are using that website to write your thesis.

On top of the usual packages that relates to maths, some additional ones are listed in the example such as the \texttt{hyperref} package which creates hyperlinks into the outputed pdf in order to jump between sections, and the \texttt{todonotes} which allows you to create sticker notes in the margins about what needs to be done as well as giving you a list of these after the table of content by calling \verb|\listoftodos| (check \href{http://mirrors.ctan.org/macros/latex/contrib/todonotes/todonotes.pdf}{its documentation} for more info).
Your bibilography needs to be setup somewhere, so if you are using \texttt{.bib} files, this is the right place to include the package with all the options you would like, and then to add the files needed as a ressource, so that referencing a book like Knuth's TeXbook \cite{texbook} becomes very easy. 
Notice the invocation with the \verb|\subfix{..}| command (or the relative path in the Overleaf project as the subfix didn't seem to work there unfortunately...).

The \texttt{mypreamble} file is also the place to create the styling of your theorems, definitions, remarks and other scholia. 

Lastly, all your macros for new commands should go there, so that they are all in one place and available to use everywhere.

\begin{rem}[Technical implementation]
The choice has been made to make to have this document as a plain \texttt{.tex} file instead of making it a package file (as \texttt{.sty}). This is a personal choice to avoid any interpretation of the commands listed there and to make the packages placed there too. 
\end{rem}

\subsection{The other files}
All the other files of the structure correspond to the actual content of the thesis separated between chapters.
These are pretty standalone files that one would write in a classical \texttt{article} class style, with only a few elements that will be covered in the following section.

\section{Using subfiles}\label{sec:subfiles}
The reason why I chose to use the \texttt{subfiles} package is that it allows you to include files into the main document, while keeping the possibility to compile them separately. 
That way you don't have to move back to the main file every time you want to compile something, you can compile only the desired section instead of the whole document, and you don't need to delete all the stuff outside of the \verb|\begin{document}..\end{document}| in the file storing your chapter content in order to make it compile from the main document.

How to do it is pretty straightforward and can be found on p.2--3 of the \href{https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/contrib/subfiles/subfiles.pdf}{package documentation}. 
In short, the subfiles, are using a special document class with the path to the main file by calling upon \verb| \documentclass[../main]{subfiles}|. 
This does most of the job, since this will allow the file to compile by using all the preamble of the main file. In turn, when in \texttt{main.tex} the command \verb|\subfile{..}| is invoked, it will only pick the content located between the \verb|\begin{document}| and \verb|\end{document}| commands. 
If you want to run some actions depending on if the file is included or if it is compiled by itself there is a command for it that you can include in the body of the document:
\begin{verbatim}
    \ifSubfilesClassLoaded{ 
        % actions to do if compiling this file alone
    	}{ 
        % else condition, i.e. if we are compiling the main file
     }
\end{verbatim}
which can be used to only create a local titlepage, toc or bibliography which should not appear when compiling the main file (you can check the difference between the result of the compilation of the \texttt{intro.tex} file on its own compared to when it is integrated into the main).

\subsection{Including graphics}
In order to make sure that the path will not get broken when compiling the main file, you might need to use the \verb|\subfix{..}| command around the filename so that the \texttt{subfiles} class can deal with that problem for us by doing the following: \verb|\includegraphics[<options>]{\subfix{image}}|.

\subsection{Cross-referencing}
Most of the job of cross referencing is done by the \texttt{xr-hyper} package, but we need to help it a bit. This is the reason of the presence of \verb|\externaldocument{\subfix{main}}| in the preamble. 
After that, when you compile one of the subfile, it will always read the auxiliary file generated by the \texttt{main} document to find the references and to include the appropriate number in the right places. 
For example, if we create an equation here that we will reference in Chapter \ref{sec:Beg}:
\begin{equation}\label{eq:thull}
\Omega(I) = \{ (\lambda, \rho)\in \Lambda(I)\times P(I) \mid s(\lambda t) = (s\rho) t \quad \forall s,t\in S\},
\end{equation}
(which denotes the translational hull of a subsemigroup $I\subseteq S$), we already have the labels appropriately introduced.

\subsubsection{Using the auxiliary file in a \LaTeX\ editor}
In order for the cross referencing to work in subfiles, you first need to compile the \texttt{main.tex} file. 
This will create the \texttt{main.aux} file which stores all the labels and associated values. 
Then compiling any subfile will use that auxiliary file and should give you access to all these references as expected.

\subsubsection{Using cross-ref in overleaf}\label{sec:overleaf}

If you intend to use Overleaf, some additional steps can be needed as described in the \href{https://www.overleaf.com/learn/how-to/Cross_referencing_with_the_xr_package_in_Overleaf}{documentation on the overleaf website}.
This is due to the fact that we cannot directly access the \texttt{.aux} files which contains the references we need as they are only stored in the cache and not in the file system. In order to do that, there are three necessary steps to accomplish this (see ): 
\begin{enumerate}
    \item in the file \texttt{mypreamble.tex} you need to uncomment the line that relates to the overleaf cross-referencing at the top of the file;
    \item a new file named \texttt{latexmkrc} needs to be created containing the following code:
    \begin{verbatim}
        add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' );
        sub makeexternaldocument {
            if (!($root_filename eq $_[0]))
            {
                system( "latexmk -cd -pdf \"$_[0]\"" );
            }
        }
    \end{verbatim}
    which will force the creation of the auxiliary file of a dependency file called upon;
    \item add the command \verb|\myexternaldocument{main}| to the preamble of each subfile, which will force the availability of \texttt{main.aux}.
\end{enumerate}

This process will allow the cross-referencing to happen, but will make the compilation time much slower, because it will require the compilation of the \texttt{main} file every time, which in turns ask all the subfiles to be compiled. If this is ok for you, then you can leave the settings as such and never touch this again.

However, there are ways to speed up the compilation process by using the fact that Overleaf keep the compiled files available in the cache.
To do this, simply unset all of the elements listed above (so keeping the lines commented out, and not creating the \texttt{latexmkrc} file). Then, compile the \texttt{main.tex} once, which will set the \texttt{.aux} file in the cache, and compile the subfile as usual. 
You should be able to keep this cache set for a while, but remember that your browser might clean it at any point without you knowing it, so you would need to recompile the main for it to be working again.
It might also happen that the first compilations of the subfile produce errors but it should resolves itself fairly quickly.

\begin{rem}
In the log you will notice that Overleaf warns you about labels being defined multiple times. This is normal because it is reading the labels set both in the \texttt{main.aux} file as well as those in the auxiliary file of the current file you are compiling. 
For this reason, you need to be extra careful not to use the same name for labels. 
A way to check is to use the autofill of Overleaf to try a \verb|\ref{..}| with the label you are going to set, and if it is not suggested, then you should be fine to set it with \verb|\label{..}|.
\end{rem}

\section{Accessibility}
\todo[caption={Create the accessibility section}, inline]{Find the tools necessary to allow graphics and tables to be accessible.}
\end{document}