\section{$M/M/c$ queue and variants}
\label{sec:MMC}

\subsection{$M/M/c$ queue}

One of the simplest system that can be modeled with the
library is a
call center with a single call type, and a single agent group having a fixed
capacity~$c$, i.e., a $M/M/c$ queue with FIFO discipline.
This model is implemented for demonstration purposes only since
simple formulas are available to compute the average
waiting time, the average queue length, etc. \cite{pKLE75a}
It could also be implemented without ContactCenters, as shown in the
Examples user's guide of SSJ \cite{iLEC04j}.

Arrivals
follow an homogeneous Poisson process with rate
$\lambda$, and customers
are queued if they cannot be served immediately.  Abandonment is not
allowed and service times are i.i.d.\ exponential variables with mean~$1/\mu$.

The
system estimates
the service level, the expected speed of answer,
and the agents' occupancy ratio.
Let $\Sg(s)$ be the number of
served contacts
having waited in queue for less than an \emph{acceptable waiting time}
$s$, and let $S$
be the total number of served contacts.
Since no abandonment occurs, this is equivalent to
the number of arrivals.
 Let $\WS$ be the sum of waiting times for
served contacts.
The \emph{service level} is defined by
\begin{equation}
g_0(s)=\frac{\E[\Sg(s)]}{\E[S]}.\label{eq:slnoab}
\end{equation}
The \emph{speed of answer} is defined by
\begin{equation}
w_{\mathrm{X}}=\frac{\E[\WS]}{\E[S]}.\label{eq:sans}
\end{equation}
The \emph{agents' occupancy ratio} is defined by
\begin{equation}
o=\frac{\E\left[\int_0^{t_P} \Nb(t)\ dt\right]}{\E\left[\int_0^{t_P}
    (N(t)+\Ng(t)) dt\right]}.\label{eq:occ}
\end{equation}
$t_P$ corresponds to the time at which the contact center closes.
$\Ng(t)$ gives the number of \emph{ghost agents}, i.e.,
agents that must exit the system after finishing their current
service.  Since ghost agents appear only when $N(t)$ changes with time,
$\Ng(t)=0$ for this model.
To get an estimate of each performance measure of interest, we perform
$n$ independent replications of a simulation on a
finite horizon.

Most elements of the contact center simulator are
provided by the ContactCenters library as independent components.
The modeler's task consists of assembling these elements and
providing some glue code for statistical collecting, routing and stopping
conditions, some elements being optional.
For this example, whose code is presented on Listing~\ref{lst:MMC},
simpler programs can be written, especially
if the library is not used.  However,
we prefer to demonstrate how to balance simplicity and scalability in
a contact center simulation.

The first part of the program defines and constructs various objects
while the second part contains the simulation logic. The \texttt{main}
method, at the end of the file, constructs a $M/M/c$ queue simulator,
triggers a
simulation by calling \texttt{simulate}, and prints a statistical
report using \texttt{print\-Statistics}.  A \texttt{Chrono} is used to
determine the CPU time taken by the simulation.
The \texttt{simulate} method calls
\texttt{simulate\-One\-Day} $n$ times to perform the
replications while \texttt{simulate\-One\-Day} initializes the system,
performs the simulation, and collects some observations.

\lstinputlisting[
caption={A $M/M/c$ queue implemented with ContactCenters},%
emph={main,simulateOneDay,MyContactFactory,MyContactMeasures},
label=lst:MMC
]
{MMC.java}

At the beginning of the program, the necessary classes are retrieved
using \texttt{import} statements, and
a class named \texttt{MMC} and representing the simulator is declared.
Because variants of this example will be presented later as subclasses of
\texttt{MMC}, some indirections that might appear
unnecessary will be used in the program.

In this example and most of the following ones, hard-coded constants are
used as
input data for simplicity.  In general, it is strongly
recommended to use a parameter file, since it allows modification of
the parameters without recompiling the simulator.  The package
\path{umontreal.iro.lecuyer.xmlconfig} provides facilities to support
XML-based configuration files.  As with the underlying SSJ library,
the simulation
logic of ContactCenters makes no assumption about the time unit, but
input data should be defined consistently to avoid confusion in the
future.  In our examples, unless specified otherwise, the time
unit is the minute.  For example, the arrival rate specifies the
expected number of contacts per minute.

The objects representing components of the contact center, such as
the arrival process, waiting queue, agent group, as well as
the random variate generator for the service times can be accessed
through fields of the \texttt{MMC} class.
Since the components themselves do not compute any statistic, the
simulator defines some counters and statistical collectors to estimate
the performance measures of interest.
Counters are used during replications to compute observations while
statistical collectors are used at the end to collect them.
We use integers for counting events
rather than statistical probes to clearly show the difference between
the two steps during the simulation.
\texttt{vstat} is used to compute the integrals of the number of
agents over simulation time, for estimating the occupancy ratio.
Each agent group volume statistical object contains accumulates
observing the
total number of agents, the number of busy agents, etc.\ for a single
agent group.
For each counter, a statistical probe is defined to collect the
observations computed during each replication.

When instantiating the \texttt{MMC} class, the constructor, shown
after the declaration of fields, creates
the contact center objects and connects them together.
Inbound contacts are simulated using an arrival process which needs
to determine how to construct contacts.
Contacts are represented by \texttt{Contact} instances which are
constructed by a \emph{factory}, i.e.,
a mechanism permitting the instantiation of objects from the
\texttt{Contact} class, or any subclass.
In contrast, a constructor instantiates objects from a
single class.  A contact factory is defined by creating a class
implementing the \texttt{Contact\-Factory} interface.  The
\texttt{new\-Instance}
method, specified by this interface, must construct and return an
initialized instance of \texttt{Contact} (or any subclass of
\texttt{Contact}).  In this example, \texttt{My\-Contact\-Factory}
creates the contacts and sets their service times.

Arrival processes of different types could use the same contact
factory, but in this example, a single Poisson process is needed.
In addition to the contact factory, the process requires a
random stream for generating the exponential inter-arrival times, and
an arrival rate.

Constructing the agent group only requires the number of agents in
it.
This object manages the service of contacts and keeps counters for the
number of free and busy agents.  All agents of a group are usually
considered identical, simplifying the routing significantly.
The agent group automatically schedules events to manage service
termination if service times are associated with handled contacts.

The constructed standard waiting queue
orders waiting contacts based on their arrival times only,
implementing \emph{First In First Out} (FIFO) or \emph{Last In First
  Out} (LIFO) disciplines; the choice between FIFO and LIFO is made by
the routing policy.

The router uses a queue priority policy, but in
fact, any routing policy will act identically here since there is a
single call type and a single agent group.  The only important parameters
are the type-to-group and group-to-type maps which are always the same
for a single-type and single-group contact center.
To maximize the flexibility of the
library, no assumption is made about the connections between
components.  Arrival processes, agent groups,
and waiting queues must be manually connected
to the router.

The components of the library communicate using the \emph{observers} design pattern
\cite{iGAM98a}.  In that setting, an \emph{observable}
object, also called a \emph{broadcaster}, is
capable of transmitting some information to a list of registered
listeners known at runtime only.
A \emph{listener}, also called an \emph{observer}, is an object
receiving information
broadcast by an observable object.
In Java, listeners are required to implement a particular interface the
broadcaster uses to transmit the information through specified
methods.
Each component of the library defines its own listener interface to
avoid the necessity of type casting by observers.

Each time
a new contact is created by the factory and returned to the arrival
process, it is broadcast to a list of registered \emph{new-contact
  listeners}.  Such a listener can correspond to any object
implementing the \texttt{New\-Contact\-Listener} interface, which
specifies a \texttt{new\-Contact} method receiving \texttt{Contact}
objects.  For the contacts to be processed, the list bound to the
arrival process being used
must include a reference to the router, which can listen to new
contacts.

While it
does not interact with the arrival process, the router affects the
waiting queue by inserting new contacts when they cannot be served
immediately, or by
pulling ones when agents are free.  It also affects agent
groups by sending them contacts to serve.  The linking mechanism is
different from arrival processes
to emphasize the two types of relationships.

The simulator also needs to be notified
about contacts leaving the router through an
\emph{exited-contact listener}.  Such a listener object implements an
interface called \texttt{Exited\-Contact\-Listener} specifying methods
to receive exited contacts.  Each method transmits all available
information, permitting the simulator to count events under complex
conditions.

These
connections can easily be changed during the life cycle of the
simulator:  new listeners can be added, and old ones can be removed.
It is even possible, with some care, to completely replace the router
at runtime, allowing different routing policies to be tested without
recreating the entire system.

The \texttt{simulate} method initializes the statistical collectors
and performs $n$ independent replications by using
\texttt{simulate\-One\-Day}.  The latter method may be considered as
the heart of the program.  First, the simulation clock is initialized, and
the event list is cleared by \texttt{Sim.init}.  An event for the end
of the day is then scheduled, and
all the contact center's components are reset, avoiding
any side effect from previous replications.  This initialization
disables the arrival
process.  Then, after the event
counters are reset to 0, the arrival process is started, scheduling
the first contact.  The simulation can now be started using
\texttt{Sim.start}.  This instructs SSJ to start executing events,
until the event list is empty.

When the first arrival occurs, the Poisson arrival process calls the
\texttt{new\-Instance} method of \texttt{My\-Contact\-Factory} to get
a new  contact object.
This method simply constructs the appropriate object and generates a
service time which is stored in the
contact object to be retrieved later by the agent group.
After the new contact is returned, it is broadcast to the router, and a
new arrival is scheduled.  The user only needs to
provide the \texttt{new\-Instance} method, the rest of the logic being
implemented once in \texttt{Contact\-Arrival\-Process}, and inherited by
\texttt{Poisson\-Arrival\-Process}.

In its \texttt{new\-Contact} method,
the router sends the newly-constructed contact to an agent, or
adds it to the waiting queue if no agent is available.
The way the agent or the waiting queue are selected, called \emph{agent
  selection} and \emph{queue selection}, respectively, depends on the
algorithm implemented in the chosen subclass of \texttt{Router}.
In this example,
when a service starts, a free agent becomes busy, and an event is
scheduled to happen after the service time elapses.
By default, the service time is extracted from contacts, but this can
be customized in many ways if needed, as we will do in
section~\ref{sec:Bank}.
Since the default service time is infinite, it is important to set a
service time in the contact factory, or change the service time
generator of the agent group.
If the contact is queued, the contact is added, with extra
information, to an internal linked list.

When a service ends, the router is notified,
the contact exits the
system, and it is broadcast to the \texttt{served}
method of \texttt{My\-Contact\-Measures}.
This method receives all information about the served contact
through the \emph{end-service event} object.  In this example, after a
service is
counted, the waiting time of the contact must be obtained: the served
\texttt{Contact} is extracted from the end-service event, and the
total queue time is queried.  Note that this obtains the
\emph{cumulative} queue time, i.e., the time spent by the contact in
all waiting queues.  In simple systems, this is the same as the waiting
time in the last queue since the contact waits only once.
Other information such as the starting time of the service, and the
reason why the service ended can be extracted from the event.
The two other methods of \texttt{My\-Contact\-Measures} contain no
code, because no contact is blocked or abandons in this model.

When an agent became free due to the service termination, the
router tries to perform \emph{contact selection}, i.e., it
scans waiting queues to assign a waiting contact to the free agent.
Without contact selection, all queued contacts would wait forever.  In
this example, the router simply takes the first contact
in the waiting queue, implementing a FIFO discipline.  If the queue is
empty at pull time, the affected agent remains free until the
following arrival.

When the simulation clock reaches \texttt{DAYLENGTH}, the
\texttt{End\-Sim\-Event} is executed, which calls \texttt{end\-Sim} to
disable the arrival
process.  This cancels the last scheduled arrival, breaking the life
cycle of the process.
If the arrival process is never disabled, the simulation will run
forever, and results will never be printed.
\texttt{end\-Sim} also stores the integrals of $N(t)$ and $\Nb(t)$ for
the occupancy ratio to exclude the wrap-up period following the
closing time.  No more arrival occurs, but in-progress and queued
contacts are served before the end of the replication.  After all
these services are over, \texttt{Sim.start} ends and the
\texttt{simulate\-One\-Day} method continues its execution.
Note that in a further example, the \texttt{end\-Sim} method will be
overridden to change how the simulation is terminated.

It is important not to end the simulation abruptly using
\texttt{Sim.stop}, otherwise the system will end non-empty:
queues will contain contacts, and some
agents will still be serving customers.  If the simulation is stopped
abruptly, the program needs to take this non-empty state into account
during statistical collecting.

The \texttt{addObs} method is called to add observations to
statistical collectors.  In further examples, this will be overridden
to change how observations are collected.
The number of served contacts as well as the service level for the
replication are added into tallies.  A tally for functions of multiple means is used for the
service level to get a ratio of averages instead of an average of ratios.
This estimates the long-term service level rather than the performance
measure during a single day.
The integrals for $\Nb(t)$ and
$N(t)$ are added to tallies for estimating the occupancy ratio.
As with the service level, we
try to estimate a long-term measure.

After $n$ independent replications of this process, we have
statistical results for the estimated performance measures, including
sample averages, sample variances, and Student-$t$ confidence
intervals.  For the ratios, confidence intervals are computed using
the delta theorem \cite{tSER80a}.  The \texttt{print\-Statistics}
method is used to show a statistical report similar to Listing~\ref{res:MMC}.

\lstinputlisting[caption={Results of the program \texttt{MMC}},%
label=res:MMC,language={},float=htb
 ]{MMC.res}

\subsection{Supporting abandonment}

To support abandonment, some modifications to the previous program are
necessary: patience times must be generated and associated with
contacts, and the contacts having abandoned need to be counted.  Even
if the abandonment count is not required, the service level
computation must be
altered as follows to take this new aspect into account.

Let $\Lb(s)$ be the number of
contacts having abandoned after a waiting time greater than $s$, and
let $L$ be the total number of abandoned contacts.  The new service
level estimator is defined by
\begin{equation}
g_1(s)=\frac{\E[\Sg(s)]}{\E[S + \Lb(s)]}.\label{eq:slab}
\end{equation}
If abandonment is disabled, the new estimator reverts
to~(\ref{eq:slnoab}).

Listing~\ref{lst:MMCAb} presents an extension of the previous
program supporting abandonment.  Instead of rewriting the whole
simulator, we inherit from it and change its behavior by overriding
appropriate methods.

\lstinputlisting[
caption={An extension of the $M/M/c$ model supporting abandonment},%
emph={main,MyContactFactoryAb,MyContactMeasuresAb},
label=lst:MMCAb
]
{MMCAb.java}

Patience times are i.i.d.\ exponential variables with mean~$1/\nu$,
and are generated the same way as service times.
To support this aspect,
new fields containing the abandonment rate $\nu$ as well as a random
variate generator for the patience time are defined.
Then, a new counter and a new statistical
collector are declared for the number of abandoned contacts.
A statistical probe is also defined for the new service level estimator.
The logic of the main method is the same as for the previous example,
except it constructs an instance of \texttt{MMCAb} rather than
\texttt{MMC}.

The constructor first calls the superclass' constructor to create the
contact center, and alters the constructed system in the following
ways.  When contacts are created by the factory, they
must now be assigned a patience time.  To
achieve this result, the factory bound to the arrival process is
replaced by a new one called \texttt{My\-Contact\-Factory\-Ab}.  A
second exited-contact listener is also connected to the router in order
to count abandoned contacts.  The old listener, registered by the
superclass,
as well as the new one we have just created, will both be called by
the router when broadcasting an exited contact.  This way, is is not
necessary to completely rewrite the event-processing code.

The \texttt{simulate} method needs to be overridden to initialize the
added collectors.  \texttt{simulate\-One\-Day} is also overridden to reset
the new counter at the beginning of each replication.  All the code in
the superclass is reused, and overridden methods are called instead of
old ones.

\texttt{My\-Contact\-Factory\-Ab} extends the previous contact
factory to set the patience time of newly-constructed contacts. The
\texttt{new\-Instance} method of the superclass is first used to create the
contact, then a patience time is set in a way similar to the service time.

Abandonment is managed automatically by the waiting queue as follows.
Rather than contact instances, the queue stores objects representing
simulation events
happening at the time of automatic removal, e.g., abandonment,
disconnection, transfer to another queue, etc.
In the previous subsection, these \emph{dequeue events} were never
scheduled,
because patience times default to infinity if unspecified.  The
patience time, more generally the \emph{maximal queue time}, is by
default extracted from the contacts, the same way as the service
time.

\lstinputlisting[caption={Results of the program \texttt{MMCAb}},%
label=res:MMCAb,language={},float=htb
 ]{MMCAb.res}

The
\texttt{My\-Contact\-Measures\-Ab} class defines the \texttt{dequeued}
method to count abandoned contacts.  In a way similar to
\texttt{served} in \texttt{My\-Contact\-Measures}, this method takes
an object representing a
dequeue event to receive maximal
information.  An abandoned contact is counted, and if the waiting time is
greater than or equal to $s$, a contact having abandoned after the
acceptable waiting time is added.  In contrast with the contact
factory,
\texttt{My\-Contact\-Measures\-Ab} has no inheritance relationship
with its counterpart in \texttt{MMC}.  Both inner classes are
independent observers performing complementary tasks.

The \texttt{addObs} method is overridden to collect the number of
abandoned contacts and to compute service level differently.
The superclass' method is called and adds observations in the old and
inherited collectors.

Finally,
\texttt{print\-Statistics} is overridden to take the number of
abandoned contacts into account.  Listing~\ref{res:MMCAb} presents the
results of the extended program.
Abandonment increases the service level, because it reduces the size
of the waiting queue and allows customers to be served more quickly.
The occupancy ratio of agents is reduced, because some customers
served in the $M/M/c$ system abandon.

\subsection{Clearing the queue at the end of the day}

If the contact center was very busy, a big queue could build up
during the day.  This would result in agents working for a long time
after their shifts.  To make the model more realistic without
supporting abandonment,
when the contact center closes, queued contacts may be disconnected
instead of being served.
Agents still terminate their services, but the queued contacts are not
served.  To implement this, at the end of the simulation, the
\texttt{queue.clear} method
is called to remove all contacts.  This method accepts a
\emph{dequeue type} giving the reason why contacts are removed.
The dequeue type~0 is reserved for contacts to be served while dequeue
type~1 is used for abandoned contacts.  In this example, we clear the
queue with an indicator different from~1 to permit statistical
collectors to distinguish abandonment from disconnection.
Listing~\ref{lst:MMCClrQ} presents a second extension of the
$M/M/c$ queue, with support for disconnection.  This new aspect has an
impact on the original service level estimator.  We therefore define a
new collector for a corrected estimator including the number of
disconnected contacts in its denominator.

\lstinputlisting[
caption={An extension of the $M/M/c$ model supporting disconnections},%
emph={main,MyContactMeasuresClr},
label=lst:MMCClrQ
]
{MMCClrQ.java}

\lstinputlisting[caption={Results of the program \texttt{MMCClrQ}},%
label=res:MMCClrQ,language={},float=htb
 ]{MMCClrQ.res}

As it was made for abandonment
in the previous example, the base $M/M/c$ program is extended to
support disconnection.  This time, a new contact factory is not
needed.  As with the previous example, a second
observer is connected to the router to count additional events.
The exited-contact listener simply counts a
disconnection when a contact leaves the queue.  However, if abandonment
was additionally supported, it would be important to adapt the
exited-contact listener to distinguish abandoned and disconnected
contacts.  The \texttt{end\-Sim} method is
overridden to clear the waiting queue.

Listing~\ref{res:MMCClrQ} presents
statistical result of this program.
Clearing the waiting queue does not have a great impact on the
performance of the contact center, because the queue at
the end of the day is not too large.

\subsection{Limiting the queue capacity}
\label{sec:qclimit}

The capacity of a real system is never infinite.  For example, call
centers own a certain number of phone lines, and a caller arriving at
a time when all lines are busy cannot be served or wait in queue; it is
\emph{blocked} by the system.  To support this aspect,
the \texttt{Router} class defines the
\texttt{set\-Total\-Queue\-Capacity} method to limit the number of queued
contacts.
Blocked contacts are notified to the \texttt{blocked} method of registered
exited-contact listeners and can be counted too.  With this mechanism,
a limitation can be enforced on the
capacity over all waiting queues only.  In section~\ref{sec:Telethon},
we will
see a more general way of limiting the capacity of a contact center,
by using trunk groups.

Listing~\ref{lst:MMCBlocked} presents an extension of the $M/M/c$
basic model with limited queue capacity.  The program is similar to
examples in previous subsections: we extend the \texttt{MMC} class to
alter the contact center and add new statistical counters.  The
estimator of the service level is also modified to add the number of
blocked contacts in its denominator.
This time, the \texttt{blocked} method of the exited-contact listener
is defined and simply increments the counter for the number of blocked
contacts.  The \texttt{bType} indicator may be useful to get the
reason of blocking.

\lstinputlisting[
caption={An extension of the $M/M/c$ model with limited queue capacity},%
emph={main,MyContactMeasuresBlocked},
label=lst:MMCBlocked
]
{MMCBlocked.java}

Listing~\ref{res:MMCBlocked} displays the statistical results of the
new program.  Limiting the capacity has an effect similar to
abandonment by limiting the number of contacts to serve.

\lstinputlisting[caption={Results of the program \texttt{MMCBlocked}},%
label=res:MMCBlocked,language={},float=htb
 ]{MMCBlocked.res}

\subsection{Preparing for parallel simulations}
\label{sec:MMCSim}

As mentioned in the overview, most examples of this guide use the
\texttt{Sim} static class for simplicity.
But
if several instances of a simulator are needed, with one instance
assigned to one thread, each call to
static methods in the \texttt{Sim} class must be
replaced with a call to methods in an instance of \texttt{Simulator}.
The program in Listing~\ref{lst:MMCSim} is an adaptation of
Listing~\ref{lst:MMC} showing how to do this.

\lstinputlisting[
caption={An extension of the $M/M/c$ model using \texttt{Simulator}},%
emph={main},
label=lst:MMCSim
]
{MMCSim.java}

First, a field of type \texttt{Simulator} named \texttt{sim} is added
to the program.
This simulator encapsulates a simulation clock and event list specific
to a \texttt{MMCSim} instance rather than having a clock and a list
shared among all instances.
Calls to \texttt{Sim.init} and \texttt{Sim.start}
in the program are then replaced
with calls to \texttt{sim.init} and \texttt{sim.start}.

The simulator must be passed to most objects of ContactCenters.
This includes contacts, arrival processes, statistical collectors
for agent groups, and any user-defined event.
Consequently, we had to add a constructor to the
\texttt{End\-Sim\-Event} class in order to pass the simulator, and
change how \texttt{arriv\-Proc} and \texttt{vcalc} are constructed.
The \texttt{My\-Contact\-Factory} class is also modified to pass the
simulator to each new contact.
Agent groups and waiting queues do not need the simulator, because
they use the one assigned to the contacts they process.

If one forgets to give the simulator to an object that needs one, no
compile or run time errors occur by default.
The object in question  silently uses the default simulator, which
could result in unexecuted simulation events or other unpredictable
errors.
To help in preventing this, we would like
the program to crash as soon as
possible if the default simulator is used.
This can be done by replacing the default simulator with a dummy
unusable object whose each method throws an
\texttt{Unsupported\-Operation\-Exception}; we do this at the
beginning of the \texttt{main} method in the program.
If the program does not throw an exception, one can
then be relatively
confident that the default simulator is never used.


\chapter{Useful and important packages}

% TODO: Write something about unicode-math

\section{\packtitle{microtype} for better typesetting}

Use the package~\packname{microtype}\massindex[packages]{microtype}[\packname].
It makes your document look nicer and helps you to circumvent overfull hboxes.
Simply including the package is enough to let it work its magic\index{magic!zzzz@\igobble |see {\packname{microtype}}}

\section{\packtitle{mathtools} for mathematics}

The package~\packname{amsmath}\massindex[packages]{amsmath}[\packname] is a standard for mathematical typesetting.
The package~\packname{mathtools}\massindex[packages]{mathtools}[\packname] is an extension of~\packname{amsmath} that fixes some problems and also provides new (and often times very useful) functionalities.
The package~\packname{mathtools} automatically loads \packname{amsmath}, so instead of~\packname{amsmath} include~\packname{mathtools}.

Note that the important mathematical packages~\packname{amssymb}\massindex[packages]{amssymb}[\packname] and \packname{amsthm}\massindex[packages]{amsthm}[\packname] are not automatically loaded by~\packname{mathtools} and therefore still need to be included by hand.
Two other useful packages for mathematical content are \packname{stmaryrd}\massindex[packages]{stmaryrd}[\packname] (which provides some more symbols) and occasionally \packname{extarrows}\massindex[packages]{extarrows}[\packname] (which provides certain kinds of extensible arrows, see \cref{extensible arrow table}).

\section{\packtitle{amsthm} for theorem-like environments}
\label{defining theorem-like environments}

To define theorem-like environments\index{theorem-like environments} -- like~\envname{lemma}\massindex[theorem-like environments]{lemma}[\envname], \envname{proposition}\massindex[theorem-like environments]{proposition}[\envname], \envname{theorem}\massindex[theorem-like environments]{theorem}[\envname], \envname{corollary}\massindex[theorem-like environments]{corollary}[\envname], etc.,\ include the package~\packname{amsthm}\massindex[packages]{amsthm}[\packname].
New environments can then be defined with the command~\comname{newtheorem}\massindex[\piname{amsthm}]{newtheorem}[\comname]:
\begin{showcode}{Syntax of \comname{newtheorem}}
\newtheorem{internal name of the environment}{name to be printed}
\end{showcode}
\begin{showlatex}{Using the command~\comname{newtheorem}}
% in the preamble
\newtheorem{proposition}{Proposition}
% in the main body
\begin{proposition}
  Every finite subgroup of $k^\times$ is cyclic.
\end{proposition}
\end{showlatex}
The variant \comname{newtheorem*}\massindex{newtheorem*}[\comname] defines unnumbered theorem-like environments:
\begin{showlatex}{Using the command~\comname{newtheorem*}}
% in the preamble
\newtheorem*{claim}{Claim}
% in the main body
\begin{claim}
  The symmetric group $S_3$ is the smallest non-abelian group.
\end{claim}
\end{showlatex}

If multiple theorem-like environments are defined then their have by default independent counters\index{counter}:
\begin{showlatex}{Theorem-like environment use different counters by default}
%in the preamble
\newtheorem{idea}{Idea}
\newtheorem{problem}{Problem}
%in the main text
\begin{idea}
  Fly to the moon in a car.
\end{idea}
\begin{problem}
  Cars don't fly.
\end{problem}
\end{showlatex}
For mathematical texts this behavior is pretty bad, as it makes it harder to find a specific result.
(If page~492 features both Lemma~112 and Proposition~43 then where is Remark~20?)

To solve this problem we define a new counter \inlinecode{alltheorems} and tell all theorem-like environments to use this counter\index{counter}.
To define the now counter we use the appropriately named command~\comname{newcounter}\massindex{newcounter}[\comname]:
\begin{showcode}{Syntax of \comname{newcounter}}
\newcounter{name}[dependence]
\end{showcode}
The explicit code looks as follows
\begin{showlatex}{Setting up a common counter}
% in the preamble
\newcounter{alltheorems}

\newtheorem{assumption}[alltheorems]{Assumption}
\newtheorem{consequence}[alltheorems]{Consequence}

% in the main text
\begin{assumption}
  Cats hunt mice.
\end{assumption}

\begin{assumption}
  Tigers are cats.
\end{assumption}

\begin{consequence}
  Tigers hunt mice.
\end{consequence}
\end{showlatex}

In practice one often wants the counter to be bound to the surround section (or chapter).
This can be achieved by binding the new counter to the section counter:
\begin{showlatex}[
  before lower = {\stoptoc},
  after lower = {\starttoc \addtocounter{section}{-2}}
]{Binding a new counter to the section level}
% in the preamble
\newcounter{sometheorems}[section]
\renewcommand{\thesometheorems}{\thesection.\arabic{sometheorems}}
\newtheorem{corollary}[sometheorems]{Corollary}

% in the main text
\section{Free abelian groups}

\begin{corollary}
  Every subgroup of a free abelian group is again free abelian.
\end{corollary}

\begin{corollary}
  Every subgroup of $\mathbb{Z}^n$ admits a basis.
\end{corollary}

\section{More free abelian groups}

\begin{corollary}
  Every subgroup of a subgroup of $\mathbb{Z}^n$ admits a basis.
\end{corollary}
\end{showlatex}
The addition of \inlinecode{[section]} to the definition of the new counter ensures that the resulting counter~\inlinecode{sometheorems} resets every time the counter~\inlinecode{section} is increased (which happens every time a new section begins).
We also change the way the counter~\inlinecode{sometheorems} is printed, namely printing it in the form~\enquote{(section~number).(counter~number)} with both numbers printed in Arabic numerals.

\section{\packtitle{tikz-cd} for commutative diagrams}

There are many packages for drawing commutative diagrams\index{commutative diagrams}.
Many of them have a rather restricted functionality, and quite a lot of them produce bad looking output.
You should use the package~\packname{tikz-cd}\massindex[packages]{tikz-cd}[\packname].
We refer to the very readable manual \cite{tikz-cd} for an explanation of this package.

\section{\packtitle{cleveref} and \packtitle{hyperref} for referencing}

\subsection{Recalling basic referencing}

To refer to a numbered part of the document, like a theorem, an item of a list, a chapter or a section, one should never write down this number explicitly in the code.
The referencing system of {\LaTeX} should be used instead.
Using this referencing system always consists of two steps:
Setting a label at the position that you want to refer to, and then referencing this label at the desired position.

\subsubsection{The basic \comname{label} and \comname{ref}}

The command for setting a label is \comname{label}\massindex[referencing]{label}[\comname]:
\begin{showcode}{Syntax of \comname{label}}
\label{labelname}
\end{showcode}
There are multiple commands for referencing this label, the most basic of which is \comname{ref}\massindex[referencing]{ref}[\comname]:
\begin{showcode}{Syntax of \comname{ref}}
\ref{labelname}
\end{showcode}
Referencing a label with \comname{ref} will print the number of whatever the specified label appears in.
\begin{showlatex}{Using the commands~\comname{label} and~\comname{ref}}
\begin{theorem}
  \label{vector spaces are free}
  Every vector space admits a basis.
\end{theorem}
It follows from \ref{vector spaces are free} that every $k$-vector space is isomorphic to $k^{\oplus I}$ for some suitable index set $I$.
\end{showlatex}

Instead of giving just a simple number it is customary to also specify what hides behinds this number, e.g.\ a theorem, table or figure.
The specified name and number should then be separated by a tie~\inlinecode{\customtexttilde} (as explained in \cref{non-breakable space}) to ensure that no line break occurs at this position.
The name of the referred to environment is usually capitalised.
\begin{showlatex}[label = {hardcoding references}]{Specifying the kind of reference}
\begin{theorem}
  \label{every vector space has a basis}
  Every vector space admits a basis.
\end{theorem}
It follows from Theorem~\ref{vector spaces are free} that every $k$-vector space is isomorphic to $k^{\oplus I}$ for some suitable index set $I$.
\end{showlatex}
In praxis this behavior can be automated by using the upcoming \packname{cleveref}\massindex[packages,referencing]{cleveref}[\packname] package.

\subsubsection{\comname{eqref}}

When referring to an equation it is customary to put the resulting number in parentheses.
This is done via the command~\comname{eqref}\massindex[referencing]{eqref}[\comname].
\begin{showcode}{Syntax of \comname{eqref}}
\eqref{labelname}
\end{showcode}
The command~\comname{eqref} is used in the same way as the original \comname{ref}:
\begin{showlatex}{Using the command~\comname{eqref}}
A classic result in mathematics shows
\begin{equation}
  \label{important formula}
  1 + 1 = 2 \,.
\end{equation}
Note that the identity~\eqref{important formula} shows that Fermat’s conjecture on the sum $a^n + b^n = c^n$ cannot be generalized to the case $n = 1$.
\end{showlatex}

\subsubsection{Choosing labels}

Always use descriptive labels.
Cryptic sequences of seemingly random letters will backfire on you down the road.

\subsection{\packtitle{cleveref}}

There are two related problems with hardcoding the type of a reference as done in \cref{hardcoding references}:
One has to remember or to look up what type of environment the label refers to, and if this type is changed (e.g.\ by promoting a proposition to a theorem) then the hardcorded types need to be manually adjusted.

These problems can be circumvented by using the package~\packname{cleveref}\massindex[packages,referencing]{cleveref}[\packname].
The author recommends to load this package with the options~\optname{capitalise}\massindex[\piname{cleveref},referencing]{capitalise}[\optname] and \optname{noabbrev}\massindex[\piname{cleveref},referencing]{noabbrev}[\optname]:
\begin{showcode}[label={cref example}]{Loading the package~\packname{cleveref}}
\usepackage[capitalise, noabbrev]{cleveref}
\end{showcode}

\subsubsection{The command~\comname{cref}}

The package~\packname{cleveref} provides the command~\comname{cref}\massindex[\piname{cleveref},referencing]{cref}[\comname]
\begin{showcode}{Syntax of \comname{cref}}
\cref{labelname}
\end{showcode}
The command~\comname{cref} differs from the more primitive~\comname{ref} in that it automatically inserts the right kind of type before the reference.
\begin{showlatex}{Using the command~\comname{cref}}
\begin{lemma}
  \label{dim is well-defined}
  Every two bases of a vector space have the same cardinality.
\end{lemma}

\begin{remark}
  One can generalize \cref{dim is well-defined} to non-commutative rings:
  If $R$ is some ring and $M$ is a semisimple $R$-module then for every irreducible $R$-module $L$ the multiplicity of $L$ in $M$ is well-defined.
\end{remark}
\end{showlatex}

The used options options~\inlinecode{capitalise} and~\inlinecode{noabbrev} have the following effects:
\begin{myitemize}
  \item
    The option~\inlinecode{capitalise} ensures that the printed type of the reference will begin with an upper case letter.
    In \cref{cref example} we would otherwise get~\enquote{\lcnamecref{dim is well-defined}~\labelcref{dim is well-defined}} instead of~\enquote{\cref{dim is well-defined}}.
  \item
    The option~\inlinecode{noabbrev} ensures that printed types won’t be abbreviated.
    One wil otherwise get~\enquote{eq.\ (5)} instead of~\enquote{equation~(5)}.
\end{myitemize}

The command~\comname{cref} has the variant \comname{Cref}\massindex[\piname{cleveref},referencing]{Cref}[\comname] which ensures that the inserted type will start with an upper case letter.
One should always use~\comname{Cref} instead of~\comname{cref} at the beginning of a sentence, even if the option~\optname{capitalise} is set.

\subsubsection{The commands~\comname{*name*ref}}

The package~\packname{cleveref} provides another family of useful commands aside from~\comname{cref} and~\comname{Cref}.
An overview of these commands can be found in \cref{name ref commands}.
\begin{table}[tb]
  \begin{center}
  \begin{tabular}{@{}llll@{}}
    \toprule
    %
    {}
    &
    \theading{lower case}
    &
    \theading{upper case}
    &
    \theading{default case}
    \\
    \cmidrule(lr){2-2}
    \cmidrule(lr){3-3}
    \cmidrule(l){4-4}
    singular
    &
    \comname{lcnamecref}\massindex[\piname{cleveref},referencing]{lcnamecref}[\comname]
    &
    \comname{nameCref}\massindex[\piname{cleveref},referencing]{nameCref}[\comname]
    &
    \comname{namecref}\massindex[\piname{cleveref},referencing]{namecref}[\comname]
    \\
    plural
    &
    \comname{lcnamecrefs}\massindex[\piname{cleveref},referencing]{lcnamecrefs}[\comname]
    &
    \comname{nameCrefs}\massindex[\piname{cleveref},referencing]{nameCrefs}[\comname]
    &
    \comname{namecrefs}\massindex[\piname{cleveref},referencing]{namecrefs}[\comname]
    \\
    \bottomrule
  \end{tabular}
  \end{center}
  \caption{The commands~\comname{*name*ref}.}
  \label{name ref commands}
\end{table}
They can be used to print the type of a reference without its number.
This can be used be used to circumvent hardcoding types into the source code:
\begin{showlatex}{Using~\comname{lcnamecref}}
\begin{lemma}
  \label{weak cayley}
  Every group embeds into a non-abelian group.
\end{lemma}
The above \lcnamecref{weak cayley} does directly follow of Cayley’s~theorem.
\end{showlatex}
By using the various referencing commands introduced so far it is now possible to avoid (nearly?) every kind of hardcorded type.

\subsection{\packtitle{hyperref}}

If the resulting \filename{pdf}-file is supposed to be navigated digitally then the package~\packname{hyperref}\massindex[packages,referencing]{hyperref}[\packname] should be used.
This package puts hyperlinks\index{hyperlink} in the \filename{pdf}-file whenever some kind of reference is used.

\subsection{Order of inclusion}

The packages~\packname{cleveref} and~\packname{hyperref} are a bit peculiar when it comes to where they have to be included in the preamble.
The general rule is that the package~\packname{hyperref} should be the very last package to be included, to ensure that it interacts properly with all other used packages.
There are some rare exceptions to this rule, one of which happened to be~\packname{cleveref}.

If you’re defining some common counter for your theorem-like environments (which you should do, as explained in \cref{defining theorem-like environments}) then this needs to be done after~\packname{cleverref} was included.
Otherwise~\packname{cleveref} will have problems knowing what names to print when the command~\comname{cref} is used.

Overall your preamble should have the following order of inclusions:
\begin{showcode}{Order of preamble with \packname{cleveref} and \packname{hyperref}}
% most packages
...
\usepackage{amsthm}
...

% the last packages
\usepackage{hyperref}
\usepackage{cleveref}

% defining theorem-like environments
\newcounter{everything}
\newtheorem{theorem}[everything]{Theorem}
\end{showcode}

\section{\packtitle{csquotes} for quotation marks}

Dealing with quotations marks\index{quotation marks} in {\LaTeX} by hand can be a pain in the ass, for at least two reasons:
Different languages use different kinds of quotation marks, and finding the right combination of {\LaTeX} code to get the correct ones can be a non-trivial problem.
(Depending on your keyboard layout it may even be non-trival in non-trivial ways.)
One way to circumvent this problem is by using the package~\packname{csquotes}\massindex[packages]{csquotes}[\packname].
This package provides the command~\comname{enquote}\massindex[\piname{csquotes}]{enquote}[\comname]:
\begin{showcode}{Syntax of~\comname{enquote}}
\enquote{text}
\end{showcode}
This commands inserts quotation marks around the specified text:
\begin{showlatex}*{Using the command~\comname{enquote}}
\enquote{This is a quote.}
\end{showlatex}
The command~\comname{enquote} can automatically adjust the quotation marks to the conventions of the used language when this language is specified through the package~\packname{babel}\massindex[packages]{babel}[\packname].
This is done by loading the package~\packname{csquotes} with the option~\optname{babel}\massindex[\piname{cleveref}]{babel}[\optname] set to~\optname{true}.
\begin{showlatex}{\comname{enquote} chooses the right kind of quotation marks}
\begin{tabular}{@{}ll@{}}
  \toprule
  American English
  &
  \selectlanguage{american}
  \enquote{quote}
  \\
  British English
  &
  \selectlanguage{british}
  \enquote{quotation}
  \\
  German
  &
  \selectlanguage{ngerman}
  \enquote{Zitat}
  \\
  French
  &
  \selectlanguage{french}
  \enquote{citation}
  \\
  \bottomrule
\end{tabular}
\end{showlatex}

The command~\comname{enquote} automatically handles nested quotation marks\index{quotation marks!nested}:
\begin{showlatex}*{Nested quotes with \comname{enquote}}
\enquote{This is a \enquote{quote} inside a quote.}
\end{showlatex}
So for dealing with quotes of any kind use the package~\packname{csquotes}.

\section{\packtitle{enumitem} for configuration of lists}

In {\LaTeX} there are three different kinds of list environments:
Numbered lists are provided by the environment~\envname{enumerate}\massindex[list environments]{enumerate}[\envname]:
\begin{showlatex}*{Using the environment~\envname{enumerate}}
\begin{enumerate}
  \item
    Assumption
  \item
    ???
  \item
    Contradiction
\end{enumerate}
\end{showlatex}
Unnumbered lists are provided by the environment~\envname{itemize}\massindex[list environments]{itemize}[\envname]:
\begin{showlatex}*{Using the environment~\envname{itemize}}
\begin{itemize}
  \item
    This is a list item.
  \item
    This is also a list item.
  \item
    And yet another list item.
\end{itemize}
\end{showlatex}
The environment~\envname{description}\massindex[list environments]{description}[\envname] uses no predefined symbols for the list items and instead expects a descriptive text from the user:
\begin{showlatex}*{Using the environment~\envname{description}}
\begin{description}
  \item[Field]
    A special kind of ring.
  \item[Ring]
    A generalization of fields.
\end{description}
\end{showlatex}

The package~\packname{enumitem}\massindex[packages]{enumitem}[\packname]\expandafter\index\expandafter{\einame{enumerate}!zzzz@\igobble |seealso{\packname{enumitem}}} is immensely useful for the configuration of the style and behavior of these list environments.
It provides (among others) the following features:

\subsection{Style of numbering}

For the environment~\envname{enumerate} the style of the numbering can be changed by using the option~\optname{label}\massindex[\piname{enumitem}]{label}[\optname]
\begin{showlatex}*{Changing the numbering style of \envname{enumerate} lists}
\begin{enumerate}[label = (\alph*)]
  \item
    First entry.
  \item
    Second entry.
  \item
    Third entry.
\end{enumerate}
\end{showlatex}
For a list of possible labels see \cref{enumitem labels}.
\begin{table}[tb]
  \begin{center}
  \begin{tabular}{@{}ll@{}}
    \toprule
    \theading{option}
    &
    \theading{description}
    \\
    \midrule
    \comname{alph*}%
    \massindex[\piname{enumitem}]{alph*}[\optname]
    &
    lower case alphabetic
    \\
    \comname{Alph*}%
    \massindex[\piname{enumitem}]{Alph*}[\optname]
    &
    upper case alphabetic
    \\
    \comname{roman*}%
    \massindex[\piname{enumitem}]{roman*}[\optname]
    &
    lower case Roman numerals%
    \index{Roman numerals}%
    \index{numerals!Roman}
    \\
    \comname{Roman*}%
    \massindex[\piname{enumitem}]{Roman*}[\optname]
    &
    upper case Roman numerals%
    \index{Roman numerals}%
    \index{numerals!Roman}
    \\
    \comname{arabic*}%
    \massindex[\piname{enumitem}]{arabic*}[\optname]
    &
    Arabic numerals%
    \index{Arabic numeral}%
    \index{numerals!Arabic}
    \\
    \bottomrule
  \end{tabular}
  \end{center}
  \caption{Possible labels for the environment~\envname{enumerate}.}
  \label{enumitem labels}
\end{table}
One can similarly change the symbol for~\envname{itemize} lists via the option~\optname{label}\massindex[\piname{enumitem}]{label}[\optname]:
\begin{showlatex}*{Changing the symbol for~\envname{itemize} lists}
With the standard symbol:
\begin{itemize}[label = {\textbullet}]
  \item
    First entry.
  \item
    Second entry.
\end{itemize}
Now with a different symbol:
\begin{itemize}[label = {\textopenbullet}]
  \item
    First entry again.
  \item
    Second entry again.
\end{itemize}
\end{showlatex}

\subsection{Resuming lists}

One can resume lists with the option~\optname{resume*}\massindex[\piname{enumitem}]{resume*}[\optname].
The option~\optname{resume}\massindex[\piname{enumitem}]{resume}[\optname] works similarly to~\optname{resume} but doesn’t copy any style options from the previous list.
\begin{showlatex}{Resuming lists with \optname{resume*}}
Some text before the first \texttt{enumerate} environment.
\begin{enumerate}[label = \roman*.]
  \item
    First entry.
  \item
    Second entry.
\end{enumerate}
Some text between the \texttt{enumerate} environment.
\begin{enumerate}[resume*]
  \item
    Third entry.
  \item
    Fourth entry.
\end{enumerate}
Some text after the second \texttt{enumerate} environment.
\begin{enumerate}[resume]
  \item
    Fifth entry.
  \item
    Sixth entry.
\end{enumerate}
Some text after the third \texttt{enumerate} environmen.
\end{showlatex}

\subsection{Spacing}

One can change the various spacings\index{spacing}\index{spacing!in lists} involved in the list environments.
For a full overview we refer to~\cite{enumitem}, and in particular to~\cite[Figure~1]{enumitem}.
We give here only some of the more important configurations.

\subsubsection{Multiple paragraphs in a list item}
\index{paragraphs}\index{indentation!of paragraphs}

If a list item contains multiple paragraphs of text then the new paragraphs are by default not indented but instead separated from the preceding paragraph by some additional vertical space:

\begin{showlatex}*{Indentation and distance of pararaphs in lists, default behavior}
\begin{enumerate}
  \item
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna.

    In massa tempor nec feugiat. Nunc aliquet bibendum enim facilisis gravida.
\end{enumerate}
\end{showlatex}

One can adjust the indentation of the paragraphs with the option~\optname{listparindent}\massindex[\piname{enumitem}]{listparindent}[\optname] and the additional vertical spacing between paragraphs with the option~\optname{parsep}\massindex[\piname{enumitem}]{parsep}[\optname].
With this we can regain the standard indentation pattern in lists:

\begin{showlatex}*{Indentation and distance of pararaphs in lists, changed behavior}
\begin{enumerate}[listparindent = \parindent, parsep = 0pt]
  \item
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna.

    In massa tempor nec feugiat. Nunc aliquet bibendum enim facilisis gravida.
\end{enumerate}
\end{showlatex}

\subsubsection{Distance between items}

One can control the distance between list items with the option~\optname{itemsep}\massindex[\piname{enumitem}]{itemsep}[\optname]:

\begin{showlatex}{Distance between list items with \optname{itemsep}}
A list with standard item distance:
\begin{enumerate}
  \item
    First entry.
  \item
    Second entry.
\end{enumerate}
Now a list without additional item distance:
\begin{enumerate}[itemsep = 0pt]
  \item
    First entry again.
  \item
    Second entry again.
\end{enumerate}
\end{showlatex}

\subsubsection{Indentation}
\label{list indentation with enumitem}
\index{indentation!for list environments|(}

The environment~\envname{enumerate}\massindex{enumerate}[\envname] has by default two kinds of indentation\massindex{indent}:
An indentation of the labels with respect to the left margin, and an indentation of the list items with respect to the label.
\begin{showlatex}*{\envname{enumerate}~environment with standard indentation}
Lorem ipsum dolor sit amet,
\begin{enumerate}
  \item
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
\end{showlatex}

We can remove both indentations by using the option~\optname{wide}\massindex[\piname{enumitem}]{wide}[\optname] with the value~\optname{0pt}:
\begin{showlatex}*{\envname{enumerate}~environment without  indentation}
Lorem ipsum dolor sit amet,
\begin{enumerate}[wide = 0pt]
  \item
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
\end{showlatex}
We can add back the identation between the item~labels and the item~text by also setting the option~\optname{leftmargin}\massindex[\piname{enumitem}]{leftmargin}[\optname] to the value~\optname{*}:
\begin{showlatex}*{\envname{enumerate}~environments with only identitation between label and text}
Lorem ipsum dolor sit amet,
\begin{enumerate}[wide = 0pt, leftmargin = *]
  \item
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
\end{showlatex}
One can also add back the indentation between the left~margin and the item~labels by also using the option~\optname{labelindent}:
\begin{showlatex}*{\envname{enumerate}~environment with indentation between margin and label}
Lorem ipsum dolor sit amet,
\begin{enumerate}[wide = 0pt, leftmargin = \parindent, labelindent = \parindent]
  \item
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
\end{showlatex}
One can also combine the above two indentations to regain something that looks like the standard indentation:
\begin{showlatex}*[label = {better standard indentation}]{\envname{enumerate}~environment with indentation between margin and label, and label and text}
Lorem ipsum dolor sit amet,
\begin{enumerate}[wide = 0pt, leftmargin = *, labelindent = \parindent]
  \item
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
\end{showlatex}
But \cref{better standard indentation} does actually have an advantage over the standard indentation, namely that it properly handels long labels:
\begin{showlatex}{Proper vs.\ improper placement of long labels}
The standard identation:
\begin{enumerate}[label = {(Latin \arabic*)}]
  \item
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{enumerate}
An indentation with adjusted parameters:
\begin{enumerate}[label = {(Latin \arabic*)}, wide = 0pt, leftmargin = *, labelindent = \parindent]
  \item
  Dolor sed viverra ipsum nunc aliquet bibendum enim.
  In massa tempor nec feugiat.
\end{enumerate}
\end{showlatex}

The indentitation for the environment~\envname{itemize}\massindex{itemize}[\envname] can be adjusted in the same way as for the environment~\envname{description}.

For the environment~\envname{description}\massindex{description}[\envname] we can proceed similarly as for~\envname{enumerate}.
We first observe the standard identation for this environment:
There is a fixed identation between the left~margin and the items~texts.
The item~labels are aligned at the left~margin.
\begin{showlatex}*{\envname{description}~environment with standard indentation}
Text, text, text, text, text, text, text.
\begin{description}
  \item[First item]
    Text, text, text, text, text, text, text, text, text, text, text.
  \item[Second item]
     Text, text, text, text, text, text, text, text, text, text, text.
\end{description}
\end{showlatex}
We can remove the identation by again using the option~\optname{wide}\massindex[\piname{enumitem}]{wide}[\optname].
\begin{showlatex}*{\envname{description}~environment with no indentation}
Text, text, text, text, text, text, text.
\begin{description}[wide = 0pt]
  \item[First item]
    Text, text, text, text, text, text, text, text, text, text.
  \item[Second item]
     Text, text, text, text, text, text, text, text, text, text.
\end{description}
\end{showlatex}

\index{indentation!for list environments|)}

\subsection{Global settings}

Global settings can be set via the command~\comname{setlist}\massindex[\piname{enumitem}]{setlist}[\optname]:
\begin{showcode}{Syntax of~\comname{setlist}}
\setlist[kind of list]{options}
\end{showcode}
Consider the following example:
\begin{showlatex}*{Global settings for list environments}
\setlist[enumerate]{label = \roman*)}
\begin{enumerate}
  \item
    First entry.
  \item
    Second entry.
