\ProvidesFile{filedate.tex}[2013/03/25 documenting filedate.sty]
%% 2012/06/24
\title{\pkgtitle{filedate.sty}{Access and Compare 
       \LaTeX~File~%                                %% 2012/11/06 
       Info 
       \\                                           %% 2012/11/06
       and Modification Date}} 
% \listfiles
{ \RequirePackage{makedoc} \ProcessLineMessage{}
  \MakeJobDoc{18}%% 2012/10/16
  {\SectionLevelThreeParseInput}  }           %% Three 2013/03/24
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
\usepackage{filedate,readprov}
\MDkeywords{modification date, metadata, package documentation, 
            %% <- were these two 2012/10/25 ->
            document versions, macro programming}
\usepackage{lmodern}
\usepackage{filesdo}              %% TODO makedoc.cfg? 2013/03/25
\sloppy 
\providecommand*{\LuaTeX}{Lua\TeX}
\providecommand*{\pdfTeX}{pdf\TeX}
\providecommand*{\XeLaTeX}{X\lower.5ex\hbox{E}\kern-.125em\LaTeX}
%% <- TODO some logo package
% \newcommand*{\qtdfile}{}                          %% 2012/11/06
\newcommand*{\secref}[1]{Section~\ref{sec:#1}}      %% 2013/03/24
\begin{document}
\maketitle
\begin{MDabstract}
'filedate.sty' provides basic access to the date of a 
\LaTeX\ source file according to its `\ProvidesFile', 
`\ProvidesPackage', or `\ProvidesClass' entry---the ``info date"---, 
as well as to its modification date according to `\pdffilemoddate' 
if the latter is available. Moreover commands are provided
to compare the ``info date" with the modification date, with ``today"'s 
date, or with another date---that a script accessing modification dates 
such as \CtanPkgRef{adhocfilelist}{adhocfilelist.sh}
may insert---, and to choose the effect of comparisons 
(error vs.\ ``notice," reference date characterization). 
Thus updating the ``info date" (``\strong{date consistency}") 
of a source file may be ensured by a test 
during typesetting from it or by some (shell/\TeX) script.
v0.4 enables checking info dates automatically as soon as 
a \LaTeX\ file is loaded while typesetting or in a 
\ctanpkgref{myfilist} script.

\MDaddtoabstract{Related packages:} \ctanpkgref{filemod}, 
\ctanpkgref{getfiledate}, \ctanpkgref{zwgetfdate}, 
\ctanpkgref{fileinfo}
\end{MDabstract}
\tableofcontents

%   \newpage
\section{Features and Usage}
\subsection{Basics of Usage}                        %% 2013/03/24
\subsubsection{The Most Interesting Command}
The package allows to check whether the file \strong{info}
date <date> according to `\Provides' near the top of a \LaTeX\ 
input file <file>---i.e.,
\[`\Provides...{<file>}[<date> ...]'\]
has been updated the same day when <file> actually was \strong{modified} 
most recently. With \pdfTeX, this can be checked by 
\[|\CheckDateOfPDFmod{<file>}|\]

\subsubsection{Installing and Calling}
The file 'filedate.sty' is provided ready, installation only requires
putting it somewhere where \TeX\ finds it
(which may need updating the filename data
 base).\urlfoot{ukfaqref}{inst-wlcf}           %% corr. 2011/02/08

%% extended 2011/01/14:
Below the `\documentclass' line(s) and above `\begin{document}',
you load 'filedate.sty' (as usually) by
\[|\usepackage{filedate}|\] 
but in ``\TeX\ scripts" such as \hyperref[sec:wrong]{below}, 
\[|\RequirePackage{filedate}|\]
is better.

\subsubsection{Demonstration with a ``\TeX\ script" Example}
\label{sec:wrong}
The accompanying `wrong.tex' is an example of a ``\pkg{filedate} \TeX\ script" 
demonstrating what may go wrong.
% \begin{quotation}\tt\small
% \expandafter\def\expandafter\{\expandafter{\string{}
% \expandafter\def\expandafter\}\expandafter{\string}}
% \obeyspaces\obeylines
% \cs{ProvidesFile}\{wrong.tex\}[2012/10/15 filedate.sty demo]
% \cs{RequirePackage}\{filedate\}
% \cs{CheckDateOfPDFmod}\{wrong\}
% \cs{CheckDateOfPDFmod}\{wrong.tex\}
% \cs{CheckDateOfToday}\{wrong.tex\}
% \cs{stop}
% \end{quotation}
\MDsamplecodeinput{wrong}
\ReadFileInfos{wrong}
You may run it (by the command line \qtd{\file{latex wrong}}) and experience:
\begin{enumerate}
%  \AddQuotes
  \item `wrong.tex''s ``info date" is \qtd{\file{\theinfodateof{wrong.tex}}}, 
    but its modification date is at least one day later.
  \item 
    `\CheckDateOfPDFmod{wrong}' demonstrates that in 
    \[|\CheckDateOfPDFmod{<file>}|\] 
    <file> must be the \Wikiref{filename} \emph{including extension.}
    Otherwise the ``info date" may be (displayed as) ``unknown."
  \item 
    |\CheckDateOfPDFmod{wrong.tex}| tests against `wrong.tex''s 
    modification date according to `\pdffilemoddate'---the present 
    package documentation uses \ctanpkgref{pdftex} indeed.
  \item 
    |\CheckDateOfToday{wrong.tex}| tests against ``today"'s date, 
    which should be different from `2012/10/15'.
  \item 
    The ``script" terminates on \LaTeX's |\stop| command, 
    without typesetting anything. 
%     (or that's what I expect and what has happened when I tried it).
    \TeX\ is just used as a program, a command interpreter 
    (as with \ctanpkgref{docstrip}).
\end{enumerate}

% \subsection{The Single Commands}
% $\dots$ are described below near to their implementation.

  \pagebreak[2]                                     %% 2013/03/25

\section{Implementation and Single Commands}
\subsection{Package File Header (Legalese)}
\input{filedate.doc}

  \pagebreak                                        %% 2013/03/25
\section{Use with Present Package Documentation}
\label{sec:demo-here}
%% mod. 2012/11/06:
\noNiceVerb
 \input{fdatechk.tex}
\useNiceVerb

\AddQuotes

Above this paragraph,
the documentation source `filedate.tex' issues 
\[|\input{fdatechk.tex}|\]
in order to run the following \TeX~script `fdatechk.tex':
\MDsamplecodeinput{fdatechk}
(That is done \emph{above} the paragraph to avoid wrong spacing 
 within the paragraph from `filedate.tex'.)
This way we check whether the ``info dates" of the package file 
`filedate.sty', of the documentation source and driver 
`filedate.tex', and of some other related files 
are the same as their modification dates 
according to |\pdffilemoddate| (using \code{pdflatex}).
When I added the (original) check on 2012-10-17, 
it indeed informed me that I had not updated 
`filedate.tex's info date 
(\code{2012/10/16}, 
 generation of first version of the file from a template, 
 draft).---%%% 2013/03/25
|\EqualityMessages| confirms that the tests were run indeed. 
%
|\DoWithBasesExts| is from the 'filesdo' package 
(\ctanpkgdref{commado} bundle).

The \TeX~script `srcfiles.tex' that in the first instance 
generates a release overview additionally inputs `fdatechk.tex'
(as of 2012-11-06) as well. This way the check is performed 
even when I rerun the documentation without updating the file list, 
as well the other way round.
%% rm. 2012/11/06:
% However, such checks rather 
% approaching package management should better be based on modification 
% \emph{times}. If this should be done by \TeX\ 
% (\CtanPkgRef{pdftex}{\pdfTeX}, \ctanpkgref{pdfcmds}), 
% it should better be based on the \ctanpkgref{filemod} package. 

\end{document}

VERSION HISTORY

2012/10/16  for v0.2    started     %% was v0.1 2012/10/19
2012/10/17              completed
2012/10/19  for v0.21   added srcfiles check, corr. history
2012/10/25  for v0.3    more than two keywords, lmodern
2012/11/06  for r0.3a   final demo with `fdatechk.tex', \AddQuotes 
                        for \qtd{\file{..., and other mod.s of 
                        doc. there; title extended
2012/11/11  for v0.4    v0.4 in abstract
2013/03/24  for v0.41   deeper sectioning level, \secref, 
                        \MDsamplecodeinput (+ `code'),
                        \subsubsections for "Basic Usage"
2013/03/25  for v0.41   \usepackage{filesdo}, \label{sec:demo-here}, 
                        mentioning `filesdo' there; 
                        folding and page breaks