doibanner (24jul24)

git-svn-id: svn://tug.org/texlive/trunk@71892 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 586 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/doibanner/CHANGELOG.md b/Master/texmf-dist/doc/latex/doibanner/CHANGELOG.md
new file mode 100644
index 00000000000..0da2ac7be3f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/doibanner/CHANGELOG.md
@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to the project `doibanner` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project does __not__ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+<!-- ## [Unreleased] -->
+
+
+## [0.2] - \[2024-07-23\]
+
+Initial release of [this package on the Comprehensive TeX Archive Network (CTAN)](https://www.ctan.org/pkg/doibanner)
+
+The package contains a revised version of the `doi.sty` and `tutorial/doi.tex`
+files. Since the previous material was not publicly available, the changes
+listed below are mainly to ensure that I myself do not forget how the structure
+of the package has changed.
+
+### Added
+
+- `CHANGELOG.md` file to document all notable changes to this project.
+- `example/doibanner_example.tex` and resulting standalone as `png` to act as teaser.
+- `build.lua` script to install and manage this package via `i3build`.
+- `doibanner.dtx` and `doibanner.ins`, which contains a revised melange of the
+    files `src/doi.sty` and `tutorial/doi.tex`
+
+### Fixed
+
+-  trailing whitespace from banner and link generated by doibanner and doiurl, respectively
+-  definition of `urlbase` as package option
+
+### Removed
+
+- `\doi` macro, `\doiurl` and `\doibanner` have a mandatory argument beginning
+    with this version (breaking change)
+- `src/doi.sty` and `tutorial/doi.tex` files, the package was converted into
+    `doibanner.dtx`, which allows unpacking the `doibanner.sty` file from it,
+    and can be compiled in order to obtain a package documentation.
+
+
+## [0.1] - \[2021/05/09\]
+
+Initial version of this package.
+
+
+<!-- [unreleased]: https://codeberg.org/Cs137/doibanner/compare/v0.2...HEAD -->
+[0.2]: https://codeberg.org/Cs137/doibanner/releases/tag/v0.2
+[0.1]: https://codeberg.org/Cs137/doibanner/releases/tag/v0.1
+
diff --git a/Master/texmf-dist/doc/latex/doibanner/README.md b/Master/texmf-dist/doc/latex/doibanner/README.md
new file mode 100644
index 00000000000..4630c567f4c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/doibanner/README.md
@@ -0,0 +1,26 @@
+# doibanner
+
+A LaTeX package to generate DOI banners and links.
+
+![_Screenshot of example output generated with `\doibanner`_](./example/doibanner_example.png "Example output generated with doibanner")
+
+
+This package includes an updated version of `doi.sty`, initially created for
+personal use to enhance scientific documents with DOI banners and links. I've
+converted it into `doibanner.dtx` and added documentation, allowing you to
+benefit from the package as well.
+
+Latest release: 2024-07-23 v0.2
+
+
+## Changes
+
+All notable changes to this project are documented in the file
+[`CHANGELOG.md`](https://codeberg.org/Cs137/doibanner/src/branch/main/CHANGELOG.md).
+
+
+## Credits
+
+This package was created and is maintained by Christian Schreinemachers, (C) 2024.
+The source code is hosted on [Codeberg](https://codeberg.org/Cs137/doibanner).
+This material is subject to the [LaTeX Project Public License 1.3c](https://www.ctan.org/license/lppl1.3).
diff --git a/Master/texmf-dist/doc/latex/doibanner/doibanner.pdf b/Master/texmf-dist/doc/latex/doibanner/doibanner.pdf
new file mode 100644
index 00000000000..e44caf66be8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/doibanner/doibanner.pdf
diff --git a/Master/texmf-dist/source/latex/doibanner/doibanner.dtx b/Master/texmf-dist/source/latex/doibanner/doibanner.dtx
new file mode 100644
index 00000000000..099cfb61965
--- /dev/null
+++ b/Master/texmf-dist/source/latex/doibanner/doibanner.dtx
@@ -0,0 +1,353 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2024 Christian Schreinemachers
+%
+% This work may be distributed and/or modified under the conditions
+% of the LaTeX Project Public License, either version 1.3c of this
+% license or (at your option) any later version. The latest version
+% of this license is in
+%
+%    http://www.latex-project.org/lppl.txt
+%
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008-05-04 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The current maintainer of this work is
+%   Christian Schreinemachers.
+%
+% This work consists of the files
+%    doibanner.dtx
+%    doibanner.ins
+% and the derived files
+%    doibanner.sty
+%    doibanner.pdf
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \fi
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{doibanner}
+%<package>  [2024-07-23 v0.2 Generate DOI banners and links]
+%
+%<*driver>
+\documentclass[a4paper]{ltxdoc}
+\usepackage[T1]{fontenc}
+\usepackage{doibanner}
+\usepackage[toc]{multitoc}
+\usepackage{geometry}
+\usepackage{fancyvrb}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\DoNotIndex{\def,\definecolor,\adjustbox,\begin,\bfseries,\DeclareStringOption,
+            \end,\endinput,\fill,\fontfamily,\href,\hspace,\IfBooleanTF,\Large,
+            \NewDocumentCommand,\node,\ProcessKeyvalOptions,\RequirePackage,
+            \SetupKeyvalOptions,\selectfont,\sfdefault,\vspace}
+\setlength{\IndexMin}{40ex}
+\setlength{\columnseprule}{.4pt}
+\addtolength{\oddsidemargin}{2cm}
+\addtolength{\textwidth}{-2cm}
+\begin{document}
+  \DocInput{doibanner.dtx}
+\end{document}
+%</driver>
+% \fi
+% \CheckSum{60}
+% \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         \~}
+%
+%  \changes{v0.2}{2024-07-23}{Add documentation}
+%  \changes{v0.2}{2024-07-23}{Convert into dtx}
+%  \changes{v0.1}{2021/05/09}{Initial version}
+%
+%  \GetFileInfo{doibanner.sty}
+%
+%
+% ^^A -----------------------------
+%
+%  \pagestyle{headings}
+%
+%  \newcommand*{\package}[1]{\textsf{#1}}
+%  \newcommand*{\opt}[1]{\texttt{#1}}
+%  \newcommand*{\default}[1]{(default: \opt{#1})}
+%
+%
+% ^^A -----------------------------
+%
+%  \title{The \package{doibanner} package}
+%  \author{Christian Schreinemachers}
+%  \date{%
+%    Released \filedate\thanks{%
+%      \package{doibanner}~\fileversion
+%      ~(\href{https://codeberg.org/Cs137/doibanner/releases/tag/\fileversion}{source code})}%
+%  }
+%  \hypersetup{%
+%    pdfauthor={Christian Schreinemachers},%
+%    pdftitle={The doibanner package},%
+%    pdfsubject={LaTeX package documentation},%
+%    pdfkeywords={doibanner, latex, documentation}%
+%  }
+%  \maketitle
+%
+%
+% ^^A -----------------------------
+%
+%  \begin{abstract}
+%    The \package{doibanner} package allows to generate a banner for a
+%    declared DOI. It provides the \cs{doibanner} macro, which draws the
+%    banner using \package{TikZ} and adds a link via \package{hyperref},
+%    if desired. Its output might look as follows:
+%    \par\medskip\centering{\doibanner*{xx.xxxx/yyyyyy.zzzzzzzz}}
+%  \end{abstract}
+%
+%
+% ^^A -----------------------------
+%
+%  \tableofcontents
+%
+%
+% ^^A -----------------------------
+%
+%  \section{Introduction}
+%  ^^A
+%    I published several documents on \href{https://zenodo.org/}{\textit{Zenodo}},
+%    a general-purpose open repository. They offer to register a DOI for an
+%    entry and download a banner of it. The latter can be added to contents
+%    foreseen for the entry, or when referring to it.
+%
+%    In order to avoid the manual step of downloading a banner to add to
+%    my material, I decided to create a \LaTeX{} package that draws a comparable
+%    banner and includes a link to the corresponding URL. Due to the motivation,
+%    the resulting banner is heavily inspired by the design applied in the
+%    banner offered by \textit{Zenodo}. It is drawn using the \package{tikz}
+%    package the link is included with \package{hyperref}.
+%
+%    The application of this package is not limited to \textit{Zenodo}
+%    depositions, it can be used to create a banner from a DOI string that
+%    can be included in any \LaTeX{} document.
+%
+%
+% ^^A -----------------------------
+%
+%  \section{Usage}
+%  ^^A
+%    Load the package in your document's preamble and specify any of the
+%    options described in the next subsection as follows:
+%
+%    \begin{quote}
+%      \cs{usepackage}\oarg{option(s)}\{doibanner\}
+%    \end{quote}
+%
+%
+% ^^A -----------------------------
+%
+%  \subsection{Options}
+%   ^^A
+%    \DescribeMacro{urlbase=\meta{string}}
+%      \default{https://doi.org/} specifies the prefix to convert a DOI string
+%      into an URL, for normal usecases this does not require any adjustment.
+%
+%
+% ^^A -----------------------------
+%
+%  \subsection{Macros}
+%   ^^A
+%    The following subsections list the content that can be generated with this package.
+%
+%    \subsubsection*{doibanner}
+%     ^^A
+%    \DescribeMacro{\doibanner\marg{string}}
+%    A DOI banner can be created using the command \cs{doibanner}, which
+%    requires a DOI string as argument.
+%    An execiton of \cs{doibanner\{xx.xxxx/yyyyyy.zzzzzzzz\}}, generates the
+%    following banner: \doibanner{xx.xxxx/yyyyyy.zzzzzzzz}
+%
+%    \DescribeMacro{\doibanner*\marg{string}}
+%    The starred version of the command leads to the same banner, but it does
+%    not contain a link to the DOI's URL:
+%    \doibanner*{xx.xxxx/yyyyyy.zzzzzzzz}
+%
+%    \subsubsection*{doiurl}
+%     ^^A
+%    \DescribeMacro{\doiurl\marg{string}}
+%    An URL is generated by appending the provided \emph{string} to the string
+%    defined as the package option \opt{urlbase}. The resulting link is labelled
+%    with the DOI string.
+%    A call of \cs{doiurl\{xx.xxxx/yyyyyy.zzzzzzzz\}} results in
+%    \doiurl{xx.xxxx/yyyyyy.zzzzzzzz}.
+%
+%    \DescribeMacro{\doiurl*\marg{string}}
+%    The command is also available as starred version, which prints the full
+%    URL instead of the DOI string and does not include a link. Its output for
+%    the aforementioned example will be as follows:
+%    \doiurl*{xx.xxxx/yyyyyy.zzzzzzzz}.
+%
+%
+% ^^A -----------------------------
+%
+% ^^A  \section{Known limitations}
+% ^^A  ^^A
+% ^^A    \begin{itemize}
+% ^^A      \item
+% ^^A    \end{itemize}
+%
+%
+% ^^A -----------------------------
+%
+%  \MaybeStop{
+%
+%    \PrintIndex
+%
+%    \PrintChanges
+%    \par\noindent
+%    The
+%    \href{https://codeberg.org/Cs137/doibanner/}{package repository on Codeberg}
+%    contains a detailed
+%    \href{https://codeberg.org/Cs137/doibanner/src/branch/main/CHANGELOG.md}{changelog file}.
+%
+%  }
+%
+%
+% ^^A -----------------------------
+%
+%  \section{Implementation}
+%
+%  \subsection{Dependencies}
+%   ^^A
+%    In order to use \package{doibanner}, the packages
+%      \href{https://www.ctan.org/pkg/adjustbox}{\package{adjustbox}},
+%      \href{https://www.ctan.org/pkg/hyperref}{\package{hyperref}},
+%      \href{https://www.ctan.org/pkg/kvoptions}{\package{kvoptions}},
+%      \href{https://www.ctan.org/pkg/tikz}{\package{tkiz}}, and
+%      \href{https://www.ctan.org/pkg/xparse}{\package{xparse}}
+%    are required as dependencies.
+%
+% \iffalse
+%<*package>
+% \fi
+%    \begin{macrocode}
+\RequirePackage{adjustbox}
+\RequirePackage{hyperref}
+\RequirePackage{kvoptions}
+\RequirePackage{tikz}
+\RequirePackage{xparse}
+%    \end{macrocode}
+%
+%
+%  ^^A -----------------------------
+%
+%  \subsection{Options}
+%   ^^A
+%  \begin{macro}{\doibanner@urlbase}
+%  \changes{v0.2}{2024-07-23}{Add \opt{urlbase} option}
+%  The package options and are internally available as \cs{doibanner@}\meta{option}.
+%    \begin{macrocode}
+\SetupKeyvalOptions{family=doibanner,prefix=doibanner@}
+\DeclareStringOption[https://doi.org/]{urlbase}
+\ProcessKeyvalOptions{doibanner}
+%    \end{macrocode}
+%  \end{macro}
+%
+%
+%  ^^A -----------------------------
+%
+%  \subsection{Macros}
+%
+%  \changes{v0.2}{2024-07-23}{Remove \cs{doi} macro}
+%
+%  \begin{macro}{\doiurl}
+%  \changes{v0.2}{2024-07-23}{Remove trailing whitespace}
+%  The \meta{string} is appended to the option \opt{urlbase} to
+%  generate an URL.
+%    \begin{macrocode}
+\NewDocumentCommand\doiurl{s m}{%
+  \IfBooleanTF#1
+    {\doibanner@urlbase#2}%
+    {\href{\doibanner@urlbase#2}{#2}}%
+}
+%    \end{macrocode}
+%  \end{macro}
+%
+%  \begin{macro}{\doibanner@draw}
+%  Draw the DOI banner including its \meta{string}.
+%    \begin{macrocode}
+\definecolor{leftcolor}{RGB}{85,85,85}
+\definecolor{rightcolor}{RGB}{0,126,198}
+\definecolor{topcolor}{RGB}{59,59,59}
+\definecolor{bottomtextcolor}{RGB}{60,60,60}
+\NewDocumentCommand\doibanner@draw{ O{width=3.6cm} m}{%
+  \adjustbox{#1}{%
+    \begin{tikzpicture}
+      \fill [leftcolor,draw]
+        (1.5,0) --
+        ++(0,.8) {[rounded corners=5] --
+        ++(-1.5,0) --
+        ++(0,-.8)} --
+        cycle
+        {};
+      \node[bottomtextcolor] at (.75,.35) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large DOI}};
+      \node[white] at (.75,.4) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large DOI}};
+      \fill [rightcolor,draw]
+        (1.5,0) {[rounded corners=5] --
+        ++(6.5,0) --
+        ++(0,.8)} --
+        ++(-6.5,0) --
+        cycle
+        {};
+      \node[bottomtextcolor] at (4.75,.35) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large #2}};
+      \node[white] at (4.75,.4) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large #2}};
+      \fill [topcolor,draw,opacity=0.1]
+        (0,0) [rounded corners=5] --
+        ++(8,0) --
+        ++(0,.8) --
+        ++(-8,0) --
+        cycle
+        {};
+    \end{tikzpicture}
+    \hspace{-4mm}
+    \vspace{-4mm}
+  }
+}
+%    \end{macrocode}
+%  \end{macro}
+%
+%  \begin{macro}{\doibanner@draw}
+%  \changes{v0.2}{2024-07-23}{Remove trailing whitespace}
+%  Display the DOI banner with or without (*) a link to its URL.
+%    \begin{macrocode}
+\NewDocumentCommand\doibanner{s m}{%
+  \IfBooleanTF#1
+  {\doibanner@draw{#2}}%
+  {\href{\doibanner@urlbase#2}{\doibanner@draw{#2}}}%
+}
+%    \end{macrocode}
+%  \end{macro}
+%
+%    \begin{macrocode}
+\endinput
+%    \end{macrocode}
+% \iffalse
+%</package>
+% \fi
+%
+% \Finale
+\endinput
+%%
+%% End of file `doibanner.dtx'.
+
diff --git a/Master/texmf-dist/source/latex/doibanner/doibanner.ins b/Master/texmf-dist/source/latex/doibanner/doibanner.ins
new file mode 100644
index 00000000000..177fe7e6f61
--- /dev/null
+++ b/Master/texmf-dist/source/latex/doibanner/doibanner.ins
@@ -0,0 +1,62 @@
+%%
+%% Copyright (C) 2024 Christian Schreinemachers
+%%
+%% This work may be distributed and/or modified under the conditions
+%% of the LaTeX Project Public License, either version 1.3c of this
+%% license or (at your option) any later version. The latest version
+%% of this license is in
+%%
+%%    http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.3c or later is part of all distributions of
+%% LaTeX version 2008-05-04 or later.
+%%
+\input docstrip.tex
+\keepsilent
+
+\preamble
+
+Copyright (C) 2024 Christian Schreinemachers
+
+This work may be distributed and/or modified under the conditions
+of the LaTeX Project Public License, either version 1.3c of this
+license or (at your option) any later version. The latest version
+of this license is in
+
+   http://www.latex-project.org/lppl.txt
+
+and version 1.3c or later is part of all distributions of LaTeX
+version 2008-05-04 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The current maintainer of this work is
+  Christian Schreinemachers.
+
+This work consists of the files
+   doibanner.dtx
+   doibanner.ins
+and the derived files
+   doibanner.sty
+   doibanner.pdf
+
+\endpreamble
+\askforoverwritefalse
+\generate{\file{doibanner.sty}{\from{doibanner.dtx}{package}}}
+
+\obeyspaces
+\Msg{****************************************************}
+\Msg{* To finish the installation you have to move the  *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{*                                                  *}
+\Msg{*    doibanner.sty                                *}
+\Msg{*                                                  *}
+\Msg{* To produce the documentation run the file        *}
+\Msg{* bib2qr.dtx through LaTeX.                        *}
+\Msg{*                                                  *}
+\Msg{* Happy TeXing!                                    *}
+\Msg{****************************************************}
+\endbatchfile
+%%
+%% End of file `doibanner.ins'.
+
diff --git a/Master/texmf-dist/tex/latex/doibanner/doibanner.sty b/Master/texmf-dist/tex/latex/doibanner/doibanner.sty
new file mode 100644
index 00000000000..af9267c1d19
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/doibanner/doibanner.sty
@@ -0,0 +1,94 @@
+%%
+%% This is file `doibanner.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% doibanner.dtx  (with options: `package')
+%% 
+%% Copyright (C) 2024 Christian Schreinemachers
+%% 
+%% This work may be distributed and/or modified under the conditions
+%% of the LaTeX Project Public License, either version 1.3c of this
+%% license or (at your option) any later version. The latest version
+%% of this license is in
+%% 
+%%    http://www.latex-project.org/lppl.txt
+%% 
+%% and version 1.3c or later is part of all distributions of LaTeX
+%% version 2008-05-04 or later.
+%% 
+%% This work has the LPPL maintenance status `maintained'.
+%% 
+%% The current maintainer of this work is
+%%   Christian Schreinemachers.
+%% 
+%% This work consists of the files
+%%    doibanner.dtx
+%%    doibanner.ins
+%% and the derived files
+%%    doibanner.sty
+%%    doibanner.pdf
+%% 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{doibanner}
+  [2024-07-23 v0.2 Generate DOI banners and links]
+\RequirePackage{adjustbox}
+\RequirePackage{hyperref}
+\RequirePackage{kvoptions}
+\RequirePackage{tikz}
+\RequirePackage{xparse}
+\SetupKeyvalOptions{family=doibanner,prefix=doibanner@}
+\DeclareStringOption[https://doi.org/]{urlbase}
+\ProcessKeyvalOptions{doibanner}
+\NewDocumentCommand\doiurl{s m}{%
+  \IfBooleanTF#1
+    {\doibanner@urlbase#2}%
+    {\href{\doibanner@urlbase#2}{#2}}%
+}
+\definecolor{leftcolor}{RGB}{85,85,85}
+\definecolor{rightcolor}{RGB}{0,126,198}
+\definecolor{topcolor}{RGB}{59,59,59}
+\definecolor{bottomtextcolor}{RGB}{60,60,60}
+\NewDocumentCommand\doibanner@draw{ O{width=3.6cm} m}{%
+  \adjustbox{#1}{%
+    \begin{tikzpicture}
+      \fill [leftcolor,draw]
+        (1.5,0) --
+        ++(0,.8) {[rounded corners=5] --
+        ++(-1.5,0) --
+        ++(0,-.8)} --
+        cycle
+        {};
+      \node[bottomtextcolor] at (.75,.35) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large DOI}};
+      \node[white] at (.75,.4) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large DOI}};
+      \fill [rightcolor,draw]
+        (1.5,0) {[rounded corners=5] --
+        ++(6.5,0) --
+        ++(0,.8)} --
+        ++(-6.5,0) --
+        cycle
+        {};
+      \node[bottomtextcolor] at (4.75,.35) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large #2}};
+      \node[white] at (4.75,.4) {{\fontfamily{\sfdefault}\selectfont\bfseries \Large #2}};
+      \fill [topcolor,draw,opacity=0.1]
+        (0,0) [rounded corners=5] --
+        ++(8,0) --
+        ++(0,.8) --
+        ++(-8,0) --
+        cycle
+        {};
+    \end{tikzpicture}
+    \hspace{-4mm}
+    \vspace{-4mm}
+  }
+}
+\NewDocumentCommand\doibanner{s m}{%
+  \IfBooleanTF#1
+  {\doibanner@draw{#2}}%
+  {\href{\doibanner@urlbase#2}{\doibanner@draw{#2}}}%
+}
+\endinput
+%%
+%% End of file `doibanner.sty'.