summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/mycv/Doc/Chapters/Fundamentals.tex
blob: 8533ce5d527ddb4c86195770acf3543570e96d9f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
%*********************************************************
\chapter{Fundamentals}
\quotes[1973]{
   ``Computer programming is an art, because it applies
     accumulated knowledge to the world, because it
     requires skill and ingenuity, and especially because
     it produces objects of beauty''
}{Knuth}
%*********************************************************

\section{Introduction}

The main goal of this class (\classname) is to give support for creating \textit{curriculum
vit\ae{}} (\CV) with different layouts, allowing easy switching among them.
%That is primarily the goal this class focus on.
The class also provides a basic support for using the \textit{TikZ} decorations and defines a bunch
of commands for handling the contents of a \CV, even though this is not its primary goal.
%\classname, in fact, mainly focus on switching from different curriculum layouts,
%rather than handling the curriculum contents.
On \keyword{CTAN} archives, there are available various \CV packages more
\textit{contents-oriented}, as it were, and they may be used together with this class,
providing missing contents functionality.

Probably, the choice of the class's name was not so appropriate but, at the beginning, I did not
plan to publish it and chose the simplest and most obvious name. I realized that only when I
wrote these notes, but by then it was a bit too late.
%As far as the class is concerned, it uses a file-based and list-driven approach. Each file
%represents the contents of a user-chosen part of the curriculum (ideally a section, but this is not
%mandatory and may be anything else); besides, the \CV is logically divided into three main
%components: header, body and footer components. For each main component a list is associated: it
%contains sub-components, among which files with the \CV contents. In addiction, each sub-component
%may have associated some generic or specific commands to be executed.

Before starting to describe \classname more in details, I have to say it was my first class in
\LaTeX{} and, although I tried to do my best, the lack of experience probably brought me to make
some choice not so opportune as I hoped. It goes without saying that any advice or constructive
criticism is greatly appreciated.

\section{Class files}
The class \classname is composed by five files. A short brief of each one is given here:
\squishlist
   \item \ctext{mycv.cls}
      \begin{myindent}
      it is the main file and, basically, handles the class options~\myref{sec:class-options} as
      well as the inclusion of all other files (the remaining four);
      \end{myindent}
   \item \ctext{mycv\_base.def}
      \begin{myindent}
      it contains all the commands and definitions dealing with the layout components of a
      \CV~\myref{sec:layout-components}: it is the core-system file;
      \end{myindent}
   \item \ctext{mycv\_style.def}
      \begin{myindent}
      it contains the default style commands~\myref{sub:style-commands} provided by this class: if
      the default style is not used, %~\myref{sec:class-options}
      this file will not be included by \textit{mycv.cls};
      \end{myindent}
   \item \ctext{mycv\_dec.def}
      \begin{myindent}
      it contains the decoration commands~\myref{sub:decoration-commands}: if decorations are not
      enabled%
      %~\myref{sec:class-options}
      , this file will not be included by \textit{mycv.cls};
      \end{myindent}
   \item \ctext{mycv\_misc.def}
      \begin{myindent}
      it contains some miscellaneous commands and definitions.
      \end{myindent}
\squishend

\section {Layout components}
\label{sec:layout-components}

This class considers a \textit{curriculum vit\ae{}} as logically divided into three main
components: \textit{header}, \textit{body} and \textit{footer}.
For each of these ones, a list, that basically contains some sub-components, is being
associated; files with the \CV contents
%, or ideally a part of them (a section for example, but
%this is not mandatory and may be anything else),
are also considered sub-components\footnote{it may be a good practice, to make the best use of this
class, to subdivide the contents of each cv section in different files, although this is not
mandatory and any other choice may be made}. For these reasons, we can actually say that \classname
uses a
%file-based and
sort of \textit{list-driven} approach.%\\
%Besides, the \CV contents (ideally a section, but may be anything else) is divided in more files.

\subsection{Main components}

\classname recognizes the following three lists that, for all intends and purposes, are a concrete
representation of the main logical components:

\def\tmpcolor{black}
\squishlist[0pt]
   \item \textbf{\ctext[\tmpcolor]{headerlayoutlist}};
   \item \textbf{\ctext[\tmpcolor]{bodylayoutlist}};
   \item \textbf{\ctext[\tmpcolor]{footerlayoutlist}}.
\squishend\sep

It is mandatory, for the correct behavior of the class, to not change the above list names. In
the case a component is not required, the relative list may be omitted: for example, if a \CV does
not have a footer component, the list \textit{footerlayoutlist} is not strictly necessary.
What follows is an example of a list definition:
\codeskip
\begin{lstlisting}[firstnumber=1,numbers=none]
\def\headerlayoutlist{sub-component1,sub-component2,[...]}
\end{lstlisting}

\subsection{Sub-components}

We previously said that \classname is based on three main components (\textit{header},
\textit{body} and \textit{footer}) and that each of these ones are represented by a list. A list
(therefore a main component), in turn, may have one or more sub-component, separated by
a comma, which are identified as follows:

