bibcop.dtx

% \iffalse meta-comment
% (The MIT License)
%
% Copyright (c) 2022-2024 Yegor Bugayenko
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the 'Software'), to deal
% in the Software without restriction, including without limitation the rights
% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
% copies of the Software, and to permit persons to whom the Software is
% furnished to do so, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in all
% copies or substantial portions of the Software.
%
% THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
% SOFTWARE.
% \fi

% \CheckSum{0}
%
% \CharacterTable
%  {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
%   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
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}

% \GetFileInfo{bibcop.dtx}
% \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}

% \iffalse
%<*driver>
\ProvidesFile{bibcop.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{bibcop}
%<*package>
[0000-00-00 0.0.0 Style Checker of Bibliography Files]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage[maxnames=1,minnames=1,maxbibnames=1,natbib=true,citestyle=authoryear,bibstyle=authoryear,doi=false,url=false,isbn=false,isbn=false]{biblatex}
\addbibresource{bibcop.bib}
\usepackage[tt=false, type1=true]{libertine}
\usepackage{microtype}
\AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
\usepackage{href-ul}
\usepackage{xcolor}
\usepackage{graphicx}
\PageIndex
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{bibcop.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi

% \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}}}
% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}}
% \date{\filedate, \fileversion}
%
% \maketitle
%
% \textbf{\color{red}NB!}
% You must run \TeX{} processor with |--shell-escape| option
% and you must have \href{https://www.perl.org}{Perl} installed.
% This package doesn't work on Windows.

% \section{Introduction}
%
% This package scans a |.bib| file for style errors and emits
% warning messages if any issues are found (the package must be included before
% all other bibliography related packages):
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\documentclass{article}
\usepackage{bibcop}
\begin{document}
\bibliographystyle{plain}
\bibliography{main}
\end{document}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% Some warnings may be printed in the \TeX{} log.
% Once the issues in the |main.bib| file are fixed, the warnings disappear.

% Bibcop doesn't pay much attention the formatting of the |.bib| file. It doesn't emit
% warnings if a comma is missed after the last tag in a \BibTeX{} entry or the tags
% and their equation symbols are not aligned. Instead, Bibcop is focused on the content
% of the tags and their possible inconsistencies.

% If the |.sty| file is used directly (without installing it into the \TeX{} tree),
% the |bibcop.pl| file must also be placed next to it --- it is the Perl script that does all the work
% of checking your |.bib| files. The |.sty| is just a simple wrapper around it.

% The |\usepackage{bibcop}| must stay right after |\usepackage{biblatex}|
% (if Bib\LaTeX{} is used), otherwise
% there won't be any warnings from |bibcop|.

% \section{Package Options}

% It's possible to configure the behavior of the package with the help of a few package options:

% \DescribeMacro{verbose}
% The |verbose| package option prints all debugging messages to the \TeX{} log:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[verbose]{bibcop}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{script}
% 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):
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[script=my-perl-script.pl]{bibcop}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{no*}
% It's possible to suppress certain rules, by using one of the |no*| package options:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[nodoi,nowraps]{bibcop}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% The following options are available:
% \begin{itemize}\setlength\itemsep{0pt}
% \item |nocaps| allows arbitrary capitalization in titles;
% \item |nowraps| allows titles to have no double curly braces;
% \item |nodoi| allows the absence of the |doi| tag in all entries;
% \item |noinproc| allows the |booktitle| tag in |@inproceedings| entries to not start with ``Proceedings of the'';
% \item |noorg| allows mentioning of ACM/IEEE in the |booktitle| tag;
% \item |notags| allows any tags and allow to miss important tags.
% \end{itemize}

% \section{The Rules}

% This is a more or less complete list of rules enforced on a |.bib| file:

% \DescribeMacro{types}
% Only |@article|, |@book|, |@inproceedings|, and |@misc| types of \BibTeX{} entries are allowed.
% Everything else, like |@manual|, |@phdthesis|, and many others are simply prohibited.
% The mentioned four should be enough for everything.

