summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/bibcop/bibcop.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-12-16 03:01:21 +0000
committerNorbert Preining <norbert@preining.info>2022-12-16 03:01:21 +0000
commit14c4ab52b25f4384f6db7938c2666fdd0f75a723 (patch)
tree00da17c9471442a0486f7901e54e4db06e0a6174 /macros/latex/contrib/bibcop/bibcop.dtx
parent9e62b694b4955e33f16762e5c1f9f67bf736cf5b (diff)
CTAN sync 202212160301
Diffstat (limited to 'macros/latex/contrib/bibcop/bibcop.dtx')
-rw-r--r--macros/latex/contrib/bibcop/bibcop.dtx140
1 files changed, 101 insertions, 39 deletions
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