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/checkcites/checkcites-doc.tex |
Initial commit
Diffstat (limited to 'support/checkcites/checkcites-doc.tex')
-rw-r--r-- | support/checkcites/checkcites-doc.tex | 509 |
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} |