| 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 |