\ProvidesFile{nicefilelist.tex}[2012/05/20 documenting nicefilelist.sty] \title{\pkg{\huge nicefilelist.sty }\\---\\\cs{listfiles} Alignment for Connoisseurs\thanks{This document describes version \textcolor{blue}{\UseVersionOf{\jobname.sty}} of \pkg{\jobname.sty} as of \UseDateOf{\jobname.sty}.}} % \listfiles { \RequirePackage{makedoc} \ProcessLineMessage{} \MakeJobDoc{19}%% 2012/03/21 {\SectionLevelTwoParseInput} } \documentclass[fleqn]{article}%% TODO paper dimensions!? \input{makedoc.cfg} %% shared formatting settings % \ReadPackageInfos{nicefilelist} \usepackage{nicefilelist} \sloppy \begin{document} \maketitle \begin{abstract}\noindent While \CtanPkgRef{longnamefilelist}{longnamefilelist.sty} improves \LaTeX's \cs{listfiles} with respect to long base filenames only, 'nicefilelist.sty' can keep separate columns for (i)~date (ii)~version, and (iii)~``caption" (don't write caption text in date column), their alignment not being disturbed by short filename extensions such as `.fd'. This is achieved basing on the \ctanpkgref{monofill} package. Thus 'nicefilelist' is more ``powerful" than 'longnamefilelist', the former however is an ``extension" of the latter neither with respect to implementation nor with respect to user interface. \end{abstract} \tableofcontents \section{Features and Usage} We are describing relations to, ahm, related packages---rather brief{}ly. The \ctanpkgref{latexfileinfo-pkgs} package provides a more general overview. %% <- 2012/05/18 \subsection{Relation to 'longnamefilelist.sty'} \CtanPkgRef{longnamefilelist}{longnamefilelist.sty} equips \cs{listfiles} with an optional argument for the maximum number of characters in the base filename. By contrast, 'nicefilelist' does not provide arguments for \cs{listfiles}, rather column widths for basename, extension, and version number are determined by \emph{templates} using \CtanPkgRef{monofill}{monofill.sty}. As a ``template" for doing this, see the initial settings in Sec.~\ref{sec:templates}. (Such settings must precede the \cs{listfiles command}) So 'nicefilelist''s \emph{user interface} (at present) does not \emph{extend} 'longnamefilelist''s user interface. Using 'monofill' is a very different approach than the one of 'longnamefilelist'. 'nicefilelist' is more powerful than 'longnamefilelist', but is not based on it in any way. It does not make sense to load both packages, they just overwrite each other's behaviour of \cs{listfiles}. 'longnamefilelist' may become ``obsolete" by the present package, unless one finds that its version of \cs{listfiles} looks fine enough and it is easier to understand and to use than 'nicefilelist'. \subsection{Installing} The file 'nicefilelist.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} \subsection{Calling} Below the `\documentclass' line(s) and above `\begin{document}', you load 'nicefilelist.sty' (as usually) by \[`\usepackage{nicefilelist}'\] Alternatively---e.g., for use with \ctanpkgref{myfilist} from the \ctanpkgref{fileinfo} bundle, see~Sec.~\ref{sec:myfilist}, or in order to include the `.cls' file in the list---you may load it by \[`\RequirePackage{nicefilelist}'\] before `\documentclass' or when you don't use `\documentclass'. As of v0.4, there is a package option `[r]' in order to place strings like \qtd{`r0.4'} in the column reserved for version numbers. You get this functionality by \[`\usepackage[r]{nicefilelist}'\] or \[`\RequirePackage[r]{nicefilelist}'\] See Section~\ref{sec:opt} for more information. \subsection{Usage and Sample with 'myfilist.sty'} \label{sec:myfilist} \subsubsection{Basically} In order to get a reduced and/or rearranged list of used files with the \ctanpkgref{myfilist} package, `nicefilelist.sty' must be loaded earlier than `myfilist.sty'. This is due to a kind of limitation of the latter, it \emph{issues} `\listfiles' (TODO). Therefore \cs{listfiles} must be modified earlier---or \emph{issued} earlier, in this case the \cs{listfiles} in `myfilist.sty' does nothing. The file `SrcFILEs.txt' accompanying the distribution of 'longnamefilelist', e.g., can be generated by running the following file `srcfiles.tex' with \LaTeX: \begin{quotation}\tt\small \expandafter\def\expandafter\{\expandafter{\string{} \expandafter\def\expandafter\}\expandafter{\string}} \obeyspaces\obeylines \cs{ProvidesFile}\{srcfiles.tex\}[2012/03/23 ~ file infos -\empty> SrcFILEs.txt] \cs{RequirePackage}\{nicefilelist\} \%\% INSERT MODIFICATIONS OF INITIAL \%\% \verb+`nicefilelist'/`monofill'+ SETTINGS HERE! \cs{RequirePackage}\{myfilist\} \%\% documentation: \cs{ReadFileInfos}\{nicefilelist\} \%\% demonstration: \cs{ReadFileInfos}\{provonly.fd,wrong.prv,empty.f\} \% \cs{ReadFileInfos}\{utopia.xyz\} \%\% present file: \cs{ReadFileInfos}\{nicefilelist\} \cs{ReadFileInfos}\{srcfiles\} \cs{ListInfos}[SrcFILEs.txt] \end{quotation} Note the lines where to place \strong{custom} modifications of settings for alignment (Sec.~\ref{sec:templates}) or failure displays (Sec.~\ref{sec:failure}). The previous code mentions the following files: \begin{description} \item[`provonly.fd'] has a proper `\ProvidesFile' line without date, for seeing what happens in the date and version columns. It also was a test for the case that there are fewer characters than a date has, and there is no blank space. \item[`wrong.prv'] has a `\ProvidesFile' line with wrong file name. \item[`empty.f'] just is an empty file. \item[`utopia.xyz'] is not present at all, you get an error when you remove the comment mark. \end{description} Moreover, my `.tex' files have dates, but not version numbers, so you see what happens then: \vskip\topsep \begin{small}\tt \obeyspaces\obeylines ~ *File List* nicefilelist.sty 2012/03/23 v0.1 \rlap{more file list alignment (UL)} ~ monofill.sty 2012/03/19 v0.1a monospace alignment (UL) ~ myfilist.sty 2011/01/30 v0.3a \rlap{\cs{listfiles} -- mine only (UL)} ~ readprov.sty 2010/11/27 v0.3 \rlap{file infos without loading (UL)} nicefilelist.tex 2012/03/23 -- \rlap{documenting nicefilelist.sty} ~ provonly.fd -- -- -- -- such ~ wrong.prv * NOT FOUND * ~ empty.f * NOT FOUND * ~ srcfiles.tex 2012/03/23 -- file infos -> SrcFILEs.txt ~ *********** ~ ~List made at 2012/03/23, 10:31 ~from script file srcfiles.tex \end{small} %% TODO update example!? %% \subsubsection{More Generally and Shorthand} \label{sec:short} In the above example, the 'myfilist' command `\EmptyFileList' is missing---it is not intended there. Usually however, it \emph{is} intended, i.e., the following sequence of lines is wanted: \begin{quotation}\tt\small \expandafter\def\expandafter\{\expandafter{\string{} \expandafter\def\expandafter\}\expandafter{\string}} \obeyspaces\obeylines \cs{RequirePackage}[r]\{nicefilefilelist\} \cs{MFfieldtemplate}\{f-base\}[] \cs{RequirePackage}\{myfilist\} \cs{EmptyFileList}[] \end{quotation} Here you also see usage of package option |[r]| for release numbers and the adjustment \[|\MFfieldtemplate{f-base}{}|\] according to Section~\ref{sec:templates}. While there are also field identifiers |f-ext| and |f-version|, it seems that only |f-base| varies between real-life applications. With v0.5, the last three code lines in the snippet above can be replaced by \[|\MaxBaseEmptyList{}[|]\] ---``optionally" without \qtd{`[]'}. This may save the user from worrying about usage with 'myfilist'. \section{Implementation} \subsection{Package File Header (Legalese)} \input{nicefilelist.doc} \pagebreak %% 2012/09/30 \section{Credits} \begin{enumerate} %% 2012/05/20 \item It was \textsc{Martin Muench} who pointed out the shortcomings of 'longnamefilelist' that the present package addresses---thanks! %% 2012/05/20: \item For \textsc{Alois Kabelschacht}---whose idea in TUGboat~\textbf{8}~\#2\footnote{\tugbartref{tb08-2/tb18kabel}{% ``&\expandafter\ vs. &\let\ and &\def\ in Conditionals and a Generalization of PLAIN's &\loop,"} TUGboat Vol.~8 (1987), No.~2, pp.~184f. (\urlhttpref{tug.org/TUGboat/tb08-2/tb18kabel.pdf})} is used for v0.3---cf.\ the \ctanpkgref{dowith} documentation. \end{enumerate} \section{Missing} \begin{enumerate} \item The package once might provide \ctanpkgref{keyval}-style optional arguments for \cs{listfiles} or even call \cs{listfiles} automatically with 'keyval' package options. %% 2012/05/18: \item Another idea from \textsc{Martin Muench}: wrapping inside caption column. Can \ctanpkgref{hardwrap} help? \end{enumerate} \end{document} VERSION HISTORY 2012/03/20 for v0.1 started 2012/03/22 trying something 2012/03/23 for v0.1a without "aligning the dots" etc. 2012/05/18 for v0.30 Legalize -> Legalese; add. TODO "wrapping"; ref. to `latexfileinfo-pkgs' 2012/05/20 for v0.31 mention Kabelschacht 2012/05/20 for v0.4 on new package option [r] 2012/09/30 for v0.5 \MaxBaseEmptyList, doc. \pagebreak