diff options
Diffstat (limited to 'macros/latex/contrib/doibanner/doibanner.dtx')
-rw-r--r-- | macros/latex/contrib/doibanner/doibanner.dtx | 412 |
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'. + |