diff options
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.tex | 525 |
1 files changed, 0 insertions, 525 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 deleted file mode 100644 index 027ae60948b..00000000000 --- a/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Usage.tex +++ /dev/null @@ -1,525 +0,0 @@ -% ***************************************************************************** -\chapter{Usage} -\quotes{% - “There are two ways to write error-free programs; only the third one works”% -}{Alan J. Perlis} -% ***************************************************************************** -\ifparchment\begin{parchment}\fi -\section{Requirements} -When \textit{decorations} are not enabled and the \textit{default style} is not used, \classname -has %, in addiction to \ctLaTeXe{} obviously, -the following requirements:\codeskip -\begin{latexcode}[numbers=none] -\RequirePackage{kvoptions} % for class options with key-value format -\RequirePackage{etextools} % for lists and other useful tools -\RequirePackage{ifthen} % for the \ifthenelse command -\RequirePackage{xstring} % for string utilities -\RequirePackage{svn-prov} % for file info extracted from SVN -\RequirePackage{hyperref} % for hypertext links and other stuff -\end{latexcode} - -If the default style is used, by means of the class option -``\textit{style}''~\myref{sec:class-options}, this class requires (in addiction to -\textit{hyperref} and \textit{svn-prov}):\codeskip -\begin{latexcode}[numbers=none] -\RequirePackage{xparse} % for commands with multiple default arguments -\RequirePackage{pifont} % for the 'ding' style (itemize environment) -\RequirePackage{titlesec} % for title format and spacing -\RequirePackage{fancyhdr} % for custom headers and footers -\RequirePackage{xcolor} % for colors -\RequirePackage{calligra} % for the calligra font -\RequirePackage{times} % for the times font -\RequirePackage{marvosym} % symbols - phone -\RequirePackage{amssymb} % symbols - email -\end{latexcode} - -Finally, if decorations are enabled, by using the class -option ``\textit{withDec}``~\myref{sec:class-options}, this class also requires (in addiction -to \textit{svn-prov}, \textit{xparse} and \textit{xstring}):\codeskip -\begin{latexcode}[firstnumber=1,numbers=none] -\RequirePackage{tikz} % for graphics -\end{latexcode} - -\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 the extension ``.sty'') containing the style commands. - By default, the file \textit{mycv\_style.sty}, provided by the class itself, is that used. - It is also possible to not use any 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}''.\\ -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{Conditionals} - -\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 the one 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 update of the document. -\item \cmdname{myitemize} - \cmddsep - a list environment that uses the \textit{ding} style. -\squishend - -\subsection{Decorations} -\label{sub:decoration-commands} - -\classname provides some commands for \textit{TikZ} decorations. The support -provided is not complete at all (on the other hand \textit{TikZ} has a huge amount of -functionality), but it is enough for this class purposes. The only \textit{TikZ} path supported is -\textit{rectangle}. - -\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$, shows the decoration \argname{decoration-type}, - while if $0$ does not. - The \textit{starred} version of the command uses the shading technique and the last argument is - the background shading color.\\ - The \textit{not starred} version does not consider the argument \argname{shading-type} - (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$, shows the decoration \argname{decoration-type}, - while if $0$ does not.\\ - \argname{decoration-type} was tested with the following decorations: ``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{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{Some examples} - -This section gives some \textit{minimal} examples and does 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 the code organized, we need a file containing the layout components -for the \DPL and \SPL (\textit{model-layouts.tex}). We opt to share the \textit{header} and -\textit{footer} components, so we also create a second file named \textit{model-common.tex}, -such as in listing~\ref{lst:model-common}. -\begin{latexcode}[firstnumber=1,caption=model-common.tex,label=lst:model-common] -% ---------------------- -% the shared header list -% ---------------------- -\def\headerlayoutlist{% - &MainHeaderPageBegin&:<postcmd:vspace=10pt>, - % --------------------------------- left header - |SubHeaderPageBegin|:<precmd:hfill>, - % header file (1) - $header_title@$, - |SubHeaderPageEnd|:<postcmd:hfill>, - % --------------------------------- right header - |SubHeaderPageBegin|, - % header file (2) - $header_contacts@$, - |SubHeaderPageEnd|, - &MainHeaderPageEnd&% -} - -% ---------------------- -% the shared footer list -% ---------------------- -\def\footerlayoutlist{footer_sign@} -\end{latexcode} - -\subsection{Double page layout} - -Here we deal with the layout components specific for the \DPL, as showed in -listing~\ref{lst:dplmodel}. -%\lstinputlisting[firstnumber=1,caption=model-dpl.tex,label=lst:dplmodel]{ -%../Examples/Models/model-dpl.tex} -\begin{latexcode}[firstnumber=1,caption=DPL model (part of 'model-layouts.tex'),label=lst:dplmodel] -\def\bodylayoutlist{% the DPL's body list - % --------------------------------------------------------- - % moves the right margin to the left (text and title rules) - % --------------------------------------------------------- - &MainBodyPageBegin&:<0.96>, - % --------------------------------------------------------- - % the 2 directives below are just used as a trick to do the - % same thing for the left margin (it is moved to the right) - % --------------------------------------------------------- - |SubBodyPageBegin|, - |SubBodyPageEnd|, - % ----------------------------------------- - % left page (0.48 of textwidth) - % ----------------------------------------- - |SubBodyPageBegin|:<0.48>, - $contents_partA@$:<precmd:vspace=10pt:sectionnumber=1>, - $contents_partB@$:<precmd:vspace=10pt:sectionnumber=2>, - $contents_partC@$:<precmd:vspace=10pt:sectionnumber=3>, - |SubBodyPageEnd|:<postcmd:hfill>, - % ----------------------------------------- - % right page (0.48 of textwidth) - % ----------------------------------------- - |SubBodyPageBegin|:<0.48>, - $contents_partA@$:<precmd:vspace=10pt:sectionnumber=4>, - $contents_partB@$:<precmd:vspace=10pt:sectionnumber=5>, - |SubBodyPageEnd|, - % ----------------------------------------- - &MainBodyPageEnd&% -} -\end{latexcode} - -\subsection{Single page layout} - -As far as the \SPL, we do not need to use the \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}. -\begin{latexcode}[firstnumber=1,caption=SPL model (part of -'model-layouts.tex'),label=lst:splmodel] -\def\bodylayoutlist{% the SPL's body list - % --------------------------------------------------- - $contents_partA@$:<precmd:vspace=10pt:sectionnumber=1>, - $contents_partB@$:<precmd:vspace=10pt:sectionnumber=2>, - $contents_partC@$:<precmd:vspace=10pt:sectionnumber=3>, - $contents_partA@$:<precmd:vspace=10pt:sectionnumber=4>, - $contents_partB@$:<precmd:vspace=10pt:sectionnumber=5> - % --------------------------------------------------- -} -\end{latexcode} - -\subsection{Main file} - -Since we both have the components for the double and single page layouts, we can proceed writing the -main file (\textit{mycv-example-main.tex}) that picks and use them.\\ -We start by setting up some options for the %\classname -class, such as those related to the decorations and language support, as well as the name of the -model (layout) we mean to register. -Besides, we opt 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 its path with -the option ``\textit{cntdir}''. %~\myref{sec:class-options}. -% (see the listings~~\ref{lst:dplmodel} or~\ref{lst:splmodel}). - -In listing~\ref{lst:mycv-example-main} we take the \DPL as an example, but switching to the -\SPL would just be a matter of changing the ``\textit{mdlname}'' option from \keyword{verDPL} to -\keyword{verSPL}. -\begin{latexcode}[firstnumber=1,label=lst:mycv-example-main,caption=mycv-example-main.tex] -\documentclass[10pt,mdlname=verDPL,withDec,language=english]{mycv} -\input{mycv-example-common} -\begin{document} -\cvdec\myrenderlayout\mycfoot{Last update: \today} -\end{document} -\end{latexcode} - -The file \textit{mycv-example-common[.tex]}, showed in listing~\ref{lst:example-common}, -selects the appropriate layout components (listings~\ref{lst:dplmodel} or \ref{lst:splmodel}) to be -included and, subsequently, processed by \textit{\textbackslash{}myrenderlayout}. -%(to be more exact, those components are selected inside the file \textit{model-layouts[.tex]}).\\ -%by using -%the conditional command \textit{\textbackslash{}ifmodel}.\\ -In addiction, the file \textit{mycv-example-common.tex} contains some decoration commands, which -need to be used only if the option ``\textit{withDec}' was given to the class; this is the -reason of the conditional command \textit{\textbackslash{}ifoption}. -\begin{latexcode}[firstnumber=1,caption=mcv-example-common.tex,label=lst:example-common] -[...] -\ifoption{withDec}{% - \newcommand{\cvdec}{ - \mydecorationsSetLineWidth[0.3mm]% - \mydecorationsPathmorphing*{coil}<radial><lightgray> - } - [...] -}{\newcommand{\cvdec}{}} - -% include layouts components -\input{Models/model-layouts} -[...] -\end{latexcode} -%\lstinputlisting[firstnumber=1,caption=mcv-example-common.tex,label=lst:example]{ -%../Examples/mycv-example-common.tex} - -\subsection{Layout notes} - -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 page layout, since \LaTeX{} would automatically -break the section contents. Unfortunately, with a double page layout the behavior is substantially -different: this is because the class 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 -page 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{latexcode}[firstnumber=1,label=lst:split-contents-example, -caption=workaround example] -% --------------------------------------------------------- -% file with the section contents: i.e. <section_skills.tex> -% --------------------------------------------------------- -% increases the counter 'cnt': it's defined outside this file -\stepcounter{cnt} - -% selects the appropriate part of the file contents -\newcommand{\condblock}[2]{\ifthenelse{\value{cnt}<2}{#1}{#2}} - -\condblock{skills section contents part A}% - {skills section contents part B (the remaining part)} - -% ------------------------------------------------------ -% file with the DPL components: i.e. <model-layouts.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{latexcode} - -Of course the proposed workaround is not the best we could wish for, since it requires manual -operations. % (any advice about that is greatly appreciated).\\ -As an alternative, it is possible to not use the \verb|*PageBegin| and \verb|*PageEnd| mechanism, -delegating the double page layout to an external package (i.e. \textit{multicols}). -This kind of approach is showed in listings~\ref{lst:model-dpl2}. -\begin{latexcode}[firstnumber=1,caption=DPL$2$ model (part of -'model-layouts.tex'),label=lst:model-dpl2] -\newcommand{\mcbegin}{\begin{multicols}{2}} -\newcommand{\mcend}{\end{multicols}} - -\def\bodylayoutlist{% - $contents_partA@$:<precmd:vspace=10pt:mcbegin:sectionnumber=1>,% - [...] - $contents_partB@$:<precmd:vspace=10pt:sectionnumber=6>:<postcmd:mcend>,% -} -\end{latexcode} - -Notice the usage of the commands \textit{\textbackslash{mcbegin}} and -\textit{\textbackslash{mcend}}, which act as a wrapper for the \textit{multicols} environment. - -\section{Split file contents} - -This class uses a file based approach as far as the contents of a \CV, that is to say it needs that -the contents be into separated file/s (at least one) with respect to the main file. - -As the class works, having the contents in just one single file is not as good as would be with -multiple files (ideally a file for each section of the document), since multiple files allow to -more easily customize the \CV layout without directly acting on the contents. -On the other hand, a multiple file approach may compel to use several files and not be -convenient.\\ -For these reasons, this class provides a \keyword{PERL} script named -\textit{mycv\_split\_contents.pl} (for a list of all the options provided, type -\textit{mycv\_split\_contents.pl -h} inside a shell environment) -% or take a look at the file itself(function \textit{usage})), -that can process a file and, according to what specified by the -directives in the file itself, split its contents into several files (which will be those -effectively used by the class). In this way is possible to directly manage one single file for the -contents. - -If requested, the script can also create a basic model file with the layout components: -it has to be considered just as a skeleton and probably needs to be edited by hand afterward. - -The directives that may be used inside a contents file have the following form:\codeskip -\begin{latexcode}[numbers=none] -###::|filename|:$component$:&commands& -\end{latexcode} - -{\color{orange}\textit{filemane}} is the name of the file to create, -{\color{brown}\textit{component}} is the main component (\textit{header}, \textit{body} or -\textit{footer}) that the file represents, while {\color{red}\textit{commands}} are the relative -commands associated to the component. -Both \textit{component} and \textit{commands} are not mandatory, but may be useful, especially -\textit{component}, when is requested to generate a basic model file.\\ -The script \textit{mycv\_split\_contents.pl} may be called inside the main file as showed in -listing~\ref{lst:mycv-example-main2}. - -\begin{latexcode}[firstnumber=1,caption=mycv-example-main.tex,label=lst:mycv-example-main2] -% ------------------------------------------------------------------- -% To compile this file is necessary to use the option '-shell-escape' -% to enable the 'write18' construct. -% ------------------------------------------------------------------- -\documentclass[10pt,mdlname=verSPL,withDec,language=english]{mycv} -\immediate\write18{<dirpath>/mycv_split_contents.pl -i cv-contents.tex} -[...] -\end{latexcode} - -When the file \textit{cv-contents.tex} (listing~\ref{lst:cv-contents}) is processed by the script, -the files \textit{*.tex} are created in the directory ''Contents`` (the default one). -\begin{latexcode}[firstnumber=1,caption=cv-contents.tex,label=lst:cv-contents] -% ----------------------------- -% ###::header_title.tex::header -% ----------------------------- -[...] -% ------------------------------------------------------------------- -% ###::contents_partA.tex::body::<precmd:vspace=10pt:sectionnumber=1> -% ------------------------------------------------------------------- -[...] -% ------------------------------------------------------------------- -% ###::contents_partB.tex::body::<precmd:vspace=10pt:sectionnumber=2> -% ------------------------------------------------------------------- -[...] -% ---------------------------- -% ###::footer_sign.tex::footer -% ---------------------------- -[...] -\end{latexcode} - -%To make the example works, is necessary to compile the main file using the option -%\textit{-shell-escape} to enable the \textit{\textbackslash{write18}} construct. -%as follows:\codeskip -%\begin{latexcode}[numbers=none] -%||pdflatex|| -&shell-escape& mycv-example-spl.tex -%\end{latexcode} - -\bigskip -\fbox{That's all, {\color{brown}happy \LaTeX{}ing!}} -\hfill\Large\calligra{AndreaGhersi} -\ifparchment\end{parchment}\fi -%\todo[color=lightgray!10,noline]{That's all, {\color{brown}happy \LaTeX{}ing!}} |