\documentclass[thesis_guide.tex]{subfiles}
% chktex-file 1 chktex-file 46

\begin{document}

%==============================================================================
\chapter{Tips and tricks}%
\label{sec:tips}\index{tips}
%==============================================================================

\LaTeX\ file: \href{run:./guide_tips.tex}{guide\_tips.tex}\\[1ex]
\noindent
Over time I have collected quite a lengthy list of things you should
\enquote{Do} and \enquote{Not Do} (at least in my head) that I think
it is useful to write down early in the document, so that you may
actually read them!  In this chapter I first tell you how to get
and use the style file and then give some tips.
I have also started to add a list of common English mistakes,
especially those made by German speakers!

%------------------------------------------------------------------------------
\section{How to use the \Package{ubonn-thesis} style}%
\label{sec:tips:howto}
%------------------------------------------------------------------------------

My original idea with this document was that you also look at the \LaTeX{} that
is used to create it, in order to find out how things are done.
I therefore do not always give you the \LaTeX{} commands in the printed
document, but assume that you would have a look at the \LaTeX{} source.
To help you with this, each chapter contains a link to the relevant
file at the top. This link should work if you have compiled the guide
yourself and are in the \File{guide} subdirectory of the
\File{ubonn-thesis} directory tree.
As of version 7.0 of the guide,
I have started using the \Package{tcolorbox} package that allows me to show
both the \LaTeX{} and the result automatically.
Hence in more and more places you will find compiled \LaTeX{} and the source code side by side.
The files that make up this document are available in a Git repository and as a \texttt{tar} file.
To get the latest Git version give the command:

