Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2018-2019 by Richard Grewe <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.2
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.2 or later is part of all distributions of LaTeX
14 % version 1999/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{rgltxdoc.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{rgltxdoc}
24 %<*package>
25 [2019/12/21 v1.3 Common documentation code used for Richard Grewe's packages]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \RequirePackage{rgltxdoc}
31 \EnableCrossrefs
32 \CodelineIndex
33 \RecordChanges
34 \begin{document}
35 \DocInput{rgltxdoc.dtx}
36 \PrintChanges
37 \PrintIndex
38 \end{document}
39 %</driver>
40 % \fi
41 %
42 % \CheckSum{0}
43 %
44 % \CharacterTable
45 % {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
46 % 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
47 % Digits \0\1\2\3\4\5\6\7\8\9
48 % Exclamation \! Double quote \" Hash (number) \#
49 % Dollar \$ Percent \% Ampersand \&
50 % Acute accent \' Left paren \( Right paren \)
51 % Asterisk \* Plus \+ Comma \,
52 % Minus \- Point \. Solidus \/
53 % Colon \: Semicolon \; Less than \<
54 % Equals \= Greater than \> Question mark \?
55 % Commercial at \@ Left bracket \[ Backslash \\
56 % Right bracket \] Circumflex \^ Underscore \_
57 % Grave accent \` Left brace \{ Vertical bar \|
58 % Right brace \} Tilde \~}
59 %
60 %
61 % \changes{v1}{2019/01/05}{Initial version}
62 %
63 % \GetFileInfo{rgltxdoc.dtx}
64 %
65 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
66 %
67 %
68 % \title{The \pkgname{rgltxdoc} package\thanks{This document
69 % corresponds to \pkgname{rgltxdoc}~\fileversion, dated \filedate.
70 % The package is available online at
71 % \url{http://www.ctan.org/pkg/rgltxdoc} and
72 % \url{https://github.com/Ri-Ga/rgltxdoc}.}}
73 % \author{Richard Grewe\\ \texttt{[email protected]}}
74 %
75 % \maketitle
76 %
77 % \section{Introduction}
78 %
79 % This package combines several other packages and defines additional
80 % macros and environments for the purpose of documenting LaTeX code.
81 % The package mainly serves the purpose of combining the preferences
82 % used in the author's package documentations. However, others can
83 % use the package as well. Compatibility between versions cannot be
84 % guaranteed, however.
85 %
86 % \StopEventually{}
87 %\iffalse
88 %<*package>
89 %\fi
90 %
91 % \section{Basic Dependencies}
92 %
93 % Generally, the documentation can be compiled with \hologo{pdfLaTeX}
94 % and with \hologo{LuaLaTeX}. Other processors are untested. There is no
95 % assertion as to how close the \hologo{pdfLaTeX} and \hologo{LuaLaTeX}
96 % results are to each other.
97 % \begin{macrocode}
98 \RequirePackage{ifluatex}
99 % \end{macrocode}
100 % The \pkgname{etoolbox} package is used to simplify some of the
101 % package's code.
102 % \begin{macrocode}
103 \RequirePackage{etoolbox}
104 % \end{macrocode}
105 %
106 % \section{Documentation Input}
107 %
108 % The documentation is expected to be written in UTF-8 and in US-English
109 % language. If \pkgname{babel} is already loaded, it will not be loaded
110 % again, though. This is to support packages that use other languages
111 % than English in examples and load \pkgname{babel} accordingly.
112 % \changes{v1.1}{2019/01/12}{load babel only if not yet loaded}
113 % \begin{macrocode}
114 \ifbool{luatex}{
115 \RequirePackage[utf8]{luainputenc}
116 \RequirePackage{polyglossia}
117 \setmainlanguage[variant=american]{english}
118 }{
119 \RequirePackage[utf8]{inputenc}
120 \@ifpackageloaded{babel}{}
121 {\RequirePackage[english]{babel}}
122 }
123 % \end{macrocode}
124 %
125 % \section{General Appearance}
126 %
127 % Code in this section determines the general appearance of
128 % documentation text and is not specific to documenting \hologo{LaTeX}
129 % code.
130 %
131 % \subsection{Page Layout}
132 %
133 % For the page layout, A4 is used for the paper size.
134 % Border correction established wider left margins for typesetting long
135 % macro names.
136 % The |DIV| value is tuned to make the lines wide enough to support
137 % at least 72~characters in the package documentation code.
138 % \begin{macrocode}
139 \RequirePackage[a4paper,twoside=false]{geometry}
140 \RequirePackage[DIV=9,BCOR=2.25cm]{typearea}
141 % \end{macrocode}
142 %
143 % \subsection{Fonts}
144 %
145 % For the font, Latin Modern is used.
146 % Particularly, a light version of the typewriter font is used, such
147 % that highlighting in listings is possible via a bold font series.
148 % \begin{macrocode}
149 \ifbool{luatex}{
150 \RequirePackage{fontspec}
151 \setmainfont[SmallCapsFont={* Caps}]{Latin Modern Roman}
152 \setsansfont{Latin Modern Sans}
153 \setmonofont[Scale=MatchLowercase,
154 SmallCapsFont={Latin Modern Mono Caps}]
155 {Latin Modern Mono Light}
156 }{
157 \RequirePackage[T1]{fontenc}
158 \RequirePackage[lighttt]{lmodern}
159 % \end{macrocode}
160 % With just the above code, a construct like |\cs{foo\meta{bar}}| for
161 % documenting parameter-dependent macro names fails due to missing
162 % fonts. The following two lines fix this. The first line ensures that
163 % the typewriter font is loaded (via an |\hbox| with typewriter text
164 % that is not actually displayed) and the second line declares the
165 % required font shape (see
166 % \url{https://tex.stackexchange.com/questions/234003/italic-font-in-lmodern-lighttt}).
167 % \begin{macrocode}
168 \bgroup\setbox\z@\hbox{\ttfamily ignore}\egroup
169 \DeclareFontShape{T1}{lmtt}{m}{it}{<->sub*lmtt/m/sl}{}
170 }
171 % \end{macrocode}
172 % Finally, \pkgname{microtype} is used for small font improvements.
173 % \begin{macrocode}
174 \RequirePackage{microtype}
175 % \end{macrocode}
176 % We simplify quoting names through the \pkgname{csquotes} package and
177 % register |"| to produce double opening/closing quotation marks.
178 % \begin{macrocode}
179 \RequirePackage[autostyle=true]{csquotes}
180 \MakeOuterQuote{"}
181 % \end{macrocode}
182 %
183 % \subsection{Document Structure}
184 %
185 % For the most part, documentations are structured as usual, through a
186 % title as well as sections and sub-sections and so forth.
187 % The following two packages improve the possibilities for using lists
188 % in documentation and visually improve the index through a two-column
189 % layout.
190 % \begin{macrocode}
191 \RequirePackage[inline]{enumitem}
192 \RequirePackage[columns=2]{idxlayout}
193 % \end{macrocode}
194 %
195 % The \pkgname{cleveref} package now requires \pkgname{amsmath} to be
196 % loaded before. We actually do not need \pkgname{amsmath}, but it also
197 % should not harm to load it nonetheless to avoid that
198 % \pkgname{rgltxdoc} now has to be loaded after \pkgname{amsmath}.
199 % \changes{v1.3}{2019/12/21}{add \pkgname{amsmath} dependency}
200 % \begin{macrocode}
201 \RequirePackage{amsmath}
202 % \end{macrocode}
203 %
204 % The \pkgname{cleveref} and \pkgname{varioref} packages shall be used
205 % for referencing structural entities, such as sections and figures.
206 % Hyperlinks are enabled through \pkgname{hypdoc}.
207 % \begin{macrocode}
208 \RequirePackage{varioref}
209 \RequirePackage{hypdoc}
210 \RequirePackage[capitalise,noabbrev,nameinlink]{cleveref}
211 % \end{macrocode}
212 %
213 %
214 % \section{Documenting Things}
215 %
216 % This package builds on the \pkgname{doc} package for several
217 % documentation macros, such as |\marg|, |\oarg|, and |\meta|.
218 % \begin{macrocode}
219 \RequirePackage{doc}
220 % \end{macrocode}
221 %
222 % \subsection{Macros and Environments}\label{sec:MacrosEnvs}
223 %
224 % The main macros here, |\NiceDescribeMacro| and |\NiceDescribeEnv|, are
225 % references to |\DescribeMacro| and |\DescribeEnv| of the \pkgname{doc}
226 % package, with which they share the purpose.
227 % The main difference is the appearance in that the "nice" macros
228 % include the argument list.
229 %
230 % \NiceDescribeMacros{2}
231 % {\NiceDescribeMacro}{\oarg{idx}\marg{macro}\marg{parameters}}
232 % {\NiceDescribeMacros}{\marg{n}\oarg{idx$_1$}\marg{macro$_1$}\marg{params$_1$}\ldots\oarg{idx$_n$}\marg{macro$_n$}\marg{params$_n$}}
233 % These macros produce a description header for a single macro or,
234 % respectively, for multiple macros.
235 % The above two lines are an example of such a description header, which
236 % is produced by the following code:
237 % \begin{lstlisting}
238 % \NiceDescribeMacros{2}
239 % {\NiceDescribeMacro}{\oarg{idx}\marg{macro}\marg{parameters}}
240 % {\NiceDescribeMacros}{\marg{n}
241 % \oarg{idx$_1$}\marg{macro$_1$}\marg{params$_1$}\ldots
242 % \oarg{idx$_n$}\marg{macro$_n$}\marg{params$_n$}}
243 % \end{lstlisting}
244 % The arguments to the macro are described below:
245 % \begin{KeyValTable}{ArgDesc}
246 % \Row{arg=\meta{n},
247 % desc={This argument specifies the number of macros to be
248 % described.}}
249 % \Row{arg=\pbox[t]{\linewidth}{\meta{macro},\\\meta{macro$_1$},\ldots,\\\meta{macro$_n$}},
250 % desc={These arguments specify the macros for which a description
251 % header shall be produced.}}
252 % \Row{arg=\pbox[t]{\linewidth}{\meta{parameters},\\\meta{params$_1$},\ldots,\\\meta{params$_n$}},
253 % desc={These arguments take the sequence that specifies all optional
254 % and mandatory arguments of the respective \meta{macro}.
255 % Typically, these would be sequences of \cs{oarg} and \cs{marg}
256 % instances.}}
257 % \Row{arg=\pbox[t]{\linewidth}{\meta{idx},\\\meta{idx$_1$},\ldots,\\\meta{idx$_N$}},
258 % desc={These optional arguments arguments specify which index entries
259 % shall be documented, if they differ from the respective
260 % \meta{macro} parameters. This, for instance allows \meta{macro} to
261 % be "\texttt{\cs{foo}(*)}" whereas the \meta{idx} parameter could be
262 % "\texttt{\cs{foo},\cs{foo}*}".}}
263 % \end{KeyValTable}
264 %
265 % \NiceDescribeMacros{2}
266 % {\NiceDescribeEnv}{\oarg{idx}\marg{environment}\marg{parameters}}
267 % {\NiceDescribeEnvs}{\marg{n}\oarg{idx$_1$}\marg{env$_1$}\marg{params$_1$}\ldots\oarg{idx$_n$}\marg{env$_n$}\marg{params$_n$}}
268 % These macros are the counterparts of |\NiceDescribeMacro| and,
269 % respectively, |\NiceDescribeMacros| when it comes to \hologo{LaTeX}
270 % environments. The \meta{environment} (resp.\ \meta{env$_1$} to
271 % \meta{env$_n$}) parameters are the names of the respective environments.
272 % A usage example can be found in the implementation part of
273 % \vref{sec:KeysValues:impl}.
274 %
275 % \NiceDescribeMacros{2}
276 % {\NiceDescribeCounter}{\oarg{idx}\marg{counter}\marg{qualifiers}}
277 % {\NiceDescribeCounters}{\marg{n}\oarg{idx$_1$}\marg{ctr$_1$}\marg{qual$_1$}\ldots\oarg{idx$_n$}\marg{ctr$_n$}\marg{qual$_n$}}
278 % These macros are analogous to the above macros, but aimed for
279 % documenting \hologo{LaTeX} counters.
280 %
281 % \NiceDescribeMacros{2}
282 % {\NiceDescribeKey}{\oarg{idx}\marg{keyname}\marg{keyconfig}}
283 % {\NiceDescribeKeys}{\marg{n}\oarg{idx$_1$}\marg{name$_1$}\marg{cfg$_1$}\ldots\oarg{idx$_n$}\marg{name$_n$}\marg{cfg$_n$}}
284 % These macros are for documenting option keys, for instances of
285 % packages \pkgname{xkeyval} or \pkgname{pgfkeys}.
286 % The \meta{keyconfig} is a key-value list in which the keys "vals",
287 % "init", and "def" can be used to specify the range of
288 % expected/permitted values, the initial (preset) value, and the default
289 % (if the key is provided without a value).
290 %
291 % \NiceDescribeMacro{\NewNiceDescription}{\marg{type}\marg{efmt}\marg{afmt}\marg{icmd}}
292 % This macro is used internally for defining the above macros and can be
293 % used for defining new types of entity descriptions. The following
294 % table describes the arguments of the macro.
295 % \begin{KeyValTable}{ArgDesc}
296 % \Row{arg=\meta{type},
297 % desc={The \meta{type} argument is the name of the type of entities.}}
298 % \Row{arg=\meta{efmt},
299 % desc={The \meta{efmt} argument is \hologo{TeX} code that formats the
300 % entities in the margin. It can -- and should -- reference the
301 % positional parameter |\#1|, through which it is passed the name of
302 % the entities.}}
303 % \Row{arg=\meta{afmt},
304 % desc={The \meta{afmt} argument is \hologo{TeX} code that formats the
305 % arguments or qualifiers of the entities in the body of the
306 % documentation. Analogous to \meta{efmt}, also \meta{afmt} receives
307 % the arguments/qualifiers through the positional parameter |\#1|.}}
308 % \Row{arg=\meta{icmd},
309 % desc={The \meta{icmd} argument is \hologo{TeX} code that adds a
310 % usage entry for the entity to the index. It takes one argument,
311 % through which \meta{icmd} is passed the entity name.}}
312 % \end{KeyValTable}
313 % A usage example for |\NewNiceDescription| can be found in the
314 % implementation below.
315 %
316 %
317 % \paragraph{Implementation}
318 %
319 % \begin{macro}{\NewNiceDescription}
320 % The |\NewNiceDescription|\marg{type}\marg{efmt}\marg{afmt}\marg{icmd}
321 % macro defines the \cs{NiceDescribe\meta{type}} and
322 % \cs{NiceDescribe\meta{type}s} macros and saves the \meta{efmt} and
323 % \meta{afmt} parameters for use by \cs{NiceDescribe\meta{type}s}.
324 % \begin{macrocode}
325 \newcommand\NewNiceDescription[4]{%
326 \expandafter\newcommand\csname NiceDescribe#1\endcsname{%
327 \csname NiceDescribe#1s\endcsname{1}}%
328 \expandafter\newcommand\csname NiceDescribe#1s\endcsname{%
329 \rgltxdoc@Desc
330 {\csuse{rgltxdoc@@efmt@#1}}
331 {\csuse{rgltxdoc@@afmt@#1}}
332 {#4}}%
333 \csdef{rgltxdoc@@efmt@#1}##1{#2}%
334 \csdef{rgltxdoc@@afmt@#1}##1{#3}}
335 % \end{macrocode}
336 % \end{macro}
337 %
338 % \begin{macro}{\NiceDescribeMacro}
339 % \begin{macro}{\NiceDescribeMacros}
340 % Macro names are formatted detokenized through |\string|.
341 % Arguments are formatted as is.
342 % For the index, |\SpecialUsageIndex| of the \pkgname{doc} package is
343 % used.
344 % \begin{macrocode}
345 \NewNiceDescription{Macro}{\string#1}{#1}{\SpecialUsageIndex}
346 % \end{macrocode}
347 % \end{macro}
348 % \end{macro}
349 % \begin{macro}{\NiceDescribeEnv}
350 % \begin{macro}{\NiceDescribeEnvs}
351 % Environment names are formatted with a gray |\begin| and |\end|.
352 % The arguments of environments are formatted as is.
353 % For the index, |\SpecialEnvIndex| of the \pkgname{doc} package is
354 % used.
355 % \begin{macrocode}
356 \NewNiceDescription{Env}
357 {\textcolor{gray}{\cs{begin}}\cmarg{#1}\\
358 \textcolor{gray}{\cs{end}}\cmarg{#1}}
359 {#1}{\SpecialEnvIndex}
360 % \end{macrocode}
361 % \end{macro}
362 % \end{macro}
363 % \begin{macro}{\NiceDescribeCounter}
364 % \begin{macro}{\NiceDescribeCounters}
365 % Counter names are formatted as is. Arguments or qualifiers should
366 % usually not be present for counters, but if provided, they would be
367 % formatted as is.
368 % The index entry is produced through |\SpecialOtherIndex| (see its
369 % documentation below).
370 % \begin{macrocode}
371 \NewNiceDescription{Counter}{#1}{#1}
372 {\SpecialOtherIndex{counter}{counters}}
373 % \end{macrocode}
374 % \end{macro}
375 % \end{macro}
376 % \begin{macro}{\NiceDescribeKey}
377 % \begin{macro}{\NiceDescribeKeys}
378 % Option-key names are formatted as is. Arguments are split into the range
379 % of values (|vals|), the initial value (|init|), and the default value
380 % (|def| -- the value used when only the key but no value is specified
381 % to the key). These three can be set as keys. The index entry is
382 % produced through |\SpecialOtherIndex| (see its documentation below).
383 % \changes{v1.2}{2019/05/04}{macros added}
384 % \begin{macrocode}
385 \NewNiceDescription{Key}{#1\,\textrm{=}\,\null}
386 {\begingroup
387 \newcommand\vmeta[1]{{\normalfont\meta{##1}}}%
388 \setkeys[rgltxdoc]{DescOpt}{#1}%
389 \setbox\z@\hbox{\qquad\let\rgltxdoc@@sep\@empty
390 \rgltxdoc@opt{default}{\cmdrgltxdoc@DescOpt@def}%
391 \rgltxdoc@opt{initially}{\cmdrgltxdoc@DescOpt@init}}%
392 \parbox[t]{\linewidth-\wd\z@}{%
393 \raggedright\cmdrgltxdoc@DescOpt@vals}%
394 \box\z@\endgroup}
395 {\SpecialOtherIndex{option-key}{option-keys}}
396 \usepackage{xkeyval,calc}
397 \define@key[rgltxdoc]{DescOpt}{vals}{%
398 \def\cmdrgltxdoc@DescOpt@vals{}\let\rgltxdoc@@sep\@empty%
399 \def\do##1{%
400 \protected@eappto\cmdrgltxdoc@DescOpt@vals{\rgltxdoc@@sep\texttt{##1}}%
401 \def\rgltxdoc@@sep{, }}%
402 \docsvlist{#1}}
403 \define@cmdkey[rgltxdoc]{DescOpt}{init}{}
404 \define@cmdkey[rgltxdoc]{DescOpt}{def}{}
405 \newcommand\rgltxdoc@opt[2]{\ifdef{#2}
406 {\rgltxdoc@@sep\textsl{#1: }\texttt{#2}%
407 \def\rgltxdoc@@sep{, }}
408 {}}
409 % \end{macrocode}
410 % \end{macro}
411 % \end{macro}
412 %
413 % \begin{macro}{\SpecialOtherIndex}
414 % The |\SpecialOtherIndex|\marg{type}\marg{types}\marg{name} macro
415 % adds an index entry of the given \meta{type} (with plural form
416 % \meta{types}) and given \meta{name}.
417 % The macro is a straightforward generalization of |\SpecialEnvIndex|
418 % (both from \pkgname{hypdoc} and from \pkgname{doc}).
419 % \changes{v1.2}{2019/05/04}{enabled \pkgname{hypdoc} support}
420 % \begin{macrocode}
421 \newcommand*\SpecialOtherIndex[3]{%
422 \@bsphack
423 \begingroup
424 \HD@target
425 \let\HDorg@encapchar\encapchar
426 \edef\encapchar usage{%
427 \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage}%
428 }%
429 \rgltxdoc@nohyp@SpecialOtherIndex{#1}{#2}{#3}%
430 \endgroup
431 \@esphack}
432 \newcommand\rgltxdoc@nohyp@SpecialOtherIndex[3]{%
433 \index{#3\actualchar{\protect\ttfamily#3}
434 (#1)\encapchar usage}%
435 \index{#2:\levelchar#3\actualchar
436 {\protect\ttfamily#3}\encapchar usage}}
437 % \end{macrocode}
438 % \end{macro}
439 %
440 % \begin{macro}{\rgltxdoc@DescRec}
441 % The
442 % |\rgltxdoc@Desc|\marg{efmt}\marg{afmt}\marg{icmd}\marg{n}\oarg{idx}\marg{entity}\marg{args}
443 % macro formats a description header for \meta{n} entities, of which the
444 % first are specified through \meta{idx}, \meta{entity}, and
445 % \meta{args}.
446 % The margin parts are formatted through the \meta{efmt}\marg{entity}
447 % macro, the parts in the text body through the \meta{afmt}\marg{args}
448 % macro. The index entries are created through the
449 % \meta{icmd}\marg{idx} macro.
450 % In its implementation, |\rgltxdoc@Desc| builds on |\pbox| from the
451 % \pkgname{pbox} package. It uses |\rgltxdoc@DescRec| and
452 % |\rgltxdoc@DescRec@i| (both with the same argument lists) for the
453 % parsing of arguments and for recursively grabbing the arguments for
454 % the \meta{n} entities.
455 % At first, |\rgltxdoc@Desc| creates some vertical space above a
456 % list of description headers. Afterwards it starts the recursion.
457 % \begin{macrocode}
458 \RequirePackage{pbox}
459 \newcommand\rgltxdoc@Desc{\medskip\par\noindent\rgltxdoc@DescRec}
460 \newcommand\rgltxdoc@DescRec[4]{%
461 \@ifnextchar[%]
462 {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}}%
463 {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}[]}}
464 \def\rgltxdoc@DescRec@i#1#2#3#4[#5]#6#7{%
465 % \end{macrocode}
466 % The following code creates the "margin" text (more precisely, a box to
467 % the left of the text) and the \meta{args} next to it.
468 % \begin{macrocode}
469 \rgltxdoc@inmargin{\ttfamily #1{#6}}%
470 % \end{macrocode}
471 % If there is no \meta{args}, then the margin part is moved towards the
472 % left by a |\quad|.
473 % \begin{macrocode}
474 {\ifstrempty{#7}{\quad}{}}%
475 #2{#7}\relax
476 % \end{macrocode}
477 % Next, the index entries are created, through the comma-separated
478 % \meta{idx} if this optional argument is given.
479 % \begin{macrocode}
480 \ifstrempty{#5}%
481 {#3{#6}}%
482 {\forcsvlist{#3}{#5}}%
483 % \end{macrocode}
484 % Next, we check whether $\meta{n}>1$ and recurse, after a line break,
485 % if this is satisfied.
486 % \begin{macrocode}
487 \ifnumgreater{#4}{1}%
488 {\\\rgltxdoc@DescRec{#1}{#2}{#3}{#4-1}}%
489 % \end{macrocode}
490 % Finally, the following code ends a list of description headers, taking
491 % into account that an empty \meta{args} allows the documentation text
492 % to already start in the same line as the "margin" text.
493 % \begin{macrocode}
494 {\ifstrempty{#7}{}{\smallskip\par\noindent}\ignorespaces}}
495 % \end{macrocode}
496 % \end{macro}
497 %
498 % \begin{macro}{\rgltxdoc@inmargin}
499 % The |\rgltxdoc@inmargin|\marg{text}\marg{spacing} macro puts
500 % \meta{text} into the margin of a newly started paragraph and uses
501 % \meta{spacing} to put additional horizontal spacing between
502 % \meta{text} and the left side of the paragraph.
503 % \begin{macrocode}
504 \newcommand\rgltxdoc@inmargin[2]{%
505 \leavevmode\null\hbox to\z@{\hss%
506 \pbox[t]{3\marginparwidth}{#1}%
507 #2}}
508 % \end{macrocode}
509 % \end{macro}
510 %
511 %
512 % \subsection{Arguments, Keys, and Values}
513 %
514 % Longer descriptions of macro/environment arguments as well as of keys
515 % (in key-value lists) and special values can be typeset in tables.
516 % For a common appearance, the \pkgname{keyvaltable} package is used.
517 %
518 % \NiceDescribeEnv{KeyValTable}{\cmarg{KeyDesc}}
519 % This table is used for describing keys in key-value lists. It has
520 % three columns: |key|, |desc|, and |default|. The former two have the
521 % obvious meaning. The latter allows for specifying a default value for
522 % the key that is used when the key is not provided.
523 %
524 % \NiceDescribeEnv{KeyValTable}{\cmarg{ValDesc}}
525 % This table is used for describing special values (constants). It has
526 % two columns, |val| and |desc|, with their obvious meaning.
527 %
528 % \NiceDescribeEnv{KeyValTable}{\cmarg{ArgDesc}}
529 % This table is used for describing arguments of macros and environments
530 % in a structured fashion. It has two columns, |arg| and |desc|.
531 % Examples of this kind of table can be found in \cref{sec:MacrosEnvs}.
532 %
533 % \paragraph{Implementation}\label{sec:KeysValues:impl}
534 %
535 % The \pkgname{keyvaltable} package is used for creating the tables that
536 % document keys, values etc.
537 % \begin{macrocode}
538 \RequirePackage{keyvaltable}
539 \kvtSet{headbg=black!10,rowbg=white..black!5}
540 % \end{macrocode}
541 % The following code defines the table types. The code should be
542 % self-explanatory in terms of which columns exist and what their
543 % alignment and purpose is.
544 % \begin{macrocode}
545 \NewKeyValTable{KeyDesc}{%
546 key: align=l, format=\texttt, head=\textbf{Key};
547 desc: align=X, head=\textbf{Description and Possible Values};
548 default: align=l, format=\texttt, head=\textbf{Default};
549 }
550 \NewKeyValTable[showhead=false]{ValDesc}{%
551 val: align=l, format=\texttt, head=\textbf{Value};
552 desc: align=X, head=\textbf{Description};
553 }
554 \NewKeyValTable[showhead=false]{ArgDesc}{%
555 arg: align=l, head=\textbf{Argument};
556 desc: align=X, head=\textbf{Description};
557 }
558 % \end{macrocode}
559 %
560 %
561 % \subsection{Individual Entities}
562 %
563 % \begin{macro}{\env}
564 % The |\env|\marg{environment} macro is the counterpart of |\cs| for
565 % environment names instead of command names.
566 % \begin{macrocode}
567 \newcommand\env[1]{\texttt{#1}}
568 % \end{macrocode}
569 % \end{macro}
570 %
571 % \begin{macro}{\pkgname}
572 % The |\pkgname|\marg{package-name} macro typesets package names in a
573 % uniform font (sans-serif). Moreover, the package checks whether the
574 % package actually exists, in order to identify embarrassing typos in
575 % the package name.
576 % \begin{macrocode}
577 \newrobustcmd\pkgname[1]{%
578 \IfFileExists{#1.sty}
579 {\textsf{#1}}
580 {\rgltxdoc@err{Package `#1' not found. Spelling?}}}
581 % \end{macrocode}
582 % \end{macro}
583 % \begin{macro}{\pkgnames}
584 % The |\pkgnames|\marg{package-names} macro typesets a comma-separated
585 % list of package names.
586 % \changes{v1.2}{2019/05/04}{macro added}
587 % \begin{macrocode}
588 \newcommand\pkgnames{%
589 \def\do##1{\pkgname{##1}\def\do####1{, \pkgname{####1}}}%
590 \docsvlist}
591 % \end{macrocode}
592 % \end{macro}
593 %
594 % \begin{macro}{\cmarg}
595 % \begin{macro}{\coarg}
596 % The |\cmarg|\marg{const-arg} and |\coarg|\marg{const-arg} macros are
597 % counterparts for |\marg| and |\oarg|. They format constant argument
598 % values, though.
599 % \begin{macrocode}
600 \newcommand\cmarg[1]{\mbox{\texttt{\string{#1\string}}}}
601 \newcommand\coarg[1]{\mbox{\texttt{[#1]}}}
602 % \end{macrocode}
603 % \end{macro}
604 % \end{macro}
605 %
606 % The following enables references to various \hologo{LaTeX} tools in
607 % the common formatting of their names.
608 % \begin{macrocode}
609 \RequirePackage{hologo}
610 % \end{macrocode}
611 %
612 %
613 % \section{Typesetting Examples}
614 %
615 % For typesetting examples, the \pkgname{showexpl} package is used.
616 % Some specific settings for the appearance of the example listings are
617 % defined and some auxiliary macros simplify special examples.
618 %
619 % Generally, code examples shall be typeset in one of two ways:
620 % \begin{enumerate}
621 % \item through \env{lstlisting} environments, if only code shall be
622 % displayed but no visualization of the code's output;
623 % \item through \env{LTXexample} environments, if the code as well as its
624 % output shall be displayed.
625 % \end{enumerate}
626 % Below follows an example of \env{LTXexample} that uses some of the
627 % features provided by \pkgname{rgltxdoc} on top of \pkgname{showexpl}:
628 % Labels/references and sections.
629 % \begin{LTXexample}
630 % \section{Test}
631 % \label{sec:test}
632 % \cref{sec:test} has number~\ref{sec:test}.
633 % \end{LTXexample}
634 %
635 % The following code performs the setup for both (because
636 % \env{LTXexample} builds on \env{lstlisting}).
637 % \begin{macrocode}
638 \RequirePackage{showexpl}
639 \lstset{%
640 gobble=2,
641 frame=trbl,
642 backgroundcolor=\color{black!5!white},
643 explpreset={%
644 numbers=none, columns=flexible, basicstyle=\footnotesize\ttfamily},
645 numbers=none, columns=flexible, basicstyle=\footnotesize\ttfamily,
646 preset={\rgltxdoc@ExampleFix\rgltxdoc@SaveSecs\small\sffamily},
647 overhang=2cm,
648 pos=r,
649 captionpos=b}
650 % \end{macrocode}
651 % The following enables references to \env{LTXexample} and
652 % \env{lstlisting} environments through |\cref| and |\vref|.
653 % \begin{macrocode}
654 \crefname{lstlisting}{Listing}{Listings}
655 % \end{macrocode}
656 %
657 % The following adds the |morepreset| key to \env{listing} environments,
658 % to allow for extending |preset| code rather than overwriting it.
659 % \begin{macrocode}
660 \lst@Key{morepreset}\relax{\appto\SX@preset{#1}}
661 % \end{macrocode}
662 %
663 % \begin{macro}{\rgltxdoc@ExampleFix}
664 % The |\rgltxdoc@ExampleFix| macro performs some setup to enable, to
665 % some extent, functionality that \pkgname{showexpl} disables or does
666 % not implement. Concretely,
667 % \begin{itemize}
668 % \item the macro simulates labels and references, as long as labels are
669 % only referenced after they have been defined (in \env{LTXexample}
670 % environments, the normal label and ref mechanism is otherwise
671 % disabled);
672 % \item the macro re-enables the default |\marginpar| macro, which is
673 % disabled by \env{LTXexample} presumably due to its suboptimal
674 % appearance; for the cases in which the appearance can be justified,
675 % the macro is enabled.
676 % \end{itemize}
677 % \begin{macrocode}
678 \newcommand\rgltxdoc@ExampleFix{%
679 % \end{macrocode}
680 % The fake |\label|\oarg{type}\marg{label} macro takes the optional
681 % \meta{type}, as the \pkgname{cleveref} package defines it. The macro
682 % first saves the current label value in a global macro for basic
683 % |\ref|s. Then, for |\cref|s, the macro also stores the label's type,
684 % either from \meta{type} or from \pkgname{cleveref}'s routines.
685 % \begin{macrocode}
686 \renewcommand\label[2][]{%
687 \global\csletcs{rgltxdoc@@lbl@##2}{@currentlabel}%
688 \ifstrempty{##1}
689 {\csxdef{rgltxdoc@@lbltype@##2}{\rgltxdoc@curlbltype}}
690 {\csgdef{rgltxdoc@@lbltype@##2}{##1}}}%
691 % \end{macrocode}
692 % The |\ref| and |\cref| macros simply use the values stored by
693 % |\label|. Note that the multitude of further \pkgname{cleveref} and
694 % \pkgname{varioref} macros, e.g., |\crefrange| are currently not
695 % implemented. They would need to be defined when there is actual
696 % demand for them.
697 % \begin{macrocode}
698 \def\ref##1{\csuse{rgltxdoc@@lbl@##1}}%
699 \def\cref##1{%
700 \csuse{cref@\csuse{rgltxdoc@@lbltype@##1}@name}~\ref{##1}}%
701 \let\marginpar=\rgltxdoc@@marginpar
702 }
703 \let\rgltxdoc@@marginpar=\marginpar
704 % \end{macrocode}
705 % The |\rgltxdoc@curlbltype| and |\rgltxdoc@curlbltype@i| macros are
706 % auxiliary macros for parsing the content of |\cref@currentlabel|, as set
707 % by the \pkgname{cleveref} package. The first bracketet value in the
708 % content is the label type we're interested in here.
709 % If there's no current label type, we silently use the empty string.
710 % \begin{macrocode}
711 \def\rgltxdoc@curlbltype{%
712 \@ifundefined{cref@currentlabel}{}
713 {\expandafter\rgltxdoc@curlbltype@i\cref@currentlabel\@nil}}
714 \def\rgltxdoc@curlbltype@i[#1][#2][#3]#4\@nil{#1}
715 % \end{macrocode}
716 % \end{macro}
717 %
718 % \begin{macro}{\rgltxdoc@SaveSecs}
719 % \begin{macro}{\rgltxdoc@RestoreSecs}
720 % The |\rgltxdoc@SaveSecs| macro saves the section counters and the
721 % |\rgltxdoc@RestoreSecs| macro restores the values of the section
722 % counters. This allows one to use sectioning commands in code examples
723 % without interfering with the section numbering in the documentation.
724 % The |\rgltxdoc@SaveSecs| macro additionally disables the TOC macro,
725 % such that example sections do not appear in the documentation's TOC.
726 % \changes{v1.2}{2019/05/04}{disabled contents lines}
727 % \begin{macrocode}
728 \newcommand\rgltxdoc@SaveSecs{%
729 \def\addcontentsline##1##2##3{}%
730 \@for\SC:=chapter,section,subsection,subsubsection\do{%
731 \@ifundefined{c@\SC}{}
732 {\csedef{rgltx@@ctr@\SC}{\the\value{\SC}}%
733 \setcounter{\SC}{0}}}}
734 \newcommand\rgltxdoc@RestoreSecs{%
735 \@for\SC:=chapter,section,subsection,subsubsection\do{%
736 \@ifundefined{c@\SC}{}
737 {\setcounter{\SC}{\csuse{rgltx@@ctr@\SC}}}}}
738 \patchcmd{\SX@resultInput}{\par}{\rgltxdoc@RestoreSecs\par}
739 {}
740 {\rgltxdoc@warn{Could not patch showexpl to reset section counters.}}
741 % \end{macrocode}
742 % \end{macro}
743 % \end{macro}
744 %
745 % \section{Shared Internal Code}
746 %
747 % \begin{macro}{\rgltxdoc@err}
748 % \begin{macro}{\rgltxdoc@warn}
749 % The |\rgltxdoc@err|\marg{error} macro raises the given \meta{error}.
750 % The |\rgltxdoc@warn|\marg{warning} macro raises the given
751 % \meta{warning}.
752 % \begin{macrocode}
753 \newcommand\rgltxdoc@err[1]{%
754 \PackageError{rgltxdoc}{#1}{}}
755 \newcommand\rgltxdoc@warn[1]{%
756 \PackageWarning{rgltxdoc}{#1}{}}
757 % \end{macrocode}
758 % \end{macro}
759 % \end{macro}
760 %
761 % \section{Future Work}
762 %
763 % \begin{itemize}
764 % \item Add keys, as listed in |KeyDesc| tables to the index
765 % automatically.
766 % \end{itemize}
767 %
768 %\iffalse
769 %</package>
770 %\fi
771 % \Finale
772 \endinput