summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/getfiledate/getfiledate-guide.tex
blob: d6a7ec6e6103cd64085165b748e29172d3189442 (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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
% This is file getfiledate-guide.tex, the documentation for the getfiledate      %
% package.                                                                       %
%                                                                                %
% (c) Ahmed Musa 2009                                                            %
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
\documentclass[a4paper,11pt,final]{article}
\usepackage[scaled=0.9]{helvet}
\usepackage{mathpazo}
\usepackage{getfiledate}
\usepackage[left=3.5cm,right=3.5cm,top=3.5cm,bottom=3.5cm]{geometry}
\usepackage{fancyvrb,shortvrb}
\usepackage{array,colortbl}
\usepackage{multicol}
\usepackage{parskip}
\usepackage{xspace}
\usepackage{fancyhdr}
\usepackage{lastpage}
\usepackage{ltablex}
\keepXColumns
\usepackage{hyperref}
\usepackage{doipubmed}
\new\let\TC\textcolor
\xglobal\definecolorset{rgb}{x}{0}{green1,0.00,0.59,0.00;%
  green2,0.84,0.84,0.00;blue1,0.50,0.00,1.00;magenta1,0.50,0.00,0.50;%
  magenta2,0.50,0.00,1.00}
\hypersetup{colorlinks=true,linkcolor=red,pdfpagemode=UseThumbs,
  implicit=true,breaklinks=true,citecolor=purple,pdfview=FitH,
  pdfstartview=FitH}
\CustomVerbatimEnvironment{gfdverbatim}{Verbatim}{numbers=left,
  numberblanklines=false,firstnumber=last,frame=single,
  rulecolor=\color{orange},framerule=2pt,
  framesep=2pt,fillcolor=\color{violet!55},formatcom=\color{xmagenta20},
  xrightmargin=0pc,commandchars=\|\(\),commentchar=\?}
\new\def\stya#1{\TC{xgreen10}{\texttt{#1}}}
\new\def\styb#1{\TC{teal}{\texttt{#1}}}
\new\def\cmda#1{\stya{\string#1}}
\new\def\cmdb#1{\styb{\string#1}}
\new\def\cmdc#1{\stya{#1\string\hsize}}
\newcommand*\email[1]{\href{mailto:#1}{#1}}
\def\ie{i.e.\xspace}
\newcounter{examplecnt}[section]
\new\def\gfdexample{%
  \refstepcounter{examplecnt}
  \endgraf\vspace*{.5\baselineskip}%
  \TC{purple}{\textbf{Example~\thesection.\theexamplecnt}}%
  \endgraf\nobreak
}
\date{\TC{purple}{\today}\vadjust{\kern2ex\hrule}}
\new\def\helv{\fontfamily{phv}\selectfont\color{xmagenta10}}
\def\eg{e.g.\xspace}
\def\ie{i.e.\xspace}
\def\etc{etc.\xspace}
\fancyhf{}
\fancyhfoffset[R,L]{\dimexpr\marginparsep+\marginparwidth}
\lhead{\helv The \texttt{\TC{blue}{getfiledate}} Package}
\rhead{\helv Page~\thepage~of~\pageref*{LastPage}}
\renew\def\headrule{\color{blue}\hrule height1pt width\headwidth\relax
  \vspace{2pt}\hrule height1pt width\headwidth\vspace{-2pt}}
\renew\def\footrule{\color{green}\hrule height1pt width\headwidth\relax
  \vspace{2pt}\hrule height1pt width\headwidth\vspace{2pt}}
\pagestyle{fancyplain}

\begin{document}
\MakeShortVerb{\+}
\title{{\bfseries The \TC{blue}{\texttt{getfiledate}} Package}\\[1ex]
Version 1.2}
\author{Ahmed Musa\\[.5ex]University of Central Lancashire\\
  Preston, United Kingdom\\[1ex]\email{a.musa@rocketmail.com}
}
\maketitle

\columnseprule=0.5pt\premulticols=2cm
\begin{multicols}{2}
  \small\tableofcontents\normalsize
\end{multicols}
\bigskip

\begin{center}
\fboxsep3pt\fboxrule2.5pt
\fcolorbox{red}{yellow}{\fcolorbox{xmagenta20}{gray!15}{%
\parbox{\dimexpr\hsize-4\fboxsep-4\fboxrule}{%
\hfil\fcolorbox{cyan}{white}{\hspace{1cm}\textbf{Summary}\hspace{1cm}}\hfill\\[.5ex]
The \stya{getfiledate} package fetches from the system the date of last modification or opening of a resident file. It is based on an idea by Heiko Oberdiek \citeurl{oberdiek@uni-freiburg.de} that appeared in February 2009 on the discussion/newsgroup website \url{comp.text.tex}, namely, using the \cmda{\pdffilemoddate} command of pdf\TeX. This package creates a user-friendly interface for obtaining and presenting the needed filedate in several formats.
}}}
\end{center}

\section{User interface}
The package may be loaded without options as in
\begin{gfdverbatim}
\usepackage{getfiledate}
\end{gfdverbatim}
or with options as in
\begin{gfdverbatim}
\usepackage[option=value]{getfiledate}
\end{gfdverbatim}
The options include the filename for which you want to print the date of last modification. The options and their default values are described in section~\ref{sec:PackageOptions}. It is advisable to first load the package by \cmda{\usepackage\{getfiledate\}} and then use the macro \cmda{\getfiledate} to dynamically determine and print the date of last modification of filenames. The \cmda{\getfiledate} macro sets the various options. The \cmdb{\documentclass} and \cmda{\usepackage\{getfiledate\}} options lists may, however, be used to set options that apply throughout the document.

\section{Package options\label{sec:PackageOptions}}
The package options are listed in Table~\ref{tab:Package-options} below.

\begingroup
\small
\rowcolors{3}{yellow!20}{gray!25}
\extrarowheight2pt
\begin{tabularx}{\linewidth}{m{3cm}m{3.5cm}X}
\caption{Package options\label{tab:Package-options}}\\
\rowcolor{green!55}
\bf Option & \bf Default & \bf Meaning\\
\endfirsthead
\multicolumn{3}{l}{\emph{Continued from last page}}\\
\bf Option & \bf Default & \bf Meaning\\
\endhead
\multicolumn{3}{r}{\emph{Continued on next page}}\\
\endfoot
\endlastfoot
+file+ & +getfiledate.sty+ & The file for which the date of last modification is required.\\
+prefix+ & The date of last modification of file & The prefix of filename.\\
+postfix+ & +was+ & The postfix of filename, not that of filedate. It has been necessary to provide  both prefix and postfix following user requests.\\
+width+ & +\hsize+ & The width of the parbox or boxedminipage containing the filedate.\\
+head+ & +0ex+ & The vertical separation between the paragraph before the filedate and the filedate itself. When this option is passed to package without value, its default becomes the +\baselineskip+.\\
+foot+ & +0ex+ & The vertical skip between the filedate's line and the paragraph after filedate. When this option is passed to package without value, its default becomes the +\baselineskip+.\\
+marker+ & +\empty+ & The mark before the filename, on the same line with the filedate.\\
+markercolor+ & +blue+ & The color of the marker.\\
+filenamecolor+ & +blue+ & The color of the filename.\\
+datecolor+ & +blue+ & The color of filedate.\\
+inlinespace+ & +1em+ & The horizontal separation between the marker and the filedate.\\
+separator+ & +\textbullet+ & The marker between the filedate and filetime.\\
+sepcolor+ & +black+ & The color of the separator.\\
+framecolor+ & +black+ & The color of the boxrule for the boxedminipage.\\
+framesep+ & +3pt+ & The +\fboxsep+ for the boxedminipage.\\
+framerule+ & +0.4pt+ & The +\fboxrule+ for the boxedminipage.\\
+align+ & +justified+ & Alignment of the boxedminipage (possible values are \stya{center}, \stya{left}, \stya{right} and \stya{justified}).\\
+putprefix+ & +true+ & The boolean switch for placing prefix and postfix before the filedate. If this option is not entered in the call to \cmda{\getfiledate}, or if it is entered as \stya{putprefix=true}, both prefix and postfix will be inserted. On the other hand, if the user sets \stya{putprefix=false}, then no prefix and postfix will be inserted (even if the user specifies prefix and postfix in the call to \cmda{\getfiledate}). This option has been necessitated by users who just want to get filedate without any prefix, postfix or filename.\\
+notime+ & +false+ & The boolean switch for turning the display of time on or off.\\
+boxed+ & +false+ & The boolean switch for enclosing the filedate in a box. If the user simply enters this option without value, it will be assumed to be +true+. If it doesn't appear in the options list, its value is +false+.
\end{tabularx}
\endgroup

\section{Examples}
\gfdexample

The simplest example is to use the \cmda{\getfiledate} macro in the following way:
\begin{gfdverbatim}
\getfiledate[putprefix]{dir/filename.ext}
\end{gfdverbatim}
for which the default values of the package options will be used. For the sample file \styb{misc-test1.tex}, the outcome of this will be:

\small
\getfiledate{misc-test1.tex}
\normalsize

\bigskip
The prefix and postfix can be turned off as follows:

\begin{gfdverbatim}
\getfiledate[putprefix=false]{dir/filename.ext}
\end{gfdverbatim}

which gives

\small
\getfiledate[putprefix=false]{misc-test1.tex}
\normalsize

\bigskip
If the user needs the prefix and postfix in subsequent calls to \cmda{\getfiledate}, he has to turn them on again---through \stya{putprefix} as follows. Once turned on, they remain in effect until switched off later.

The setting
\begin{gfdverbatim}
\getfiledate[putprefix,marker={$\star$}]{dir/filename.ext}
\end{gfdverbatim}

gives

\small
\getfiledate[putprefix,marker={$\star$}]{misc-test1.tex}
\normalsize

\bigskip
The ability to change both the prefix and postfix automatically provides a +babel+ (\ie, multilingual) support. For example, if I want the postfix to be \cmdb{\mrule}, I can simply enter

\begin{gfdverbatim}
\new\def\mrule{\rule[.2ex]{.5cm}{3pt}}
\getfiledate[putprefix,marker={$\star$},
  postfix=\mrule]{dir/filename.ext}
\end{gfdverbatim}

to get

\new\def\mrule{\rule[.2ex]{.5cm}{3pt}}
\small
\getfiledate[putprefix,marker={$\star$},postfix=\mrule]{misc-test1.tex}
\normalsize

\bigskip
You can use all package options to customize the format of the result. The following examples illustrate the most important issues in using this package.

\gfdexample
The example in this section was obtained with the following settings. There are values specified for \stya{head} and \stya{foot}.
\begin{gfdverbatim}
\getfiledate[putprefix,postfix,head=.1\baselineskip,
  foot=2\baselineskip,markercolor=magenta,
  filenamecolor=purple,datecolor=orange,
  inlinespace=.5em,marker=$\blacktriangleright$,separator
]{misc-test1.tex}
\end{gfdverbatim}

The outcome of this is
\small
\getfiledate[putprefix,postfix,
  head=.1\baselineskip,foot=2\baselineskip,
  markercolor=magenta,filenamecolor=purple,datecolor=orange,
  inlinespace=.5em,marker=$\blacktriangleright$,separator
]{misc-test1.tex}
\normalsize

If you don't need the \stya{marker}, you can simply enter \stya{marker} without value as follows

\begin{gfdverbatim}
\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,filenamecolor=xgreen10,
  prefix=The date of final changes to file,
  datecolor=orange,inlinespace=.5em,boxed=false,
  separator=$\spadesuit$,sepcolor=green,|color(red)marker|color(xmagenta20),align=center
]{misc-test1.tex}
\end{gfdverbatim}

to get

\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,
  prefix=The date of final changes to file,
  marker,filenamecolor=xgreen10,datecolor=orange,
  inlinespace=1em,align=center,boxed=false,
  separator=$\spadesuit$,sepcolor=green
]{misc-test1.tex}

If you simply remove \stya{marker} from the key-value list, the \stya{marker} will retain the last value you assigned to it rather than the default value (which is nil).

\gfdexample

Unlike the case of the \stya{marker}, if you don't need the \stya{separator}, you would have to enter \stya{separator=\{\}} or simply \stya{separator=} as follows

\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=\baselineskip,
  width=.6\hsize,filenamecolor=xgreen10,
  prefix=The date of final changes to file,
  datecolor=orange,inlinespace=.5em,boxed=false,
  |color(red)separator=,|color(xmagenta20)sepcolor=green,marker,align=center
]{misc-test1.tex}
\end{gfdverbatim}

