summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/modguide.tex
blob: ff796c76879cf5f4622a9785c79821ca2dd55253 (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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
% \iffalse meta-comment
%
% Copyright (C) 1993-2019
% 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 2008 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}