\begin{bashlisting}
git clone https://gitlab.uni-bonn.de/uni/ubonn-thesis.git
\end{bashlisting}
\noindent
If you want to checkout a particular version you can give the command:
\begin{bashlisting}
git clone --branch N.M https://gitlab.uni-bonn.de/uni/ubonn-thesis.git
\end{bashlisting}
Since the move to GitLab (2025-09-10) you no longer have to be in the University of Bonn network for the clone commands to work.
\noindent
The tar file (and the tag tree (as of version 1.5)) also includes
the guide as a PDF file: \File{thesis\_guide.pdf}.  It can be
obtained from:\\
\url{https://www.pi.uni-bonn.de/brock/en/thesis-guide}.

\par\noindent
Once you have the files, you can then give the command:
\begin{bashlisting}
make new [THESIS=dirname] # or
make new [THESIS=dirname] SUBFILE=1 # or
python thesis_util.py new [--thesis=dirname] [--type physics|astro] [--subfile]
\end{bashlisting}
\noindent to create a new directory with several files to help you get started.
By default the directory name will be \texttt{mythesis}.
Under Windows you must use the Python script \File{thesis\_util.py} to create your thesis skeleton.
You can also use this script for Linux and macOS.
Use the \texttt{SUBFILE} variant if you want to include each chapter using the \Package{subfiles} package,
rather than \Macro{include}.
I recommend this, as it makes it very easy to compile a single chapter,
either standalone or inside an editor such as VS Code.
If you want to write a thesis that uses the astronomy style of references
(\Option{authoryear} style and a bibliography at the end of each chapter)
give the command:
\begin{bashlisting}
make astro [THESIS=dirname] # or
make astro [THESIS=dirname] SUBFILE=1 # or
python thesis_util.py new [--thesis=dirname] [--type astro] [--subfile]
\end{bashlisting}
% If you choose a different name, you have to adjust the \Macro{include}
% commands inside \texttt{./dirname.tex}.
To compile\index{compiling} your thesis switch to your new directory
\verb+cd mythesis [or dirname]+ and try:
\begin{bashlisting}
make [thesis]
\end{bashlisting}
See \cref{sec:tips:options} for a list of the options that can be passed to the package.
I no longer support versions of \TeXLive older than 2018.

As of version 6.0, \Command{make thesis} uses the \Command{latexmk}\index{latexmk} command for compilation.
\Command{latexmk} looks at your logfile and decides how many times \Command{pdflatex} etc.
have to be run.
If you use \Package{feynmf} or \Package{feynmp} you should use the commented out version
of the \Command{LATEXMK} variable that includes the \Option{-shell-escape} option.\footnote{%
  I got this information from \url{https://tex.stackexchange.com/questions/374160/how-to-have-latexmk-always-use-shell-escape}.}
For details on how to compile a glossary with \Command{latexmk} see \cref{G-sec:app:glossary}.
If for some reason \Command{latexmk}\index{latexmk} does not work you can use the command
\Command{make thesis11} instead.
The tool \Command{pplatex}\footnote{%
Can be downloaded from \url{https://github.com/stefanhepp/pplatex}.
}
is supposed to provide a nicely formatted version of the \LaTeX\ output on the command line.

The style file should work for all recent \TeX\ installations.
% However, some of the packages I recommend have
% been changing quite a lot over the past few years.
% You should therefore set the \TeXLive version you are using appropriately.
% The default setting is 2020.\footnote{%
% Setting the \TeXLive version to one that is lower than your installation should not cause any problems.}
% For an an up-to-date version of MikTeX (2.9) you should probably use the current year.
% Things should compile without any changes if you use \TeXLive 2016 or later.
% Look in the style file to see what changes are made depending on the year you use.
% You can change the \TeXLive version when you make a new thesis
% by giving a command like \enquote{\texttt{make new TEXLIVE=2021}}. %\footnote{%
If you switch to a newer \TeX\ version do a
\enquote{\texttt{make clean cleanbbl cleanblx}} in between.

Note that as of version 2.1, the main file for the thesis
(\texttt{mythesis.tex}), the \texttt{Makefile} and the style file
(\texttt{ubonn-thesis.sty}) are copied into your \texttt{mythesis}
subdirectory. This means that if you update the \Package{ubonn-thesis}
you can look for differences between the new style file and the one
you have. It also implies that if you want the update to have an
effect on your thesis you should copy the new versions of
\File{ubonn-thesis.sty} and \File{ubonn-biblatex.sty} into the directory with your thesis.
For more details see \cref{sec:tips:update}.

As of version~4.0 of the package, you specify the type of thesis and the stage as options
to the \Macro{documentclass} or to the \Package{ubonn-thesis} package.
These options select the appropriate title and cover pages.
The following thesis types exist:
\begin{description}\setlength{\parskip}{0pt}\setlength{\itemsep}{0pt}
\item[PhD] a PhD thesis;\index{PhD}\index{thesis!PhD}
\item[Master] a Master thesis;\index{MSc}\index{thesis!Master}
% \item[Diplom] a Diplom thesis;\index{Diplom}\index{thesis!Diplom}
\item[Bachelor] a Bachelor thesis.\index{BSc}\index{thesis!Bachelor}
\end{description}
The following stages exist:
\begin{description}\setlength{\parskip}{0pt}\setlength{\itemsep}{0pt}
\item[Draft] you are still writing your thesis;
\item[Submit] you are ready to submit your thesis;
\item[Final] the final version of your thesis.
  For PhD theses this is the version that goes to ULB\@;
% \item[PILibrary] final version of your thesis with an extra cover page\index{cover}
%   including an abstract for the PI library.
\end{description}
See \cref{G-sec:submit} for some more details about thesis submission.

If you change the stage of your thesis from say \Option{Draft}\index{Draft} to \Option{Submit}\index{Submit}
you may encounter \Package{biblatex} errors.
These can be fixed by giving the command \texttt{make cleanall; make}.

If you are not a member of the
\foreignquote{ngerman}{Physikalisches Institut} you should
also change \Macro{InstituteName}, \Macro{inInstitute} and
\Macro{InstituteAddress}. The style file \texttt{ubonn-thesis.sty}
already contains the appropriate definitions for PI, HISKP, IAP and
AIfA.

All packages that are needed should be part of your \TeX\
installation. If not you may have to install them or ask your system
administrator to do so.

If you just want to make the cover pages, use the file \texttt{cover\_only.tex}.
Be sure to adapt the font selected in \texttt{ubonn-thesis.sty}
to the font you actually used in your thesis.
Be aware that not all font sizes are available in all font collections.
If you used the default \LaTeX{} font in your thesis,
then choose \Package{lmodern}\index{font!lmodern} in the style file.

The main file for this guide is \texttt{guide/thesis\_guide.tex} and
it includes the \LaTeX\ files in the directory \texttt{./guide} and
some of the Feynman graphs in the directories 
\File{axodraw}, \File{feynmf}, \File{pyfeynhand} and \texttt{tikz}.
This guide should compile without changes for \TeXLive 2022 or later.
It does not compile for \TeXLive 2020 and earlier.
For versions inbetween set \Macro{TweakYear} in \texttt{thesis\_guide.tex} to the appropriate value.


%------------------------------------------------------------------------------
\section{Options that can be passed to \Package{ubonn-thesis}}%
\label{sec:tips:options}\index{options}
%------------------------------------------------------------------------------

From version~3.0 onwards it is possible to change things
in the style file by passing options to it.
A few default packages also changed with this version.
\Package{subfig} \(\to\) \Package{subcaption}.
I have oscillated between \Package{longtable} and \Package{xtab}.
\Package{longtable} seems to be more actively maintained
and work a little bit better.
The syntax \Option{siunitx} and \Option{siunitx=true} is equivalent.
Use \Option{siunitx=false} to turn off an option.
The following options exist:\\

\begin{longtable}{llp{10.0cm}}
  \toprule
  Option & Default & Description \\
  \midrule
\endfirsthead
  \midrule
  Option & Default & Description \\
  \midrule
\endhead
  \midrule
  \multicolumn{3}{r}{Continued on next page}\\
  \midrule
\endfoot
  \bottomrule
\endlastfoot
  PhD & false & A PhD thesis.\\
  Master & false & A Master thesis.\\
  Diplom & false & A Diplom thesis.
    \emph{This option is deprecated and no longer tested.}\\
  Bachelor & false & A Bachelor thesis.\\
  Draft & true & Draft version of the thesis.\\
  Submit & false & Version of the thesis to be submitted.\\
  Final & false & Final version of the thesis (for PhD theses ready to go to ULB).\\
  PILibrary & false & Final version including an extra cover page for the PI library.
     \emph{This option is deprecated and no longer tested.}\\
  thesistype & Unknown & Specify the thesis type.\\
  thesisversion & Draft & Specify the stage of the thesis.\\
  twoside & true & Margins set for two-sided printing.\\
  newtx & true & Use the \Package{newtx} font packages (newer version of \Package{txfonts}).\\
  txfonts & false & Use a Times-Roman-like font.\\
  palatino & false & Use a combination of Palatino, Helvetica and Courier fonts.\\
  fontname & false & Use the font name rather than its filename for fonts with \LuaLaTeX\ and \XeLaTeX.\\
  subcaption & true & A package for making sub-figures (and sub-tables) and captions for them.\\
  subfig & false & A package for making sub-figures and captions for them.\\
  subfigure & false & A package for making sub-figures and captions for them (deprecated).\\
  longtable & true &  A package for tables that are longer than one page.\\
  supertabular & false &  Another package for tables that are longer than one page.\\
  xtab & false & Another package for tables that are longer than one page.\\
  xltab & false & Another package for tables that are longer than one page.\\
  tableheading & true & Table caption spacing set correctly for captions above the table.\\
  biblatex & true & Include \Package{biblatex}.\\
  siunitx & true & Use the \Package{siunitx} package for typesetting units.\\
  numerr & false & Macros for rounding and asymmetric errors.\\
  numpmcorr & false & Use macro for different width \enquote{\(+\)} and \enquote{\(-\)}.\\
  eVkern & false & Apply a kern of -0.1em to \unit{\eV} in order to move \enquote{e} and \enquote{V} closer together.
    This is not necessary if you use the \Package{newtx} font package.\\
  dcolumn & false & A package for helping to align things in tables.\\
  cleveref & true & Turn on use of the \Package{cleveref} package.\\
  clevercaps & true & Capitalise Fig., Table etc.\\
  cleverabbrev & true & Abbreviate Figure to Fig.\ etc.\\
  diffcoeff & false & A lot of useful commands for derivatives.\\ 
  diffcoeffISO & false & Follow ISO conventions in \Package{diffcoeff}.\\
  derivative & false & A new package (released in 2021) with lot of useful commands for derivatives.\\
  physics & false & Useful mathematical constructions for physics.\\
  hepparticles & true & Standardised names and formatting for particle physics.
    This loads \Package{hepnicenames} and \Package{heppennames}.\\
  hepitalic & true & Use italics rather than upright letters for particles.\\
  mhchem & true & A nice package for chemical elements and processes.\\
  bookmark & true & use \Package{bookmark} package to improve bookmarks in PDF file.\\
  feynmf & false & Include the \Package{feynmf} package for Feynman graphs.\\
  feynmp & false & Include the \Package{feynmp} package for Feynman graphs.\\
  titlesec & false & Use the \Package{titlesec} package for formatting chapter titles.\\
  astrobib & false & Adjust \Package{biblatex} options to conform to the usual astronomy style.\\
  firstinits & false & Use \Option{firstinits} instead of \Option{giveninits} for \Package{biblatex}.\\
  floatopt & true & Adjust settings that control the number and placement of floats.\\
  lineno & false & Show line numbers -- only works in \Option{Draft} mode.\\
  linenofix & true & Fix line numbers around AMS math environments without using the \Package{linenomath} environment.\\
  todonotes & false & Turn on use of the \Package{todonotes} package and define \Macro{mynote}.\\
  shownotes & false & Show the ToDo notes (also turns on \Option{todonotes}).\\
  showframe & false & Shows a frame around page elements for debugging purposes.\\
  coveroffset & \qty{1}{cm} & Offset of the cover page when \Option{twoside=true}.\\
  bibstyle & numeric-comp & Specify the style to use for the references.
    Standard values are \Option{numeric-comp} or \Option{alphabetic}.\\
  backend & biber & Specify the backend to use for \Package{biblatex}.
    Possibilities are \Option{biber}, \Option{bibtex} or \Option{bibtex8}.\\
  refsection & chapter & Set things up for references to be at the end of each chapter.\\
  bibencoding & & Set the encoding for the bibliography (usually not needed).\\
  texlive & 0 & Specify the \TeXLive version.
    \emph{This option is deprecated and will be ignored.}\\
    % You can also use the older command \verb|\newcommand*{\texlive}{2020}|.\\
\end{longtable}

A few default option values are adjusted depending on the \TeXLive version.
See the \texttt{ubonn-thesis} style file to find out what is changed.
The option \Option{twoside} should probably be set to \texttt{false} for an online version of your thesis
that is not going to be printed.

You can tweak the bibliography by passing various options to the
\Package{ubonn-biblatex} style file.
These are detailed in \cref{G-sec:ref:bbx}.

If you use \LuaLaTeX\ or \XeLaTeX,
the \Option{newtx} and \Option{txfonts} options select the TeX Gyre Termes font,
while the \Option{palatino} option selects the TeX Gyre Pagella font.
The TeX Gyre font Heros is used as the sans-serif and Cursor as the monospaced font.
Fonts are by default selected using the filename.
If for some reason this does not work you can try the \Option{fontname=true} option,
which uses the font name instead.

Depending on the font you use, you may find that the \enquote{e} and \enquote{V} in \unit{\eV}, \unit{\MeV} etc.\
are too far apart.
You can pass the option \Option{eVkern} to \Package{ubonn-thesis} in order to move them 0.1em closer together.\footnote{%
It is not needed if you use the \Package{newtx} font package.}


%------------------------------------------------------------------------------
\section{Do}%
\label{sec:tips:do}
%------------------------------------------------------------------------------

\begin{itemize}
\item Have 1--2 other people read your thesis well before you are
  supposed to submit it. Do not ask too many; everyone has their own
  opinions on how things should be written, how much detail should be
  included etc.\ and these opinions will not necessarily agree with
  each other!

\item Write \enquote{nice} \LaTeX. It makes it much easier to find mistakes
  in your document. If you like to use the keyboard rather than the
  mouse when moving round in a document, turn on \enquote{auto-fill-mode
  (emacs)}\index{emacs} or its equivalent in any other editor, so
  that line breaks are inserted.

\item Make sure every table and figure is referenced in the text. I
  get very irritated when I suddenly find a figure that is not
  described in the text. A useful package to check this is
  \Package{refcheck}.\footnote{%
  There is a conflict if you use \Package{refcheck}, \Package{subcaption} and \Package{hyperref} together.
  See \url{http://tex.stackexchange.com/questions/273970/conflict-refcheck-subcaption-packages-for-label-with-underscores} for a workaround.}
  You need to run \LaTeX\ one more time for it to work.
  It indicates both in the log file and the resulting PDF which
  figures, tables, equations and sections are referenced.

\item Use a units package to format numbers and their units. Recent
  versions of \LaTeX\ include the \PackageG{siunitx} package, which
  is a superior replacement of \Package{SIunits}. I used to
  use \Package{SIunits}, or rather \Package{hepunits} which is
  built on top of \Package{SIunits}, and defines common particle
  physics units such as \unit{\GeV}. Use of these packages is
  discussed in \cref{sec:tips:units}.
  An alternative is the \Package{units} package.

\item Define any complicated symbols once you use them more than
  once:
\begin{tcblisting}{listing only}
\newcommand*{\etajet}{\ensuremath{\eta_{\text{jet}}}\xspace}
\end{tcblisting}
  If you decide at a later date that jet should be a superscript
  rather than a subscript you only have to change this in one place!

  Note that Kopka~\cite{kopka04}
  recommends using \Macro{newcommand*} rather than \Macro{newcommand}
  for short commands.

\item If you use normal words in superscripts or subscripts (or
  anything else in math mode) enclose them in \Macro{text}. You can
  also use \Macro{mathrm} or \Macro{textrm}. However, if you then use
  the same symbols in slides with a sans-serif font, the text may well
  continue to be in a serif font.\\
  {\sffamily Compare: A common jet energy cut at the LHC is now
    \(p_{T}^{\text{jet}} > \qty{20}{\GeV}\), while at HERA we typically
    used \(p_{T}^{\mathrm{jet}} > \qty[detect-family=false]{6}{\GeV}\).
  }
  The \unit{\GeV} in the first expression is in sans-serif. This is
  because the
  \Macro{sisetup}\texttt{\{detect-family=true\}}
  option is set in \texttt{ubonn-thesis.sty}
  (see \cref{sec:tips:siunitx}).  I used the option
  \Option{detect-family=false}
  for the \Macro{SI} command in the 2nd expression.
  In the first expression I use \Macro{text} for \enquote{jet}, while
  I use \Macro{mathrm} in the second expression.

\item Use \Macro{xspace} and
  \Macro{ensuremath} in all commands where you would
  like to use a symbol both in text mode and in math mode. Without
  \Macro{xspace} you have to make sure that you end every symbol with
  \texttt{\textbackslash} or \texttt{\{\}}, otherwise the space is used
  to signify the end of the symbol, e.g.\ in \LaTeX we have to pay
  attention otherwise the symbol and the next word run together.

\item Decide how you want to write abbreviations for particles and
  stick to it -- you should probably define the particle names in your
  style file and always use them (also for quarks).
  There are packages \Package{hepnicenames} and \Package{heppennames},
  which use \Package{hepparticles}.\footnote{%
    Note that \Package{hepnicenames} automatically includes \Package{heppennames},
    so it is sufficient to include \Package{hepnicenames} to be able to use both sets of definitions.}
  These packages have many predefined particles and a standard convention for naming.
  It is easy to add further definitions.
  See \cref{sec:tips:hepparticles} for some more details on how to write particles
  that are relevant for particle physics.

\item Decide how you want to write coordinate axes\index{coordinates}
  and stick to it. Far too often I see text like: \enquote{The proton
    beam defines the Z direction, while the interaction point is
    denoted as \((x_{0}, y_{0}, z_{0})\). The polar angle is measured
    with respect to the z axis and \(\cot\theta = p_{Z}/\pT\)}. Which is
  the best way of writing the coordinates? As \(x\), \(y\) and \(z\) are
  often used for kinematic variables, there are arguments in favour of
  \((X, Y, Z)\).

\item Use \Macro{enquote} from the \PackageG{csquotes} package to
  quote text rather than using explicit quotation marks. This has the
  advantage that consistent quotation marks are used everywhere (also
  if they are nested) and that they are also correct for the language
  (and dialect\footnote{%
    By default, British (UK) English\index{British English}\index{UK English}
    uses `British quoted text' for outer quotation marks,
    while American (US) English\index{American English}\index{US English}
    uses \foreignquote{USenglish}{American quoted text}. In this guide
    (and in \texttt{ubonn-thesis.sty})
    \foreignquote{USenglish}{American (US) quotes} are used even if you
    write in British (UK) English.})
  you are writing your thesis in.
  You can also see in \cref{G-sec:intro} how this works, even
  when switching languages inside a paragraph.

\item Use sizes that depend on the font size, \texttt{em}\index{em}
  (width of \enquote{M}) and \texttt{ex}\index{ex} (height of \enquote{x}), for
  spacing that should change with the text size. Use absolute sizes
  \texttt{cm, mm, pt} etc.\ where they are appropriate, e.g.\ title
  pages, boxes, etc. \Macro{quad} and
  \Macro{qquad} are also useful sizes in tables and
  equations.

\item Add a \textbackslash{} (or \{\}) after abbreviations that end with a full
  stop such as e.g.\ if followed directly by text. If you do not, an
  end of sentence space is added rather than a normal interword
  space. Note that \textbackslash{} is not needed (but does no harm)
  after abbreviations that only consist of capital letters:\\
  compare \enquote{e.g. my name is Ian C. Brock} % chktex 12
  and \enquote{e.g.\ my name is Ian C.\ Brock},
  where \textbackslash{} was included in the second version. In this
  example the difference is small. However, if \LaTeX{} increases the
  spacing between words to fill a line the effect is more obvious.

\item If a capital letter ends a sentence you should add the
  command \Macro{@} before the full stop, e.g.\
  \verb|\ldots as discussed in the chapter on QCD\@.|
  which produces \ldots as discussed in the chapter on QCD\@.
  This is necessary, as otherwise only an interword space is used
  before the next sentence.

\item Ask someone (me) if you cannot easily find out how to solve
  formatting problems. I once saw a thesis in German, where the
  author wanted to use commas instead of full stops in numbers and
  wrote numbers as \verb+\(2,\!47\)+ to produce \(2,\!47\) instead of
  \(2,47\). There are usually much better solutions, e.g.\
  \verb+\num{2.47}+ with the \Package{siunitx} package produces
  \num{2.47} in English and \foreignlanguage{ngerman}{\num{2.47}} in
  German. In the end such solutions will save you time!

\item Use punctuation in equations and \enquote{\text{d}},
  i.e.\ an upright \enquote{d} (if you are writing in British English)
  for derivatives,\index{derivative} e.g.
  \begin{equation*}
    \int y\,\mathrm{d}x\,.
  \end{equation*}
  This is also one of the the very few places, where it makes sense
  to put some spacing in by hand -- normally you should leave this to \TeX.
  The \Package{derivative} package provides the command \verb|\odif{x}|,
  while the \Package{diffcoeff} package (as of version 3.0) provides the command \verb|\dl|,
  and you can add space using a syntax such as \verb|\dl2x|.\footnote{%
  The digit can be anything between 0 and 9 (negative values are also possible).
  2 and 3 look to me to be sensible default values to use.}
  The \Package{physics} package provides the command \verb|\dd{x}|,
  which does the spacing for you.
\begin{tcblisting}{listing only}
\begin{equation*}
  \int y \dl2x\,.
\end{equation*}      
\end{tcblisting}

\item Pay attention to the alignment of numbers in
  tables. \Package{siunitx} provides the \Option{S} column specifier to
  help with this.
  Recent versions of \Package{siunitx} provide the command \Macro{tablenum},
  which gives a lot of flexibility.
  Packages such as \Package{dcolumn} also provide assistance.
\end{itemize}

Not really a strict \enquote{Do}: I highly recommend that you use an
integrated environment for editing and compiling your thesis.
If you are use macOS or Windows you probably get TeXShop or TeXworks by default.
\TeXstudio is based on \TeXmaker and is available for Linux,
Windows and macOS\@.
It used to be my preferred \LaTeX\ environment under all systems!
In the past couple of years,
I have switched to the Visual Studio Code\index{Visual Studio Code} editor instead.
The main reason for this is so that I can use the same program
for editing scripts, e.g.\ a \File{Makefile}, as I use for \LaTeX\ code.
The \texttt{LaTeX Workshop}\index{LaTeX Workshop@\LaTeX\ Workshop} extension is being actively developed
and is very nice.
The \Package{Spell Right} spelling checker works very well
and I have also activated the use of \Package{ChkTeX} to improve my \LaTeX\ syntax.
Under Linux you can also use Kile\index{kile} or the way I used to work
was to use \texttt{emacs}\index{emacs} and AUCTeX.
Note that the RefTeX\index{RefTeX} mode in \texttt{emacs} also provides powerful
tools for finding cross-references and the names of citations easily.

An increasingly popular alternative is Overleaf\index{Overleaf}.
If you want to write your thesis using Overleaf,
you first have to upload a zip file of a skeleton thesis as a project.
See \cref{G-sec:app:overleaf} for details on how to set things up and get started.
  
One advantage of such environments is that it is usually
possible to switch between a position in your output file
and the relevant place in the source code and vice versa.
This makes it much quicker to fix
things when you spot an error in your output PDF file. You can usually
also step through the errors when you try to compile your file and fix
them directly. In addition, they know which environments and
mathematical symbols exist, which can speed things up if you have not
been working with \LaTeX\ for the past 20 years!

More details on integrated environments and installing \TeX\ for different systems can be found
in \cref{G-sec:app:tex}.


%------------------------------------------------------------------------------
\section{Do not}%
\label{sec:tips:dont}
%------------------------------------------------------------------------------

\begin{itemize}
\item Don't write symbols differently in math mode and in text. One of
  my pet hates is:
  \begin{displayquote}
  The most famous equation in the world is:
  \begin{equation}
    \label{eq:emc1}
    E = m c^{2}
  \end{equation}
  where E is the energy of the particle and m is its mass,    
  \end{displayquote}
  i.e.\ \(E\) and \(m\) are in math mode in the equation,
  but in text mode in the text where they are explained.

\item Do not start a new paragraph when describing the elements in an equation.
  The equation above is described correctly. Wrong would be:
  \begin{displayquote}
    The most famous equation in the world is:
  \begin{equation}
    \label{eq:emc2}
    E = m c^{2}
  \end{equation}

  \hspace*{1em}where \(E\) is the energy of the particle and \(m\) is its mass.
  \end{displayquote}
  Using the paragraph options of this guide, you add extra vertical space.
  If your paragraphs are indented, \enquote{where} would also be indented.

  If you want to leave a blank line in your \LaTeX\ file for clarity,
  you should make it a comment line, i.e.\ \enquote{\%}.

\item Another example of how not to write things is something like
  \enquote{The scale factor, SF, used to correct the MC is determined in
  an independent dataset using \(SF = N_{data} / N_{MC}\)}. Note the
  wrong font and spacing of \(SF\), \(data\) and \(MC\). All should be
  enclosed in \Macro{text}: \(\text{SF} = N_{\text{data}} / N_{\text{MC}}\).

\item Do not include the directory (or at least the top-level directory)
  or the extension of the file in \Macro{includegraphics} commands.
  Use \Macro{graphicspath}
  instead to set up a list of directories that hold the
  figures.\index{figures!directories} Let \LaTeX{} or pdf\LaTeX{} pick
  the extension for the figure, so that you can (in principle) easily
  switch between the two.

\item Do not use the old font commands \Macro{rm}, \Macro{tt}, \Macro{sc} etc.
  If you are running a recent version of \TeXLive, you may have seen warnings of the form:
  {\small
  \begin{verbatim}
  Class scrartcl Warning: Usage of deprecated font command `\sc'!
  (scrartcl)              You should note, that in 1994 font command `\sc' has
  (scrartcl)              been defined for compatibility to Script 2.0 only.
  (scrartcl)              Now, after two decades of LaTeX2e and NFSS2, you
  (scrartcl)              shouldn't use such commands any longer and within
  (scrartcl)              KOMA-Script usage of `\sc' is definitely deprecated.
  (scrartcl)              See `fntguide.pdf' for more information about
  (scrartcl)              recommended font commands.
  (scrartcl)              Note also, that KOMA-Script will remove the definition
  (scrartcl)              of `\sc' anytime until release of about version 3.20.
  (scrartcl)              But for now, KOMA-Script will replace deprecated `\sc'
  (scrartcl)              by `\normalfont \scshape ' on input line 94.
  \end{verbatim}
  }
  If you have \TeXLive 2016 or later, you will find that KOMA-Script has gone ahead with its threat
  and \Macro{sc} etc.\ now give errors and compilation stops!
  Instead you should use \Macro{textsc} etc.
  You should also use \verb|\mathcal{L}| instead of \verb|{\cal L}|.
  A nice, brief explanation of the differences can be found in \foreignlanguage{ngerman}{\enquote{Das \LaTeX2e\ Sündenregister}},
  which you can find with the command \texttt{texdoc l2tabu}.
  The English variant is called \enquote{An essential guide to \LaTeX2e\ usage: Obsolete commands and packages}
  and can be found with the command \texttt{texdoc l2tabuen}.
  I highly recommend you read this document to find out what constructs you should avoid in your documents.
  You can read the font guide by giving the command \texttt{texdoc fntguide}.

\item Do not try to end paragraphs with
  \textbackslash\textbackslash. 
  Outside tables, these should be used sparingly when
  for some reason you really have to start a new line.
  Just leave an empty line for a new paragraph.

\item Do not draw conclusions or interpret figures in the caption. The
  caption should just describe what is in the figure. Interpretation
  belongs in the main body of the text.

\item Do not start trying to format figure and table captions inside
  each caption -- use the options available in \KOMAScript{} to set
  such things at the beginning of the document.

\item Do not worry about overfull boxes, positions of figures
  and tables, etc.\ until you reach the final version of your thesis.
\end{itemize}


%------------------------------------------------------------------------------
\section{Units}%
\label{sec:tips:units}\index{units}
%------------------------------------------------------------------------------

As mentioned above, but I'll say it again just to make the point,
one of my pet hates is inconsistent and poor typesetting and spacing
of units. At least three standard packages exist to solve this
problem: \Package{siunitx}, \Package{SIunits} and \Package{units}. My
favourite is \Package{siunitx} as it offers many extra features in
addition to the correct typesetting of numbers and their units.
Information on the other (older) packages has been relegated to
\cref{G-sec:app:tips:units}.


%------------------------------------------------------------------------------
\subsection{siunitx package}%
\label{sec:tips:siunitx}\index{siunitx}

This package is a more modern and complete package than either
\Package{SIunits} or \Package{units}.

One very attractive feature is that it allows you to format
computer-generated numbers
such as \verb+1.4E4+ automatically:
\begin{tcblisting}{}
\num{1.4E4}\\
\num[exponent-product=\cdot]{-3.4E-6}\\
\qty{2.99467E8}{\metre\per\second}\\
\qty[round-mode=places,round-precision=1]{2.99467E8}{\m.\s^{-1}}
\end{tcblisting}
\noindent
Depending on the language or using the option \Option{exponent-product}
you can change the way exponents are output.
It is even possible to set the number of decimal places
using the rounding abilities.
The last two examples only differ by the use of the \Option{round-mode} and
\Option{round-precision} options, and even rounds correctly!

Another extremely nice feature of the package is that you can typeset
numbers in a single way and then a full stop or a comma will be used
as the decimal point, depending on which language you set for your
document. This means that computer generated decimal numbers can be
output with commas in a German thesis just by changing the language of
your thesis -- this for me is \LaTeX{} at its best! For example:
\begin{tcblisting}{}
\num{1.2345E-3}\\
\foreignlanguage{ngerman}{\num{1.2345E-3}}
\end{tcblisting}
\noindent
where the 1st example is in the default language of the document and
the second says that this piece of text is in German
(\Option{ngerman} to be exact).

In keeping with \LaTeX{} philosophy, you can specify a number and its
error:
\begin{tcblisting}{}
\num{2.88(32)}\\
\num[separate-uncertainty=false]{2.88(32)}\\
\num{2.88(32)E-3}
\end{tcblisting}
The 1st example uses \Option{separate-uncertainty} option
(which I specify), while the 2nd uses the package default
(given here as \Option{separate-uncertainty=false}).
Errors and powers can also be combined.
You also give as
an option how units with negative powers of units should be shown,
e.g.\ per second. This can be changed for a single command.

Some examples are given below:
\begin{tcblisting}{}
\(c\) is \qty{3E8}{\metre\per\second}\\
\(c\) is \qty[per-mode=fraction, fraction-function=\sfrac]{3E8}{\metre\per\second}\\
\(c = \qty[per-mode=symbol]{2.99E8}{\metre\per\second}\)\\
\(\hbar\) is \qty{1.054E-34}{\joule.\second}
\end{tcblisting}
\noindent
The 1st example uses the default \Macro{per},
while the 2nd example uses\\
\Option{per-mode=fraction, fraction-function=\Macro{sfrac}}.
The 3rd example shows that it does not matter whether one is in math mode or not
and uses \Option{per-mode=symbol}.
You use \enquote{.} or \enquote{,} to make a space between the units,
as illustrated in the last example.

Angles are also very straightforward:
\begin{tcblisting}{listing side text}
\ang{90}
\end{tcblisting}

If you want to write something like \qty[parse-numbers=false]{90(99)}{\%},
include the option \Option{parse-numbers=false} with the \Macro{SI} command,
so that it does not try to interpret \num[parse-numbers=false]{90(99)}:
\begin{tcblisting}{listing side text}
\qty[parse-numbers=false]{90(99)}{\%}
\end{tcblisting}

If you also want to use \Package{siunitx} in slides, where one usually
uses a sans serif font, you may at first be disappointed that
\Package{siunitx} uses a serif font for the units! Do not despair!
You can use the command
\Macro{sisetup}\texttt{\{detect-family=true\}}
to ensure that the package uses the current font
(in all its aspects) rather than its default.

Have a look at the manual, \texttt{texdoc siunitx}, for many more
examples. \Package{siunitx} also contains useful and powerful tools
for typesetting tables and as mentioned above can be used to round
numbers. These aspects are discussed in \cref{G-sec:table}.

Version 3 of \Package{siunitx} replaces \Macro{SI} with \Macro{qty}
and \Macro{si} with \Macro{unit}.
This version was released in June 2021,
so it might take a while before you are affected by this change.
The old macro names will continue to work.

Note that the \Macro{clight} symbol that is used in the macro
\Macro{MeVovercsq} to produce \unit{\MeVovercsq} is defined as \(c_{0}\) in
\Package{siunitx} version 2. As this is not the way it is usually
written in particle physics I redefined it using one of the following:
\begin{tcblisting}{listing only, hbox}
\DeclareSIUnit\clight{\text{\ensuremath{c}}}   % siunitx version 2
\DeclareSIUnit\clight{\ensuremath{\mathit{c}}} % siunitx version 3 (after 2021/04/09)
\end{tcblisting}

%------------------------------------------------------------------------------
\subsection{Rounding and numbers with asymmetric errors}%
\label{sec:tips:pmerr}\index{asymmetric errors}\index{errors!asymmetric}

Two things that are currently not built into the \Package{siunitx} package
are separate statistical and  systematic errors and asymmetric errors.
In addition it may be desirable to round the numbers.
From the author I got some suggestions on how to define such things.
They can be included by passing the option \Option{numerr} to 
\Package{ubonn-thesis}.
This option defines several new macros:
\begin{itemize}
  \item \Macro{numR}, \Macro{numRF} and  \Macro{numRP}
    for rounding numbers.
    \Macro{numRF} uses a fixed number of digits,
    whose value can be  given as an optional argument.
    \Macro{numRP} does the same, but with a fixed number of decimal places.
    For \Macro{numR} you specify the rounding mode (and any other options)
    using \Macro{sisetup} before calling it.
  \item \Macro{numpmerr} can be used to pass the rounding precision
    as the first optional argument and the mode as the second optional argument.
  \item \Macro{numerrt}, \Macro{numpmerrx} and \Macro{numpmerrt}
    can be used to write errors with a description,
    which are asymmetric and both, respectively.
    Any \Package{sisetup} options can be passed as the first (optional) argument.
  \item The corresponding macros for values and errors are
    \Macro{qtypmerr}, \Macro{qtyerrt}, \Macro{qtypmerrx} and \Macro{qtypmerrt}. For the macros
    whose names end with \enquote{\texttt{t}}, you also have to provide
    the descriptive text.
  \item If you have two errors then use \Macro{qtyerrtt}
    or \Macro{qtypmerrtt}, which have one or two more arguments, respectively.
  \item For the standard case of statistical and systematic
    errors, you can use the macros \Macro{qtyerrs} and
    \Macro{qtypmerrs}.
\end{itemize}
For all the macros except \Macro{numRF}, \Macro{numRP}
\Macro{numpmerr} and \Macro{qtypmerr}
the first (optional) argument can be used to pass any options you like to
the \Macro{num} command.

Examples of the rounding macros' usage are:
\begin{tcblisting}{}
\sisetup{round-precision=3}
\begin{tabular}{ll}
  \numR{1234.5678}\\
  \numRF{1234.5678} & \numRF[2]{1234.5678}\\
  \numRP{1234.5678} & \numRP[2]{1234.5678}\\
\end{tabular}
\end{tcblisting}

Examples of the asymmetric error macros are:
\begin{tcblisting}{}
\renewcommand{\arraystretch}{1.4}
\begin{equation*}
\begin{array}{lll}
  \numpmerr{+0.1234}{-0.4567} & \numpmerr[2][places]{+0.1234}{-0.4567} &
  \numpmerrx[round-mode=places, round-precision=2]{+0.1235}{-0.4568}\\
  \numpmerrt{+0.1234}{-0.4567}{stat.} & \numpmerr[2]{+0.1236}{-0.4569}\,\text{(stat.)} &
  \numpmerrt[round-mode=places, round-precision=2]{+0.1237}{-0.4560}{sys.}\\
\end{array}
\end{equation*}
\end{tcblisting}

Examples of the quantities macros are:
\begin{tcblisting}{}
\begin{align*}
  \sigma & = \qtyerrs{3.42}{0.46}{0.32}{\pico\barn} & \Macro{qtyerrs}\\
  \sigma & = \qtyerrs[round-mode=places, round-precision=1]{3.43}{0.46}{0.32}{\pico\barn} & \Macro{qtyerrs}\\
  \sigma & = \qtyerrt[round-mode=places, round-precision=2]{3.43}{0.46}{stat.}{\pico\barn} & \Macro{qtyerrt}\\
  \sigma & = \qtyerrtt{3.43}{0.46}{stat.}{0.32}{sys.}{\pico\barn} & \Macro{qtyerrtt}\\
  \sigma & = \qtypmerr{3.44}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerr}\\
  \sigma & = \qtypmerr[2][figures]{3.45}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerr}\\
  \sigma & = \qtypmerrx[round-mode=figures, round-precision=2]{3.46}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerrs}\\
  \sigma & = \qtypmerrt{3.47}{+0.46}{-0.32}{stat.}{\pico\barn} & \Macro{qtypmerrt}\\
  \sigma & = \qtypmerrs{3.48}{+0.46}{-0.32}{+0.06}{-0.04}{\pico\barn} & \Macro{qtypmerrs}\\
  \sigma & = \qtypmerrtt{3.49}{+0.46}{-0.32}{stat.}{+0.06}{-0.04}{sys.}{\pico\barn} & \Macro{qtypmerrtt}
\end{align*}
\end{tcblisting}
The last two examples use \Macro{qtypmerrs} and \Macro{qtypmerrtt} just
to show that they can both give the same output. If you need even more
complicated combinations of errors, or more errors, have a look at the
definitions, e.g.
\begin{tcblisting}{}
\begin{equation*}
  \sigma_{t\bar{t}} = (\num{164.6}%
  \valuesep\numerrt{8.7}{stat.}%
  \valuesep\numpmerrt{+6.4}{-5.3}{sys.}%
  \valuesep\numerrt{8.2}{lumi.})%
  \valuesep\unit{\pico\barn}
\end{equation*}    
\end{tcblisting}

Rounding\index{rounding} is very nice and works well, but can slow down compilation considerably.
More discussion on rounding can be found  in \cref{G-sec:table:siunitx}.

Details of the arguments for all the macros can be found in \cref{tab:numerr,tab:qtyerr}.

\begin{table}[htbp]
  \caption{Arguments of error macros.
  \enquote{prec} is short for the \Option{rounding-precision},
  \enquote{mode} for the \Option{rounding-mode}.
  Columns that start with \enquote{m} mean mandatory arguments.}
  \label{tab:numerr}
  \begin{tabular}{lllll}
    Macro & Options & m1 & m2 & m3 \\
    \Macro{numR}      & [sisetup]   & value & error \\
    \Macro{numRF}     & [prec] & value & error \\
    \Macro{numRP}     & [prec] & value & error \\
    \Macro{numpmerr}  & [prec] [mode] & value & err+ & err-\\
    \Macro{numpmerrx} & [siunitx] & value & err+ & err-\\
  \end{tabular}
\end{table}

\begin{table}[htbp]
  \caption{Arguments of quantity macros.
  \enquote{prec} is short for the \Option{rounding-precision},
  \enquote{mode} for the \Option{rounding-mode},
  \enquote{desc} is short for the description of what the error is,
  \enquote{stat.} is short for statistical error,
  \enquote{sys.} is short for systematic error/
  Columns that start with \enquote{m} mean mandatory arguments.}
  \label{tab:qtyerr}
  \begin{tabular}{ll lllllll l}
    Macro & Options & m1 & m2 & m3 & m4 & m5 & m6 & m7 & m8\\
    \Macro{qtypmerr} & [prec] [mode] & value & err+ & err- & unit\\
    \Macro{qtypmerrx} & [sisetup] & value & +err & err- & unit\\
    \Macro{qtyerrt} & [sisetup] & value & error & desc & unit\\
    \Macro{qtyerrtt} & [sisetup] & value & error & desc
      & error & desc & unit\\
    \Macro{qtypmerrt} & [sisetup] & value & err+ & err- & desc & unit\\
    \Macro{qtypmerrtt} & [sisetup] & value & err+ & err- & desc
      & err+ & err- & desc & unit\\
      \Macro{qtyerrs} & [sisetup] & value & stat. & sys. & unit\\
      \Macro{qtypmerrs} & [sisetup] & value & stat.+ & stat.- & sys.+ & sys- & unit\\
    \end{tabular}
\end{table}

Note that the option \Option{numpmcorr} can be used to make the superscript and the subscript
have the same width.
This is needed as in some fonts \enquote{\(+\)} and \enquote{\(-\)} have a different width.
This option is enabled by default as pdf\LaTeX\ has this problem.
It is not needed (and slows things down) for \LuaLaTeX\ and \XeLaTeX.

%------------------------------------------------------------------------------
\section{Definitions in particle physics}%
\label{sec:tips:hepparticles}
%------------------------------------------------------------------------------

At some point the CERN Computer Newsletter claimed that all particles should be written
upright, e.g.\ \(\text{Z}\) boson, \(\text{b}\) quark.
However, nowadays it seems to be much more common to use italics.
This is also how the particles are written in the PDG\@.
While ATLAS usually uses italics, CMS (and the CERN Courier) use upright letters.

If you use the \Package{hepnicenames}, \Package{heppennames} or \Package{hepparticles} packages,
you can use the option \Option{italic} to switch from upright and italics.
This is of course very nice!
You just have to get used to the conventions used there for particle names.
Many particles are available in \Package{hepnicenames},
while \Package{heppennames} is more complete.
Note that there is a bug in the
\Package{hepnicenames}, \Package{heppennames} and \Package{hepparticles} packages
as of \TeXLive 2019.
Upright particles are not printed.
I have a solution to the problem,
but it has not yet made it to the official version.

\noindent\textbf{Some examples from \Package{heppennames}:}
\begin{tcblisting}{listing side text}
\Pe, \Pl, \Pqt, \Paqt\\
\PZ, \PWpm\\
\PBz, \PBpm, \PacB\\
\PBz{}\PBz, \PBz\PBz
\end{tcblisting}

\noindent\textbf{Some examples from \Package{hepnicenames}:}
\begin{tcblisting}{listing side text}
\APelectron, \Plepton, \Ptop, \APtop\\
\PZ, \PWpm\\
\PBzero, \PBpm, \APBc\\
\PBzero{}\PBzero, \PBzero\PBzero
\end{tcblisting}

You can use commands like \Macro{HepParticle} to define particles that are missing.
There are also macros for antiparticles and supersymmetric particles.
If you define particles yourself,
I would recommend one of the following definitions:
\begin{tcblisting}{listing only}
\newcommand*{\Zo}{\ensuremath{Z}\xspace}
\newcommand*{\Zo}{\ensuremath{\text{Z}}\xspace}
\newcommand*{\bbarQ}{\ensuremath{\bar{b}}\xspace}
\newcommand*{\bbarQ}{\ensuremath{\bar{\text{b}}}\xspace}
\end{tcblisting}
\index{particles}
\noindent
which produce \ensuremath{Z}, \ensuremath{\text{Z}},
\ensuremath{\bar{b}}, \ensuremath{\bar{\text{b}}}. Note that you are
not allowed to include numbers in the names of commands, so
\Macro{Z0} or \Macro{U1S} are not valid commands.
For \(\overline{B}^{\pm}_{c}\) and other particles whose names are capital
letters, it can be debated whether it better to use
\Macro{overline} than \Macro{bar}.
Compare \(\overline{B}^{\pm}_{c}\) and \(\bar{B}^{\pm}_{c}\).
If you use upright letters the choice is maybe
easier: \(\overline{\text{B}}^{\pm}_{\text{c}}\) and
\(\bar{\text{B}}^{\pm}_{\text{c}}\) or
\(\overline{\text{K}}^{0}_{\text{S}}\) and
\(\bar{\text{K}}^{0}_{\text{L}}\).
\Package{hepparticles} tries to tweak the size of the bar to make it look good.

Another problem is that, depending on the font you use, the spacing between \enquote{e} and \enquote{V}
on \unit{\eV} and its derivatives, e.g.\ \unit{\GeV}, can be larger than you would like.
As this is font dependent the \Package{siunitx} package does not try to fix this.\footnote{%
A discussion of this can be found in
\url{http://tex.stackexchange.com/questions/219854/can-i-declare-a-new-automatic-kern-for-ev-without-modifying-font-metrics}.}
The \Package{ubonn-thesis} package contains an option \Option{eVkern} that introduces a -0.1em kerning,
i.e.\ shift of \enquote{V} closer to \enquote{e} by 0.1em, which you can turn on if necessary.


%------------------------------------------------------------------------------
\section{Hints}%
\label{sec:tips:hints}
%------------------------------------------------------------------------------

\Package{xspace} is great, but how do you write \(B^{0}\bar{B}^{0}\) when
you have defined the symbols \Macro{Bo} and \Macro{Bobar} with
\Macro{xspace} at the end. Here you need \verb+{}+ between the two
commands, e.g.\ \verb+\Bo{}\Bobar+ produces \Bo{}\Bobar while
\verb+\Bo\Bobar+ produces \Bo\Bobar.

How should you write \enquote{between \(10^{4}\) and \(10^{5}\)}?\index{range}
If you use math mode it looks like \(10^{4} - 10^{5}\), which is not
really what you want.
Although it is rather clumsy, the best way to do
it is \verb+\(10^{4}\)--\(10^{5}\)+ which produces
\enquote{\(10^{4}\)--\(10^{5}\)}.

With \Package{siunitx} and \Macro{num} there is a built-in option.
You simply write
\begin{tcblisting}{listing side text}
\numrange{3e4}{7e4}
\end{tcblisting}
You can steer how often the units are written out:
\begin{tcblisting}{}
\qtyrange[range-units=repeat, range-phrase=--]{5}{7}{\GeV}\\
\qtyrange[range-units=single, range-phrase=--]{5}{7}{\GeV}\\
\qtyrange[range-units=brackets, range-phrase=--]{5}{7}{\GeV}
\end{tcblisting}
In a single range, such settings are rather long-winded!
However, they can be applied to the whole
document using the \Macro{sisetup} macro.

A similar problem is how do you write \enquote{about 10\%}?  Again the
simple solution \(\sim 10\%\) or \(\sim\) 10\% have too much space. In the
file \texttt{thesis\_defs.sty} two macros \Macro{mysim} and
\Macro{mysymeq} are defined that add some negative space so that you
can simply put everything in math mode: \(\mysim 10\%\) or \(\mysimeq 0.2\).
An alternative is to use \Macro{SI} or \Macro{unit}, as there
should actually be some space between the number and the \% sign,
e.g.\ \verb+\(\sim\)\qty{10}{\%}+, which produces \(\sim\)\qty{10}{\%}, is
completely correct and does not need the use of \Macro{mysim}.

What is the difference between \Macro{textrm} and
\Macro{mathrm}? I used to worry about this and found a
few examples (which I then forgot) where the font size was better
using one or the other. Then I learnt about \Macro{text},
converted all my predefined symbols to use \Macro{text} rather than
\Macro{mathrm} or \Macro{textrm}, and don't have to worry any
more.
Having played around with using a sans serif font in the main document I understand the differences better.
\Macro{text} uses the standard text font,
while \Macro{mathrm} and \Macro{textrm} use the math font.
In documents like your thesis, these are usually the same,
so you do not see any difference.
If your text font is sans serif, as in University of Bonn letters,
and you use a serif math font, then you will see a difference.
I can given an example for the definition
of the transverse energy of the highest energy jet:
\begin{tcblisting}{}
\(p_{\mathrm{T}}^{\mathrm{1^{\text{st}} jet}}\)\\
\(p_{\textrm{T}}^{\textrm{1}^{\text{st}}\textrm{ jet}}\)\\
\(p_{\text{T}}^{1^{\text{st}}\text{ jet}}\)
\end{tcblisting}
As you can see
from this example, the key difference is that \Macro{mathrm} switches
to an upright font, but keeps you in math mode -- hence ignoring any
spaces.
\Macro{textrm} switches to text mode (with a serif font) and
therefore pays attention to spaces.
You cannot use a superscript or subscript inside \Macro{textrm},
as it is for text mode.
The 3rd example uses \Macro{text}, which is my preferred solution.

A perennial problem is bold math\index{math!bold} when it is needed in
section headings etc. This is further complicated by the fact that the
table of contents is usually not typeset using a bold font (except for
chapter titles, or whatever the highest level(s) of sectioning are). % chktex 36
One way to get this right in both cases is to give the
heading twice, once with \Macro{boldmath} for the real title and once
without as the optional title for the table of contents.
An alternative solution is to add the command\\
\verb|\def\bfseries{\fontseries\bfdefault\selectfont\boldmath}|.
As of version 3.0 of \Package{ubonn-thesis} this command is included,
so \Macro{boldmath} should no longer be needed.
An illustration of how this works is given in \cref{G-sec:emc2}.
Note that this fix does not work for \LuaLaTeX and \XeLaTeX and so is not applied.
\Cref{G-sec:emc2} illustrates ways of getting around the problem.

For math mode the official \LaTeX\ macro is \verb|\(...\)|.
\verb|$...$| is the \TeX\ primitive.
It is therefore recommended to use \verb|\(...\)| for inline equations etc.,
although it must be said that probably well over \qty{90}{\%} of people still use \verb|$...$|.
There still seem to be a few cases when \verb|\(...\)| leads to errors.
This sometimes happened for \TeXLive versions from 2013 or earlier
when used in figure or table captions.


%------------------------------------------------------------------------------
\section{Common English mistakes}%
\label{sec:tips:english}\index{English mistakes}
%------------------------------------------------------------------------------

Several constructs are often used by German (and other non-native) speakers
that are not grammatically correct in English.
Additions to the list are welcome.
These are the ones I remember coming across so far:
\begin{itemize}
\item \enquote{He has been living here since five years.}
  Correct: \enquote{\emph{He has been living here for five years.}}
  An example of the correct use of \enquote{since}:
  \enquote{Since becoming ATLAS spokesperson he has implemented \ldots.}
\item \enquote{This allows to measure \(m_{\PH}\) very accurately.}
  Correct: \enquote{\emph{This allows \(m_{\PH}\) to be measured accurately.}}
  See comment below about \enquote{fluff}.
\item \enquote{The table contains lots of informations.}
  Correct: \enquote{The table contains a lot of information.}
\item \enquote{The table contains a lot of information, that is redundant.}
  Correct: \enquote{\emph{The table contains a lot of information that is redundant.}}
  You do not need a comma before \enquote{that} in English.
\item \enquote{The main topics to discuss include: Building a new detector; \ldots}
  Correct: \enquote{\emph{The main topics to discuss include: building a new detector; \ldots}}
  In British English you should not capitalise the word after a colon.
  In American English it is often capitalised.
\item \enquote{less} and \enquote{fewer}: use \enquote{fewer} for things that you can count and
  \enquote{less} for things you cannot count: \enquote{less energy} and \enquote{fewer jets}.
\item \enquote{The interaction occurs with a highly energetic hadron.}
  Correct: \enquote{\emph{The interaction occurs with a high energy hadron.}}
  One could argue that: \enquote{\emph{The interaction occurs with a high-energy hadron.}}
  is even better, as it makes clear that \enquote{high} is describing the energy of the hadron.
\item \enquote{Energy is measured in the hadronic calorimeter.}
  Correct: \enquote{\emph{Energy is measured in the hadron calorimeter.}}
  This is somewhat controversial.
  There are in fact ATLAS publications that use the term \enquote{hadronic calorimeter}.
\item \enquote{We are not sensible to this effect.}
  Correct: \enquote{\emph{We are not sensitive to this effect.}}
\item \enquote{We have to choose between Xenon (Xe)  and Argon (Ar).}
  Correct: \enquote{\emph{We have to choose between xenon (Xe) and argon (Ar).}}
\item \enquote{We loose \qty{50}{\%} of the signal due to this cut.}
  Correct: \enquote{\emph{We lose \qty{50}{\%} of the signal due to this cut.}}
\item  \enquote{\emph{Its uncertain what its meaning is}}
  Correct: \enquote{It's uncertain what its meaning is.}
  In the first usage \enquote{it's} is short for \enquote{it is}.
\item \enquote{\emph{Explain how the drawing looks.}}
  Correct: \enquote{Explain what the drawing looks like.}
\item \enquote{\emph{He raises the stone above his head to get a pay raise.}}
  Correct: \enquote{He raises the stone above his head to get a pay rise.}
\item \enquote{\emph{The agreement is well and the data are good described by the simulation.}}
  Correct: \enquote{Good agreement is seen and the data are well described by the simulation.}
\end{itemize}

A general comment (which also applies to theses in other languages) is that you should avoid \enquote{fluff}.
A statement that is often attributed to Mark Twain\footnote{%
See \url{https://quoteinvestigator.com/2012/08/29/substitute-damn/} for a discussion of the source.}:
\begin{quote}
  Substitute \enquote{damn} every time you're inclined to write \enquote{very};
  your editor will delete it and the writing will be just as it should be.
\end{quote}
This also (\enquote{damn!}) applies to other similar words such as \enquote{also, really}.
Common usage of fluff is in statements like \enquote{very high energy},
which can be properly written as just \enquote{high energy} without compromising content.
What does the \enquote{very} add if it is not compared to anything?
If it is compared, why not choose a better adjective?

Although a case can be made for name assignment used with \enquote{so-called},
it makes more sense for proper assignment to use
\enquote{called}, \enquote{defined as} or \enquote{referred to as}.
\enquote{So-called} is typically used to indicate that a name assigned is not entirely true or in fact wrong.
For example, one could say \enquote{wrongly identified and non-prompt leptons,
so-called fake leptons, are estimated \ldots}
This is because non-prompt leptons are not fake leptons in reality,
but are often grouped under the same \enquote{fake lepton} umbrella term.
One should not use \enquote{so-called} to define or give a proper name.
For example, \enquote{when charged particles pass through gasses,
they induce charges in the gas material that can be measured, so-called ionization} is incorrect.
Correct: \enquote{\emph{The induction of charge in gasses in this manner 
is one definition of ionization.}}
or \enquote{\emph{when charged particles \ldots can be measured,
\enquote{referred to as} or \enquote{called ionization}.}}
 
To  make matters more complex, \enquote{so-called} should not be confused with \enquote{so called}, unhyphenated.
This is no longer an adjective but it is now a combination of an adverb and a verb!
In this way, \enquote{so called} essentially means \enquote{it is called this way because}.
For example, \enquote{\emph{ATLAS is an general-purpose detector;
  it is so called because it has means to detect and measure the broadest possible range of signals.}}

One further important point: decide early on if you are going to write your thesis in American or British English.
Typical American spellings include: \foreignlanguage{USenglish}{center, flavor, color, hadronize}.
The British English spellings are: centre, flavour, colour, hadronise.
Choose one or the other and do not mix them.
Note that the conventions on punctuation and where it is placed relative to quotes
are different in American and British English.

You should also decide how to capitalise your chapter and section headings.
You can either capitalise just the first word (and proper names and acronyms),
or every important word.
Most journals have moved to the first option,
but there are some that use the latter (most notably APS journals).
Both are fine -- just be consistent!

%------------------------------------------------------------------------------
\section{Line numbering}%
\label{sec:tips:lineno}\index{lineno}\index{line numbers}
%------------------------------------------------------------------------------

This is a very useful package that may be useful when writing your thesis
and occasionally has some problems.
Hence, I thought I would include some information here.
Pass the option \Option{lineno=true} to \Package{ubonn-thesis} to get line numbers.
This will only turn on line numbers when in \Option{Draft} mode.

\begin{figure}[htbp]
  \centering
  \begin{tabular}{cc}
  \includegraphics[width=7cm]{BCDijet} &
  \includegraphics[width=7cm]{BCDijet-linenomath}\\
  (a) & (b)
  \end{tabular}
  \caption{Example of (a) a problem with line numbers and (b) its solution.}%
  \label{fig:lineno}
\end{figure}

Sometimes a block of lines is not numbered -- see \cref{fig:lineno}a.
Such problems are associated with text that is close to math mode environments.
Most of the problems can be solved by using a new
version of the \Package{lineno} package.
However, while this works for \enquote{standard} \LaTeX{}
math environments: \Env{displaymath}, \Env{equation} and \Env{eqnarray},
it may not work for recommended \Package{amsmath} environments such as \Env{equation*},
\Env{align(*)} and \Env{alignat(*)}. % chktex 36
If the option \Option{linenofix} is set, which is default,
then it should also work for these environments.
If this option causes other problems turn it off and use the solution below.

Enclose the equation in \Env{linenomath} environment, e.g.
\begin{tcblisting}{listing only}
The total visible cross section for inclusive heavy-quark jet
production, \(\sigma^{q}\), with \(q\in\{b,c\}\) is given by
\begin{linenomath}
\begin{equation*}
  \sigma^{q} = \frac{N_{q}^{\text{rec,Data}}}%
    {\mathcal{A}_{q}\cdot\mathcal{L}_{\text{Data}}}.
\end{equation*}
\end{linenomath}
Here, \(\mathcal{L}_{\text{Data}}=\) denotes the integrated luminosity,
\(\mathcal{A}_{q}\) is the acceptance and \(N_{q}^{\text{rec,Data}}\) the
number of reconstructed heavy-quark jets in data, which was determined
\end{tcblisting}
\noindent
Then the line numbering will be correct, see \cref{fig:lineno}b.


%------------------------------------------------------------------------------
\section{Updating \Package{ubonn-thesis}}%
\label{sec:tips:update}\index{updating}\index{ubonn-thesis!updating}
%------------------------------------------------------------------------------

When you make a new thesis skeleton (as of version 2.1) the files
\File{ubonn-thesis.sty} and \File{ubonn-biblatex.sty} are copied
to your \texttt{mythesis} directory.
As of version 6.0, your \File{mythesis} directory should be completely standalone
and does not rely on any files in the parent directory.
If you want to profit from updates to \Package{ubonn-thesis},
you therefore need to copy the new version into \texttt{mythesis} again.
The advantage of this scheme is
that you can easily check what the differences are before you do the
copy. More importantly, if you have made your own changes to the style
file, it should be relatively easy to merge the two versions. Having
all files in the \texttt{mythesis} subdirectory also makes it much easier
for you to use your own version manager for your thesis.

What is therefore the best way to update \Package{ubonn-thesis}?
If you are using Git, then you first need to do a \Command{git pull}
in the \File{ubonn-thesis} directory.
If you use a tar file, then you should unpack it and copy over your
\texttt{mythesis} directory tree to the new \File{ubonn-thesis} tree.
As of version 6.0, you can then use a command like
\Command{make update THESIS=mythesis} to copy the style files,
the bib file with the standard references and the covers to your
\File{mythesis} directory.
You will be asked before existing files are overwritten.
% If you overwrite the \File{Makefile} make sure you update the value of \Command{THESIS} afterwards.
The \File{Makefile} is not updated in this process (as of version 9.1),
as changes to it are only rarely made,
and you may have adapted it to your use.
Have a look at \File{thesis\_skel/Makefile} to see if there are any updates to the \File{Makefile} that you should also include.

If you are using Overleaf\index{Overleaf}, you can try to download the project as a zip file,
unpack it into a subdirectory of \File{ubonn-thesis},
apply the changes you want to make,
make a zip file of it again
and import the zip file of the project back into Overleaf.
Otherwise, you will have to make any relevant changes by hand.
Have a look at the \File{Makefile} to see which files I normally try to update.

As a side remark, I would also recommend that you put all Feynman
graphs etc.\ in subdirectories of \texttt{mythesis}. You may have to
change some variables that are set at the beginning of the
\texttt{Makefile} so that this works if you use \Package{feynmf}. If
you use \Package{feynmp} just add \Macro{write18} statements.
See \cref{G-sec:fig:feynman} for some more details.

\end{document}