to get

\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,
  prefix=The date of final changes to file,
  marker,filenamecolor=xgreen10,datecolor=orange,
  inlinespace=2em,align=center,boxed=false,
  separator=,sepcolor=green
]{misc-test1.tex}

The same trick can be applied to some other keys. If you simply remove the \stya{separator} from the key-value list, the \stya{separator} will retain the last value you assigned to it rather than the default value (which is \cmda{\textbullet}). If in the subsequent calls to \cmda{\getfiledate}, you need the \stya{separator}, you would have to specify it or (to use the default value) simply enter \stya{separator} without value.

\textbf{Notes}: The user should note the following:
\begin{itemize}
\item The inclusion of the \stya{width} (\cmdc{0.6}) in the above example. The \stya{width} will maintain this value until it is changed again, as in the following examples.

\item If you enter \stya{putprefix=false} and you want the outcome centered, you should remember to set the right \stya{width}. For example, the following will not be centered, simply because the value of \stya{width} is \cmdc{0.8}:

    \begin{gfdverbatim}
    \getfiledate[putprefix=false,align=center,
      width=0.8\hsize,separator]{dir/filename.ext}
    \end{gfdverbatim}

    which gives

    \getfiledate[putprefix=false,align=center,width=0.8\hsize,separator]{misc-test1.tex}

    Setting \cmdc{width=.3} gives the desired result:

    \getfiledate[putprefix=false,align=center,width=0.3\hsize,separator]{misc-test1.tex}

