| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 1993-2025 |
| 4 |
% The LaTeX Project and any individual authors listed elsewhere |
| 5 |
% in this file. |
| 6 |
% |
| 7 |
% This file is part of the LaTeX base system. |
| 8 |
% ------------------------------------------- |
| 9 |
% |
| 10 |
% It may be distributed and/or modified under the |
| 11 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 12 |
% of this license or (at your option) any later version. |
| 13 |
% The latest version of this license is in |
| 14 |
% http://www.latex-project.org/lppl.txt |
| 15 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 16 |
% version 2008 or later. |
| 17 |
% |
| 18 |
% This file has the LPPL maintenance status "maintained". |
| 19 |
% |
| 20 |
% The list of all files belonging to the LaTeX base distribution is |
| 21 |
% given in the file `manifest.txt'. See also `legal.txt' for additional |
| 22 |
% information. |
| 23 |
% |
| 24 |
% The list of derived (unpacked) files belonging to the distribution |
| 25 |
% and covered by LPPL is defined by the unpacking scripts (with |
| 26 |
% extension .ins) which are part of the distribution. |
| 27 |
% |
| 28 |
% \fi |
| 29 |
% Filename: modguide.tex |
| 30 |
|
| 31 |
\NeedsTeXFormat{LaTeX2e}[1995/12/01] |
| 32 |
|
| 33 |
\documentclass{ltxguide}[1995/11/28] |
| 34 |
|
| 35 |
\newcommand{\reasonsection}[1]{\subsubsection*{\it #1}} |
| 36 |
|
| 37 |
\newcommand{\nstex}{\textsf{NS-TeX}} |
| 38 |
|
| 39 |
\setcounter{secnumdepth}{-1} |
| 40 |
|
| 41 |
\title{Modifying \LaTeX} |
| 42 |
|
| 43 |
\author{\copyright~Copyright 1995, \LaTeX\ Project Team.\\ |
| 44 |
All rights reserved.% |
| 45 |
\footnote{This file may be distributed and/or modified under the |
| 46 |
conditions of the \LaTeX{} Project Public License, either version 1.3c |
| 47 |
of this license or (at your option) any later version. See the source |
| 48 |
texttt{modguide.tex} for full details.}% |
| 49 |
} |
| 50 |
|
| 51 |
\date{12 December 1995} |
| 52 |
|
| 53 |
\begin{document} |
| 54 |
|
| 55 |
\maketitle |
| 56 |
|
| 57 |
\tableofcontents |
| 58 |
|
| 59 |
\begin{abstract} |
| 60 |
This document was produced in response to suggestions that the |
| 61 |
modification and distribution conditions for the files constituting |
| 62 |
the New Standard \LaTeX{} system should be similar to those implied |
| 63 |
by Version~2 of the \textsc{GNU} General Public Licence, as |
| 64 |
published by the Free Software Foundation. |
| 65 |
\end{abstract} |
| 66 |
|
| 67 |
\section{Introduction} |
| 68 |
\label{sec:intro} |
| 69 |
|
| 70 |
This article describes the principles underlying our policy on |
| 71 |
distribution and modification of the files comprising the \LaTeX{} |
| 72 |
system. It has been produced as a result of detailed discussions of |
| 73 |
the issues involved in the support and maintenance of a widely |
| 74 |
distributed document processing system used by diverse people for many |
| 75 |
applications. These discussions have involved users, maintainers of |
| 76 |
installations that support \LaTeX{} and various types of organisations |
| 77 |
that distribute it. The discussions are continuing and we hope that |
| 78 |
the ideas in this article will make a useful contribution to the |
| 79 |
debate. |
| 80 |
|
| 81 |
Our aim is that \LaTeX{} should be a system which can be trusted by |
| 82 |
users of all types to fulfill their needs. Such a system must be |
| 83 |
stable and well-maintained. This implies that it must be reasonably |
| 84 |
easy to maintain (otherwise it will simply not get maintained at |
| 85 |
all). So here is a summary of our basic philosophy: |
| 86 |
\begin{quote} |
| 87 |
We believe that the freedom to rely on a widely-used standard for |
| 88 |
document interchange and formatting is as important as the freedom to |
| 89 |
experiment with the contents of files. |
| 90 |
|
| 91 |
We are therefore adopting a policy similar to that which Donald |
| 92 |
Knuth applies to modifications of the underlying \TeX{} system: that |
| 93 |
certain files, together with their names, are part of the system and |
| 94 |
therefore the contents of these files should not be changed unless |
| 95 |
the following conditions are met: |
| 96 |
\begin{itemize} |
| 97 |
\item they are clearly marked as being no longer part of the |
| 98 |
standard system; |
| 99 |
\item the name of the file is changed. |
| 100 |
\end{itemize} |
| 101 |
\end{quote} |
| 102 |
|
| 103 |
|
| 104 |
\section{The system} |
| 105 |
\label{sec:sys} |
| 106 |
|
| 107 |
In developing this philosophy, and the consequent limitations on how |
| 108 |
modifications of the system should be carried out, we were heavily |
| 109 |
influenced by the following facts concerning the current widespread |
| 110 |
and wide-ranging uses of the \LaTeX{} system. |
| 111 |
\begin{enumerate} |
| 112 |
\item \LaTeX{} is not just a document processing system; |
| 113 |
it also defines a language for document exchange. |
| 114 |
|
| 115 |
\item The standard document class files, and some other files, also |
| 116 |
define a particular formatting of a document. |
| 117 |
|
| 118 |
\item The packages that we maintain define a particular document |
| 119 |
interface and, in some cases, particular formatting of parts of a |
| 120 |
document. |
| 121 |
|
| 122 |
\item The interfaces between different parts of the \LaTeX{} system |
| 123 |
are very complex and it is therefore very difficult to check that a |
| 124 |
change to one file does not affect the functionality of both that |
| 125 |
file and also other parts of the system not obviously connected to |
| 126 |
the file that has been changed. |
| 127 |
\end{enumerate} |
| 128 |
|
| 129 |
This leads us to the general principle that: |
| 130 |
\begin{quote} |
| 131 |
with certain special exceptions, if you change the contents of a |
| 132 |
file then the changed version should have a different file name. |
| 133 |
\end{quote} |
| 134 |
|
| 135 |
We certainly do not wish to prevent people from experimenting with the |
| 136 |
code in different ways and adapting it to their purposes. However, we |
| 137 |
are concerned that any distribution of modifications to the code |
| 138 |
should be very clearly identified as not being a part of the standard |
| 139 |
distribution. The exact wording and form of the distribution |
| 140 |
conditions is thus something that is flexible, but only within the |
| 141 |
constraint of keeping \LaTeX{} as a standardised, reliable product for |
| 142 |
the purposes described above: the exchange and formatting of |
| 143 |
documents. |
| 144 |
|
| 145 |
|
| 146 |
\section{Some examples} |
| 147 |
\label{sec:expl} |
| 148 |
|
| 149 |
Here we elaborate the arguments that have led us to the above |
| 150 |
conclusion. |
| 151 |
|
| 152 |
|
| 153 |
\reasonsection{Separate development considered harmful!} |
| 154 |
\label{sec:ja} |
| 155 |
|
| 156 |
In many fields, the use of \LaTeX{} as a language for communication |
| 157 |
is just as important as its capacity for fine typesetting; this is a |
| 158 |
very important consideration for a large population of authors, |
| 159 |
journal editors, archivists, etc. |
| 160 |
|
| 161 |
Related to this issue of portability is the fact that the file names |
| 162 |
are part of the end-user syntax. |
| 163 |
|
| 164 |
As a real example, the \LaTeX{} `tools' collection contains the |
| 165 |
package `array.sty'. A new user-level feature was added to this file |
| 166 |
at the end of 1994 and a document using this feature can contain the |
| 167 |
line: |
| 168 |
\begin{verbatim} |
| 169 |
\usepackage{array}[1994/10/16] |
| 170 |
\end{verbatim} |
| 171 |
|
| 172 |
By supplying the optional argument, the document author is indicating |
| 173 |
that a version of the file \texttt{array.sty} dated no earlier than |
| 174 |
that date is required to run this document without error. |
| 175 |
|
| 176 |
This feature would be totally worthless if we were to allow an |
| 177 |
alternative version of the array package to be distributed under the |
| 178 |
same name since it would mean that there would be in circulation files |
| 179 |
of a later date, but without the new feature. If the document |
| 180 |
were processed using this `alternative array' then it would certainly |
| 181 |
produce `undefined command' errors and would probably not be |
| 182 |
processable at all. |
| 183 |
|
| 184 |
|
| 185 |
\reasonsection{What's in a file-name?} |
| 186 |
\label{sec:jb} |
| 187 |
|
| 188 |
In a pure markup language, such as SGML, it is reasonably clear that |
| 189 |
control over the final presentation lies with the receiver of a |
| 190 |
document and not with the author. |
| 191 |
|
| 192 |
However, the way that \LaTeX{} is often used in practice means that |
| 193 |
most people (at least when using the standard classes and packages) |
| 194 |
expect the formatting to be preserved when they send the document to |
| 195 |
another site. |
| 196 |
|
| 197 |
For example, suppose, as is still the most common use of \LaTeX{} in |
| 198 |
publishing, you produce a document for `camera-ready-copy' using the |
| 199 |
class `article' and that you carefully tune the formatting by, for |
| 200 |
example, adding some explicit line breaks etc, to ensure that it fits |
| 201 |
the 8 page limit set by the editor a journal or proceedings. |
| 202 |
|
| 203 |
It then gets sent to the editor or a referee who, without anyone |
| 204 |
knowing, has a non-standard version of the class file `article' and so |
| 205 |
it then runs to 9 pages. The consequence of this will, at the least, |
| 206 |
be a lot of wasted time whilst everyone involved works out what has |
| 207 |
gone wrong; it will probably also lead to everyone blaming each other |
| 208 |
for something which was in fact caused by a misguided distribution |
| 209 |
policy. |
| 210 |
|
| 211 |
It should also be noted that, for most people, the version of the |
| 212 |
class file `article' that gets used is decided by a site maintainer |
| 213 |
or the compilers of a CD-ROM distribution. To most users, |
| 214 |
the symbols \texttt{a\,r\,t\,i\,c\,l\,e} in: |
| 215 |
\begin{verbatim} |
| 216 |
\documentclass{article} |
| 217 |
\end{verbatim} |
| 218 |
are just as much part of \LaTeX{}'s syntax as are the symbols |
| 219 |
\texttt{1\,2\,p\,t} in: |
| 220 |
\begin{verbatim} |
| 221 |
\hspace{12pt} |
| 222 |
\end{verbatim} |
| 223 |
Thus they should both define a standard formatting rather than |
| 224 |
sometimes producing 1 more page or a 5pt larger space. |
| 225 |
|
| 226 |
Users rely on the fact that the command (or menu item) `LaTeX' |
| 227 |
produces a completely standard \LaTeX, including the fact that |
| 228 |
`article' is the `standard article'. They would not be at all happy |
| 229 |
if the person who installed and maintains \LaTeX{} for them were |
| 230 |
allowed to customise `article' every second day so as (in her or his |
| 231 |
opinion) to improve the layout; or because another user wanted to write |
| 232 |
a document in a different language or typeset one with different fonts. |
| 233 |
|
| 234 |
\reasonsection{\TeX{} itself} |
| 235 |
\label{sec:tex} |
| 236 |
|
| 237 |
We have modelled our policies on those of the \TeX{} system since this |
| 238 |
has for some time now been widely acknowledged as a very stable and |
| 239 |
high quality typesetting system. |
| 240 |
|
| 241 |
The distribution policy set up by Donald Knuth for \TeX{} has the |
| 242 |
following features: |
| 243 |
\begin{itemize} |
| 244 |
\item There is a clearly specified method for changing parts of the |
| 245 |
software by the use of `change files'. |
| 246 |
\item Although arbitrary changes are allowed, the resulting program |
| 247 |
can be called \TeX{} only if its functionality is precisely the same |
| 248 |
as that of \TeX{} (i.e.~neither less nor more) in all important |
| 249 |
areas. |
| 250 |
\item There are many files in the system that cannot be changed at all |
| 251 |
(without changing the name): examples are the file |
| 252 |
\texttt{plain.tex} and the files associated with fonts, including |
| 253 |
the Metafont source files. |
| 254 |
\end{itemize} |
| 255 |
|
| 256 |
|
| 257 |
\reasonsection{Maintaining complexity} |
| 258 |
\label{sec:compl} |
| 259 |
|
| 260 |
Our experience of maintaining \LaTeX{} has shown us just how complex |
| 261 |
are the interactions between different parts of the system. |
| 262 |
|
| 263 |
We have therefore, with lots of help from the bug reports you send in, |
| 264 |
developed a large suite of test files which we run to check the |
| 265 |
effects of every change we make. A non-negligible percentage of these |
| 266 |
test runs give unexpected results and hence show up some unexpected |
| 267 |
dependency in the system. |
| 268 |
|
| 269 |
|
| 270 |
\section{Some assurances} |
| 271 |
\label{sec:conc} |
| 272 |
|
| 273 |
We are certainly not attempting to stop people reformatting \LaTeX{} |
| 274 |
documents in any way they wish. There are many ways of customising |
| 275 |
incoming documents to your personal style that do not involve changing |
| 276 |
the contents of \LaTeX{}'s standard files; indeed, this freedom is one |
| 277 |
of the system's many advantages. |
| 278 |
The simplest way to achieve this is to replace |
| 279 |
\begin{quote} |
| 280 |
\verb|\documentclass{article}|\quad by\quad |
| 281 |
\verb|\documentclass{myart}| |
| 282 |
\end{quote} |
| 283 |
|
| 284 |
Nor do we wish to discourage the production of new packages improving |
| 285 |
on the functionality or implementation of those we distribute. All we |
| 286 |
ask is that, in the best interests of all \LaTeX{} users, you give |
| 287 |
your superbly improved class or package file some other name. |
| 288 |
|
| 289 |
\section{Configuration possibilities} |
| 290 |
\label{sec:conposs} |
| 291 |
|
| 292 |
The standard \LaTeX{} system format can be configured in several ways |
| 293 |
to suit the needs and resources of an installation. For example, the |
| 294 |
loading of fonts and font tables can be customised to match the font |
| 295 |
shapes, families and encodings normally used in text mode. Also, by |
| 296 |
producing the appropriate font definition files, the font tables |
| 297 |
themselves can be set up to take advantage of the available fonts and |
| 298 |
sizes. The loading of hyphenation patterns can be adjusted to cover |
| 299 |
the languages used; this has to be done as part of making the format |
| 300 |
since this is the only stage at which patterns can be loaded. |
| 301 |
|
| 302 |
A complete list of these configuration possibilities can be found in |
| 303 |
the distributed guide \emph{Configuration options for} \LaTeXe{} |
| 304 |
(\texttt{cfgguide.tex}). However, as it says there, the number of |
| 305 |
configuration possibilities is strictly limited; we hope that having |
| 306 |
read this far you will appreciate the reasons for this decision. One |
| 307 |
consequence of this is that there is no provision for a general |
| 308 |
purpose configuration file, or for adding extra code just before the |
| 309 |
|\dump| of the format file. |
| 310 |
|
| 311 |
This was a deliberate decision and we hope that everyone (yes, that |
| 312 |
includes you!) will support its intent. Otherwise there will be a |
| 313 |
rapid return to the very situation, of several incompatible versions |
| 314 |
of \LaTeX~2.09, that originally prompted us to produce \LaTeXe{}: the |
| 315 |
new, and \emph{only}, `Standard \LaTeX'. This will make \LaTeX{} |
| 316 |
unmaintainable and, hence, unmaintained (by us, at least). |
| 317 |
|
| 318 |
\begin{quote} |
| 319 |
Therefore you should not misuse the configuration files or other |
| 320 |
parts of the distribution to produce non-standard versions of |
| 321 |
\LaTeX{}. |
| 322 |
\end{quote} |
| 323 |
|
| 324 |
Some of the allowed configurations can result in a system that can produce |
| 325 |
documents that are no longer `formatting compatible'; for example, the |
| 326 |
use of different default fonts will most likely produce different line |
| 327 |
and page breaks. If you do produce a system that is configured in |
| 328 |
such a way that it is not `formatting compatible' then you should |
| 329 |
consider carefully the needs of users who need to create portable |
| 330 |
documents. A good way to provide for their needs is to make |
| 331 |
available, in addition, a standard form of \LaTeX{} without any |
| 332 |
`formatting incompatible' customisations. |
| 333 |
|
| 334 |
|
| 335 |
\section{Modification conditions} |
| 336 |
\label{sec:modcon} |
| 337 |
|
| 338 |
It is possible that you need to produce a document processing system |
| 339 |
based on standard \LaTeX{} but with functionality that cannot be |
| 340 |
implemented by using the approved configuration files and complying |
| 341 |
with the restriction on the code that is allowed in them. In other |
| 342 |
words, you may need a system which is sufficiently distinct from |
| 343 |
Standard \LaTeX{} that it is not feasible to do this simply by using |
| 344 |
the configuration options we provide or by producing new classes and |
| 345 |
packages. |
| 346 |
|
| 347 |
If you do produce such a system then, for the reasons described |
| 348 |
above, you should ensure that your system is clearly distinguished |
| 349 |
from Standard \LaTeX{} in every possible way, including the following. |
| 350 |
|
| 351 |
|
| 352 |
\begin{enumerate} |
| 353 |
\item |
| 354 |
Give your system a distinguished name, such as \nstex, which clearly |
| 355 |
distinguishes it from \LaTeX{}. |
| 356 |
|
| 357 |
\item |
| 358 |
Ensure that it contains no file with a name the same as that of |
| 359 |
a file in the standard distribution but with different contents. |
| 360 |
(If this is not possible then you must: |
| 361 |
\begin{itemize} |
| 362 |
\item |
| 363 |
ensure that files from the non-\LaTeX{} system cannot be |
| 364 |
accidentally accessed whilst using a standard \LaTeX{}; |
| 365 |
\item ensure that each file from the non-\LaTeX{} system clearly |
| 366 |
identifies itself as a non-\LaTeX{} file on the terminal and in the |
| 367 |
log file.) |
| 368 |
\end{itemize} |
| 369 |
|
| 370 |
\item |
| 371 |
Ensure that the method used to run your system is clearly |
| 372 |
\label{mcon:command} |
| 373 |
distinct from that used to run Standard \LaTeX; e.g.~by using a |
| 374 |
command name or menu entry that is clearly not \texttt{latex} |
| 375 |
(or \texttt{LaTeX} etc). |
| 376 |
|
| 377 |
\item |
| 378 |
Ensure that, when a file is being processed by your system, the |
| 379 |
use of non-standard \LaTeX{} is clearly proclaimed to the user by |
| 380 |
whatever means is appropriate. |
| 381 |
|
| 382 |
\item Ensure that what is written at the beginning of the log file |
| 383 |
clearly shows that your system has been used, and that it is |
| 384 |
not Standard \LaTeX{}. |
| 385 |
See the file \texttt{cfgguide.tex} for how to achieve this. |
| 386 |
|
| 387 |
\item |
| 388 |
Clearly explain to users that bug reports concerning your |
| 389 |
system should not be sent to the maintainers of Standard |
| 390 |
\LaTeX{}. |
| 391 |
\end{enumerate} |
| 392 |
|
| 393 |
\subsection*{Note to system administrators} |
| 394 |
|
| 395 |
If you install a non-standard (modified) version of \LaTeX{} on a |
| 396 |
multi-user site then please, in addition, install Standard \LaTeX{} |
| 397 |
and observe the conditions enumerated above, particularly |
| 398 |
\ref{mcon:command}. |
| 399 |
|
| 400 |
\end{document} |