summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/refcheck/refdemo.tex
blob: a40d2c9c5af70936483730d90c5abb679c734abf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
\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}