summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/filedate/docsrc/filedate.tex
blob: 6be4950cbe99ee15ea0205e394eb3276e80689c4 (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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
\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