\item The assignment to keys can be localized by enclosing the \cmda{\getfiledate} command in a group (\eg, \cmdb{\bgroup} ... \cmdb{\egroup}).

\item The change of \stya{prefix} here. The default value of \stya{prefix} is \stya{The date of last modification of file}. The \stya{prefix} will maintain this value until it is changed in the next call (see the next example).
\item The ability to change the \stya{prefix} and \stya{postfix} provides a babel (\ie, multilingual) support, since the user can specify suitable values of these keys.

\item The use of the key-value \stya{align=center} above. The key \stya{align} can assume values of \stya{center}, \stya{left}, \stya{right}, and \stya{justified}. Any other value for \stya{align} will be rejected by the package.
\item Some of the package options (\eg, \stya{putprefix}, \stya{notime}) can be submitted globally via the options list of \cmdb{\documentclass}.
\end{itemize}

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=0ex,foot=\baselineskip,
  prefix,width=\hsize,markercolor=magenta,filenamecolor=red,
  datecolor=violet,inlinespace=.5em,marker=$\triangleright$,
  separator=$\clubsuit$,sepcolor=xbgreen1
]{misc-test2.tex}
\end{gfdverbatim}

The outcome is:
\getfiledate[head=0ex,
  foot=1ex,width=\hsize,prefix,
  markercolor=magenta,filenamecolor=red,datecolor=violet,
  inlinespace=.5em,marker=$\triangleright$,
  separator=$\clubsuit$,sepcolor=red!55!green!65
]{misc-test2.tex}
Here we simply passed the \stya{prefix} without value so that its default value was used.

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=\baselineskip,
  markercolor=red!65,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,marker={$\star$},
  separator=$\Diamond$,sepcolor=red
]{misc-test3.tex}
\end{gfdverbatim}

