nicefilelist update 13Oct

git-svn-id: svn://tug.org/texlive/trunk@27959 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 262 insertions, 5 deletions

diff --git a/Master/texmf-dist/doc/latex/nicefilelist/SrcFILEs.txt b/Master/texmf-dist/doc/latex/nicefilelist/SrcFILEs.txt
index 781b455515b..c92c8c1f2cf 100644
--- a/Master/texmf-dist/doc/latex/nicefilelist/SrcFILEs.txt
+++ b/Master/texmf-dist/doc/latex/nicefilelist/SrcFILEs.txt
@@ -1,17 +1,17 @@
 
      *File List*
-nicefilelist.sty  2012/09/30  v0.5   more file list alignment (UL)
+nicefilelist.sty  2012/10/03  v0.6   more file list alignment (UL)
     monofill.sty  2012/03/29  v0.1a  monospace alignment (UL)
-    myfilist.sty  2012/05/26  v0.4   \listfiles -- mine only (UL)
+    myfilist.sty  2012/10/11  v0.6   \listfiles -- mine only (UL)
     readprov.sty  2012/03/20  v0.3b  file infos without loading (UL)
-nicefilelist.tex  2012/05/20   --    documenting nicefilelist.sty
+nicefilelist.tex  2012/10/11   --    documenting nicefilelist.sty
     provonly.fd    --  -- --   --    such
        wrong.prv   * NOT FOUND *
        empty.f     * NOT FOUND *
     srcfiles.tex  2012/05/20   --    file infos -> SrcFILEs.txt
-nicefilelist.RLS  2012/10/01  r0.5   v0.5 \MaxBaseEmptyList
+nicefilelist.RLS  2012/10/11  r0.6   v0.6 \MaxBaseEmptyList*
      ***********
 
