% !TeX encoding = UTF-8
% !TeX program = pdflatex
% !TeX spellcheck = en_US


\documentclass[a5paper,11pt]{article}

\usepackage[scale=0.85, footskip=0.8cm,heightrounded]{geometry}
\usepackage[T1]{fontenc}
\usepackage[scaled=1]{newtxtext}
\usepackage{textcomp}
\usepackage{amsmath}
\usepackage[varg,cmintegrals,cmbraces]{newtxmath}
\usepackage{microtype}
\usepackage{graphicx}
\usepackage{color}
\definecolor{gray}{gray}{0.4}
\definecolor{sfondoblu}{rgb}{0.94,0.97,1}
\usepackage{curve2e}
\usepackage{listings}
\lstset{language=[LaTeX]TeX,
	basicstyle=\scriptsize\ttfamily,
	keywordstyle=\color{blue}\bfseries,
	commentstyle=\color{gray},
	backgroundcolor=\color{sfondoblu},
	frameround=tttt,
	frame=tlrb,
	escapechar=|,
	morekeywords={submitdate, cycle,  courseorganizer, AcademicYear, copyyear, Faculty, course, PhDorganizer, IDnumber, advisor, coadvisor, examdate, examiner, authoremail, frontmatter, mainmatter, maketitle, tableofcontents, chapter, appendix, backmatter, dedication, selectlanguage, tutor, tutorcoord, thesistype, customdirectorlabel, schoolname, schooladdress, schoolwebsite, schoolprincipal, phantomsection, director, hypersetup},
	columns=flexible
}

\definecolor{sapred}{rgb}{0.5098039,0.1411765,0.2}

\usepackage{multicol}

% eliminate dots in the table of contents
\makeatletter
\renewcommand{\@dotsep}{10000}
\makeatother

\usepackage[bookmarks=false,hyperfootnotes=false]{hyperref}
\hypersetup{
			colorlinks=true,
			linkcolor=blue,
			anchorcolor=blue,
			citecolor=blue,
			urlcolor=blue,
			pdftitle={sapthesis.cls documentation},
			pdfauthor={Francesco Biccari}
}

\newcommand{\bs}{\textbackslash}
\newcommand{\sq}{\textquotesingle}

\author{\small Francesco Biccari\thanks{\href{mailto:biccari@gmail.com}{biccari@gmail.com}}}
\title{\small Documentation of the \LaTeX\ class\\
		\Large \textbf{\texttt{sapthesis.cls}}\\
		\small \vspace{0.2cm} Version 5.1, 2022-07-04
}
\date{}

