Debian Codegraph @

texmf-dist/source/latex/doibanner/doibanner.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2024 Christian Schreinemachers
4 %
5 % This work may be distributed and/or modified under the conditions
6 % of the LaTeX Project Public License, either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3c or later is part of all distributions of LaTeX
13 % version 2008-05-04 or later.
14 %
15 % This work has the LPPL maintenance status `maintained'.
16 %
17 % The current maintainer of this work is Christian Schreinemachers.
18 %
19 % This work consists of the files
20 % doibanner.dtx
21 % doibanner.ins
22 % README.md
23 % and the derived files
24 % doibanner.sty
25 % doibanner.pdf
26 %
27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28 %
29 % \fi
30 % \iffalse
31 %<package>\NeedsTeXFormat{LaTeX2e}
32 %<package>\ProvidesPackage{doibanner}
33 %<package> [2024-07-28 v0.3 Generate DOI banners and links]
34 %
35 %<*driver>
36 \documentclass[a4paper]{ltxdoc}
37 \usepackage[%
38 pdfusetitle,%
39 hyperindex=false,%
40 pdfsubject={LaTeX package documentation},%
41 pdfkeywords={doibanner, latex, documentation}%
42 ]{hyperref}
43 \usepackage{doibanner}
44 \usepackage[toc]{multitoc}
45 \usepackage{geometry}
46 \usepackage{fancyvrb}
47 \EnableCrossrefs
48 \CodelineIndex
49 \RecordChanges
50 \DoNotIndex{\adjustbox,\begin,\bfseries,\DeclareKeys,\definecolor,\end,\fill,
51 \fontfamily,\href,\IfBooleanTF,\Large,\NewDocumentCommand,\node,
52 \ProcessKeyOptions,\RequirePackage,\relax,\selectfont,\SetKeys,
53 \sfdefault,\tikzstyle}
54 \setcounter{IndexColumns}{2}
55 \setlength{\IndexMin}{40ex}
56 \setlength{\columnseprule}{.4pt}
57 \addtolength{\oddsidemargin}{2cm}
58 \addtolength{\textwidth}{-2cm}
59 \begin{document}
60 \DocInput{doibanner.dtx}
61 \end{document}
62 %</driver>
63 % \fi
64 %
65 % \pagestyle{headings}
66 %
67 % \newcommand*{\package}[1]{\textsf{#1}}
68 % \newcommand*{\opt}[1]{\texttt{#1}}
69 % \newcommand*{\default}[1]{(default: \opt{#1})}
70 %
71 %
72 % ^^A -----------------------------
73 %
74 % \changes{v0.3}{2024-07-28}{%
75 % Add package options \opt{width} and \opt{label},
76 % fix mistakes,
77 % improve documentation,
78 % remove unnecessary dependencies}
79 % \changes{v0.2}{2024-07-23}{%
80 % Initial release,
81 % convert into dtx,
82 % add documentation,
83 % add \opt{urlbase} package option}
84 % \changes{v0.1}{2021/05/09}{Initial version}
85 %
86 % \GetFileInfo{doibanner.sty}
87 %
88 %
89 % ^^A -----------------------------
90 %
91 % \title{The \package{doibanner} package}
92 % \author{Christian Schreinemachers}
93 % \date{%
94 % Released \filedate\thanks{%
95 % \package{doibanner}~\fileversion
96 % ~(\href{https://codeberg.org/Cs137/doibanner/releases/tag/\fileversion}{source code})}%
97 % }
98 % \maketitle
99 %
100 %
101 % ^^A -----------------------------
102 %
103 % \begin{abstract}
104 % The \package{doibanner} package allows to generate a banner for a declared
105 % \href{https://www.doi.org/the-identifier/what-is-a-doi/}{digital object identifier}
106 % (DOI). It provides the \cs{doibanner} macro, which draws the banner using
107 % \package{TikZ} and adds a link via \package{hyperref}, if desired. Its
108 % output can be scaled by \package{adjustbox} and it might look as follows:
109 % \par\medskip\centering{\doibanner*[width=5cm]{xx.xxxx/yyyyyy.zzzzzzzz}}
110 % \end{abstract}
111 %
112 %
113 % ^^A -----------------------------
114 %
115 % \tableofcontents
116 %
117 %
118 % ^^A -----------------------------
119 %
120 % \section{Introduction}
121 % ^^A
122 % I published several documents on \href{https://zenodo.org/}{\emph{Zenodo}},
123 % a general-purpose open repository. They offer to register a
124 % \href{https://www.doi.org/the-identifier/what-is-a-doi/}{digital object identifier}
125 % (DOI) for an entry and download a banner of it. The latter can be added to
126 % contents foreseen for the entry, or e.g. when referring to the entry in a
127 % slide deck.
128 %
129 % Since I frequently use such banners in \LaTeX{} documents, I decided to
130 % create a package that generates a similar banner and includes a link to the
131 % corresponding URL. Additionally, this package eliminates the need to
132 % manually download the banner and manage a file that might be used across
133 % multiple documents.
134 %
135 % Due to the motivation, the resulting banner is heavily inspired by the
136 % design applied in the banner offered by \emph{Zenodo}. It is drawn using
137 % the \package{tikz} package, a link to its URL can be included with
138 % \package{hyperref}, and it can be scaled using \package{adjustbox}.
139 %
140 % The application of this package is not limited to \emph{Zenodo}
141 % depositions, it can be used to create a banner for a DOI that can
142 % be included in any \LaTeX{} document.
143 %
144 %
145 % ^^A -----------------------------
146 %
147 % \section{Usage}
148 % ^^A
149 % Load the package in your document's preamble and specify any of the
150 % options described in the next subsection as follows:
151 %
152 % \begin{quote}
153 % \cs{usepackage}\oarg{option(s)}\{doibanner\}
154 % \end{quote}
155 %
156 %
157 % ^^A -----------------------------
158 %
159 % \subsection{Options}
160 % ^^A
161 % In order to change the default behaviour of this package, declare one
162 % or more of the options described in this subsection with your desired
163 % value.
164 %
165 % \DescribeMacro{label=\meta{string}}
166 % \default{DOI} specifies the label (left part) of the DOI banner generated
167 % by \cs{doibanner}. The widths of the left and right part of the banner
168 % are fixed and do currently not take the length of the text displayed on
169 % top into account. Consequently, only a short expression should be declared
170 % as value for the option \opt{label}.
171 %
172 % \DescribeMacro{urlbase=\meta{string}}
173 % \default{https://doi.org/} specifies the base URL to convert a DOI string
174 % into its URL, for normal use cases this does not require any adjustment.
175 %
176 % \DescribeMacro{width=\meta{dimen}}
177 % \default{3.6cm} specifies the total width of the DOI banner generated by
178 % \cs{doibanner}. The widths of the individual parts of the banner are
179 % fixed and can currently not be changed.
180 %
181 %
182 % ^^A -----------------------------
183 %
184 % \subsection{Macros}
185 % ^^A
186 % \subsubsection*{\cs{doibanner}\oarg{dimen}\marg{string}}
187 %
188 % A DOI banner can be created using the command \cs{doibanner}, which requires
189 % a DOI string as argument. Moreover, a \oarg{dimen} option can be defined.
190 % The latter specifies the banner's width. If it is not declared, the value
191 % of the \opt{width} package option is taken into account \default{3.6cm}.
192 %
193 % \DescribeMacro{\doibanner}
194 % An execution of \cs{doibanner\{xx.xxxx/yyyyyy.zzzzzzzz\}} results in this
195 % banner: \doibanner{xx.xxxx/yyyyyy.zzzzzzzz} If a banner with a width of
196 % let's say 3\,cm is desired, it can be achieved by specifying the macro option
197 % \opt{width} accordingly (\cs{doibanner}\opt{[width=3cm]\{xx.xxxx/yyyyyy.zzzzzzzz\}}):
198 % \doibanner[width=3cm]{xx.xxxx/yyyyyy.zzzzzzzz}
199 %
200 % \DescribeMacro{\doibanner*}
201 % The starred version of the command leads to the same banner, but it does
202 % not contain a link to the DOI's URL:
203 % \doibanner*{xx.xxxx/yyyyyy.zzzzzzzz}
204 %
205 % \subsubsection*{\cs{doiurl}\marg{string}}
206 % ^^A
207 % \DescribeMacro{\doiurl}
208 % An URL is generated by appending the provided \emph{string} to the string
209 % defined as the package option \opt{urlbase}. The resulting link is labelled
210 % with the DOI string.
211 % A call of \cs{doiurl\{xx.xxxx/yyyyyy.zzzzzzzz\}} results in
212 % \doiurl{xx.xxxx/yyyyyy.zzzzzzzz}.
213 %
214 % \DescribeMacro{\doiurl*}
215 % The command is also available as starred version, which prints the full
216 % URL instead of the DOI string and does not include a link. Its output for
217 % the aforementioned example is as follows:
218 % \doiurl*{xx.xxxx/yyyyyy.zzzzzzzz}.
219 %
220 %
221 % ^^A -----------------------------
222 %
223 % ^^A \section{Known limitations}
224 % ^^A ^^A
225 % ^^A \begin{itemize}
226 % ^^A \item
227 % ^^A \end{itemize}
228 %
229 %
230 % ^^A -----------------------------
231 %
232 % \MaybeStop{
233 %
234 % \IndexPrologue{%
235 % \section{Index}
236 % Numbers written in italic refer to the page where the corresponding entry
237 % is described; numbers underlined refer to the code line of the definition;
238 % numbers in roman refer to the code lines where the entry is used.
239 % }
240 % \PrintIndex
241 %
242 % \GlossaryPrologue{%
243 % \section{Change History}
244 % The changes listed in this section aim to provide a brief overview of the
245 % changes introduced into the package \package{doibanner}. The
246 % \href{https://codeberg.org/Cs137/doibanner/}{package repository on Codeberg}
247 % contains a
248 % \href{https://codeberg.org/Cs137/doibanner/src/branch/main/CHANGELOG.md}{changelog file},
249 % consult it to read a detailed description of the changes introduced into
250 % this package.
251 % }
252 % \PrintChanges
253 %
254 % }
255 %
256 %
257 % ^^A -----------------------------
258 %
259 % \section{Implementation}
260 %
261 % \subsection{Dependencies}
262 % ^^A
263 % In order to use \package{doibanner}, the packages
264 % \href{https://www.ctan.org/pkg/adjustbox}{\package{adjustbox}},
265 % \href{https://www.ctan.org/pkg/hyperref}{\package{hyperref}}, and
266 % \href{https://www.ctan.org/pkg/tikz}{\package{tkiz}}
267 % are required as package dependencies.
268 %
269 % \iffalse
270 %<*package>
271 % \fi
272 % \begin{macrocode}
273 \RequirePackage{adjustbox}
274 \RequirePackage{hyperref}
275 \RequirePackage{tikz}
276 % \end{macrocode}
277 %
278 %
279 % ^^A -----------------------------
280 %
281 % \subsection{Constants}
282 % ^^A
283 % Definition of colours for the banner areas and labels, custom colour
284 % definitions are currently not supported.
285 % \begin{macrocode}
286 \definecolor{leftcolor}{RGB}{82,82,82}
287 \definecolor{rightcolor}{RGB}{6,119,183}
288 %
289 \definecolor{toptextcolor}{RGB}{235,235,235}
290 \definecolor{bottomtextcolor}{RGB}{59,59,59}
291 % \end{macrocode}
292 % ^^A
293 % Definition of font and colour for the banner's top and bottom text layers.
294 % \begin{macrocode}
295 \tikzstyle{toptextstyle} = [
296 font=\fontfamily{\sfdefault}\selectfont\bfseries\Large,toptextcolor]
297 \tikzstyle{bottomtextstyle} = [
298 font=\fontfamily{\sfdefault}\selectfont\bfseries\Large,bottomtextcolor]
299 % \end{macrocode}
300 %
301 %
302 % ^^A -----------------------------
303 %
304 % \subsection{Options}
305 % ^^A
306 % The package options are internally available as \cs{@doibanner@}\meta{option}.
307 % \begin{macrocode}
308 \DeclareKeys[@doibanner]{
309 label.store = \@doibanner@label,
310 label.usage = load,
311 urlbase.store = \@doibanner@urlbase,
312 urlbase.usage = load,
313 width.store = \@doibanner@width,
314 width.usage = load,
315 }
316 % \end{macrocode}
317 %
318 % \subsubsection*{Assignement of default values}
319 % \begin{macrocode}
320 \SetKeys[@doibanner]{
321 label=DOI,
322 urlbase=https://doi.org/,
323 width=3.6cm,
324 }
325 % \end{macrocode}
326 %
327 % \subsubsection*{Processing of package options}
328 % \begin{macrocode}
329 \ProcessKeyOptions[@doibanner]\relax
330 % \end{macrocode}
331 %
332 %
333 % ^^A -----------------------------
334 %
335 % \subsection{Macros}
336 %
337 % \changes{v0.2}{2024-07-23}{Remove \cs{doi} macro}
338 %
339 % \begin{macro}{\doiurl}
340 % \changes{v0.2}{2024-07-23}{Remove trailing space}
341 % \oarg{dimen}\\
342 % The \meta{string} is appended to the package option \opt{urlbase} to
343 % generate the URL.
344 % \begin{macrocode}
345 \NewDocumentCommand\doiurl{s m}{%
346 \IfBooleanTF#1
347 {\@doibanner@urlbase#2}%
348 {\href{\@doibanner@urlbase#2}{#2}}%
349 }
350 % \end{macrocode}
351 % \end{macro}
352 %
353 % \begin{macro}{\@doibanner@draw}
354 % \changes{v0.3}{2024-07-28}{Rename macro, remove top part}
355 % \oarg{dimen}\marg{string}\\
356 % Draw the DOI banner including its \opt{label} and \meta{string}, provide
357 % \opt{width=\meta{dimen}} to define the banners width as well.
358 % \begin{macrocode}
359 \NewDocumentCommand\@doibanner@draw{o m}{%
360 \adjustbox{#1}{%
361 \begin{tikzpicture}
362 % left part
363 \fill [leftcolor,draw]
364 (1.5,0) --
365 ++(0,.8) {[rounded corners=5] --
366 ++(-1.5,0) --
367 ++(0,-.8)} --
368 cycle
369 {};
370 \node[bottomtextstyle] at (.75,.35) {\@doibanner@label};
371 \node[toptextstyle] at (.75,.4) {\@doibanner@label};
372 % right part
373 \fill [rightcolor,draw]
374 (1.5,0) {[rounded corners=5] --
375 ++(6.5,0) --
376 ++(0,.8)} --
377 ++(-6.5,0) --
378 cycle
379 {};
380 \node[bottomtextstyle] at (4.75,.35) {#2};
381 \node[toptextstyle] at (4.75,.4) {#2};
382 \end{tikzpicture}%
383 }%
384 }
385 % \end{macrocode}
386 % \end{macro}
387 %
388 % \begin{macro}{\doibanner}
389 % \changes{v0.3}{2024-07-28}{Add \opt{width} option}
390 % \changes{v0.2}{2024-07-23}{Remove trailing space}
391 % \oarg{dimen}\marg{string}\\
392 % Display the DOI banner with or without (*) a link to its URL. Specify a
393 % \oarg{dimen}, if you want a banner width deviating from the one defined
394 % as \opt{width} package option.
395 % \begin{macrocode}
396 \NewDocumentCommand\doibanner{s O{width=\@doibanner@width} m}{%
397 \IfBooleanTF#1
398 {\@doibanner@draw[#2]{#3}}%
399 {\href{\@doibanner@urlbase#3}{\@doibanner@draw[#2]{#3}}}%
400 }
401 % \end{macrocode}
402 % \end{macro}
403 %
404 % \iffalse
405 %</package>
406 % \fi
407 %
408 % \Finale
409 \endinput
410 %%
411 %% End of file `doibanner.dtx'.
412