Debian Codegraph @

texmf-dist/source/latex/nicefilelist/nicefilelist.tex

raw
1 \ProvidesFile{nicefilelist.tex}[2025/04/21 documenting nicefilelist.sty]
2 \title{\pkg{\huge nicefilelist.sty
3 }\\ -- \\\cs{listfiles} Alignment for Connoisseurs\thanks{This
4 document describes version
5 \textcolor{blue}{\UseVersionOf{\jobname.sty}}
6 of \pkg{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
7 { \RequirePackage{makedoc} \ProcessLineMessage{}
8 \MakeJobDoc{18}%% 2012/10/30
9 {\SectionLevelTwoParseInput} }
10 \documentclass[fleqn]{article}%% TODO paper dimensions!?
11 \input{makedoc.cfg} %% shared formatting settings
12 \usepackage[wrap]{nicefilelist} \listfiles
13 %% <- 2012/10/30 try without 'myfilist'
14 \MDkeywords{Package management, document management, plain text output}
15 \sloppy
16 \begin{document}
17 \maketitle
18 \begin{MDabstract}
19 While \CtanPkgRef{longnamefilelist}{longnamefilelist.sty}
20 improves \LaTeX's \cs{listfiles} with respect to long base filenames only,
21 'nicefilelist.sty' can keep separate columns for
22 (i)~date, (ii)~version, and (iii)~``caption" %% 1st, 2012/10/30
23 (do not write caption text in date column),
24 their alignment not being disturbed by short filename extensions such as `.fd'.
25 This is achieved basing on the \ctanpkgref{monofill} package.
26
27 % Thus 'nicefilelist' is more ``powerful" than 'longnamefilelist',
28 % the former however is an ``extension" of the latter
29 % neither with respect to implementation nor with respect to user interface.
30
31 %% <- 2012/10/29 ->
32 v0.7 offers a package option `[wrap]' for automatic word wrapping
33 within the caption column, using the \ctanpkgref{hardwrap} package,
34 so file names and captions can be quite long without disturbing
35 the alignment.
36
37 v0.9a offers a package option `[autolength]' for automatic sizing
38 of the columns, using the \ctanpkgref{xstring} package.
39
40 v0.9c offers the options `[hashes]' and/or `[sizes]' to the
41 `\listfiles' command, `\listfiles[hashes,sizes]', as provided
42 by \LaTeX{} release 2024-06-01, see \LaTeX{} News Issue~39 at
43 \url{https://www.latex-project.org/news/latex2e-news/ltnews39.pdf}.
44
45 As opposed to the \ctanpkgref{dateiliste} package, this is about the
46 \meta{plain text} output in the `.log' file or, with \ctanpkgref{myfilist},
47 as a stand-alone plain text file.
48
49 \MDaddtoabstract{Related packages}Cf.~\ctanpkgref{latexfileinfo-pkgs}.
50 \end{MDabstract}
51 \tableofcontents
52 \section{Features and Usage}
53 % We are describing relations to related packages - rather briefly.
54 % The \ctanpkgref{latexfileinfo-pkgs} package provides a more general overview.
55 % %% <- 2012/05/18
56 %% 2012/10/29:
57 Additionally or also ``complementarily" to the presentation given here,
58 the functionality of the package is summarized in the file
59 `latexfileinfo_pkgs.htm' from the \ctanpkgref{latexfileinfo-pkgs},
60 in a comparison with packages resembling `nicefilelist' in
61 certain respects.
62
63 \subsection{Relation to 'longnamefilelist.sty'}
64 \CtanPkgRef{longnamefilelist}{longnamefilelist.sty} equips
65 \cs{listfiles} with an optional argument for the maximum number of characters
66 in the base filename. By contrast, 'nicefilelist' does not provide
67 arguments for \cs{listfiles}, rather column widths for basename, extension,
68 and version number are determined by \emph{templates} using
69 \CtanPkgRef{monofill}{monofill.sty}. As a ``template" for doing this,
70 see the initial settings in section~\ref{sec:templates}.
71 (Such settings must precede the \cs{listfiles command})
72 So 'nicefilelist''s \emph{user interface} (at present) does not \emph{extend}
73 'longnamefilelist''s user interface.
74
75 Using 'monofill' is a very different approach than the one of 'longnamefilelist'.
76 'nicefilelist' is more powerful than 'longnamefilelist', but is not based on it
77 in any way. It does not make sense to load both packages, they just overwrite
78 each other's behaviour of \cs{listfiles}.
79
80 'longnamefilelist' may become ``obsolete" by the present package,
81 unless one finds that its version of \cs{listfiles} looks fine enough
82 and it is easier to understand and to use than 'nicefilelist'.
83
84 \subsection{Installing}
85 The file 'nicefilelist.sty' is provided ready, installation only requires
86 putting it somewhere where \TeX\ finds it
87 (which may need updating the filename data base).
88
89 \subsection{Calling}
90 %% restructured for v0.7 2012/10/29:
91 Below the `\documentclass' line(s) and above `\begin{document}',
92 you load 'nicefilelist.sty' (as usually) by
93 \[`\usepackage{nicefilelist}'\]
94 or by
95 \[`\usepackage[<options>]{nicefilelist}'\]
96 where <options> may be `r', `wrap', and/or `autolength' -- see
97 summaries in sections~\ref{sec:set} and \ref{sec:opt}
98 on the package options and an example in section~\ref{sec:short}.
99 Alternatively -- e.g., for use with \ctanpkgref{myfilist} from the
100 \ctanpkgref{fileinfo} bundle (in a ``\TeX~script"), see section~\ref{sec:myfilist},
101 or in order to include the `.cls' file in the list -- you may load it by
102 \[`\RequirePackage{nicefilelist}'\]
103 or by
104 \[`\RequirePackage[<options>]{nicefilelist}'\]
105 before `\documentclass' or when you do not use `\documentclass'.
106
107 \subsection{Choosing Settings} %% new 2012/10/29
108 \label{sec:set}
109
110 \subsubsection{The Columns, Their Widths, and Their ``Missing" Content}
111 \label{sec:cols}
112
113 \AddQuotes %% 2012/10/29
114
115 The 'nicefilelist' package considers the listing from `\listfiles'
116 a five-column table, the columns being (reserved for) \\
117 (i)~the base filename, \\ (ii)~the filename extension, \\
118 (iii)~the date, \\
119 (iv)~the version (or with option `[r]': the release) number, and \\
120 (v)~the caption \\ of a \LaTeX\ source file. The filename base column
121 is right-adjusted, the other ones are left-adjusted.
122 Date, version, and caption are made up from the <f-info> argument in
123 \[|\Provides<f-type>{<f-base>.<f-ext>}[<f-info>|]\]
124 where <f-type> is `Class', `Package', or `File'.
125
126 The fixed usual format `YYYY/MM/DD'
127 or `YYYY-MM-DD' (accepted by \LaTeX\ since 2017-03-08)
128 for the date is assumed;
129 in fact, when <f-info> does not start according to this format,
130 it is assumed that no date is given, and some ``missing''
131 text will appear in the ``date" column, determined by a macro
132 |\NFLnodate|.
133 \pagebreak
134
135 Using the filemod package, it is possible to use the date
136 of a file which does not explicitly declare a date:
137
138 \begin{verbatim}
139 \makeatletter
140 \RequirePackage{filemod}%
141 \renewcommand*\thefilemoddate[3]{#1-#2-#3}
142 \renewcommand*{\NFLnodate}{\filemodprintdate{%
143 \filename@area\filename@base.\filename@ext}}
144 \makeatother
145 \renewcommand*{\NFLnotfound}{%
146 \NFLnodate\NFLspaceII\NFLnoversion\NFLspaceIII}
147 \end{verbatim}
148
149 The version number
150 (or ``string") must follow in format `v<digit>.<digits>',
151 otherwise some ``missing" text appears in the ``version" column,
152 determined by a macro |\NFLnoversion|.
153 What remains is placed in the ``caption" column.
154 |\NFLnotfound| determines an alternative filling
155 in the case that <f-info> cannot be obtained.
156 See the default settings for these ``failure" texts in
157 section~\ref{sec:fail}.
158
159 The column widths for filename base and extension
160 and the column width for version or release
161 are determined using the \ctanpkgref{monofill} package.
162 They have ``field identifiers" |f-base|, |f-ext|,
163 and |f-version| respectively. The respective widths are
164 determined by templates <longest> in
165 \[|\MDfieldtemplate{<field-id>}{<longest>}|\]
166 See section~\ref{sec:templates} for the default settings.
167 Probably only adjusting the width for \emph{base} filenames
168 is required in real life, see the example in section~\ref{sec:short}.
169 (But there exist extensions .info and .mkii and versions
170 v4.6.3.1 (fontawesome.sty).)
171 %% 2023-01-06
172 Option `autolength' measures the respective length of the field and
173 writes it into the .aux file for use in the next compilation run.
174 This option requires \LaTeX{} format-version at least 2022-11-01.
175
176 The spaces between the columns are determined by macros
177 |\NFLspaceI|, |\NFLspaceII|, and |\NFLspaceIII|,
178 see section~\ref{sec:templates} for the defaults.
179
180 \DontAddQuotes %% 2012/10/29
181
182 \subsubsection{The Caption Column}
183 The width of the caption column (unfortunately) is determined by
184 the stuff enumerated above and the width of the console output window or screen.
185 With long filenames and long captions, the result may look poor.
186 The \emph{characters} that do not fit into the line may continue
187 at left end of the window or screen, disturbing the appearance
188 of a ``table" -- unless you use package option |[wrap]|.
189 The latter requires the \ctanpkgref{hardwrap} package by
190 Will Robertson and Kevin Godby. This package tries to determine
191 the screen width by some subtle tests, and until it finds something
192 better, it assumes a width of 80~characters (I~suppose).
193 'hardwrap' does \wikienref{Word wrap}{\emph{word wrapping}},
194 i.e., it does not just put \emph{characters} not fitting into the
195 next line, but entire \emph{words}. Moreover, it allows inserting
196 some ``newline sequence" before the first word that is too much,
197 and we use this feature here to put the next word into the
198 \emph{caption column} rather than at the beginning of the next line.
199 (Details and implementation are in section~\ref{sec:opt}.)
200
201 If you are not happy with the column width that 'hardwrap'
202 chooses, but want to assume your own width <max-line-chars>
203 (e.g., your width, measured by your doctor, divided by the
204 width of one character),
205 compute its difference <max-line-chars-minus-one> to 1
206 (maybe by your electronic calculator, or an emulation,
207 or a Lua script, cf.~\ctanpkgref{lualatex-doc}, or by
208 \ctanpkgref{bigintcalc}), and enter
209 the 'hardwrap' instruction
210 \[|\setmaxprintline{<max-line-chars-minus-one>}|\]
211 when 'hardwrap' or 'nicefilelist' have been loaded
212 \emph{and} before the internal macro `\@dofilelist' is run
213 (which happens at the end of the document or when
214 \ctanpkgref{myfilist}'s `\ListInfos' is issued, for instance).
215
216 \subsubsection{Extended information in \texttt{listfiles}}
217 Since \LaTeX{} release 2024-06-01 the |\listfiles| command
218 takes the option `hashes' to give the MD5 hash and
219 `sizes' to give the file size of each file in the `.log',
220 printed after the end of the caption (in a new line);
221 see \LaTeX{} News Issue~39 at
222 \url{https://www.latex-project.org/news/latex2e-news/ltnews39.pdf}.
223
224 \subsection{Usage and examples with 'myfilist.sty'}
225 \label{sec:myfilist}
226 \subsubsection{Basically}
227 In order to get a reduced and/or rearranged list of file infos
228 with the \ctanpkgref{myfilist} package,
229 `nicefilelist.sty' must be loaded earlier than
230 `myfilist.sty'. This is due to a kind of limitation of the latter,
231 it \emph{issues} `\listfiles' (\TODO).
232 Therefore \cs{listfiles} must be modified earlier -- or \emph{issued} earlier,
233 in this case the \cs{listfiles} in `myfilist.sty' does nothing.
234 The file `SrcFILEs.txt' accompanying the -- first -- distribution of
235 'nicefilelist' %% corr., was `longname'; `first' etc. 2012/10/29
236 was generated by running the following file `srcfiles.tex' with \LaTeX:
237 \begin{quotation}\tt\small
238 \expandafter\def\expandafter\{\expandafter{\string{}
239 \expandafter\def\expandafter\}\expandafter{\string}}
240 \obeyspaces\obeylines
241 \cs{ProvidesFile}\{srcfiles.tex\}[2012/03/23
242 ~ file infos -\empty> SrcFILEs.txt]
243 \cs{RequirePackage}\{nicefilelist\}
244 \%\% INSERT MODIFICATIONS OF INITIAL
245 \%\% \verb+`nicefilelist'/`monofill'+ SETTINGS HERE!
246 \cs{RequirePackage}\{myfilist\}
247 \%\% documentation:
248 \cs{ReadFileInfos}\{nicefilelist\}
249 \%\% demonstration:
250 \cs{ReadFileInfos}\{provonly.fd,wrong.prv,empty.f\}
251 \% \cs{ReadFileInfos}\{utopia.xyz\}
252 \%\% present file:
253 \cs{ReadFileInfos}\{nicefilelist\}
254 \cs{ReadFileInfos}\{srcfiles\}
255 \cs{ListInfos}[SrcFILEs.txt]
256 \end{quotation}
257 Note the lines where to place \strong{custom} modifications of settings
258 for alignment (section~\ref{sec:templates}) or failure displays
259 (section~\ref{sec:fail}).
260
261 The previous code mentions the following files:
262 \begin{description}
263 \item[`provonly.fd'] has a proper `\ProvidesFile' line without date,
264 for seeing what happens in the date and version columns.
265 It also was a test for the case that there are fewer
266 characters than a date has, and there is no blank space.
267 \item[`wrong.prv'] has a `\ProvidesFile' line with wrong file name.
268 \item[`empty.f'] just is an empty file.
269 \item[`utopia.xyz'] is not present at all, you get an error when you remove
270 the comment mark.
271 \end{description}
272 Moreover, my `.tex' files have dates, but not version numbers,
273 so you see what happens then:
274 \vskip\topsep
275 \begin{small}
276 \begin{verbatim}
277 *File List*
278 -----RELEASE.--- -- -- -- -- --
279 nicefilelist.RLS 2025/04/21 v0.9c options sizes \& hashes for \listfiles
280 -----PACKAGE.--- -- -- -- -- --
281 nicefilelist.sty 2025/04/21 v0.9c More file list alignment (UL; HMM)
282 ------DOCSRC.--- -- -- -- -- --
283 nicefilelist.tex 2025/04/21 -- documenting nicefilelist.sty
284 srcfiles.tex 2025/04/21 -- file infos -> SrcFILEs.txt
285 --------DEMO.--- -- -- -- -- --
286 provonly.fd -- -- -- -- no date, no version, but a lot of info,
287 look how that is wrapped!
288 wrong.prv * NOT FOUND *
289 empty.f * NOT FOUND *
290 --------USED.--- -- -- -- -- --
291 hardwrap.sty 2011/02/12 v0.2 Hard wrap messages
292 myfilist.sty 2012/11/22 v0.71 \listfiles -- mine only (UL)
293 readprov.sty 2012/11/22 v0.5 file infos without loading (UL)
294 fifinddo.sty 2012/11/17 v0.61 filtering TeX(t) files by TeX (UL)
295 makedoc.sty 2012/08/28 v0.52 TeX input from *.sty (UL)
296 niceverb.sty 2012/11/27 v0.51 minimize doc markup (UL)
297 texlinks.sty 2013/01/22 v0.82 TeX-related links (UL)
298 makedoc.cfg 2012/11/30 -- documentation settings
299 mdoccorr.cfg 2012/11/13 -- `makedoc' local typographical corrections
300 -not-so-much.--- -- -- -- -- --
301 kvsetkeys.sty 2012/04/25 v1.16 Key value parser (HO)
302 ***********
303
304 List made at 2025/04/21, 19:16
305 from script file srcfiles.tex
306 \end{verbatim}
307 \end{small}
308
309 \subsubsection{More Generally and Shorthand}
310 \label{sec:short}
311
312 \AddQuotes %% 2012/10/11
313
314 In the above example, the 'myfilist' command `\EmptyFileList'
315 was missing -- it was not intended there. Usually however, %% is -> was 2012/10/29
316 it \emph{is} intended, i.e., the following sequence of
317 lines is wanted:
318 \begin{quotation}\tt\small
319 \expandafter\def\expandafter\{\expandafter{\string{}
320 \expandafter\def\expandafter\}\expandafter{\string}}
321 \obeyspaces\obeylines
322 \cs{RequirePackage}[r]\{nicefilefilelist\}
323 \cs{MFfieldtemplate}\{f-base\}[<longest-name>]
324 \cs{RequirePackage}\{myfilist\}
325 \cs{EmptyFileList}[<read-again-files>]
326 \end{quotation}
327 Here you also see usage of package option |[r]| for
328 release numbers and the adjustment
329 \[|\MFfieldtemplate{f-base}{<longest-name>}|\]
330 according to section~\ref{sec:templates}.
331
332 With v0.5, the last three code lines in the snippet above
333 can be replaced by
334 \[|\MaxBaseEmptyList{<longest-name>}[<read-again-files>]|\]
335 \ -- ``optionally" without `[<read-again-files>]'.
336 This may save the user from worrying about usage
337 with 'myfilist'.
338
339 \DontAddQuotes
340
341 'nicefilelist' formats file lists nicely
342 even when base filenames have eight characters at most,
343 what \LaTeX's original `\listfiles' was made for.
344 v0.6 simplifies this case by a star version of `\MaxBaseEmptyList':
345 \pagebreak[2]
346 \[|\MaxBaseEmptyList*|\]
347 works like `\MaxBaseEmptyList{nicefile}' (eight characters) -- still,
348 optional `[<read-again-files>]' may follow. This feature is demonstrated
349 with \ctanpkgref{inputtrc} v/r0.3.
350
351 \subsubsection{Sample with Wrapped Caption Column} %% 2012/10/30
352
353 \AddQuotes
354
355 The most recent version of the accompanying `SrcFILEs.txt' contains
356 the following:
357 \bigskip
358 \begingroup \footnotesize
359 \hrule
360 \verbatiminput{SrcFILEs.txt}
361 \hrule
362 \endgroup
363 \bigskip
364
365 This exemplifies
366 \begin{enumerate}
367 \item \strong{wrapping} of `provonly.fd''s and \ctanpkgref{kvsetkeys}\file{.sty}
368 file info within the \strong{caption} column
369 using 'nicefilelist''s `[wrap]' option,
370 \item inserted ``\strong{comments}" from \ctanpkgref{myfilist}'s `\FileListRemark',
371 \item a file `nicefilelist.RLS' for a \strong{release summary}. This is to track
372 what has happened most recently, whether the most recent release
373 has been installed (system-wide), or (for me) whether most recent versions
374 of package and documentation have been released.
375 When such an `.RLS' file is installed together with packages
376 in the `tex' subtree of a \acro{TDS}, the release summary can be
377 accessed quickly as a \strong{terminal display}
378 by one of the packages \ctanpkgref{ltxfileinfo},
379 \ctanpkgref{latexfileversion}, or \ctanpkgref{typeoutfileinfo}.
380 One aim of the `[wrap]' option is allowing longer ``release captions"
381 (looking fine in the package file list) than fit into a small part
382 of a single line.
383 \end{enumerate}
384 %
385 The above `SrcFILEs.txt' has been generated from the following version
386 of the \TeX\ script `srcfiles.tex':
387 \bigskip
388 \hrule
389 \verbatiminput{srcfiles.tex}
390 \smallskip
391 \hrule
392
393 \DontAddQuotes
394
395 \section{Implementation}
396 \subsection{Package File Header (Legalese)}
397 \input{nicefilelist.doc}
398
399 \pagebreak
400 \section{Credits}
401 \begin{enumerate} %% 2012/05/20
402 \item It was \ctanpkgauref{muench-hm}{\textsc{H.-Martin M\"{u}nch}}
403 who pointed out the shortcomings
404 of 'longnamefilelist' that the present package addresses -- thanks!
405 %% 2012/05/20:
406 \item For \textsc{Alois Kabelschacht} -- whose idea in
407 TUGboat~\textbf{8}~\#2\footnote{\tugbartref{tb08-2/tb18kabel}{%
408 ``&\expandafter\ vs.\ %% .\ 2012/12/12
409 &\let\ and &\def\ in Conditionals
410 and a Generalization of PLAIN's &\loop,"}
411 TUGboat Vol.~8 (1987), No.~2, pp.~184f.
412 (\urlhttpref{tug.org/TUGboat/tb08-2/tb18kabel.pdf})}
413 is used for v0.3 -- cf.\ the \ctanpkgref{dowith} documentation.
414 %% 2012/05/18:
415 \item Another idea from \textsc{H.-Martin M\"{u}nch}:
416 wrapping inside caption column.
417 Implemented by UL with help of \ctanpkgref{hardwrap} as option |wrap|.
418 \end{enumerate}
419
420 \section{Missing}
421 % \begin{enumerate} %% rm. 2012/10/29
422 % \item
423 The package once might provide \ctanpkgref{keyval}-style
424 optional arguments for \cs{listfiles} or even call \cs{listfiles}
425 automatically with 'keyval' package options.
426
427 Well, nicefilelist 2025/04/21 v0.9c \emph{does} introduce the options `sizes' and `hashes' for
428 |\listfiles|, because the recent kernel provides those!
429 (Works only for formats 2024-06-01 and newer.)
430 % \end{enumerate}
431 \end{document}
432
433 VERSION HISTORY
434
435 2012/03/20 for v0.1 started
436 2012/03/22 trying something
437 2012/03/23 for v0.1a without "aligning the dots" etc.
438 2012/05/18 for v0.30 Legalize -> Legalese; add. TODO "wrapping";
439 ref. to `latexfileinfo-pkgs'
440 2012/05/20 for v0.31 mention Kabelschacht
441 2012/05/20 for v0.4 on new package option [r]
442 2012/09/30 for v0.5 \MaxBaseEmptyList, doc. \pagebreak
443 2012/10/11 for v0.6 \MaxBaseEmptyList*, \AddQuotes
444 2012/10/29 for v0.7 "M\"{u}nch", one item less missing, MDabstract,
445 usage restructured and extended
446 2012/10/30 \listfiles
447 2012/12/12 for v0.7a vs.\
448 2022/12/05 for v0.8a accepts also the new date format with dashes
449 2023/01/06 for v0.9a regards |ver@@| for version; new option [autolength]
450 2023/02/13 for v0.9b bug-fix: file extension missed when |\input|
451 2025/04/21 for v0.9c implement the |\listfiles| options hashes \& sizes from kernel