Debian Codegraph @

texmf-dist/doc/support/checkcites/checkcites-doc.tex

raw
1 % arara: pdflatex
2 % arara: pdflatex
3 % arara: pdflatex
4 % arara: clean: { extensions: [ listing, out, aux, log, toc ] }
5 \documentclass[12pt,a4paper]{article}
6
7 \usepackage[T1]{fontenc}
8 \usepackage[utf8]{inputenc}
9
10 \usepackage[english]{babel}
11 \usepackage{tgpagella}
12
13 \usepackage[margin=1in]{geometry}
14
15 \usepackage[svgnames]{xcolor}
16 \usepackage[colorlinks, linkcolor={blue}, urlcolor={blue}]{hyperref}
17
18 \usepackage[breakable]{tcolorbox}
19 \tcbuselibrary{listings}
20
21 \newcommand{\checkcites}{\texttt{checkcites}}
22 \newcommand{\email}[1]{\small\texttt{#1}}
23 \newcommand{\version}{Version 2.8 from December 14, 2024.}
24
25 \newenvironment{infoblock}[1]
26 {\par\addvspace{\medskipamount}
27 \begin{tcolorbox}[colframe=DarkTurquoise,coltitle=black,fonttitle=\bfseries,title=#1]}
28 {\end{tcolorbox}\addvspace{\medskipamount}}
29
30 \newenvironment{terminal}
31 {\par\addvspace{\medskipamount}
32 \begin{tcolorbox}[colframe=DarkTurquoise]}
33 {\end{tcolorbox}\par\addvspace{\medskipamount}}
34
35 \title{The \checkcites\footnote{\version}\ \ script}
36 \author{%
37 Enrico Gregorio\\\email{[email protected]}\\[3ex]
38 Island of \TeX\\\email{https://gitlab.com/islandoftex}%
39 }
40 \date{}
41
42 \begin{document}
43
44 \maketitle
45
46 \tableofcontents
47
48 \section{Introduction}
49 \label{sec:intro}
50
51 \checkcites\ is a Lua script written for the sole purpose of
52 detecting unused or undefined references from both \LaTeX\ auxiliary
53 or bibliography files. We use the term \emph{unused reference} to
54 refer to the reference present the bibliography file~--~with the
55 \verb|.bib| extension~--~but not cited in the \verb|.tex| file.
56 The term \emph{undefined reference} is exactly the opposite, i.e,
57 the item cited in the \verb|.tex| file, but not present in the
58 \verb|.bib| file.
59
60 The original idea came from a question posted
61 in the \TeX\ community at Stack Exchange about
62 \href{http://tex.stackexchange.com/questions/43276}{how to check
63 which bibliography entries were not used}. We decided to write a
64 script to check references. We opted for Lua, since it is a very
65 straightforward language and it has an interpreter available on every
66 modern \TeX\ distribution.
67
68 \begin{infoblock}{Attention!}
69 From version 2.1 on, \checkcites\ relies on specific libraries
70 available in the \verb|texlua| ecosystem and thus is not be supported
71 in vanilla \verb|lua| interpreters. Please make sure to use this
72 script with an updated \verb|texlua| interpreter in order to ensure
73 the correct behaviour.
74 \end{infoblock}
75
76 \section{How the script works}
77 \label{sec:howto}
78
79 \checkcites\ uses the generated auxiliary files to start the
80 analysis. From version 2.0 on, the scripts supports two backends:
81
82 \begin{description}
83 \item[\texttt{bibtex}] Default behavior, the script checks
84 \verb|.aux| files looking for citations, in the form of
85 \verb|\citation{a}|. For every \verb|\citation| line found,
86 \checkcites\ will extract the citations and add them to a
87 table, even for multiple citations separated by commas, like
88 \verb|\citation{a,b,c}|. The citation table contains no duplicate
89 values. At the same time \checkcites\ also looks for bibliography
90 data, in the form of \verb|\bibdata{a}|. Similarly, for every
91 \verb|\bibdata| line found, the script will extract the bibliography
92 data and add them to a table, even if they are separated by commas,
93 like \verb|\bibdata{d,e,f}|. Again, no duplicate values are allowed.
94 Stick with this backend if you are using Bib\TeX\ or Bib\LaTeX\ with
95 the \verb|backend=bibtex| package option.
96
97 \item[\texttt{biber}] With this backend, the script checks
98 \verb|.bcf| files (which are XML-based) looking for citations, in the
99 form of \verb|bcf:citekey| tags. For every tag found, \checkcites\
100 will extract the corresponding values and add them to a table. The
101 citation table contains no duplicate values. At the same time
102 \checkcites\ also looks for bibliography data, in the form of
103 \verb|bcf:datasource| tags. Similarly, for every tag found, the
104 script will extract the bibliography data and add them to a table.
105 Again, no duplicate values are allowed. Stick with this backend if
106 you are using Bib\LaTeX\ with the default options or with the
107 \verb|backend=biber| option explicitly set. It is important to note,
108 however, that the \verb|glob=true| option is not supported yet.
109 \end{description}
110
111 \begin{infoblock}{Attention!}
112 If \verb|\citation{*}| (Bib\TeX) or simply \verb|*| (Bib\LaTeX)
113 is found, \checkcites\ will issue a message telling that
114 \verb|\nocite{*}| is in the \verb|.tex| document, but the script will
115 do the check nonetheless.
116 \end{infoblock}
117
118 Now, \checkcites\ will extract all entries from the bibliography
119 files found in the previous steps, regardless of which backend was
120 used. For every element in the bibliography data table, the script
121 will look for entries like \verb|@BOOK|, \verb|@ARTICLE| and so
122 forth~--~we actually use pattern matching for this~-- and add their
123 identifiers to a table. No duplicate values are allowed.
124
125 \begin{infoblock}{Attention!}
126 If \checkcites\ cannot find a certain bibliography file, the script
127 ends. Make sure to put the correct name of the bibliography file in
128 your \verb|.tex| file.
129 \end{infoblock}
130
131 Let there be $A$ and $B$ the sets of citations and references,
132 respectively. In order to get all unused references in the
133 \verb|.bib| files, we compute the set difference:
134 \[
135 B - A = \{ x : x \in B, x \notin A \}.
136 \]
137 Similarly, in order to get all undefined references in the
138 \verb|.tex| file, we compute the set difference:
139 \[
140 A - B = \{ x : x \in A, x \notin B \}.
141 \]
142 If there are either unused or undefined references, \checkcites\ will
143 print them in a list format. In Section~\ref{sec:usage} there is a
144 more complete explanation on how to use the script.
145
146 \section{Usage}
147 \label{sec:usage}
148
149 \checkcites\ is very easy to use. First of all, let us define two
150 files that will be used here to explain the script usage. Here is our
151 sample bibliography file \verb|example.bib|, with five fictional
152 entries.
153
154 \begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
155 title=Bibliography file, fonttitle=\bfseries, breakable,
156 listing options={columns=fullflexible,basicstyle=\ttfamily}}
157 @BOOK{foo:2012a,
158 title = {My Title One},
159 publisher = {My Publisher One},
160 year = {2012},
161 editor = {My Editor One},
162 author = {Author One}
163 }
164
165 @BOOK{foo:2012b,
166 title = {My Title Two},
167 publisher = {My Publisher Two},
168 year = {2012},
169 editor = {My Editor Two},
170 author = {Author Two}
171 }
172
173 @BOOK{foo:2012c,
174 title = {My Title Three},
175 publisher = {My Publisher Three},
176 year = {2012},
177 editor = {My Editor Three},
178 author = {Author Three}
179 }
180
181 @BOOK{foo:2012d,
182 title = {My Title Four},
183 publisher = {My Publisher Four},
184 year = {2012},
185 editor = {My Editor Four},
186 author = {Author Four}
187 }
188
189 @BOOK{foo:2012e,
190 title = {My Title Five},
191 publisher = {My Publisher Five},
192 year = {2012},
193 editor = {My Editor Five},
194 author = {Author Five}
195 }
196 \end{tcblisting}
197
198 The second file is our main \LaTeX{} document, \verb|document.tex|.
199 Observe that we will stick with Bib\TeX\ for now and check Bib\LaTeX\
200 later on.
201
202 \begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
203 title=Main document, fonttitle=\bfseries,
204 listing options={columns=fullflexible,basicstyle=\ttfamily}}
205 \documentclass{article}
206
207 \begin{document}
208
209 Hello world \cite{foo:2012a,foo:2012c},
210 how are you \cite{foo:2012f},
211 and goodbye \cite{foo:2012d,foo:2012a}.
212
213 \bibliographystyle{plain}
214 \bibliography{example}
215
216 \end{document}
217 \end{tcblisting}
218
219 Open a terminal and run \verb|checkcites|:
220
221 \begin{terminal}
222 \begin{verbatim}
223 $ checkcites
224 \end{verbatim}
225 \tcblower\small
226 \begin{verbatim}
227 _ _ _ _
228 ___| |_ ___ ___| |_ ___|_| |_ ___ ___
229 | _| | -_| _| '_| _| | _| -_|_ -|
230 |___|_|_|___|___|_,_|___|_|_| |___|___|
231
232 checkcites.lua -- a reference checker script (v2.8)
233 Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
234 Copyright (c) 2024, Enrico Gregorio, Island of TeX
235
236 --------------------------------------------------------------------------
237 I am sorry, but you have not provided any command line argument, including
238 files to check and options. Make sure to invoke the script with the actual
239 arguments. Refer to the user documentation if you are unsure of how this
240 tool works. The script will end now.
241 \end{verbatim}
242 \end{terminal}
243
244 If you do not have \checkcites\ installed with your \TeX\
245 distribution, you can run the standalone script \verb|checkcites.lua|
246 with either \verb|texlua| or \verb|lua|. We recommend to use
247 \verb|texlua|, as it is shipped with all the modern \TeX\
248 distributions:
249 \begin{terminal}
250 \begin{verbatim}
251 $ texlua checkcites.lua
252 \end{verbatim}
253 \end{terminal}
254
255 When you run \checkcites\ without providing any argument to it, the a
256 message error will appear. Do not panic! Try again with the
257 \verb|--help| flag:
258 \begin{terminal}
259 \begin{verbatim}
260 $ checkcites --help
261 \end{verbatim}
262 \tcblower\small
263 \begin{verbatim}
264 _ _ _ _
265 ___| |_ ___ ___| |_ ___|_| |_ ___ ___
266 | _| | -_| _| '_| _| | _| -_|_ -|
267 |___|_|_|___|___|_,_|___|_|_| |___|___|
268
269 checkcites.lua -- a reference checker script (v2.8)
270 Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
271 Copyright (c) 2024, Enrico Gregorio, Island of TeX
272
273 Usage: checkcites.lua [ [ --all | --unused | --undefined ] [ --backend
274 <arg> ] <file> [ <file 2> ... <file n> ] | --help | --version ]
275
276 -a,--all list all unused and undefined references
277 -u,--unused list only unused references in your bibliography files
278 -U,--undefined list only undefined references in your TeX source file
279 -c,--crossrefs enable cross-reference checks (disabled by default)
280 -b,--backend <arg> set the backend-based file lookup policy
281 -j,--json <file> export the generated report as a JSON file
282 -h,--help print the help message
283 -v,--version print the script version
284
285 Unless specified, the script lists all unused and undefined references by
286 default. Also, the default backend is set to "bibtex". Please refer to the
287 user documentation for more details.
288 \end{verbatim}
289 \end{terminal}
290
291 Since we are using Bib\TeX, we do not need to set up the
292 backend! Simply provide the auxiliary file~--~the one with the
293 \verb|.aux| extension~--~which is generated when you compile your
294 main \verb|.tex| file. For example, if your main document is named
295 \verb|foo.tex|, you probably have a \verb|foo.aux| file too. Let us
296 compile our sample document \verb|document.tex|:
297 \begin{terminal}
298 \begin{verbatim}
299 $ pdflatex document.tex
300 \end{verbatim}
301 \end{terminal}
302
303 After running \verb|pdflatex| on our \verb|.tex| file, there is now a
304 \verb|document.aux| file in our work directory.
305
306 \begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
307 title=Auxiliary file, fonttitle=\bfseries,
308 listing options={columns=fullflexible,basicstyle=\ttfamily}}
309 \relax
310 \citation{foo:2012a}
311 \citation{foo:2012c}
312 \citation{foo:2012f}
313 \citation{foo:2012d}
314 \citation{foo:2012a}
315 \bibstyle{plain}
316 \bibdata{example}
317 \end{tcblisting}
318
319 Now we can run \checkcites\ on the \verb|document.aux| file:
320
321 \begin{terminal}
322 \begin{verbatim}
323 $ checkcites document.aux
324 \end{verbatim}
325 \tcblower\small
326 \begin{verbatim}
327 _ _ _ _
328 ___| |_ ___ ___| |_ ___|_| |_ ___ ___
329 | _| | -_| _| '_| _| | _| -_|_ -|
330 |___|_|_|___|___|_,_|___|_|_| |___|___|
331
332 checkcites.lua -- a reference checker script (v2.8)
333 Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
334 Copyright (c) 2024, Enrico Gregorio, Island of TeX
335
336 Great, I found 4 citations in 1 file. I also found 1 bibliography file. Let
337 me check this file and extract the references. Please wait a moment.
338
339 Fantastic, I found 5 references in 1 bibliography file. Please wait a
340 moment while the reports are generated.
341
342 --------------------------------------------------------------------------
343 Report of unused references in your TeX document (that is, references
344 present in bibliography files, but not cited in the TeX source file)
345 --------------------------------------------------------------------------
346
347 Unused references in your TeX document: 2
348 => foo:2012b
349 => foo:2012e
350
351 --------------------------------------------------------------------------
352 Report of undefined references in your TeX document (that is, references
353 cited in the TeX source file, but not present in the bibliography files)
354 --------------------------------------------------------------------------
355
356 Undefined references in your TeX document: 1
357 => foo:2012f
358 \end{verbatim}
359 \end{terminal}
360
361 As we can see in the script output, \checkcites\ analyzed
362 both \verb|.aux| and \verb|.bib| files and managed to find two
363 unused references in the bibliography file~--~\verb|foo:2012b|
364 and \verb|foo:2012e|~--~and one undefined reference in the
365 document~--~\verb|foo:2012f|.
366
367 \checkcites\ allows a couple of command line flags that will tell it
368 how to behave. For example, check this command line:
369
370 \begin{terminal}
371 \begin{verbatim}
372 $ checkcites --unused document.aux
373 \end{verbatim}
374 \end{terminal}
375
376 The \verb|--unused| flag will make the script only look for unused
377 references in the \verb|.bib| file. The argument order does not
378 matter, you can also run:
379
380 \begin{terminal}
381 \begin{verbatim}
382 $ checkcites document.aux --unused
383 \end{verbatim}
384 \end{terminal}
385
386 The script will behave the same. Similarly, you can use:
387
388 \begin{terminal}
389 \begin{verbatim}
390 $ checkcites --undefined document.aux
391 \end{verbatim}
392 \end{terminal}
393
394 The \verb|--undefined| flag will make the script only look
395 for undefined references in the \verb|.tex| file. If you want
396 \checkcites\ to look for both unused and undefined references, run:
397
398 \begin{terminal}
399 \begin{verbatim}
400 $ checkcites --all document.aux
401 \end{verbatim}
402 \end{terminal}
403
404 If no special argument is provided, the \verb|--all| flag is set as
405 default.
406
407 Observe that our example relied on the default backend, which
408 uses Bib\TeX. Let us change our document a bit to make it
409 Bib\LaTeX-compliant:
410
411 \begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
412 title=Main document, fonttitle=\bfseries,
413 listing options={columns=fullflexible,basicstyle=\ttfamily}}
414 \documentclass{article}
415
416 \usepackage{biblatex}
417 \addbibresource{example.bib}
418
419 \begin{document}
420
421 Hello world \cite{foo:2012a,foo:2012c},
422 how are you \cite{foo:2012f},
423 and goodbye \cite{foo:2012d,foo:2012a}.
424
425 \printbibliography
426
427 \end{document}
428 \end{tcblisting}
429
430 As usual, let's compile our sample document \verb|document.tex|:
431
432 \begin{terminal}
433 \begin{verbatim}
434 $ pdflatex document.tex
435 \end{verbatim}
436 \end{terminal}
437
438 After running \verb|pdflatex| on our \verb|.tex| file, there is now a
439 \verb|document.aux| file in our work directory, as expected. However,
440 since we are using Bib\LaTeX\ as well, there is another file of
441 interest in our working directory, one that has a \verb|.bcf|
442 extension! In order to run \checkcites\ on that specific file, we
443 need to provide the \verb|biber| backend:
444
445 \begin{terminal}
446 \begin{verbatim}
447 $ checkcites --backend biber document.bcf
448 \end{verbatim}
449 \end{terminal}
450
451 We can even omit the file extension, the script will automatically
452 assign one based on the current backend:
453
454 \begin{terminal}
455 \begin{verbatim}
456 $ checkcites --backend biber document
457 \end{verbatim}
458 \end{terminal}
459
460 Now, let us run \checkcites\ on the \verb|.bcf| file, providing the
461 \verb|biber| backend:
462
463 \begin{terminal}
464 \begin{verbatim}
465 $ checkcites --backend biber document.bcf
466 \end{verbatim}
467 \tcblower\small
468 \begin{verbatim}
469 _ _ _ _
470 ___| |_ ___ ___| |_ ___|_| |_ ___ ___
471 | _| | -_| _| '_| _| | _| -_|_ -|
472 |___|_|_|___|___|_,_|___|_|_| |___|___|
473
474 checkcites.lua -- a reference checker script (v2.8)
475 Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
476 Copyright (c) 2024, Enrico Gregorio, Island of TeX
477
478 Great, I found 4 citations in 1 file. I also found 1 bibliography file. Let
479 me check this file and extract the references. Please wait a moment.
480
481 Fantastic, I found 5 references in 1 bibliography file. Please wait a
482 moment while the reports are generated.
483
484 --------------------------------------------------------------------------
485 Report of unused references in your TeX document (that is, references
486 present in bibliography files, but not cited in the TeX source file)
487 --------------------------------------------------------------------------
488
489 Unused references in your TeX document: 2
490 => foo:2012b
491 => foo:2012e
492
493 --------------------------------------------------------------------------
494 Report of undefined references in your TeX document (that is, references
495 cited in the TeX source file, but not present in the bibliography files)
496 --------------------------------------------------------------------------
497
498 Undefined references in your TeX document: 1
499 => foo:2012f
500 \end{verbatim}
501 \end{terminal}
502
503 If you rely on cross-references in your bibliography file,
504 \checkcites\ might complain about unused entries. We can try the
505 experimental feature available from version 2.3 on that attempts to
506 check cross-references through the \verb|--crossrefs| command line
507 flag:
508
509 \begin{terminal}
510 \begin{verbatim}
511 $ checkcites --crossrefs document.aux
512 \end{verbatim}
513 \end{terminal}
514
515 This feature is disabled by default and it is known to work with both
516 \verb|bibtex| and \verb|biber| backends. Please report if you find an
517 issue.
518
519 From version 2.7 on, \checkcites\ can export the reference report to a
520 JSON file through the \verb|--json| command line flag:
521
522 \begin{terminal}
523 \begin{verbatim}
524 $ checkcites document.aux --json report.json
525 \end{verbatim}
526 \end{terminal}
527
528 The script will generate a file named \verb|report.json| with the
529 following structure and content:
530
531 \begin{tcblisting}{colframe=DarkTurquoise,coltitle=black,listing only,
532 title=JSON file, fonttitle=\bfseries, breakable,
533 listing options={columns=fullflexible,basicstyle=\ttfamily}}
534 {
535 "settings" : {
536 "backend" : "bibtex",
537 "operation" : "list all unused and undefined references",
538 "crossrefs" : false
539 },
540 "project" : {
541 "forcibly_cite_all" : false,
542 "bibliographies" : [ "example" ],
543 "citations" : [ "foo:2012a", "foo:2012c",
544 "foo:2012f", "foo:2012d" ],
545 "crossrefs" : []
546 },
547 "results" : {
548 "unused" : {
549 "active" : true,
550 "occurrences" : [ "foo:2012b", "foo:2012e" ]
551 },
552 "undefined" : {
553 "active" : true,
554 "occurrences" : [ "foo:2012f" ]
555 }
556 }
557 }
558 \end{tcblisting}
559
560 Note that the JSON file has three main groups. The first
561 group contains the execution settings and has the backend used,
562 a description of the operation being performed, and whether
563 cross-references checks were enabled. The second group contains
564 relevant information about the project itself, such as whether all
565 references will be cited (when \verb|\nocite{*}| is found), and the
566 list of bibliographies, citations and cross-references found. Finally,
567 the third group contains the analysis results, with a special
568 \verb|active| key that indicates whether that particular check has
569 been performed, and a list of occurrences. That is all, folks!
570
571 \section{License}
572 \label{sec:license}
573
574 This script is licensed under the
575 \href{http://www.latex-project.org/lppl/}{\LaTeX\ Project Public
576 License}. If you want to support \LaTeX{} development by a
577 donation, the best way to do this is donating to the
578 \href{http://www.tug.org/}{TeX Users Group}.
579
580 \end{document}