summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex')
-rw-r--r--Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex377
1 files changed, 377 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex b/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex
new file mode 100644
index 00000000000..faccb9d8767
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex
@@ -0,0 +1,377 @@
+% *****************************************************************************
+\chapter{Usage}
+\quotes{%
+ “There are two ways to write error-free programs; only the third one works”%
+}{Alan J. Perlis}
+% *****************************************************************************
+
+\section{Requirements}
+
+When \textit{decorations} are not enabled and the \textit{default style} is not used, \classname has
+the following requirements:\codeskip
+\begin{lstlisting}[firstnumber=1,numbers=none]
+\NeedsTeXFormat{LaTeX2e}
+\RequirePackage{kvoptions} % for options
+\RequirePackage{etextools} % for lists and other useful tools
+\RequirePackage{ifthen} % for \ifthenelse command
+\RequirePackage{pifont} % for ding style (itemize environment)
+\RequirePackage{xstring} % for string utilities
+\RequirePackage{xparse} % for commands with multiple default arguments
+\end{lstlisting}\codeskip
+
+In addiction, if the default style is used, by means of the class option
+``\textit{style}''~\myref{sec:class-options}, this class requires:\codeskip
+\begin{lstlisting}[firstnumber=1,numbers=none]
+\RequirePackage{titlesec} % for title format and spacing
+\RequirePackage{fancyhdr} % for custom footer
+\RequirePackage{xcolor} % for color
+\RequirePackage{calligra} % for calligra font
+\RequirePackage{times} % times font
+\RequirePackage{marvosym} % symbols - phone
+\RequirePackage{amssymb} % symbols - email
+\end{lstlisting}\codeskip
+
+Finally, if decorations are enabled, by using the class option
+``\textit{withDec}``~\myref{sec:class-options}, this class also requires:\codeskip
+\begin{lstlisting}[firstnumber=1,numbers=none]
+RequirePackage{tikz} % for graphics
+\end{lstlisting}\codeskip
+
+\section{Class options}
+\label{sec:class-options}
+
+\classname can use any option supported by the \textit{article} class, on which is based. In
+addiction, it provides the following options:
+
+\def\tmpcolor{brown}
+\squishlist
+\item {\color{red}language=<\argname[\tmpcolor]{string}>}
+ \begin{myindent}
+ string language to pass to the \textit{babel} package for the document (\CV) language;
+ \end{myindent}
+\item {\color{red}cntdir=<\argname[\tmpcolor]{dirname}>}
+ \begin{myindent}
+ sets the directory name where \classname will search for files with the \CV contents.\\
+ The default one is ``Contents'';
+ \end{myindent}
+\item {\color{red}style=<\argname[\tmpcolor]{filemane}>}
+ \begin{myindent}
+ specifies the file name (with or without ``.tex'' extension) with the style commands.
+ By default, the file \textit{mycv\_default\_style}, provided by the class itself, is that used.
+ It is also possible to not use a style file by specifying the value ``none'' as file name;
+ \end{myindent}
+\item {\color{red}mdlname=<\argname[\tmpcolor]{name}>}
+ \begin{myindent}
+ registers a name for the layout (model) intended to be used: in this way is possible, for
+ example, to select the appropriate layout configuration file or a layout-specific portion of
+ code;
+ \end{myindent}
+\item {\color{red}withDec}
+ \begin{myindent}
+ enables support for decorations (provided by the \textit{TikZ} package);
+ \end{myindent}
+\squishend
+
+\section{Class commands}
+
+Here follows the complete list of the commands provided by \classname. The style commands
+%~\myref{sub:style-commands}
+are only available if the class option ``\textit{style}'' was used~\myref{sec:class-options}. The
+same goes for the decoration commands,
+%~\myref{sub:decoration-commands}
+which need the class option ``\textit{withDec}'' to be used. In the following text of this section,
+when present, the form {\color{blue}\omissis} (or {\color{blue}<...>}) indicates the default choice
+for an optional argument of a command.
+
+\subsection{Conditional}
+
+\squishlist
+\item
+ \cmdname{ifoption}\marg{option}\arghsep\marg{true}\arghsep\marg{false}\argvsep
+ \cmdname{ifmodel}\marg{mdlname}\arghsep\marg{true}\arghsep\marg{false}\cmddsep
+ \textit{ifoption} checks whether \argname{option} was used,
+ while \textit{ifmodel} checks whether \argname{mdlname} was registered in the class; then both
+ commands use the appropriate \argname{true} or \argname{false} block of code.
+\squishend
+
+\subsection{Default style}
+\label{sub:style-commands}
+
+\squishlist
+\item \cmdname{mysectionTitleFormat}
+ \begin{myindent}
+ \dargone{titlerule-color-above}{myheadingscolor}\argvsep
+ \dargone{titlerule-color-below}{myheadingscolor}
+ \end{myindent}\cmddsep
+ \argname{titlerule-color-above} is the color for the rule above a section name, while
+ \argname{titlerule-color-below} is for that below. \textit{myheadingscolor} is the default color.
+\item \cmdname{mysectionTitleSpacing}
+ \begin{myindent}
+ \dargone{left}{$0\text{pt}$}\arghsep
+ \dargone{beforesep}{$0\text{pt}$}\arghsep
+ \dargone{aftersep}{$5\text{pt}$}
+ \end{myindent}\cmddsep
+ this command is just an alias for
+ \textit{\textbackslash{titlespacing}\{\textbackslash{section}\}\{\argname{left}\}%
+ \{\argname{beforesep}\}\{\argname{aftersep}\}}. See the \textit{titlesec} package for further
+ information.
+\item \cmdname{mycfoot}
+ \marg{text}\cmddsep
+ adds \argname{text} to the page footer. It may be useful, for example, to show information
+ about the last document update.% (\textbackslash{}mycfoot\{Last update \textbackslash{}today\}).
+\squishend
+
+\subsection{Decorations}
+\label{sub:decoration-commands}
+
+\classname provides some commands for using the \textit{TikZ} decorations. The support
+provided is not complete at all (on the other hand \textit{TikZ} has a huge amount of
+functionality), but is enough for this class purposes. The only \textit{TikZ} path supported is
+\textit{rectangle}.
+%\\ Here follows the provided commands list:
+
+\squishlist
+\item \cmdname{mydecorationsPathmorphing}[*]
+ \begin{myindent}
+ \dargone{show-decoration}{$1$}\argvsep
+ \marg{decoration-type}\argvsep
+ \dargone{decoration-color}{gray}\argvsep
+ \dargtwo{shading-type}{radial}\argvsep
+ \dargtwo{background-color}{white}%
+ \end{myindent}\cmddsep
+ \argname{show-decoration}, if equals $1$, does show the decoration \argname{decoration-type},
+ while if $0$ does not.
+ \textit{Starred} version uses the shading technique, unlike the \textit{not starred} one, and the
+ last argument is the background shading color.\\
+ For \textit{not starred} version, the argument \argname{shading-type} is not considered
+ (just for a matter of clarity, a ``none'' value may be used), and the last argument is simply the
+ background color.\\
+ \argname{decoration-type} was tested with the following values: ``shape'', ``straight'',
+ ``zigzag``, ``random steps``, ``saw``, ``bent``, ``bumps``, ``coil``, ``snake'' and
+ ``Koch snowflake``.\\
+ \argname{shading-type} was tested with ``radial'' and ``ball'' shadings.
+\item \cmdname{mydecorationsShape}
+ \begin{myindent}
+ \dargone{show-decoration}{$1$}\arghsep
+ \marg{decoration-type}\arghsep
+ \dargone{decoration-color}{gray}
+ \end{myindent}\cmddsep
+ \argname{show-decoration}, if equals $1$, does show the decoration \argname{decoration-type},
+ while if $0$ does not.
+ \argname{decoration-type} was tested with the following ones: ``dart'', ``diamond'',
+ ``rectangle'' and ``star''.
+\item \cmdname{mydecorationsFading}
+ \begin{myindent}
+ \dargone{path-fading}{north}\argvsep
+ \marg{primary-color}\argvsep
+ \dargone{color-gradient}{$80$}\argvsep
+ \dargone{secondary-color}{black}\argvsep
+ \dargtwo{opacity}{$1.0$}%
+ \end{myindent}\cmddsep
+ the resulting fill color is given by \argname{primary-color}, \argname{color-gradient}
+ and \argname{secondary-color}, which are composed as follows:
+ \argname{primary-color}!\argname{color-gradient}!\argname{secondary-color}.
+\item \cmdname{mydecorationsSetPos[XTL|YTL|XBR|YBR]}
+ \begin{myindent}
+ \dargone{coordinate-value}{$1\text{cm}\mid-1\text{cm}\mid-1\text{cm}\mid1\text{cm}$}
+ \end{myindent}\cmddsep
+ sets the position for the decoration in use. Since the decoration path is \textit{rectangle}, it
+ is sufficient to have the $(x,y)$ coordinates of two points: the top-left and bottom-right.
+ \textit{XTL} stands for ``\texttt{X-Top-Left}'', \textit{XBR} for ``\texttt{X-Bottom-Right}''
+ and so on.
+\item
+ \cmdname{mydecorationsSetLineWidth}[*]
+ \dargone{line-width}{tikz value}\cmdvsep
+ \cmdname{mydecorationsSetSegmentAmplitude}[*]
+ \dargone{segment-amplitude}{tikz value}\cmdvsep
+ \cmdname{mydecorationsSetSegmentLength}[*]
+ \dargone{segment-length}{tikz value}\cmddsep
+ these commands may respectively be used for modifying the properties \argname{line-width},
+ \argname{segment-amplitude} and \argname{segment-length} for the decoration in use.
+ \textit{Starred} versions do not require any argument and reinitialize the properties to their
+ default values.
+\squishend
+
+\subsection{Miscellaneous}
+
+\squishlist
+\item
+ \cmdname{mypdfauthor}
+ \marg{author}\cmdvsep
+ \cmdname{mypdftitle}
+ \marg{title}\cmdvsep
+ \cmdname{mypdfsubject}
+ \marg{subject}\cmddsep
+ these commands do nothing but register \argname{author}, \argname{title} and \argname{subject}
+ information in the document properties of the pdf is being produced.
+
+\item \cmdname{mylang}
+ \marg{text}\arghsep
+ \dargone{language}{english}\cmddsep
+ temporarily changes the language in use (\textit{babel} package) to \argname{language} for
+ \argname{text}.
+
+\item \cmdname{myitemize}
+ \cmddsep
+ a list environment that uses the \textit{ding} style.
+
+\item \cmdname{mychangemargin}
+ \marg{left-margin}\arghsep
+ \marg{right-margin}\cmddsep
+ \textit{mychangemargin} environment changes the left and right margin of a portion of
+ text. The environments \textit{mychangemarginLeft} and \textit{mychangemarginRight}, whose
+ meaning is straight forward, are also available.
+
+\item \cmdname{myrenderlayout}
+ \dargone{component}{a}\cmddsep
+ processes and draws the layout component(s). The option value ``h'' is for the header component,
+ ``b'' and ``f'', respectively, for the body and footer ones, while ``a'' is for all components.
+\squishend
+
+\section{An example}
+
+This section gives a \textit{minimal} example and some considerations about the use of \classname
+(the class permits to do much better with a little patience). This is done by creating two
+\textit{curriculum vit\ae{}} with the same contents, but different layouts: one \CV will use a
+double page layout (abbreviated \DPL from here forward), while the other will use a single page
+layout (\SPL).
+
+The sample code presented here can be found in the ``Examples'' directory shipped with the
+\textit{mycv} bundle, which this document is part of, and that also contains files with the \CV
+contents: these files are not listed in the present document, as they do not contain anything worth
+being mentioned for the purpose of these notes.
+
+First and foremost, to keep things ordered, we need a file containing the layout components
+for the \DPL (\textit{model-dpl.tex}) and another one for the
+\SPL (\textit{model-spl.tex}).
+%For our intents,
+We opt for having the header and footer components being shared, so we create a third file named
+\textit{model-common.tex} such as this:
+\lstinputlisting[firstnumber=1,caption=model-common.tex,label=lst:model-common]{
+../Examples/Models/model-common.tex}\codeskip
+
+Notice that in listing~\ref{lst:model-common}, for the \DPL, we used some decoration commands.
+Obviously, it is also possible to not use decorations (simply by not using the relative class
+option), but in that case the showed code would yield some compilation errors, since decoration
+commands would be called without being defined.\\
+A possible solution makes the use of the conditional command \textit{\textbackslash{}ifoption}, so
+that the first part of the code would become something like in listing~\ref{lst:model-common-hint}.
+\begin{lstlisting}[firstnumber=1,label=lst:model-common-hint,caption=model-common-hint]
+\ifmodel{verDPL}{%
+ \ifoption{withDec}{%
+ [...]
+ }{\newcommand{\cvdec}{}}
+}{\newcommand{\cvdec}{}}
+\end{lstlisting}\codeskip
+
+Now we can deal with the layout components specific for the \DPL (\textit{model-dpl.tex})
+as in listing~\ref{lst:dplmodel}.
+\lstinputlisting[firstnumber=1,caption=model-dpl.tex,label=lst:dplmodel]{
+../Examples/Models/model-dpl.tex }
+\codeskip
+
+%The directive colored in red moves the right margin to the left (text and title rules) while the
+%directives in orange are just used as a trick to do the same thing for the left margin (that is
+%moved to the right):\codeskip
+%\begin{lstlisting}[firstnumber=1,numbers=none]
+%&MainBodyPageBegin&:<0.96>
+%|SubBodyPageBegin|,
+%|SubBodyPageEnd|,
+%\end{lstlisting}
+
+As far as the \DPL, we have done; we still have to deal with the layout components specific for
+the \SPL (\textit{model-dpl.tex}). In this case, we do not need to use \verb|*PageBegin| components,
+but it is sufficient to directly include the files with the contents. The resulting code is showed
+in listing~\ref{lst:splmodel}.
+\lstinputlisting[firstnumber=1,caption=model-spl.tex,label=lst:splmodel]{
+../Examples/Models/model-spl.tex }
+\codeskip
+
+At this point, we both have the components for the double and single page layouts and we can
+proceed writing the main files (\textit{mycv-example-dpl.tex} and \textit{mycv-example-spl.tex})
+that pick and use them.\\
+We start by setting up some options for the \classname class; we have chosen to store the \CV
+contents files in the directory ``Contents'' (that is the default one where the class searches
+for the contents files), so there is not need to specify the directory path with the option
+``\textit{cntdir}''~\myref{sec:class-options}.
+\\
+The options we want to pass to the class are those related to the decorations support and language;
+in addiction, we pass the name of the layout (model) we mean to use.
+% (see the listings~~\ref{lst:dplmodel} or ~\ref{lst:splmodel}).
+\\
+Here we take the \DPL as an example (listing~\ref{lst:mycv-example-dpl}), but switching to the
+\SPL would just be a matter of changing the ``\textit{mdlname}'' option from \keyword{verDPL} to
+\keyword{verSPL}.
+\begin{lstlisting}[firstnumber=1,label=lst:mycv-example-dpl,caption=mycv-example-dpl.tex]
+\documentclass[10pt,mdlname=verDPL,withDec,language=english]{mycv}
+\input{mycv-example-common}
+\end{lstlisting}\codeskip
+
+What remains to do is just to include the appropriate layout components file (\ref{lst:dplmodel} or
+\ref{lst:splmodel}) and process them with the \textit{\textbackslash{}myrenderlayout} command, as
+showed in listing~\ref{lst:example-common}; since this portion of code is shared between
+\textit{mycv-example-dpl.tex} and \textit{mycv-example-spl.tex}, we need to use
+\textit{\textbackslash{}ifmodel} for selecting the right file to be included.
+\begin{lstlisting}[firstnumber=1,caption=mcv-example-common.tex,label=lst:example-common]
+[...]
+\ifmodel{verSPL}{\input{Models/model-spl}}{\relax}
+\ifmodel{verDPL}{\input{Models/model-dpl}}{\relax}
+
+\begin{document}
+\myrenderlayout % all components
+[...]
+\end{document}
+\end{lstlisting}
+%\lstinputlisting[firstnumber=1,caption=mcv-example-common.tex,label=lst:example]{
+%../Examples/mycv-example-common.tex}
+
+\section{Split the contents}
+
+When a double layout page is used, it may occur, for example, that a section is too long for a
+page: this would not be a problem with a single layout page, since \LaTeX{} would automatically
+break the section contents. Unfortunately, with a double page layout the behavior is substantially
+different: this is because \classname uses a \textit{minipage-based mechanism} and a minipage is by
+itself not breakable. Thus, what happens is that part of the section contents comes out from the
+margins, without being displayed.
+
+When a problem such as this occurs, a possible workaround is to manually break the section contents.
+This can be done by using a counter that keeps track of the number of times a same file is included:
+when the counter is equal $1$, a part of the section contents is included in the left page,
+otherwise is the remaining one to be included in the right page.
+Listing~\ref{lst:split-contents-example} shows a practical example of what just discussed.
+
+\begin{lstlisting}[firstnumber=1,label=lst:split-contents-example,caption=split-contents-example]
+% ---------------------------------------------------------
+% file with the section contents: i.e. <section_skills.tex>
+% ---------------------------------------------------------
+% increase the counter 'acounter', that is defined outside this file
+\stepcounter{acounter}
+\newcommand{\conditionalblock}[2]{\ifthenelse{\value{acounter}<2}{#1}{#2}}
+\textconditionalblock%
+ {skills section contents part A}%
+ {skills section contents part B (the remaining part)}
+% --------------------------------------------------
+% file with the DPL components: i.e. <model-dpl.tex>
+% --------------------------------------------------
+\def\bodylayoutlist{%
+ |SubBodyPageBegin|:<0.48>, % left page
+ % include part A in the left page
+ section_skills@,
+ [...]
+ |SubBodyPageEnd|,
+ |SubBodyPageBegin|:<0.48>, % right page
+ % include part B in the right page
+ section_skills@,
+ [...]
+ |SubBodyPageEnd|
+}
+\end{lstlisting}\codeskip
+
+Of course the proposed workaround is not the best we could wish for, since it requires manual
+operations. Unfortunately, at the moment, I would not know how to solve the problem with a brighter
+idea. Any advice or comment is greatly appreciated, either for the specific problem or for this
+work in general.
+
+\bigskip\bigskip
+That's all, {\color{brown}happy \LaTeX{}ing!}\\[5pt]
+\Large\calligra{AndreaGhersi} \ No newline at end of file