diff options
Diffstat (limited to 'macros/latex/contrib/filedate/docsrc/filedate.tex')
-rw-r--r-- | macros/latex/contrib/filedate/docsrc/filedate.tex | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/macros/latex/contrib/filedate/docsrc/filedate.tex b/macros/latex/contrib/filedate/docsrc/filedate.tex new file mode 100644 index 0000000000..6be4950cbe --- /dev/null +++ b/macros/latex/contrib/filedate/docsrc/filedate.tex @@ -0,0 +1,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 |