%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Contents: Specialities of the LaTeX system
% $Id: spec.tex,v 1.3 1998/03/26 15:36:54 oetiker Exp oetiker $
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
\chapter{Specialities}
\begin{intro}
  When putting together a large document \LaTeX{} will help you
  with some special features like index generation,
  bibliography management and other things.
  A much more complete description of specialities and
  enhancements possible with \LaTeX{} can be found in the
  {\normalfont\manual{}} and {\normalfont \companion}.
\end{intro}

\section{Including EPS Graphics}
With the \texttt{figure} and the \texttt{table} environment \LaTeX{}
provides the basic facilities to work with floating bodies such as
images or graphics.

There are also several possibilities to generate the actual
\wi{graphics} with basic \LaTeX{} or a \LaTeX{} extension package.
Unfortunately, most users find them quite difficult to understand.
Therefore this will not be explained any further in this manual. For
more information on that subject please refer to \companion{} and the
\manual.

A much easier way to get graphics into a document, is to generate them
with a specialised software package\footnote{Such as XFig, CorelDraw!,
  Freehand, Gnuplot, \ldots} and then include the finished graphics
into the document. Here again, \LaTeX{} packages offer many ways to do
that. In this introduction, only the use of \wi{Encapsulated
  PostScript} (EPS) graphics will be discussed, because it is quite
easy to do and widely used.  In order to use pictures in the EPS
format, you must have a \wi{PostScript} printer\footnote{Another
  possibility to output PostScript is the \textsc{\wi{GhostScript}}
  program available from \texttt{CTAN:/tex-archive/support/ghostscript}}
available for output.

A good set of commands for inclusion of graphics is provided in the
\pai{graphicx} package by D.~P.~Carlisle. It is part of a whole family
of packages called the ``graphics''
bundle\footnote{\texttt{CTAN:/tex-archive/macros/latex/packages/graphics}}.

Assuming you are working on a system with a
PostScript printer available for output and with the \textsf{graphicx}
package installed, you can use the following step by step guide to
include a picture into your document:

\begin{enumerate}
\item Export the picture from your graphics program in EPS
  format.
\item Load the \textsf{graphicx} package in the preamble of the input
  file with
\begin{command}
\verb|\usepackage[|\emph{driver}\verb|]{graphicx}|
\end{command}
where \emph{driver} is the name of your ``dvi to postscript'' The most
widely used program is called \texttt{dvips}. The name of the driver is
required because there is no standard on how graphics are included in
\TeX{}. Knowing the name of the \emph{driver}, the
\textsf{graphicx} package can choose the correct method to insert
information about the graphics into the \texttt{.dvi}~file so that the
printer understands it and can correctly include the \texttt{.eps} file.
\item Use the command 
\begin{command}
\ci{includegraphics}\verb|[|\emph{key}=\emph{value}, \ldots\verb|]{|\emph{file}\verb|}|
\end{command}
to include \emph{file} into your document. The optional parameter
accepts a comma separated list of \emph{keys} and associated
\emph{values}. The \emph{keys} can be used to alter the width, height
and rotation of the included graphic. Table~\ref{keyvals} lists the
most important keys.
\end{enumerate}

\begin{table}[htb]
\caption{Key Names for \textsf{graphicx} Package}
\label{keyvals}
\begin{lined}{9cm}
\begin{tabular}{@{}ll}
\texttt{width}& scale graphic to the specified width\\
\texttt{height}& scale graphic to the specified height\\
\texttt{angle}& rotate graphic counter clockwise\\
\texttt{scale}& scale graphic \\
\end{tabular}

\bigskip
\end{lined}
\end{table}