- List made at 2012/10/01, 08:57
+ List made at 2012/10/11, 16:33
  from script file srcfiles.tex
 
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/empty.f b/Master/texmf-dist/doc/latex/nicefilelist/empty.f
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicefilelist/empty.f
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.pdf b/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.pdf
index f72d758866f..a83c1d15cda 100644
--- a/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.pdf
+++ b/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.pdf
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.tex b/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.tex
new file mode 100644
index 00000000000..d7fda80e25d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicefilelist/nicefilelist.tex
@@ -0,0 +1,236 @@
+\ProvidesFile{nicefilelist.tex}[2012/10/11 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}.}}
+% \listfiles
+{ \RequirePackage{makedoc} \ProcessLineMessage{}
+  \MakeJobDoc{19}%% 2012/03/21
+  {\SectionLevelTwoParseInput}  }
+\documentclass[fleqn]{article}%% TODO paper dimensions!?
+\input{makedoc.cfg} %% shared formatting settings
+% \ReadPackageInfos{nicefilelist}
+\usepackage{nicefilelist}
+\sloppy
+\begin{document}
+\maketitle
+\begin{abstract}\noindent
+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" 
+(don't 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.
+\end{abstract}
+\tableofcontents
+\section{Features and Usage}
+We are describing relations to, ahm, related packages---rather brief{}ly. 
+The \ctanpkgref{latexfileinfo-pkgs} package provides a more general overview.
+%% <- 2012/05/18
+\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 Sec.~\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).\urlfoot{ukfaqref}{inst-wlcf} 
+
+\subsection{Calling}
+
+Below the `\documentclass' line(s) and above `\begin{document}',
+you load 'nicefilelist.sty' (as usually) by
+\[`\usepackage{nicefilelist}'\]
+Alternatively---e.g., for use with \ctanpkgref{myfilist} from the 
+\ctanpkgref{fileinfo} bundle, see~Sec.~\ref{sec:myfilist}, 
+or in order to include the `.cls' file in the list---you may load it by 
+\[`\RequirePackage{nicefilelist}'\]
+before `\documentclass' or when you don't use `\documentclass'. 
+
+As of v0.4, there is a package option |[r]| in order to place 
+strings like `r0.4' in the column reserved for version numbers. 
+You get this functionality by 
+\[`\usepackage[r]{nicefilelist}'\]
+or
+\[`\RequirePackage[r]{nicefilelist}'\]
+See Section~\ref{sec:opt} for more information.
+
+\subsection{Usage and Sample with 'myfilist.sty'}
+\label{sec:myfilist}
+\subsubsection{Basically}
+In order to get a reduced and/or rearranged list of used files 
+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 distribution of 'longnamefilelist',
+e.g., can be 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 (Sec.~\ref{sec:templates}) or failure displays (Sec.~\ref{sec:failure}).
+
+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}\tt
+\obeyspaces\obeylines
+~    *File List*
+nicefilelist.sty  2012/03/23  v0.1   \rlap{more file list alignment (UL)}
+~   monofill.sty  2012/03/19  v0.1a  monospace alignment (UL)
+~   myfilist.sty  2011/01/30  v0.3a  \rlap{\cs{listfiles} -- mine only (UL)}
+~   readprov.sty  2010/11/27  v0.3   \rlap{file infos without loading (UL)}
+nicefilelist.tex  2012/03/23   --    \rlap{documenting nicefilelist.sty}
+~   provonly.fd    --  -- --   --    such 
+~      wrong.prv   * NOT FOUND *
+~      empty.f     * NOT FOUND *
+~   srcfiles.tex  2012/03/23   --    file infos -> SrcFILEs.txt
+~    ***********
+~
+~List made at 2012/03/23, 10:31
+~from script file srcfiles.tex
+\end{small}
+%% TODO update example!?
+%%
+\subsubsection{More Generally and Shorthand}
+\label{sec:short}
+
+\AddQuotes                          %% 2012/10/11
+
+In the above example, the 'myfilist' command `\EmptyFileList'
+is missing---it is not intended there. Usually however, 
+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}. While there are also 
+field identifiers |f-ext| and |f-version|, it seems that only 
+|f-base| varies between real-life applications.
+
+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.
+
+\section{Implementation}
+\subsection{Package File Header (Legalese)}
+\input{nicefilelist.doc}
+
+\pagebreak          %% 2012/09/30
+\section{Credits}
+\begin{enumerate}   %% 2012/05/20
+  \item It was \textsc{Martin Muench} 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. &\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.
+\end{enumerate}
+
+\section{Missing}
+\begin{enumerate}
+  \item The package once might provide \ctanpkgref{keyval}-style 
+        optional arguments for \cs{listfiles} or even call \cs{listfiles} 
+        automatically with 'keyval' package options.
+  %% 2012/05/18:
+  \item Another idea from \textsc{Martin Muench}: wrapping inside caption column. 
+        Can \ctanpkgref{hardwrap} help?
+\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
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/provonly.fd b/Master/texmf-dist/doc/latex/nicefilelist/provonly.fd
new file mode 100644
index 00000000000..2b07688d8dc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicefilelist/provonly.fd
@@ -0,0 +1,2 @@
+% \ProvidesFile{provonly.fd}[2012/03/22 v0.11a such]
+\ProvidesFile{provonly.fd}[such]
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/srcfiles.tex b/Master/texmf-dist/doc/latex/nicefilelist/srcfiles.tex
new file mode 100644
index 00000000000..75cb27a5f82
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicefilelist/srcfiles.tex
@@ -0,0 +1,18 @@
+\ProvidesFile{srcfiles.tex}[2012/05/20 file infos -> SrcFILEs.txt]
+\RequirePackage[r]{nicefilelist}
+\RequirePackage[no-bot]{myfilist}
+% \EmptyFileList[nicefilelist.sty] %%% [readprov.sty,myfilist.sty]
+%% packages:
+% \ReadPackageInfos{nicefilelist}
+%% documentation:
+\ReadFileInfos{nicefilelist}
+%% Test:
+\ReadFileInfos{provonly.fd,wrong.prv,empty.f}
+% \ReadFileInfos{utopia.xxx}
+%% documentation settings and auxiliaries:
+% \ReadPackageInfos{fifinddo,makedoc,niceverb}
+% \ReadFileInfos{makedoc.cfg,mdoccorr.cfg}
+\ReadFileInfos{srcfiles}
+\ReadFileInfos{nicefilelist.RLS} %% 2012/05/18
+\ListInfos[SrcFILEs.txt]
+
diff --git a/Master/texmf-dist/doc/latex/nicefilelist/wrong.prv b/Master/texmf-dist/doc/latex/nicefilelist/wrong.prv
new file mode 100644
index 00000000000..166454f5c82
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicefilelist/wrong.prv
@@ -0,0 +1 @@
+\ProvidesFile{diffname.prv}[2012/03/23 v0.1 wrong]