Debian Codegraph @

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