Debian Codegraph @

texmf-dist/doc/generic/memoize/yadoc.sty

raw
1 %% yadoc.sty
2 %%
3 %% This file is a part of Memoize, a TeX package for externalization of
4 %% graphics and memoization of compilation results in general, available at
5 %% https://ctan.org/pkg/memoize and https://github.com/sasozivanovic/memoize.
6 %%
7 %% Copyright (c) 2020- Saso Zivanovic <[email protected]>
8 %% (Sa\v{s}o \v{Z}ivanovi\'{c})
9 %%
10 %% This work may be distributed and/or modified under the conditions of the
11 %% LaTeX Project Public License, either version 1.3c of this license or (at
12 %% your option) any later version. The latest version of this license is in
13 %% https://www.latex-project.org/lppl.txt and version 1.3c or later is part of
14 %% all distributions of LaTeX version 2008 or later.
15 %%
16 %% This work has the LPPL maintenance status `maintained'.
17 %% The Current Maintainer of this work is Saso Zivanovic.
18 %%
19 %% The files belonging to this work and covered by LPPL are listed in
20 %% (<texmf>/doc/generic/memoize/)FILES.
21
22 \RequirePackage{tcolorbox}
23 %\tcbuselibrary{listings,documentation,xparse,raster,hooks,breakable}
24 \tcbuselibrary{raster,skins}
25
26 \RequirePackage{etoolbox}
27
28 \newif\ifyadoc@into@index
29 \newif\ifyadoc@index@gather
30 \newif\ifyadoc@index@colorize@names
31 \newif\ifyadoc@ref@page
32 \newif\ifyadoc@show@keypath
33
34 \newcommand\yadocset[1]{\pgfqkeys{/yadoc}{#1}\ignorespaces}
35
36 \yadocset{
37 cmd item/.style={
38 name prefix=\textbackslash,
39 label prefix=cmd,
40 },
41 key item/.style={
42 name prefix={\ifdefempty{\yadoc@keypath}{}{%
43 \ifyadoc@show@keypath
44 \textcolor
45 {\yadoc@name@color!\yadoc@keypath@color@opacity}%
46 {\yadoc@keypath/}%
47 \fi
48 }%
49 },
50 ref prefix={\protect\ifyadoc@show@keypath\yadoc@keypath/\protect\fi},
51 index prefix=,
52 parameters prefix={\texttt{=}},
53 label prefix:=key:\yadoc@keypath@label/,
54 index annotation={key\ifdefempty{\yadoc@keypath}{}{ in \texttt{\yadoc@keypath}}},
55 },
56 env item/.style={
57 head prefix={\texttt{\cs{begin}\{}},
58 head infix={\}},
59 head suffix={%
60 \par\strut{\ttfamily\nobreakspace\nobreakspace}\meta{environment body}%
61 \par\strut\texttt{\cs{end}\{\yadoc@do@name\}}},
62 index annotation=environment,
63 label prefix=env,
64 },
65 register item/.style={
66 name prefix=\textbackslash,
67 label prefix=reg,
68 index annotation=register,
69 },
70 file item/.style={
71 index annotation=file,
72 label prefix=file,
73 },
74 value item/.style={
75 index annotation={value of
76 {\docref[show keypath,into index=false,link color=gray]{\yadoc@of}}},
77 label prefix:={\yadoc@of=},
78 },
79 scope/.code={%
80 \begingroup
81 \pgfkeysalso{#1}%
82 \endgroup
83 },
84 generic item/.style={
85 label prefix:=,
86 },
87 %
88 raster options/.style={},
89 before body/.store in=\yadoc@before@body,
90 after body/.store in=\yadoc@after@body,
91 left/.dimstore in=\yadoc@left,
92 right/.dimstore in=\yadoc@right,
93 left indent/.dimstore in=\kvtcb@doc@indentleft,
94 right indent/.dimstore in=\kvtcb@doc@indentright,
95 name/.store in=\yadoc@name,
96 name/.append style={label={#1}, index={#1}, sort index={#1}},
97 parameters/.store in=\yadoc@parameters,
98 description/.store in=\yadoc@description,
99 label/.store in=\yadoc@label,
100 label prefix:/.store in=\yadoc@label@prefix,
101 label prefix/.style={label prefix:={#1:}},
102 name font/.store in=\yadoc@name@font,
103 name color/.store in=\yadoc@name@color,
104 name prefix/.store in=\yadoc@name@prefix,
105 name suffix/.store in=\yadoc@name@suffix,
106 name prefix/.append style={index prefix={#1}, ref prefix={#1}},
107 name suffix/.append style={index suffix={#1}, ref suffix={#1}},
108 parameters font/.store in=\yadoc@parameters@font,
109 parameters prefix/.store in=\yadoc@parameters@prefix,
110 parameters suffix/.store in=\yadoc@parameters@suffix,
111 keypath/.store in=\yadoc@keypath,
112 keypath label/.store in=\yadoc@keypath@label,
113 keypath/.append style={keypath label={#1}},
114 keypath color opacity/.store in=\yadoc@keypath@color@opacity,
115 show keypath/.is if=yadoc@show@keypath,
116 index/.store in=\yadoc@index,
117 index prefix/.store in=\yadoc@index@prefix,
118 index suffix/.store in=\yadoc@index@suffix,
119 index annotation/.initial=,
120 index font/.store in=\yadoc@index@font,
121 index annotation font/.store in=\yadoc@index@annotation@font,
122 sort index/.store in=\yadoc@sort@index,
123 index colorize names/.is if=yadoc@index@colorize@names,
124 index page number format/.store in=\yadoc@index@page@number@format,
125 index gather/.is if=yadoc@index@gather,
126 index command/.store in=\yadoc@index@command,
127 index actual/.store in=\yadoc@index@actual,
128 index quote/.store in=\yadoc@index@quote,
129 index level/.store in=\yadoc@index@level,
130 index encapsulator/.store in=\yadoc@index@encapsulator,
131 see/.initial=,
132 ref font/.store in=\yadoc@ref@font,
133 ref prefix/.store in=\yadoc@ref@prefix,
134 ref suffix/.store in=\yadoc@ref@suffix,
135 head prefix/.store in=\yadoc@head@prefix,
136 head infix/.store in=\yadoc@head@infix,
137 head suffix/.store in=\yadoc@head@suffix,
138 phrases/.code={\pgfqkeys{/yadoc/phrases}{#1}},
139 phrases/.unknown/.code={\csdef{yadoc@phrases@\pgfkeyscurrentname}{#1}},
140 ref page/.is if=yadoc@ref@page,
141 of/.store in=\yadoc@of,
142 link color/.code={\hypercolor{link}{#1}},
143 long description/.style={% for do/def
144 head/.append style={
145 sidebyside gap=1em,
146 lefthand ratio=#1,
147 },
148 },
149 long description/.default=0.6,
150 %
151 .unknown/.code={%
152 \pgfkeysifdefined{/yadoc/\pgfkeyscurrentname\space item/.@cmd}{%
153 \begingroup
154 \expandafter\pgfkeysalso\expandafter{%
155 \pgfkeyscurrentname\space item,
156 before,#1,after,
157 do
158 }%
159 \endgroup
160 }{%
161 \PackageError{yadoc}{Unknown item "\pgfkeyscurrentname"}%
162 {Perhaps you have misspelled an option name?}%
163 }%
164 },
165 before/.code={},
166 after/.code={},
167 do/.is choice,
168 ref options/.style={
169 show keypath=false,
170 },
171 def options/.style={
172 show keypath,
173 },
174 aux options/.style={
175 show keypath=false,
176 },
177 foreign options/.style={
178 show keypath=false,
179 cmd item/.append style={index annotation=command},
180 },
181 index options/.code=,
182 into index/.is if=yadoc@into@index,
183 print/.is if=yadoc@printref,
184 }
185
186 \NewDocumentEnvironment{doc}{O{}m}{%
187 \begin{list}{}{%
188 \setlength{\leftmargin}{\yadoc@left}%
189 \setlength{\itemindent}{0pt}%
190 \setlength{\itemsep}{0pt}%
191 \setlength{\parsep}{0pt}%
192 \setlength{\rightmargin}{\yadoc@right}%
193 }%
194 \item
195 \begin{tcboxedraster}[
196 raster columns=1,
197 raster row skip=0pt,
198 raster before skip=0pt,
199 raster after skip=0pt,
200 raster force size=false,
201 /yadoc/raster options
202 ]{blankest,
203 before skip=1\baselineskip plus 6\baselineskip minus .5\baselineskip,
204 after skip=0pt plus 2pt minus .5\baselineskip,%
205 #1%
206 }%
207 \yadocset{do/.default=def,def options,#2}%
208 \end{tcboxedraster}
209 \nopagebreak
210 \yadoc@before@body\relax
211 \nopagebreak
212 \ignorespaces
213 }{%
214 \ifvmode\else\unskip\fi
215 \yadoc@after@body\relax
216 \end{list}%
217 }
218
219 \newcommand\docaux[2]{%
220 \begingroup
221 \yadocset{do/.default=aux,aux options,#1={name={#2}}}%
222 \endgroup
223 }
224
225 \newcommand\docAux[1]{%
226 \begingroup
227 \yadocset{do/.default=aux,aux options,#1}%
228 \endgroup
229 }
230
231 \newcommand\docForeign[1]{%
232 \begingroup
233 \yadoc@hyperreffalse
234 \yadocset{do/.default=foreign,foreign options,#1}%
235 \endgroup
236 }
237
238 \newcommand\docindex[1]{%
239 \begingroup
240 \yadoc@hyperreffalse
241 \yadocset{do/.default=index,index options,#1}%
242 \endgroup
243 }
244
245 \yadocset{
246 do/def/.code={%
247 \begin{tcolorbox}[%
248 blank,
249 colback=white, colframe=white,
250 code={%
251 \tcbdimto\tcb@temp@grow@left{\yadoc@left}%
252 \tcbdimto\tcb@temp@grow@right{\yadoc@right}%
253 },
254 grow to left by=\tcb@temp@grow@left,
255 grow to right by=\tcb@temp@grow@right,
256 sidebyside, sidebyside align=top, sidebyside gap=-\tcb@w@upper@real,
257 force nobeforeafter,
258 phantom=\phantomsection,
259 /yadoc/head,
260 ]%
261 \yadoc@head@prefix
262 \yadoc@do@name
263 \yadoc@do@index
264 \yadoc@do@label
265 \yadoc@head@infix
266 \yadoc@do@parameters
267 \yadoc@head@suffix
268 \yadoc@do@description
269 \end{tcolorbox}
270 \nopagebreak
271 },
272 do/aux/.code={%
273 \yadoc@do@name
274 \yadoc@do@index
275 \yadoc@do@label
276 },
277 do/foreign/.code={%
278 \yadoc@do@label
279 },
280 do/index/.code={%
281 \yadoc@do@label
282 \yadoc@do@index
283 },
284 }
285
286 \def\yadoc@do@name{%
287 \begingroup
288 \yadoc@name@colorize{%
289 \yadoc@name@font
290 \strut\yadoc@name@prefix\yadoc@name\yadoc@name@suffix\strut
291 }%
292 \endgroup
293 }
294
295 \def\yadoc@do@index{%
296 \ifyadoc@into@index
297 \yadoc@index@command{%
298 \yadoc@sort@index
299 \yadoc@index@actual
300 \yadoc@format@index
301 }%
302 \ifyadoc@index@gather
303 \yadoc@index@command{%
304 \yadoc@phrases@Commands
305 \yadoc@index@level
306 \yadoc@sort@index
307 \yadoc@index@actual
308 \yadoc@format@index
309 }%
310 \fi
311 \fi
312 }
313
314 \def\yadoc@name@colorize{%
315 \ifdefempty\yadoc@name@color{}{%
316 \textcolor{\yadoc@name@color}%
317 }%
318 }
319
320 \def\yadoc@format@index{%
321 {%
322 \ifyadoc@index@colorize@names\yadoc@name@colorize\fi
323 \yadoc@index@font
324 \yadoc@index@prefix\yadoc@index\yadoc@index@suffix
325 }%
326 {%
327 \ifkeyempty{/yadoc/index annotation}{}{%
328 \space\yadoc@index@annotation@font\pgfkeysvalueof{/yadoc/index annotation}%
329 }%
330 }%
331 \ifdefempty\yadoc@index@page@number@format{}{%
332 \yadoc@index@encapsulator
333 \yadoc@index@page@number@format
334 }%
335 \ifkeyempty{/yadoc/see}{}{%
336 \yadoc@index@encapsulator
337 see{\pgfkeysvalueof{/yadoc/see}}%
338 }%
339 }
340
341 \def\yadoc@do@label{%
342 \ifdefempty{\yadoc@label}{}{%
343 \begingroup
344 \yadocset{ref options}%
345 \protected@edef\@currentlabel{%
346 \protect\ifyadoc@setupref
347 \ifyadoc@hyperref
348 \protect\yadoc@hyperreftrue
349 \else
350 \protect\yadoc@hyperreffalse
351 \fi
352 \protect\fi
353 \protect\ifyadoc@printref
354 \yadoc@ref@font
355 \yadoc@ref@prefix\yadoc@name\yadoc@ref@suffix
356 \protect\fi
357 \protect\ifyadoc@into@index
358 \yadoc@do@index
359 \protect\fi
360 }%
361 \label{\yadoc@label@prefix\yadoc@label}%
362 \endgroup
363 }%
364 }
365
366 \def\yadoc@do@parameters{%
367 \ifdefempty\yadoc@parameters{}{%
368 \begingroup
369 \yadoc@parameters@font
370 \yadoc@parameters@prefix\yadoc@parameters\yadoc@parameters@suffix
371 \endgroup
372 }%
373 }
374
375 \def\yadoc@do@description{%
376 \ifdefempty{\yadoc@description}{}{%
377 \tcblower
378 \raggedleft
379 \strut
380 (\yadoc@description)%
381 \strut
382 }%
383 }
384
385 % ref
386
387 \newif\ifyadoc@setupref
388 \newif\ifyadoc@printref
389 \newif\ifyadoc@hyperref
390 \yadoc@printreftrue
391 \yadoc@hyperreftrue
392 \DeclareRobustCommand\docref[2][]{%
393 \quitvmode % otherwise, extra vertical space if this begins an \item !?!
394 \begingroup
395 \yadocset{ref options,#1}%
396 \ifcsname r@#2\endcsname
397 \expanded{%
398 \noexpand\yadoc@setupreftrue
399 \ifyadoc@printref\noexpand\yadoc@printreffalse\fi
400 \ifyadoc@into@index\noexpand\yadoc@into@indexfalse\fi
401 \ifmemoize\noexpand\memoizefalse\fi
402 \ref*{#2}%
403 \noexpand\yadoc@setupreffalse
404 \ifyadoc@printref\noexpand\yadoc@printreftrue\fi
405 \ifyadoc@into@index\noexpand\yadoc@into@indextrue\fi
406 \ifmemoize\noexpand\memoizetrue\fi
407 }%
408 \fi
409 \ifyadoc@printref\else\yadoc@hyperreffalse\fi
410 \ifyadoc@hyperref
411 \ifnum\getpagerefnumber{#2}=\thepage\relax
412 \yadoc@into@indexfalse
413 \fi
414 \hyperref[#2]{%
415 \ref*{#2}%
416 \ifyadoc@printref
417 \ifyadoc@ref@page\yadoc@ref@pagenumber{#2}\fi
418 \fi
419 }%
420 \else
421 \ref*{#2}%
422 \ifyadoc@printref
423 \ifyadoc@ref@page\yadoc@ref@pagenumber{#2}\fi
424 \fi
425 \fi
426 \endgroup
427 }
428 \def\yadoc@ref@pagenumber#1{%
429 \ifnum\getpagerefnumber{#1}=\thepage\relax
430 \else%
431 \textsuperscript{%
432 {\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}%
433 \selectfont\char213}%
434 \,\yadoc@phrases@pageshort\,\pageref*{#1}}%
435 \fi
436 }
437
438
439 \yadocset{
440 before body=,
441 after body=,
442 left=2em,
443 right=0pt,
444 left indent=-2em,
445 right indent=0pt,
446 name=,
447 name font=\ttfamily\bfseries,
448 index font=\ttfamily,
449 ref font=\ttfamily,
450 index annotation font=,
451 name color=black,
452 name prefix=,
453 name suffix=,
454 label=,
455 label prefix=,
456 parameters=,
457 parameters font=,
458 parameters prefix=,
459 parameters suffix=,
460 keypath=,
461 keypath color opacity=30,
462 description=,
463 into index=true,
464 index colorize names=false,
465 index page number format=,
466 index command=\index,
467 index gather=false,
468 index actual={@},
469 index quote={"},
470 index level={!},
471 index encapsulator={|},
472 head prefix=,
473 head infix=,
474 head suffix=,
475 ref page=false,
476 phrases={
477 index=Index,
478 pageshort=P.,
479 Commands=Commands,
480 },
481 text/.code={#1},
482 comma/.code={,\ },
483 and/.code={\ and\ },
484 }
485
486 \def\ifkeyempty#1{\ifcsempty{pgfk@#1}}
487
488 \AddToHook{begindocument}{%
489 \robustify\index
490 \robustify\hypersetup
491 }