Debian Codegraph @

texmf-dist/doc/latex/base/modguide.tex

raw
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}