summaryrefslogtreecommitdiff
path: root/support/chklref/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/chklref/doc
Initial commit
Diffstat (limited to 'support/chklref/doc')
-rw-r--r--support/chklref/doc/Makefile.in38
-rw-r--r--support/chklref/doc/chklref.tex202
2 files changed, 240 insertions, 0 deletions
diff --git a/support/chklref/doc/Makefile.in b/support/chklref/doc/Makefile.in
new file mode 100644
index 0000000000..4d99942c57
--- /dev/null
+++ b/support/chklref/doc/Makefile.in
@@ -0,0 +1,38 @@
+.PHONY: all clean distclean install uninstall
+
+include ../Make.incl
+
+DOCFILES=chklref.pdf
+VERSION_NUMBER=$(shell cat ../VERSION)
+
+
+all: chklref.pdf clean
+
+install: all
+ if ! test -d $(DESTDIR)$(DOCDIR); then $(INSTALL) -d $(DESTDIR)$(DOCDIR); fi
+ $(INSTALL) -m 644 $(DOCFILES) $(DESTDIR)$(DOCDIR)
+
+
+define chk_rm
+@for f in $(2); do echo "uninstalling $(1)/$$f"; $(RM) $(1)/$$f; done
+endef
+
+uninstall:
+ $(call chk_rm, $(DOCDIR), $(DESTDIR)$(DOCFILES))
+
+
+chklref.pdf: VERSION.tex chklref.tex
+ $(PDFLATEX) chklref.tex
+ $(PDFLATEX) chklref.tex
+
+VERSION.tex: ../VERSION
+ echo "\\def\\\chkVERSION{$(VERSION_NUMBER)}" > VERSION.tex
+
+
+clean:
+ $(RM) chklref.dvi chklref.log chklref.aux chklref.out
+
+distclean: clean
+ $(RM) chklref.pdf
+
+
diff --git a/support/chklref/doc/chklref.tex b/support/chklref/doc/chklref.tex
new file mode 100644
index 0000000000..755194aeeb
--- /dev/null
+++ b/support/chklref/doc/chklref.tex
@@ -0,0 +1,202 @@
+\documentclass[a4paper,11pt,twoside]{article}
+\usepackage{a4wide}
+\usepackage{latexsym,t1enc,lmodern,url}
+\usepackage{amssymb, amsmath}
+\usepackage[utf8]{inputenc}
+\usepackage[english]{babel}
+
+%%--------------------------------------------
+\hbadness=10000
+\emergencystretch=\hsize
+\tolerance=9999
+\textheight=9.0in
+%%--------------------------------------------
+
+\def\chk{{\it chklref}}
+\input{VERSION.tex}
+\makeatletter
+
+\title{Check \LaTeX\ references : chklref \\
+Version \chkVERSION}
+\date{\today}
+\author{Jérôme Lelong}
+
+
+\begin{document}
+\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 achieve.
+\end{abstract}
+
+\section{What {\it chklref} can do for a \LaTeX\ user ?}
+
+While writing a \LaTeX document, it is quite common to add labels that will
+reveal unused in the end, 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 do so.
+
+\chk\ parses the \LaTeX\ file to detect labels that do not have any 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 star version: it looks
+for the non star environments not containing any label.
+
+For instance, consider you a have a \LaTeX\ 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! in order to remove the unneeded number appearing next to the
+equation.
+
+Star environments with labels are also tracked because with most \LaTeX\
+distributions it does not even 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 is about labels in star environments and one is about
+unneeded labels. Each of these output lines begins with a line number referring
+to the parsed \LaTeX\ file. Then, the decision to be made 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
+confusion.
+
+\begin{figure}[h!]
+ \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, see
+Figure~\ref{fig:output}. In this case, a ``remove bibitem'' message is printed.
+\begin{figure}[h!]
+ \centering
+\begin{verbatim}
+**********************************
+** Non cited Bibliography entries **
+**********************************
+remove bibitem : premia
+\end{verbatim}
+ \caption{Bibliography analysis}
+ \label{fig:biblio}
+\end{figure}
+
+
+\section{Usage}
+
+Typical usage : \verb!chklref file.tex!.
+\\
+
+\section{Installation}
+
+
+\subsection{System wide installation}
+
+You need the root privileges to perform this installation. \\
+
+\noindent Simply run
+
+\begin{verbatim}
+ ./configure
+ make
+ sudo make install
+\end{verbatim}
+This package follows the TDS\footnote{TeX Directory Structure
+ \url{http://www.tug.org/twg/tds/}} and installs:
+\begin{itemize}
+ \item the main program in \verb!$(prefix)!
+ \item the \TeX\ package \verb!chklref.sty! in \verb!$(texmf_prefix)/tex/latex/chklref!
+ \item the manual \verb!chklref.pdf! in \verb!$(texmf_prefix)/doc/latex/chklref!
+ \item the Perl parser \verb!chkparser! in \verb!$(texmf_prefix)/scripts/chklref!
+\end{itemize}
+The following default values are used
+\begin{itemize}
+ \item \verb!prefix=/usr/local!
+ \item \verb!texmf_prefix=$(prefix)/share/texmf!
+\end{itemize}
+
+These default values can be changed with the flags \verb!--prefix! and
+\verb!--with-texmf-prefix! passed to the configure script.\\
+
+Do not forget to run "sudo texhash" to update your \TeX\ Directory Structure.
+
+\paragraph{Notes for installation under MacOS X.}
+
+Under MacOS X, your tex distribution is probably not installed under
+\verb!/usr/share/texmf! nor \verb!/usr/local/share/texmf!. You are most likely using
+the TeXlive distribution provided by MacTeX which installs under
+\verb!/usr/local/texlive!. Hence, you should invoke configure with
+
+\begin{verbatim}
+ --with-texmf-prefix=/usr/local/texlive/texmf-local
+\end{verbatim}
+
+\subsection{Installation on a single account}
+
+This installation does not require any particular privileges.
+
+We assume that the directory \verb!$HOME/bin! is in your PATH, if not you have to add it
+your PATH. You can install the software on your account using
+\begin{verbatim}
+ ./configure --prefix=$HOME --with-texmf-prefix=$HOME/texmf
+ make
+ make install
+\end{verbatim}
+For the installation on a single account, there is \emph{no} need to run
+texhash.
+
+
+\paragraph{Notes for installation under MacOS X.}
+
+The directory \verb!$HOME/texmf! may not exist because it is replaced by
+\verb!$HOME/Library/texmf! instead. So, either use
+\begin{verbatim}
+ ./configure --prefix=$HOME --with-texmf-prefix=$HOME/Library/texmf
+\end{verbatim}
+or create a symbolic link
+\begin{verbatim}
+ ln -s $HOME/Library/texmf $HOME/texmf
+\end{verbatim}
+
+
+
+\section{Requirements}
+
+\chk\ is written mainly in \TeX\ with a small Perl script to parser the output
+generated by the \TeX\ package. It should be working with any standard Perl
+installation.
+
+\section{Source code}
+
+The source code is available from GitHub
+\url{https://github.com/jlelong/chklref}.
+\\
+
+\noindent It is distributed under the GPL licence version 3 or any later version
+in the hope it will be useful but without any warranty. Should you find a bug in
+chklref, send me a mail to \verb!jerome.lelong@gmail.com! describing the problem
+with a minimal \LaTeX\ file to reproduce the problem or fill in an issue on the
+GitHub repository.
+
+\end{document}
+% vim: set spelllang=en spell:
+