path: root/info/ltx3pub/vt02d01.tex

%%% ====================================================================
%%%  @LaTeX3-article{  LaTeX3-VT02-01,
%%%  filename        = "vt02d01.tex",
%%%  archived        = "ctan:/tex-archive/info/ltx3pub/",
%%%  author          = "Daniel Flipo",
%%%  doc-group       = "Volunteer Task VT02",
%%%  title           = "Validation of {\LaTeX}~2.09
%%%                     as part of the {\LaTeX3} project",
%%%  version         = "1.02",
%%%  date            = "25 March 1993",
%%%  time            = "17:21:04 MET",
%%%  status          = "public, contributed",
%%%  author-email    = "flipo@alea.citilille.fr",
%%%  author-address  = "Daniel Flipo, UFR de Math\'ematiques B\^at M2,
%%%                     Universit\'e des Sciences et Technologies
%%%                     F-59655 Villeneuve d'Ascq Cedex",
%%%  abstract        = "This is both a call for volunteers to help
%%%                     us in validating \LaTeX~2.09 (one of the
%%%                     tasks of the \LaTeX3 project), and a brief
%%%                     explanation of the kind of work to be done
%%%                     in this area.  ",
%%%  keywords        = "Validation, LaTeX",
%%%  project-address = "LaTeX3 Project            \\
%%%                     c/o Dr. Chris Rowley      \\
%%%                     The Open University       \\
%%%                     Parsifal College          \\
%%%                     Finchley Road             \\
%%%                     London NW3 7BG, England, UK",
%%%  project-tel     = "+44 171 794 0575",
%%%  project-FAX     = "+44 171 433 6196",
%%%  project-email   = "LTX3-Mgr@SHSU.edu",
%%%  copyright       = "Copyright (C) 1993 LaTeX3 Project
%%%                     and Daniel Flipo.
%%%                     All rights reserved.
%%%
%%%                     Permission is granted to make and distribute
%%%                     verbatim copies of this publication or of
%%%                     coherent parts from this publication provided
%%%                     this copyright notice and this permission
%%%                     notice are preserved on all copies.
%%%
%%%                     Permission is granted to copy and distribute
%%%                     translations of this publication or of
%%%                     individual items from this publication into
%%%                     another language provided that the translation
%%%                     is approved by the original copyright holders.
%%%
%%%                     No other permissions to copy or distribute this
%%%                     publication in any form are granted and in
%%%                     particular no permission to copy parts of it
%%%                     in such a way as to materially change its
%%%                     meaning.",
%%%  generalinfo     = "To subscribe to the LaTeX3 discussion list:
%%%
%%%                      Send mail to listserv@vm.urz.uni-heidelberg.de
%%%                      with the following line as the body of the
%%%                      message (substituting your own name):
%%%
%%%                        subscribe LaTeX-L First-name Surname
%%%
%%%                     To find out about volunteer work:
%%%
%%%                      look at the document vol-task.tex which can
%%%                      be obtained electronically, see below.
%%%
%%%                     To retrieve project publications electronically:
%%%
%%%                      Project publications are available for
%%%                      retrieval by anonymous ftp from ctan hosts:
%%%                          ftp.tex.ac.uk
%%%                          ftp.dante.de
%%%                          ftp.shsu.edu
%%%                      in the directory /tex-archive/info/ltx3pub.
%%%
%%%                      The file ltx3pub.bib in that directory gives
%%%                      full bibliographical information including
%%%                      abstracts in BibTeX format.  A brief history
%%%                      of the project and a description of its aims
%%%                      is contained in l3d001.tex.
%%%
%%%                     If you only have access to email, and not ftp
%%%                      You may use the ftpmail service.
%%%                      Send a message just containg the word
%%%                          help
%%%                      to ftpmail@ftp.shsu.edu
%%%                      for more information about this service.
%%%
%%%                     For offers of financial contributions or
%%%                      contributions of computing equipment or
%%%                      software, contact the project at the above
%%%                      address, or the TeX Users Group.
%%%
%%%                     For offers of technical assistance, contact the
%%%                      project at the above address.
%%%
%%%                     For technical enquiries and suggestions, send
%%%                      e-mail to the latex-l list or contact the
%%%                      project at the above address.",
%%%  checksum        = "36968 394 2248 16233",
%%%  docstring       = "The checksum field above contains a CRC-16
%%%                     checksum as the first value, followed by the
%%%                     equivalent of the standard UNIX wc (word
%%%                     count) utility output of lines, words, and
%%%                     characters.  This is produced by Robert
%%%                     Solovay's checksum utility.",
%%%  }
%%% ====================================================================
\documentstyle{l3ms001}

\title{Validation of \LaTeX~2.09\\
as part of the \LaTeX3 project}
\author{Daniel \sc Flipo\thanks{\tt flipo@alea.citilille.fr}}
\date{25 March 1993 \\
Version 1.02}

\begin{document}
\thispagestyle{empty}

\maketitle

