Ok, you have arrived at that moment in which you have to “write”.

My (but not only mine) suggestion is to start simple, and build-up over multiple passes. Don’t try to write an entire thesis straight from scratch, and don’t try to write it expecting it already “in the final form”. Rather, start with titles, sections, and notes on what you want to add to each of them. Would you have figures, prepare some sketches (I like to draw them on my drawing tablet), and fill them in. Do you have preliminary plots? Add them as mere screenshots, it would help to build the “here is what I want to have”, and it will help to structure the final document better.

LaTeX, Overleaf, and git

Whether you are preparing a random workshop paper, a project report, a thesis, or a thesis, it’s strongly suggested (read: do that!) to write it using LaTeX. Although, simpler reports can be done much easier with pandoc, here some tips.

The separation of “content” and “aspect” of LaTeX allows to focus on the content, rather than the aspect. That would come after, and usually it’s somewhat beautiful enough automatically. Is your report becoming an article? And later part of your thesis? By careful use of \input you can reuse the same text, same formatting, and same figures in all documents, with minimal changes.

So when you start, don’t look immediately for “the right template”. Just start writing!

A little rant

Nowadays most people like to think LaTeX = Overleaf, following the same trend of git = GitHub. While Overleaf is great and simplify collaboration, especially when interacting with multiple authors, or when reviewing a document thanks to the ability to comment the source and track history, it has limits.

Of course with “two clicks” you are ready to compile your PDF without messing with a LaTeX installation, but if you want to do anything a bit more complex, you may hit some limitations.

One of the main issues is the “single window” editing, which by default doesn’t allow you to work with two panes or two different files open, as you would in any modern editor or IDE. Maybe you don’t need it when you start, but it becomes extremely useful when re-organizing text from other documents, or when moving contents around.

Have you tried Overleaf support for handling bibliography? Wouldn’t it be so nice if you could sync with your local Zotero installation?

Or perhaps you have your figures generated by scripts, and every time you need to manually upload to the correct path with the correct naming. If only there was some way to import and update them automatically…

And wait when you discover that Overleaf can be “down” for whatever technical reason, or that you cannot access your files while your are on a plane.

Have you read their Terms and Conditions? Maybe you’ll find some surprises..

So, please, don’t assume that “I cannot do X because Overleaf doesn’t allow me to do so”, but rather think about “can I do it on my local computer?”. If the answer is “yes”, keep reading.

And I am intentionally ignoring the side of me that would conspire that “Overleaf is just mining unpublished scientific text” for some greater, darker, project. :P

git integration

Overleaf Premium (as available at many institutions) allows you to directly sync with git. This means you can git pull from a Overleaf URL, and git push your changes.

Unfortunately, you don’t have a direct correspondence between Overleaf labels or “history snapshots” and commits, but rather a commit is generated every time you pull. But better than nothing.

Get in the habit to periodically sync with your local computer (e.g. every day), it is also fun (or insightful) later to see the statistics on when and how much you have written everyday.

You can even automate this with a cronjob, or with some automatic tools (shameless plug). I use the latter as an automatic way to backup my documents, between Overleaf and GitHub. It is not the perfect workflows, but it is better than nothing.

And it’s better than the manual built-in GitHub synchronization of Overleaf.

Local compilation

Given you have all the required LaTeX packages installed, and that you are on a Unix-like system, you should be able to compile your document with the following:

latexmk main.tex -xelatex -shell-escape -jobname=licthesis -f -r .latexmkrc-local

where .latexmkrc-local is a file in your folder with the following content:

# Fix generating of glossaries
# Source: https://github.com/overleaf/docker-image/issues/6#issuecomment-282931678

add_cus_dep('glo', 'gls', 0, 'makeglo2gls');
sub makeglo2gls {
    system("makeindex -s '$_[0]'.ist -t '$_[0]'.glg -o '$_[0]'.gls '$_[0]'.glo");
}

add_cus_dep('acn', 'acr', 0, 'makeacn2acr');
sub makeacn2acr {
    system("makeindex -s \"$_[0].ist\" -t \"$_[0].alg\" -o \"$_[0].acr\" \"$_[0].acn\"");
}

This is required to correctly generate your glossary, and depending on your document you may skip it. A complete overview on how Overleaf compile your files is here.

Regularly save the files!

In general, you would have a final document, in G5 format, with black links (otherwise you’ll pay more!). This is what you will later send to the print service, and before that to the other parties involved in the process. Tip: when you compile a file, save it as PDF (don’t assume “I can download it tomorrow”) with a date in your local machine. This would allow to version the files “the old way”. It won’t hurt to sometimes download the document sources as .zip. Better safe than sorry!

Start writing “well”

Books have been written on how to write, how to write well, and how not to write. Beside the actual text that you are writing (e.g. the story), there are few general rules when writing LaTeX that can save headaches later. Here there are some general tips. Refer to some proper style manuals for more details.

Split in chapters/sections/logical units

Don’t write in a single, giant, file. Make use of \input{filename} for all your chapters, at least.

Split lines

Just because modern editors wrap text around the end of the screen, it doesn’t mean you should have 1000 characters lines! Take the habit of adding a “newline” every time you have a dot in your sentence. And use an empty line (or more) to separate paragraphs. If you want later to join paragraphs, use a % in the empty line: you would still see the 2 paragraphs in the source, but they will be rendered as a single one.

Use labels

Start to give meaningful labels to all sections of your document. Something like \label{cha:background} after your \chapter{Background} would help later. For sections, you can add a reference to the chapter they belong (e.g. \label{sec:background:ethernet}). The same is for figures, tables, and every other element that you would “cite”.

If you upgrade the \ref to \Cref, you will get automatically Figure 1.1 instead of manually typing “Figure”. This is provided by the package cleverref.

Citations

Get in the habit to use a non-breakable space ~ beside the last word in a sentence. This would prevent the citation to get alone on a new line. So write in this work~\cite{the_work}..

Footnotes

There are contrasting opinions on where to put footnotes signs. I like the “after punctuation, if any” rule, and no space. So you would write something like:

A PCIe 4.0 x16 slot supports up to 200 Gbps of bandwidth,\footnote{However, when considering ...} while on a PCIe 5.0\footnote{Which is what you can buy today}...

This would be rendered to something like

A PCIe 4.0 x16 slot supports up to 200 Gbps of bandwidth,¹ while on a PCIe 5.0² ...

But what if you have both citations and footnotes in the same sentence? What order to use? I don’t have an answer, I would rewrite the sentence to avoid the dilemma :/.

Please look around and find the style you like the most. But be consistent! You can probably design a complex regex to verify in your files that you used the same order everywhere, or simply ctrl-f for \footnote.

Symbols

Using numbers can be problematic when numbers are used also for references. This would make your footnotes to use symbols instead:

\usepackage[symbol,perpage]{footmisc}

Units, SI prefixes, and numbers

Depending on your level of pedanticism you may want to have all numbers correctly formatted. This can be done with the siunitx package. So every number would become something like \qty{100}{\giga\bps}. You may have to define your units, but this ensure an higher consistency level! Also ranges can be correctly written with the above package.

Glossary

Would you have a glossary in your document, you would have to add some (or many) \gls around your document. You can replace them later, don’t worry.

General style rules

When using LaTeX you are using a tool that is used by professionals, and (hopefully) experts. So, unless you have a good reason to change some embedded rule, don’t.

For instance, don’t change the line width, or randomly the amount of space added at the paragraph start.

Hyphenation, figure placements, and overfullness

TeX creator, Prof. Em. Donald Knuth is very opinionated on some things. But on most of them, he has his motivations.

For instance, LaTeX is built with some mechanisms to automatically split words, or move figures to new pages, and many studies (hopefully - I didn’t really count them) have been done to improve these algorithms. Take advantage of them, and don’t force LaTeX to “go to new line here”, unless you are in the very last version of your document, and that would save a hanging word.

So a general

\hyphenpenalty=5000
\tolerance=1000

should be fine for most documents. It’s of course desirable to disable it in some parts, for instance in your keywords list, or for the table of contents. This can be done with the following syntax (although there may be better ways):

\hyphenpenalty=15000
\tolerance=1000

\tableofcontents

\hyphenpenalty=5000
\tolerance=1000

More rants here.

Emphasize words

When referring to a specific concept, is good to emphasize the subject of the sentence. You should use this with \emph{}, not with \textit{}.

Although in most cases it would be rendered in the same way, it’s possible to redefine what \emph{} means, and it should be seen more like a \gls macro telling the compiler “here there is something different, please take care of it”, rather than “THIS MUST BE ITALIC!”.

Oxford comma

Many style manuals dictate different rules, and you should follow one of them if there are strong opinions in your field. But in general, it’s suggested to use the Oxford comma, before the last coordinating conjuction (e.g. and/or):

CPUs, GPUs, and NICs communicates on the PCIe bus.

Newlines in titles and captions

Sometime you have long titles. And breaking them (as \chapter{Related Works in this\\field that I love so much\\to write a whole book}) it’s not a great idea. Mainly because it would result with the same broken lines also in your PDF index and Table of Contents (where you can have hyphenation perhaps). The proper way to to it is:

\chapter[Related Works in this field that I love so much to write a whole book]
{Related Works in this\\field that I love so much\\to write a whole book}

The [] argument will go in the ToC and index, the {} will go in the actual rendered text “here”.

You should to the same for figures, add a shorter title as [], and a longer, more descriptive, caption in {}.

I KNOW WHAT I WANT. AND I’LL DO IT BETTER THAN WHO WRITE THIS TEMPLATE!

Ok, then let’s see common snippets that I find myself using multiple times.

Fixing hanging sentences

Sometimes a sentence get pushed on a new page, there, alone. It’s bad. Imagine its loneliness.

Imagine you don’t have figures to move around. Most times, you can fix it by rewriting your text. Or in more unorthodox way, with \vspace{-.1cm} around a section header. This would “save” 1 mm around the header, and you can increase until it fits. Normally, the difference is visible, but without abusing of it is still pleasant to the eye.

Colored links

The modern human is used to click on a colored link. By default LaTex won’t highlight them. But hyperref can:

\usepackage[hyphens,url]{hyperref}
\hypersetup{
	colorlinks,
    breaklinks,
    anchorcolor=darkblue,
	citecolor=darkblue,
	filecolor=blue,
	linkcolor=teal,
	urlcolor=darkblue
}

Wait, they want me to pay for color pages!

You should be able to use \usepackage[ocgcolorlinks]{ocgx2}, but that relies on the ability of your pdf processor to remove those. To be “sure” about it, I would generate a different pdf with black links, just for printing. This could be easily done by defining, or not, a macro at the beginning of your file:

\newcommand*{\PRINT}{}

And surrounding all color related commands in an if statement:

\ifdefined\PRINT
    \typeout{GENERATING A PDF FOR PRINT!}
    \hypersetup{
	colorlinks,
    breaklinks,
    anchorcolor=black,
	citecolor=black,
	filecolor=black,
	linkcolor=black,
	urlcolor=black
}
\else
...
\fi

The same could be used when defining an highlighting schema for your code.

Sans-serif titles, but serif ToC

If you are using a random LaTeX class, there is the risk that who designed it didn’t think about corner cases. This could, for instance, result in ugly Table Of Contents, or different styles between different lists (e.g. with Figures).

In most cases, you are already manipulating titles, typically via titlesec, and you should then use titletoc. The following would generate an uniform listing across Content, Figures, Tables, and Codes.

\usepackage{titletoc}

\newcommand*{\tocdots}{0.25pc}
\newcommand*{\tocfont}{\rmfamily}
\titlecontents{chapter}[0em]
{\tocfont\bfseries\hangindent2.7em}
{\thecontentslabel\enspace}
{}
{\tocfont\hfill\contentspage}
[\vskip 4pt]

\titlecontents{section}[1em]
{\tocfont\hangindent2.7em}
{\thecontentslabel\enspace}
{}
{\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]

\titlecontents{subsection}[2.5em]
{\tocfont\hangindent2.7em}
{\tocfont\thecontentslabel\enspace}
{}
{\tocfont\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]


\titlecontents{subsubsection}[4em]
{\tocfont\hangindent2.7em}
{\tocfont\thecontentslabel\enspace}
{}
{\tocfont\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]


\titlecontents{figure}[0em]
{\tocfont\hangindent2.7em}
{\thecontentslabel\enspace}
{}
{\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]