The following example code will hopefully make things clear:
\begin{code}
\begin{verbatim}
\begin{figure}
\begin{center}
\includegraphics[angle=90, width=0.5\textwidth]{test.eps}
\end{center}
\end{figure}
\end{verbatim}
\end{code}
This includes the graphic stored in the file \texttt{test.eps}. The graphic
is \emph{first} rotated by an angle of 90 degrees and \emph{then} scaled to the
final width of 0.5 times the width of a standard paragraph.
The aspect ratio is 1.0 because no special height is specified.
The width and height parameters can also be specified in absolute
sizes. Refer to Table \ref{units} on page \pageref{units} for more
information. If you want to know more on this topic, make sure to read
\cite{graphics} and \cite{eps}. 

\section{Bibliography}
 
With the \ei{thebibliography} environment you can produce a
\wi{bibliography}.  Each entry starts with
\begin{command}
\ci{bibitem}\verb|{|\emph{marker}\verb|}|
\end{command}
The \emph{marker} is then used to cite the book, article or paper
within the document.
\begin{command}
\ci{cite}\verb|{|\emph{marker}\verb|}|
\end{command}
The numbering of the entries is generated automatically.  The
parameter after the \verb|\begin{thebibliography}| command sets the maximum
width of these numbers.

\begin{example}
Partl~\cite{pa} has 
proposed, that \ldots
 
