diff --git a/.gitignore b/.gitignore
index 84f231c..3212bef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,5 @@ template.pdf
 
 # release tarballs
 moderncv-*.tar.gz
+
+examples/
diff --git a/KNOWN_BUGS b/KNOWN_BUGS
index 15b86ec..05cb6af 100644
--- a/KNOWN_BUGS
+++ b/KNOWN_BUGS
@@ -1,3 +1,6 @@
+- skillmatrix does not break automatically in fancystyle.
+- long names break the oldstyle and possibly other styles (needs testing).
+- long urls in classic style can make the name break line. Fixed width for the adresspart must be implemented. 
 - When using the "fancy" style, undesired space is added between the bibliography
   head and the first entry, as well as after the last entry
 - Moderncv is incompatible with biblatex.
diff --git a/README.md b/README.md
index 7a78a30..eeec599 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,55 @@
 
 ## A modern curriculum vitae class for LaTeX
 
-**moderncv** provides a documentclass for typesetting curricula vitae in various styles. Moderncv aims to be both straightforward to use and customizable, providing five ready-made styles (classic, casual, banking, oldstyle and fancy) and allowing one to define his own by modifying colors, fonts, icons, etc.
+`moderncv` provides a documentclass for typesetting applications (curricula vitae and cover letters) in various styles. `moderncv` aims to be both straightforward to use and customizable, providing five ready-made styles (classic, casual, banking, oldstyle and fancy) and allowing one to define his own by modifying colors, fonts, icons, etc.
 
