summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/refcheck/refdemo.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/refcheck/refdemo.tex')
-rw-r--r--Master/texmf-dist/doc/latex/refcheck/refdemo.tex233
1 files changed, 233 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/refcheck/refdemo.tex b/Master/texmf-dist/doc/latex/refcheck/refdemo.tex
new file mode 100644
index 00000000000..0eb5372dcd6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refcheck/refdemo.tex
@@ -0,0 +1,233 @@
+\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}
+\def\curvertime{2004/03/31}
+
+\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}
+ <Info by RefCheck> Unused label `eq.2' on page 1
+ <Info by RefCheck> Unlabelled equation (3) on page 1
+\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}
+ <Info by RefCheck> Unused bibitem `book3' on page 2
+\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 current version \textbf{\curversion} adds possibility to check
+usage of labels in external files. More compability with \textbf{cite} package
+was achieved.
+
+\medskip
+
+\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}