summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/cfgguide.tex
blob: 84cde10c84fa541bd0bd31242af0693496df88ae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
% \iffalse meta-comment
%
% Copyright (C) 1993-2020
% 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: 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 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}