\ProvidesFile{nicefilelist.tex}[2025/04/21 documenting nicefilelist.sty]
\title{\pkg{\huge nicefilelist.sty
       }\\ -- \\\cs{listfiles} Alignment for Connoisseurs\thanks{This
       document describes version
       \textcolor{blue}{\UseVersionOf{\jobname.sty}}
       of \pkg{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
{ \RequirePackage{makedoc} \ProcessLineMessage{}
  \MakeJobDoc{18}%% 2012/10/30
  {\SectionLevelTwoParseInput}  }
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
\usepackage[wrap]{nicefilelist} \listfiles
%% <- 2012/10/30 try without 'myfilist'
\MDkeywords{Package management, document management, plain text output}
\sloppy
\begin{document}
\maketitle
\begin{MDabstract}
While \CtanPkgRef{longnamefilelist}{longnamefilelist.sty}
improves \LaTeX's \cs{listfiles} with respect to long base filenames only,
'nicefilelist.sty' can keep separate columns for
(i)~date, (ii)~version, and (iii)~``caption" %% 1st, 2012/10/30
(do not write caption text in date column),
their alignment not being disturbed by short filename extensions such as `.fd'.
This is achieved basing on the \ctanpkgref{monofill} package.

% Thus 'nicefilelist' is more ``powerful" than 'longnamefilelist',
% the former however is an ``extension" of the latter
% neither with respect to implementation nor with respect to user interface.

%% <- 2012/10/29 ->
v0.7 offers a package option `[wrap]' for automatic word wrapping
within the caption column, using the \ctanpkgref{hardwrap} package,
so file names and captions can be quite long without disturbing
the alignment.

v0.9a offers a package option `[autolength]' for automatic sizing
of the columns, using the \ctanpkgref{xstring} package.

v0.9c offers the options `[hashes]' and/or `[sizes]' to the
`\listfiles' command, `\listfiles[hashes,sizes]', as provided
by \LaTeX{} release 2024-06-01, see \LaTeX{} News Issue~39 at
\url{https://www.latex-project.org/news/latex2e-news/ltnews39.pdf}.

As opposed to the \ctanpkgref{dateiliste} package, this is about the
\meta{plain text} output in the `.log' file or, with \ctanpkgref{myfilist},
as a stand-alone plain text file.

\MDaddtoabstract{Related packages}Cf.~\ctanpkgref{latexfileinfo-pkgs}.
\end{MDabstract}
\tableofcontents
\section{Features and Usage}
% We are describing relations to related packages - rather briefly.
% The \ctanpkgref{latexfileinfo-pkgs} package provides a more general overview.
% %% <- 2012/05/18
%% 2012/10/29:
Additionally or also ``complementarily" to the presentation given here,
the functionality of the package is summarized in the file
`latexfileinfo_pkgs.htm' from the \ctanpkgref{latexfileinfo-pkgs},
in a comparison with packages resembling `nicefilelist' in
certain respects.

\subsection{Relation to 'longnamefilelist.sty'}
\CtanPkgRef{longnamefilelist}{longnamefilelist.sty} equips
\cs{listfiles} with an optional argument for the maximum number of characters
in the base filename. By contrast, 'nicefilelist' does not provide
arguments for \cs{listfiles}, rather column widths for basename, extension,
and version number are determined by \emph{templates} using
\CtanPkgRef{monofill}{monofill.sty}. As a ``template" for doing this,
see the initial settings in section~\ref{sec:templates}.
(Such settings must precede the \cs{listfiles command})
So 'nicefilelist''s \emph{user interface} (at present) does not \emph{extend}
'longnamefilelist''s user interface.

Using 'monofill' is a very different approach than the one of 'longnamefilelist'.
'nicefilelist' is more powerful than 'longnamefilelist', but is not based on it
in any way. It does not make sense to load both packages, they just overwrite
each other's behaviour of \cs{listfiles}.

'longnamefilelist' may become ``obsolete" by the present package,
unless one finds that its version of \cs{listfiles} looks fine enough
and it is easier to understand and to use than 'nicefilelist'.

\subsection{Installing}
The file 'nicefilelist.sty' is provided ready, installation only requires
putting it somewhere where \TeX\ finds it
(which may need updating the filename data base).

\subsection{Calling}
%% restructured for v0.7 2012/10/29:
Below the `\documentclass' line(s) and above `\begin{document}',
you load 'nicefilelist.sty' (as usually) by
\[`\usepackage{nicefilelist}'\]
or by
\[`\usepackage[<options>]{nicefilelist}'\]
where <options> may be `r', `wrap', and/or `autolength' -- see
summaries in sections~\ref{sec:set} and \ref{sec:opt}
on the package options and an example in section~\ref{sec:short}.
Alternatively -- e.g., for use with \ctanpkgref{myfilist} from the
\ctanpkgref{fileinfo} bundle (in a ``\TeX~script"), see section~\ref{sec:myfilist},
or in order to include the `.cls' file in the list -- you may load it by
\[`\RequirePackage{nicefilelist}'\]
or by
\[`\RequirePackage[<options>]{nicefilelist}'\]
before `\documentclass' or when you do not use `\documentclass'.

\subsection{Choosing Settings}                      %% new 2012/10/29
\label{sec:set}

\subsubsection{The Columns, Their Widths, and Their ``Missing" Content}
\label{sec:cols}

\AddQuotes                          %% 2012/10/29

The 'nicefilelist' package considers the listing from `\listfiles'
a five-column table, the columns being (reserved for) \\
(i)~the base filename, \\ (ii)~the filename extension, \\
(iii)~the date, \\
(iv)~the version (or with option `[r]': the release) number, and \\
(v)~the caption \\ of a \LaTeX\ source file. The filename base column
is right-adjusted, the other ones are left-adjusted.
Date, version, and caption are made up from the <f-info> argument in
\[|\Provides<f-type>{<f-base>.<f-ext>}[<f-info>|]\]
where <f-type> is `Class', `Package', or `File'.

The fixed usual format `YYYY/MM/DD'
or `YYYY-MM-DD' (accepted by \LaTeX\ since 2017-03-08)
for the date is assumed;
in fact, when <f-info> does not start according to this format,
it is assumed that no date is given, and some ``missing''
text will appear in the ``date" column, determined by a macro
|\NFLnodate|.
\pagebreak

Using the filemod package, it is possible to use the date
of a file which does not explicitly declare a date:

\begin{verbatim}
\makeatletter
\RequirePackage{filemod}%
\renewcommand*\thefilemoddate[3]{#1-#2-#3}
\renewcommand*{\NFLnodate}{\filemodprintdate{%
               \filename@area\filename@base.\filename@ext}}
\makeatother
\renewcommand*{\NFLnotfound}{%
               \NFLnodate\NFLspaceII\NFLnoversion\NFLspaceIII}
\end{verbatim}

The version number
(or ``string") must follow in format `v<digit>.<digits>',
otherwise some ``missing" text appears in the ``version" column,
determined by a macro |\NFLnoversion|.
What remains is placed in the ``caption" column.
|\NFLnotfound| determines an alternative filling
in the case that <f-info> cannot be obtained.
See the default settings for these ``failure" texts in
section~\ref{sec:fail}.

The column widths for filename base and extension
and the column width for version or release
are determined using the \ctanpkgref{monofill} package.
They have ``field identifiers" |f-base|, |f-ext|,
and |f-version| respectively. The respective widths are
determined by templates <longest> in
\[|\MDfieldtemplate{<field-id>}{<longest>}|\]
See section~\ref{sec:templates} for the default settings.
Probably only adjusting the width for \emph{base} filenames
is required in real life, see the example in section~\ref{sec:short}.
(But there exist extensions .info and .mkii and versions
v4.6.3.1 (fontawesome.sty).)
%% 2023-01-06
Option `autolength' measures the respective length of the field and
writes it into the .aux file for use in the next compilation run.
This option requires \LaTeX{} format-version at least 2022-11-01.

The spaces between the columns are determined by macros
|\NFLspaceI|, |\NFLspaceII|, and |\NFLspaceIII|,
see section~\ref{sec:templates} for the defaults.

\DontAddQuotes              %% 2012/10/29

\subsubsection{The Caption Column}
The width of the caption column (unfortunately) is determined by
the stuff enumerated above and the width of the console output window or screen.
With long filenames and long captions, the result may look poor.
The \emph{characters} that do not fit into the line may continue
at left end of the window or screen, disturbing the appearance
of a ``table" -- unless you use package option |[wrap]|.
The latter requires the \ctanpkgref{hardwrap} package by
Will Robertson and Kevin Godby. This package tries to determine
the screen width by some subtle tests, and until it finds something
better, it assumes a width of 80~characters (I~suppose).
'hardwrap' does \wikienref{Word wrap}{\emph{word wrapping}},
i.e., it does not just put \emph{characters} not fitting into the
next line, but entire \emph{words}. Moreover, it allows inserting
some ``newline sequence" before the first word that is too much,
and we use this feature here to put the next word into the
\emph{caption column} rather than at the beginning of the next line.
(Details and implementation are in section~\ref{sec:opt}.)

If you are not happy with the column width that 'hardwrap'
chooses, but want to assume your own width <max-line-chars>
(e.g., your width, measured by your doctor, divided by the
 width of one character),
compute its difference <max-line-chars-minus-one> to 1
(maybe by your electronic calculator, or an emulation,
or a Lua script, cf.~\ctanpkgref{lualatex-doc}, or by
\ctanpkgref{bigintcalc}), and enter
the 'hardwrap' instruction
\[|\setmaxprintline{<max-line-chars-minus-one>}|\]
when 'hardwrap' or 'nicefilelist' have been loaded
\emph{and} before the internal macro `\@dofilelist' is run
(which happens at the end of the document or when
\ctanpkgref{myfilist}'s `\ListInfos' is issued, for instance).

\subsubsection{Extended information in \texttt{listfiles}}
Since \LaTeX{} release 2024-06-01 the |\listfiles| command
takes the option `hashes' to give the MD5 hash and
`sizes' to give the file size of each file in the `.log',
printed after the end of the caption (in a new line);
see \LaTeX{} News Issue~39 at
\url{https://www.latex-project.org/news/latex2e-news/ltnews39.pdf}.

\subsection{Usage and examples with 'myfilist.sty'}
\label{sec:myfilist}
\subsubsection{Basically}
In order to get a reduced and/or rearranged list of file infos
with the \ctanpkgref{myfilist} package,
`nicefilelist.sty' must be loaded earlier than
`myfilist.sty'. This is due to a kind of limitation of the latter,
it \emph{issues} `\listfiles' (\TODO).
Therefore \cs{listfiles} must be modified earlier -- or \emph{issued} earlier,
in this case the \cs{listfiles} in `myfilist.sty' does nothing.
The file `SrcFILEs.txt' accompanying the -- first -- distribution of
'nicefilelist' %% corr., was `longname'; `first' etc. 2012/10/29
was generated by running the following file `srcfiles.tex' with \LaTeX:
\begin{quotation}\tt\small
\expandafter\def\expandafter\{\expandafter{\string{}
\expandafter\def\expandafter\}\expandafter{\string}}
\obeyspaces\obeylines
\cs{ProvidesFile}\{srcfiles.tex\}[2012/03/23
 ~                           file infos -\empty> SrcFILEs.txt]
\cs{RequirePackage}\{nicefilelist\}
\%\% INSERT MODIFICATIONS OF INITIAL
\%\% \verb+`nicefilelist'/`monofill'+ SETTINGS HERE!
\cs{RequirePackage}\{myfilist\}
\%\% documentation:
\cs{ReadFileInfos}\{nicefilelist\}
\%\% demonstration:
\cs{ReadFileInfos}\{provonly.fd,wrong.prv,empty.f\}
\% \cs{ReadFileInfos}\{utopia.xyz\}
\%\% present file:
\cs{ReadFileInfos}\{nicefilelist\}
\cs{ReadFileInfos}\{srcfiles\}
\cs{ListInfos}[SrcFILEs.txt]
\end{quotation}
Note the lines where to place \strong{custom} modifications of settings
for alignment (section~\ref{sec:templates}) or failure displays
(section~\ref{sec:fail}).

The previous code mentions the following files:
\begin{description}
  \item[`provonly.fd'] has a proper `\ProvidesFile' line without date,
                       for seeing what happens in the date and version columns.
                       It also was a test for the case that there are fewer
                       characters than a date has, and there is no blank space.
  \item[`wrong.prv']   has a `\ProvidesFile' line with wrong file name.
  \item[`empty.f']     just is an empty file.
  \item[`utopia.xyz']  is not present at all, you get an error when you remove
                       the comment mark.
\end{description}
Moreover, my `.tex' files have dates, but not version numbers,
so you see what happens then:
\vskip\topsep
\begin{small}
\begin{verbatim}
     *File List*
-----RELEASE.---   --  -- --   --     -- 
nicefilelist.RLS  2025/04/21  v0.9c  options sizes \& hashes for \listfiles
-----PACKAGE.---   --  -- --   --     -- 
nicefilelist.sty  2025/04/21  v0.9c  More file list alignment (UL; HMM)
------DOCSRC.---   --  -- --   --     -- 
nicefilelist.tex  2025/04/21   --    documenting nicefilelist.sty
    srcfiles.tex  2025/04/21   --    file infos -> SrcFILEs.txt
--------DEMO.---   --  -- --   --     -- 
    provonly.fd    --  -- --   --    no date, no version, but a lot of info,
                                     look how that is wrapped!
       wrong.prv   * NOT FOUND *     
       empty.f     * NOT FOUND *     
--------USED.---   --  -- --   --     -- 
    hardwrap.sty  2011/02/12  v0.2   Hard wrap messages
    myfilist.sty  2012/11/22  v0.71  \listfiles -- mine only (UL)
    readprov.sty  2012/11/22  v0.5   file infos without loading (UL)
    fifinddo.sty  2012/11/17  v0.61  filtering TeX(t) files by TeX (UL)
     makedoc.sty  2012/08/28  v0.52  TeX input from *.sty (UL)
    niceverb.sty  2012/11/27  v0.51  minimize doc markup (UL)
    texlinks.sty  2013/01/22  v0.82  TeX-related links (UL)
     makedoc.cfg  2012/11/30   --    documentation settings
    mdoccorr.cfg  2012/11/13   --    `makedoc' local typographical corrections
-not-so-much.---   --  -- --   --     -- 
   kvsetkeys.sty  2012/04/25  v1.16  Key value parser (HO)
     ***********

 List made at 2025/04/21, 19:16
 from script file srcfiles.tex
\end{verbatim}
\end{small}

\subsubsection{More Generally and Shorthand}
\label{sec:short}

\AddQuotes                          %% 2012/10/11

In the above example, the 'myfilist' command `\EmptyFileList'
was missing -- it was not intended there. Usually however, %% is -> was 2012/10/29
it \emph{is} intended, i.e., the following sequence of
lines is wanted:
\begin{quotation}\tt\small
\expandafter\def\expandafter\{\expandafter{\string{}
\expandafter\def\expandafter\}\expandafter{\string}}
\obeyspaces\obeylines
\cs{RequirePackage}[r]\{nicefilefilelist\}
\cs{MFfieldtemplate}\{f-base\}[<longest-name>]
\cs{RequirePackage}\{myfilist\}
\cs{EmptyFileList}[<read-again-files>]
\end{quotation}
Here you also see usage of package option |[r]| for
release numbers and the adjustment
   \[|\MFfieldtemplate{f-base}{<longest-name>}|\]
according to section~\ref{sec:templates}.

With v0.5, the last three code lines in the snippet above
can be replaced by
\[|\MaxBaseEmptyList{<longest-name>}[<read-again-files>]|\]
\ -- ``optionally" without `[<read-again-files>]'.
This may save the user from worrying about usage
with 'myfilist'.

\DontAddQuotes

'nicefilelist' formats file lists nicely
even when base filenames have eight characters at most,
what \LaTeX's original `\listfiles' was made for.
v0.6 simplifies this case by a star version of `\MaxBaseEmptyList':
\pagebreak[2]
\[|\MaxBaseEmptyList*|\]
works like `\MaxBaseEmptyList{nicefile}' (eight characters) -- still,
optional `[<read-again-files>]' may follow. This feature is demonstrated
with \ctanpkgref{inputtrc} v/r0.3.

\subsubsection{Sample with Wrapped Caption Column} %% 2012/10/30

\AddQuotes

The most recent version of the accompanying `SrcFILEs.txt' contains
the following:
\bigskip
\begingroup \footnotesize
\hrule
\verbatiminput{SrcFILEs.txt}
\hrule
\endgroup
\bigskip

This exemplifies
\begin{enumerate}
  \item \strong{wrapping} of `provonly.fd''s and \ctanpkgref{kvsetkeys}\file{.sty}
        file info within the \strong{caption} column
        using 'nicefilelist''s `[wrap]' option,
  \item inserted ``\strong{comments}" from \ctanpkgref{myfilist}'s `\FileListRemark',
  \item a file `nicefilelist.RLS' for a \strong{release summary}. This is to track
        what has happened most recently, whether the most recent release
        has been installed (system-wide), or (for me) whether most recent versions
        of package and documentation have been released.
        When such an `.RLS' file is installed together with packages
        in the `tex' subtree of a \acro{TDS}, the release summary can be
        accessed quickly as a \strong{terminal display}
        by one of the packages \ctanpkgref{ltxfileinfo},
        \ctanpkgref{latexfileversion}, or \ctanpkgref{typeoutfileinfo}.
        One aim of the `[wrap]' option is allowing longer ``release captions"
        (looking fine in the package file list) than fit into a small part
        of a single line.
\end{enumerate}
%
The above `SrcFILEs.txt' has been generated from the following version
of the \TeX\ script `srcfiles.tex':
\bigskip
\hrule
\verbatiminput{srcfiles.tex}
\smallskip
\hrule

\DontAddQuotes

\section{Implementation}
\subsection{Package File Header (Legalese)}
\input{nicefilelist.doc}

\pagebreak
\section{Credits}
\begin{enumerate} %% 2012/05/20
  \item It was \ctanpkgauref{muench-hm}{\textsc{H.-Martin M\"{u}nch}}
        who pointed out the shortcomings
        of 'longnamefilelist' that the present package addresses -- thanks!
  %% 2012/05/20:
  \item For \textsc{Alois Kabelschacht} -- whose idea in
        TUGboat~\textbf{8}~\#2\footnote{\tugbartref{tb08-2/tb18kabel}{%
            ``&\expandafter\ vs.\               %% .\ 2012/12/12
            &\let\ and &\def\ in Conditionals
            and a Generalization of PLAIN's &\loop,"}
            TUGboat Vol.~8 (1987), No.~2, pp.~184f.
            (\urlhttpref{tug.org/TUGboat/tb08-2/tb18kabel.pdf})}
        is used for v0.3 -- cf.\ the \ctanpkgref{dowith} documentation.
   %% 2012/05/18:
   \item Another idea from \textsc{H.-Martin M\"{u}nch}:
         wrapping inside caption column.
         Implemented by UL with help of \ctanpkgref{hardwrap} as option |wrap|.
\end{enumerate}

\section{Missing}
% \begin{enumerate} %% rm. 2012/10/29
%   \item
        The package once might provide \ctanpkgref{keyval}-style
        optional arguments for \cs{listfiles} or even call \cs{listfiles}
        automatically with 'keyval' package options.
        
        Well, nicefilelist 2025/04/21 v0.9c \emph{does} introduce the options `sizes' and `hashes' for
        |\listfiles|, because the recent kernel provides those!
        (Works only for formats 2024-06-01 and newer.)
% \end{enumerate}
\end{document}

VERSION HISTORY

2012/03/20  for v0.1    started
2012/03/22              trying something
2012/03/23  for v0.1a   without "aligning the dots" etc.
2012/05/18  for v0.30   Legalize -> Legalese; add. TODO "wrapping";
                        ref. to `latexfileinfo-pkgs'
2012/05/20  for v0.31   mention Kabelschacht
2012/05/20  for v0.4    on new package option [r]
2012/09/30  for v0.5    \MaxBaseEmptyList, doc. \pagebreak
2012/10/11  for v0.6    \MaxBaseEmptyList*, \AddQuotes
2012/10/29  for v0.7    "M\"{u}nch", one item less missing, MDabstract,
                        usage restructured and extended
2012/10/30              \listfiles
2012/12/12  for v0.7a   vs.\ 
2022/12/05  for v0.8a   accepts also the new date format with dashes
2023/01/06  for v0.9a   regards |ver@@| for version; new option [autolength]
2023/02/13  for v0.9b   bug-fix: file extension missed when |\input|
2025/04/21  for v0.9c   implement the |\listfiles| options hashes \& sizes from kernel