summaryrefslogtreecommitdiff
path: root/biblio/bibtex/utils/bibcop/bibcop.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'biblio/bibtex/utils/bibcop/bibcop.dtx')
-rw-r--r--biblio/bibtex/utils/bibcop/bibcop.dtx471
1 files changed, 471 insertions, 0 deletions
diff --git a/biblio/bibtex/utils/bibcop/bibcop.dtx b/biblio/bibtex/utils/bibcop/bibcop.dtx
new file mode 100644
index 0000000000..d084f00961
--- /dev/null
+++ b/biblio/bibtex/utils/bibcop/bibcop.dtx
@@ -0,0 +1,471 @@
+% \iffalse meta-comment
+% (The MIT License)
+%
+% Copyright (c) 2022-2023 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>
+[2023-01-08 0.0.6 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
+
+% \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
+
+% \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
+
+% \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}
+
+% \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:
+% \begin{macrocode}
+\RequirePackage{pgfopts}
+\pgfkeys{
+ /bibcop/.cd,
+ 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}{\bibliography}
+% Then, we re-define the |\bibliography| command:
+% \begin{macrocode}
+\makeatletter
+\ifdefined\bibliography
+ \let\bibcop@oldbibliography\bibliography
+ \renewcommand\bibliography[1]{%
+ \iexec{\bibcop@script\space
+ \ifdefined\bibcop@verbose--verbose\fi\space
+ --latex '#1.bib'}%
+ \message{bibcop: style checking finished^^J}%
+ \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]{%
+ \iexec{\bibcop@script\space
+ \ifdefined\bibcop@verbose--verbose\fi\space
+ --latex '#1'}%
+ \message{bibcop: style checking finished^^J}%
+ \bibcop@oldaddbibresource{#1}%
+ }
+\fi
+\makeatother
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macrocode}
+\endinput
+% \end{macrocode}
+
+% \Finale
+
+% \clearpage
+% \printbibliography
+% \clearpage
+
+% \PrintChanges
+% \clearpage
+% \PrintIndex