adhocfilelist — Listing LaTeX Source File Infos
According to Command Line

[ abstract | overview | requirements | installing | related | background | customize | idea/thanks ]  [ reload ]

Abstract.

The package may thus be considered an extension of the latexfileversion (Harald Harders) and typeoutfileinfo packages that display ⟨info⟩ for a single file ⟨file⟩. Moreover, it is a somewhat simplified interface to the packages myfilist, longnamefilelist, nicefilelist, and filedate.

Overview of command line contents.

⟨call⟩ ⟨options⟩ ⟨files⟩

⟨call⟩

This is either

• ⟨path⟩adhocfilelist.sh where ⟨path⟩ is “./” or something, depending on where you place the file adhocfilelist.sh, or on your use of symbolic links, the environment variable PATH, or
• an alias for ⟨path⟩adhocfilelist.sh.

⟨options⟩

Some options “switch into find mode”, affecting the interpretation of ⟨files⟩, marked by “(f)”. Their description may be inaccurate here, understanding the details may require some knowledge of find (see “background” below). Some options have one parameter, some have none.

-0

(f) List files modified “today” only (unless …)

-a ⟨integer⟩

(f) List files modified ⟨integer⟩ days ago only (unless ⟨integer⟩ starts with “-” or “+” …)

-c

(f) Compare date according to \Provides... content with modification date using filedate additionally.

TODO: The restriction to find (v0.7) is temporary, removing it is straightforward, but I may have to postpone this for a while.

-f

(f) Add ⟨files⟩ to other find criteria, replacing internal default settings (as opposed to -g). For allowing certain file name extensions such as .tex, the star must be escaped and ⟨files⟩ best has outer single quotes, such as

'-L ( -name \*.tex -o -name \*.sty )'

-F ⟨find-file⟩

(f) Add content of the file ⟨find-file⟩ to other find criteria. As compared with -f, stars must be escaped, while other quoting seems not to be needed in ⟨files⟩.

-g

(f) Add ⟨files⟩ to other find criteria, among which some hopefully “generally useful” are added from within adhocfilelist.sh. As to quoting/escaping in ⟨files⟩, this is as with -f.

-h

Display an overview (brief version of present one, “help”), and ignore everything else of the command line.

-i ⟨tex-file⟩

Prepend (“input”) contents of the file ⟨tex-file⟩ to the temporary .tex file that adhocfilelist.sh generates internally — to get more individual settings than adhocfilelist.sh’s internal defaults (which are replaced by the content of ⟨tex-file⟩) and than the options -l and -n provide.

-l ⟨integer⟩

Format list by the longnamefilelist package where ⟨integer⟩ is the maximum length of base filenames in the list (about as …)

-n ⟨filename⟩

Format list by the nicefilelist package where ⟨filename⟩ is the longest base filename (or a template). If base filenames do not have more than eight characters, you can use “-n .” as a shorthand for “-n ⟨filename⟩” with a ⟨filename⟩ of eight characters.

-o ⟨txt-file⟩

Save the displayed file info list (“output”) as plain text file ⟨txt-file⟩ also.

-x

Use xelatex rather than latex (v0.7). — The idea for this has been that the script should provide “date consistency” checks (option -c) “even with XeTeX where \pdffilemoddate is not available.” However, the script has used latex before v0.7 which will run pdfTeX usually, even when the user prefers typesetting with XeTeX, and anyway it does not rely on \pdffilemoddate. The real problem with filedate and XeTeX is that a reliable consistency check does not work while typesetting with XeTeX. But filedate can be used for “TeX scripts” too, i.e., without typesetting, and that is what the present package does. The present package does not provide consistency checks while typesetting with XeTeX. It should not be make a difference whether the “TeX script” that adhocfilelist generates is run with XeTeX or with pdfTeX. So the only “special XeTeX support” from here probably will be the present -x in case latex does not work, maybe because pdfTeX or anything implementing the latex command is missing on the user’s (unusual) installation.

Options can not be “contracted” like “-0f” (too difficult with processing [parts of] find expressions — -name …).

⟨files⟩

Whenever an option “switches into find mode”, ⟨files⟩ is interpreted as part of a command line for the find utility. Otherwise, ⟨files⟩ is expected to be a comma-separated list of filenames (for LaTeX source files), whose extension .tex (if so) may be omitted — unless -h …

Requirements.

System

The package will work on a 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 contact-ednotes.sty.de.vu.

Actually the package was developed with the GNU bash shell and the GNU find utility on Ubuntu 10.04.

My impression is in fact (looking at The Open Group’s man page for find) that in order to use the find options -0, -a, -f, -F, and -g, the GNU version of find is required, because action -printf is used and essential (difficult without).

LaTeX

The package requires that the fileinfo bundle is installed. In order to use the -l option, longnamefilelist must be installed additionally. In order to use the -n option, nicefilelist must be installed additionally. In order to use the -c option, filedate must be installed additionally.

Installing.

Related packages.

The next section indicates details that may be improve understanding the LaTeX-related command line options -i, -l, and -n.

Background.

find

We are describing the interface to find. To learn about the contents of a find command line, the Wikipedia article may be a good start, next enter “man find” in the terminal, finally see the GNU manual.

adhocfilelist.sh forms the following find command line in order to get a comma-separated list of files:

find ⟨prefix⟩ ⟨files⟩ ⟨day⟩ -printf ,%f

These parts are as follows:

⟨prefix⟩

is

-L -maxdepth 1 ( -name \*.tex -o ⟨more⟩ )

where ⟨more⟩ in addition to files with extension .tex allows those with extensions .sty, .cfg, .cls, .dtx, .def, and .fd — unless with options

