path: root/macros/latex/contrib/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
%    README.md
% and the derived files
%    doibanner.sty
%    doibanner.pdf
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \fi
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{doibanner}
%<package>  [2024-07-28 v0.3 Generate DOI banners and links]
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage[%
  pdfusetitle,%
  hyperindex=false,%
  pdfsubject={LaTeX package documentation},%
  pdfkeywords={doibanner, latex, documentation}%
]{hyperref}
\usepackage{doibanner}
\usepackage[toc]{multitoc}
\usepackage{geometry}
\usepackage{fancyvrb}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\DoNotIndex{\adjustbox,\begin,\bfseries,\DeclareKeys,\definecolor,\end,\fill,
            \fontfamily,\href,\IfBooleanTF,\Large,\NewDocumentCommand,\node,
            \ProcessKeyOptions,\RequirePackage,\relax,\selectfont,\SetKeys,
            \sfdefault,\tikzstyle}
\setcounter{IndexColumns}{2}
\setlength{\IndexMin}{40ex}
\setlength{\columnseprule}{.4pt}
\addtolength{\oddsidemargin}{2cm}
\addtolength{\textwidth}{-2cm}
\begin{document}
  \DocInput{doibanner.dtx}
\end{document}
%</driver>
% \fi
%
%  \pagestyle{headings}
%
%  \newcommand*{\package}[1]{\textsf{#1}}
%  \newcommand*{\opt}[1]{\texttt{#1}}
%  \newcommand*{\default}[1]{(default: \opt{#1})}
%
%
% ^^A -----------------------------
%
%  \changes{v0.3}{2024-07-28}{%
%    Add package options \opt{width} and \opt{label},
%    fix mistakes,
%    improve documentation,
%    remove unnecessary dependencies}
%  \changes{v0.2}{2024-07-23}{%
%    Initial release,
%    convert into dtx,
%    add documentation,
%    add \opt{urlbase} package option}
%  \changes{v0.1}{2021/05/09}{Initial version}
%
%  \GetFileInfo{doibanner.sty}
%
%
% ^^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})}%
%  }
%  \maketitle
%
%
% ^^A -----------------------------
%
%  \begin{abstract}
%    The \package{doibanner} package allows to generate a banner for a declared
%    \href{https://www.doi.org/the-identifier/what-is-a-doi/}{digital object identifier}
%    (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 can be scaled by \package{adjustbox} and it might look as follows:
%    \par\medskip\centering{\doibanner*[width=5cm]{xx.xxxx/yyyyyy.zzzzzzzz}}
%  \end{abstract}
%
%
% ^^A -----------------------------
%
%  \tableofcontents
%
%
% ^^A -----------------------------
%
%  \section{Introduction}
%  ^^A
%    I published several documents on \href{https://zenodo.org/}{\emph{Zenodo}},
%    a general-purpose open repository. They offer to register a
%    \href{https://www.doi.org/the-identifier/what-is-a-doi/}{digital object identifier}
%    (DOI) for an entry and download a banner of it. The latter can be added to
%    contents foreseen for the entry, or e.g. when referring to the entry in a
%    slide deck.
%
%    Since I frequently use such banners in \LaTeX{} documents, I decided to
%    create a package that generates a similar banner and includes a link to the
%    corresponding URL. Additionally, this package eliminates the need to
%    manually download the banner and manage a file that might be used across
%    multiple documents.
%
%    Due to the motivation, the resulting banner is heavily inspired by the
%    design applied in the banner offered by \emph{Zenodo}. It is drawn using
%    the \package{tikz} package, a link to its URL can be included with
%    \package{hyperref}, and it can be scaled using \package{adjustbox}.
%
%    The application of this package is not limited to \emph{Zenodo}
%    depositions, it can be used to create a banner for a DOI 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
%    In order to change the default behaviour of this package, declare one
%    or more of the options described in this subsection with your desired
%    value.
%
%    \DescribeMacro{label=\meta{string}}
%      \default{DOI} specifies the label (left part) of the DOI banner generated
%      by \cs{doibanner}. The widths of the left and right part of the banner
%      are fixed and do currently not take the length of the text displayed on
%      top into account. Consequently, only a short expression should be declared
%      as value for the option \opt{label}.
%
%    \DescribeMacro{urlbase=\meta{string}}
%      \default{https://doi.org/} specifies the base URL to convert a DOI string
%      into its URL, for normal use cases this does not require any adjustment.
%
%    \DescribeMacro{width=\meta{dimen}}
%      \default{3.6cm} specifies the total width of the DOI banner generated by
%      \cs{doibanner}. The widths of the individual parts of the banner are
%      fixed and can currently not be changed.
%
%
% ^^A -----------------------------
%
%  \subsection{Macros}
%   ^^A
%    \subsubsection*{\cs{doibanner}\oarg{dimen}\marg{string}}
%
%    A DOI banner can be created using the command \cs{doibanner}, which requires
%    a DOI string as argument. Moreover, a \oarg{dimen} option can be defined.
%    The latter specifies the banner's width. If it is not declared, the value
%    of the \opt{width} package option is taken into account \default{3.6cm}.
%
%    \DescribeMacro{\doibanner}
%    An execution of \cs{doibanner\{xx.xxxx/yyyyyy.zzzzzzzz\}} results in this
%    banner: \doibanner{xx.xxxx/yyyyyy.zzzzzzzz} If a banner with a width of
%    let's say 3\,cm is desired, it can be achieved by specifying the macro option
%    \opt{width} accordingly (\cs{doibanner}\opt{[width=3cm]\{xx.xxxx/yyyyyy.zzzzzzzz\}}):
%    \doibanner[width=3cm]{xx.xxxx/yyyyyy.zzzzzzzz}
%
%    \DescribeMacro{\doibanner*}
%    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*{\cs{doiurl}\marg{string}}
%     ^^A
%    \DescribeMacro{\doiurl}
%    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*}
%    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 is as follows:
%    \doiurl*{xx.xxxx/yyyyyy.zzzzzzzz}.
%
%
% ^^A -----------------------------
%
% ^^A  \section{Known limitations}
% ^^A  ^^A
% ^^A    \begin{itemize}
% ^^A      \item
% ^^A    \end{itemize}
%
%
% ^^A -----------------------------
%
%  \MaybeStop{
%
%    \IndexPrologue{%
%      \section{Index}
%      Numbers written in italic refer to the page where the corresponding entry
%      is described; numbers underlined refer to the code line of the definition;
%      numbers in roman refer to the code lines where the entry is used.
%    }
%    \PrintIndex
%
%    \GlossaryPrologue{%
%      \section{Change History}
%      The changes listed in this section aim to provide a brief overview of the
%      changes introduced into the package \package{doibanner}. The
%      \href{https://codeberg.org/Cs137/doibanner/}{package repository on Codeberg}
%      contains a
%      \href{https://codeberg.org/Cs137/doibanner/src/branch/main/CHANGELOG.md}{changelog file},
%      consult it to read a detailed description of the changes introduced into
%      this package.
%    }
%    \PrintChanges
%
%  }
%
%
% ^^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}}, and
%      \href{https://www.ctan.org/pkg/tikz}{\package{tkiz}}
%    are required as package dependencies.
%
% \iffalse
%<*package>
% \fi
%    \begin{macrocode}
\RequirePackage{adjustbox}
\RequirePackage{hyperref}
\RequirePackage{tikz}
%    \end{macrocode}
%
%
%  ^^A -----------------------------
%
%  \subsection{Constants}
%   ^^A
%  Definition of colours for the banner areas and labels, custom colour
%  definitions are currently not supported.
%    \begin{macrocode}
\definecolor{leftcolor}{RGB}{82,82,82}
\definecolor{rightcolor}{RGB}{6,119,183}
%
\definecolor{toptextcolor}{RGB}{235,235,235}
\definecolor{bottomtextcolor}{RGB}{59,59,59}
%    \end{macrocode}
%   ^^A
%  Definition of font and colour for the banner's top and bottom text layers.
%    \begin{macrocode}
\tikzstyle{toptextstyle} = [
  font=\fontfamily{\sfdefault}\selectfont\bfseries\Large,toptextcolor]
\tikzstyle{bottomtextstyle} = [
  font=\fontfamily{\sfdefault}\selectfont\bfseries\Large,bottomtextcolor]
%    \end{macrocode}
%
%
%  ^^A -----------------------------
%
%  \subsection{Options}
%   ^^A
%  The package options are internally available as \cs{@doibanner@}\meta{option}.
%    \begin{macrocode}
\DeclareKeys[@doibanner]{
  label.store = \@doibanner@label,
  label.usage = load,
  urlbase.store = \@doibanner@urlbase,
  urlbase.usage = load,
  width.store = \@doibanner@width,
  width.usage = load,
}
%    \end{macrocode}
%
%  \subsubsection*{Assignement of default values}
%    \begin{macrocode}
\SetKeys[@doibanner]{
  label=DOI,
  urlbase=https://doi.org/,
  width=3.6cm,
}
%    \end{macrocode}
%
%  \subsubsection*{Processing of package options}
%    \begin{macrocode}
\ProcessKeyOptions[@doibanner]\relax
%    \end{macrocode}
%
%
%  ^^A -----------------------------
%
%  \subsection{Macros}
%
%  \changes{v0.2}{2024-07-23}{Remove \cs{doi} macro}
%
%  \begin{macro}{\doiurl}
%  \changes{v0.2}{2024-07-23}{Remove trailing space}
%  \oarg{dimen}\\
%  The \meta{string} is appended to the package option \opt{urlbase} to
%  generate the 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}
%  \changes{v0.3}{2024-07-28}{Rename macro, remove top part}
%  \oarg{dimen}\marg{string}\\
%  Draw the DOI banner including its \opt{label} and \meta{string}, provide
%  \opt{width=\meta{dimen}} to define the banners width as well.
%    \begin{macrocode}
\NewDocumentCommand\@doibanner@draw{o m}{%
  \adjustbox{#1}{%
    \begin{tikzpicture}
% left part
      \fill [leftcolor,draw]
        (1.5,0) --
        ++(0,.8) {[rounded corners=5] --
        ++(-1.5,0) --
        ++(0,-.8)} --
        cycle
        {};
      \node[bottomtextstyle] at (.75,.35) {\@doibanner@label};
      \node[toptextstyle] at (.75,.4) {\@doibanner@label};
% right part
      \fill [rightcolor,draw]
        (1.5,0) {[rounded corners=5] --
        ++(6.5,0) --
        ++(0,.8)} --
        ++(-6.5,0) --
        cycle
        {};
      \node[bottomtextstyle] at (4.75,.35) {#2};
      \node[toptextstyle] at (4.75,.4) {#2};
    \end{tikzpicture}%
  }%
}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\doibanner}
%  \changes{v0.3}{2024-07-28}{Add \opt{width} option}
%  \changes{v0.2}{2024-07-23}{Remove trailing space}
%  \oarg{dimen}\marg{string}\\
%  Display the DOI banner with or without (*) a link to its URL. Specify a
%  \oarg{dimen}, if you want a banner width deviating from the one defined
%  as \opt{width} package option.
%    \begin{macrocode}
\NewDocumentCommand\doibanner{s O{width=\@doibanner@width} m}{%
  \IfBooleanTF#1
  {\@doibanner@draw[#2]{#3}}%
  {\href{\@doibanner@urlbase#3}{\@doibanner@draw[#2]{#3}}}%
}
%    \end{macrocode}
%  \end{macro}
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput
%%
%% End of file `doibanner.dtx'.