List LaTeX file infos according to command line

From 7091f02f114d34ab2164074d16106b9e9b4e8bb4 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 22 Nov 2012 00:51:36 +0000 Subject: adhocfilelist (21nov12) git-svn-id: svn://tug.org/texlive/trunk@28326 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/support/adhocfilelist/adhocfilelist.htm | 296 +++++++++++---------- 1 file changed, 149 insertions(+), 147 deletions(-) (limited to 'Master/texmf-dist/doc/support/adhocfilelist/adhocfilelist.htm') diff --git a/Master/texmf-dist/doc/support/adhocfilelist/adhocfilelist.htm b/Master/texmf-dist/doc/support/adhocfilelist/adhocfilelist.htm index 9bd63c2dc07..0aa80e2be40 100644 --- a/Master/texmf-dist/doc/support/adhocfilelist/adhocfilelist.htm +++ b/Master/texmf-dist/doc/support/adhocfilelist/adhocfilelist.htm @@ -1,15 +1,15 @@ - - + with blog.sty, 2012-11-20 --> + + List LaTeX file infos according to command line - + @@ -24,20 +24,20 @@

Abstract.

-adhocfilelist.sh is a shell script with command line options +

Abstract.

+adhocfilelist.sh is a shell script with command line options and parameters that displays ⟨info⟩ for files ⟨file⟩ on screen that (i) are indicated on the command line and (ii) contain \ProvidesFile{⟨file⟩}[⟨info⟩], @@ -47,55 +47,55 @@ There is one line for each file, formatted about as with LaTeX’s \listfiles. This formatting can be varied, and the output may additionally be saved in a plain text file. The files ⟨file⟩ are either (a) listed explicitly, separated by commas, or -(b) they are gathered by the Unix find utility. -For the latter, adhocfilelist provides a somewhat simplified +(b) they are gathered by the Unix find utility. +For the latter, 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 filedate “consistency checks” -even with XeTeX (where \pdffilemoddate +and it may allow filedate “consistency checks” +even with XeTeX (where \pdffilemoddate is unavailable).

The package may thus be considered an extension of the -latexfileversion (Harald Harders) -and typeoutfileinfo packages +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. +myfilist, longnamefilelist, +nicefilelist, and filedate. -

Overview of command line contents.

-The general structure of a command line using adhocfilelist is +

Overview of command line contents.

+The general structure of a command line using adhocfilelist is

-⟨call⟩ -⟨options⟩ -⟨files⟩ +⟨call⟩ +⟨options⟩ +⟨files⟩

The three parts are as follows:

⟨call⟩

This is either

⟨path⟩adhocfilelist.sh +
⟨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, +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. +
an alias for +⟨path⟩adhocfilelist.sh.

⟨options⟩

-Some options “switch into find mode”, +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). +understanding the details may require some knowledge of find +(see “background” below). Some options have one parameter, some have none.

-0: (f) @@ -105,12 +105,12 @@ 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. +date using filedate additionally.
-TODO: The restriction to find (v0.7) is temporary, removing it is +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, +Add ⟨files⟩ to other find criteria, replacing internal default settings (as opposed to -g). For allowing certain file name extensions such as .tex, @@ -118,17 +118,18 @@ the star must be escaped and ⟨files⟩ best has outer single quotes, such as
-'-follow ( -name \*.tex -o -name \*.sty )' +'-L ( -name \*.tex -o -name \*.sty )' +
-F ⟨find-file⟩: (f) -Add content of the file ⟨find-file⟩ to other find criteria. +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, +Add ⟨files⟩ to other find criteria, among which some hopefully “generally useful” -are added from within adhocfilelist.sh. +are added from within adhocfilelist.sh. As to quoting/escaping in ⟨files⟩, this is as with -f.
-h: @@ -136,18 +137,18 @@ 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 +to the temporary .tex file that adhocfilelist.sh generates internally — to get more individual settings -than adhocfilelist.sh’s internal defaults +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 +Format list by the longnamefilelist package where ⟨integer⟩ is the maximum length of base -filenames in the list (about as …) +filenames in the list (about as …)
-n ⟨filename⟩: -Format list by the nicefilelist package -where ⟨filename⟩ is the longest base filename (or a template). +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 @@ -159,19 +160,19 @@ as plain text file ⟨txt-file⟩ also. 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 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 +The real problem with filedate and XeTeX is that a reliable consistency check does not work -while typesetting with XeTeX. But filedate can be +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. +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 @@ -179,104 +180,105 @@ the latex command is missing on the user’s (unusual) installa

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

⟨files⟩

-Whenever an option “switches into find mode”, +

