Still rewriting/adding documentation

doc/abstract.tex

-% Give a short summary of your thesis
+
 \begin{abstract}\noindent
-  A summary of your work, about half a page of length. An abstract should give
-  the reader all relevant information about the paper in a nutshell:
-  Topic, research question, method, results, evaluation of results.
+  The \cmd{cs-scrreprt} template is based on KOMA-Script
+  \cmd{scrreprt} and provides the thesis author with some extra
+  commands (mainly) for title page and declaration, i.\,e. the formal stuff.
+
+  This text introduces the template and gives further advise on how to
+  write and structure a thesis, how use \LaTeX\ to support you in this
+  project, and which common \LaTeX\ mistakes you should avoid.
 \end{abstract}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "thesisdoc"
+%%% End:

doc/appendix-code.tex

-\chapter{Code}
+\chapter{Additional Stuff}
+\label{cha:appendix}
 
-An appendix is the place for any additional information that may
-belong to the thesis, e.\,g. details on a questionnaire you did.
+\todo
 
-\section{Maybe a section?}
 
-You may structure your appendix like any other chapter, but it is ok to only have a chapter for each appendix.
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "thesisdoc"
+%%% End:

doc/chapter-close.tex

-\chapter{Conclusions and Future Work} \label{chapter_five}
+\chapter{Conclusions and Future Work}
+\label{chap:summary}
 
 The fifth and last chapter typically is named {Conclusions and Further Work}. Here you summarize what you have done. State what you have reached and open problems.
\ No newline at end of file

doc/chapter-intro.tex

 \chapter{Introduction}
 \label{chap:intro}
 
-\begin{howtoThesis}
+\begin{TODO}
+  This document needs vast reoganization! It started as an example on
+  how to use the template and evolved into some kind of manual, so the
+  structure does not fit well any more.
+\end{TODO}
 
-  This document is an example on how to use this template.  It is
-  written using the template and you will find lots of comments in the
-  source code. It explains how to use this template and gives hints
-  how to organize your thesis.
+This document is an example on how to use this template.  It is
+written using the template and you will find lots of comments in the
+source code. It explains how to use this template and gives hints
+how to organize your thesis.
 
-In the introduction the reader learns what to expect and how the rest
-of the text is organized. It gives the motivation of your work:
-\begin{itemize*}
-\item What is the topic?
-\item Why is this relevant?
-\item Why is this exciting?
-\item What concrete problem do you want to solve?
-\end{itemize*}
-Clearly state your research question.
-
-Try to write this as a sketch when you start writing. You will rewrite
-this chapter if you are finished with the rest anyway.
-The end of the introduction gives an advanced organizer for the rest of the
-thesis, i.\,e., a sentence for each chapter.
-
-\end{howtoThesis}
 
 This document is \emph{not} an introduction in \LaTeX\ (we will
 refer to some in section~\ref{sec:latexintro}) but gives some hints

doc/chapter-methods.tex

 \chapter{Using \LaTeX~and this Template}
 \label{chap:methods}
 
-\begin{howtoThesis}
-  
-In the “methods” chapter, you present your own work. This chapter is the
-most important one. Give definitions for concepts, present algorithms
-in an abstract way and relate your work to concepts introduced in
-chapter~\ref{chap:sor}.
+\begin{TODO}
+  Bad title, fix this. We may want to make two chapters out of
+  this.
 
-\end{howtoThesis}
+  Add intro paragraph.
+\end{TODO}
 
 \section{Semantic Markup}
 \label{sec:semantic-markup}
@@ -43,11 +41,20 @@ text as much as possible.\footnote{sometimes we have to give direct
   visual hints, especially in micro-typography.} \LaTeX\ allows us to
 define new (semantic) commands for this.
 
-\section{Structuring}
-\label{sec:structuring}
+\begin{TODO}
+  Use this! Work with it actively!
+\end{TODO}
 
 \begin{howtoThesis}
 
+\section{Thesis Composition}
+\label{sec:thesis-composition}
+
+\todo
+
+\subsection{Chapter Structure}
+\label{sec:structure}
+
 The chapters Introduction and Conclusions should have no sections.
 For the other chapters, each sectioning (chapter, section, subsection,
 \dots) should have either \emph{none} or \emph{at least two} sub
