Debian Codegraph @

texmf-dist/source/latex/lstaddons/lstlinebgrd.dtx

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright (c) 2011-2024 by Martin Scharrer <[email protected]>
4 %% ----------------------------------------------------------------------
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either version 1.3
7 %% of this license or (at your option) any later version.
8 %% The latest version of this license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of LaTeX
11 %% version 2005/12/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Martin Scharrer.
16 %%
17 %% This work consists of the files lstlinebgrd.dtx and lstladdons.ins
18 %% and the derived filebase lstlinebgrd.sty.
19 %%
20 %<=/COPYRIGHT>
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{lstlinebgrd.dtx}[%
26 %<=*DATE>
27 2014/08/18
28 %<=/DATE>
29 %<=*VERSION>
30 v0.2
31 %<=/VERSION>
32 DTX file for 'lstlinebgrd']
33 \documentclass{ydoc}
34 \GetFileInfo{lstlinebgrd.dtx}
35 \usepackage{lstlinebgrd}[\filedate]
36 \EnableCrossrefs
37 \CodelineIndex
38 \RecordChanges
39 \floatstyle{plaintop}
40 \restylefloat{example}
41 \belowcaptionskip=\medskipamount
42
43 \renewcommand\topfraction{.9}
44 \renewcommand\bottomfraction{.9}
45 \renewcommand\textfraction{.1}
46 \renewcommand\floatpagefraction{.7}
47 \renewcommand\dbltopfraction{.9}
48 \begin{document}
49 \DocInput{\jobname.dtx}
50 \PrintChanges
51 \PrintIndex
52 \end{document}
53 %</driver>
54 % \fi
55 %
56 % \CheckSum{0}
57 %
58 % \CharacterTable
59 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
60 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
61 % Digits \0\1\2\3\4\5\6\7\8\9
62 % Exclamation \! Double quote \" Hash (number) \#
63 % Dollar \$ Percent \% Ampersand \&
64 % Acute accent \' Left paren \( Right paren \)
65 % Asterisk \* Plus \+ Comma \,
66 % Minus \- Point \. Solidus \/
67 % Colon \: Semicolon \; Less than \<
68 % Equals \= Greater than \> Question mark \?
69 % Commercial at \@ Left bracket \[ Backslash \\
70 % Right bracket \] Circumflex \^ Underscore \_
71 % Grave accent \` Left brace \{ Vertical bar \|
72 % Right brace \} Tilde \~}
73 %
74
75 % \changes{v0.1}{2012/05/03}{Initial release.}
76 % \changes{v0.2}{2024/08/18}{Updated internal separator.}
77 %
78 % \DoNotIndex{\newcommand,\newenvironment}
79 %
80 % \GetFileInfo{lstlinebgrd.dtx}
81 % \author{Martin Scharrer}
82 % \email{[email protected]}
83 % \ifdefined\repository
84 % \repository{https://github.com/MartinScharrer/lstaddons/}
85 % \fi
86 %
87 % \maketitle
88 %
89 % \begin{abstract}\noindent
90 % This add-on package to \pkg{listings} provides the option to add background colors to lines of listings.
91 % Every line can be given a different color by using a conditional which
92 % depends on the line number.
93 %
94 % This package was created as response to the question
95 % \href{http://tex.stackexchange.com/q/18969/2975}{``Creating a zebra effect using listings''}
96 % on \href{http://tex.stackexchange.com/}{\TeX\ Stack Exchange}.
97 % \end{abstract}
98 %
99 % \section{Usage}
100 % The following settings are added by \pkg{lstlinebgrd} for \pkg{listings} and can be used in \Macro\lstset or any
101 % \pkg{listings} macro which accepts options.
102 %
103 % \DescribeKey{linebackgroundcolor}'='<color commands>
104 % This options allows the user to provide some \LaTeX\ code which sets the background
105 % color. The code must use \Macro\color{<color>} or a different color macro.
106 % The use of conditionals is permitted and can be used to color lines depending on
107 % the line number (|\value{lstnumber}|) etc., as shown in the example section.
108 % The initial setting of this option is |{}|, i.e.\ no coloring is done.
109 %
110 % \DescribeKey{linebackgroundsep}'='<length>
111 % Sets the distance of the begin of the background color bar and the line.
112 % A horizontal skip of this amount to the left from the start of the line is done
113 % before drawing the background line. This means that positive amounts will move
114 % the background color bar to the left and negative amounts to the right.
115 % This does not effect the total width of the color bar.
116 %
117 % \DescribeKey{linebackgroundwidth}'='<length>
118 % Sets the width of the background color bar. The initial default value is |\linewidth|.
119 % Note that the background width does not take the actual width of the text into account,
120 % because \pkg{listing} does not provide this information.
121 %
122 % \DescribeKey{linebackgroundheight}'='<length>
123 % Sets the height of the background color bar, i.e.\ the amount above the baseline.
124 % The initial value is |\ht\strutbox|, i.e.\ the full height of the line.
125 %
126 % \DescribeKey{linebackgrounddepth}'='<length>
127 % Sets the depth of the background color bar, i.e.\ the amount below the baseline.
128 % The initial value is |\dp\strutbox|, i.e.\ the full depth of the line.
129 %
130 % \DescribeKey{linebackgroundcmd}'='<macro>
131 % This advanced option sets the macro used to draw the background color bar. It is called at the correct
132 % starting position and receives the width, height and depth as three arguments in this order.
133 % The initial value is |\color@block| which is an internal macro of the \pkg{xcolor} package.
134 % This option can be used by advanced users to fine tune the background coloring.
135 %
136 %
137 % \clearpage
138 % \section{Examples}
139 % \def\PrintExample{%
140 % \begingroup
141 % \BoxExample
142 % \sffamily
143 % \par\medskip
144 % \centerline{Code\strut}%
145 % \smallskip
146 % \hrule
147 % \usebox\examplecodebox
148 % \par\hrule\bigskip
149 % \centerline{Result\strut}%
150 % \smallskip
151 % \hrule
152 % \usebox\exampleresultbox
153 % \par\hrule\medskip
154 % \endgroup
155 % }
156 %
157 % \begin{example}
158 % \caption{Basic example: zebra effect.}
159 % \begin{examplecode}
160 % \begin{lstlisting}[language=C,basicstyle=\ttfamily,linebackgroundcolor={\ifodd\value{lstnumber}\color{green}\fi}]
161 % /**
162 % * Prints Hello World.
163 % **/
164 % #include <stdio.h>
165
166 % int main(void) {
167 % printf("Hello World!");
168 % return 0;
169 % }
170 % \end{lstlisting}
171 % \end{examplecode}
172 % \end{example}
173 % \begin{example}
174 % \caption{Two-colored zebra effect with extra adjustments.}
175 % \begin{examplecode}
176 % \begin{lstlisting}[language=C,basicstyle=\ttfamily\Large,linebackgroundcolor={\ifodd\value{lstnumber}\color{green}\else\color{yellow}\fi},numbers=left,linebackgroundsep=1em,linebackgroundwidth=18em]
177 % /**
178 % * Prints Hello World.
179 % **/
180 % #include <stdio.h>
181 %
182 % int main(void) {
183 % printf("Hello World!");
184 % return 0;
185 % }
186 % \end{lstlisting}
187 % \end{examplecode}
188 % \end{example}
189 %
190 % \begin{example}
191 % \caption{Gradient effect with extra adjustments.}
192 % \begin{examplecode}
193 % \begin{lstlisting}[language=C,basicstyle=\ttfamily\tiny,linebackgroundcolor={\color{blue!\the\numexpr 5*\value{lstnumber}\relax}},linebackgroundheight=1.7ex,linebackgrounddepth=.4ex]
194 % /**
195 % * Prints Hello World.
196 % **/
197 % #include <stdio.h>
198 %
199 % int main(void) {
200 % printf("Hello World!");
201 % return 0;
202 % }
203 % /**
204 % * Prints Hello World.
205 % **/
206 % #include <stdio.h>
207 %
208 % int main(void) {
209 % printf("Hello World!");
210 % return 0;
211 % }
212 % \end{lstlisting}
213 % \end{examplecode}
214 % \end{example}
215 %
216 % \StopEventually{}
217 % \clearpage
218 % \section{Implementation}
219 %
220 % \iffalse
221 %<*lstlinebgrd.sty>
222 % \fi
223 % \begin{macrocode}
224 %<!COPYRIGHT>
225 \ProvidesPackage{lstlinebgrd}[%
226 %<!DATE>
227 %<!VERSION>
228 %<*DRIVER>
229 2099/01/01 develop
230 %</DRIVER>
231 Provides 'listings' options to color the background of lines]
232 % \end{macrocode}
233 % \begin{macrocode}
234 %
235 \RequirePackage{listings}
236 \RequirePackage{xcolor}
237
238 % Patch line number key to call line background macro
239 \lst@Key{numbers}{none}{%
240 \def\lst@PlaceNumber{\lst@linebgrd}%
241 \lstKV@SwitchCases{#1}%
242 {none:\\%
243 left:\def\lst@PlaceNumber{\llap{\normalfont
244 \lst@numberstyle{\thelstnumber}\kern\lst@numbersep}\lst@linebgrd}\\%
245 right:\def\lst@PlaceNumber{\rlap{\normalfont
246 \kern\linewidth \kern\lst@numbersep
247 \lst@numberstyle{\thelstnumber}}\lst@linebgrd}%
248 }{\PackageError{Listings}{Numbers #1 unknown}\@ehc}}
249
250 % New keys
251 \lst@Key{linebackgroundcolor}{}{%
252 \def\lst@linebgrdcolor{#1}%
253 }
254 \lst@Key{linebackgroundsep}{0pt}{%
255 \def\lst@linebgrdsep{#1}%
256 }
257 \lst@Key{linebackgroundwidth}{\linewidth}{%
258 \def\lst@linebgrdwidth{#1}%
259 }
260 \lst@Key{linebackgroundheight}{\ht\strutbox}{%
261 \def\lst@linebgrdheight{#1}%
262 }
263 \lst@Key{linebackgrounddepth}{\dp\strutbox}{%
264 \def\lst@linebgrddepth{#1}%
265 }
266 \lst@Key{linebackgroundcmd}{\color@block}{%
267 \def\lst@linebgrdcmd{#1}%
268 }
269
270
271 % Line Background macro
272 \newcommand{\lst@linebgrd}{%
273 \ifx\lst@linebgrdcolor\empty\else
274 \rlap{%
275 \lst@basicstyle
276 \color{-.}% By default use the opposite (`-`) of the current color (`.`) as background
277 \lst@linebgrdcolor{%
278 \kern-\dimexpr\lst@linebgrdsep\relax%
279 \lst@linebgrdcmd{\lst@linebgrdwidth}{\lst@linebgrdheight}{\lst@linebgrddepth}%
280 }%
281 }%
282 \fi
283 }
284 % \end{macrocode}
285 % \iffalse
286 %</lstlinebgrd.sty>
287 % \fi
288 %
289 % \Finale
290 \endinput