-Most commands are defined in such a way that arguments are optional.
+### Getting started 
+Once you clone this repo have a look at some examples and build the manual to see if this package suits your needs.
+This can be done by issuing 
+```make
+make userguide
+```
+in a terminal. After completion of the compilation precompiled versions of the template in all styles can be found in the folder `examples` and 
+the user guide in the folder `manual`.  
+Alternatively get the tar ball from [CTAN](https://ctan.org/pkg/moderncv?lang=de). The examples as well as the documentation are already prebuilt in that tarball.
+
+To start working on your own application use and modify the template file `template.tex`.
+The user guide can be found in the folder `manual` and contains additional information on what the document class offers.
+
+### Makefile
+The `Makefile` supports the following rules.
+
+#### Rules for building templates and the user guide
+* `template:` Build the `moderncv` template `template.tex` with `LuaLaTeX`. This rule can be called in one of two ways: 
+  * `make template`: Build the template in default style.
+  * `make template STYLE=<style>`: Build the template in the style specified by
+	`<style>`. `<style>` can be classic, casual, banking, oldstyle or fancy.
+
+* `templates:` Build the template `template.tex` with LuaLaTeX for _all moderncv styles_ and move resulting `pdf` files to the folder `examples/`.
+
+* `userguide:`  Build the user manual `manual/moderncv_userguide.tex` with `LuaLaTeX`. This rule calls the rule `templates` before compiling the documentation.
+
+* `clean:` Clean the clutter created by compiling the documents.
+
+* `delete:`Delete `template.pdf` and `manual/moderncv_userguide.pdf`.
+
+* `deleteexamples:` Delete `examples/` folder and remaining template example `pdf` files in folder `manual/`.
+
+* `force:`  Force rebuilding the user guide by running the rules `delete` `deleteexamples`  `userguide` and clean.
+
+#### Rules intended for package maintainance
+* `version:` Update the version information (version number and date) of all `moderncv` files (*.sty, moderncv.cls, *.tex). This rule can be called in two different ways. Note, however, that it is intended to be called by the rule `release` and usually does not need to be called explicitly.
+  * `make version`: Called in this way the version number is obtained through `git describe --tags`. If this information is newer all `moderncv` files get updated. 
+  * `make version NEW=<version number>`: Optionally, the desired version number `<version number>` can be specified. 
+
+* `tarball:`  Create a new release tarball suitable for upload to CTAN. If the `example/` folder is present, it gets included in the tar archive. Similary, all `pdf` files in the `manual/` folder get included aswell. This rule is intended to be called by the rule `release` and usually does not need to be called explicitly.
+
+* `release:`Update the version information of all files including the subtitle
+  in the user guide, rebuild examples as well as the user
+  guide and create a releasable tarball including the compiled pdfs. 
+  Before runing `make release` for an actual release be sure to tag the last
+  commit with the intended version information.
 
-Until a decent manual is written, one can always look in the `template.tex` file for an example. It can be compiled to pdf via `latexmk -pdf ./template.tex`.
 
 If using [`academicons`](https://ctan.org/tex-archive/fonts/academicons) in the template, you need to use a Xe(La)TeX or Lua(La)TeX engine for them to render. Otherwise an alternative will be used automatically.
 
@@ -19,7 +63,7 @@ If using [`academicons`](https://ctan.org/tex-archive/fonts/academicons) in the
 As the main goal is to keep this package alive, it is maintained in a loosely structured team. You can contact us in our matrix room [moderncv:matrix.org](https://matrix.to/#/#moderncv:matrix.org), feel free to join if you have questions or want to contribute. Development takes place at [github.com/moderncv/moderncv](https://github.com/moderncv/moderncv).
 
 ## Licence
-moderncv is licensed under the [LPPL-1.3c](https://spdx.org/licenses/LPPL-1.3c.html).
+`moderncv` is licensed under the [LPPL-1.3c](https://spdx.org/licenses/LPPL-1.3c.html).
 
 ## Origin
 Original author: Xavier Danaux <xdanaux@gmail.com><br/>
diff --git a/manual/moderncv_userguide.tex b/manual/moderncv_userguide.tex
index db0ea1c..1bf54af 100644
--- a/manual/moderncv_userguide.tex
+++ b/manual/moderncv_userguide.tex
@@ -1,5 +1,5 @@
-%% moderncv_userguide.tex (compiled with pdfLaTeX)
-%% Copyright 2007 Cristina Sambo
+%% moderncv_userguide.tex as shipped with 2021/01/21 v2.1.0 modern curriculum vitae and letter document class (moderncv)
+% 2021 David Seus, cryptointerest@posteo.de
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License version 1.3c,
@@ -7,14 +7,40 @@
 
 \documentclass[a4paper,11pt]{article}
 
-\title{\bfseries Moderncv -- v. 0.6}
-\author{Package by Xavier Danaux \\ \begin{small}Documentation by Cristina Sambo \end{small}}
-\date{}
+\title{\texttt{moderncv} User Guide\\{\small Package version v2.1.0}}
+% Cristina Sambo,
+\author{Package by Xavier Danaux \\ \begin{small}Documentation by David Seus \end{small}}
+\date{\today}
 
 %language and encoding options
 \usepackage[english]{babel}
+\usepackage{ifxetex,ifluatex}
+\newif\ifxetexorluatex
+\ifxetex
+  \xetexorluatextrue
+\else
+  \ifluatex
+    \xetexorluatextrue
+  \else
+    \xetexorluatexfalse
+  \fi
+\fi
+%%%% PDFLaTeX or LUALaTeX/XeLaTeX %%%%%%%
+\ifxetexorluatex
+    %\usepackage{luatextra}
+%     \usepackage{lualatex-math}
+    \usepackage{shellesc} % fix a bug for lualatex shellescape
+  %  \usepackage{unicode-math}
+%  \setmathfont{xits-math.otf}
+\else
+    %% if pdflatex is used uncomment the following packages. If lualatex is used comment them.
+    \usepackage[utf8]{inputenx}
+    %additions for utf8
+    \input{ix-utf8enc.dfu}
+    %% if pdflatex is used uncomment above packages. If lualatex is used comment them.
+\fi
+\PassOptionsToPackage{T1}{fontenc} % T2A for cyrillics
 \usepackage[T1]{fontenc}
-\usepackage[latin1]{inputenc}
 
 %font options
 \usepackage{txfonts}
@@ -29,434 +55,942 @@
 \frenchspacing %(to suppress additional space after a full stop)
 
 %packages
-\usepackage[pdftex]{graphicx}
-\usepackage[pdftex]{xcolor}
+\usepackage{graphicx}
+\usepackage{xcolor}
 \usepackage[labelfont=sl,font=small,width=0.9\textwidth]{caption}
 \usepackage{marvosym}
 \usepackage{latexsym}
-
-%pdfLaTeX options
-\pdfpagewidth=\paperwidth
-\pdfpageheight=\paperheight
-\pdfimageresolution=150
-\pdfinfo{
-	/Title		(Moderncv -- v. 0.6)
-	/Author		(Cristina Sambo)
-	/Subject		(Moderncv package user's guide)
-	/Keywords	(curriculum vitae, LaTeX)
+\usepackage{url}
+\usepackage{scrhack} % Fix warnings when using KOMA with listings package
+\usepackage{xspace}  % To get the spacing after macros right
+\usepackage{mparhack} % To get marginpar right
+\usepackage{microtype}
+%****************************************************************************************************
+% Setup code listings
+% ****************************************************************************************************
+\usepackage{listings}
+%\lstset{emph={trueIndex,root},emphstyle=\color{BlueViolet}}%\underbar} % for special keywords
+\lstset{language=[LaTeX]Tex,%C++,
+  morekeywords={PassOptionsToPackage,selectlanguage},
+  keywordstyle=\color{cvblue},%\bfseries,
+  basicstyle=\small\ttfamily,
+  %identifierstyle=\color{NavyBlue},
+  commentstyle=\color{gray}\ttfamily,
+  stringstyle=\rmfamily,
+  numbers=none,%left,%
+  numberstyle=\scriptsize,%\tiny
+  stepnumber=5,
+  numbersep=8pt,
+  showstringspaces=false,
+  breaklines=true,
+  %frameround=ftff,
+  %frame=single,
+  belowcaptionskip=.75\baselineskip,
+%   frame=L,
+  emph={cvitem,cventry,cvdoubleentry,cvdoubleitem,moderncvstyle,moderncvcolor,%
+  cvskill,cvskilllegend,cvskillplainlegend,cvskillhead,cvskillentry,nopagenumbers,%
+  name,address,email,link,social,phone,homepage,extrainfo,photo,quote,section,subsection,setlength,NewDocumentCommand,definecolor,colorlet,cvitemwithcomment},%
+  emphstyle={\color{cvblue}},%
+  emph={[2]familydefault,sfdefault,rmdefault,inputenc,moderncv,document,bibliographyitemlabel,%
+  addresssymbol,mobilephonesymbol,fixedphonesymbol,faxphonesymbol,emailsymbol,homepagesymbol,linkedinsocialsymbol,%
+  xingsocialsymbol,twittersocialsymbol,githubsocialsymbol,gitlabsocialsymbol,%
+  stackoverflowsocialsymbol,bitbucketsocialsymbol,skypesocialsymbol,orcidsocialsymbol,researchgatesocialsymbol,%
+  researcheridsocialsymbol,telegramsocialsymbol,whatsappsocialsymbol,signalsocialsymbol,matrixsocialsymbol,googlescholarsocialsymbol,cvstretchability,bornsymbol},%
+  emphstyle={[2]\color{cvblue!60!cvgrey}\bfseries},
 }
 
-%my commands
-\definecolor{bluecv}{rgb}{0.25,0.5,0.75}
-\definecolor{greencv}{rgb}{0.55,0.85,0.35}
-\definecolor{redcv}{rgb}{1.00,0.30,0.30}
-\definecolor{orangecv}{rgb}{1,0.65,0.20}
-\definecolor{greycv}{rgb}{0.75,0.75,0.75}
+\usepackage{hyperref}
+\hypersetup{%
+  unicode=true,
+%   draft, % hyperref's draft mode, for printing see below
+  colorlinks=true, linktocpage=true, pdfstartpage=3, pdfstartview=FitV,%
+  % uncomment the following line if you want to have black links (e.g., for printing)
+  %colorlinks=false, linktocpage=false, pdfstartpage=3, pdfstartview=FitV, pdfborder={0 0 0},%
+  breaklinks=true, pageanchor=true,%
+  pdfpagemode=UseNone, %
+  % pdfpagemode=UseOutlines,%
+  plainpages=false, bookmarksnumbered, bookmarksopen=true, bookmarksopenlevel=1,%
+  hypertexnames=true, pdfhighlight=/O,%nesting=true,%frenchlinks,%
+  urlcolor=cvblue, linkcolor=cvblue, citecolor=cvblue, %pagecolor=RoyalBlue,%
+  %urlcolor=Black, linkcolor=Black, citecolor=Black, %pagecolor=Black,%
+%   pdfborder={0 0 1},		% width of pdf link border 0 0 1, 0 0 0 = colorlinks
+%   linkbordercolor=gray!15,
+%   citebordercolor=green!15,
+}
 
+
+%my commands
+% automatically read known bugs file. works only for single ligned entries
+% \newread\myread% Get a file handle grip called \myread
+% \newcommand{\loaditemsfromfile}[2][enumerate]{%
+% %   \DeclareDocumentCommand\multiLineRead{}{}
+% \IfFileExists{#2}{%
+%   \openin\myread=#2
+% %   \begingroup\endlinechar=-1
+%   \def\matchmarco{\par}
+%     \begin{#1}  % Use an itemize enviroment with #1 as name of the env.
+%       \def\multiLineRead{}
+%       \loop\unless\ifeof\myread%
+% %       \renewcommand{\multiLineRead}{}
+%         \read\myread to \localvariable
+%         \loop\unless\ifx\localvariable\matchmacro\fi% infinite loop
+%         \ifeof\myread
+%         \else
+%           \ifx\localvariable\matchmacro\relax
+%               \def\multiLineRead{}
+%           \else
+%               \edef\multiLineRead{\multiLineRead,Test} %\localvariable
+%               \item \multiLineRead
+%           \fi
+%         \fi
+%         \repeat
+%       \repeat
+%     \end{#1} % close the environment
+% %   \endgroup
+%   \closein\myread%  \close the file
+% }{}%
+% }
+% consider using datatool
+% https://packages.oth-regensburg.de/ctan/macros/latex/contrib/datatool/datatool-user.pdf
+% \makeatletter
+% \newread\myread
+% \newcommand{\loaditemsfromfile}[2][enumerate]{%
+% %   \DeclareDocumentCommand\multiLineRead{}{}
+% \IfFileExists{#2}{%
+%     \def\linetomatch{\endlinechar}% \edef is not required
+%     \openin\myread=#2
+%     \begingroup\endlinechar=-1
+%     \begin{#1}  % Use an itemize enviroment with #1 as name of the env.
+%       \item TEst
+%     \@whilesw\unless\ifeof\myread\fi{%
+%         \read\myread to \dataline
+%         \noindent"\linetomatch"
+%         \ifx\dataline\linetomatch\relax
+%             \item equals
+%         \else
+%             \item does not equal "\dataline"
+%         \fi
+%     }%
+%     \end{#1}%
+%     \endgroup
+%     \closein\myread
+% }{}%
+% }%
+% \makeatother
+
+
+
+\definecolor{cvblue}{rgb}{0.22,0.45,0.70}
+\definecolor{cvgreen}{rgb}{0.35,0.70,0.30}
+\definecolor{cvred}{rgb}{0.95,0.20,0.20}
+\definecolor{cvorange}{rgb}{0.95,0.55,0.15}
+\definecolor{cvgrey}{rgb}{0.75,0.75,0.75}
+\definecolor{cvburgundy}{rgb}{0.596078,0,0}% burgundy: 139/255 (0.545098) or 152/255 (0.596078)
+\definecolor{cvgrey}{rgb}{0.55,0.55,0.55}
+\definecolor{cvpurple}{rgb}{0.50,0.33,0.80}% purple
+
+\newcommand{\todo}[1]{\marginpar{\textcolor{red}{[\textbf{TODO:} #1]}}}
+\newcommand{\todox}[1]{\textcolor{red}{[\textbf{TODO:} #1]}}
+% macros
+% \newcommand{\code}[1]{\texttt{#1}}
+% \newcommand{\Code}[1]{\texttt{#1} }
+\newcommand{\code}[1]{\lstinline!#1!}
+\newcommand{\Code}[1]{\lstinline!#1!~} %\lstinline!#1!
+\newcommand{\moderncv}{\code{moderncv}}
+\newcommand{\Moderncv}{\Code{moderncv}}
+\newcommand{\github}{GitHub}
+\newcommand{\Github}{GitHub~}
+\newcommand{\ctan}{CTAN}
+\newcommand{\Ctan}{CTAN~}
+\newcommand{\cvtemplate}{\code{template.tex}}
+\newcommand{\Cvtemplate}{\code{template.tex}~}
+\newcommand{\latex}{\LaTeX}
+\newcommand{\Latex}{\LaTeX\~}
+\newcommand{\biblatex}{BibLaTeX}
+\newcommand{\Biblatex}{BibLaTeX~}
+\newcommand{\cvdoccolorbox}[1]{{\color{#1}\rule{4ex}{2ex}}}
+% current Code repository.
+\newcommand{\moderncvGithub}{\url{https://github.com/moderncv/moderncv}}
+\newcommand{\moderncvCtan}{\url{https://ctan.org/pkg/moderncv}}
 %==================
 % DOCUMENT BEGINNING
 %==================
 \begin{document}
 \maketitle
-
 \begin{abstract}
-\noindent \texttt{Moderncv}, as its author says in the readme file, provides a documentclass for typesetting modern curriculum vitaes in various styles. It is fairly customizable, allowing you to define your own style by changing the colors, the fonts, \dots\ and provides two default styles: classic and casual.
+\noindent
+\Moderncv provides a document class for typesetting modern curriculum vit\ae~ and corresponding cover letters
+for applications in various styles.
+Five predefined styles are available and each of the styles can be adjusted through options adjusting headings and colors.
+It is fairly customizable, allowing the user to adjust the look and feel of each style to their liking.
+Several macros allow the user to add content to the CV and format it in a consistent way.
+A letter of motivation consistent with the style is part of the template as well.
 \end{abstract}
+\tableofcontents
 
-\section{Introduction}
-When I saw this class for the first time I was amazed: ``Here it is what I need,'' I thought. Using the very clear examples, it was easy to make my first CV.
-Indeed the class is very simple to use; in this documentation I will only put together all the things to help users to have all on hand.
+\section{Getting started}
+\subsection{How to read this manual}
+This manual is organized as follows.
+The present section contains information on how to get started with the \Moderncv
+package, i.e. how to install required packages to your system.
+%
+% \emph{Note, that it is assumed, that you know how to install \LaTeX\ packages in case some are missing}.
+%
+Section \ref{section:moderncvTemplate} provides a step by step guide of the \Moderncv template file and how to work with it.
+%
+Section \ref{section:customization} discusses details of the customizations that can be done by the user:
+The different styles, their options, colors and tips and tricks.
+%
+Section \ref{section:implementationDetails} contains information about the packages being used by \moderncv,
+known problems and possible solutions that have been found.
 
-\smallskip
-\texttt{Moderncv} requires the following packages: \texttt{ifthen}, \texttt{ifpdf}, \texttt{color}, \texttt{lmodern}, \texttt{marvosym}, \texttt{url}, \texttt{hyperref}, \texttt{longtable}, \texttt{graphicx}, \texttt{fancyhdr}, usually all just included in the \LaTeX\ distributions.
+\subsection{Installation instructions}
+If the \Moderncv package does not ship with your \LaTeX\ distribution, or the installed version is too old,
+grab the \Moderncv code from \Ctan or \github: \medskip
 
-\section{In the preamble}
+\begin{tabular}{l}
+  \moderncvCtan \\%[.5ex]
+  \moderncvGithub
+\end{tabular}
 
-At the very beginning of your preamble (that is the part before \verb|\begin{document}|) insert:
+\paragraph{Note.} Depending on your \LaTeX\ distribution some additional packages might have to be installed.
+Section \ref{section:implementationDetails:requiredPackages} lists all packages that \Moderncv requires to be installed on your system.
 
-\begin{verbatim}
-\documentclass[<options>]{moderncv}
-\end{verbatim}
+\section{The \texttt{moderncv} template step by step.}
+This section is meant as a quick reference to the \Moderncv package and should contain enough information
+to get a first working curriculum vit\ae~ typeset.
+\label{section:moderncvTemplate}
+The easiest way to get started with \Moderncv is to adjust the template that comes with the package.
+In case the \Moderncv package is part of your \LaTeX\ distribution, search for the folder \Moderncv
+on your system containing all files of the package.
+In this folder, there should be a file called \cvtemplate.
+In case you downloaded the package from \Github or \Ctan move into the folder of the newly downloaded (and possibly extracted) package to
+find the file \Cvtemplate there.
 
-where the options are:
+\paragraph{Note.} If you downloaded \Moderncv from \Github or \Ctan and you move the \Cvtemplate to another folder make sure to adjust the \Code{TEXINPUTS} variable to find the newly downloaded package.
+Otherwise either the old package version gets used or \LaTeX\ throws an error if there is no other version installed.
 
-\begin{description}
- \item[paper size options:] \texttt{a4paper}, \texttt{a5paper}, \texttt{b5paper}, \texttt{letterpaper}, \texttt{legalpaper}, \texttt{ex\-ec\-u\-tive\-pa\-per}, \texttt{landscape}
- \item[font size options:] \texttt{10pt}, \texttt{11pt}, \texttt{12pt}
- \item[font option:] \texttt{nolmodern}, for people without the latin modern fonts
- \item[color option:] \texttt{nocolor}, to have all in black and white
- \item[draft/final options:] \texttt{draft}, \texttt{final}
-\end{description}
+Test your setup by compiling \Cvtemplate and have a look at the result.
 
-The default options are: \texttt{a4paper}, \texttt{11pt}, \texttt{color}, \texttt{final}.
+\paragraph{Note.} The \Moderncv packages should compile fine with \Code{pdflatex}, \Code{lualatex} and \Code{xelatex}. However, when using \Code{pdflatex} not all icons are available so using either
+\Code{lualatex} or \Code{xelatex} \emph{is strongly recommended}.
 
-After the documentclass specification, choose the theme for your curriculum vit\ae:
+\subsection{Basic setup}
+A document using the \Moderncv document class gets set up as any other document class. We go through the template step by step.
+\subsubsection*{Configuring document class options}
+The \Moderncv document class is loaded as per usual, by
+\begin{lstlisting}
+  \documentclass[<options>]{moderncv}
+\end{lstlisting}
+where up to one of each category of the following options \smallskip
 
-\begin{verbatim}
-\moderncvtheme[<options>]{casual}
-\end{verbatim}
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.52\textwidth}}
+ {\bfseries \code{paper}:}  & \code{a4paper}, \code{a5paper}, \code{b5paper}, \code{letterpaper},
+                    \code{legalpaper}, \code{executivepaper}, \code{landscape} \\
+ {\bfseries \code{font family:}}   & \code{sans}, \code{roman} \\
+ {\bfseries \code{font size:}}   & \code{10pt}, \code{11pt}, \code{12pt} \\
+ {\bfseries \code{draft/final:}} & \code{draft}, \code{final}
+\end{tabular}
+\endgroup \smallskip
 
-which is the default theme, or
+\noindent can be passed to the document class.
+By default, the \Moderncv document class uses \code{a4paper}, \code{11pt}, \code{final}.
 
-\begin{verbatim}
-\moderncvtheme[<options>]{classic}
-\end{verbatim}
+\subsubsection*{Configuring \texttt{moderncv} style and color}
+Choose a \Moderncv style and color by adjusting the commands
+\begin{lstlisting}
+  \moderncvstyle{<style>}
+  \moderncvcolor{<color>}
+\end{lstlisting}
+where the possible options as explained in \Cvtemplate are \smallskip
 
-where the theme options are:
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.82\textwidth}}
+ {\bfseries \code{style}:}  & \code{casual} (default), \code{classic}, \code{banking}, \code{oldstyle},
+                    \code{fancy} \\
+ {\bfseries \code{color:}}   & \code{black} \cvdoccolorbox{black}, \code{blue} \cvdoccolorbox{cvblue} (default), \code{burgundy} \cvdoccolorbox{cvburgundy}, \code{green} \cvdoccolorbox{cvgreen}, \code{grey} \cvdoccolorbox{cvgrey}, \code{orange} \cvdoccolorbox{cvorange}, \code{purple} \cvdoccolorbox{cvpurple}, \code{red} \cvdoccolorbox{cvred}
+\end{tabular}
+\endgroup
 
-\begin{description}
- \item[color options:] you can choose between five color:
-	\begin{itemize}
-	 \item[\texttt{blue}] {\color{bluecv}\rule{1cm}{2ex}} (default color)
-	 \item[\texttt{green}] {\color{greencv}\rule{1cm}{2ex}}
-	 \item[\texttt{red}] {\color{redcv}\rule{1cm}{2ex}}
-	 \item[\texttt{orange}] {\color{orangecv}\rule{1cm}{2ex}}
-	 \item[\texttt{grey}] {\color{greycv}\rule{1cm}{2ex}}
-	\end{itemize}
- \item[roman option:] \texttt{roman}, for {\fontsize{11}{12} \usefont{T1}{lmr}{m}{n}\selectfont roman} fonts, instead of \fontsize{11}{12} \usefont{T1}{lmss}{m}{n}\selectfont sans serif fonts.
-\end{description}
+\paragraph{Note.} If you downloaded the package from \Ctan the folder should contain a subfolder
+\Code{examples/} in which the template has been built for all style options in the standard color blue.
+If you clone the \Github repository you can build these examples by executing
+\begin{lstlisting}
+  Make templates
+\end{lstlisting}
+in shell.
 
-Then you have to specify the character encoding (utf8, latin1, and so on):
 
-\begin{verbatim}
-\usepackage[<your encoding>]{inputenc}
-\end{verbatim}
+\paragraph{Note.} Some of the styles take additional options to fine tune their appearance. To keep
+this overview short, the description of these options is postponed to section \ref{section:customization:stylesAndOptions}.
 
-and you can adjust the page geometry:
+\subsubsection*{Font family and page numbering}
+The default font family is set by adjusting and uncommenting the line containing the command
+\lstinline!\renewcommand{\familydefault}{\sfdefault}! in \cvtemplate.
+Use \lstinline!\sfdefault! for the default sans serif font, \lstinline!\rmdefault! for the default roman one, or any Tex font name. The general syntax is
+\begin{lstlisting}
+  \renewcommand{\familydefault}{<fontfamily>}
+  %\nopagenumbers{}
+\end{lstlisting}
+ Uncomment the line \lstinline!%\nopagenumbers{}! to suppress automatic page numbering for CVs longer than one page.
 
-\begin{verbatim}
-\usepackage[<options>]{geometry}
-\recomputelengths
-\end{verbatim}
+\subsubsection*{Adjusting input encoding}
+In case you are not using \Code{xelatex} or \Code{lualatex} which both use \Code{utf8} encoding by default uncomment the line containing \lstinline!\usepackage[utf8]{inputenc}! and adjust the encoding to your needs.
+\begin{lstlisting}
+  %\usepackage[utf8]{inputenc}
+  %\usepackage{CJKutf8}  % if you need to use CJK to typeset your resume in Chinese, Japanese or Korean
+\end{lstlisting}
+\subsubsection{Language specific setup}
+The \Code{babel} package can be loaded in the praeamble of your CV.
 
-where \verb|\recomputelengths| is required when changes are made to page layout lengths.
+That's about it for the general \Moderncv setup.
+The next section deals with inputting your personal data.
 
-Now we can get into the part most related to our curriculum vit\ae: our personal data. They will be inserted in the header of the first page, in the classic theme, or in the footer of every page, in the case of casual theme.
+\subsection{Personal data}
+Edit the the personal data section to reflect your personal information. This data will be inserted in the header of the first page of the curriculum vit\ae~ and/or in the footer of every page.
+This data will also appear on the cover letter.
+The default template settings are
+
+\begin{lstlisting}
+  \name{John}{Doe}
+  \title{R\'{e}sum\'{e} title}
+  \born{4 July 1776}
+  \address{street and number}{postcode city}{country}
+  \phone[mobile]{+1~(234)~567~890}
+  \phone[fixed]{+2~(345)~678~901}
+  \phone[fax]{+3~(456)~789~012}
+  \email{john@doe.org}
+  \homepage{www.johndoe.com}
+  % Social icons
+  \social[linkedin]{john.doe}
+  \social[xing]{john\_doe}
+  \social[twitter]{jdoe}
+  \social[github]{jdoe}
+  \social[gitlab]{jdoe}
+  \social[stackoverflow]{0000000/johndoe}
+  \social[bitbucket]{jdoe}
+  \social[skype]{jdoe}
+  \social[orcid]{0000-0000-000-000}
+  \social[researchgate]{jdoe}
+  \social[researcherid]{jdoe}
+  \social[telegram]{jdoe}
+  \social[whatsapp]{12345678901}
+  \social[signal]{12345678901}
+  \social[matrix]{@johndoe:matrix.org}
+  \social[googlescholar]{googlescholarid}
+
+  \extrainfo{additional information}
+  \photo[64pt][0.4pt]{picture}
+  \quote{Some quote}
+\end{lstlisting}
+\todo{explain adding pictures}
+In the actual template file, some information is marked as optional and can be commented out if one does not need it.
+The idea here is that there is options for those who need them.
+The commands are pretty self explanatory. Try out what you like and see what you need.
+
+\todox{Add note about how to cope with long names and long URLs. is this handled correctly?}
+
+\todox{explain the second optional argument of \code{\\social} command}
+
+
+\paragraph{Bibliography.}
+In case BibTeX is used, the bibliography settings are adjusted in the lines
+\begin{lstlisting}
+  % to show numerical labels in the bibliography (default is to show no labels)
+  % \renewcommand*{\bibliographyitemlabel}{[\arabic{enumiv}]}
+  % \renewcommand{\refname}{Articles}
+
+  % bibliography with mutiple entries
+  %\usepackage{multibib}
+  %\newcites{book,misc}{{Books},{Others}}
+\end{lstlisting}
+By default no labels are shown for bibliography entries.
+Having the line
+\lstinline!%\renewcommand*{\bibliographyitemlabel}{[\arabic{enumiv}]}! uncommented,
+allows to fine tune the labels.
+The line \lstinline!%\renewcommand{\refname}{Articles}! allows to redefine the bibliography heading string ``Publications'' that is shown by default.
+Finally, adjustments using the multibib package can be done in the last two lines shown here.
+
+\paragraph{Note.} \biblatex~ is not supported as of now.
+
+\subsection{Modifying CV content}
+\subsubsection{Structuring the CV}
+The CV can be structured into sections and subsections. Use
+
+\begin{lstlisting}
+  \section{<title>}
+\end{lstlisting}
+
+and
+
+\begin{lstlisting}
+  \subsection{<title>}
+\end{lstlisting}
+
+as with any other document style.
+
+\subsubsection{\texttt{moderncv} macros}
+
+The \Moderncv package provides several macros to add content to you CV. The easiest way to understand their intended use is to have a look at how they are used in the template.
+Nonetheless, we list the macros here along with a short description of their intended use.
+
+\paragraph{\code{\\cvitem}.} Simple entry taking two arguments, a descriptor and a body. Flexible command that can be used to list job experiences and similar. Usage
+\begin{lstlisting}
+  \cvitem{<descriptor>}{<body>}
+\end{lstlisting}
+
+\paragraph{\code{\\cvdoubleitem.}} Two column cvitem. Takes four arguments. It is intended to enter skills such as computer skills or language skills in a two-column fasion. Usage
+\begin{lstlisting}
+  \cvdoubleitem{<category_1>}{<descriptor_1>}{<category_2>}{<descriptor_2>}
+\end{lstlisting}
+
+\paragraph{\code{\\cvitemwithcomment.}} Expands the cvitem command by an additional argument. Takes three arguments, a descriptor, a skill level  and a comment. It is intended to enter skills such as computer skills or language skills. Usage
+\begin{lstlisting}
+  \cvitemwithcomment{<descriptor>}{<skill_level>}{<comment>}
+\end{lstlisting}
+
+\paragraph{\code{\\cventry.}} Command taking six arguments intended to enter education or job experience.
+Arguments 3 to 6 can be left empty. In case longer descriptive texts are not broken properly a minipage can be used in argument 6. Alternatively \code{\\newline\{\}} can be used to break lines.  Usage
+\begin{lstlisting}
+  \cventry{<year--year>}{<Degree>}{<Institution>}{<City>}{<Grade>}{<Description>}
+  \cventry{<year--year>}{<Job_title>}{<Employer>}{<City>}{}{<line_1>\newline{}<line_2>}
+\end{lstlisting}
+
+\paragraph{\code{\\cvlistitem.}} Command taking one argument intended to enter a bullet list item.
+Very long lines get broken. Usage
+\begin{lstlisting}
+  \cvlistitem{<Item>}
+\end{lstlisting}
+
+\paragraph{\code{\\cvlistdoubleitem.}} Command taking two argument intended typeset a bullet list in two columns. Usage
+\begin{lstlisting}
+  \cvlistdoubleitem{<Item_1>}{Item_2>}
+\end{lstlisting}
+
+\paragraph{\code{cvcolumns.}} Environment to tipeset multi-column cvitems. This can be combined with the itemize environment.
+The multicolumn environment is added with
+\begin{lstlisting}
+  \begin{cvcolumns}
+  \end{cvcolumns}.
+\end{lstlisting}
+Each column can be added with the \code{\\cvcolumn[<width>]{<content>}} command, where <width> is a number between 0 and 1 controling the width of the column.
+Usage
+\begin{lstlisting}
+  \begin{cvcolumns}
+    \cvcolumn{<category_1>}{<content>}
+    \cvcolumn{<category_2>}{<content>}
+    \cvcolumn[0.5]{<content>}
+  \end{cvcolumns}
+\end{lstlisting}
+
+\paragraph{Skill matrix.} The skill matrix is a table intended to display skills such as computer skills or project management skills graphically on a scale of one to five.
+The skill matrix table consists of several elements.
+\begin{itemize}
+  \item the graphical representation of the skill on a scale from one to five,
+  \item the legend, explaining the meaning of the scale,
+  \item a header line, to explain the meaning of the table columns
+  \item the actual skill entries.
+\end{itemize}\medskip
+
+{\bfseries Skill representation. } The graphical representation of skill can be entered with the command
+\begin{lstlisting}
+  \cvskill{<1-5>}
+\end{lstlisting}
+It can be used outside of the skill matrix, too. \medskip
+
+
+{\bfseries Legend. } The standard legend can be created by the command
+\begin{lstlisting}
+  \cvskilllegend
+  % or
+  \cvskilllegend*{<descriptor>}
+  % or
+  \cvskilllegend*[<post_padding>]{<descriptor>}
+\end{lstlisting}
+The first form inserts the legend with no descriptor in its standard form without any lines.
+Adding an asterix * includes dashed lines.
+The second form makes it possible to adjust the post padding of the legend. \code{<post_padding>} needs to be a valid length like 1em or 1ex.
+
+The most general form of the skill legend command can be used to translate the legend descriptions into other languages as well as add a name descriptor.
+
+\begin{lstlisting}
+  \cvskilllegend[*][<post_padding>][<first_level>][<second_level>][<third_level>][<fourth_level>][<fifth_level>]{<name>}
+  % example: German translation
+  \cvskillplainlegend[0.2em][Grundkenntnisse][Grundkenntnisse und eigene Erfahrung in Projekten][Umfangreiche Erfahrung in Projekten][Vertiefte Expertenkenntnisse][Experte/Guru]{Legende}
+\end{lstlisting}
+
+An alternative legend style with the first three skill levels in one column is provided by
+\begin{lstlisting}
+  \cvskillplainlegend[*][<post_padding>][<first_level>][<second_level>][<third_level>][<fourth_level>][<fifth_level>]{<name>}
+\end{lstlisting} \medskip
+
+{\bfseries Header line. } To add a header line to the skill matrix table use
+\begin{lstlisting}
+  \cvskillhead[-0.1em]%   standard legend in english, adjust padding
+  % example german translation
+  \cvskillhead[0.25em][Level][F\"ahigkeit][Jahre][Bemerkung]
+  % general form
+  \cvskillhead[<post_padding>][<Level>][<Skill>][<Years>][<Comment>]%
+\end{lstlisting}
+
+{\bfseries Skill matrix entry. } The skill matrix entry can be added with the \code{cvskillentry} command
+\begin{lstlisting}
+  % general form
+  \cvskillentry[*][<post_padding>]{<skill_cathegory>}{<0-5>}{<skill_name>}{<years_of_experience>}{<comment>}%
+  % Example usages:
+  \cvskillentry*{Language:}{3}{Python}{2}{I'm so experienced in Python and have realised a million projects. At least.}
+  \cvskillentry{}{2}{Lilypond}{14}{So much sheet music! Man, I'm the best!}
+\end{lstlisting}
+The asterix * toggles the inclusion of a dashed line.
+Some length adjustments can be made to the skill matrix and will be explained in section \ref{section:length:skillmatrix}.
+
+\subsection{Letter of motivation}
+
+\todo{add short explanation of motivation letter.}
+To add a subject to the letter of motivation or close with your signature see sections \ref{section:add:subject} and \ref{section:add:signature}
+
+
+
+\section{Customization}
+\label{section:customization}
+\subsection{Styles and their options}
+\label{section:customization:stylesAndOptions}
+Each style allows fine tuning through passing options to the \Code{\\moderncvstyle} command. The general syntax
+\begin{lstlisting}
+  \moderncvstyle[<option1>,<option2>,...]{<style>}
+\end{lstlisting}
+for passing options follows the usual \LaTeX\ scheme.
+Each style defines their own options and not all options are available for each style.
+Below is a list of all options available along with a short description.
+
+\paragraph{\texttt{casual}.} This style allows the following options which \emph{only} affect footer and head style:\medskip
+
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.72\textwidth}}
+ {\bfseries \code{head alignment}:}  & values: \Code{left}, \Code{right} (default). This option allows to influence the alignment of the title and the picture if one is included.  \\
+ {\bfseries \texttt{name}:} & values: \Code{alternate}. Displays the name in all lowercase letters. Differentiation of the name is done by color (disabled by default). This feature is discouraged for  longer names.\\
+ {\bfseries \code{data in head}:} & values: \Code{details}, \Code{nodetails} (default). Show personal data in the header (\code{details}) or in the footer (\code{nodetails} (default)). \\
+ {\bfseries \code{symbols:}}   & values: \Code{symbols} (default), \code{nosymbols}. These options let you chose between the inclusion of icons for the personal data or text based abbreviations.
+\end{tabular}\medskip
+\endgroup
+
+\paragraph{\texttt{classic}.} This style allows the following options which \emph{only} affect footer and head style:\medskip
+
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.75\textwidth}}
+ {\bfseries \code{alignment}:}  & values: \Code{left} (default), \code{right}. The option toggles the alignment of the address block and the picture.  \\
+ {\bfseries \code{data in head}:} & values: \Code{details}, \Code{nodetails} (default). Show personal data in the header (\code{details}) or in the footer (\code{nodetails} (default)). \\
+ {\bfseries \code{symbols:}}   & values: \Code{symbols} (default), \code{nosymbols}. These options let you chose between the inclusion of icons for the personal data or text based abbreviations.
+\end{tabular}\medskip
+\endgroup
+
+\paragraph{\texttt{banking}.} This style allows the following options:\medskip
+
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.68\textwidth}}
+  {\bfseries \code{alignment (body)}:}  & values: \Code{left} (default), \Code{center}, \code{right}. This option allows to influence the alignment of the entries in the style.   \\
+  %
+  {\bfseries \code{rule style}:}  & values: \Code{fullrules}, \Code{shortrules}, \Code{mixedrules} (default), \code{norules}. This option allows to adjust the rules used in the style.   \\
+  {\bfseries \code{data in head}:} & values: \Code{details}, \Code{nodetails} (default). Show personal data in the header (\code{details}) or in the footer (\code{nodetails} (default)). \\
+ {\bfseries \code{symbols:}}   & values: \Code{symbols} (default), \code{nosymbols}. These options let you chose between the inclusion of icons for the personal data or text based abbreviations.
+\end{tabular}\medskip
+\endgroup
+
+\paragraph{\texttt{oldstyle}.} This style allows the following options:\medskip
+
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.73\textwidth}}
+  {\bfseries \code{data in head}:} & values: \Code{details}, \Code{nodetails} (default). Show personal data in the header (\code{details}) or in the footer (\code{nodetails} (default)). \\
+ {\bfseries \code{symbols:}}   & values: \Code{symbols} (default), \code{nosymbols}. These options let you chose between the inclusion of icons for the personal data or text based abbreviations.
+\end{tabular}\medskip
+\endgroup
+
+\paragraph{\texttt{fancy}.} This style allows the following options:\medskip
+
+\begingroup
+\renewcommand{\arraystretch}{1.1}
+\begin{tabular}{r@{\hspace{2ex}}p{0.73\textwidth}}
+  {\bfseries \code{data in head}:} & values: \Code{details}, \Code{nodetails} (default). Show personal data in the header (\code{details}) or in the footer (\code{nodetails} (default)). \\
+ {\bfseries \code{symbols:}}   & values: \Code{symbols} (default), \code{nosymbols}. These options let you chose between the inclusion of icons for the personal data or text based abbreviations.
+\end{tabular}\medskip
+\endgroup
+
+
+\paragraph{Note.} From each option category only one of the possibilities listed can be passed at a time, e.g.:
+\begin{lstlisting}
+  \moderncvstyle[left,nosymbols]{casual}
+\end{lstlisting}
+
+
+\subsection{Adjusting colors}
+The colors of each style can be readjusted.
+
+\paragraph{Note.} For the color adjustments to take effect, it is paramount to load the color theme \emph{before} the \moderncv~ style, i.e.
+
+\begin{lstlisting}
+  \moderncvcolor{blue}
+  \moderncvstyle{casual}
+\end{lstlisting}
+not
+\begin{lstlisting}
+  \moderncvstyle{casual}
+  \moderncvcolor{blue}
+\end{lstlisting}
+like in older template versions.
+
+\paragraph{Base colors.} Each style defines three main colors, \code{color0}, \code{color1} and \code{color2}. So far in all styles, \code{color0} is black and the main text color. \code{color1} is the main theme color, like blue, green, etc and finally, \code{color2} is a some form of grey used for the user data etc. These colors can be redefined by using e.g.
+
+\begin{lstlisting}
+  \definecolor{color1}{rgb}{0.55,0.55,0.55}% dark grey
+\end{lstlisting}
+or
+\begin{lstlisting}
+  \colorlet{color1}{<my_color>}% black
+\end{lstlisting}
+Each mechanism to name and define colors used my the \Code{xcolor} package can be used to redefine the colors.
+
+\paragraph{Fine tuning.} If yet a finer control over the color scheme of the style is desired, the following colors are being used internally and can be redefined at will.
+
+\paragraph{casual}
+\begin{lstlisting}
+% head and footer
+\colorlet{lastnamecolor}{color1}
+\colorlet{namecolor}{lastnamecolor}
+\colorlet{headrulecolor}{color1}
+\colorlet{firstnamecolor}{lastnamecolor!50}
+\colorlet{titlecolor}{color2}
+\colorlet{addresscolor}{color2}
+\colorlet{quotecolor}{color1}
+\colorlet{pictureframecolor}{color1}
+% body
+\colorlet{bodyrulecolor}{color1}
+\colorlet{sectioncolor}{color1}
+\colorlet{subsectioncolor}{color1}
+\colorlet{hintstylecolor}{color0}
+% letter
+\colorlet{letterclosingcolor}{color2}
+% skillmatrix
+\colorlet{skillmatrixfullcolor}{color1}
+\colorlet{skillmatrixemptycolor}{color2!30}
+
+\end{lstlisting}
+
+
+\subsection{Modifying symbols and icons}
+\subsubsection{Icons}
+As we have seen in section \ref{section:customization:stylesAndOptions}, the use of icons can be
+influenced by the \code{symbols} and \Code{nosymbols} options that can be passed to the \Code{\\moderncvstyle} command. \medskip
+
+The icons used in the display of the personal data (phone numbers, email, fax, social accounts, etc.) can be customized by redefining the internal commands representing the symbols.
+\begin{lstlisting}
+  \renewcommand*{<\symbolcommand>}{{\small<\symbol>}~}
+\end{lstlisting}
+Using \code{\\small} is optional, but by default all icons are rendered using the small
+versions of the symbols used. \emph{The above command is what should be used if one merely whishes to
+  replace an icon/symbol leaving the size consistent with the default icons}.
+The tilde ensures proper spacing after the symbols and is recommended as well.
+
+Currently \moderncv\ supports the following commands as \code{<\\symbolcommand>}:
+\begin{itemize}
+  \item \lstinline!\addresssymbol!
+  \item \lstinline!\mobilephonesymbol!
+  \item \lstinline!\fixedphonesymbol!
+  \item \lstinline!\faxphonesymbol!
+  \item \lstinline!\emailsymbol!
+  \item \lstinline!\homepagesymbol!
+  \item \lstinline!\linkedinsocialsymbol!
+  \item \lstinline!\xingsocialsymbol!
+  \item \lstinline!\twittersocialsymbol!
+  \item \lstinline!\githubsocialsymbol!
+  \item \lstinline!\gitlabsocialsymbol!
+  \item \lstinline!\stackoverflowsocialsymbol!
+  \item \lstinline!\googlescholarsocialsymbol!
+  \item \lstinline!\telegramsocialsymbol!
+  \item \lstinline!\whatsappsocialsymbol!
+  \item \lstinline!\signalsocialsymbol!
+  \item \lstinline!\matrixsocialsymbol!
+  \item \lstinline!\orcidsocialsymbol!
+  \item \lstinline!\researchgatesocialsymbol!
+  \item \lstinline!\researcheridsocialsymbol!
+  \item \lstinline!\bitbucketsocialsymbol!
+  \item \lstinline!\skypesocialsymbol!
+  \item \lstinline!\bornsymbol!
+\end{itemize}
+The possible options for \Code{<\\symbol>} depend on the package that is used.
+By default the \Code{marvosym} package is loaded if \Code{pdflatex} is used and the packages
+\code{academicons} and \Code{fontawesome5} are loaded if \Code{lualatex} or \Code{xelatex} are
+employed. The documentation including full lists of all available symbols and icons can be found
+in the respective package documentations \medskip
+
+\begin{tabular}{l}
+  \url{https://ctan.org/pkg/marvosym}\\[1ex]
+  \url{https://ctan.org/pkg/fontawesome5}\\[1ex]
+  \url{https://ctan.org/pkg/academicons}
+\end{tabular}
+
+\paragraph{Example.}
+If one wanted to use the dingbat fonts to substitute fixed phone symbol one would load the \Code{pifont} package in the preamble, then substitute the default symbol \Code{\\fixedphonesymbol} with the dingbat symbol \ding{38}\ by:
+\begin{lstlisting}
+  \renewcommand*{\fixedphonesymbol}{\ding{38}~}
+\end{lstlisting}
+
+\subsubsection{Listing labels}
+The labels used in \Code{itemize} environments or the \Moderncv macros \code{cvlistitem} and \Code{cvlistdoubleitem} can be affected in two different ways:
 
 \begin{itemize}
-\item \verb|\firstname{John}|
-\item \verb|\familyname{Doe}|
-\item \verb|\title{Resum\'e title}|: optional
-\item \verb|\address{street and number}{postcode city}|: optional
-\item \verb|\mobile{mobile}|: optional
-\item \verb|\phone{phone}|: optional
-\item \verb|\fax{fax}|: optional
-\item \verb|\email{email}|: optional
-\item \verb|\extrainfo{additional information}|: optional; here you can put, for example, the address of your website
-\item \verb|\photo[64pt]{picture}|: optional; \texttt{64pt} is the height the picture, you can set here the size you prefer; \texttt{picture} is the name of the picture file
-\item \verb|\quote{Some quote}|: optional
+ \item By redefining the internal commands \code{\\labelitemi}, \code{\\labelitemii} as well as
+  \code{\\labelitemiii} and \code{\\labelitemiv}, e.g.
+  \begin{lstlisting}
+  \renewcommand{\labelitemi}{-}.
+  \end{lstlisting}
+  This will affect both, the \Code{itemize} environments as well as the macros \Code{cvlistitem} and \Code{cvlistdoubleitem}.
+  \item If one only whishes to change the labels of the macros \Code{cvlistitem} and \Code{cvlistdoubleitem}, one needs to redefine the \code{\\listitemsymbol}, e.g.
+\begin{lstlisting}
+  \renewcommand{\listitemsymbol}{-}.
+\end{lstlisting}
+This will leave the definitions of \Code{itemize} environments untouched.
 \end{itemize}
 
-Finally you can suppress automatic page numbering for CVs longer than one page:
+\subsection{Adjusting lengths}
+\todo{Add more adjustable lengths}
+Some of the lengths in moderncv can be adjusted.
+The hints column can be adjusted by issuing
+\begin{lstlisting}
+  \setlength{\hintscolumnwidth}{3cm}
+\end{lstlisting}
 
-\begin{verbatim}
-\nopagenumbers{}
-\end{verbatim}
+For the classic style, the width of the space for the name can be adjusted to avoid breaks.
+One should be careful though, the length is normally calculated to avoid any overlap with the personal info. This should be used at one's own typographical risk.
+\begin{lstlisting}
+  \setlength{\makecvheadnamewidth}{10cm}
+\end{lstlisting}
 
-\subsection{Examples}
-
-In practice, you will type:
-
-\begin{verbatim}
-\documentclass[11pt,a4paper]{moderncv}
-
-% moderncv themes
-\moderncvtheme[green]{casual}
-
-% character encoding
-\usepackage[utf8]{inputenc}
-
-% adjust the page margins
-\usepackage[scale=0.8]{geometry}
-\recomputelengths
-
-% personal data
-\firstname{John}
-\familyname{Doe}
-\title{Design enthusiast}
-\address{12 somestreet}{3456 somecity}
-\mobile{+123 456 7890}
-\phone{+12 (3)456 78 90}
-\fax{+12 (3)456 78 90}
-\email{jdoe@design.org}
-\extrainfo{\weblink{www.ctan.org}}
-\photo[64pt]{jdoe_picture}
-\quote{Any intelligent fool can make things bigger, more complex,
-and more violent. It takes a touch of genius -- and a lot of courage -- to
-move in the opposite direction.}
-
-\begin{document}
-\maketitle
-
-... <what you'll see in the next section>
-
-\end{document}
-\end{verbatim}
-
-to obtain a casual moderncv in green, as shown in figure \ref{fig:casual}, and you will substitute the line describing the theme with:
-
-\begin{verbatim}
-% moderncv themes
-\moderncvtheme[blue]{classic}
-\end{verbatim}
-
-to obtain a classic moderncv in blue, as shown in figure \ref{fig:classic}.
+% The different lengths used by moderncv are customizable by
+% \begin{lstlisting}
+% \setlength{<length>}{<new_dimensions>}
+% \end{lstlisting}
+% where \Code{<length>} are \Code{quotewidth}, \Code{separatorcolumnwidth}, \Code{maincolumnwidth}, \Code{doubleitemmaincolumnwidth}, \Code{listitemsymbolwidth}, \Code{listdoubleitemmaincolumnwidth},
 
 
-\begin{figure}[p]
- \centering
- \fbox{\includegraphics[angle=90,width=\textwidth]{cv_casual.pdf}}
- \caption{An example of casual moderncv in green.}
- \label{fig:casual}
-\end{figure}
+\subsubsection{Lengths in the skillmatrix}
+\label{section:length:skillmatrix}
+The column widths of the skill matrix legend as well as the skill matrix columns can be tweaked.
 
-\begin{figure}[p]
- \centering
- \fbox{\includegraphics[angle=90,width=\textwidth]{cv_classic.pdf}}
- \caption{An example of classic moderncv in blue.}
- \label{fig:classic}
-\end{figure}
+Adjusting the width of the skill matrix columns can be done by
+\begin{lstlisting}
+  \setcvskillcolumns[<width>][<factor>][<exp_width>]
+  %% <width>, <exp_width> should be lengths smaller than \textwidth, <factor> needs to be between 0 and 1.
+  %% Examples:
+  \setcvskillcolumns[5em][][]%    adjust first column. Same as \setcvskillcolumns[5em]
+  \setcvskillcolumns[][0.45][]%   adjust third (skill) column. Same as \setcvskillcolumns[][0.45]
+  \setcvskillcolumns[][][\widthof{``Year''}]%     adjust fourth (years) column.
+  \setcvskillcolumns[][0.45][\widthof{``Year''}]%
+  \setcvskillcolumns[\widthof{``Languag''}][0.48][]
+  \setcvskillcolumns[\widthof{``Languag''}]%
+\end{lstlisting}
 
-\section{Customize sections}
+In order to adjust the legend columns, one can use
+\begin{lstlisting}
+  \setcvskilllegendcolumns[<width>][<factor>]
+  %% <factor> needs to be between 0 and 1. <width> should be a length smaller than \textwidth
+  %% Examples:
+  \setcvskilllegendcolumns[][0.45]
+  \setcvskilllegendcolumns[\widthof{``Legend''}][0.45]
+  \setcvskilllegendcolumns[0ex][0.46] % this is usefull for the banking style
+\end{lstlisting}
 
-Now we are ready to edit the part between \verb|\begin{document}| and \verb|\end{document}|.
+\subsection{Pagebreaks and orphaned section headers}
+If \latex\ breaks pages just after \code{\\section} or \code{\\subsection} commands, try adjusting
+the the stretchability of the page
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{<length>} %
+  \setlength{\cvsubsectionstretchability}{<length>},
+\end{lstlisting}
+for example
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{\baselineskip} % or
+  % \setlength{\cvsubsectionstretchability}{100pt},
+\end{lstlisting}
+in the document. It tells \latex\ that it needs approximately \Code{<length>} extra length after
+section and subsection commands.
 
-As you can seen in figure \ref{fig:casual} e \ref{fig:classic}, you can divide your CV into sections, each of them describing what you are, what you know and what you have done in your life. Every section is divided into items chosen from different flavours. More in details:
+By default,
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{.9\baselineskip}
+  \setlength{\cvsubsectionstretchability}{.9\baselineskip}
+\end{lstlisting}
 
-\subsection{Section}
+is set in the package.
+This should solve orphaned \Code{\\section} and \Code{\\subsection} commands that are used alone for most people.
+However \latex\ does not check for content. So in case of using
+\begin{lstlisting}
+  \section{blub}
+  \subsection{blubblub}
+\end{lstlisting}
+directly one after the other the subsection might be unorphaned leaving enough space on the previous page for \latex\ not to also break \Code{\\section\{blub\}} to the new page.
+One way of solving this is to increase \Code{\\cvsectionstretchability} to an artificially high value to force the break of the section header.
+However, this will change the behaviour for all \Code{\\section} commands in your CV and might cause a page break in a situation where it would not have been necessary (down the line on another page), e.g. in a case like
+\begin{lstlisting}
+  \section{blub}
+  \cvitem{blubblub}
+\end{lstlisting}
 
-The command to open a new section is:
+in which the item previously would have fit on the page.
+It is therefore recommended to force the page break manually by a \newpage command in this special case.
 
-\begin{verbatim}
-\section{<title>}
-\end{verbatim}
+\paragraph{Experts only:}
+Internally a custom needspace command is being used:
 
-and every section can be divided into subsections:
-
-\begin{verbatim}
-\subsection{<title>}
-\end{verbatim}
-
-If necessary, there is a command to close the section:
-
-\begin{verbatim}
-\closesection{}
-\end{verbatim}
-
-and even one to create an empty section:
-
-\begin{verbatim}
-\emptysection{}
-\end{verbatim}
-
-An example of their usage can be the next one:
-
-\begin{verbatim}
-\section{Section with your own content}\closesection
-Your content here, inside the normal \LaTeX{} environment.
-You can use any regular \LaTeX{} command, display mathematics
-\[e =m\,c^2,\]
-put some table or figure, \dots
-
-\emptysection{}
-\cvitem{Now}{Back to moderncv layout, without making a new section :-)}
-\end{verbatim}
-
-whose result is shown in figure \ref{fig:ex_sec}.
-
-\begin{figure}[!ht]
- \centering
- \fbox{\includegraphics[width=0.9\textwidth]{ex_sec}}
- \caption{Example of usage of section commands.}
- \label{fig:ex_sec}
-\end{figure}
-
-\subsection{Items}
-
-Inside sections, you can choose between different kinds of items depending on the purpose:
-
-\begin{itemize}
- \item in the sections describing your education or your job experiences, you can use:
- \begin{verbatim}
-\cventry{years}{degree/job title}{institution/employer}
-{localization}{optional: grade/...}
-{optional: comment/job description}
-  \end{verbatim}
-\vspace{-20pt}
-where the last three arguments can be left empty
- \item inside `language' cvsection environment, you can type every entry with:
- \begin{verbatim}
-\cvlanguage{name}{level}{comment}
- \end{verbatim}
- \item inside `computer skills' cvsection environment, you can type every entry with:
- \begin{verbatim}
-\cvcomputer{category}{programs}{category}{programs}
- \end{verbatim}
- \item to typeset lines with a hint on the left:
- \begin{verbatim}
-\cvline{leftmark}{text}
- \end{verbatim}
- \item to typeset entry with a description on the left, but in two columns inside a cvsection:
- \begin{verbatim}
-\cvdoubleitem{subtitle}{text}{subtitle}{text}
- \end{verbatim}
- \item to typeset lists on one column inside a cvsection:
- \begin{verbatim}
-\cvlistitem{point1}
- \end{verbatim}
- \item to typeset lists on two columns inside a cvsection:
- \begin{verbatim}
-\cvlistdoubleitem{point1}{point2}
- \end{verbatim}
- \item to add a section listing all your publications stored in a BibTeX file:
- \begin{verbatim}
-\nocite{*}
-\bibliographystyle{plain}
-\bibliography{BibTeX_file}
- \end{verbatim}
-\vspace{-20pt}
- where the name of the section title can be changed by redefining the \texttt{refname} with  \verb|\renewcommand{\refname}{<new_name>}|
-\end{itemize}
-
-\subsubsection*{Example}
-
-Let's put all together and see in figure \ref{fig:sections} what is the result:
-
-\begin{verbatim}
-... preamble ...
-\begin{document}
-\section{Education}
-\cventry{year--year}{Degree}{Institution}{City}{\textit{Grade}}{Description}
-\cventry{year--year}{Degree}{Institution}{City}{\textit{Grade}}{Description}
-%
-\section{Master thesis}
-\cvline{title}{\emph{Title}}
-\cvline{supervisors}{Supervisors}
-\cvline{description}{\small Short thesis abstract}
-%
-\section{Experience}
-\subsection{Vocational}
-\cventry{year--year}{Job title}{Employer}{City}{}{Description}
-\cventry{year--year}{Job title}{Employer}{City}{}{Description}
-\subsection{Miscellaneous}
-\cventry{year--year}{Job title}{Employer}{City}{}%
-  {Description line 1\newline{}Description line 2}
-%
-\section{Languages}
-\cvlanguage{language 1}{Skill level}{Comment}
-\cvlanguage{language 2}{Skill level}{Comment}
-%
-\section{Computer skills}
-\cvcomputer{category 1}{XXX, YYY, ZZZ}{category 3}{XXX, YYY, ZZZ}
-\cvcomputer{category 2}{XXX, YYY, ZZZ}{category 4}{XXX, YYY, ZZZ}
-%
-\section{Interests}
-\cvline{hobby 1}{\small Description}
-\cvline{hobby 2}{\small Description}
-\cvline{hobby 3}{\small Description}
-%
-\closesection{}
-\pagebreak
-%
-\section{Extra}
-\cvlistitem{Item 1}
-\cvlistitem{Item 2}
-\cvlistitem{Item 3}
-%
-\section{Extra 2}
-\cvlistdoubleitem{Item 1}{Item 4}
-\cvlistdoubleitem{Item 2}{Item 5}
-\cvlistdoubleitem{Item 3}{}
-%
-% Publications from a BibTeX file
-\nocite{*}
-\bibliographystyle{plain}
-\bibliography{publications}  % 'publications' is the name of a BibTeX file
-%
-\end{document}
-\end{verbatim}
-
-\begin{figure}[!ht]
- \centering
- \fbox{\includegraphics[angle=90,width=\textwidth]{test_cvsection2.pdf}}\\
- \fbox{\includegraphics[angle=90,width=\textwidth]{test_cvsection1.pdf}}
-\caption{Example of usage of items inside cvsections.}
- \label{fig:sections}
-\end{figure}
-
-\section{More customizations}
-
-You have some useful commands to personalize your CV further.
-
-\subsection*{Modifying the symbols}
-You can modify the symbols used for the personal data (phone number, the email, \ldots) redefining \texttt{phonesymbol}, \texttt{emailsymbol}, \texttt{addresssymbol}, \texttt{mobilesymbol}, \texttt{faxsymbol}.
-
-For example: if you want to use the dingbat fonts, load the \texttt{pifont} package in the preamble, then substitute the default symbol \Telefon\ with the dingbat symbol \ding{38}\ by:
-\begin{verbatim}
-\renewcommand{\phonesymbol}{\ding{38}}
-\end{verbatim}
-
-You can change the symbol for lists in two way:
-\begin{itemize}
- \item redefining the command \texttt{listitemsymbol}: \verb|\renewcommand{\listitemsymbol}{-}|
- \item adding a specification for the label in \texttt{cvlistitem} and \texttt{cvlistdoubleitem}
-\end{itemize}
-
-For example: the  following code produces the result shown in figure \ref{fig:ex_items}.
-
-\begin{verbatim}
-\closesection{}                   % needed to renewcommands
-\renewcommand{\listitemsymbol}{-} % change the symbol for lists
-
-\section{Extra 1}
-\cvlistitem{Item 1}
-\cvlistitem{Item 2}
-\cvlistitem[+]{Item 3}            % optional other symbol
-
-\section{Extra 2}
-\cvlistdoubleitem[\Neutral]{Item 1}{Item 4}
-\cvlistdoubleitem[\Neutral]{Item 2}{Item 5}
-\cvlistdoubleitem[\Neutral]{Item 3}{}
-\end{verbatim}
-
-\begin{figure}[!hbt]
- \centering
- \fbox{\includegraphics[width=.8\textwidth]{ex_items.png}}
- \caption{Example of customization of the list labels.}
- \label{fig:ex_items}
-\end{figure}
-
-\subsection*{Adjusting lengths}
-The different lengths used by moderncv are customizable by
-\begin{verbatim}
-\setlength{<length>}{<new_dimensions>}
-\end{verbatim}
-where \texttt{<length>} are \texttt{quote\-width}, \texttt{sep\-a\-ra\-tor\-col\-umn\-width}, \texttt{main\-col\-umn\-width}, \texttt{doub\-le\-i\-tem\-main\-col\-umn\-width}, \texttt{list\-i\-tem\-sym\-bol\-width}, \texttt{list\-doub\-le\-i\-tem\-main\-col\-umn\-width},
-
-In particular, the first column can be set to any width. You can do that in two ways:
-\begin{itemize}
- \item using \verb|\sethintscolumnlength{<length>}|, where  \texttt{<length>} is the desired length in a unit LaTeX understands
- \item using \verb|\sethintscolumntowidth{<string>}|, where \texttt{<string>} is a string of the desired length (usually, the longest string that has to appear in the column)
-\end{itemize}
-
-\subsection*{Additional commands}
-There are commands to manage hypertextual links:
-\begin{itemize}
- \item[-] \verb|\weblink[optional text]{link}|
- \item[-] \verb|\httplink[optional text]{link}|
- \item[-] \verb|\emaillink[optional text]{link}|
-\end{itemize}
-
-There is a \verb|\today| command, useful for example if you need to add the date the CV was produced.
-
-\subsection*{Putting things at the end of CV}
-Sometimes there is the need to add some lines at the end of the CV. For example, in Italy it is necessary to add the permission to treat the personal data contained in the r\'esum\'e. You can do that dropping out of the layout of \texttt{moderncv} and pushing the lines at the end by the command \verb|\vfill|:
-\begin{verbatim}
-\emptysection{}\closesection
-\vfill
+\begin{lstlisting}
+  \NewDocumentCommand\@cvneedspace{m}{%
+    \begingroup
+      \setlength{\dimen@}{#1}%
+      \vskip\z@\@plus\dimen@
+      \penalty \withinstretchpenalty\vskip\z@\@plus -\dimen@
+      \vskip\dimen@
+      \penalty \poststretchpenalty%
+      \vskip -\dimen@
+      \vskip\z@skip % hide the previous |\vskip| from |\addvspace|
+    \endgroup
+  }
+\end{lstlisting}
+This means that alternatively to setting \Code{\\cvsectionstretchability} and/or \code{\\cvsubsectionstretchability} , penalties for pagebreaks can be influenced by redefining the internal penalties:
+\begin{lstlisting}
+ % must be between -100 and 9999. The higher the less likely a page break will occur.
+% This is where the page break should occur, so this number should not bee too high
+ \renewcommand{\withinstretchpenalty}{<-100...9999>}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+ \renewcommand{\poststretchpenalty}{<-100...9999>}.
+\end{lstlisting}
+The defaults are \Code{\\poststretchpenalty = 9999} and \Code{\\withinstretchpenalty = 0}.
+The penalties must be between -100 and 9999. The higher the value the less likely a page break will occur. A good explanation of this can be found under
 \begin{center}
-\textit{\small Ai sensi del D. Lgs. 196/2003 ...}
+  \url{https://tex.stackexchange.com/questions/348994/understanding-needspace}
 \end{center}
-\end{verbatim}
+
+
+
+\subsection{Tips and Tricks}
+\subsubsection{Including a scanned signature in letter of motivation}
+\label{section:add:signature}
+In case one wishes to add a scanned signature to the letter of motivation, place the following into your praeamble
+%%%% redefinition of makeletterclosing without printing Name and last name but inserting
+%%%% a signature png instead.
+\begin{lstlisting}
+  \makeatletter
+  \renewcommand*{\makeletterclosing}{
+    \@closing\\[3em]%
+    \includegraphics[height=1.5cm,width=5.5cm]{<signature.png>}
+    %   {\bfseries \@firstname~\@lastname}%
+    \ifthenelse{\isundefined{\@enclosure}}{}{%
+      \\%
+      \vfill%
+      {\color{color2}\itshape\enclname: \@enclosure}}}
+  \makeatother
+\end{lstlisting}
+
+\subsubsection{Including a subject in letter of motivation}
+\label{section:add:subject}
+In case you want to add a subject to you letter of motivation, add the following in the praeamble
+\begin{lstlisting}
+  %%%% redefine letterhead to add subject line
+  \makeatletter
+  \renewcommand*{\makeletterhead}{%
+    % recompute lengths (in case we are switching from letter to resume, or vice versa)
+    \recomputeletterlengths%
+    % recipient block
+    \begin{minipage}[t]{.5\textwidth}
+      \raggedright%
+      \addressfont%
+      {\bfseries\upshape\@recipientname}\\%
+      \@recipientaddress%
+    \end{minipage}
+    % date
+    \hfill% US style
+  %  \\[1em]% UK style
+    \@date\\[4em]% US informal style: "January 1, 1900"; UK formal style: "01/01/1900"
+    % opening
+    \raggedright%
+    {\bfseries\subject}\\[2em]
+    \@opening\\[1.5em]%
+    % ensure no extra spacing after \makelettertitle due to a possible blank line
+  %  \ignorespacesafterend% not working
+    \hspace{0pt}\par\vspace{-\baselineskip}\vspace{-\parskip}
+    }
+  \makeatother
+\end{lstlisting}
+The a subject can thereafter be added to the letter of motivation by
+\begin{lstlisting}
+  \subject{<subject_text>}
+\end{lstlisting}
+
+\subsubsection{Legal disclaimer at the end of CV}
+Some countries (e.g. Italy) require to add the permission to treat the personal data contained in the CV. This can be achieved by the command \code{\\vfill}. At the end of the last entry to your
+CV, add the following:%
+\footnote{Example provided by Cristina Sambo} %
+\begin{lstlisting}
+  \vfill
+  \begin{center}
+  \textit{\small Ai sensi del D. Lgs. 196/2003 ...}
+  \end{center}
+\end{lstlisting}
+
+
+
+\section{Implementation details}
+\label{section:implementationDetails}
+
+\subsection{Creating your own styles}
+\todox{Add explanation on how to create styles and and how to recombine headers, footers, bodies etc.}
+
+\subsection{Required packages}
+\label{section:implementationDetails:requiredPackages}
+In addition to the packages that \Moderncv itself provides the following packages are loaded internally:
+
+\begin{itemize}
+  \item\code{etoolbox},
+  \item\code{ifthen},
+  \item\code{xcolor},
+  \item\code{ifxetex,ifluatex},
+  \item\code{fontenc},
+  \item\code{url},
+  \item\code{hyperref},
+  \item\code{graphicx},
+  \item\code{fancyhdr},
+  \item\code{tweaklist},
+  \item\code{calc},
+  \item\code{xparse},
+  \item\code{microtype},
+  \item\code{expl3},
+  \item\code{tikz},
+  \item\code{changepage},
+  \item\code{fontawesome5},
+  \item\code{academicons},
+  \item\code{tgpagella}, %
+  \item\code{ebgaramond}, %
+  \item\code{kurier},
+  \item\code{multirow},
+  \item\code{arydshln}. %
+\end{itemize}
+
+Note that the \Code{tweaklist} package has been altered for the development of \Moderncv and ships
+with \moderncv.
+
+Most of the packages should be included in the \LaTeX\ distribution of your choice.
+
+\subsection{Known conflicts with other packages}
+\begin{enumerate}
+  \item The \Moderncv packages is incompatible with biber.
+\end{enumerate}
+
+\subsection{Known bugs}
+\input{known_bugs}
 
 \end{document}
diff --git a/moderncv.cls b/moderncv.cls
index 271ca6c..7f465ed 100644
--- a/moderncv.cls
+++ b/moderncv.cls
@@ -553,11 +553,11 @@
 \newcommand*{\cvdoubleitem}[5][.25em]{}
 
 % makes a resume line with a list item
-% usage: \cvlistitem[label]{item}
+% usage: \cvlistitem[spacing]{item}
 \newcommand*{\cvlistitem}[2][\listitemsymbol]{}
 
 % makes a resume line with 2 list items
-% usage: \cvlistdoubleitem[label]{item1}{item2}
+% usage: \cvlistdoubleitem[spacing]{item1}{item2}
 \newcommand*{\cvlistdoubleitem}[3][\listitemsymbol]{}
 
 % makes a typical resume job / education entry
diff --git a/template.tex b/template.tex
index 22be6f0..750b4ce 100644
--- a/template.tex
+++ b/template.tex
@@ -16,7 +16,6 @@
 
 % adjust the page margins
 \usepackage[scale=0.75]{geometry}
-\setlength{\footskip}{149.60005pt}                 % depending on the amount of information in the footer, you need to change this value. comment this line out and set it to the size given in the warning
 %\setlength{\hintscolumnwidth}{3cm}                % if you want to change the width of the column with the dates
 %\setlength{\makecvheadnamewidth}{10cm}            % for the 'classic' style, if you want to force the width allocated to your name and avoid line breaks. be careful though, the length is normally calculated to avoid any overlap with your personal info; use this at your own typographical risks...