Configuration options for L^{A}TEX 2ε

\begin{matrix}c \\ ◯ \end{matrix} Copyright 1995, L^{A}TEX3 Project Team. All rights reserved.

17 June 1995

Contents

1 Configuring L^{A}TEX 2

2 System configuration 2 2.1 texsys.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Configuring the L^{A}TEX format 2 3.1 fonttext.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.2 fontmath.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.3 preload.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.4 hyphen.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Configuring compatibility mode 5 4.1 latex209.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

5 Configuration files for standard packages and classes 5 5.1 sfonts.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.2 ltxdoc.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5.3 ltxguide.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

6 Configuration for other supported packages 6 6.1 graphics.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 6.2 color.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1 Configuring L^{A}TEX

Since one of the main aims of the new standard L^{A}TEX is to provide a highly portable document format, the number of configuration possibilities is strictly limited. 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 L^{A}TEX system may be configured differently.

Local configuration options are, by convention, placed in ‘configuration files’, which have extension cfg. This file lists the possibilities for configuration in the most recent release of L^{A}TEX.

2 System configuration

2.1 texsys.cfg

This is the only configuration file that must be present. During installation, if L^{A}TEX can not 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, L^{A}TEX is not able to test reliably whether a given file exists on the system.

The contents of the file texsys.cfg allow L^{A}TEX to cope with various differences between the behaviour 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 L^{A}TEX 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 create the L^{A}TEX format on your system. If this happens then start the process again with an empty texsys.cfg file; this will produce a format that should always ‘work’ and, at least, allow you to typeset the documentation. However, it is possible be that L^{A}TEX can find only those files that are in the current directory. In that case you must set the macro \input@path correctly for your system.

3 Configuring the L^{A}TEX format

There are four configuration files to control personal preferences that may be incorporated into the L^{A}TEX format file, latex.fmt. The range of preferences that can be configured by these files is strictly limited so as to ensure document portability.

All four files work in the same way: if the file ⟨file⟩.cfg is found, it will be input by iniTEX; otherwise a default file ⟨file⟩.ltx will be input instead. Thus, providing one of these .cfg files completely overrides any settings in the corresponding standard .ltx file.

3.1 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 are normally used in text mode, as well as the behavior of font attribute commands such as \textbf etc. It can be used, for example, to produce a L^{A}TEX format that by default typesets documents in Times.

Please note that use of this configuration file has the following consequences.

• 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.

• The L^{A}TEX3 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.

The default file fonttext.ltx comes from the documented file fontdef.dtx so this file should be consulted for further information.

3.2 fontmath.cfg

The file fontmath.cfg can contain declarations relating to the use of fonts in math mode.

If it exists, it defines which font shapes are used in math mode. 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 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 that use of this configuration file has the following consequences.

• Since the content of this configuration file is likely to change in the future, anyone writing such a file must be prepared to update it for use with future releases.

• 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.

• The L^{A}TEX3 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.

The default file fontmath.ltx comes from the documented file fontdef.dtx so this file should be consulted for further information.

3.3 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 can not 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 L^{A}TEX 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.

3.4 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; L^{A}TEX 2.09 always loaded this file when its format was made.

With L^{A}TEX 2ε 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:

• set \language=⟨number⟩;

• load the file which contains the hyphenation patterns for that language.

If the patterns you use require some definitions or assignments then a group should be used to keep such changes local to their file.

After this the file hyphen.cfg should:

• set \language to its default value;

• set \lefthyphenmin and \righthyphenmin to the correct values for this default language.

There are packages available, such as ‘french’, that can help you with this configuration. The ‘babel’ collection contains many examples of setting up a multilingual L^{A}TEX format. The documentation in lthyphen.dtx (the source file for hyphen.ltx) also contains some useful examples.

4 Configuring compatibility mode

When processing documents that begin with \documentstyle, L^{A}TEX 2ε tries to emulate the old L^{A}TEX 2.09 system as far as possible.

4.1 latex209.cfg

Whenever a L^{A}TEX document starts with \documentstyle, rather than with \documentclass, L^{A}TEX assumes that it is a L^{A}TEX 2.09 document and therefore processes it in ‘compatibility mode’. This does the following:

   • sets the flag \@compatibilitytrue;

• inputs the file latex209.def;

• inputs the file latex209.cfg if it exists.

The L^{A}TEX 2.09 set-up allowed the format itself to be customised. When making the format with iniTEX, the process ended with this request:

     Input any local modifications here.

If your site did input any modifications at that point then the L^{A}TEX 2ε ‘compatibility mode’ will not fully emulate L^{A}TEX 2.09 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. For example, if your site used NFSS1 with ‘newlfont’, you would add \ExecuteOptions{newlfont}

to latex209.cfg.

5 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.

5.1 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.

5.2 ltxdoc.cfg

The file ltxdoc.cfg can be used to customise some aspects of the behaviour of the 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 article class is loaded, you may pass options to 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.

     \PassOptionsToClass{a4paper}{article}

You should note however, that even if paper size options are specified, the 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:

     \AtEndOfClass{\setlength{\textwidth}{ ...}}

To set the \textwidth to your desired value at the end of the 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:
     \AtBeginDocument{\OnlyDescription}

The documentation of the ltxdoc package, which may be typeset from the file ltxdoc.dtx, contains more examples of the use of this configuration file.

5.3 ltxguide.cfg

The class ltxguide is used by the ‘guide’ documents, such as this document, in the L^{A}TEX distribution. A configuration file, ltxguide.cfg, may be used with this class in a way very similar to the customisation of the ltxdoc class described in the previous section.

6 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 L^{A}TEX produces. More documentation on these files comes with the graphics bundle but we mention them here for completeness.

6.1 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 graphics package, and so affects all the packages in the bundle that are based on graphics: graphicx, epsfig, lscape.

6.2 color.cfg

Normally this file is identical to graphics.cfg. It specifies the default driver option for the colour package.