The outcome is:
\getfiledate[head=\baselineskip,
  foot=\baselineskip,markercolor=red!65,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,marker={$\star$},
  separator=$\Diamond$,sepcolor=red
]{misc-test3.tex}

\gfdexample

The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=2ex,
  filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  markercolor=cyan,separator=$\heartsuit$,sepcolor
]{misc-test4.tex}|color(black) % Use default sepcolor
\end{gfdverbatim}

The outcome is:
\getfiledate[head=\baselineskip,foot=2ex,
  markercolor=cyan,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  separator=$\heartsuit$,sepcolor
]{misc-test4.tex}

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=1ex,foot=1ex,
  markercolor=purple,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,
  marker={$\blacktriangleright$},separator={}
]{misc-test5.tex}|color(black) % The separator is nil here.
\end{gfdverbatim}

The outcome of this is:
\getfiledate[head=1ex,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  separator={}
]{misc-test5.tex}

\gfdexample
Instead of keeping \stya{head} and \stya{foot}, you may instead decide to frame your result, as follows:
\begin{gfdverbatim}
\getfiledate[head=.5\baselineskip,
  foot=.5\baselineskip,width=12.5cm,framesep=5pt,framerule=.4pt,
  align=center,markercolor=purple,filenamecolor=blue,
  datecolor=orange,marker={$\blacktriangleright$},
  separator=$\heartsuit$,boxed
]{misc-test5.tex}|color(black) % marker has no effect here.
\end{gfdverbatim}

