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 | 377 |
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 |