⟨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 +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, +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. +contact-ednotes.sty.de.vu.

-Actually the package was developed with the GNU bash +Actually the package was developed with the GNU bash shell and the -GNU find utility on -Ubuntu 10.04. +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 +(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, +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. +The package requires that the fileinfo bundle is installed. In order to use the -l option, -longnamefilelist must be installed additionally. +longnamefilelist must be installed additionally. In order to use the -n option, -nicefilelist must be installed additionally. +nicefilelist must be installed additionally. In order to use the -c option, -filedate must be installed additionally. +filedate must be installed additionally.

Installing.

-No more advice than implied by the section on “⟨call⟩” +

Installing.

+No more advice than implied by the section on “⟨call⟩” can be given right now. -

Related packages.

The file -latexfileinfo_pkgs.htm +latexfileinfo_pkgs.htm describes related packages available on -CTAN +CTAN in some detail. The most obvious ones have been mentioned above already.

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

Background.

For understanding the options -0, -a, -f, -F, and -g, -knowing something about the find utility -and the present interface to it may be helpful. +knowing something about the find utility +and the present interface to it may be helpful. The options -i, -l, -n, -and -o refer to the myfilist package -and its enhancements by the packages longnamefilelist -and nicefilelist, and it may be helpful to know -what a “myfilist script” is. +and -o refer to the myfilist package +and its enhancements by the packages longnamefilelist +and nicefilelist, and it may be helpful to know +what a “myfilist script” is.

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, +

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. +GNU manual.

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

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

These parts are as follows:

⟨prefix⟩: +
⟨prefix⟩: is
--follow -maxdepth 1 ( -name \*.tex -o ⟨more⟩ ) +-L -maxdepth 1 ( -name \*.tex -o ⟨more⟩ ) +
where ⟨more⟩ in addition to files with extension .tex allows @@ -290,12 +292,12 @@ 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” +-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⟩: +into find mode otherwise without deleting ⟨prefix⟩. +
⟨files⟩: +is as in the overview. +
⟨day⟩: is empty, unless -0 sets it to
-daystart -mtime 0 @@ -318,7 +320,7 @@ are allowed —cf. GNU documentation on -age ranges. +age ranges.
A tricky little thing here is that ⟨day⟩ may be expected to be a restriction, @@ -327,12 +329,12 @@ 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 +TODO: This is different with option -c (v0.7) whose functionality also may change soon.

myfilist

-The LaTeX package myfilist provides some commands +

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 @@ -342,48 +344,48 @@ like Essentially this is the command which the list of filenames that -was ⟨files⟩ or that is produced by find is passed to. +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. +“myfilist script” here. More precisely, such a script is (mostly) structured as follows:

-⟨loading-settings⟩
-⟨collecting-infos⟩
-⟨writing-to-screen+file⟩ +⟨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) +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. +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 +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⟩ +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 +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. +be controlled by adhocfilelist’s interface so far. The option -i ⟨tex-file⟩ has the effect that ⟨loading-settings⟩ becomes

@@ -393,32 +395,32 @@ has the effect that ⟨loading-settings⟩ becomes

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⟩]” +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 +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.

In general, options -F ⟨find-file⟩ and -i ⟨tex-file⟩ will be needed to deal with certain directories ⟨dir⟩. @@ -427,18 +429,18 @@ Two ways come to my mind how to simplify this situation.

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

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

-Here ⟨call⟩ is as in the overview, +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⟩.

@@ -454,11 +456,11 @@ 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 +directory ⟨center⟩ and define an alias as follows:

-alias ⟨name⟩='⟨call⟩ +alias ⟨name⟩='⟨call⟩ -F ⟨center⟩/⟨find-file⟩ -i ⟨center⟩/⟨tex-file⟩ ⟨more⟩' @@ -478,41 +480,41 @@ is installed like a TeX package.)

The idea/motivation; acknowledgements.

One day (most probably 2012-09-27), I wanted to check the \ProvideFile contents of two files I knew I had edited that day. -On 2012-09-26, I had thought about simplifying typeoutfileinfo +On 2012-09-26, I had thought about simplifying typeoutfileinfo by using a single command line without any piping. I realized that LaTeX s \typeout could be replaced by -\ReadFileInfos from myfilist. -Therefore “ad hoc”. +\ReadFileInfos from myfilist. +Therefore “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 $(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. +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) +OpenBook +from Galileo Press +(getopts — bad here, however) and Prof. Jürgen Plates -lecture notes +lecture notes (“Optionen ermitteln” — “by hand”).

-Then quoting/escaping for filename extensions with find became difficult … +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.

[→ top of page ]

-- cgit v1.2.3