Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2022 by Ruben Deisenroth <[email protected]>
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of
13 % LaTeX version 2005/12/01 or later.
14 %
15 % \fi
16 %
17 % \iffalse
18 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
19 %<package>\RequirePackage{expl3,l3keys2e}
20 %<package>\ProvidesExplPackage {darkmode} {2022-09-01} {1.0.1}
21 %<package>{Provide general dark mode support for any LaTeX document.}
22 %
23 %<*driver>
24 \documentclass{l3doc}
25 \hypersetup{
26 hidelinks,
27 }
28 \usepackage{etoolbox}
29 \usepackage{darkmode}
30 \EnableCrossrefs
31 \CodelineIndex
32 \RecordChanges
33 \setlength{\parindent}{0pt}
34 %\setlength{\parskip}{1em}%
35 \begin{document}
36 \DocInput{darkmode.dtx}
37 \end{document}
38 %</driver>
39 % \fi
40 % \CheckSum{0}
41 % \GetFileInfo{darkmode.sty}
42 % \title{The \pkg{darkmode} package\thanks{This document
43 % corresponds to \textsf{darkmode}~\fileversion,
44 % dated~\filedate.}}
45 % \author{Ruben Deisenroth \\ \texttt{[email protected]}}
46 % \maketitle
47 % \tableofcontents
48 %
49 % \begin{documentation}
50 % \section{Introduction}
51 % The \pkg{darkmode} Package provides an API for template and package developers to create dynamic color schemes for light- and darkmodes. For those unaware: We refer to \emph{dark mode} when a document has a dark background with a light font and to light mode if it has a dark font with a light background.
52 % \subsection{Why}
53 % Now you might think: Why would anyone even need to use a dark mode for PDF files?\\ While for the common task of printing a dark mode has a lot of disadvantages and would take a lot of ink, theese days it becomes more and more common to view PDF files directly on a Screen. And Screens emit a lot of Blue light, which - especially in the evening - can be really annoying to stare at when working on a large text document. Also modern displays can get so bright that a stark black and white contrast is too strong for most lighting scenarios.
54 % \section{Usage}
55
56 % \subsection{Basic usage}
57 % The basic Idea behind this package is that the dark mode is enabled in the preamble once, either by passing the package option \verb+enable+ or via the command \tn{enabledarkmode}, and applies to the rest of the document.
58 % \subsection{Adopting the Darkmode}
59 % When defining custom colors and commands, we can check if the dark mode is active or not to dynamically adjust the Colors.\par
60 % Example: \begin{verbatim}
61 % \DeclareDocumentCommand{\bluecode}{m}{%
62 % \texttt{\textcolor{\IfDarkModeTF{cyan}{blue}}{#1}}%
63 % }
64 % \end{verbatim}
65 % Note that in most scenarios it is possible to use the \tn{IfDarkModeTF} command inline without any sideeffects. If cases where this doesn't work, an alternative is to wrap the entire definition of a macro in the switch:
66 % \begin{verbatim}
67 % \IfDarkModeTF{%
68 % \definecolor{accentcolor}{RGB}{0, 157, 129}%
69 % }{%
70 % \definecolor{accentcolor}{RGB}{0, 122, 93}%
71 % }
72 % \end{verbatim}
73 % Another usefull trick is the usage of the colors \cs{thepagecolor} from the \pkg{pagecolor}-Package and the color \texttt{fgcolor} which is defined to the default font color. You can mix any color with these two colors to easily derive fitting colors:
74 % \begin{verbatim}
75 % % Fancy Altering Table Row Colors
76 % \rowcolors{2}{\thepagecolor}{fgcolor!10!\thepagecolor}
77 % \end{verbatim}
78 % Note that \verb+yellow!10!\thepagecolor+ is not the same as \verb+yellow!10+ because the second one would just default to \verb+yellow!10!white+.
79 % \section{Detailed documentation}
80 % \subsection{Package options}
81 % There following options can be passed to the package:
82 % \begin{itemize}
83 % \item \texttt{enable} - boolean input, enables or disables the dark mode for the entire document
84 % \item \texttt{defaulthook} - boolean input, whether to enable or disable the default hook (\tn{@darkmode@on@enable} or \tn{\@darkmode@on@disable})
85 % \item \texttt{nodefaulthook} - meta key for disabeling the default hook
86 %\end{itemize}
87 % \subsection{User Commands}
88 % \begin{function}{\enabledarkmode,\disabledarkmode}
89 % \tn{enabledarkmode} enables the dark Mode at the current position, while \tn{disabledarkmode} disables the dark mode at the current position.\\\textbf{Note:} that this is only intended to be used in the preamble for an entire document mainly with a CI/CD. Trying to toggle the dark mode between different pages may lead to unexpected behavior and is not recommended. For regular use to pass the \emph{enabled} option to the package.
90 % \end{function}
91 % \begin{function}[EXP]{\IfDarkModeT,\IfDarkModeF,\IfDarkModeTF}
92 % \begin{syntax}
93 % \tn{IfDarkModeT} \Arg{true code}
94 % \tn{IfDarkModeF} \Arg{false code}
95 % \tn{IfDarkModeTF} \Arg{true code} \Arg{false code}
96 % \end{syntax}
97 % Checks whether the dark mode is enabled or not. If so, \meta{true code} is executed, otherwise \meta{false code} is executed. These macros are fully expandable.
98 % \end{function}
99 % \subsection{Commands for developers}
100 % This functionality is mostly aimed at package developers and template creators, for the end user it should not be necessary to manually fixup the Switching with compatible Packages and Classes.
101 % \begin{function}[added = 2022-08-30]{\@darkmode@set@enabled,\@darkmode@set@disabled}
102 % Functions for template developers that want to implement dark mode toggling with \LaTeXe{}.
103 % \end{function}
104 % \end{documentation}
105 % \clearpage
106 % \begin{implementation}
107 % \section{implementation}
108 % \begin{variable}{\g_@@_dark_mode_bool}
109 % First we define the package Options. The usage of initial ensures that the boolean \cs{g_@@_dark_mode_bool} always exists.
110 % \begin{macrocode}
111 \RequirePackage{xcolor,pagecolor}
112 \keys_define:nn {darkmode} {
113 enable .bool_gset:N = \g_@@_dark_mode_bool,
114 enable .initial:n = false,
115 enable .default:n = true,
116 defaulthook .bool_gset:N = \g_@@_dark_mode_hook_bool,
117 defaulthook .initial:n = true,
118 defaulthook .default:n = true,
119 nodefaulthook .meta:n = {defaulthook=false},
120 }
121 % \end{macrocode}
122 % Now we process the package options.
123 % \begin{macrocode}
124 \ProcessKeysOptions{darkmode}
125 % \end{macrocode}
126 % \end{variable}
127
128 % \begin{macro}[pTF]{\__darkmode_if_dark_mode:}
129 % We need a global Conditional to decide whether the dark mode is currently active or not
130 % \begin{macrocode}
131 \prg_new_conditional:Nnn \__darkmode_if_dark_mode: {T,F,TF} {
132 \bool_if:NTF \g_@@_dark_mode_bool
133 {\prg_return_true:}
134 {\prg_return_false:}
135 }
136 % \end{macrocode}
137 % \end{macro}
138 % \begin{macro}{\IfDarkModeT,\IfDarkModeF,\IfDarkModeTF}
139 % \begin{macrocode}
140 \cs_set_eq:NN\IfDarkModeT \__darkmode_if_dark_mode:T
141 \cs_set_eq:NN\IfDarkModeF \__darkmode_if_dark_mode:F
142 \cs_set_eq:NN\IfDarkModeTF \__darkmode_if_dark_mode:TF
143 % \end{macrocode}
144 % \end{macro}
145 % \begin{macro}{\enabledarkmode,\@darkmode@set@enabled,\@darkmode@on@enable}
146 % \begin{macrocode}
147 \definecolor{darkmode@anthrazitgrau}{HTML}{293133}
148 \colorlet{fgcolor}{.}
149 \DeclareDocumentCommand{\@darkmode@set@enabled}{}{
150 \bool_set_true:c {g_@@_dark_mode_bool}
151 }
152 \DeclareDocumentCommand{\@darkmode@on@enable}{}{
153 \pagecolor{darkmode@anthrazitgrau}
154 \color{white}
155 \selectcolormodel{RGB}
156 \colorlet{fgcolor}{.}
157 }
158 \DeclareDocumentCommand{\enabledarkmode}{}{
159 \@darkmode@set@enabled
160 \bool_if:cT {g_@@_dark_mode_hook_bool} {\@darkmode@on@enable}
161 }
162 % \end{macrocode}
163 % \end{macro}
164 % \begin{macro}{\disabledarkmode, \@darkmode@set@disabled, \@darkmode@on@disabled}
165 % \begin{macrocode}
166 \DeclareDocumentCommand{\@darkmode@set@disabled}{}{
167 \bool_set_false:c {g_@@_dark_mode_bool}
168 }
169 \DeclareDocumentCommand{\@darkmode@on@disable}{}{
170 \pagecolor{white}
171 \color{black}
172 \colorlet{fgcolor}{.}
173 }
174 \DeclareDocumentCommand{\disabledarkmode}{}{
175 \@darkmode@set@disabled
176 \bool_if:cT {g_@@_dark_mode_hook_bool} {\@darkmode@on@disable}
177 }
178 % \end{macrocode}
179 % \end{macro}
180 % \begin{macro}{\__darkmode_update_from_bool}
181 % \begin{macrocode}
182 \DeclareDocumentCommand{\__darkmode_update_from_bool}{}{
183 \IfDarkModeTF{\enabledarkmode}{\disabledarkmode}
184 }
185 \__darkmode_update_from_bool
186 % \end{macrocode}
187 % \end{macro}
188 % \end{implementation}
189 % \clearpage
190 % \PrintIndex
191 \endinput