% \DescribeMacro{tags}
% There are pretty limited lists of allowed tags for each type of \BibTeX{} entry. The tags
% that are not in the list are prohibited to use.

% \DescribeMacro{doi}
% Every \BibTeX{} entry must have the |doi| tag, which is a unique
% \href{https://www.doi.org}{Digital Object Identifier}
% of the material that you reference. It seems to be a good practice, in order to avoid ambiguity,
% to always mention the DOI.
% It also recommended to use the \href{https://ctan.org/pkg/iexec}{doi} package,
% in order to make all ``|doi|'' fields turned into hyper links.

% \DescribeMacro{caps}
% In the |title|, |booktitle|, and |journal| tags, all major words must be capitalized,
% as it is \href{https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case}{recommended} by APA:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
title = {A Preliminary Architecture for a Basic Data-Flow Processor}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% Here, the leading ``|A|'' is capital because it opens the title.
% The word ``|for|'' and the article ``|a|'' are minor words, that's why they are in lower case.
% Both parts of the composite word ``|Data-Flow|'' are capitalized.
% Sometimes this rule may need to be violated, when there is custom capitalization, as it is done
% by the author of the paper. In order to do this, the words with custom capitalization
% must be wrapped in curled brackets, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
title = {Structured Programming {with} Go {To} Statements}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% This rule may be disabled by the |nocaps| package option.

% \DescribeMacro{author}
% The |author| must contain a list of authors separated by ``|and|''. Each author
% must have two parts separated by a comma. The first part is the last name of the author,
% the second part is a list of their first names separated by a space, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
author = {Knuth, Donald E. and Duane, Bibby}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% When the list of authors is too long, it's possible to say ``|and others|'':
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
author = {Knuth, Donald E. and others}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% When first names are shortened to a single letter, it has to have a tailing dot.
% A specially pronounced author may be wrapped it in curled brackets, to make Bibcop ignore it:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
author = {{Some author} and {I}}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{shorts}
% It is not allowed to shorten any words aside from the |author| tag, for example this is illegal:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
journal = {J. Log. Comput.}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% This must be replaced with the following:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
journal = {Journal of Logic and Computation}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{brackets}
% The |title|, |booktitle|, and |journal| must be wrapped in double brackets, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
title = {{A Survey of Symbolic Execution Techniques}}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% This is necessary in order to prevent down-casing of capitalized words, which is done by some
% bibliography styles.

% \DescribeMacro{year}
% It is not allowed to mention the year inside the title of a conference or a journal, for example,
% this would be illegal:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
booktitle = {{1994 IEEE International Conference on Computer Languages}},
\end{verbatim}
%\iffalse
%</verb>
%\fi
% The year should only be mentioned in the |year| tag, nowhere else.
% In the |year| tag only numbers are allowed:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
year = {1994},
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{month}
% The |month| may contain only a number:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
month = {12},
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{volume}
% The |volume| may contain only a number:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
volume = {32},
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{number}
% The |number| may contain only a number:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
number = {132},
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{pages}
% The |pages| may contain either a number or two numbers separated by a double dash:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
pages = {145--163},
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{proceedings}
% The |booktitle| in the |@inproceedings| entry must always start with ``|Proceedings| |of| |the|'',
% as in this example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
booktitle = {{Proceedings of the International
  Conference on Computer Languages}},
\end{verbatim}
%\iffalse
%</verb>
%\fi
% This rule may be disabled by the |noinproc| package option.

% \DescribeMacro{arXiv}
% 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}:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
@misc{bugayenko2021,
  archivePrefix = {arXiv},
  eprint = {2111.13384},
  primaryClass = {cs.PL},
}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{typography}
% All tags in each \BibTeX{} entry are checked for obeying the basic typography rules:
% \begin{itemize}
%   \item No spaces are allowed in front of a comma, a semi-colon, a colon, a dot, a question mark, and an exclamation mark;
%   \item A text may not end with a dot, a comma, a semi-colon, a colon, or a dash;
%   \item A triple dash must be surrounded by spaces.
% \end{itemize}

% \DescribeMacro{Unicode}
% Any non-ASCII characters are prohibited in the entire |.bib| file.

% \StopEventually{}

% \section{Implementation}
% \changes{0.0.1}{2022/12/11}{First draft.}
% \changes{0.0.2}{2022/12/12}{Documentation extended, more rules added.}
% \changes{0.0.4}{2022/12/14}{Extra checks for the typography, together with more extensive Perl testing.}
% \changes{0.0.4}{2022/12/14}{The \texttt{--verbose} option introduced, to enable debugging information only on demand.}
% \changes{0.0.4}{2022/12/15}{Package options introduced, the \texttt{verbose} option enables detailed logging inside the \TeX{} log.}
% \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.}

