\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