| 1 |
checkcites.lua -- Version 2.8 from December 14, 2024 |
| 2 |
==================================================== |
| 3 |
|
| 4 |
License |
| 5 |
------- |
| 6 |
|
| 7 |
Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda |
| 8 |
Copyright (c) 2024, Enrico Gregorio, Island of TeX |
| 9 |
|
| 10 |
- Enrico dot Gregorio at univr dot it |
| 11 |
- https://gitlab.com/islandoftex |
| 12 |
|
| 13 |
This script is licensed under the LaTeX Project Public License. |
| 14 |
If you want to support LaTeX development by a donation, the best |
| 15 |
way to do this is donating to the TeX Users Group. |
| 16 |
|
| 17 |
About |
| 18 |
----- |
| 19 |
|
| 20 |
checkcites is a Lua script written for the sole purpose of detecting |
| 21 |
unused or undefined references from both LaTeX auxiliary or bibliography |
| 22 |
files. We use the term *unused reference* to refer to the reference |
| 23 |
present the bibliography file -- with the '.bib' extension -- but not |
| 24 |
cited in the '.tex' file. The term *undefined reference* is exactly the |
| 25 |
opposite, i.e, the item cited in the '.tex' file, but not present in the |
| 26 |
'.bib' file. |
| 27 |
|
| 28 |
The original idea came from a question posted in the TEX community at |
| 29 |
Stack Exchange about how to check which bibliography entries were not |
| 30 |
used. We decided to write a script to check references. We opted for |
| 31 |
Lua, since it's a very straightforward language and it has an |
| 32 |
interpreter available on every modern TEX distribution. |
| 33 |
|
| 34 |
Installation |
| 35 |
------------ |
| 36 |
|
| 37 |
1. Create a new directory named 'checkcites' inside the 'scripts' |
| 38 |
directory of your TEXMF tree and copy the 'checkcites.lua' inside |
| 39 |
the new directory. In TeX Live, the new directory would be: |
| 40 |
|
| 41 |
texlive/<year>/texmf/scripts/checkcites |
| 42 |
|
| 43 |
2. Rebuild the filename databases with the proper distro tool, |
| 44 |
e.g, running 'mktexlsr'. |
| 45 |
|
| 46 |
3. Create a symbolic link to the newly created script inside |
| 47 |
the 'bin' directory of your TeX distro. In TeX Live, the |
| 48 |
full path is: |
| 49 |
|
| 50 |
texlive/<year>/bin/<arch> |
| 51 |
|
| 52 |
For TeX Live: |
| 53 |
|
| 54 |
Win32: make a copy of 'runscript.exe' inside the very same |
| 55 |
location (i.e, 'bin/win32') and rename it to |
| 56 |
'checkcites.exe'. |
| 57 |
|
| 58 |
Linux: create a symbolic link (i.e, 'ln -s') inside the 'bin' |
| 59 |
directory, targeting the script set in #1. Name it |
| 60 |
'checkcites' and give it proper execute ('x') permission. |
| 61 |
|
| 62 |
Usage |
| 63 |
----- |
| 64 |
|
| 65 |
The script is pretty simple to use. The only requirement is a recent |
| 66 |
TeX distribution, such as TeX Live. |
| 67 |
|
| 68 |
checkcites uses the generated auxiliary files to start the analysis. |
| 69 |
From version 2.0 on, the scripts supports two backends: |
| 70 |
|
| 71 |
-> bibtex |
| 72 |
|
| 73 |
Default behavior, the script checks '.aux' files looking for citations, |
| 74 |
in the form of '\citation{a}'. For every \citation line found, checkcites |
| 75 |
will extract the citations and add them to a table, even for multiple |
| 76 |
citations separated by commas, like '\citation{a,b,c}'. The citation |
| 77 |
table contains no duplicate values. At the same time checkcites also |
| 78 |
looks for bibliography data, in the form of '\bibdata{a}'. Similarly, |
| 79 |
for every '\bibdata' line found, the script will extract the bibliography |
| 80 |
data and add them to a table, even if they are separated by commas, like |
| 81 |
'\bibdata{d,e,f}'. Again, no duplicate values are allowed. Stick with this |
| 82 |
backend if you are using BibTeX or BibLaTeX with the 'backend=bibtex' |
| 83 |
package option. |
| 84 |
|
| 85 |
-> biber |
| 86 |
|
| 87 |
With this backend, the script checks '.bcf files' (which are XML-based) |
| 88 |
looking for citations, in the form of 'bcf:citekey' tags. For every tag |
| 89 |
found, checkcites will extract the corresponding values and add them to |
| 90 |
a table. The citation table contains no duplicate values. At the same |
| 91 |
time checkcites also looks for bibliography data, in the form of |
| 92 |
'bcf:datasource' tags. Similarly, for every tag found, the script will |
| 93 |
extract the bibliography data and add them to a table. Again, no duplicate |
| 94 |
values are allowed. Stick with this backend if you are using BibLaTeX with |
| 95 |
the default options or with the 'backend=biber' option explicitly set. |
| 96 |
It is important to note, however, that the 'glob=true' option is not |
| 97 |
supported yet. |
| 98 |
|
| 99 |
Open a terminal and run checkcites: |
| 100 |
|
| 101 |
$ checkcites |
| 102 |
|
| 103 |
When you run checkcites without providing any argument to it, the a message |
| 104 |
error will appear. Do not panic! Try again with the --help flag: |
| 105 |
|
| 106 |
$ checkcites --help |
| 107 |
|
| 108 |
If you are using BibTeX, simply provide the auxiliary file -- the one with |
| 109 |
the '.aux' extension -- which is generated when you compile your main '.tex' |
| 110 |
file. For example, if your main document is named 'foo.tex', you probably |
| 111 |
have a 'foo.aux' file too. Then simply invoke |
| 112 |
|
| 113 |
$ checkcites foo.aux |
| 114 |
|
| 115 |
checkcites allows an additional argument that will tell it how to |
| 116 |
behave. For example |
| 117 |
|
| 118 |
$ checkcites --unused foo.aux |
| 119 |
|
| 120 |
will make the script only look for unused references in your '.bib' |
| 121 |
file. The argument order doesn't matter, you can also run |
| 122 |
|
| 123 |
$ checkcites foo.aux --unused |
| 124 |
|
| 125 |
and get the same behaviour. Similarly, you can use |
| 126 |
|
| 127 |
$ checkcites --undefined foo.aux |
| 128 |
|
| 129 |
to make the script only look for undefined references in your |
| 130 |
'.tex' file. If you want checkcites to look for both unused and |
| 131 |
undefined references, go with |
| 132 |
|
| 133 |
$ checkcites --all foo.aux |
| 134 |
|
| 135 |
If no special argument is provided, --all is set as default. |
| 136 |
|
| 137 |
If you are using BibLaTeX, we need to inspect '.bcf' files instead. For |
| 138 |
example, if your main document is named 'foo.tex', you probably have a |
| 139 |
'foo.bcf' file too. Then invoke |
| 140 |
|
| 141 |
$ checkcites foo.aux --backend biber |
| 142 |
|
| 143 |
Note the --backend flag used for BibLaTeX support. We can even omit the |
| 144 |
file extension, the script will automatically assign one based on the |
| 145 |
current backend. |
| 146 |
|
| 147 |
That is it, folks! |
| 148 |
|
| 149 |
Official code repository |
| 150 |
------------------------ |
| 151 |
|
| 152 |
http://gitlab.com/islandoftex/checkcites |