From 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 9 Jan 2006 00:49:07 +0000 Subject: doc/latex git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/refcheck/refdemo.pdf | Bin 0 -> 59404 bytes Master/texmf-dist/doc/latex/refcheck/refdemo.tex | 233 +++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/refcheck/refdemo.pdf create mode 100644 Master/texmf-dist/doc/latex/refcheck/refdemo.tex (limited to 'Master/texmf-dist/doc/latex/refcheck') diff --git a/Master/texmf-dist/doc/latex/refcheck/refdemo.pdf b/Master/texmf-dist/doc/latex/refcheck/refdemo.pdf new file mode 100644 index 00000000000..20fd6bbe3ef Binary files /dev/null and b/Master/texmf-dist/doc/latex/refcheck/refdemo.pdf differ 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} + Unused label `eq.2' on page 1 + 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} + 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} -- cgit v1.2.3