% degree
  \providecommand{\degree}{\mbox{\textdegree}}
  \providecommand{\g}{\degree}

  % gradi Celsius
  \providecommand{\celsius}{\ensuremath{\textrm{\upshape\textdegree}\kern-\scriptspace\mathrm{C}}}
  \providecommand{\C}{\celsius}
  
  % Angstrom
  \providecommand{\angstrom}{\mbox{\AA}}
  \providecommand{\A}{\angstrom}
  
  % micro
  \providecommand{\micro}{\mbox{\textmu}}
  
  % Ohm
  \providecommand{\ohm}{\ensuremath{\mbox{\textohm}}}
  
  % Napier's number
  \providecommand{\eu}{\ensuremath{\mathrm{e}}}
  
  % imaginary unit
  \providecommand{\iu}{\ensuremath{\mathrm{i}}}
  
  % roman subscript
  \providecommand*{\rb}[1]{\ensuremath{_\mathrm{#1}}}
  
  % roman superscript
  \providecommand*{\rp}[1]{\ensuremath{^\mathrm{#1}}}

  % differential (only math)
  \providecommand{\di}{\mathop{}\!d}
  
  % derivative and partial derivative (only math)
  \providecommand*{\der}[3][]{\frac{d^{#1}#2}{d #3^{#1}}}
  \providecommand*{\pder}[3][]{%
    \frac{\partial^{#1}#2}{\partial #3^{#1}}%
  }

  % measurement unit
  \providecommand*{\un}[1]{\ensuremath{\mathrm{\,#1}}}
  
  
\begin{document}
\maketitle

\begin{abstract}\noindent
This document describes how to use \texttt{sapthesis.cls}, a \LaTeX\ document class for the typesetting of the theses of the ``Sapienza University of Rome''. The official web page of \textsf{sapthesis} is\\
{\footnotesize\url{http://biccari.altervista.org/c/informatica/latex/sapthesis.php}}.
\end{abstract}

\setcounter{tocdepth}{2}
\renewcommand{\columnseprule}{0.4pt}
\setlength{\columnsep}{1.5cm}

\addtocontents{toc}{\protect\begin{multicols}{2}}
{\small
\tableofcontents}

\clearpage

\section{Introduction}

After several years in my faculty I noticed that usually students spend a lot of time to refine the aesthetic aspect of their \LaTeX\ documents instead of focusing on the content.
This is against the philosophy of \LaTeX, which was created to relieve the writer from the typesetter's work.
Apart from the time spent, the resulting documents are obviously all different from each other and good aesthetic results are not always achieved.
This has a negative impact both on the student's work and on the university.
Moreover in 2007 the Sapienza university changed completely its
logo and a lot of strict graphic rules for official documents were introduced.%
\footnote{A thesis is not an official document and therefore these guidelines can not be applied (private communication with Laura Gobbo, Ufficio Stampa e Comunicazione Sapienza  Universit\`a di Roma).
However some Microsoft Word templates, with a completely different style, are provided.
To give a look to the new Sapienza style see 
\href{https://www.uniroma1.it/it/pagina/marchio-identita-visiva-e-sistema-grafico}{Marchio, identità visiva e sistema grafico} and \href{https://www.uniroma1.it/it/pagina/impaginazione-della-tesi-e-logo}{Template tesi}.}

For these reasons I thought that a \LaTeX\ class for the theses of my 
university would have been a good idea.
\textsf{Sapthesis} is the result of my work.
Its official web page is
{\footnotesize\url{http://biccari.altervista.org/c/informatica/latex/sapthesis.php}}.
\textsf{Sapthesis} is released under the terms of the latest version of the 
\href{http://www.latex-project.org/lppl/}{\LaTeX\ Project Public License}.

To give a look to a document composed by \textsf{sapthesis} class, compile one of the several examples reported in App.\,\ref{sec:examples}.

I would like to thank the Italian \TeX\ user group (\href{http://www.guitex.org/}{GuIT}) for the help provided, in particular Enrico Gregorio and Claudio Beccari. I would also thank all the users who reported bugs and suggestions.

\section[Requirements\\ and installation]{Requirements and installation}
\label{requirements_installation}

The simplest way to install \textsf{sapthesis} is by the package manager of 
your \TeX\ distribution (\TeX\ Live or MiK\TeX). For manual installation see 
the \texttt{README} file. 

The \textsf{sapthesis} package provides: the 
\texttt{sapthesis.cls} class file; the documentation 
\texttt{sapthesis-doc.pdf} (this file) and its source code; the logo of 
Sapienza university; an English Bib\TeX\ style, called 
\texttt{sapthesis.bst}, which can be used, obviously, only if you use the 
Bib\TeX\ way to compose your bibliography and if your thesis is written in 
English (its usage is not mandatory).


\textsf{Sapthesis} explicitely loads the packages \textsf{xkeyval}, \textsf{etoolbox}, \textsf{geometry}, \textsf{ifxetex}, \textsf{xltxtra}, \textsf{fontenc}, \textsf{textcomp}, \textsf{lmodern}, \textsf{caption}, \textsf{graphicx}, \textsf{color}, \textsf{booktabs}, \textsf{amsmath}, \textsf{fancyhdr}.
Do \textbf{not} include these packages in the preamble of your document!





\section{Usage}

A \LaTeX\ document based on \textsf{sapthesis} can be compiled only by the commands
\texttt{pdflatex} and \texttt{xelatex}. In this manual only \texttt{pdflatex} will be considered.


As usual, in order to use this class, you need to call it by
\begin{lstlisting}
\documentclass[|\textit{\texttt{options}}|]{sapthesis}
\end{lstlisting}
You have to specify the class options for your case (see Sec.~\ref{class_options}). Then you have to provide some fundamental information (title, author, etc\ldots) by specific commands in the preamble (see Sec.~\ref{commands_titlepage}). Finally, remember to follow a source code structure similar to those of the examples given in App.~\ref{sec:examples}.
Especially the usage of the commands \texttt{\bs frontmatter}, \texttt{\bs mainmatter} and \texttt{\bs backmatter} is mandatory, otherwise the page style of the document will be wrong!

This class supports, at the moment, two languages: Italian and English. The choice of the language is automatic according to the \texttt{babel} package settings. If babel is not loaded, english is used. See below to override the automatic choice. 

\subsection{Class options}
\label{class_options}
The following options can be passed to the \texttt{\bs documentclass} command.

\begin{description}

\item[\texttt{a4paper/a5paper/b5paper}] Choose one of these three options to set the paper format. The default value is \texttt{a4paper}.
\item[\texttt{layout=\textsl{a5paper/b5paper}}] If, for some reason, it is impossible to print on A5 or B5 directly (printer not supporting these formats, paper not available, ...), it is possible to specify the A5 or B5 layout, maintaining the A4 paper format: some cropmarks will be printed to show where the page should be cut.
\item[\texttt{draft}] The usual \texttt{draft} option of the \LaTeX\ Standard Classes.
\item[\texttt{oneside}] The usual \texttt{oneside} option of the \LaTeX\ Standard Classes.
\item[\texttt{twoside}] (default) The usual \texttt{twoside} option of the \LaTeX\ Standard Classes.

\item[\texttt{binding=\textsl{length}}] (zero default binding)
The value of this option is an offset of the text column.
It is useful to take into account the margin for the binding (ask to your bookbinder for information).
\item[\texttt{noexaminfo}] Suppress all the final exam informations. Indeed, by default, \textsf{Sapthesis} shows some information about the final thesis discussion on the back of the title page. By default it shows the phrase ``Thesis not yet defended''. Otherwise, as explained later, giving the commands 
\texttt{\bs examdate\{\dots\}} and \texttt{\bs examiner\{\dots\}} the date and
the examiners list are shown.
\item[\texttt{nodefaultfont}] Avoid the loading of packages \textsf{fontenc}, \textsf{textcomp} and \textsf{lmodern}.
\item[\texttt{romandiff}] See App.~\ref{sec:usefulcommands}.
\item[\texttt{italian} / \texttt{english}] Explicitly declare the language of 
the title page. Useful to write the title page in a language 
and the thesis in a different language.
\end{description}

\subsection[Commands for the\\ title page]{Commands for the title page}
\label{commands_titlepage}

As usual, the title page is generated by the \texttt{\bs maketitle} command.
It needs some information that you can supply by the following commands
in the preamble.
\begin{description}
\item[\texttt{\bs title\{\dots\}}] Mandatory. Title of the thesis. The text is justified, however it is recommended to insert manual linebreaks (\bs\bs) to compose a beautiful title.

\item[\texttt{\bs subtitle\{\dots\}}] Optional. Subtitle (try to avoid a subtitle). If both\\ \texttt{\bs subtitle\{\dots\}} and \texttt{\bs alttitle\{\dots\}} are used, the latter is discarded. 

\item[\texttt{\bs alttitle\{\dots\}}] Optional. Alternative title (try to avoid an alternative title). This command, together with the \texttt{\bs title\{\dots\}} command, is typically used to insert in the frontispiece the title in another language. If both \texttt{\bs subtitle\{\dots\}} and \texttt{\bs alttitle\{\dots\}} are used, the latter is discarded.

\item[\texttt{\bs author\{\dots\}}] Mandatory. Author (student's name).

\item[\texttt{\bs IDnumber\{\dots\}}] Mandatory. ID number (\textit{matricola} in Italian).

\item[\texttt{\bs course\{\dots\}}] Mandatory. Use the official Italian name of the course.
Even though your thesis is in English you should write here the official name of the course, which normally is in Italian.

\item[\texttt{\bs cycle\{\dots\}}] Mandatory only for PhD's. Use the form: \texttt{\bs cycle\{XXII\}}

\item[\texttt{\bs courseorganizer\{\dots\}}] Mandatory. Course organizer (for example Scuola di Scienze Matematiche Fisiche e Naturali). Use \bs\bs\ to properly break the lines.

\item[\texttt{\bs AcademicYear\{\dots\}}] Academic Year.

\item[\texttt{\bs advisor\{\dots\}}] You must specify at least one advisor.
If you have more than one advisor, put several advisor commands in the correct order:\\
\texttt{\bs advisor\{Prof.~Pippo\}} \texttt{\bs advisor\{Dr.~Pluto\}}

\item[\texttt{\bs customadvisorlabel\{\dots\}}] Optional. Specify the label for advisors. It can be used, for example, to print ``Relatrice'' instead of ``Relatore''.

\item[\texttt{\bs coadvisor\{\dots\}}] Optional. Co-advisors of the thesis. 
Same syntax of the \texttt{\bs advisor} command.

\item[\texttt{\bs customcoadvisorlabel\{\dots\}}] Optional. Specify the label for co-advisors. It can be used to print ``external advisor'' or similar labels.

\item[\texttt{\bs director\{\dots\}}] Optional. Director of the PhD program, head of the Specialization degree, or similar. Same syntax of the \texttt{\bs advisor} command. Avoid its usage if possible.

\item[\texttt{\bs customdirectorlabel\{\dots\}}] Optional. Specify the label for director.

\end{description}

Together with the title page, \textsf{Sapthesis} will also compose an information page just after the title page. See also the \texttt{\bs noexaminfo} class option described in a previous section. Here follow the necessary commands to compose this page.
\begin{description}
\item[\texttt{\bs examdate\{\dots\}}] Optional. Date of the final exam.\\
Example: \texttt{\bs examdate\{16 February 2020\}}.

\item[\texttt{\bs examiner[\dots]\{\dots\}}] Optional. Specifies the members of the
board of examiners of the final exam. Usage similar to \texttt{\bs advisor} command. The optional argument can be used to specify the role of that examiner in the commission.

\item[\texttt{\bs thesistype\{\dots\}}] Optional. Type of thesis (usually PhD thesis, Master thesis, and so on). 

\item[\texttt{\bs ISBN\{\dots\}}] Optional. ISBN

\item[\texttt{\bs copyyear\{\dots\}}] Mandatory. Copyright year (usually the 
graduation year).

\item[\texttt{\bs copyrightstatement\{\dots\}}] Optional. Specify a copyright statement that will be printed in place of the default one.

\item[\texttt{\bs versiondate\{\dots\}}] Optional. Date version of the thesis.

\item[\texttt{\bs website\{\dots\}}] Optional. Thesis website. Automatically 
hyper-linked if \textsf{hyperref} package is loaded.

\item[\texttt{\bs authoremail\{\dots\}}] Mandatory. Email of the thesis author.
It is automatically hyper-linked if \textsf{hyperref} package is loaded.

\item[\texttt{\bs reviewer\{\dots\}}] Optional. Reviewers of the thesis (typically this applies to PhD theses only). Same syntax of the \texttt{\bs advisor} command. The list of the reviewer is preceded by the a text which can be specified by the \texttt{\bs reviewerlabel\{\dots\}} command.

\item[\texttt{\bs extrainfo\{\dots\}}] Optional. This command can be used to insert an arbitraly long text at the top of the back of the titlepage. For example, in the past it was used to provide some information for TFA theses (tutor, tutor coordinator, principal of the school, name of the school, and so on). 


\end{description}



\subsection[Other commands\\ and environments]{Other commands and environments}

\begin{description}

\item[\texttt{\bs dedication\{\dots\}}] A command to compose the dedication.

\item[\texttt{abstract}] An environment to compose the abstract of your document. This environment has an optional parameter to choose the title of the abstract section.
If you use a language for the abstract different from that of the thesis, consider the \texttt{\bs selectlanguage\{\dots\}} command provided by the \texttt{babel} package.

\item[\texttt{acknowledgments}] An environment to compose the acknowledgments of your document. This environment has an optional parameter to choose the title of the acknowledgments section.
If you use a language for the acknowledgments different from that of the thesis, consider the \texttt{\bs selectlanguage\{\dots\}} command provided by the \texttt{babel} package.


\end{description}
\textcolor{sapred}{%
The \texttt{sapthesis} class defines also the color \texttt{sapred} which is the \emph{Sapienza red}: RGB(130,36,51). Example of usage: \texttt{\bs textcolor\{sapred\}\{blah blah\}}}


\section{Recommendations}

\begin{itemize}

\item Do \textbf{not} change the default layout.

\item Do \textbf{not} load the packages already loaded by \textsf{sapthesis} (see Sec.~\ref{requirements_installation}).

\item As you already should know, \LaTeX\ can process only documents
in pure ASCII. If you want to insert \emph{directly} other characters, not included in the 128 ASCII characters (for example accented letters), you have to use a particular text encoding for your source file. Then you have to ``tell'' to \LaTeX\ which encoding you have chosen by the packages \texttt{inputenc}. It is always recommended to use UTF-8 character encoding and specify this choice also by the \emph{magic lines} at the beginning of the source code (see the examples in App.~\ref{sec:examples}).

\item Respect the following thesis structure:

\begin{itemize}
\item Title page (\texttt{\bs maketitle} command)
\item Dedication (\texttt{\bs dedication} command)
\item Abstract (\texttt{abstract} environment)
\item Acknowledgements (\texttt{acknowledgments} environment)
\item Table of contents (\texttt{\bs tableofcontens} command)
\item Chapters
\item Appendices
\item Bibliography
\end{itemize}

\item It is recommended to avoid or limit the acknowledgments in a thesis, it 
is not very professional. The dedication should be enough.

\item Do not put any preface in your thesis. The preface should be written only by an eminent expert in the field to comment exceptionally important results of the student.

\item Usually tables and figures are centered. Remember that, according to the typographic rules, the table captions should be placed \textbf{above} the table, whereas the figure caption should be placed \textbf{below} the figure.

\item If the figure has a small width, it is possible to put the figure caption
aside the figure using the \texttt{sidecap} package (not preloaded by \textsf{sapthesis}).

\item Avoid the use of colors unless really necessary. Remember that the figures should be readable even if they are printed in gray scale!

\item Subscripts and superscripts should be in italic if they represent variable quantities, whereas should be in roman if they are simply labels.

\item The name of operators should be typed in roman. Example: use $\sin$ (\texttt{\$\bs sin\$}) instead of $sin$ (\texttt{\$sin\$}).

\item The margin notes are rarely used in scientific documents and should \textbf{not} be used in a scientific thesis.

\item Do not divide the bibliography per chapter unless it is \textbf{really} necessary.
This will save you from wasting a lot of time to prepare your \LaTeX\ source code.
Order your bibliography alphabetically according to the
first author surname: this order is very useful, contrary to the other typical order, the citation order.

\end{itemize}

\clearpage
\section{Other useful commands}
\label{sec:usefulcommands}

\textsf{Sapthesis} provides several useful commands for scientific texts.

\begin{description}
\item[\texttt{\bs eu}] Napier's number, $\mathrm{e}$,  in roman.

\item[\texttt{\bs iu}] Imaginary unit, $\mathrm{i}$,  in roman.

\item[\texttt{\bs der\{\dots\}\{\dots\}}] Derivative. The first argument represents the function to derive while the second the variables separated by commas. The differential symbol is automatically inserted. Examples:
\texttt{\bs der\{f\}\{x\}}, \texttt{\bs der\{f\}\{x,y\}}, \texttt{\bs der\{f\}\{*\{3\}\{x\}\}}, 
\texttt{\bs der\{f\}\{*\{2\}\{x\},*\{2\}\{y\},z\}}.

\item[\texttt{\bs pder\{\dots\}\{\dots\}}] Partial derivative. Same syntax of the \texttt{\bs der} command.

\item[\texttt{\bs rb\{\dots\}}] Roman suBscript

\item[\texttt{\bs rp\{\dots\}}] Roman suPerscript

\item[\texttt{\bs tb\{\dots\}}] Text suBscript

\item[\texttt{\bs tp\{\dots\}}] Text suPerscript

\item[\texttt{\bs un\{\dots\}}] Useful command to typeset measurement units in the correct way, e.g. \texttt{25\bs un\{m/s\}},
\texttt{13\bs un\{kg\bs ,cm\^{}\{-3\}\}}. It can be used both inside or outside the math environment.
For heavy usage of measurement units and to insert numbers in the form
\texttt{1.4e-5}, the package \textsf{siunitx} is recommended.

\item[\texttt{\bs g}] Shortcut for the \texttt{\bs degree} command. Example: \texttt{45\bs g} produces 45\g.

\item[\texttt{\bs C}] Shortcut for the \texttt{\bs celsius} command. Example: \texttt{37\bs ,\bs C} produces 37\,\C. (Not available in math mode compiling with \texttt{xelatex}).

\item[\texttt{\bs A}] Angstrom. Example: \texttt{10\bs ,\bs A} produces 10\,\A.

\item[\texttt{\bs micro}] Micro prefix. Example: \texttt{7\bs ,\bs micro m} produces 7\,\micro m.

\item[\texttt{\bs ohm}] Ohm. Example: \texttt{100\bs ,\bs ohm} produces 100\,\ohm.

\item[\texttt{\bs di}] Differential symbol with automatic spacing. Example: 
\texttt{\$\bs int x \bs di x\$} produces $\int x \di x$. If you prefer the differential symbol in roman ($\mathrm{d}$), you can use the \texttt{romandiff} document class option.

\item[\texttt{\bs x}] Shortcut for the \texttt{\bs times} command. E.g.: \texttt{\$7 \bs x 10\^{}5\$} produces $7 \times 10^5$.

\end{description}

\clearpage
\section{Examples}
\label{sec:examples}

\subsection*{PhD thesis in English}
\begin{lstlisting}
% !TeX encoding = UTF-8
% !TeX program = pdflatex
% !TeX spellcheck = en_US

\documentclass[binding=0.6cm]{sapthesis}

\usepackage{microtype}
\usepackage{hyperref}
\hypersetup{pdftitle={My thesis},pdfauthor={Francesco Biccari}}

\title{My thesis}
\author{Francesco Biccari}
\IDnumber{123456}
\course{Dottorato di Ricerca in Filologia}
\courseorganizer{Scuola di Dottorato in Scienze Filologiche}
\cycle{XXXVII}
\AcademicYear{2021/2022}
\advisor{Prof. Caio}
\coadvisor{Dr. Sempronio}
\authoremail{pippo@pippo.com}
\copyyear{2022}
\thesistype{PhD thesis}

\begin{document}

\frontmatter
\maketitle
\dedication{Dedicated to\\ Donald Knuth}

\begin{abstract}
This thesis deals with myself.
\end{abstract}

\tableofcontents

\mainmatter
\chapter{Introduction}
...

\backmatter
\cleardoublepage
\phantomsection % Give this command only if hyperref is loaded
\addcontentsline{toc}{chapter}{\bibname}
% Here put the code for the bibliography. You can use BibTeX or
% the BibLaTeX package or the simple environment thebibliography.

\end{document}
\end{lstlisting}


\clearpage
\subsection*{Master thesis (Laurea/Laurea Magistrale) in Italian}

\begin{lstlisting}
% !TeX encoding = UTF-8
% !TeX program = pdflatex
% !TeX spellcheck = it_IT

\documentclass[binding=0.6cm]{sapthesis}

\usepackage{microtype}
\usepackage[italian]{babel}
\usepackage[utf8]{inputenc}
\usepackage{hyperref}
\hypersetup{pdftitle={La mia tesi},pdfauthor={Francesco Biccari}}

\title{La mia tesi}
\author{Francesco Biccari}
\IDnumber{123456}
\course{Laurea Magistrale in Fisica}
\courseorganizer{Facolt|\`a| di Scienze Matematiche, Fisiche e Naturali}
\AcademicYear{2021/2022}
\advisor{Prof. Caio}
\coadvisor{Dr. Sempronio}
\authoremail{francesco.biccari@pippo.com}
\copyyear{2022}
\thesistype{Tesi di Laurea Magistrale}

\begin{document}

\frontmatter
\maketitle
\dedication{Dedicato a\\ Donald Knuth}

\begin{abstract}
Questa tesi parla di me.
\end{abstract}

\tableofcontents

\mainmatter
\chapter{Introduzione}
...

\backmatter
\cleardoublepage
\phantomsection % Give this command only if hyperref is loaded
\addcontentsline{toc}{chapter}{\bibname}
% Here put the code for the bibliography. You can use BibTeX or
% the BibLaTeX package or the simple environment thebibliography.

\end{document}
\end{lstlisting}


\clearpage
\subsection*{Specialization thesis in English}

\begin{lstlisting}
% !TeX encoding = UTF-8
% !TeX program = pdflatex
% !TeX spellcheck = en_US

\documentclass[binding=0.6cm]{sapthesis}

\usepackage{microtype}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage{hyperref}
\hypersetup{pdftitle={My thesis},pdfauthor={Francesco Biccari}}

\title{My thesis}
\author{Francesco Biccari}
\IDnumber{123456}
\course{Specializzazione in Fisica Medica}
\courseorganizer{Facolt|\`a| di Medicina e Chirurgia}
\AcademicYear{2021/2022}
\advisor{Prof. Caio}
\coadvisor{Dr. Sempronio}
\director{Prof. Pippo}
\customdirectorlabel{Direttore della Scuola di Specializzazione}
\authoremail{francesco.biccari@pippo.com}
\copyyear{2022}
\thesistype{Specialization thesis}

\begin{document}

\frontmatter
\maketitle
\dedication{Dedicated to\\ Donald Knuth}

\begin{abstract}
This thesis deals with myself.
\end{abstract}

\tableofcontents

\mainmatter
\chapter{Introduction}
...

\backmatter
\cleardoublepage
\phantomsection % Give this command only if hyperref is loaded
\addcontentsline{toc}{chapter}{\bibname}
% Here put the code for the bibliography. You can use BibTeX or
% the BibLaTeX package or the simple environment thebibliography.

\end{document}
\end{lstlisting}


\appendix

\section{A very brief introduction to the \TeX\ world}

Many people want to (or are compelled to) write in \LaTeX\ without studying
a basic manual. Here follows a very brief introduction to the \TeX\ world.

\TeX, the document preparation system designed by Donald Knuth in 1978, is a program to typeset documents.
It is a mark-up language: you write a simple text decorated with \TeX\ commands (source code) which is then compiled to obtain the final product, a document in pdf format. 
\LaTeX\ is just a set of macros, written in \TeX, to simplify the writing of the source code: it can be thought as a simpler programming language with respect to \TeX. A source code written in \LaTeX\ can be compiled by several ``compilers'': \texttt{pdflatex} (the most common), or \texttt{xelatex}, or others.

The following list of \LaTeX\ manuals, may be especially useful for Italian authors.

\begin{itemize}
\item \href{http://www.lorenzopantieri.net/LaTeX_files/ArteLaTeX.pdf}{\textsc{L. 
Pantieri \& T. Gordini}, \textit{L'arte di scrivere con} \LaTeX, (2017)}

\item \href{http://mirror.ctan.org/info/symbols/comprehensive/symbols-a4.pdf}{\textsc{S. Pakin}, \textit{The comprehensive} \LaTeX\ \textit{symbol list}, (2021)}

\item \href{http://profs.sci.univr.it/~gregorio/breveguida.pdf}{\textsc{E. Gregorio}, \LaTeX\textit{: breve guida ai pacchetti di uso pi\`u comune}, (2010)}
\end{itemize}

In order to use \LaTeX, you have to install a \TeX\ distribution. It contains the compilers, several fonts and other files needed by the compilers and also many \emph{packages}, which can be thought as libraries or extensions of \LaTeX. The most famous distributions are \href{http://miktex.org/}{MiKTeX} (available only for Windows, Linux, and Mac), \href{http://www.tug.org/texlive/}{TeX Live} (available for Windows, Linux, and Mac) and \href{https://tug.org/mactex/}{MacTeX} (available only for Mac OS).

Finally we discuss the editor, that is the program used to write your source file. Since a source file written in \LaTeX, like in any other programming language, is a simple text file, you can write your code with any text editor you want (for example Notepad in Windows). However the suggested editors are:
\begin{itemize}
\item \href{http://tug.org/texworks/}{TeXworks}. Already installed with any \TeX\ distribution. Very simple and powerful. Use TeXworks if you are not an expert. Enrico Gregorio has written a very good and brief TeXworks manual in Italian, which can be found at: {\small \url{http://profs.sci.univr.it/~gregorio/introtexworks.pdf}}.

\item \href{http://texstudio.sourceforge.net/}{TeXstudio} (cross-platform), \href{http://www.xm1math.net/texmaker/}{TeXmaker} (cross-platform), \href{http://pages.uoregon.edu/koch/texshop/}{TeXshop} (only for Mac), \href{http://kile.sourceforge.net/}{Kile} (only for Linux). Powerful editors.

\item \textbf{Avoid} other editors unless you know what you are doing!

\end{itemize}

Finally we explain how to compile the example documents provided in the \textsf{sapthesis} package. Double click on one of the \texttt{.tex} file in the \texttt{examples} folder. 
TeXworks should start showing the content of that file. 
The \texttt{pdflatex} compiler should be automatically selected thanks to the \emph{magic lines} placed at the beginning of the file.
Now, in order to compile, press the green button. 
At the end of the compilation the resulting pdf appears in a separate window. Remember to compile at least three times, because \LaTeX\ needs more than one compilation to correctly resolve the internal cross references (for example for the table of contents composition, or when you refer to a figure by the \texttt{\bs label}\,--\,\texttt{\bs ref}\,/\,\texttt{\bs pageref} mechanism).


\subsection*{Using Overleaf}

\href{https://www.overleaf.com/}{Overleaf} is a collaborative cloud-based online text editor, specifically designed for \LaTeX. The compilation of the source file is performed remotely on the Overleaf servers, by a TeXLive distribution. Therefore, using \textsf{sapthesis} in Overleaf is straightforward. You don't need to do anything, the package is already available. For any reason \textsf{sapthesis} is not available or the version present in Overleaf is outdated, just copy the files of \textsf{sapthesis } in your remote working directory in Overleaf. Local files have always precedence with respect to global files.

\subsection*{Using LyX}

\href{https://www.lyx.org/}{LyX} is an advanced \LaTeX\ editor which does not simply show the source code like any text editor, but instead it renders maths, images, tables and some text formatting commands. However this ``layer'' between the writer and the real source code is sometimes frustrating and many authors discourage the usage of LyX.

Using \textsf{sapthesis} with LyX is quite straightforward.
\begin{itemize}
\item
Install \textsf{sapthesis} by the package manager of your \TeX\ distribution or manually.

\item
Copy the file \texttt{sapthesis.layout} in the directory\\ \texttt{C:\bs Program Files\bs Lyx20\bs Resources\bs layouts\bs}\\ and then, in LyX, click on \textsf{Tools > Reconfigure}. This will add the \textsf{sapthesis} class in the list of LyX available classes.

\item
In LyX, first of all, go in \textsf{Tools > Preferences > Language Settings > Language} and choose ``none'' in Language package. This step is necessary because LyX not only loads babel with the desired language, but it passes the language also as an option for the class! This triggers an error in many classes.

\item 
Create a new document and go in \textsf{Document > Settings > Document Class}. Here you can choose \textsf{sapthesis} as the class for the document and write the class options.

\item 
Write the preamble in \textsf{Document > Settings > LaTeX Preamble}.

\item Create the titlepage inserting the title by the \textsf{Title} item in the LyX left menu.

\end{itemize}

It is recommended to activate \textsf{View > Source Pane}. This step is not necessary but it is very useful to observe the \LaTeX\ code produced by LyX (on the right choose ``Complete source'' or ``Preamble'').









\clearpage
\section{Frequently Asked Questions}

\subsection{How can I increase the font size?}

The default font used in \textsf{Sapthesis} is Latin Modern. The default font size is 11\,pt using A4 and 10\,pt using A5 and B5. At the moment it is impossible to change the font size unless you modify the \textsf{Sapthesis} class file (\texttt{sapthesis.cls}). The reason for this choice is to maintain a common format for all the theses.


\subsection{How can I increase the line-spacing?}

The line-spacing in typography is defined as the distance between two lines. A strange ``tradition'' in Italy is to write the thesis with a double line-spacing. This is an incredibly large number. The lines are so separated that the effect is very ugly. Two reasons are behind this choice. The first one is that a lot of space is available for your professor to comment your text. The second one is that, in this way, the thesis is thicker.

This effect is amplified when you use Microsoft Word because Word defines the line-spacing in a different way with respect to the typical definition. And usually people do not know that. Therefore, when you set the value of 2 for the line-spacing in Word, actually you obtain a line-spacing of 2.34 according to the normal definition of the term! (Word adds an extra 17\% of space, I do not know why).

Of course this large value of the line-spacing is a nonsense. It is known in typography that the best value ranges between 1.20 and 1.45. In \LaTeX\ the default line-spacing is 1.20, which means that, if you use a font size of 10\,pt, the line-spacing is 12\,pt. In \textsf{Sapthesis} the line-spacing is set to 1.20. Nowadays, professors typically correct a thesis by using the comment tools of the their pdf viewer. There are still some who want to print it and want a double line-spacing. In that case, give them a copy with a double line-spacing but ask them to have the permission to print it in a more normal line-spacing, in order to save paper.

If you want to change the line-spacing, do not use the \texttt{\bs linespread} command. Load instead the \textsf{setspace} package and use, for example, the \texttt{\bs onehalfspacing} command.



\subsection{Single sided or double sided printing?}

A strange ``tradition'' in Italy is to print the theses only on one side of the paper sheets. In the past this was justified because a thesis was manually typed by a \href{https://en.wikipedia.org/wiki/Typewriter}{typewriter machine}.
Today, where the theses are all composed by a computer, this ``tradition'' is kept mainly because in this way the professors and the students are happy to see a thicker book.

Of course this is a nonsense. Not only because the bulky effect is only aesthetic (if you open the thesis you can see that only one side is printed), but especially because it is a waste of paper. Moreover, reading a book where only the right page is printed is quite ugly and strange, isn't it? (Have you ever seen a book, containing mainly text, printed single sided?)

The only real reason to print single sided is when a good paper is not available. Indeed, a low quality paper, like the one typically used for photocopies, has a grammage of 80\,g/m$^2$. It is a little bit semitransparent and this can be a problem when you print double sided, especially if you have many color images. The best approach is using a proper paper grammage of 90\,g/m$^2$ or 100\,g/m$^2$. Ask to the printing service which type of paper is more suitable to print your thesis double sided.


\subsection{Inverted margins? How much space for binding?}

Another typical question regards the margins of the thesis. Quite often the students (and incredibly also the printing services) complain about the margins of the thesis. They think that the margins are reversed because in \LaTeX\ standard classes, by default, the inner margin is smaller than the outer margin. The same behaviour, but with slightly different proportions, is adopted in \textsf{Sapthesis} (see Figure\,\ref{layout}). Of course, they are wrong. This is the correct behavior! Indeed, as you can see in any book, the sum of the two inner margins should be more or less equal to the width of a single outer margin. This is for an aesthetic reason. Otherwise the two columns of text would be too much separated when the book is open.

\begin{figure}[!b]
\centering
\setlength{\unitlength}{0.12mm}
\begin{picture}(420,297)(-210,0)
\polyline(-210,0)(210,0)(210,297)(-210,297)(-210,0)
\Line(0,0)(0,297)
\put(27.05,37.4){\polygon(0,0)(139.2,0)(139.2,223.8)(0,223.8)}
\put(-27.05,37.4){\polygon(0,0)(-139.2,0)(-139.2,223.8)(0,223.8)}
\put(27.05,268.16){\polygon(0,0)(139.2,0)(139.2,4.22)(0,4.22)}
\put(-27.05,268.16){\polygon(0,0)(-139.2,0)(-139.2,4.22)(0,4.22)}
\end{picture}
\caption{A4 page layout scheme of \textsf{UniFiTh} class using a zero binding margin.}
\label{layout}
\end{figure}


At this point the students usually reply ``what about the binding margin? The inner margin should be larger because some space is used by the binding process!'' This is partially true. The effect described above in Figure\,\ref{layout} is what should happen \emph{after} the binding process. For this reason there is the documentclass \texttt{binding} option in \textsf{Sapthesis} (see Section\,\ref{class_options}). Typical values are 6 or 7\,mm but it is always preferable to ask the printing service which is the correct value according to the binding method (be careful because many printing services are not professional and suggest arbitrarly binding margin values).

\subsection{Numbered introduction and conclusions?}

There is a strange ``tradition'' in Italy to not attribute a number to the Introduction and Conclusions of a thesis. Probably, only because they are usually short chapters. So it seems that they do not deserve a proper number like any other chapter.

In my (and not only mine) opinion this is a nonsense. The Introduction and Conclusions chapters are part of the thesis, and they should be read to properly understand the thesis. They cannot be skipped. So why don't attribute a number to those chapters?

Therefore I suggest to use the following structure of the thesis (which is the same reported in the examples in Appendix \ref{sec:examples}).

\begin{lstlisting}
...

\frontmatter
\maketitle
...

% The chapters after the mainmatter command are numbered
\mainmatter
\chapter{Introduction}
\chapter{...}
\chapter{...}
\chapter{...}
\chapter{Conclusions}

\backmatter
...
\end{lstlisting}

However, if you really want to follow the nonsense of not giving a number to the Introduction and Conclusions chapter, you can do it in the following way. But keep in mind that \emph{if you do not number the Introduction and Conclusions, you cannot insert any numbered equation, table, or picture in these chapters}. Indeed, all these objects are numbered with the chapter number: Fig.\,1.2, Tab.\,3.2, Eq.\,(4.1), etc. If the chapter does not have a number, how can we assign a number to Figures, Tables, or Equations?

\begin{lstlisting}
...

\frontmatter
\maketitle

% The chapters after the mainmatter command are numbered
\mainmatter
\chapter*{Introduction}   % The chapter* does not attribute a number
\markboth{Introduction}{} % This command is necessary for the headings
\chapter{...}
\chapter{...}
\chapter{...}
\chapter*{Conclusions}    % The chapter* does not attribute a number
\markboth{Conclusions}{}  % This command is necessary for the headings

\backmatter
...
\end{lstlisting}

Finally, it is worth noting that the first and last chapter of a thesis must not to be always called Introduction and Conclusions! 

\subsection{How to reduce the size of the pdf?}

Usually, students do not optimize the images of their thesis. This is a very bad practice and one of the typical consequences is the excessive large size of the final pdf. The topic is too long to be covered here, however I want to provide a simple way to reduce \textit{a posteriori} the file size of the pdf.

Using \href{https://www.ghostscript.com/}{Ghostscript} we can ``distill'' a pdf file, which means interpreting it and re-enconding it again. This is just a small list of possible commands (commands are intended for Windows 64 bit but they can easily applied to other operating systems changing the name of the Ghostscript executable):

\begin{lstlisting}
BEST QUALITY (Flate image encoding)

gswin64c.exe -q -dNOPAUSE -dBATCH -dSAFER -sDEVICE=pdfwrite -sOutputFile=output.pdf
-dAutoFilterColorImages=false -dAutoFilterGrayImages=false 
-dColorImageFilter=/FlateEncode -dGrayImageFilter=/FlateEncode 
-dPDFSETTINGS=/prepress -dCompatibilityLevel=1.5 input.pdf
\end{lstlisting}

\begin{lstlisting}
BEST QUALITY (DECT image encoding)

gswin64c.exe -q -dNOPAUSE -dBATCH -dSAFER -sDEVICE=pdfwrite -sOutputFile=output.pdf
-dPDFSETTINGS=/prepress -dCompatibilityLevel=1.5 input.pdf
\end{lstlisting}

\begin{lstlisting}
LOWER QUALITY (DECT image encoding)
Substitute XXXXXXX with one of the following settings (order of descending quality):
/printer /ebook /screen

gswin64c.exe -q -dNOPAUSE -dBATCH -dSAFER -sDEVICE=pdfwrite -sOutputFile=output.pdf
-dPDFSETTINGS=XXXXXXX -dCompatibilityLevel=1.5 input.pdf
\end{lstlisting}

\subsection{How to create an archivable pdf?}

\href{https://en.wikipedia.org/wiki/PDF/A}{PDF/A} is a particular PDF format, standardized by ISO, specialized for use in the archiving and long-term preservation of electronic documents. Public and private institutions, including universities, increasingly require this form to archive electronic documents. There are several levels of PDF/A. The suggested format for a thesis is the PDF/A-2b.

The best and free way to check if a pdf file is compliant to one of the PDF/A levels is to use \href{https://verapdf.org/}{veraPDF}, an open source software supported by the most important PDF associations in the world and funded by the European Commission. This software is freely available for Windows, Linux, and Mac.

A PDF/A file can be generated directly in \LaTeX, properly following some rules (see ``Creare file archiviabili con pdf\LaTeX\ e Lua\LaTeX'' by Claudio Beccari) however we do not have enough space to cover this topic here.
A faster way is to transform the file of the thesis in a PDF/A compliant pdf file using \href{https://www.ghostscript.com/}{Ghostscript}. Follow the following steps:

\begin{enumerate}
\item Copy in your working directory an \texttt{icc} color profile. Since the pdf file will be viewed mainly on electronic screen, you can use a generic sRGB color profile. You can download one here: \url{https://www.color.org/srgbprofiles.xalter}. Rename it, for example, in \texttt{srgb.icc}.

\item Copy a PostScript definition file, with the instructions to convert the file in PDF/A, in your working directory. This file, containing all the proper commands, can be found in your computer.
You can find it under the name \texttt{PDFA\_def.ps} in the \texttt{lib} folder of your Ghostscript installation directory (for example \texttt{C:\bs Program Files\bs gs\bs gs9.22\bs lib\bs}typically in the lib subfolder). Copy this file in your working directory and rename it! Let us suppose to rename it in \texttt{PDFArenamed.ps}.

\item Modify the PostScript definition file. Open the \texttt{PDFArenamed.ps} file and specify the color profile (\texttt{srgb.icc}) and the title of your pdf file. To do that use the text editor you prefer. The variables to modify are intuitive and easily identifiable: \texttt{/ICCProfile} and \texttt{/Title}.

\item Open a terminal and launch the following command
\begin{lstlisting}
gswin64.exe -q -dNOPAUSE -dBATCH -dNOSAFER 
-sDEVICE=pdfwrite -sOutputFile=output.pdf
-dPDFA=2 -dPDFACompatibilityPolicy=1
-sColorConversionStrategy=UseDeviceIndependentColor
-sProcessColorModel=DeviceRGB
PDFArenamed.ps input.pdf
\end{lstlisting}

\item Finally, control that the converted file correctly adheres to the PDF/A format using the VeraPDF software.
 
\end{enumerate}

\addtocontents{toc}{\protect\end{multicols}}
\end{document}
