diff options
Diffstat (limited to 'macros/latex/contrib/getfiledate/getfiledate-guide.tex')
-rw-r--r-- | macros/latex/contrib/getfiledate/getfiledate-guide.tex | 447 |
1 files changed, 447 insertions, 0 deletions
diff --git a/macros/latex/contrib/getfiledate/getfiledate-guide.tex b/macros/latex/contrib/getfiledate/getfiledate-guide.tex new file mode 100644 index 0000000000..d6a7ec6e61 --- /dev/null +++ b/macros/latex/contrib/getfiledate/getfiledate-guide.tex @@ -0,0 +1,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}
\ No newline at end of file |