% arara: pdflatex
% arara: bibtex
% arara: makeglossaries
% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
% arara: makeindex: { style: thesis-index.ist}
% arara: pdflatex
% arara: pdflatex
% arara: pdflatex
% arara: pdflatex
% arara: makeindex: { style: thesis-index.ist}
% arara: pdflatex
\documentclass[report]{dickimawthesis}

\usepackage{scrhack}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{longtable}
\usepackage{listings}
\usepackage{booktabs}
\usepackage{alltt}
\usepackage{siunitx}
\usepackage{array}

\usepackage{cmap}

\usepackage[utf8]{inputenc}
\usepackage[math]{anttor}
\usepackage{libris}
\renewcommand*{\ttdefault}{txtt}

\showdowfalse
\newcommand*{\bookdocdate}{\formatdate{16}{03}{2013}}

\renewcommand{\glossaryname}{Summary of Commands and
Environments}

% document information

\authordetails{1970}{Talbot}{Nicola L.~C.}
\title[Using LaTeX to Write a PhD Thesis]{Using \LaTeX\ to Write a~PhD Thesis}
\version{1.3}
\volume{2}
\series{The Dickimaw \LaTeX\ Series}
\seriesurl{http://www.dickimaw-books.com/latex/}

\date{\bookdocdate}
\keywords{LaTeX,typesetting,thesis,tutorial}
\affiliation
  {Dickimaw Books}
  {www.dickimaw-books.com}
  {Saxlingham Nethergate}

\subject{Thesis writing}

% this is for LaTeX2HTML's benefit:
%\manscreenpdf{thesis_screen.pdf}
%\manscreenlog{thesis_screen.log}
%\manpaperpdf{thesis_a4.pdf}
%\manpaperlog{thesis_a4.log}

% ensure that the index and glossary information is written to the appropriate files
\makeindex
\makeglossaries

% Acronyms

\newacr{ctan}{CTAN}
 {the Comprehensive \TeX\ Archive Network}
 {http://mirror.ctan.org/}

\newacr{ukfaq}{UK FAQ}
 {UK List of \TeX\ Frequently Asked Questions}
 {http://www.tex.ac.uk/faq}

\newcommand{\koma}{KOMA-Script}

\input{glsentries}

% shortcuts to other documents

\newcommand*{\latexbook}{the \LaTeX\ user's guide~\cite{lamport94}}
\newcommand*{\Latexbook}{The \LaTeX\ user's guide~\cite{lamport94}}
\newcommand*{\latexcomp}{\emph{The \LaTeX\ Companion}~\cite{goossens94}}
\newcommand*{\latexguide}{\emph{A Guide to \LaTeX}~\cite{kopka95}}

\newcommand*{\baseurl}{http://www.dickimaw-books.com}

\newcommand*{\packageurl}{\baseurl/latex/packages}

\newcommand*{\packagecls}[1]{%
\htmladdnormallink{\cls{#1}}{\packageurl/index.html\##1}}

\newcommand*{\packagesty}[1]{%
\htmladdnormallink{\sty{#1}}{\packageurl/index.html\##1}}

\newcommand*{\downloadurl}{\baseurl/latex/thesis/examples}

\newcommand*{\texdoc}{\htmladdnormallink{texdoc}{\baseurl/latex/novices/html/texdoc.html}}

\indexpreamble{\latexhtml{Page numbers}{Locations} in \textbf{bold}
indicate the entry
definition in the summary.}

\newcommand{\xtableref}[1]{\objectref{Table}{#1}}

% \figconts[graphics opts]{image}{caption}{label}
\newcommand{\figconts}[4][]{%
  \begin{makeimage}\end{makeimage}\figuretop{#4}
  \centering
  \incPgfOrGraphics[#1]{#2}%
  #3% caption
  \label{#4}%
}

\newcommand{\fboxfigconts}[4][]{%
  \begin{makeimage}\end{makeimage}\figuretop{#4}
  \centering
  \incFboxPgfOrGraphics[#1]{#2}%
  #3% caption
  \label{#4}%
}

\newcommand*{\backcovertext}{If you choose to buy a~copy of this
book,
Dickimaw Books asks for your support through buying the Dickimaw
Books edition to help cover costs.}

\copyrighttext{%
  Copyright \textcopyright\ 2007  Nicola L.~C. Talbot

  Permission is granted to copy, distribute and/or modify this
  document under the terms of the GNU Free Documentation License,
  Version 1.2 or any later version published by the Free Software
  Foundation; with no Invariant Sections, no Front-Cover Texts, and
  one Back-Cover Text: \dq{\backcovertext} A copy of the license is
included in
  the section entitled \htmlref{\dq{GNU Free Documentation
  License}}{sec:fdl}.

  \doifnotbook
  {%
     The base URL for this document is: \url{\baseurl/latex/thesis/}
  }%
}


\html{\input{htmlonly}}

% Need a long table for the required and optional fields (for screen format), but it's
% confusing LaTeX2HTML.

\newenvironment{FieldTabA4}
 {\begin{table}[htbp]
  \caption{Required and Optional Fields}\label{tab:reqopt}
  \centering
  \begin{tabular}{lp{0.4\textwidth}>{\raggedright}p{0.4\textwidth}}
  \bfseries Entry Type & \bfseries Required Fields & \bfseries
Optional Fields\tabularnewline
 }
 {
  \end{tabular}
  \end{table}
 }

\newenvironment{FieldTabScr}
 {\newpage\begin{longtable}{lp{0.4\textwidth}>{\raggedright}p{0.4\textwidth}}
  \caption{Required and Optional
Fields}\label{tab:reqopt}\tabularnewline
  \bfseries Entry Type & \bfseries Required Fields & \bfseries
Optional Fields\tabularnewline
  \endfirsthead
  \caption*{Required and Optional Fields Cont.}\tabularnewline
  \bfseries Entry Type & \bfseries Required Fields & \bfseries
Optional Fields\tabularnewline
  \endhead
  \endfoot
 }
 {\end{longtable}}

\newenvironment{FieldTab}
 {\ifscreen\begin{FieldTabScr}\else\begin{FieldTabA4}\fi}
 {\ifscreen\end{FieldTabScr}\else\end{FieldTabA4}\fi}

\newenvironment{fieldtab}{\latexhtml{\begin{FieldTab}}{\begin{FieldTabA4}}}{\latexhtml{\end{FieldTab}}{\end{FieldTabA4}}}

\begin{document}

\maketitle

\frontmatter
\setcounter{tocdepth}{2}
\setnode{contents}
\tableofcontents
\setnode{listoffigures}
\listoffigures
\setnode{listoftables}
\listoftables
\listofexamples

\chapter{Abstract}

This book is aimed at PhD students who want to use \LaTeX\ to typeset their PhD thesis.
If you are unfamiliar with \LaTeX\, I~recommend
that you first read Volume~1: \latexnovices.

\begin{htmlonly}
The examples given in this document can be download from the 
\htmladdnormallink{examples directory}{examples/index.html}.
\end{htmlonly}

\mainmatter

%%%%%%%%%%%%%%%% INTRODUCTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%

\setnode{introduction}
\chapter{Introduction}
\label{ch:intro}


Many PhD students in the sciences are encouraged to produce their
PhD thesis in \LaTeX, particularly if their work involves a~lot of
mathematics. In addition, these days, \LaTeX\ is no longer the sole
province of mathematicians and computer scientists and is now
starting to be used in the arts and social sciences (see, for
example, some of the topics listed in the \TeX\ online
catalogue~\cite{texcattopic}). This book is intended as a~brief
guide on how to typeset the various components that are usually
required for a~thesis. If you have never used \LaTeX\ before, I
recommend that you first read Volume~1: \latexnovices, as this book
assumes you have a~basic knowledge of \LaTeX. As with Volume~1, I'll
be using PDF\LaTeX\ and TeXWorks. If you are creating a~DVI file or
you are using a~different editor, you'll have to adapt the
instructions.

\warning
If you are unfamiliar with terms such as \dq{preamble}, read
\novices[ch:def]{definitions}. If you don't know how to find package
documentation, read \novices{texdoc}.

Throughout this document there are pointers to related topics
in the \gls{ukfaq}.
\latexhtml{These are displayed in the margin in
square brackets, as illustrated on the
\ifbookorother{\ifthispageodd{right}{left}}{right}.}{%
These are displayed in the text like this:}%
\faq{What is LaTeX?}{latex} You may find these resources useful in
answering related questions that are not covered in this
book.
\doifbook{%
  To find the resources, go to \url{http://www.tex.ac.uk/faq} and
  either look for the question title in the list, or enter a~keyword
  in the search field.%
}
\latex{%

On-line versions of this book, along with associated files, are available at:
\url{\baseurl/latex/thesis/}.
\doifnotbook
{%
  The links in this document are colour-coded: internal links are
  blue, external links are magenta.
}%
}

\latexhtml
{%
To refresh your memory or for those who haven't read Volume~1, 
throughout this book source code is
illustrated in a~typewriter font with the word
\inputlabelformat{Input} placed in the margin, and the corresponding
output (how it will appear in the PDF document) is typeset with the
word \outputlabelformat{Output} in the margin.

\xminisec{Example:}
A single line of code is displayed like this:
}%
{%
To refresh your memory or for those who haven't read 
\htmladdnormallink{Volume~1}{\baseurl/latex/novices/}, 
throughout this book, source code is
illustrated in the form:}
\begin{codeS}
This is an \gls{textbf}\marg{example}.
\end{codeS}%
The corresponding
output\html{ (how it will appear in the PDF
document)\footnote{This HTML version of the book uses bitmaps to
illustrate the output, which doesn't look as good as the actual PDF
version.}}\ is illustrated like this:
\begin{resultS}[exampleoutput.html]
This is an \textbf{example}.
\end{resultS}%
\begin{latexonly}
Segments of code that are longer than one line are bounded above and
below, illustrated as follows:
\begin{code}
\begin{alltt}
Line one\gls{par}
Line two\glsni{par}
Line three.
\end{alltt}
\end{code}%
with corresponding output:
\begin{result}
Line one\par
Line two\par
Line three.
\end{result}%
\end{latexonly}%
\doifnotbook
{%
  (Commands typeset in blue, such as \glsni{par}, indicate a
  hyperlink to the command definition in the
  \latexhtml{\htmlref{summary}{ch:glossary}}{\htmladdnormallink{summary}{summary.html}}.)
}

Command definitions are shown in a~typewriter font in the
form:
\begin{definition}
\glsni{documentclass}\gls{opt.opensq}\meta{options}\gls{opt.closesq}\gls{leftbracechar}\meta{class file}\gls{rightbracechar}
\end{definition}%
In this case the command being defined is called
\cmdname{documentclass} and text typed \meta{like this} (such as
\meta{options} and \meta{class file}) indicates the type of thing
you
need to substitute. (Don't type the angle brackets!) For example, if
you want the \icls{scrbook}
class file you would substitute \meta{class file} with
\texttt{scrbook} and if you want the \clsopt{letterpaper} option
you
would substitute \meta{options} with \texttt{letterpaper}, like
this:
\begin{codeS}
\glsnl{documentclass}\oarg*{letterpaper}\marg*{scrbook}
\end{codeS}
When it's important to indicate a~space, the visible space
symbol~\gls{visiblespace} is used. For example:
\begin{codeS}
A\glsni{visiblespace}sentence\glsni{visiblespace}consisting\glsni{visiblespace}of\glsni{visiblespace}six\glsni{visiblespace}words.
\end{codeS}
When you type up the code, replace any occurrences of
\glsni{visiblespace} with a~space.

\xminisec{Note:}

\warning Be careful of the dangers of obsolete code propagation.
It often happens that students pass on their \LaTeX\ code to new
students who, in their turn, pass it on to the next lot of students,
and so on. You're told \dq{use this magic bit of code to format your
thesis} without knowing what it does. Ancient buggy code that's
20~years out-of-date festers in university departments
refusing to die. But if it worked for previous students, what's the
problem? The problem is that it may stop working a~week before your
submission date and when you go for help, you may be told you're
using obsolete packages and there's nothing for it but to rewrite
your thesis using the modern alternatives.

How do you know if a~package is obsolete? Some of the obsolete
packages and commands are listed in l2tabu~\cite{l2tabu}, or you can
check to see if a~package is listed in \gls{ctan}['s] obsolete
tree (\url{http://mirror.ctan.org/obsolete/}). Stefan~Kottwitz also
has a~list of obsolete classes and packages in his
\htmladdnormallinkfoot{TeXblog}{http://texblog.net/latex-articles/packages/}.
The other thing to do is check the package's entry on \gls{ctan} to
see if it has been deprecated. For example, suppose someone tells
you to use the \sty{glossary} package. If you go to
\url{http://ctan.org/pkg/glossary} it will tell you that the
\sty{glossary} package is no longer supported and that it's been
replaced by the \sty{glossaries} package. Similarly, if you go to
\url{http://ctan.org/pkg/epsfig} it will tell you that the
\sty{epsfig} package is obsolete and you should use \sty{graphicx}
instead.

\setnode{build}
\section{Building Your Document}
\label{sec:build}

To \dq{typeset}, \dq{build}, \dq{compile} or \dq{LaTeX} your
document means to run the \iappname{pdflatex} (or \iappname{latex})
executable on your document source code. If you are using a
front-end, such as TeXworks, WinEdt, TeXstudio, or TeXnicCenter,
this usually just means clicking on the appropriate button or
selecting the appropriate menu item.
(See \novices[ch:tex2pdf]{fromsource2output} for further details.)

It's important to remember that a~front-end is an
\keyword{interface}. It's not, for example, TeXworks that is
creating your PDF. When you click on the \dq{typeset} button, 
TeXworks tells the operating system to run the required executable.
This is usually \appname{pdflatex}, but there are other executables
that may need to be used to help create your document, such as
\iappname{bibtex} or \iappname{biber} (discussed in
\chapterref{ch:citations}) and \iappname{makeindex} or
\iappname{xindy} (discussed in \chapterref{ch:indgloss}).

For example, if your document has a~bibliography and you are using
TeXworks, you first need to make sure the drop-down menu is set to
\dq{pdfLaTeX} (see \figureref{fig:texworks-pdflatex}) and click on
the green \dq{Typeset} button. Then you need to select \dq{BibTeX}
from the drop-down menu (see \figureref{fig:texworks-bibtex}) and
click on the green \dq{Typeset} button. Then again select \dq{pdfLaTeX}
(\figureref{fig:texworks-pdflatex}) and click the \dq{Typeset}
button. Finally, to ensure your cross-references are all up-to-date,
you need to click on the \dq{Typeset} button again. If you are using
\iappname{biber} instead of \iappname{bibtex} (see
\sectionref{sec:biblatex}), then you have to replace the above
\dq{BibTeX} step with \dq{Biber} instead.

\begin{figure}[htbp]
\figconts
 {pictures/texworks-pdflatex}
 {\caption{Selecting pdfLaTeX from the Drop-Down Menu}}
 {fig:texworks-pdflatex}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/texworks-bibtex}
 {\caption{Selecting BibTeX from the Drop-Down Menu}}
 {fig:texworks-bibtex}
\end{figure}

If the tool you require isn't listed in the drop-down box, you will
have to add it. For example, to add \iappname{makeglossaries} to the
list of available tools in TeXworks, you need to select
\menu{Edit}\menuto\menu{Preferences}, which will open the
\dq{TeXworks Preferences} dialog. Make sure the \dq{Typesetting} tab
is selected and click on the lower
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} button
next to the \dq{Processing tools} list. This will open the \dq{Tool
Configuration} dialog. Set the \dq{Name} field to the name of the
application, as you want it to appear in the tool list (for example
\dq{MakeGlossaries}). Then click on the \dq{Browse} button to find
the application on your computer. Next you need to click on the
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} button
next to the \dq{Arguments} list. Set the argument to
\verb|$basename|. Since \appname{makeglossaries} doesn't modify the
PDF, uncheck the \dq{View PDF after running} box (see
\figureref{fig:texworks-makeglossaries}).

\begin{figure}[htbp]
\figconts
 {pictures/texworks-makeglossaries}
 {\caption{Adding Makeglossaries to the list of tools in TeXworks}}
 {fig:texworks-makeglossaries}
\end{figure}

This is a~bit of a~hassle (if not downright confusing for a
beginner) and even more so when you have glossaries and an index in
your document as well as a~bibliography. Fortunately there are ways
of automating this process so that you only need one button press to
perform all those different steps. There are several applications
available to do this for you, and I~strongly recommend you try one
of them, if possible, to reduce the complexity involved in building
a~document.

\novices{crossref} mentioned \iappname{latexmk}, which is available
on \gls{ctan}. This is a~Perl script, so it will run on any
operating system that has Perl installed (see \novices{perl}).
Since Volume~1 was published, a~Java alternative called
\iappname{arara} has arrived on \gls*{ctan}. Java applications will
run on any operating system that has the \htmladdnormallinkfoot{Java
Runtime Environment}{http://www.java.com/getjava/} installed, so
both \appname{latexmk} and \appname{arara} are multi-platform
solutions to automated document compilation.
\sectionref{sec:latexmk} gives a~brief introduction to
\appname{latexmk}, and \sectionref{sec:arara} gives a~brief
introduction to \appname{arara}.

\setnode{latexmk}
\subsection{LaTeXmk}
\label{sec:latexmk}

As mentioned \latexhtml{above}{\htmlref{in the previous
section}{sec:build}}, \iappname{latexmk} is a~Perl script that
automates the process of building a~\LaTeX\ document. In order to
use \appname{latexmk}, you must have Perl installed (see
\novices{perl}). Both TeX~Live and MikTeX come with
\appname{latexmk} but, if for some reason you don't have it
installed, you can use the TeX~Live or MikTeX update manager to
install it. Alternatively, you can download
\url{http://mirror.ctan.org/support/latexmk.zip} and install it
manually.

Once \appname{latexmk} is installed, you then need to add it to the
list of available tools in TeXworks\footnote{If you are using a
different front-end, you will have to consult your front-end's
manual.}. This is done via the \menu{Edit}\menuto\menu{Preferences}
menu item. This opens TeXwork's Preferences dialog box. Make sure
the \dq{Typesetting} tab is selected (\figureref{fig:texworks-pref}).

\begin{figure}[htbp]
\figconts
 {pictures/texworks-pref}
 {\caption{TeXwork's Preferences Dialog Box}}
 {fig:texworks-pref}
\end{figure}

To add a~new tool, click on the lower
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} 
button next to the list of processing tools. This opens the tool
configuration dialog box (\figureref{fig:texworks-latexmkbibtex}).

\begin{figure}
  \figconts
  {pictures/texworks-latexmkbibtex}
  {\caption{Adding LaTeXmk in the TeXWorks Tool Configuration Dialog}}
  {fig:texworks-latexmkbibtex}
\end{figure}

Type \dq{LaTeXmk} in the \dq{Name} box, then use the \dq{Browse}
button to locate \appname{latexmk} on your computer. Next you need
to click on the
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} button
to add each argument. The argument list should consist of the
following (in the order listed):
\begin{verbatim}
-e
$pdflatex=q/pdflatex $synctexoption %O %S/
-pdf
-bibtex
$fullname
\end{verbatim}

Once you've done this, click \dq{Okay} to close the tool
configuration dialog, and click \dq{Okay} to close the Preferences
dialog box. LaTeXmk should now be listed in the drop-down menu next
to the green \dq{Typeset} button. Now, if you have LaTeXmk selected
and you click on the \dq{Typeset} button \appname{pdflatex} and
\appname{bibtex}\slash\appname{biber} will be run as necessary to
create an up-to-date PDF.

Unfortunately, adding \iappname{makeindex}, \iappname{texindy} or
\iappname{makeglossaries} to LaTeXmk's set of rules is more
complicated. For this you need to create a~configuration\slash initialisation (RC) file\footnote{There are some example RC files
available at:
\url{http://mirror.ctan.org/support/latexmk/example_rcfiles/}.}. The
name and location of this file depends on your operating system. For
example, on a~Unix-like operating system, this may be
\verb|$HOME/.latexmkrc|. You will need to consult the
\appname{latexmk} manual~\cite{latexmk} for further details.

Once you've found out the name and location of the RC file for your
operating system, you can use the text editor of your choice to
create this file. To add \iappname{makeglossaries}, you need to type
the following in the RC file:
\begin{verbatim}
add_cus_dep('glo', 'gls', 0, 'makeglossaries');
add_cus_dep('acn', 'acr', 0, 'makeglossaries');
sub makeglossaries{
  system( "makeglossaries \"$_[0]\"" );
}
\end{verbatim}

To add \iappname{makeindex}, you need to type the following:
\begin{verbatim}
add_cus_dep('idx', 'ind', 0, 'makeindex');
sub makeindex{
  system("makeindex \"$_[0].idx\"");
}
\end{verbatim}

If you prefer to use \iappname{texindy} instead of
\appname{makeindex}, you will need to replace the above lines with
(change the language as appropriate):
\begin{verbatim}
add_cus_dep('idx', 'ind', 0, 'texindy');
sub texindy{
  system("texindy -L english \"$_[0].idx\"");
}
\end{verbatim}

Now select \dq{LaTeXmk} from the drop-down menu next to the green
\dq{Typeset} button in TeXworks (\figureref{fig:texworks-latexmk}),
and you're ready to build your documents.

\begin{figure}
  \figconts
  {pictures/texworks-latexmk}
  {\caption{LaTeXmk Tool Selected in TeXworks}}
  {fig:texworks-latexmk}
\end{figure}


\setnode{arara}
\subsection{Arara}
\label{sec:arara}

As mentioned in \sectionref{sec:build}, \iappname{arara} is a~Java
application that automates the process of building a~\LaTeX\
document. In order to use \appname{arara}, you must have the
\htmladdnormallink{Java Runtime
Environment}{http://www.java.com/getjava/} installed. The latest
TeX~Live distribution includes \appname{arara}, so you can install
it via the TeX~Live package manager.

Alternative, you can install \appname{arara} manually as follows:
fetch the installer
\htmladdnormallink{\texttt{arara-3.0\booklinebreak-installer.jar}}{https://github.com/cereda/arara/blob/master/releases/arara-3.0-installer.jar} 
(or
\htmladdnormallink{\texttt{arara-3.0-installer.exe}}{https://github.com/cereda/arara/blob/master/releases/arara-3.0-installer.exe})
from \url{https://github.com/cereda/arara/tree/master/releases}.
On Windows, run \reportlinebreak\screenlinebreak\texttt{arara-3.0-installer.exe}. On other operating
systems run \reportlinebreak\texttt{arara-3.0-\screenlinebreak installer.jar} in privileged mode.
For example, on a~Unix-based system:
\begin{verbatim}
sudo java -jar arara-3.0-installer.jar
\end{verbatim}
(If you are doing a~manual install make sure you check the box to add the predefined rules, as shown
in \figureref{fig:arara-installer}.)

\begin{figure}
  \figconts
  {pictures/arara-installer}
  {\caption{Arara Installer}}
  {fig:arara-installer}
\end{figure}

Once \appname{arara} has been installed, you can add it to the list
of tools in TeXworks. As \htmlref{before}{sec:latexmk}, open the
TeXwork's Preferences dialog box using
\menu{Edit}\menuto\menu{Preferences} and select the \dq{Typesetting}
tab (\figureref{fig:texworks-pref}).

To add a~new tool, click on the lower
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} 
button next to the list of processing tools. This opens the tool
configuration dialog box (\figureref{fig:texworks-arara}). Type
\dq{Arara} in the \dq{Name} box and use the \dq{Browse} button to
find the \appname{arara} application on your computer. Use the 
\incGraphics[alt=+,height=2ex]{pictures/texworks-addbutton} 
button to add \verb|$basename| to the list
of arguments, as shown in \figureref{fig:texworks-arara}.

\begin{figure}
  \figconts
  {pictures/texworks-arara}
  {\caption{Adding Arara in the TeXWorks Tool Configuration Dialog}}
  {fig:texworks-arara}
\end{figure}

Unlike \iappname{latexmk}, \appname{arara} doesn't read the log file
to determine what applications need to be run. Instead, you tell
\appname{arara} how to build your document by placing special comments 
in your source code. For example, if your document contains the
following:
\begin{code}
\begin{alltt}
\gls{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} bibtex
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\marg{scrbook}
\end{alltt}
\end{code}
Then running \appname{arara} on the document will run
\appname{pdflatex}, \appname{bibtex}, \appname{pdflatex} and
\appname{pdflatex} on your document. \appname{Arara} knows the rules
\dq{pdflatex} and \dq{bibtex}. It also knows the rules \dq{biber},
\dq{makeglossaries} and \dq{makeindex}.
So, if your document has a~bibliography, an index and glossaries,
you need to put the following comments in your source code
(replace \texttt{bibtex} with \texttt{biber} if required):
\begin{code}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }\newline
\glsni{percentchar.arara} bibtex\newline
\glsni{percentchar.arara} makeglossaries\newline
\glsni{percentchar.arara} makeindex\newline
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }\newline
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }\newline
\glsni{documentclass}\marg{scrbook}
\end{code}
Now you just need to select \dq{Arara} from the drop-down list in
TeXworks (\figureref{fig:texworks-arara2}) and click the green
\dq{Typeset} button, and \appname{arara} will do all the work for
you.

\xminisec{Note:}
\warning If you don't add these arara comments to your source code,
nothing will happen when you run \appname{arara} on your document!
You must remember to provide \appname{arara} with the rules to build
your document.

\begin{figure}
  \figconts
  {pictures/texworks-arara2}
  {\caption{Using Arara in TeXworks}}
  {fig:texworks-arara2}
\end{figure}

Unfortunately \appname{arara} (v3.0) doesn't have a~rule for
\iappname{texindy}, but you can add one by creating a~file called
\texttt{texindy.yaml} that contains the following:\footnote{Thanks to
Paulo Cereda for supply this.}\screenpagebreak
\begin{alltt}
!config
\# TeXindy rule for arara
\# requires arara 3.0+
identifier: texindy
name: TeXindy
command: <arara> texindy @\{german\} @\{language\} @\{codepage\} @\{module\}\bookcontinueline\reportcontinueline\screencontinueline @\{input\} @\{options\} "@\{getBasename(file)\}.idx"
arguments: 
- identifier: german
  flag: <arara> @\{isTrue(parameters.german,"-g")\}
- identifier: language
  flag: <arara> -L @\{parameters.language\}
- identifier: codepage
  flag: <arara> -C @\{parameters.codepage\}
- identifier: module
  flag: <arara> -M @\{parameters.module\}
- identifier: input
  flag: <arara> -I @\{parameters.input\}
- identifier: options
  flag: <arara> @\{parameters.options\}
\end{alltt}
\latex{(The symbol \continuesymbol\ above indicates a~line wrap.
Don't insert a~line break at that point.) }This file should be saved in the \texttt{rules} subdirectory of the
\texttt{arara} installation directory. (For example, on Unix-like
systems \texttt{/usr/local/arara/\reportlinebreak\screenlinebreak rules/texindy.yaml}.)

So if you'd rather use \appname{texindy} instead of
\appname{makeindex} you can replace the 
\begin{alltt}
\gls{percentchar.arara} makeindex
\end{alltt}
directive with
\begin{alltt}
\glsni{percentchar.arara} texindy: \marg*{ language: english, codepage: latin1 }
\end{alltt}
(Change the language and encoding as appropriate.)

\setnode{start}
\chapter{Getting Started}
\label{ch:start}

There are many different thesis designs, varying according to
university or discipline~\cite{thesistemplates}. If you have been told to use a~particular
class file, use that one. If not, there are a~selection of thesis
class files available on \gls{ctan} and listed in the
\htmladdnormallinkfoot{OnLine \TeX\ Catalogue's Topic
Index}{http://mirror.ctan.org/help/Catalogue/bytopic.html\#theses}~\cite{texcattopic}.
Since there are so many to choose from, I'm just going to follow on
from \htmladdnormallink{Volume~1}{\baseurl/latex/novices/} of this series and use one of the \koma\ class files.
But which one? The \icls{scrreprt} class is the one usually
recommended for a~report or thesis. It defaults to one-sided and has
an \gls{env-abstract} environment, but it doesn't define
\gls{frontmatter}, \gls{mainmatter} or \gls{backmatter}. The
\icls{scrbook} class does define those commands, but it doesn't
provide an \glsni{env-abstract} environment and defaults to two-sided
layout. So, you can either do:
\begin{code}
\begin{alltt}
\gls{documentclass}\marg{scrreprt}
\gls{title}\marg{A Sample Thesis}
\gls{author}\marg{A.N. Other}

\gls{begin}\marg{document}
\gls{maketitle}

\gls{pagenumbering}\marg{roman}
\gls{tableofcontents}

\gls{chapter}*\marg{Acknowledgements}

\glsni{begin}\marg{abstract}
This is the abstract
\gls{end}\marg{abstract}

\glsni{pagenumbering}\marg{arabic}

\glsni{chapter}\marg{Introduction}
...
\glsni{end}\marg{document}
\end{alltt}
\end{code}
\bookpagebreak\noindent
or you can do:
\begin{code}
\begin{alltt}
\gls{documentclass}\oarg{oneside}\marg{scrbook}
\gls{title}\marg{A Sample Thesis}
\gls{author}\marg{A.N. Other}

\glsni{begin}\marg{document}
\gls{maketitle}

\gls{frontmatter}
\gls{tableofcontents}

\glsni{chapter}\marg{Acknowledgements}

\glsni{chapter}\marg{Abstract}
This is the abstract

\gls{mainmatter}

\glsni{chapter}\marg{Introduction}
...
\glsni{end}\marg{document}
\end{alltt}
\end{code}
I'm going to use the second approach simply out of personal
preference. The \koma\ options mentioned in this book are available
for both \icls{scrreprt} and \icls{scrbook}, so choose whichever
class file you feel best suits your thesis.

Unless you have been told otherwise, I~recommend that you start
out with a~skeletal document that looks something like the
following:
\begin{codelisting}{thesis1.tex}\label{ex:thesis1}
\begin{alltt}
\gls{documentclass}\oarg{oneside}\marg{scrbook}

\gls{title}\marg{A Sample Thesis}
\gls{author}\marg{A.N. Other}
\gls{date}\marg{July 2013}
\gls{titlehead}\marg{A Thesis submitted for the degree of Doctor of Philosophy}
\gls{publishers}\marg{School of Something\gls{dbbackslashchar}University of Somewhere}

\glsni{begin}\marg{document}
\gls{maketitle}

\gls{frontmatter}
\gls{tableofcontents}
\gls{listoffigures}
\gls{listoftables}

\gls{chapter}\marg{Acknowledgements}

I would like to thank my supervisor, Professor Someone. This
research was funded by the Imaginary Research Council.

\gls{chapter}\marg{Abstract}

A brief summary of the project goes here.

\gls{percentchar} A glossary and list of acronyms may go here
\glsni{percentchar} or may go in the back matter.

\gls{mainmatter}

\gls{chapter}\marg{Introduction}
\gls{label}\marg{ch:intro}

\gls{chapter}\marg{Technical Introduction}
\glsni{label}\marg{ch:techintro}

\gls{chapter}\marg{Method}
\glsni{label}\marg{ch:method}

\gls{chapter}\marg{Results}
\glsni{label}\marg{ch:results}

\gls{chapter}\marg{Conclusions}
\glsni{label}\marg{ch:conc}

\gls{backmatter}

\glsni{percentchar} A glossary and list of acronyms may go here
\glsni{percentchar} or may go in the front matter after the abstract.

\glsni{percentchar} The bibliography will go here

\glsni{end}\marg{document}
\end{alltt}
\end{codelisting}

If you do this, it will help ensure that your document has the
correct structure before you begin with the actual contents of the
document. (Note that the chapter titles will naturally vary
depending on your subject or institution, and you may need a
different paper size if you are not in Europe. I~have based the
above on my own PhD thesis which I~wrote in the early to mid
1990s in the Department of Electronic Systems Engineering at
the University of Essex, and it may well not fit your own
requirements.)

If you haven't started your thesis yet, go ahead and try this.
Creating a~skeletal document can have an amazing psychological
effect on some people: for very little effort it can produce a
document several pages long, which can give you a~sense of
achievement that can help give you sufficient momentum to get
started (but of course, it's not guaranteed to work with
everyone). Remember that if you want to use \iappname{arara} 
(see \sectionref{sec:arara}) you must add the build rules to the
document:
\begin{code}
\begin{alltt}
\gls{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{oneside}\marg{scrbook}
\end{alltt}
\end{code}
(I'll add the \appname{arara} rules to sample listings, in the event
that you want to use \appname{arara}. Since they are comments, they
will be ignored if you use \iappname{pdflatex} explicitly or if you
use another automation method, such as \iappname{latexmk}.)

Now think about other requirements. What font size have you been
told to use?
\begin{description}
\item[10pt] Use the \clsopt{10pt} class option:
\begin{codeS}
\gls{documentclass}\oarg{oneside,10pt}\marg{scrbook}
\end{codeS}

\item[11pt] Use the \clsopt{11pt} class option:
\begin{codeS}
\gls{documentclass}\oarg{oneside,11pt}\marg{scrbook}
\end{codeS}

\item[12pt] Use the \clsopt{12pt} class option:
\begin{codeS}
\gls{documentclass}\oarg{oneside,12pt}\marg{scrbook}
\end{codeS}
\end{description}
Have you been told to have a~blank line between paragraphs and no
paragraph indentation? If so, use the \scrclsopt[full]{parskip} class
option:
\begin{codeS}
\gls{documentclass}\oarg{oneside,12pt,parskip=full}\marg{scrbook}
\end{codeS}
\label{geometry}%
\faq{Changing the margins in \LaTeX}{changemargin}Have you been told to have certain sized margins? If so, you can use
the \isty{geometry} package. For example, if you have been told you
must have 1~inch margins, you can do
\begin{codeS}
\gls{usepackage}\oarg{margin=1in}\marg{geometry}
\end{codeS}
Changing the default fonts is covered in \novices[sec:changingfonts]{documentfonts}.
Other possible formatting requirements, such as double-spacing, are
covered in \chapterref{ch:formatting}.

\setnode{include}
\chapter{Splitting a~Large Document into Several Files}
\label{ch:include}

Some people prefer to place each chapter of a~large document in a
separate file and then input the file into the main document.

There are two basic ways of including the contents of an external
file:
\begin{definition}
\gls{input}\marg{\meta{filename}}
\end{definition}
and
\begin{definition}
\gls{include}\marg{\meta{filename}}
\end{definition}
where \meta{filename} is the name of the file. (The \texttt{.tex}
extension may be omitted in both cases.) The differences between the
two commands are as follows:
\begin{description}
 \item[\glsni{input}] acts as though the contents of the file were
  typed where the \glsni{input} command was. For example, suppose my
  main file contained the following:
\begin{code}
\begin{alltt}
Here is a short paragraph.

\glsni{input}\marg{myfile}
\end{alltt}
\end{code}
and suppose the file \texttt{myfile.tex} contained the following
lines:
\begin{code}
\begin{alltt}
Here is some sample text.
\end{alltt}
\end{code}
then the \glsni{input} command behaves as though you had simply
typed the following in your main document file:
\begin{code}
\begin{alltt}
Here is a short paragraph.

Here is some sample text.
\end{alltt}
\end{code}

 \item[\glsni{include}] does more than just input the contents of
 the file. It also starts a~new page (using \gls{clearpage}) and creates an auxiliary file
 associated with the included file. It also issues another \glsni{clearpage}
 once the file has been read in. Using this approach, you can also
 govern which files to include using
\begin{definition}
\gls{includeonly}\marg{\meta{file list}}
\end{definition}
in the preamble, where \meta{file list} is a~comma-separated list of
files you want included. This way, if you only want to work on one
or two chapters, you can only include those chapters, which will
speed up the document build.  \LaTeX\ will still read in all the
cross-referencing information for the missing chapters, but won't
include those chapters in the PDF file.  There is a~definite advantage to this
if you have, say, a~large number of images in your results chapter,
which you don't need when you're working on, say, the technical
introduction.  You can still reference all the figures in the
omitted chapter, as long as you have previously 
\htmladdnormallink{\LaTeX{}ed the
document}{\baseurl/latex/novices/html/fromsource2output.html\#itm:step2}
without the \glsni{includeonly} command.

The \sty{excludeonly} package provides the logically opposite
command:
\begin{definition}
\gls{excludeonly}\marg{\meta{file list}}
\end{definition}

\end{description}

The \htmlref{previous example}{ex:thesis1}\doifbook{ \vpageref{ex:thesis1}} can 
now be split into various files:
\begin{codelisting}[\texttt{thesis.tex}]{thesis2.tex}\label{ex:thesis2}
\begin{alltt}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\gls{documentclass}\oarg{oneside}\marg{scrbook}

\gls{title}\marg{A Sample Thesis}
\gls{author}\marg{A.N. Other}
\gls{date}\marg{July 2013}
\gls{titlehead}\marg{A Thesis submitted for the degree of Doctor of Philosophy}
\gls{publishers}\marg{School of Something\gls{dbbackslashchar}University of Somewhere}

\glsni{begin}\marg{document}
\gls{maketitle}

\gls{frontmatter}
\gls{tableofcontents}
\gls{listoffigures}
\gls{listoftables}

\gls{chapter}\marg{Acknowledgements}

I would like to thank my supervisor, Professor Someone. This
research was funded by the Imaginary Research Council.

\gls{chapter}\marg{Abstract}

A brief summary of the project goes here.

\gls{mainmatter}

\glsni{include}\marg{intro}

\glsni{include}\marg{techintro}

\glsni{include}\marg{method}

\glsni{include}\marg{results}

\glsni{include}\marg{conc}

\gls{backmatter}

\glsni{end}\marg{document}
\end{alltt}
\end{codelisting}

\begin{codelisting}[\texttt{intro.tex}]{intro.tex}
\begin{alltt}
\gls{chapter}\marg{Introduction}
\gls{label}\marg{ch:intro}
\end{alltt}
\end{codelisting}

\begin{codelisting}[\texttt{techintro.tex}]{techintro.tex}
\begin{alltt}
\gls{chapter}\marg{Technical Introduction}
\gls{label}\marg{ch:techintro}
\end{alltt}
\end{codelisting}

\begin{codelisting}[\texttt{method.tex}]{method.tex}
\begin{alltt}
\gls{chapter}\marg{Method}
\gls{label}\marg{ch:method}
\end{alltt}
\end{codelisting}

\begin{codelisting}[\texttt{results.tex}]{results.tex}
\begin{alltt}
\gls{chapter}\marg{Results}
\gls{label}\marg{ch:results}
\end{alltt}
\end{codelisting}

\begin{codelisting}[\texttt{conc.tex}]{conc.tex}
\begin{alltt}
\gls{chapter}\marg{Conclusions}
\gls{label}\marg{ch:conc}
\end{alltt}
\end{codelisting}

If you only want to work on, say, the Method and Results chapters,
you can place the following command in the preamble:
\begin{codeS}
\glsni{includeonly}\marg{method,results}
\end{codeS}

% Formatting

\setnode{formatting}
\chapter{Formatting}
\label{ch:formatting}

It used to be that in order to change the format of chapter and
section headings, you needed to have some understanding of the
internal workings of classes such as \icls{report} or \icls{book}.
Modern classes, such as \icls{memoir} and the \koma\ classes,
provide a~much easier interface. However, I~recommend that you first
write your thesis, and then worry about changing the document style.
The ability to separate content from style is one of the
advantages of using \LaTeX\ over a~word processor. Remember that
writing your thesis is more important than the layout. Whilst it may
be that your school or department insists on a~certain style, it
should not take precedence over the actual task of writing.

\setnode{docstyles}
\section{Changing the Document Style}
\label{sec:docstyles}

If you are using a~custom thesis class file provided by your
department or school, then you should stick to the styles set up in
that class. If not, you may need to change the default style of your
chosen class to fit the requirements. \novices[sec:section]{sectionunits} described 
how to change the fonts used by chapter and section headings for the
\koma\ classes. For example, if the chapter headings must be set in
a~large, bold, serif font you can do:
\begin{codeS}
\gls{addtokomafont}\marg{\gls{large}\gls{bfseries}\gls{rmfamily}}
\end{codeS}
The headings in the \koma\ classes default to ragged-right
justification (recall \gls{raggedright} from
\xrsectionref{Declarations}{declaration} of Volume~1) which is done via
\begin{definition}
\gls{raggedsection}
\end{definition}
This can be redefined as required. For example, suppose you are
required to have centred headings, then you can do:
\begin{codeS}
\gls{renewcommand}*\marg{\glsni{raggedsection}}\marg{\gls{centering}}
\end{codeS}

\setnode{newpagestyle}
\section{Changing the Page Style}
\label{sec:newpagestyle}

\novices{pagestyle} described the command
\begin{definition}
\gls{pagestyle}\marg{\meta{style}}
\end{definition}
which can be used to set the page style. The \icls{scrbook} class
defaults to the \ipagestyle{headings} page style, but if this isn't
appropriate, you can use the \isty{scrpage2} package, which comes
with the \koma\ bundle. This package provides its own versions of
the \ipagestyle{plain} and \pagestylefmt{headings} page styles, called
\ipagestyle{scrplain} and \ipagestyle{scrheadings}.

For simplicity, I'm assuming that your thesis is a~one-sided
document. If this isn't the case and your odd and even page styles
need to be different, you'll need to consult the \koma\
documentation~\cite{koma}.

With the \pagestylefmt{scrheadings} page style, the page header and
footer are both divided into three areas
(\figureref{fig:pagestyle}): the inner (left) head/foot, the centre
head/foot and the outer (right) head/foot.

\begin{figure}[htbp]
\figconts
 {pictures/pagestyle}
 {\caption{Page Header and Footer Elements}}
 {fig:pagestyle}
\end{figure}

These elements can be set using:
\begin{definition}
\gls{ihead}\oarg{\meta{scrplain inner head}}\marg{\meta{scrheadings inner head}}\\
\gls{chead}\oarg{\meta{scrplain centre head}}\marg{\meta{scrheadings centre head}}\\
\gls{ohead}\oarg{\meta{scrplain outer head}}\marg{\meta{scrheadings outer head}}\\
\gls{ifoot}\oarg{\meta{scrplain inner foot}}\marg{\meta{scrheadings inner foot}}\\
\gls{cfoot}\oarg{\meta{scrplain centre foot}}\marg{\meta{scrheadings centre foot}}\\
\gls{ofoot}\oarg{\meta{scrplain outer foot}}\marg{\meta{scrheadings outer foot}}
\end{definition}
In each case, the optional argument indicates what to do if the
\pagestylefmt{scrplain} page style is in use and the mandatory
argument indicates what to do if the \pagestylefmt{scrheadings}
page style is in use. (If the optional argument is missing, no
modification is made to the \pagestylefmt{scrplain} style.) 
Within both types of argument, you can use
\begin{definition}
\gls{pagemark}
\end{definition}
to insert the current page number and
\begin{definition}
\gls{headmark}
\end{definition}
to insert the running heading. For example, suppose you are required
to put your registration number on the bottom left of each page and
the page number on the bottom right, and you are also required to put
the current chapter or section heading at the top left of each page,
unless it's the first page of a~chapter. Then you can do:
\begin{codelisting}{thesis-pagestyles.tex}
\begin{alltt}
\glsni{usepackage}\marg{scrpage2}

\gls{pagestyle}\marg{scrheadings}

\gls{newcommand}\marg{\cmdname{myregnum}}\marg{123456789}\glsni{percentchar} registration number

\glsni{ihead}\marg{}
\glsni{chead}\marg{}
\glsni{ohead}\oarg{}\marg{\glsni{headmark}}
\glsni{ifoot}\oarg{\cmdname{myregnum}}\marg{\cmdname{myregnum}}\glsni{percentchar} registration number
\glsni{cfoot}\oarg{}\marg{}
\glsni{ofoot}\oarg{\glsni{pagemark}}\marg{\glsni{pagemark}}
\end{alltt}
\end{codelisting}

Note that the above don't use any font changing commands. If you
want to change the font for the header and footer, you need to
redefine \gls{headfont}. The page number style is given by
\gls{pnumfont}. So for italic headers and footers with bold
page numbers, you can redefine these commands as follows:
\begin{code}
\glsni{renewcommand}*\marg{\glsni{headfont}}\marg{\gls{normalfont}\gls{itshape}}\newline
\glsni{renewcommand}*\marg{\glsni{pnumfont}}\marg{\glsni{normalfont}\glsni{bfseries}}
\end{code}

\setnode{setspace}
\section{Double-Spacing}
\label{sec:setspace}

Whilst double-spacing is usually frowned upon in the world of modern
typesetting, it is usually a~requirement for anything that may need
hand-written annotations, which can include theses. This extra space
gives the examiners room to write comments.\footnote{Despite the
current digital age, many people still use hand-written annotations
on manuscripts. It's unlikely that your examiners have pens
that are incompatible with your paper.}

Double-spacing can be achieved via the \isty{setspace} package. You
can either set the spacing using the package options \istyopt{setspace}{singlespacing},
\istyopt{setspace}{onehalfspacing} or \istyopt{setspace}{doublespacing},
or you can switch via the declarations:
\begin{definition}
\gls{singlespacing}\newline
\gls{onehalfspacing}\newline
\gls{doublespacing}
\end{definition}
So, if your thesis has to be double-spaced, you can do:
\begin{codelisting}{thesis-doublespaced.tex}
\begin{alltt}
\glsni{usepackage}\oarg{doublespacing}\marg{setspace}
\end{alltt}
\end{codelisting}

\setnode{titlepagelayout}
\section{Changing the Title Page}
\label{sec:titlepage}

\novices{title} described how to lay out the title page using
\gls{maketitle}. If this layout isn't appropriate for your
school or department's specifications, you can lay out the title page
manually using the \gls{env-titlepage} environment instead of
\gls{maketitle}. Within this environment, you can use
\gls{hspace}\marg{\meta{length}} and \gls{vspace}\marg{\meta{length}}
to insert horizontal and vertical spacing. (The unstarred versions
are ignored if they occur at the start of a~line or page,
respectively. The starred versions will insert the given
spacing, regardless of their location.) You can also use \gls{hfill}
and \gls{vfill}, which will expand to fill the available space
horizontally or vertically, respectively.

\bookpagebreak
\xminisec{Example:}

\begin{codelisting}{thesis-titlepage.tex}
\begin{alltt}
\glsni{begin}\marg{titlepage}
 \gls{centering}
 \glsni{vspace}*\marg{1in}
 \glsni{begin}\marg{Large}\glsni{bfseries}
  A Sample PhD Thesis\glsni{par}
 \glsni{end}\marg{Large}
 \glsni{vspace}\marg{1.5in}
 \glsni{begin}\marg{large}\glsni{bfseries}
  A. N. Other\glsni{par}
 \glsni{end}\marg{large}
 \glsni{vfill}
 A Thesis submitted for the degree of Doctor of Philosophy
 \glsni{par}
 \glsni{vspace}\marg{0.5in}
 School of Something
 \glsni{par}
 University of Somewhere
 \glsni{par}
 \glsni{vspace}\marg{0.5in}
 July 2013
 \glsni{par}
\glsni{end}\marg{titlepage}
\end{alltt}
\end{codelisting}
The result is shown in \figureref{fig:titlepage}.
(If you require \htmlref{double-spacing}{sec:setspace}, you may need
to wait until after the title page before switching to
double-spacing.)

\begin{figure}[htbp]
\fboxfigconts
 {pictures/titlepage}
 {\caption{Sample Title Page}}
 {fig:titlepage}
\end{figure}

\setnode{verbatim}
\section{Listings and Other Verbatim Text}
\label{sec:verbatim}

\faq{Code listings in \LaTeX}{codelist}There may be times when you want to include text exactly as you have
typed it into your source code. For example, you may want to include
a~short segment of computer code. This can be done using the \gls{env-verbatim}
environment.

\xminisec{Example:}

Note how I~don't need to worry about \htmladdnormallink{special
characters}{\baseurl/latex/novices/html/symbols.html}, such as
\gls{hashchar}, within the \glsni{env-verbatim} environment:
\begin{code}
\begin{alltt}
\glsni{begin}\marg{verbatim}
\#include <stdio.h> /* needed for printf */

int main()
\marg*{
   printf("Hello World\cmdname{n}");

   return 1;
}
\glsni{end}\marg{verbatim}
\end{alltt}
\end{code}
This just produces:
\begin{result}[verbatim.html]
\begin{verbatim}
#include <stdio.h> /* needed for printf */

int main()
{
   printf("Hello World\n");

   return 1;
}
\end{verbatim}
\end{result}

A more sophisticated approach is to use the \isty{listings} package.
With this package, you first need to specify the programming
language. For example, the above code is in C, so I~need to specify
this using:
\begin{codeS}
\gls{lstset}\marg{language=C}
\end{codeS}
Now I~can use the \gls{env-lstlisting} environment to typeset my 
C~code:
\begin{code}
\begin{alltt}
\glsni{begin}\marg{lstlisting}
\#include <stdio.h> /* needed for printf */

int main()
\marg*{
   printf("Hello World\cmdname{n}");

   return 1;
}
\glsni{end}\marg{lstlisting}
\end{alltt}
\end{code}
The resulting output looks like:
\begin{result}[The keywords 'include' 'int' and 'return' are rendered in bold. The normal serif font is used.]
\lstset{language=C}
\lstinputlisting{listing-samples/helloworld.c}
\end{result}
I~can also have inline code snippets using:
\begin{definition}
\gls{lstinline}\oarg{\meta{options}}\meta{char}\meta{code}\meta{char}
\end{definition}
This is different syntax to the usual forms of command argument.
You can chose any character \meta{char} that isn't
the open square bracket \gls{opt.opensq}
and that doesn't occur in
\meta{code} to delimit the code, but the start and end \meta{char}
must match. (The optional argument is discussed below.) So the following are all equivalent:
\begin{enumerate}
\item \meta{char} is the exclamation mark character:
\begin{codeS}
\glsni{lstinline}!\#include <stdio.h>!
\end{codeS}

\item \meta{char} is the vertical bar character:
\begin{codeS}
\glsni{lstinline}|\#include <stdio.h>|
\end{codeS}

\item \meta{char} is the double-quote character:
\begin{codeS}
\glsni{lstinline}"\#include <stdio.h>"
\end{codeS}

\item \meta{char} is the plus symbol:
\begin{codeS}
\glsni{lstinline}+\#include <stdio.h>+
\end{codeS}

\end{enumerate}
And so on, but \meta{char} can't be, say, \verb|#| as that occurs in
\meta{code}. Example:
\begin{code}
The stdio header file (required for the \glsni{lstinline}+printf+
function) is loaded using the directive
\glsni{lstinline}!\#include <stdio.h>! on the
first line.
\end{code}
Result:
\begin{result}[The keyword 'include' is rendered in bold.]
\lstset{language=C}%
The stdio header file (required for the \lstinline+printf+ function)
is loaded using the directive
\lstinline!#include <stdio.h>! on the
first line.
\end{result}

Another alternative is to input the code from an external file. For
example, suppose my C~code is contained in the file
\texttt{helloworld.c}, then I~can input it using:
\begin{codeS}
\gls{lstinputlisting}\oarg{\meta{options}}\marg{helloworld.c}
\end{codeS}
(Remember to use a~forward slash \texttt{/} as the directory
divider, even if you are using Windows.)

All the above (\glsni{lstinline}, \glsni{lstinputlisting} and the 
\glsni{env-lstlisting} environment) have an optional argument
\meta{options} that
can be used to override the default settings. These are
\meta{key}=\meta{value} options.  There are a~lot of options
available, but I'm only going to cover a~few. If you want more
detail, have a~look at the \sty{listings}
documentation~\cite{listings}.

\begin{description}
\item[\ikeyvalopt{lstinputlisting}{title}=\marg{\meta{text}}] is used to
set an unnumbered and unlabelled title. If \meta{text} contains a
comma or equal sign, make sure you enclose \meta{text} in curly
braces \gls{leftbracechar} and~\gls{rightbracechar}.

\item[\ikeyvalopt{lstinputlisting}{caption}=\marg{\oarg{\meta{short}}\meta{text}}] is
used to set a~numbered caption. The optional part \meta{short} is an
alternative short caption for the list of listings, which can be
produced using
\begin{definition}
\gls{lstlistoflistings}
\end{definition}
As above, if the caption contains a~comma or equal sign, make sure
you enclose it in curly braces \glsni{leftbracechar} and
\glsni{rightbracechar}.

\item[\ikeyvalopt{lstinputlisting}{label}=\marg{\meta{text}}] is used to
assign a~label to this listing so the number can be referenced via
\gls{ref}.

\item[\ikeyvalopt{lstinputlisting}{numbers}=\marg{\meta{setting}}]
The value \meta{setting} may be one of: \texttt{none} (no line
numbers), \texttt{left} (line numbers on the left) or 
\texttt{right} (line numbers on the right). 

\item[\ikeyvalopt{lstinputlisting}{mathescape}] This is a~boolean
key that can either be \texttt{true} (dollar
\gls{dollarchar} character acts as the usual math mode shift) or \texttt{false} 
(deactivates the usual behaviour of \glsni{dollarchar}).

\item[\ikeyvalopt{lstinputlisting}{basicstyle}=\marg{\meta{declaration}}]
The value (one or more declarations) is used 
at the start of the listing to set the basic font style. For
example, \meta{declaration} could be \gls{ttfamily} (which actually
makes more sense for a~listing).

\end{description}\reportpagebreak

\xminisec{Note:}
\warning If you set \ikeyvalopt{lstinputlisting}{basicstyle} to
\glsni{ttfamily} and you want bold keywords, make sure you are using a
typewriter font that supports bold, as not all of them do. (Recall
from \novices[sec:changingfonts]{documentfonts} how to change the font family.) This
book uses txtt (see \novices{renewcom}). Other possibilities include 
\sty{beramono}, \sty{tgcursor}, \sty{courier}, \sty{DejaVuSansMono}
(or \sty{dejavu} to load the serif and sans-serif DejaVu fonts as
well), \sty{lmodern} and \sty{luximono}.

\xminisec{KOMA and \sty{listings}}
\warning If you want to use the \sty{listings} package with one of
the \koma\ classes, you need to load \sty{scrhack} \emph{before}
\sty{listings}, otherwise you will get a~warning that looks like:
\begin{verbatim}
Class scrbook Warning: Usage of deprecated \float@listhead!
(scrbook)              You should use the features of package `tocbasic'
(scrbook)              instead of \float@listhead.
(scrbook)              Definition of \float@listhead my be removed from
(scrbook)              `scrbook' soon, so it should not be used  on input 
line 57.
\end{verbatim}

\xminisec{Example:}

\begin{codelisting}{thesis-listings.tex}
\null\par

\glsni{begin}\marg{lstlisting}\oarg{language=C\comma basicstyle=\glsni{ttfamily}\comma mathescape=true}\newline
\#include <stdio.h> /* needed for printf */\newline
\#include <math.h> /* needed for sqrt */\newline
\mbox{}\newline
int main()\newline
\marg*{\newline
\mbox{}~~~double x = sqrt(2.0); /* \glsni{dollarchar}x = \gls{sqrt}\marg{2}\glsni{dollarchar} */\newline
\mbox{}\newline
\mbox{}~~~printf("x = \%f\cmdname{n}", x);\newline
\mbox{}\newline
\mbox{}~~~return 1;\newline
}\newline
\glsni{end}\marg{lstlisting}
\end{codelisting}
Result:
\begin{result}[The formula in the comment is typeset in math mode and spaces in the string are displayed with the visible space symbol]
\lstinputlisting[language=C,basicstyle=\ttfamily,mathescape=true]{listing-samples/sqrt.c}
\end{result}
If you are using \htmlref{double-spacing}{sec:setspace}, you may
need to temporarily switch it off in the listings. You can do this
by adding \gls{singlespacing} to the \ikeyvalopt{lstset}{basicstyle} setting.
\begin{codeS}
\glsni{lstset}\marg{basicstyle=\marg{\glsni{ttfamily}\glsni{singlespacing}}}
\end{codeS}
(Check with your supervisor to find out if listings should be
double- or single-spaced.)

\xminisec{Note:}
It is not usually appropriate to have reams of listings in
your thesis. It can annoy an examiner if you have included every
single piece of code you have written during your PhD, as it comes
across as padding to make it look as though your thesis is a~lot
larger than it really is. (Examiners are not easily fooled, and it's
best not to irritate them as it is likely to make them less
sympathetic towards you.) If you want to include listings in your
thesis, check with your supervisor first to find out whether or not
it is appropriate. 

\warning
Be careful when you use verbatim-like environments or commands, such
as \gls{env-verbatim}, \gls{env-lstlisting}, \gls{lstinline} and
\gls{lstinputlisting}. In general, they can't be used in the
argument of another command.\faq{Why doesn't verbatim work within
\ldots?}{verbwithin}

\setnode{tabbing}
\section{Tabbing}
\label{sec:tabbing}

The \gls{env-tabbing} environment lets you create tab stops so that you
can tab to a~particular distance from the left margin.  Within the
tabbing environment, you can use the command \gls{tabstop} to set a~tab
stop, \gls{greaterthan} to jump to the next tab stop, \gls{lessthan} to go
back a~tab stop, \gls{plus} to shift the left border by one tab stop
to the right, \gls{hyphen-tab} to shift the left border by one tab stop to
the left. In addition, \gls{dbbackslashchar} will start a~new line and
\gls{kill} will set any tabs stops defined in that line, but will
not typeset the line itself.

\xminisec{Note:}
\warning You may recall two of the above commands from Volume~1:
\gls{hyphen-discretionary} was described as a~discretionary hyphen
in \xrsectionref{Hyphenation}{hyphenation} and \gls{macron} was
described as the macron accent command in
\xrsectionref[sec:chars]{Special Characters and Symbols}{symbols}.
These two commands take on different meanings when they are used in
the \glsni{env-tabbing} environment.\faq{Accents misbehave in 
\envname{tabbing}}{tabacc} If you want accents in your
\glsni{env-tabbing} environment, either use the \isty{inputenc}
package (see \novices{inputenc}) or use \gls{a}\meta{accent symbol}\marg{\meta{c}}, 
for example \verb|\a"{u}| instead of
\verb|\"{u}|.\reportpagebreak\screenpagebreak

\xminisec{Example:}

\begin{code}
\begin{alltt}
\glsni{begin}\marg{tabbing}
Zero \glsni{tabstop}One \glsni{tabstop}Two \glsni{tabstop}Three\glsni{dbbackslashchar}
\glsni{greaterthan}First tab stop\glsni{dbbackslashchar}
\glsni{greaterthan}A\glsni{greaterthan}\glsni{greaterthan}B\glsni{dbbackslashchar}
\glsni{greaterthan}\glsni{greaterthan}Second tab stop
\glsni{end}\marg{tabbing}
\end{alltt}
\end{code}
This produces the following output:
\begin{result}
\begin{tabbing}
Zero \=One \=Two \=Three\\
\>First tab stop\\
\>A\>\>B\\
\>\>Second tab stop
\end{tabbing}
\end{result}

\xminisec{Another Example:}
This example sets up four tab stops, but ignores the
first line:
\begin{code}
\begin{alltt}
\glsni{begin}\marg{tabbing}
AAA \glsni{tabstop}BBBB \glsni{tabstop}XX \glsni{tabstop}YYYYYY \glsni{tabstop}Z \glsni{kill}
\glsni{greaterthan}\glsni{greaterthan}\glsni{greaterthan}Third tab stop\glsni{dbbackslashchar}
\glsni{greaterthan}a \glsni{greaterthan}b \glsni{greaterthan} \glsni{greaterthan}c
\glsni{end}\marg{tabbing}
\end{alltt}
\end{code}
This produces the following output:
\begin{result}[The first line isn't shown]
\begin{tabbing}
AAA \=BBBB \=XX \=YYYYYY \=Z \kill
\>\>\>Third tab stop\\
\>a \>b \> \>c
\end{tabbing}
\end{result}

\setnode{newtheorem}
\section{Theorems}
\label{sec:newtheorem}

A PhD thesis can often contain theorems, lemmas, definitions etc.
The \LaTeX\ kernel comes with the command:
\begin{definition}
\gls{newtheorem}\marg{\meta{name}}\oarg{\meta{counter}}\marg{\meta{title}}\oarg{\meta{outer counter}}
\end{definition}
which can be used to create an environment called \meta{name} that
has an optional argument. Each instance of the environment starts
with \meta{title} followed by the associated counter value. If
\meta{counter} is present, the new environment uses that counter
instead of having a~new counter defined for it. If \meta{outer
counter} is present, the environment counter is reset every time
\meta{outer counter} is incremented. The optional arguments are
mutually exclusive.

In the example below, I've use \glsni{newtheorem} to define a~new
environment called \envname{theorem}, which has an associated
counter, also called \counter{theorem}, that is dependant on the
\counter{chapter} counter.\bookpagebreak
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\glsni{newtheorem}\marg{theorem}\marg{Theorem}\oarg{chapter}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{theorem}
If proposition \glsni{dollarchar}P\glsni{dollarchar} is a tautology 
then \glsni{dollarchar}\gls{sim} P\glsni{dollarchar} is a contradiction,
and conversely.
\glsni{end}\marg{theorem}
\end{alltt}
\end{code}
Resulting output:
\begin{result}[theorem.html]
\begin{theorem}
If proposition $P$ is a tautology then $\sim P$ is a contradiction,
and conversely.
\end{theorem}
\end{result}
The optional argument to the new environment can be used to add a
caption. Modifying the above example (changes shown \modification{like this}):
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\glsni{newtheorem}\marg{theorem}\marg{Theorem}\oarg{chapter}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{theorem}\modification{\oarg{Tautologies and Contradictions}}
If proposition \glsni{dollarchar}P\glsni{dollarchar} is a tautology 
then \glsni{dollarchar}\glsni{sim} P\glsni{dollarchar} is a contradiction,
and conversely.
\glsni{end}\marg{theorem}
\end{alltt}
\end{code}\reportpagebreak\noindent
Resulting output:
\begin{result}[As the previous example except the code in the optional argument is added in paretheses to the running header]
\begin{theorem}[Tautologies and Contradictions]
If proposition $P$ is a tautology then $\sim P$ is a contradiction,
and conversely.
\end{theorem}
\end{result}
Here's an example that uses the first optional argument of
\glsni{newtheorem}:
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\glsni{newtheorem}\marg{exercise}\marg{Exercise}
\glsni{newtheorem}\marg{suppexercise}\oarg{exercise}\marg{Supplementary Exercise}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{exercise}
This is an example of how to create a theorem-like environment.
\glsni{end}\marg{exercise}
\glsni{begin}\marg{suppexercise}
This is another example of how to create a theorem-like environment.
\glsni{end}\marg{suppexercise}
\end{alltt}
\end{code}
Result:
\begin{result}[extheorem.html]
\begin{Exercise}
This is an example of how to create a theorem-like environment.
\end{Exercise}
\begin{Suppexercise}
This is another example of how to create a theorem-like environment.
\end{Suppexercise}
\end{result}

Unfortunately there isn't a~great deal of flexibility with the
environment appearance. \faq{Theorem bodies printed in a~roman
font}{theoremfmt}However there are various packages available that
provide enhancements to this basic command, allowing you to adjust
the appearance to suit your requirements.  There seem to be two main
contenders: \isty{amsthm} and \isty{ntheorem}. Both have advantages
and disadvantages. For example, \sty{ntheorem} is more flexible but
\isty{amsthm} is more robust. Therefore I'm going to describe both,
and you will have to decide which one you prefer.

\xminisec{Note:}
\warning If you are using either packages with \isty{amsmath}, you must
load \sty{amsmath} first:
\begin{code}
\begin{alltt}
\gls{usepackage}\marg{amsmath}
\gls{usepackage}\marg{ntheorem}
\end{alltt}
\end{code}
or
\begin{code}
\begin{alltt}
\gls{usepackage}\marg{amsmath}
\gls{usepackage}\marg{amsthm}
\end{alltt}
\end{code}

With both \sty{amsthm} and \sty{ntheorem}, you can still define new
theorem-like environments using \gls{newtheorem}, but there is also
a~starred version of that command, which can be used to define
unnumbered theorem-like environments.

\xminisec{Example:}
Suppose I~want to have an unnumbered \envname{remark} environment, 
I~can define the environment like this:
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\glsni{newtheorem}*\marg{note}\marg{Note}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{note}
This is a note about something.
\glsni{end}\marg{note}
\end{alltt}
\end{code}
Result:
\begin{result}[Similar to before but the header text is just 'Note' without a number]
\begin{plainnote}
This is a note about something.
\end{plainnote}
\end{result}

\setnode{amsthm}
\subsection{The \sty{amsthm} Package}
\label{sec:amsthm}

The \isty{amsthm} package provides three predefined theorem styles:
\texttt{plain}, \texttt{definition} and \texttt{remark}. When you define a
new theorem-like environment with \gls{newtheorem}, it is given
the style \emph{currently in effect}. You can change the
current style with:
\begin{definition}
\gls{theoremstyle}\marg{\meta{style name}}
\end{definition}
where \meta{style name} is the name of the theorem style.

\xminisec{Example:}

This example defines six theorem-like environments: \envname{theorem},
\envname{lemma}, \envname{defn}, \envname{conj}, \envname{note} and
\envname{remark}. The \envname{note} environment is unnumbered as
it's defined using the starred version of \glsni{newtheorem}.
The definitions have been arranged according to the required theorem style.
\begin{code}
\begin{alltt}
\glsni{theoremstyle}\marg{plain}
\glsni{newtheorem}\marg{theorem}\marg{Theorem}
\glsni{newtheorem}\marg{lemma}\marg{Lemma}

\glsni{theoremstyle}\marg{definition}
\glsni{newtheorem}\marg{defn}\marg{Definition}
\glsni{newtheorem}\marg{conj}\marg{Conjecture}

\glsni{theoremstyle}\marg{remark}
\glsni{newtheorem}*\marg{note}\marg{Note}
\glsni{newtheorem}\marg{remark}\marg{Remark}
\end{alltt}
\end{code}

\label{amsthm-proof}%
The \sty{amsthm} package also provides the \gls{env-proof} environment,
which can be used for typesetting proofs.
\begin{definition}
\glsni{begin}\marg{proof}\oarg{\meta{title}}
\end{definition}
The optional argument \meta{title} is a replacement for the default
title. This environment automatically inserts a~QED symbol at
the end of it, but if the default location isn't appropriate (which
can happen if the proof ends with an equation) then use
\begin{definition}
\gls{qedhere}
\end{definition}
where you want the QED symbol to appear. The symbol is given by
\begin{definition}
\gls{qedsymbol}
\end{definition}
This defaults to an unfilled square $\openbox$, but you can redefine
\glsni{qedsymbol} to something else if you prefer. (Recall
redefining commands from \novices{renewcom}.)

\begin{codelisting}{thesis-amsthm.tex}
\null\par

\glsni{percentchar} in the preamble:\newline
\mbox{}\newline
\glsni{usepackage}\marg{amsthm}\newline
\glsni{theoremstyle}\marg{plain}\newline
\glsni{newtheorem}\marg{theorem}\marg{Theorem}\newline
\mbox{}\newline
\glsni{theoremstyle}\marg{definition}\newline
\glsni{newtheorem}\marg{defn}\marg{Definition}\newline
\glsni{newtheorem}\marg{xmpl}\marg{Example}\oarg{chapter}\newline
\mbox{}\newline
\glsni{theoremstyle}\marg{remark}\newline
\glsni{newtheorem}\marg{remark}\marg{Remark}\newline
\mbox{}\newline
\glsni{percentchar} later in the document:\newline
\mbox{}\newline
\glsni{begin}\marg{defn}\oarg{Tautology}\glsni{label}\marg{def:tautology}\newline
A \gls{emph}\marg{tautology} is a proposition that is always true for any
value of its variables.\newline
\glsni{end}\marg{defn}\newline
\mbox{}\newline
\glsni{begin}\marg{defn}\oarg{Contradiction}\glsni{label}\marg{def:contradiction}\newline
A \glsni{emph}\marg{contradiction} is a proposition that is always false for any
value of its variables.\newline
\glsni{end}\marg{defn}\newline
\mbox{}\newline
\glsni{begin}\marg{theorem}\newline
If proposition \glsni{dollarchar}P\glsni{dollarchar} is a tautology 
then \glsni{dollarchar}\gls{sim} P\glsni{dollarchar} is a contradiction,
and conversely.\newline
\glsni{begin}\marg{proof}\newline
If \glsni{dollarchar}P\glsni{dollarchar} is a tautology, then all
elements of its truth table are true (by Definition\glsni{tildechar}\glsni{ref}\marg{def:tautology}), 
so all elements of the truth table for \glsni{dollarchar}\glsni{sim} P\glsni{dollarchar} 
are false, therefore \glsni{dollarchar}\glsni{sim} P\glsni{dollarchar} is a
contradiction (by Definition\glsni{tildechar}\glsni{ref}\marg{def:contradiction}).\newline
\glsni{end}\marg{proof}\newline
\glsni{end}\marg{theorem}\newline
\mbox{}\newline
\glsni{begin}\marg{xmpl}\glsni{label}\marg{ex:rain}\newline
\gls{quotedblleft}It is raining or it is not raining\gls{quotedblright} is a tautology,
but \glsni{quotedblleft}it is not raining and it is raining\glsni{quotedblright} is a
contradiction.\newline
\glsni{end}\marg{xmpl}\newline
\mbox{}\newline
\glsni{begin}\marg{remark}\newline
Example\gls{tildechar}\glsni{ref}\marg{ex:rain} used De Morgan\gls{quoteright}s Law
\glsni{dollarchar}\glsni{sim} (p \gls{vee} q) \gls{equiv} \glsni{sim} p \gls{wedge} \glsni{sim} q\glsni{dollarchar}.\newline
\glsni{end}\marg{remark}
\end{codelisting}
Result:
\begin{result}[amsthm.html]
\noindent\textbf{Definition \refstepcounter{defn}\thedefn\label{def:tautology}} (Tautology). A \emph{tautology} is a
proposition that is always true for any of its variables.
\par\vskip\baselineskip\noindent
\textbf{Definition \refstepcounter{defn}\thedefn\label{def:contradiction}} (Contradiction). A \emph{contradiction} is a
proposition that is always false for any value of its variables.
\par\vskip\baselineskip\noindent
\textbf{Theorem \refstepcounter{theorem}\thetheorem.} \emph{If proposition $P$ is a tautology then 
$\sim P$ is a contradiction, and conversely.}
\par\vskip\baselineskip
\noindent\emph{Proof.} If $P$ is a tautology, then all elements of
its true table are true (by Definition~\ref*{def:tautology}), so all elements of the
truth table for $\sim P$ are false, therefore $\sim P$ is a
contradiction (by
Definition~\ref*{def:contradiction}).\hfill$\openbox$\par
\vskip\baselineskip\noindent
\textbf{Example~\refstepcounter{Example}\theExample\label{ex:rain}.} ``It is raining or it is not raining'' is a
tautology, but ``it is not raining and it is raining'' is a
contradiction.
\par\vskip\baselineskip\noindent
\emph{Remark}~\refstepcounter{Remark}\theRemark. Example~\ref*{ex:rain} used De~Morgan's Law 
$\sim (p \vee q) \equiv \sim p \wedge \sim q$.
\end{result}

A new theorem style can be created using
\begin{definition}
\gls{newtheoremstyle}\marg{\meta{name}}\marg{\meta{space
above}}\marg{\meta{space below}}\marg{\meta{body
font}}\marg{\meta{indent}}\marg{\meta{head
font}}\marg{\meta{post head punctuation}}\marg{\meta{post head
space}}\marg{\meta{head spec}}
\end{definition}
This defines a~new theorem style called \meta{name}, which can later be set
using \booklinebreak\gls{theoremstyle}. The other arguments are as follows:
\begin{fwlist}{\meta{post head punctuation}}
\fwitem{\meta{space above}} the amount of space above the
theorem-like environment
\fwitem{\meta{space below}} the amount of space below the
theorem-like environment
\fwitem{\meta{body font}} the font to be used in the main theorem
body
\fwitem{\meta{indent}} the amount of indentation (empty means
no indent or use \nxgls{parindent} for normal paragraph
indentation)
\fwitem{\meta{head font}} the font to be used in the theorem
header
\fwitem{\meta{post head punctuation}} the punctuation to be inserted
after the theorem head
\fwitem{\meta{post head space}} the space to put
after the theorem head (use \texttt{\marg{\glsni{visiblespace}}} for a~normal interword space or
\gls{newline} for a~linebreak)
\fwitem{\meta{head spec}} the theorem head spec
\end{fwlist}

\xminisec{Example:}
This example creates a~new style called \texttt{note} that inserts a
space of 2ex above the theorem and 2ex below.\footnote{Recall the \Indextt{ex} unit from
\novices{length}.}  The body font is just
the normal font. There is no indent, the theorem header is in small
caps, a~full stop is put after the theorem head and a~line break is
inserted between the theorem head and body:
\begin{code}
\begin{alltt}
\glsni{newtheoremstyle}\marg{note}\glsni{percentchar} style name
\marg{2ex}\glsni{percentchar} above space
\marg{2ex}\glsni{percentchar} below space
\marg{}\glsni{percentchar} body font
\marg{}\glsni{percentchar} indent amount
\marg{\gls{scshape}}\glsni{percentchar} head font
\marg{.}\glsni{percentchar} post head punctuation
\marg{\glsni{newline}}\glsni{percentchar} post head punctuation
\marg{}\glsni{percentchar} head spec
\end{alltt}
\end{code}
Once you have defined the style, you can now use it. For example (in
the preamble):
\begin{code}
\begin{alltt}
\gls{theoremstyle}\marg{note}
\gls{newtheorem}\marg{scnote}\marg{Note}
\end{alltt}
\end{code}
This defines a~theorem-like environment called \envname{scnote}. You
can now use it later in the document:
\begin{code}
\begin{alltt}
\glsni{begin}\marg{scnote}
This is an example of a theorem-like environment.
\glsni{end}\marg{scnote}
\end{alltt}
\end{code}
This produces:
\begin{result}[The header is in small-caps followed by a number and a full stop. The body of the environment starts on the next line and is in the normal font.]
\vspace{2ex}
\noindent
\textsc{Note 1.}

\vspace{2ex}
\noindent
This is an example of a theorem-like environment.
\end{result}

\setnode{ntheorem}
\subsection{The \sty{ntheorem} Package}
\label{sec:ntheorem}

The \isty{ntheorem} package provides nine predefined theorem styles, listed 
in \tableref{tab:ntheoremstyles}. The 
default is \texttt{plain}. When you define a
new theorem-like environment with \booklinebreak\gls{newtheorem}, it is given
the style \emph{currently in effect}. You can change the
current style with:
\begin{definition}
\gls{theoremstyle}\marg{\meta{style name}}
\end{definition}
where \meta{style name} is the name of the theorem style.

\begin{table}[htbp]
\caption[Theorem Styles]{Predefined Theorem Styles Provided by \sty{ntheorem}}
\label{tab:ntheoremstyles}
\centering
\begin{tabular}{lp{0.7\linewidth}}
\texttt{plain} & Like the original \LaTeX\ style\\
\texttt{break} & Header is followed by a~line break\\
\texttt{change} & Like \texttt{plain} but header and number interchanged\\
\texttt{changebreak} & Combination of \texttt{change} and \texttt{break}\\
\texttt{margin} & Number is set in the margin\\
\texttt{marginbreak} & Like \texttt{margin} but header followed by
a~line break\\
\texttt{nonumberplain} & Like \texttt{plain} but without the number\\
\texttt{nonumberbreak} & Like \texttt{break} but without the number\\
\texttt{empty} & No number and no name. Only the optional argument
is used in the header.
\end{tabular}
\end{table}

In addition to these styles, you can also use
\begin{definition}
\gls{theoremheaderfont}\marg{\meta{declarations}}
\end{definition}
to set the header font to \meta{declarations}, which should consist
of font declaration commands such as \gls{normalfont},
\begin{definition}
\gls{theorembodyfont}\marg{\meta{declarations}}
\end{definition}
to set the body font to \meta{declarations}, and
\begin{definition}
\gls{theoremnumbering}\marg{\meta{style}}
\end{definition}
to set the appearance of the theorem number, where \meta{style} may be one
of: \texttt{arabic}, \texttt{roman}, \texttt{Roman}, \texttt{alph},
\texttt{Alph}, \texttt{greek}, \texttt{Greek} or \texttt{fnsymbol}.
Remember that the above commands all need to be used before the new
theorem-like environment is defined.
For additional commands that affect the style of the theorems, see the \isty{ntheorem}
documentation~\cite{ntheorem}.

\xminisec{Example:}
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\glsni{theoremstyle}\marg{marginbreak}
\glsni{theorembodyfont}\marg{\glsni{normalfont}}
\glsni{newtheorem}\marg{note}\marg{Note}\oarg{chapter}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{note}
This is a sample note. The number is in the margin.
\glsni{end}\marg{note}
\end{alltt}
\end{code}
Result\html{ (the vertical line in the image below indicates the boundary of the text
area and won't appear in the PDF)}:
\begin{result}
\begin{note}
This is a sample note. The number is in the margin.
\end{note}
\end{result}

If you use the \istyopt{ntheorem}{standard} package option to
\sty{ntheorem}, it will automatically define the following
environments: \envname{Theorem}, \envname{Lemma},
\envname{Proposition}, \envname{Corollary}, \envname{Satz},
\envname{Korollar}, \envname{Definition}, \envname{Example},
\envname{Beispiel}, \envname{Anmerkung}, \envname{Bemerkung},
\envname{Remark}, \gls*{env-Proof} and
\envname{Beweis}.

\warning Unlike \isty{amsthm}'s \gls{env-proof} environment,
\isty{ntheorem}'s \gls{env-Proof} environment appends its optional
argument in parentheses, if present, to the proof title. (Recall
from \htmlref{earlier}{amsthm-proof}\doifbook{
\vpageref{amsthm-proof}} that \isty{amsthm}'s \gls{env-proof}
environment uses its optional argument as a replacement for the
default proof title.)

\xminisec{Example:}

\begin{codelisting}{thesis-ntheorem.tex}
\null\par

\glsni{percentchar} in the preamble:\newline
\mbox{}\newline
\glsni{usepackage}\oarg{standard}\marg{ntheorem}\newline
\mbox{}\newline
\glsni{percentchar} later in the document:\newline
\mbox{}\newline
\glsni{begin}\marg{Definition}\oarg{Tautology}\glsni{label}\marg{def:tautology}\newline
A \gls{emph}\marg{tautology} is a~proposition that is always true for any
value of its variables.\newline
\glsni{end}\marg{Definition}\newline
\mbox{}\newline
\glsni{begin}\marg{Definition}\oarg{Contradiction}\glsni{label}\marg{def:contradiction}\newline
A \glsni{emph}\marg{contradiction} is a~proposition that is always false for any
value of its variables.\newline
\glsni{end}\marg{Definition}\newline
\mbox{}\newline
\glsni{begin}\marg{Theorem}\newline
If proposition \glsni{dollarchar}P\glsni{dollarchar} is a~tautology 
then \glsni{dollarchar}\gls{sim} P\glsni{dollarchar} is a~contradiction,
and conversely.\newline
\glsni{begin}\marg{Proof}\newline
If \glsni{dollarchar}P\glsni{dollarchar} is a~tautology, then all
elements of its truth table are true (by Definition\glsni{tildechar}\glsni{ref}\marg{def:tautology}), 
so all elements of the truth table for \glsni{dollarchar}\glsni{sim} P\glsni{dollarchar} 
are false, therefore \glsni{dollarchar}\glsni{sim} P\glsni{dollarchar} is a
contradiction (by Definition\glsni{tildechar}\glsni{ref}\marg{def:contradiction}).\newline
\glsni{end}\marg{Proof}\newline
\glsni{end}\marg{Theorem}\newline
\mbox{}\newline
\glsni{begin}\marg{Example}\glsni{label}\marg{ex:rain}\newline
\glsni{quotedblleft}It is raining or it is not raining\glsni{quotedblright} is a~tautology,
but \glsni{quotedblleft}it is not raining and it is raining\glsni{quotedblright} is a~contradiction.\newline
\glsni{end}\marg{Example}\newline
\mbox{}\newline
\glsni{begin}\marg{Remark}\newline
Example\gls{tildechar}\glsni{ref}\marg{ex:rain} used De
Morgan\glsni{quoteright}s Law
\glsni{dollarchar}\glsni{sim} (p \gls{vee} q) \gls{equiv} \glsni{sim} p \gls{wedge} \glsni{sim} q\glsni{dollarchar}.\newline
\glsni{end}\marg{Remark}\newline
\end{codelisting}
Result:
\begin{result}[ntheorem.html]
\begin{Definition}[Tautology]\label{nthm:def:tautology}
A \emph{tautology} is a~proposition that is always true for any
value of its variables.
\end{Definition}

\begin{Definition}[Contradiction]\label{nthm:def:contradiction}
A \emph{contradiction} is a~proposition that is always false for any
value of its variables.
\end{Definition}

\begin{Theorem}
If proposition $P$ is a~tautology 
then $\sim P$ is a~contradiction,
and conversely.
\begin{Proof}
If $P$ is a tautology, then all elements of its truth table are
true (by Definition~\ref{nthm:def:tautology}), so all elements of the
truth table for $\sim P$ are false,
therefore $\sim P$ is a contradiction (by
Definition~\ref{nthm:def:contradiction}).
\end{Proof}
\end{Theorem}

\begin{Example}\label{ex:rain2}
``It is raining or it is not raining'' is a~tautology,
but ``it is not raining and it is raining'' is a~contradiction.
\end{Example}

\begin{Remark}
Example~\ref*{ex:rain2} used De Morgan's Law
$\sim (p \vee q) \equiv \sim p \wedge \sim q$.
\end{Remark}

\end{result}

\setnode{algorithms}
\section{Algorithms}
\label{sec:algorithms}

If you want to display an algorithm, such as pseudo-code, you can
use a~combination of the \gls{env-tabbing} environment (described in
\sectionref{sec:tabbing}) and a~theorem-like environment (described
above in \sectionref{sec:newtheorem}). 

\xminisec{Example:}
\begin{code}
\begin{alltt}
\glsni{percentchar} in the preamble:
\gls{theoremstyle}\marg{break}
\gls{theorembodyfont}\marg{\glsni{normalfont}}
\gls{newtheorem}\marg{algorithm}\marg{Algorithm}

\glsni{percentchar} later in the document:
\glsni{begin}\marg{algorithm}\oarg{Gauss-Seidel Algorithm}
\glsni{begin}\marg{tabbing}
1. \gls{tabstop}For \glsni{dollarchar}k=1\glsni{dollarchar} to maximum number of iterations\gls{dbbackslashchar}
\gls{greaterthan}2. For \glsni{tabstop}\glsni{dollarchar}i=1\glsni{dollarchar} to \glsni{dollarchar}n\glsni{dollarchar}\glsni{dbbackslashchar}
\glsni{greaterthan}\glsni{greaterthan}Set 
\glsni{begin}\marg{math}
x\gls{underscorechar}i\gls{circumchar}\marg{(k)} = 
\gls{frac}\marg{b\glsni{underscorechar}i-\gls{sum}\glsni{underscorechar}\marg{j=1}\glsni{circumchar}\marg{i-1}a\glsni{underscorechar}\marg{ij}x\glsni{underscorechar}j\glsni{circumchar}\marg{(k)}
         -\glsni{sum}\glsni{underscorechar}\marg{j=i+1}\glsni{circumchar}\marg{n}a\glsni{underscorechar}\marg{ij}x\glsni{underscorechar}j\glsni{circumchar}\marg{(k-1)}}\glsni{percentchar}
     \marg{a\glsni{underscorechar}\marg{ii}}
\glsni{end}\marg{math}
\glsni{dbbackslashchar}
\glsni{greaterthan}3. If \glsni{dollarchar}\gls{lvert}\gls{vec}\marg{x}\glsni{circumchar}\marg{(k)}-\glsni{vec}\marg{x}\glsni{circumchar}\marg{(k-1)}\gls{rvert} < \gls{epsilon}\glsni{dollarchar}, 
where \glsni{dollarchar}\glsni{epsilon}\glsni{dollarchar} is a specified stopping criteria, stop.
\glsni{end}\marg{tabbing}
\glsni{end}\marg{algorithm}
\end{alltt}
\end{code}
Result:
\begin{result}
\begin{algorithm}[Gauss-Seidel Algorithm]
\begin{tabbing}
1. \=For $k=1$ to maximum number of iterations\\
\>2. For \=$i=1$ to $n$\\
\>\>Set
\begin{math}
x_i^{(k)} =
\frac{b_i-\sum_{j=1}^{i-1}a_{ij}x_j^{(k)}
-\sum_{j=i+1}^{n}a_{ij}x_j^{(k-1)}}%
{a_{ii}}
\end{math}
\\
\>3. If $\lvert\vec{x}^{(k)}-\vec{x}^{(k-1)}\rvert < \epsilon$,
where $\epsilon$ is a specified stopping criteria, stop.
\end{tabbing}
\end{algorithm}
\end{result}
(See \novices[sec:vec]{vectors} to find out how to redefine 
\glsni{vec} to display its argument in bold.)

If you want a~more sophisticated approach, there are some packages
available on \gls{ctan}, such as \isty{alg}, \isty{algorithm2e},
\isty{algorithms} and \isty{algorithmicx}. I'm going to briefly
introduce the \sty{algorithm2e} package here. This provides the
\gls{env-algorithm} floating environment. Like the 
\gls{env-figure} and \gls{env-table} environments described in 
\novices[ch:floats]{floats}, the \glsni{env-algorithm} environment has an optional argument that
specifies the placement.
\begin{definition}
\glsni{begin}\marg{algorithm}\oarg{\meta{placement}}
\end{definition}
If you are using a~class or package that already defines an
\envname{algorithm} environment, you can use the
\istyopt{algorithm2e}{algo2e} package option:
\begin{codeS}
\glsni{usepackage}\oarg{algo2e}\marg{algorithm2e}
\end{codeS}
This will define an environment called \gls{env-algorithm2e} instead
of \glsni{env-algorithm} to avoid conflict.

Within the body of the environment, you must mark the end of each
line with \gls{algo2e.semicolon} regardless of whether you want a
semi-colon to appear. To suppress the default end-of-line
semi-colon, use
\begin{definition}
\gls{DontPrintSemicolon}
\end{definition}
To switch it back on again, use
\begin{definition}
\gls{PrintSemicolon}
\end{definition}
There are a~variety of commands that may be used within the 
\glsni{env-algorithm} environment. Some of the commands are
described below, but for a~complete list you should consult the
\sty{algorithm2e} documentation~\cite{algorithm2e}.\bookpagebreak

First there are the commands for the algorithm input, output and
data:
\begin{definition}
\gls{KwIn}\marg{\meta{input}}\newline
\gls{KwOut}\marg{\meta{output}}\newline
\gls{KwData}\marg{\meta{input}}\newline
\gls{KwResult}\marg{\meta{output}}
\end{definition}
Next there are commands for basic keywords:
\begin{definition}
\gls{KwTo}\newline
\gls{KwRet}\marg{\meta{value}}\newline
\gls{Return}\marg{\meta{value}}
\end{definition}
There are a~lot of conditionals, but here's a~selection:
\begin{definition}
\gls{If}\marg{\meta{condition}}\marg{\meta{then block}}\newline
\gls{uIf}\marg{\meta{condition}}\marg{\meta{then block without end}}\newline
\gls{ElseIf}\marg{\meta{else-if block}}\newline
\gls{uElseIf}\marg{\meta{else-if block without end}}\newline
\gls{Else}\marg{\meta{else block}}
\end{definition}
Similarly there are a~lot of loops, but here's a~selection:
\begin{definition}
\gls{For}\marg{\meta{condition}}\marg{\meta{body}}\newline
\gls{While}\marg{\meta{condition}}\marg{\meta{body}}
\end{definition}

\xminisec{Example:}

The above algorithm can be written using the \gls{env-algorithm2e}
environment as follows (this document has used the
\istyopt{algorithm2e}{algo2e} package option):
\begin{codelisting}{thesis-algorithms.tex}
\begin{alltt}
\glsni{begin}\marg{algorithm2e}
\gls{caption}\marg{Gauss-Seidel Algorithm}\gls{label}\marg{alg:gauss-seidel}
\glsni{KwIn}
\marg{\glsni{percentchar}
 scalar \glsni{dollarchar}\glsni{epsilon}\glsni{dollarchar},
 matrix \glsni{dollarchar}\gls{mathbf}\marg{A} = (a\glsni{underscorechar}\marg{ij})\glsni{dollarchar}, 
 vector \glsni{dollarchar}\gls{vec}\marg{b}\glsni{dollarchar}
 and initial vector \glsni{dollarchar}\glsni{vec}\marg{x}\gls{circumchar}\marg{(0)}\glsni{dollarchar}
}
\glsni{For}\marg{\glsni{dollarchar}k\gls{leftarrow} 1\glsni{dollarchar} \glsni{KwTo} maximum iterations}
\marg{
   \glsni{For}\marg{\glsni{dollarchar}i\glsni{leftarrow} 1\glsni{dollarchar} \glsni{KwTo} \glsni{dollarchar}n\glsni{dollarchar}}
   \marg{
      \glsni{dollarchar}
      x\glsni{underscorechar}i\glsni{circumchar}\marg{(k)} =
      \glsni{frac}
      \marg{
        b\glsni{underscorechar}i-\glsni{sum}\glsni{underscorechar}\marg{j=1}\glsni{circumchar}\marg{i-1}a\glsni{underscorechar}\marg{ij}x\glsni{underscorechar}j\glsni{circumchar}\marg{(k)}
        -\glsni{sum}\glsni{underscorechar}\marg{j=i+1}\glsni{circumchar}\marg{n}a\glsni{underscorechar}\marg{ij}x\glsni{underscorechar}j\glsni{circumchar}\marg{(k-1)}
      }\glsni{percentchar}
      \marg{a\glsni{underscorechar}\marg{ii}}
      \glsni{dollarchar}\glsni{algo2e.semicolon}
   }
   \glsni{If}\marg{\glsni{dollarchar}\glsni{lvert}\glsni{vec}\marg{x}\glsni{circumchar}\marg{(k)}-\glsni{vec}\marg{x}\glsni{circumchar}\marg{(k-1)}\glsni{rvert} < \glsni{epsilon}\glsni{dollarchar}}
   \marg{Stop}
}
\glsni{end}\marg{algorithm2e}
\end{alltt}
\end{codelisting}
The result is shown in Algorithm~\ref{alg:gauss-seidel}.

\begin{algorithm2e}
\caption{Gauss-Seidel Algorithm}\label{alg:gauss-seidel}
\KwIn
{%
 Scalar $\epsilon$,
 matrix $\mathbf{A}=(a_{ij})$,
 vector $\vec{b}$
 and initial vector $\vec{x}^{(0)}$
}
\For{$k\leftarrow 1$ \KwTo maximum iterations}
{
   \For{$i\leftarrow 1$ \KwTo $n$}
   {
     $
      x_i^{(k)} =
      \frac{b_i-\sum_{j=1}^{i-1}a_{ij}x_j^{(k)}
      -\sum_{j=i+1}^{n}a_{ij}x_j^{(k-1)}}%
      {a_{ii}}
      $\;
   }
   \If{$\lvert\vec{x}^{(k)}-\vec{x}^{(k-1)}\rvert < \epsilon$}{Stop}
}
\end{algorithm2e}

The \gls{env-algorithm} environment (as defined by \sty{algorithm2e} 
without the \istyopt{algorithm2e}{algo2e} option) or \gls{env-algorithm2e}
environment (as defined with the \optfmt{algo2e} option)
uses the \icounter{algocf} counter.  So in this document, to ensure
that the \envname{algorithm} environment defined with
\gls{newtheorem} used the same counter as \gls{env-algorithm2e},
I~had the following in my preamble:
\begin{code}
\begin{alltt}
\glsni{usepackage}\marg{ntheorem}
\glsni{usepackage}\oarg{algo2e}\marg{algorithm2e}

\glsni{theoremstyle}\marg{break}
\glsni{theorembodyfont}\marg{\glsni{normalfont}}
\glsni{newtheorem}\marg{algorithm}\oarg{algocf}\marg{Algorithm}
\end{alltt}
\end{code}

\setnode{siunitx}
\section{Formatting SI Units}
\label{sec:siunitx}

If you need to typeset numbers and units then I~strongly recommend
that you use the \isty{siunitx} package. This section just provides
a~brief introduction to that package. You will need to read the
\sty{siunitx} package documentation~\cite{siunitx} if you want
further details.

\begin{definition}
\gls{num}\marg{\meta{number}}
\end{definition}
This command typesets \meta{number}, adding appropriate spacing between
number groups where necessary. It also adds a~leading zero if
omitted before the decimal point and identifies exponents. Note that
the command recognises both \dq{\texttt{.}} and \dq{\texttt{,}} as the
decimal marker. If you want one of these characters between number
groups (instead of the default space) you can change the settings,
but it's best to stick to the default settings unless instructed to
do otherwise.

\xminisec{Example:}

\begin{code}
Out of \glsni{num}\marg{12890} experiments, \glsni{num}\marg{1289} of them had a mean
squared error of \glsni{num}\marg{.346} and \glsni{num}\marg{128} of them had a mean squared
error of \glsni{num}\marg{1.23e-6}.
\end{code}\reportpagebreak\noindent
Result:
\begin{result}[sinum.html]
Out of \num{12890} experiments, \num{1289} of them had a mean
squared error of \num{.346} and \num{128} of them had a mean squared
error of \num{1.23e-6}.
\end{result}

\begin{definition}
\gls{ang}\marg{\meta{angle}}
\end{definition}
This command typesets an angle. The argument \meta{angle} may be a
single number or three (some possibly empty) values separated by
semi-colons.

\xminisec{Example:}
\begin{codeS}
The result formed an arc from \glsni{ang}\marg{45} to \glsni{ang}\marg{60;2;3}.
\end{codeS}
Result:
\begin{resultS}[siang.html]
The result formed an arc from \ang{45} to \ang{60;2;3}.
\end{resultS}

\begin{definition}
\gls{si}\marg{\meta{unit}}
\end{definition}
This command typesets a~unit. The \meta{unit} can be formed from
commands like \gls{metre}, \gls{gram}, \gls{second} or \gls{kilo}.
(See the \sty{siunitx} documentation~\cite{siunitx} for the full
list.)\bookpagebreak

\xminisec{Example:}
\begin{code}
The distance was measured in \glsni{si}\marg{\glsni{kilo}\glsni{metre}} and the
area in \glsni{si}\marg{\glsni{kilo}\glsni{metre}\gls{squared}}.
The acceleration was given in \glsni{si}\marg{\glsni{metre}\gls{per}\gls{square}\glsni{second}}.
\end{code}\screenpagebreak
Result:
\begin{result}[siunit.html]
The distance was measured in \si{\kilo\metre} and the
area in \si{\kilo\metre\squared}.
The acceleration was given in \si{\metre\per\square\second}.
\end{result}

\begin{definition}
\gls{SI}\marg{\meta{number}}\marg{\meta{unit}}
\end{definition}
This combines the functionality of \glsni{num} and \glsni{si} so
that you can typeset both a~number and a~unit.

\xminisec{Example:}
\begin{code}
The acceleration was approximately \glsni{SI}\marg{9.78}\marg{\glsni{metre}\glsni{per}\glsni{square}\glsni{second}}.
\end{code}
Result:
\begin{resultS}[sinumunit.html]
The acceleration was approximately \SI{9.78}{\metre\per\square\second}.
\end{resultS}

% Generating a~Bibliography

\setnode{citations}
\chapter{Generating a~Bibliography}
\label{ch:citations}

\novices[sec:bib]{biblio} introduced the 
\gls{env-thebibliography} environment. While it is 
possible to write this environment yourself, as was done in
Volume~1, it's not practical with a~large number of citations.

Instead, the preferred method is to create an external database
of bibliographic data and use an application that fetches the relevant
information from that database and writes a~file containing
the \glsni{env-thebibliography} environment, which can then be input
into your document. This means that:
\begin{enumerate}
\item Only the references that you cite are included in the
bibliography.  (Examiners tend to fault uncited references\footnote{%
When your examiners read through your thesis, they can check off each
citation they encounter against your bibliography. When they reached
the end of the thesis, they can then look through the bibliography
for unchecked entries. One or two may appear the result of 
carelessness, whereas a~large quantity will look like padding and
may lead the examiners to suspect a~certain amount of duplicity
on your part.}.)

\item References are displayed in a~consistent manner.

\item Entries can be sorted in order of citation or alphabetically.

\end{enumerate}
Traditionally the \iappnamelink{bibtex}{http://www.bibtex.org/} application 
is used to generate the \glsni{env-thebibliography} environment. It
comes with \TeX\ distributions and most books on \LaTeX\ cover
\appname{bibtex}.  Unfortunately \appname{bibtex} has some
drawbacks, most notably the complexity of creating your own custom
style. UTF-8 has also been a~problem, although newer versions of
\appname{bibtex} apparently fix this.

In 2006, Philipp Lehman brought out the \isty{biblatex} package to
provide a~more flexible way of typesetting bibliographies. This
originally used \appname{bibtex} to just sort the entries and used \LaTeX\ macros to deal
with the actual formatting, but it is now moving over to using
\iappnamelink{biber}{http://biblatex-biber.sourceforge.net/} instead
of \appname{bibtex}.

Since some journals, conferences or other types of scientific
publishers require you to use \appname{bibtex},
\sectionref{sec:bibtex} provides a~brief introduction to
\appname{bibtex} and then \sectionref{sec:biblatex} discusses
\sty{biblatex} and \appname{biber}. But first
\sectionref{sec:creatingbibfile} covers creating the actual
database, which is required for both methods.

\setnode{creatingbibfile}
\section{Creating a~Bibliography Database}
\label{sec:creatingbibfile}

This section covers creating a~\texttt{.bib} file that contains the
bibliographic information you want to cite in your documents.
You can use an ordinary text editor to create a~bibliographic
database (as described in \sectionref{sec:bibformat}) but it can be
difficult to remember the names of the required fields and it's easy
to make syntactic mistakes. It can also be hard to keep track of
entries in a~large database. To make life easier, there are a~number
of bibliography reference managers available that provide a
convenient graphical interface. One such application is
\appname{JabRef} and is described \htmlref{next}{sec:jabref}.

\setnode{jabref}
\subsection{JabRef}
\label{sec:jabref}

I've chosen to describe \iappname{JabRef} here because it's an open
source Java application that can run on any operating system that
has the \htmladdnormallinkfoot{Java Runtime
Environment}{http://www.java.com/getjava/} installed (at least
version 1.5). You can download \appname{JabRef} from
\url{http://jabref.sourceforge.net/download.php}. Linux users may
also be able to install it via their \dq{Add/Remove Software} tool.
(If you have successfully been using
\htmlref{\appname{arara}}{sec:arara}, you already have Java
installed.)

Once you have installed it, run \appname{JabRef} and select
\menu{File}\menuto\menu{New database} to create a~new database
(see \figureref{fig:jabref1}). When you save your data, it's saved as a
BibTeX (\texttt{.bib}) file.

Note that if you use the \isty{inputenc} package in 
your thesis (see \novices{inputenc}) you'll have to make sure
\appname{JabRef} is using the same encoding as your document. You
can do this by selecting \menu{Options}\menuto\menu{Preferences} to
open the Preferences dialog box and set the default encoding as
appropriate. For example, I~use UTF-8 so I've set that as the default
encoding (see \figureref{fig:jabref-pref}). I~also need to change
the database encoding in the \dq{Database properties} dialog, 
\figureref{fig:jabref-dataprop}, which
can be opened using \menu{File}\menuto\menu{Database properties}.

\begin{figure}[htbp]
\figconts
 {pictures/jabref1}
 {\caption{JabRef}}
 {fig:jabref1}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/jabref-pref}
 {\caption{JabRef Preferences}}
 {fig:jabref-pref}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/jabref-dataprop}
 {\caption{JabRef Database Properties}}
 {fig:jabref-dataprop}
\end{figure}

To create a~new entry you can select \menu{BibTeX}\menuto\menu{New
entry}, which will open the dialog box shown in
\figureref{fig:jabref2}. Now you need to click on the button
appropriate to the entry. For example, click on \dq{Article} for an
article in a~journal or click on \dq{Inproceedings} for a~paper
in a~conference proceedings. 

\xminisec{Example (Book):}

Suppose I~want to enter information about a
book. I~need to select \menu{BibTeX}\menuto\menu{New entry} and then click on the button labelled \dq{Book}. This now displays fields in
which I~can enter the relevant information (see \figureref{fig:jabref3}).

\begin{figure}[htbp]
\figconts
 {pictures/jabref2}
 {\caption{JabRef (Select Entry Type)}}
 {fig:jabref2}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/jabref3}
 {\caption{JabRef (New Entry)}}
 {fig:jabref3}
\end{figure}

Next I~need to enter information in the \dq{Required fields} tab. This will
usually include the title and the author. I~also need to specify a
key that uniquely identifies this entry. If you have read 
\novices[sec:bib]{biblio} this key corresponds to the mandatory argument 
of \gls{bibitem} and is also used in \glsi{cite}.
\figureref{fig:jabref4} shows the details for my new entry. I've set
the key to the author's surname followed by the year to make it easy
to remember. This key won't appear anywhere in the document, it's
just used to identify the entry, just like the \gls{label}/\gls{ref}
mechanism. Alternatively, I~can click on the \dq{Generate BibTeX
Key} button \incGraphics{pictures/generatekey} to automatically
insert a~unique key.

\begin{figure}[htbp]
\figconts
 {pictures/jabref4}
 {\caption{JabRef (Entering the Required Fields)}}
 {fig:jabref4}
\end{figure}

There are also optional fields you can specify as well. In
\figureref{fig:jabref5}, I've added the book's edition.

\begin{figure}[htbp]
\figconts
 {pictures/jabref5}
 {\caption{JabRef (Entering Optional Fields)}}
 {fig:jabref5}
\end{figure}

\xminisec{Example (Journal Article):}

Now I~want to enter an article in a~journal. So I~need to go back
to \menu{BibTeX}\menuto\menu{New entry} and click on \dq{Article}.
This time I've used the \dq{Generate BibTeX Key} button to generate
the key to save me typing. (See \figureref{fig:jabref6}.) I've also
used the \dq{General} tab to enter the DOI for this article. The
entry now has an icon \incGraphics{pictures/doibutton} next to it. I~can
click on this button to direct my web browser to the article's entry
on the Internet.

\begin{figure}[htbp]
\figconts
 {pictures/jabref6}
 {\caption{JabRef (Adding an Article)}}
 {fig:jabref6}
\end{figure}

BibTeX uses the European assumption\faq{\BiBTeX\ sorting and name
prefixes}{bibprefixsort} that names are composed of
forenames, an optional \dq{von} part which starts with a~lower case
letter, a~surname and an optional \dq{jr} part. In order to enable
BibTeX to correctly identify these components, names in the author
or editor fields must be entered in one of the formats listed in
\tableref{tab:bibnameformats}.

\begin{table}[htbp]
\caption{Name Formats for Bibliographic Data}
\label{tab:bibnameformats}
\centering
\begin{tabular}{l}
\meta{forenames} \meta{von} \meta{surname}\\
\meta{von} \meta{surname}, \meta{forenames}\\
\meta{von} \meta{surname}, \meta{jr}, \meta{forenames}
\end{tabular}
\end{table}

\bookpagebreak
\xminisec{Examples:}

\begin{center}
\begin{tabular}{ll}
\toprule
\bfseries Entry & \bfseries Abbreviated as\\
\midrule
\ttfamily Alex Thomas von Neumann & A.T. von Neumann\\
\ttfamily John Chris \{Smith Jones\} & J.C. Smith Jones\\
\ttfamily van de Klee, Mary-Jane & M.-J. van de Klee\\
\ttfamily Smith, Jr, Fred John & F.J. Smith, Jr\\
\ttfamily \verb|Maria {\MakeUppercase{d}e La} Cruz| & M. De La Cruz\\
\bottomrule
\end{tabular}
\end{center}

Compare the last example with: \texttt{Maria De La Cruz} which would
be abbreviated to: M.~D.~L.~Cruz, which is incorrect. Let's analyse
this last example in more detail: BibTeX always expects the \dq{von}
part to start with a~lower case letter, but \dq{De} and \dq{La} both
start with an upper case letter, so BibTeX will assume that these
form part of the forenames. However, BibTeX will ignore any \LaTeX\
commands such as \faq{Case-changing
oddities}{casechange}\gls{MakeUppercase} in
\verb|\MakeUppercase{d}e| since it assumes that the command is an
accent command\faq{Accents in bibliographies}{bibaccent}. So when it
parses \verb|\MakeUppercase{d}e| it will skip \glsni{MakeUppercase}
and look at the following letter. In this case it is \dq{d} which is
lower case, so from BibTeX's point of view the word
\verb|\MakeUppercase{d}e| starts with a~lower case letter (\dq{d}),
so it is therefore the \dq{von} part. You can either do the same
with the \dq{La} part, or, as in the above example, you can place it
in the same group as \verb|\MakeUppercase{d}e|.

Multiple authors should be separated by the keyword
\dq{and}. \textbf{Don't use a~comma to separate the authors.}  
Here is an example with three authors:
\begin{codeS}
Gavin C. Cawley and Nicola L. C. Talbot and Mark Girolami
\end{codeS}
If the author is an institution or company that
happens to have the word \dq{and} in its name, such as \dq{Smith and
Jones Inc}, then you need to group the \dq{and} to indicate that you
mean the word \dq{and} rather than the keyword:
\begin{codeS}
Smith \marg{and} Jones Inc
\end{codeS}

\figureref{fig:jabref7} shows the entry for a~paper in a~conference
proceedings, so for that one I~used \menu{BibTeX}\menuto\menu{New
entry} and clicked on the \dq{Inproceedings} button.

\begin{figure}[htbp]
\figconts
 {pictures/jabref7}
 {\caption{JabRef (Adding a~Conference Paper)}}
 {fig:jabref7}
\end{figure}

Notice the way I've written the title for this entry:
\begin{code}
Sparse multinomial logistic regression via \marg{Bayesian} \marg{L1}
regularisation
\end{code}
BibTeX automatically converts the title to lower case (apart from
the initial letter) but here both \dq{Bayesian} and \dq{L1} should
begin with a~capital. I~therefore need to enclose those words in
braces to instruct BibTeX not to convert their case.

Multiple editors must also be separated by the \dq{and} keyword, as
shown in \figureref{fig:jabref8}. For that entry, the editors are
listed as:
\begin{codeS}
Bernhard Sch\"{o}lkopf and John Platt and Thomas Hofmann
\end{codeS}
Note that if I~don't use the \isty{inputenc} package, I~need to
change this to:
\begin{codeS}
Bernhard Sch\gls{doublequote}\marg{o}lkopf and John Platt and Thomas Hofmann
\end{codeS}

\begin{figure}[htbp]
\figconts
 {pictures/jabref8}
 {\caption{JabRef (Adding Editor List)}}
 {fig:jabref8}
\end{figure}

It's also possible to import entries from other formats, such as
Copac or ISI, using \menu{File}\menuto\menu{Import into new database} or
\menu{file}\menuto\menu{Import into current database}.
Alternatively, you can copy and paste a~plain text reference using
\menu{BibTeX}\menuto\menu{New entry from plain text}. This again
opens the dialog box where you need to click on the entry type, but
then it opens the \dq{Plain text import} window. 

\xminisec{Example:}

Suppose I~want to add an entry for an article whose DOI
is 10.1007/s10994-008-5055-9. First, I~direct my browser to
\htmladdnormallink{\texttt{http://dx.doi.org/10.1007/\reportlinebreak\screenlinebreak s10994-008-5055-9}}{http://dx.doi.org/10.1007/s10994-008-5055-9}, which takes me to
the article's web page. In this case, it's in a~journal published by
Springer, so my browser is redirected to the SpringerLink cite.
There I~can use the export as text only option, then copy and paste
the reference into \appname{JabRef}'s import window, as shown in 
\figureref{fig:jabref-textimport1}.

\begin{figure}[htbp]
\figconts
 {pictures/jabref-textimport1}
 {\caption{Importing a~Plain Text Reference}}
 {fig:jabref-textimport1}
\end{figure}

Next, I~need to select text, for example an author's name, and select the
appropriate field in the \dq{Work options} list. Then click on the
\dq{Insert} button. For example, in
\figureref{fig:jabref-textimport2} I~have selected an author's name
then I~selected the \dq{author} field in the \dq{Work options} list.

\begin{figure}[htbp]
\figconts
 {pictures/jabref-textimport2}
 {\caption{Importing a~Plain Text Reference (Selecting a~Field)}}
 {fig:jabref-textimport2}
\end{figure}

Next I~clicked on the \dq{Insert} button. Now the author's name is
highlighted in red and the author field has a~tick next to it (see
\figureref{fig:jabref-textimport3}). I~can repeat this process for
the next author. (Just make sure the \dq{Append} rather than
\dq{Override} radio button is selected.)

\begin{figure}[htbp]
\figconts
 {pictures/jabref-textimport3}
 {\caption{Importing a~Plain Text Reference (Field Selected)}}
 {fig:jabref-textimport3}
\end{figure}

I~can repeat this for all the different fields. Each time, I~select
the text in the raw source panel, then select the appropriate field from
the \dq{Work options} list and then click \dq{Insert}. Once I~have
finished, I~then need to click \dq{Accept}.

\setnode{bibformat}
\subsection{Writing the .bib File Manually}
\label{sec:bibformat}

It may be that you don't want to or can't use a~bibliography
management application, such as
\htmlref{\appname{JabRef}}{sec:jabref}. In which case,
you can create the \texttt{.bib} file in an ordinary text editor,
such as the one you use to write your \LaTeX\ documents.
When you save the file, make sure you give it the extension
\texttt{.bib}.  Entries in this file should have the following 
form\faq{Creating a~BibTeX bibliography}{buildbib}:

\vbox{\begin{ttfamily}
\begin{tabbing}
xxx\=\kill
@\meta{entry type}\{\meta{keyword},\\
   \>\meta{field name} \== "\meta{text}",\\
   \>\>   \vellipsis\\
   \>\meta{field name} = "\meta{text}"\\
\}
\end{tabbing}
\end{ttfamily}}
\noindent where \meta{entry type} indicates the type of entry (e.g.\ book or article).
Standard entry types are listed in \tableref{tab:entrytype}.

\begin{table}[htbp]
\caption{Standard BiBTeX entry types}
\label{tab:entrytype}
\centering
\begin{tabular}{ll}
\toprule
\bfseries Entry Name & \bfseries Description\\
\midrule
\ibibentry{article} & Article from a~journal\\
\ibibentry{book} & Published book\\
\ibibentry{booklet} & Printed work without a~publisher\\
\ibibentry{conference} & Identical to \ibibentry{inproceedings}\\
\ibibentry{inbook} & Part, chapter, section etc of a~book\\
\ibibentry{incollection} & A chapter of a~book with its own author and title\\
\ibibentry{inproceedings} & An article in a~conference proceedings\\
\ibibentry{manual} & Technical documentation\\
\ibibentry{mastersthesis} & A master's thesis\\
\ibibentry{misc} & Non-standard work\\
\ibibentry{phdthesis} & PhD thesis\\
\ibibentry{proceedings} & Conference proceedings\\
\ibibentry{techreport} & Report published by an institution\\
\ibibentry{unpublished} & Unpublished work with an author and
title\\
\bottomrule
\end{tabular}
\end{table}

Within an entry, \meta{keyword} is a~short label that is used to cite
this work with the \glsi{cite} command. If you have written
bibliographies with the \gls{env-thebibliography}
environment, it's the same as the
argument to \gls{bibitem}.  There then follows a~comma-separated
list of fields of the form \meta{field name} \texttt{=} \meta{value}.
The \meta{field name} indicates what kind of field it is, e.g.\
\ibibfield{title} or \ibibfield{author}.  \tableref{tab:fields} lists
the standard fields.  Note that some bibliography styles may define
additional non-standard fields, such as \texttt{email} or 
\texttt{url}.\faq{URLS in BibTeX bibliographies}{citeURL}
See the Bib\TeX\ documentation~\cite{bibtex} for information about other fields not
listed in \tableref{tab:fields}.

\begin{table}[hbtp]
\caption{Standard BiBTeX fields}
\label{tab:fields}
\centering\latex{\ifscreen\small\fi}
\begin{tabular}{ll}
\ibibfield{address} & Publisher/Institution's address\\
\ibibfield{author} & Author names\\
\ibibfield{booktitle} & Title of book where only a~part of the book is being cited\\
\ibibfield{chapter} & Chapter or section number\\
\ibibfield{edition} & The edition of the book\\
\ibibfield{howpublished} & How a~non-standard work was published\\
\ibibfield{institution} & The institute sponsoring the work\\
\ibibfield{journal} & The name of the journal\\
\ibibfield{month} & The month the work was published\\
\ibibfield{note} & Any additional information\\
\ibibfield{number} & The number of the journal, technical report etc\\
\ibibfield{organization} & Organization sponsoring conference or manual\\
\ibibfield{pages} & Page number or page range\\
\ibibfield{publisher} & Publisher's name\\
\ibibfield{school} & Academic institution where thesis was written\\
\ibibfield{series} & Name of a~series\\
\ibibfield{title} & The title of the work\\
\ibibfield{type} & The type of technical report\\
\ibibfield{volume} & The volume number.
\end{tabular}
\end{table}

The required and optional fields for the standard entry types are
listed in \tableref{tab:reqopt}.  If an entry has a~field that is
neither required nor optional, BibTeX will ignore it.  This means
that you can have a~field called, say, \ibibfield{abstract}, which will
be ignored by the standard bibliography styles, but will be included if
you use a~bibliography style that has an \ibibfield{abstract} field.
So you can store additional information in the database that won't
appear in the bibliography.

\begin{fieldtab}
\ibibentry{article} & 
\ibibfield{author}, \ibibfield{title}, \ibibfield{journal}, \ibibfield{year} & 
\ibibfield{volume}, \ibibfield{month}, \ibibfield{note},
\ibibfield{number}, \ibibfield{pages} \tabularnewline
\ibibentry{book} & 
\ibibfield{author} or \ibibfield{editor}, \ibibfield{title}, \ibibfield{publisher}, \ibibfield{year} & 
\ibibfield{address}, \ibibfield{edition}, \ibibfield{volume} or
\ibibfield{number}, \ibibfield{month}, \ibibfield{note},
\ibibfield{pages}, \ibibfield{series} \tabularnewline
\ibibentry{booklet} & \ibibfield{title} &
\ibibfield{author}, \ibibfield{address}, \ibibfield{howpublished},
\ibibfield{month}, \ibibfield{note}, \ibibfield{year}
\tabularnewline
\ibibentry{inbook} & 
\ibibfield{author} or \ibibfield{editor}, \ibibfield{chapter} or \ibibfield{pages}, \ibibfield{title}, \ibibfield{publisher}, 
\ibibfield{year} & 
\ibibfield{address}, \ibibfield{edition}, \ibibfield{volume} or \ibibfield{number}, \ibibfield{month}, \ibibfield{note}, 
\ibibfield{series}, \ibibfield{type} \tabularnewline
\ibibentry{incollection} & 
\ibibfield{author}, \ibibfield{title}, \ibibfield{booktitle}, \ibibfield{publisher}, \ibibfield{year} & 
\ibibfield{address}, \ibibfield{chapter}, \ibibfield{editor}, \ibibfield{edition}, \ibibfield{volume} or \ibibfield{number}, 
\ibibfield{month}, \ibibfield{note}, \ibibfield{pages},
\ibibfield{series}, \ibibfield{type} \tabularnewline
\ibibentry{inproceedings} & 
\ibibfield{author}, \ibibfield{title}, \ibibfield{booktitle}, \ibibfield{year} & 
\ibibfield{address}, \ibibfield{editor}, \ibibfield{volume} or \ibibfield{number}, \ibibfield{month}, \ibibfield{note}, 
\ibibfield{organization}, \ibibfield{pages}, \ibibfield{publisher},
\ibibfield{series}, \ibibfield{type} \tabularnewline
\ibibentry{manual} & \ibibfield{title} & 
\ibibfield{author}, \ibibfield{address}, \ibibfield{edition}, \ibibfield{month}, \ibibfield{note}, \ibibfield{organization}, 
\ibibfield{year}\tabularnewline
\ibibentry{mastersthesis} & \ibibfield{author}, \ibibfield{title}, \ibibfield{school}, \ibibfield{year} & 
\ibibfield{address}, \ibibfield{month}, \ibibfield{note},
\ibibfield{type}\tabularnewline
\ibibentry{misc} & --- & 
\ibibfield{author}, \ibibfield{howpublished}, \ibibfield{month},
\ibibfield{note}, \ibibfield{title}, \ibibfield{year}\tabularnewline
\ibibentry{phdthesis} & \ibibfield{author}, \ibibfield{title}, \ibibfield{school}, \ibibfield{year} & 
\ibibfield{address}, \ibibfield{month}, \ibibfield{note},
\ibibfield{type}\tabularnewline
\ibibentry{proceedings} & \ibibfield{title}, \ibibfield{year} & 
\ibibfield{editor}, \ibibfield{organization}, \ibibfield{address}, \ibibfield{volume} or \ibibfield{number}, \ibibfield{series},
\ibibfield{month}, \ibibfield{publisher},
\ibibfield{note}\tabularnewline
\ibibentry{techreport} & 
\ibibfield{author}, \ibibfield{title}, \ibibfield{institution}, \ibibfield{year} &
\ibibfield{type}, \ibibfield{number}, \ibibfield{address},
\ibibfield{month}, \ibibfield{note} \tabularnewline
\ibibentry{unpublished} & \ibibfield{author}, \ibibfield{title}, \ibibfield{note} &
\ibibfield{month}, \ibibfield{year}
\end{fieldtab}\screenpagebreak

The \ibibfield{author} and \ibibfield{editor} fields have the same
format as described in \sectionref{sec:jabref}. That is, each
name should be in one of the forms listed in \tableref{tab:bibnameformats},
and multiple authors or editors must be separated with the keyword
\dq{and}.

\xminisec{Example (Multiple Authors):}

This example uses the \ibibentry{book} entry:
\begin{code}
\begin{verbatim}
@book{goossens97,
   author = "Goossens, Michel and Rahtz, Sebastian and
             Mittelbach, Frank",
   title = "The \LaTeX\ graphics companion: illustrating
            documents with \TeX\ and {PostScript}",
   publisher = "Addison Wesley Longman, Inc",
   year = 1997
}
\end{verbatim}
\end{code}
In this example, the \meta{keyword} is \verb|goossens97|. That is
the identifying key used in \glsi{cite}, described \htmlref{below}{sec:bibtex}.
The standard bibliography styles usually convert titles to lower case, 
so the name PostScript is enclosed in curly braces to prevent this from
happening.

Note that curly braces \verb|{}| can be used instead of double quotes.
The above example can just as easily be written:
\begin{code}
\begin{verbatim}
@book{goossens97,
   author = {Goossens, Michel and Rahtz, Sebastian and
             Mittelbach, Frank},
   title = {The \LaTeX\ graphics companion: illustrating
            documents with \TeX\ and {PostScript}},
   publisher = {Addison Wesley Longman, Inc},
   year = 1997
}
\end{verbatim}
\end{code}

Numbers (such as the year 1997) don't need to be delimited with quotes 
or braces.  So you can have
\begin{codeS}
pages = 10
\end{codeS}
but a~page range would need to be delimited:
\begin{codeS}
\begin{alltt}
pages = "10\gls{endash}45"
\end{alltt}
\end{codeS}

Bibliography styles always have three-letter abbreviations for months:
\texttt{jan}, \texttt{feb}, \texttt{mar}, etc.  These should be used
instead of typing them in explicitly, as their format depends on the
bibliography style.  These abbreviations should be entered without
quotes. For example:
\begin{code}
\begin{verbatim}
@inproceedings{talbot97,
   author    = "Talbot, Nicola and Cawley, Gavin",
   title     = "A fast index assignment algorithm for
                robust vector quantisation of image data",
   booktitle = "Proceedings of the I.E.E.E. International
                Conference on Image Processing",
   address   = "Santa Barbara, California, USA",
   month     = oct,
   year      = 1997
}
\end{verbatim}
\end{code}

\setnode{bibtex}
\section{BibTeX}
\label{sec:bibtex}

Now that we've created a~\texttt{.bib} file (as described 
\htmlref{above}{sec:creatingbibfile}) we next need to look at how to
incorporate the information in the database into a~\LaTeX\ document.
As mentioned in \novices[sec:bib]{biblio}, entries are cited in the document using:
\begin{definition}
\gls{cite}\oarg{\meta{text}}\marg{\meta{key list}}
\end{definition}
where \meta{key list} is a~comma-separated list of keys. Each key
uniquely identifies an entry in the database. If you used
\appname{JabRef} (\sectionref{sec:jabref}), this is the key you
entered in the \dq{Bibtexkey} field. If you wrote the \texttt{.bib}
file in a~text editor (\sectionref{sec:bibformat}) it's the 
\meta{keyword} bit at the start of the list of fields for the entry.

Next you need to specify what type of bibliography style you want to
use.  There are many available, but the basic ones 
are:\faq{Choosing a~bibliography style}{whatbst}
\begin{description}
\item[\ibst{abbrv}] Entries sorted alphabetically with abbreviated
first names, months and journal names.

\item[\ibst{alpha}] Entries sorted alphabetically with the citation
represented by abbreviated author surname and year instead of a~number.

\item[\ibst{plain}] Entries sorted alphabetically, with the citation
represented by a~number.

\item[\ibst{unsrt}]  Entries sorted according to citation with the
citation represented by a~number.

\end{description}
The style is specified in your \LaTeX\ document with the command:
\begin{definition}
\gls{bibliographystyle}\marg{\meta{style}}
\end{definition}
where \meta{style} is the name of the style. Some people put this
command in the document's preamble and some people put it near their
bibliography, but wherever you choose to put it, this command
should only be used once.

The actual bibliography itself is input into the document using
\begin{definition}
\gls{bibliography}\marg{\meta{database}}
\end{definition}
where \meta{database} is the name of the database \emph{without the
\texttt{.bib} extension}. In fact, this argument can be a
comma-separated list of databases if your entries are stored across
multiple files.

Recall the example thesis in \listingref{ex:thesis1} ended with:
\begin{code}
\begin{alltt}
\glsni{percentchar} The bibliography will go here

\glsni{end}\marg{document}
\end{alltt}
\end{code}\bookpagebreak\noindent
If my references are stored in the file \examplecode{thesis-ref.bib},
then I~can replace the above comment as follows:
\begin{codelisting}{thesis-biblio.tex}
\begin{alltt}
\glsni{bibliographystyle}\marg{plain}
\glsni{bibliography}\marg{thesis-ref}

\glsni{end}\marg{document}
\end{alltt}
\end{codelisting}
Elsewhere in my document I~need some citations. For example:
\begin{code}
See Turabian\glsni{tildechar}\glsni{cite}\marg{turabian96} for 
a~comprehensive guide on preparing a~thesis.
\end{code}
If you are using \iappname{arara} (see \sectionref{sec:arara}) you
need the following lines in your source code:
\begin{code}
\begin{alltt}
\gls{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} \iappname{bibtex}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\end{alltt}
\end{code}
If you are using \iappname{latexmk} (see \sectionref{sec:latexmk})
make sure you are using the \texttt{-bibtex} argument
(\figureref{fig:texworks-latexmkbibtex}).

If you are not using either \appname{latexmk} or \appname{arara},
you will need to run \PDFLaTeX, then run Bib\TeX, then run
\PDFLaTeX\ twice more (see \sectionref{sec:build}).

If your citations appear as two question marks ?? in your PDF, then
the citation key you used hasn't been recognised. This could be that
you've forgotten the Bib\TeX\ and subsequent \emph{two} \PDFLaTeX\
calls, or it could be that the key hasn't been defined, or you have
misspelt it.

Recall from \novices[sec:bib]{biblio} that the bibliography doesn't
usually get added to the table of contents for most class files, but
the \koma\ classes provide the options \scrclsopt[totocnumbered]{bibliography} and
\scrclsopt[totoc]{bibliography}, that add a~numbered or
unnumbered bibliography to the table of contents.

You can add backlinks from your bibliography back to the section or page where
the entries were cited using the \istyopt{hyperref}{backref} option
of the \isty{hyperref} package. (The \sty{hyperref} package should
usually be loaded last.) For example, to have backreferences to the
pages on which the citation occurs:
\begin{codeS}
\gls{usepackage}\oarg{backref}\marg{hyperref}
\end{codeS}
The \sty{hyperref} package is covered in more detail in
\latexpdfdoc.

\setnode{natbib}
\subsection{Author--Year Citations}
\label{sec:natbib}

The default behaviour of citations with bibliography styles such as
\texttt{plain} is to produce a~numerical reference in square brackets.
If you're using \iappname{bibtex} (rather than \isty{biblatex},
described \htmlref{below}{sec:biblatex}) you
can override this using a~number of packages. One such package is
\isty{natbib}. This comes with some drop-in replacements for the
standard bibliography styles: \ibst{plainnat}, \ibst{unsrtnat}
and \ibst{abbrvnat}. The \sty{natbib} package comes with a~variety of
package options, but I'm just going to mention a~few of them:
\istyopt{natbib}{authoryear} for author--year citations (default),
\istyopt{natbib}{numbers} for numerical citations,
\istyopt{natbib}{super} for superscripted numerical citations,
\istyopt{natbib}{round} for round parentheses,
\istyopt{natbib}{square} for square parentheses
and \istyopt{natbib}{sort\&compress} which sorts multiple citations
and compresses consecutive numbers into a~range. For example, 
[4,2,8,3] will become [2--4,8].

So for citations that give the author and year rather than a~number,
you need to load \sty{natbib} in the preamble:
\begin{codeS}
\glsni{usepackage}\oarg{round}\marg{natbib}
\end{codeS}
and specify one of the \sty{natbib} bibliography styles:
\begin{codeS}
\gls{bibliographystyle}\marg{plainnat}
\end{codeS}
There are two main replacements for \gls{cite}:
\begin{definition}
\gls{citet}\oarg{\meta{pre}}\oarg{\meta{post}}\marg{\meta{key}}
\end{definition}
for textual citations and
\begin{definition}
\gls{citep}\oarg{\meta{pre}}\oarg{\meta{post}}\marg{\meta{key}}
\end{definition}
for parenthetical citations.

Unlike \glsni{cite}, these commands have two optional arguments. The
second \meta{post} is a~suffix, the same as \glsni{cite}'s only optional
argument. The first optional argument \meta{pre} is a~prefix. If
only one optional argument is present, it is assumed to be
\meta{post}, so if you only want a~prefix and no suffix, you have to
specify an empty argument for \meta{post}.

\xminisec{Example:}
(Using the same \examplecode{thesis-ref.bib} database as earlier.)
\begin{codelisting}{thesis-nat.tex}
\null\par
A textual citation \glsni{citet}\marg{turabian96}
and a~parenthetical citation \glsni{citep}\oarg{see}\oarg{Chapter
9}\marg{goossens97}.
\end{codelisting}
Result:
\begin{result}[natbib.html]
A textual citation Turabian (1996) and a~parenthetical citation
(see Goossens et al., 1997, Chapter 9).
\end{result}

\setnode{bibtextroubleshooting}
\subsection{Troubleshooting}
\label{sec:bibtextroubleshooting}

\begin{itemize}
 \item \BiBTeX\ writes the \gls{env-thebibliography} environment to
a~\texttt{.bbl} file, which is then input into the document by 
\gls{bibliography}. If you have made a~\LaTeX\ error in the
\texttt{.bib} file, this error will be copied to the \texttt{.bbl}
file. If you have corrected the error in the \texttt{.bib} file,
but you are still getting an error when you \LaTeX\ your document,
try deleting the \texttt{.bbl} file. (In TeXworks, you can use the
menu item \menu{File}\menuto\menu{Remove Aux Files}.)

 \item Remember to use double quotes or braces to delimit the field
names in your \texttt{.bib} file.

 \item Remember to put a~comma at the end of each field entry (except the
last).

 \item It is better to only use alphanumerical characters in the
keywords. Some punctuation characters such as \texttt{.} (full stop)
should be fine (unless you're using a~package such as \sty{babel}
that makes them active), but spaces are not recommended, and commas
should definitely be avoided.

 \item If you have entered a~field in the \texttt{.bib} file, but it
doesn't appear in the bibliography, check to make sure that the
field is required or optional for that type of entry, and check the
spelling. (You can avoid this problem by using a~bibliography
management system such as \htmlref{JabRef}{sec:jabref}.)

 \item Check the \BiBTeX\ log file (\texttt{.blg}) for messages.

 \item If you get an error that looks something like:
\begin{verbatim}
ERROR - Cannot find control file 'thesis-ref.bcf'! - did you pass
the "backend=biber" option to BibLaTeX?
\end{verbatim}
then you have inadvertently used \iappname{biber} (see
\htmlref{below}{sec:biblatex})
instead of \iappname{bibtex}.

  \item If you get an error that looks something like:
\begin{verbatim}
I found no \citation commands---while reading file thesis1.aux
I found no \bibdata command---while reading file thesis1.aux
I found no \bibstyle command---while reading file thesis1.aux
\end{verbatim}
then you probably forgot to use the \gls{bibliography} and
\gls{bibliographystyle} commands in
your document.
\end{itemize}

\setnode{biblatex}
\section{Biblatex}
\label{sec:biblatex}

The \istystart{biblatex} package is a~reimplementation of \LaTeX's
bibliographic facilities. The formatting of the bibliography is
governed by \LaTeX\ commands instead of selecting a~BibTeX style
(as was done with \gls{bibliographystyle} described \htmlref{above}{sec:bibtex}).
This package uses
\iappnamelink{biber}{http://biblatex-biber.sourceforge.net/} instead
of BibTeX to process the bibliographic database and sort the
entries. Legacy BibTeX is also supported, but with a~reduced feature
set. The \sty{biblatex} package also supports multiple
bibliographies, for example a~bibliography for each chapter in the
document. The \sty{biblatex} package requires e-\TeX, so make sure
you have a~recent \TeX\ distribution. Biber comes with the
latest version of \TeX~Live.

If you are using \iappname{JabRef} (described in
\sectionref{sec:jabref}) there is a~BibLaTeX mode option in the
Advanced tab of the \appname{JabRef} preferences dialog, illustrated in
\figureref{fig:jabref9}. (Use \menu{Options}\menuto\menu{Preferences} to
open the dialog.) You will have to quit and restart \appname{JabRef}
after enabling this option. When you restart, you should find extra
fields when you edit an entry or create a~new entry, as illustrated
in \figureref{fig:jabref10}. You should also find that there are
more entry types available (see \figureref{fig:jabref11}).

\begin{figure}[htbp]
\figconts
 {pictures/jabref9}
 {\caption{JabRef Advanced Preferences}}
 {fig:jabref9}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/jabref10}
 {\caption{JabRef in BibLaTeX Mode}}
 {fig:jabref10}
\end{figure}

\begin{figure}[htbp]
\figconts
 {pictures/jabref11}
 {\caption{JabRef in BibLaTeX Mode (Select Entry Type)}}
 {fig:jabref11}
\end{figure}

With BibTeX, there was a~\ibibfield{month} and \ibibfield{year}
field. BibLaTeX provides a~replacement \ibibfield{date} field,
although if this field is missing it will fall back on the
\bibfield{month} and \bibfield{year} fields. In
\figureref{fig:jabref12}, I've edited my earlier example to use the
new \bibfield{date} field. Note that the date should be specified as
\meta{year}\texttt{-}\meta{month}\texttt{-}\meta{day} where
\texttt{-}\meta{day} or \texttt{-}\meta{month}\texttt{-}\meta{day}
maybe omitted. A slash \texttt{/} should be used to indicate a
range, for example \texttt{2002-01/2002-02}.

\begin{figure}[htbp]
\figconts
 {pictures/jabref12}
 {\caption{JabRef in BibLaTeX Mode (Setting the Publication Date)}}
 {fig:jabref12}
\end{figure}

Recall from \figureref{fig:jabref-pref} and \figureref{fig:jabref-dataprop} that
I~set the default encoding to UTF-8. With BibLaTeX and \appname{biber}, my
UTF-8 bibliography can be correctly sorted, but I~need to make sure
that I~load the \isty{inputenc} package before \sty{biblatex} in my
document:
\begin{code}
\glsni{usepackage}\oarg{utf8}\marg{inputenc}\newline
\glsni{usepackage}\marg{biblatex}
\end{code}

\sectionref{sec:natbib} described the \isty{natbib} package.
BibLaTeX has a~compatibility module:
\begin{codeS}
\glsni{usepackage}\oarg{natbib}\marg{biblatex}
\end{codeS}
This provides the same commands (such as \gls{citet} and \gls{citep}) that 
\isty{natbib} provides.

The default sorting order is name, title and year. This can be
changed using the \istyopt{biblatex}{sorting} package option. For
example, to sort by name, year and title:
\begin{codeS}
\glsni{usepackage}\oarg{sorting=nyt}\marg{biblatex}
\end{codeS}
Or you can suppress the sorting, so that all entries are in citation
order:
\begin{codeS}
\glsni{usepackage}\oarg{sorting=none}\marg{biblatex}
\end{codeS}
For other possible values, see the \sty{biblatex}
documentation~\cite{biblatex}.

If you want a~list of back-references in the bibliography, referring
to the pages on which the entries were cited, you can use the
\istyopt{biblatex}{backref} option:
\begin{codeS}
\glsni{usepackage}\oarg{backref}\marg{biblatex}
\end{codeS}

The default database backend is \iappname{biber}, which is
recommended, but if for some reason you want to stick to using
\iappname{bibtex} you can use the \istyopt{biblatex}{backend}
option to switch to \optfmt{bibtex}:
\begin{codeS}
\glsni{usepackage}\oarg{backend=bibtex}\marg{biblatex}
\end{codeS}
There are also options that govern whether certain fields are
printed in the bibliography, such as \istyopt{biblatex}{isbn},
\istyopt{biblatex}{url} or \istyopt{biblatex}{doi}. For example:
\begin{codeS}
\glsni{usepackage}\oarg{isbn,url,doi}\marg{biblatex}
\end{codeS}
The style can be set using the \istyopt{biblatex}{style} option. The
default is \optfmt{numeric}, which produces a~numeric citation, such
as [1]. There is also \optfmt{numeric-comp}, which is like
\isty{natbib}'s \istyopt{natbib}{sort\&compress} option, described
in \sectionref{sec:natbib}, or \optfmt{authoryear} which displays
\meta{author} \meta{year} citations.

There are many other citation styles. For these and for other
package options, see the \sty{biblatex} documentation~\cite{biblatex}.

With BibLaTeX, you don't use the \gls{bibliography} command,
described in \sectionref{sec:bibtex}. Instead, you add the bib file
as a~resource \emph{in the preamble} using:
\begin{definition}
\gls{addbibresource}\oarg{\meta{options}}\marg{\meta{resource}}
\end{definition}
where \meta{resource} is the name of the bib file \emph{including
the file extension}. However, the resource doesn't have to be a~bib file.
You can only add one resource at a~time:
\begin{code}
\glsni{addbibresource}\marg{bibfile1.bib}\newline
\glsni{addbibresource}\marg{bibfile2.bib}
\end{code}
The resource can be a~remote one, in which case you need to use the
\ikeyvalopt{addbibresource}{location} option with the value
\texttt{remote} and specify the URL:
\begin{code}
\glsni{addbibresource}\oarg{location=remote}\marg{http://www.somewhere.com/bibfile2.bib}
\end{code}
This is only available if you use \iappname{biber} as the backend.
Another option is \ikeyvalopt{addbibresource}{datatype} which
specifies the format of the resource. The default is
\texttt{bibtex}, but it can also be \Indextt{ris},
\Indextt{zoterordfxm} or \Indextt{endnotexml}. See the \sty{biblatex}
and \sty{biber} documentation~\cite{biber} for further details.

The bibliography itself is displayed using
\begin{definition}
\gls{printbibliography}\oarg{\meta{options}}
\end{definition}
This should go in the document where you want the bibliography to be
displayed.

Like the \isty{natbib} commands described in
\sectionref{sec:natbib}, the \sty{biblatex} commands generally have two
optional arguments, indicating the prenote and postnote, and a
mandatory argument specifying the key or a~comma-separated list of
keys. If you want a~prenote but not a~postnote, you need to give an
empty second optional argument. The basic commands are:
\begin{definition}
\gls{cite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}\newline
\gls{Cite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}
\end{definition}
These are bare citation commands. The latter is provided if the
citation occurs at the start of a~sentence.
\begin{definition}
\gls{parencite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}\newline
\gls{Parencite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}
\end{definition}
These commands are like \glsni{cite} and \glsni{Cite} but enclose
the citation in parentheses (square if the numeric style is used).
\begin{definition}
\gls{textcite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}\newline
\gls{Textcite}\oarg{\meta{prenote}}\oarg{\meta{postnote}}\marg{\meta{key}}
\end{definition}
These commands are used for citations in the flow of text. The
latter is provided if the citation occurs at the start of a
sentence. For other citation commands, see the \sty{biblatex}
documentation~\cite{biblatex}.

So, the example document from \listingref{ex:thesis1}, can now be
edited so that the preamble looks like:
\begin{codelisting}{thesis-biblatex.tex}\label{ex:thesis-biblatex}
\begin{alltt}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} \iappname{biber}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{oneside}\marg{scrbook}

\glsni{usepackage}\oarg{backend=biber}\marg{biblatex}

\glsni{addbibresource}\marg{thesis-refs.bib}
\end{alltt}
\end{codelisting}
(where \examplecode{thesis-refs.bib} is the name of my bibliography
database, see \sectionref{sec:creatingbibfile}) and the end of the
document looks like:
\begin{code}
\begin{alltt}
\glsni{printbibliography}

\glsni{end}\marg{document}
\end{alltt}
\end{code}
Elsewhere in the document, I~need to cite some of the entries in my
bibliography database:
\begin{code}
\null

First of all, let's cite a
book\glsni{tildechar}\glsni{parencite}\marg{wainwright93} now let's
cite a~journal paper and a~conference
proceedings\glsni{tildechar}\glsni{parencite}\marg{cawley96,talbot97}.
Finally, let's cite a~chapter in a
book\glsni{tildechar}\glsni{parencite}\oarg{Chapter 9}\marg{goossens97}.

\null
\end{code}

If you want to build the document using \iappname{arara}
(\sectionref{sec:arara}) remember to
include the \gls{percentchar.arara} comments (as shown
above). If you are using \iappname{latexmk} (\sectionref{sec:latexmk})
remember to use the \texttt{-bibtex} option as illustrated in
\figureref{fig:texworks-latexmkbibtex}. 

If you're not using an automated method, such as \appname{arara}
or \appname{latexmk}, you need a~\PDFLaTeX\ run, a
\appname{biber} run (or \appname{bibtex} if you've chosen that as
your backend) followed by two more \PDFLaTeX\ runs. 

\setnode{biblatextroubleshooting}
\subsection{Troubleshooting}
\label{sec:biblatextroubleshooting}

Most of the comments from the 
\htmlref{\BiBTeX\ troubleshooting 
section}{sec:bibtextroubleshooting}\doifbook{ (see
page~\pageref{sec:bibtextroubleshooting})}
also apply here.
If you get an error that looks like:
\begin{verbatim}
I found no \citation commands---while reading file thesis-biblatex.aux
I found no \bibdata command---while reading file thesis-biblatex.aux
I found no \bibstyle command---while reading file thesis-biblatex.aux
\end{verbatim}
then you have inadvertently used \iappname{bibtex} instead of
\iappname{biber}. If you actually want to use \appname{bibtex} with
the \istyend{biblatex} package remember that you have to specify
\appname{bibtex} using:
\begin{codeS}
\glsni{usepackage}\oarg{backend=bibtex}\marg{biblatex}
\end{codeS}


% Indexes and Glossaries

\setnode{indgloss}
\chapter{Generating Indexes and Glossaries}
\label{ch:indgloss}

Most theses will need a~glossary of terms or a~list of acronyms or
notation. It's less likely that you'll need an index in your thesis,
but since the same mechanism is used to generate glossaries and
indexes, both topics are covered in this chapter. There are two
basic methods of generating a~glossary or index:

\begin{enumerate}

\item The glossary or indexing information is written to a~temporary
file by \LaTeX\ while the document is being built. An external
application is then used to collate and sort the entries defined in
that temporary file and \LaTeX\ code to display the result is
written to another file. You then need to run (PDF)\LaTeX\ on your
document to ensure the sorted and collated glossary or index is
displayed. (You may then need an additional \LaTeX\ run to ensure
the table of contents is up-to-date.) This is similar to the way you
had to use \appname{bibtex} or \appname{biber} between LaTeX runs in
the \htmlref{previous chapter}{ch:citations}.

\item The glossary or indexing information is collated and sorted by
\LaTeX\ during the document build. (At least two runs are required,
but no external indexing application is needed.)

\end{enumerate}

The first approach (see \sectionref{sec:makeindexglos}) is more
efficient, but a~lot of users, especially beginners, have difficulty
with the intermediate step where the external indexing application
is run. The second approach (see \sectionref{sec:datagidx}) is
slower, but you don't need to worry about running an indexing
application. If you're not writing in English (in particular if you
are not using the Latin alphabet) you're better off using the first
approach with \iappname{xindy}. In this chapter I'll describe both
approaches and you can choose which you prefer.

\setnode{makeindexglos}
\section{Using an External Indexing Application}
\label{sec:makeindexglos}

This section describes how to create indexes 
(\sectionref{sec:makeidx}) or glossaries
(\sectionref{sec:makeglossaries}) using an
external indexing application. There are two popular indexing
applications: \iappname{makeindex} and \iappname{xindy}. All \TeX\
distributions should come with \appname{makeindex}. The \TeX~Live
distribution also comes with \appname{xindy}, but if you have a
different \TeX\ distribution (such as MikTeX) you may need to
fetch \iappname{xindy} from \url{http://www.xindy.org/}.

\xminisec{Note:}
You must have Perl installed in order to use \iappname{xindy} as it's
a~Perl script. (See \xrsectionref{Perl}{perl} from Volume~1.) If you
have successfully been using
\htmlref{\appname{latexmk}}{sec:latexmk}, you already have Perl
installed.

\setnode{makeidx}
\subsection{Creating an Index (\texorpdfstring{\sty{makeidx}}{makeidx} 
package)}
\label{sec:makeidx}

\novices[ch:newcom]{newcom}
introduced the command:
\begin{definition}
\gls{index}\marg{\meta{text}}
\end{definition}
to index the word given in \meta{text}. For example, if
\verb|\index{circuit}| occurs on page~42, then \dq{42} will be added to
the \keyword{location list} for the term \dq{circuit}.  

\xminisec{Note:}

\warning
\glsni{index} doesn't display any text. It just adds a~line to the
index file with the information required by \appname{makeindex} or
\appname{xindy} to sort and collate the information.

The default action of \glsni{index} simply ignores its argument. To
ensure the indexing mechanism works, you must activate it by placing
\begin{definition}
\gls{makeindex}
\end{definition}
in the document preamble.

Finally, you need to use
\begin{definition}
\gls{printindex}
\end{definition}
(defined in the \isty{makeidx} package) to display the index.

\xminisec{Note:}
\warning
\glsni{printindex} won't produce any text until
you have run the external indexing application.

Here's an example document:
\begin{codelisting}{sample-index.tex}\label{ex:sample-index}
\begin{alltt}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} \iappname{makeindex}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{12pt,oneside}\marg{scrbook}

\glsni{usepackage}\marg{makeidx}

\glsni{makeindex}

\glsni{title}\marg{Sample Document}
\glsni{author}\marg{Me}

\glsni{begin}\marg{document}
\glsni{maketitle}

\glsni{chapter}\marg{Sample}

Stuff about eigenvectors\glsni{index}\marg{eigenvector} and
eigenvalues\glsni{index}\marg{eigenvalue}.

\glsni{chapter}\marg{Another Sample}

Some more stuff about eigenvectors\glsni{index}\marg{eigenvector} and
eigenvalues\glsni{index}\marg{eigenvalue}. Something about
eigen-decomposition\glsni{index}\marg{eigen-decomposition}.

\glsni{backmatter}

\glsni{printindex}

\glsni{end}\marg{document}
\end{alltt}
\end{codelisting}

If you are using \iappname{arara} to build your document (see
\sectionref{sec:arara}), remember to include the
\glsni{percentchar.arara} comments, as shown in the above listing.
If you are using \iappname{latexmk} to build your document, remember
to include the \texttt{.idx} custom dependency to your RC file, as
described in \sectionref{sec:latexmk}.

If you aren't using an automated method to build your document, you
will need to run \PDFLaTeX, then run \iappname{makeindex}, and 
then run \PDFLaTeX\ again (see \sectionref{sec:build}).

If you prefer to use \iappname{xindy} instead of
\iappname{makeindex}, you need to run \iappname{texindy} (a
\appname{xindy} wrapper customised for \LaTeX\ documents).
If you are using \iappname{arara}, change the line:
\begin{alltt}
\gls{percentchar.arara} makeindex
\end{alltt}
to (change the language as required):
\begin{alltt}
\gls{percentchar.arara} texindy: \marg*{ language: english }
\end{alltt}
(Make sure you have added the \appname{texindy} rule as described in
\sectionref{sec:arara}.) If you are using \iappname{latexmk} to
build your document, you will need to change the custom dependency
for \texttt{.idx} files, as described in \sectionref{sec:latexmk}.

\setnode{makeindexindexsort}
\subsubsection{Overriding the Default Sort}
\label{sec:makeindexsort}

By default the index entry will be sorted according to the word
being indexed. However, you can override this by writing the
argument of \glsni{index} in the form:
\begin{definition}
\meta{sort}\gls{atchar}\meta{word}
\end{definition}
where \meta{sort} is how to sort the term and \meta{word} is how the
term should appear in the index.

The \iappname{makeindex} application doesn't understand \LaTeX\
commands. It simply sorts the term as is. So, for example, if you do
\begin{codeS}
\glsni{index}\marg{\gls{AE} olian}
\end{codeS}
then \iappname{makeindex} will sort it according to the characters 
\gls{backslashchar}, A, E, \glsni{visiblespace} (space), o, l, i, a,
n. Since \appname{makeindex} sorts symbols (such as \glsni{backslashchar}) 
before letters, it will put
\texttt{\glsni{AE}\glsni{visiblespace}olian} before, say,
\texttt{adze}, since \glsni{backslashchar} comes before \dq{a}.

To get around this, you need to specify the sort key:
\begin{codeS}
\glsni{index}\marg{AEolian\glsni{atchar}\glsni{AE} olian}
\end{codeS}
Now \appname{makeindex} will put \dq{\AE olian} after \dq{adze}.
Here's another example that indexes a~function or method:
\begin{codeS}
\glsni{index}\marg{sqrt()\glsni{atchar}\gls{texttt}\marg{sqrt()}}
\end{codeS}

You will also need to do something similar if you are entering the
character directly via the \sty{inputenc} package:
\begin{codeS}
\glsni{index}\marg{elite\glsni{atchar}\'elite}
\end{codeS}

Note, however, that you don't need to do this if you are using
\iappname{xindy}. You just need to make sure you match the input
encoding. For example:
\begin{code}
\begin{alltt}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} \iappname{texindy}: \marg{ language: english, codepage: latin1}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{12pt,oneside}\marg{scrbook}

\glsni{usepackage}\oarg{latin1}\marg{inputenc}
\glsni{usepackage}\marg{makeidx}
\end{alltt}
\end{code}
Later in the document:
\begin{codeS}
\glsni{index}\marg{\'elite}
\end{codeS}

\setnode{makeindexformat}
\subsubsection{Setting the Location Format}
\label{sec:makeindexformat}

Each index entry has an associated \keyword{location list} that
directs the reader to the pages in the document associated with that
entry. For example, if you look up \gls*{index} in this book's
\latexhtml{\htmlref{index}{ch:index}}{\htmladdnormallink{index}{bookindex.html}},
the entry's location list will include this page. If the location
list is long, it's helpful to highlight a~particular location to
direct the reader to the principle definition or discussion related
to that term. This is usually done by formatting the relevant
location in a~different font, for example bold or italic.

\bookpagebreak
You can specify the format for the location by writing
the argument of \glsni{index} in the form:
\begin{definition}
\meta{word}\gls{index.barchar}\meta{format}
\end{definition}
where \meta{format} is the name of a~text-block command \emph{without}
the leading backslash. For example:
\begin{codeS}
\glsni{index}\marg{eigenvector\glsni{index.barchar}textbf}
\end{codeS}

You can combine \gls{atchar} and \glsni{index.barchar}. For example:
\begin{codeS}
\glsni{index}\marg{sqrt()\glsni{atchar}\gls{texttt}\marg{sqrt()}\glsni{index.barchar}textbf}
\end{codeS}

\xminisec{Note:}

\warning
Make sure the format you use is the name of a~command that takes an
argument. While it won't cause an error to use, say,
\texttt{bfseries} instead of \texttt{textbf}, it will cause the
unexpected side-effect of rendering the rest of your index in that
font, instead of just that particular location.

You can also use \meta{format} to cross-reference another entry.
If you have an entry that's just a~synonym for another entry, you
can use:
\begin{definition}
\meta{word}\glsni{index.barchar}see\marg{\meta{name}}
\end{definition}
where \meta{name} is the other entry. If you want to direct the
reader to a~similar topic, you can use:
\begin{definition}
\meta{word}\glsni{index.barchar}seealso\marg{\meta{topic}}
\end{definition}
where \meta{topic} is the other entry.

For example:
\begin{codeS}
\glsni{index}\marg{eigenvector\glsni{index.barchar}seealso\marg{eigenvalue}}
\end{codeS}

\setnode{makeindexsublevels}
\subsubsection{Sub Levels}
\label{sec:makeindexsublevels}

An entry in the index may have sub-items. With \iappname{makeindex}
you can have a~maximum of three levels. With \iappname{xindy}
you can have an arbitrary number of levels. However, it's a~good
idea to consider the advice in the Oxford Style
Manual~\cite{oxford}: \dq{In all but the most complex indexes,
subentries within subentries (\emph{sub-subentries}) should be
avoided.} In other words, just because it's possible to do something
doesn't mean you should do it.

To indicate a~subentry, the argument of \gls{index} should be in the
form:
\begin{definition}
\meta{main entry}\gls{makeindex.exclamchar}\meta{subentry}
\end{definition}
For example:
\begin{codeS}
\glsni{index}\marg{reptile\glsni{makeindex.exclamchar}caiman}
\end{codeS}\bookpagebreak
If you really must have a~sub-subentry:
\begin{codeS}
\glsni{index}\marg{reptile\glsni{makeindex.exclamchar}crocodylian\glsni{makeindex.exclamchar}caiman}
\end{codeS}

You can combine \gls{atchar}, \gls{index.barchar} and
\glsni{makeindex.exclamchar}. For example:
\begin{codeS}
\glsni{index}\marg{methods\glsni{makeindex.exclamchar}sqrt()\glsni{atchar}\glsni{texttt}\marg{sqrt()}\glsni{index.barchar}textbf}
\end{codeS}

\listingref{ex:thesis-biblatex} can now be modified as 
follows (download the document for the complete
code):\reportpagebreak
\begin{codelisting}{thesis-index.tex}\label{ex:thesis-index}
\begin{alltt}
\glsni{percentchar} In the preamble:
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} biber
\glsni{percentchar.arara} \iappname{makeindex}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{oneside,12pt}\marg{scrbook}

\glsni{usepackage}\marg{makeidx}
\gls{makeindex}

\glsni{percentchar} Later in the document:

Some sample code is shown in Listing\gls{tildechar}\gls{ref}\marg{lst:sample}.  
This uses the function \gls{lstinline}"sqrt()"\glsni{percentchar}
\gls{index}\marg{sqrt()\gls{atchar}\glsni{texttt}\marg{sqrt()}}\glsni{percentchar}
\glsni{index}\marg{functions\gls{makeindex.exclamchar}sqrt()\glsni{atchar}\glsni{texttt}\marg{sqrt()}}\glsni{percentchar}
\glsni{index}\marg{square root\gls{index.barchar}see\marg{\glsni{texttt}\marg{sqrt()}}}.

\glsni{begin}\marg{Definition}\oarg{Tautology}
A \glsni{emph}\marg{tautology}\glsni{index}\marg{tautology\glsni{index.barchar}textbf} is a proposition 
that is always true for any value of its variables.
\glsni{end}\marg{Definition}

\glsni{begin}\marg{Definition}\oarg{Contradiction}
A \glsni{emph}\marg{contradiction}\glsni{index}\marg{contradiction\glsni{index.barchar}textbf} is 
a proposition that is always false for any 
value of its variables.
\glsni{end}\marg{Definition}

\glsni{percentchar} At the end of the document:

\glsni{printbibliography}
\glsni{printindex}

\glsni{end}\marg{document}
\end{alltt}
\end{codelisting}

The index for the above document looks like:
\begin{result}[sampleindex.html]
\begin{simtheindex}

  \item contradiction, \textbf{2}

  \indexspace

  \item functions
    \subitem \texttt{sqrt()}, 2

  \indexspace

  \item \texttt{sqrt()}, 2
  \item square root, \see{\texttt{sqrt()}}{2}

  \indexspace

  \item tautology, \textbf{2}

\end{simtheindex}
\end{result}


\setnode{makeindextroubleshooting}
\subsubsection{Troubleshooting}
\label{sec:makeindextroubleshooting}

\begin{itemize}
\item My index hasn't appeared.

  \begin{enumerate}
   \item Make sure you have the command \gls{printindex} at the
place where you want the index to appear (this command is defined in
the \isty{makeidx} package).

   \item Make sure you have the command \gls{makeindex} in the
preamble.

   \item If you are building the document using \iappname{arara}
make sure you included all the \gls{percentchar.arara} directives as
shown in \listingref{ex:thesis-index}. If you are using
\iappname{latexmk}, make sure you have included the \texttt{.idx}
dependency, as described in \sectionref{sec:latexmk}. If you're not
using an automated tool, make sure you run (PDF)\LaTeX, then
\iappname{makeindex} and then (PDF)\LaTeX\ again (see
\sectionref{sec:build}).

   \item Check \appname{makeindex}'s log file (which has the
extension \texttt{.ilg} by default) for error messages.
  \end{enumerate}

  \item I~want to index the character \gls{makeindex.doublequote},
    \gls{atchar}, \gls{makeindex.exclamchar} or \gls{index.barchar}
    but it's not working.

  If you want any of these symbols in your index, you will need to
prefix the character with the double-quote symbol
\glsni{makeindex.doublequote}. For example to index the
\glsni{atchar} symbol:
\begin{codeS}
\gls{index}\marg{\glsni{makeindex.doublequote}\glsni{atchar}}
\end{codeS}

\item I~have multiple entries of the same item. For example:

\null~~~identity matrix, 10, 22--30\newline
\null~~~identity matrix, 4\newline\null

Check to make sure the sort argument to each of the corresponding
\glsni{index} commands is the same. Pay particular attention to
spaces as \iappname{makeindex} will treat the following entries
differently:
\begin{code}
\begin{alltt}
\glsni{index}\marg{identity\glsni{visiblespace}matrix}
\glsni{index}\marg{identity\glsni{visiblespace}\glsni{visiblespace}matrix}
\end{alltt}
\end{code}
\LaTeX\ however treats multiple spaces the same as a~single space,
so the text will appear the same in the index.

\item \LaTeX\ says that the command \gls{printindex} is undefined.

You have forgotten to load the \sty{makeidx} package.
\end{itemize}

% Generating glossaries

\setnode{makeglossaries}
\subsection{Creating Glossaries, Lists of Symbols or Acronyms 
(\texorpdfstring{\sty{glossaries}}{glossaries} package)}
\label{sec:makeglossaries}

There are a~number of packages available to assist producing a~list
of acronyms (such as the \isty{acronym} package) or a~glossary (such
as the \isty{nomencl} package). You can see a~list of available
packages in the \htmladdnormallinkfoot{OnLine \TeX\ Catalogue's
Topic
Index}{http://mirror.ctan.org/help/Catalogue/bytopic.html\#index}~\cite{texcattopic}.
Here, I've chosen to describe the \isty{glossaries} package.
Firstly, it encompasses the functionality of both \sty{acronym} and
\sty{nomencl} as \isty{glossaries} allows you to define multiple
lists of acronyms, lists of symbols or glossaries. Secondly, I~wrote
the \sty{glossaries} package, so it's the one with which I~am most
familiar.

The \sty{glossaries} package is very flexible, but the downside to
that is that it has too many features to cover briefly. I'm
therefore only going to introduce the basics here. If you want more
detail you'll have to read the user
manual~\cite{glossaries}. I~will
use the term \dq{glossary} to mean a~list of terms or a~list of
notation or a~list of symbols or a~list of acronyms.

\xminisec{Note:}

\warning If you want to use both \isty{glossaries} and
\isty{hyperref}, you must load \sty{hyperref} \emph{before}
\sty{glossaries}. This is an exception to the usual advice of
loading \sty{hyperref} last.

\setnode{newglossaryentry}
\subsubsection{Defining Glossary Entries}
\label{sec:newglossaryentry}

Firstly, in order to make the glossary (or glossaries, if you have
more than one) appear, you must use the command
\begin{definition}
\gls{makeglossaries}
\end{definition}
in the preamble. This is analogous to the \glsni{makeindex} command
described in \sectionref{sec:makeidx}.

Next you need to define the terms you want to appear in the
glossary. This is done using the command:
\begin{definition}
\gls{newglossaryentry}\marg{\meta{label}}\marg{\meta{key-val list}}
\end{definition}
The first argument \meta{label} is a~unique label so that you can
refer to this entry in your document text. The entry will only
appear in the glossary if you have referenced it in the document
using one of the commands listed later. The second argument is a
comma-separated list of \meta{key}=\meta{value} options. Common keys
are:
\begin{itemize}
\item \ikeyvalopt{newglossaryentry}{name}

 The name of the entry (as it will appear in the glossary).

\item \ikeyvalopt{newglossaryentry}{description}

 A brief description of this entry (to appear in the glossary).

\item \ikeyvalopt{newglossaryentry}{text}

 How this entry will appear in the document text where the singular
form is required. If this key is omitted the value of 
\keyvalopt{name} will be used.

\item \ikeyvalopt{newglossaryentry}{first}

 How this entry will appear in the document text the first time it
is used, where the first use requires the singular form. If this key
is omitted the value of \keyvalopt{text} is used.

\item \ikeyvalopt{newglossaryentry}{plural}

 How this entry will appear in the document text where the plural
form is required. If this key is omitted, the value is obtained by
appending the letter \dq{s} to the value of the 
\keyvalopt{text} key.

\item \ikeyvalopt{newglossaryentry}{firstplural}

How this entry will appear in the document text the first time it is
used, where the first use requires the plural form. If this field is
omitted, the value is obtained by appending the letter \dq{s} to the
value of the \keyvalopt{first} key.

\item \ikeyvalopt{newglossaryentry}{symbol}

This key is provided to allow the user to specify an associated
symbol, but most glossary styles ignore this value.

\item \ikeyvalopt{newglossaryentry}{sort}

This value indicates how to sort this entry (analogous to using the
\gls{atchar} character in the argument of \gls{index}, as described
in \sectionref{sec:makeidx}). If this key is omitted the value of
\keyvalopt{name} is used.

\item \ikeyvalopt{newglossaryentry}{type}

This is the glossary type to which this entry belongs (see
\sectionref{sec:newglossary}). If omitted the main (default) glossary 
is assumed.
\end{itemize}

\xminisec{Examples:}

The following defines the term \dq{set} and assigns a
brief description. The term is given the label \texttt{set}. This is the
minimum amount of information you must give: 
\begin{code}
\begin{alltt}
\gls{newglossaryentry}\marg{set}\glsni{percentchar} the label
\marg{\glsni{percentchar}
  name=\marg{set},\glsni{percentchar} the term
  description=\marg{a collection of objects}\glsni{percentchar} a brief description
}
\end{alltt}
\end{code}
The following entry also has an associated symbol:
\begin{code}
\begin{alltt}
\glsni{newglossaryentry}\marg{U}\glsni{percentchar} the label
\marg{\glsni{percentchar}
  name=\marg{universal set},\glsni{percentchar} the term
  description=\marg{the set of all things},\glsni{percentchar} a brief description
  symbol=\marg{\gls{ensuremath}\marg{\gls{mathcal}\marg{U}}}\glsni{percentchar} the associate symbol
}
\end{alltt}
\end{code}
The plural of the word \dq{matrix} is \dq{matrices} not \dq{matrixs},
so the term needs the plural form set explicitly: 
\begin{code}
\begin{alltt}
\glsni{newglossaryentry}\marg{matrix}\glsni{percentchar} the label
\marg{name=\marg{matrix},\glsni{percentchar} the term
 description=\marg{a rectangular table of elements},\glsni{percentchar} brief description
 plural=\marg{matrices}\glsni{percentchar} the plural
}
\end{alltt}
\end{code}
The \sty{glossaries} package also provides the shortcut command:
\begin{definition}
\gls{newacronym}\oarg{\meta{key-val
list}}\marg{\meta{label}}\marg{\meta{abbrv}}\marg{\meta{long}}
\end{definition}
The default behaviour of this command is equivalent to:
\begin{code}
\glsni{newglossaryentry}\marg{\meta{label}}\marg{name=\marg{\meta{abbrv}}\comma
description=\marg{\meta{long}}\comma
text=\marg{\meta{abbrv}}\comma
first=\marg{\meta{long} (\meta{abbrv})}\comma
plural=\marg{\meta{abbrv}s}\comma
firstplural=\marg{\meta{long}s (\meta{abbrv}s)}\comma
\meta{key-val list}}
\end{code}

\xminisec{Example:}
\begin{codeS}
\glsni{newacronym}\marg{svm}\marg{SVM}\marg{support vector machine}
\end{codeS}
is equivalent to 
\begin{code}
\begin{alltt}
\glsni{newglossaryentry}\marg{svm}\glsni{percentchar} the label
\marg{\glsni{percentchar}
  name=\marg{SVM},\glsni{percentchar}
  description=\marg{support vector machine},\glsni{percentchar}
  first=\marg{support vector machine (SVM)},\glsni{percentchar}
  firstplural=\marg{support vector machines (SVMs)},\glsni{percentchar}
  text=\marg{SVM},\glsni{percentchar}
  plural=\marg{SVMs}\glsni{percentchar}
}
\end{alltt}
\end{code}

There are some package options that modify the behaviour of
\glsni{newacronym}. For example, the package option
\istyopt{glossaries}{description} changes \glsni{newacronym} so that
you need to explicitly set the description in the optional argument.
For example:
\begin{code}
\glsni{usepackage}\oarg{description}\marg{glossaries}\newline
\mbox{}\newline
\glsni{newacronym}\oarg{description=\marg{a~statistical pattern
recognition technique}}\marg{svm}\marg{SVM}\marg{support vector
machine}
\end{code}

Another package option is \istyopt{glossaries}{footnote} which will
modify the behaviour of \glsni{newacronym} so that the long form is
displayed as a~footnote on first use. For a~full list of available
options, see the \sty{glossaries} documentation~\cite{glossaries}.

\setnode{glslink}
\subsubsection{Displaying Terms in the Document}
\label{sec:glslink}

Any glossary term that has been defined using
\gls{newglossaryentry} or \reportlinebreak\gls{newacronym}, as described above,
can be displayed in the document using one of the commands described
in this section. (There are other less commonly used commands
available as well, see the \sty{glossaries}
documentation~\cite{glossaries} for
details of them.)

Each term has an associated \keyword{first use flag}. This is a
boolean (true\slash false) switch that determines whether or not the entry has
been used. This is how the \sty{glossaries} package determines
whether to display the value of the
\ikeyvalopt{newglossaryentry}{first} key or to display the value of
the \ikeyvalopt{newglossaryentry}{text} key. You can reset this flag
using:\bookpagebreak
\begin{definition}
\gls{glsreset}\marg{\meta{label}}
\end{definition}
Conversely, you can unset it using:
\begin{definition}
\gls{glsunset}\marg{\meta{label}}
\end{definition}

To display a~term that has previously been defined using either
\reportlinebreak\gls{newglossaryentry} or \gls{newacronym} you can use one of the
following commands:
\begin{definition}
\gls{gls}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\begin{definition}
\gls{glspl}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\begin{definition}
\gls{Gls}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\begin{definition}
\gls{Glspl}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
These commands all have the same syntax: \meta{label} is the label
that uniquely identifies the term (as supplied in
\gls{newglossaryentry} or \gls{newacronym}), \meta{insert} is
additional text to insert after the term (but inside the hyperlink,
if used with the \isty{hyperref} package), and \meta{options} is a
\meta{key}=\meta{value} list of options. Available options are:
\begin{itemize}
\item \ikeyvalopt{gls}{format}

This specifies how to format the associated location for this
entry. It is analogous to the \gls{index.barchar} special character
used in \gls{index} (see \sectionref{sec:makeindexformat}). As with
\glsni{index}, the format must not include the initial backslash.
For example, \booklinebreak\texttt{format=textbf} indicates that the location
should be displayed in bold. (If you are using the \isty{hyperref}
package, you should use the \texttt{hyper}\meta{xx} formats instead,
such as \texttt{hyperbf}, see the \sty{glossaries}
documentation~\cite{glossaries} for
further detail.)

\item \ikeyvalopt{gls}{counter}

This specifies which counter to use for the associated location
in the glossary. This is usually the page number, but can be
changed to, say, the section in which the term is used.

\item \ikeyvalopt{gls}{hyper}

This is a~boolean key which can be used to enable/disable the
hyperlink to the relevant entry in the glossary. Note that setting
\texttt{hyper=true} will only have an effect if hyperlinks are
supported (through loading the \isty{hyperref} package before
loading the \isty{glossaries} package). The above commands all have
starred versions that are a~shortcut for \texttt{hyper=false}. For
example \texttt{\glsni{gls}*\marg{svm}} is equivalent to
\texttt{\glsni{gls}\oarg{hyper=false}\marg{svm}}.

\end{itemize}

The above commands \glsni{gls} and \glsni{Gls} will display the value of
the \ikeyvalopt{newglossaryentry}{first} or
\ikeyvalopt{newglossaryentry}{text} key, depending on whether or not
the entry has already been used. Similarly, \glsni{glspl} and
\glsni{Glspl} will display the value of the
\ikeyvalopt{newglossaryentry}{firstplural} or
\ikeyvalopt{newglossaryentry}{plural} key, depending on whether or
not the entry has already been used.
The upper case forms, \glsni{Gls} and \glsni{Glspl},
will capitalise the first letter.

\xminisec{Example:}

Suppose I~have defined the following entry:
\begin{code}
\begin{alltt}
\glsni{newglossaryentry}\marg{matrix}\glsni{percentchar} the label
\marg{name=\marg{matrix},\glsni{percentchar} the term
 description=\marg{a rectangular table of elements},\glsni{percentchar} brief description
 plural=\marg{matrices}\glsni{percentchar} the plural
}
\end{alltt}
\end{code}
Then (later in the document)
\begin{code}
\gls{Glspl}\marg{matrix} are usually denoted by a~bold capital letter, such as 
\glsni{dollarchar}\glsni{mathbf}\marg{A}\glsni{dollarchar}.
The \gls{gls}\marg{matrix}\oarg{'s} \glsni{dollarchar}(i,j)\glsni{dollarchar}th
element is usually denoted
\glsni{dollarchar}a\gls{underscorechar}\marg{ij}\glsni{dollarchar}.
\gls{Gls}\marg{matrix}
\glsni{dollarchar}\glsni{mathbf}\marg{I}\glsni{dollarchar} is the
identity \gls{gls}\marg{matrix}.
\end{code}
will display:
\begin{result}[matrix.html]
Matrices are usually denoted by a~bold capital letter, such as
$\mathbf{A}$. The matrix's $(i,j)$th element is usually denoted
$a_{ij}$.
Matrix $\mathbf{I}$ is the identity matrix.
\end{result}

If you have used the \ikeyvalopt{newglossaryentry}{symbol} key when
you defined a~term, you can access its value with:
\begin{definition}
\gls{glssymbol}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
This has the same syntax as commands like \gls{gls} but it doesn't
affect or query the first use flag.

Terms that have been defined using \gls{newacronym} can also be
referenced using the commands:
\begin{definition}
\gls{acrshort}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}\newline
\gls{Acrshort}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\begin{definition}
\gls{acrlong}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}\newline
\gls{Acrlong}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\begin{definition}
\gls{acrfull}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}\newline
\gls{Acrfull}\oarg{\meta{options}}\marg{\meta{label}}\oarg{\meta{insert}}
\end{definition}
\emph{These commands don't affect the first use flag.} The first two
(\glsni{acrshort} and \glsni{Acrshort}) will display the
abbreviation only, the middle two (\glsni{acrlong} and
\glsni{Acrlong}) will display the long form only, and the last two
(\glsni{acrfull} and \glsni{Acrfull}) display both the long and
short form. These commands have the same syntax as \glsni{gls}
and \gls{Gls}.

If you find these commands a~little long-winded to type, you can use
the package option \istyopt{glossaries}{shortcuts}, which will
provide shorter synonyms, such as \gls{acs}, \gls{acl} and
\gls{acf}. This option also defines \gls{ac} which is equivalent to
\gls{gls}. See the glossaries user guide~\cite{glossaries} for
further details.

\xminisec{Another Example:}

Suppose I~have defined an acronym as follows:
\begin{codeS}
\glsni{newacronym}\marg{svm}\marg{SVM}\marg{support vector machine}
\end{codeS}
Then (later in the document):
\begin{code}
First use: \gls{gls}\marg{svm}\gls{at}. Next use: 
\gls{gls}\marg{svm}\glsni{at}.
Short: \glsni{acrshort}\marg{svm}\glsni{at}.
Long: \glsni{acrlong}\marg{svm}.
Full: \glsni{acrfull}\marg{svm}\glsni{at}.
\end{code}
produces:
\begin{result}[svm.html]
First use: support vector machine (SVM)\@. Next use: SVM\@.
Short: SVM\@. Long: support vector machine. Full:
support vector machine (SVM)\@.
\end{result}
(Recall \glsni{at} from \novices{intersentencespacing}.)

\xminisec{Note:}

\warning Avoid using commands like \gls{gls} in section headings or
captions. Instead, use commands like:
\begin{definition}
\gls{glsentrytext}\marg{\meta{label}}
\end{definition}
(displays the value of the \ikeyvalopt{newglossaryentry}{text} key
without a~hyperlink) or
\begin{definition}
\gls{glsentryfirst}\marg{\meta{label}}
\end{definition}
(displays the value of the \ikeyvalopt{newglossaryentry}{first} key
without a~hyperlink). These commands don't affect the first use
flag. For related commands, see the glossaries user
guide~\cite{glossaries}.

\warning Take care if you want to use the uppercase variants, such
as \gls{Gls} or \gls{Acrlong}. If the first letter is an accent
(either entered using accents commands such as
\texttt{\gls{acute}\marg{e}} or entered directly such as
\texttt{\'{e}} with the \isty{inputenc} package) then you must group
that letter when you define the term.\bookpagebreak

\xminisec{Example:}

\begin{code}
\begin{alltt}
\gls{newglossaryentry}\marg{elite}\glsni{percentchar} label
\marg{\glsni{percentchar}
  name=\marg{\marg{\'{e}}lite},\glsni{percentchar}
  description=\marg{select group or class}\glsni{percentchar}
}
\end{alltt}
\end{code}

\setnode{newglossary}
\subsubsection{Defining New Glossaries}
\label{sec:newglossary}

If you want the list of acronyms to be separate from the main
glossary, you need to use the package option
\istyopt{glossaries}{acronym}. This will change the effect of
\gls{newacronym} so that it adds the term to the list of acronyms
instead of to the main glossary.

You can also define your own custom glossaries using
\begin{definition}
\gls{newglossary}\oarg{\meta{log-ext}}\marg{\meta{name}}\marg{\meta{in-ext}}\marg{\meta{out-ext}}\marg{\meta{title}}\oarg{\meta{counter}}
\end{definition}
where \meta{name} is a~label that uniquely defines this new glossary
and \meta{title} is the title to be used when the glossary is
displayed in the document via \glsi{printglossary} or
\glsi{printglossaries}, see \sectionref{sec:printglossaries}.
The other mandatory arguments, \meta{in-ext} and \meta{out-ext},
specify the file extensions to give to the input and output files
for this new glossary. The first optional argument \meta{log-ext} is
the extension for the log file. This information is provided for the
benefit of the \iappname{makeglossaries} application. The final
optional argument \meta{counter} is the name of the counter used by
default in the location lists for this new glossary. If omitted, the
\icounter{page} counter is used (unless overridden by the
\istyopt{glossaries}{counter} package option).

\xminisec{Note:}

\warning All glossaries must be defined before \gls{makeglossaries}
to ensure that the relevant output files are opened.

\xminisec{Example:}

The following defines a~new glossary called \dq{notation}:
\begin{codeS}
\glsni{newglossary}\oarg{nlg}\marg{notation}\marg{not}\marg{ntn}\marg{Notation}
\end{codeS}
When it gets displayed (using \glsni{printglossary} or
\glsni{printglossaries}) the title will default to \dq{Notation}.
I~now need to use the \ikeyvalopt{newglossaryentry}{type} key if 
I~want to define an entry to go in this new glossary:
\begin{code}
\begin{alltt}
\gls{newglossaryentry}\marg{not:set}\glsni{percentchar} label
\marg{\glsni{percentchar}
  type=notation,\glsni{percentchar} glossary type
  name=\marg{\glsni{dollarchar}\gls{mathcal}\marg{S}\glsni{dollarchar}},\glsni{percentchar}
  description=\marg{A set},\glsni{percentchar}
  sort=\marg{S}\glsni{percentchar}
}
\end{alltt}
\end{code}
Later in the document I~can use this entry:
\begin{codeS}
A \gls{gls}\marg{not:set} is a~collection of objects.
\end{codeS}

\setnode{printglossaries}
\subsubsection{Displaying Glossaries}
\label{sec:printglossaries}

Now that you know how to define entries and how to use them in the
document text, let's now look at the more complicated task of
displaying the glossaries. To display all the defined glossaries
use:
\begin{definition}
\gls{printglossaries}
\end{definition}
To only display a~particular glossary use:
\begin{definition}
\gls{printglossary}\oarg{\meta{options}}
\end{definition}
where \meta{options} is a~comma-separated list of
\meta{key}=\meta{value} options. Available keys:
\begin{itemize}
\item \ikeyvalopt{printglossary}{type}

The glossary to print. If omitted, the main (default) glossary is
assumed.

\item \ikeyvalopt{printglossary}{style}

The glossary style to use. There are a~lot of predefined styles to
choose from, such as \texttt{list}, \texttt{long} or \texttt{tree}.
See the \sty{glossaries} user manual~\cite{glossaries} for further
details.

\item \ikeyvalopt{printglossary}{title}

Overrides the default title for this glossary.

\item \ikeyvalopt{printglossary}{toctitle}

Overrides the default title for the table of contents.

\item \ikeyvalopt{printglossary}{numberedsection}

Put this glossary in a~numbered section (instead of an unnumbered
section).

\item \ikeyvalopt{printglossary}{nonumberlist}

Suppress the location lists for this glossary.
\end{itemize}

\xminisec{Note:}

\warning By default, the glossaries aren't added to the table of
contents. If you want them added to the table of contents use the
package option \istyopt{glossaries}{toc}.\bookpagebreak
\begin{codeS}
\glsni{usepackage}\oarg{toc}\marg{glossaries}
\end{codeS}

Only those entries that have been used in the document (via commands
like \gls{gls}) are displayed in the glossary. If you want to add an
entry without displaying it in the document, use
\begin{definition}
\gls{glsadd}\oarg{\meta{options}}\marg{\meta{label}}
\end{definition}
where \meta{label} is the unique label identifying the entry. The
optional argument \meta{options} is the same as for commands like
\glsni{gls} except there is no \ikeyvalopt{newglossaryentry}{hyper}
key.

Alternatively, you can add all defined entries using:
\begin{definition}
\gls{glsaddall}\oarg{\meta{options}}
\end{definition}
where \meta{options} is the same as for \glsni{glsadd} except that
there is also a~\ikeyvalopt{glsaddall}{types} key where the value
should be a~comma-separated list of all the glossaries to iterate
over. For example, to add all entries defined in the \dq{acronym}
glossary and the \dq{notation} glossary, but not the \dq{main}
glossary:
\begin{codeS}
\glsni{glsaddall}\oarg{types=\marg{acronym,notation}}
\end{codeS}

\xminisec{Note:}

\warning As with \gls{printindex}
the glossaries won't be displayed until the relevant files have been
created either by \iappname{makeindex} or by \iappname{xindy}.
Unlike in \sectionref{sec:makeidx}, if you want to use
\appname{xindy} to create your glossary files, you can't use the
\iappname{texindy} wrapper but must either use \appname{xindy}
directly or use the \iappname{makeglossaries} wrapper, described
below. If you want to use \appname{xindy} with the \isty{glossaries}
package, you must use the \istyopt{glossaries}{xindy} package option:
\begin{codeS}
\glsni{usepackage}\oarg{xindy}\marg{glossaries}
\end{codeS}
If omitted, \iappname{makeindex} will be assumed.

If you have Perl installed, you can use the \iappname{makeglossaries}
application that comes with the \isty{glossaries} package. If you
have been using \iappname{latexmk} or \appname{xindy}, then you
already have Perl installed. If you don't want to install Perl for
some reason, there's a~Java alternative to \appname{makeglossaries}
called \iappname{makeglossariesgui} that's available from
\gls{ctan}. However, if you don't install Perl, you are restricting
your options as you won't be able to use \appname{xindy}\footnote{or
a~lot of other useful Perl scripts, such as \appname{epstopdf}}.

If you are using \iappname{arara} (see \sectionref{sec:arara}), then
all you need to do is add another \gls{percentchar.arara} directive
in your source code:
\begin{codeS}
\glsni{percentchar.arara} \iappname{makeglossaries}
\end{codeS}
If you are using \iappname{latexmk}, then make sure you have added
the custom dependencies for \texttt{.gls} as described in
\sectionref{sec:latexmk}. If you are not using any automated tool to
build your document, you will have to invoke
\iappname{makeglossaries} between (PDF)\LaTeX\ runs (see
\sectionref{sec:build}).

Adding to \listingref{ex:thesis-index}:
\begin{codelisting}{thesis-glossaries.tex}\label{ex:thesis-glossaries}
\begin{alltt}
\glsni{percentchar} In the preamble:
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} biber
\glsni{percentchar.arara} \iappname{makeglossaries}
\glsni{percentchar.arara} makeindex
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{oneside,12pt}\marg{scrbook}

\glsni{usepackage}\oarg{toc,acronym}\marg{glossaries}

\glsni{newglossary}\oarg{nlg}\marg{notation}\marg{not}\marg{ntn}\marg{Notation}

\gls{makeglossaries}

\glsni{newglossaryentry}\marg{matrix}\glsni{percentchar} the label
\marg{name=\marg{matrix},\glsni{percentchar} the term
 description=\marg{a rectangular table of elements},\glsni{percentchar} brief description
 plural=\marg{matrices}\glsni{percentchar} the plural
}

\glsni{newacronym}\marg{svm}\marg{SVM}\marg{support vector machine}

\gls{newglossaryentry}\marg{not:set}\glsni{percentchar} label
\marg{\glsni{percentchar}
  type=notation,\glsni{percentchar} glossary type
  name=\marg{\glsni{dollarchar}\gls{mathcal}\marg{S}\glsni{dollarchar}},\glsni{percentchar}
  description=\marg{A set},\glsni{percentchar}
  sort=\marg{S}\glsni{percentchar}
}

\glsni{percentchar} Later in the document:

\end{alltt}
\gls{Glspl}\marg{matrix} are usually denoted by a bold capital
letter, such as \glsni{dollarchar}\glsni{mathbf}\marg{A}\glsni{dollarchar}. The \gls{gls}\marg{matrix}\oarg{'s}
\glsni{dollarchar}(i,j)\glsni{dollarchar}th element is usually
denoted
\glsni{dollarchar}a\gls{underscorechar}\marg{ij}\glsni{dollarchar}.
\gls{Gls}\marg{matrix}
\glsni{dollarchar}\glsni{mathbf}\marg{I}\glsni{dollarchar} is the
identity \gls{gls}\marg{matrix}.\newline
\mbox{}\newline
First use: \gls{gls}\marg{svm}\gls{at}. Next use: 
\gls{gls}\marg{svm}\glsni{at}.
Short: \gls{acrshort}\marg{svm}\glsni{at}.
Long: \gls{acrlong}\marg{svm}.
Full: \gls{acrfull}\marg{svm}\glsni{at}.\newline
\mbox{}\newline
A \gls{gls}\marg{not:set} is a collection of objects.
\begin{alltt}

\glsni{percentchar} At the end of the document:

\glsni{backmatter}

\glsni{printglossaries}
\end{alltt}
\end{codelisting}

\setnode{glossariestroubleshooting}
\subsubsection{Troubleshooting}
\label{sec:glossariestroubleshooting}

If you run into difficulties with the \isty{glossaries} package,
first consult the \htmladdnormallinkfoot{glossaries
FAQ}{http://www.dickimaw-books.com/faqs/glossariesfaq.html}\@.
You can also check my \htmladdnormallinkfoot{bug
tracker}{http://www.dickimaw-books.com/cgi-bin/bugtracker.cgi?category=glossaries}
if you think you've stumbled on a~bug. If you are using TeXnicCenter
instead of TeXworks, there are instructions on how to get
TeXnicCenter to run \iappname{makeglossaries} in an article I~wrote
on the \LaTeX\ Community's Know How
section~\cite{latexcommunitygloss}.

If you're completely confused about how to generate the glossary
files, you might want to consider using \sty{datagidx} instead,
described \htmlref{next}{sec:datagidx}.

% Using datagidx

\setnode{datagidx}
\section{Using \LaTeX\ to Sort and Collate Indexes or Glossaries
(\sty{datagidx} package)}
\label{sec:datagidx}

\sectionref{sec:makeindexglos} described how to create an index or
glossaries using an external indexing application. Some users
stumble when it comes to invoking the indexing application. There is
an alternative where \TeX\ does the sorting and collating. This
by-passes the need to use \iappname{makeindex}, \iappname{xindy} or
\iappname{makeglossaries}, but it's less efficient and takes longer
to build your document. This section describes how to do this using
the \isty{datagidx} package. This package comes with my
\isty{datatool} bundle (at least version 2.13). The documentation
for \sty{datagidx} is included in the \sty{datatool} user
manual~\cite{datatool}.

The \sty{datatool} package allows you to define databases that you
can access in your document. The \sty{datagidx} package has a~special
interface to this facility that allows you to define databases for
the purposes of indexing. These databases and their definitions must
be defined in the preamble. In this section, the term \dq{indexing}
will be used to refer to either indexes or glossaries, as the same
mechanism is used for both tasks.

A new indexing database is defined using:
\begin{definition}
\gls{newgidx}\marg{\meta{label}}\marg{\meta{title}}
\end{definition}
where \meta{label} is a~label that uniquely identifies this database
and \meta{title} is the title to be used when the index (or
glossary) is displayed. For example:
\begin{codeS}
\glsni{newgidx}\marg{index}\marg{Index}
\end{codeS}
creates a~new database labelled \texttt{index}. When the index is
displayed, it will have the section heading \dq{Index}.

As in \sectionref{sec:makeindexglos}, each term in the index (or
glossary) database has an associated location list. This list is
initially null. The locations are added to terms used in the
document on \emph{the second} \LaTeX\ run. When you display the
index, only those entries with a~non-null location list or a
cross-reference will be shown. The default location is the page
number on which the entry was referenced. The \sty{datagidx} package
knows about the following page numbering styles: \texttt{arabic},
\texttt{roman}, \texttt{Roman}, \texttt{alph} and \texttt{Alph}. If
your document has another type of numbering style, or if you want to
use a~different counter for the location, consult the \sty{datagidx}
section of the \sty{datatool} manual~\cite{datatool}.

Once you have defined the indexing database, you can now define
terms associated with that database using
\begin{definition}
\gls{newterm}\oarg{\meta{options}}\marg{\meta{name}}
\end{definition}
where \meta{name} is the term and \meta{options} is a~list of
\meta{key}=\meta{value} options. The following keys are available:
\begin{itemize}

 \item \ikeyvalopt{newterm}{database}

 Identifies the database in which to store this term. For example:
\begin{definition}
\glsni{newterm}\oarg{database=index}\marg{eigenvalue}
\end{definition}
It can be somewhat cumbersome having to type the database for each
new term. Instead you can define the default database using:
\begin{definition}
\gls{DTLgidxSetDefaultDB}\marg{\meta{label}}
\end{definition}
For example:
\begin{code}
\begin{alltt}
\glsni{newgidx}\marg{index}\marg{Index}
\glsni{DTLgidxSetDefaultDB}\marg{index}

\glsni{newterm}\marg{eigenvalue}
\glsni{newterm}\marg{eigenvector}
\end{alltt}
\end{code}

 \item \ikeyvalopt{newterm}{label}

A label uniquely identifying this
term. If omitted the label is extracted from \meta{name}.

 \item \ikeyvalopt{newterm}{sort} 

The sort key. If omitted this is extracted from \meta{name}.

 \item \ikeyvalopt{newterm}{parent}

The parent entry, if this is a~sub-term. (The value should be the
label identifying the parent, which must already be defined.)

 \item \ikeyvalopt{newterm}{text}

How the entry should appear in the document text. If omitted,
\meta{name} is used. If present, \meta{name} indicates how the term
should appear in the index\slash glossary.

 \item \ikeyvalopt{newterm}{description}

An optional associated description.

 \item \ikeyvalopt{newterm}{plural}

The plural form of this term. If omitted this value is obtained by
appending \dq{s} to \meta{name} (or the value of \keyvalopt{text} if
supplied).

 \item \ikeyvalopt{newterm}{symbol}

An optional associated symbol.

 \item \ikeyvalopt{newterm}{short}

An associated short form, if required. (Defaults to \meta{name} if
omitted.)

 \item \ikeyvalopt{newterm}{long}

An associated long form, if required. (Defaults to \meta{name} if
omitted.)

 \item \ikeyvalopt{newterm}{shortplural}

The plural of the associated short form. If omitted, the value is
obtained by appending \dq{s} to the short form.

 \item \ikeyvalopt{newterm}{longplural}

The plural of the associated long form. If omitted, the value is
obtained by appending \dq{s} to the long form.

 \item \ikeyvalopt{newterm}{see}

A cross-reference to a~synonym. The value should be the label of
another entry. This entry will not have a~location list, just the
reference to the other term.

 \item \ikeyvalopt{newterm}{seealso}

A cross-reference to a~closely related term. Both this term and the
cross-referenced term should have a~location list.

\end{itemize}
It's also possible to add your own custom keys. See the
\sty{datagidx} section of the \sty{datatool} user
guide~\cite{datatool} for further details.

As with \gls{newglossaryentry}, discussed in
\sectionref{sec:newglossaryentry}, if the term starts with an
accented letter (or a~ligature) the letter must be grouped.

\xminisec{Example:}\label{ex:elite}

\begin{code}
\begin{alltt}
\glsni{newterm}\oarg{label=elite,sort=elite}\marg{\marg{\'{e}}lite}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   plural=\marg{\marg{\oe}sophagi},
   label=\marg{oesophagus},
   sort=\marg{oesophagus},
   description=\marg{tube connecting throat and stomach}
 }
 \marg{\marg{\oe}sophagus}
\end{alltt}
\end{code}

There is a~shortcut command for defining acronyms:
\begin{definition}
\gls{newacro}\oarg{\meta{options}}\marg{\meta{short}}\marg{\meta{long}}
\end{definition}
where \meta{short} is the abbreviation and \meta{long} is the long
form. The optional argument \meta{options} is the same as for 
\glsni{newterm}. This is equivalent to:
\begin{alltt}
\glsni{newterm}
 \oarg{\glsni{percentchar}
   description=\marg{\glsni{capitalisewords}\marg{\meta{long}}},\glsni{percentchar}
   short=\marg{\glsni{acronymfont}\marg{\meta{short}}},\glsni{percentchar}
   long=\marg{\meta{long}},\glsni{percentchar}
   text=\marg{\glsni{DTLgidxAcrStyle}\marg{\meta{long}}\marg{\glsni{acronymfont}\marg{\meta{short}}}},\glsni{percentchar}
   plural=\marg{\glsni{DTLgidxAcrStyle}\marg{\meta{long}s}\marg{\glsni{acronymfont}\marg{\meta{short}s}}},\glsni{percentchar}
   sort=\marg{\meta{short}},\glsni{percentchar}
   \meta{options}\glsni{percentchar}
 }\glsni{percentchar}
 \marg{\glsni{MakeTextUppercase}\marg{\meta{short}}}
\end{alltt}
where
\begin{definition}
\gls{DTLgidxAcrStyle}\marg{\meta{long}}\marg{\meta{short}}
\end{definition}
formats the full version of the acronym. This defaults to:
\meta{long} (\meta{short}), and
\begin{definition}
\gls{acronymfont}\marg{\meta{text}}
\end{definition}
is the font used to format acronyms. By default this just displays
its argument, but can be redefined if you want the acronyms
formatted in a~particular style or font (such as small-caps).
The other commands used above are:
\begin{definition}
\gls{MakeTextUppercase}\marg{\meta{text}}
\end{definition}
This is defined by the \isty{textcase} package and converts
\meta{text} to uppercase.
\begin{definition}
\gls{capitalisewords}\marg{\meta{text}}
\end{definition}
This is defined by the \isty{mfirstuc} package and capitalises the
first letter of each word in \meta{text}.

\xminisec{Example:}\label{ex:svm}

\begin{codeS}
\glsni{newacro}\marg{svm}\marg{support vector machine}
\end{codeS}

Once you have defined the terms in the preamble, you can later use
them in the document:
\begin{definition}
\gls{datagidx.gls}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.glspl}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.Gls}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.Glspl}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
These are similar to those described in \sectionref{sec:glslink},
but they have a~different syntax. Here \meta{format} is the name of
a~text-block commands (such as \gls{textbf}) \emph{without}
the initial backslash that should be used to format the location for
this reference. This is analogous to the \gls{index.barchar}
special character described in \sectionref{sec:makeindexformat}.

There are also commands associated with acronyms:
\begin{definition}
\gls{datagidx.acr}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.acrpl}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.Acr}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\begin{definition}
\gls{datagidx.Acrpl}\marg{\oarg{\meta{format}}\meta{label}}
\end{definition}
\warning
Unlike the \isty{glossaries} package, described in
\sectionref{sec:makeglossaries}, there is a~difference between
\isty{datagidx}'s \glsni{datagidx.gls} and \glsni{datagidx.acr}.
Here \glsni{datagidx.gls} will always display the value of the
\ikeyvalopt{newterm}{text} field, whereas \glsni{datagidx.acr} will
display the full form on first use (the \ikeyvalopt{newterm}{text}
field) and the abbreviation on subsequent use (the
\ikeyvalopt{newterm}{short} field).

You can also add terms to the index without creating any link text:
\begin{definition}
\gls{datagidx.glsadd}\marg{\meta{label}}
\end{definition}
This adds the term uniquely identified by \meta{label}.
\begin{definition}
\gls{datagidx.glsaddall}\marg{\meta{database name}}
\end{definition}
This adds all the terms defined in the database uniquely identified
by \meta{database name}.

\xminisec{Note:}

\warning Unlike most commands, the optional part of the above
commands occurs \emph{inside} the mandatory argument.

\xminisec{Examples:}

Given the \texttt{elite} and
\texttt{oesophagus} examples defined \xpageref{earlier}{ex:elite}, I~can reference those entries in the text as
follows:
\begin{codeS}
\gls{datagidx.Gls}\marg{elite} and
\gls{datagidx.glspl}\marg{oesophagus}.
\end{codeS}
This produces:
\begin{resultS}[Elite and oesophagi]
\'{E}lite and \oe sophagi.
\end{resultS}
Elsewhere, I~might have the main topic about \oe sophagi:
\begin{code}
The \gls{datagidx.gls}\marg{\oarg{textbf}oesophagus} connects
the throat and the stomach.
\end{code}
This produces:
\begin{resultS}[The oesophagus connects the throat and the stomach.]
The \oe sophagus connects the throat and the stomach.
\end{resultS}
and the associated location will be typeset in bold.

Here's an example using the \texttt{svm} example defined
\xpageref{earlier}{ex:svm}:
\begin{code}
First use: \gls{datagidx.acr}\marg{svm}\gls{at}.
Subsequent use: \gls{datagidx.acr}\marg{svm}\glsni{at}.
Full form:  \gls{datagidx.gls}\marg{svm}.
\end{code}
This produces:
\begin{result}[datagidx-svm.html]
First use: support vector machine (SVM)\@.
Subsequent use: SVM\@.
Full form: support vector machine (SVM).
\end{result}

You can unset and reset acronyms using
\begin{definition}
\gls{glsunset}\marg{\meta{label}}
\end{definition}
and
\begin{definition}
\gls{glsreset}\marg{\meta{label}}
\end{definition}

To display the index or glossary or list of acronyms use:
\begin{definition}
\gls{printterms}\oarg{\meta{options}}
\end{definition}
where \meta{options} is a~comma-separated \meta{key}=\meta{value} list.
Common options are:
\begin{itemize} 

 \item \ikeyvalopt{printterms}{database}

 The label uniquely identifying the database containing the relevant
terms.

 \item \ikeyvalopt{printterms}{postdesc}

 This may have the value \optfmt{dot} (put a~full stop after the
description, if there is a~description) or \optfmt{none} (don't put
a~full stop after the description).

 \item \ikeyvalopt{printterms}{columns}

 This value must be an integer greater than or equal to 1,
indicating the number of columns for the page layout.

 \item \ikeyvalopt{printterms}{style}

 The style to use. There are a~number of predefined styles, such as
\texttt{index} or \texttt{gloss}. See the user guide~\cite{datatool}
for further details.

 \item \ikeyvalopt{printterms}{namecase}

 Indicates whether any case change should be applied to the entry's
name. Available values are: \optfmt{nochange} (no change),
\optfmt{uc} (convert to uppercase), \optfmt{lc} (convert to lower
case), \optfmt{firstuc} (convert the first letter to uppercase)
and \optfmt{capitalise} (capitalise each initial letter using
\gls{capitalisewords}).

\end{itemize}
For a~full list of options see the \sty{datagidx} section of the
\sty{datatool} user guide~\cite{datatool}.

\listingref{ex:thesis-glossaries} can now be rewritten as follows:
\begin{codelisting}{thesis-datagidx.tex}
\begin{alltt}
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} biber
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{percentchar.arara} pdflatex: \marg{ synctex: on }
\glsni{documentclass}\oarg{oneside,12pt}\marg{scrbook}

\glsni{usepackage}\marg{datagidx}

\glsni{newgidx}\marg{index}\marg{Index}
\glsni{newgidx}\marg{glossary}\marg{Glossary}
\glsni{newgidx}\marg{acronym}\marg{Acronyms}
\glsni{newgidx}\marg{notation}\marg{Notation}

\glsni{DTLgidxSetDefaultDB}\marg{glossary}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   description=\marg{a rectangular table of elements},\glsni{percentchar} brief description
   plural=\marg{matrices}\glsni{percentchar} the plural
 }%
 \marg{matrix}% the name

\glsni{DTLgidxSetDefaultDB}\marg{acronym}

\glsni{newacro}\marg{svm}\marg{support vector machine}

\glsni{DTLgidxSetDefaultDB}\marg{notation}

\glsni{newterm}
 \oarg{\glsni{percentchar}
  label=\marg{not:set},\glsni{percentchar} label
  description=\marg{A set},\glsni{percentchar}
  sort=\marg{S}\glsni{percentchar}
 }\glsni{percentchar}
 \marg{\gls{ensuremath}\marg{\gls{mathcal}\marg{S}}}

\glsni{DTLgidxSetDefaultDB}\marg{index}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   label=\marg{function},\glsni{percentchar}
   text=\marg{function}\glsni{percentchar}
 }\glsni{percentchar}
 \marg{functions}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   see=\marg{sqrt},\glsni{percentchar}
 }\glsni{percentchar}
 \marg{square root}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   label=\marg{fn.sqrt},
   parent=\marg{function}
 }\glsni{percentchar}
 \marg{\glsni{texttt}\marg{sqrt()}}

\glsni{newterm}
 \oarg{\glsni{percentchar}
   label=\marg{sqrt},
 }\glsni{percentchar}
 \marg{\texttt{sqrt()}}

\glsni{newterm}\marg{tautology}
\glsni{newterm}\marg{contradiction}

\glsni{percentchar} later in the document:

\end{alltt}
\glsni{datagidx.Glspl}\marg{matrix} are usually denoted by a~bold capital letter, such as
\glsni{dollarchar}\glsni{mathbf}\marg{A}\glsni{dollarchar}. 
The \glsni{datagidx.gls}\marg{matrix}'s
\glsni{dollarchar}(i,j)\glsni{dollarchar}th element is usually
denoted
\glsni{dollarchar}a\glsni{underscorechar}\marg{ij}\glsni{dollarchar}.
\glsni{datagidx.Gls}\marg{matrix}
\glsni{dollarchar}\glsni{mathbf}\marg{I}\glsni{dollarchar} is the identity
\glsni{datagidx.gls}\marg{matrix}.\newline
\mbox{}\newline
First use: \gls{datagidx.acr}\marg{svm}\glsni{at}. 
Next use: \gls{datagidx.acr}\marg{svm}\glsni{at}.
Full: \gls{datagidx.gls}\marg{svm}\glsni{at}.\newline
\mbox{}\newline
A \gls{datagidx.gls}\marg{not:set} is a~collection of
objects.\newline
\mbox{}\newline
\ldots\newline
\mbox{}\newline
Some sample code is shown in
Listing\glsni{tildechar}\glsni{ref}\marg{lst:sample}.
This uses the function
\gls{datagidx.gls}\marg{fn.sqrt}.\gls{datagidx.glsadd}\marg{sqrt}\newline
\mbox{}\newline
\ldots\newline
\mbox{}\newline
\glsni{begin}\marg{Definition}\oarg{Tautology}\newline
A \glsni{emph}\marg{\glsni{datagidx.gls}\marg{\oarg{textbf}tautology}} is a~proposition
that is always true for any value of its variables.\newline
\glsni{end}\marg{Definition}\newline
\mbox{}\newline
\glsni{begin}\marg{Definition}\oarg{Contradiction}\newline
A \glsni{emph}\marg{\gls{datagidx.gls}\marg{\oarg{textbf}contradiction}} is a
proposition that is always false for any
value of its variables.\newline
\glsni{end}\marg{Definition}
\begin{alltt}

\glsni{percentchar} At the end of the document:
\glsni{backmatter}

\glsni{printterms}\oarg{database=glossary}
\glsni{printterms}\oarg{database=acronym}
\glsni{printterms}\oarg{database=notation}

\glsni{printbibliography}

\glsni{printterms}\oarg{database=index}
\end{alltt}
\end{codelisting}

Note that there is now no need to call either \iappname{makeindex}
or \iappname{makeglossaries}. The only external application 
being called is \iappname{biber} for the bibliography.

\appendix

\setnode{generaladvice}
\chapter{General Advice}
\label{ch:generaladvice}

If you encounter any \LaTeX\ problems, check 
\latexhtml{Appendix~\ref{nov-ch:errors} (Common Errors)
and Appendix~\ref{nov-ch:help} (Need More Help?) in \latexnovices.}{%
\xrsectionref{Common Errors}{commonerrors} and
\xrsectionref{Need More Help?}{help}}

\setnode{toomanyunprocessedfloats}
\section{Too Many Unprocessed Floats}
\label{sec:toomanyunprocessedfloats}

A common problem PhD student's encounter when writing a~thesis is
the \dq{too many unprocessed floats} error.\faq{Too many unprocessed
floats}{tmupfl} This is usually caused by having too many figures
and tables in the results chapter and not enough surrounding text.
If this happens, there are a~number of things you can try doing:
\begin{enumerate}

 \item Make sure you haven't been too restrictive in where you want
your floats to go. If you use a~placement specifier, give LaTeX as
many options as possible. For example:
\begin{codeS}
\glsni{begin}\marg{figure}\oarg{htbp}
\end{codeS}
which indicates that the figure can be placed \dq{here}
(\texttt{h}), at the top of a~page (\texttt{t}), at the bottom of
the page (\texttt{b}) or on a~page solely consisting of floats
(\texttt{p}). If you just use the \texttt{h} placement specifier
then you are stating: \dq{I~want it \emph{here} and \emph{nowhere
else}!} If \TeX\ can't put it \emph{exactly here}, then you have
given no alternative place to put it, and it won't get placed
anywhere, unless a~\gls{clearpage} command is issued, at which point
all remaining unprocessed floats will be dumped at that point. If
you are determined that an image must be placed \emph{exactly here}
then it should not be placed in a~floating environment. 

\item Try increasing the amount of text in the chapter. Remember
that you should never simply print all the figures and tables in a
results chapter without discussing them to some extent.

\item If all else fails, try using the \glsni{clearpage} command. This
forces all unprocessed floats to be processed immediately, and start
a~new page. This may result in the page ending prematurely, if you
wish to avoid this, you can use the \isty{afterpage} package, and
use the command: 
\begin{codeS}
\gls{afterpage}\marg{\gls{clearpage}}
\end{codeS}
\end{enumerate}
For other problems, check the FAQ~\cite{ukfaq}.

\setnode{thesiswritingadvice}
\section{General Thesis Writing Advice}
\label{sec:thesiswritingadvice}

This section is not specific to \LaTeX. Some of the points have
already been mentioned in asides or footnotes. Remember that each
college or university or even school within a~university may have
different requirements, and requirements will also vary according to
country, so some of this advice may not apply to you. I~am writing
from the point of view of an English scientist, and am basing it on
my own experience and on the comments of English science-based PhD
examiners and supervisors. I~cannot guarantee that your own
department or university will agree with them. \emph{If in doubt,
check with your supervisor.}
\begin{enumerate}

\item Find out the thesis style requirements from your supervisor or
your department's website. Many universities still require
\htmlref{double-spaced}{sec:setspace}, single-sided documents 
with \htmlref{wide margins}{geometry}.
Double-spacing is by and large looked down on in the world of
typesetting, but this requirement for a~PhD thesis has nothing to do
with \ae sthetics or readability. In England the purpose of the PhD
viva is to defend your work\footnote{I~gather this is not the case
in some other countries, where the viva is more informal, and the
decision to pass or fail you has already been made before your viva.}. Before your viva, paper copies of
your thesis are sent to your examiners. The double spacing and wide
margins provide the examiners room to write the comments and
criticisms they wish to raise during the viva, as well as any
typographical corrections. Whilst they could write these comments on
a~separate piece of paper, cross-referencing the page in
the thesis, it is more efficient for the comments to actually be on
the relevant page of the thesis. That way, as they go through the
manuscript during your viva, they can easily see the comments,
questions or criticisms they wish to raise alongside the
corresponding
text. If you present them with a~single-spaced document with narrow
margins, you are effectively telling them that you don't want them
to criticise your work!

\item Don't try to pad your thesis with irrelevant information. This
includes adding items in your bibliography that are not referenced
in the text, adding figures or tables that are not explained in the
text, and supplying all the source code you have written. The
outcome of your viva will not depend on the physical size of your
thesis, but on the clarity of your writing and on the quality of
your work.

\item Clearly delineate your thesis through the use of chapters and
sections, outlining your original aims and objectives, an overview
of the subject matter including references to other people's work in
the area, the methods you employed to extend or innovate the field,
your results and conclusions. 

\item Make sure your references include some recent journal or
conference papers to illustrate that you are aware of new
developments in your field. Remember that due to the nature of
publishing, most books are dated by the time they reach the book
shelves. Journal and conference papers are likely to be more
up-to-date\footnote{Having said that, I~know someone who submitted
an article to a~journal, and it took three and a~half years before
the reviewers came back with comments. In the end, the author
withdrew the manuscript because by that time the topic was out of
date.}.

\item Always explain acronyms, technical terms and symbols. It is a
good idea to include a~glossary of terms, list of notation or list
of acronyms to avoid confusion (see \chapterref{ch:indgloss}).

\item If you have equations, make sure you explain the variables
used, and how you go from one equation to the next. Depending on
your field, you might also consider clarifying the mathematics by
providing graphical representations of the equations\footnote{When I
was a~PhD student, I~was once rendered speechless when asked to
provide a~graphical illustration of an equation involving a
quadruple summation that had no graphical meaning from my point of
view. Perhaps this was a~drawback of being a~mathematician doing a
PhD in an electronics department.}.

\item If you include any graphs, bar charts, pie charts or any other
form of data plot, make sure it is clearly labelled and no
distortion is introduced (such as using three-dimensional bar charts
or pie charts\footnote{The sole purpose of 3D pie charts or bar
charts appears to be to look pretty and impress people who have no
understanding of mathematics.}.) 

\item If you have used a~computer application to generate numerical
results, make sure you have some understanding of the underlying
process and what the results mean. This doesn't necessarily mean
that you need to understand complex computer code, or complex
algorithms, but what you shouldn't do is say something along the
lines of, \dq{well, I~clicked on this button, and it said $m=0.678$.}
What is the purpose of the button? What does $m$ represent? What
does the result $ m=0.678$ signify? What value were you expecting or
hoping to get? Numbers on their own are meaningless. If I~ran into a
room shouting \dq{I've got 42!} What does that mean? Forty-two what?
Forty-two brilliant reviews? (Great!) Forty-two percent in an exam?
(Not good.) Forty-two spots on my face? (Very bad!) 

\item\label{itm:gcc1} Don't waste time worrying about the best way
to word your thesis in your first draft. Write first, then edit it
later or you will never get started. 

\item\label{itm:gcc2} If your supervisor offers to critique chapters of
your thesis, don't say no! Such offers are not made
out of politeness, but a~desire to ensure that you pass. Don't be
embarrassed and worry that it's not good enough, that's the whole
point in your supervisor helping you improve it\footnote{but don't
expect your supervisor to actually write your thesis!}. 

\item Write in a~clear concise manner. A thesis is a~technical
document, not a~novel, so don't be tempted to write something along
the lines of: \dq{I~awaited with bated breath, my whole body quivering
with excitement at the eager anticipation that my algorithm would
prove superior to all others, and, oh joy, my experiments proved me
right.} 

\item Don't decorate your thesis with irrelevant clip art. It is
unprofessional and highly inappropriate in the sciences.

\item Make regular backups of your work. Be prepared for any of the
following: accidentally deleting your thesis, accidentally
overwriting your thesis with another file, software failure,
hardware failure, viruses, fire and theft. Consider using at least
a~two-tier system where you keep one backup in a safe place where
you live and ask a close relative or friend to take care of another backup.

\end{enumerate}
Items~\ref{itm:gcc1} and~\ref{itm:gcc2} above were supplied by
Dr~Gavin Cawley\footnote{School of Computing Sciences, University of
East Anglia} who has been both a~PhD supervisor and examiner. 

\backmatter

\clearpage\phantomsection
\setnode{bibliography}
\bibliographystyle{plain}
\bibliography{thesis}

\setnode{acronyms}
\printglossary[type=acronym,nonumberlist,style=acronyms]

\setnode{summary}
\setdoublecolumnglo
\printglossary[style=summary]

\setnode{bookindex}
\printindex

\setnode{licence}
\chapter{GNU Free Documentation License}
\input{../fdl}

\setnode{history}
\chapter{History}\markright{History}

\historyitem{\protect\bookdocdate\ (Version 1.3)}

\begin{itemize}
 \item Added recap on building the document.
 \item Added sections on \appname{latexmk} and \appname{arara}.
 \item Changed examples to use KOMA.
 \item Added sections on \appname{jabref}, \sty{natbib} and \sty{biblatex}.
 \item Added information about the \sty{listings}, \sty{siunitx},
  \sty{amsthm}, \sty{ntheorem} and \sty{algorithm2e} packages.
 \item Added section on \sty{datagidx} to the chapter on indexes and
glossaries.
 \item Added summary section.
 \item Some sections have been reordered.
 \item Removed section on modifying textual tags such as
\cmdname{contentsname} (now in Volume~1).
\end{itemize}

\backcoverheading
(See \url{http://www.gnu.org/licenses/fdl-howto-opt.html#SEC2}.)

\backcovertext

\end{document}

