gitinfo2.tex

% gitinfo2.tex
% Copyright 2014 Brent Longborough
%
% 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 Brent Longborough.
%
% This work consists of these files:
%     gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
%     gitinfotest.tex, post-git-sample.txt,
%     and gitPseudoHeadInfo.gin
% -----------------------------------------------------
\documentclass[a4paper,12pt,twoside,openany]{memoir}
% =====================================================
% This is a tweak to allow this document to be formatted
% even when it doesn't live in an adequately configured
% git repository. Please do not try this at home.
% You have been warned.
% -----------------------------------------------------
\makeatletter
\newcommand{\GI@repo@prefix}{}
\newcommand{\GI@githeadinfo@file}{\GI@repo@prefix./gitPseudoHeadInfo.gin}
\makeatother
% -----------------------------------------------------
% End of tweak
% =====================================================
\usepackage[pcount,grumpy,mark,markifdirty]{gitinfo2}
\usepackage{tgpagella}
\usepackage{tgadventor}
\usepackage{fontspec}
\setmainfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Pagella}
\setsansfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Adventor}
\setmonofont{Consolas}
\usepackage{enumitem}
\setlist[description]{%
    format=\ttfamily\bfseries,
    style=nextline,
    leftmargin=5em,
    itemsep=0.5\onelineskip}
\setulmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setlrmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setheadfoot{1.2\baselineskip}{0.0849\paperwidth}
\setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
\setheaderspaces{*}{*}{0.618}
\checkandfixthelayout[fixed]
\tightlists
\chapterstyle{bringhurst}
\pagestyle{empty}
\aliaspagestyle{chapter}{empty}
\settocdepth{section}
\setsecnumdepth{none}
\newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\textbf{#1}\,}
\newcommand{\sfit}[1]{\textit{#1}}
\newcommand{\git}{\sfit{git}}
\newcommand*{\emailat}{@}
\newcommand{\opname}{\sfit{gitinfo}}
\newcommand{\tpname}{\sfit{gitinfo2}}
\newcommand{\tpfname}{\textsf{gitinfo2.sty}}
\newcommand{\ginname}{gitHeadInfo.gin}
\newcommand{\metaname}{\texttt{\ginname}}
\newcommand{\metapath}{\texttt{.git/\ginname}}
% -----------------------------------------------------
\usepackage[%
	bookmarksnumbered,
	bookmarksopen,
	linktocpage,
	]{hyperref}
\hypersetup{
   pdfauthor={Brent Longborough},
   pdftitle={The gitinfo2 package: git metadata for LaTeX},
   pdfkeywords={git;metadata;dvcs},
}
\begin{document}
\frontmatter
% -----------------------------------------------------
\title{%
	\Huge \tpfname\\[2ex]%
	\Large A package for accessing metadata\\from the \git\ \textsc{dvcs}
	}
\author{Brent Longborough}
\date{12th May, 2014}
\maketitle

{\centering
Release:\gitReln\ (\gitAbbrevHash)\\
}
%\vspace*{2\baselineskip}
% -----------------------------------------------------
\begingroup
\thispagestyle{empty}
\aliaspagestyle{chapter}{empty}
\setlength{\afterchapskip}{20pt}
\let\clearpage\relax
\let\chaptitlefont\Large\bfseries
\vspace*{5\baselineskip}
\tableofcontents*
\endgroup
% -----------------------------------------------------
\mainmatter
\pagestyle{giruled}
\aliaspagestyle{chapter}{giplain}
\chapter{Introduction}
More and more, writers are using version control systems
to manage the progress of their works.
One popular distributed version control system commonly used today
is \git.

Among other blessings, \git provides
some useful metadata concerning the history of the developers'
work, and, in particular, about the current state of that work.

\tpname\ allows writers to incorporate some of this metadata
into their documents, to show from which point in their development
a given formatted copy was produced.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{How \tpname\ works}
\begin{enumerate}
\item Whenever you commit work or check out a branch in \git,
\git\ executes a \textit{post-commit} or \textit{post-checkout hook}.

\item The \tpname\ package includes a sample hook
(placed in your \git\ hooks directory),
which extracts metadata from \git\ and writes it to a \TeX\ file,
named \metaname\ (`gin' for \textbf{g}it \textbf{in}fo).

\item When you format your document, \tpname\ reads
\metaname\ and stores the metadada
in a series of \LaTeX\ commands.

\item You may use these commands to insert
the metadata you need at any point in the document.
\end{enumerate}

It is important to note that \tpname\ reads the metadata
with the equivalent of \texttt{\textbackslash input\{.git/\ginname\}}
in the repository (module or submodule) root.

If you actually want to use \tpname, then please read on.
But you may just be reading this to see whether it will be useful;
in this case,
please skip the next chapter and go on to (Using the package)
on page \pageref{ch:using}.
If you like what you see, you can come back to
read (Setup) later.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{Why a new package?}

The improvements to \opname\ version~2 mean that 
existing repositories would not work; 
so if I just dumped a new version of \opname\  
on to CTAN, anyone who updated \opname\ 
would need to migrate all their active repositories
before they could resume work.

So in order to avoid the rebukes that would follow, 
I have changed the package name to \tpname, 
and the inner package name from \sfit{gitsetinfo}
to \sfit{gitexinfo}.

\opname\ is now informally deprecated, 
and the first reply to any bug reports or feature requests
will be `try \tpname'.
Of course, I will support \tpname\ itself 
to the best of my somewhat limited ability. 

For obvious reasons, \emph{do not try} 
to use both packages in the same repository;
for a new repository, use \tpname,
and for an old one, either leave it alone with \opname,
or migrate it to \tpname.

To the administrators of CTAN, 
I'm sorry I caused you this clutter 
by not getting it right the first time.

% -----------------------------------------------------
\chapter{Setup and tailoring}
\tpname\ will be installed by your favourite package or distribution manager,
but before you can start to use it,
you need to configure each of your \git\ working copies
by setting up hooks to capture the metadata.

If you're familiar with tweaking \git, you can probably work it out for yourself.
If not, I suggest you follow these steps:

\begin{enumerate}

\item First, you need a \git\ repository and working tree.
For this example, let's suppose that the root of the working tree is in
\texttt{\textasciitilde/compsci}

\item Copy the file \texttt{post-xxx-sample.txt} as \texttt{post-checkout}
into the \git\ hooks directory in your working copy.
In our example case, you should end up with a file called
\texttt{\textasciitilde/compsci/.git/hooks/post-checkout}

\item If you're using a unix-like system,
don't forget to make the file executable.
Just how you do this is outside the scope of this manual,
but one possible way is with commands such as this:

\begin{verbatim}
chmod g+x post-checkout.
\end{verbatim}

\item Test your setup with ``git checkout master''
(or another suitable branch name).
This should generate copies of \metaname\ in the directories
you intended.

\item Now make two more copies of this file in the same directory (\texttt{hooks}), calling them
\texttt{post-commit} and \texttt{post-merge}, and you're done.
As before, users of unix-like systems should ensure these files are marked as executable.
\end{enumerate}

If you don't want to install \tpname\ using a package manager,
you can instead just copy the two *.sty files into your document directory.
However, it may be simpler, for more complex project trees,
to install the package as part of your \TeX distribution.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Migrating from version 1}

Version~2 of \tpname\ simplifies setup and brings additional convenience.
But this comes at a cost:
existing repositories need to be upgraded to be compatible.
This decision wasn't taken lightly; I really do think the incompatible changes
will give us a much firmer base for the future.
The changes needed, which should be applied to every repository, follow.

\bpara{Update \git\ hooks.}
Replace the hooks (\texttt{post-checkout}, \texttt{post-commit},
and \texttt{post-merge}) with the contents of the file \texttt{post-xxx-sample.txt}.
Since \tpname\ now uses only a single \metaname\ file for the whole repository,
you do \emph{not} need to tailor these hooks to map your document folders.

If you are fortunate enough to be using a unix-like system,
don't forget to ensure the hooks are executable.

\bpara{Recreate the new \metaname\ file.}
After you've replaced the hooks, the simplest way is to re-check-out the current branch,
using a command such as \verb!git checkout!.

\bpara{Delete the old \metaname\ files,}
when you're ready.

\bpara{If you're a \sfit{memoir} user,}
and you use the \texttt{footinfo} package option,
you will need to adjust your page styles.

From \tpname\ version~2, we no longer override the standard \sfit{memoir}
page styles.
Instead, \tpname\ provides three new page styles:
\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings},
which you should now use to provide \tpname-tailored pages.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Tailoring release tags}

As shipped, the \git\ hook code uses a certain convention
for identifying `release' tags:
the tag must begin with a numeric digit, and contain at least one decimal
point.\footnote{I.e. full stop or period, depending on which variant of English you use.}

Here is the line in the hook where this convention is established:

\begin{quotation}
{\ttfamily
RELTAG=\$(git describe \textellipsis\ --match '[0-9]*.*' \textellipsis)
}
\end{quotation}

By changing the \texttt{--match} parameter, you can decide exactly which tags
qualify as `release' tags for your needs. Thus

\begin{quotation}
{\ttfamily
RELTAG=\$(git describe \textellipsis\ --match 'R.*' \textellipsis)
}
\end{quotation}
would allow you to find tags like `R.2.0.1' and `R.L.Stevenson',
or

\begin{quotation}
{\ttfamily
RELTAG=\$(git describe \textellipsis\ --match '*' \textellipsis)
}
\end{quotation}
would allow you to find any tag whatsoever.

You can change the hooks without needing to alter \tpname,
since whatever tag is found is used as-is.

% -----------------------------------------------------
\chapter{Using the package}
\label{ch:using}
Once you've set up your \git hooks, and done your first commit,
merge, or checkout to drive them,
you can start incorporating the metadata into your document.

The \tpname\ package is loaded in the usual way:\\[0.5\baselineskip]
\texttt{\textbackslash usepackage[$<options>$]\{gitinfo2\}}

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Package options}

The following options are available:

\subsection{General options}

\begin{description}

\item[grumpy]
By default, If \tpname\ can't find \metaname\ (the metadata file),
it will set all the metadata to a common value, ``(None)'',
issue a package warning, and carry on.
If the \texttt{grumpy} option is used,
this warning becomes an error, and processing stops.

\item[\texttt{missing=\textit{text}}]
If \tpname\ can't find \metaname (the metadata file),
or some particular item of metadata,
it will normally set the metadata to a default common value, ``(None)''.
You can change this value to something else with, say
\texttt{missing=Help!} or \texttt{missing=\{What a mess\}}.

If you have complex needs, as in the second example,
don't forget to enclose your text in \{\}s.

\item[\texttt{notags=\textit{text}}]
If \tpname\ can't find any tags in the \git\ references,
it will normally set the tag list to a default value, ``(None)''.
You can change this value to something else with, say
\texttt{missing=\{They stole my tags.\}} or 
\texttt{notags=HelpNoTags!}. 

Again, for complex needs, as in the first example,
don't forget to enclose your text in \{\}s.

\item[\texttt{dirty=\textit{text}}]
If \tpname\ detects that your working copy is dirty
(in the git sense --- it has uncommitted changes),
it makes this information available as a command.
For a clean repository, this is empty, while for a dirty repository
it provides the default text ``(*)''.
You can change this value to something else with, say
\texttt{dirty=Unclean!} or \texttt{dirty=\{This repo is grotty\}}.

Again, for complex needs, as in the second example,
don't forget to enclose your text in \{\}s.

\item[\texttt{maxdepth=\textit{n}}]
In order to locate \metapath\ in the repository root,
\tpname\ starts in the directory containing the document being processed,
and searches up the directory tree until it finds it.
This search is limited to {\ttfamily\itshape n} levels --- 4 by default.
If have to deal with documents
deeper in your repository tree, you can extend this limit with, say,
{\ttfamily maxdepth=8}.

\end{description}

\subsection{Options for watermarking}

These options allow you to place a watermark of \git\ metadata, 
at the bottom of the paper, conditionally or unconditionally

\begin{description}

\item[mark]
This option causes \tpname\ to generate a watermark, 
centred at the bottom of each sheet,
containing `useful' \git\ metadata. 
The watermark is always added.

\item[markifdraft]
This option is like {\ttfamily\bfseries mark,}
but only activates the watermark if the document is being processed
with the {\ttfamily\bfseries draft} option. 

\item[markifdirty]
This option is like {\ttfamily\bfseries mark,}
but only activates the watermark if the last commit or checkout left 
uncommitted changes in the repository.

\item[draft]
This option \emph{should not be used;} it only exists to `capture' the 
{\ttfamily\bfseries draft} option from the document class definition.

\end{description}

\subsection{Options for \sfit{memoir} users}

\begin{description}

\item[footinfo]
This option is no longer used, and if present is silently ignored.
For \sfit{memoir} users, \tpname\ now creates, automatically,
three new page styles.
More detail is given below (For \sfit{memoir} users).

\item[pcount]
For \sfit{memoir} users, this option will replace the folio
in the new page styles with one of the form \textit{x/y},
where \textit{x} is the folio and \textit{y} is the page count.

No warning is given, and no action taken,
if this parameter is used with another document class.
More detail is given below (For \sfit{memoir} users).
\end{description}
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{The metadata}
The \git\ metadata, for the current HEAD commit,
is made available in the document
as a series of parameter-less \LaTeX commands.
Here they are:

\begin{description}

\item[gitReferences]
    A list of any \git\ references (tags, branches) associated
    with this commit.
    This string is not for the faint-hearted;
    its format and order may vary between versions of \git.\\
    Example:\\\textit{\small\gitReferences}

\item[gitBranch]
    The name of the current branch.
    Depending on how you use \git,\footnote{For example, checking out unnamed branches}
    this information may not be available,
    and will then be shown as the default or specified value of
    the \texttt{missing} package option.\\
    Example: \textit{\gitBranch}

\item[gitDirty]
    If the last commit or checkout left uncommitted changes in the working tree,
    the default or specified value of the \texttt{dirty} package option; 
    otherwise empty.

\item[gitAbbrevHash]
    The seven-hex-char abbreviated commit hash\\
    Example: \textit{\gitAbbrevHash}

\item[gitHash]
    The full 40-hex-character commit hash\\
    Example: \textit{\gitHash}

\item[gitAuthorName]
    The name of the author of this commit\\
    Example: \textit{\gitAuthorName}

\item[gitAuthorEmail]
    The email address of the author of this commit\\
    Example: \textit{myemail\emailat evilspam.net}

\item[gitAuthorDate]
    The date this change was committed by the author,
    in the format \textit{yyyy-mm-dd}\\
    Example: \textit{\gitAuthorDate}

\item[gitAuthorIsoDate]
    The date and time this change was committed by the author,
    in ISO format\\
    Example: \textit{\gitAuthorIsoDate}
\clearpage
\item[gitAuthorUnixDate]
    The date and time this change was committed by the author,
    as a Unix timestamp\\
    Example: \textit{\gitAuthorUnixDate}

\item[gitCommitterName]
    The name of the committer of this commit\\
    Example: \textit{\gitCommitterName}

\item[gitCommitterEmail]
    The email address of the committer of this commit\\
    Example: \textit{watcher\emailat gchq.gov.uk}

\item[gitCommitterDate]
    The date this change was committed by the committer,
    in the format \textit{yyyy-mm-dd}\\
    Example: \textit{\gitCommitterDate}

\item[gitCommitterIsoDate]
    The date and time this change was committed by the committer,
    in ISO format\\
    Example: \textit{\gitCommitterIsoDate}

\item[gitCommitterUnixDate]
    The date and time this change was committed by the committer,
    as a Unix timestamp\\
    Example: \textit{\gitCommitterUnixDate}

\end{description}


\subsection{Additional metadata (Version 1)}

Three more commands are available, but their use should be considered
experimental. \tpname\ searches the \git\ references metadata for
anything (probably a \git\ tag) that looks like a number with a decimal point.
The first such number it finds is taken as a ``Version Number''
and made available in three different formats, explained here:

\begin{description}
\item[gitVtag]
    The version number, without decorations. If no version number is found,
    empty (i.e. zero width).
\item[gitVtags]
    The version number, with a leading space. If no version number is found,
    empty.
\item[gitVtagn]
    The version number, with a leading space.
    If no version number is found, a space,
    followed by the default or specified value of
    the \texttt{missing} package option.\\
    Example: \textit{\gitVtagn}
\end{description}

These versioning tags have been superseded by release tags in Version 2,
although they should continue to work as before.

\subsection{Additional metadata (Version 2)}

From Version 2 onwards, additional \git\ metadata is available,
in general improving or extending the facilities available in Version 1.
The Version 1 metadata is retained for backward compatibility.

Included is a new set of \texttt{gitRel} commands,
designed to replace \texttt{gitVtag} and its cousins.
\tpname\ searches the \git\ metadata for tags
on the current \textsc{head} commit or its ancestors,
and makes the first tag found available.
It also looks for the latest such tag
whose name begins with a digit, and which contains a full stop (period),
and makes the tag, and the number of commits following it,
available as a `release number'.%
\footnote{\tpname\ doesn't check for numerics, so you can use a tag like `1.5-beta' if you wish.}
Here are the new commands in Version~2:

\begin{description}

\item[gitFirstTagDescribe]
	The last tag reachable from the current \textsc{head}.
    Please see git-describe for more information.
    If the working copy is \textit{dirty} (has uncommitted changes),
    the string has '-*' appended.\\
    Example: \textit{\gitFirstTagDescribe}

\item[gitRel]
    The release number, without any decorations.
    If no release number is found, empty (i.e. zero width).

\item[gitRels]
    The release number, with a leading space.
    If no release number is found, empty.

\item[gitReln]
    The release number, with a leading space.
    If no release number is found, a space,
    followed by the default or specified value of
    the \texttt{missing} package option.

\item[gitRoff]
    The number of commits between the current \textsc{head}
    and the tag holding the release number.
    If the tag refers to the current \textsc{head}, zero.

\item[gitTags]
    A comma-separated list of tags associated with the current \textsc{head}.\\
    Example: \textit{\gitTags}

\item[gitDescribe]
    The raw output from the git-describe command for the last release tag
    reachable from the current \textsc{head}, including tag name, commit offset, 
    short hash, and a dirty flag.
    Please see git-describe for more information.
    Example: \textit{\gitDescribe}

\end{description}

\clearpage
\subsection{Watermark tailoring commands}

If you use the Version 2 options to place a watermark,
you can tailor the format of the watermark to suit your needs,
by redefining one or more of the following commands.

\begin{description}

\item[gitMark]
    Contains the text of the watermark. 
    Output from the default definition can be seen
    below the footer
    at the bottom of this page.
    The definition, split onto three lines to fit, is:

\begin{verbatim}
Branch: \gitBranch\,@\,\gitAbbrevHash{} / 
Release:\gitReln{} (\gitAuthorDate)\\
Head tags: \gitTags
\end{verbatim}

You can tailor this by redefining \verb!\gitMark!. 
For example: 

\begin{verbatim}
\renewcommand{\gitMark}{\gitHash\hfill\gitRel}
\end{verbatim}

\item[gitMarkFormat]
    Defines typesetting parameters for the whole watermark.
    The default definition is:

\begin{verbatim}
\color{gray}\small\sffamily
\end{verbatim}
You can tailor this by redefining \verb!\gitMarkFormat!. For example: 

\begin{verbatim}
\renewcommand{\gitMarkFormat}{\color(red)\ttfamily}
\end{verbatim}

\item[gitMarkPref]
    Contains the text of the watermark prefix, 
    which depends on the reason the document is being watermarked.
    is being printed.
    The default values are \sfit{[Dirty]}, \sfit{[Draft]}, or \sfit{[git]}.
    You can tailor this by redefining \verb!\gitMarkPref!. For example: 

\begin{verbatim}
\renewcommand{\gitMarkPref}{[Pending review]}
\end{verbatim}

\end{description}

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{For \sfit{memoir} users}
If you use \sfit{memoir}, \tpname\ provides you with
three new pagestyles, based on
\sfit{plain},\sfit{ruled}, and \sfit{headings}.
The new pagestyles are called
\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings}.

