ru-thesis/instructions.tex

% Uncomment the lines with a single % if you wish to process the document separately
% \documentclass[12pt,a4paper,titlepage,draft]{memoir}
% \usepackage[]{ruthesis}
% \usepackage{custom}
% \graphicspath{{graphics/}{Graphics/}{./}}
% \author{Joseph~T.~Foley\formatemail{foley}}  % My name, for the titlepage
% \title{Project Report and Thesis Preparation Instructions}  % The title, for the titlepage
% \renewcommand{\maketitlehookc}{}% Skip the degree details
% \renewcommand{\maketitlehookd}{}% Skip the supervisor details
% \usepackage[hidelinks]{hyperref} % must be last package loaded!

%% Macros for filling in commonly changed items
\newcommand{\TIheadofgrad}{TBA}
\newcommand{\TItvdadmin}{Sigrún Þorgeirsdóttir~\formatemail{sigrunth}}

%% Template Developers 
%% Warning:  overleaf only accepts branch Master
% 1. git clone <overleaf repo>
% 2. git remote add gitea <gitea repo>
% 4. <DO SOME WORK>
% 5. <COMMIT AND PUSH TO GITEA>
% 6. git push origin
% 7. git push gitea

% \begin{document} % this tells the compiler that it is time to make
%                  % text to print instead of just getting ready.
% \maketitle{}  % make a title page from the Title, Date, and Author
% \newpage
% \listoffixmes{}
% \tableofcontents{}
% %\section*{Errata} %%section* avoids putting a number 
% \enableindents{}% turn on/off paragraph indents
% \mainmatter{}
\section{Introduction} % sections break up the document into pieces
These instructions detail how to prepare a final project report, master's thesis, or PhD dissertation for Reykjavík University.
These instructions (unless otherwise stated) assume you are in the Reykjavík University School of Technology.
If you are in another school, you should make sure that the template meets your specific requirements.

Critical information:  The current version of the template uses Lua\LaTeX{} for enhanced font, code, and language support.
{\em It will not work on PDF\LaTeX{} nor classic \LaTeX.}
We also have discovered that Overleaf's LiveTex 2025 does not work with StiX2 so you should use the 2024 version.
If you are writing a PhD dissertation, you will want to edit \path{main-dissertation.tex} rather than \path{main.tex}

