summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/modguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/modguide.tex')
-rw-r--r--macros/latex-dev/base/modguide.tex412
1 files changed, 412 insertions, 0 deletions
diff --git a/macros/latex-dev/base/modguide.tex b/macros/latex-dev/base/modguide.tex
new file mode 100644
index 0000000000..ff796c7687
--- /dev/null
+++ b/macros/latex-dev/base/modguide.tex
@@ -0,0 +1,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}