1 % \iffalse meta-comment
3 % Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009
4 % The LaTeX3 Project and any individual authors listed elsewhere
7 % This file is part of the LaTeX base system.
8 % -------------------------------------------
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 2005/12/01 or later.
18 % This file has the LPPL maintenance status "maintained".
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
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.
29 % Filename: cfgguide.tex
31 \NeedsTeXFormat{LaTeX2e
}[1995/
12/
01]
33 \documentclass{ltxguide
}[1995/
11/
28]
35 \newcommand{\filesection}[1]{\subsection{\sffamily{#1}}}
36 \newcommand{\iniTeX}{ini
\TeX}
38 \setcounter{secnumdepth
}{0}
40 \title{Configuration options for
\LaTeXe}
42 \author{\copyright~Copyright
1998,
2001,
2003 \LaTeX3 Project Team.\\
45 \date{14 February
2003}
55 \section{Configuring
\LaTeX}
57 Since one of the main aims of the new standard
\LaTeX{} is to give all
58 users the freedom provided by a reliable
document processing system
59 linked to a highly portable
document format, the number of
60 configuration possibilities is strictly limited. The reasons for this
61 are explained in more detail in the article
62 \textit{Modifying
\LaTeX{}} in the file
\texttt{modguide.tex
}.
63 An important consequence of this is that any
document that relies on
64 any extension package must declare this package within the
document
65 file; this helps to ensure that the
document will work at a different
66 site, where the
\LaTeX{} system may be configured differently.
68 Local configuration options are, by convention, placed in
69 `configuration files', which have extension |.cfg|. This
document
70 describes the possibilities for configuration in this release of
71 \LaTeX; it also explains how to configure the font definition files to
72 take advantage of the available fonts.
74 The last section considers briefly how to proceed if you require
75 further customisation of the formatter.
78 \section{System configuration
}
80 \filesection{texsys.cfg
}
82 This is the only configuration file that
\emph{must
} be present.
83 During installation, if
\LaTeX\ cannot find a file with this name
84 then a default file |texsys.cfg|, consisting entirely of comments, is
85 written out and used. Note that, until this file has been read,
86 \LaTeX{} is not able to test reliably whether a given file exists on
89 The contents of the file |texsys.cfg| allow
\LaTeX{} to cope with
90 various differences between the behaviours of different
\TeX{} systems,
91 mainly in relation to file handling. The default version of this file
92 contains, in its comments, possible settings that may be needed for a
93 range of
\TeX{} systems. For more information, typeset the file
96 If you have copied your
\LaTeX{} installation from a computer that
97 used a different operating system then you may well have a version of
98 |texsys.cfg| that will make it difficult to install
\LaTeX{} on your
99 system. If this happens then start the process again with an empty
100 |texsys.cfg| file; this will produce an installation that should, at
101 least, allow you to typeset the documentation. However, it is
102 possible that
\LaTeX{} can still find only those files that are in the
103 current directory; in this case you must set the macro |
\input@path|
104 correctly for your system.
107 \section{Configuring the
\LaTeX\ format
}
109 There are four configuration files that enable personal preferences to
110 be incorporated into the
\LaTeX{} format file |latex.fmt|. The range
111 of preferences that can be configured by these files is strictly
112 limited as this helps to ensure
document portability.
114 All four files work in the same way: if the file
\m{file
}|.cfg| is
115 found, it will be input by
\iniTeX; otherwise a default file
116 \m{file
}|.ltx| will be input; this is sometimes done via a
117 minimal
\m{file
}|.cfg| that simply inputs
\m{file
}|.ltx|. Thus,
118 providing your own version of any of these |.cfg| files can completely
119 override any settings in the corresponding default standard |.ltx|
123 \subsection{Font configuration
}
125 Before you even think about configuring the font declarations by
126 producing a file |fontmath.cfg| or |fonttext.cfg|, you should
127 read the documented file |fontdef.dtx|. This is the source file from
128 which the default files |fonttext.ltx| and |fontmath.ltx| are
129 produced; it contains information concerning the
130 contents of the default files and what sort of customisation is
131 possible. In particular, it describes in detail the effects of
132 individual customisations on
document portability including: which
133 customisations can be made without endangering the ability to exchange
134 documents with other sites (even if the formatting differs); and which
135 things should be left untouched because they will make your system so
136 different from others that the documents it produces will be
139 \textbf{WARNING
} Please note that use of either of these font
140 configuration files has the following consequences.
142 \item Since the content of the file |fontdef.dtx|
\emph{might
}
143 change in the future, anyone writing a font configuration file
144 must be prepared to update it for use with future releases.
145 \item Documents produced on your system are likely, at best, to be
146 portable only in the sense of being processable at a different
147 site---the actual formatting will not be the same if different
149 \item The
\LaTeX3 project team will not be able to support you in
150 diagnosing problems if these cannot be reproduced with a format
151 that does not use any configuration files.
154 \filesection{fonttext.cfg
}
156 The file |fonttext.cfg| can contain declarations relating to the use
157 of fonts in text modes.
159 If it exists, it defines which font shapes, families and encodings are
160 normally used in text mode, as well as the behavior of font attribute
161 commands such as |
\textbf| etc.
163 It could be used, for example, to produce a
\LaTeX\ format that, by
164 default, typesets documents using Times fonts. Be warned, however,
165 that such customisation can have unfortunate consequences; so please
166 read carefully this section and the file |fontdef.dtx| below if you
167 are thinking of doing this.
169 Please note carefully the above
\textbf{warning
}.
171 \filesection{fontmath.cfg
}
173 The file |fontmath.cfg| can contain declarations relating to the use
174 of fonts in math mode.
176 If it exists, it defines which fonts in which sizes are used in math
177 mode, and how they are used. It also defines all the math mode
178 commands that `are likely to' depend on the choice of math fonts used
179 (e.g.~commands that depend on the position of a glyph in a math font).
181 The main reason for the existence of this file is to provide for future
182 updates when a standard math font encoding is available. Right now we
183 do
\emph{not
} encourage the use of this configuration file other than
184 for special applications. Writing a proper configuration file for math
185 mode needs expert knowledge!
187 Please note carefully the above
\textbf{warning
}.
189 \filesection{preload.cfg
}
191 The contents of the file |preload.cfg| can control the preloading of
192 commonly used fonts. Preloading fonts speeds up the processing of
193 documents but, because fonts cannot be `unloaded', you should not
194 preload too many; otherwise you may be unable to process documents
195 requiring unusual font families.
197 The default file |preload.ltx| is produced from |preload.dtx|. It
198 loads only a few fonts and these are a good choice if you normally use
199 documents at the default,
10\,pt, size. If you normally use
11\,pt
200 or~
12\,pt then the time for
\LaTeX\ to startup may be noticeably
201 decreased if you preload the corresponding fonts for the sizes you
202 use. Similarly, if you normally use a different font family, for
203 example Times Roman (|ptm|) then you may want to preload fonts in this
204 family rather than the default Computer Modern fonts.
206 \subsection{Hyphenation configuration
}
208 \filesection{hyphen.cfg
}
210 In order to hyphenate text,
\TeX{} must have hyphenation patterns and,
211 since these patterns can be loaded only by
\iniTeX, the choice of
212 which patterns to load must be made when the format is created.
214 The hyphenation patterns for American English are stored in the file
215 named |hyphen.tex|;
\LaTeX~
2.09 always loaded this file when its
218 With
\LaTeXe{} it is possible to configure which hyphenation patterns
219 are to be loaded into the format. When
\iniTeX{} is processing
220 |latex.ltx|, it looks for a file called |hyphen.cfg|; this file can
221 be used to control which hyphenation patterns are loaded. If a file
222 |hyphen.cfg| cannot be found then
\iniTeX{} will load the file
225 The file |hyphen.ltx| loads the file |hyphen.tex| if it can find it;
226 otherwise it stops with an error since a format with no hyphenation
227 patterns is not very useful. It then sets |
\language=
0| and it sets
228 the values |
\lefthyphenmin=
2| and |
\righthyphenmin=
3|, which are
229 needed for American English.
231 Thus, if you want any other patterns to be loaded then you should
232 create a file |hyphen.cfg|. For each language for which you wish to
233 load hyphenation patterns this file should:
235 \item set |
\language=|
\m{number
};
236 \item load the file which contains the hyphenation patterns for that
239 If the patterns you use require some definitions or assignments then
240 a group should be used to keep such changes local to their file.
242 \textbf{Note.
} The hyphenation files that are read in should
\emph{only
}
243 set the hyphenation tables for the language, using the commands
244 |
\hyphenation| and |
\patterns|. In particular they should make no
245 assignments to the lowercase/uppercase tables (|
\lccode| and
246 |
\uccode|) and should not make any global command definitions to be
247 used after the file has been read. Unfortunately some older
248 hyphenation files do contain such settings; thus they are
249 \emph{incompatible
} with the mechanisms
\LaTeX\ uses to ensure
250 independence of input and output encodings.
252 After this the file |hyphen.cfg| should:
254 \item set |
\language| to its default value;
255 \item set |
\lefthyphenmin| and |
\righthyphenmin| to the correct values
256 for this default language.
259 There are packages available, such as `french', that can help you with
260 this configuration. The `babel' collection contains many examples of
261 setting up a multi-lingual
\LaTeX{} format. The documentation in
262 |lthyphen.dtx| (the source file for |hyphen.ltx|) also contains some
265 [We intend in a future release of
\LaTeX{} to provide a set of
266 standard commands for use in configuring hyphenation.
]
269 \section{Configuring the font definition files
}
271 If you have special fonts available (or if some fonts are unavailable)
272 at your site then you may need to produce customised versions of the
273 font definition files; these have extension
\texttt{.fd
} and are read
274 by
\LaTeX{} to obtain information about the font files installed at your
275 system and when to load them.
277 Although we do not encourage such customisation, you will find
278 information about the content of these files and its syntax in the
279 documented source file
\texttt{cmfonts.fdd
} and
280 \textit{\LaTeXe{} font selection
} in the file
\texttt{fntguide.tex
}.
281 [We hope to be able to provide further information and examples on
282 this subject at some time in the future.
]
284 Please note that the use of customised font definition files has the
285 following consequences.
287 \item Documents produced on your system will, at best, to be
288 portable only in the sense of being processable at a different
289 site---the actual formatting will not be the same if different
291 \item The
\LaTeX3 project team will not be able to support you in
292 diagnosing problems if these cannot be reproduced with a format
293 that does not use any customised font definition files.
296 Please also note that the whilst licence conditions on the standard
297 font definition files allow you to produce a customised version for
298 your own use, they do not allow you to distribute such a customised
299 font definition file under the original file name!
302 \subsection*
{Note to system administrators
}
304 If you install a version of
\LaTeX{} with a locally configured font
305 set-up then this system is likely to produce documents that are no
306 longer `formatting compatible'; for example, the use of different
307 default fonts will most likely produce different line and page breaks.
308 If you do install, on a multi-user system, a system that is configured
309 in such a way that it is not `formatting compatible' then you should
310 consider carefully the needs of users who need to create portable
311 documents. A good way to provide for their needs is to make
312 available, in addition, a standard form of
\LaTeX{} without any
313 `formatting incompatible' customisations.
316 \section{Configuring compatibility mode
}
318 When processing documents that begin with |
\documentstyle|,
\LaTeXe{}
319 tries to emulate the old
\LaTeX~
2.09 system as far as possible.
321 \filesection{latex209.cfg
}
323 Whenever a
\LaTeX{} document starts with |
\documentstyle|, rather than
324 with |
\documentclass|,
\LaTeX{} assumes that it is a
\LaTeX~
2.09
325 document and therefore processes it in `compatibility mode'. This
328 \item sets the flag |\@compatibilitytrue|;
329 \item inputs the file |latex209.def|;
330 \item inputs the file |latex209.cfg| if it exists.
333 The
\LaTeX~
2.09 set-up allowed the format itself to be customised.
334 When making the format with
\iniTeX, the process ended with this
337 Input any local modifications here.
340 If your site did input any modifications at that point then the
341 \LaTeXe{} `compatibility mode' will not fully emulate
\LaTeX~
2.09
342 \emph{as installed at your site
}. In this case you should put all
343 these `local modifications' into a file called |latex209.cfg| and put
344 this file in the default input path at your site. These `local
345 modifications', although not stored in the format, will then be loaded
346 before any old-style
document is processed. This should ensure that
347 you can continue to process any old documents that made use of this
351 \section[Configuration files for standard packages and classes
]%
352 {Configuration files for standard packages\\ and classes
}
354 Most of the packages in the distribution do not have any associated
355 configuration files. The exceptions are listed here.
357 \filesection{sfonts.cfg
}
359 The file |sfonts.cfg| can contain declarations relating to the use of
360 fonts in the slides class.
361 If it exists, it is read instead of the file |sfonts.def|.
363 Please note that use of this configuration file has the following
366 \item Since the font set-up for slides has not yet been revised to
367 fit modern usage, the content of this file should be completely
368 updated sometime. Thus anyone writing such a configuration
369 file must be prepared to update it for use with future releases.
370 \item Documents are portable only in the sense of being processable
371 at a different site---the actual formatting will not be the same
372 if different fonts are used.
373 \item The
\LaTeX3 project team will not be able to support you in
374 diagnosing problems if these cannot be reproduced with a format
375 that does not use this configuration file.
379 \filesection{ltnews.cfg
}
381 The file |ltnews.cfg| can be used to customise some aspects of the
382 behaviour of the
\textsf{ltnews
} class; this class is used to typeset
383 the the one page newsletter accompanying every
\LaTeX{} distribution.
384 If this file is present then it is read in at the beginning of the
388 \filesection{ltxdoc.cfg
}
390 The file |ltxdoc.cfg| can be used to customise some aspects of the
391 behaviour of the
\textsf{ltxdoc
} class; this class is used to typeset
392 the documented code in the |.dtx| files. If this file is present then
393 it is read in at the beginning of the file |ltxdoc.cls|.
395 As this file is read before the
\textsf{article
} class is loaded, you
396 may pass options to
\textsf{article
}. For example the following line
397 might be added to |ltxdoc.cfg| to format the documentation for A4 paper
398 instead of the default US letter paper size.
400 |
\PassOptionsToClass{a4paper}{article
}|
402 You should note however, that even if paper size options are specified,
403 the
\textsf{ltxdoc
} class always sets the |
\textwidth| parameter to
404 355\,pt, to enable
72 columns of text to appear in the verbatim code
405 listings. If you really need to over-ride this you could use:
407 |
\AtEndOfClass{\setlength{\textwidth}{ ...
}}|
409 To set the |
\textwidth| to your desired value at the end of the
410 \textsf{ltxdoc
} class.
412 By default, most of the |.dtx| documented code files in the
413 distribution will produce a `description' section followed by full
414 source listing of the package. If you wish to suppress the source
415 listings you may add the following line to |ltxdoc.cfg|:
417 |
\AtBeginDocument{\OnlyDescription}|
420 The documentation of the
\textsf{ltxdoc
} package, which may be typeset
421 from the file |ltxdoc.dtx|, contains more examples of the use of this
424 \filesection{ltxguide.cfg
}
426 The class
\textsf{ltxguide
} is used by the `guide' documents, such as
427 this
document, in the
\LaTeX\ distribution. A configuration file
428 |ltxguide.cfg| may be used with this class in a way very similar to
429 the customisation of the
\textsf{ltxdoc
} class described in the
432 \section{Configuration for other supported packages
}
434 The `graphics' bundle of packages needs two configuration files,
435 primarily to specify the driver used to process the |.dvi| file that
436 \LaTeX{} produces. More documentation on these files comes with the
437 graphics bundle but we mention them here for completeness.
439 \filesection{graphics.cfg
}
440 Normally this file just specifies a default option, by calling
441 |
\ExecuteOptions|, for example |
\ExecuteOptions{dvips}| or
442 |
\ExecuteOptions{textures
}|.
444 This file is read by the
\textsf{graphics
} package, and so affects
445 all the packages in the bundle that are based on
\textsf{graphics
}:
446 \textsf{graphicx},
\textsf{epsfig
},
\textsf{lscape
}.
448 \filesection{color.cfg
}
449 Normally this file is identical to |graphics.cfg|. It specifies the
450 default driver option for the
\textsf{color} package.
452 \section{Non-standard versions
}
454 If you feel the need to make a version of
\LaTeX{} that differs from
455 the standard version in ways that are not possible using the above
456 configuration possibilities, then you should first read
457 \textit{Modifying
\LaTeX{}} in the file |modguide.tex|; this
458 will probably make you realise that you do not have any such need.
460 Thus we are sure that you will never need to create a non-standard
461 version and, even if you do create one, we hope that you will not
462 distribute such a version. Nevertheless, you are permitted to do this
463 provided you take great care to do the following:
466 respect the conditions in legal.txt and individual files regarding
467 modification of files and changing the name;
470 change all the relevant `|
\typeout| banners': i.e.~those produced by
471 all the non-standard files in your version and by the format;
474 ensure that the method used to run your version is clearly
475 distinguished from that used to run standard
\LaTeX{}; e.g.~by using
476 a command name or menu entry that is clearly different from
477 \texttt{latex
} (or
\texttt{LaTeX
} etc).
480 \subsection{Examples
}
482 Since we have been prompted, despite our misgivings, to
document how
483 to do this by members of the League for Programming Freedom, it seems
484 appropriate to describe here a possible modification of
\LaTeX{} to
485 produce a system called fsf
\TeX.
487 To do this, you should create a file called
\texttt{fsftex.tex
} and
488 then run it using
\iniTeX{} and the standard
\LaTeX{} format.
490 The contents of the file
\texttt{fsftex.tex
} should be as shown on
491 page
\pageref{fsfcode
}. The particular changes to the
\LaTeX{} kernel
492 that you wish to make need to be added to the file at the position
493 indicated. You can also choose the extensions you want to use for the
494 class and package files in your system.
503 % iniTEX Source code to make a `fsftex' format.
505 % To make this format on Unix:
507 % initex \&latex fsftex
509 % Then to run the format on file.tex:
513 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
514 % *** VERY IMPORTANT!!! ***
515 % Change the typeout banner so users know that they
516 % are NOT running Standard LaTeX.
517 \everyjob{\typeout{fsfTeX
1.0 based on LaTeX2e
\fmtversion}}
520 % fsfTeX changes some LaTeX internals:
521 % ... put what you like here ...
522 \def \fsf@xxxx
{Some arbitrary
\emph{freely modifiable
} code goes here
}
524 % fsfTeX class files have extension .fcl (this week):
525 \def \@clsextension
{fcl
}
527 % fsfTeX package files have extension .fsy:
528 \def \@pkgextension
{fsy
}
530 % Change the file handling so that when a fsfTeX package or class
531 % is not available, the standard LaTeX file will be read.
533 % For example, \documentclass{article} will load article.fcl if such
534 % a file exists, but article.cls otherwise. This allows arbitrary
535 % processing on `article' documents without changing the standard
538 \let\fsf@missingfileerror\@missingfileerror
540 \def\@missingfileerror
#1#2{%
541 \ifx #2\@clsextension
542 \InputIfFileExists {#1.cls
}%
543 {\wlog {fsfTeX: loading
#1.cls rather than
#1.
#2.
}}%
544 {\fsf@missingfileerror
{#1}{#2}}%
546 \ifx #2\@pkgextension
547 \InputIfFileExists {#1.sty
}%
548 {\wlog {fsfTeX: loading
#1.sty rather than
#1.
#2.
}}%
549 {\fsf@missingfileerror
{#1}{#2}}%
551 \fsf@missingfileerror
{#1}{#2}%