\end{enumerate}
\end{showlatex}

\subsection{Nested lists}

When lists are nested one can use different settings for each list.
\begin{showlatex}{Different settings for nested lists}
\begin{enumerate}[label = \Roman*)]
  \item
    First entry.
    \begin{enumerate}[label = \alph*)]
      \item
        First entry, first subentry.
      \item
        First entry, second subentry.
    \end{enumerate}
  \item
    Second entry.
    \begin{enumerate}[label = \arabic*)]
      \item
        Second entry, first subentry.
      \item
        Second entry, second subentry.
    \end{enumerate}
\end{enumerate}
\end{showlatex}
One can also use different global settings for different depths:
\begin{showlatex}{Global settings depending on level}
\setlist[enumerate, 1]{label = (\roman*)}
\setlist[enumerate, 2]{label = (\alph*)}
\begin{enumerate}
  \item
    First entry.
    \begin{enumerate}
      \item
        First entry, first subentry.
      \item
        First entry, second subentry.
    \end{enumerate}
  \item
    Second entry.
    \begin{enumerate}
      \item
        Second entry, first subentry.
      \item
        Second entry, second subentry.
    \end{enumerate}
\end{enumerate}
\end{showlatex}
The counter of the first depth and second depth can be accessed via the counters~\inlinecode{enumi}\massindex[\piname{enumitem}]{enumi}[\inlinecode] and \inlinecode{enumii}\massindex[\piname{enumitem}]{enumii}[\inlinecode]:
\begin{showlatex}{Accessing level counters in settings for list environments}
\setlist[enumerate, 1]{label = (\arabic*)}
\setlist[enumerate, 2]{label = (\arabic{enumi}.\alph*)}
\begin{enumerate}
  \item
    An entry.
    \begin{enumerate}
      \item
        Again an entry.
      \item
        Again an entry.
    \end{enumerate}
  \item
    Another entry.
    \begin{enumerate}
      \item
        Yet another entry.
      \item
        Yet another entry.
    \end{enumerate}
