Debian Codegraph @

texmf-dist/source/latex/filedate/filedate.tex

raw
1 \ProvidesFile{filedate.tex}[2013/03/25 documenting filedate.sty]
2 %% 2012/06/24
3 \title{\pkgtitle{filedate.sty}{Access and Compare
4 \LaTeX~File~% %% 2012/11/06
5 Info
6 \\ %% 2012/11/06
7 and Modification Date}}
8 % \listfiles
9 { \RequirePackage{makedoc} \ProcessLineMessage{}
10 \MakeJobDoc{18}%% 2012/10/16
11 {\SectionLevelThreeParseInput} } %% Three 2013/03/24
12 \documentclass[fleqn]{article}%% TODO paper dimensions!?
13 \input{makedoc.cfg} %% shared formatting settings
14 \usepackage{filedate,readprov}
15 \MDkeywords{modification date, metadata, package documentation,
16 %% <- were these two 2012/10/25 ->
17 document versions, macro programming}
18 \usepackage{lmodern}
19 \usepackage{filesdo} %% TODO makedoc.cfg? 2013/03/25
20 \sloppy
21 \providecommand*{\LuaTeX}{Lua\TeX}
22 \providecommand*{\pdfTeX}{pdf\TeX}
23 \providecommand*{\XeLaTeX}{X\lower.5ex\hbox{E}\kern-.125em\LaTeX}
24 %% <- TODO some logo package
25 % \newcommand*{\qtdfile}{} %% 2012/11/06
26 \newcommand*{\secref}[1]{Section~\ref{sec:#1}} %% 2013/03/24
27 \begin{document}
28 \maketitle
29 \begin{MDabstract}
30 'filedate.sty' provides basic access to the date of a
31 \LaTeX\ source file according to its `\ProvidesFile',
32 `\ProvidesPackage', or `\ProvidesClass' entry---the ``info date"---,
33 as well as to its modification date according to `\pdffilemoddate'
34 if the latter is available. Moreover commands are provided
35 to compare the ``info date" with the modification date, with ``today"'s
36 date, or with another date---that a script accessing modification dates
37 such as \CtanPkgRef{adhocfilelist}{adhocfilelist.sh}
38 may insert---, and to choose the effect of comparisons
39 (error vs.\ ``notice," reference date characterization).
40 Thus updating the ``info date" (``\strong{date consistency}")
41 of a source file may be ensured by a test
42 during typesetting from it or by some (shell/\TeX) script.
43 v0.4 enables checking info dates automatically as soon as
44 a \LaTeX\ file is loaded while typesetting or in a
45 \ctanpkgref{myfilist} script.
46
47 \MDaddtoabstract{Related packages:} \ctanpkgref{filemod},
48 \ctanpkgref{getfiledate}, \ctanpkgref{zwgetfdate},
49 \ctanpkgref{fileinfo}
50 \end{MDabstract}
51 \tableofcontents
52
53 % \newpage
54 \section{Features and Usage}
55 \subsection{Basics of Usage} %% 2013/03/24
56 \subsubsection{The Most Interesting Command}
57 The package allows to check whether the file \strong{info}
58 date <date> according to `\Provides' near the top of a \LaTeX\
59 input file <file>---i.e.,
60 \[`\Provides...{<file>}[<date> ...]'\]
61 has been updated the same day when <file> actually was \strong{modified}
62 most recently. With \pdfTeX, this can be checked by
63 \[|\CheckDateOfPDFmod{<file>}|\]
64
65 \subsubsection{Installing and Calling}
66 The file 'filedate.sty' is provided ready, installation only requires
67 putting it somewhere where \TeX\ finds it
68 (which may need updating the filename data
69 base).\urlfoot{ukfaqref}{inst-wlcf} %% corr. 2011/02/08
70
71 %% extended 2011/01/14:
72 Below the `\documentclass' line(s) and above `\begin{document}',
73 you load 'filedate.sty' (as usually) by
74 \[|\usepackage{filedate}|\]
75 but in ``\TeX\ scripts" such as \hyperref[sec:wrong]{below},
76 \[|\RequirePackage{filedate}|\]
77 is better.
78
79 \subsubsection{Demonstration with a ``\TeX\ script" Example}
80 \label{sec:wrong}
81 The accompanying `wrong.tex' is an example of a ``\pkg{filedate} \TeX\ script"
82 demonstrating what may go wrong.
83 % \begin{quotation}\tt\small
84 % \expandafter\def\expandafter\{\expandafter{\string{}
85 % \expandafter\def\expandafter\}\expandafter{\string}}
86 % \obeyspaces\obeylines
87 % \cs{ProvidesFile}\{wrong.tex\}[2012/10/15 filedate.sty demo]
88 % \cs{RequirePackage}\{filedate\}
89 % \cs{CheckDateOfPDFmod}\{wrong\}
90 % \cs{CheckDateOfPDFmod}\{wrong.tex\}
91 % \cs{CheckDateOfToday}\{wrong.tex\}
92 % \cs{stop}
93 % \end{quotation}
94 \MDsamplecodeinput{wrong}
95 \ReadFileInfos{wrong}
96 You may run it (by the command line \qtd{\file{latex wrong}}) and experience:
97 \begin{enumerate}
98 % \AddQuotes
99 \item `wrong.tex''s ``info date" is \qtd{\file{\theinfodateof{wrong.tex}}},
100 but its modification date is at least one day later.
101 \item
102 `\CheckDateOfPDFmod{wrong}' demonstrates that in
103 \[|\CheckDateOfPDFmod{<file>}|\]
104 <file> must be the \Wikiref{filename} \emph{including extension.}
105 Otherwise the ``info date" may be (displayed as) ``unknown."
106 \item
107 |\CheckDateOfPDFmod{wrong.tex}| tests against `wrong.tex''s
108 modification date according to `\pdffilemoddate'---the present
109 package documentation uses \ctanpkgref{pdftex} indeed.
110 \item
111 |\CheckDateOfToday{wrong.tex}| tests against ``today"'s date,
112 which should be different from `2012/10/15'.
113 \item
114 The ``script" terminates on \LaTeX's |\stop| command,
115 without typesetting anything.
116 % (or that's what I expect and what has happened when I tried it).
117 \TeX\ is just used as a program, a command interpreter
118 (as with \ctanpkgref{docstrip}).
119 \end{enumerate}
120
121 % \subsection{The Single Commands}
122 % $\dots$ are described below near to their implementation.
123
124 \pagebreak[2] %% 2013/03/25
125
126 \section{Implementation and Single Commands}
127 \subsection{Package File Header (Legalese)}
128 \input{filedate.doc}
129
130 \pagebreak %% 2013/03/25
131 \section{Use with Present Package Documentation}
132 \label{sec:demo-here}
133 %% mod. 2012/11/06:
134 \noNiceVerb
135 \input{fdatechk.tex}
136 \useNiceVerb
137
138 \AddQuotes
139
140 Above this paragraph,
141 the documentation source `filedate.tex' issues
142 \[|\input{fdatechk.tex}|\]
143 in order to run the following \TeX~script `fdatechk.tex':
144 \MDsamplecodeinput{fdatechk}
145 (That is done \emph{above} the paragraph to avoid wrong spacing
146 within the paragraph from `filedate.tex'.)
147 This way we check whether the ``info dates" of the package file
148 `filedate.sty', of the documentation source and driver
149 `filedate.tex', and of some other related files
150 are the same as their modification dates
151 according to |\pdffilemoddate| (using \code{pdflatex}).
152 When I added the (original) check on 2012-10-17,
153 it indeed informed me that I had not updated
154 `filedate.tex's info date
155 (\code{2012/10/16},
156 generation of first version of the file from a template,
157 draft).---%%% 2013/03/25
158 |\EqualityMessages| confirms that the tests were run indeed.
159 %
160 |\DoWithBasesExts| is from the 'filesdo' package
161 (\ctanpkgdref{commado} bundle).
162
163 The \TeX~script `srcfiles.tex' that in the first instance
164 generates a release overview additionally inputs `fdatechk.tex'
165 (as of 2012-11-06) as well. This way the check is performed
166 even when I rerun the documentation without updating the file list,
167 as well the other way round.
168 %% rm. 2012/11/06:
169 % However, such checks rather
170 % approaching package management should better be based on modification
171 % \emph{times}. If this should be done by \TeX\
172 % (\CtanPkgRef{pdftex}{\pdfTeX}, \ctanpkgref{pdfcmds}),
173 % it should better be based on the \ctanpkgref{filemod} package.
174
175 \end{document}
176
177 VERSION HISTORY
178
179 2012/10/16 for v0.2 started %% was v0.1 2012/10/19
180 2012/10/17 completed
181 2012/10/19 for v0.21 added srcfiles check, corr. history
182 2012/10/25 for v0.3 more than two keywords, lmodern
183 2012/11/06 for r0.3a final demo with `fdatechk.tex', \AddQuotes
184 for \qtd{\file{..., and other mod.s of
185 doc. there; title extended
186 2012/11/11 for v0.4 v0.4 in abstract
187 2013/03/24 for v0.41 deeper sectioning level, \secref,
188 \MDsamplecodeinput (+ `code'),
189 \subsubsections for "Basic Usage"
190 2013/03/25 for v0.41 \usepackage{filesdo}, \label{sec:demo-here},
191 mentioning `filesdo' there;
192 folding and page breaks