Debian Codegraph @

texmf-dist/doc/support/checkcites/README

raw
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