% First, we include a few packages.
% We need \href{https://ctan.org/pkg/iexec}{iexec} for executing Perl scripts:
%    \begin{macrocode}
\RequirePackage{iexec}
%    \end{macrocode}

% Then, we process package options:
% \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}.}
%    \begin{macrocode}
\RequirePackage{pgfopts}
\pgfkeys{
  /bibcop/.cd,
  notags/.store in=\bibcop@notags,
  noorg/.store in=\bibcop@noorg,
  noinproc/.store in=\bibcop@noinproc,
  nocaps/.store in=\bibcop@nocaps,
  nodoi/.store in=\bibcop@nodoi,
  nowraps/.store in=\bibcop@nowraps,
  verbose/.store in=\bibcop@verbose,
  script/.store in = \bibcop@script,
}
\ProcessPgfPackageOptions{/bibcop}
%    \end{macrocode}

% \begin{macro}{bibcop.pl}
% Then, we find the Perl script:
%    \begin{macrocode}
\makeatletter
\ifdefined\bibcop@script\else
  \IfFileExists{bibcop.pl}
    {\gdef\bibcop@script{perl ./bibcop.pl}}
    {\gdef\bibcop@script{bibcop}}
\fi
\message{bibcop: The Perl script is at '\bibcop@script'^^J}%
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\bibcop@exec}
% \changes{0.0.16}{2024/01/11}{When \texttt{-shell-escape} is not set, there is no validation performed.}
% Then, we define a supplementary command to execute the Perl script:
%    \begin{macrocode}
\RequirePackage{shellesc}
\makeatletter
\newcommand\bibcop@exec[1]{
  \iexec[maybe]{\bibcop@script\space
    \ifdefined\bibcop@verbose--verbose\fi\space
    \ifdefined\bibcop@notags--no:tags\fi\space
    \ifdefined\bibcop@noinproc--no:org\fi\space
    \ifdefined\bibcop@noinproc--no:inproc\fi\space
    \ifdefined\bibcop@nodoi--no:doi\fi\space
    \ifdefined\bibcop@nocaps--no:caps\fi\space
    \ifdefined\bibcop@nowraps--no:wraps\fi\space
    --latex '#1'}%
  \message{bibcop: style checking finished for #1^^J}%
}
\makeatother

% \begin{macro}{\bibliography}
% Then, we re-define the |\bibliography| command:
%    \begin{macrocode}
\makeatletter
\ifdefined\bibliography
  \let\bibcop@oldbibliography\bibliography
  \renewcommand\bibliography[1]{%
    \bibcop@exec{#1.bib}%
    \bibcop@oldbibliography{#1}%
  }
\fi
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\addbibresource}
% Then, we re-define the |\addbibresource| command:
%    \begin{macrocode}
\makeatletter
\ifdefined\addbibresource
  \let\bibcop@oldaddbibresource\addbibresource
  \renewcommand\addbibresource[1]{%
    \bibcop@exec{#1}%
    \bibcop@oldaddbibresource{#1}%
  }
\fi
\makeatother
%    \end{macrocode}
% \end{macro}

%    \begin{macrocode}
\endinput
%    \end{macrocode}

% \Finale

% \clearpage
% \printbibliography
% \clearpage

% \PrintChanges
% \clearpage
% \PrintIndex