checkcites.lua -- Version 2.8 from December 14, 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