summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/filedate/filedate.tex
blob: 2e1a2383ec5058685bd2bb8de23afb8c7514089e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
\ProvidesFile{filedate.tex}[2012/10/25 documenting filedate.sty]
%% 2012/06/24
\title{\pkgtitle{filedate.sty}{Access and Compare Info and Modification Date}} 
% \listfiles
{ \RequirePackage{makedoc} \ProcessLineMessage{}
  \MakeJobDoc{18}%% 2012/10/16
  {\SectionLevelTwoParseInput}  }
\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}
\sloppy 
\newcommand*{\TODO}[1][]{%
    \textcolor{blue}{TODO\ifx$#1$\else\space#1\fi}}
\providecommand*{\LuaTeX}{Lua\TeX}
\providecommand*{\pdfTeX}{pdf\TeX}
\providecommand*{\XeLaTeX}{X\lower.5ex\hbox{E}\kern-.125em\LaTeX}
%% <- TODO some logo package
\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.

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

%   \newpage
\section{Features and Usage}

\subsection{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.

\subsection{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}
\vskip \bigskipamount
\hrule
\verbatiminput{wrong}
\hrule
\vskip \bigskipamount
\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

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

\section{Use with Present Package Documentation}
At this place, the documentation source \qtd{\file{filedate.tex}}
issues 
\begin{verbatim}
    \EqualityMessages
    \CheckDateOfPDFmod{filedate.sty}
    \CheckDateOfPDFmod{filedate.tex}
    \ReadFileInfos{srcfiles}
    \CheckDateOfPDFmod{srcfiles.tex}
\end{verbatim}
    \EqualityMessages
    \CheckDateOfPDFmod{filedate.sty}
    \CheckDateOfPDFmod{filedate.tex}
    \ReadFileInfos{srcfiles}
    \CheckDateOfPDFmod{srcfiles.tex}
in order to check whether the ``info dates" of the package file 
\qtd{\file{filedate.sty}} and of the documentation source and driver 
\qtd{\file{filedate.tex}} are the same as their modification dates 
according to |\pdffilemoddate| (using \code{pdflatex}).
When I added this on 2012-10-17, it indeed informed me that I had not updated 
\file{filedate.tex}'s info date 
(\code{2012/10/16}, 
 generation of first version of the file from a template, draft). 

|\EqualityMessages| confirms that the tests were run indeed. 

Check for \qtd{\file{srcfiles.tex}}, the \TeX\ script generating a 
release overview, has been added 2012-10-19. 
That script performs the checks as well, 
but I might not run it the same day. 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