checkcites.lua -- Version 2.7 from March 3, 2024
================================================

License
-------

Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
Copyright (c) 2024, Enrico Gregorio, Island of TeX

- Enrico dot Gregorio at univr dot it
- https://gitlab.com/islandoftex

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 the term *unused reference* to refer to the reference
present the bibliography file -- with the '.bib' extension -- but not
cited in the '.tex' file. The term *undefined reference* is exactly the
opposite, i.e, the item cited in the '.tex' file, but not present in the
'.bib' file.

The original idea came from a question posted in the TEX community at
Stack Exchange 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/<year>/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/<year>/bin/<arch>

   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.

checkcites uses the generated auxiliary files to start the analysis.
From version 2.0 on, the scripts supports two backends:

-> bibtex

Default behavior, the script checks '.aux' files looking for citations,
in the form of '\citation{a}'. For every \citation line found, checkcites
will extract the citations and add them to a table, even for multiple
citations separated by commas, like '\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 '\bibdata{a}'. Similarly,
for every '\bibdata' line found, the script will extract the bibliography
data and add them to a table, even if they are separated by commas, like
'\bibdata{d,e,f}'. Again, no duplicate values are allowed. Stick with this
backend if you are using BibTeX or BibLaTeX with the 'backend=bibtex'
package option.

-> biber

With this backend, the script checks '.bcf files' (which are XML-based)
looking for citations, in the form of '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
'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 BibLaTeX with
the default options or with the 'backend=biber' option explicitly set.
It is important to note, however, that the 'glob=true' option is not
supported yet.

Open a terminal and run checkcites:

$ checkcites

When you run checkcites without providing any argument to it, the a message
error will appear. Do not panic! Try again with the --help flag:

$ checkcites --help

If you are using BibTeX, simply provide the auxiliary file -- the one with
the '.aux' extension -- which is generated when you compile your main '.tex'
file. For example, if your main document is named 'foo.tex', you probably
have a 'foo.aux' file too. Then simply invoke

$ 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.

If you are using BibLaTeX, we need to inspect '.bcf' files instead. For
example, if your main document is named 'foo.tex', you probably have a
'foo.bcf' file too. Then invoke

$ checkcites foo.aux --backend biber

Note the --backend flag used for BibLaTeX support. We can even omit the
file extension, the script will automatically assign one based on the
current backend.

That is it, folks!

Official code repository
------------------------

http://gitlab.com/islandoftex/checkcites