%% -*- ispell-local-dictionary: "british"; -*-

\documentclass[a4paper,11pt,twoside]{article}
\usepackage{a4wide}
\usepackage{latexsym,t1enc,lmodern,url}
\usepackage{amssymb, amsmath, amsthm}
\usepackage[latin1]{inputenc}
\usepackage[english]{babel}

%%--------------------------------------------
\hbadness=10000
\emergencystretch=\hsize
\tolerance=9999
\textheight=9.0in
%%--------------------------------------------

\def\chk{{\it chklref}}

\makeatletter

\ifx\HCode\undefined%
\def\page{}%
\def\endpage{}%
\else%
\def\page{\HCode{<div id='page'>}}%
\def\endpage{\HCode{</div>}}%
\fi
\makeatother



\title{Check \LaTeX\ references : chklref \\
Version 2.5}
\date{Monday 16 August 2010}
\author{J\'er\^ome Lelong}
  

\begin{document}
\page
\maketitle

\begin{abstract} Which \LaTeX\ user has never dreamt of cleaning its \TeX\ file
  of any useless labels right before submitting an article for instance? This is
  precisely what \chk\ will help you do.
\end{abstract}

\section{What {\it chklref} can do for a \LaTeX\ user ?}

While typing a \TeX, it is quite common to add labels that will in the end
reveal unused, this is especially true for equations or any other mathematical
environments. It would be quite convenient to wipe out those labels from the
final version of the document. \chk\ has been designed to help any \TeX\
user doing so.

\chk\ parses all the \TeX\ file to detect labels that do not have a matching
reference. At the end of the program, a summary is printed with the list of
labels to be removed. Obviously, this search is performed in the whole document
and not only within mathematical environments. Nonetheless, there is something
specifically dedicated to environments that have a starred version : it looks
for the non starred environments not containing any label.

For instance, consider you a have a \TeX\ file with the following piece of code
\begin{verbatim}
\begin{equation}
  x^2 + x + 1 = 0
\end{equation}
\end{verbatim}
\chk\ will advise you to consider using \verb!equation*! instead of
\verb!equation! to remove the unneeded and by the way unsable number that would
otherwise appear next to the equation.

Starred environments with labels are also tracked because with most \LaTeX\
distributions it does event raise a warning. However in case you may refer to
this label the number that would appear is likely to be nonsense.

The summary printed at the end of the program contains two sections (see
Figure~\ref{fig:output}): one about labels in starred environments and one about
unneeded labels. Each of these output lines begins with a line number referring
to the parsed \TeX\ file. Then, the action to be undertaken is printed :
``remove label'' or ``use a starred environment''. In the case of a ``remove
label'' message, the label to be removed is also printed to avoid any possible
confusions.

\begin{figure}[htbp]
  \centering
\begin{verbatim}
************************************
** Labels in starred environments **
************************************
line  264 : remove label eq:quantified
line  200 : consider using a STAR environment

*******************
** Unused Labels **
*******************
line  313 : remove label eq:prog_dyn_prix
\end{verbatim}
  \caption{Program output}
  \label{fig:output}
\end{figure}

Since version 2.5, the checking of bibliography entries has been added to
detect if some entries are not explicitly cited in the text. In this case, a
``remove bibitem'' message is printed.
\begin{verbatim}
**********************************
** Uncited Bibliography entries **
**********************************
remove bibitem : premia
\end{verbatim}


\section{Usage}

Typical usage : \verb!chklref file.tex!.
\\


\section{Requirements}

\chk\ is written partly in \TeX, partly in Perl. The Perl part is very
standard \textemdash\ it actually only parses the output of the \TeX\ part
\textemdash\ and should work with any standard Perl installation.


\section{Source code}

The source code is available from
\url{http://www-ljk.imag.fr/membres/Jerome.Lelong/soft/chklref/index.html}.
\\

\noindent It is distributed under the GPL license version 3 or any later
version in the hope it will be usefull but without any warrany. In the case
you find a bug in the code, could you send me a mail to
\verb!jerome.lelong@gmail.com! describing the problem with a minimal \TeX\
file to reproduce the problem.

\endpage
\end{document}