%\vfill
\begin{abstract}
This is both a call for volunteers to help us in validating
\LaTeX~2.09 (one of the tasks of the \LaTeX3 project), and a brief
explanation of the kind of work to be done in this area.
\end{abstract}

%\vfill

\section{Task description}

The following is a short task description as it appears in the
volunteer task list document for the \LaTeX3 project~\cite{tub:MRD92}:
\begin{quote}
Writing test files for regression testing: checking bug fixes and
improvements to verify that they don't have undesirable
side effects; making sure that bug fixes really correct the problem
they were intended to correct; testing interaction with
various document styles, style options, and environments.

We would like three kinds of validation files:
\begin{enumerate}
\item General documents.
\item Exhaustive tests of special environments/modules such as tables,
displayed equations, theorems, floating figures, pictures, etc.
\item Bug files containing tests of all bugs that are supposed to be
fixed (as well as those that are not fixed, with comments about their
status).
\end{enumerate}
\end{quote}


\section{Introduction}

As coordinator of the task called ``Validating \LaTeX~2.09'', I would
like to invite some of the \LaTeX{} users to join our group. Some work
has been done already, but a lot remains to be done; at present only
two people are working on this task and I am afraid it is not enough
if we want to be able to complete the job in a reasonable amount of
time. The total amount of time required was estimated by
Frank~Mittelbach around 2 to 3 weeks, but Knuth's well known
correcting rule should probably be applied to these figures\dots

I expect that a small team of four to five persons, spending each a
limited amount of time for the project could be much more efficient
and complete the job by the end of~93 or even earlier.

This task does not require a \TeX{}pert (I'm not one myself but
\TeX{}perts are welcome!) and offers anybody wanting to help the
\LaTeX3 project a good opportunity to support this ambitious and
motivating project.

