moderntimeline.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011-2015 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>
    [2015/08/31 0.9 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{333}
%
% \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.9}{2015/08/31}{Add month support, thanks to Astrinus}
% \changes{0.8}{2015/02/25}{Add the tlsetnotshadedfraction command, thanks to Stefano Gronchi}
% \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}
%
% \DescribeMacro{\tlsetnotshadedfraction}
% If last year in |\tlcventry| and |\tllabelcventry| is 0, the bar
% is shaded. With this command you control the fraction of the bar
% that is not shaded (default = 0):
%
% \begin{verbatim}
%    \tlsetnotshadedfraction{0.4} % The first 40% of the bar is not shaded
% \end{verbatim}
%
%
% \DescribeMacro{\tlenablemonths}
% If you want to use months when drawing bars with |\tlcventry| and
% |\tllabelcventry|, issue this command. This feature is not enabled
% by default since it changes the way the bar are drawn if the month
% is not specified.
%
% \DescribeMacro{\tldisablemonths}
% This macro (default behaviour) does not in fact ignore months, but
% retain the historical behaviour of this package to draw the bars at
% the beginning of the year, so is not advisable to use months in dates.
% Default.
%
%
% \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.
%
% You can also specify months (which are used only for adjusting the bar length:
% they are not shown in the labels), separated by a slash from the year:
%
% \begin{verbatim}
%    \tlcventry{1999/2}{2002/6}{WYSIWYG User}{Unnamed Company}
%        {Somewhere}{}{Tried hard to typeset documents}
%    \tlcventry[blue]{2002/8}{0}{Happy TeXnician}{Any Company}
%        {Anywhere}{}{Achieved nice typography and shared code with friends}
% \end{verbatim}
%
% Don't use a leading zero, since this make PGF think the number is in octal,
% so it complains when sees \texttt{08} and \texttt{09}.
%
%
% \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}
%
% You can enter months for adjusting bar length as in |\tlcventry|.
%
%
% \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*
\newif\ifstartyear
\newif\ifissince
%    \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}
%
%
% \begin{macro}{\tlsetnotshadedfraction}
%    \begin{macrocode}
\newcommand{\tlsetnotshadedfraction}[1]{%
   \def\tl@nsfrac{#1}
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tlenablemonths}
%    \begin{macrocode}
\newcommand{\tlenablemonths}{%
   \def\tl@nomonthvalue{6}
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tldisablemonths}
%    \begin{macrocode}
\newcommand{\tldisablemonths}{%
   \def\tl@nomonthvalue{0}
}
%    \end{macrocode}
% \end{macro}
%
%
% Defaults
%    \begin{macrocode}
\tltext{\scriptsize}
\tlwidth{0.8ex}
\tlrunningwidth{0.05ex}
\tlrunningcolor{gray}
\tlsince{}
\tlsetnotshadedfraction{0}
\tldisablemonths
%    \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}{\tl@yearfraction}
%    \begin{macrocode}
\newcommand{\tl@yearfraction}[1]{% Month 1 - 12 -> 0 - 11
  \gdef\tl@tmpyear{-1}% Resetting
  \gdef\tl@tmpmonth{-1}%
  \begingroup%
  \edef\@tempa{#1/}%
  \expandafter\endgroup\expandafter\tl@yearfraction@auxi\@tempa\@nnil%
  \ifstartyear
    \pgfmathsetmacro\tl@startyear{\tl@tmpyear+(\tl@tmpmonth-1)/12}%
  \else
    \ifnum\tl@tmpyear=0
      \pgfmathsetmacro\tl@endyear{\tl@lastyear}%
      \issincetrue%
    \else
      \pgfmathsetmacro\tl@endyear{\tl@tmpyear+\tl@tmpmonth/12}%
      \issincefalse%
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl@yearfraction@auxi}
%    \begin{macrocode}
\newcommand{\tl@yearfraction@auxi}[2]{}
\def\tl@yearfraction@auxi#1/#2\@nnil{%
  \ifnum\tl@tmpyear<0 % First call
    \pgfmathsetmacro\tl@tmpyear{+#1}%
    \ifx\@nnil#2\@nnil
      \pgfmathsetmacro\tl@tmpmonth{+\tl@nomonthvalue}%
    \else
      \expandafter\tl@yearfraction@auxi#2\@nnil%
    \fi
  \else
    \pgfmathsetmacro\tl@tmpmonth{#1}%
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl@splitlabels}
%    \begin{macrocode}
\newcommand{\tl@splitlabels}[1]{
  \gdef\tl@startlabel{}% Resetting
  \begingroup%
  \edef\@tempa{#1///}%
  \expandafter\endgroup\expandafter\tl@splitlabels@auxi\@tempa\@nnil%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl@splitlabels@auxi}
%    \begin{macrocode}
\newcommand{\tl@splitlabels@auxi}[2]{}
\def\tl@splitlabels@auxi#1///#2\@nnil{%
  \ifx\tl@startlabel\empty\relax% First call
    \gdef\tl@startlabel{#1}
    \ifx\@nnil#2\@nnil
      \gdef\tl@startlabel{}
    \else
      \expandafter\tl@splitlabels@auxi#2\@nnil%
    \fi
  \else
    \gdef\tl@endlabel{#1}
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl@formatstartyear}
%    \begin{macrocode}
\newcommand{\tl@formatstartyear}[1]{
  \startyeartrue
  \tl@yearfraction{#1}
  \pgfmathsetmacro\tl@startfraction{(\tl@startyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
  \ifissince
    \xdef\tl@startlabel{\tl@since \tl@tmpyear}
  \else
    \xdef\tl@startlabel{\tl@tmpyear}
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl@formatendyear}
%    \begin{macrocode}
\newcommand{\tl@formatendyear}[1]{
  \startyearfalse%
  \tl@yearfraction{#1}
  \pgfmathsetmacro\tl@endfraction{(\tl@endyear-\tl@firstyear)/(\tl@lastyear-\tl@firstyear)}%
  \ifissince%
    \xdef\tl@endlabel{}
  \else
    \xdef\tl@endlabel{\tl@tmpyear}
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tldatelabelcventry}
%    \begin{macrocode}
\newcommand{\tldatelabelcventry}[8][color1]{%
%    \end{macrocode}
%    \begin{macrocode}
\issincefalse
\tl@formatstartyear{#2}
\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] {#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}
\issincefalse
\tl@formatstartyear{#2}
\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}
\tl@formatendyear{#3}
\tl@formatstartyear{#2}
 \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] {\tl@endlabel}
       (\hintscolumnwidth,0pt) ;
    \ifissince
       \newdimen\fullcolorwidth
       \pgfmathsetlength\fullcolorwidth{\tl@startfraction*(1+(1-\tl@startfraction)*\tl@nsfrac)*\hintscolumnwidth}
       \shade [left color=#1,right color=#1]
(\tl@startfraction*\hintscolumnwidth,0)
           rectangle (\fullcolorwidth,\tl@width);
       \shade [left color=#1] (\fullcolorwidth,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}
\tl@formatendyear{#3}
\tl@formatstartyear{#2}
 \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) ;
    \ifissince
       \newdimen\fullcolorwidth
       \pgfmathsetlength\fullcolorwidth{\tl@startfraction*(1+(1-\tl@startfraction)*\tl@nsfrac)*\hintscolumnwidth}
       \shade [left color=#1,right color=#1]
(\tl@startfraction*\hintscolumnwidth,0)
           rectangle (\fullcolorwidth,\tl@width);
       \shade [left color=#1] (\fullcolorwidth,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