For the \sfit{giplain} and \sfit{giruled} pagestyles,
the folio is moved from the centre to the outer margin of the footer,
and a revision stamp is placed in the inner margin.

For the \sfit{giheadings} pagestyle,
the folio is moved from the outer margin of the header
to the outer margin of the footer,
and a revision stamp is placed in the inner margin of the footer.

If you use the \texttt{pcount} option, a solidus, and the page count,
are appended to the folio.

The revision stamp is generated by this fragment:

\begin{verbatim}
    Release\gitRels: \gitAbbrevHash{} (\gitAuthorDate)
\end{verbatim}
\noindent
which is set at tiny in the sans-serif font.

Note that, in contrast to version 1 of \tpname,
version 2 no longer modifies the existing page styles.
If you wish to use this facility,
you must now select
the appropriate \sfit{gi\textellipsis} page style 
explicitly.

You can see an example in the footer of this page, 
above the \tpname\ watermark.
% -----------------------------------------------------
\chapter{Etc}
\section{Acknowledgements \& dependencies}

The \href{http://tex.stackexchange.com}{\TeX.SE community}
has been a constant source of help, inspiration, and amazement.
In particular, I'd like to thank
\href{http://tex.stackexchange.com/users/73/joseph-wright}{Joseph Wright},
who rescued me from the jaws of the TeX parser by explaining
\textbackslash expandafter.

I's also like to register my thanks to the owners of the packages on which
\tpname\ depends: eso-pic, etoolbox, kvoptions, and xstring.

Many people have written to me kindly
to point out some of the defects in \opname, and to offer code.
I owe you all an apology for the amount of time that elapsed
from your suggestions to the making of \tpname.

In some cases, I have not taken up suggestions other than as food for thought,
in others used the code or suggestions directly, and,
in yet others, adapted.
I thank you all, especially for stimulating my thought processes,
and thus, hopefully, 
helping to make \tpname\ a whole lot better than \opname.

I think I owe a special mention, both for ideas and code,
to Clea Rees, Jörg Weber, and Kai Mindermann
for improving the handling of \git\ references;
to Jörg Weber for watermarking;
and to Michael Rans and Ross Vandegrift for 
the deduplication of \metaname.

My sincere thanks, too, to
Adrian Burd,
Felix Wenger,
Johannes Hoetzer,
Martin W Leidig,
Nik (of gwdg nokta de),
Omid (of gmail nokta com),
Robbie Morrison,
Ryan Matlock, and
Sasaki~Suguru.

The failings, of course, I claim for my self.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Copyright \& licence}
Copyright \copyright\ 2014, Brent Longborough.

This work --- \tpname\ --- 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 at
\url{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 Brent Longborough.

This work consists of the files
gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
post-git-sample.txt, and \ginname.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{From the author}
Although my limitations as a \TeX nician
mean that I've implemented \tpname\ in a rather simplistic way
that needs some setup that is more complicated than I wanted,
I hope you find the package useful.
I'll be very happy to receive your comments by email.\\[\baselineskip]
Brent Longborough\\[\baselineskip]
\textsf{brent+ctancontrib (bei) longborough (punkt) org}\\
and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
% -----------------------------------------------------
\end{document}