Debian Codegraph @

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

raw
1 % \iffalse
2 %% skdoc documentation class
3 %%
4 %% Copyright (C) 2012-2025 by Simon Sigurdhsson <[email protected]>
5 %%
6 %% This work may be distributed and/or modified under the
7 %% conditions of the LaTeX Project Public License, either version 1.3
8 %% of this license or (at your option) any later version.
9 %% The latest version of this license is in
10 %% http://www.latex-project.org/lppl.txt
11 %% and version 1.3 or later is part of all distributions of LaTeX
12 %% version 2005/12/01 or later.
13 %%
14 %% This work has the LPPL maintenance status `maintained'.
15 %%
16 %% The Current Maintainer of this work is Simon Sigurdhsson.
17 %%
18 %% This work consists of the files skdoc.dtx
19 %% and the derived filebase skdoc.cls.
20 %
21 %<*ignore>
22 \begingroup
23 \catcode123=1 %
24 \catcode125=2 %
25 \def\x{LaTeX2e}%
26 \expandafter\endgroup
27 \ifcase 0\ifx\install y1\fi\expandafter
28 \ifx\csname processbatchFile\endcsname\relax\else1\fi
29 \ifx\fmtname\x\else 1\fi\relax
30 \else\csname fi\endcsname
31 %</ignore>
32 %<*install>
33 \input docstrip.tex
34
35 \preamble
36 \endpreamble
37
38 \keepsilent
39 \askforoverwritefalse
40
41 \generate{%
42 \file{skdoc.cls}{\from{skdoc.dtx}{class}}%
43 }
44
45 \begingroup
46 \obeyspaces
47 \Msg{*************************************************************}%
48 \Msg{* *}%
49 \Msg{* To finish the installation you have to move the following *}%
50 \Msg{* file into a directory searched by TeX: *}%
51 \Msg{* *}%
52 \Msg{* skdoc.cls *}%
53 \Msg{* *}%
54 \Msg{* To produce the documentation run the file skdoc.dtx *}%
55 \Msg{* through LaTeX. *}%
56 \Msg{* *}%
57 \Msg{* Happy TeXing! *}%
58 \Msg{* *}%
59 \Msg{*************************************************************}%
60 \endgroup%
61
62 \endbatchfile
63 %</install>
64 %<*ignore>
65 \fi
66 %</ignore>
67 %<*class>
68 \RequirePackage{expl3}
69 %</class>
70 %<*driver>
71 \RequirePackage{xparse}
72 \ProvidesExplFile{skdoc.dtx}
73 %</driver>
74 %<class>\ProvidesExplClass{skdoc}
75 %<*class>
76 {2025/01/08}{1.5e}{skdoc documentation class}
77 %</class>
78 %
79 %<*driver>
80 \msg_new:nnn{skdoc-dtx}{not-installed}
81 {Run~`tex'~on~skdoc.dtx~before~generating~the~documentation!}
82 \IfFileExists{skdoc.cls}{}{
83 \msg_fatal:nn{skdoc-dtx}{not-installed}
84 }
85 \cs_set_protected_nopar:Npn\ExplHack{
86 \char_set_catcode_letter:n{ 58 }
87 \char_set_catcode_letter:n{ 95 }
88 }
89 \ExplSyntaxOff
90 \DeclareDocumentCommand\MakePercentIgnore{}{\catcode`\%9\relax}
91 \DeclareDocumentCommand\MakePercentComment{}{\catcode`\%14\relax}
92 \DeclareDocumentCommand\DocInput{m}{
93 \MakePercentIgnore\input{#1}\MakePercentComment
94 }
95 \documentclass[highlight=false]{skdoc}
96 \usepackage{hologo}
97 \usepackage{booktabs}
98 \usepackage{csquotes}
99 \usepackage[style=authoryear,backend=biber]{biblatex}
100 %%\usepackage{chslacite}
101 \begin{filecontents}{skdoc.bib}
102 @online{Lazarides12,
103 author = {Yannis Lazarides},
104 title = {Different approach to literate programming for \LaTeX},
105 year = {2012},
106 url = {http://tex.stackexchange.com/q/47237/66}
107 }
108 @online{Talbot13,
109 author = {Nicola Talbot},
110 title = {Answer to \enquote{Distinct formatted page numbers with glossaries and Xindy}},
111 year = {2013},
112 url = {http://tex.stackexchange.com/a/89830/66}
113 }
114 @manual{Rahtz10,
115 author = {Sebastian Rahtz and Herbert Vo\ss},
116 title = {The \enquote{\textsf{fancyvrb}} package},
117 subtitle = {Fancy Verbatims in \LaTeX},
118 date = {2012-05-15},
119 version = {2.8},
120 url = {http://mirrors.ctan.org/macros/latex/contrib/fancyvrb/fancyvrb.pdf}
121 }
122 \end{filecontents}
123 \addbibresource{skdoc.bib}
124 \OnlyDescription
125 \begin{document}
126 \DocInput{skdoc.dtx}
127 \end{document}
128 % \fi
129 %
130 % \deftripstyle{skdoc-class}{}{}{}%
131 % {\small The~\textbf{\thepkg}~document~class,~\theversion}%
132 % {}{\small\pagemark}
133 % \pagestyle{skdoc-class}
134 %
135 % \version{1.5e}
136 % \changes{1.0}{Initial version}
137 % \changes{1.1}{Added support for syntax highlighting using \pkg{minted}}
138 % \changes{1.1a}{Deprecate the use of \pkg{bibtex} in favour of \pkg{biblatex}}
139 % \changes{1.2}{Use \pkg{l3prg} booleans instead of toggles}
140 % \changes{1.2b}{Use \pkg{inconsolata}. Don't use \pkg{ascii}}
141 % \changes{1.3}{Allow multiple targets per \env{MacroCode}}
142 % \changes{1.3b}{Use \pkg{sourcecodepro} instead of \pkg{inconsolata}. Fix issue with index entries of different types with same name}
143 % \changes{1.4}{Added option to control \pkg{babel}. Allow optional default value arguments in \env{macro} and friends. Fix spacing issue in \env{option} and friends}
144 % \changes{1.4a}{Fix various compatibility issues with latest \pkg{glossaries}}
145 % \changes{1.4b}{Track \pkg{expl3} changes (thanks to Joseph Wright)}
146 % \changes{1.5}{Fix incompatibilities with \pkg{minted}}
147 % \changes{1.5a}{Track \pkg{expl3} changes (thanks to Felix Faltin)}
148 % \changes{1.5b}{Track \pkg{expl3} changes (thanks to Phelype Oleinik). Replace \pkg{opensans} option \opt{osfigures} with \opt{oldstyle} (\#40)}
149 % \changes{1.5c}{Replace \pkg{scrpage} package with \pkg{scrlayer-scrpage} (thanks to Daniel Wunderlich)}
150 % \changes{1.5d}{Use compatibiltiy levels for \pkg{scrartcl} (\#44)}
151 % \changes{1.5e}{Fix incompatibilities with \pkg{glossaries} (\#47). Use \pkg{minted2} instead of \pkg{minted}}
152 % \iffalse
153 %%% Don't forget to update the version number and release date of
154 %%% the package declaration on line 76!
155 % \fi
156 %
157 % \package[ctan=skdoc,vcs=https://github.com/urdh/skdoc]{skdoc}
158 % \repository{https://github.com/urdh/skdoc}
159 % \title{The \thepkg{} document class}
160 % \author{Simon Sigurdhsson}
161 % \email{[email protected]}
162 % \maketitle
163 %
164 % \begin{abstract}
165 % The \thepkg{} class provides macros to document the functionality
166 % and implementation of \LaTeX\ packages and document classes. It is
167 % loosely based on the \pkg{ydoc} and \pkg{ltxdoc} classes, but has
168 % a number of incompatible differences.
169 %
170 % The class defines a \env{MacroCode} environment which substitutes
171 % the usual \pkg{docstrip} method of installing packages. It has the
172 % ability to generate both documentation and code in a single run of
173 % a single file.
174 % \end{abstract}
175 %
176 % \tableofcontents
177 %
178 % \section{Introduction}
179 % This document class, inspired by a question on the \TeX\ Stack
180 % Exchange\footcite{Lazarides12}, aims to provide an alternative to
181 % the standard \pkg{docstrip} method of literate programming for
182 % \LaTeX\ packages. It also aims to provide a more modern, appealing
183 % style for \LaTeX\ package documentation.
184 %
185 % In order to achieve this, it builds upon already existing features
186 % of the \pkg{expl3}, \pkg{verbatim} and \pkg{ydoc} packages as well
187 % as the KOMA-script document classes.
188 %
189 % So far it is mainly intended to be an experiment to explore a less
190 % cumbersome way of writing \LaTeX\ packages, and as such I give no
191 % guarantee that this package will continue to exist in a working
192 % state (\emph{i.e.} future users may not be able to extract code from
193 % package documentation based on \thepkg) or that its public API
194 % (commands and environments described by this documentation; consider
195 % undocumented macros part of a private API) will be stable.
196 %
197 % The documentation of \thepkg\ is in fact typeset using the class
198 % itself. It does not, however, make use of the main feature of this
199 % class (the \env{MacroCode} environment), because bootstrapping the
200 % class to generate itself is more complicated than it is useful.
201 %
202 % \section{Documentation}
203 % Since \thepkg\ is based on \pkg{ydoc} many of the macros and
204 % environment present in that package are also available in \thepkg,
205 % in a possibly redefined incanation. However, any macros or
206 % environment present in \pkg{ydoc} but not described in this
207 % documentation should be considered part of the private API of
208 % \thepkg. In the future, the removal of the \pkg{ydoc} dependency
209 % may result in such macros being unavailable, and at present changes
210 % made by \thepkg\ may break such macros without notice.
211 %
212 % \subsection{Options}
213 % \Option{load}\WithValues{\meta{package}}\AndDefault{\cs{jobname}}
214 % \label{ssec:options:load} The \opt{load}
215 % option declares that if the package specified exists, it should
216 % be loaded. This is intended to load any package provided in the
217 % implementation, but requires that the documentation provides
218 % stub variants of the macros used in the documentation so that
219 % \LaTeX\ still completes its first run.
220 %
221 % \Option{highlight}\WithValues{true,false}\AndDefault{true}
222 % \label{ssec:option:highlight}
223 % The \opt{highlight} option enables or disabled syntax highlighting
224 % of the implementation code. Highlighting is performed using
225 % \pkg{minted2}, and falls back to no highlighting if there is no
226 % \cs{write18} access, if \pkg{minted2} is unavailable or if the
227 % \texttt{pygmentize} binary can't be found.
228 % \Notice{On non-unix platforms, the test for \texttt{pygmentize}
229 % will likely fail. Therefore, syntax highlighting is not supported
230 % on such platforms.}
231 %
232 % Generally, there should be no reason to disable syntax highlighting
233 % unless the documentation describes a very large package, and the
234 % repeated calls to \texttt{pygmentize} take too long.
235 %
236 % \Option{babel}
237 % The \opt{babel} option allows you to specify what languages are loaded
238 % by the \pkg{babel} package. It is a key-value option, and its content
239 % is passed as options to the \pkg{babel} \cs*{usepackage} declaration.
240 %
241 % \subsection{General macros}
242 % The document class defines a number of general macros intended for
243 % use in parts of the document not strictly considered
244 % \enquote{documentation} or \enquote{implementation}, in addition to
245 % being used in those parts. These \enquote{general} macros include
246 % macros that define metadata, generate the title page, typeset
247 % notices or warnings and those that refer to macros, environments,
248 % packages and such.
249 %
250 % \subsubsection{Metadata}
251 % Several macros for defining metadata (\emph{i.e.} information about
252 % the package and its documentation) are made available. These mostly
253 % set an internal variable which is used to typeset the title page,
254 % and to insert PDF metadata whenever \hologo{pdfLaTeX} is used to
255 % generate the documentation.
256 %
257 % \DescribeMacro\package['ctan='<identifier>',vcs='<url>]{<package name>}
258 % The \cs{package} macro defines the package name used by \cs{thepkg},
259 % \cs{maketitle} and similar macros. It also calls \cs{title} to set
260 % a sensible default title based on the package name. The optional
261 % key-value argument takes two keys: \texttt{ctan} and \texttt{vcs}.
262 % The first one accepts an optional value \meta{identifier}, which
263 % should be the identifier the package has on CTAN (the default is
264 % \cs{jobname}), while the other takes a mandatory argument \meta{url}
265 % specifying the URL of a VCS repository where development versions
266 % of the package are available. The two optional keys imply calls to
267 % the \cs{ctan} and \cs{repository} macros, respectively.
268 %
269 % \DescribeMacro\version{<version>}
270 % Sets the version number of the package the documentation describes.
271 % Here, \meta{version} should not include the initial \enquote{v},
272 % \emph{i.e.} the argument should be the same as that given to
273 % \emph{e.g.} the \LaTeX3 \cs{ProvidesExplPackage} or the standard
274 % \pkg{ltxdoc} \cs{changes}.
275 %
276 % \DescribeMacro\ctan{<identifier>}
277 % As detailed above, this macro defines the CTAN identifier of the
278 % package, which is (optionally) used in the \cs{maketitle} macro.
279 %
280 % \DescribeMacro\repository{<url>}
281 % Again, as detailed above this macro defines the URL of a source code
282 % repository containing a development version of the package, which
283 % is optionally used by \cs{maketitle}.
284 %
285 % \DescribeMacro\author{<name>}
286 % Defines the name of the package author. This is used by
287 % \cs{maketitle} and is mandatory if \cs{maketitle} is used.
288 %
289 % \DescribeMacro\email{<email>}
290 % Defines the email of the package author. This is used by
291 % \cs{maketitle} and is mandatory if \cs{maketitle} is used.
292 %
293 % \DescribeMacro\title{<title>}
294 % Defines the package title. By default, the \cs{package} macro sets
295 % a sensible title that should suit most packages, but using \cs{title}
296 % will override this title (useful for \emph{e.g.} document classes or
297 % \hologo{BibTeX} styles).
298 %
299 % Three macros retrieving the set metadata are also available. They
300 % can be used to typeset the current version of the package, and the
301 % package name, respectively.
302 %
303 % \DescribeMacro\theversion
304 % Returns the version as defined by \cs{version}, with a leading
305 % \enquote{v}. That is, issuing \Macro\version{1.0} makes
306 % \cs{theversion} print \enquote{v1.0}.
307 %
308 % \DescribeMacro\thepackage
309 % \DescribeMacro\thepkg
310 % The \cs{thepackage} and \cs{thepkg} macros return the package name
311 % as defined by the \cs{package} macro, enclosed in \cs{pkg*}. That is,
312 % the package name is typeset as a package but not indexed.
313 %
314 % \subsubsection{The preamble}
315 % The preamble of any documentation most often consists of a title page
316 % containing an abstract, and possibly a table of contents. The \thepkg
317 % \ package provides macros and environments that typeset such things,
318 % and these should be fully compatible with most other document classes.
319 %
320 % \DescribeMacro\maketitle
321 % The \cs{maketitle} macro typesets a title page. This title page uses
322 % the metadata defined by the macros described earlier, and typesets
323 % them in a manner which is illustrated by the documentation of this
324 % class. This style is inspired by \pkg{skrapport}, which is in turn
325 % inspired by the title pages of the Prac\TeX\ Journal.
326 %
327 % \DescribeEnv[<package abstract>]{abstract}
328 % The \env{abstract} environment typesets an abstract of the package.
329 % Again, its style is illustrated by this document and it is inspired
330 % by the \pkg{skrapport} package as well as the Prac\TeX\ Journal.
331 %
332 % \DescribeMacro\tableofcontents
333 % Finally, a Table of Contents may be printed. The actual table of
334 % contents is provided by the \pkg{scrartcl} document class, but \thepkg
335 % \ redefines a couple of the internal macros to style the Table of
336 % Contents in a manner similar to that of the \pkg{microtype} manual.
337 %
338 % \subsubsection{The LPPL license}
339 % \DescribeMacro\PrintLPPL
340 % If the LPPL license is present in a directory where \LaTeX\ can find
341 % it, in a file called \file{lppl.tex}, then \cs{PrintLPPL} will
342 % include the entire LPPL license in the document, and typeset it in
343 % a fairly compact manner.
344 %
345 % \subsubsection{Notices and warnings}
346 % The document class provides macros to indicate information that may
347 % be of extra importance in the documentation. Such information is
348 % categorized as either notices or warnings, which are treated
349 % differently.
350 %
351 % \DescribeMacro\Notice{<notice>}
352 % A notice is a short piece of text that contains information that may
353 % explain some unexpected but unharmful behaviour of a macro or similar.
354 % It is typeset inline, emphasized and in parantheses --- as such, the
355 % sequence \Macro\Notice{a notice} yields \Notice{a notice}.
356 %
357 % \DescribeMacro\Warning{<warning>}
358 % A warning is a short comment that conveys information that the user
359 % must be aware of. This includes unexpected potentially harmful
360 % behaviour, deprecation notices and so on. It is typeset in its own
361 % \cs{fbox} --- the sequence \Macro\Warning{a warning} yields the
362 % following: \Warning{a warning}
363 %
364 % \DescribeMacro\LongWarning{<warning>}
365 % The \cs{LongWarning} macro is a variant of \cs{Warning} that has been
366 % adapted for longer texts, possibly including paragraph breaks. Like
367 % \cs{Warning}, it is typeset in a box: \LongWarning{a long warning}
368 %
369 % \subsubsection{Referential macros}\label{sec:ref-macros}
370 % The family of macros originating from \cs{cs} are used to typeset
371 % various concepts in running text. In addition to adhering to the
372 % general format of the corresponding concept, they index their
373 % argument. Each of these macros have a starred variant which does
374 % not index its argument; use these when appropriate.
375 %
376 % \DescribeMacro\cs{<command sequence>}
377 % Typesets a command sequence, or macro. The argument should be
378 % provided without the leading backslash, and the command sequence
379 % will be typeset in a monospaced font.
380 %
381 % \DescribeMacro\env{<environment name>}
382 % Typesets an environment name, which will be typeset in a monospace
383 % font.
384 %
385 % \DescribeMacro\pkg{<package name>}
386 % Typesets a package, document class or bundle name. The name will
387 % be typeset in a sans-serif font.
388 %
389 % \DescribeMacro\opt{<option>}
390 % Typesets a package or document class option. As of \theversion,
391 % options are typeset using a monospace font.
392 %
393 % \DescribeMacro\bib{<\hologo{BibTeX} entry type>}
394 % Typesets a \hologo{BibTeX} entry type. The agument should be provided
395 % without the leading \texttt{@} sign. The entry type will be typeset
396 % in a monospace font.
397 %
398 % \DescribeMacro\thm{<theme name>}
399 % Typesets a theme name. As of \theversion, the theme name will be
400 % typeset in an upright serif font.
401 %
402 % \DescribeMacro\file{<filename>}
403 % Typesets a filename. As of \theversion, the filename will be typeset
404 % in a monospace font.
405 %
406 % \subsection{Documenting the package}\label{sec:doc-macros}
407 % The documentation part of any \LaTeX\ manual is arguably the most
408 % important one, and to facilitate proper typesetting of the
409 % documentation \thepkg\ povides a number of different macros, all
410 % inspired by or inherited from \pkg{ydoc}. The first of these
411 % macros that will be discussed are the macros that typeset differen
412 % kinds of arguments in running text.
413 %
414 % \DescribeMacro\meta{<meta text>}
415 % The \cs{meta} macro typesets a placeholder to be placed in an
416 % argument. This can be used to refer to arguments and contents of
417 % macros and environments described by commands discussed later in
418 % this documentation. It is typeset in brackets: \meta{meta text}.
419 %
420 % \DescribeMacro\marg{<mandatory argument>}
421 % \DescribeMacro\oarg{<optional argument>}
422 % \DescribeMacro\parg{<picture-style argument>}
423 % \DescribeMacro\aarg{<beamer-style argument>}
424 % \DescribeMacro\sarg
425 % These macros typeset different kinds of arguments (mandatory,
426 % optional, picture-style, beamer-style and star arguments,
427 % respetively). These can be used to describe arguments, but
428 % are mostly used internally. See table~\ref{tab:args} for
429 % examples of how these macros are typeset.
430 %
431 % \begin{table}[tb]
432 % \centering
433 % \caption{Typesetting arguments}
434 % \label{tab:args}
435 % \begin{tabular}{ll}
436 % \toprule
437 % Invokation & Result \\
438 % \midrule
439 % \Macro\marg{argument} & \marg{argument} \\
440 % \Macro\oarg{argument} & \oarg{argument} \\
441 % \Macro\parg{argument} & \parg{argument} \\
442 % \Macro\aarg{argument} & \aarg{argument} \\
443 % \Macro\sarg & \sarg \\
444 % \bottomrule
445 % \end{tabular}
446 % \end{table}
447 %
448 % \subsubsection{Examples}
449 % \DescribeEnv[<example code>]{example}
450 % Perhaps the most powerful way to illustrate features of a package
451 % is to show their function by examples. This is made possible by
452 % the \env{example} environment. By enclosing example code in this
453 % environment, the actual code is typeset next to the result it would
454 % produce, as seen below\footnote{Note that the showcased \env{example}
455 % environment doesn't contain another \env{example} environment --- the
456 % environment is not intended to be nested inside itself.}\footnote{The
457 % percent characters in the example are caused by the \pkg{docstrip}
458 % requirement of prefixing the documentation with them.}:
459 % \begin{example}
460 % Simply typesetting a
461 % \emph{paragraph} may
462 % be simple enough, but
463 % it should showcase
464 % the utility of the
465 % environment well enough.
466 % \end{example}
467 %
468 % Note that for this to work the package obviously needs to be loaded.
469 % As such, it is probably a good idea to combine the use of \env{example}
470 % with the \opt{load} option, so be sure to read up on the caveats of
471 % using that option (see page \pageref{ssec:options:load}).
472 %
473 % Since the \env{example} environment is based on the same mechanisms
474 % as \env{MacroCode}, (mostly) the same typesetting properties apply.
475 % In particular, the code will be highlighted if \pkg{minted2} is
476 % available. \Notice{Since the backend utilizes \cs{verbatim}, the
477 % usual caveats apply. In particular, leaving whitespace before
478 % \cs{end}\marg{example} will result in an extra newline at the end
479 % of the displayed code.}
480 %
481 % \subsubsection{Options}
482 % Package options are of course important to describe, and to this
483 % end four macros are provided. They aid in describing options of
484 % both regular boolean and the more modern key-value syntax. They
485 % are intended to be used in a sequence: \\
486 % \mbox{\Macro\Option{...}
487 % \AlsoMacro\WithValues{...}
488 % \AlsoMacro\AndDefault{...}}
489 %
490 % \DescribeMacro\Option{<option>}
491 % \DescribeMacro\Options{<option>,...}
492 % These macros typeset an option, and may be followed by the
493 % \cs{WithValues} macro \Notice{the with \cs{Options}, only the
494 % first option in the list will work with \cs{WithValues}}.
495 %
496 % \DescribeMacro\WithValues{<value>,...}
497 % This macro typesets a comma-separated list of values a specific
498 % option can take. It may be followed by the \cs{AndDefault} macro.
499 %
500 % \DescribeMacro\AndDefault{<default value>}
501 % This macro typesets the default value of an option. It may follow
502 % either \cs{Options} or \cs{WithValues}.
503 %
504 % Common constructs using these macros include:
505 % \begin{itemize}
506 % \item \mbox{\small
507 % \Macro\Option{<option>}
508 % \AlsoMacro\WithValues{<value>,...}
509 % \AlsoMacro\AndDefault{<default>}}
510 % \item \mbox{\small
511 % \Macro\Options{<option>,no\meta{option}}
512 % \AlsoMacro\AndDefault{no\meta{option}}}
513 % \end{itemize}
514 %
515 % \subsubsection{Macros}
516 % The \thepkg\ class inherits a number of macros for describing the
517 % package macros from the \pkg{ydoc} package. Only four of them are
518 % to be considered stable.
519 % \LongWarning{
520 % The macros \cs{MakeShortMacroArgs} and \cs{DeleteShortMacroArgs}
521 % and the environments \env{DescribeMacros} and \env{DescribeMacrosTab}
522 % provided by \pkg{ydoc} are unsupported as of \thepkg\ \theversion.
523 % They may work, but this is
524 % not a guarantee and they are most likely broken or may break other
525 % features of \thepkg.
526 % }
527 %
528 % \DescribeMacro\DescribeMacro<\textbackslash macro><macro arguments>
529 % The \cs{DescribeMacro} macro documents a macro along with its
530 % arguments. Any number of \meta{macro arguments} may follow the macro,
531 % and \cs{DescribeMacro} will stop reading arguments on the first
532 % non-argument token. The macro will be indexed.
533 % \LongWarning{Although \meta{\textbackslash macro} can include
534 % \texttt{@} signs, it is not possible to document \LaTeX3-style
535 % macros (with underscores and colons) without the following hack:
536 % \par \medskip \begingroup
537 % \cs*{ExplSyntaxOn} \\
538 % \cs*{cs\_set\_protected\_nopar:Npn}\cs*{ExplHack}\texttt{\{} \\
539 % \hspace*{2ex}\cs*{char\_set\_catcode\_letter:n}\texttt{\{~58~\}} \\
540 % \hspace*{2ex}\cs*{char\_set\_catcode\_letter:n}\texttt{\{~95~\}} \\
541 % \texttt{\}} \\
542 % \cs*{ExplSyntaxOff} \\
543 % \cs*{ExplHack} \\
544 % \endgroup }
545 %
546 % \DescribeMacro\Macro<\textbackslash macro><macro arguments>
547 % This is simply a variant of \cs{DescribeMacro} for use in running
548 % text. It is equivalent to \cs{MacroArgs}\cs{AlsoMacro}.
549 %
550 % \DescribeMacro\MacroArgs<macro aguments>
551 % This macro formats \meta{macro arguments} the same way
552 % \cs{DescribeMacro} does. As with \cs{Macro}, it is used in
553 % running text.
554 %
555 % \DescribeMacro\AlsoMacro<\textbackslash macro><further arguments>
556 % This macro should be used inside \meta{macro arguments} of the macros
557 % described above, and typesets an additional macro as part of the
558 % syntax of the described macro. For instance, the \cs{csname} macro
559 % could be described with the sequence
560 % \cs*{Macro}\cs*{csname}\texttt{<command sequence name>}
561 % \cs*{AlsoMacro}\cs{endcsname}, which would be rendered as
562 % \Macro\csname<command sequence name>\AlsoMacro\endcsname\relax.
563 %
564 % \subsubsection{Environments}
565 % In addition to the macros describing macros, \thepkg\ also inherits
566 % one environment and one macro to describe environments. These are
567 % similar to the macros described previously in both form and function,
568 % but lack equivalents for running text.
569 %
570 % \DescribeMacro\DescribeEnv[<body content>]{<name>}<arguments>
571 % This macro describes an environment, in the same way
572 % \cs{DescribeMacro} does for macros. The \meta{body content}, which
573 % is optional, may be used to indicate what kind of content the
574 % environment is designed to contain. The \cs{MacroArgs}
575 % macro is automatically inserted before \meta{body content}.
576 %
577 % \subsubsection{Other entities}
578 % The document class also provides macros to describe \hologo{BibTeX}
579 % entries and generic themes. The \hologo{BibTeX} entries are described
580 % using the \cs{BibEntry} and \cs{WithFields} macros, while themes are
581 % described using the \cs{Theme} macro.
582 %
583 % \DescribeMacro\BibEntry{<entry name>}
584 % \AlsoMacro\WithFields[<optional fields>]{<mandatory fields>}
585 % These two macros describe a \hologo{BibTeX} entry named
586 % \meta{entry name} (\emph{i.e.}, \bib*{\meta{entry name}}) along with
587 % its optional and mandatory fields.
588 %
589 % \DescribeMacro\Theme{<theme name>}
590 % This macro describes a theme named \meta{theme name}. These could be
591 % used to describe any kind of theme, such as color themes of a
592 % document class.
593 %
594 % \DescribeMacro\DescribeFile{<filename>}
595 % This macro describes a special file named \meta{filename}. This
596 % could be a configuration file or similar that is either part of
597 % the package or something the package reads if available.
598 %
599 % \subsection{Describing the implementation}
600 % In true \TeX\ (and literal programming) fashion the document class
601 % also provides ways to describe, in detail, parts of the
602 % implementation. The most essential of the implementation environments,
603 % without which \thepkg\ doesn't generate any files, is the
604 % \env{MacroCode} environment. Other than that, the implementation
605 % environments should be compatible with or analogous to the standard
606 % \pkg{ltxdoc} document class.
607 %
608 % \subsubsection{Implementation environments}\label{sec:impl-env}
609 % The environments described in this section indicate the
610 % implementation of different concepts including macros, environments
611 % and options. They each have a starred variant which doesn't print
612 % the concept name (only indexes it), and a non-starred variant which
613 % does \Notice{inside these environments, \cs{changes} will refer to
614 % the relevant entity instead of logging \enquote{general} changes}.
615 %
616 % Some of the following environment can typeset descriptions of the
617 % internal arguments (\texttt{\#1}, \texttt{\#2} \emph{etc.}) to
618 % improve readability of the implementation code.
619 %
620 % \DescribeEnv[<description>]{macro}{<\textbackslash macro>}
621 % [<\# of args>]{<arg 1 description>}[<default value>]'...'
622 % {<arg n description>}[<default value>]
623 % With this environment, the implementation of a macro is described.
624 % Note that as with \cs{DescribeMacro}, \LaTeX3-style macros can not
625 % be used in \meta{\textbackslash macro} without the catcode hack
626 % mentioned earlier.
627 %
628 % \DescribeEnv[<description>]{environment}{<environment>}
629 % [<\# of args>]{<arg 1 description>}[<default value>]'...'
630 % {<arg n description>}[<default value>]
631 % This environment describes the implementation of an environment.
632 %
633 % \DescribeEnv[<description>]{option}{<option>}
634 % This environment describes the implementation of an option.
635 %
636 % \DescribeEnv[<description>]{bibentry}{<@entry>}
637 % This environment describes the implementation of a \hologo{BibTeX}
638 % entry type.
639 %
640 % \DescribeEnv[<description>]{theme}{<theme>}
641 % This environment describes the implementation of a theme.
642 %
643 % \subsubsection{The \env{MacroCode} environment}
644 % The \enquote{main event} of the \thepkg\ document class is the
645 % \env{MacroCode} environment. It has roughly the same role the
646 % \env{macrocode} environment has in the \pkg{docstrip} system, except
647 % that it in addition to typesetting the implementation also saves it
648 % to the target files.
649 %
650 % The workflow is simple; before using \env{MacroCode} to export code
651 % to a file the file must be declared using \cs{DeclareFile}, which
652 % also assigns a key to the file (the default is the filename). This
653 % key is passed to the \env{MacroCode} environment, which saves the
654 % code to the specified file.
655 %
656 % \DescribeMacro\DeclareFile['key='<key>',preamble='<preamble>]{<filename>}
657 % The \cs{DeclareFile} macro declares a file for future use with
658 % \env{MacroCode}. The optional argument is a comma separated list of
659 % key-value options, where the possible keys are \texttt{key} and
660 % \texttt{preamble}. Here \meta{key} is a key that is used instead
661 % of the filename in \env{MacroCode}, and \meta{preamble} is a
662 % token or command sequence expanding to a preamble which will be
663 % prepended to the file on output.
664 %
665 % \DescribeMacro\PreambleTo{<\textbackslash token>}{<filename>}
666 % Reads the preamble from \meta{filename}. Lines from the file are
667 % appended to \meta{\textbackslash token} until a line which does not
668 % begin with \texttt{\%\%} is encountered.
669 %
670 % \DescribeMacro\SelfPreambleTo{<\textbackslash token>}
671 % This reads the preamble from the curent file. It is equivalent to
672 % the sequence
673 % \Macro\PreambleTo{<\textbackslash token>}{\cs*{jobname}.tex}.
674 %
675 % \DescribeEnv[<implementation>]{MacroCode}{<key>',...'}
676 % The \env{MacroCode} environment typesets and exports
677 % \meta{implementation} verbatim to the file associated with \meta{key}.
678 % As such, it is the analogue of the \env{macrocode} environment from
679 % \pkg{ltxdoc}, but does not suffer from some of its drawbacks (the
680 % sensitivity to whitespace, for instance). As detailed by the
681 % description of the \opt{highlight} option (on page
682 % \pageref{ssec:option:highlight}), the environment will highlight
683 % the code using \pkg{minted2} if possible. Multiple \meta{key}s are
684 % allowed, and the code will be written to all corresponding files.
685 %
686 % \subsubsection{Hiding the implementation}
687 % For lagre packages it may be of interest to hide the implementation
688 % from the documentation. This is accomplished using the two marker
689 % macros \cs{Implementation} and \cs{Finale} (which should be present
690 % even if not hiding the implementation), and the switch macro
691 % \cs{OnlyDescription}.
692 %
693 % \DescribeMacro\Implementation
694 % This macro indicates the start of the implementation. Normally, this
695 % would directly precede the \cs{section} under which the implementation
696 % is organized.
697 %
698 % \DescribeMacro\Finale
699 % This macro indicates the end of the implementation. Usually the only
700 % things happening after this is the printing of indices, the change
701 % log, bibliographies and the end of the \env{document} environment.
702 %
703 % \DescribeMacro\OnlyDescription
704 % This macro, which should be issued in the preamble, indicates that the
705 % implementation should be hidden. \Warning{this has the side effect
706 % that a page break is inserted where the implementation would normally
707 % reside.}
708 %
709 % \subsection{Documenting changes}
710 % One type of useful information you should provide in your
711 % documentation is a list of changes. The \thepkg\ document class
712 % provides a change list system based on the \pkg{glossaries} package.
713 % As such, including a change list in your documentation requires you
714 % to run \texttt{makeglossaries} between the first and second \LaTeX\
715 % run.
716 %
717 % \DescribeMacro\changes{<version>}{<description>}
718 % The \cs{changes} macro provides the main interface to the change
719 % list system, and adds changes to the change list. Each change is
720 % added with a \emph{context}; if the macro is issued inside one of
721 % the macros described in section~\ref{sec:impl-env}, the concept
722 % currenly being described will be the context. Outside these
723 % environment, the context is \enquote{general}. For every context
724 % and \meta{version}, only one change may be recorded, otherwise
725 % \pkg{glossaries} will issue a warning.
726 %
727 % \DescribeMacro\PrintChanges
728 % This macro prints the list of changes. As explained earlier, this
729 % requires you to run \texttt{makeglossaries} between the two \LaTeX\
730 % runs.
731 %
732 % \subsection{Producing an index}
733 % The macros previously discussed in sections~\ref{sec:ref-macros},
734 % \ref{sec:doc-macros} and \ref{sec:impl-env} automatically index their
735 % aguments using \pkg{glossaries}. By running \texttt{makeglossaries}
736 % you can include an index of all macros, environments, packages and
737 % such that are discussed, documented or implemented in your package.
738 %
739 % \DescribeMacro\PrintIndex
740 % Much like the \cs{PrintChanges} macro, this prints the index. As with
741 % the list of changes, this requires that you run
742 % \texttt{makeglossaries} between the two \LaTeX\ runs.
743 %
744 % \section{Known issues}
745 % A list of current issues is available in the Github repository of this
746 % package\footnote{\url{https://github.com/urdh/skdoc/issues}}, but as
747 % of the release of \theversion, there are two known issues.
748 % \begin{description}
749 % \item[\#30] The use of \pkg{expl3}-style macros in \cs{cs} may cause
750 % issues when generating a glossary. Since such macros are in general
751 % implementation details, a workaround may be to omit the
752 % implementation from the output by using \cs{OnlyDescription}.
753 % \item[\#34] When generating examples utilizing the documented package,
754 % if a previous version of this package is installed on the machine
755 % where this generation is done, the installed version will be used
756 % instead of the version being documented. This may cause incorrect
757 % output or compiler errors. A workaround is to temporarily remove
758 % the installed version while generating documentation for the more
759 % recent version.
760 % \end{description}
761 %
762 % If you discover any bugs in this package, please report them to the
763 % issue tracker in the \thepackage\ Github repository.
764 %
765 % \Implementation \ExplHack
766 % \section{Implementation}
767 % \iffalse
768 %</driver>
769 %<*class>
770 % \fi
771 % \subsection{Require packages}
772 % We begin with loading the \pkg{scrartcl} KOMA-script class and a
773 % few packages we'll be needing.
774 % \begin{macrocode}
775 \PassOptionsToPackage{log-declarations=false}{xparse}
776 \LoadClass[ DIV7,
777 headings=big,
778 numbers=noenddot,
779 abstract=true,
780 bibliography=totocnumbered,
781 index=totoc,
782 version=3.32
783 ]{scrartcl}
784 % \end{macrocode}
785 % These packages are basic low-level things that we use to declare
786 % commands, work with strings and so on.
787 % \begin{macrocode}
788 \RequirePackage{etoolbox,xstring,xparse,atbegshi,kvoptions,pdftexcmds,everyhook}
789 % \end{macrocode}
790 % Now, higher-level packages we use in our definitions.
791 % \begin{macrocode}
792 \RequirePackage{verbatim,needspace,marginnote,calc,hyperref,multicol,hologo}
793 \RequirePackage[nomain,xindy,numberedsection,order=letter,
794 sanitizesort=false]{glossaries}
795 % \end{macrocode}
796 % We also include the \pkg{ydoc} packages we'll be extending.
797 % \begin{macrocode}
798 \RequirePackage{ydoc-code,ydoc-desc}
799 % \end{macrocode}
800 % The rest is basically just styling.
801 % \begin{macrocode}
802 \RequirePackage{scrlayer-scrpage}
803 \AtEndOfClass{%
804 \RequirePackage[\skdoc@babel]{babel}
805 \RequirePackage[english=british]{csquotes}
806 \RequirePackage[font=small,labelfont=bf,textfont=it]{caption}
807 \RequirePackage{PTSerif,sourcecodepro}
808 \RequirePackage[defaultsans,oldstyle,scale=0.95]{opensans}
809 \RequirePackage[babel]{microtype}
810 }
811 % \end{macrocode}
812 %
813 % \subsection{Error messages}
814 % Set up some error message texts for later use.
815 % \begin{macrocode}
816 \msg_new:nnn{skdoc}{key-exists}{File~key~"#1"~already~declared!}
817 \msg_new:nnn{skdoc}{key-nexists}{File~key~"#1"~hasn't~been~declared!}
818 \msg_new:nnn{skdoc}{wrote-file}{Writing~things~to~file~"#1".}
819 \msg_new:nnn{skdoc}{read-preamble}{Reading~preamble~from~file~"#1".}
820 \msg_new:nnn{skdoc}{no-lppl}{Could~not~include~LPPL:~lppl.tex~does~not~exist!}
821 \msg_new:nnn{skdoc}{no-minted}{Syntax~highlighting~disabled:~couldn't~find~minted.sty!}
822 \msg_new:nnn{skdoc}{no-shell-escape}{Syntax~highlighting~disabled:~running~without~unrestricted~\string\write18.}
823 \msg_new:nnn{skdoc}{no-pygments}{Syntax~highlighting~disabled:~couldn't~find~"pygmentize".}
824 \msg_new:nnnn{skdoc}{bibtex-unsupported}{The `bibtex` package is unsupported: continue at own risk!}{Use a more modern bibliography system (i.e. `biblatex`) instead.}
825 % \end{macrocode}
826 %
827 % \subsection{Booleans}
828 % Set up some booleans used throughout the code.
829 % \begin{macro}{\g__skdoc_use_minted_bool}
830 % The \texttt{use_minted} boolean keeps track of wether we're using
831 % \pkg{minted2} or not. The default value is \emph{false}.
832 % \begin{macrocode}
833 \bool_new:N\g__skdoc_use_minted_bool
834 \bool_gset_false:N\g__skdoc_use_minted_bool
835 % \end{macrocode}
836 % \end{macro}
837 % \begin{macro}{\g__skdoc_no_index_bool}
838 % The \texttt{no_index} boolean keeps track of wether the indexing
839 % macros should write things to the index or not. The default value is
840 % \emph{false} (don't not write things to the index).
841 % \begin{macrocode}
842 \bool_new:N\g__skdoc_no_index_bool
843 \bool_gset_false:N\g__skdoc_no_index_bool
844 % \end{macrocode}
845 % \end{macro}
846 % \begin{macro}{\g__skdoc_in_example_bool}
847 % The \texttt{in_example} boolean keeps track of wether we are currently
848 % inside an example or not (used mainly by \cs{skdoc@verbatim}). The
849 % default value is of course \emph{false}.
850 % \begin{macrocode}
851 \bool_new:N\g__skdoc_in_example_bool
852 \bool_gset_false:N\g__skdoc_in_example_bool
853 % \end{macrocode}
854 % \end{macro}
855 % \begin{macro}{\g__skdoc_with_implementation_bool}
856 % The \texttt{with_implementation} boolean keeps track of wether we are
857 % going to typeset the implementation or not. The default value is
858 % \emph{true}, and this is only changed by \cs{OnlyDescription}.
859 % \begin{macrocode}
860 \bool_new:N\g__skdoc_with_implementation_bool
861 \bool_gset_true:N\g__skdoc_with_implementation_bool
862 % \end{macrocode}
863 % \end{macro}
864 % \begin{macro}{\g__skdoc_in_implementation_bool}
865 % The \texttt{in_implementation} boolean keeps track of wether we are
866 % in the implementation part of the documentation or not. It defaults
867 % to \emph{false}, and is changed by \cs{Implementation} and \cs{Finale}.
868 % \begin{macrocode}
869 \bool_new:N\g__skdoc_in_implementation_bool
870 \bool_gset_false:N\g__skdoc_in_implementation_bool
871 % \end{macrocode}
872 % \end{macro}
873 % \begin{macro}{\g__skdoc_negative_space_bool}
874 % This boolean keeps track of the negative spacing added by description
875 % environments, allowing \env{MacroCode} to offset it if it follows the
876 % start of these environments directly. Bit of a hack, really.
877 % \begin{macrocode}
878 \bool_new:N\g__skdoc_negative_space_bool
879 \bool_gset_false:N\g__skdoc_negative_space_bool
880 % \end{macrocode}
881 % \end{macro}
882 %
883 % Finally, we define a helpful conditional based on the last two
884 % booleans. It decides wether code in \cs{skdoc@verbatim} is typeset
885 % or just output to a file.
886 % \begin{macro*}{\__skdoc_if_print_code_p:}
887 % \begin{macro*}{\__skdoc_if_print_code:T}
888 % \begin{macro*}{\__skdoc_if_print_code:F}
889 % \begin{macro}{\__skdoc_if_print_code:TF}
890 % \begin{macrocode}
891 \prg_new_conditional:Nnn\__skdoc_if_print_code:{p,T,F,TF}{
892 \bool_if:nTF{
893 \g__skdoc_in_implementation_bool &&
894 !\g__skdoc_with_implementation_bool
895 }{
896 \prg_return_false:
897 }{
898 \prg_return_true:
899 }
900 }
901 % \end{macrocode}
902 % \end{macro}
903 % \end{macro*}
904 % \end{macro*}
905 % \end{macro*}
906 %
907 % \subsection{Options}
908 % Define the all options, and process them.
909 % \begin{macrocode}
910 \SetupKeyvalOptions{
911 family=skdoc,
912 prefix=skdoc@
913 }
914 \DeclareStringOption{load}[\jobname]
915 \DeclareStringOption[british]{babel}
916 \DeclareBoolOption[true]{highlight}
917 \ProcessKeyvalOptions*
918 % \end{macrocode}
919 % If the \opt{load} option was used, load the given package if it exists.
920 % \begin{macrocode}
921 \IfStrEq{\skdoc@load}{}{}{%
922 \IfFileExists{\[email protected]}{%
923 \RequirePackage{\skdoc@load}
924 }{}
925 }
926 % \end{macrocode}
927 %
928 % \subsection{Special case: syntax highlighting}
929 % We support syntax highlighting through \pkg{minted2}, but only if
930 % we're running with unrestricted \cs{write18} access \emph{and}
931 % there exists a suitable executable (\texttt{pygmentize}). Since
932 % \pkg{minted2} bails out without \cs{write18} access, we have to test
933 % that before even loading it.
934 %
935 % \subsubsection{A simple \cs{write18} test}
936 % Using the \cs{pdf@shellescape} macro from \pkg{pdftexcmds}, we
937 % can define a new conditional that decides if we have unrestricted
938 % \cs{write18} or not.
939 % \begin{macro*}{\__skdoc_if_shellescape:T}
940 % \begin{macro*}{\__skdoc_if_shellescape:F}
941 % \begin{macro}{\__skdoc_if_shellescape:TF}
942 % \begin{macrocode}
943 \prg_new_conditional:Nnn\__skdoc_if_shellescape:{T,F,TF}{
944 \if_cs_exist:N\pdf@shellescape
945 % \end{macrocode}
946 % If the command sequence exists (it really should), we test to see
947 % if it is equal to one. The \cs{pdf@shellescape} macro will be zero
948 % if no \cs{write18} access is available, two if we have restricted
949 % access and one if access is unrestricted.
950 % \begin{macrocode}
951 \if_int_compare:w\pdf@shellescape=\c_one_int
952 \prg_return_true:
953 \else:
954 \prg_return_false:
955 \fi:
956 % \end{macrocode}
957 % If the command sequence doesn't exist, we assume that we have
958 % unrestricted \cs{write18} access (we probably don't), and let
959 % \LaTeX\ complain about it later.
960 % \begin{macrocode}
961 \else:
962 \prg_return_true:
963 \fi:
964 }
965 % \end{macrocode}
966 % \end{macro}
967 % \end{macro*}
968 % \end{macro*}
969 %
970 % \subsubsection{Testing for an application}
971 % In order to find out wether \texttt{pygmentize} is installed, we
972 % have to test for its binary. This is done by shelling out to
973 % \texttt{which} and reading a temporary file, which means we need
974 % a way to delete that file.
975 % \begin{macro}{\__skdoc_rm:n}[1]
976 % {The file to be removed}
977 % \begin{macrocode}
978 \cs_new:Npn\__skdoc_rm:n#1{
979 \immediate\write18{rm~#1}
980 }
981 % \end{macrocode}
982 % \end{macro}
983 % Now, let's define the actual test. Note that this test will fail
984 % on non-unixy platforms (\emph{i.e.} Windows). Deal with it for now.
985 % \begin{macro*}{\__skdoc_if_pygmentize:nT}
986 % \begin{macro*}{\__skdoc_if_pygmentize:nF}
987 % \begin{macro}{\__skdoc_if_pygmentize:nTF}[1]
988 % {The name of the binary to check existence of}
989 % \begin{macrocode}
990 \prg_new_conditional:Nnn\__skdoc_if_pygmentize:{T,F,TF}{
991 % \end{macrocode}
992 % First, run \texttt{which} to create the temporary file.
993 % \begin{macrocode}
994 \immediate\write18{which~pygmentize~&&~touch~\jobname.aex}
995 % \end{macrocode}
996 % A temporary boolean is defined to hold the result of the test (this
997 % is a bit of carco cult programming, any clues as to why placing the
998 % result inside \cs{file_if_exists:nTF} doesn't work are welcome), and
999 % if the test is successful we remove the temporary file.
1000 % \begin{macrocode}
1001 \bool_set:Nn\l_tmpa_bool{\c_false_bool}
1002 \file_if_exist:nT{\jobname.aex}{
1003 \__skdoc_rm:n{\jobname.aex}
1004 \bool_set:Nn\l_tmpa_bool{\c_true_bool}
1005 }
1006 % \end{macrocode}
1007 % Finally, the temporary boolean is used to return a result.
1008 % \begin{macrocode}
1009 \if_bool:N\l_tmpa_bool
1010 \prg_return_true:
1011 \else:
1012 \prg_return_false:
1013 \fi:
1014 }
1015 % \end{macrocode}
1016 % \end{macro}
1017 % \end{macro*}
1018 % \end{macro*}
1019 %
1020 % Using the macros defined above, we can test for both \cs{write18}
1021 % and \texttt{pygmentize}, loading \pkg{minted2} and setting a flag
1022 % if both exist. If the option \opt{highlight} was supplied and set
1023 % to \texttt{false}, we do nothing.
1024 % \begin{macrocode}
1025 \ifskdoc@highlight
1026 \IfFileExists{\[email protected]}{
1027 \__skdoc_if_shellescape:TF{
1028 \__skdoc_if_pygmentize:TF{
1029 \bool_gset_true:N\g__skdoc_use_minted_bool
1030 % \end{macrocode}
1031 % Since \pkg{minted2} (through \pkg{fancyvrb}) loads \pkg{lineno}, and something
1032 % above already defines \cs{c@linenumber}, we have to resort to a bit of a hack
1033 % before we actually load \pkg{minted2}.
1034 % \begin{macrocode}
1035 \cs_undefine:N\c@linenumber
1036 \cs_undefine:N\cl@linenumber
1037 \cs_undefine:N\p@linenumber
1038 \cs_undefine:N\thelinenumber
1039 \RequirePackage{minted2}
1040 % \end{macrocode}
1041 % Now that we have \pkg{minted2}, we redefine the style of the line
1042 % numbers to match what we have further down for the non-highlighted
1043 % mode.
1044 % \begin{macrocode}
1045 \renewcommand{\theFancyVerbLine}{
1046 \sffamily\tiny\textcolor{lightgray}{
1047 \oldstylenums{\arabic{FancyVerbLine}}}
1048 }
1049 % \end{macrocode}
1050 % We also define our own Pygments style, to match the \thepackage%
1051 % color theme. This is a bunch of code generated by running
1052 % \texttt{pygmentize -S default -f latex}, with modifications. Note
1053 % the abundancy of \verb|#| characters; this is somewhat black magic,
1054 % but apparently \LaTeX\ expands them one more time than I'd expect
1055 % in this context. Probably a \LaTeX3 artifact. Also, the macro names
1056 % somehow correspond to Pygments entities (see \emph{e.g.}
1057 % \texttt{pygmentize -S default -f html}), but it's not entirely
1058 % apparent which macro corresponds to what entity.
1059 % \begin{macrocode}
1060 \def\PY@reset{\let\PY@it=\relax \let\PY@bf=\relax%
1061 \let\PY@ul=\relax \let\PY@tc=\relax%
1062 \let\PY@bc=\relax \let\PY@ff=\relax}
1063 \def\PY@tok##1{\csname PY@tok@##1\endcsname}
1064 \def\PY@toks##1+{\ifx\relax##1\empty\else%
1065 \PY@tok{##1}\expandafter\PY@toks\fi}
1066 \def\PY@do##1{\PY@bc{\PY@tc{\PY@ul{%
1067 \PY@it{\PY@bf{\PY@ff{##1}}}}}}}
1068 \def\PY##1##2{\PY@reset\PY@toks##1+\relax+\PY@do{##2}}
1069 \expandafter\def\csname PY@tok@gd\endcsname{%
1070 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1071 \expandafter\def\csname PY@tok@gu\endcsname{%
1072 \let\PY@bf=\textbf%
1073 \def\PY@tc####1{\textcolor{optioncolor}{####1}}}
1074 \expandafter\def\csname PY@tok@gt\endcsname{%
1075 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1076 \expandafter\def\csname PY@tok@gs\endcsname{%
1077 \let\PY@bf=\textbf}
1078 \expandafter\def\csname PY@tok@gr\endcsname{%
1079 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1080 \expandafter\def\csname PY@tok@cm\endcsname{%
1081 \let\PY@it=\textit%
1082 \def\PY@tc####1{\textcolor{lightgray}{####1}}}
1083 \expandafter\def\csname PY@tok@vg\endcsname{%
1084 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1085 \expandafter\def\csname PY@tok@m\endcsname{%
1086 \def\PY@tc####1{\textcolor{meta}{####1}}}
1087 \expandafter\def\csname PY@tok@mh\endcsname{%
1088 \def\PY@tc####1{\textcolor{meta}{####1}}}
1089 \expandafter\def\csname PY@tok@cs\endcsname{%
1090 \let\PY@it=\textit%
1091 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1092 \expandafter\def\csname PY@tok@ge\endcsname{%
1093 \let\PY@it=\textit}
1094 \expandafter\def\csname PY@tok@vc\endcsname{%
1095 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1096 \expandafter\def\csname PY@tok@il\endcsname{%
1097 \def\PY@tc####1{\textcolor{meta}{####1}}}
1098 \expandafter\def\csname PY@tok@go\endcsname{%
1099 \def\PY@tc####1{\textcolor{gray}{####1}}}
1100 \expandafter\def\csname PY@tok@cp\endcsname{%
1101 \def\PY@tc####1{\textcolor{sharp!75}{####1}}}
1102 \expandafter\def\csname PY@tok@gi\endcsname{%
1103 \def\PY@tc####1{\textcolor{bright}{####1}}}
1104 \expandafter\def\csname PY@tok@gh\endcsname{%
1105 \let\PY@bf=\textbf%
1106 \def\PY@tc####1{\textcolor{section}{####1}}}
1107 \expandafter\def\csname PY@tok@ni\endcsname{%
1108 \let\PY@bf=\textbf%
1109 \def\PY@tc####1{\textcolor{keydesc}{####1}}}
1110 \expandafter\def\csname PY@tok@nn\endcsname{%
1111 \let\PY@ul=\underline%
1112 \def\PY@tc####1{\textcolor{black}{####1}}}
1113 \expandafter\def\csname PY@tok@no\endcsname{%
1114 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1115 \expandafter\def\csname PY@tok@na\endcsname{%
1116 \def\PY@tc####1{\textcolor{meta!50}{####1}}}
1117 \expandafter\def\csname PY@tok@nb\endcsname{%
1118 \def\PY@tc####1{\textcolor{black}{####1}}}
1119 \expandafter\def\csname PY@tok@nc\endcsname{%
1120 \let\PY@ul=\underline%
1121 \def\PY@tc####1{\textcolor{bright}{####1}}}
1122 \expandafter\def\csname PY@tok@nd\endcsname{%
1123 \def\PY@tc####1{\textcolor{gray}{####1}}}
1124 \expandafter\def\csname PY@tok@si\endcsname{%
1125 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1126 \expandafter\def\csname PY@tok@nf\endcsname{%
1127 \def\PY@tc####1{\textcolor{bright}{####1}}}
1128 \expandafter\def\csname PY@tok@s2\endcsname{%
1129 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1130 \expandafter\def\csname PY@tok@vi\endcsname{%
1131 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1132 \expandafter\def\csname PY@tok@nt\endcsname{%
1133 \let\PY@bf=\textbf%
1134 \def\PY@tc####1{\textcolor{meta!50}{####1}}}
1135 \expandafter\def\csname PY@tok@nv\endcsname{%
1136 \def\PY@tc####1{\textcolor{scriptcolor}{####1}}}
1137 \expandafter\def\csname PY@tok@s1\endcsname{%
1138 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1139 \expandafter\def\csname PY@tok@gp\endcsname{%
1140 \def\PY@tc####1{\textcolor{gray}{####1}}}
1141 \expandafter\def\csname PY@tok@sh\endcsname{%
1142 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1143 \expandafter\def\csname PY@tok@ow\endcsname{%
1144 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1145 \expandafter\def\csname PY@tok@sx\endcsname{%
1146 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1147 \expandafter\def\csname PY@tok@bp\endcsname{%
1148 \def\PY@tc####1{\textcolor{black}{####1}}}
1149 \expandafter\def\csname PY@tok@c1\endcsname{%
1150 \let\PY@it=\textit%
1151 \def\PY@tc####1{\textcolor{lightgray}{####1}}}
1152 \expandafter\def\csname PY@tok@kc\endcsname{%
1153 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1154 \expandafter\def\csname PY@tok@c\endcsname{%
1155 \let\PY@it=\textit%
1156 \def\PY@tc####1{\textcolor{lightgray}{####1}}}
1157 \expandafter\def\csname PY@tok@mf\endcsname{%
1158 \def\PY@tc####1{\textcolor{meta}{####1}}}
1159 \expandafter\def\csname PY@tok@err\endcsname{%
1160 \def\PY@tc####1{\textcolor{intlink}{####1}}%
1161 \def\PY@bc####1{\setlength{\fboxsep}{0pt}%
1162 \colorbox{bright}{\strut ####1}}}
1163 \expandafter\def\csname PY@tok@kd\endcsname{%
1164 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1165 \expandafter\def\csname PY@tok@ss\endcsname{%
1166 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1167 \expandafter\def\csname PY@tok@sr\endcsname{%
1168 \def\PY@tc####1{\textcolor{meta}{####1}}}
1169 \expandafter\def\csname PY@tok@mo\endcsname{%
1170 \def\PY@tc####1{\textcolor{meta}{####1}}}
1171 \expandafter\def\csname PY@tok@mi\endcsname{%
1172 \def\PY@tc####1{\textcolor{meta}{####1}}}
1173 \expandafter\def\csname PY@tok@kn\endcsname{%
1174 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1175 \expandafter\def\csname PY@tok@kr\endcsname{%
1176 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1177 \expandafter\def\csname PY@tok@s\endcsname{%
1178 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1179 \expandafter\def\csname PY@tok@kp\endcsname{%
1180 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1181 \expandafter\def\csname PY@tok@w\endcsname{%
1182 \def\PY@tc####1{\textcolor{lightgray}{####1}}}
1183 \expandafter\def\csname PY@tok@kt\endcsname{%
1184 \def\PY@tc####1{\textcolor{black}{####1}}}
1185 \expandafter\def\csname PY@tok@sc\endcsname{%
1186 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1187 \expandafter\def\csname PY@tok@sb\endcsname{%
1188 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1189 \expandafter\def\csname PY@tok@k\endcsname{%
1190 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1191 \expandafter\def\csname PY@tok@se\endcsname{%
1192 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1193 \expandafter\def\csname PY@tok@sd\endcsname{%
1194 \def\PY@tc####1{\textcolor{sharp}{####1}}}
1195 \expandafter\def\csname PY@tok@nl\endcsname{%
1196 \def\PY@tc####1{\textcolor{bright}{####1}}}
1197 \expandafter\def\csname PY@tok@ne\endcsname{%
1198 \def\PY@tc####1{\textcolor{bright}{####1}}}
1199 \expandafter\def\csname PY@tok@o\endcsname{%
1200 \def\PY@tc####1{\textcolor{macroimpl}{####1}}}
1201 \def\PYZbs{\char`\\}
1202 \def\PYZus{\char`\_}
1203 \def\PYZob{\char`\{}
1204 \def\PYZcb{\char`\}}
1205 \def\PYZca{\char`\^}
1206 \def\PYZam{\char`\&}
1207 \def\PYZlt{\char`\<}
1208 \def\PYZgt{\char`\>}
1209 \def\PYZsh{\char`\#}
1210 \def\PYZpc{\char`\%}
1211 \def\PYZdl{\char`\$}
1212 \def\PYZhy{\char`\-}
1213 \def\PYZsq{\char`\'}
1214 \def\PYZdq{\char`\"}
1215 \def\PYZti{\char`\~}
1216 \def\PYZat{@}
1217 \def\PYZlb{[}
1218 \def\PYZrb{]}
1219 % \end{macrocode}
1220 % If there's no \texttt{pygmentize}, no \cs{write18} or no \pkg{minted2},
1221 % we display a warning message and proceed without highlighting.
1222 % \begin{macrocode}
1223 }{
1224 \msg_warning:nn{skdoc}{no-pygments}
1225 }
1226 }{
1227 \msg_warning:nn{skdoc}{no-shell-escape}
1228 }
1229 }{
1230 \msg_warning:nn{skdoc}{no-minted}
1231 }
1232 \fi
1233 % \end{macrocode}
1234 % \subsection{The \env{MacroCode} environment}
1235 % We need a token list and input/output.
1236 % \begin{macrocode}
1237 \tl_new:N\skdoc@temptl
1238 \ior_new:N\skdoc@input
1239 \iow_new:N\skdoc@output
1240 % \end{macrocode}
1241 % \begin{macro}{\DeclareFile}[2]
1242 % {A list of key-value parameters}
1243 % {Filename of the file being declared}
1244 % This declares a file as part of the bundle, which means we will be
1245 % writing things to it.
1246 % \changes{1.1a}{Don't create a new token list until we know the
1247 % key isn't a duplicate}
1248 % \begin{macrocode}
1249 \DeclareDocumentCommand\DeclareFile{om}{
1250 \group_begin:
1251 \keys_define:nn{skdoc@declarefile}{%
1252 preamble .value_required:n = true,
1253 preamble .code:n = \edef\skdoc@preamble{##1},
1254 key .value_required:n = true,
1255 key .code:n = \def\skdoc@key{##1}
1256 }%
1257 \def\skdoc@preamble{}%
1258 \def\skdoc@key{#2}%
1259 \IfNoValueTF{#1}{}{\keys_set:nn{skdoc@declarefile}{#1}}
1260 \int_if_exist:cTF{skdoc@output@\skdoc@key @line}{
1261 \msg_critical:nnx{skdoc}{key-exists}{\skdoc@key}
1262 }{
1263 \int_zero_new:c{skdoc@output@\skdoc@key @line}
1264 }
1265 \tl_new:c{skdoc@output@\skdoc@key}
1266 \IfStrEq{\skdoc@preamble}{}{
1267 \def\skdoc@preamble@extra{}
1268 }{
1269 \tl_set:Nx\l_tmpa_tl{\skdoc@preamble}
1270 \edef\skdoc@temp{\tl_head:N\l_tmpa_tl}
1271 \def\skdoc@preamble@extra{
1272 \skdoc@temp\skdoc@temp\space~This~is~file~`#2',~generated~from~`\c_sys_jobname_str.tex'~(key~`\skdoc@key').
1273 }
1274 }
1275 \expandafter\xdef\csname skdoc@write@#2\endcsname{%
1276 \noexpand\msg_log:nnn{skdoc}{wrote-file}{#2}
1277 \noexpand\iow_open:Nn\noexpand\skdoc@output{#2}
1278 \noexpand\IfStrEq{\skdoc@preamble}{}{}{
1279 \noexpand\iow_now:Nx\noexpand\skdoc@output{\skdoc@preamble@extra}
1280 \noexpand\iow_now:Nx\noexpand\skdoc@output{\skdoc@preamble}
1281 }
1282 \noexpand\iow_now:Nx\noexpand\skdoc@output{\noexpand\tl_to_str:c{skdoc@output@\skdoc@key}}
1283 \noexpand\iow_close:N\noexpand\skdoc@output
1284 }
1285 \AfterEndDocument{\csname skdoc@write@#2\endcsname}
1286 \group_end:
1287 }
1288 % \end{macrocode}
1289 % \end{macro}
1290 % \begin{environment}{skdoc@verbatim}[1]
1291 % {The key of the file being described}
1292 % \changes{1.1}{Introducing syntax highlighting}
1293 % \changes{1.1a}{Test for key existence before bumping counter,
1294 % use \cs{Needspace*} to prevent code label from
1295 % staying on the wrong page in some situations}
1296 % \changes{1.2}{Hide line numbers when inside \env{example}}
1297 % \changes{1.3}{Allow multiple (comma-separated) targets}
1298 % \changes{1.3a}{Fix critical bug}
1299 % This environment does all the actual work for \env{MacroCode}.
1300 % \begin{macrocode}
1301 \clist_new:N\l__skdoc_keys
1302 \DeclareDocumentEnvironment{skdoc@verbatim}{m}{%
1303 \clist_set:Nn\l__skdoc_keys{#1}
1304 % \end{macrocode}
1305 % If the file we're supposed to write to hasn't been initialized yet,
1306 % we error out with a critical error.
1307 % \begin{macrocode}
1308 \clist_map_inline:Nn\l__skdoc_keys{
1309 \int_if_exist:cTF{skdoc@output@##1@line}{}{
1310 \msg_critical:nnn{skdoc}{key-nexists}{##1}
1311 }%
1312 % \end{macrocode}
1313 % Before doing anything, set create or increment a counter keeping
1314 % track of the line number of the file we're writing to.
1315 % \begin{macrocode}
1316 \int_compare:nNnT{\int_use:c{skdoc@output@##1@line}}=\c_zero_int%
1317 {\int_gincr:c{skdoc@output@##1@line}}%
1318 }
1319 % \end{macrocode}
1320 % Now, if we're supposed to print code, we set a few things up.
1321 % \begin{macrocode}
1322 \__skdoc_if_print_code:T{
1323 \bool_if:NTF\g__skdoc_use_minted_bool{
1324 % \end{macrocode}
1325 % If we're using \pkg{minted2}, we set a few options ans open the
1326 % output file.
1327 % \begin{macrocode}
1328 \bool_if:NF\g__skdoc_in_example_bool{
1329 \setkeys{minted@opt@g}{linenos}
1330 }%
1331 \exp_args:Nnx\setkeys{FV}{
1332 firstnumber=\int_use:c{skdoc@output@#1@line}
1333 }%
1334 \iow_open:Nn\minted@code{\jobname.pyg}%
1335 \Needspace*{2\baselineskip}%
1336 }{
1337 % \end{macrocode}
1338 % Otherwise, we hack spaces with \cs{@bsphack} (unless we're in an
1339 % \env{example} environment).
1340 % \begin{macrocode}
1341 \bool_if:NF\g__skdoc_in_example_bool{\@bsphack}%
1342 }
1343 \bool_if:NF\g__skdoc_in_example_bool{
1344 % \end{macrocode}
1345 % In all non-example code, \pkg{minted2} or not, we output a small
1346 % marker showing what file we are writing to.
1347 % \begin{macrocode}
1348 \marginnote{
1349 \leavevmode
1350 \llap{
1351 \scriptsize\color{gray}
1352 $\langle$#1$\rangle$
1353 \makebox[2ex]{\strut}
1354 }
1355 }
1356 }
1357 }
1358 % \end{macrocode}
1359 % Otherwise, we set up the \env{verbatim} line processor.
1360 % \begin{macrocode}
1361 \def\verbatim@processline{%
1362 % \end{macrocode}
1363 % We alsays append the line to the appropriate token list, so that it
1364 % is saved to the output file.
1365 % \begin{macrocode}
1366 \clist_map_inline:Nn\l__skdoc_keys{
1367 \tl_gput_right:cx{skdoc@output@####1}{\the\verbatim@line\iow_newline:}%
1368 }
1369 % \end{macrocode}
1370 % If we're supposed to print code, we do a lot more...
1371 % \begin{macrocode}
1372 \__skdoc_if_print_code:T{
1373 \bool_if:NTF\g__skdoc_use_minted_bool{
1374 % \end{macrocode}
1375 % ...but if we're using minted, \enquote{a lot more} consists of also
1376 % writing the line to the file used by \pkg{minted2}.
1377 % \begin{macrocode}
1378 \iow_now:Nx\minted@code{\the\verbatim@line}%
1379 }{
1380 % \end{macrocode}
1381 % Otherwise, we actually do a lot of stuff. We typeset the line number
1382 % (unless we're in an example):
1383 % \begin{macrocode}
1384 \noindent\leavevmode%
1385 \bool_if:NF\g__skdoc_in_example_bool{\hspace*{-5ex}}
1386 \begin{minipage}[c][1ex]{\textwidth}
1387 \bool_if:nF{
1388 \g__skdoc_in_example_bool &&
1389 !\int_compare_p:nNn{\clist_count:N\l__skdoc_keys}>\c_one_int
1390 }{
1391 \makebox[4ex]{%
1392 \leavevmode
1393 \sffamily\tiny\color{lightgray}\hfill%
1394 \clist_map_inline:Nn\l__skdoc_keys{
1395 \oldstylenums{\int_use:c{skdoc@output@####1@line}}%
1396 }
1397 }%
1398 \hspace*{1ex}%
1399 }
1400 % \end{macrocode}
1401 % We also typeset the actual line:
1402 % \begin{macrocode}
1403 {
1404 \verbatim@font
1405 \the\verbatim@line
1406 }
1407 \end{minipage}
1408 % \end{macrocode}
1409 % Both of them in the same one-line-high minipage covering the page
1410 % width. Note the use of \cs{llap} for line numbers in the margin.
1411 % We end with a \cs{par} for the next line.
1412 % \begin{macrocode}
1413 \par
1414 }
1415 }
1416 % \end{macrocode}
1417 % Finally, the line number counter is incremented.
1418 % \begin{macrocode}
1419 \clist_map_inline:Nn\l__skdoc_keys{
1420 \int_gincr:c{skdoc@output@####1@line}%
1421 }
1422 }%
1423 % \end{macrocode}
1424 % Now the \env{verbatim} catcode magic begins.
1425 % \begin{macrocode}
1426 \group_begin:
1427 \let\do\@makeother\dospecials\catcode`\^^M\active%
1428 \bool_if:nT{
1429 \__skdoc_if_print_code_p: &&
1430 !\g__skdoc_use_minted_bool
1431 }{
1432 \frenchspacing\@vobeyspaces
1433 }
1434 \verbatim@start%
1435 }{%
1436 \group_end:
1437 % \end{macrocode}
1438 % The catcode magic is over! Now, if we're printing code, there are
1439 % a few things left to do.
1440 % \begin{macrocode}
1441 \__skdoc_if_print_code:T{
1442 \bool_if:NTF\g__skdoc_use_minted_bool{
1443 % \end{macrocode}
1444 % If we're using \pkg{minted2}, we still have to actually print the code.
1445 % We begin with closing the output file.
1446 % \begin{macrocode}
1447 \iow_close:N\minted@code%
1448 % \end{macrocode}
1449 % A few spacing fixes are applied. Since \pkg{minted2} uses
1450 % \pkg{fancyvrb}, these negative \cs{vspace}s are derived from the
1451 % \pkg{fancyvrb} documentation \parencite[pp.~46--47]{Rahtz10}. What
1452 % we want to do is to offset the spacing produced by \pkg{minted2}, so
1453 % that we are in control.
1454 % \begin{macrocode}
1455 \bool_if:NF\g__skdoc_in_example_bool{
1456 \vspace*{-\topsep}
1457 \vspace*{-\partopsep}
1458 \vspace*{-\parskip}
1459 }
1460 % \end{macrocode}
1461 % Now, the internal \pkg{minted2} macro \cs{minted@pygmentize} is called
1462 % to highlight and typeset the code, and the temporary file is removed.
1463 % \begin{macrocode}
1464 \minted@pygmentize{latex}%
1465 \DeleteFile{\jobname.pyg}%
1466 % \end{macrocode}
1467 % This is followed by more space-offsetting.
1468 % \begin{macrocode}
1469 \vspace*{-\topsep}
1470 \vspace*{-\partopsep}
1471 }{
1472 % \end{macrocode}
1473 % If we aren't using \pkg{minted2}, we hack spaces with \cs{@esphack}
1474 % instead.
1475 % \begin{macrocode}
1476 \bool_if:NF\g__skdoc_in_example_bool{\@esphack}%
1477 }
1478 }%
1479 }
1480 % \end{macrocode}
1481 % \end{environment}
1482 % \begin{environment}{MacroCode}[1]
1483 % {The key of the file being described}
1484 % \changes{1.1}{Minor changes due to syntax highlighting}
1485 % \changes{1.3b}{Offset negative spacing from the description environments}
1486 % \begin{macrocode}
1487 \DeclareDocumentEnvironment{MacroCode}{m}{
1488 \__skdoc_if_print_code:T{
1489 \bool_if:NT\g__skdoc_negative_space_bool{\vspace{\baselineskip}}
1490 \vspace{.2\baselineskip}
1491 \bool_if:NF\g__skdoc_use_minted_bool{\par\noindent}
1492 }
1493 \skdoc@verbatim{#1}
1494 }{
1495 \endskdoc@verbatim
1496 \__skdoc_if_print_code:T{
1497 \vspace{.5\baselineskip}
1498 }
1499 }
1500 % \end{macrocode}
1501 % \end{environment}
1502 %
1503 % \subsubsection{Reading a preamble}
1504 % \begin{macro}{\PreambleTo}[2]
1505 % {A token to which we will save the preamble}
1506 % {File to read the preamble from}
1507 % Read preamble from a document and store in variable.
1508 % \begin{macrocode}
1509 \DeclareDocumentCommand\PreambleTo{mm}{%
1510 \group_begin:
1511 \msg_info:nnn{skdoc}{read-preamble}{#2}
1512 \ior_open:Nn\skdoc@input{#2}
1513 \bool_until_do:nn{\ior_if_eof_p:N\skdoc@input}{%
1514 \tl_if_empty:NTF\skdoc@temptl{}{%
1515 \tl_put_right:Nx\skdoc@temptl{\iow_newline:}
1516 }
1517 \tl_clear:N\l_tmpb_tl
1518 \ior_str_get:NN\skdoc@input\l_tmpa_tl
1519 \tl_put_right:Nx\l_tmpb_tl{\tl_head:N\l_tmpa_tl}
1520 \IfStrEq{\tl_to_str:N\l_tmpb_tl}{\@percentchar}{%
1521 \tl_set_eq:NN\l_tmpb_tl\skdoc@temptl
1522 \tl_concat:NNN\skdoc@temptl\l_tmpb_tl\l_tmpa_tl
1523 }{%
1524 \ior_close:N\skdoc@input
1525 }
1526 }
1527 \xdef#1{\tl_to_str:N\skdoc@temptl}
1528 \group_end:
1529 }
1530 % \end{macrocode}
1531 % \end{macro}
1532 % \begin{macro}{\SelfPreambleTo}[1]
1533 % {A token to which we will save the preamble}
1534 % \changes{1.4c}{Fix mis-spelling of \cs{c_sys_jobname_str}}
1535 % Shorthand to read preamble from current document.
1536 % \begin{macrocode}
1537 \DeclareDocumentCommand\SelfPreambleTo{m}{%
1538 \PreambleTo{#1}{\c_sys_jobname_str}%
1539 }
1540 % \end{macrocode}
1541 % \end{macro}
1542 %
1543 % \subsection{Styling}
1544 % \subsubsection{Colors}
1545 % First, we redefine a couple of colors from \pkg{ydoc} as well as
1546 % defining a couple for ourselves.
1547 % \begin{macrocode}
1548 \definecolorset{RGB}{}{}{
1549 section,11,72,107;
1550 extlink,73,10,61;
1551 intlink,140,35,24;
1552 sharp,250,105,0;
1553 bright,198,229,217;
1554 macrodesc,73,10,61;
1555 keydesc,140,35,24;
1556 macroimpl,73,10,61;
1557 meta,11,72,107;
1558 scriptcolor,140,35,24;
1559 optioncolor,73,10,61;
1560 opt,73,10,61
1561 }
1562 % \end{macrocode}
1563 % \subsubsection{Fonts}
1564 % Then we redefine a couple of the KOMA-script font commands to use
1565 % our newly defined colors, along with other fixes.
1566 % \begin{macrocode}
1567 \RenewDocumentCommand\descfont{}{\sffamily\fontseries{sb}}
1568 \RenewDocumentCommand\sectfont{}{\sffamily\fontseries{sb}}
1569 \addtokomafont{minisec}{\bfseries}
1570 \addtokomafont{paragraph}{\color{section}}
1571 \addtokomafont{section}{\color{section}}
1572 \addtokomafont{subsection}{\color{section}}
1573 \addtokomafont{subsubsection}{\color{section}}
1574 \addtokomafont{descriptionlabel}{\color{section}}
1575 \addtokomafont{sectionentry}{\rmfamily\bfseries}
1576 \addtokomafont{sectionentrypagenumber}{\rmfamily\bfseries}
1577 % \end{macrocode}
1578 % \subsubsection{Configuring \pkg{hyperref}}
1579 % Finally, we set up \pkg{hyperref} to also use our colors.
1580 % \begin{macrocode}
1581 \hypersetup{
1582 colorlinks=true,
1583 linkcolor=intlink,
1584 anchorcolor=intlink,
1585 citecolor=black,
1586 urlcolor=extlink
1587 }
1588 % \end{macrocode}
1589 %
1590 % \subsection{Documentation macros}
1591 % We can now start defining the documentation macros.
1592 %
1593 % \subsubsection{Inline referencing}
1594 % We introduce a couple of macros for referencing various constructs
1595 % in running text, \emph{i.e.} \cs{cs}-like macros. The starred
1596 % variants will not index the use, the non-starred variants will.
1597 % \begin{macro}{\cs}[2]
1598 % {True if this is the starred variant}
1599 % {The macro name to be typeset}
1600 % The \cs{cs} macro typesets a macro.
1601 % \begin{macrocode}
1602 \DeclareDocumentCommand\cs{sm}{
1603 \texttt{\char`\\#2}
1604 \bool_if:NF\g__skdoc_no_index_bool{
1605 \IfBooleanTF{#1}{}{\index@macro{#2}}
1606 }
1607 }
1608 % \end{macrocode}
1609 % \end{macro}
1610 % \begin{macro}{\env}[2]
1611 % {True if this is the starred variant}
1612 % {The environment name to be typeset}
1613 % The \cs{env} macro typesets an environment.
1614 % \begin{macrocode}
1615 \DeclareDocumentCommand\env{sm}{
1616 \texttt{#2}
1617 \bool_if:NF\g__skdoc_no_index_bool{
1618 \IfBooleanTF{#1}{}{\index@environment{#2}}
1619 }
1620 }
1621 % \end{macrocode}
1622 % \end{macro}
1623 % \begin{macro}{\pkg}[2]
1624 % {True if this is the starred variant}
1625 % {The package name to be typeset}
1626 % The \cs{pkg} macro typesets a package.
1627 % \begin{macrocode}
1628 \DeclareDocumentCommand\pkg{sm}{
1629 \textsf{#2}
1630 \bool_if:NF\g__skdoc_no_index_bool{
1631 \IfBooleanTF{#1}{}{\index@package{#2}}
1632 }
1633 }
1634 % \end{macrocode}
1635 % \end{macro}
1636 % \begin{macro}{\opt}[2]
1637 % {True if this is the starred variant}
1638 % {The option name to be typeset}
1639 % The \cs{opt} macro typesets an option
1640 % \begin{macrocode}
1641 \DeclareDocumentCommand\opt{sm}{
1642 \texttt{#2}
1643 \bool_if:NF\g__skdoc_no_index_bool{
1644 \IfBooleanTF{#1}{}{\index@option{#2}}
1645 }
1646 }
1647 % \end{macrocode}
1648 % \end{macro}
1649 % \begin{macro}{\bib}[2]
1650 % {True if this is the starred variant}
1651 % {The \hologo{BibTeX} entry type name to be typeset}
1652 % The \cs{bib} macro typesets a \hologo{BibTeX} entry type.
1653 % \begin{macrocode}
1654 \DeclareDocumentCommand\bib{sm}{
1655 \texttt{@#2}
1656 \bool_if:NF\g__skdoc_no_index_bool{
1657 \IfBooleanTF{#1}{}{\index@bibentry{#2}}
1658 }
1659 }
1660 % \end{macrocode}
1661 % \end{macro}
1662 % \begin{macro}{\thm}[2]
1663 % {True if this is the starred variant}
1664 % {The theme name to be typeset}
1665 % The \cs{thm} macro typesets a theme of some sort.
1666 % \begin{macrocode}
1667 \DeclareDocumentCommand\thm{sm}{
1668 \textrm{#2}
1669 \bool_if:NF\g__skdoc_no_index_bool{
1670 \IfBooleanTF{#1}{}{\index@theme{#2}}
1671 }
1672 }
1673 % \end{macrocode}
1674 % \end{macro}
1675 % \begin{macro}{\file}[2]
1676 % {True if this is the starred variant}
1677 % {The file name to be typeset}
1678 % The \cs{file} macro typesets a file name.
1679 % \begin{macrocode}
1680 \DeclareDocumentCommand\file{sm}{
1681 \texttt{#2}
1682 \bool_if:NF\g__skdoc_no_index_bool{
1683 \IfBooleanTF{#1}{}{\index@file{#2}}
1684 }
1685 }
1686 % \end{macrocode}
1687 % \end{macro}
1688 %
1689 % \subsubsection{Descriptional macros}
1690 % A range of descriptional macros are made available by the \pkg{ydoc}
1691 % package, but we need to redefine and extend them.
1692 %
1693 % We begin with extending.
1694 % \begin{macro}{\Describe@Macro}[1]
1695 % {The macro name, including leading backslash}
1696 % The \cs{Describe@Macro} macro is changed to typeset its agument in
1697 % a \cs{marginnote} instead of an \cs{fbox}.
1698 % \begin{macrocode}
1699 \def\Describe@Macro#1{%
1700 \endgroup
1701 \edef\name{\expandafter\@gobble\string#1}%
1702 \global\@namedef{href@desc@\name}{}%
1703 \immediate\write\@mainaux{%
1704 \global\noexpand\@namedef{href@desc@\name}{}%
1705 }%
1706 \hbox\y@bgroup
1707 \@ifundefined{href@impl@\name}{}{\hyperlink{impl:\name}}%
1708 {%
1709 \hbox{
1710 \vbox to 0pt{
1711 \vss\hbox{
1712 \raisebox{4ex}{\hypertarget{desc:\name}{}
1713 }
1714 }
1715 }%
1716 \marginnote{\llap{\PrintMacroName{#1}}}
1717 }%
1718 }%
1719 \ydoc@macrocatcodes
1720 \macroargsstyle
1721 \read@Macro@arg
1722 }
1723 % \end{macrocode}
1724 % \end{macro}
1725 % \begin{macro}{\descframe}[1]
1726 % {Contents to be framed}
1727 % Similarly, \cs{descframe} is changed to produce an \cs{mbox}
1728 % instead of an \cs{fbox}.
1729 % \begin{macrocode}
1730 \def\descframe#1{%
1731 \mbox{\hspace*{1.5\descsep}#1\hspace*{2\descsep}}%
1732 }
1733 % \end{macrocode}
1734 % \end{macro}
1735 % \begin{macro}{\PrintMacroName}[1]
1736 % {Macro name to be printed}
1737 % \cs{PrintMacroName} is hooked to also index the macro name while
1738 % printing it.
1739 % \begin{macrocode}
1740 \let\old@PrintMacroName\PrintMacroName
1741 \DeclareDocumentCommand\PrintMacroName{m}{%
1742 \index@macro*{\expandafter\@gobble\string#1}
1743 \old@PrintMacroName{#1}
1744 }
1745 % \end{macrocode}
1746 % \end{macro}
1747 % \begin{macro}{\PrintEnvName}[2]
1748 % {Either \cs{end} or \cs{begin}}
1749 % {Name of the environment to be printed}
1750 % Similarly to \cs{PrintMacroName}, the \cs{PrintEnvName} is hooked
1751 % to index the environment when printing the \cs{begin} part of the
1752 % environment.
1753 % \begin{macrocode}
1754 \let\old@PrintEnvName\PrintEnvName
1755 \def\PrintEnvName#1#2{
1756 \ifx#1\begin
1757 \edef\skdoc@temp{\noexpand\index@environment*{#2}}
1758 \skdoc@temp
1759 \fi
1760 \old@PrintEnvName{#1}{#2}
1761 }
1762 % \end{macrocode}
1763 % \end{macro}
1764 % \begin{macro}{\DescribeEnv}[2]
1765 % {Environment body or \cs{NoValue}}
1766 % {Environment name}
1767 % \begin{macrocode}
1768 \DeclareDocumentCommand\DescribeEnv{om}{
1769 \medskip\par\noindent
1770 \marginnote{
1771 \envcodestyle
1772 \hfill\llap{\PrintEnvName{\begin}{#2}}\mbox{}\\
1773 \IfNoValueTF{#1}{}{\hfill\llap{\MacroArgs#1}\mbox{}\\}
1774 \hfill\llap{\PrintEnvName{\end}{#2}}\mbox{}\\
1775 }
1776 \begingroup
1777 \def\after@Macro@args{\endDescribeEnv}
1778 \y@bgroup
1779 \ydoc@macrocatcodes
1780 \macroargsstyle
1781 \read@Macro@arg
1782 }
1783 \DeclareDocumentCommand\endDescribeEnv{}{
1784 \endgroup
1785 \smallskip\par\noindent
1786 }
1787 % \end{macrocode}
1788 % \end{macro}
1789 %
1790 % Then we add a few of our own. For instance, we add macros to
1791 % typeset descriptions of options. We also undefine the \cs{optpar}
1792 % macro defined by \pkg{ydoc}, since we supersede it with \cs{Option}.
1793 % \begin{macrocode}
1794 \let\optpar\relax
1795 % \end{macrocode}
1796 % \begin{macro}{\Options}[1]
1797 % {A comma-separated list of options}
1798 % \begin{macrocode}
1799 \DeclareDocumentCommand\Options{m}{
1800 \clist_set:Nn\l_tmpa_clist{#1}
1801 \marginnote{
1802 \clist_map_inline:Nn\l_tmpa_clist{
1803 \index@option*{####1}
1804 \hfill
1805 \llap{\textcolor{opt}{\opt{####1}}}
1806 \mbox{}\\
1807 }
1808 }
1809 \nobreak
1810 }
1811 % \end{macrocode}
1812 % \end{macro}
1813 % \begin{macro}{\Option}[1]
1814 % {And option}
1815 % \begin{macrocode}
1816 \DeclareDocumentCommand\Option{m}{
1817 \Options{#1}
1818 }
1819 % \end{macrocode}
1820 % \end{macro}
1821 % \begin{macro*}{\skdoc@WithValues@peek}
1822 % \changes{1.2a}{Add \cs{ignorespaces} to fix spacing bug}
1823 % \begin{macrocode}
1824 \def\skdoc@WithValues@peek{
1825 \ifx\@let@token\AndDefault\else\par\noindent\nobreak\ignorespaces\fi
1826 }
1827 % \end{macrocode}
1828 % \end{macro*}
1829 % \begin{macro}{\WithValues}[1]
1830 % {Values of a key-value option}
1831 % The \cs{WithValues} macro peeks ahead to see if there's an
1832 % \cs{AndDefault} macro further down. It typesets the values of
1833 % a key-vaue option
1834 % \begin{macrocode}
1835 \DeclareDocumentCommand\WithValues{m}{
1836 \noindent\makebox[\linewidth][l]{\texttt{#1}}
1837 \futurelet\@let@token\skdoc@WithValues@peek
1838 }
1839 % \end{macrocode}
1840 % \end{macro}
1841 % \begin{macro}{\AndDefault}[1]
1842 % {The value of a key-value option}
1843 % Typesets the default value of a key-value option. To the far
1844 % right of the line.
1845 % \changes{1.2a}{Add \cs{ignorespaces} to fix spacing bug}
1846 % \begin{macrocode}
1847 \DeclareDocumentCommand\AndDefault{m}{
1848 \llap{\textcolor{gray}{\texttt{(#1)}}}\par\noindent\nobreak\ignorespaces
1849 }
1850 % \end{macrocode}
1851 % \end{macro}
1852 %
1853 % Similar macros are provided for \hologo{BibTeX} entries.
1854 % \begin{macro}{\BibEntry}[1]
1855 % {The name of the \hologo{BibTeX} entry}
1856 % \begin{macrocode}
1857 \DeclareDocumentCommand\BibEntry{m}{
1858 \marginnote{
1859 \index@bibentry*{#1}
1860 \hfill\llap{\textcolor{macrodesc}{\bib{#1}}}
1861 }
1862 \nobreak
1863 }
1864 % \end{macrocode}
1865 % \end{macro}
1866 % \begin{macro}{\WithFields}[2]
1867 % {Optional fields}
1868 % {Mandatory fields}
1869 % \changes{1.2a}{Add \cs{ignorespaces} to fix spacing bug}
1870 % \begin{macrocode}
1871 \DeclareDocumentCommand\WithFields{om}{
1872 \noindent\makebox[\linewidth]{
1873 \texttt{#2}
1874 \IfNoValueTF{#1}{}{
1875 \textcolor{gray}{\texttt{,#2}}
1876 }
1877 }
1878 \par\noindent\nobreak\ignorespaces
1879 }
1880 % \end{macrocode}
1881 % \end{macro}
1882 %
1883 % A macro for describing themes is supplied.
1884 % \begin{macro}{\Theme}[1]
1885 % {The theme name}
1886 % \changes{1.2a}{Add \cs{ignorespaces} to fix spacing bug}
1887 % \begin{macrocode}
1888 \DeclareDocumentCommand\Theme{m}{
1889 \marginnote{
1890 \index@theme*{#1}
1891 \hfill\llap{\textcolor{macrodesc}{\thm{#1}}}
1892 }
1893 \nobreak\par\noindent\nobreak\ignorespaces
1894 }
1895 % \end{macrocode}
1896 % \end{macro}
1897 %
1898 % And finally, a macro for describing files is provided.
1899 % \begin{macro}{\DescribeFile}[1]
1900 % {The filename}
1901 % \changes{1.2a}{Add \cs{ignorespaces} to fix spacing bug}
1902 % \begin{macrocode}
1903 \DeclareDocumentCommand\DescribeFile{m}{
1904 \marginnote{
1905 \index@file*{#1}
1906 \hfill\llap{\textcolor{macrodesc}{\file{#1}}}
1907 }
1908 \nobreak\par\noindent\nobreak\ignorespaces
1909 }
1910 % \end{macrocode}
1911 % \end{macro}
1912 %
1913 % Lastly, we define an envionment for showing examples. It's quite
1914 % complex, utilizing (and kind of hacking) \cs{skdoc@verbatim} and
1915 % typesetting the content using \pkg{l3coffins}.
1916 %
1917 % First, three dimensions used in constructing the side-by-side boxes.
1918 % \begin{macro}{\c__skdoc_example_margin_dim}
1919 % This dimension, set to half of \cs{baselineskip}, dictates the margin
1920 % between the content of the coffins and the dividing ruler.
1921 % \begin{macrocode}
1922 \dim_const:Nn\c__skdoc_example_margin_dim{0.5\baselineskip}
1923 % \end{macrocode}
1924 % \end{macro}
1925 % \begin{macro}{\c__skdoc_example_linewidth_dim}
1926 % This dimension sets the width of the dividing ruler.
1927 % \begin{macrocode}
1928 \dim_const:Nn\c__skdoc_example_linewidth_dim{1pt}
1929 % \end{macrocode}
1930 % \end{macro}
1931 %
1932 % Next, three coffins used by the \env{example} environment are defined.
1933 % One for code, one for the divider and one for the result.
1934 % \begin{macro}{\l__skdoc_example_code_coffin}
1935 % \begin{macrocode}
1936 \coffin_new:N\l__skdoc_example_code_coffin
1937 % \end{macrocode}
1938 % \end{macro}
1939 % \begin{macro}{\l__skdoc_example_divider_coffin}
1940 % \begin{macrocode}
1941 \coffin_new:N\l__skdoc_example_divider_coffin
1942 % \end{macrocode}
1943 % \end{macro}
1944 % \begin{macro}{\l__skdoc_example_result_coffin}
1945 % \begin{macrocode}
1946 \coffin_new:N\l__skdoc_example_result_coffin
1947 % \end{macrocode}
1948 % \end{macro}
1949 %
1950 % Finally, we can define the actual \env{example} environment!
1951 % \begin{environment}{example}
1952 % \changes{1.2}{Print example code next to the result}
1953 % \begin{macrocode}
1954 \DeclareDocumentEnvironment{example}{}{
1955 % \end{macrocode}
1956 % The environment starts by priting a small header indicating that
1957 % the content is in fact an example. It also sets a couple of counters
1958 % and IO variables to trick \cs{skdoc@verbatim} into thinking that it's
1959 % actually writing to a defined output file.
1960 % \begin{macrocode}
1961 \bool_gset_true:N\g__skdoc_in_example_bool%
1962 \minisec{Example:}%
1963 \int_zero_new:c{skdoc@output@skdoc@private@example@line}%
1964 \tl_if_exist:cTF{skdoc@output@skdoc@private@example}{
1965 \tl_clear:c{skdoc@output@skdoc@private@example}
1966 }{
1967 \tl_new:c{skdoc@output@skdoc@private@example}
1968 }
1969 % \end{macrocode}
1970 % Next, we calculate the coffin width. We do this locally, not in a
1971 % global constant, since we may be somewhere where \cs{textwidth}
1972 % might have changed.
1973 % \begin{macrocode}
1974 \dim_set:Nn\l_tmpa_dim{ \textwidth/2
1975 -\c__skdoc_example_margin_dim
1976 -\c__skdoc_example_linewidth_dim/2}
1977 % \end{macrocode}
1978 % The code coffin is now filled, after clearing it. It'll get filled
1979 % with the contents of the verbatim environment, typeset like other
1980 % \env{MacroCode} environments in the document (\emph{i.e.} \pkg{minted2}
1981 % if possible).
1982 % \begin{macrocode}
1983 \coffin_clear:N\l__skdoc_example_code_coffin
1984 \vcoffin_set:Nnw\l__skdoc_example_code_coffin{\l_tmpa_dim}
1985 \skdoc@verbatim{skdoc@private@example}
1986 }{
1987 \endskdoc@verbatim
1988 \vcoffin_set_end:
1989 % \end{macrocode}
1990 % Next comes the example result coffin. After clearing it, it gets
1991 % filled by writing the contents of the token list defined previously
1992 % (the one \cs{skdoc@verbatim} is tricked into writing to) to a
1993 % temporary file, then reading that temporary file using \cs{input}.
1994 % We leave the temporary file behind; cleaning up requires \cs{write18}.
1995 % Also: Meh.
1996 % \begin{macrocode}
1997 \coffin_clear:N\l__skdoc_example_result_coffin
1998 \vcoffin_set:Nnw\l__skdoc_example_result_coffin{\l_tmpa_dim}
1999 \iow_open:Nn\skdoc@output{\jobname.skdoc.tmp}
2000 \iow_now:Nx\skdoc@output{\tl_to_str:c{skdoc@output@skdoc@private@example}}
2001 \iow_close:N\skdoc@output
2002 \input{\jobname.skdoc.tmp}
2003 \vcoffin_set_end:
2004 % \end{macrocode}
2005 % The divider coffin, being dependent on the height of the two previous
2006 % coffins, is also reset every time. After clearing, we calculate the
2007 % maximum height of the two coffins, and add two margins (top and
2008 % bottom). This value is used to typeset a (gray) rule of the width
2009 % specified earlier (by \cs{c__skdoc_example_linewidth_dim}). Margins
2010 % are also added to either side of this rule.
2011 % \begin{macrocode}
2012 \coffin_clear:N\l__skdoc_example_divider_coffin
2013 \dim_set:Nn\l_tmpa_dim{
2014 \dim_max:nn{\coffin_ht:N\l__skdoc_example_code_coffin}%
2015 {\coffin_ht:N\l__skdoc_example_result_coffin}
2016 + 2\c__skdoc_example_margin_dim}
2017 \hcoffin_set:Nn\l__skdoc_example_divider_coffin{
2018 \color{lightgray}
2019 \hspace*{\c__skdoc_example_margin_dim}
2020 \rule{\c__skdoc_example_linewidth_dim}{\l_tmpa_dim}
2021 \hspace*{\c__skdoc_example_margin_dim}
2022 }
2023 % \end{macrocode}
2024 % It's finally time to join and typeset the coffins. We clear a temporary
2025 % coffin, copy the divider into it, and proceed to attach the example
2026 % result coffin to the left and the code to the right (vertical centers
2027 % touching, so that they are \enquote{centered} vertically). The
2028 % temporary coffin is then typeset.
2029 % \begin{macrocode}
2030 \coffin_clear:N\l_tmpa_coffin
2031 \coffin_set_eq:NN\l_tmpa_coffin\l__skdoc_example_divider_coffin
2032 \coffin_join:NnnNnnnn\l_tmpa_coffin{l}{vc}%
2033 \l__skdoc_example_result_coffin{r}{vc}%
2034 {0pt}{0pt}
2035 \coffin_join:NnnNnnnn\l_tmpa_coffin{r}{vc}%
2036 \l__skdoc_example_code_coffin{l}{vc}%
2037 {0pt}{0pt}
2038 \coffin_typeset:Nnnnn\l_tmpa_coffin{T}{l}{0pt}{0pt}
2039 \bool_gset_false:N\g__skdoc_in_example_bool%
2040 \vspace*{\c__skdoc_example_margin_dim}\par
2041 }
2042 % \end{macrocode}
2043 % \end{environment}
2044 %
2045 % \subsubsection{Implementation environment}
2046 % We define environments that encase the implementation of macros,
2047 % environments, options, \hologo{BibTeX} entry types and themes.
2048 % Watch out---there's a lot of duplicate code here.
2049 % \begin{environment}{macro}[3]
2050 % {True if this is the starred variant}
2051 % {Name of the macro being implemented}
2052 % {If given, the number of arguments that
2053 % \cs{macro@impl@args} will read}
2054 % \begin{macrocode}
2055 \DeclareDocumentEnvironment{macro}{smo}{%
2056 \IfBooleanTF{#1}{}{\@bsphack}
2057 \index@macro!{\expandafter\@gobble\string#2}
2058 \@macroname{#2}%
2059 \IfBooleanTF{#1}{
2060 \IfNoValueTF{#3}{}{
2061 \int_compare:nNnTF{#3}>{0}{
2062 \use:c{use_none:\prg_replicate:nn{#3}{n}}
2063 }{}
2064 }
2065 }{
2066 \PrintMacroImpl{#2}
2067 \IfNoValueTF{#3}{
2068 \macro@impl@argline@noarg{(no~arguments)}
2069 }{\macro@impl@args[#3]}
2070 }%
2071 }{
2072 \let\skdoc@macroname@key\@empty
2073 \IfBooleanTF{#1}{}{\par\@esphack}
2074 }
2075 % \end{macrocode}
2076 % \end{environment}
2077 % \begin{environment}{environment}[3]
2078 % {True if this is the starred variant}
2079 % {Name of the environment being implemented}
2080 % {If given, the number of arguments that
2081 % \cs{macro@impl@args} will read}
2082 % \begin{macrocode}
2083 \DeclareDocumentEnvironment{environment}{smo}{%
2084 \IfBooleanTF{#1}{}{\@bsphack}
2085 \index@environment!{#2}
2086 \@environmentname{#2}%
2087 \IfBooleanTF{#1}{
2088 \IfNoValueTF{#3}{}{
2089 \int_compare:nNnTF{#3}>{0}{
2090 \use:c{use_none:\prg_replicate:nn{#3}{n}}
2091 }{}
2092 }
2093 }{
2094 \PrintEnvImplName{#2}
2095 \IfNoValueTF{#3}{
2096 \macro@impl@argline@noarg{(no~arguments)}
2097 }{\macro@impl@args[#3]}
2098 }%
2099 }{
2100 \let\skdoc@macroname@key\@empty
2101 \IfBooleanTF{#1}{}{\par\@esphack}
2102 }
2103 % \end{macrocode}
2104 % \end{environment}
2105 % \begin{environment}{option}[3]
2106 % {True if this is the starred variant}
2107 % {Name of the option being implemented}
2108 % {Values this key-value option can take}
2109 % \begin{macrocode}
2110 \DeclareDocumentEnvironment{option}{smg}{%
2111 \IfBooleanTF{#1}{}{\@bsphack}
2112 \index@option!{#2}
2113 \@optionname{#2}%
2114 \IfBooleanTF{#1}{}{
2115 \vspace{\baselineskip}
2116 \PrintEnvImplName{#2}
2117 \IfNoValueTF{#3}{
2118 \macro@impl@argline@noarg{(option)}
2119 }{
2120 \macro@impl@argline@noarg{
2121 Option~with~values~\texttt{\textcolor{gray}{#3}}
2122 }
2123 }
2124 }%
2125 }{
2126 \let\skdoc@macroname@key\@empty
2127 \IfBooleanTF{#1}{}{\par\@esphack}
2128 }
2129 % \end{macrocode}
2130 % \end{environment}
2131 % \begin{environment}{bibentry}[2]
2132 % {True if this is the starred variant}
2133 % {Name of the \hologo{BibTeX} entry type being implemented}
2134 % \begin{macrocode}
2135 \DeclareDocumentEnvironment{bibentry}{sm}{%
2136 \IfBooleanTF{#1}{}{\@bsphack}
2137 \index@bibentry!{\expandafter\@gobble\string#2}
2138 \@bibentryname{#2}%
2139 \IfBooleanTF{#1}{}{
2140 \vspace{\baselineskip}
2141 \PrintEnvImplName{#2}
2142 \macro@impl@argline@noarg{(\hologoRobust{BibTeX}~entry~type)}
2143 }%
2144 }{
2145 \let\skdoc@macroname@key\@empty
2146 \IfBooleanTF{#1}{}{\par\@esphack}
2147 }
2148 % \end{macrocode}
2149 % \end{environment}
2150 % \begin{environment}{theme}[2]
2151 % {True if this is the starred variant}
2152 % {Name of the theme being implemented}
2153 % \begin{macrocode}
2154 \DeclareDocumentEnvironment{theme}{sm}{%
2155 \IfBooleanTF{#1}{}{\@bsphack}
2156 \index@theme!{#2}
2157 \@themename{#2}%
2158 \IfBooleanTF{#1}{}{
2159 \vspace{\baselineskip}
2160 \PrintEnvImplName{#2}
2161 \macro@impl@argline@noarg{(theme)}
2162 }%
2163 }{
2164 \let\skdoc@macroname@key\@empty
2165 \IfBooleanTF{#1}{}{\par\@esphack}
2166 }
2167 % \end{macrocode}
2168 % \end{environment}
2169 % We also provide starred variants of the environments, which will
2170 % add the implementation to the index but not print anything.
2171 % \begin{environment}{macro*}[2]
2172 % {Name of the macro being implemented}
2173 % {If given, the number of arguments that
2174 % \cs{macro@impl@args} will read}
2175 % \begin{macrocode}
2176 \DeclareDocumentEnvironment{macro*}{mo}%
2177 {\begin{macro}*{#1}[#2]}{\end{macro}}
2178 % \end{macrocode}
2179 % \end{environment}
2180 % \begin{environment}{environment*}[2]
2181 % {Name of the environment being implemented}
2182 % {If given, the number of arguments that
2183 % \cs{macro@impl@args} will read}
2184 % \begin{macrocode}
2185 \DeclareDocumentEnvironment{environment*}{mo}%
2186 {\begin{environment}*{#1}[#2]}{\end{environment}}
2187 % \end{macrocode}
2188 % \end{environment}
2189 % \begin{environment}{option*}[2]
2190 % {Name of the option being implemented}
2191 % {Values this key-value option can take}
2192 % \begin{macrocode}
2193 \DeclareDocumentEnvironment{option*}{mg}%
2194 {\begin{option}*{#1}{#2}}{\end{option}}
2195 % \end{macrocode}
2196 % \end{environment}
2197 % \begin{environment}{bibentry*}[1]
2198 % {Name of the \hologo{BibTeX} entry type being implemented}
2199 % \begin{macrocode}
2200 \DeclareDocumentEnvironment{bibentry*}{m}%
2201 {\begin{bibentry}*{#1}}{\end{bibentry}}
2202 % \end{macrocode}
2203 % \end{environment}
2204 % \begin{environment}{theme*}[1]
2205 % {Name of the theme being implemented}
2206 % \begin{macrocode}
2207 \DeclareDocumentEnvironment{theme*}{m}%
2208 {\begin{theme}*{#1}}{\end{theme}}
2209 % \end{macrocode}
2210 % \end{environment}
2211 % And finally, we redefine some of the underlying \pkg{ydoc} macros
2212 % to behave the way we want them to.
2213 % For instance, we redefine the commands that print environment and
2214 % macro implementation names so that they typeset the name i a
2215 % \cs{marginnote} rather than in an \cs{fbox}.
2216 % \begin{macro}{\PrintEnvImplName}[1]
2217 % {The environment name to be printed}
2218 % \changes{1.3}{Fixed incorrect spacing}
2219 % \begin{macrocode}
2220 \def\PrintEnvImplName#1{%
2221 \par\leavevmode\null
2222 \hbox{%
2223 \marginnote{\llap{\implstyle{#1\strut}}}%
2224 }
2225 \null
2226 }
2227 % \end{macrocode}
2228 % \end{macro}
2229 % \begin{macro}{\PrintMacroImpl}[1]
2230 % {The macro name to be printed}
2231 % \begin{macrocode}
2232 \def\PrintMacroImpl#1{%
2233 \par
2234 \hbox{%
2235 \edef\name{\expandafter\@gobble\string#1}%
2236 \global\@namedef{href@impl@\name}{}%
2237 \immediate\write\@mainaux{%
2238 \global\noexpand\@namedef{href@impl@\name}{}%
2239 }%
2240 \raisebox{4ex}[4ex]{\hypertarget{impl:\name}{}}%
2241 \@ifundefined{href@desc@\name}{}{\hyperlink{desc:\name}}%
2242 \marginnote{\llap{\PrintMacroImplName{#1}}}%
2243 }%
2244 \par
2245 }
2246 % \end{macrocode}
2247 % \end{macro}
2248 % We also redefine the utility macros belonging to \cs{macro@impl@arg}.
2249 % \begin{macro*}{\macro@impl@argline}[2]
2250 % {The argument number}
2251 % {Description of the argument}
2252 % \begin{macrocode}
2253 \def\macro@impl@argline#1#2{%
2254 \par\noindent{\texttt{\##1}:~#2\strut}%
2255 }
2256 % \end{macrocode}
2257 % \end{macro*}
2258 % \begin{macro*}{\macro@impl@args}[1]
2259 % {The number of arguments to read}
2260 % \begin{macrocode}
2261 \def\macro@impl@args[#1]{%
2262 \vspace*{-\baselineskip}
2263 \begingroup
2264 \let\macro@impl@argcnt\@tempcnta
2265 \let\macro@impl@curarg\@tempcntb
2266 \macro@impl@argcnt=#1\relax
2267 \macro@impl@curarg=0\relax
2268 \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
2269 \expandafter\macro@impl@arg
2270 \else
2271 \expandafter\macro@impl@endargs
2272 \fi
2273 }
2274 % \end{macrocode}
2275 % \end{macro*}
2276 % \begin{macro*}{\macro@impl@arg@noopt}
2277 % \begin{macrocode}
2278 \def\macro@impl@arg@noopt#1{%
2279 \macro@impl@argline{\the\macro@impl@curarg}{#1}
2280 \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
2281 \expandafter\macro@impl@arg
2282 \else
2283 \expandafter\macro@impl@endargs
2284 \fi
2285 }
2286 % \end{macrocode}
2287 % \end{macro*}
2288 % \begin{macro*}{\macro@impl@arg@opt}
2289 % \begin{macrocode}
2290 \def\macro@impl@arg@opt#1[#2]{%
2291 \macro@impl@argline{\the\macro@impl@curarg}
2292 {#1\hfill\AndDefault{#1}\vspace{-\baselineskip}}
2293 \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
2294 \expandafter\macro@impl@arg
2295 \else
2296 \expandafter\macro@impl@endargs
2297 \fi
2298 }
2299 % \end{macrocode}
2300 % \end{macro*}
2301 % \begin{macro*}{\macro@impl@arg}
2302 % \begin{macrocode}
2303 \def\macro@impl@arg#1{%
2304 \advance\macro@impl@curarg by\@ne\relax
2305 \@ifnextchar[%]
2306 {\macro@impl@arg@opt{#1}}%
2307 {\macro@impl@arg@noopt{#1}}%
2308 }
2309 % \end{macrocode}
2310 % \end{macro*}
2311 % \begin{macro*}{\macro@impl@endargs}
2312 % \changes{1.3b}{Conditionally don't add space if another environment follows}
2313 % \begin{macrocode}
2314 \def\macro@impl@endargs{
2315 \endgroup
2316 \peek_meaning_ignore_spaces:NTF\begin
2317 {
2318 \vspace{-\baselineskip}
2319 \bool_gset_true:N\g__skdoc_negative_space_bool
2320 \PushPreHook{par}{
2321 \bool_gset_false:N\g__skdoc_negative_space_bool
2322 \PopPreHook{par}
2323 }
2324 }
2325 {\par\medskip}%
2326 }
2327 % \end{macrocode}
2328 % \end{macro*}
2329 % \begin{macro*}{\macro@impl@argline@noarg}[1]
2330 % {The line to print instead of an argument line}
2331 % \changes{1.3b}{Conditionally don't add space if another environment follows}
2332 % This last macro is a replacement used when there are no arguments
2333 % or if the implementation is an option or something like that. It
2334 % behaves pretty much like \cs{macro@impl@args}, but with only one
2335 % argument to read.
2336 % \begin{macrocode}
2337 \def\macro@impl@argline@noarg#1{%
2338 \vspace*{-\baselineskip}
2339 \par\noindent{#1\strut}
2340 \peek_meaning_ignore_spaces:NTF\begin
2341 {
2342 \vspace{-\baselineskip}
2343 \bool_gset_true:N\g__skdoc_negative_space_bool
2344 \PushPreHook{par}{
2345 \bool_gset_false:N\g__skdoc_negative_space_bool
2346 \PopPreHook{par}
2347 }
2348 }
2349 {\par\medskip}%
2350 }
2351 % \end{macrocode}
2352 % \end{macro*}
2353 %
2354 % \subsection{The index}
2355 % \begin{macro*}{\__skdoc_if_do_index:T}
2356 % \begin{macro*}{\__skdoc_if_do_index:F}
2357 % \begin{macro*}{\__skdoc_if_do_index:TF}
2358 % \begin{macro}{\__skdoc_if_do_index_p:}
2359 % \begin{macrocode}
2360 \prg_new_conditional:Nnn\__skdoc_if_do_index:{p,T,F,TF}{
2361 \bool_if:nTF{
2362 \__skdoc_if_print_code_p: &&
2363 !\g__skdoc_no_index_bool
2364 }{
2365 \prg_return_true:
2366 }{
2367 \prg_return_false:
2368 }
2369 }
2370 % \end{macrocode}
2371 % \end{macro}
2372 % \end{macro*}
2373 % \end{macro*}
2374 % \end{macro*}
2375 % The index is based on \pkg{glossaries}, and as such the whole
2376 % process of adding entries to the index is reduced to adding
2377 % glossary entries. This is done through two wrapper macros around
2378 % the \cs{newglossaryentry} macro.
2379 % \begin{macro}{\@index@}[1]
2380 % {The key of the index entry}
2381 % {The text of the index entry}
2382 % What \cs{@index@} does is to decide wether we are hiding the
2383 % implementation part of the documentation (discussed later), and
2384 % wether we are in the actual implementation or not. If we are in
2385 % the implementation and aren't printing it, we shouldn't add an
2386 % index entry.
2387 % \begin{macrocode}
2388 \DeclareDocumentCommand\@index@{mm}{
2389 \__skdoc_if_do_index:T{
2390 \@index@@{#1}{#2}
2391 }
2392 }
2393 % \end{macrocode}
2394 % \end{macro}
2395 % \begin{macro}{\@index@@}[2]
2396 % {The key of the index entry}
2397 % {The text of the index entry}
2398 % This macro does the actual adding to the glossary.
2399 % \begin{macrocode}
2400 \DeclareDocumentCommand\@index@@{mm}{
2401 \newglossaryentry{index-#1}{
2402 type=index,
2403 name={#2},
2404 description={\nopostdesc},
2405 sort={#1}
2406 }
2407 }
2408 % \end{macrocode}
2409 % \end{macro}
2410 %
2411 % \subsubsection{Adding index entries}
2412 % These macros add an index entry with different contents depending
2413 % on the thing (macro, environment, etc.) that is being indexed. They
2414 % all have non-starred variants which are used by the referring
2415 % macros (\cs{cs} \emph{et. al}), and starred variants used by the
2416 % description macros (the star affects the style of the page number).
2417 % Each environment first test wether the given entry key exists, and
2418 % defines a new entry if it doesn't. Then, a usage of the entry is
2419 % recorded.
2420 % There is also a exclamation variant that is used by the implementation
2421 % environments, that typesets a normal use of the entity.
2422 %
2423 % Note the duplicate use of \cs{ifglsentryexists} --- this is needed
2424 % since \cs{@index@} doesn't always add the entity to the index
2425 % \emph{i.e.} nothing in the implementation is added when we're hiding
2426 % the implementation.
2427 % \begin{macro}{\index@macro}[3]
2428 % {True if this is the starred variant}
2429 % {True if this is the exclamation variant}
2430 % {The name of the macro being indexed, without backslash}
2431 % \begin{macrocode}
2432 \DeclareDocumentCommand\index@macro{st!m}{
2433 \def\skdoc@temp{#3-macro}
2434 \ifglsentryexists{index-\skdoc@temp}{}{
2435 \@index@{#3-macro}{\cs*{#3}}
2436 }
2437 \__skdoc_if_do_index:T{
2438 \IfBooleanTF{#2}{
2439 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2440 }{
2441 \IfBooleanTF{#1}{
2442 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2443 }{
2444 \glsadd[types=index]{index-\skdoc@temp}
2445 }
2446 }
2447 }
2448 }
2449 % \end{macrocode}
2450 % \end{macro}
2451 % \begin{macro}{\index@environment}[3]
2452 % {True if this is the starred variant}
2453 % {True if this is the exclamation variant}
2454 % {The name of the environment being indexed}
2455 % \begin{macrocode}
2456 \DeclareDocumentCommand\index@environment{st!m}{
2457 \def\skdoc@temp{\string#3-env}
2458 \ifglsentryexists{index-\skdoc@temp}{}{
2459 \@index@{\string#3-env}{\env*{\string#3}~(environment)}
2460 }
2461 \__skdoc_if_do_index:T{
2462 \IfBooleanTF{#2}{
2463 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2464 }{
2465 \IfBooleanTF{#1}{
2466 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2467 }{
2468 \glsadd[types=index]{index-\skdoc@temp}
2469 }
2470 }
2471 }
2472 }
2473 % \end{macrocode}
2474 % \end{macro}
2475 % \begin{macro}{\index@option}[3]
2476 % {True if this is the starred variant}
2477 % {True if this is the exclamation variant}
2478 % {The name of the option being indexed}
2479 % \begin{macrocode}
2480 \DeclareDocumentCommand\index@option{st!m}{
2481 \def\skdoc@temp{\string#3-opt}
2482 \ifglsentryexists{index-\skdoc@temp}{}{
2483 \@index@{\string#3-opt}{\opt*{\string#3}~(option)}
2484 }
2485 \__skdoc_if_do_index:T{
2486 \IfBooleanTF{#2}{
2487 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2488 }{
2489 \IfBooleanTF{#1}{
2490 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2491 }{
2492 \glsadd[types=index]{index-\skdoc@temp}
2493 }
2494 }
2495 }
2496 }
2497 % \end{macrocode}
2498 % \end{macro}
2499 % \begin{macro}{\index@bibentry}[3]
2500 % {True if this is the starred variant}
2501 % {True if this is the exclamation variant}
2502 % {The name of the \hologo{BibTeX} entry type
2503 % being indexed, without initial \texttt{@} sign}
2504 % \begin{macrocode}
2505 \DeclareDocumentCommand\index@bibentry{st!m}{
2506 \def\skdoc@temp{#3-bib}
2507 \ifglsentryexists{index-\skdoc@temp}{}{
2508 \@index@{#3-bib}{\bib*{#3}~(\hologoRobust{BibTeX}~entry~type)}
2509 }
2510 \__skdoc_if_do_index:T{
2511 \IfBooleanTF{#2}{
2512 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2513 }{
2514 \IfBooleanTF{#1}{
2515 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2516 }{
2517 \glsadd[types=index]{index-\skdoc@temp}
2518 }
2519 }
2520 }
2521 }
2522 % \end{macrocode}
2523 % \end{macro}
2524 % \begin{macro}{\index@theme}[3]
2525 % {True if this is the starred variant}
2526 % {True if this is the exclamation variant}
2527 % {The name of the theme being indexed}
2528 % \begin{macrocode}
2529 \DeclareDocumentCommand\index@theme{st!m}{
2530 \def\skdoc@temp{\string#3-theme}
2531 \ifglsentryexists{index-\skdoc@temp}{}{
2532 \@index@{\string#3-theme}{\thm*{\string#3}~(theme)}
2533 }
2534 \__skdoc_if_do_index:T{
2535 \IfBooleanTF{#2}{
2536 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2537 }{
2538 \IfBooleanTF{#1}{
2539 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2540 }{
2541 \glsadd[types=index]{index-\skdoc@temp}
2542 }
2543 }
2544 }
2545 }
2546 % \end{macrocode}
2547 % \end{macro}
2548 % \begin{macro}{\index@package}[3]
2549 % {True if this is the starred variant}
2550 % {True if this is the exclamation variant}
2551 % {The name of the package being indexed}
2552 % \begin{macrocode}
2553 \DeclareDocumentCommand\index@package{st!m}{
2554 \def\skdoc@temp{\string#3-pkg}
2555 \ifglsentryexists{index-\skdoc@temp}{}{
2556 \@index@{\string#3-pkg}{\pkg*{\string#3}~(package)}
2557 }
2558 \__skdoc_if_do_index:T{
2559 \IfBooleanTF{#2}{
2560 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2561 }{
2562 \IfBooleanTF{#1}{
2563 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2564 }{
2565 \glsadd[types=index]{index-\skdoc@temp}
2566 }
2567 }
2568 }
2569 }
2570 % \end{macrocode}
2571 % \end{macro}
2572 % \begin{macro}{\index@file}[3]
2573 % {True if this is the starred variant}
2574 % {True if this is the exclamation variant}
2575 % {The name of the file being indexed}
2576 % \begin{macrocode}
2577 \DeclareDocumentCommand\index@file{st!m}{
2578 \def\skdoc@temp{\string#3-file}
2579 \ifglsentryexists{index-\skdoc@temp}{}{
2580 \@index@{\string#3-file}{\file*{\string#3}~(file)}
2581 }
2582 \__skdoc_if_do_index:T{
2583 \IfBooleanTF{#2}{
2584 \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
2585 }{
2586 \IfBooleanTF{#1}{
2587 \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
2588 }{
2589 \glsadd[types=index]{index-\skdoc@temp}
2590 }
2591 }
2592 }
2593 }
2594 % \end{macrocode}
2595 % \end{macro}
2596 %
2597 % Notice the references to \cs{hyperul}? We need to define that as
2598 % well. It's simple enough. Note that \cs{GlsAddXdyAttribute} isn't
2599 % called until later.
2600 % \begin{macro}{\hyperul}[1]
2601 % {Word to underline and link}
2602 % \begin{macrocode}
2603 \ProvideDocumentCommand\hyperul{m}{
2604 \underline{\hyperup{#1}}
2605 }
2606 % \end{macrocode}
2607 % \end{macro}
2608 %
2609 % \subsubsection{Displaying the index}
2610 % Displaying the index is very simple. We begin by defining
2611 % our own \pkg{glossaries} style.
2612 % \begin{macrocode}
2613 \newglossarystyle{docindex}{
2614 \setglossarystyle{indexgroup}
2615 \renewcommand*{\glspostdescription}{\unskip\leaders\hbox to 2.9mm{\hss.}\hfill\strut}
2616 \renewenvironment{theglossary}{
2617 \bool_gset_true:N\g__skdoc_no_index_bool
2618 \begin{multicols}{2}
2619 \setlength{\parindent}{0pt}
2620 \setlength{\parskip}{0pt plus 0.3pt}
2621 \let\item\@idxitem
2622 }{
2623 \end{multicols}
2624 \bool_gset_false:N\g__skdoc_no_index_bool
2625 }
2626 \renewcommand*{\glstreenamefmt}[1]{##1}
2627 \renewcommand*{\glsgroupheading}[1]{
2628 \IfStrEq{##1}{default}{
2629 \item{\descfont\glssymbolsgroupname}
2630 }{
2631 \item{\descfont\glsgetgrouptitle{##1}}
2632 }
2633 }
2634 \renewcommand*{\glsgroupskip}{
2635 \par\vspace{15\p@}\relax
2636 }
2637 }
2638 % \end{macrocode}
2639 % We follow that up by defining the actual glossay, and making sure
2640 % to run \cs{makeglossaries} when the preamble is complete.
2641 % \begin{macrocode}
2642 \newglossary{index}{ids}{ido}{Index}
2643 \AtBeginDocument{\makeglossaries}
2644 % \end{macrocode}
2645 % \begin{macro}{\PrintIndex}
2646 % \changes{1.2}{Fixed incorrect reference to boldfaced text}
2647 % Finally, we define a command \cs{PrintIndex} that prints the index.
2648 % Note the preamble that describes how the index page numbers work.
2649 % \begin{macrocode}
2650 \providecommand*\PrintIndex{%
2651 \begingroup
2652 \renewcommand*{\glossarypreamble}{
2653 Numbers~written~in~italic~refer~to~the~page~where~the~
2654 corresponding~entry~is~described;~numbers~underlined~refer~
2655 to~the~page~were~the~implementation~of~the~corresponding~
2656 entry~is~discussed.~Numbers~in~roman~refer~to~other~
2657 mentions~of~the~entry.\par
2658 }
2659 \printglossary[type=index,style=docindex]
2660 \endgroup
2661 }
2662 % \end{macrocode}
2663 % \end{macro}
2664 %
2665 % \subsubsection{Hacking \pkg{glossaries}}
2666 % The following redefinition of an internal \pkg{glossaries} macro,
2667 % provided by \textcite{Talbot13}, makes sure that the underlined
2668 % and italic page numbers in the index have precedence over the plain
2669 % nubmer format. In the event that a macro is described and implemented
2670 % on the same page, the description format (italic) is used.
2671 % \begin{macro}{\@gls@addpredefinedattributes}
2672 % \changes{1.4a}{Add Xdy attribute \texttt{@gobble}}
2673 % \begin{macrocode}
2674 \RenewDocumentCommand\@gls@addpredefinedattributes{}{
2675 \GlsAddXdyAttribute{hyperit}
2676 \GlsAddXdyAttribute{hyperul}
2677 \GlsAddXdyAttribute{glsnumberformat}
2678 \GlsAddXdyAttribute{@gobble}
2679 }
2680 % \end{macrocode}
2681 % \end{macro}
2682 %
2683 % \subsection{The changelog}
2684 % The changelog is implemented as a glossary using the
2685 % \pkg{glossaries} package. We begin by defining a name
2686 % for general changes, and commands that save the name of
2687 % the current macro, environment or similar for use by the
2688 % \cs{changes} macro.
2689 % \begin{macro}{\generalname}
2690 % \begin{macrocode}
2691 \DeclareDocumentCommand\generalname{}{General}
2692 % \end{macrocode}
2693 % \end{macro}
2694 % \begin{macro*}{\@macroname}[1]
2695 % {Name of the macro being described}
2696 % \begin{macrocode}
2697 \DeclareDocumentCommand\@macroname{m}{
2698 \def\skdoc@macroname@stylized{\cs*{\expandafter\@gobble\string#1}}
2699 \def\skdoc@macroname@key{macro-\expandafter\@gobble\string#1}
2700 }
2701 % \end{macrocode}
2702 % \end{macro*}
2703 % \begin{macro*}{\@environmentname}[1]
2704 % {Name of the environment being described}
2705 % \begin{macrocode}
2706 \DeclareDocumentCommand\@environmentname{m}{
2707 \def\skdoc@macroname@stylized{\env*{\string#1}}
2708 \def\skdoc@macroname@key{env-#1}
2709 }
2710 % \end{macrocode}
2711 % \end{macro*}
2712 % \begin{macro*}{\@optionname}[1]
2713 % {Name of the option being described}
2714 % \begin{macrocode}
2715 \DeclareDocumentCommand\@optionname{m}{
2716 \def\skdoc@macroname@stylized{\opt*{\string#1}}
2717 \def\skdoc@macroname@key{opt-#1}
2718 }
2719 % \end{macrocode}
2720 % \end{macro*}
2721 % \begin{macro*}{\@ebibentryname}[1]
2722 % {Name of the \hologo{BibTeX} entry being described}
2723 % \begin{macrocode}
2724 \DeclareDocumentCommand\@bibentryname{m}{
2725 \def\skdoc@macroname@stylized{\bib*{\expandafter\@gobble\string#1}}
2726 \def\skdoc@macroname@key{bibentry-\expandafter\@gobble\string#1}
2727 }
2728 % \end{macrocode}
2729 % \end{macro*}
2730 % \begin{macro*}{\@themename}[1]
2731 % {Name of the theme being described}
2732 % \begin{macrocode}
2733 \DeclareDocumentCommand\@themename{m}{
2734 \def\skdoc@macroname@stylized{\thm*{\string#1}}
2735 \def\skdoc@macroname@key{thm-#1}
2736 }
2737 % \end{macrocode}
2738 % \end{macro*}
2739 % Along with these we also define the variables they affect as empty.
2740 % \begin{macrocode}
2741 \def\skdoc@macroname@stylized{}
2742 \let\skdoc@macroname@key\@empty
2743 % \end{macrocode}
2744 %
2745 % \subsubsection{Adding changes}
2746 % Since the changelog is based on \pkg{glossaries}, adding changes
2747 % amounts to simply adding a glossary entry.
2748 % \begin{macro}{\changes}[2]
2749 % {The version in which the changes were made}
2750 % {A short description of the changes}
2751 % \changes{1.4a}{Unconditionally add version \enquote{parent} to
2752 % circumvent strange behaviour by \pkg{glossaries}. Also, gobble
2753 % page numbers for similar reasons}
2754 % \changes{1.5e}{Added an extra intermediate layer of macros
2755 % (\cs{@changes}) to force expansion of \cs{skdoc@macroname@stylized}}
2756 % \begin{macrocode}
2757 \DeclareDocumentCommand\changes{mm}{%
2758 \@bsphack
2759 \newglossaryentry{#1}{
2760 type=changes,
2761 name={v#1},
2762 description={\nopostdesc},
2763 nonumberlist=true
2764 }
2765 \ifx\skdoc@macroname@key\@empty
2766 \exp_args:Ne\@changes{\generalname}{!general}{#1}{#2}
2767 \else
2768 \exp_args:Nee\@changes{\skdoc@macroname@stylized}{\skdoc@macroname@key}{#1}{#2}
2769 \fi
2770 \@esphack
2771 }
2772 % \end{macrocode}
2773 % \end{macro}
2774 % \begin{macro}{\@changes}[2]
2775 % {A prefix prepended to the change log message}
2776 % {An internal key used for sorting changes within each version}
2777 % {The version in which the changes were made}
2778 % {A short description of the changes}
2779 % \begin{macrocode}
2780 \DeclareDocumentCommand\@changes{mmmm}{%
2781 \newglossaryentry{#3-#2}{
2782 type=changes,
2783 name={#1},
2784 description={#4},
2785 parent={#3},
2786 sort={#2},
2787 nonumberlist=true
2788 }
2789 \glsadd[types=changes,format=@gobble]{#3-#2}
2790 }
2791 % \end{macrocode}
2792 % \end{macro}
2793 %
2794 % \subsubsection{Displaying the changelog}
2795 % Displaying the changelog is equally simple. We begin by defining
2796 % our own \pkg{glossaries} style.
2797 % \begin{macrocode}
2798 \newglossarystyle{changelog}{
2799 \setglossarystyle{altlist}
2800 \renewenvironment{theglossary}{
2801 \bool_gset_true:N\g__skdoc_no_index_bool
2802 \begin{multicols}{2}\begin{description}
2803 }{
2804 \end{description}\end{multicols}
2805 \bool_gset_false:N\g__skdoc_no_index_bool
2806 }
2807 \renewcommand*{\glossentry}[2]{
2808 \par\vspace{5\p@}\relax
2809 \item[\glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}}]
2810 \mbox{}\par\nobreak\@afterheading
2811 }
2812 \renewcommand*{\subglossentry}[3]{
2813 \par\hspace*{\itemindent}
2814 \glssubentryitem{##2}\glstarget{##2}{\strut}%
2815 \glossentryname{##2}:~\glossentrydesc{##2}%
2816 \glspostdescription\space ##3
2817 }
2818 }
2819 % \end{macrocode}
2820 % We follow that up by defining the actual glossary, and making sure
2821 % to run \cs{makeglossaries} when the preamble is complete.
2822 % \begin{macrocode}
2823 \newglossary{changes}{gls}{glo}{Changes}
2824 \AtBeginDocument{\makeglossaries}
2825 % \end{macrocode}
2826 % \begin{macro}{\PrintChanges}
2827 % Finally, we define a command \cs{PrintChanges} that prints the
2828 % list of changes.
2829 % \begin{macrocode}
2830 \DeclareDocumentCommand\PrintChanges{}{%
2831 \begingroup
2832 \printglossary[type=changes,style=changelog]
2833 \endgroup
2834 }
2835 % \end{macrocode}
2836 % \end{macro}
2837 %
2838 % \subsection{Hiding the implementation}
2839 % We define commands to hide the implementation from the documentation.
2840 % Here, the ``implementation'' is understood to be everything between
2841 % the \cs{Implementation} and \cs{Finale} macros. What we do is disable
2842 % and/or reset page and section counters for the duration of the
2843 % implementation, and set a shipout hook that simply discards the pages
2844 % while we are in the implementation. A consquence of this is that we
2845 % must force a page break between what's before the implementation and
2846 % what's after, which might look horrible.
2847 %
2848 % We define a counter in which we save the page number we had when
2849 % the implementation started.
2850 % \begin{macrocode}
2851 \newcounter{skdoc@impl@page}
2852 % \end{macrocode}
2853 % Then we define the shipout hook. Fairly straight-forward.
2854 % \begin{macrocode}
2855 \AtBeginShipout{
2856 \__skdoc_if_print_code:F{\AtBeginShipoutDiscard}
2857 }
2858 % \end{macrocode}
2859 % \begin{macro}{\OnlyDescription}
2860 % The \cs{OnlyDescription} macro simply toggles the appropriate toggle.
2861 % \begin{macrocode}
2862 \DeclareDocumentCommand\OnlyDescription{}{
2863 \bool_gset_false:N\g__skdoc_with_implementation_bool
2864 }
2865 % \end{macrocode}
2866 % \end{macro}
2867 % \begin{macro}{\Implementation}
2868 % \changes{1.1a}{Hide references used in the hidden implementation}
2869 % The \cs{Implementation} macro defines all the sectioning commands
2870 % to be empty (saving the old ones), clears the page, saves the page
2871 % number and toggles the appropriate toggle. If \pkg{biblatex} is
2872 % loaded, we start a new \env{refsection} so that we can hide
2873 % references used in the implementation from the final bibliography.
2874 % \begin{macrocode}
2875 \DeclareDocumentCommand\Implementation{}{
2876 \bool_if:NF\g__skdoc_with_implementation_bool{
2877 \clearpage
2878 \bool_gset_true:N\g__skdoc_in_implementation_bool
2879 \let\skdoc@old@part\part
2880 \DeclareDocumentCommand\part{som}{}
2881 \let\skdoc@old@section\section
2882 \DeclareDocumentCommand\section{som}{}
2883 \let\skdoc@old@subsection\subsection
2884 \DeclareDocumentCommand\subsection{som}{}
2885 \let\skdoc@old@subsubsection\subsubsection
2886 \DeclareDocumentCommand\subsubsection{som}{}
2887 \let\skdoc@old@paragraph\paragraph
2888 \DeclareDocumentCommand\paragraph{som}{}
2889 \let\skdoc@old@subparagraph\subparagraph
2890 \DeclareDocumentCommand\subparagraph{som}{}
2891 \cs_if_exist:NTF\refsection{\refsection}{}
2892 \setcounter{skdoc@impl@page}{\value{page}}
2893 }
2894 }
2895 % \end{macrocode}
2896 % \end{macro}
2897 % \begin{macro}{\Finale}
2898 % \changes{1.1a}{Hide references used in the hidden implementation}
2899 % The \cs{Finale} macro basically just undoes what the
2900 % \cs{Implementation} macro did. If \pkg{biblatex} is used, the
2901 % \env{refsection} environment is ended and the (local) bibliography
2902 % is printed.
2903 % \begin{macrocode}
2904 \DeclareDocumentCommand\Finale{}{
2905 \bool_if:NF\g__skdoc_with_implementation_bool{
2906 \cs_if_exist:NTF\refsection{\printbibliography\endrefsection}{}
2907 \clearpage
2908 \bool_gset_false:N\g__skdoc_in_implementation_bool
2909 \let\part\skdoc@old@part
2910 \let\section\skdoc@old@section
2911 \let\subsection\skdoc@old@subsection
2912 \let\subsubsection\skdoc@old@subsubsection
2913 \let\paragraph\skdoc@old@paragraph
2914 \let\subparagraph\skdoc@old@subparagraph
2915 \setcounter{page}{\value{skdoc@impl@page}}
2916 }
2917 }
2918 % \end{macrocode}
2919 % \end{macro}
2920 %
2921 % \subsection{Document metadata}
2922 % \subsubsection{Setting metadata}
2923 % We override a bunch of the general titlepage macros and add a few
2924 % of our own. First, we initialize the underlying variables.
2925 % \begin{macrocode}
2926 \let\@ctan\@empty%
2927 \let\@repository\@empty%
2928 \let\@plainemail\@empty%
2929 \let\@email\@empty%
2930 \let\@version\@empty%
2931 % \end{macrocode}
2932 % Then, we define the actual macros.
2933 % \begin{macro}{\package}[2]
2934 % {A list of key-value options}
2935 % {The package name}
2936 % The \cs{package} macro sets the package name of the documentation.
2937 % The key-value options are \opt{vcs} and \opt{ctan}.
2938 % \begin{macrocode}
2939 \DeclareDocumentCommand\package{om}{%
2940 \keys_define:nn{skdoc@package}{%
2941 vcs .value_required:n = true,%
2942 vcs .code:n = \repository{##1},%
2943 ctan .code:n = \ctan{##1},%
2944 ctan .default:n = #2%
2945 }%
2946 \IfNoValueTF{#1}{}{\keys_set:nn{skdoc@package}{#1}}%
2947 \def\@package{#2}%
2948 \title{The~\textbf{\textsf{\@package}}~package}%
2949 }
2950 % \end{macrocode}
2951 % \end{macro}
2952 % \begin{macro}{\ctan}[1]
2953 % {The name of a package or bundle on CTAN}
2954 % \begin{macrocode}
2955 \DeclareDocumentCommand\ctan{m}{%
2956 \def\@ctan{\url{http://www.ctan.org/pkg/#1}}%
2957 }
2958 % \end{macrocode}
2959 % \end{macro}
2960 % \begin{macro}{\repository}[1]
2961 % {The URI of an online repository}
2962 % \begin{macrocode}
2963 \DeclareDocumentCommand\repository{m}{%
2964 \def\@repository{\url{#1}}%
2965 }
2966 % \end{macrocode}
2967 % \end{macro}
2968 % \begin{macro}{\email}[1]
2969 % {The email address of the author}
2970 % \begin{macrocode}
2971 \DeclareDocumentCommand\email{m}{%
2972 \def\@plainemail{#1}%
2973 \def\@email{\href{mailto:\@plainemail}{\@plainemail}}%
2974 }
2975 % \end{macrocode}
2976 % \end{macro}
2977 % \begin{macro}{\version}[1]
2978 % {The version of the package, with no leading ``v''}
2979 % \begin{macrocode}
2980 \DeclareDocumentCommand\version{m}{%
2981 \def\@version{#1}%
2982 }
2983 % \end{macrocode}
2984 % \end{macro}
2985 % Finally, we set the default package name to \cs{jobname}.
2986 % \begin{macrocode}
2987 \package{\jobname}
2988 % \end{macrocode}
2989 %
2990 % \subsubsection{Using metadata}
2991 % We define two macros that read useful metadata; \cs{theversion}
2992 % and \cs{thepackage}. These are used internally by \cs{maketitle}.
2993 % \begin{macro}{\theversion}
2994 % \begin{macrocode}
2995 \DeclareDocumentCommand\theversion{}{v\@version}
2996 % \end{macrocode}
2997 % \end{macro}
2998 % \begin{macro}{\thepackage}
2999 % \begin{macrocode}
3000 \DeclareDocumentCommand\thepackage{}{\pkg*{\@package}}
3001 % \end{macrocode}
3002 % \end{macro}
3003 % \begin{macro}{\thepkg}
3004 % \begin{macrocode}
3005 \DeclareDocumentCommand\thepkg{}{\thepackage}
3006 % \end{macrocode}
3007 % \end{macro}
3008 % \changes{1.5e}{Always expand \cs{@title} when setting metadata}
3009 % Additionally we define \cs{skdocpdfsettings}, which is also used
3010 % by \cs{maketitle}, to include PDF metadata if the documentation
3011 % is being compiled using \hologo{pdfLaTeX}.
3012 % \begin{macrocode}
3013 \ifpdf
3014 \def\skdocpdfsettings{%
3015 \hypersetup{%
3016 pdfauthor = {\@author\space<\@plainemail>},
3017 pdftitle = {\text_purify:n{\@title}},
3018 pdfsubject = {Documentation~of~LaTeX~package~\@package},
3019 pdfkeywords = {\@package,~LaTeX,~TeX}
3020 }%
3021 }%
3022 \else
3023 \let\skdocpdfsettings\empty%
3024 \fi
3025 % \end{macrocode}
3026 %
3027 % \subsection{General document commands}
3028 % Most of the general document commands are defined by the
3029 % \pkg{scrartcl} document class we base ourselves on, but a few
3030 % of them have to be redefined.
3031 %
3032 % \subsubsection{Notices and warnings}
3033 % We define macros to typeset notices and warnings in the documentation
3034 % text. Notices are typeset as \Notice{this is a notice}, and warnings
3035 % are typeset as follows: \Warning{this is a warning}
3036 % A macro for longer warnings is also available:
3037 % \LongWarning{This is a longer warning.}
3038 %
3039 % \begin{macro}{\Notice}[1]
3040 % {Notice text}
3041 % \begin{macrocode}
3042 \DeclareDocumentCommand\Notice{m}{
3043 (\emph{\textbf{Note:}~#1})
3044 }
3045 % \end{macrocode}
3046 % \end{macro}
3047 % \begin{macro}{\Warning}[1]
3048 % {Warning text}
3049 % \changes{1.5}{Fix spacing to consider \cs{fboxsep} and \cs{fboxrule}}
3050 % \begin{macrocode}
3051 \DeclareDocumentCommand\Warning{+m}{
3052 \vspace{\baselineskip}
3053 \par\noindent
3054 \fbox{\begin{minipage}[c]{\textwidth-2\fboxsep-2\fboxrule}
3055 \centering
3056 \textbf{Warning:}~#1
3057 \end{minipage}}
3058 \vspace{\baselineskip}
3059 \par
3060 }
3061 % \end{macrocode}
3062 % \end{macro}
3063 % \begin{macro}{\LongWarning}[1]
3064 % {Warning text}
3065 % \changes{1.5}{Fix spacing to consider \cs{fboxsep} and \cs{fboxrule}}
3066 % \begin{macrocode}
3067 \DeclareDocumentCommand\LongWarning{+m}{
3068 \Warning{
3069 \par\noindent
3070 \begin{minipage}{\textwidth-2\fboxsep-2\fboxrule}
3071 #1
3072 \end{minipage}
3073 }
3074 }
3075 % \end{macrocode}
3076 % \end{macro}
3077 %
3078 % \subsubsection{The title page}
3079 % The title page consists of the \cs{maketitle} and the \env{abstract}.
3080 % We redefine both, inspired slightly by the Prac\TeX\ journal and the
3081 % \pkg{skrapport} document class.
3082 % \begin{macro}{\@maketitle}
3083 % \changes{1.5}{Get rid of a superfluous \cs{newpage}}
3084 % \begin{macrocode}
3085 \def\@maketitle{%
3086 \null
3087 \begin{flushleft}%
3088 {%
3089 \Huge\sectfont\@title%
3090 \ifx\@ctan\@empty\else%
3091 \footnote{Available~on~\@ctan.}%
3092 \fi
3093 \ifx\@repository\@empty\else%
3094 \footnote{Development~version~available~on~\@repository.}%
3095 \fi%
3096 \par%
3097 }%
3098 \vskip 1em
3099 {%
3100 \Large\@author
3101 \ifx\@email\@empty\else%
3102 \space
3103 \newlength\skdoc@minipage@ew%
3104 \settowidth{\skdoc@minipage@ew}{%
3105 \normalsize{$\lceil${\@email}$\rfloor$}}
3106 \begin{minipage}[b]{\skdoc@minipage@ew}
3107 \normalsize{$\lceil${\@email}$\rfloor$}
3108 \end{minipage}\par%
3109 \fi%
3110 }%
3111 \ifx\@version\@empty\else
3112 \vskip .5em
3113 {%
3114 \large Version~\@version\par%
3115 }%
3116 \fi
3117 \end{flushleft}%
3118 \par\bigskip%
3119 }
3120 % \end{macrocode}
3121 % \end{macro}
3122 % \begin{macro}{\maketitle}
3123 % \begin{macrocode}
3124 \def\maketitle{%
3125 \begingroup
3126 \skdocpdfsettings
3127 \renewcommand\thefootnote{\@fnsymbol\c@footnote}
3128 \@maketitle
3129 \setcounter{footnote}{0}
3130 \skdocpdfsettings
3131 \endgroup
3132 }
3133 % \end{macrocode}
3134 % \end{macro}
3135 % \begin{environment}{abstract}
3136 % \begin{macrocode}
3137 \DeclareDocumentEnvironment{abstract}{}{
3138 \newlength\skdoc@abstract@tw%
3139 \newlength\skdoc@abstract@aw%
3140 \settowidth{\skdoc@abstract@tw}{\descfont\abstractname}%
3141 \setlength{\skdoc@abstract@aw}{\the\textwidth-\the\skdoc@abstract@tw-2em}%
3142 \begin{minipage}{\textwidth}
3143 \begin{minipage}[t]{\skdoc@abstract@tw}%
3144 \begin{flushright}%
3145 \leavevmode\descfont\abstractname%
3146 \end{flushright}%
3147 \end{minipage}%
3148 \hspace{1em}%
3149 \begin{minipage}[t]{\skdoc@abstract@aw}%
3150 }{
3151 \end{minipage}
3152 \end{minipage}
3153 }
3154 % \end{macrocode}
3155 % \end{environment}
3156 %
3157 % \subsubsection{Table of contents}
3158 % The table of contents are redefined to imitate the excellent table
3159 % of contents of the \pkg{microtype} manual.
3160 % \begin{macro*}{\l@section}
3161 % \begin{macrocode}
3162 \let\l@section@\l@section
3163 \def\l@section{\vskip -.75ex\l@section@}
3164 % \end{macrocode}
3165 % \end{macro*}
3166 % \begin{macro*}{\l@subsection}
3167 % \begin{macrocode}
3168 \def\l@subsection{\vskip.35ex\penalty\@secpenalty\@dottedtocline{2}{1.5em}{2.7em}}
3169 % \end{macrocode}
3170 % \end{macro*}
3171 % \begin{macro*}{l@subsubsection}
3172 % \begin{macrocode}
3173 \def\l@subsubsection#1#2{
3174 \leftskip 4.2em
3175 \parindent 0pt
3176 {\let\numberline\@gobble{\small #1~[#2]}}
3177 }
3178 % \end{macrocode}
3179 % \end{macro*}
3180 % \begin{macro*}{\l@table}
3181 % \begin{macrocode}
3182 \def\l@table{\@dottedtocline{1}{0pt}{1.5em}}
3183 % \end{macrocode}
3184 % \end{macro*}
3185 % \begin{macro*}{\l@figure}
3186 % \begin{macrocode}
3187 \def\l@figure{\@dottedtocline{1}{0pt}{1.5em}}
3188 % \end{macrocode}
3189 % \end{macro*}
3190 % \begin{macrocode}
3191 \def\@pnumwidth{1.7em}
3192 \AtEndDocument{\addtocontents{toc}{\par}}
3193 % \end{macrocode}
3194 % \begin{macro}{\tableofcontents}
3195 % \begin{macrocode}
3196 \let\old@tableofcontents\tableofcontents
3197 \DeclareDocumentCommand\tableofcontents{}{
3198 \bool_gset_true:N\g__skdoc_no_index_bool
3199 \microtypesetup{protrusion=false}
3200 \old@tableofcontents
3201 \microtypesetup{protrusion=true}
3202 \bool_gset_false:N\g__skdoc_no_index_bool
3203 }
3204 % \end{macrocode}
3205 % \end{macro}
3206 %
3207 % \subsubsection{Including the LPPL license}
3208 % A helper macro that includes the LPPL license is also provided.
3209 % \begin{macro}{\PrintLPPL}
3210 % \begin{macrocode}
3211 \DeclareDocumentCommand\PrintLPPL{}{
3212 \begingroup
3213 \IfFileExists{lppl.tex}{
3214 \let\old@verbatim@font\verbatim@font
3215 \def\verbatim@font{
3216 \old@verbatim@font\tiny
3217 }
3218 \def\LPPLicense{\begingroup\small}
3219 \def\endLPPLicense{\endmulticols\endgroup}
3220 \DeclareDocumentCommand\LPPLsection{m}{
3221 \section{####1}
3222 }
3223 \DeclareDocumentCommand\skdoc@lppl@hack{m}{
3224 \end{multicols}
3225 \begin{multicols}{2}
3226 [\subsection*{####1}][6\baselineskip]
3227 }
3228 \DeclareDocumentCommand\LPPLsubsection{m}{
3229 \subsection*{####1}
3230 \let\LPPLsubsection\skdoc@lppl@hack
3231 \begin{multicols}{2}
3232 }
3233 \DeclareDocumentCommand\LPPLsubsubsection{m}{
3234 \subsubsection*{####1}
3235 }
3236 \DeclareDocumentCommand\LPPLparagraph{m}{\paragraph*{####1}}
3237 \DeclareDocumentCommand\LPPLfile{m}{\file{####1}}
3238 \let\oldmakeatletter\makeatletter
3239 \long\def\makeatletter####1\makeatother{
3240 \let\makeatletter\oldmakeatletter
3241 }
3242 \setlength\leftmargini{15pt}
3243 \setlength\leftmarginii{12.5pt}
3244 \setlength\leftmarginiii{10pt}
3245 \newenvironment{enum}[1][0]{
3246 \list\labelenumi{
3247 \usecounter{enumi}
3248 \setcounter{enumi}{####1}
3249 \addtocounter{enumi}{-1}
3250 \leftmargin 30pt
3251 \itemindent-15pt
3252 \labelwidth 15pt
3253 \labelsep 0pt
3254 \def\makelabel########1{########1\hss}}
3255 }{\endlist}
3256 \input{lppl}
3257 }{
3258 \msg_warning:nn{skdoc}{no-lppl}
3259 }
3260 \endgroup
3261 }
3262 % \end{macrocode}
3263 % \end{macro}
3264 %
3265 % \subsection{Cosmetic changes}
3266 % We perform a couple of cosmetic changes to existing features as
3267 % well. First, we set a new header/footer style using the KOMA-script
3268 % \cs{deftripstyle} macro.
3269 % \begin{macrocode}
3270 \deftripstyle{skdoc}%
3271 {}{}{}%
3272 {\small The~\textbf{\pkg*{\@package}}~package,~v\@version}{}{\small\pagemark}
3273 \AfterBeginDocument{\pagestyle{skdoc}}
3274 % \end{macrocode}
3275 % We also redefine the section level format to set the section numbers
3276 % in the margin, much like the \pkg{microtype} manual.
3277 % \begin{macrocode}
3278 \RenewDocumentCommand{\othersectionlevelsformat}{m}{%
3279 \makebox[0pt][r]{%
3280 \fontfamily{fos}\mdseries\selectfont
3281 \csname the#1\endcsname\enskip}%
3282 }
3283 % \end{macrocode}
3284 % Finally, we actually use \pkg{microtype} in the document class, and
3285 % make sure to disable it in the verbatim environments.
3286 % Set up microtype properly
3287 % \begin{macrocode}
3288 \g@addto@macro\@verbatim{\microtypesetup{activate=false}}
3289 \AtEndOfClass{%
3290 \microtypesetup{expansion,kerning,spacing,tracking}%
3291 \DisableLigatures{family = tt*}%
3292 }
3293 % \end{macrocode}
3294 % We also want numbers on the bibliography headings, if we are loading
3295 % \pkg{biblatex}. If we happen to be loading \pkg{bibtex}, we issue a
3296 % warning instead.
3297 % \begin{macrocode}
3298 \AtBeginDocument{
3299 \ifdefined\defbibheading
3300 \defbibheading{bibliography}[\bibname]{\section{#1}}
3301 \fi
3302 \@ifpackageloaded{bibtex}{\msg_warning:nn{skdoc}{bibtex-unsupported}}{}
3303 }
3304 % \end{macrocode}
3305 % Oh, and we want \cs{marginpar}s on the left, not on the right.
3306 % \begin{macrocode}
3307 \AtBeginDocument{\reversemarginpar}
3308 % \end{macrocode}
3309 %
3310 % That's it, we're done!
3311 % \begin{macrocode}
3312 \endinput
3313 % \end{macrocode}
3314 % \iffalse
3315 %</class>
3316 % \fi
3317 % \Finale
3318 % \section{Installation}
3319 % The easiest way to install this package is using the package
3320 % manager provided by your \LaTeX\ installation if such a program
3321 % is available. Failing that, provided you have obtained the package
3322 % source (\file{skdoc.dtx} and \file{Makefile}) from either CTAN
3323 % or Github, running \texttt{make install} inside the source directory
3324 % works well. This will extract the documentation and code from
3325 % \file{skdoc.dtx}, install all files into the TDS tree at
3326 % \texttt{TEXMFHOME} and run \texttt{mktexlsr}.
3327 %
3328 % If you want to extract code and documentation without installing
3329 % the package, run \texttt{make all} instead. If you insist on not
3330 % using \texttt{make}, remember that \file{skdoc.cls} is generated
3331 % by running \texttt{tex}, while the documentation is generated by
3332 % running \texttt{pdflatex}.
3333 %
3334 % \PrintChanges
3335 % \PrintIndex
3336 % \printbibliography
3337 % \endinput