@@ -57,8 +64,110 @@ Every chapter, section etc starts with some introducing paragraph
 telling the reader what to expect here. This is, between the chapter
 heading and the section heading there should be at least one sentence.
 
+In general, your thesis roughly should be structured the following
+way.
+
+\subsubsection{Titlepage}
+\label{sec:struct-title}
+
+The title page holds all the formal stuff, just follow the
+template. There are some requirements from the university,
+\Note{do we have a link?}
+\Note{On an English thesis: does the German title have to be
+  \emph{somewhere}?}
+make sure to fulfil them. Please note that the title itself has to be
+the same as given in the application and changing it later is extra
+formal work (we want to avoid this).
+
+\subsubsection{Abstract}
+\label{sec:struct-abstract}
+
+\Note{Do we want an abstract in English \emph{and} German?}
+A summary of your work, less than half a page of length. An
+abstract should give the reader all relevant information about the
+paper in a nutshell: Topic, research question, method, results,
+evaluation of results. This is what one reads to figure out if the
+paper (thesis) should be read.
+
+\subsubsection{Introduction}
+\label{sec:struct-intro}
+
+In the introduction the reader learns what to expect and how the rest
+of the text is organized. It gives the motivation of your work:
+\begin{itemize*}
+\item What is the topic?
+\item Why is this relevant?
+\item Why is this exciting?
+\item What concrete problem do you want to solve?
+\end{itemize*}
+Clearly state your research question.
+
+Try to write this as a sketch when you start writing. You will rewrite
+this chapter if you are finished with the rest anyway.
+The end of the introduction gives an advanced organizer for the rest of the
+thesis, i.\,e., a sentence for each chapter. Something like:
+
+“Chapter~\ref{chap:sor} gives an overview on the state of the research
+on logomachy and rabulistics. In Chapter~\ref{chap:methods}
+I\footnote{This is your thesis, so it should be “I” and not “we”. If
+  you did something together with someone else (e.\,g. your advisor)
+  clearly state what \emph{your} part of the work is.}
+\Note{I like it if authors tell me that \emph{they} developed something
+  instead of sticking to passive sentence constructions. I hope this
+  is ok.}
+introduce the Aballa-model and the SuperCaliFragiListicExpialidocious
+algorithm that …”
+
+\subsubsection{State of the Research}
+\label{sec:struct-sor}
+
+In this chapter you introduce all necessary theoretical and empirical
+findings, formalisms or algorithms on which your own work is
+based. Name the chapter such that the scope is clearly characterized,
+e.\,g., \emph{Generalizing Patterns in Rabulistic Approaches to
+  Logomachy}. Show that you know the relevant papers of your
+field. Use a section for each aspect you are covering.
+
+\subsubsection{Methods}
+\label{sec:struct-methods}
+
+In the “methods” chapter, you present your own work. This chapter is the
+most important one. Give definitions for concepts, present algorithms
+in an abstract way and relate your work to concepts introduced in
+the state of research chapter. Give this chapter an appropriate
+name.
+
+\subsubsection{Realisation and Evaluation}
+\label{sec:struct-eval}
+
+This chapter is typically named \emph{Realisation and
+  Evaluation}. Here you give the most important technical details
+(more details are given in the appendix). Then you evaluate your
+approach -- typically by test runs. Describe the data used for the
+tests carefully. Give meaningful graphs. This chapter together
+with the appendix should give all information which is necessary that
+somebody else can do the same test runs as you did.
+
+\subsubsection{Conclusions and Future Work}
+\label{sec:struct-summary}
+
+Here you summarize what you have done. State what you have reached and
+open problems.
+
+\subsubsection{Appendix}
+\label{sec:struct-appendix}
+
+An appendix is the place for any additional information that may
+belong to the thesis, e.\,g. details on your program code or a
+questionnaire you did. Name your appendix chapters accordingly.
+You may structure your appendix like any other chapter, but it is ok
+to only have a chapter for each appendix.
+
 \end{howtoThesis}
 
