1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
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
|
