Improve build script for amsmath

[latex2e.git] / latex2e-20160201 / doc / modguide.tex

% \iffalse meta-comment
%
% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file. 
% 
% This file is part of the LaTeX base system.
% -------------------------------------------
% 
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later.
% 
% This file has the LPPL maintenance status "maintained".
% 
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
% 
% The list of derived (unpacked) files belonging to the distribution 
% and covered by LPPL is defined by the unpacking scripts (with 
% extension .ins) which are part of the distribution.
% 
% \fi
% Filename: modguide.tex

\NeedsTeXFormat{LaTeX2e}[1995/12/01]
 
\documentclass{ltxguide}[1995/11/28]

\newcommand{\reasonsection}[1]{\subsubsection*{\it #1}}

\newcommand{\nstex}{\textsf{NS-TeX}}

\setcounter{secnumdepth}{-1}

\title{Modifying \LaTeX}
 
\author{\copyright~Copyright 1995, \LaTeX3 Project Team.\\
   All rights reserved.}
 
\date{12 December 1995}
 
\begin{document}
 
\maketitle
 
\tableofcontents

\begin{abstract}
  This document was produced in response to suggestions that the
  modification and distribution conditions for the files constituting
  the New Standard \LaTeX{} system should be similar to those implied
  by Version~2 of the \textsc{GNU} General Public Licence, as
  published by the Free Software Foundation.
\end{abstract}

\section{Introduction}
\label{sec:intro}

This article describes the principles underlying our policy on
distribution and modification of the files comprising the \LaTeX{}
system.  It has been produced as a result of detailed discussions of
the issues involved in the support and maintenance of a widely
distributed document processing system used by diverse people for many
applications.  These discussions have involved users, maintainers of
installations that support \LaTeX{} and various types of organisations
that distribute it.  The discussions are continuing and we hope that
the ideas in this article will make a useful contribution to the
debate.

Our aim is that \LaTeX{} should be a system which can be trusted by
users of all types to fulfill their needs.  Such a system must be
stable and well-maintained.  This implies that it must be reasonably
easy to maintain (otherwise it will simply not get maintained at
all).  So here is a summary of our basic philosophy:
\begin{quote}
  We believe that the freedom to rely on a widely-used standard for
  document interchange and formatting is as important as the freedom to
  experiment with the contents of files.

  We are therefore adopting a policy similar to that which Donald
  Knuth applies to modifications of the underlying \TeX{} system: that
  certain files, together with their names, are part of the system and
  therefore the contents of these files should not be changed unless
  the following conditions are met:
  \begin{itemize}
  \item they are clearly marked as being no longer part of the
    standard system;
  \item the name of the file is changed.
  \end{itemize}
\end{quote}


\section{The system}
\label{sec:sys}

In developing this philosophy, and the consequent limitations on how
modifications of the system should be carried out, we were heavily
influenced by the following facts concerning the current widespread
and wide-ranging uses of the \LaTeX{} system.
\begin{enumerate}
\item  \LaTeX{} is not just a document processing system;
  it also defines a language for document exchange.

\item The standard document class files, and some other files, also
  define a particular formatting of a document.

\item  The packages that we maintain define a particular document
  interface and, in some cases, particular formatting of parts of a
  document. 
  
\item The interfaces between different parts of the \LaTeX{} system
  are very complex and it is therefore very difficult to check that a
  change to one file does not affect the functionality of both that
  file and also other parts of the system not obviously connected to
  the file that has been changed.
\end{enumerate}

This leads us to the general principle that:
\begin{quote}
  with certain special exceptions, if you change the contents of a
  file then the changed version should have a different file name.
\end{quote}

We certainly do not wish to prevent people from experimenting with the
code in different ways and adapting it to their purposes.  However, we
are concerned that any distribution of modifications to the code
should be very clearly identified as not being a part of the standard
distribution.  The exact wording and form of the distribution
conditions is thus something that is flexible, but only within the
constraint of keeping \LaTeX{} as a standardised, reliable product for
the purposes described above: the exchange and formatting of
documents.


\section{Some examples}
\label{sec:expl}

Here we elaborate the arguments that have led us to the above
conclusion.


\reasonsection{Separate development considered harmful!}
\label{sec:ja}

In many fields, the use of \LaTeX{} as a language for communication
is just as important as its capacity for fine typesetting; this is a
very important consideration for a large population of authors,
journal editors, archivists, etc.

Related to this issue of portability is the fact that the file names
are part of the end-user syntax.

As a real example, the \LaTeX{} `tools' collection contains the
package `array.sty'.  A new user-level feature was added to this file
at the end of 1994 and a document using this feature can contain the
line:
\begin{verbatim}
   \usepackage{array}[1994/10/16]
\end{verbatim}
  
By supplying the optional argument, the document author is indicating
that a version of the file \texttt{array.sty} dated no earlier than
that date is required to run this document without error.

This feature would be totally worthless if we were to allow an
alternative version of the array package to be distributed under the
same name since it would mean that there would be in circulation files
of a later date, but without the new feature.  If the document
were processed using this `alternative array' then it would certainly
produce `undefined command' errors and would probably not be
processable at all.
 

\reasonsection{What's in a file-name?}
\label{sec:jb}

In a pure markup language, such as SGML, it is reasonably clear that
control over the final presentation lies with the receiver of a
document and not with the author.

However, the way that \LaTeX{} is often used in practice means that
most people (at least when using the standard classes and packages)
expect the formatting to be preserved when they send the document to
another site.

For example, suppose, as is still the most common use of \LaTeX{} in
publishing, you produce a document for `camera-ready-copy' using the
class `article' and that you carefully tune the formatting by, for
example, adding some explicit line breaks etc, to ensure that it fits
the 8 page limit set by the editor a journal or proceedings.

It then gets sent to the editor or a referee who, without anyone
knowing, has a non-standard version of the class file `article' and so
it then runs to 9 pages.  The consequence of this will, at the least,
be a lot of wasted time whilst everyone involved works out what has
gone wrong; it will probably also lead to everyone blaming each other
for something which was in fact caused by a misguided distribution
policy.

It should also be noted that, for most people, the version of the
class file `article' that gets used is decided by a site maintainer
or the compilers of a CD-ROM distribution.  To most users,
the symbols \texttt{a\,r\,t\,i\,c\,l\,e} in:
\begin{verbatim}
   \documentclass{article}
\end{verbatim}
are just as much part of \LaTeX{}'s syntax as are the symbols
\texttt{1\,2\,p\,t} in:
\begin{verbatim}
   \hspace{12pt}
\end{verbatim}
Thus they should both define a standard formatting rather than
sometimes producing 1 more page or a 5pt larger space.

Users rely on the fact that the command (or menu item) `LaTeX'
produces a completely standard \LaTeX, including the fact that
`article' is the `standard article'.  They would not be at all happy
if the person who installed and maintains \LaTeX{} for them were
allowed to customise `article' every second day so as (in her or his
opinion) to improve the layout; or because another user wanted to write
a document in a different language or typeset one with different fonts.

\reasonsection{\TeX{} itself}
\label{sec:tex}

We have modelled our policies on those of the \TeX{} system since this
has for some time now been widely acknowledged as a very stable and
high quality typesetting system.

The distribution policy set up by Donald Knuth for \TeX{} has the
following features:
\begin{itemize}
\item There is a clearly specified method for changing parts of the
  software by the use of `change files'.
\item Although arbitrary changes are allowed, the resulting program
  can be called \TeX{} only if its functionality is precisely the same
  as that of \TeX{} (i.e.~neither less nor more) in all important
  areas.
\item There are many files in the system that cannot be changed at all
  (without changing the name): examples are the file
  \texttt{plain.tex} and the files associated with fonts, including
  the Metafont source files.
\end{itemize}


\reasonsection{Maintaining complexity}
\label{sec:compl}

Our experience of maintaining \LaTeX{} has shown us just how complex
are the interactions between different parts of the system.

We have therefore, with lots of help from the bug reports you send in,
developed a large suite of test files which we run to check the
effects of every change we make.  A non-negligible percentage of these
test runs give unexpected results and hence show up some unexpected
dependency in the system.


\section{Some assurances}
\label{sec:conc}

We are certainly not attempting to stop people reformatting \LaTeX{}
documents in any way they wish.  There are many ways of customising
incoming documents to your personal style that do not involve changing
the contents of \LaTeX{}'s standard files; indeed, this freedom is one
of the system's many advantages.
The simplest way to achieve this is to replace
\begin{quote}
\verb|\documentclass{article}|\quad by\quad
\verb|\documentclass{myart}| 
\end{quote}

Nor do we wish to discourage the production of new packages improving
on the functionality or implementation of those we distribute.  All we
ask is that, in the best interests of all \LaTeX{} users, you give
your superbly improved class or package file some other name. 

\section{Configuration possibilities}
\label{sec:conposs}

The standard \LaTeX{} system format can be configured in several ways
to suit the needs and resources of an installation.  For example, the
loading of fonts and font tables can be customised to match the font
shapes, families and encodings normally used in text mode.  Also, by
producing the appropriate font definition files, the font tables
themselves can be set up to take advantage of the available fonts and
sizes.  The loading of hyphenation patterns can be adjusted to cover
the languages used; this has to be done as part of making the format
since this is the only stage at which patterns can be loaded.

A complete list of these configuration possibilities can be found in
the distributed guide \emph{Configuration options for} \LaTeXe{}
(\texttt{cfgguide.tex}).  However, as it says there, the number of
configuration possibilities is strictly limited; we hope that having
read this far you will appreciate the reasons for this decision.  One
consequence of this is that there is no provision for a general
purpose configuration file, or for adding extra code just before the
|\dump| of the format file.

This was a deliberate decision and we hope that everyone (yes, that
includes you!) will support its intent.  Otherwise there will be a
rapid return to the very situation, of several incompatible versions
of \LaTeX~2.09, that originally prompted us to produce \LaTeXe{}: the
new, and \emph{only}, `Standard \LaTeX'.  This will make \LaTeX{}
unmaintainable and, hence, unmaintained (by us, at least).

\begin{quote}
  Therefore you should not misuse the configuration files or other
  parts of the distribution to produce non-standard versions of
  \LaTeX{}.
\end{quote}

Some of the allowed configurations can result in a system that can produce
documents that are no longer `formatting compatible'; for example, the
use of different default fonts will most likely produce different line
and page breaks.  If you do produce a system that is configured in
such a way that it is not `formatting compatible' then you should
consider carefully the needs of users who need to create portable
documents.  A good way to provide for their needs is to make
available, in addition, a standard form of \LaTeX{} without any
`formatting incompatible' customisations.


\section{Modification conditions}
\label{sec:modcon}

It is possible that you need to produce a document processing system
based on standard \LaTeX{} but with functionality that cannot be
implemented by using the approved configuration files and complying
with the restriction on the code that is allowed in them.  In other
words, you may need a system which is sufficiently distinct from
Standard \LaTeX{} that it is not feasible to do this simply by using
the configuration options we provide or by producing new classes and
packages.

If you do produce such a system then, for the reasons described
above, you should ensure that your system is clearly distinguished
from Standard \LaTeX{} in every possible way, including the following.


\begin{enumerate}
\item
  Give your system a distinguished name, such as \nstex, which clearly
  distinguishes it from \LaTeX{}.

\item
  Ensure that it contains no file with a name the same as that of
  a file in the standard distribution but with different contents.
  (If this is not possible then you must: 
  \begin{itemize}
  \item
    ensure that files from the non-\LaTeX{} system cannot be
    accidentally accessed whilst using a standard \LaTeX{};
  \item ensure that each file from the non-\LaTeX{} system clearly
    identifies itself as a non-\LaTeX{} file on the terminal and in the
    log file.)
  \end{itemize}

\item
  Ensure that the method used to run your system is clearly
\label{mcon:command}
  distinct from that used to run Standard \LaTeX; e.g.~by using a
  command name or menu entry that is clearly not \texttt{latex}
  (or \texttt{LaTeX} etc).

\item
  Ensure that, when a file is being processed by your system, the
  use of non-standard \LaTeX{} is clearly proclaimed to the user by
  whatever means is appropriate.

\item Ensure that what is written at the beginning of the log file
  clearly shows that your system has been used, and that it is 
  not Standard \LaTeX{}.
  See the file \texttt{cfgguide.tex} for how to achieve this.

\item
 Clearly explain to users that bug reports concerning your 
 system should not be sent to the maintainers of Standard
 \LaTeX{}. 
\end{enumerate}

\subsection*{Note to system administrators}

If you install a non-standard (modified) version of \LaTeX{} on a
multi-user site then please, in addition, install Standard \LaTeX{}
and observe the conditions enumerated above, particularly
\ref{mcon:command}.


\section{What do you think?}
\label{sec:you}

We are interested in your views on the issues raised in this document.
The best way to let us know what you think, and to discuss your ideas
with others, is to join the \texttt{LaTeX-L} mailing list and send your
comments there.
To subscribe to this list, mail to:
\begin{verbatim}
   listserv@urz.uni-heidelberg.de
\end{verbatim}
the following one line message:
\begin{verbatim}
   subscribe LATEX-L <your-first-name> <your-second-name>
\end{verbatim}

\end{document}