path: root/Master/texmf-dist/source/latex/doibanner/doibanner.dtx

% \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'.