summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/doibanner/doibanner.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/doibanner/doibanner.dtx')
-rw-r--r--macros/latex/contrib/doibanner/doibanner.dtx412
1 files changed, 412 insertions, 0 deletions
diff --git a/macros/latex/contrib/doibanner/doibanner.dtx b/macros/latex/contrib/doibanner/doibanner.dtx
new file mode 100644
index 0000000000..e004b53e31
--- /dev/null
+++ b/macros/latex/contrib/doibanner/doibanner.dtx
@@ -0,0 +1,412 @@
+% \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'.
+