%%% \vspace{24} \begin{small} [\,\ancrefslist{{{intro}{intro}} {{table}{table}} {{single}{\cs{GetFileInfo}~etc.}} {{several}{\cs{listfiles}~etc.}}{{rcs}{rcs/svn}} {{thanks}{thanks}}}\,]\quad [\,\textit{\fileref{\htmljob}{reload}}\,] \end{small} \nextruleview{intro} \section{0\quad Introduction (with links to sections)} For \Wikienref{\LaTeX} source files, it is recommended to start them with \LaTeX\ command \begin{itemize} \item \cs{ProvidesClass}\code{ ~}\quad (for \file{.cls} files) \item \cs{ProvidesPackage}\quad (for \file{.sty} files) \item \cs{ProvidesFile}\code{ ~ }\quad (for all other files) \end{itemize} (after \cs{NeedsTeXFormat}). Their trailing optional argument can provide the most recent \begin{itemize} \item \wikienref{Revision control}{revision} \strong{date}\\ (expected as \emph{\endqtd{first word}} in trailing optional argument) \item the corresponding \strong{version} string\\ (expected as \emph{\endqtd{second word}} in trailing optional argument)\pardash and \item and a brief \strong{description} of the file ("caption")\\ (expected as anything \emph{else} in trailing optional argument). \end{itemize} Here we are listing and comparing \TeX\ packages available from \httpref{ctan.org}{\acro{CTAN}} that make use of this information.
The document especially describes five packages of my own, including interrelations and dependencies, and thus extends their documentations; see \ancref{table}{table below} for them. An \emph{asterisk}* near a package name indicates that the package is \emph{not mine}; so what I tell about it may be wrong or bad \dots\ (please let me know via \webdesignref{contact.html}{form}, or should I add something?) ...
We have the \emph{cases} of %% single vs. several \begin{enumerate} \item displaying \ancref{single}{single} file info (\strongcs{GetFileInfo} ...) \item listing infos of \ancref{several}{several} files (\strongcs{listfiles} etc.) \end{enumerate} and for each %% LaTeX vs. external \begin{enumerate-a} \item access by \emph{\LaTeX} (\ancref{sing-ltx}{1\,}\cdot\ancref{sev-ltx}{\,2}) \item access by \emph{external} program (\ancref{sing-ext}{1\,}\cdot\ancref{sev-ext}{\,2}). \end{enumerate-a} \emph{Related} subjects are using \begin{enumerate-i} \item \ancref{rcs}{revision control systems} and \item modification time according to \ancref{filemod}{pdf\TeX}. \end{enumerate-i} \lineanc{table}A \emph{tabular overview} of the first two case distinctions:
\begin{stdallrulestable} \endcell just using \emph{\LaTeX}\qquad \endcell using \emph{external} program \endline \textbf{\ancref{single}{single} file}\endcell \fakeitem \ancref{doc}{\pkg{doc}}* ~ ~ ~ ~ ~ ~\,\,\, (Frank \ctanpkgauref{mittelbach}{Mittelbach})\\ \fakeitem \ancref{zwgetfdate}{\pkg{zwgetfdate}}*\,\,\,\,\,\,\,\, (Zden\unicodehexentity{011b}k \ctanpkgauref{wagner}{Wagner})\\ \fakeitem \ancref{readprov}{\pkg{readprov}} \endcell \fakeitem \ancref{lfv} {\pkg{latexfileversion}}* \,(Harald \ctanpkgauref{harders}{Harders}) \\ \fakeitem \ancref{lfi} {\pkg{ltxfileinfo}}*~ ~ ~ ~ \,\,\,\,\,\,\,\,\, \,(Wybo \ctanpkgauref{dekker}{Dekker}) \\ \fakeitem \ancref{tofi}{\pkg{typeoutfileinfo}} \endline \textbf{file \ancref{several}{list}}\endcell \fakeitem \ancref{cl} {\pkg{classlist}}*~~~~~~~\,\,\,\, (Heiko \ctanpkgauref{oberdiek}{Oberdiek}) \\ \fakeitem \ancref{dl} {\pkg{dateiliste}}*~~~~~ ~\, \,(Paul \ctanpkgauref{ebermann}{Ebermann}) \\ \fakeitem \ancref{lnfl}{\pkg{longnamefilelist}} \\ \fakeitem \ancref{nfl} {\pkg{nicefilelist}} \\ \fakeitem \ancref{mfl} {\pkg{myfilist}} \\ \endcell \fakeitem[\ancref{ltxinput}{\pkg{ltxinput}}* ~ ~ ~ ~ ~ ~ ~ ~ \,\,\,\,\,\, (Jim \ctanpkgauref{green}{Green})] \\ \fakeitem[\ancref{tle}{\pkg{texlog-extract}}* ~ \,\,\, (Wybo \ctanpkgauref{dekker}{Dekker})] \\ \\ [\,don't really belong here \dots\,] \\ \\ \end{stdallrulestable} \nextruleview{single} \section{1\quad Access Single File Info} %% v0.11: distributing intro words over first two subsections % \internallinksbar{{{sing-ltx}{a}}{{sing-ext}{b}}{{filemod}{c}}} \begin{small} [\,\ancref{sing-ltx}{a:}\enspace \ancrefslist{{{doc}{\pkg{doc}}} {{readprov}{\pkg{readprov}}} {{zwgetfdate}{\pkg{zwgetfdate}}} }\,]\quad [\,\ancref{sing-ext}{b:}\enspace \ancrefslist{{{lfv}{\pkg{latexfileversion}}} {{lfi}{\pkg{ltxfileinfo}}} {{tofi}{\pkg{typeoutfileinfo}}}}\,]\quad [\,\ancref{filemod}{c:\enspace \pkg{filemod}}\,] \end{small} \subsection{\lineanc{sing-ltx}a.\quad Access in \emph{\LaTeX} Run} %% shortening 2012/04/05: \emdash originally for \emph{automatic} inclusion of \emph{current} revision date and version of a package %%% (? cf.~\ancref{sing-ext}{next subsection}) in \emph{typesetting} the latter's documentation (\textit{\endqtd{This document describes version \dots\ as of \dots}}), but then \dots \begin{description} \ditem{\lineanc{doc}\CPR{doc}*} \begin{itemize} \item Belongs to \LaTeX\ \CtanPkgRef{latex-base}{base} distribution. \item Provides \strong{\cs{GetFileInfo}}\code{\{\metavar{file}\}}; after using this, you have \cs{filedate}, \cs{fileversion}, \cs{fileinfo} of \metavar{file}. \item \metavar{file} must have been \emph{loaded} in the \LaTeX\ run. \item \cs{GetFileInfo} is \emph{fragile}. \end{itemize} \ditem{\lineanc{zwgetfdate}\CPR{zwgetfdate}*} \begin{itemize} \item Provides \strongcs{DateOfFile}\metaarg{file} and \strong{\cs{DateOfPackage}}\metaarg{file}. \item \metavar{file} must have been \emph{loaded}. \end{itemize} \ditem{\lineanc{readprov}\CPR{readprov}} \begin{itemize} \item %%% \pkg{readprov} further provides %%% \emph{robust}, expandable Provides \strongcs{UseDateOf}\metaarg{file} and \strongcs{UseVersionOf}\metaarg{file} \Endash \emph{robust} (expandable). %% add. 2012/05/29 \item %%% It steals % Steals \ancref{doc}{\pkg{doc}}'s \strongcs{GetFileInfo} so \pkg{doc} is not % needed, in case ... %% <- 2012/05/26 -> Provides \ancref{doc}{\pkg{doc}}'s \strongcs{GetFileInfo} (with modified definition; used internally) %% was "useed" 2012/05/29 \item Provides \begin{itemize} \item \strongcs{ReadFileInfos}\metaarg{files} \item \strongcs{ReadPackageInfos}\metaarg{files} \item \strongcs{ReadClassInfo}\metaarg{file} \end{itemize} as \emph{alternatives} to \cs{GetFileInfo}. \begin{itemize} %% 2012/04/05 \item They do \emph{not} really \emph{load} \metavar{file}/\metavar{files} ... \item ... so can be used with incompatible packages and classes (multiple latter by \cs{ReadFileInfos\{\metavar{base}.cls\}}). \item This allows \strong{adding arbitrary} \LaTeX\ source files to the list of files that \LaTeX\ manages for \ancref{latex}{\strong{\cs{listfiles}}}\pardash this is used for \ancref{myfilist}{\pkg{myfilist}}. \end{itemize} \end{itemize} \end{description} \subsection{\lineanc{sing-ext}b.\quad \emph{Screen} Display Using \emph{External} Program} \emdash when you wonder whether the most recent version of a package or a chapter file is present \dots \begin{description} \ditem{\lineanc{lfv}\CPR{latexfileversion}*} \begin{itemize} \item \Wikienref{Bash (Unix shell)} script. \item \emph{Nice} screen display. %% TODO sample 2012/05/05 \item Invokes \code{latex} run using a copy of \ancref{doc}{\pkg{doc}}'s \cs{GetFileInfo}. \end{itemize} \ditem{\lineanc{lfi}\CPR{ltxfileinfo}*} \begin{itemize} \item \Wikiendisambref{Ruby}{programming language} script. \item Displays nice \mirrorctanref{support/ltxfileinfo/doc/ltxfileinfo.html}{table} of infos (including \emph{location} in file system) on screen. \end{itemize} \ditem{\lineanc{tofi}\CPR{typeoutfileinfo}} \begin{itemize} \item 5-lines \Wikienref{Bash (Unix shell)} script. \item Expects \code{latex} won't append too many screen lines after 1-line \strongcs{typeout}\\ (\emph{tolerable} screen display as compared with \ancref{lfv}{latexfileversion}). \item Invokes \code{latex} run using \ancref{readprov}{\pkg{readprov}}. \end{itemize} \end{description} \subsection{\lineanc{filemod}c.\quad Related, while different ...} \begin{description} \ditem{\CPR{filemod}*} \begin{itemize} \item Uses \tugref{applications/pdftex/NEWS}{\pdfTeX}'s \cs{pdffilemoddate\{\metavar{file}\}} primitive. \item Compares modification dates of files. \item Files include images. \item Also works with \code{pdflatex} in \acro{DVI} mode. \end{itemize} \end{description} \nextruleview{several} \section{2\quad File Info List} This is about listing \emph{all} files input in a \LaTeX\ run, \emph{or}~... \subsection{\lineanc{sev-ltx}a.\quad Create in \LaTeX\ Run} \begin{small} [\,\ancrefslist{{{latex}{\pkg{LaTeX}}} {{cl}{\pkg{classlist}}} {{dl}{\pkg{dateiliste}}} {{lnfl}{\pkg{longnamefilelist}}} {{mfl}{\pkg{myfilist}}} {{nfl}{\pkg{nicefilelist}}}}\,] \end{small} \begin{description} \ditem{\lineanc{latex}\CPR{latex}*} \begin{itemize} \item \LaTeX\ provides \strong{\cs{listfiles}} for the document preamble. \item \cs{listfiles} issues a list of \strong{all} files input in the \code{latex} run near end of \file{.log} file, together with their infos according to \cs{Provide...} commands. \item The list is a \strong{two-column} "table" (plain text), \emph{base} filenames flush right, \emph{info} (maybe date, maybe version, maybe anything) flush left. \item Any file whose base \Wikienref{filename} has \strong{more than 8}~characters or whose filename extension does \emph{not} have 3~characters \strong{corrupts} alignment. \end{itemize} \ditem{\lineanc{cl}\CPR{classlist}*} \begin{itemize} \item Remembers (separately) files input by ~(a)~\strong{\cs{documentclass}}~ and what was input by ~(b)~\strong{\cs{LoadClass}}. \item On \strong{\cs{PrintClassList}}, the list of loaded class files appears on screen. \item Configurable by \strongcs{PrintClassListEntry} and \strongcs{PrintClassListTitle}. \end{itemize} \ditem{\lineanc{dl}\CPR{dateiliste}*} \begin{itemize} \item Lists anything that the \ancref{latex}{original} \cs{listfiles} would list. \item \strong{Typesets} the list as a \LaTeX\ table, using package \CPR{longtable}. \item Separate \strong{columns} for \begin{itemize} \item filename \item \emph{page} where input (optionally) %% \emph 2012/04/09 \item date \item version \item description ("caption") \end{itemize} \item Supports \strong{\acro{RCS}}, \wikienref{Concurrent Versions System}{\acro{CVS}}, and \acro{SVN} (cf.~\ancref{rcs}{section below}). \item Highly configurable. \item E.g., you can replace info for a file by what you want to see in the list (cf.~\ancref{myfilist}{\pkg{myfilist}}). \item I haven't seen what happens with \emph{plain text} (\file{.log}) output. \end{itemize} \ditem{\lineanc{lnfl}\CPR{longnamefilelist}} \begin{itemize} \item Overcomes \ancref{latex}{\LaTeX}'s "8-character~limit" by a new \strong{optional argument} for \cs{listfiles}, indicating number of characters to be reserved for base filenames, e.g. accounting for "\code{longnamefilelist.sty}": \begin{quote} \cs{listfiles[16]} \end{quote} \pardash view \mirrorctanref{macros/latex/contrib/longnamefilelist/% SrcFILEs.txt}{example outcome} \item \emdash showing combination with \ancref{mfl}{\pkg{myfilist}} \item \emdash while also working as single addition to \LaTeX~\CtanPkgRef{latex-base}{base}, \emph{no} need of \ancref{mfl}{\pkg{myfilist}} or \CPR{monofill}. \item Still, filename \strong{extension}s with number of characters differing from 3 break alignment. Martin Mnch mentions \file{t1cmtt.fd} (standard \LaTeX\ font definition) and \file{supp-pdf.mkii} (\Wikienref{ConTeXt}). \end{itemize} \ditem{\lineanc{nfl}\CPR{nicefilelist}} \begin{itemize} \item Uses separate \strong{columns} for \strong{date} and \strong{time} (like \ancref{dl}{\pkg{dateiliste}}). \item (Picky) recognition of "date" and "version"\pardash if not present, left \strong{empty} or gets "missing" display: \begin{codelines} nicefilelist.sty~ 2012/03/29~ v0.2 ~ more file list alignment (UL)\/ nicefilelist.tex~ 2012/03/23~ ~--~ ~ documenting nicefilelist.sty \end{codelines} (Martin Mnch's idea). \item Problem of varying filename \strong{extension} lengths overcome by actually keeping a separate flush-left column for them. \item Column widths configurable by \strong{templates}\pardash replace pre-configuration (\CPR{monofill} commands): \begin{codelines} \EXECUTE{\MFfieldtemplate[~]{nfl}{% /MFfieldtemplate(f-base)...(nicefilelist)..}} \MFleftinfield{% \\MFfieldtemplate\{f-base\}~~~\{nicefilelist\}}{nfl}\%\%\ base name \/ \MFleftinfield{% \\MFfieldtemplate\{f-ext\}~~~~\{tex\}}{nfl}\%\%\ name extension \/ \MFleftinfield{% \\MFfieldtemplate\{f-version\}\{v0.11a\}}{nfl}\%\%\ version \end{codelines} \item First code line above shows \strong{difference} to \CPR{longnamefilelist}, equivalent there would be \cs{listfiles[12]}. \pkg{nicefilelist} does \emph{not} provide an optional argument for \cs{listfiles}. \item Column \strong{distances} and "\strong{missing}" display configurable too. \item Can be combined with \ancref{mfl}{\pkg{myfilist}}\pardash view \mirrorctanref{macros/latex/contrib/nicefilelist/% doc/% %% 2012/05/26 SrcFILEs.txt}{output sample}. \item Needs just \CPR{monofill}, additionally to \LaTeX~\CtanPkgRef{latex-base}{base}. %% 2012/05/27: \item \pkg{nicefilelist} v0.4 provides an option \code{[r]} to allow "release numbers" in the column reserved for versions: \begin{codelines} nicefilelist.sty~ 2012/05/20~ v0.4 ~ more file list alignment (UL)\/ nicefilelist.tex~ 2012/05/20~ ~--~ ~ documenting nicefilelist.sty\/ nicefilelist.RLS~ 2012/05/20~ r0.4 ~ v0.4 Kabelschacht + [r] \end{codelines} \file{.RLS} files are an idea to provide/access a release summary. \end{itemize} \ditem{\lineanc{mfl}\lineanc{myfilist}\CPR{myfilist}} \begin{itemize} \item Allows \strong{removing} all entries that \LaTeX\ has collected for \ancref{latex}{\cs{listfiles}} at a certain point (\strong{\cs{EmptyFileList}}). %% 2012/05/26 \item Then, by commands from \ancref{readprov}{\pkg{readprov}}, you can \strong{add arbitrary} files to the list (as they are \emph{not} really \emph{loaded}), in the order you want to have them in the list. %% 2012/05/29: (However, for many combinations of package files, you could actually \emph{load} them, without \pkg{readprov}.) \item Thus actually, you can set up a list of files you want to have \emph{independently} of a typesetting run ... \item ... and actually, the \strong{intended} application is generating the list \strong{without} any \strong{typesetting}, by running \code{latex} on a "\strong{script}" file just loading \pkg{readprov} and \pkg{myfilist} and using only commands from \emph{them}. (No \cs{documentclass}, no \code{\{document\}} environment.) \item View \mirrorctanref{macros/latex/contrib/longnamefilelist/docsrc/% srcfiles.tex}{input example} for \ancref{lnfl}{\pkg{longnamefilelist}}. \item Besides \file{.log} output, the list can be written into a \strong{separate} plain text \strong{file%%% } ... % \item ... view }\pardash view \mirrorctanref{macros/latex/contrib/longnamefilelist/% SrcFILEs.txt}{output example} for \ancref{lnfl}{\pkg{longnamefilelist}}. \item \strong{Main applications} in my mind and actual work: \begin{enumerate} \item List of \file{.sty} and \file{.tex} files for \emph{my} \strong{\acro{CTAN} packages} and \strong{bundles} (instead of the \file{.dtx}/\CPR{docstrip} system, I use \CPR{nicetext}). \item List of \strong{package} files specific to some \strong{project} that often change\pardash manual replacement for a "concurrent versions" system with single author. E.g.: \begin{itemize} \item \CPR{nicetext} packages underlying \strong{documentation} of a certain different package. \item \strong{style} files underlying a \strong{book} project at which authors and programmers work on changing computers. \end{itemize} \item List of \strong{chapter} \cs{include} files for a \strong{book} project, edited at changing computers (by a number of authors). \item Often, one \strong{forgets} to \strong{update} version information in the \cs{Provides...} command\pardash the \pkg{myfilist} helps you to \pkg{check} this (e.g., right before a release; \ancref{filemod}{\pkg{filemod}} might automate this check, perhaps together with \ancref{readprov}{\pkg{readprov}}, \emph{without} \pkg{myfilist}). \end{enumerate} \item My actual \strong{workflow} with \Wikienref{Bash (Unix shell)}: \begin{itemize} \item \strong{\code{upsfl}} with \begin{codelines} alias upsfl='latex srcfiles'} \end{codelines} updates the list of source files, and actually displays the updated list on screen. \item \strong{\code{shsfl}} with \begin{codelines} \code{alias shsfl='more SrcFILEs.txt'} \end{codelines} displays the source file list without updating, and waits when the list is too long for your (netbook) screen. \end{itemize} \item Combinable with \ancref{dl}{\pkg{dateiliste}}? \end{itemize} \end{description} \subsection{\lineanc{sev-ext}b.\quad Create by External Program} Hm, not so related, \emph{no} infos (it seems), lists only; so, just \emph{"most related I could find"} for this section~... \begin{description} \ditem{\lineanc{ltxinput}\CPR{ltxinput}*} \begin{itemize} \item \wikienref{MS-DOS}{\acro{MS-DOS}} utility (compiled from \wikienref{C (programming language)}{\acro{C}}). \item Lists files that \emph{would} be input (recursively). \end{itemize} \ditem{\lineanc{tle}\CPR{texlog-extract}*} \begin{itemize} \item \Wikiendisambref{Ruby}{programming language} script. \item Lists files that issued errors and warnings (colored). \end{itemize} \end{description} \nextruleview{rcs} \section{\lineanc{rcs}3\quad \acro{RCS}/\acro{SVN}} For \wikienref{Revision control}{revision control systems} \wikienref{Revision control system}{\acro{RCS}} and \wikienref{Apache Subversion}{\acro{SVN}}, there are \begin{itemize} \item \CPR{rcs}* \cdot\ \CPR{rcsinfo}* \cdot\ \CPR{rcs-multi}* \item \CPR{svn}* \cdot\ \CPR{svninfo}* \cdot\ \CPR{svn-multi}* \item \CPR{svn-prov}* provides \acro{SVN} variants of \cs{ProvidesClass}, \cs{ProvidesFile}, and \cs{ProvidesPackage}. \end{itemize} \emdash sorry, I can't tell more about them right now~\dots %% 2012/04/08 \nextruleview{thanks} \section{Acknowledgements} Thanks to Martin Mnch, Moss (I wrote this for his question), %% 2012/04/06 and Rainer Sch”pf! \ancref{rcs}{\acro{RCS} stuff} mainly has been stolen from \bytopicref{revision}{Jrgen Fenn's Topic Index} of the \mirrorctanref{help/Catalogue}{\TeX~Catalogue}.
%%% \vspace{24} \hrule \small*~not~mine\endsmall \rightpar{\textit{% Last~revised~\isotoday\ \copyright~\webdesignref{contact.html}{Uwe Lck} \vspace{6} (using \CtanPkgRef{morehype}{blog.sty} and \CtanPkgRef{monofill}{monofill.sty}) \vspace{6} License: \httpref{www.latex-project.org/lppl/}{LPPL~1.3c} or later, author-maintained.}} \entotopofpage \vspace{550} \finish %% HISTORY: %% 2012/04/02 v0.1 first upload %% 2012/04/02 v0.11 little improvements afterwards, %% especially intro words for section 1 %% 2012/04/05 v0.12 less words in section 1; %% sub-itemize for readprov %% 2012/04/06 wrote for Moss %% 2012/04/08 started table, some other additions %% 2012/04/09 continued (fix of strange bug!?) %% %% 2012/05/05f. v0.2 renamed `latexfileinfo-pkgs', table %% reformatted manually, minor rewordings %% and reformattings, link fixes %% 2012/05/13 v0.2a modified \ProvidesFile for different %% generation method %% 2012/05/26 v0.21 corr. \GetFileInfo, %% nicefilelist sample link fixed %% 2012/05/27 nicefilelist's option [r] %% 2012/05/29 v0.22 remark `myfilist' without `readprov', %% typo fix, \UseDateOf ... robust