diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/chklref/doc |
Initial commit
Diffstat (limited to 'support/chklref/doc')
-rw-r--r-- | support/chklref/doc/Makefile.in | 38 | ||||
-rw-r--r-- | support/chklref/doc/chklref.tex | 202 |
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: + |