\begin{description}
\item [Overleaf Template:]  \url{https://www.overleaf.com/latex/templates/reykjavik-university-project-report-and-thesis-template/fcwvcgnstrjs}
\item [Actively developed code:] \url{https://gitea.cs.ru.is/foley/ru-thesis}
\item [Current maintainer:] Joseph Timothy Foley.
  His email is his last name AT \texttt{ru.is}
\end{description}

\section{Frequently Asked Questions}
\begin{itemize}
    \item {\em Why isn't there the RU logo on the front of the template on Overleaf/Git?}
    The official cover for these documents is generated by the Reykjavik University department.
    Putting the RU logo on GitHub or Overleaf's templates is incompatible with their licensing rules due to the font surrounding it, so we cannot legally include it.
    A cropped version is available at RU Help \url{https://uthelp.refined.site/space/UKB/312279050/Final+Project+%2F+Thesis+%2F+Dissertation+Template}
    Take this file and put it into the \path{graphics} folder and the logo should update.
    The official source of the logo for print can be found at \url{https://hr.kreatives.is/wp-content/uploads/2021/12/HR_Logo_Colors_2017.pdf}
    For Dissertations, see Section~\ref{sec:coverpage} about how to integrate the cover from Communications into your document.    
\item {\em How do I use APA citations?}
  The template is setup to use IEEE citations by default.
  For those who want to use APA, you will need to adjust lines at the top of \path{main.tex}
  See the comments in the file right after \verb|\usepackage[backend=biber,style=ieee]{biblatex}|

    \item {\em Why does the margins and page size look weird?}
  As mentioned in the Abstract, this template was optimized for the B5 paper size so that it in print copy it has the same size as a standard textbook that fits on a standard bookshelf.
  This size also has the benefit of being similar to an e-Reader screen.
  
  \item {\em My advisor doesn't like this format and asked me to change it.  
      What should I do?}
    Please contact the head of Graduate Affairs in your Department about what is required in the thesis format and who determines the formatting.
    The Reykjavik University library is officially in charge of the outside of the thesis and suggested templates.

  \item {\em Why are there all these blank pages?}
  In printed books, content in the main body of the book traditionally starts on the Right i.e. ``Recto'' side.
  The template puts blank pages so that the Abstract, Table of Contents, and Chapters always start on the right side which may involve putting blank pages.
  
  \item {\em I've been told to use a Word Template.  Where is it?}
    As of 2025-10-15, the RU Library has been working on an Word template for non-technical users.
     
    The template authors tested MS Word to see if could properly typeset according to standard practice and found it had insufficient enforcement of formatting and margins.
    In addition, MS Word is unable to hyphenate Icelandic properly which results in very ugly typesetting.
    If you need a WYSIWYG editor to generate an Icelandic document, we recommend OpenOffice or LibreOffice with the extension developed at University of Iceland: \url{https://extensions.openoffice.org/fr/project/icelandic-hyphenation-dictionary}

  The authors do not recommend using MS Word for any document that must be printed as a book\footnote{Publishers accept MS Word documents then pay people in Asia to extract the content and convert it into XML or LaTeX.}.

  \item {\em Everything suddenly broke while I was trying to fix a citation}
  The most common causes of this problem:
  \begin{itemize}
      \item \texttt{.bib} file has a weird UTF-8 character in it like a dash character "--"  (which is different than "-" or "---" separator). 
      This can even be space characters that are non standard.
      \item Forgetting to end each field with a ",".  
      \item Putting anything except "a-Z0-9" in the citation id field.  (the first one)
      \item Putting a URL in anything except the URL field
      \item Using ``\&'' to separate author names.  
      Names are separated with the word ``and''.
      Only use ``,'' when you are reversing the order e.g. ``Foley, Joseph''
      \item Having ``\&'' or underscore or ``\verb|\|'' in a field  
   \end{itemize}
   
  There are so many ways the citations can go wrong that Joe recommends using Zotero to export the \texttt{.bib} for beginning users.
  The JabRef tool is also very helpful for finding issues and managing the \texttt{.bib} files.
\end{itemize}

\section{Coverpage}\label{sec:coverpage}
Reykjavik University's communications department insists on a common outer appearance of official printed documentation, which includes Doctoral Dissertations.
The library has been delegated the role of deciding what the non-printed student theses and project reports should look like.
They have stated that since most never are printed, the focus should be on suitability for displaying on a screen and e-reader.
The current template in \path{main.tex} implements the cover page and copyright page that go on the inside.

Doctoral students need to contact the RU Communications department for slightly different custom cover PDF before the document is to be published\footnote{The author highly suggests doing this 2 weeks before it is due.}.
This class supports the RU Communication's desire for the common appearance through the \texttt{rucover} package.
Place \texttt{cover.pdf} into the same directory that you have your thesis' main file.
\LaTeX{} includes the file automatically if you add \verb|\usepackage{rucover}| to your preamble.
You can control the filename with \verb|\usepackage[filename=name.pdf]{rucover}|.


\section{Files and Directories/Folders}
\begin{itemize}
%\item \path{cls/}: contains the \path{rureport.cls} template used to format these instructions.
\item \path{graphics/:} contains the graphics to generate this document.
%\item \path{covers/:} contains the official covers (from RU Communications) to be put on the outside of the finished book.
\item \path{IEEEtran/:} contains the IEEE citation style files
%\item \path{deadlines.xlsx}: A deadline calculator that uses the semester's
%graduation date
\end{itemize}

\section{Limited Access}
In general, access to the project report, thesis, or dissertation shall be open.
If restricting access to a thesis is sought, e.g.\ for the purpose of protecting intellectual property or protecting commercial interests of an industrial partner participating in the MSc project, permission needs to be acquired, see {\em Reglur um skil á lokaritgerðum og lokaverkefnum við Háskólann í Reykjavík\/} (\url{http://www.ru.is/bokasafn/skemman}).
If restriction of access to a thesis is granted it should be clearly stated in the thesis right after the keywords following the abstract with specification of the date at which the restriction of access should be lifted.

\section{Printing and Binding}
If you are making a print copy to be bound into a book, you may need a signature page.
This is no longer required for most electronic submissions except perhaps PhD.

If you decide to print, make sure you are doing it on archival acid-free paper.
Otherwise, your document will yellow and fall apart in the library over time.
Traditionally, the student prints out and binds a copy for each advisor and examiner: this varies significantly.
This may also be required if the research was funded in some cases.
If you are using a printing house to take care of the binding, they may be able to take the completed PDFs (cover and inside text) and print them for you.

\section{Submission}
When your document is finished and approved by your advisor, it needs to be uploaded to Skemman~\url{https://skemman.is}.
An important thing to remember is that the uploaded document will follow you for the rest of your career:
employers are likely to find it and skim it.
Make sure the document is something you would be proud to have associated with you.

The general submission sequence is:
\begin{enumerate}
\item Defense complete, minor corrections complete after X days of work.
\item Save the completed thesis text as \path{main.pdf}
%\item Get signature pages signed by supervisor(s) and examiner.
%\item Sign the library release page.
%\item Scan the pages in, put them into the document in the appropriate places.
\item Open the official cover files in \path{cover}, fill in the appropriate fields, and save as a \path{cover.pdf}
%  \item Use a PDF binding tool such as PDFsam \url{https://pdfsam.org} to putthe cover before the first page and save as \path{thesis.pdf} 
\item Upload the finished \path{main.pdf} to Skemman.
\item An autogenerated email is sent from Skemman.
  This email should be forwarded to your admin such at \TItvdadmin{}.
\item Grade for the thesis is published.
\item Graduation!
\item Sometime after graduation, the published thesis is released by RU on Skemman for others to read and enjoy.
\end{enumerate}

\section{LaTeX Template Instructions}
Some information is at the top of \path{main.tex} file, this file is for a general overview and common problems.

\subsection{Preparation}
\begin{enumerate}
\item Find a safe place to work on your thesis document.
  The author recommends Git on Overleaf, but anywhere data is backed up is a appropriate.
  If you are working with sensitive information, you should avoid bitbucket, google drive, dropbox, and any other free cloud service.
  If you think this is unnecessary, just consider how much time you will lose if your computer crashes.
   Due to Murphy's law, this is likely to happen just before your thesis is due\footnote{This has happened many times.}.

 \item Get a LaTeX installation.
   We recommend TeXlive \url{https://www.tug.org/texlive/}
   For this template on windows, MiKTeX will also work, but will run very slowly the first time you render the template.
   {\em As of September 2024, both MikTeX and TexLive did not want to install properly on the author's Windows 11 computer.}
   You will need to enable the ``miktex'' option in the template to substitute packages.
   It is very very important that you run the ``MikTeX Update Wizard'' before you start.
   Otherwise you may get errors when you try to build the document.

   Under Apple iOS and linux this is the TexLive series of packages.
   Linux distributions name the packages differently.
   The author's recommendations for RedHat distributions such as Redhat Enterprise Linux, Centos, Fedora are in Listing~\ref{code:texlive-redhat}.
   Debian-based distributions including Ubuntu and PopOS would use the packages in Listing~\ref{code:texlive-debian}.
   
   \begin{lstlisting}[caption={RedHat Packages},label={code:texlive-redhat}]
       sudo dnf -y install texlive-scheme-medium texlive-collection-{fontsrecommended,luatex,latexrecommended} texlive-biblatex-{apa,apa-doc,ieee,ieee-doc} texlive-{amsfonts,amsmath,canoniclayout,eepic,gitinfo2,fixme,makeglos,nomencl,lastpage,lipsum,listings,ltxkeys,pgf,pseudocode,stix2-otf,stix2-type1,siunitx,xurl}
     \end{lstlisting}
     \begin{lstlisting}[caption={Debian/Ubuntu Packages},label={code:texlive-debian}]
       sudo apt-get -y install texlive texlive-luatex texlive-latex-extra texlive-science texlive-generic-extra texlive-lang-european texlive-lang-german latex-xcolor texlive-pictures pgf texlive-bibtex-extra texlive-publishers chktex evince fonts-lmodern lmodern biber
     \end{lstlisting}

   Alternatively, if nothing you are doing is particularly private or proprietary, you can do development online using Overleaf.
   In this case, you won't need to setup the rest of the tools mentioned below except perhaps the Reference Manager mentioned in step~\ref{list:refmanager}.
 \item Get a LaTeX Integrated Development Environment (recommended, but not required)
   Many people like TeXStudio \url{http://texstudio.sourceforge.net/}.
   Some other code editors and IDEs may include LaTeX support.
   If you want to learn a very powerful (but old-fashioned) editor, consider GNU Emacs: \url{http://www.gnu.org/software/emacs/}.
   Of note, the author used Emacs to write this template.

    \item Get a references manager (recommended, but not required)\label{list:refmanager}
   \url{http://jabref.sourceforge.net/}  (You may have to install a Java JRE first.)
   The reference library is in \path{references.bib} by default.
   It is just a text file that can be edited, but be careful with the formatting.
   A common mistake is to forget ``,'' at the end of each piece of an entry/line.

   If you are going to make glossaries or acronym lists, you will need
   a perl interpreter.  Only windows usually needs this installed:
   \url{http://www.activestate.com/activeperl}

 \item Get supporting programs for some tools.
   For glossaries under Windows, you will need to install Perl
   \url{http://strawberryperl.com/}
   (it is already installed on the other platforms.)
   
 \item Try building the \path{main.tex} file with lualatex.  If you get errors, there
   is something wrong with your LaTeX installation.  Fix those first.

 \item Rename the \path{main.tex} file with your information (optional).
   DEGREE-NAME-YEAR is the recommended scheme 
   e.g. \path{msc-foley-2025.tex}.
   This is referred to as the ``Main'' file.
 \item Set your UI to use \path{lualatex} as the processor.
   If you are typing commands in manually, this is by typing in \path{lualatex main.tex}
   
 \item Open and read the options at the top of the previous file and set
   it up for your document.
   You will need to fill in the title and author at least.

 \item Start editing all of the \path{.tex} files with your content.

 \item Compile the document by running lualatex on the Main file, run \path{biber}, then view the result.

 \item When you print, make sure that the scale is 100\%.
   If you allow it to resize when printing, the margins won't be right.

\end{enumerate}

\subsection{Important Details}

\begin{itemize}
\item Make absolutely sure that your \path{references.bib} is in UTF-8.  If it is another format (CP1251, EBDIC) you may get weird problems with any accented characters.
  {\em Students have run into encoding issues in the past and it has taken a surprisingly long time to debug.}
\item Make sure the rest of the files, particularly the \path{.tex} file are in UTF8 or are at least in the same encoding.
  If the files are in different encoding, you will discover errors with accented characters when you try to include them together.
  Watch out for line endings. Linux, Windows, and OSX all use different line endings in text files.
\item Reference managed management uses biber/biblatex instead of bibtex.
Icelandic characters may not work properly in your \path{references.bib} file if you use BibTeX.
TexMaker and TeXStudio require a configuration change to do this.
\item Be consistent about UPPER and lower case in naming files.
  Preferably just use the 26 English letters, 10 numbers, dash ``-'', and underscore ``\_'' to avoid filename issues.
  Windows doesn't care (but some programs in Windows do).
  OSX sometimes cares.
  Linux always cares.
\item \LaTeX{} generates a bunch of temporary files that you don't want to put into version control.
  Look at Appendix~\ref{src:gitignore-example} for a list of extensions.
\end{itemize}

\section{Department of Engineering Information}


\subsection{Thesis Defense (Oral Examination Procedure)}
The examiner is selected by the Department Head in consultation with the supervisor(s).  
The choice of examiner needs to be approved by the Director of Graduate Studies.  
The examiner shall have the qualifications necessary to supervise the thesis, but must not have collaborated in the project on which the thesis is based and must fulfil the rules of Reykjavík University on impartiality of examiners.
The oral examination shall be open to the public and shall be announced through appropriate channels with at least 3 days notice.  
The examination should take the form of an approximately 30 minute presentation by the student, followed by questions from the examiner, School representative (most often the Department Head), supervisor(s) and the audience.  
The audience then leaves the room and the examiner(s), supervisor and School representative have the opportunity to put further questions to the candidate and, as appropriate, request modifications to the thesis.  
Subsequently, the candidate leaves the room and the examiner, School representative and supervisor(s) deliberate and decide upon the grade.  
Normally, the student will be informed of the grade the next day.  
If the thesis is subject to confidentiality, or for other valid reasons approved by the Director of Graduate Studies, the oral examination may be closed to the public.

\subsection{Grading}
The appointed examiner shall evaluate the thesis and the oral defense of the thesis, together with the
supervisor(s) and the department's representative.  
One grade shall be awarded for the thesis and defence.  
The minimum passing grade is 6.0, see Guidelines for grading MSc theses in the appendix.  
The following factors shall be taken into account:

\begin{itemize}
\item Significance and originality of work
\item Scientific and technological challenge and results
\item Methodological quality
\item Presentation
\end{itemize}

The number of ECTS credits awarded for the Master's project shall be taken into account.  
Thus, significantly more demands in terms of originality, quantity and scientific quality of the work should be placed on the student for a 60 ECTS thesis than a 30 ECTS thesis.

\subsection{Guidelines for grading MSc thesis (English)}
The guidelines below describe typical projects in different grading brackets.  
This is meant for
examiners and instructors in grading master's theses.  
The projects need not fulfil every aspect of
these desciptions in order to be awarded the corresponding grade.
\begin{description}
\item [Superior (9,0-10,0)]
  The project is excellent.  
The handling of the material shows considerable originality and independant thought.
  Considerable skill in the definition and organized solving of the problem.
  Very good understanding of concepts.
  Academic approach and handling of material.
  Exemplary methods in collection and processing of data.
  Use of references is very precise and supports the projects well.
  The thesis may well lead to a publishable article.
  Exceptionally well polished thesis with very good grammar, spelling and language use.
  The thesis is in English.
  The student's performance in the defense is excellent.
\item[First grade (7,5-8,5)]
  The project is very good and handling of material is good and somewhat original.
  Clear understanding of the material and the definition of the problem is good and the solving well organized.
  Data gathering and processing without major weaknesses and intelligent use of references.
  The thesis is well arranged and grammar, spelling and language is good.
  The student's performance in the defense is either good or very good.
\item[Second grade (6,0-7,0)]
  The project is acceptable.
  Handling of material is fair and some independant thinking.
  Definition and analysis of project reflects some understanding.
  Data collection and processing is without major flaws.
  Deficiencies in the literature review.
  Flaws have not been addressed despite the instructor's suggestions.
  Language, grammar and spelling is fair.
  The student's performance in the defense is fair.
\item[Fail (1,0-5,5)]
  The project is unacceptable.
  The project has major flaws that have not been addressed despite the instructor's suggestions.
  Limited understanding of the material.
  Definitions and analysis do not show understanding of what is relevant in solving the problem at hand.  
Major errors or misunderstanding.
  Data collection and analysis has deficiencies and literature review is weak.
  The subject is not adhered to or major inconsistencies.
  Language, grammar and spelling is fair or poor.
  The student's performance in the defense is fair or poor.
\end{description}

\subsection{Viðmið fyrir einkunnagjöf}
Eftirfarandi er lýsing á dæmigerðum verkefnum í mismunandi einkunnabilum sem er ætluð til stuðnings fyrir frófdómara og leiðbeinendur við mat á MSc verkefnum.
Lýsinging þarf ekki að eiga við verkefnið í öllum atriðum til að verkefnið geti hlotið vipkomandi einkunn.

\begin{description}
\item[Ágætiseinkunn (9,0 -- 10,0)] Verkefni er afburðagott.
  Efnistök engdurspegla umtalsverðan frumleika og sjálfstæði í hugsun.
  Umtalsverð færni í skilgeiningu og skipulegri úrlausn viðfangsefnisins.
  Mjög góður skilningur á hugtökum.
  Visindaleg nálgun við efnistök.
  Fyrirmyndar vinnubrögð við öflun og úrvinnslu gagna.
  Heimildanotkun mjög nákvæm og styður vel við verkefnið.
  Ætla má að ritgerðin geti leitt til birtingarhæfrar greinar.
  Frágangur sérlega góður og stafsetning og málfar mjög gott.
  Ritgerðin er skrifuð á ensku.
  Frammistaða nemanda í vörninni afburðagóð.
\item[1. einkunn (7,5 -- 8,5)] Verkefni er mjög gott, efnistök góð og nokkuð frumleg.
  Skýr skilningur á viðfangsefninu og góð færni í skilgreiningu þess og skipulegri úrlausn.
  Vinnubrögð við öflun og úrvinnslu gagna án verulegra veikleika og heimildanotkun skynsamleg.
  Frágangur góður og stafsetning og málfar gott.
  Frammistaða nemanda í vörninni góð eða mjög góð.
\item[2. einkunn (6,0 -- 7,0)]  Verkefnið er þokkalegt.
  Allgóð efnistök og sjálfstæð hugsun á köflum.
  Skilgreining og úrvinnsla viðfangsefnis endurspegla nokkurn skilning á viðfangsefninu.
  Öflun og úrvinnsla gagna án verulegra galla.
  Heimildanotkun nokkuð áfátt.
  Finna má galla sem ekki hafa verið lagfærðir þrátt fyrir ábendingar leiðbeinanda.
  Málfar og stafsetning þokkaleg.
  Frammistaða nemanda í vörninni þokkaleg.
\item[Falleinkunn 0,0 -- 5,5]  Verkefni fullnægir ekki lágmarkskröfum.
  Verkefnið hefur áberandi galla sem ekki hafa verið lagfærðir þrátt fyrir ábendingar leiðbeinanda.
  Takmarkaður skilningur á viðfangsefninu.
  Skilgreining og úrlausn viðfangsefnis sýnir ekki næganlega góða tilfinningu fyrir því hvað skiptir máli við lausn þess.
  Verulegar villur eða misskilningur.
  Öflun og úrvinnsla gagna er töluvert áfátt sem og heimildanotkun.
  Farið út fyrir efnið eða umtalsverð ósamkvæmni.
  Málfar og stafsetning sæmileg eða slök.
  Frammistaða nemanda í vörninni sæmileg eða slök.
\end{description}

\section{Doctorate Special Instructions}
Final Preparation for PhD Dissertations:\footnote{Always refer to the website in case details have changed}
\begin{enumerate}
  \item Use \path{main-dissertation.tex} not \path{main.tex}!
  \item Send PDF to Administrative person \TItvdadmin{}
  % \item Get signature pages signed, and scan them into PDF
  \item Talk to one of the printing companies in Iceland and ask if they can do a B4 booklet with a printed cover.
    \fxwarning{Someone needs to tell me which ones are good and what are the magic words}
  \item Make clear which elements are the outside cover and which are the inside contents.
    \textbf{You want to make sure they don't print a copy of the cover inside the book.}
  \item They will insert your signature pages into the PDF and start the printing process;
    The paper you want is archival-quality acid-free 240$\times$\SI{170}{\milli\meter} (aka B5, Programme, or Book Economy.
  \item If you can, get a proof of the print to check that the layout is correct and the quality is acceptable, particularly any figures.
  \item If is acceptable, then get them to print out the required number of copies.
  \item Finally bring the copies to head of graduate studies(\TIheadofgrad{}), who should forward them as appropriate.
  \end{enumerate}
  
  % \end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "main"
%%% TeX-engine: luatex
%%% End: