path: root/macros/latex-dev/base/cfgguide.tex

% \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}