Debian Codegraph @

texmf-dist/source/bibtex/bibcop/bibcop.dtx

raw
1 % \iffalse meta-comment
2 % SPDX-FileCopyrightText: Copyright (c) 2022-2025 Yegor Bugayenko
3 % SPDX-License-Identifier: MIT
4 % \fi
5
6 % \CheckSum{0}
7 %
8 % \CharacterTable
9 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
10 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
11 % Digits \0\1\2\3\4\5\6\7\8\9
12 % Exclamation \! Double quote \" Hash (number) \#
13 % Dollar \$ Percent \% Ampersand \&
14 % Acute accent \' Left paren \( Right paren \)
15 % Asterisk \* Plus \+ Comma \,
16 % Minus \- Point \. Solidus \/
17 % Colon \: Semicolon \; Less than \<
18 % Equals \= Greater than \> Question mark \?
19 % Commercial at \@ Left bracket \[ Backslash \\
20 % Right bracket \] Circumflex \^ Underscore \_
21 % Grave accent \` Left brace \{ Vertical bar \|
22 % Right brace \} Tilde \~}
23
24 % \GetFileInfo{bibcop.dtx}
25 % \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}
26
27 % \iffalse
28 %<*driver>
29 \ProvidesFile{bibcop.dtx}
30 %</driver>
31 %<package>\NeedsTeXFormat{LaTeX2e}
32 %<package>\ProvidesPackage{bibcop}
33 %<*package>
34 [2025/04/28 0.0.32 Style Checker of Bibliography Files]
35 %</package>
36 %<*driver>
37 \documentclass{ltxdoc}
38 \usepackage[T1]{fontenc}
39 \usepackage[maxnames=1,minnames=1,maxbibnames=1,natbib=true,citestyle=authoryear,bibstyle=authoryear,doi=false,url=false,isbn=false,isbn=false]{biblatex}
40 \addbibresource{bibcop.bib}
41 \usepackage[tt=false, type1=true]{libertine}
42 \usepackage{microtype}
43 \AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
44 \usepackage{href-ul}
45 \usepackage{xcolor}
46 \usepackage{graphicx}
47 \PageIndex
48 \EnableCrossrefs
49 \CodelineIndex
50 \RecordChanges
51 \begin{document}
52 \DocInput{bibcop.dtx}
53 \PrintChanges
54 \PrintIndex
55 \end{document}
56 %</driver>
57 % \fi
58
59 % \title{\includegraphics[height=1in]{bibcop-logo.pdf} \\ |bibcop|: \LaTeX{} Package \\ for Style Checking of |.bib| Files\thanks{The sources are in GitHub at \href{https://github.com/yegor256/bibcop}{yegor256/bibcop}}}
60 % \author{Yegor Bugayenko \\ \texttt{[email protected]}}
61 % \date{\filedate, \fileversion}
62 %
63 % \maketitle
64 %
65 % \textbf{\color{red}NB!}
66 % You must run \TeX{} processor with |--shell-escape| option
67 % and you must have \href{https://www.perl.org}{Perl} installed.
68 % This package doesn't work on Windows.
69
70 % \section{Introduction}
71 %
72 % This package scans a |.bib| file for style errors and emits
73 % warning messages if any issues are found (the package must be included before
74 % all other bibliography related packages):
75 %\iffalse
76 %<*verb>
77 %\fi
78 \begin{verbatim}
79 \documentclass{article}
80 \usepackage{bibcop}
81 \begin{document}
82 \bibliographystyle{plain}
83 \bibliography{main}
84 \end{document}
85 \end{verbatim}
86 %\iffalse
87 %</verb>
88 %\fi
89 % Some warnings may be printed in the \TeX{} log.
90 % Once the issues in the |main.bib| file are fixed, the warnings disappear.
91
92 % Bibcop doesn't pay much attention to the formatting of the |.bib| file. It doesn't emit
93 % warnings if a comma is missed after the last tag in a \BibTeX{} entry or the tags
94 % and their equation symbols are not aligned. Instead, Bibcop is focused on the content
95 % of the tags and their possible inconsistencies.
96
97 % If the |.sty| file is used directly (without installing it into the \TeX{} tree),
98 % the |bibcop.pl| file must also be placed next to it --- it is the Perl script that does all the work
99 % of checking your |.bib| files. The |.sty| is just a simple wrapper around it.
100
101 % The |\usepackage{bibcop}| must stay right after |\usepackage{biblatex}|
102 % (if Bib\LaTeX{} is used), otherwise
103 % there won't be any warnings from |bibcop|.
104
105 % \section{Package Options}
106
107 % It's possible to configure the behavior of the package with the help of a few package options:
108
109 % \DescribeMacro{verbose}
110 % The |verbose| package option prints all debugging messages to the \TeX{} log:
111 %\iffalse
112 %<*verb>
113 %\fi
114 \begin{verbatim}
115 \usepackage[verbose]{bibcop}
116 \end{verbatim}
117 %\iffalse
118 %</verb>
119 %\fi
120
121 % \DescribeMacro{script}
122 % The package depends on the |bibcop.pl| file, which is a Perl script that does all the work. This file is supposed to be located either in the current directory or in the |texmf-dist/scripts/bibcop/| directory. Using the |script| option the location of the script may be explicitly defined (it is not recommended to use this option unless there is a special demand for it):
123 %\iffalse
124 %<*verb>
125 %\fi
126 \begin{verbatim}
127 \usepackage[script=my-perl-script.pl]{bibcop}
128 \end{verbatim}
129 %\iffalse
130 %</verb>
131 %\fi
132
133 % \DescribeMacro{no*}
134 % It's possible to suppress certain rules, by using one of the |no*| package options:
135 %\iffalse
136 %<*verb>
137 %\fi
138 \begin{verbatim}
139 \usepackage[nodoi,nowraps]{bibcop}
140 \end{verbatim}
141 %\iffalse
142 %</verb>
143 %\fi
144 % The following options are available:
145 % \begin{itemize}\setlength\itemsep{0pt}
146 % \item |nocaps| allows arbitrary capitalization in titles;
147 % \item |nowraps| allows titles to have no double curly braces;
148 % \item |nodoi| allows the absence of the |doi| tag in all entries;
149 % \item |noinproc| allows the |booktitle| tag in |@inproceedings| entries to not start with ``Proceedings of the'';
150 % \item |noorg| allows mentioning of ACM/IEEE in the |booktitle| tag;
151 % \item |notags| allows any tags and allows missing important tags.
152 % \end{itemize}
153
154 % \section{The Rules}
155
156 % This is a more or less complete list of rules enforced on a |.bib| file:
157
158 % \DescribeMacro{types}
159 % Only |@article|, |@book|, |@inproceedings|, |@phdthesis|, |@incollection|, and |@misc| types of \BibTeX{} entries are allowed.
160 % Everything else, like |@manual|, |@inbook|, and \href{https://www.bibtex.com/e/entry-types/}{many others} are simply prohibited.
161 % The mentioned four should be enough for everything.
162
163 % \DescribeMacro{tags}
164 % There are pretty limited lists of allowed tags for each type of \BibTeX{} entry. The tags
165 % that are not in the list are prohibited to use.
166
167 % \DescribeMacro{doi}
168 % Every \BibTeX{} entry must have the |doi| tag, which is a unique
169 % \href{https://www.doi.org}{Digital Object Identifier}
170 % of the material that you reference. It seems to be a good practice, in order to avoid ambiguity,
171 % to always mention the DOI.
172 % It is also recommended to use the \href{https://ctan.org/pkg/doi}{doi} package,
173 % in order to make all ``|doi|'' fields turned into hyper links.
174
175 % \DescribeMacro{caps}
176 % In the |title|, |booktitle|, and |journal| tags, all major words must be capitalized,
177 % as it is \href{https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case}{recommended} by APA:
178 %\iffalse
179 %<*verb>
180 %\fi
181 \begin{verbatim}
182 title = {A Preliminary Architecture for a Basic Data-Flow Processor}
183 \end{verbatim}
184 %\iffalse
185 %</verb>
186 %\fi
187 % Here, the leading ``|A|'' is capital because it opens the title.
188 % The word ``|for|'' and the article ``|a|'' are minor words, that's why they are in lower case.
189 % Both parts of the composite word ``|Data-Flow|'' are capitalized.
190 % Sometimes this rule may need to be violated, when there is custom capitalization, as it is done
191 % by the author of the paper. In order to do this, the words with custom capitalization
192 % must be wrapped in curled brackets, for example:
193 %\iffalse
194 %<*verb>
195 %\fi
196 \begin{verbatim}
197 title = {Structured Programming {with} Go {To} Statements}
198 \end{verbatim}
199 %\iffalse
200 %</verb>
201 %\fi
202 % This rule may be disabled by the |nocaps| package option.
203
204 % \DescribeMacro{author}
205 % The |author| must contain a list of authors separated by ``|and|''. Each author
206 % must have two parts separated by a comma. The first part is the last name of the author,
207 % the second part is a list of their first names separated by a space, for example:
208 %\iffalse
209 %<*verb>
210 %\fi
211 \begin{verbatim}
212 author = {Knuth, Donald E. and Duane, Bibby}
213 \end{verbatim}
214 %\iffalse
215 %</verb>
216 %\fi
217 % When the list of authors is too long, it's possible to say ``|and others|'':
218 %\iffalse
219 %<*verb>
220 %\fi
221 \begin{verbatim}
222 author = {Knuth, Donald E. and others}
223 \end{verbatim}
224 %\iffalse
225 %</verb>
226 %\fi
227 % When first names are shortened to a single letter, it has to have a tailing dot.
228 % A specially pronounced author may be wrapped in curled brackets, to make Bibcop ignore it:
229 %\iffalse
230 %<*verb>
231 %\fi
232 \begin{verbatim}
233 author = {{Some author} and {I}}
234 \end{verbatim}
235 %\iffalse
236 %</verb>
237 %\fi
238
239 % \DescribeMacro{shorts}
240 % It is not allowed to shorten any words aside from the |author| tag, for example this is illegal:
241 %\iffalse
242 %<*verb>
243 %\fi
244 \begin{verbatim}
245 journal = {J. Log. Comput.}
246 \end{verbatim}
247 %\iffalse
248 %</verb>
249 %\fi
250 % This must be replaced with the following:
251 %\iffalse
252 %<*verb>
253 %\fi
254 \begin{verbatim}
255 journal = {Journal of Logic and Computation}
256 \end{verbatim}
257 %\iffalse
258 %</verb>
259 %\fi
260
261 % \DescribeMacro{brackets}
262 % The |title|, |booktitle|, and |journal| must be wrapped in double brackets, for example:
263 %\iffalse
264 %<*verb>
265 %\fi
266 \begin{verbatim}
267 title = {{A Survey of Symbolic Execution Techniques}}
268 \end{verbatim}
269 %\iffalse
270 %</verb>
271 %\fi
272 % This is necessary in order to prevent down-casing of capitalized words, which is done by some
273 % bibliography styles.
274
275 % \DescribeMacro{year}
276 % It is not allowed to mention the year inside the title of a conference or a journal, for example,
277 % this would be illegal:
278 %\iffalse
279 %<*verb>
280 %\fi
281 \begin{verbatim}
282 booktitle = {{1994 IEEE International Conference on Computer Languages}},
283 \end{verbatim}
284 %\iffalse
285 %</verb>
286 %\fi
287 % The year should only be mentioned in the |year| tag, nowhere else.
288 % In the |year| tag only numbers are allowed:
289 %\iffalse
290 %<*verb>
291 %\fi
292 \begin{verbatim}
293 year = {1994},
294 \end{verbatim}
295 %\iffalse
296 %</verb>
297 %\fi
298
299 % \DescribeMacro{month}
300 % The |month| may contain only a number:
301 %\iffalse
302 %<*verb>
303 %\fi
304 \begin{verbatim}
305 month = {12},
306 \end{verbatim}
307 %\iffalse
308 %</verb>
309 %\fi
310
311 % \DescribeMacro{volume}
312 % The |volume| may contain only a number:
313 %\iffalse
314 %<*verb>
315 %\fi
316 \begin{verbatim}
317 volume = {32},
318 \end{verbatim}
319 %\iffalse
320 %</verb>
321 %\fi
322
323 % \DescribeMacro{number}
324 % The |number| may contain only a number:
325 %\iffalse
326 %<*verb>
327 %\fi
328 \begin{verbatim}
329 number = {132},
330 \end{verbatim}
331 %\iffalse
332 %</verb>
333 %\fi
334
335 % \DescribeMacro{pages}
336 % The |pages| may contain either a number or two numbers separated by a double dash:
337 %\iffalse
338 %<*verb>
339 %\fi
340 \begin{verbatim}
341 pages = {145--163},
342 \end{verbatim}
343 %\iffalse
344 %</verb>
345 %\fi
346
347 % \DescribeMacro{proceedings}
348 % The |booktitle| in the |@inproceedings| entry must always start with ``|Proceedings| |of| |the|'',
349 % as in this example:
350 %\iffalse
351 %<*verb>
352 %\fi
353 \begin{verbatim}
354 booktitle = {{Proceedings of the International
355 Conference on Computer Languages}},
356 \end{verbatim}
357 %\iffalse
358 %</verb>
359 %\fi
360 % This rule may be disabled by the |noinproc| package option.
361
362 % \DescribeMacro{arXiv}
363 % If the |archivePrefix| is present, the |eprint| and the |primaryClass| must also be present and must adhere to the formatting principles of \href{https://arxiv.org/help/arxiv_identifier}{arXiv identifiers}:
364 %\iffalse
365 %<*verb>
366 %\fi
367 \begin{verbatim}
368 @misc{bugayenko2021,
369 archivePrefix = {arXiv},
370 eprint = {2111.13384},
371 primaryClass = {cs.PL},
372 }
373 \end{verbatim}
374 %\iffalse
375 %</verb>
376 %\fi
377
378 % \DescribeMacro{typography}
379 % All tags in each \BibTeX{} entry are checked for obeying the basic typography rules:
380 % \begin{itemize}
381 % \item No spaces are allowed in front of a comma, a semi-colon, a colon, a dot, a question mark, and an exclamation mark;
382 % \item A text may not end with a dot, a comma, a semi-colon, a colon, or a dash;
383 % \item A triple dash must be surrounded by spaces.
384 % \end{itemize}
385
386 % \DescribeMacro{Unicode}
387 % Any non-ASCII characters are prohibited in the entire |.bib| file.
388
389 % \StopEventually{}
390
391 % \section{Implementation}
392 % \changes{0.0.1}{2022/12/11}{First draft.}
393 % \changes{0.0.2}{2022/12/12}{Documentation extended, more rules added.}
394 % \changes{0.0.4}{2022/12/14}{Extra checks for the typography, together with more extensive Perl testing.}
395 % \changes{0.0.4}{2022/12/14}{The \texttt{--verbose} option introduced, to enable debugging information only on demand.}
396 % \changes{0.0.4}{2022/12/15}{Package options introduced, the \texttt{verbose} option enables detailed logging inside the \TeX{} log.}
397 % \changes{0.0.6}{2023/01/08}{The \texttt{script} package option introduced, to enable explicit configuration of the location of the \texttt{bibcop.pl} Perl script.}
398
399 % First, we include a few packages.
400 % We need \href{https://ctan.org/pkg/iexec}{iexec} for executing Perl scripts:
401 % \begin{macrocode}
402 \RequirePackage{iexec}
403 % \end{macrocode}
404
405 % Then, we process package options:
406 % \changes{0.0.12}{2023/05/20}{A few package options introduced to give users an ability to disable certain style rules: \texttt{nocaps}, \texttt{nowraps}, \texttt{notags}, \texttt{noorg}, \texttt{noinproc}, and \texttt{nodoi}. Also, a command line scripts gets a new set of options, which start from \texttt{--no:}, for example \texttt{--no:caps}.}
407 % \begin{macrocode}
408 \RequirePackage{pgfopts}
409 \pgfkeys{
410 /bibcop/.cd,
411 notags/.store in=\bibcop@notags,
412 noorg/.store in=\bibcop@noorg,
413 noinproc/.store in=\bibcop@noinproc,
414 nocaps/.store in=\bibcop@nocaps,
415 nodoi/.store in=\bibcop@nodoi,
416 nowraps/.store in=\bibcop@nowraps,
417 verbose/.store in=\bibcop@verbose,
418 script/.store in = \bibcop@script,
419 }
420 \ProcessPgfPackageOptions{/bibcop}
421 % \end{macrocode}
422
423 % \begin{macro}{bibcop.pl}
424 % Then, we find the Perl script:
425 % \begin{macrocode}
426 \makeatletter
427 \ifdefined\bibcop@script\else
428 \IfFileExists{bibcop.pl}
429 {\gdef\bibcop@script{perl ./bibcop.pl}}
430 {\gdef\bibcop@script{bibcop}}
431 \fi
432 \message{bibcop: The Perl script is at '\bibcop@script'^^J}%
433 \makeatother
434 % \end{macrocode}
435 % \end{macro}
436
437 % \begin{macro}{\bibcop@exec}
438 % \changes{0.0.16}{2024/01/11}{When \texttt{-shell-escape} is not set, there is no validation performed.}
439 % Then, we define a supplementary command to execute the Perl script:
440 % \begin{macrocode}
441 \RequirePackage{shellesc}
442 \makeatletter
443 \newcommand\bibcop@exec[1]{
444 \iexec[maybe]{\bibcop@script\space
445 \ifdefined\bibcop@verbose--verbose\fi\space
446 \ifdefined\bibcop@notags--no:tags\fi\space
447 \ifdefined\bibcop@noorg--no:org\fi\space
448 \ifdefined\bibcop@noinproc--no:inproc\fi\space
449 \ifdefined\bibcop@nodoi--no:doi\fi\space
450 \ifdefined\bibcop@nocaps--no:caps\fi\space
451 \ifdefined\bibcop@nowraps--no:wraps\fi\space
452 --latex '#1'}%
453 \message{bibcop: style checking finished for #1^^J}%
454 }
455 \makeatother
456
457 % \begin{macro}{\bibliography}
458 % Then, we re-define the |\bibliography| command:
459 % \begin{macrocode}
460 \makeatletter
461 \ifdefined\bibliography
462 \let\bibcop@oldbibliography\bibliography
463 \renewcommand\bibliography[1]{%
464 \bibcop@exec{#1.bib}%
465 \bibcop@oldbibliography{#1}%
466 }
467 \fi
468 \makeatother
469 % \end{macrocode}
470 % \end{macro}
471
472 % \begin{macro}{\addbibresource}
473 % Then, we re-define the |\addbibresource| command:
474 % \begin{macrocode}
475 \makeatletter
476 \ifdefined\addbibresource
477 \let\bibcop@oldaddbibresource\addbibresource
478 \renewcommand\addbibresource[1]{%
479 \bibcop@exec{#1}%
480 \bibcop@oldaddbibresource{#1}%
481 }
482 \fi
483 \makeatother
484 % \end{macrocode}
485 % \end{macro}
486
487 % \begin{macrocode}
488 \endinput
489 % \end{macrocode}
490
491 % \Finale
492
493 % \clearpage
494 % \printbibliography
495 % \clearpage
496
497 % \PrintChanges
498 % \clearpage
499 % \PrintIndex