From 14c4ab52b25f4384f6db7938c2666fdd0f75a723 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 16 Dec 2022 03:01:21 +0000
Subject: CTAN sync 202212160301

---
 macros/latex/contrib/bibcop/bibcop.dtx | 140 ++++++++++++++++++++++++---------
 1 file changed, 101 insertions(+), 39 deletions(-)

(limited to 'macros/latex/contrib/bibcop/bibcop.dtx')

diff --git a/macros/latex/contrib/bibcop/bibcop.dtx b/macros/latex/contrib/bibcop/bibcop.dtx
index 36c8ac747b..de48e128ef 100644
--- a/macros/latex/contrib/bibcop/bibcop.dtx
+++ b/macros/latex/contrib/bibcop/bibcop.dtx
@@ -50,7 +50,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}
 %<package>\ProvidesPackage{bibcop}
 %<*package>
-[2022-12-13 0.0.3 Style Checker of Bibliography Files]
+[2022-12-15 0.0.4 Style Checker of Bibliography Files]
 %</package>
 %<*driver>
 \documentclass{ltxdoc}
@@ -68,9 +68,9 @@
 \CodelineIndex
 \RecordChanges
 \begin{document}
-	\DocInput{bibcop.dtx}
-	\PrintChanges
-	\PrintIndex
+  \DocInput{bibcop.dtx}
+  \PrintChanges
+  \PrintIndex
 \end{document}
 %</driver>
 % \fi
@@ -88,8 +88,8 @@
 
 % \section{Introduction}
 %
-% This package scans your |.bib| files for style errors and emits
-% warning messages if any issues are found (make sure you use it before
+% 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>
@@ -105,40 +105,57 @@
 %\iffalse
 %</verb>
 %\fi
-% You may see warnings in the \TeX{} log --- fix the issues in the |main.bib| file
-% and the warnings will disappear.
+% Some warnings may be printed in the \TeX{} log.
+% Once the issues in the |main.bib| file are fixed, the warnings disappear.
 
-% If you use the |.sty| file (without installing it into the \TeX{} tree), don't forget
-% to also copy the |bibcop.pl| file --- it is the Perl script that does all the work
+% 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.
 
-% Make sure |\usepackage{bibcop}| stays right after |\usepackage{biblatex}|
-% (if you use it), otherwise
-% you won't see any warnings from |bibcop|.
+% 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
 
 % \section{The Rules}
 
-% This is a more or less complete list of rules we enforce on a |.bib| file:
+% 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 bib items are allowed.
+% 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{keys}
-% There are pretty limited lists of allowed keys for each type of bib item. The keys
+% \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 bib item must have the |doi| key, which is a unique
+% 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. I would also recommend to use \href{https://ctan.org/pkg/iexec}{doi} package,
+% 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 |title|, |booktitle|, and |journal| keys, all major words must be capitalized,
-% as it is \href{https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case}{recommended by APA}:
+% 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
@@ -151,9 +168,9 @@ title = {A Preliminary Architecture for a Basic Data-Flow Processor}
 % 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 you need to violate this rule and use custom capitalization, as it is done
-% by the author of the paper. In order to do this, wrap the words with custom capitalization
-% in curled brackets, for example:
+% 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
@@ -190,7 +207,7 @@ author = {Knuth, Donald E. and others}
 % When first names are shortened to a single letter, it has to have a tailing dot.
 
 % \DescribeMacro{shorts}
-% It is not allowed to shorten any words, for example this is illegal:
+% It is not allowed to shorten any words aside from the |author| tag, for example this is illegal:
 %\iffalse
 %<*verb>
 %\fi
@@ -212,7 +229,7 @@ journal = {Journal of Logic and Computation}
 %\fi
 
 % \DescribeMacro{brackets}
-% The |title|, |booktitle|, and |journal| must be wrapped with double brackets, for example:
+% The |title|, |booktitle|, and |journal| must be wrapped in double brackets, for example:
 %\iffalse
 %<*verb>
 %\fi
@@ -237,8 +254,8 @@ booktitle = {{1994 IEEE International Conference on Computer Languages}},
 %\iffalse
 %</verb>
 %\fi
-% The year should only be mentioned in the |year| key, nowhere else.
-% In the |year| key only numbers are allowed:
+% The year should only be mentioned in the |year| tag, nowhere else.
+% In the |year| tag only numbers are allowed:
 %\iffalse
 %<*verb>
 %\fi
@@ -298,7 +315,7 @@ pages = {145--163},
 %\fi
 
 % \DescribeMacro{proceedings}
-% The |booktitle| in the |@inproceedings| bib item must always start with ``|Proceedings| |of| |the|'',
+% The |booktitle| in the |@inproceedings| entry must always start with ``|Proceedings| |of| |the|'',
 % as in this example:
 %\iffalse
 %<*verb>
@@ -311,11 +328,38 @@ booktitle = {{Proceedings of the International
 %</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.}
 
 % First, we include a few packages.
 % We need \href{https://ctan.org/pkg/iexec}{iexec} for executing Perl scripts:
@@ -323,6 +367,16 @@ booktitle = {{Proceedings of the International
 \RequirePackage{iexec}
 %    \end{macrocode}
 
+% Then, we process package options:
+%    \begin{macrocode}
+\RequirePackage{pgfopts}
+\pgfkeys{
+  /bibcop/.cd,
+  verbose/.store in=\bibcop@verbose,
+}
+\ProcessPgfPackageOptions{/bibcop}
+%    \end{macrocode}
+
 % \begin{macro}{bibcop.pl}
 % Then, we copy the Perl script using |\VerbatimCopy| from
 % \href{https://ctan.org/pkg/verbatimcopy}{verbatimcopy}:
@@ -338,12 +392,14 @@ booktitle = {{Proceedings of the International
 %    \begin{macrocode}
 \makeatletter
 \ifdefined\bibliography
-	\let\bibcop@oldbibliography\bibliography
-	\renewcommand\bibliography[1]{%
-	  \iexec{perl "./bibcop.tmp.pl" --latex '#1.bib'}%
+  \let\bibcop@oldbibliography\bibliography
+  \renewcommand\bibliography[1]{%
+    \iexec{perl "./bibcop.tmp.pl"\space
+      \ifdefined\bibcop@verbose--verbose\fi\space
+      --latex '#1.bib'}%
     \message{bibcop: style checking finished^^J}%
-	  \bibcop@oldbibliography{#1}%
-	}
+    \bibcop@oldbibliography{#1}%
+  }
 \fi
 \makeatother
 %    \end{macrocode}
@@ -354,17 +410,23 @@ booktitle = {{Proceedings of the International
 %    \begin{macrocode}
 \makeatletter
 \ifdefined\addbibresource
-	\let\bibcop@oldaddbibresource\addbibresource
-	\renewcommand\addbibresource[1]{%
-	  \iexec{perl "./bibcop.tmp.pl" --latex '#1'}%
+  \let\bibcop@oldaddbibresource\addbibresource
+  \renewcommand\addbibresource[1]{%
+    \iexec{perl "./bibcop.tmp.pl"\space
+      \ifdefined\bibcop@verbose--verbose\fi\space
+      --latex '#1'}%
     \message{bibcop: style checking finished^^J}%
-	  \bibcop@oldaddbibresource{#1}%
-	}
+    \bibcop@oldaddbibresource{#1}%
+  }
 \fi
 \makeatother
 %    \end{macrocode}
 % \end{macro}
 
+%    \begin{macrocode}
+\endinput
+%    \end{macrocode}
+
 % \Finale
 
 % \clearpage
-- 
cgit v1.2.3

