From 09da414d5ff0230b79f8a5f7edcaa05f81e83adb Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 12 Mar 2012 23:40:01 +0000 Subject: new lua script checkcites (12mar12) git-svn-id: svn://tug.org/texlive/trunk@25623 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/support/checkcites/README | 101 ++++++ .../doc/support/checkcites/checkcites-doc.pdf | Bin 0 -> 219757 bytes .../doc/support/checkcites/checkcites-doc.tex | 339 +++++++++++++++++++++ 3 files changed, 440 insertions(+) create mode 100644 Master/texmf-dist/doc/support/checkcites/README create mode 100644 Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf create mode 100644 Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex (limited to 'Master/texmf-dist/doc/support/checkcites') diff --git a/Master/texmf-dist/doc/support/checkcites/README b/Master/texmf-dist/doc/support/checkcites/README new file mode 100644 index 00000000000..37a2b00d74c --- /dev/null +++ b/Master/texmf-dist/doc/support/checkcites/README @@ -0,0 +1,101 @@ +checkcites.lua -- Version 1.0g from March 7, 2012. +================================================== + +License +------- + +Copyright 2012 Enrico Gregorio, Paulo Roberto Massa Cereda + +- Enrico dot Gregorio at univr dot it +- cereda at users dot sf dot net + +This script is licensed under the LaTeX Project Public License. +If you want to support LaTeX development by a donation, the best +way to do this is donating to the TeX Users Group. + +About +----- + +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 'unused reference' to refer to the +reference present the bibliography file -- with the '.bib' +extension -- but not cited in the '.tex' file. The 'undefined +reference' is exactly the opposite, that is, the items cited in the +'.tex' file, but not present in the '.bib' file. + +The original idea came from a question posted in the TeX.sx community +about how to check which bibliography entries were not used. We +decided to write a script to check references. We opted for Lua, +since it's a very straightforward language and it has an interpreter +available on every modern TeX distribution. + +Installation +------------ + +1. Create a new directory named 'checkcites' inside the 'scripts' + directory of your TEXMF tree and copy the 'checkcites.lua' inside + the new directory. In TeX Live, the new directory would be: + + texlive//texmf/scripts/checkcites + +2. Rebuild the filename databases with the proper distro tool, + e.g, running 'mktexlsr'. + +3. Create a symbolic link to the newly created script inside + the 'bin' directory of your TeX distro. In TeX Live, the + full path is: + + texlive//bin/ + + For TeX Live: + + Win32: make a copy of 'runscript.exe' inside the very same + location (i.e, 'bin/win32') and rename it to + 'checkcites.exe'. + + Linux: create a symbolic link (i.e, 'ln -s') inside the 'bin' + directory, targeting the script set in #1. Name it + 'checkcites' and give it proper execute ('x') permission. + +Usage +----- + +The script is pretty simple to use. The only requirement is a recent +TeX distribution, such as TeX Live. Then run checkcites: + +$ checkcites + +It will print the script usage. The only required argument is the +'.aux' file which is generated when you compile your '.tex' file. +If your main document is named 'foo.tex', you will have a 'foo.aux' +file too. To run the script on that file, go with: + +$ checkcites foo.aux + +checkcites allows an additional argument that will tell it how to +behave. For example + +$ checkcites --unused foo.aux + +will make the script only look for unused references in your '.bib' +file. The argument order doesn't matter, you can also run + +$ checkcites foo.aux --unused + +and get the same behaviour. Similarly, you can use + +$ checkcites --undefined foo.aux + +to make the script only look for undefined references in your +'.tex' file. If you want checkcites to look for both unused and +undefined references, go with + +$ checkcites --all foo.aux + +If no special argument is provided, --all is set as default. + +Official code repository +------------------------ + +http://github.com/cereda/checkcites diff --git a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf new file mode 100644 index 00000000000..c99f2d71d52 Binary files /dev/null and b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf differ diff --git a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex new file mode 100644 index 00000000000..e520b1085f0 --- /dev/null +++ b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex @@ -0,0 +1,339 @@ +\documentclass[12pt,a4paper]{article} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} + +\usepackage[english]{babel} + +\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 1.0g from March 7, 2012.} + +\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 \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 +\emph{undefined reference} is exactly the opposite, that is, the items +cited in the \texttt{.tex} file, but not present in the \verb|.bib| +file. + +The original idea came from a question posted in the +\href{http://tex.stackexchange.com}{TeX.sx community} 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's 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 \verb|.aux| file to start the +analysis. The first step is to extract all citations found, 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}|. Then the citations table has all duplicate +values removed --~in other words, the table becomes a set. Let's call +$A$ the set of citations. + +\begin{infoblock}{Attention!} +If \verb|\citation{*}| is found, the script ends, mainly because all +citations will be used in this case. We opted for ending the script +instead of ignoring this step. +\end{infoblock} + +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}|. The table has all duplicate values removed. + +\begin{infoblock}{Attention!} +If no \verb|\bibdata| command is found, the script ends. There's +nothing to do in this case. +\end{infoblock} + +Now, \checkcites\ will extract all entries from the bibliography files +found in the previous step. 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. The script treats all +\verb|.bib| files as if they were only one. After all files have been +analyzed and all entries identifiers extracted, the table has all +duplicate values removed. Let's call $B$ the set of bibliography +entries. + +\begin{infoblock}{Attention!} +If \checkcites\ cannot find a certain bibliography file --~that is, a +\verb|.bib| file~-- the script ends. Make sure to put the correct +name of the bibliography file in your \verb|.tex| file. +\end{infoblock} + +Now we have both sets $A$ and $B$. 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's 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's define two files +that will be used here to explain the script usage. Here's 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|. + +\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 +\begin{verbatim} +checkcites.lua -- a reference checker script (v1.0g) +Copyright (c) 2012 Enrico Gregorio, Paulo Roberto Massa Cereda + +Usage: checkcites.lua [--all | --unused | --undefined] file.aux + +--all Lists all unused and undefined references. +--unused Lists only unused references in your 'bib' file. +--undefined Lists only undefined references in your 'tex' file. + +If no flag is provided, '--all' is set by default. +Be sure to have all your 'bib' files in the same directory. +\end{verbatim} +\end{terminal} + +If you don't 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's 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 +script usage will be printed, as seen in the previous output. The only +required argument is the auxiliary file --~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'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's 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 +\begin{verbatim} +checkcites.lua -- a reference checker script (v1.0g) +Copyright (c) 2012 Enrico Gregorio, Paulo Roberto Massa Cereda + +I found 4 citation(s). +Great, there's only one 'bib' file. Let me check it. +I found 5 reference(s). + +Unused reference(s) in your bibliography file(s): 2 +- foo:2012b +- foo:2012e + +Undefined reference(s) in your TeX file: 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 found 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 command line switch that will tell it how to +behave. For example, + +\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 doesn't 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. + +\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} -- cgit v1.2.3