+\subsection{\LaTeX\ Headings}
+\label{sec:latex-headings}
+
 You should always use the appropriate \LaTeX\ commands for the
 headings (like \verb|\chapter{…}|, \verb|\section{…}|,
 \verb|\subsection{…}|, …). If you feel the need to derive from the
@@ -93,7 +202,7 @@ page headings.
 You use \verb|\label{sec:foo}| to assign tags to your sections and
 \verb|\ref{sec:foo}| and \verb|\pageref{sec:foo}| to refer to the
 tagged section by number and page number (e.\,g. see
-section~\ref{sec:structuring} on page~\pageref{sec:structuring}). A~good
+section~\ref{sec:structure} on page~\pageref{sec:structure}). A~good
 \LaTeX-editor will automatically provide you with labels for your
 sections.
 
@@ -254,8 +363,8 @@ provides you with everyting you need.
 \label{sec:typography}
 \begin{itemize}\Note{This will become several subsections}
 \item widows und orphans
-\item „“ “” …
-\item Microtypography (spacings etc)
+\item „…“ “…” ``…'' {\selectlanguage{ngerman}"`…"'} …
+\item Microtypography (spacings etc) (e.\,g., a~good thing, …)
 \item hyphenation
 \item don't mess around
 \item matching fonts

doc/chapter-sor.tex

-\chapter{\LaTeX\ and Scientific Articles)}
+\chapter{\LaTeX}
 \label{chap:sor}
 
 \begin{howtoThesis}
 
-In this chapter you introduce all necessary theoretical and empirical
-findings, formalisms or algorithms on which your own work is
-based. Name the chapter such that the scope is clearly characterized,
-e.g., \emph{ Generalizing Patterns with Grammar Inference Methods}. Use
-a section for each aspect you are covering.
-
 As the document you are currently reading is a manual and \emph{not} a
 thesis or scientific paper this chapter gives you proposals on what to
 read but does not fully discuss the state of the art covering
 everything.
 
 If you have other helpful sources please file an issue or a pull
-request to the
+request to the\Note{Do we have a function email address we can give
+  here?
+}
 \fhref{https://gitlab.rz.uni-bamberg.de/cogsys/public/students/thesis-template}{repo}.
 
 \end{howtoThesis}

doc/draft-commands.tex

 \newenvironment{TODO}{%
   \begin{quote}
-    \color{red!80!black}
-    \mbox{}\marginline{TODO}%
+    \color{red!80!black}%
+    \mbox{}\marginline{\sffamily\bfseries TODO}\ignorespaces
 }{%
   \end{quote}
 }
-
+\newcommand{\todo}[1][\rule{2em}{2ex}]{
+  \begin{TODO}
+    #1
+  \end{TODO}}
 
 \newcommand{\Note}[1]{\marginline{%
-    \tikz\node[fill=yellow,draw=yellow!60!red,thick,
-    node font=\footnotesize\sffamily,text width=\linewidth-2em,
-    minimum size=2em,inner sep=1em]{#1};}}
+    \tikz[baseline=(note.base)]
+    \node[fill=yellow,draw=yellow!75!red,thick,
+    node font=\footnotesize\sffamily,text width=\linewidth-2ex,
+    align=left, text=red!25!black,
+    minimum size=2em,inner sep=1ex] (note){#1};}}

doc/thesisdoc.tex

@@ -148,15 +148,15 @@
 \listoftables
 \listoffigures
 
-% 1. Chapter: ''Introduction''
+% 1. Chapter: ``Introduction''
 \input{chapter-intro.tex}
-% 2. Chapter: ''State of Research''
+% 2. Chapter: ``State of Research''
 \input{chapter-sor.tex}
-% 3. Chapter: ''Methods''
+% 3. Chapter: ``Methods''
 \input{chapter-methods.tex}
-% 4. Chapter: ''Realisation and Evaluation''
+% 4. Chapter: ``Realisation and Evaluation''
 \input{chapter-eval.tex}
-% 5. Chapter: ''Conclusions and Future Work''
+% 5. Chapter: ``Conclusions and Future Work''
 \input{chapter-close.tex}