Restructure the template (part 2) (#4)

* Restructure the template (part 2)
* Update CI versions
* CI: build thesis PDF ourselves
* Add forgotten plots

.github/workflows/ci.yml

@@ -12,15 +12,14 @@ jobs:
   build:
     name: Build thesis PDF
     runs-on: ubuntu-latest
+    container: { image: 'aergus/latex' }
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Build the thesis
-        uses: xu-cheng/latex-action@v3
-        with:
-          root_file: thesis.tex
+        run: latexmk thesis
       - name: Upload artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: Thesis
           path: |

.gitignore

@@ -19,10 +19,10 @@
 # these rules might exclude image files for figures etc.
 # *.ps
 # *.eps
-*.pdf
+# *.pdf
 
-## Generated if empty string is given at "Please type another file name for output:"
-.pdf
+# The thesis PDF output
+thesis.pdf
 
 ## Bibliography auxiliary files (bibtex/biblatex/biber):
 *.bbl

.latexmkrc

@@ -0,0 +1 @@
+$pdf_mode = 4

README.md

@@ -1,16 +1,36 @@
 # Thesis Template
-This repository includes a template for your bachelor's or master's thesis.
-You may use the the command runner tool [`just`](https://github.com/casey/just) ([justfile](/justfile)) for easily building the PDF.
-The build process assumes that you already have a functioning LaTeX toolchain with `lualatex` installed.
-The file `thesis.tex` is the main file and includes each chapter as a separate file located in the [src](/src/) folder.
 
-# Tips
+This repository includes a template for your thesis.
 
-- Use `git` for organising your thesis files. This allows you to easily revert changes and backup your files to Github.
-- For ensuring your `.tex` source files remain readable, we adivse you to put every sentence on a separate line.
+## Getting started
 
-# Disclaimer
+1. Click on the "Use this template" button in GitHub and make a new private repository for your thesis.
+2. Clone your new repository with `git`.
+3. Run `make` to check that everything works. The resulting thesis file should be in `thesis.pdf`
+4. Fill in the blanks in `metadata.tex`.
+5. Read through the example code, then erase it.
+6. Write your thesis.
+7. Remove the `todos.tex` file.
+8. Submit and defend the thesis!
+
+### Installing LaTeX
+
+Be sure to install a LaTeX toolchain with `lualatex` support.
+
+- On a unix-style system, use TeXLive, your package manager has something like `texlive-full` or `texlive-scheme-full`.
+- On Windows, use [MiKTeX](https://www.tug.org/texlive/windows.html).
+
+#### Editor support
+
+If you want to have a Overleaf-like experience locally, we recommend using VSCode with the `james-yu.latex-workshop` package.
+
+## Disclaimer
 
 This template provides a basic thesis structure and a brief description of what to put in each chapter.
 While this is a good starting point, we offer no guarantee that this structure is appropiate for your particular thesis or covers all requirements for a good grade.
-It is your responsibility to appropiately adjust this template to fit your needs and requirements.
+It is _your_ responsibility to appropiately adjust this template to fit your needs and requirements.
+
+## License
+
+Most of the default text and the overall structure is based on <https://github.com/exaexa/better-mff-thesis>,
+which is available in the public domain. Thanks!

bibliography.bib

@@ -1,18 +1,51 @@
-@article{brachthäuserBoxing,
-  author = {Brachth\"{a}user, Jonathan Immanuel and Schuster, Philipp and Lee, Edward and Boruch-Gruszecki, Aleksander},
-  title = {Effects, capabilities, and boxes: from scope-based reasoning to type-based reasoning and back},
-  year = {2022},
-  issue_date = {April 2022},
-  publisher = {Association for Computing Machinery},
-  address = {New York, NY, USA},
-  volume = {6},
-  number = {OOPSLA1},
-  url = {https://doi.org/10.1145/3527320},
-  doi = {10.1145/3527320},
-  abstract = {Reasoning about the use of external resources is an important aspect of many practical applications. Effect systems enable tracking such information in types, but at the cost of complicating signatures of common functions. Capabilities coupled with escape analysis offer safety and natural signatures, but are often overly coarse grained and restrictive. We present System C, which builds on and generalizes ideas from type-based escape analysis and demonstrates that capabilities and effects can be reconciled harmoniously. By assuming that all functions are second class, we can admit natural signatures for many common programs. By introducing a notion of boxed values, we can lift the restrictions of second-class values at the cost of needing to track degree-of-impurity information in types. The system we present is expressive enough to support effect handlers in full capacity. We practically evaluate System C in an implementation and prove its soundness.},
-  journal = {Proc. ACM Program. Lang.},
-  month = apr,
-  articleno = {76},
-  numpages = {30},
-  keywords = {capabilities, effect polymorphism, effect systems, second-class values}
+@book{knuth1979tex,
+  title={TEX and METAFONT: New directions in typesetting},
+  author={Knuth, Donald Ervin},
+  year={1979},
+  publisher={American Mathematical Society}
+}
+
+@book{lamport1994latex,
+  title={LATEX: a document preparation system: user's guide and reference manual},
+  author={Lamport, Leslie},
+  year={1994},
+  publisher={Addison-Wesley}
+}
+
+@book{glasman2010science,
+  title={Science research writing for non-native speakers of English},
+  author={Glasman-Deal, Hilary},
+  year={2010},
+  publisher={World Scientific}
+}
+
+@book{tufte1990envisioning,
+  title={Envisioning information},
+  author={Tufte, Edward R and Goeler, Nora Hillman and Benson, Richard},
+  year={1990},
+  publisher={Graphics press Cheshire, CT}
+}
+
+@book{tufte1983visual,
+  title={Visual display of quantitative information},
+  author={Tufte, Edward R},
+  year={1983},
+  publisher={Graphics press Cheshire, CT}
+}
+
+@book{wilke2019fundamentals,
+  title={Fundamentals of Data Visualization},
+  author={Wilke, Claus O},
+  year={2019},
+  publisher={O'Reilly Media, Inc.},
+  url={https://clauswilke.com/dataviz/},
+  isbn={9781492031086}
+}
+
+@techreport{tantau2015tikz,
+  title={The TikZ and PGF Packages (Manual for version 3.1.8b)},
+  author={Tantau, Till},
+  year={2020},
+  institution={Institut f{\"u}r Theoretische Informatik Universit{\"a}t zu L{\"u}beck},
+  url={http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf}
 }

bibliography.tex

@@ -0,0 +1,4 @@
+\chapwithtoc{Bibliography}
+
+% put your references into `bibliography.bib`
+\printbibliography[heading=none]

ch1.tex

@@ -0,0 +1,70 @@
+\chapter{Important first chapter}\label{chap:refs}
+
+The first chapter of a thesis builds the theoretical backgrounds necessary for readers to understand the rest of the thesis.
+In this chapter, you should summarize and reference a lot of existing literature and research.
+
+
+You should use the standard \emph{citations}\todo{Use \textbackslash{}emph command like this, to highlight the first occurrence of an important word or term. Reader will notice it, and hopefully remember the importance.}.
+
+
+
+\begin{description}
+\item[Obtaining bibTeX citation] Go to Google Scholar\footnote{\url{https://scholar.google.com}}\todo{This footnote is an acceptable way to `cite' webpages or URLs. Documents without proper titles, authors and publishers generally do not form citations. For this reason, avoid citations of wikipedia pages.}, find the relevant literature, click the tiny double-quote button below the link, and copy the bibTeX entry.
+\item[Saving the citation] Insert the bibTeX entry to the file \texttt{refs.bib}. On the first line of the entry you should see the short reference name --- from Scholar, it usually looks like \texttt{author2015title} --- you will use that to refer to the citation.
+\item[Using the citation] Use the \verb|\cite| command to typeset the citation number correctly in the text; a long citation description will be automatically added to the bibliography at the end of the thesis. Always use a non-breakable space before the citing parenthesis to avoid unacceptable line breaks:
+\begin{Verbatim}
+Trees utilize gravity to invade ye
+noble sires~\cite{newton1666apple}.
+\end{Verbatim}
+\item[Why should I bother with citations at all?] For two main reasons:
+\begin{itemize}
+\item You do not have to explain everything in the thesis; instead you send the reader to refer to details in some other literature. Use citations to simplify the detailed explanations.
+\item If you describe something that already exists without using a citation, the reviewer may think that you \emph{claim} to have invented it. Expectably, they will demand academic correctness, and, from your perspective, being accused of plagiarism is not a good starting point for a successful defense. Use citations to identify the people who invented the ideas that you build upon.
+\end{itemize}
+\item[How many citations should I use?]
+Cite any non-trivial building block or assumption that you use, if it is published in the literature. You do not have to cite trivia, such as the basic definitions taught in the introductory courses.
+
+The rule of thumb is that you should read, understand and briefly review at least around 4 scientific papers. A thesis that contains less than 3 sound citations will spark doubt in reviewers.
+\end{description}
+
+There are several main commands for inserting citations, used as follows:
+\begin{itemize}
+\item \citet{knuth1979tex} described a great system for typesetting theses.
+\item We are typesetting this thesis with \LaTeX, which is based on \TeX{} and METAFONT~\cite{knuth1979tex}.
+\item \TeX{} was expanded to \LaTeX{} by \citet{lamport1994latex}, hence the name.
+\item Revered are the authors of these systems!~\cite{knuth1979tex,lamport1994latex}
+\end{itemize}
+
+\section{Some extra assorted hints before you start writing English}
+
+\paragraph{Word order}
+Strictly adhere to the English word order rules. The sentences follow a fixed structure with a subject followed by a verb and an object (in this order). Exceptions to this rule must be handled specially, and usually separated by commas.
+
+\paragraph{Sentence structure}
+Do not write long sentences. One sentence should contain exactly one fact. Multiple facts should be grouped in a paragraph to communicate one coherent idea. Both the sentences and paragraphs should include various hints about their relation to the other ideas and paragraps. These are typically materialized as adverbs or short sentence parts that clarify the cause--outcome and target--method--result relationship of the sentences in a paragraph. Such `word glue' helps the readers to correctly draw the lines that hold their mental images of your thesis together, and ideally see the big picture of what you were trying to convey right from the first read.
+
+Paragraphs are grouped in labeled sections for a sole purpose of making the navigation in the thesis easier. Do not use the headings as `names for paragraphs' --- the text should make perfect sense even if all headings are removed. If a section of your text contains one paragraph per heading, you might have wanted to write an explicit list instead.
+
+Mind the rules for placing commas:
+\begin{itemize}
+\item Do not use the comma before subordinate clauses that begin with `that' (like this one). English does not use subordinate clauses as often as German or Slavic languages because the lack of a suitable word inflection method makes them hard to understand. In scientific English, try to avoid them as much as possible. Ask doubtfully whether each `which' and `when' is necessary --- most of these helper conjunctions can be removed by converting the clause to non-subordinate.
+
+As an usual example, \xxx{\textit{`The sentence, which I wrote, seemed ugly.'}} is perfectly bad; slightly improved by \xxx{\textit{`The sentence that I wrote seemed ugly.'}}, which can be easily reduced to \textit{`The sentence I wrote seemed ugly.'}. A final version with added storytelling value could say \textit{`I wrote a sentence but it seemed ugly.'}
+\item Use the \emph{Oxford comma} before `and' and `or' at the end of a longer, comma-separated list of items. Certainly use it to disambiguate any possible mixtures of conjunctions: \textit{`The car is available in red, red and green, and green versions.'} Remember that English `or' is typically understood more like `either this or that, but not both,' and the use of `and` is much more appropriate in cases such as possibility overviews and example listings (like in this sentence).
+\item Consider placing extra commas around any parts of the sentence that break the usual word order, especially if they are longer than a single word.
+\end{itemize}
+
+\paragraph{Nouns}
+Every noun needs a determiner (`a', `the', `my', `some', \dots); the exceptions to this rule, such as non-adjectivized names and indeterminate plural, are relatively scarce. Without a determiner, a noun can be easily mistaken for something completely different, such as an adjective or a verb.
+
+Name all things with appropriate nouns to help both the reader and yourself, and do not hesitate to invent good names and labels for anything that you will refer to more than once. Proper naming will save you a lot of writing effort because you will not have to repeat descriptions such as \xxx{\textit{`the third output of the second benchmarked method of the improved set,'}} instead you may introduce a labeling that will allow you to say just something like \textit{`output M2\textsuperscript{+}-3'}. At the same time, this will reduce the risk that the reader will confuse the object with another one --- for illustration, the long version of the previous example might very easily confuse with the second output of the third method. The same also applies to methods descriptions, algorithms, programs, testing datasets, theorems, use-cases, challenges and other things. As an example, \xxx{\textit{`the algorithm that organizes the potatoes into appropriate buckets'}} shortens nicely as \textit{`the potato bucketer'} and may be labeled as a procedure \textsc{BucketPotatoes()}, and \xxx{\textit{`the issue where the robot crashes into a wall and takes significant time to return to the previous task'}} may be called just \textit{`the crash--recovery lag'}.
+
+\paragraph{Verbs}
+Although English can express a whopping 65 base verb tenses and their variants, scientific literature often suppresses this complexity and uses only several basic tenses where the meaning is clearly defined. Typically, you state facts in present simple (\textit{`Theorem 1 proves that Gadget B works as intended.'}), talk about previous work and experiments done in past simple (\textit{`We constructed Gadget B from Gizmo C, which was previously prepared by Tinkerer et al.'}), and identify achieved results in present perfect (\textit{`We have constructed Technology T.'}). Avoid using future tense, except for sections that explicitly describe future work --- as a typical mistake, if you state that the thesis \emph{will} describe something in later chapters, you imply that the description is not present there yet.
+
+Do not write sentences in passive voice, unless you explicitly need to highlight that something has passively subjected itself to an action. Active voice is more preferable in the theses because it clearly highlights the actors and their contributions --- typically, \textit{`you did it'} instead of \textit{`it was done'} by a mysterious entity, which the reviewers rarely envision as yourself. Writing in active voice additionally benefits the explanation of complex processes: There, the word order forces you to identify the acting subject as the first word in the sentence, which further disambiguates how the individual process parts are triggered and ordered.
+
+Try to avoid overusing gerunds (verbs that end with `-ing'). It is convenient to write shorter sentences by using gerunds as adjectives, but these are typically quite hard to understand because the readers may easily confuse the intended adjectives with verbs. If your sentence contains two gerunds close to each other, it may need a rewrite.
+
+\paragraph{Scientific writing resources}
+Consult the book by \citet{glasman2010science} for more useful details and recommended terminology for writing about the scientific research.