% \iffalse meta-comment
%
% Copyright (C) 2017 Vincent Goulet
%
% This file may be distributed and/or modified under the conditions
% of the LaTeX Project Public License, either version 1.3c 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.3c or later is part of all distributions of LaTeX
% version 2006/05/20 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Vincent Goulet
% <vincent.goulet@act.ulaval.ca>.
%
% This work consists of the files actuarialangle.dtx and
% actuarialangle.ins and the derived files listed in the README.md
% file.
%
% \fi
%
% \iffalse
%<*dtx>
          \ProvidesFile{actuarialangle.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}[2009/09/24]
%<package>\ProvidesPackage{actuarialangle}[2017/04/10 v2.0 Actuarial angle]
%<*batchfile>
\begingroup
\input docstrip.tex
\keepsilent
\askforoverwritefalse

\preamble

This is a generated file.

Copyright (C) 2017 Vincent Goulet

This file may be distributed and/or modified under the conditions
of the LaTeX Project Public License, either version 1.3c 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.3c or later is part of all distributions of LaTeX
version 2006/05/20 or later.

This work has the LPPL maintenance status `maintained'.

The Current Maintainer of this work is Vincent Goulet
<vincent.goulet@act.ulaval.ca>.

This work consists of the files actuarialangle.dtx and
actuarialangle.ins and the derived files listed in the README.md file.

\endpreamble
\generate{\file{actuarialangle.sty}{\from{actuarialangle.dtx}{package}}}
\endgroup
%</batchfile>
%<*driver>
\documentclass[11pt,x11names]{ltxdoc}
  \usepackage[utf8]{inputenc}
  \usepackage[T1]{fontenc}
  \usepackage{natbib}
  \usepackage{microtype}
  \usepackage[scaled=0.90]{helvet}
  \usepackage[scaled=1.02]{inconsolata}
  \usepackage[sc]{mathpazo}
  \usepackage{actuarialangle}
  \usepackage{framed}
  \DisableCrossrefs
  \CodelineNumbered
  \RecordChanges
  \GlossaryPrologue{\section*{Version history}%
    \addcontentsline{toc}{section}{Version history}}

  %% colors
  \usepackage{xcolor}
  \definecolor{link}{rgb}{0,0.4,0.6}   % ~dvips RoyalBlue
  \definecolor{url}{rgb}{0.6,0,0}      % dark red
  \definecolor{citation}{rgb}{0,0.5,0} % dark green
  \colorlet{shadecolor}{LightYellow1}

  %% left aligned description list
  \usepackage{enumitem}
  \setlist[description]{leftmargin=*,align=left}

  %% environments for demo code; 'texample' mostly lifted from
  %% documentation of amsmath
  \newenvironment{demo}{\begin{trivlist}\item}{\end{trivlist}}
  \newenvironment{texample}[1][0.5]{%
    \noindent\begin{minipage}{#1\linewidth}\begin{snugshade*}%
      \def\producing{\end{snugshade*}\end{minipage}\hfill\begin{minipage}{\dimexpr0.97\linewidth-#1\linewidth}%
        \hbox\bgroup\kern-.2pt%
        \vbox\bgroup\parindent0pt\relax
        % The 3pt is to cancel the -\lineskip from \displ@y
        \abovedisplayskip3pt \abovedisplayshortskip\abovedisplayskip
        \belowdisplayskip0pt \belowdisplayshortskip\belowdisplayskip
        \noindent}
    }{%
      \par
      % Ensure that a lonely \[\] structure doesn't take up width less than
      % \hsize.
      \hrule height0pt width\hsize
      \egroup\kern-.2pt\egroup
    \end{minipage}%
    \par
  }

  %% utility macro
  \newcommand{\pkg}[1]{\textsf{#1}}

  %% hyperlinks
  \usepackage{hyperref}
  \hypersetup{colorlinks, linktocpage,
    urlcolor=url, linkcolor=link, citecolor=citation,
    bookmarksopen, bookmarksnumbered, bookmarksdepth=subsection,
    pdftitle={actuarialangle User Guide},
    pdfauthor={Vincent Goulet}}

  %% autoref labels
  \let\subsectionautorefname\sectionautorefname
  \let\subsubsectionautorefname\sectionautorefname

\begin{document}
  \DocInput{actuarialangle.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{126}
% \changes{v1.0}{2012-10-16}{Initial release.}
% \changes{v1.1}{2017-02-01}{Various improvements to the README
%   file, including conversion to markdown format after the project was
%   moved to GitHub.}
% \changes{v2.0}{2017-04-09}{Complete new documentation.}
%
% \GetFileInfo{actuarialangle.sty}
%
% \title{Actuarial angle symbol for life contingencies \\
%   and financial mathematics%
%   \thanks{This document corresponds to
%   \pkg{actuarialangle}~\fileversion, dated~\filedate.}}
% \author{Vincent Goulet\thanks{%
%   École d'actuariat, Université Laval.} \\
%   \url{vincent.goulet@act.ulaval.ca}}
% \maketitle
%
% \begin{abstract}
%   Package \pkg{actuarialangle} provides commands to typeset the
%   ``angle'' symbol denoting a duration $n$ in actuarial notation, as
%   in $\angln$, and an overhead angle bracket, as in $\group{xy}$.
% \end{abstract}
%
% \section{Introduction}
%
% This package defines commands to typeset two symbols used in
% actuarial notation for life contingencies and financial mathematics.
% The first is the ``angle'' denoting a duration in the present value
% of an insurance or annuity: $\angln$. The second is an overhead
% angle bracket (or ``roof'') used to emphasize joint status when
% ambiguity is possible: $\group{xy}$. The bracket is normally used
% with a precedence number above. Facilities to position such numbers
% are provided by package \pkg{actuarialsymbol}
% \citep{actuarialsymbol}.
%
% For additional details on actuarial notation for life contingencies,
% see \citet{Bowers:2e:1997}.
%
% \section{Package options}
% \label{sec:options}
%
% The package offers the following options:
% \begin{description}
% \item[\mdseries\ttfamily thinspace] insert a thin space of 1mu
%   between the material under the angle and the right descender; this
%   is the default starting with version 2.0 of the package;
% \item[\mdseries\ttfamily thickspace] insert a thicker space of 2mu
%   between the material under the angle and the right descender; this
%   was the value used in versions of the package prior to 2.0;
% \item[\mdseries\ttfamily nobracket] do not define command
%   \cmd{\overanglebracket}; this option also prevents loading of
%   package \pkg{pict2e}.
% \end{description}
% We provide option |nobracket| in case the bracket symbol is not
% needed and \pkg{pict2e} \citep{pict2e} interferes with other
% packages. Loading the package with
% \begin{quote}
%   |\usepackage[thickspace,nobracket]{actuarialangle}|
% \end{quote}
% yields the behaviour of versions prior to 2.0, but for the defunct
% features mentioned in \autoref{sec:defunct}.
%
% \section{Package features}
%\label{sec:features}
%
% \begin{DescribeMacro}{\actuarialangle}
%   In math mode, the command
%   \begin{quote}
%     |\actuarialangle|\marg{duration}
%   \end{quote}
%   composes an angle symbol around \meta{duration}. This is the
%   ``raw'' command that does not insert any space between
%   \meta{duration} and the right descender of the angle. The symbol
%   scales gracefully if the command is ever used outside of a
%   first-level subscript.
%   \begin{demo}
%     \begin{texample}
%       |\actuarialangle{n} \quad| \\
%       |a_{\actuarialangle{n}}|
%       \producing
%       $\actuarialangle{n} \quad a_{\actuarialangle{n}}$
%     \end{texample}
%   \end{demo}
% \end{DescribeMacro}
%
% \begin{DescribeMacro}{\angl}
% \begin{DescribeMacro}{\angln}
% \begin{DescribeMacro}{\anglr}
% \begin{DescribeMacro}{\anglk}
%   Users are expected to typeset angle symbols with the command
%   \begin{quote}
%     |\angl|\marg{duration}
%   \end{quote}
%   In contrast to \cmd{\actuarialangle}, this command inserts some
%   thin space (by default or with package option |thinspace|) or
%   thick space (with package option |thinkspace|) between
%   \marg{duration} and the right descender.
%   \begin{demo}
%     \begin{texample}
%       |% with option thinspace:| \\
%       |\angl{n} \quad a_{\angl{n}}|
%       \producing
%       $\angl{n} \quad a_{\angl{n}}$
%     \end{texample}
%     \begin{texample}
%       |% with option thickspace| \\
%       |\angl{n} \quad a_{\angl{n}}|
%       \producing
%       $\angl{n\mkern1mu} \quad a_{\angl{n\mkern1mu}}$
%     \end{texample}
%   \end{demo}
%   Commands \cmd{\angln}, \cmd{\anglr} and \cmd{\anglk} are shortcuts
%   for the common cases \cmd{\angl}|{n}|, \cmd{\angl}|{r}| and
%   \cmd{\angl}|{k}|, respectively.
% \end{DescribeMacro}
% \end{DescribeMacro}
% \end{DescribeMacro}
% \end{DescribeMacro}
%
% \begin{DescribeMacro}{\overanglebracket}
% \begin{DescribeMacro}{\group}
%   The command
%   \begin{quote}
%     \cmd{\overanglebracket}\marg{statuses}
%   \end{quote}
%   composes an angle bracket (``roof'') above \meta{statuses}. The
%   rule thickness and spacing relative to the statuses match those of
%   the angle symbol. Command \cmd{\group} is a convenient alias for
%   \cmd{\overanglebracket}.
%   \begin{demo}
%     \begin{texample}
%       |\group{xy} \quad| \\
%       |A_{\group{xy}:\angln}|
%       \producing
%       $\group{xy} \quad A_{\group{xy}:\angln}$
%     \end{texample}
%   \end{demo}
% \end{DescribeMacro}
% \end{DescribeMacro}
%
% \section{Defunct features}
% \label{sec:defunct}
%
% Versions prior to 2.0 of the package included the undocumented
% commands
% \begin{quote}
%   \cmd{\topprecedence} (with alias \cmd{\lift}) \\
%   \cmd{\vartopprecedence} \\
%   \cmd{\bottomprecedence} \\
%   \cmd{\varbottomprecedence}
% \end{quote}
% to typeset precedence numbers above and below statuses in subscript
% of an actuarial symbol. These features have been moved --- and
% improved on the way --- to package \pkg{actuarialsymbol}
% \citep{actuarialsymbol}.
%
% \StopEventually{
%   \begin{thebibliography}{3}
%   \bibitem[Beauchemin and Goulet(2017)]{actuarialsymbol}
%   D.~Beauchemin and V.~Goulet.
%   \newblock \emph{Actuarial symbols of life contingencies and financial
%     mathematics}, 2017.
%   \newblock URL \url{http://www.ctan.org/pkg/actuarialsymbol/}.
%
%   \bibitem[Bowers et~al.(1997)Bowers, Gerber, Hickman, Jones, and
%     Nesbitt]{Bowers:2e:1997}
%   N.~L. Bowers, H.~U. Gerber, J.~C. Hickman, D.~A. Jones, and C.~J. Nesbitt.
%   \newblock \emph{Actuarial Mathematics}.
%   \newblock Society of Actuaries, Shaumburg, IL, second edition, 1997.
%   \newblock ISBN 0-9389594-6-8.
%
%   \bibitem[Gä{\ss}lein et~al.(2016)Gä{\ss}lein, Niepraschk, and Tkadlec]{pict2e}
%   H.~Gä{\ss}lein, R.~Niepraschk, and J.~Tkadlec.
%   \newblock \emph{The pict2e package}, 2016.
%   \newblock URL \url{http://www.ctan.org/pkg/pict2e/}.
%   \end{thebibliography}
%   \PrintChanges
% }
%
% \appendix
% \section{Implementation}
% \label{sec:implementation}
%
% This appendix contains the annotated source code of the package.
% Most readers can stop reading here.
%\iffalse
%<*package>
%\fi
%
% \subsection{Package options}
% \label{sec:implementation:options}
%
% \begin{macro}{\ifacta@thinspace}
%   \changes{v2.0}{2017-04-07}{Options |thinspace| and |thickspace|
%   added to control spacing between material under the angle and
%   right descender.} %
% \begin{macro}{\ifacta@nobracket}
%   \changes{v2.0}{2017-04-09}{Added option |nobracket| to prevent
%   definition of the command to typeset the over angle bracket and
%   loading of package \pkg{pict2e}.} %
%   Two flags are defined to keep track of the spacing between the
%   material under the angle and right descender, and whether or not
%   the package should define the command \cmd{\overanglebracket} and
%   load package \pkg{pict2e}.
%    \begin{macrocode}
\newif\ifacta@thinspace \acta@thinspacetrue
\newif\ifacta@bracket   \acta@brackettrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\DeclareOption}
%   Declaration of the package options and processing. Defaults are
%   |thinspace| and to define the bracket.
%    \begin{macrocode}
\DeclareOption{thinspace}{\acta@thinspacetrue}
\DeclareOption{thickspace}{\acta@thinspacefalse}
\DeclareOption{nobracket}{\acta@bracketfalse}
\ProcessOptions
%    \end{macrocode}
% \end{macro}
%
% \subsection{Actuarial angle}
% \label{sec:implementation:actuarialangle}
%
% The original author of macros \cmd{\actuarialangle} and
% |\acta@angle| is unknown. Some of the comments below are his or
% hers.
%
% \begin{macro}{\actuarialangle}
%   We first define the ``raw'' user level command.
%    \begin{macrocode}
\DeclareRobustCommand{\actuarialangle}{\mathpalette\acta@angle}
%    \end{macrocode}
%   The operation of \cmd{\mathpalette} ensures that proper sizing the
%   command is ever used outside of a first-level subscript.
% \end{macro}
%
% \begin{macro}{\acta@angle}
%   Next we define the real workhorse.
%    \begin{macrocode}
\def\acta@angle#1#2{%
  \mathord{%
%    \end{macrocode}
% Add a bit of preceding space.
%    \begin{macrocode}
    \mkern1mu
%    \end{macrocode}
%   We need many nested boxes here: first a vbox to stack the horizontal
%   rule of the angle and the symbol; second an hbox position the symbol
%   and the right descender of the angle side-to-side; third a vbox to
%   insert spacing between the horizontal rule and the symbol.
%    \begin{macrocode}
    \vbox{\hrule \hbox{%
        \vbox{%
%    \end{macrocode}
%   The amount of vertical space below is the normal space for
%   \cmd{\overline} in a subscript.
%    \begin{macrocode}
          \kern3\fontdimen8\scriptfont\thr@@
          \hbox{$#1#2\m@th$}}%
%    \end{macrocode}
%   Make the right-hand rule extend down to the depth of a parenthesis
%   even if the symbol under the angle does not have a descender.
%    \begin{macrocode}
        \setbox\z@\hbox{$#1()$}\vrule depth\dp\z@}}%
%    \end{macrocode}
%   Finishing touch is a bit of following space.
%    \begin{macrocode}
    \mkern1mu}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\angl}
% \begin{macro}{\angln}
% \begin{macro}{\anglr}
% \begin{macro}{\anglk}
%   \changes{v2.0}{2017-04-07}{Added an \cmd{\anglk} shortcut.} %
%   Finally, we define the main user level function \cmd{\angl} and
%   shortcuts for common cases.
%    \begin{macrocode}
\ifacta@thinspace
  \def\angl#1{{\actuarialangle{{#1}\mkern1mu}}}
\else
  \def\angl#1{{\actuarialangle{{#1}\mkern2mu}}}
\fi
\def\angln{{\angl n}}
\def\anglr{{\angl r}}
\def\anglk{{\angl k}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \section{Over angle bracket}
% \label{sec:implementation:overanglebracket}
%
% The code of this section is executed only if |\acta@bracket| is
% |true|, that is when the package is \emph{not} loaded with option
% |nobracket|.
%    \begin{macrocode}
\ifacta@bracket
%    \end{macrocode}
% Drawing the angle bracket requires package \pkg{pict2e}
% \citep{pict2e} to get arbitrary slopes and neat line joins in paths.
%    \begin{macrocode}
  \RequirePackage{pict2e}
%    \end{macrocode}
%
% \begin{macro}{\overanglebracket}
%   \changes{v2.0}{2017-04-08}{Command \cmd{\overanglebracket} added to
%   typeset an angle bracket (``roof'') above statuses.} %
%   Here is the user level command.
%    \begin{macrocode}
  \DeclareRobustCommand{\overanglebracket}{%
    \mathpalette\acta@anglebracket}
%    \end{macrocode}
%   We use \cmd{\mathpalette} as above.
% \end{macro}
%
% \begin{macro}{\acta@anglebracket}
%   The workhorse is |\acta@anglebracket|. It builds the bracket
%   symbol with path lines.
%    \begin{macrocode}
  \def\acta@anglebracket#1#2{%
%    \end{macrocode}
%   Box zero contains the material under the bracket. The width of this
%   box will determine the width of the flat part of the bracket and the
%   height, the length of the descenders. Hence we store these values.
%    \begin{macrocode}
    \setbox\z@\hbox{$\m@th#1#2$}
    \dimen0\wd\z@ \dimen1\ht\z@
%    \end{macrocode}
%   Box two contains the bracket itself. It is drawn in three parts
%   stitched together; the first and third parts are expressed in a
%   dimension relative |\dimen1|, above, whereas the central part is
%   expressed relative |\dimen0|.
%    \begin{macrocode}
    \setbox\tw@\hbox{%
      \setlength{\unitlength}{\dimen1}%
      \begin{picture}(0.4,0)
        \polyline(0.4001,0)(0.4,0)(0,-0.8)
      \end{picture}%
      \setlength{\unitlength}{\dimen0}%
      \begin{picture}(1,0)
        \put(0,0){\line(1,0){1}}
      \end{picture}%
      \setlength{\unitlength}{\dimen1}%
      \begin{picture}(0.4,0)
        \polyline(-0.0001,0)(0,0)(0.4,-0.8)
      \end{picture}}
%    \end{macrocode}
%   We store the width of the total width of the backet to center the
%   material under it, below.
%    \begin{macrocode}
    \dimen@\wd\tw@
%    \end{macrocode}
%   Box containing the whole symbol. The lineskip between the bracket
%   and the statuses is the same as in |\acta@angle|, plus half the
%   default rule thickness.
%    \begin{macrocode}
    \vbox to\dimen1{%
      \baselineskip\z@
      \lineskip3\fontdimen8\scriptfont\thr@@
      \advance\lineskip by 0.2pt
      \lineskiplimit\lineskip
      \vss
      \box\tw@%
      \hbox to\dimen@{\hss\unhbox\z@\hss}
    }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\group}
%   Alias for \cmd{\overanglebracket}.
%    \begin{macrocode}
  \let\group\overanglebracket
\fi
%    \end{macrocode}
% \end{macro}
%
%\iffalse
%</package>
%\fi
%
% \Finale
% \obeyspaces
% \typeout{*************************************************************}
% \typeout{*                                                           *}
% \typeout{* To finish the installation you have to move the following *}
% \typeout{* file into a directory searched by TeX:                    *}
% \typeout{*                                                           *}
% \typeout{*  actuarialangle.sty                                       *}
% \typeout{*                                                           *}
% \typeout{* To produce the documentation, run actuarialangle.dtx      *}
% \typeout{* through LaTeX.                                            *}
% \typeout{*                                                           *}
% \typeout{* Happy actuarial TeXing!                                   *}
% \typeout{*                                                           *}
% \typeout{*************************************************************}
%
% ^^A Local Variables:
% ^^A mode: doctex
% ^^A TeX-master: t
% ^^A End:
\endinput