\begin{thebibliography}{99}
\bibitem{pa} H.~Partl: 
\emph{German \TeX},
TUGboat Vol.~9, No.~1 ('88)
\end{thebibliography}
\end{example}
\chaptermark{Specialities} % w need to fix the damage done by the
                           %bibliography example.
\thispagestyle{fancyplain}

For larger projects, you might want to check out the Bib\TeX{}
program. Bib\TeX{} is included with most \TeX distributions. It
allows you to maintain a bibliographic database and then extract the
references relevant to things you cited in your paper. The visual
presentation of Bib\TeX{} generated bibliographies is based on a style
sheets concept which allows you to create bibliographies following
a wide rage of established designs.

\section{Indexing} \label{sec:indexing}
A very useful feature of many books is their \wi{index}. With \LaTeX{}
and the support program \texttt{makeindex}\footnote{On systems not supporting
  filenames longer than 8~characters, the program may be called
  \texttt{makeidx}.} indexes can be generated quite easily.  In this
introduction, only the basic index generation commands will be explained.
For a more in depth view please refer to \companion.  \index{makeindex
  program} \index{makeidx package}

To enable the indexing feature of \LaTeX{} the \pai{makeidx} package
must be loaded in the preamble with:
\begin{command}
\verb|\usepackage{makeidx}|
\end{command}
\noindent and the special indexing commands must be enabled by putting 
the
\begin{command}
  \ci{makeindex}
\end{command}
\noindent command into the input file preamble.

The content of the index is specified with
\begin{command}
  \ci{index}\verb|{|\emph{key}\verb|}|
\end{command}
\noindent commands, where \emph{key} is the index entry. You enter the
index commands at the points in the text where you want the final index
entries to point to.  Table~\ref{index} explains the syntax of the
\emph{key} argument with several examples.

\begin{table}[!tp]
\caption{Index Key Syntax Examples}
\label{index}
\begin{center}
\begin{tabular}{@{}lll@{}}
  \textbf{Example} &\textbf{Index Entry} &\textbf{Comment}\\\hline
  \rule{0pt}{1.05em}\verb|\index{hello}| &hello, 1 &Plain entry\\ 
\verb|\index{hello!Peter}|   &\hspace*{2ex}Peter, 3 &Subentry under `hello'\\ 
\verb|\index{Sam@\textsl{Sam}}|     &\textsl{Sam}, 2& Formated entry\\ 
\verb|\index{Lin@\textbf{Lin}}|     &\textbf{Lin}, 7& Same as above\\ 
\verb.\index{Jenny|textbf}.     &Jenny, \textbf{3}& Formated page number\\
\verb.\index{Joe|textit}.     &Joe, \textit{5}& Same as above
\end{tabular}
\end{center}
\end{table}

When the input file is processed with \LaTeX{}, each \verb|\index|
command writes an appropriate index entry together with the current
page number to a special file. The file has the same name as the
\LaTeX{} input file, but a different extension (\verb|.idx|). This
\texttt{.idx} file can then be processed with the \texttt{makeindex}
program.

\begin{command}
  \texttt{makeindex} \emph{filename}
\end{command}
The \texttt{makeindex} program generates a sorted index with the same base
file name, but this time with the extension \texttt{.ind}. If now the
\LaTeX{} input file is processed again, this sorted index gets
included into the document at the point where \LaTeX{} finds
\begin{command}
  \ci{printindex}
\end{command}

The \pai{showidx} package which comes with \LaTeXe{} prints out all
index entries in the left margin of the text. This is quite useful for
proof reading a document and verifying the index.
   
% Add some infos on PROTECT ...  


\section{Fancy Headers}


The \pai{fancyhdr} package\footnote{Available from
  \texttt{CPAN:/macros/latex/contrib/supported/fancyhdr/}}, written by
Piet van Oostrum provides a few simple commands which allow you to
customise the header and footer lines of your document.  If you look
at the top of this page you can see a possible application of this
package.

\begin{figure}[!htbp]
\begin{lined}{\textwidth}
\begin{verbatim}
\documentclass{book}
\usepackage{fancyhdr}
\pagestyle{fancy}
% with this we ensure that the chapter and section
% headings are in lowercase.
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}
\fancyhf{}  % delete current setting for header and footer
\fancyhead[LE,RO]{\bfseries\thepage}
\fancyhead[LO]{\bfseries\rightmark}
\fancyhead[RE]{\bfseries\leftmark}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt}
\addtolength{\headheight}{0.5pt} % make space for the rule
\fancypagestyle{plain}{%
   \fancyhead{} % get rid of headers on plain pages
   \renewcommand{\headrulewidth}{0pt} % and the line
}
\end{verbatim}
\end{lined}
\caption{Example \pai{fancyhdr} setup} \label{fancyhdr}
\end{figure}

The tricky problem when customising headers and footers is to get
things like running section and chapter names in there. \LaTeX{}
accomplishes this with a two stage approach. In the header and footer
definition you use the commands \ci{rightmark} and \ci{leftmark} to
represent the current chapter and section heading respectively.
The values of these two commands are overwritten whenever a chapter or
section command is processed. 

For ultimate flexibility, the \verb|\chapter| command and its friends
do not redefine \ci{rightmark} and \ci{leftmark} themselves,
they call yet another command called \ci{chaptermark},
\ci{sectionmark} and \ci{subsectionmark} which is
then responsible for redefining \ci{rightmark} and
\ci{markleft}. 

So, if you wanted to change the look of the chapter
name in the header line, you simply have to ``renew'' the \ci{chaptermark}
command. \cih{sectionmark}\cih{subsectionmark}

 
Figure \ref{fancyhdr} shows a possible setup for the \pai{fancyhdr}
package which makes the headers look about the same as they look in
this booklet. In any case I suggest you fetch the documentation for
the package at the address mentioned in the footnote. 

\section{The Verbatim Package}

Earlier in this book you got to know the \ei{verbatim}
\emph{environment}.  In this section you are going to learn about the
\pai{verbatim} \emph{package}. The \pai{verbatim} package is basically
a reimplementation of the \ei{verbatim} environment which works around
some of the limitations of the original \ei{verbatim} environment.
This by itself is not spectacular, but with the implementation of the
\pai{verbatim} package, there was also new functionality added, and
this is the reason I am mentioning the package here. The \pai{verbatim}
package provides the

\begin{command}
\ci{verbatiminput}\verb|{|\emph{filename}\verb|}|
\end{command}

\noindent command which allows you to include raw ASCII text into your
document as if it was inside a \ei{verbatim} environment.

As the \pai{verbatim} package is part of the `tools' bundle, you
should find it preinstalled on most systems. If you want to know more
about this package make sure to read \cite{verbatim} 


%%% Local Variables: 
%%% mode: latex 
%%% TeX-master: "lshort2e" 
%%% End:  









