diff options
Diffstat (limited to 'macros/latex-dev/doc/modguide.tex')
-rw-r--r-- | macros/latex-dev/doc/modguide.tex | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/macros/latex-dev/doc/modguide.tex b/macros/latex-dev/doc/modguide.tex new file mode 100644 index 0000000000..147fec7878 --- /dev/null +++ b/macros/latex-dev/doc/modguide.tex @@ -0,0 +1,412 @@ +% \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} |