\titlecontents{listing}[0em]
{\tocfont\hangindent2.7em}
{\thecontentslabel\enspace}
{}
{\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]

\titlecontents{table}[0em]
{\tocfont\hangindent2.7em}
{\thecontentslabel\enspace}
{}
{\titlerule*[\tocdots]{.}\contentspage}
[\vskip 4pt]

\renewcommand\lstlistlistingname{List of Codes}

Otherwise, if not titlesec is used, tocloft is good as well.

Footnotes in tables

By default, footnotes in tables won’t be rendered. Use \usepackage{tablefootnote}:

PORT_N\tablefootnote{Where N is an integer number, \eg 1,2,3, ...}

Common macros

If you like to use many “strange old” terms, you may have to italicize them. For instance, many people likes to italicize e.g., i.e., and similar terms. It’s good to define them as macro:

\usepackage{xspace}
\newcommand\ie{\textit{i.e.}\xspace}
\newcommand\eg{\textit{e.g.}\xspace}

This would allow to easily change them later, if needed. xspace should prevent problems related to missing spaces after the macro.

Similarly, for math-like descriptions:

\def\first {$(i)$\xspace}
\def\second {$(ii)$\xspace}
\def\third {$(iii)$\xspace}

Quotes

If you like to have “quoted” sentences (like this one) you may soon realized that a simple " don’t get correctly rendered. You should indeed use the awkward back-tick and apostrophe to correctly enclose some text, see the following example:

However, there is a smarter way. Use the csquotes package, and the \enquote{} macro:

Yes, it’s more keys to press, but it’s easier to keep consistent. And if one day you decide to write in another language, or you want to change the quotes style, it’s a matter of messing around with the package options. In most cases, if your language is set correctly, the style should be already the preferred for your language (so it’s a matter of babel/polyglossia). Otherwise, the package documentation on CTAN should provide better instruction that what found here!

TODO

The todo package is quite useful to highlight missing content.

\todo{Write here about that time you forgot about the default route}

would create a margin-note, by default.

It’s usually better to have these notes in the text body:

\usepackage{todonotes}ô
\let\oldtodo\todo
\renewcommand{\todo}[1]{\oldtodo[inline]{#1}}
}

Images

There are multiple ways, and styles, to include an image in a LaTeX document. But in most cases, this would boil down to \includegraphics command (from graphicx), usually enclosed in a floating figure environment:

\begin{figure}[t]
  \centering
  \includegraphics[width=.95\linewidth]{file.pdf}
  \caption[This is a short caption for ToF]{This is the long description of the figure to appear below it}
  \label{fig:figure_name}
\end{figure}

The [t] in the environment will ask the compiler to place the figure at the top of the page, but without forcing it. A common combination is [thp], which would attempt to put at the top of the page, else here where the figure is, or in a new page if it doesn’t fit otherwise. A ! will force a placement, but you shouldn’t use it, unless really sure on what you want.

In general, you should strive to have a vector image for all images. The standard way to do this is to include pdf or svg images, with the first preferred, as it gets included as is. Alternatives include eps, but that is generally slow since it requires a further conversion at each compilation.

Photos should be in .jpg, screenshots and other non-vectorial diagram should instead be in .png to avoid artifacts.

When multiple figures are to be combined in a single figure (like 1.a, 1.b, …), the subfigure environment should be use inside the main figure environment, with multiple figures that can above each other (with a newline between the subfigure environments or side by side (just don’t have a new line between the subfigures). Either width or height should be specified accordingly (e.g. width=.045\linewidth ) for it to fit nicely.

In general, avoid to have extensions to your file inclusions, LaTeX compilers are in general smart enough to pick the correct one. And it allows for later re-conversion, without changing your source.

An helper script that perform such conversions to have everything as pdf images is here.

Printing G5 in A4

In Sweden, the G5 format is commonly used for thesis. They even tried to standardize as ISO, but that didn’t take off…

Anyhow, this format is close enough to an A5, but large enough to not fit 2 full pages in a single A4 sheet. Unless you ignore all typography rules, and reduce margins! This Python package will do that for you.

Good for proof-printing. Bad for the environment, since you are printing!

MORE TO COME …

This will be updated when more common pitfals, rants, or tips are found!