moderntimeline.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011-2012 by Raphaël Pinson <raphink@gmail.com>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Raphaël Pinson.
%
% This work consists of the files moderntimeline.dtx and moderntimeline.ins
% and the derived filebase moderntimeline.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{moderntimeline.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{moderntimeline}
%<*package>
    [2012/04/27 0.7 Add timelines to moderncv entries]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{moderntimeline}[2012/04/26]
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{moderntimeline.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{222}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{0.7}{2012/04/26}{Various fixes by Jake to allow fractional years in tllabelcventry}
% \changes{0.6}{2012/01/17}{Fix compatibility with moderncv 0.15.1}
% \changes{0.5}{2011/11/15}{Fix positions in tlcventry and tldatecventry, add tltextsingle, thanks to Stéphane Dupille}
% \changes{0.4}{2011/10/02}{Add firstyear and lastyear options}
% \changes{0.3}{2011/09/29}{Bugfix: initialize tlsince}
% \changes{0.2}{2011/09/29}{Add tlsince and options for tltext*}
% \changes{0.1}{2011/09/28}{Initial release}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{moderntimeline.dtx}
% \title{The \textsf{moderntimeline} package}
% \author{Raphaël Pinson \\ \url{raphink@gmail.com}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \section{Introduction}
%
% As I was reworking my CV (which uses \textsf{moderncv}),
% the thought came to me that instead of just putting
% dates in front of each entries, it would be nice to have
% timelines to make them more graphical and get a better
% grasp of the time span of each entry.
%
% After playing a bit, I asked a question on
% stackexchange.com\footnote{\url{http://tex.stackexchange.com/questions/29725/putting-a-timeline-for-dates-in-moderncv}}
% and adapted the answer provided by Jake\footnote{\url{http://tex.stackexchange.com/users/2552/jake}}
% and turned it into this package.
%
% \section{Usage}
%
% This package is to be used together with the \textsf{moderncv} class,
% and can be loaded with:
%
% \begin{verbatim}
%    \usepackage[firstyear=1999,lastyear=2012]{moderntimeline}
% \end{verbatim}
%
% The \texttt{firstyear} and \texttt{lastyear} options indicate the maximum dates used
% to calibrate the time line. They are not mandatory and can be set later
% by means of the |\ltmaxdates| macro.
%
% \subsection{Settings}
%
% Before you typeset entries, you need to adjust
% the settings for this package.
%
% \DescribeMacro{\tlwidth}
% You can optionally set the width of the time line
% by calling |\tlwidth| with a dimension.
%
% \DescribeMacro{\tlrunningwidth}
% For each entry, a running line is traced behind the
% time line. You can set the width of this line by
% means of the |\tlrunningwidth| macro.
%
% \DescribeMacro{\tlrunningcolor}
% To set the color of the running line placed behind
% the time line, you can use the |\tlrunningcolor| macro.
%
% \DescribeMacro{\tltextstart}
% If you wish to set the size of the start date label,
% you can do so by using |\tltextstart|, passing it
% a text size macro.
%
% It also takes an optional first argument to set the
% position of the label, for example if you wish
% to center the label on the start of the line
% and set the text size to |\scriptsize|:
%
% \begin{verbatim}
%    \tltextstart[base]{\scriptsize}
% \end{verbatim}
%
%
% \DescribeMacro{\tltextend}
% If you wish to set the size of the end date label,
% you can do so by using |\tltextend|, passing it
% a text size macro.
%
% It also takes an optional first argument to set the
% position of the label, for example if you wish
% to center the label on the start of the line
% and set the text size to |\scriptsize|:
%
% \begin{verbatim}
%    \tltextend[base]{\scriptsize}
% \end{verbatim}
%
%
% \DescribeMacro{\tltextsingle}
% If you wish to set the size of single date labels,
% you can do so by using |\tltextsingle|, passing it
% a text size macro.
%
% For example if you wish to set the text size to
% |\scriptsize|:
%
% \begin{verbatim}
%    \tltextsingle{\scriptsize}
% \end{verbatim}
%
%
% \DescribeMacro{\tltext}
% You can set the sizes of both the start and end dates
% by calling the |\tltext| macro with a text size macro.
%
%
% \DescribeMacro{\tlmaxdates}
% Before you can typeset any entry, you need to specify
% the maximal range of dates which will serve as a reference.
% This range will be mapped to the width of the left column,
% and dates will be positionned accordingly.
% To set the range, use the |\tlmaxdates| macro, passing it
% the first and last dates you will be using:
%
% \begin{verbatim}
%    \tlmaxdates{1999}{2012}
% \end{verbatim}
%
% If you are going to use the last date of the range
% as a start date or a unique date for an entry,
% you should probably set the max date a bit higher
% to prevent the date label from overflowing into
% the entry text.
%
% Since version 0.4, you can set these dates by passing the
% \texttt{firstyear} and \texttt{lastyear} options to the package.
%
%
% \DescribeMacro{\tlsince}
% When using a date range without an end year,
% you might want to add "Since" in front of the starting year.
% In order to do this, you can use the |\tlsince| macro:
%
% \begin{verbatim}
%    \tlsince{Since~}
% \end{verbatim}
%
%
% \subsection{CV entries}
%
% This package provides new CV entry commands
% for the \textsf{moderncv} class.
% They are described in this section.
%
%
% \DescribeMacro{\tlcventry}
% The |\tlcventry| macro lets you typeset
% a date range.
% In addition to the standard CV entry, one option
% and two mandatory arguments are added:
%
% \begin{verbatim}
%    \tlcventry{1999}{2002}{WYSIWYG User}{Unnamed Company}
%        {Somewhere}{}{Tried hard to typeset documents}
%    \tlcventry[blue]{2002}{0}{Happy TeXnician}{Any Company}
%        {Anywhere}{}{Achieved nice typography and shared code with friends}
% \end{verbatim}
%
% The option sets the color of the time line.
% If unset, the color defaults to the theme color of the CV.
%
% The two arguments added in the beginning of the call
% are the start and end dates for the entry.
% If the position is still held, use \texttt{0} as the end date.
% This will add a gradient at the end of the time line.
%
%
% \DescribeMacro{\tllabelcventry}
% The |\tllabelcventry| macro is similar to |\tlcventry|,
% but it takes yet a third additional argument, which lets you
% set a label for the time line.
% When this is used, the dates are not typeset around the time line,
% only the label is placed where the start date would normally be.
%
% This is useful when your dates contain month names, or if the
% time span is too short to properly typeset the dates above
% and under the time line:
%
% \begin{verbatim}
%    \tllabelcventry[magenta]{2002}{2003}{July--November 2002}
%        {Scribus Student}{GNU School}
%        {The Internet}{}{Tried Scribus for a short while}
% \end{verbatim}
%
% \DescribeMacro{\tldatecventry}
% Positions usually last long enough to draw time lines,
% but there are also punctual entries, such as diplomas.
% The |\tldatecventry| lets to typeset unique dates.
% It places a bullet on the date and typesets the date above it:
%
% \begin{verbatim}
%    \tldatecventry[brown]{2011}{Trusted TeX.SX user}{}{tex.stackexchange.com}
%        {The Internet}{}{Achived 20k reputation on TeX.SX}
% \end{verbatim}
%
%
% \DescribeMacro{\tldatelabelcventry}
% Similarly to |\tllabelcventry|, you might want to place
% a label on a unique date entry, such as an exact date
% or a month. The |\tldatelabelcventry| provides a parameter to achive this:
%
% \begin{verbatim}
%    \tldatelabelcventry[brown]{2011}{Christmas 2011}{Happy TeXer}{}{Home}
%        {Townville}{}{Received Don Knuth's \emph{3:16} as a gift.}
% \end{verbatim}
%
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
%    \begin{macrocode}
\ProvidesPackage{moderntimeline}
\RequirePackage{tikz}
\RequirePackage{kvoptions}
\SetupKeyvalOptions{
   family=moderntimeline,
   prefix=tl@,
}
\DeclareStringOption{firstyear}
\DeclareStringOption{lastyear}
\ProcessKeyvalOptions*
%    \end{macrocode}
%
% \begin{macro}{\tlwidth}
%    \begin{macrocode}
\newcommand{\tlwidth}[1]{%
   \def\tl@width{#1}
   \pgfmathsetmacro\tl@textstartabove{\tl@width+1pt}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tlrunningwidth}
%    \begin{macrocode}
\newcommand{\tlrunningwidth}[1]{%
   \def\tl@runningwidth{#1}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tlrunningcolor}
%    \begin{macrocode}
\newcommand{\tlrunningcolor}[1]{%
   \def\tl@runningcolor{#1}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tlsince}
%    \begin{macrocode}
\newcommand{\tlsince}[1]{%
   \def\tl@since{#1}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tltextstart}
%    \begin{macrocode}
\newcommand{\tltextstart}[2][base west]{%
   \tikzset{
       tl@startyear/.style={
           font=#2,
           name=tl@startyear,
           above=\tl@textstartabove,
           inner xsep=0pt,
           anchor=#1,
       }
   }
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tltextend}
%    \begin{macrocode}
\newcommand{\tltextend}[2][north east]{%
   \tikzset{
       tl@endyear/.style={
           font=#2,
           name=tl@endyear,
           below,
           inner xsep=0pt,
           anchor=#1,
       }
   }
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tltextsingle}
%    \begin{macrocode}
\newcommand{\tltextsingle}[1]{%
   \tikzset{
       tl@singleyear/.style={
           font=#1,
           name=tl@singleyear,
           above=1pt,
           inner xsep=0pt,
       }
   }
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tltext}
%    \begin{macrocode}
\newcommand{\tltext}[1]{%
%    \end{macrocode}
%    \begin{macrocode}
   \tltextstart{#1}%
   \tltextend{#1}%
   \tltextsingle{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% Defaults
%    \begin{macrocode}
\tltext{\scriptsize}
\tlwidth{0.8ex}
\tlrunningwidth{0.05ex}
\tlrunningcolor{gray}
\tlsince{}
%    \end{macrocode}
%
%
% \begin{macro}{\tlmaxdates}
%    \begin{macrocode}
\newcommand{\tlmaxdates}[2]{%
   \def\tl@firstyear{#1}
   \def\tl@lastyear{#2}
   \pgfmathsetmacro\tl@yearrange{\tl@lastyear-\tl@firstyear}
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tldatelabelcventry}
%    \begin{macrocode}
\newcommand{\tldatelabelcventry}[8][color1]{%
%    \end{macrocode}
%    \begin{macrocode}
\pgfmathsetmacro\tl@endyear{\tl@lastyear}
\pgfmathsetmacro\tl@startfraction{(#2-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\pgfmathsetmacro\tl@endfraction{(\tl@endyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
%    \end{macrocode}
%    \begin{macrocode}
 \cventry{\tikz{
     \fill [\tl@runningcolor] (0,0)
        rectangle (\hintscolumnwidth,\tl@runningwidth);
     \fill [#1] (0,0)
        ++(\tl@startfraction*\hintscolumnwidth,0pt)
        node [tl@startyear] {#3}
        node {$\bullet$};
   }
}
{#4}{#5}{#6}{#7}{#8}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tldatecventry}
%    \begin{macrocode}
\newcommand{\tldatecventry}[7][color1]{%
%    \end{macrocode}
%    \begin{macrocode}
\pgfmathsetmacro\tl@endyear{\tl@lastyear}%
\pgfmathsetmacro\tl@startfraction{(#2-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\pgfmathsetmacro\tl@endfraction{(\tl@endyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\cventry{\tikz[baseline=0pt]{
    \useasboundingbox (0,-1.5ex) rectangle (\hintscolumnwidth,1ex);
    \fill [\tl@runningcolor] (0,0)
       rectangle (\hintscolumnwidth,\tl@runningwidth);
    \fill [#1] (0,0)
       ++(\tl@startfraction*\hintscolumnwidth,0pt)
       node [tl@singleyear] {#2}
       node {$\bullet$};
  }%
}%
{#3}{#4}{#5}{#6}{#7}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tlcventry}
%    \begin{macrocode}
\newcommand{\tlcventry}[8][color1]{%
%    \end{macrocode}
%    \begin{macrocode}
\pgfmathsetmacro\tl@endyear{ifthenelse(#3==0,\tl@lastyear,#3)}%
\pgfmathsetmacro\tl@startfraction{(#2-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\pgfmathsetmacro\tl@endfraction{(\tl@endyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\pgfmathsetlength{\pgf@xa}{#3} \ifdim\pgf@xa=0pt \def\tl@startlabel{\tl@since #2} \else \def\tl@startlabel{#2} \fi
 \cventry{\tikz[baseline=0pt]{
    \useasboundingbox (0,-1.5ex) rectangle (\hintscolumnwidth,1ex);
    \fill [\tl@runningcolor] (0,0)
       rectangle (\hintscolumnwidth,\tl@runningwidth);
    \fill [#1] (0,0)
       ++(\tl@startfraction*\hintscolumnwidth,0pt)
       node [tl@startyear] {\tl@startlabel}
       rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width-1pt)
       node [tl@endyear] {\pgfmathparse{ifthenelse(#3==0,,#3)}\pgfmathresult}
       (\hintscolumnwidth,0pt) ;
    \pgfmathsetlength{\pgf@xa}{#3} \ifdim\pgf@xa=0pt
       \shade [left color=#1] (\tl@startfraction*\hintscolumnwidth,0)
           rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width);
    \else
       \fill [#1] (\tl@startfraction*\hintscolumnwidth,0)
           rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width);
    \fi
    }%
}%
{#4}{#5}{#6}{#7}{#8}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tllabelcventry}
%    \begin{macrocode}
\newcommand{\tllabelcventry}[9][color1]{%
%    \end{macrocode}
%    \begin{macrocode}
\pgfmathsetmacro\tl@endyear{ifthenelse(#3==0,\tl@lastyear,#3)}
\pgfmathsetmacro\tl@startfraction{(#2-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
\pgfmathsetmacro\tl@endfraction{(\tl@endyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
 \cventry{\tikz[baseline=0pt]{
     \fill [\tl@runningcolor] (0,0)
        rectangle (\hintscolumnwidth,\tl@runningwidth);
     \useasboundingbox (0,-1.5ex)
        rectangle (\hintscolumnwidth,1ex);
     \fill [#1] (0,0) 
        ++(\tl@startfraction*\hintscolumnwidth,0pt)
        node [tl@startyear] {#4}
        rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width-1pt);
     \pgfmathsetlength{\pgf@xa}{#3} \ifdim\pgf@xa=0pt
        \shade [left color=#1] (\tl@startfraction*\hintscolumnwidth,0) 
            rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width);
     \else
        \fill [#1] (\tl@startfraction*\hintscolumnwidth,0) 
            rectangle (\tl@endfraction*\hintscolumnwidth,\tl@width);
     \fi
     }
}
{#5}{#6}{#7}{#8}{#9}%
}
%    \end{macrocode}
% \end{macro}
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput