summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-10-31 21:45:40 +0000
committerKarl Berry <karl@freefriends.org>2012-10-31 21:45:40 +0000
commit2769c57ab6c21c58cd9ba299282200a870e912f8 (patch)
tree3b995eb8ed13fdefab32d90f5107e9a7c2e8c462 /Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
parentfe292a00361ba423d6f6fa42be3d88782b664c0b (diff)
nicefilelist (31oct12)
git-svn-id: svn://tug.org/texlive/trunk@28141 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex')
-rw-r--r--Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex234
1 files changed, 192 insertions, 42 deletions
diff --git a/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex b/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
index d7fda80e25d..3f12835d7d5 100644
--- a/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
+++ b/Master/texmf-dist/source/latex/nicefilelist/nicefilelist.tex
@@ -1,38 +1,56 @@
-\ProvidesFile{nicefilelist.tex}[2012/10/11 documenting nicefilelist.sty]
+\ProvidesFile{nicefilelist.tex}[2012/10/30 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
+ \MakeJobDoc{18}%% 2012/10/30
{\SectionLevelTwoParseInput} }
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
-% \ReadPackageInfos{nicefilelist}
-\usepackage{nicefilelist}
+\usepackage[wrap]{nicefilelist} \listfiles
+%% <- 2012/10/30 try without 'myfilist'
+\MDkeywords{Package management, document management, plain text output}
\sloppy
\begin{document}
\maketitle
-\begin{abstract}\noindent
+\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"
+(i)~date, (ii)~version, and (iii)~``caption" %% 1st , 2012/10/30
(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}
+% 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 filenames and captions can be quite long without disturbing alignment.
+
+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, ahm, related packages---rather brief{}ly.
-The \ctanpkgref{latexfileinfo-pkgs} package provides a more general overview.
-%% <- 2012/05/18
+% We are describing relations to, ahm, related packages---rather brief{}ly.
+% 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
@@ -61,37 +79,121 @@ putting it somewhere where \TeX\ finds it
base).\urlfoot{ukfaqref}{inst-wlcf}
\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', or `r,wrap'~\dots---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, see~Sec.~\ref{sec:myfilist},
+\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 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{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' for the date is assumed;
+in fact, when <f-info> doesn't 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|. 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}.
+
+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
-\subsection{Usage and Sample with 'myfilist.sty'}
+\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 don't 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
+(``\Wikienref{not invented here}"). 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 doesn't 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).
+
+\subsection{Usage and Samples with 'myfilist.sty'}
\label{sec:myfilist}
\subsubsection{Basically}
-In order to get a reduced and/or rearranged list of used files
+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).
+ 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:
+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}}
@@ -113,7 +215,8 @@ with \LaTeX:
\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}).
+for alignment (Section~\ref{sec:templates}) or failure displays
+(Section~\ref{sec:fail}).
The previous code mentions the following files:
\begin{description}
@@ -154,7 +257,7 @@ nicefilelist.tex 2012/03/23 -- \rlap{documenting nicefilelist.sty}
\AddQuotes %% 2012/10/11
In the above example, the 'myfilist' command `\EmptyFileList'
-is missing---it is not intended there. Usually however,
+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
@@ -169,9 +272,7 @@ lines is wanted:
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.
+according to Section~\ref{sec:templates}.
With v0.5, the last three code lines in the snippet above
can be replaced by
@@ -192,14 +293,59 @@ 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 %% 2012/09/30
+% \pagebreak %% 2012/09/30 rm. 2012/10/29
\section{Credits}
\begin{enumerate} %% 2012/05/20
- \item It was \textsc{Martin Muench} who pointed out the shortcomings
+ \item It was \ctanpkgauref{muench-hm}{\textsc{Martin M\"unch}}
+ who pointed out the shortcomings
of 'longnamefilelist' that the present package addresses---thanks!
%% 2012/05/20:
\item For \textsc{Alois Kabelschacht}---whose idea in
@@ -212,14 +358,15 @@ with \ctanpkgref{inputtrc} v/r0.3.
\end{enumerate}
\section{Missing}
-\begin{enumerate}
- \item The package once might provide \ctanpkgref{keyval}-style
+% \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.
- %% 2012/05/18:
- \item Another idea from \textsc{Martin Muench}: wrapping inside caption column.
- Can \ctanpkgref{hardwrap} help?
-\end{enumerate}
+% %% 2012/05/18:
+% \item Another idea from \textsc{Martin Muench}: wrapping inside caption column.
+% Can \ctanpkgref{hardwrap} help?
+% \end{enumerate}
\end{document}
@@ -234,3 +381,6 @@ VERSION HISTORY
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nch", one item less missing, MDabstract,
+ usage restructured and extended
+2012/10/30 \listfiles