summaryrefslogtreecommitdiff
path: root/support/checkcites/checkcites-doc.tex
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/checkcites/checkcites-doc.tex
Initial commit
Diffstat (limited to 'support/checkcites/checkcites-doc.tex')
-rw-r--r--support/checkcites/checkcites-doc.tex509
1 files changed, 509 insertions, 0 deletions
diff --git a/support/checkcites/checkcites-doc.tex b/support/checkcites/checkcites-doc.tex
new file mode 100644
index 0000000000..447505587c
--- /dev/null
+++ b/support/checkcites/checkcites-doc.tex
@@ -0,0 +1,509 @@
+% arara: pdflatex
+% arara: pdflatex
+% arara: pdflatex
+% arara: clean: { extensions: [ listing, out, aux, log, toc ] }
+\documentclass[12pt,a4paper]{article}
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+
+\usepackage[english]{babel}
+\usepackage{tgpagella}
+
+\usepackage[margin=1in]{geometry}
+
+\usepackage[svgnames]{xcolor}
+\usepackage[colorlinks, linkcolor={blue}, urlcolor={blue}]{hyperref}
+
+\usepackage{tcolorbox}
+\tcbuselibrary{listings}
+
+\newcommand{\checkcites}{\texttt{checkcites}}
+\newcommand{\email}[1]{\small\texttt{#1}}
+\newcommand{\version}{Version 2.1 from July 26, 2019.}
+
+\newenvironment{infoblock}[1]
+ {\par\addvspace{\medskipamount}
+ \begin{tcolorbox}[colframe=DarkTurquoise,coltitle=black,fonttitle=\bfseries,title=#1]}
+ {\end{tcolorbox}\addvspace{\medskipamount}}
+
+\newenvironment{terminal}
+ {\par\addvspace{\medskipamount}
+ \begin{tcolorbox}[colframe=DarkTurquoise]}
+ {\end{tcolorbox}\par\addvspace{\medskipamount}}
+
+\title{The \checkcites\footnote{\version}\ \ script}
+\author{%
+ Enrico Gregorio\\\email{Enrico dot Gregorio at univr dot it}\\[3ex]
+ Paulo Roberto Massa Cereda\\\email{cereda at users dot sf dot net}%
+}
+\date{}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+\label{sec:intro}
+
+\checkcites\ is a Lua script written for the sole purpose of
+detecting unused or undefined references from both \LaTeX\ auxiliary
+or bibliography files. We use the term \emph{unused reference} to
+refer to the reference present the bibliography file~--~with the
+\verb|.bib| extension~--~but not cited in the \verb|.tex| file.
+The term \emph{undefined reference} is exactly the opposite, i.e,
+the item cited in the \verb|.tex| file, but not present in the
+\verb|.bib| file.
+
+The original idea came from a question posted
+in the \TeX\ community at Stack Exchange about
+\href{http://tex.stackexchange.com/questions/43276}{how to check
+which bibliography entries were not used}. We decided to write a
+script to check references. We opted for Lua, since it is a very
+straightforward language and it has an interpreter available on every
+modern \TeX\ distribution.
+
+\begin{infoblock}{Attention!}
+\checkcites\ is known to run with the most recent \verb|texlua| and
+\verb|lua| interpreters. Unfortunately, the code is incompatible with
+interpreters prior to the Lua 5.1 language specification.
+\end{infoblock}
+
+\section{How the script works}
+\label{sec:howto}
+
+\checkcites\ uses the generated auxiliary files to start the
+analysis. From version 2.0 on, the scripts supports two backends:
+
+\begin{description}
+\item[\texttt{bibtex}] Default behavior, the script checks
+\verb|.aux| files looking for citations, in the form of
+\verb|\citation{a}|. For every \verb|\citation| line found,
+\checkcites\ will extract the citations and add them to a
+table, even for multiple citations separated by commas, like
+\verb|\citation{a,b,c}|. The citation table contains no duplicate
+values. At the same time \checkcites\ also looks for bibliography
+data, in the form of \verb|\bibdata{a}|. Similarly, for every
+\verb|\bibdata| line found, the script will extract the bibliography
+data and add them to a table, even if they are separated by commas,
+like \verb|\bibdata{d,e,f}|. Again, no duplicate values are allowed.
+Stick with this backend if you are using Bib\TeX\ or Bib\LaTeX\ with
+the \verb|backend=bibtex| package option.
+
+\item[\texttt{biber}] With this backend, the script checks
+\verb|.bcf| files (which are XML-based) looking for citations, in the
+form of \verb|bcf:citekey| tags. For every tag found, \checkcites\
+will extract the corresponding values and add them to a table. The
+citation table contains no duplicate values. At the same time
+\checkcites\ also looks for bibliography data, in the form of
+\verb|bcf:datasource| tags. Similarly, for every tag found, the
+script will extract the bibliography data and add them to a table.
+Again, no duplicate values are allowed. Stick with this backend if
+you are using Bib\LaTeX\ with the default options or with the
+\verb|backend=biber| option explicitly set.
+\end{description}
+
+\begin{infoblock}{Attention!}
+If \verb|\citation{*}| (Bib\TeX) or simply \verb|*| (Bib\LaTeX)
+is found, \checkcites\ will issue a message telling that
+\verb|\nocite{*}| is in the \verb|.tex| document, but the script will
+do the check nonetheless.
+\end{infoblock}
+
+Now, \checkcites\ will extract all entries from the bibliography
+files found in the previous steps, regardless of which backend was
+used. For every element in the bibliography data table, the script
+will look for entries like \verb|@BOOK|, \verb|@ARTICLE| and so
+forth~--~we actually use pattern matching for this~-- and add their
+identifiers to a table. No duplicate values are allowed.
+
+\begin{infoblock}{Attention!}
+If \checkcites\ cannot find a certain bibliography file, the script
+ends. Make sure to put the correct name of the bibliography file in
+your \verb|.tex| file.
+\end{infoblock}
+
+Let there be $A$ and $B$ the sets of citations and references,
+respectively. In order to get all unused references in the
+\verb|.bib| files, we compute the set difference:
+\[
+B - A = \{ x : x \in B, x \notin A \}.
+\]
+Similarly, in order to get all undefined references in the
+\verb|.tex| file, we compute the set difference:
+\[
+A - B = \{ x : x \in A, x \notin B \}.
+\]
+If there are either unused or undefined references, \checkcites\ will
+print them in a list format. In Section~\ref{sec:usage} there is a
+more complete explanation on how to use the script.
+
+\section{Usage}
+\label{sec:usage}
+
+\checkcites\ is very easy to use. First of all, let us define two
+files that will be used here to explain the script usage. Here is our
+sample bibliography file \verb|example.bib|, with five fictional
+entries.
+
+\begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
+ title=Bibliography file, fonttitle=\bfseries,
+ listing options={columns=fullflexible,basicstyle=\ttfamily}}
+@BOOK{foo:2012a,
+ title = {My Title One},
+ publisher = {My Publisher One},
+ year = {2012},
+ editor = {My Editor One},
+ author = {Author One}
+}
+
+@BOOK{foo:2012b,
+ title = {My Title Two},
+ publisher = {My Publisher Two},
+ year = {2012},
+ editor = {My Editor Two},
+ author = {Author Two}
+}
+
+@BOOK{foo:2012c,
+ title = {My Title Three},
+ publisher = {My Publisher Three},
+ year = {2012},
+ editor = {My Editor Three},
+ author = {Author Three}
+}
+
+@BOOK{foo:2012d,
+ title = {My Title Four},
+ publisher = {My Publisher Four},
+ year = {2012},
+ editor = {My Editor Four},
+ author = {Author Four}
+}
+
+@BOOK{foo:2012e,
+ title = {My Title Five},
+ publisher = {My Publisher Five},
+ year = {2012},
+ editor = {My Editor Five},
+ author = {Author Five}
+}
+\end{tcblisting}
+
+The second file is our main \LaTeX{} document, \verb|document.tex|.
+Observe that we will stick with Bib\TeX\ for now and check Bib\LaTeX\
+later on.
+
+\begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
+ title=Main document, fonttitle=\bfseries,
+ listing options={columns=fullflexible,basicstyle=\ttfamily}}
+\documentclass{article}
+
+\begin{document}
+
+Hello world \cite{foo:2012a,foo:2012c},
+how are you \cite{foo:2012f},
+and goodbye \cite{foo:2012d,foo:2012a}.
+
+\bibliographystyle{plain}
+\bibliography{example}
+
+\end{document}
+\end{tcblisting}
+
+Open a terminal and run \verb|checkcites|:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites
+\end{verbatim}
+\tcblower\small
+\begin{verbatim}
+ _ _ _ _
+ ___| |_ ___ ___| |_ ___|_| |_ ___ ___
+| _| | -_| _| '_| _| | _| -_|_ -|
+|___|_|_|___|___|_,_|___|_|_| |___|___|
+
+checkcites.lua -- a reference checker script (v2.1)
+Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Roberto Massa Cereda
+
+--------------------------------------------------------------------------
+I am sorry, but you have not provided any command line argument, including
+files to check and options. Make sure to invoke the script with the actual
+arguments. Refer to the user documentation if you are unsure of how this
+tool works. The script will end now.
+\end{verbatim}
+\end{terminal}
+
+If you do not have \checkcites\ installed with your \TeX\
+distribution, you can run the standalone script \verb|checkcites.lua|
+with either \verb|texlua| or \verb|lua|. We recommend to use
+\verb|texlua|, as it is shipped with all the modern \TeX\
+distributions:
+\begin{terminal}
+\begin{verbatim}
+$ texlua checkcites.lua
+\end{verbatim}
+\end{terminal}
+
+When you run \checkcites\ without providing any argument to it, the a
+message error will appear. Do not panic! Try again with the
+\verb|--help| flag:
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --help
+\end{verbatim}
+\tcblower\small
+\begin{verbatim}
+ _ _ _ _
+ ___| |_ ___ ___| |_ ___|_| |_ ___ ___
+| _| | -_| _| '_| _| | _| -_|_ -|
+|___|_|_|___|___|_,_|___|_|_| |___|___|
+
+checkcites.lua -- a reference checker script (v2.1)
+Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Roberto Massa Cereda
+
+Usage: checkcites.lua [ [ --all | --unused | --undefined ] [ --backend
+<arg> ] <file> [ <file 2> ... <file n> ] | --help | --version ]
+
+-a,--all list all unused and undefined references
+-u,--unused list only unused references in your bibliography files
+-U,--undefined list only undefined references in your TeX source file
+-b,--backend <arg> set the backend-based file lookup policy
+-h,--help print the help message
+-v,--version print the script version
+
+Unless specified, the script lists all unused and undefined references by
+default. Also, the default backend is set to "bibtex". Please refer to the
+user documentation for more details.
+\end{verbatim}
+\end{terminal}
+
+Since we are using Bib\TeX, we do not need to set up the
+backend! Simply provide the auxiliary file~--~the one with the
+\verb|.aux| extension~--~which is generated when you compile your
+main \verb|.tex| file. For example, if your main document is named
+\verb|foo.tex|, you probably have a \verb|foo.aux| file too. Let us
+compile our sample document \verb|document.tex|:
+\begin{terminal}
+\begin{verbatim}
+$ pdflatex document.tex
+\end{verbatim}
+\end{terminal}
+
+After running \verb|pdflatex| on our \verb|.tex| file, there is now a
+\verb|document.aux| file in our work directory.
+
+\begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
+ title=Auxiliary file, fonttitle=\bfseries,
+ listing options={columns=fullflexible,basicstyle=\ttfamily}}
+\relax
+\citation{foo:2012a}
+\citation{foo:2012c}
+\citation{foo:2012f}
+\citation{foo:2012d}
+\citation{foo:2012a}
+\bibstyle{plain}
+\bibdata{example}
+\end{tcblisting}
+
+Now we can run \checkcites\ on the \verb|document.aux| file:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites document.aux
+\end{verbatim}
+\tcblower\small
+\begin{verbatim}
+ _ _ _ _
+ ___| |_ ___ ___| |_ ___|_| |_ ___ ___
+| _| | -_| _| '_| _| | _| -_|_ -|
+|___|_|_|___|___|_,_|___|_|_| |___|___|
+
+checkcites.lua -- a reference checker script (v2.1)
+Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Roberto Massa Cereda
+
+Great, I found 4 citations in 1 file. I also found 1 bibliography file. Let
+me check this file and extract the references. Please wait a moment.
+
+Fantastic, I found 5 references in 1 bibliography file. Please wait a
+moment while the reports are generated.
+
+--------------------------------------------------------------------------
+Report of unused references in your TeX document (that is, references
+present in bibliography files, but not cited in the TeX source file)
+--------------------------------------------------------------------------
+
+Unused references in your TeX document: 2
+=> foo:2012b
+=> foo:2012e
+
+--------------------------------------------------------------------------
+Report of undefined references in your TeX document (that is, references
+cited in the TeX source file, but not present in the bibliography files)
+--------------------------------------------------------------------------
+
+Undefined references in your TeX document: 1
+=> foo:2012f
+\end{verbatim}
+\end{terminal}
+
+As we can see in the script output, \checkcites\ analyzed
+both \verb|.aux| and \verb|.bib| files and managed to find two
+unused references in the bibliography file~--~\verb|foo:2012b|
+and \verb|foo:2012e|~--~and one undefined reference in the
+document~--~\verb|foo:2012f|.
+
+\checkcites\ allows a couple of command line flags that will tell it
+how to behave. For example, check this command line:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --unused document.aux
+\end{verbatim}
+\end{terminal}
+
+The \verb|--unused| flag will make the script only look for unused
+references in the \verb|.bib| file. The argument order does not
+matter, you can also run:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites document.aux --unused
+\end{verbatim}
+\end{terminal}
+
+The script will behave the same. Similarly, you can use:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --undefined document.aux
+\end{verbatim}
+\end{terminal}
+
+The \verb|--undefined| flag will make the script only look
+for undefined references in the \verb|.tex| file. If you want
+\checkcites\ to look for both unused and undefined references, run:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --all document.aux
+\end{verbatim}
+\end{terminal}
+
+If no special argument is provided, the \verb|--all| flag is set as
+default.
+
+Observe that our example relied on the default backend, which
+uses Bib\TeX. Let us change our document a bit to make it
+Bib\LaTeX-compliant:
+
+\begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
+ title=Main document, fonttitle=\bfseries,
+ listing options={columns=fullflexible,basicstyle=\ttfamily}}
+\documentclass{article}
+
+\usepackage{biblatex}
+\addbibresource{example.bib}
+
+\begin{document}
+
+Hello world \cite{foo:2012a,foo:2012c},
+how are you \cite{foo:2012f},
+and goodbye \cite{foo:2012d,foo:2012a}.
+
+\printbibliography
+
+\end{document}
+\end{tcblisting}
+
+As usual, let's compile our sample document \verb|document.tex|:
+
+\begin{terminal}
+\begin{verbatim}
+$ pdflatex document.tex
+\end{verbatim}
+\end{terminal}
+
+After running \verb|pdflatex| on our \verb|.tex| file, there is now a
+\verb|document.aux| file in our work directory, as expected. However,
+since we are using Bib\LaTeX\ as well, there is another file of
+interest in our working directory, one that has a \verb|.bcf|
+extension! In order to run \checkcites\ on that specific file, we
+need to provide the \verb|biber| backend:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --backend biber document.bcf
+\end{verbatim}
+\end{terminal}
+
+We can even omit the file extension, the script will automatically
+assign one based on the current backend:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --backend biber document
+\end{verbatim}
+\end{terminal}
+
+Now, let us run \checkcites\ on the \verb|.bcf| file, providing the
+\verb|biber| backend:
+
+\begin{terminal}
+\begin{verbatim}
+$ checkcites --backend biber document.bcf
+\end{verbatim}
+\tcblower\small
+\begin{verbatim}
+ _ _ _ _
+ ___| |_ ___ ___| |_ ___|_| |_ ___ ___
+| _| | -_| _| '_| _| | _| -_|_ -|
+|___|_|_|___|___|_,_|___|_|_| |___|___|
+
+checkcites.lua -- a reference checker script (v2.1)
+Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Roberto Massa Cereda
+
+Great, I found 4 citations in 1 file. I also found 1 bibliography file. Let
+me check this file and extract the references. Please wait a moment.
+
+Fantastic, I found 5 references in 1 bibliography file. Please wait a
+moment while the reports are generated.
+
+--------------------------------------------------------------------------
+Report of unused references in your TeX document (that is, references
+present in bibliography files, but not cited in the TeX source file)
+--------------------------------------------------------------------------
+
+Unused references in your TeX document: 2
+=> foo:2012b
+=> foo:2012e
+
+--------------------------------------------------------------------------
+Report of undefined references in your TeX document (that is, references
+cited in the TeX source file, but not present in the bibliography files)
+--------------------------------------------------------------------------
+
+Undefined references in your TeX document: 1
+=> foo:2012f
+\end{verbatim}
+\end{terminal}
+
+That is all, folks!
+
+\section{License}
+\label{sec:license}
+
+This script is licensed under the
+\href{http://www.latex-project.org/lppl/}{\LaTeX\ Project Public
+License}. If you want to support \LaTeX{} development by a
+donation, the best way to do this is donating to the
+\href{http://www.tug.org/}{TeX Users Group}.
+
+\begin{infoblock}{Official code repository}
+\url{http://github.com/cereda/checkcites}
+\end{infoblock}
+
+\end{document}