Newer
Older
2019-Onodera / refcheck / refdemo.tex
\documentclass[11pt]{article}
\usepackage{refcheck}
\textwidth=360pt
\begin{document}
\baselineskip=4.5mm
\textheight=40\baselineskip
\pagestyle{myheadings}

\parindent=1em\parskip=0.75ex
\makeatletter

\thispagestyle{empty}

\enlargethispage{-8mm}

\def\RefCheck{\textsl{Refcheck\/}}
\def\AmS{\mbox{$\mathcal{A}$\kern-0.17em\raise-2.1pt\hbox{$\mathcal{M}$}%
\kern-0.115em$\mathcal{S}$}}
\renewcommand{\refname}{{\normalsize References}}
\def\curversion{1.9.1}
\def\curvertime{2013/02/14}

\section*{\RefCheck{\tiny${}^{\mathrm{\ \ ver.
\curversion}}_{\mathrm{\curvertime}}$} for \LaTeXe}
\markboth{\hfill\bfseries\RefCheck\ for \LaTeXe\hfill}%
{\hfill\bfseries\RefCheck\ for \LaTeXe\hfill}
This short demo file describes usage of \RefCheck\ package
with \LaTeXe. The package looks for useless labels,
unlabelled equations, unused bibliography references
and puts `keys' of labels on margins.

To start checking, one should just write
\begin{verbatim}
     \documentclass{article}
     \usepackage{refcheck}
\end{verbatim}
at the beginning of document and compile the file twice.
Then, comments on references could be found in \texttt{.log} file and
in the margins.

Consider the set of equations
\begin{eqnarray}
&&a=b\label{eq.1}\\
&&b=c\label{eq.2}\\
&&c=d,
\end{eqnarray}
written as
\begin{verbatim}
     \begin{eqnarray}
     &&a=b\label{eq.1}\\
     &&b=c\label{eq.2}\\
     &&c=d,
     \end{eqnarray}
\end{verbatim}
Then the \texttt{.log} file will contains the following messages:
{\small
\begin{verbatim}
 Package refcheck Warning: Unused label `eq.2' on input line 44.
 Package refcheck Warning: Unlabelled equation (3) on input line 46.
\end{verbatim}
}
\noindent
because the equation (\ref{eq.1}) is
referenced here by \verb#(\ref{eq.1})#, the label {\tt eq.2} of the second
equation is not used and the last equation is numbered but it is not
labelled.

Keys of labels are written in the marginal notes when the option
\textit{showrefs\/} (default) or the command \verb#\showrefnames# are
invoked. This regime can be set off by the option \textit{norefs} or (at
any point of text) by the command \verb#\norefnames#.

These marks include some information on labels.  Namely, useless
labels are underlined and bounded by `\texttt{?}', the mark `\unl@bld@mark'
means that the equation is unlabelled.  Marks are framed for
the labels which are used in text.

\newpage

The package is working in the same way with bibliography.
Consider the following short list of books:

\vspace{-1\baselineskip}

\begin{thebibliography}{9}
 \bibitem{book1}A book.
 \bibitem{book2}Another book.
 \bibitem{book3}Third book.
\end{thebibliography}
defined as follows
\begin{verbatim}
     \begin{thebibliography}{9}
     \bibitem{book1}A book.
     \bibitem{book2}Another book.
     \bibitem{book3}Third book.
     \end{thebibliography}
\end{verbatim}
Further, we use the labels of \cite{book1,book2} with the
command \verb#\cite{book1,book2}# and do not use the label
`book3'. Then, the \texttt{.log} file will contain the following message
{\small
\begin{verbatim}
 Package refcheck Warning: Unused bibitem `book3' on input line 88.
\end{verbatim}}

Commands \verb#\showcitenames# and \verb#\nocitenames# for
bibliography are analogous to the commands \verb#\showrefnames# and
\verb#\norefnames#.  They set on and off \RefCheck\ to write keys of
bibitems to output.  The same function is for the options
\textit{showcites\/} (default) and \textit{nocites}.

Options \textit{msgs\/} (default) and \textit{nomsgs\/} state whether
\RefCheck\ writes its messages to \texttt{.log} file or not.

The check of unlabelled equations can be switched off by the option
\mbox{\textit{ignoreunlbld\/}} and on (default) by the option
\textit{chkunlbld\/}.

\medskip

\RefCheck\ generally works with \AmS-\LaTeX\ and \textbf{hyperref},
but the packages must be loaded \underline{before} the \RefCheck\ package.

\medskip

