diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/base/cfgguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/base/cfgguide.tex | 561 |
1 files changed, 561 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/base/cfgguide.tex b/Master/texmf-dist/doc/latex/base/cfgguide.tex new file mode 100644 index 00000000000..9e734529ea9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/base/cfgguide.tex @@ -0,0 +1,561 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 +% 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.3 +% 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.3 or later is part of all distributions of LaTeX +% version 2003/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: cfgguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1995/11/28] + +\newcommand{\filesection}[1]{\subsection{\sffamily{#1}}} +\newcommand{\iniTeX}{ini\TeX} + +\setcounter{secnumdepth}{0} + +\title{Configuration options for \LaTeXe} + +\author{\copyright~Copyright 1998, 2001, 2003 \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{14 February 2003} + +\begin{document} + +\maketitle + +\tableofcontents + +\newpage + +\section{Configuring \LaTeX} + +Since one of the main aims of the new standard \LaTeX{} is to give all +users the freedom provided by a reliable document processing system +linked to a highly portable document format, the number of +configuration possibilities is strictly limited. The reasons for this +are explained in more detail in the article +\textit{Modifying \LaTeX{}} in the file \texttt{modguide.tex}. +An important consequence of this is that any document that relies on +any extension package must declare this package within the document +file; this helps to ensure that the document will work at a different +site, where the \LaTeX{} system may be configured differently. + +Local configuration options are, by convention, placed in +`configuration files', which have extension |.cfg|. This document +describes the possibilities for configuration in this release of +\LaTeX; it also explains how to configure the font definition files to +take advantage of the available fonts. + +The last section considers briefly how to proceed if you require +further customisation of the formatter. + + +\section{System configuration} + +\filesection{texsys.cfg} + +This is the only configuration file that \emph{must} be present. +During installation, if \LaTeX\ cannot find a file with this name +then a default file |texsys.cfg|, consisting entirely of comments, is +written out and used. Note that, until this file has been read, +\LaTeX{} is not able to test reliably whether a given file exists on +the system. + +The contents of the file |texsys.cfg| allow \LaTeX{} to cope with +various differences between the behaviours of different \TeX{} systems, +mainly in relation to file handling. The default version of this file +contains, in its comments, possible settings that may be needed for a +range of \TeX{} systems. For more information, typeset the file +|ltdirchk.dtx|. + +If you have copied your \LaTeX{} installation from a computer that +used a different operating system then you may well have a version of +|texsys.cfg| that will make it difficult to install \LaTeX{} on your +system. If this happens then start the process again with an empty +|texsys.cfg| file; this will produce an installation that should, at +least, allow you to typeset the documentation. However, it is +possible that \LaTeX{} can still find only those files that are in the +current directory; in this case you must set the macro |\input@path| +correctly for your system. + + +\section{Configuring the \LaTeX\ format} + +There are four configuration files that enable personal preferences to +be incorporated into the \LaTeX{} format file |latex.fmt|. The range +of preferences that can be configured by these files is strictly +limited as this helps to ensure document portability. + +All four files work in the same way: if the file \m{file}|.cfg| is +found, it will be input by \iniTeX; otherwise a default file +\m{file}|.ltx| will be input; this is sometimes done via a +minimal \m{file}|.cfg| that simply inputs \m{file}|.ltx|. Thus, +providing your own version of any of these |.cfg| files can completely +override any settings in the corresponding default standard |.ltx| +file. + + +\subsection{Font configuration} + +Before you even think about configuring the font declarations by +producing a file |fontmath.cfg| or |fonttext.cfg|, you should +read the documented file |fontdef.dtx|. This is the source file from +which the default files |fonttext.ltx| and |fontmath.ltx| are +produced; it contains information concerning the +contents of the default files and what sort of customisation is +possible. In particular, it describes in detail the effects of +individual customisations on document portability including: which +customisations can be made without endangering the ability to exchange +documents with other sites (even if the formatting differs); and which +things should be left untouched because they will make your system so +different from others that the documents it produces will be +non-portable. + +\textbf{WARNING } Please note that use of either of these font +configuration files has the following consequences. + \begin{itemize} + \item Since the content of the file |fontdef.dtx| \emph{might} + change in the future, anyone writing a font configuration file + must be prepared to update it for use with future releases. + \item Documents produced on your system are likely, at best, to be + portable only in the sense of being processable at a different + site---the actual formatting will not be the same if different + fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use any configuration files. + \end{itemize} + +\filesection{fonttext.cfg} + +The file |fonttext.cfg| can contain declarations relating to the use +of fonts in text modes. + +If it exists, it defines which font shapes, families and encodings are +normally used in text mode, as well as the behavior of font attribute +commands such as |\textbf| etc. + +It could be used, for example, to produce a \LaTeX\ format that, by +default, typesets documents using Times fonts. Be warned, however, +that such customisation can have unfortunate consequences; so please +read carefully this section and the file |fontdef.dtx| below if you +are thinking of doing this. + +Please note carefully the above \textbf{warning}. + +\filesection{fontmath.cfg} + +The file |fontmath.cfg| can contain declarations relating to the use +of fonts in math mode. + +If it exists, it defines which fonts in which sizes are used in math +mode, and how they are used. It also defines all the math mode +commands that `are likely to' depend on the choice of math fonts used +(e.g.~commands that depend on the position of a glyph in a math font). + +The main reason for the existence of this file is to provide for future +updates when a standard math font encoding is available. Right now we +do \emph{not} encourage the use of this configuration file other than +for special applications. Writing a proper configuration file for math +mode needs expert knowledge! + +Please note carefully the above \textbf{warning}. + +\filesection{preload.cfg} + +The contents of the file |preload.cfg| can control the preloading of +commonly used fonts. Preloading fonts speeds up the processing of +documents but, because fonts cannot be `unloaded', you should not +preload too many; otherwise you may be unable to process documents +requiring unusual font families. + +The default file |preload.ltx| is produced from |preload.dtx|. It +loads only a few fonts and these are a good choice if you normally use +documents at the default, 10\,pt, size. If you normally use 11\,pt +or~12\,pt then the time for \LaTeX\ to startup may be noticeably +decreased if you preload the corresponding fonts for the sizes you +use. Similarly, if you normally use a different font family, for +example Times Roman (|ptm|) then you may want to preload fonts in this +family rather than the default Computer Modern fonts. + +\subsection{Hyphenation configuration} + +\filesection{hyphen.cfg} + +In order to hyphenate text, \TeX{} must have hyphenation patterns and, +since these patterns can be loaded only by \iniTeX, the choice of +which patterns to load must be made when the format is created. + +The hyphenation patterns for American English are stored in the file +named |hyphen.tex|; \LaTeX~2.09 always loaded this file when its +format was made. + +With \LaTeXe{} it is possible to configure which hyphenation patterns +are to be loaded into the format. When \iniTeX{} is processing +|latex.ltx|, it looks for a file called |hyphen.cfg|; this file can +be used to control which hyphenation patterns are loaded. If a file +|hyphen.cfg| cannot be found then \iniTeX{} will load the file +|hyphen.ltx|. + +The file |hyphen.ltx| loads the file |hyphen.tex| if it can find it; +otherwise it stops with an error since a format with no hyphenation +patterns is not very useful. It then sets |\language=0| and it sets +the values |\lefthyphenmin=2| and |\righthyphenmin=3|, which are +needed for American English. + +Thus, if you want any other patterns to be loaded then you should +create a file |hyphen.cfg|. For each language for which you wish to +load hyphenation patterns this file should: +\begin{itemize} +\item set |\language=|\m{number}; +\item load the file which contains the hyphenation patterns for that + language. +\end{itemize} +If the patterns you use require some definitions or assignments then +a group should be used to keep such changes local to their file. + +\textbf{Note.} The hyphenation files that are read in should \emph{only} +set the hyphenation tables for the language, using the commands +|\hyphenation| and |\patterns|. In particular they should make no +assignments to the lowercase/uppercase tables (|\lccode| and +|\uccode|) and should not make any global command definitions to be +used after the file has been read. Unfortunately some older +hyphenation files do contain such settings; thus they are +\emph{incompatible} with the mechanisms \LaTeX\ uses to ensure +independence of input and output encodings. + +After this the file |hyphen.cfg| should: +\begin{itemize} +\item set |\language| to its default value; +\item set |\lefthyphenmin| and |\righthyphenmin| to the correct values + for this default language. +\end{itemize} + +There are packages available, such as `french', that can help you with +this configuration. The `babel' collection contains many examples of +setting up a multi-lingual \LaTeX{} format. The documentation in +|lthyphen.dtx| (the source file for |hyphen.ltx|) also contains some +useful examples. + +[We intend in a future release of \LaTeX{} to provide a set of +standard commands for use in configuring hyphenation.] + + +\section{Configuring the font definition files} + +If you have special fonts available (or if some fonts are unavailable) +at your site then you may need to produce customised versions of the +font definition files; these have extension \texttt{.fd} and are read +by \LaTeX{} to obtain information about the font files installed at your +system and when to load them. + +Although we do not encourage such customisation, you will find +information about the content of these files and its syntax in the +documented source file \texttt{cmfonts.fdd} and +\textit{\LaTeXe{} font selection} in the file \texttt{fntguide.tex}. +[We hope to be able to provide further information and examples on +this subject at some time in the future.] + +Please note that the use of customised font definition files has the +following consequences. + \begin{itemize} + \item Documents produced on your system will, at best, to be + portable only in the sense of being processable at a different + site---the actual formatting will not be the same if different + fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use any customised font definition files. + \end{itemize} + +Please also note that the whilst licence conditions on the standard +font definition files allow you to produce a customised version for +your own use, they do not allow you to distribute such a customised +font definition file under the original file name! + + +\subsection*{Note to system administrators} + +If you install a version of \LaTeX{} with a locally configured font +set-up then this system is likely to 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 install, on a multi-user system, 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{Configuring compatibility mode} + +When processing documents that begin with |\documentstyle|, \LaTeXe{} +tries to emulate the old \LaTeX~2.09 system as far as possible. + +\filesection{latex209.cfg} + +Whenever a \LaTeX{} document starts with |\documentstyle|, rather than +with |\documentclass|, \LaTeX{} assumes that it is a \LaTeX~2.09 +document and therefore processes it in `compatibility mode'. This +does the following: +\begin{itemize} +\item sets the flag |\@compatibilitytrue|; +\item inputs the file |latex209.def|; +\item inputs the file |latex209.cfg| if it exists. +\end{itemize} + +The \LaTeX~2.09 set-up allowed the format itself to be customised. +When making the format with \iniTeX, the process ended with this +request: +\begin{quote}\tt + Input any local modifications here. +\end{quote} + +If your site did input any modifications at that point then the +\LaTeXe{} `compatibility mode' will not fully emulate \LaTeX~2.09 +\emph{as installed at your site}. In this case you should put all +these `local modifications' into a file called |latex209.cfg| and put +this file in the default input path at your site. These `local +modifications', although not stored in the format, will then be loaded +before any old-style document is processed. This should ensure that +you can continue to process any old documents that made use of this +local customisation. + + +\section[Configuration files for standard packages and classes]% + {Configuration files for standard packages\\ and classes} + +Most of the packages in the distribution do not have any associated +configuration files. The exceptions are listed here. + +\filesection{sfonts.cfg} + +The file |sfonts.cfg| can contain declarations relating to the use of +fonts in the slides class. +If it exists, it is read instead of the file |sfonts.def|. + +Please note that use of this configuration file has the following +consequences. + \begin{itemize} + \item Since the font set-up for slides has not yet been revised to + fit modern usage, the content of this file should be completely + updated sometime. Thus anyone writing such a configuration + file must be prepared to update it for use with future releases. + \item Documents are portable only in the sense of being processable + at a different site---the actual formatting will not be the same + if different fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use this configuration file. + \end{itemize} + + +\filesection{ltnews.cfg} + +The file |ltnews.cfg| can be used to customise some aspects of the +behaviour of the \textsf{ltnews} class; this class is used to typeset +the the one page newsletter accompanying every \LaTeX{} distribution. +If this file is present then it is read in at the beginning of the +file |ltnews.cls|. + + +\filesection{ltxdoc.cfg} + +The file |ltxdoc.cfg| can be used to customise some aspects of the +behaviour of the \textsf{ltxdoc} class; this class is used to typeset +the documented code in the |.dtx| files. If this file is present then +it is read in at the beginning of the file |ltxdoc.cls|. + +As this file is read before the \textsf{article} class is loaded, you +may pass options to \textsf{article}. For example the following line +might be added to |ltxdoc.cfg| to format the documentation for A4 paper +instead of the default US letter paper size. +\begin{quote} +|\PassOptionsToClass{a4paper}{article}| +\end{quote} +You should note however, that even if paper size options are specified, +the \textsf{ltxdoc} class always sets the |\textwidth| parameter to +355\,pt, to enable 72 columns of text to appear in the verbatim code +listings. If you really need to over-ride this you could use: +\begin{quote} +|\AtEndOfClass{\setlength{\textwidth}{ ...}}| +\end{quote} +To set the |\textwidth| to your desired value at the end of the +\textsf{ltxdoc} class. + +By default, most of the |.dtx| documented code files in the +distribution will produce a `description' section followed by full +source listing of the package. If you wish to suppress the source +listings you may add the following line to |ltxdoc.cfg|: +\begin{quote} +|\AtBeginDocument{\OnlyDescription}| +\end{quote} + +The documentation of the \textsf{ltxdoc} package, which may be typeset +from the file |ltxdoc.dtx|, contains more examples of the use of this +configuration file. + +\filesection{ltxguide.cfg} + +The class \textsf{ltxguide} is used by the `guide' documents, such as +this document, in the \LaTeX\ distribution. A configuration file +|ltxguide.cfg| may be used with this class in a way very similar to +the customisation of the \textsf{ltxdoc} class described in the +previous section. + +\section{Configuration for other supported packages} + +The `graphics' bundle of packages needs two configuration files, +primarily to specify the driver used to process the |.dvi| file that +\LaTeX{} produces. More documentation on these files comes with the +graphics bundle but we mention them here for completeness. + +\filesection{graphics.cfg} + Normally this file just specifies a default option, by calling + |\ExecuteOptions|, for example |\ExecuteOptions{dvips}| or + |\ExecuteOptions{textures}|. + + This file is read by the \textsf{graphics} package, and so affects + all the packages in the bundle that are based on \textsf{graphics}: + \textsf{graphicx}, \textsf{epsfig}, \textsf{lscape}. + +\filesection{color.cfg} + Normally this file is identical to |graphics.cfg|. It specifies the + default driver option for the \textsf{color} package. + +\section{Non-standard versions} + +If you feel the need to make a version of \LaTeX{} that differs from +the standard version in ways that are not possible using the above +configuration possibilities, then you should first read +\textit{Modifying \LaTeX{}} in the file |modguide.tex|; this +will probably make you realise that you do not have any such need. + +Thus we are sure that you will never need to create a non-standard +version and, even if you do create one, we hope that you will not +distribute such a version. Nevertheless, you are permitted to do this +provided you take great care to do the following: +\begin{itemize} +\item +respect the conditions in legal.txt and individual files regarding +modification of files and changing the name; + +\item +change all the relevant `|\typeout| banners': i.e.~those produced by +all the non-standard files in your version and by the format; + +\item + ensure that the method used to run your version is clearly + distinguished from that used to run standard \LaTeX{}; e.g.~by using + a command name or menu entry that is clearly different from + \texttt{latex} (or \texttt{LaTeX} etc). +\end{itemize} + +\subsection{Examples} + +Since we have been prompted, despite our misgivings, to document how +to do this by members of the League for Programming Freedom, it seems +appropriate to describe here a possible modification of \LaTeX{} to +produce a system called fsf\TeX. + +To do this, you should create a file called \texttt{fsftex.tex} and +then run it using \iniTeX{} and the standard \LaTeX{} format. + +The contents of the file \texttt{fsftex.tex} should be as shown on +page \pageref{fsfcode}. The particular changes to the \LaTeX{} kernel +that you wish to make need to be added to the file at the position +indicated. You can also choose the extensions you want to use for the +class and package files in your system. + +\newpage +\label{fsfcode} + +\begin{footnotesize} +\begin{verbatim} +% fsftex.tex +% +% iniTEX Source code to make a `fsftex' format. +% +% To make this format on Unix: +% +% initex \&latex fsftex +% +% Then to run the format on file.tex: +% +% tex &fsftex file +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% *** VERY IMPORTANT!!! *** +% Change the typeout banner so users know that they +% are NOT running Standard LaTeX. +\everyjob{\typeout{fsfTeX 1.0 based on LaTeX2e \fmtversion}} +\makeatletter + +% fsfTeX changes some LaTeX internals: +% ... put what you like here ... +\def \fsf@xxxx {Some arbitrary \emph{freely modifiable} code goes here} + +% fsfTeX class files have extension .fcl (this week): +\def \@clsextension {fcl} + +% fsfTeX package files have extension .fsy: +\def \@pkgextension {fsy} + +% Change the file handling so that when a fsfTeX package or class +% is not available, the standard LaTeX file will be read. +% +% For example, \documentclass{article} will load article.fcl if such +% a file exists, but article.cls otherwise. This allows arbitrary +% processing on `article' documents without changing the standard +% article.cls file. + +\let\fsf@missingfileerror\@missingfileerror + +\def\@missingfileerror#1#2{% + \ifx #2\@clsextension + \InputIfFileExists {#1.cls}% + {\wlog {fsfTeX: loading #1.cls rather than #1.#2.}}% + {\fsf@missingfileerror {#1}{#2}}% + \else + \ifx #2\@pkgextension + \InputIfFileExists {#1.sty}% + {\wlog {fsfTeX: loading #1.sty rather than #1.#2.}}% + {\fsf@missingfileerror {#1}{#2}}% + \else + \fsf@missingfileerror {#1}{#2}% + \fi + \fi +} + +\makeatother +\dump +\end{verbatim} +\end{footnotesize} + +\end{document} |