-f

where ⟨prefix⟩ is empty

-F ⟨find-file⟩

where ⟨prefix⟩ is the content of the file ⟨find-file⟩.

Option -g is not required with options -0 and -a that switch into “find mode” too without deleting ⟨prefix⟩, it is just a way to switch into find mode otherwise without deleting ⟨prefix⟩.

⟨files⟩

is as in the overview.

⟨day⟩

is empty, unless -0 sets it to

-daystart -mtime 0

or -a ⟨integer⟩ sets it to

-daystart -mtime ⟨integer⟩

It follows that

• -0 has the same effect as (is just a shorthand for) -a 0
• if ⟨integer⟩ is “-⟨digits⟩”, files modified since ⟨digits⟩ days ago are allowed

—cf. GNU documentation on age ranges.

A tricky little thing here is that ⟨day⟩ may be expected to be a restriction, an additional criterion that a LaTeX source file must meet to be listed. However, if ⟨files⟩ ends on -o for “or”, ⟨day⟩ becomes an “additional possibility” for being listed …

TODO: This is different with option -c (v0.7) whose functionality also may change soon.

myfilist

The LaTeX package myfilist provides some commands to control the input of LaTeX’s \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

\ReadFileInfos{⟨comma-separated-list-of-filenames⟩}

Essentially this is the command which the list of filenames that was ⟨files⟩ or that is produced by find is passed to. The list is generated by running a .tex file that contains these commands. Such a file has been called a “myfilist script” here. More precisely, such a script is (mostly) structured as follows:

⟨loading-settings⟩
⟨collecting-infos⟩
⟨writing-to-screen+file⟩

These parts are as follows:

⟨loading-settings⟩

at least issues \RequirePackage{⟨myfilist⟩}. By default, adhocfilelist.sh produces (roughly)

\RequirePackage{myfilist}\EmptyFileList ⟨adhoc-adjust⟩

for ⟨loading-settings⟩ where ⟨adhoc-adjust⟩ adds technical details needed for use with adhocfilelist. (Final warnings are suppressed by a command \NoBottomLines, this might be changed in the future.)

It has been a disadvantage of LaTeX’s \listfiles functionality that the resulting plain text file list looked good with base filenames only that had up to eight characters. longnamefilelist made up for this disadvantage, and nicefilelist has additional refinements of aligning the list, proposed by Martin Münch. To use them with myfilist, they are loaded in ⟨loading-settings⟩ as well, and additional settings for column widths may be added there too. This is what options -l and -n do. Besides in their own PDF documentation (that you find by following the links), the packages are also briefly described in that file latexfileinfo_pkgs.htm to be read by a web browser.

However, more refined settings may be needed that cannot be controlled by adhocfilelist’s interface so far. The option -i ⟨tex-file⟩ has the effect that ⟨loading-settings⟩ becomes

⟨tex-file-content⟩ ⟨adhoc-adjust⟩

where ⟨tex-file-content⟩ is the content of the (.tex file) ⟨tex-file⟩ (before \endinput).

⟨collecting-infos⟩

essentially is that

\ReadFileInfos{⟨comma-separated-list-of-filenames⟩}

mentioned above.

⟨writing-to-screen+file⟩

essentially is \ListFileInfos or

\ListFileInfos[⟨txt-file⟩]

With adhocfilelist, that “[⟨txt-file⟩]” is inserted on option -o ⟨txt-file⟩.

However, myfilist has been extended at the occasion of preparing adhocfilelist so that the sections ⟨collecting-infos⟩ and ⟨writing-to-screen+file⟩ may “collapse” into a single command starting with \ReadListFileInfos.

General customization.

1. ⟨find-file⟩ and ⟨tex-file⟩ may be in the same directory ⟨dir⟩, and the latter may es well contain an executable (chmod) script file ⟨script-file⟩ with the following content:

   ⟨call⟩ -F ⟨find-file⟩ -i ⟨tex-file⟩ ⟨more⟩ $@

   Here ⟨call⟩ is as in the overview, and ⟨more⟩ may be empty or something else that you want to have fixed, such as -o ⟨txt-file⟩.

   Then you can vary additional options/parameters ⟨add⟩ by

   ./⟨script-file⟩ ⟨add⟩

2. If you have several directories ⟨dir⟩ as before of a certain “type”, such that they can share the settings in ⟨find-file⟩ and ⟨tex-file⟩, you can place the latter in some separate (“central”) directory ⟨center⟩ and define an alias as follows:

   alias ⟨name⟩='⟨call⟩ -F ⟨center⟩/⟨find-file⟩ -i ⟨center⟩/⟨tex-file⟩ ⟨more⟩'

   (Note that there is no “$@”. “⟨dir⟩/⟨tex-file⟩” could be replaced by mere “⟨tex-file⟩” if that ⟨tex-file⟩ is installed like a TeX package.)

   Then you can vary additional options/parameters ⟨add⟩ by

   ⟨name⟩ ⟨add⟩

The idea/motivation; acknowledgements.

Maybe the same day later, I realized that I could no longer remember which files I changed that day. In July I had discovered $(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 Jürgen Wolfs OpenBook from Galileo Press (getopts — bad here, however) and Prof. Jürgen Plates lecture notes (“Optionen ermitteln” — “by hand”).

Then quoting/escaping for filename extensions with find became difficult … Quotation marks and “positional parameters” with the shell are very difficult/painful — TeX is more straightforward … On the other hand it is nice that the entire command line with all the “parameters” is gobbled.

Last revised 2013-01-04 © Uwe Lück
(using blog.sty)
License: LPPL 1.3c or later, author-maintained.

[→ top of page ]