% $Id: genguide.tex,v 1.9 1994/02/01 21:21:16 schrod Exp $
%----------------------------------------------------------------------
% Copyright (c) 1988-1994 by J.Schrod. Distributed under the GPL.
%
% Generic Local Guide for LaTeX 2e distribution
%
% [LaTeX2e]
% (history at end)
%%% Keep the dates current
\def\LaTeXdate{December~21,~1993}
\def\erratadate{\fbox{errata date}}
% This file can be used to produce a `Local Guide' for LaTeX users
% with informations specific for one installation. There is a section
% with all classes/packages mentioned, but they are not all explained
% in full. Instead often the place is mentioned where the reader may
% find the real information -- therefore this Local Guide is more the
% beginning of a search.
% All places where something must be changed for a specific
% installation are marked with the todo environment. In print this
% places are framed.
% The chapter `Errata and Additions to the Manual' of the original
% Local Guide was deleted, it is transformed in a single document
% (errata.tex).
\documentclass{locguide}
\RCS $Revision: 1.9 $
\RCS $Date: 1994/02/01 21:21:16 $
% !!!!!!!!!!!!!!!!!!!!!!!!!!!!! ATTENTION !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
%
% This document is not in the public domain, but you may freely
% redistribute it. You must not distribute a DVI file of this document
% alone, it must be always accompanied by the *full* LaTeX sources.
% If you have additions, senseful alterations, discovered errors or
% omissions, you should send them to me, then other people will
% benefit from your work, too.
%
% The preferred way to reach me is per electronic mail:
% schrod@iti.informatik.th-darmstadt.de
%
% If you don't have email access, my current address is (in TeX-form):
% Technical University of Darmstadt
% WG Systems programming
% Joachim Schrod
% Alexanderstra\ss{}e 10
%
% D-64283 Darmstadt
%
% Please, no phone calls -- I'm not paid for this work...
%
% !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ATTENTION !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
%\makeindex %%% when I will find the time
\begin{document}
\title{%
\if \lgNotComplete
Generic Local Guide for\\
\fi
\LaTeX{} on \platform{}\\
{\small for \LaTeX{} (as of \LaTeXdate)}%
}
\author{
%
%\begin{todo}{}
\fbox{add your name here}
%\end{todo}
%
\end{tabular}\\ % KLUDGE, no fine control available
\begin{tabular}[t]{c} % <grmbl>
Joachim Schrod\and Christine Detig
}
\if \lgNotComplete
\date{\RCSDate}
\else
\date{\today} % you might want to adapt this, too
\fi
\maketitle
\tableofcontents
\vskip 2cm plus 1fill
\begingroup \samepage
\footnotesize
This Local Guide was derived from the \textit{Generic Local Guide}
(GLG), Revision~\RCSRevision, as of \RCSDate{}. The GLG is copyright
\copyright{} 1988--1994 by Joachim Schrod. It is distributed under the
GNU General Public License. It was inspired by the `Local Guide' for
\LaTeX{}~2.09 at the SRC of DEC, written by Leslie Lamport.
This text may (and should) be altered to fit to the local
environment, \eg{}, local classes and packages should be added.
\TeX{} is a trademark of the AMS\@.
All other trademarks for devices or software are trademarks of the
respective producers.
\endgroup
\frontMatterFinished
% This document is generic for an arbitrary platform
%
\begin{todo}{}
declare |\platform|
\end{todo}
%
\def\platform{\fbox{platform}}
% If the Babel system for usage of other than english text is not
% installed, \InstalledBabeltrue must be substituted
% by \InstalledBabelfalse.
%
\begin{todo}{}
declare |\ifInstalledBabel|
\end{todo}
%
\InstalledBabeltrue
% If the MakeIndex program for index preparation is not available,
% \InstalledMakeIndextrue must be substitutex by \InstalledMakeIndexfalse.
%
\begin{todo}{}
declare |\ifInstalledMakeIndex|
\end{todo}
%
\InstalledMakeIndextrue
\section{Introduction}
\LaTeX{} runs on a variety of computers at many different sites. This
document tells you how to use \LaTeX{} on \platform{} and describes
the local installation. We assume that you are familiar with the
activation of your \TeX{} system. \LaTeX{} itself is described in the
manual---\textit{\LaTeX{}: A~Document Preparation System} (2nd~edition).
Another useful book is \textit{The \LaTeX{} Companion} (both published by
Addison Wesley). A full reference of these and a list of other related
publications is given in the bibliography on
page~\pageref{sec:bibliography}.
%
\begin{todo}{}
Hints to other system-specific manuals, especially to the
installation manual.
\end{todo}
%
\subsection*{What You Get}
The \LaTeX{} you receive with this delivery is the \LaTeXe{}
standard release.
When we speak of \LaTeX{} in the following, we mean \LaTeXe{}. Up to
%
\begin{fixme}
Date until \LaTeX{} 2.09 was delivered
\end{fixme}
%
\LaTeX{} version~2.09 was distributed. \LaTeXe{} is fully upward
compatible to the old version. Features only found in \LaTeXe{} are a
high-level concept of classes and packages to structure your document,
and an integration of the New Font Selection Scheme (NFSS).
%
\ifInstalledBabel
You can process documents in the languages
%
\begin{todo}{}
List all languages for which hyphenation patterns are installed.
\end{todo}
%
For texts in other languages, this \LaTeX{} installation
doesn't know how to hyphenate them.
%
\begin{fixme}
How does \package{babel} integrate in \LaTeXe{}?
\end{fixme}
%
\begin{fixme}
If a package abstract for \package{babel} exists,
here is a good place for a crossref.
\end{fixme}
%
\else
The delivered \LaTeX{} will process your english documents properly.
If you want to process texts in other languages,
the \package{babel} package must be installed.
\fi
If you think that you have discovered an error in
\LaTeX{}, \ie{}, if \LaTeX{} has an other way of acting than
it is described in the documentation, inform your local
\LaTeX{} guru or your distributor. He should be aware of
any possible \LaTeX{} bugs or undocumented anomalies.
If you are on your own, have a look at section~\ref{sec:help}.
%
\begin{fixme}
Where do I introduce CTAN? I need it in the module section, here
might be a good place for a reference; the real introduction might
be done in the help section.
\end{fixme}
%
In any case, remember:
%
\begin{center}
\it If all else fails, read the documentation!
\end{center}
\subsection*{How Things are Organized}
%
\begin{todo}{}
If the operating system does not support file hierarchies the
complete following paragraph must be deleted and all filenames
must be checked.
\end{todo}
%
This description assumes that your \LaTeX{} files will not all reside
in one directory, but will be grouped in specific directories according to
their function.
%
\begin{todo}{}
Describe in which main directory the specific directories reside
(or if they are at different places).
Fill in site specific locations, \ie{}, look for all |\dir| tags in
this file and adapt them.
\end{todo}
%
\begin{description}
\item[user relevant files]
All files which are needed for the day-to-day usage are found in
\dir{inputs}.
\item[class and package sources]
Some classes and packages are documented with the |doc| system.
It allows to extract from one source file (\ext{dtx}) the class
(\ext{cls}), package (\ext{sty}), or class option (\ext{clo})
files and also---together with a corresponding |docstrip| batch file
(\ext{ins})---to create a |doc| driver file (\ext{drv}). This is a
\LaTeX{} source that creates a documented, formatted version of
the source.
This information is of interest for you since the sources may
contain a user manual. It is also important if you want to program
your own classes or packages, here you find the documentation of
internal interfaces needed to adapt \LaTeX{} to your needs.
%
\begin{fixme}
Provide recommendation to install them somewhere!
\end{fixme}
%
\item[user manuals]
Some classes or packages will come with a separate user manual.
Sometimes, only a \DVI{} file will be available. They reside in a
directory \dir{latex/doc}. Here you will also find the file
\file{features.tex} which describes the differences between
\LaTeX{}~2.09 and \LaTeXe{}.
\end{description}
\section{Let's Start}
\subsection{Running a Sample File}
\label{sec:sample}
Before preparing your own documents, you may want to get acquainted
with \LaTeX{} by running it on a sample input file. To process the
sample file first make your own copy of the file \file{example.tex}
that resides in the directory \dir{latex/doc}. This copy should be now
in your current directory; you can edit it just like any other file.
If you destroy or mess up your copy, get yourself a fresh one.
Next, run \LaTeX{} on the file \file{example.tex}.
%
\begin{todo}{}
Describe how to call \LaTeX{}.
\end{todo}
%
When \LaTeX{} has finished, it will have produced the file
\file{example.dvi}. You can now view or print this file.
%
\begin{todo}{}
Describe how to call local previewer and/or printer driver.
For sentimental reasons, you may want to include a hint to the
printer near Jane's desk.
\end{todo}
%
After it has been printed, you can delete the \LOG{} and \DVI{}
files to save your disk space.
\subsection{Creating Own Documents}
You must use a text editor to prepare an input file for \LaTeX{}. The
easiest way to start learning about \LaTeX{} is by examining the file
\file{example.tex} with your text editor.
It is best to obtain your own copy of this file in your working directory.
After you have prepared your input file, whose name should have
the extension \ext{tex}, you must run it through \LaTeX{} and print the
output. Follow the instructions of section~\ref{sec:sample},
except use
%
\begin{todo}{}
with menu systems: select
\end{todo}
%
the name of your own input file instead of \file{example.tex}.
%
\begin{todo}{}
List local (or good usable) editors. Explain how these editors
might create characters which will produce the error message
``!~Text line contains an invalid character''.
\end{todo}
%
Furthermore we would like to remind you that not all special
characters of your computer can be used in your \LaTeX{}
documents.
%
\begin{todo}{}
List all special characters that can be used.
\end{todo}
%
Please note that documents which contain an extended input character
set may not necessarily be exchangeable with other sites. If you are
planning to exchange documents, especially via electronic mail, it is
wise to restrict yourself to the default character set and write
special characters as \TeX{} tags.
\subsection{What's Special with \LaTeX{} on \platform{}?}
\label{sec:platform}
One of the most important features of \LaTeX{} is its portability. If
you write a document you can be sure that you can work with it on any
other platform where \TeX{} runs. So it's a matter of course that all
features described in the \LaTeX{} book are provided by the
implementation on \platform{} as well.
%
\begin{todo}{}
Are the invisible fonts for the \class{slides} class available?
What about \BibTeX{} and \MakeIndex{}?
\end{todo}
Nevertheless each computer platforms has its peculiarities, this
section will present you the most important specialities that concern
\LaTeX{}.
%
\begin{todo}{}
The following paragraph may be deleted with operating systems
that have file versions. Probably it must be described instead
that the new version of the auxiliary files which was produced
by the erroneous run must be deleted.
\end{todo}
%
While using \LaTeX{} problems can arise with the
cross references. This is because a previous version of a file is
destroyed if a file with the same name shall
be created. Thus, if an error forces you to stop \LaTeX{}
prematurely---by typing |x| after an error at the prompt~|?| or by
interrupting it
%
\begin{todo}{}
Describe how to interrupt a program; the next parenthesis might be
usable.
\end{todo}
%
(\ie{}, by typing \emph{Control-C})
%
\unskip---then the files that \LaTeX{} was
writing are incomplete, and the previous complete versions have
been destroyed. You probably don't care about the output on the
\DVI{} file, but if you are making a table of contents or using
cross-referencing tags, then \LaTeX{} also writes one or more
\emph{auxiliary files} that it reads the next time it processes
the same input file. If the auxiliary files are incomplete
because \LaTeX{} was stopped before reaching the end of its input
file, then the table of contents and cross-references will be
incorrect the next time \LaTeX{} is run on the same input file.
It can even happen that reading this auxiliary files causes a lot
of error messages. At least you will have to run \LaTeX{} a
second time to get them right. So, if you have interrupted your
\LaTeX{} program, the best way is to
delete all those auxiliary files, \ie{}, all files with an extension
other than \ext{tex}, \ext{log}, or \ext{dvi}. If you want to
avoid having to run \LaTeX{} twice after making an error---for
example, if your input is very long---then you should save copies
of these auxiliary files before running \LaTeX{}.
The second problem in using \LaTeX{} concerns the files that
\LaTeX{} reads. The file which \LaTeX{} is called with is called
the \emph{root file}. In addition to reading the root file,
\LaTeX{} also reads the files specified by |\input| and
|\include| commands. In the file system \TeX{} must know not only
the names of these files but also in which directories they are.
You will have no problem finding the correct files if you follow
the simple rule:
%
\begin{quote}
Keep all files specified by |\input| and |\include| commands in
the same directory as the root file.
\end{quote}
%
If you follow this rule, you never have to type a path
specifier when using \LaTeX{}. If you break this rule by
specifying a file from another directory in an |\input| or
|\include| command, you must use a full path name.
%
\begin{todo}{}
Describe by which environment variables, logicals, etc.\ the file
search is configured.
Mention if there are syntax changes for pathnames,
\eg{} `|/|' instead of `|\|'.
\end{todo}
%
\begin{todo}{}
List more special things, \eg{}
-- usage of extended character set,
-- \LOG{} file has an other extension as \ext{log},
-- special sizes of circles and disks for the |picture| environment.
\end{todo}
\subsection{Helpful \ext{tex} Files}
%
\begin{fixme}
Are these still available/functionable?
\end{fixme}
%
In the directory \dir{inputs}, where the class and package files are
located, four more input files can be found which help you to deal
with your documents and your installation.
%
\begin{todo}{}
If the users have to select input files in a menu system or if the
files in \dir{inputs} are not found automatically, delete the
following sentence.
\end{todo}
%
You don't have to copy these files, just call \LaTeX{} with their name.
\begin{description}
\item[\tt idx.tex] The index entries in an \ext{idx} file are printed
by running \LaTeX{} on the file \file{idx.tex}. \LaTeX{} will ask for
the name of the document, which must be given without an extension.
\item[\tt lablst.tex] A list of the labels (produced by |\label|) and
citations (produced by |\cite|) in a document is printed by running
\LaTeX{} on the input file \file{lablst.tex}. \LaTeX{} will then ask for
the name of the document file, which should be typed without the
extension \ext{tex}, and for the name of the document class (\eg{}
|article|), used by that file.
\item[\tt testpage.tex] The output of this input file is an exact
representation of the margins \LaTeX{} and your printer driver
produces. You can use this as a test how accurate your output
device can produce the dimensions available in \LaTeX{}.
\item[\tt tryfonts.tex] This input file produces several pages
on which the fonts of a document class are used. With that you can
detect errors in your font files or with the way a font is
handled.
\LaTeX{} asks for the document class the font test should be done
for. In every case a page is produced with the Roman fonts in the
sizes |\tiny| upto |\huge|. Afterwards you are asked for size
changing commands which you have to enter without the backslash
(`|\|'). For every size changing command examples in different
type faces (math mode, too) are generated. The input |stop| ends
the font test.
\end{description}
\section{Available Document Classes and Packages}
With \LaTeX{} you may write your document (almost) independent of the
layout to get a satisfactory output with a few tags that describe the
structure of your document. You can choose the category of your
document with the \LaTeX{} tag |\documentclass| at the start of your
root file. You get a default layout with each class. Packages provide
more tags or change the layout in certain respects.
The features provided by document classes and by packages can be
varied with \emph{options}. Options supplied at the |\documentclass|
tag apply for the class and for all packages. Options supplied at a
|\usepackage| tag apply for this package only.
I will give you an overview on the installed classes, packages, and
their options in this section. Usually, this will not be a complete
description for usage, rather it's an abstract and provides a
reference to the user manual for you. All on-line user manuals are
located in the directory \dir{latex/doc}. If the name of the
respective file has the extension \ext{tex} it is a \LaTeX{} input file and
should be run through \LaTeX{} to get a formatted output.
For every class or package the files are named that are needed for its
usage. You don't need this information if everything is installed
correctly, but it might help you in times of trouble, then you can
look for missing or damaged files. Document classes are defined in
files with the extension \ext{cls}. Sometimes other files are utilized to
implement the class options, usually these files have the extension
\ext{clo}. Packages are defined in files with the extension \ext{sty}. In the
file names the wildcard character~`|*|' is used to denote an arbitrary
number of characters in the name, \ie{}, a group of files. All these
files reside in the directory \dir{inputs}.
If you used \LaTeX{}~2.09 before, you might still have documents with
the old markup; namely, files with the |\documentstyle| tag at the
start to declare the document's category. This documents may still be
processed by the current \LaTeX{}. The document styles are mapped to
the new document classes, previous style options are either realized
internally or mapped to packages.
\begin{todo}{}
Add local styles.
\emph{Attention}: Sorted alphabetically in each subsection!
% This hint is necessary; it was overlooked often.
\end{todo}
\begin{fixme}
Another subsection with 2.09 document styles? They will have been
installed and will be used, after all. And the transition time will be
long, if one faces the reality\,\dots
\end{fixme}
\begin{fixme}
Another subsection with commonly available class options? Where are
those of the standard classes codified? In the \LaTeX{} Companion?
\end{fixme}
\subsection{Document Classes}
All document classes support the pagestyles \pgsty{plain} and
\pgsty{empty}.
\inputAbstract{classes}
\subsection{Packages}
\inputAbstract{packages}
\section{Carrying On}
The following chapter provides information about the \LaTeX{} system
that is installed at your site. Usually this information is not needed
by you; it will be of interest if you want to get an ``inner
knowledge'' of your \LaTeX{} version.
\subsection{Where the Files Are}
Table~\ref{tab:files} describes the location of all files belonging
to \LaTeX{} in a suggested installation.
%
\begin{todo}{}
Explain in which main directory(ies) this subtree resides.
\end{todo}
%
To \emph{use} \LaTeX{}, only the files in \dir{inputs} are needed.
%
\begin{fixme}
Table information was not updated to \LaTeXe{}.
do we need this section at all? cf Introduction --- \INITEX{} stuff
is no longer needed.
\end{fixme}
%
\begin{table}
\begin{center}
\begin{tabular}{ll}
\multicolumn1{c}{\scshape Files} & \multicolumn1{c}{\scshape Directory}\\[3pt]
\file{latex.tex} & \dir{initex/latex}\\
\file{lfonts.tex} & \dir{initex/latex}\\
\file{lplain.tex} & \dir{initex/latex}\\
\file{slitex.tex} & \dir{initex/latex}\\
\file{sfonts.tex} & \dir{initex/latex}\\
\file{splain.tex} & \dir{initex/latex}\\
\file{hyphen.tex} & \dir{initex}\\
hyphenation patterns& \dir{initex/hyphens/*}\\
& \qquad (own directory for each language)\\
\file{lang*.tex} & \dir{initex}\\
\file{local.tex} & \dir{initex}\\
\file{codes.tex} & \dir{initex}\\[2pt]
%
\file{*.sty} & \dir{latex}\\
\file{idx.tex} & \dir{latex}\\
\file{lablst.tex} & \dir{latex}\\
\file{testpage.tex} & \dir{latex}\\
\file{tryfonts.tex} & \dir{latex}\\[2pt]
%
\file{*.tex} & \dir{latex/doc}\\
& \qquad (documentation, \LaTeX{}able)\\
\file{*.*} & \dir{latex/doc}\\
& \qquad (documentation, not \LaTeX{}able)\\[2pt]
%
\file{*.bst} & \dir{bibtex}\\
\file{*.*} & \dir{bibtex/doc}\\
& \qquad (new \BibTeX{} documentation)\\
\end{tabular}
\end{center}
\caption{Files which are needed for \LaTeX{}}
\label{tab:files}
\end{table}
\subsection{Fonts}
Almost all characters which are in the fonts may be yield with usual
\LaTeX{} tags. But there are some type sizes you may not produce
with the size changing possibilities of \LaTeX{}. Please contact your
local \TeX{}pert who will explain you how to make these fonts
accessible via NFSS. (If you are the local expert and you do not know
it either, read the documentation on NFSS,
%
\begin{fixme}
dedicated sections in \LaTeX{} Companion?
\end{fixme}
%
and maybe you should also buy yourself a \TeX{}book and read the
chapters 4~and~9, and the appendix~F.)
Table~\ref{tab:sizes} tells you what size of type is used for
each \LaTeX{} type-size tag in the various document class
options. For example, with the |12pt| option, the |\large|
declaration causes \LaTeX{} to use 14pt type.
%
\begin{table}
\centering
\begin{tabular}{l|r|r|r|}
\multicolumn{1}{l}{\scshape size} &
\multicolumn{1}{c}{\scshape default (\texttt{10pt})} &
\multicolumn{1}{c}{\scshape \texttt{11pt} option} &
\multicolumn{1}{c}{\scshape \texttt{12pt} option}\\
\cline{2-4}
\verb|\tiny| & 5pt & 6pt & 6pt\\
\cline{2-4}
\verb|\scriptsize| & 7pt & 8pt & 8pt\\
\cline{2-4}
\verb|\footnotesize| & 8pt & 9pt & 10pt\\
\cline{2-4}
\verb|\small| & 9pt & 10pt & 11pt\\
\cline{2-4}
\verb|\normalsize| & 10pt & 11pt & 12pt\\
\cline{2-4}
\verb|\large| & 12pt & 12pt & 14pt\\
\cline{2-4}
\verb|\Large| & 14pt & 14pt & 17pt\\
\cline{2-4}
\verb|\LARGE| & 17pt & 17pt & 20pt\\
\cline{2-4}
\verb|\huge| & 20pt & 20pt & 25pt\\
\cline{2-4}
\verb|\Huge| & 25pt & 25pt & 25pt\\
\cline{2-4}
\end{tabular}
\caption{Type sizes for \LaTeX{} size-changing features}
\label{tab:sizes}
\end{table}
%%
%
\begin{fixme}
Preloaded/on demand makes not much sense any more, but
``unavailable'' still does! Have to fix the table.
Basically, the table shall explain the state if one uses the
distribution, \ie{}, without |fontdef.cfg| and |preload.cfg|.
\end{fixme}
%
Table~\ref{tab:fonts} tells, for every type size, to which class
of fonts each type style belongs, \ie{}, if it is preloaded, if
it will be loaded on demand, or if it is unavailable. The \TFM{}
files for those fonts which are loaded on demand are needed at
run time.
%
\begin{fixme}
Which names should be used best? |\rmfamily| etc.? Or should I use
the real font names?
\end{fixme}
%
Roman (|\rm|) and math italic (|\mit|) fonts are all
preloaded; the |\em| declaration uses either italic (|\it|) or
roman.
\begin{table}
\begin{center}
\begin{tabular}{l|c|c|c|c|c|c|}
\multicolumn{1}{l}{}&
\multicolumn{1}{c}{\tt \char `\\ it} &
\multicolumn{1}{c}{\tt \char `\\ bf} &
\multicolumn{1}{c}{\tt \char `\\ sl} &
\multicolumn{1}{c}{\tt \char `\\ sf} &
\multicolumn{1}{c}{\tt \char `\\ sc} &
\multicolumn{1}{c}{\tt \char `\\ tt} \\
\cline{2-7}
5\,pt & U & D & U & U & U & U \\
\cline{2-7}
6\,pt & U & D & U & U & U & U \\
\cline{2-7}
7\,pt & P & D & U & U & U & U \\
\cline{2-7}
8\,pt & P & D & D & D & D & D \\
\cline{2-7}
9\,pt & P & P & D & D & D & P \\
\cline{2-7}
10\,pt & P & P & P & P & D & P \\
\cline{2-7}
11\,pt & P & P & P & P & D & P \\
\cline{2-7}
12\,pt & P & P & P & P & D & P \\
\cline{2-7}
14\,pt & D & P & D & D & D & D \\
\cline{2-7}
17\,pt & D & P & D & D & D & D \\
\cline{2-7}
20\,pt & D & D & D & D & D & D \\
\cline{2-7}
25\,pt & U & D & U & U & U & U \\
\cline{2-7}
\end{tabular}
\caption{%
Font classes: P = preloaded,
D = loaded on demand,
U = unavailable.%
}
\label{tab:fonts}
\end{center}
\end{table}
%
\begin{fixme}
check this with NFSS -- how about reduced fonts?
\end{fixme}
%
Please note that the entry ``unavailable'' in the table does not mean
that these fonts do not exist---they just are not used by \LaTeX{}.
In fact there exists a realization of \LaTeX{} which does not know
any ``unavailable fonts.'' If this version should be used all fonts
which do not exist in reality (as \TeX{} fonts) must be generated as
scaled ones.
If you use the 11\,pt or 12\,pt as the basic font sizes for your
document, not all mathematical symbols will be set in their correct
sizes. The so-called ``extensible'' symbols (parenthesis, braces, root
sign, etc.)\ are not adapted to this size. The package
\package{exscale} (see section~\ref{package:exscale}) provides a
work-around, you might want to check its documentation.
\begin{todo}{}
Describe which font sets are available and provide crossrefs to
packages that enable the usage, \eg{} to
%
\begin{itemize}
\item special local fonts (with logos etc.)
\item \MF{} logo fonts, |manfnt| etc.
\item DC fonts
\item the adaption to ``true-size'' fonts by Sauter.
\item a version for the support of \textsc{PostScript}-fonts (who has
one that really works? \package{psnfss}?)
\item what else? \dots
\end{itemize}
\end{todo}
\begin{todo}{}
If a font manual exists its usual location should be noted here.
\end{todo}
\subsection{Errors in the \LaTeX{} book}
%
\begin{fixme}
Will that remain?
IMO it's better than including it here.
\end{fixme}
%
The errors in the \LaTeX{} book which have been known at \erratadate{}
and additions of L.~Lamport are described in the document `\textit{Errata
and Additions to the Manual}.' This document consists of the two files
\file{errata.tex} and \file{addendum.tex} which are located in the
directory \dir{latex/doc}. You must run \file{errata.tex} through
\LaTeX{} to get a formatted output.
\section{Bugs? No, Features!}
%
\begin{fixme}
Are these still occuring?
Yes, at least the first --- quite in this document, as of 01 Feb
94, Revision 1.7.
\end{fixme}
%
There are a few known bugs in \LaTeX{} that occur very seldom and
cause the user little trouble, but would be very difficult to
fix. Moreover, given the nature of complex systems, it is not
unlikely that the corrections would lead to even worse problems.
Therefore, these bugs will probably not be fixed.
The bugs and ways to get around them are listed below. Do not
worry about any of them until you are preparing the final version
of your document. These bugs are all concerned with the position
of the producing control sequence on the page and it is very
likely that changes to the text will cause them to disappear (and
perhaps to reappear at other places).
\begin{itemize}
\item In rare instances, a figure or table will be printed on the
page preceding the text where the |figure| or |table| environment
appears. This can be fixed by moving the environment further
towards the end of the document.
\item A footnote can be broken across two pages when it should
fit on a single page. This happens when there are one or more
figures or tables on the page. The problem is corrected by
moving, towards the end of the file, the last |figure| or |table|
environment that produces a figure or table on the page where the
footnote starts.
\item A marginal note at the top of a page may appear in the
wrong margin. This can be fixed by inserting a redundant
|\pagebreak| tag to force a page break exactly where \LaTeX{}
started the new page anyway.
\end{itemize}
\begin{fixme}
\file{bug.l2e} mentions \file{*.bug} as the file(s) for history of
bugs. Are these more than one file now? (Currently there is none.)
\end{fixme}
%
The file \file{latex.bug} in the directory \dir{latex/doc}
contains a history of the known bugs of \LaTeX{}. \file{latex.bug} is no
\TeX{} input file.
\section{Utilities}
\subsection{\BibTeX}
\label{sec:bibtex}
%
\begin{fixme}
Do we need a switch ifInstalledBibTeX?
\end{fixme}
%
\BibTeX{} is a program for compiling a reference list for a
document from a bibliographic database. To do this it reads the
auxiliary file with the extension \ext{aux} that \LaTeX{} produces.
%
\begin{todo}{}
Describe activation and parameters
\end{todo}
%
To produce a reference list you have to run your document
through \LaTeX{} (then the \AUX{} file will be produced),
only afterwards you can call \BibTeX{}. On the next \LaTeX{}
run you will find the reference list in your document, but a
second run is needed to get the citations into the text.
All citations are listed in the \ext{aux} file so that the corresponding
references from a bibliographic database (usually a file with the
extension \ext{bib}) can be extracted into a file with the extension \ext{bbl}
which is read from \LaTeX{}. All messages from \BibTeX{} are written
into a file with the extension \ext{blg} (see also Figure~\ref{fig:bibtex}).
More information about the usage
of \BibTeX{} can be found in the document |btxdoc| which consists of
the two files \file{btxdoc.tex} and \file{btxdoc.bib} (a \BibTeX{}
database). These two files can be found in the directory
\dir{bibtex/doc}. You have to do the above-mentioned procedure
(\LaTeX{}, \BibTeX{}, \LaTeX{}, \LaTeX{}) for this document.
\hint |btxdoc| is a newer and more complete description of
\BibTeX{} than the appendix~B of the \LaTeX{} book.
%
\begin{fixme}
Is this obsolete with the 2nd edition?
\end{fixme}
%
\begin{figure}
\begin{center}
\input{bibtex.latex}
\caption[Interaction of \protect\BibTeX{} and \LaTeX{}]{%
Interaction of \BibTeX{} and \LaTeX{}
\begin{footnotesize}
\AUX$_1$: \AUX{} file with information for \BibTeX{}\\
\AUX$_2$: \AUX{} file with citation cross references\\
Not all files read or written are shown. Dashed arrows
denotes that this file is read, but not really relevant at
this stage.
\end{footnotesize}
}
\label{fig:bibtex}
\end{center}
\end{figure}
The layout of the reference list is determined by the {\it
bibliography style}, which is defined in files with the extension \ext{bst}.
All \ext{bst} files are located in the directory \dir{bibtex/bst}. The
document |btxhak| in the directory \dir{bibtex/doc} is for those of
you who want to create own bibliography styles. The document file
\file{btxhak.tex} uses \file{btxdoc.bib}, too.
\begin{todo}{}
List all installed bibliography styles. Perhaps one needs a
paragraph below as well, if the bibstyle does not implement a
specific journal format.
\end{todo}
%
The list below explains which \ext{bst} files are available on your
installation.
%
\begin{shortdesc}
\item [abbrv] sorted; numbered citation references; abbreviated
person, month, and journal names
\item [alpha] sorted; citation references are created from the
abbreviated author names and the publication year
\item [plain] sorted; numbered citation references
\item [unsrt] numbered citation references
\item [ieeetr] format of IEEE transactions
\item [siam] format of SIAM journals
\end{shortdesc}
In addition to the usual three-letter abbreviations for the months,
the following standard bibliography styles define additional
abbreviations for journal names. They are listed in
table~\ref{tab:journal-alias}.
\begin{table}
\begin{center}
\begin{tabular}{rl}
\texttt{acmcs} & ACM Computing Surveys\\
\texttt{acta} & Acta Informatica\\
\texttt{cacm} & Communications of the ACM\\
\texttt{ibmjrd} & IBM Journal of Research and Development\\
\texttt{ibmsj} & IBM Systems Journal\\
\texttt{ieeese} & IEEE Transactions on Software Engineering\\
\texttt{ieeetc} & IEEE Transactions on Computers\\
\texttt{ieeetcad} & IEEE Transactions on Computer-Aided Design
of Integrated Circuits\\
\texttt{ipl} & Information Processing Letters\\
\texttt{jacm} & Journal of the ACM\\
\texttt{jcss} & Journal of Computer and System Sciences\\
\texttt{scp} & Science of Computer Programming\\
\texttt{sicomp} & SIAM Journal on Computing\\
\texttt{tocs} & ACM Transactions on Computer Systems\\
\texttt{tods} & ACM Transactions on Database Systems\\
\texttt{tog} & ACM Transactions on Graphics\\
\texttt{toms} & ACM Transactions on Mathematical Software\\
\texttt{toois} & ACM Transactions on Office Information Systems\\
\texttt{toplas} & ACM Transactions on Programming Languages and Systems\\
\texttt{tcs} & Theoretical Computer Science\\
\end{tabular}
\caption[Additional \texttt{BST} abbreviations]{%
Additional abbreviations for journal names in the standard
bibliography styles%
}
\label{tab:journal-alias}
\end{center}
\end{table}
\begin{todo}{}
Here it must be specified where \BibTeX{} will look for the
\ext{aux} file and the \BibTeX{} specific input files (\ext{bib}
and \ext{bst} files) and how the user may control this
search (environment variables, logicals---|BIBINPUTS|,
|TeXINPUTS|!)
\end{todo}
\subsection{\MakeIndex}
\label{sec:makeindex}
\MakeIndex{} is a program for creating a sorted index in a \LaTeX{}
document. There is a manual available that explains the usage of this
tool.
%
\begin{todo}{}
Tell also if/where \DVI{} version is installed.
\end{todo}
%
You'll find the \LaTeX{} source of the manual in the file
\file{makeindx.tex} in the directory \dir{latex/doc}.
If you want to create an index, you have to specify the option
\option{makeindex} at the |\documentclass| tag, and you must specify
the tag |\makeindex| in the document preamble. Then \LaTeX{} will
produce a \emph{raw index file}. This file has the extension \ext{idx}.
%
\begin{todo}{}
Describe program activation, especially if a \TeX{} shell is used.
\end{todo}
%
You must pass the name of this file as an argument to the |makeindex|
command. \MakeIndex{} produces a file that contains the sorted and
unified index within a |theindex| environment. This file has the
extension \ext{ind}. You can insert the sorted index into your
document at a point that is tagged with |\printindex|.
\hint You may want to process your index only if the
text of your document is sufficiently fixed.
\MakeIndex{} is freely distributable.
%
\ifInstalledMakeIndex
You have a right to obtain the source code from the same origin you
have got the program from.
%
\begin{todo}{}
Mention if/where source is available.
\end{todo}
%
\else
You may obtain the source code from CTAN or your national users group.
(Not all platforms are supported, though.)
\fi
\section{Getting Help}
\label{sec:help}
%
\begin{fixme}
how to proceed in case of problems.
hints to `gurus', mailing lists, newsgroups, user
groups, distributors, latex-bugs mailid (at last).
\end{fixme}
%
\section*{Bibliography}
\label{sec:bibliography}
%
\begin{fixme}
Why is the |thebibliography| change I sent to Rainer not in
\LaTeXe{}? Grmbbl.
\end{fixme}
%
The following list of \TeX-related literature may be helpful for you:
\begin{fixme}
Add bibliography. Some references might be missing.
Make references a standalone bib database.
Make references a standalone bib database.
Use the |tschichold| bibstyle?
\end{fixme}
\nocite{knuth:tex}
\nocite{lamport:latex}
\bibliographystyle{abbrv}
% \bibliography{genguide}
% not yet standalone!
\bibliography{abbrev,tex}
\proceedIfGLG
\begin{rcslog}
$Log: genguide.tex,v $
\Revision 1.9 1994/02/01 21:21:16 schrod
Used tag |\hint| to introduce hints for authors.
Made all type switches conform to the new \LaTeXe{} PC way of doing it.
Substituted a few remaining `i.e.'\ to |\ie{}|.
\Revision 1.8 1994/02/01 20:49:19 schrod
Merged section ``Differences from the Manual'' into ``\LaTeX{} on
platform,'' now named ``What's Special with \LaTeX{} on platform?''
Added an introduction where I explain that \LaTeX{} is the best thing
since sliced bread.
Renamed section ``Layout Definitions'' to ``Available Document Classes
and Packages.'' This promotes structural markup better.
Substituted the text that mentioned the scaled extension symbols with
a hint to \package{exscale}. That was a relict from I\LaTeX{} anyhow.
The new \BibTeX{} figure is incorporated and explained. Not only the
additional bibliography styles are listed, but all installed ones.
No todo boxes before front matter. The explanation of |fixme| and
|todo| environments is moved between front matter and text. Actually,
that place is now marked by a structure tag instead of |\eject|. The
explanations are inserted automatically if at least one respective
enviroment is in the document.
As long as any todo material is still in the document, the title
shows that this is the GLG\@. The front matter info part now names
the GLG revision.
Minor details: The bibliography has no section number. The journal
alias table is now a float.
\Revision 1.7 1994/01/31 21:17:42 schrod
\LaTeXe{}, as of December~21, 1993, is described. (The date was not
updated.) Did also minor fixes of language and spelling. Rewrote the
section on \MakeIndex{}.
Document class renamed to |locguide|, is now implemented as a real
class, not only a mock-up. I had to change a few tags because of this.
Updated copyright, meta remarks, and my address at the document
start. Checked document title and editorial comments on the second
page. The version history is now printed at the very end, as long as
at least one |todo| environment is in the document.
\Revision 1.6 1994/01/29 16:22:20 detig
Now this is a \LaTeXe{} document.
We fixed the contents so that all points still open are tagged as fixme's.
All ifreduced sections were omitted.
Extensions are now called so and are properly tagged.
todo and fixme are now environments.
\Revision 1.5 1994/01/27 20:17:00 detig
Major update for \LaTeXe{}.
Describes the actual installation structure as far as this is defined,
mentions babel, refers to NFSS, actualizes \BibTeX{} and \MakeIndex{}
information, etc.
Several points still have to be fixed.
\Revision 1.4 1994/01/27 19:58:31 schrod
Rewrote the chapter on layout definitions. We have to present classes
and packages, not styles. I don't know if we still must present
options or old styles, this might be added in the future.
\Revision 1.3 1994/01/26 14:26:00 detig
Corrected some typos that prevented formatting.
\Revision 1.2 1994/01/17 18:17:46 detig
Updated english version to generic local guide for \LaTeX{} 2.09, both in
text and file structure.
Some parts (which will be subject to major changes with \LaTeXe{}) were
left untouched, though. Some style descriptions are still to be written,
their relevance must be checked, anyhow.
\Revision 1.1.1.1 1994/01/17 13:03:40 detig
English Generic Local Guide, I\LaTeX{} version as of 90--04--19.
\Revision 0.0 1990/04/19 00:00:00 schrod
\textsl{Version History before CVS usage}
%
\begin{verbatim}
%
% DATUM PERSON BEMERKUNG
% 90-04-19 js cleaned up for distribution with ILaTeX
% 88-08 js first version
\end{verbatim}
\end{rcslog}
\end{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Local Variables:
mode: LaTeX
TeX-auto-regexp-list: LaTeX-auto-regexp-list
End: