%%% \vspace{24} \begin{small} [\,\ancrefslist{{{abstract}{abstract}} {{over}{overview}} {{required}{requirements}} {{install}{installing}} {{related}{related}} {{back}{background}} {{custom}{customize}} {{idea}{idea/thanks}}}\,]\quad [\,\textit{\fileref{\htmljob}{reload}}\,] \end{small} \labelsection{abstract}{Abstract} \file{adhocfilelist.sh} is a shell script with command line options and parameters that displays \metavar{info} for files \metavar{file} on screen that (i)~are indicated on the command line and (ii)~contain \cs{ProvidesFile}\metamandarg{file}\metaoptarg{info}, \cs{ProvidesPackage}\metamandarg{file}\metaoptarg{info}, or \cs{ProvidesClass}\metamandarg{file}\metaoptarg{info}. There is one line for each file, formatted about as with \LaTeX's \cs{listfiles}. This formatting can be varied, and the output may additionally be saved in a plain text file. The files \metavar{file} are either (a)~listed explicitly, separated by commas, or (b)~they are gathered by the Unix \Find\ utility. For the latter, \pkg{adhocfilelist} provides a somewhat simplified interface, especially for restricting the list of files to those that have been modified "today" or a few days ago. So you/I can check whether version info was updated correctly, and it may allow \ctanpkgref{filedate} \dqtd{consistency checks} even with \CtanPkgRef{xetex}{\XeTeX} (where \cs{pdffilemoddate} is unavailable).
The package may thus be considered an extension of the
\ctanpkgref{latexfileversion} (Harald \ctanpkgauref{harders}{Harders})
and \ctanpkgref{typeoutfileinfo} packages
that display \metavar{info} for a \emph{single} file \metavar{file}.
Moreover, it is a somewhat simplified interface to the packages
\ctanpkgref{myfilist}, \ctanpkgref{longnamefilelist},
\ctanpkgref{nicefilelist}, and \ctanpkgref{filedate}.
\labelsection{over}{Overview of command line contents}
The general structure of a command line using \pkg{adhocfilelist} is
\begin{quote}
\ancref{call}{\metavar{call}}
\ancref{opts}{\metavar{options}}
\ancref{files}{\metavar{files}}
\end{quote}
The three parts are as follows:
\begin{description}
\ditem{\metavar{call}\lineanc{call}}
This is either
\begin{itemize} %% 2012/10/17
\item \metavar{path}\file{adhocfilelist.sh}
where \metavar{path} is "./" or something,
depending on where you place the file \file{adhocfilelist.sh},
or on your use of \Wikienref{symbolic link}s,
the environment variable \code{\Wikiendisambref{PATH}{variable}},
or
\item an \code{\Wikiendisambref{alias}{command}} for
\metavar{path}\file{adhocfilelist.sh}. %% was
\TODO: The restriction to \find\ (v0.7) is temporary, removing it is
straightforward, but I may have to postpone this for a while.
\optitem{f} \fmode\
Add \metavar{files} to other \strong{\find} criteria,
\strong{replacing} internal default settings
(as opposed to \code{-g}).
For allowing certain file name extensions such as \ext{tex},
the star must be escaped and \metavar{files} best
has outer single quotes, such as
\begin{quote}
\EXECUTE{\MakeOther\'}
\code{'-L ( -name \cs{*}.tex -o -name \cs{*}.sty )'}
%% <- follow -> L 2012/11/19
\end{quote}
\optmetaitem{F}{find-file} \fmode\
Add content of the \strong{file} \metavar{find-file} to other \strong{\find} criteria.
As compared with \code{-f}, stars must be escaped,
while other quoting seems not to be needed in \metavar{files}.
\optitem{g} \fmode\
Add \metavar{files} to other \strong{\find} criteria,
among which some hopefully "\strong{generally useful}"
are added from within \file{adhocfilelist.sh}.
As to quoting/escaping in \metavar{files},
this is as with \code{-f}.
\optitem{h}
Display an overview (brief version of present one, "\strong{help}"),
and ignore everything else of the command line.
\optmetaitem{i}{tex-file}
Prepend ("\strong{input}") contents of the file \metavar{tex-file}
to the temporary \ext{tex} file that \file{adhocfilelist.sh}
generates internally\pardash to get more individual settings
than \file{adhocfilelist.sh}'s internal defaults
(which are \strong{replaced} by the content of \metavar{tex-file})
and than the options \code{-l} and \code{-n} provide.
\optmetaitem{l}{integer}
Format list by the \strong{\ctanpkgref{longnamefilelist}} package
where \metavar{integer} is the maximum length of base
\Wikienref{filename}s in the list (about as ...)
\optmetaitem{n}{filename}
Format list by the \strong{\ctanpkgref{nicefilelist}} package
where \metavar{filename} is the longest base \Wikienref{filename} (or a template).
%% 2012/10/15:
If base filenames do \emph{not} have more than eight characters,
you can use "\strongcode{-n~.}" as a shorthand for
"\optmeta{n}{filename}" with a \metavar{filename} of eight characters.
\optmetaitem{o}{txt-file}
Save the displayed file info list ("\strong{output}")
as plain text file \metavar{txt-file} also.
\optitem{x}
Use \code{xelatex} rather than \code{latex} (v0.7).\enpardash The
idea for this has been that the script should provide
"date consistency" checks (\strong{option~\code{-c}})
\endqtd{even with \CtanPkgRef{xetex}{\XeTeX} where \cs{pdffilemoddate}
is not available.} However, the script has used \code{latex}
before v0.7 which will run \CtanPkgRef{pdftex}{\pdfTeX} usually,
even when the user prefers \emph{typesetting} with \XeTeX,
and anyway it does not rely on \cs{pdffilemoddate}.
The real problem with \ctanpkgref{filedate} and \XeTeX\ is that
a reliable consistency check does not work
\emph{while typesetting with \XeTeX}. But \pkg{filedate} can be
used for "\TeX\ scripts" too, i.e., \emph{without} typesetting,
and that is what the present package does.
The present package does \emph{not} provide consistency checks
\emph{while typesetting with \XeTeX}.
It should not be make a difference whether the "\TeX\ script"
that \pkg{adhocfilelist} generates is run with \XeTeX\ or with \pdfTeX.
So the only "special \XeTeX\ support" from here probably
will be the present \strongcode{-x} in case \code{latex}
\emph{does not work}, maybe because \pdfTeX\ or anything implementing
the \code{latex} command is missing on the user's (unusual) installation.
\end{description}
Options can \emph{not} be "contracted" like "\code{-0f}"
(too difficult with processing [parts of] \find\
expressions\pardash\code{-name} ...).
\ditem{\metavar{files}\lineanc{files}}
Whenever an option "switches into \Find\ mode",
\metavar{files} is interpreted as part of a command line for the
\find\ utility. Otherwise, \metavar{files} is expected to be a
comma-separated list of filenames (for \LaTeX\ source files),
whose extension \ext{tex} (if so) may be omitted\pardash unless \code{-h}~...
\end{description}
\labelsection{required}{Requirements}
\begin{description}
\ditem{System}
The package will work on a \Wikienref{Unix-like} system only,
but I am not expert enough to judge what additional restrictions hold.
As I could not make work everything that should work according to
documentation, I expect the other way round that what works on
my installation may not work at other Unix-like installations.
If something doesn't work at your installation, please tell me via
\urlref{contact-ednotes.sty.de.vu}.
Actually the package was developed with the \Wikienref{GNU bash}
shell and the
\wikienref{GNU Find Utilities}{\acro{GNU} \find\ utility} on
\Wikiendisambref{Ubuntu}{operating system}~10.04.
My impression is in fact
(looking at \Wikienref{The Open Group}'s
\httpref{pubs.opengroup.org/onlinepubs/9699919799/utilities/find.html}{man page}
for \find)
that in order to use the \strong{\find} options
\strongcode{-0}, \strongcode{-a}, \strongcode{-f}, \strongcode{-F},
and \strongcode{-g}, the \strong{\acro{GNU}} version of \find\ is required,
because action \strong{-printf} is used and essential (difficult without).
\ditem{\LaTeX}
The package requires that the \ctanpkgref{fileinfo} bundle is installed.
In order to use the \strong{\code{-l}} option,
\ctanpkgref{longnamefilelist} must be installed additionally.
In order to use the \strong{\code{-n}} option,
\ctanpkgref{nicefilelist} must be installed additionally.
In order to use the \strong{\code{-c}} option,
\ctanpkgref{filedate} must be installed additionally.
\end{description}
\labelsection{install}{Installing}
No more advice than implied by the section on "\ancref{call}{\metavar{call}}"
can be given right now.
\labelsection{related}{Related packages}
The file
\mirrorctanref{info/latexfileinfo-pkgs/latexfileinfo_pkgs.htm}{%
\file{latexfileinfo_pkgs.htm}}
describes related packages available on
% \httpref{tug.ctan.org}{\acro{CTAN}}
\acro{\Wikiref{CTAN}}
in some detail.
The most obvious ones have been mentioned above already.
% It might be added that Martin \ctanpkgref{scharrer}{Scharrer}'s
% \ctanpkgref{filemod} probably could be used as an alternative to
% \code{\Wikiref{find}} in the future\pardash I have not studied
% it sufficiently yet (and may not be able soon).
The \ancref{back}{next section} indicates details that may be
improve understanding the \LaTeX-related command line options
\code{-i}, \code{-l}, and \code{-n}.
\labelsection{back}{Background}
For understanding the options \strongcode{-0}, \strongcode{-a},
\strongcode{-f}, \strongcode{-F}, and \strongcode{-g},
knowing something about the \Find\ utility %% was The 2012/10/17
and the present \ancref{back-find}{interface} to it may be helpful.
The options \strongcode{-i}, \strongcode{-l}, \strongcode{-n},
and \strongcode{-o} refer to the \ctanpkgref{myfilist} package
and its enhancements by the packages \ctanpkgref{longnamefilelist}
and \ctanpkgref{nicefilelist}, and it may be helpful to know
what a "\ancref{my-script}{\pkg{myfilist} script}" is.
\begin{description}
\ditem{\find\lineanc{back-find}}
We are describing the \strong{interface} to \Find.
To learn about the contents of a \find\ command line,
the \wikienref{find}{Wikipedia article} may be a good start,
next enter "\code{man find}" in the terminal, finally see the
\httpref{gnu.org/software/findutils/manual/find.html}{\acro{GNU} manual}.
\file{adhocfilelist.sh} forms the following \find\ command line
in order to get a comma-separated list of files:
\begin{quote}
\code{find}
\ancref{back-f-prefix}{\metacode{prefix}}
\ancref{back-f-files} {\metacode{files}}
\ancref{back-f-day} {\metacode{day}}
\code{-printf ,\%f}
\end{quote}
These parts are as follows:
\begin{description}
\ditem{\metavar{prefix}\lineanc{back-f-prefix}}
is
\begin{quote}
\code{-L -maxdepth 1 ( -name \cs{*}.tex -o }\metacode{more}\code{ )}
%% <- follow -> L 2012/11/19
\end{quote}
where \metavar{more} in addition to files with extension \ext{tex} allows
those with extensions \ext{sty}, \ext{cfg}, \ext{cls}, \ext{dtx},
\ext{def}, and \ext{fd}\pardash \strong{unless} with \strong{options}
\begin{description}
\optitem{f}
where \metavar{prefix} is empty
\optmetaitem{F}{find-file}
where \metavar{prefix} is the content of the file \metavar{find-file}.
\end{description}
Option \strongcode{-g} is not required with options
\strongcode{-0} and \strong{-a} that switch into "\strong{\find\ mode}"
too without deleting \metavar{prefix}, it is just a way to switch
into \find\ mode otherwise without deleting \metavar{prefix}.
\ditem{\metavar{files}\lineanc{back-f-files}}
is as in the \ancref{files}{overview}.
\ditem{\metavar{day}\lineanc{back-f-day}}
is empty, unless \strongcode{-0} sets it to
\begin{quote}
\code{-daystart~-mtime 0}
\end{quote}
or \strongmetaopt{a}{integer} sets it to
\begin{quote}
\code{-daystart~-mtime~}\metacode{integer}
\end{quote}
It follows that
\begin{itemize}
\item \strongcode{-0} has the same effect as
(is just a shorthand for) \strongcode{-a~0}
\item if \metavar{integer} is "\code{-\metavar{digits}}",
files modified \emph{since} \metavar{digits} days ago
are allowed
\end{itemize}
\emdash cf.~\acro{GNU} documentation on
\httpref{gnu.org/software/findutils/manual/html_node/%
find_html/Age-Ranges.html}{age ranges.}
A \strong{tricky} little thing here is that \metavar{day}
may be \emph{expected} to be a \emph{restriction},
an \emph{additional} criterion that a \LaTeX\ source file
must meet to be listed. However, if \metavar{files} ends on
\strongcode{-o} for "or", \metavar{day} becomes an
"additional possibility" for being listed ...
\TODO: This is different with \strong{option \code{-c}}
(v0.7) whose functionality also may change soon.
\end{description}
\ditem{\pkg{myfilist}\lineanc{my-script}}
The \LaTeX\ package \ctanpkgref{myfilist} provides some commands
to control the input of \LaTeX's \cs{listfiles} so that its
output is not a list of files used for typesetting,
but a list of arbitrary files that is determined by commands
like
\begin{quote}
\cs{ReadFileInfos}\metamandarg{comma-separated-list-of-filenames}
\end{quote}
Essentially this is the command which the list of filenames that
was \metavar{files} or that is produced by \find\ is passed to.
The list is generated by running a \ext{tex} file that contains
these commands. Such a file has been called a
"\strong{\pkg{myfilist} script}" here.
More precisely, such a script is (mostly) structured as follows:
\begin{quote}
\ancref{back-load-set}{\metavar{loading-settings}}\\
\ancref{back-coll-infos}{\metavar{collecting-infos}}\\
\ancref{back-write}{\metavar{writing-to-screen+file}}
\end{quote}
These parts are as follows:
\begin{description}
\ditem{\metavar{loading-settings}\lineanc{back-load-set}}
at least issues \cs{RequirePackage}\metamandarg{myfilist}.
By default, \pkg{adhocfilelist.sh} produces (roughly)
\begin{quote}
\cs{RequirePackage}\cb{myfilist}\cs{EmptyFileList}
\metacode{adhoc-adjust}
\end{quote}
for \metavar{loading-settings} where \metavar{adhoc-adjust}
adds technical details needed for use with \pkg{adhocfilelist}.
(Final warnings are suppressed by a command \cs{NoBottomLines},
this might be changed in the future.)
It has been a disadvantage of \LaTeX's \cs{listfiles} functionality
that the resulting plain text file list looked good with base filenames
only that had up to eight characters. \ctanpkgref{longnamefilelist}
made up for this disadvantage, and \ctanpkgref{nicefilelist}
has additional refinements of aligning the list, proposed by
Martin \ctanpkgauref{muench-hm}{Mnch}. To use them with
\pkg{myfilist}, they are loaded in \metavar{loading-settings}
as well, and additional settings for column widths may be added there too.
This is what \strong{options} \strongcode{-l} and \strongcode{-n} do.
Besides in their own \acro{PDF} documentation (that you find by following the
links), the packages are also briefly described in that file
\mirrorctanref{info/latexfileinfo-pkgs/latexfileinfo_pkgs.htm}{%
\file{latexfileinfo_pkgs.htm}}
to be read by a web browser.
However, more refined settings may be needed that cannot
be controlled by \pkg{adhocfilelist}'s interface so far.
The \strong{option} \strongmetaopt{i}{tex-file}
has the effect that \metavar{loading-settings} becomes
\begin{quote}
\metavar{tex-file-content}
\metavar{adhoc-adjust}
\end{quote}
where \metavar{tex-file-content} is the content of the
(\ext{tex} file) \metavar{tex-file} (before \cs{endinput}).
\ditem{\metavar{collecting-infos}\lineanc{back-coll-infos}}
essentially is that
\begin{quote}
\cs{ReadFileInfos}\metamandarg{comma-separated-list-of-filenames}
\end{quote}
mentioned above.
\ditem{\metavar{writing-to-screen+file}\lineanc{back-write}}
essentially is \cs{ListFileInfos} or
\begin{quote}
\cs{ListFileInfos}\metaoptarg{txt-file}
\end{quote}
With \pkg{adhocfilelist}, that "\metaoptarg{txt-file}"
is inserted on \strong{option} \strongmetaopt{o}{txt-file}.
\end{description}
However, \pkg{myfilist} has been extended at the occasion
of preparing \pkg{adhocfilelist} so that the sections
\metavar{collecting-infos} and \metavar{writing-to-screen+file}
may "collapse" into a single command starting with
\cs{ReadListFileInfos}.
\end{description}
\labelsection{custom}{General customization}
In general, options \strongmetaopt{F}{find-file} and
\strongmetaopt{i}{tex-file} will be needed
to deal with certain directories \metavar{dir}.
Two ways come to my mind how to simplify this situation.
\begin{enumerate}
\item \metavar{find-file} and \metavar{tex-file} may be
in the same directory \metavar{dir}, and the latter may es well
contain an executable (\code{\Wikienref{chmod}})
script file \metavar{script-file}
with the following content:
\begin{quote}
\ancref{call}{\metacode{call}}
\code{-F~}\metacode{find-file}
\code{-i~}\metacode{tex-file}
\metacode{more}
\code{\string$@}
\end{quote}
Here \metavar{call} is as in the \ancref{call}{overview},
and \metavar{more} may be empty or something else that you
want to have fixed, such as \strongmetaopt{o}{txt-file}.
\strong{Then} you can \strong{vary} additional options/parameters
\metavar{add} by
\begin{quote}
\code{./}\metacode{script-file} \metacode{add}
\end{quote}
\item If you have \strong{several directories} \metavar{dir} as before
of a certain "type", %%% \metavar{type}, %% rm. 2012/10/17
such that they can \strong{share} the settings in
\metavar{find-file} and \metavar{tex-file},
you can place the latter in some separate ("central")
directory \metavar{center} and define an \code{\Wikienref{alias}}
as follows:
\begin{quote}
\EXECUTE{\MakeOther\'}
\code{alias~}\metacode{name}\code{='}\ancref{call}{\metacode{call}}
\code{-F~}\metacode{center}\code/\metacode{find-file}
\code{-i~}\metacode{center}\code/\metacode{tex-file}
\metacode{more}\code{'}
\end{quote}
(Note that there is no "\code{\string$@}".
"\metacode{dir}\code/\metacode{tex-file}" could be replaced by
mere "\metacode{tex-file}" if that \metavar{tex-file}
is installed like a \TeX~package.)
\strong{Then} you can \strong{vary} additional options/parameters
\metavar{add} by
\begin{quote}
\metacode{name} \metacode{add}
\end{quote}
\end{enumerate}
\labelsection{idea}{The idea/motivation; acknowledgements}
One day (most probably 2012-09-27),
I wanted to check the \cs{ProvideFile} contents of \emph{two}
files I knew I had edited that day.
On 2012-09-26, I had thought about simplifying \ctanpkgref{typeoutfileinfo}
by using a single command line without any piping.
I realized that \LaTeX~s \cs{typeout} could be replaced by
\cs{ReadFileInfos} from \ctanpkgref{myfilist}.
Therefore "\Wikienref{ad hoc}".
Maybe the same day later,
I realized that I could no longer remember which files I changed that day.
In July I had discovered \code{\string$(find ...)}. Now I thought that this
could be used here. "Ad hoc" is less appropriate here, and first I thought
that there will be different script files for explicitly specified files
than for applying \find.
Only then I learnt real shell programming by googling, kind of chance,
and most helpfully from Chapter~3 of Jrgen Wolfs
\httpref{openbook.galileocomputing.de/shell_programmierung}{OpenBook}
from \Wikideref{Galileo Press}
(\code{\Wikienref{getopts}}\pardash bad here, however)
and Prof. Jrgen Plates
\httpref{netzmafia.de/skripten/unix/unix8.html}{lecture notes}
("Optionen ermitteln"\pardash "by hand").
Then quoting/escaping for filename extensions with \Find\ became difficult ...
Quotation marks and "positional parameters" with the shell are very
difficult/\strong{painful}\pardash\TeX\ is more straightforward ...
On the other hand it is nice that the entire command line with \emph{all} the
"parameters" is gobbled.
\hrule
\rightpar{\textit{%
Last~revised~\isotoday\ \copyright~\webdesignref{contact.html}{Uwe Lck}\\
% \vspace{6}
(using \CtanPkgRef{morehype}{blog.sty})\\ %% ) 2012/10/17
% \vspace{6}
License: \httpref{www.latex-project.org/lppl/}{LPPL~1.3c} or later, author-maintained.}}
\entotopofpage
\vspace{240}
\finish