I imagine that anybody having taken part in the project, even in a
very tiny bit of it, will feel a lot happier using \LaTeX3 when it is
available and this pleasure will `overcompensate' the time spent.

\pagebreak[3]
\section{Goals and methods}

% borrowed from testing.ltx:
%%%%%%%%%%%%%%%%%%%%%%%%%%%
The idea is to have a suite of test files, each one exercising a
particular set of related commands. These should be called in such a
way that one can tell from the {\tt .log} file (not the {\tt .dvi}
file) that the command has `met its specification'. The {\tt .log}
file is then edited to remove certain irrelevant information and will
then be stored, as a {\tt .tlg} file. Before a new release is issued,
all the test files will be run through the new version, and the
resulting {\tt .tlg} files will be automatically compared with the
saved original versions. Any tests which do not produce identical
results will then be notified to the maintainer of
\LaTeX, who can visually compare the {\tt .tlg} files to see whether the
differences are due to an `improvement' or are the result of a newly
introduced bug!
%%%%%%%%%%%%%%%%%%%%%%%%%%%

The first thing we started with was to get the bug lists of the parts of
\LaTeX~2.09 which are used as basis for \LaTeX3, that is latex.tex, the
standard style files (article, book\dots), the so-called Mainz files
(nfss, array.sty, verbatim.sty\dots). The testing of reported problems
usually exercises tricky parts of the code and I believe that making
sure that the reported bugs are no longer present (or to {\em know}
that they are not corrected yet) is a better start than trying random
texts.

When I start a series of validation tests, I first copy all the bug
reports of the part I am testing into the {\tt .lvt} file (the
\LaTeX{} sourcefile containing the tests). Then, for each bug I try to
build a short text that is supposed to show the bug. If I can't
(either because I do not fully understand the bug report or for any
reason) I leave the bug report with no test following it, in order to
keep the full list of what should be tested; someday myself or
somebody else might find a way to check it.


What seemed not so easy (for me anyway) at the beginning was to manage
to get the meaningful information into the {\tt .log} file and not
just on the screen or the {\tt .dvi} file. Fortunately, Frank
Mittelbach provided an input file called test209.tex which contains
helpful macros and David Carlisle wrote a paper explaining what to
do~\cite{package:validate92}.

There are two main methods of passing relevant information to the {\tt
.log} file.

\subsection{The {\tt\char"5C showoutput} command}

The easiest way is to use the standard \LaTeX{} command
\verb|\showoutput|; all the material present in the part of the {\tt
.dvi} file following that command will appear in the {\tt .log} file.
The main drawback of this is that you get a huge {\tt .log} file
containing a lot of uninteresting things. Nevertheless I use this
command for instance when I am checking the contents of headers,
footnotes, margin notes or margin dimensions.

Here is an example: bugs 190 and 198 in latex.tex. The problem is the
use of fragile commands in a footnote. I make a (nearly) empty page
containing only a line of text calling the footnote.

\begin{verbatim}
%190. Fragile commands in the definition of \thefootnote led to
%an error, even with the use of \protect. (Found by Chris Hamlin.
%Corrected 1 Nov 91.)
%198. Fix 190 did not go far enough. (Found by Chris Rowley.
% Corrected 22 Nov 91.)
%

\newpage
{\end{verbatim}%
\verb|\bugid|\footnote{{\tt \char"5C bugid} is a command provided in
{\tt test209.tex} which prints its argument (the bug number), in both
{\tt .dvi} and {\tt .log} files.}%
\verb|{190-198}|
\begin{verbatim}
Let's make a footnote\footnote%
{This footnote includes fragile commands:\\
\begin{enumerate}
\item[\protect\( *   \protect\)] First,
\item[\protect\( **  \protect\)] second,
\item[\protect\( *** \protect\)] third.
\end{enumerate}
}

\showoutput

\newpage
}\nonstopmode
\end{verbatim}

The whole page is included in braces to restrict the scope of the
\verb|\showoutput|  command and prevent the following tests falling
into the {\tt .log} file.

\subsection{The {\tt\char"5C showbox} command}

Another possibility is to build a box containing just the material
related to one precise bug. Suppose you have privatized a box (one for
the whole test file) using the \TeX{} command
\begin{verbatim}
\newbox\test
\end{verbatim}
then you can use \verb|\setbox| to fill it with a \verb|\hbox| or
\verb|\vbox| containing your material, as in the following example
which deals with bugs 138, 158 and 217 of latex.tex:

\begin{verbatim}
%138. A command like \index or \label could incorrectly suppress a
%space after the next \end command. (Reported by Johannes Braams.
%Partially fixed on 30 Nov 88.  Problem can still occur if \index
%or \label command comes inside the \end's environment.)
%158. The fix mentioned in 138 was added to the comments, but not
%to the code.  (Reported by Piet van Oostrum in TeXhax V90 #42,
%corrected 2 May 90.)
%217. The fix mentioned in 138 and 158 was done wrong in the code.
%Also the problem was now corrected completely by introducing a
%new control sequence. (Suggested by Piet van Oostrum.
%Corrected 18 Mar 92.)
%
\bugid{138-158-217}

\setbox\test\vbox{%
This is a tabular environment\label{tab1}\\
\begin{tabular}{lcr}
aaa &bbb &ccc\label{tab2}\\
\end{tabular} followed by a space.
Compare with the same\\
\begin{tabular}{lcr}
aaa &bbb &ccc\label{tab3}\\
\end{tabular}NOT followed by a space.}

{\showboxdepth3\showboxbreadth999\showbox\test}

\box\test
\end{verbatim}

The command \verb|\showbox| copies the box to the {\tt .log} file and
the commands \verb|\showboxdepth| and \verb|\showboxbreath| allow you
to control the exact amount of information you want in the {\tt .log}
file (see the \TeX{}book p.~302 for the details).

\verb|\box\test| prints the box into the {\tt .dvi} file, so that you
can check the result on your previewer: the first tabular should be
followed by a space, and not the second.

\section{What is already done}

As mentioned above, we have chosen to first of all tackle the bug lists
of the main \LaTeX{} files. Tests already completed or about to be are:
\begin{itemize}
  \item {\tt nfss.tex} (version 1), a new version called {\tt nfss 2}
is about to be released, some new checking will probably be required.
\item {\tt latex.tex} most of the checking is done, the remaining part
is on the way.
\item the basic styles files are being checked by
Chris Martin\footnote{\tt c.martin@sheffield.ac.uk}.
\end{itemize}

All the {\tt .lvt} test files already completed, as well as the tools
provided by Frank Mittelbach, are of course available on request to
those who want to help us in validating \LaTeX~2.09.

\section{What remains to be done}

I would like to have the validation of the Mainz files completed as
the next step:
\begin{itemize}
  \item {\tt array.sty}
  \item {\tt ftn.sty}
  \item {\tt multicol.sty}
  \item {\tt theorem.sty}
  \item {\tt verbatim.sty}\footnote{%
very recently Mark Senn {\tt mds@stat.purdue.edu} volunteered to
 validate {\tt verbatim.sty}.}
\end{itemize}

Another direction would be (drifting apart from checking previous
bugs) exhaustive tests of special environments or modules such as
tables, floating figures, pictures etc.

It would also be interesting to imagine complicated combinations of
environments to check the robustness of \LaTeX~2.09 when different
environments interact together. If anybody has experience in this
area, having, for instance, found a workaround where \LaTeX{} doesn't
behave as would be expected or desirable, it would be of great
interest for us to hear about these experiments.

%\section{Rules to follow}

%--precise description of the environment


%\section{Conclusion}

%other tasks

%\bibliography{string,tub92,package}
%\bibliographystyle{plain}

\begin{thebibliography}{1}

\bibitem{package:validate92}
Frank Mittelbach and David Carlisle.
\newblock The {\tt validation} package.
\newblock Distribution of tools for automatic validation of changes
   in large macro packages, June 1992.

\bibitem{tub:MRD92}
Frank Mittelbach, Chris Rowley, and Michael Downes.
\newblock Volunteer work for the {\LaTeX3} project.
\newblock {\em {TUG}boat}, 13(4):510--515, December 1992.

\end{thebibliography}

\end{document}