\RefCheck\ can be used with the \textbf{xr} package. Suppose one invokes\\
\verb#\usepackage{xr}# \verb#\externaldocument[A:]{apps}#\\ in document foo1.tex and\\
\verb#\usepackage{xr}# \verb#\externaldocument[B:]{apps}#\\ in document foo2.tex.
Then the commands \verb#\refcheckxrdoc[A:]{foo1}# and \verb#\refcheckxrdoc[B:]{foo2}#
used in apps.tex allows to check usage of labels from apps.tex in the
external files foo1.tex and foo2.tex.

\medskip

Note the problem with implicitly cited labels.  For
example, if there is a set of equations which are labelled with
$\,$\texttt{a1,a2,...an}$\,$ and referred in document by
\verb#(\ref{a1})--(\ref{an})#, then the labels
$\,$\texttt{a2,a3,...an-1}$\,$ cannot be recognized as `used'.

\medskip
\bigskip

\textbf{Summary of options and commands:}
\medskip

\noindent
\verb#\refcheckxrdoc[prefix]{foo}# to check usage of labels
of the current document in the file foo.tex where they are used
via \verb#\usepackage{xr}# and
\verb#\externaldocument[prefix]{thisdocument}#

\medskip

\begin{raggedright}
\begin{tabular}{|l|l|c|l|}
\hline
Option & Command & Switch & Function\\
\hline
showrefs$^{*}$ & \verb#\showrefnames# & on & to put keys of labels\\
\cline{1-3}
norefs & \verb#\norefnames# & off & in the marginal notes\\
\hline
showcites$^{*}$ & \verb#\showcitenames# & on & to put bibitem keys\\
\cline{1-3}
nocites & \verb#\nocitenames# & off & in the marginal notes\\
\hline
msgs$^{*}$ & \verb#\setonmsgs# & on & to write \RefCheck's\\
\cline{1-3}
nomsgs & \verb#\setoffmsgs# & off & messages to \texttt{.log}\\
\hline
chkunlbld$^{*}$ & \verb#\checkunlbld# & on & to check unlabelled\\
\cline{1-3}
ignoreunlbld & \verb#\ignoreunlbld# & off & equations\\
\hline
\end{tabular}
\end{raggedright}
\par\noindent
\mbox{\qquad}$*$ default

\bigskip

\def\item{\noindent\mbox{\kern0.5em$\bullet$\kern0.5em}}

\textbf{Versions of \RefCheck, acknowledgments and bugs:}

\item
Versions \textbf{1.0--1.3} worked with \LaTeX2.09.  Many
thanks to Antonio Loria for his useful comments on those versions.
Version \textbf{1.2} of \RefCheck\ can be found in
\texttt{/tex-archive/obsolete/macros/latex209/contrib/} in CTAN.

\item
\textbf{1.4} was the first version of \RefCheck\ for \LaTeXe, it had a
few bugs in its functionality for \AmS-\LaTeXe's \verb#\eqref#,
\verb#\tag#, \verb#split# and \verb#multline#.  Many thanks to
Cornelius C. Noack and Mikhail Zotov for finding the problem.

\item
In the version~\textbf{1.5} the bugs were removed, but it was found
(thanks to Mikhail Zotov) that the version marks \AmS-\LaTeXe's
\verb#equation*# and \verb#gather*# as unlabelled.  The versions
\textbf{1.6} solved the problem.

\item The version \textbf{1.7} (optimized code of \textbf{1.6}) was
found by Adriano Pascoletti to work incorrectly in \verb#\caption# (more
generally, when \verb#\ref#, \verb#\pageref# occur in a material
processed to \verb#\write#, in particular, to be put into \texttt{.toc},
\texttt{.lot}, \texttt{.lof} files).

\item The version \textbf{1.8} was intended to solve the
problem. Besides, some more work was done to provide compability with
\AmS-\LaTeX\ and \textbf{hyperref}.

\item The version \textbf{1.9} added possibility to check usage of labels in external
files. More compability with \textbf{cite} package was achieved.

\item The current minor version \textbf{\curversion} is intended to fix the bug discussed
at \\
{\small\texttt{http://tex.stackexchange.com/questions/88046/problem-with-refcheck}}.\\
Besides, the format of refcheck warnings is changed.

\bigskip

\textbf{New options and commands:}

\item
Version \textbf{1.5}: \textit{msgs\/} and \textit{nomsgs\/}.

\item
Version \textbf{1.6}: \textit{ignoreunlbld\/} and
\textit{chkunlbld\/} (suggested by Miroslav Fikar).

\item
Version \textbf{1.9}: \verb#\refcheckxrdoc#.

\end{document}