summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
blob: 1673621ac955dbcabd07ec29b9027b7b2c04541e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
\ProvidesFile{nicefilelist.tex}[2012/03/23 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}
\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 and Calling}
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} 

Below the `\documentclass' line(s) and above `\begin{document}',
you load 'nicefilelist.sty' (as usually) by
\begin{verbatim}
  \usepackage{nicefilelist}
\end{verbatim}
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 
\begin{verbatim}
  \RequirePackage{nicefilelist}
\end{verbatim}
before `\documentclass' or when you don't use `\documentclass'. 

\subsection{Usage and Sample with 'myfilist.sty'}
\label{sec:myfilist}
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}


% \section{Example}
% TODO
\section{Implementation}
\subsection{Package File Header (Legalize)}
\input{nicefilelist.doc}

\section{Credit}
It was \textsc{Martin Muench} who pointed out the shortcomings of 'longnamefilelist'
that the present package addresses---thanks!

\section{Missing}
The package once might provide \ctanpkgref{keyval}-style optional arguments for \cs{listfiles}
or even call \cs{listfiles} automatically with 'keyval' package options.

\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.