\squishlist[0pt]
   \item \texttt{\ctext{Main}[Header|Body|Footer]\ctext{PageBegin}};
   \item \texttt{\ctext{Main}[Header|Body|Footer]\ctext{PageEnd}};
   \item \texttt{\ctext[blue]{Sub}[Header|Body|Footer]\ctext[blue]{PageBegin}};
   \item \texttt{\ctext[blue]{Sub}[Header|Body|Footer]\ctext[blue]{PageEnd}};
   \item \texttt{\ctext[orange]{filename}} with the (partial) \CV contents.
\squishend\sep

Both ``\verb|Main[...]PageBegin|'' and ``\verb|Sub[...]PageBegin|'' are \textit{minipages}; the
difference is that the former have a default width of $100\%$ of the \textit{textwidth}
macro, while that value is $44\text{-}45\%$ for the latter (it depends on the components type).
% (for these notes does not really matter which is which).

A \textit{filename} sub-component may either directly be the name of a file or a macro (variable):
depending on the case, the syntax slightly changes.%~\myreftwo{subsub:component-options}.

\subsubsection{Sub-components options}
\label{subsub:component-options}

Each sub-component, \textit{filename} included, may have associated options, with colons
as separators, so that the syntax is something like:\sep
\begin{myindent}
\verb|sub-component:option1:option2:[...]|.
\end{myindent}\sep
If truth be told, each option has its own separator, so colons are not strictly necessary
and, as a separator, any other symbol may be used. If wanted, it is also possible to not have any,
but this is not recommended (just for a matter of clarity).
Options for a sub-component are of different types, as listed below:

\def\tmpcolor{gray}
\squishlist
   \item <\optname{[pre\textbar post]cmd}\verb|:command1:command2:[...]|>\optdsep
      a sequence of commands is executed \textit{before}/\textit{after} the
      begin or end of a sub-component (\textit{filename} included).
      A command may have a sequence of arguments, separated by ``='';
      each of them can either be \textit{optional} or \textit{mandatory}. %\\
      In total, \classname recognizes four types of arguments:
      %, as it is possible to have $3$ different kinds of optional ones:
      \squishlist
         \item \ctext[blue]{arg} (mandatory argument equivalent to \{arg\});
         \item \ctext[blue]{@arg} (optional argument equivalent to [arg]);
         \item \ctext[blue]{!arg} (optional argument equivalent to <arg>);
         \item \ctext[blue]{*} (optional argument equivalent to *).
      \squishend
   \item /\optname{m[l\textbar r]}\verb|<value>|/\hfill\opthsep{\small($1$)}\optvsep
      /\optname{endm[l\textbar r]}/\hfill\opthsep{\small($2$)}\optdsep
      changes the \textit{left}/\textit{right} margin of a text portion of a document, between
      option {\small($1$)} and option {\small($2$)}; in a typical usage, these options are
      associated with different sub-components, such as \verb|*PageBegin| and \verb|*PageEnd|.
      \\
      Each time the option {\small($1$)} is used, the option {\small($2$)} is also required
      for ending the margin modification, except for the \textit{filename}
      sub-component that automatically does that. Example (it moves the left margin to the
      right of $0.2$in):\sep
      \begin{myindent}
      \texttt{%
         \ctext[\tmpcolor]{%
            % \% moves the left margin to the right of $0.2$in\\
            SubBodyPageBegin:</ml0.2in/>\\
            \omissis\\
            SubBodyPageEnd:</endml>}%
      }.
      \end{myindent}
   \item \verb|<width-value>|\optdsep
      sets the width of a sub-component in terms of \textit{textwidth} percentage.
      This option only exists for ``\verb|*PageBegin|`` sub-components. Example:
      \ctext[\tmpcolor]{\texttt{SubBodyPageBegin:<0.48>}}.
   \item /\optname{pagesize}\verb|<value>|/\optdsep
      sets the width of a sub-component, as the option above, but in terms of absolute reference
      (instead of \textit{textwidth} percentage). Also this option only exists for
      ``\verb|*PageBegin|`` sub-components. Example:
      \ctext[\tmpcolor]{\texttt{SubBodyPageBegin:/pagesize5.5in/}}.
   \item /\optname{pagebreak}/\optdsep
      permits to break two contiguous sub-components, aligning them one above the other, instead
      side by side (that is the default behavior). This option only exists for ``\verb|*PageEnd|''
      sub-components. Example: \ctext[\tmpcolor]{\texttt{SubBodyPageEnd:/pagebreak/}}.
   \item \optname{*}varname\optvsep
      filename\optname{@}\optdsep
      \argname{varname} is a macro that expands to the name of a file (with the \CV contents),
      while \argname{filename} is directly the name itself.
      Example: \ctext[\tmpcolor]{\texttt{*headerfile}}, where the macro \textit{headerfile}
      is somewhere defined.
\squishend