\end{enumerate}
\end{showlatex}

\subsection{Cloning lists}
New list types can be constructed by cloning an already existing one via the command~\comname{newlist}\massindex[\piname{enumitem}]{newlist}[\comname]:
\begin{showcode}{Syntax of \comname{newlist}}
\newlist{new list}{original list}{depth of new list}
    \end{showcode}
    One can then set global options for this new list type without changing the global options for the original type.
    This can be used to construct list environments that serve special purposes.
    In the following example we create a new list environment that is meant for listing equivalent statements:
    \begin{showlatex}{Custom clones of list environments}
% clone enumerate as equivalenceslist, allowing up to 2 levels
\newlist{equivalenceslist}{enumerate}{2}
% set the formatting
\setlist[equivalenceslist,1]{label = (\roman*)}
\setlist[equivalenceslist,2]{label = (\alph*), leftmargin = *}
% an example
Let $M$ be an $R$-module.
For every collection of elements $x_1, \dotsc, x_n \in M$ the following conditions are equivalent:
\begin{equivalenceslist}
  \item
    For every $R$-module $N$ and every choice of elements $y_1, \dotsc, y_n \in N$ there exists a unique module homomorphism $f \colon M \to N$ with $f(x_i) = y_i$ for every $i = 1, \dotsc, n$.
  \item
    The elements $x_1, \dotsc, x_n$ are a basis of $M$, i.e.
    \begin{equivalenceslist}
      \item
        the elements $x_1, \dotsc, x_n$ are linearly independent, and
      \item
        the elements $x_1, \dotsc, x_n$ are a generating set of $M$.
    \end{equivalenceslist}
