%% $Id: zwgetfdate.tex 203 2008-06-14 18:56:59Z zw $
\input utf8-t1 % encTeX required
\documentclass[11pt]{article}
\usepackage{zwgetfdate}
% The following package will be made available soon.
\usepackage[footskip=30pt]{zwpagelayout}
\usepackage[T1]{fontenc}
\usepackage{lmodern,array}
\usepackage[protrusion=false,expansion=true,stretch=8,shrink=24,step=4]{microtype}
{\lccode`\!`\\
\lowercase{\gdef\Bslash{!}}}
\DeclareRobustCommand\cmd[1]{\texttt{\Bslash#1}}
\mubytein 0 % important due to bug in url.sty
\usepackage[pdftitle=Get the File/Package Date, pdfauthor=Zdenek\ Wagner,
            bookmarks,bookmarksopenlevel=2,bookmarksopen]{hyperref}
\mubytein 1 \mubyteout 3 \mubytelog 3
\begin{document}
\title{Get the File/Package Date}
\author{Zdeněk Wagner\\\url{http://icebearsoft.euweb.cz}}
\date{Package date: \DateOfPackage{zwgetfdate}}
\maketitle

\begin{abstract}\noindent
This package is useful for just a small group of developers who write documentation. Its purpose is
to get the date of a file or a package as specified in the \cmd{ProvidesFile} or
\cmd{ProvidesPackage}, respectively.
\end{abstract}

\tableofcontents

\section{Motivation}
File identification is a fundamental problem. If something does not work in your computer but works
elsewhere, it usually means that you have a different version of some file(s). \LaTeX\ enables checking
the correct release date of a file or package using an optional argument. You can easily display
the list as well as dates of files used in your document by the \cmd{listfiles} command. The date
thus seems to be more important than the file's version number.

Once we can identify the date of the file or package, we want to be sure that we read the correct
documentation. The developer usually creates a private packaging script which takes the right files from
his/her repository. The file to be documented is the one that is currently installed. It seems thus
natural if the date is taken automatically from the file.

The package serves this very purpose. It intercepts the standard \LaTeX\ macros \cmd{ProvidesFile} and
\cmd{ProvidesPackage} and remembers their dates. These dates can be later queried.

\section{Usage}
The package is loaded by the following command:

\medskip
\verb;\usepackage{zwgetfdate};

\medskip
The package then stores the dates of files and packages loaded \emph{after} itself including its
own date.

The package defines two commands. They try to find the date of the specified file or package and
output it. If the date is not found (the file/package was not loaded or does not contain
identification), warning is written both to the terminal and the log file but nothing is printed.
Remember that this is not a diagnostic package, you should know what you use in your document.

\subsection{Command \cmd{DateOfPackage}}
This command returns the date of a package. It was used in the title of the document, command
\verb;\DateOfPackage{zwgetfdate}; showed the date of the package being documented. This document
also makes use of the \textsc{hyperref} package. Using \verb;\DateOfPackage{hyperref}; we can see
that the package used for typesetting this manual was of \DateOfPackage{hyperref}.

\subsection{Command \cmd{DateOfFile}}
This command returns the date of the file. Remember that \verb;\DateOfFile{zwgetfdate.sty}; will
display nothing because \textsc{zwgetfdate} is loaded and identified as a package, not as an
ordinary file. However, this document is typeset in the T1 encoding and thus file
\texttt{t1enc.def} is loaded. Command \verb;\DateOfFile{t1enc.def}; will show that its date is
\DateOfFile{t1enc.def}.

\section{License}
The package can be used and distributed according to the LaTeX Project Public License version~1.3 or later the
text of which can be found at the \texttt{License.txt} file in the \texttt{doc} directory or at
\url{http://www.latex-project.org/lppl.txt}

\end{document}
