%% 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,
% available at http://www.latex-project.org/lppl/.

\documentclass[a4paper,11pt]{article}

\title{\texttt{moderncv} User Guide\\{\small Package version v2.1.0}}
\author{Package by Xavier Danaux \\ \begin{small}Documentation by Cristina Sambo, 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}

%font options
\usepackage{txfonts}
\usepackage{marvosym}
\usepackage{pifont}

%margins, spacing and page layout
\PassOptionsToPackage{dvipsnames*,svgnames,table}{xcolor}
% \usepackage{geometry}
% \geometry{top=2.5cm, bottom=3cm}
\setlength{\parindent}{0pt} %(to suppress indentation when starting a new paragraph)
\frenchspacing %(to suppress additional space after a full stop)

%packages
\usepackage{graphicx}
\usepackage{xcolor}
\usepackage[labelfont=sl,font=small,width=0.9\textwidth]{caption}
\usepackage{marvosym}
\usepackage{latexsym}
\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},%
  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,googlescholarsocialsymbol,cvstretchability},%
  emphstyle={[2]\color{cvblue!60!cvgrey}\bfseries},
}

\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 
\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.
\todox{add mention of skill matrix feature once it is accepted}
\end{abstract}
\tableofcontents

\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. 

\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

\begin{tabular}{l}
  \moderncvCtan \\%[.5ex]
  \moderncvGithub
\end{tabular}

\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. 

\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. 

\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.

Test your setup by compiling \Cvtemplate and have a look at the result. 

\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}.

\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

\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

\noindent can be passed to the document class. 
By default, the \Moderncv document class uses \code{a4paper}, \code{11pt}, \code{final}. 

\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

\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

\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.


\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}.

\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.

\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}
That's about it for the general \Moderncv setup. 
The next section deals with inputting your personal data.

\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}
  \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[googlescholar]{googlescholarid}    

  \extrainfo{additional information}     
  \photo[64pt][0.4pt]{picture}
  \quote{Some quote}                     
\end{lstlisting}
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{explain the second optional argument of \code{\\social} command}
\todox{explain adding pictures}
\todox{Add note about how to cope with long names and long URLs. is this handled correctly?}

\todox{include figures of the styles here? or in the styles section}

\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}
\todox{add short explanation explaning that sectioning can be used.}
The command to open a new section is: 

\begin{verbatim}
\section{<title>}
\end{verbatim}

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 results 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}

\subsubsection{\texttt{moderncv} macros}

Inside sections, you can choose between different kind 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 are optional
 \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 \Code{refname} with  \verb|\renewcommand{\refname}{<new_name>}|
\end{itemize}

\subsection{More customizations}

You have some useful commands to personalize your CV further.


\subsection*{Adjusting lengths}
The different lengths used by moderncv are customizable by
\begin{verbatim}
\setlength{<length>}{<new_dimensions>}
\end{verbatim}
where \Code{<length>} are \Code{quote\-width}, \Code{sep\-a\-ra\-tor\-col\-umn\-width}, \Code{main\-col\-umn\-width}, \Code{doub\-le\-i\-tem\-main\-col\-umn\-width}, \Code{list\-i\-tem\-sym\-bol\-width}, \Code{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 way:
\begin{itemize}
 \item using \verb|\sethintscolumnlength{<length>}|, where  \Code{<length>} is the desired length in a unit LaTeX understands
 \item using \verb|\sethintscolumntowidth{<string>}|, where \Code{<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|\link[optional text]{URL}|
 \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.

\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{Colors}
The colors of each style can be readjusted. 
\todox{explain the three basic colors}

\paragraph{casual}
\begin{lstlisting}
 %-------------------------------------------------------------------------------
%               Colors
%-------------------------------------------------------------------------------
% 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!\bitbucketsocialsymbol!
  \item \lstinline!\skypesocialsymbol!
  \item \lstinline!\orcidsocialsymbol!
  \item \lstinline!\researchgatesocialsymbol!
  \item \lstinline!\researcheridsocialsymbol!
  \item \lstinline!\telegramsocialsymbol!
  \item \lstinline!\googlescholarsocialsymbol!
\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 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}

\subsection{Tips and Tricks}
\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}

\subsubsection{Orphaned sections}
If \latex~ breaks pages just after \code{\\section} or \code{\\subsection} commands, try adjusting
the the stretchability of the page
\begin{lstlisting}
  \setlength{\cvstretchability}{<length>},
\end{lstlisting}
for example
\begin{lstlisting}
  \setlength{\cvstretchability}{\baselineskip} % or
  % \setlength{\cvstretchability}{100pt},
\end{lstlisting}
in the document. It tells \latex that it needs approximately \Code{<length>} extra length after 
section and subsection commands. 

\paragraph{Experts only:}
Internally a custom needspace command is being used: 

\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{\\cvstretchability}, 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}
  \url{https://tex.stackexchange.com/questions/348994/understanding-needspace}
\end{center}



\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}