\end{equivalenceslist}
\end{showlatex}

\section{\packtitle{biblatex} for bibliography}
\index{bibliography|(}

\subsection{The basic setup}

A bibliography in {\LaTeX} comes about from the interplay of three different actors:
\begin{myitemize}
  \item
    A~\filename{bib}-file\massindex[bibliography]{bib-file@\string\filename{bib}-file} that contains the metadata about the literature which should be cited.
  \item
    A bibliography package that provides commands for citing these references.
  \item
    A back~end program\index{bibliography!back~end} that accesses the~\filename{bib}-file to extract the needed information and pass them to {\LaTeX}.
\end{myitemize}
One should choose~\packname{biblatex}\massindex[packages,bibliography]{biblatex}[\packname] for the bibliography package and~\appname{biber}\massindex[bibliography]{biber}[\appname] for the back~end program.
For this the package~\packname{biblatex} needs to be loaded with the option~\optname{backend}\massindex[\piname{biblatex}!options]{backend}[\optname] set to~\optname{biber}:
\begin{showcode}{Loading the package~\packname{biblatex}}
\usepackage[backend = biber]{biblatex}
\end{showcode}
The author also likes to use the following options:
\begin{myitemize}
  \item
    By default the occurring references will simply be numbered as~[1],~[2],~[3],~etc\@.
    Often references of the form~[Eis04] are preferable, which is achieved by setting the option~\optname{style}\massindex[\piname{biblatex}!options]{style}[\optname] to~\optname{alphabetic}.
  \item
    Setting the option~\optname{dateabbrev}\massindex[\piname{biblatex}!options]{dateabbrev}[\optname] to~\optname{false} ensures that month names like \enquote{September} are not abbreviated as~\enquote{Sept.}
  \item
    Setting the option~\optname{urldate}\massindex[\piname{biblatex}!options]{urldate}[\optname] to~\optname{long} ensure that dates concerning URLs are written out as~\enquote{September~4,~2109} instead of~\enquote{09/04/2019}.
\end{myitemize}

\subsection{Creating the \filetitle{bib}-file}
\index{bib-file@\filename{bib}-file|(}
\index{bibliography!bib-file@\filename{bib}-file|(}

To most important step of creating a bibliography is to collect the references and their various metadata in a \filename{bib}-file.
For every reference we need to add an entry to this \filename{bib}-file.
These entries have the following form:
\begin{showcode}[label = {syntax of bib entry}]{Syntax for an entry of the \filename{bib}-file}
@type{label,
  key1 = {value1},
  key2 = {value2},
  key3 = {value3},
  ...
}
\end{showcode}
Instead of curly braces~\inlinecode{\{ \}} one can also use quotation marks~\inlinecode{" "} on the right hand side of the equality signs.

The specifier~\optname{@type} in \cref{syntax of bib entry} will be be replaced by something like~\optname{@book} or~\optname{@article} to explain what kind of work this entry is.
A list of all possible types can be found in~\cite[2.1]{biblatex}.
This specified type will determine which of the given data will be printed in the bibliography and how these printed date are formatted.

The given text~\optname{label} has no influence on the bibliography itself.
It will be used to add the citations to this reference in the main text.

\subsubsection{How to choose data for the bibliography}

One should follow two guidelines when adding information to the bibliography.
\begin{myitemize}
  \item
    Provide as much data as possible.
    The specified type will determine which of these data will be printed.
    To find out which type will use which information we refer again to~\cite[2.1, 2.2]{biblatex}.
  \item
    How the printed data are to be formatted is for {\LaTeX} -- and more specifically \packname{biblatex} -- to decide.
    So don’t try to preformat the provided date in the~\filename{bib}-file.
    Try in particular to give full, unabbreviated names whenever possible.
\end{myitemize}
If you feels strongly about certain data being printed, or how certain data should be formatted when printed out, then you should not try to abuse the~\filename{bib}-file for this.
Instead complains to \packname{biblatex} by changing the appropriate settings.

Some good sources for finding the data that a bibliography requires are MathSciNet\massindex[bibliography]{MathSciNet} and the websites of the publishers.
(Springer is quite good at providing all the needed information on the websites of their books.)
Most of the needed data can also be found in the cited resource -- e.g.\ book or article -- itself.

In the following we will look at some specific examples of~\filename{bib}-file entries.

% TODO: Use location instead of abusing publisher.

\subsubsection{Entry for a single book}

The \filename{bib}-file entry for a single book should roughly look as follows:
\begin{showcode}[label = {bib entry single book}]{\filename{bib}-file entry for a single book}
@book{fultonharris2004,
  title     = {Representation Theory},
  subtitle  = {A First Course},
  author    = {Fulton, William and Harris, Joe},
  edition   = {1},
  year      = {2004},
  pagetotal = {xv+551},
  publisher = {Springer-Verlag New York},
  series    = {Graduate Texts in Mathematics},
  number    = {129},
  isbn      = {978-0-387-97527-6},
  doi       = {10.1007/978-1-4612-0979-9}
}
\end{showcode}
The resulting output in the bibliography (see \cref{example bibliography}) will look as follows:
\testcite{fultonharris2004}

The type~\optname{@books}\massindex[\piname{biblatex}!types]{book}[\atname] tells {\LaTeX} that the entry is a (single) book.
The various keys have the following functions:
\begin{mydescription}
  \item[\optname{title}]
    \massindex[\piname{biblatex}!keys]{title}[\optname]
    This key specifies the title of the book.
    The expected value of this key is a text.
  \item[\optname{subtitle}]
    \massindex[\piname{biblatex}!keys]{subtitle}[\optname]
    This key specifies the subtitle of the book.
    The expected value of this key is a text.
  \item[\optname{author}]
    \massindex[\piname{biblatex}!keys]{author}[\optname]
    This key specifies the author(s) of the book.
    There are some things to be aware of here:
    \begin{myitemize}
      \item
        The name of an author needs to be given in the format~\inlinecode{Lastname, Firstname}.
        This is required so that~\appname{biber} can properly process this data.
      \item
        If multiple authors are given then they need to be separated by the word~\inlinecode{and}.
    \end{myitemize}
  \item[\optname{edition}]
    \massindex[\piname{biblatex}!keys]{edition}[\optname]
    This key specifies the edition of the book.
    The value should be given as a number for proper processing, but can in an emergency also be given as a text.
  \item[\optname{year}]
    \massindex[\piname{biblatex}!keys]{year}[\optname]
    This key specifies the year the book was published.
    One can also specify a moth with the key~\optname{month}.
    The values for both keys are expected to be numbers.

    One can also use the key~\optname{date}\massindex[\piname{biblatex}!keys]{date}[\optname] to specify the date of publication.
    This key expects a single argument, which is of one of the forms~\optname{year},~\optname{year-month}, or~\optname{year-month-day}.
    Here the value of~\optname{year} is expected to be a four digit number, and the values of~\optname{month} and~\optname{day} are expected to be two digit numbers (which may contain a leading zero).
  \item[\optname{pagetotal}]
    \massindex[\piname{biblatex}!keys]{pagetotal}[\optname]
    This key specifies the total number of pages of the book.
    The value should be an integer but can also be an arbitrary text.

    There is however a drawback to simply providing a text:
    Normally the number of pages is followed by the text~\enquote{pp.}\ or~\enquote{p.},\ depending on whether the reference consists of only a single page.
    To do so \packname{biblatex} always tried to interpret the input as a number.
    But if this interpretation fails then neither~\enquote{pp.}\ nor~\enquote{p.} will be added.

    Books often start with pages that are numbered with Roman numbers\index{Roman numerals}\index{numerals!Roman}, followed by pages that are numbered by Arabic numbers\index{Arabic numerals}\index{numerals!Arabic}.
    In this case the total number of pages should be given in the form~\enquote{(Roman~number)+(Arabic~number)}.

    As explained above, this will lead to the problem of \packname{biblatex} being unable to interpret the input as a number, which leads by default to a missing~\enquote{pp.}\ in the output.
    For this problem one can adjust the settings of \packname{biblatex} to \emph{always} include~\enquote{pp.}\ after the total page number of a book.
    This can be done as follows:
    \begin{showcode}{Adjusting the formatting of~\optname{pagestotal}}
\DeclareFieldFormat[book]{pagetotal}{#1~\ppno}
    \end{showcode}
  \item[\optname{publisher}]
    \massindex[\piname{biblatex}!keys]{publisher}[\optname]
    This key specifies the publisher of the book.
    The expected value is a text.
    Note that \enquote{Springer} is not a proper reference for a publisher.
  \item[\optname{series}]
    \massindex[\piname{biblatex}!keys]{series}[\optname]
    Many mathematical books are part of some series, e.g.\ \enquote{Graduate Texts is Mathematics} or \enquote{Cambridge Studies in Advanced Mathematics}.
    Such a series can be specified with the key~\optname{series}, which expects as its value a text.
  \item[\optname{number}]
    \massindex[\piname{biblatex}!keys]{number}[\optname]
    This key specifies the number of the book in the previously specified series.
    The values of this key is (counterintuitively) treated as a text.

    If you copy your bibliography data from somewhere else then there is a high chance that instead of the key~\optname{number} the key~\optname{volume} is used.
    This is relict from the past that isn’t correct with \packname{biblatex}.
  \item[\optname{isbn}]
    \massindex[\piname{biblatex}!keys]{isbn}[\optname]
    This key specifies the ISBN number of the book.
    The value of this field is treated as a text.
  \item[\optname{doi}]
    \massindex[\piname{biblatex}!keys]{doi}[\optname]
    This key specifies the DOI of the book (if it has one).
\end{mydescription}

\subsubsection{Entry for a book with multiple volumes}

Sometimes a book is just one volume in a small collection of books.
In this case one should use the type~\optname{@mvbook}\massindex[\piname{biblatex}!types]{mvbook}[\atname] to define the overall information of these books, and then an entry of type~\optname{@book} which is subordinate to the previously created entry.
Let’s consider an example:
\begin{showcode}[label = {bib entry multiple volume book}]{\filename{bib}-file entry for a book with multiple volumes}
@mvbook{benson,
  title     = {Representations and Cohomology},
  author    = {Benson, David J.},
  publisher = {Cambridge University Press},
  series    = {Cambridge Studies in Advanced Mathematics},
  volumes   = {2}
}

@book{benson1991,
  crossref  = {benson},
  volume    = {1},
  number    = {30},
  title     = {Basic Representation Theory of Finite Groups and Associative Algebras},
  edition   = {1},
  year      = {1991},
  pagetotal = {xii+246},
  isbn      = {978-0-521-36134-7},
  doi       = {10.1017/CBO9780511623615}
}
\end{showcode}
We can then refer to the entry of type~\optname{@book} as usual, to get the following output in the bibliography (see \cref{example bibliography}):
\testcite{benson1991}
One can also refer to the overall collection:
\testcite{benson}

There are three new keys to talk about here:
\begin{mydescription}
  \item[\optname{volumes}]
    \massindex[\piname{biblatex}!keys]{volumes}[\optname]
    This key describes the total number of volumes.
    The value of this key is expected to be an integer.
  \item[\optname{volume}]
    \massindex[\piname{biblatex}!keys]{volume}[\optname]
    This key describes the specific volume of the bibliography entry.
    The value of this key is expected to be an integer.
  \item[\optname{crossref}]
  \massindex[\piname{biblatex}!keys]{crossref}[\optname]
    This key expresses that the given entry is subordinate to some other entry.
    The expected value is the label of the superior entry.
\end{mydescription}

\subsubsection{Entry for an article}

We now consider an example for citing an article:

\begin{showcode}[label = {bib entry article}]{\filename{bib}-file entry for a single book}
@article {diamond_lemma,
  title         = {The Diamond Lemma for Ring Theory},
  author        = {Bergman, George Mark},
  year          = {1978},
  month         = {2},
  journaltitle  = {Advances in Mathematics},
  issn          = {0001-8708},
  volume        = {29},
  number        = {2},
  pages         = {178--218},
  doi           = {10.1016/0001-8708(78)90010-5}
}
\end{showcode}
The output in the bibliography (see \cref{example bibliography}) will look as follows:
\testcite{diamond_lemma}

The type~\optname{@article}\massindex[\piname{biblatex}!types]{article}[\atname] tells {\LaTeX} that the entry is for a (journal)\index{journal} article.
Many fields are as for the type~\optname{@book}, so we will focus on the changes:
\begin{mydescription}
  \item[\optname{journaltitle}]
    \massindex[\piname{biblatex}!keys]{journaltitle}[\optname]
    This key specifies the name of the journal that the article was published in.
    The expected value for this key is a text.
  \item[\optname{issn}]
    \massindex[\piname{biblatex}!keys]{issn}[\optname]
    This key specifies the ISSN (International Standard Serial Number) of the journal in question.
    The value is treated as a text.
  \item[\optname{volume}, \optname{number}]
    \massindex[\piname{biblatex}!keys]{volume}[\optname]
    \massindex[\piname{biblatex}!keys]{number}[\optname]
    These keys specify in which volume of the journal the article appeared, and in which number of the volume.
    The value for~\optname{volume} should be an integer, and the value for~\optname{number} should be an integer too (although it is treated as text).
  \item[\optname{pages}]
    \massindex[\piname{biblatex}!keys]{pages}[\optname]
    This key specifies in which page range the article appeared.
    It doesn’t matter how many dashes are used to separate the two page numbers.
    It also doesn’t matter if the dash(es) are surrounded by space.

    It is customary to specify page ranges in the form~\optname{pages~=~number--number} because this gives a right looking output even if this argument were simply to be interpreted as text.
    (Which lesser packages than \packname{biblatex} may do.)
\end{mydescription}

\subsubsection{Entry for an online resource}

We consider now an example where we cite an online resource.
For this we use the generic type~\optname{@online}\massindex[\piname{biblatex}!types]{online}[\atname].
\begin{showcode}[label = {bib entry online}]{\filename{bib}-file entry for an online resource}
@online{cayley_graph,
  title   = {Cayley graphs and the geometry of groups},
  author  = {Tao, Terence},
  date    = {2010-06-10},
  url     = {https://terrytao.wordpress.com/cayley-graphs-and-the-geometry-of-groups},
  urldate = {2019-09-06}
}
\end{showcode}
The output in the bibliography (see \cref{example bibliography}) will look as follows:
\testcite{cayley_graph}
We have three (or rather two) new fields to discuss:
\begin{mydescription}
  \item[\optname{date}]
    \massindex[\piname{biblatex}!keys]{date}[\optname]
    This key specifies when the linked-to resource was created.
    This key takes arguments of the form~\optname{year},~\optname{year-month} or~\optname{year-month-day}.
    Here the value of~\optname{year} is expected to be a four digit number, and the values of~\optname{month} and~\optname{day} are expected to be two digit numbers (which may contain a leading zero).

    Instead of~\optname{date} one can also use the overall less specific keys~\optname{year} and~\optname{month}.
  \item[\optname{url}]
    \massindex[\piname{biblatex}!keys]{url}[\optname]
    This key specifies the URL\index{URL} of the online resource.
  \item[\optname{urldate}]
    \massindex[\piname{biblatex}!keys]{urldate}[\optname]
    This key specifies the date on which the online resource was accessed.
    This is an important information since content online may change over time.
\end{mydescription}
\index{bib-file@\filename{bib}-file|)}
\index{bibliography!bib-file@\filename{bib}-file|)}

\subsubsection{Entry for an arXiv~article}

To cite an article published on arXiv one shouldn’t use the key~\optname{url} because \packname{biblatex} has a built-in way of dealing with arXiv~articles\massindex[bibliography]{arXiv}.
\begin{showcode}{\filename{bib}-file entry for an online resource}
@online{leinster2014,
  title       = {The bijection between projective indecomposable and simple modules},
  author      = {Leinster, Tom},
  date        = {2014-10-14},
  eprint      = {1410.3671v1},
  eprinttype  = {arxiv},
  eprintclass = {math.RA},
  urldate     = {2019-09-12}
}
\end{showcode}
% TODO: Fix cref-number for Example
The output in the bibliography (see \cref{example bibliography}) will look as follows:
\testcite{leinster2014}
We have used three new fields:
\begin{mydescription}
  \item[\optname{eprinttype}]
    This key specifies what kind of resource the entry is.
    The used value~\optname{arxiv} results in a predefined formatting of the resulting output.
  \item[\optname{eprint}]
    This key specifies the identifier of the resource.
  \item[\optname{eprintclass}]
    This field specifies additional information about the resource.
\end{mydescription}

% For an article that uses the old identifier scheme a slightly different syntax is needed:
% \testcite{symmgroup_2005}

\subsection{Citing the references}

Suppose now that we have added an entry to our~\filename{bib}-file, as outlines in \cref{syntax of bib entry}.
In the actual {\LaTeX} project we can then refer to this entry with the command~\comname{cite}\massindex[\piname{biblatex},bibliography]{cite}[\comname]:
\begin{showcode}{Syntax of \comname{cite}}
\cite[details]{label}
\end{showcode}
Let’s consider an example where we cite the references given in the previous examples:
\begin{showlatex}[label = {using cite}]{Using the command~\comname{cite}}
We assume that the reader is familiar with the representation theory of the symmetric groups as discussed in \cite[\S 4]{fultonharris2004}.
The reader may also want to check out \cite{benson1991} and \cite{cayley_graph}.
For a nice proof of the Poincaré--Birkhoff--Witt~Theorem we refer to \cite[\S 3]{diamond_lemma}.
\end{showlatex}

We will also need to add the bibliography into the {\LaTeX} document.
Suppose for this that the \filename{bib}-file is called \filename{references.bib}.
We then have to do three things:
\begin{myitemize}
  \item
    We need to tell {\LaTeX} how the \filename{bib}-file is called.
    This is done via the command~\comname{bibliography}\massindex[bibliography]{bibliography}[\comname]:
    \begin{showcode}{Syntax of \comname{bibliography}}
\bibliography{name of bib-file}
    \end{showcode}
    In our case we have to add~\inlinecode{{\tbs}bibliography\{references.bib\}}.
  \item
    We have to add the command~\comname{printbibliography}\massindex[\piname{biblatex},bibliography]{printbibliography}[\comname] at the position in source code where we want the bibliography to be printed.
    This typically happens near the end of the document.
  \item
    We set the option~\optname{bibliography}\massindex[KOMA-Script classes, document class!options, bibliography]{bibliography}[\optname] of~\comname{documentclass} to~\optname{totoc} to add the bibliography to the table of contents. (see \cref{layout for scrbook}).
\end{myitemize}

In our running example(s) we would get the following bibliography:
% locally overwrite \printbibliography
\let\oldprintbibliography\printbibliography
\renewcommand{\printbibliography}{%
  \oldprintbibliography[
    heading   = subbibliography,
    title     = {Bibliography},
    category  = testentries
  ]
}
\begin{showlatex}[label = {example bibliography}]
  {Using the command~\comname{printbibliography}}
\printbibliography
\end{showlatex}
% undo the above overwriting
\let\printbibliography\oldprintbibliography

\subsubsection{Compiling the bibliography}

To get the output of \cref{using cite} and \cref{example bibliography} we actually have to compile the document in the right way:

Suppose that the~\filename{bib}-file has created, we have put the citations in the text via~\comname{cite} and that we have placed \comname{printbibliography} in the source code.
Suppose that our main file is called~\filename{main.tex} and the~\filename{bib}-file is called~\filename{references.bib}.
To get the desired bibliography and cross-references between it and the text we need to complete three steps:
\begin{myenumerate}
  \item
    We compile the document~\filename{main.tex}.
    The compiler will note down in an auxiliary file~\filename{main.bcf} which labels are cited in this document
  \item
    The back~end program~\appname{biber}\massindex[bibliography]{biber}[\appname] will go through the auxiliary files~\filename{main.bcf} and write down all the requested information in a new auxiliary file~\filename{main.bbl}.
  \item
    We compile the document~\filename{main.tex} again.
    The compiler will read the various data given in the auxiliary file~\filename{main.bll} and, using the settings and commands from the package~\packname{biblatex}, will typeset both the citations in the main text and create a bibliography.
\end{myenumerate}
If you’re using a specialized {\LaTeX} editor or IDE (like {\TeX}Studio\index{TeXStudio@{\TeX}Studio}, kile\index{kile}, etc.)\ and have everything properly configured then your editor should take care of the above steps automatically when(ever) the document is compiled.
But if you’re compiling by hand in the console then you will need three commands:
\begin{showcode}{Compiling in the console (with bibliography)}
latex main.tex
biber main.bcf
latex main.tex
\end{showcode}

\index{bibliography|)}

\section{\packtitle{booktabs} for tables}

\subsection{Recalling basic tables}
\index{tables|(}

\subsubsection{The table itself}

Recall that a table is constructed with the environment~\envname{tabular}\massindex[tables]{tabular}[\envname]:

\begin{showlatex}{A basic table}
\begin{tabular}{lcr}
  longtext & text     & text      \\
  text     & longtext & text      \\
  text     & text     & longtext
\end{tabular}
\end{showlatex}
The labels~\optname{l}\massindex[tables]{l}[\optname],~\optname{c}\massindex[tables]{c}[\optname],~\optname{r}\massindex[tables]{r}[\optname] specify the alignment of the corresponding column (left aligned, centered, and right aligned).

\subsubsection{Horizontal lines}

The command~\comname{hline}\massindex[tables]{hline}[\comname]\index{tables!horizontal lines} at the beginning of a row introduces a horizontal line that separates this row from the previous one.
To get multiple parallel lines (e.g.\ a double line) one uses multiple instances of \comname{hline} directly after each other.
\begin{showlatex}{Full horizontal lines in tables}
\begin{tabular}{ccc}
  top left & top center & top right \\
  \hline\hline
  text     & text       & text      \\
  \hline
  text     & text       & text
\end{tabular}
\end{showlatex}

\subsubsection{Partial horizontal lines}

To separate only the columns $i, \dotsc, j$ by horizontal line\index{tables!horizontal lines}, the command~\comname{cline}\massindex[tables]{cline}[\comname] is used:
\begin{showcode}{Syntax of \comname{cline}}
\cline{start column-end column}
\end{showcode}
The command~\comname{cline} has the same placement as \comname{hline}:
\begin{showlatex}{Partial horizontal lines in tables}
\begin{tabular}{ccccc}
  text & text & text & text & text \\
  \cline{2-4}
  text & text & text & text & text \\
  \cline{1-2} \cline{4-5}
  text & text & text & text & text
\end{tabular}
\end{showlatex}

\subsubsection{Vertical lines}

One can put a vertical line\index{tables!vertical lines} between two columns by adding the symbol~\optname{|} between the corresponding alignment symbols.
Inserting this symbol multiple times will give parallel vertical lines.
\begin{showlatex}{Vertical lines in tables}
\begin{tabular}{l||c|c}
  first row   & text & text \\
  second row  & text & text \\
  third row   & text & text
\end{tabular}
\end{showlatex}

\subsubsection{Different kinds of lines}

The above effects can also be combined:
\begin{showlatex}{A table with all kinds of lines in it}
\begin{tabular}{|l||l|r|}
  \hline
  \textbf{Country}  &  \textbf{Town}  & \textbf{Population} \\
  \hline\hline
  France            & Paris           & 2,229,621           \\
  \cline{2-3}
  {}                & Marseille       &   855,393           \\
  \hline
  Germany           & Berlin          & 3,520,031           \\
  \cline{2-3}
  {}                & Hamburg         & 1,787,408           \\
  \hline
  Japan             & Tokyo           & 8,637,098           \\
  \cline{2-3}
  {}                & Yokohama        & 3,697,894           \\
  \hline
\end{tabular}
\end{showlatex}

\subsection{Problems and solutions}

The above table has a huge problem:
It’s ugly.
This is due to various reasons:
\begin{myitemize}
  \item
    The spacing between the horizontal lines and the text below them is both bad and inconsistent.
  \item
    The above table breaks the first rule of table club:
    Never, ever use vertical lines.
  \item
    The above table also breaks the second rule of table club:
    Never use double lines.
\end{myitemize}
The last two points are easy to fix.
The package~\packname{booktabs}\massindex[packages,tables]{booktabs}[\packname] gives a way for fixing the first problem:
\begin{myitemize}
  \item
    This package provides the commands~\comname{toprule}\massindex[\piname{booktabs},tables]{toprule}[\comname], \comname{midrule}\massindex[\piname{booktabs},tables]{midrule}[\comname] and \comname{bottomrule}\massindex[\piname{booktabs},tables]{bottomrule}[\comname] as replacements for \comname{hline}.
    The command~\comname{toprule} is to be used only for the line on top of the table.
    The command~\comname{bottomrule} is similarly only to be used for the line on the bottom of the table.
    The horizontal line~\comname{midrule} is meant to separate the main part of the table from the top part and bottom part.
  \item
    The command~\comname{cmidrule}\massindex[\piname{booktabs},tables]{cmidrule}[\comname] is the replacement for \comname{crule}.
\end{myitemize}
One should also try to minimize the number of horizontal lines.
The above example should hence look as follows:
\begin{showlatex}{Using the rules of \packname{booktabs}}
\begin{tabular}{llr}
  \toprule
  \textbf{Country}  &  \textbf{Town}  & \textbf{Population} \\
  \midrule
  France            & Paris           & 2,229,621           \\
  {}                & Marseille       &   855,393           \\
  Germany           & Berlin          & 3,520,031           \\
  {}                & Hamburg         & 1,787,408           \\
  Japan             & Tokyo           & 8,637,098           \\
  {}                & Yokohama        & 3,697,894           \\
  \bottomrule
\end{tabular}
\end{showlatex}

Note that we could leave out all non-essential horizontal lines because the table has a very regular form.
We refer to \cite{booktab} for more information about typing tables.

\index{tables|)}