The outcome is:
\getfiledate[head=.5\baselineskip,foot=.5\baselineskip,
  width=12.5cm,framesep=3pt,framerule=.4pt,align=center,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  marker={$\blacktriangleright$},separator=$\heartsuit$,
  boxed
]{misc-test5.tex}

The boolean option \stya{boxed} has the default value of \stya{true} when listed in the key-value list. If you set the key \stya{boxed(=true)} in one call to the \cmda{\getfiledate} macro, and you don't want the filedate to be boxed subsequently, you have to turn it off (\ie, enter \stya{boxed=false}) in the next call to \cmda{\getfiledate}. The choice \stya{boxed(=true)} automatically turns off \stya{marker} irrespective of whether or not you have submitted  a value to this key in \cmda{\getfiledate} macro. In the above example, the reader will notice that the setting \stya{marker=\string\blacktriangleright} has no effect on the outcome.

For the boxed filedates, you can set the options \stya{framesep} and \stya{framerule} (equivalents of \LaTeX's native \cmdb{\fboxsep} and \cmdb{\fboxrule}) as follows:
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,
  foot=1ex,marker={$\blacktriangleright$},markercolor=purple,
  filenamecolor=blue,width=.9\hsize,datecolor=orange,
  inlinespace=.5em,align=left,boxed,separator=$\blacklozenge$,
  |color(red)framesep=5pt,framerule=2pt|color(xmagenta20)
]{misc-test5.tex} |color(black) % marker has no effect here.
\end{gfdverbatim}

The outcome of this is:
\getfiledate[head=\baselineskip,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},width=.9\hsize,
  align=left,boxed,framesep=5pt,framerule=2pt,separator=$\blacklozenge$
]{misc-test5.tex}

The default values of \stya{framesep} and \stya{framerule} are 3pt and 0.4pt (\LaTeX's native values for \cmdb{\fboxsep} and \cmdb{\fboxrule}). The user should note that the keys \stya{framesep} and \stya{framerule} should, of course, be submitted without backslashes (\eg, \stya{framesep=5pt} and \stya{framerule=2pt}).

You can change the box frame color as in
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,
  foot=\baselineskip,markercolor=purple,filenamecolor=blue,
  datecolor=orange,width=8cm,align=right,boxed,framesep=5pt,
  framerule=2pt,separator=$\Diamond$,|color(red)framecolor=green|color(xmagenta20)
]{misc-test5.tex}
\end{gfdverbatim}

The outcome of this is:
\getfiledate[head=\baselineskip,foot=\baselineskip,
  markercolor=purple,filenamecolor=blue,datecolor=orange,width=8cm,
  inlinespace=.5em,marker={$\blacktriangleright$},align=right,
  boxed,framesep=5pt,framerule=2pt,separator=$\Diamond$,
  framecolor=green
]{misc-test5.tex}

This frame color will remain in force until it is changed again. The default value of \stya{framecolor} is \stya{black}.

\gfdexample

The display of time can be avoided by using the switch \stya{notime}, as follows.
\begin{gfdverbatim}
\getfiledate[notime,head=\baselineskip,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},width=.8\hsize,
  align=center,boxed,framecolor=olive!25
]{misc-test5.tex}
\end{gfdverbatim}

The outcome of this is:
\getfiledate[notime,head=\baselineskip,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},width=.8\hsize,
  align=center,boxed,framecolor=olive!25
]{misc-test5.tex}

Notice here that the immediate past values of \stya{framerule} and \stya{framesep} are still in effective.

\section{Postamble}
The record of filedates can be logged in a file (say, \cmdb{\jobname.fds}), but I haven't encountered a real need for it.

\end{document}