skdoc (28mar13)

git-svn-id: svn://tug.org/texlive/trunk@29544 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 2475 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/skdoc/skdoc.dtx b/Master/texmf-dist/source/latex/skdoc/skdoc.dtx
new file mode 100644
index 00000000000..e8fea60711c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/skdoc/skdoc.dtx
@@ -0,0 +1,2475 @@
+% \iffalse
+%% skdoc documentation class
+%%
+%% Copyright (C) 2012 by Simon Sigurdhsson <sigurdhsson@gmail.com>
+%% 
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%%   http://www.latex-project.org/lppl.txt
+%% and version 1.3 or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+%% 
+%% This work has the LPPL maintenance status `maintained'.
+%% 
+%% The Current Maintainer of this work is Simon Sigurdhsson.
+%% 
+%% This work consists of the files skdoc.dtx
+%% and the derived filebase skdoc.cls.
+%
+%<*ignore>
+\begingroup
+  \catcode123=1 %
+  \catcode125=2 %
+  \def\x{LaTeX2e}%
+\expandafter\endgroup
+\ifcase 0\ifx\install y1\fi\expandafter
+        \ifx\csname processbatchFile\endcsname\relax\else1\fi
+        \ifx\fmtname\x\else 1\fi\relax
+\else\csname fi\endcsname
+%</ignore>
+%<*install>
+\input docstrip.tex
+
+\preamble
+\endpreamble
+
+\keepsilent
+\askforoverwritefalse
+
+\generate{%
+    \file{skdoc.cls}{\from{skdoc.dtx}{class}}%
+}
+
+\begingroup
+\obeyspaces
+\Msg{*************************************************************}%
+\Msg{*                                                           *}%
+\Msg{* To finish the installation you have to move the following *}%
+\Msg{* file into a directory searched by TeX:                    *}%
+\Msg{*                                                           *}%
+\Msg{*     skdoc.cls                                             *}%
+\Msg{*                                                           *}%
+\Msg{* To produce the documentation run the file skdoc.dtx       *}%
+\Msg{* through LaTeX.                                            *}%
+\Msg{*                                                           *}%
+\Msg{* Happy TeXing!                                             *}%
+\Msg{*                                                           *}%
+\Msg{*************************************************************}%
+\endgroup%
+
+\endbatchfile
+%</install>
+%<*ignore>
+\fi
+%</ignore>
+%<*class>
+\RequirePackage{expl3}
+%</class>
+%<*driver>
+\RequirePackage{xparse}
+\ProvidesExplFile{skdoc.dtx}
+%</driver>
+%<class>\ProvidesExplClass{skdoc}
+%<*class>
+    {2012/12/26}{1.0}{skdoc documentation class}
+%</class>
+%
+%<*driver>
+\msg_new:nnn{skdoc-dtx}{not-installed}
+    {Run~`tex'~on~skdoc.dtx~before~generating~the~documentation!}
+\IfFileExists{skdoc.cls}{}{
+    \msg_fatal:nn{skdoc-dtx}{not-installed}
+}
+\ExplSyntaxOff
+\DeclareDocumentCommand\MakePercentIgnore{}{\catcode`\%9\relax}
+\DeclareDocumentCommand\MakePercentComment{}{\catcode`\%14\relax}
+\DeclareDocumentCommand\DocInput{m}{
+    \MakePercentIgnore\input{#1}\MakePercentComment
+}
+\documentclass{skdoc}
+\usepackage{hologo}
+\usepackage{booktabs}
+\usepackage[style=authoryear,backend=biber]{biblatex}
+%%\usepackage{chslacite}
+\begin{filecontents}{skdoc.bib}
+@online{Lazarides12,
+    author = {Yannis Lazarides},
+    title = {Different approach to literate programming for \LaTeX},
+    year = {2012},
+    url = {http://tex.stackexchange.com/q/47237/66}
+}
+@online{Talbot13,
+    author = {Nicola Talbot},
+    title = {Answer to \enquote{Distinct formatted page numbers with glossaries and Xindy}},
+    year = {2013},
+    url = {http://tex.stackexchange.com/a/89830/66}
+}
+\end{filecontents}
+\addbibresource{skdoc.bib}
+\OnlyDescription
+\begin{document}
+    \DocInput{skdoc.dtx}
+\end{document}
+% \fi
+%
+% \deftripstyle{skdoc-class}{}{}{}%
+% {\small The~\textbf{\thepkg}~document~class,~\theversion}%
+% {}{\small\pagemark}
+% \pagestyle{skdoc-class}
+%
+% \version{1.0}
+% \changes{1.0}{Initial version}
+%
+% \package[ctan=skbundle,vcs=https://github.com/urdh/skdoc]{skdoc}
+% \repository{https://github.com/urdh/skdoc}
+% \title{The \thepkg{} document class}
+% \author{Simon Sigurdhsson}
+% \email{sigurdhsson@gmail.com}
+% \maketitle
+%
+% \begin{abstract}
+% The \thepkg{} class provides macros to document the functionality
+% and implementation of \LaTeX\ packages and document classes. It is
+% loosely based on the \pkg{ydoc} and \pkg{ltxdoc} classes, but has
+% a number of incompatible differences.
+%
+% The class defines a \env{MacroCode} environment which substitutes
+% the usual \pkg{docstrip} method of installing packages. It has the
+% ability to generate both documentation and code in a single run of
+% a single file.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \section{Introduction}
+% This document class, inspired by a question on the \TeX\ Stack
+% Exchange\footcite{Lazarides12}, aims to provide an alternative to
+% the standard \pkg{docstrip} method of literate programming for
+% \LaTeX\ packages. It also aims to provide a more modern, appealing
+% style for \LaTeX\ package documentation.
+%
+% In order to achieve this, it builds upon already existing features
+% of the \pkg{expl3}, \pkg{verbatim} and \pkg{ydoc} packages as well
+% as the KOMA-script document classes.
+%
+% So far it is mainly intended to be an experiment to explore a less
+% cumbersome way of writing \LaTeX\ packages, and as such I give no
+% guarantee that this package will continue to exist in a working
+% state (\emph{i.e.} future users may not be able to extract code from
+% package documentation based on \thepkg) or that its public API
+% (commands and environments described by this documentation; consider
+% undocumented macros part of a private API) will be stable.
+%
+% The documentation of \thepkg\ is in fact typeset using the class
+% itself. It does not, however, make use of the main feature of this
+% class (the \env{MacroCode} environment), because bootstrapping the
+% class to generate itself is more complicated than it is useful.
+%
+% \section{Documentation}
+% Since \thepkg\ is based on \pkg{ydoc} many of the macros and
+% environment present in that package are also available in \thepkg,
+% in a possibly redefined incanation. However, any macros or
+% environment present in \pkg{ydoc} but not described in this
+% documentation should be considered part of the private API of
+% \thepkg. In the future, the removal of the \pkg{ydoc} dependency
+% may result in such macros being unavailable, and at present changes
+% made by \thepkg\ may break such macros without notice.
+%
+% \subsection{Options}
+% \Option{load}\WithValues{\meta{package}}\AndDefault{\cs{jobname}}
+% The \thepkg\ document class has only one option. The \opt{load}
+% option declares that if the package specified exists, it should
+% be loaded. This is intended to load any package provided in the
+% implementation, but requires that the documentation provides
+% stub variants of the macros used in the documentation so that
+% \LaTeX\ still completes its first run. \Warning{The \opt{load}
+% option will likely disappear in a future version.}
+%
+% \subsection{General macros}
+% The document class defines a number of general macros intended for
+% use in parts of the document not strictly considered
+% \enquote{documentation} or \enquote{implementation}, in addition to
+% being used in those parts. These \enquote{general} macros include
+% macros that define metadata, generate the title page, typeset
+% notices or warnings and those that refer to macros, environments,
+% packages and such.
+%
+% \subsubsection{Metadata}
+% Several macros for defining metadata (\emph{i.e.} information about
+% the package and its documentation) are made available. These mostly
+% set an internal variable which is used to typeset the title page,
+% and to insert PDF metadata whenever \hologo{pdfLaTeX} is used to
+% generate the documentation.
+%
+% \DescribeMacro\package['ctan='<identifier>',vcs='<url>]{<package name>}
+% The \cs{package} macro defines the package name used by \cs{thepkg},
+% \cs{maketitle} and similar macros. It also calls \cs{title} to set
+% a sensible default title based on the package name. The optional
+% key-value argument takes two keys: \texttt{ctan} and \texttt{vcs}.
+% The first one accepts an optional value \meta{identifier}, which
+% should be the identifier the package has on CTAN (the default is
+% \cs{jobname}), while the other takes a mandatory argument \meta{url}
+% specifying the URL of a VCS repository where development versions
+% of the package are available. The two optional keys imply calls to
+% the \cs{ctan} and \cs{repository} macros, respectively.
+%
+% \DescribeMacro\version{<version>}
+% Sets the version number of the package the documentation describes.
+% Here, \meta{version} should not include the initial \enquote{v},
+% \emph{i.e.} the argument should be the same as that given to
+% \emph{e.g.} the \LaTeX3 \cs{ProvidesExplPackage} or the standard
+% \pkg{ltxdoc} \cs{changes}.
+%
+% \DescribeMacro\ctan{<identifier>}
+% As detailed above, this macro defines the CTAN identifier of the
+% package, which is (optionally) used in the \cs{maketitle} macro.
+%
+% \DescribeMacro\repository{<url>}
+% Again, as detailed above this macro defines the URL of a source code
+% repository containing a development version of the package, which
+% is optionally used by \cs{maketitle}.
+%
+% \DescribeMacro\author{<name>}
+% Defines the name of the package author. This is used by
+% \cs{maketitle} and is mandatory if \cs{maketitle} is used.
+%
+% \DescribeMacro\email{<email>}
+% Defines the email of the package author. This is used by
+% \cs{maketitle} and is mandatory if \cs{maketitle} is used.
+%
+% \DescribeMacro\title{<title>}
+% Defines the package title. By default, the \cs{package} macro sets
+% a sensible title that should suit most packages, but using \cs{title}
+% will override this title (useful for \emph{e.g.} document classes or
+% \hologo{BibTeX} styles).
+%
+% Three macros retrieving the set metadata are also available. They
+% can be used to typeset the current version of the package, and the
+% package name, respectively.
+%
+% \DescribeMacro\theversion
+% Returns the version as defined by \cs{version}, with a leading
+% \enquote{v}. That is, issuing \Macro\version{1.0} makes 
+% \cs{theversion} print \enquote{v1.0}.
+%
+% \DescribeMacro\thepackage
+% \DescribeMacro\thepkg
+% The \cs{thepackage} and \cs{thepkg} macros return the package name
+% as defined by the \cs{package} macro, enclosed in \cs{pkg*}. That is,
+% the package name is typeset as a package but not indexed.
+%
+% \subsubsection{The preamble}
+% The preamble of any documentation most often consists of a title page
+% containing an abstract, and possibly a table of contents. The \thepkg
+% \ package provides macros and environments that typeset such things,
+% and these should be fully compatible with most other document classes.
+%
+% \DescribeMacro\maketitle
+% The \cs{maketitle} macro typesets a title page. This title page uses
+% the metadata defined by the macros described earlier, and typesets
+% them in a manner which is illustrated by the documentation of this
+% class. This style is inspired by \pkg{skrapport}, which is in turn
+% inspired by the title pages of the Prac\TeX\ Journal.
+%
+% \DescribeEnv[<package abstract>]{abstract}
+% The \env{abstract} environment typesets an abstract of the package.
+% Again, its style is illustrated by this document and it is inspired
+% by the \pkg{skrapport} package as well as the Prac\TeX\ Journal.
+%
+% \DescribeMacro\tableofcontents
+% Finally, a Table of Contents may be printed. The actual table of
+% contents is provided by the \pkg{scrartcl} document class, but \thepkg
+% \ redefines a couple of the internal macros to style the Table of
+% Contents in a manner similar to that of the \pkg{microtype} manual.
+%
+% \subsubsection{The LPPL license}
+% \DescribeMacro\PrintLPPL
+% If the LPPL license is present in a directory where \LaTeX\ can find
+% it, in a file called \file{lppl.tex}, then \cs{PrintLPPL} will
+% include the entire LPPL license in the document, and typeset it in
+% a fairly compact manner.
+%
+% \subsubsection{Notices and warnings}
+% The document class provides macros to indicate information that may
+% be of extra importance in the documentation. Such information is
+% categorized as either notices or warnings, which are treated
+% differently.
+% 
+% \DescribeMacro\Notice{<notice>}
+% A notice is a short piece of text that contains information that may
+% explain some unexpected but unharmful behaviour of a macro or similar.
+% It is typeset inline, emphasized and in parantheses --- as such, the
+% sequence \Macro\Notice{a notice} yields \Notice{a notice}.
+%
+% \DescribeMacro\Warning{<warning>}
+% A warning is a short comment that conveys information that the user
+% must be aware of. This includes unexpected potentially harmful
+% behaviour, deprecation notices and so on. It is typeset in its own
+% \cs{fbox} --- the sequence \Macro\Warning{a warning} yields the
+% following: \Warning{a warning}
+%
+% \DescribeMacro\LongWarning{<warning>}
+% The \cs{LongWarning} macro is a variant of \cs{Warning} that has been
+% adapted for longer texts, possibly including paragraph breaks. Like
+% \cs{Warning}, it is typeset in a box: \LongWarning{a long warning}
+%
+% \subsubsection{Referential macros}\label{sec:ref-macros}
+% The family of macros originating from \cs{cs} are used to typeset
+% various concepts in running text. In addition to adhering to the
+% general format of the corresponding concept, they index their
+% argument. Each of these macros have a starred variant which does
+% not index its argument; use these when appropriate.
+%
+% \DescribeMacro\cs{<command sequence>}
+% Typesets a command sequence, or macro. The argument should be
+% provided without the leading backslash, and the command sequence
+% will be typeset in a monospaced font.
+%
+% \DescribeMacro\env{<environment name>}
+% Typesets an environment name, which will be typeset in a monospace
+% font.
+%
+% \DescribeMacro\pkg{<package name>}
+% Typesets a package, document class or bundle name. The name will
+% be typeset in a sans-serif font.
+%
+% \DescribeMacro\opt{<option>}
+% Typesets a package or document class option. As of \theversion,
+% options are typeset using a monospace font.
+%
+% \DescribeMacro\bib{<\hologo{BibTeX} entry type>}
+% Typesets a \hologo{BibTeX} entry type. The agument should be provided
+% without the leading \texttt{@} sign. The entry type will be typeset
+% in a monospace font.
+% 
+% \DescribeMacro\thm{<theme name>}
+% Typesets a theme name. As of \theversion, the theme name will be
+% typeset in an upright serif font.
+%
+% \DescribeMacro\file{<filename>}
+% Typesets a filename. As of \theversion, the filename will be typeset
+% in a monospace font.
+%
+% \subsection{Documenting the package}\label{sec:doc-macros}
+% The documentation part of any \LaTeX\ manual is arguably the most
+% important one, and to facilitate proper typesetting of the
+% documentation \thepkg\ povides a number of different macros, all
+% inspired by or inherited from \pkg{ydoc}. The first of these
+% macros that will be discussed are the macros that typeset differen
+% kinds of arguments in running text.
+%
+% \DescribeMacro\meta{<meta text>}
+% The \cs{meta} macro typesets a placeholder to be placed in an
+% argument. This can be used to refer to arguments and contents of
+% macros and environments described by commands discussed later in
+% this documentation. It is typeset in brackets: \meta{meta text}.
+%
+% \DescribeMacro\marg{<mandatory argument>}
+% \DescribeMacro\oarg{<optional argument>}
+% \DescribeMacro\parg{<picture-style argument>}
+% \DescribeMacro\aarg{<beamer-style argument>}
+% \DescribeMacro\sarg
+% These macros typeset different kinds of arguments (mandatory,
+% optional, picture-style, beamer-style and star arguments,
+% respetively). These can be used to describe arguments, but
+% are mostly used internally. See table~\ref{tab:args} for
+% examples of how these macros are typeset.
+%
+% \begin{table}[tb]
+%   \centering
+%   \caption{Typesetting arguments}
+%   \label{tab:args}
+%   \begin{tabular}{ll}
+%      \toprule
+%      Invokation            % Result          \\
+%      \midrule
+%      \Macro\marg{argument} & \marg{argument} \\
+%      \Macro\oarg{argument} & \oarg{argument} \\
+%      \Macro\parg{argument} & \parg{argument} \\
+%      \Macro\aarg{argument} & \aarg{argument} \\
+%      \Macro\sarg           & \sarg           \\
+%      \bottomrule
+%   \end{tabular}
+% \end{table}
+%
+% \subsubsection{Options}
+% Package options are of course important to describe, and to this
+% end four macros are provided. They aid in describing options of
+% both regular boolean and the more modern key-value syntax. They
+% are intended to be used in a sequence: \\ 
+% \mbox{\Macro\Option{...}
+%       \AlsoMacro\WithValues{...}
+%       \AlsoMacro\AndDefault{...}}
+%
+% \DescribeMacro\Option{<option>}
+% \DescribeMacro\Options{<option>,...}
+% These macros typeset an option, and may be followed by the
+% \cs{WithValues} macro \Notice{the with \cs{Options}, only the
+% first option in the list will work with \cs{WithValues}}.
+%
+% \DescribeMacro\WithValues{<value>,...}
+% This macro typesets a comma-separated list of values a specific
+% option can take. It may be followed by the \cs{AndDefault} macro.
+%
+% \DescribeMacro\AndDefault{<default value>}
+% This macro typesets the default value of an option. It may follow
+% either \cs{Options} or \cs{WithValues}.
+%
+% Common constructs using these macros include:
+% \begin{itemize}
+% \item \mbox{\small
+%       \Macro\Option{<option>}
+%       \AlsoMacro\WithValues{<value>,...}
+%       \AlsoMacro\AndDefault{<default>}}
+% \item \mbox{\small
+%       \Macro\Options{<option>,no\meta{option}}
+%       \AlsoMacro\AndDefault{no\meta{option}}}
+% \end{itemize}
+% 
+% \subsubsection{Macros}
+% The \thepkg\ class inherits a number of macros for describing the
+% package macros from the \pkg{ydoc} package. Only four of them are
+% to be considered stable.
+% \LongWarning{
+% The macros \cs{MakeShortMacroArgs} and \cs{DeleteShortMacroArgs}
+% and the environments \env{DescribeMacros} and \env{DescribeMacrosTab}
+% provided by \pkg{ydoc} are unsupported as of \thepkg\ \theversion. 
+% They may work, but this is
+% not a guarantee and they are most likely broken or may break other
+% features of \thepkg.
+% }
+%
+% \DescribeMacro\DescribeMacro<\textbackslash macro><macro arguments>
+% The \cs{DescribeMacro} macro documents a macro along with its
+% arguments. Any number of \meta{macro arguments} may follow the macro,
+% and \cs{DescribeMacro} will stop reading arguments on the first
+% non-argument token. The macro will be indexed.
+% \LongWarning{Although \meta{\textbackslash macro} can include
+% \texttt{@} signs, it is not possible to document \LaTeX3-style
+% macros (with underscores and colons) without the following hack:
+% \par \medskip \begingroup
+% \cs*{ExplSyntaxOn} \\
+% \cs*{cs\_set\_protected\_nopar:Npn}\cs*{ExplHack}\texttt{\{} \\
+% \hspace*{2ex}\cs*{char\_set\_catcode\_letter:n}\texttt{\{~58~\}} \\
+% \hspace*{2ex}\cs*{char\_set\_catcode\_letter:n}\texttt{\{~95~\}} \\
+% \texttt{\}} \\
+% \cs*{ExplSyntaxOff} \\
+% \cs*{ExplHack} \\
+% \endgroup }
+%
+% \DescribeMacro\Macro<\textbackslash macro><macro arguments>
+% This is simply a variant of \cs{DescribeMacro} for use in running
+% text. It is equivalent to \cs{MacroArgs}\cs{AlsoMacro}.
+%
+% \DescribeMacro\MacroArgs<macro aguments>
+% This macro formats \meta{macro arguments} the same way
+% \cs{DescribeMacro} does. As with \cs{Macro}, it is used in
+% running text.
+%
+% \DescribeMacro\AlsoMacro<\textbackslash macro><further arguments>
+% This macro should be used inside \meta{macro arguments} of the macros
+% described above, and typesets an additional macro as part of the
+% syntax of the described macro. For instance, the \cs{csname} macro
+% could be described with the sequence
+% \cs*{Macro}\cs*{csname}\texttt{<command sequence name>}
+% \cs*{AlsoMacro}\cs{endcsname}, which would be rendered as
+% \Macro\csname<command sequence name>\AlsoMacro\endcsname\relax.
+%
+% \subsubsection{Environments}
+% In addition to the macros describing macros, \thepkg\ also inherits
+% one environment and one macro to describe environments. These are
+% similar to the macros described previously in both form and function,
+% but lack equivalents for running text.
+%
+% \DescribeMacro\DescribeEnv[<body content>]{<name>}<arguments>
+% This macro describes an environment, in the same way
+% \cs{DescribeMacro} does for macros. The \meta{body content}, which
+% is optional, may be used to indicate what kind of content the
+% environment is designed to contain. The \cs{MacroArgs}
+% macro is automatically inserted before \meta{body content}.
+%
+% \subsubsection{Other entities}
+% The document class also provides macros to describe \hologo{BibTeX}
+% entries and generic themes. The \hologo{BibTeX} entries are described
+% using the \cs{BibEntry} and \cs{WithFields} macros, while themes are
+% described using the \cs{Theme} macro.
+%
+% \DescribeMacro\BibEntry{<entry name>}
+% \AlsoMacro\WithFields[<optional fields>]{<mandatory fields>}
+% These two macros describe a \hologo{BibTeX} entry named
+% \meta{entry name} (\emph{i.e.}, \bib*{\meta{entry name}}) along with
+% its optional and mandatory fields.
+%
+% \DescribeMacro\Theme{<theme name>}
+% This macro describes a theme named \meta{theme name}. These could be
+% used to describe any kind of theme, such as color themes of a
+% document class.
+%
+% \DescribeMacro\DescribeFile{<filename>}
+% This macro describes a special file named \meta{filename}. This
+% could be a configuration file or similar that is either part of
+% the package or something the package reads if available.
+%
+% \subsection{Describing the implementation}
+% In true \TeX\ (and literal programming) fashion the document class
+% also provides ways to describe, in detail, parts of the
+% implementation. The most essential of the implementation environments,
+% without which \thepkg\ doesn't generate any files, is the
+% \env{MacroCode} environment. Other than that, the implementation
+% environments should be compatible with or analogous to the standard
+% \pkg{ltxdoc} document class.
+% 
+% \subsubsection{Implementation environments}\label{sec:impl-env}
+% The environments described in this section indicate the
+% implementation of different concepts including macros, environments
+% and options. They each have a starred variant which doesn't print
+% the concept name (only indexes it), and a non-starred variant which
+% does \Notice{inside these environments, \cs{changes} will refer to
+% the relevant entity instead of logging \enquote{general} changes}.
+%
+% Some of the following environment can typeset descriptions of the 
+% internal arguments (\texttt{\#1}, \texttt{\#2} \emph{etc.}) to
+% improve readability of the implementation code.
+%
+% \DescribeEnv[<description>]{macro}{<\textbackslash macro>}
+%                     <\# of args>{<arg 1 description>}'...'
+%                                 {<arg n description>}
+% With this environment, the implementation of a macro is described.
+% Note that as with \cs{DescribeMacro}, \LaTeX3-style macros can not
+% be used in \meta{\textbackslash macro} without the catcode hack
+% mentioned earlier.
+%
+% \DescribeEnv[<description>]{environment}{<environment>}
+%                     <\# of args>{<arg 1 description>}'...'
+%                                 {<arg n description>}
+% This environment describes the implementation of an environment.
+%
+% \DescribeEnv[<description>]{option}{<option>}
+% This environment describes the implementation of an option.
+%
+% \DescribeEnv[<description>]{bibentry}{<@entry>}
+% This environment describes the implementation of a \hologo{BibTeX}
+% entry type.
+%
+% \DescribeEnv[<description>]{theme}{<theme>}
+% This environment describes the implementation of a theme.
+%
+% \subsubsection{The \env{MacroCode} environment}
+% The \enquote{main event} of the \thepkg\ document class is the
+% \env{MacroCode} environment. It has roughly the same role the 
+% \env{macrocode} environment has in the \pkg{docstrip} system, except
+% that it in addition to typesetting the implementation also saves it
+% to the target files.
+%
+% The workflow is simple; before using \env{MacroCode} to export code
+% to a file the file must be declared using \cs{DeclareFile}, which
+% also assigns a key to the file (the default is the filename). This
+% key is passed to the \env{MacroCode} environment, which saves the
+% code to the specified file.
+%
+% \DescribeMacro\DeclareFile['key='<key>',preamble='<preamble>]{<filename>}
+% The \cs{DeclareFile} macro declares a file for future use with
+% \env{MacroCode}. The optional argument is a comma separated list of
+% key-value options, where the possible keys are \texttt{key} and
+% \texttt{preamble}. Here \meta{key} is a key that is used instead
+% of the filename in \env{MacroCode}, and \meta{preamble} is a
+% token or command sequence expanding to a preamble which will be 
+% prepended to the file on output.
+%
+% \DescribeMacro\PreambleTo{<\textbackslash token>}{<filename>}
+% Reads the preamble from \meta{filename}. Lines from the file are
+% appended to \meta{\textbackslash token} until a line which does not
+% begin with \texttt{\%\%} is encountered.
+%
+% \DescribeMacro\SelfPreambleTo{<\textbackslash token>}
+% This reads the preamble from the curent file. It is equivalent to
+% the sequence
+% \Macro\PreambleTo{<\textbackslash token>}{\cs*{jobname}.tex}.
+%
+% \DescribeEnv[<implementation>]{MacroCode}{<key>}
+% The \env{MacroCode} environment typesets and exports
+% \meta{implementation} verbatim to the file associated with \meta{key}.
+% As such, it is the analogue of the \env{macrocode} environment from
+% \pkg{ltxdoc}, but does not suffer from some of its drawbacks (the
+% sensitivity to whitespace, for instance).
+%
+% \subsubsection{Hiding the implementation}
+% For lagre packages it may be of interest to hide the implementation
+% from the documentation. This is accomplished using the two marker
+% macros \cs{Implementation} and \cs{Finale} (which should be present
+% even if not hiding the implementation), and the switch macro
+% \cs{OnlyDescription}.
+%
+% \DescribeMacro\Implementation
+% This macro indicates the start of the implementation. Normally, this
+% would directly precede the \cs{section} under which the implementation
+% is organized.
+%
+% \DescribeMacro\Finale
+% This macro indicates the end of the implementation. Usually the only
+% things happening after this is the printing of indices, the change
+% log, bibliographies and the end of the \env{document} environment.
+%
+% \DescribeMacro\OnlyDescription
+% This macro, which should be issued in the preamble, indicates that the
+% implementation should be hidden. \Warning{this has the side effect
+% that a page break is inserted where the implementation would normally
+% reside.}
+%
+% \subsection{Documenting changes}
+% One type of useful information you should provide in your
+% documentation is a list of changes. The \thepkg\ document class
+% provides a change list system based on the \pkg{glossaries} package.
+% As such, including a change list in your documentation requires you
+% to run \texttt{makeglossaries} between the first and second \LaTeX\
+% run.
+%
+% \DescribeMacro\changes{<version>}{<description>}
+% The \cs{changes} macro provides the main interface to the change
+% list system, and adds changes to the change list. Each change is
+% added with a \emph{context}; if the macro is issued inside one of
+% the macros described in section~\ref{sec:impl-env}, the concept
+% currenly being described will be the context. Outside these
+% environment, the context is \enquote{general}. For every context
+% and \meta{version}, only one change may be recorded, otherwise
+% \pkg{glossaries} will issue a warning.
+%
+% \DescribeMacro\PrintChanges
+% This macro prints the list of changes. As explained earlier, this
+% requires you to run \texttt{makeglossaries} between the two \LaTeX\ 
+% runs.
+%
+% \subsection{Producing an index}
+% The macros previously discussed in sections~\ref{sec:ref-macros},
+% \ref{sec:doc-macros} and \ref{sec:impl-env} automatically index their
+% aguments using \pkg{glossaries}. By running \texttt{makeglossaries}
+% you can include an index of all macros, environments, packages and 
+% such that are discussed, documented or implemented in your package.
+%
+% \DescribeMacro\PrintIndex
+% Much like the \cs{PrintChanges} macro, this prints the index. As with
+% the list of changes, this requires that you run 
+% \texttt{makeglossaries} between the two \LaTeX\ runs.
+%
+% \iffalse
+% \section{Planned improvements}
+% Planned improvements of this class include
+% \begin{itemize}
+%     \item Do things the \LaTeX3 way, rename the variables properly
+%           and generally conform to \pkg{expl3} guidelines when
+%           applicable. (Way future thing.)
+% \end{itemize}
+% \fi
+%
+% \Implementation
+% \section{Implementation}
+% \iffalse
+%</driver>
+%<*class>
+% \fi
+% \subsection{Require packages}
+% We begin with loading the \pkg{scrartcl} KOMA-script class and a
+% few packages we'll be needing.
+%    \begin{macrocode}
+\PassOptionsToPackage{log-declarations=false}{xparse}
+\LoadClass[ DIV7,
+            headings=big,
+            numbers=noenddot,
+            abstracton,
+            bibliography=totocnumbered,
+            index=totoc
+        ]{scrartcl}
+%    \end{macrocode}
+% These packages are basic low-level things that we use to declare
+% commands, work with strings and so on.
+%    \begin{macrocode}
+\RequirePackage{etoolbox,xstring,xparse,atbegshi,kvoptions}
+%    \end{macrocode}
+% Now, higher-level packages we use in our definitions.
+%    \begin{macrocode}
+\RequirePackage{verbatim,marginnote,calc,hyperref,multicol,hologo}
+\RequirePackage[nomain,xindy,numberedsection,order=letter,
+                sanitize={description=false,sort=false}]{glossaries}
+%    \end{macrocode}
+% We also include the \pkg{ydoc} packages we'll be extending.
+%    \begin{macrocode}
+\RequirePackage{ydoc-code,ydoc-desc}
+%    \end{macrocode}
+% The rest is basically just styling.
+%    \begin{macrocode}
+\RequirePackage[british]{babel}
+\RequirePackage[english=british]{csquotes}
+\RequirePackage[font=small,labelfont=bf,textfont=it]{caption}
+\RequirePackage{scrpage2,PTSerif,ascii}
+\RequirePackage[defaultsans,osfigures,scale=0.95]{opensans}
+\RequirePackage[babel]{microtype}
+%    \end{macrocode}
+% \subsection{Error messages}
+% Set up some error message texts for later use.
+%    \begin{macrocode}
+\msg_new:nnn{skdoc}{key-exists}{File~key~"#1"~already~declared!}
+\msg_new:nnn{skdoc}{key-nexists}{File~key~"#1"~hasn't~been~declared!}
+\msg_new:nnn{skdoc}{wrote-file}{Writing~things~to~file~"#1".}
+\msg_new:nnn{skdoc}{read-preamble}{Reading~preamble~from~file~"#1".}
+\msg_new:nnn{skdoc}{no-lppl}{Could~not~include~LPPL:~lppl.tex~does~not~exist!}
+%    \end{macrocode}
+% \subsection{Options}
+% Define the (as of version 1.0) only option, and process it.
+%    \begin{macrocode}
+\SetupKeyvalOptions{
+    family=skdoc,
+    prefix=skdoc@
+}
+\DeclareStringOption{load}[\jobname]
+\ProcessKeyvalOptions*
+%    \end{macrocode}
+% If the option was used, load the given package if it exists.
+%    \begin{macrocode}
+\IfStrEq{\skdoc@load}{}{}{%
+    \IfFileExists{\skdoc@load.sty}{%
+        \RequirePackage{\skdoc@load}
+    }{}
+}
+%    \end{macrocode}
+% \subsection{The \env{MacroCode} environment}
+% We need a token list and input/output.
+%    \begin{macrocode}
+\tl_new:N\skdoc@temptl
+\ior_new:N\skdoc@input
+\iow_new:N\skdoc@output
+%    \end{macrocode}
+% \begin{macro}{\DeclareFile}[2]
+%   {A list of key-value parameters}
+%   {Filename of the file being declared}
+% This declares a file as part of the bundle, which means we will be
+% writing things to it.
+%    \begin{macrocode}
+\DeclareDocumentCommand\DeclareFile{om}{
+    \group_begin:
+    \keys_define:nn{skdoc@declarefile}{%
+        preamble .value_required:,
+        preamble .code:n = \edef\skdoc@preamble{##1},
+        key .value_required:,
+        key .code:n = \def\skdoc@key{##1}
+    }%
+    \def\skdoc@preamble{}%
+    \def\skdoc@key{#2}%
+    \IfNoValueTF{#1}{}{\keys_set:nn{skdoc@declarefile}{#1}}
+    \tl_new:c{skdoc@output@\skdoc@key}
+    \int_if_exist:cTF{skdoc@output@\skdoc@key @line}{
+        \msg_critical:nnx{skdoc}{key-exists}{\skdoc@key}
+    }{
+        \int_zero_new:c{skdoc@output@\skdoc@key @line}
+    }
+    \IfStrEq{\skdoc@preamble}{}{}{
+        \tl_set:Nx\l_tmpa_tl{\skdoc@preamble}
+        \edef\skdoc@temp{\tl_head:N\l_tmpa_tl}
+        \def\skdoc@preamble@extra{
+            \skdoc@temp\skdoc@temp\space~This~is~file~`#2',~generated~from~`\c_job_name_tl.tex'~(key~`\skdoc@key').
+        }
+    }
+    \expandafter\xdef\csname skdoc@write@#2\endcsname{%
+        \noexpand\msg_log:nnn{skdoc}{wrote-file}{#2}
+        \noexpand\iow_open:Nn\noexpand\skdoc@output{#2}
+        \noexpand\IfStrEq{\skdoc@preamble}{}{}{
+            \noexpand\iow_now:Nx\noexpand\skdoc@output{\skdoc@preamble@extra}
+            \noexpand\iow_now:Nx\noexpand\skdoc@output{\skdoc@preamble}
+        }
+        \noexpand\iow_now:Nx\noexpand\skdoc@output{\noexpand\tl_to_str:c{skdoc@output@\skdoc@key}}
+        \noexpand\iow_close:N\noexpand\skdoc@output
+    }
+    \AfterEndDocument{\csname skdoc@write@#2\endcsname}
+    \group_end:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{environment}{skdoc@verbatim}[1]
+%   {The key of the file being described}
+% This environment does all the actual work for \env{MacroCode}.
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{skdoc@verbatim}{m}{%
+    \iftoggle{skdoc@impl}{\@bsphack}{}
+    \def\skdoc@key{#1}
+    \int_if_exist:cTF{skdoc@output@\skdoc@key @line}{}{
+        \msg_critical:nnx{skdoc}{key-nexists}{\skdoc@key}
+    }%
+    \marginnote{
+        \leavevmode
+        \llap{
+            \scriptsize\color{gray}
+            $\langle$\skdoc@key$\rangle$
+            \makebox[2ex]{\strut}
+        }
+    }
+    \def\verbatim@processline{%
+        \tl_gput_right:cx{skdoc@output@\skdoc@key}{\the\verbatim@line\iow_newline:}%
+        \int_gincr:c{skdoc@output@\skdoc@key @line}%
+        \iftoggle{skdoc@impl}{
+            \noindent\leavevmode%
+            \hspace*{-5ex}
+            \begin{minipage}[c][1ex]{\textwidth}
+                \makebox[4ex]{%
+                    \leavevmode
+                    \tiny\color{lightgray}\hfill%
+                    \int_use:c{skdoc@output@\skdoc@key @line}%
+                }%
+                \hspace*{1ex}%
+                {
+                    \verbatim@font\footnotesize
+                    \the\verbatim@line
+                }
+            \end{minipage}
+            \vskip-.75ex\par
+        }{}
+    }%
+    \let\do\@makeother\dospecials\catcode`\^^M\active%
+    \iftoggle{skdoc@impl}{
+        \frenchspacing\@vobeyspaces
+    }{}
+    \verbatim@start%
+}{%
+    \iftoggle{skdoc@impl}{\@esphack}{}%
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{MacroCode}[1]
+%   {The key of the file being described}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{MacroCode}{m}{
+    \iftoggle{skdoc@impl}{
+        \vspace{.2\baselineskip}
+        \par\noindent
+    }{}
+    \skdoc@verbatim{#1}
+}{
+    \endskdoc@verbatim
+    \iftoggle{skdoc@impl}{
+        \vspace{.5\baselineskip}
+    }{}
+}
+%    \end{macrocode}
+% \end{environment}
+%
+% \subsubsection{Reading a preamble}
+% \begin{macro}{\PreambleTo}[2]
+%   {A token to which we will save the preamble}
+%   {File to read the preamble from}
+% Read preamble from a document and store in variable.
+%    \begin{macrocode}
+\DeclareDocumentCommand\PreambleTo{mm}{%
+    \group_begin:
+    \msg_info:nnn{skdoc}{read-preamble}{#2}
+    \ior_open:Nn\skdoc@input{#2}
+    \bool_until_do:nn{\ior_if_eof_p:N\skdoc@input}{%
+        \tl_if_empty:NTF\skdoc@temptl{}{%
+            \tl_put_right:Nx\skdoc@temptl{\iow_newline:}
+        }
+        \tl_clear:N\l_tmpb_tl
+        \ior_get_str:NN\skdoc@input\l_tmpa_tl
+        \tl_put_right:Nx\l_tmpb_tl{\tl_head:N\l_tmpa_tl}
+        \IfStrEq{\tl_to_str:N\l_tmpb_tl}{\@percentchar}{%
+            \tl_set_eq:NN\l_tmpb_tl\skdoc@temptl
+            \tl_concat:NNN\skdoc@temptl\l_tmpb_tl\l_tmpa_tl
+        }{%
+            \ior_close:N\skdoc@input
+        }
+    }
+    \xdef#1{\tl_to_str:N\skdoc@temptl}
+    \group_end:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\SelfPreambleTo}[1]
+%   {A token to which we will save the preamble}
+% Shorthand to read preamble from current document.
+%    \begin{macrocode}
+\DeclareDocumentCommand\SelfPreambleTo{m}{%
+    \PreambleTo{#1}{\c_job_name_tl}%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Styling}
+% \subsubsection{Colors}
+% First, we redefine a couple of colors from \pkg{ydoc} as well as
+% defining a couple for ourselves.
+%    \begin{macrocode}
+\definecolorset{RGB}{}{}{
+    section,11,72,107;
+    extlink,73,10,61;
+    intlink,140,35,24;
+    sharp,250,105,0;
+    bright,198,229,217;
+    macrodesc,73,10,61;
+    keydesc,140,35,24;
+    macroimpl,73,10,61;
+    meta,11,72,107;
+    scriptcolor,140,35,24;
+    optioncolor,73,10,61;
+    opt,73,10,61
+}
+%    \end{macrocode}
+% \subsubsection{Fonts}
+% Then we redefine a couple of the KOMA-script font commands to use
+% our newly defined colors, along with other fixes.
+%    \begin{macrocode}
+\RenewDocumentCommand\descfont{}{\sffamily\fontseries{sb}}
+\RenewDocumentCommand\sectfont{}{\sffamily\fontseries{sb}}
+\addtokomafont{minisec}{\bfseries}
+\addtokomafont{paragraph}{\color{section}}
+\addtokomafont{section}{\color{section}}
+\addtokomafont{subsection}{\color{section}}
+\addtokomafont{subsubsection}{\color{section}}
+\addtokomafont{descriptionlabel}{\color{section}}
+\addtokomafont{sectionentry}{\rmfamily\bfseries}
+\addtokomafont{sectionentrypagenumber}{\rmfamily\bfseries}
+%    \end{macrocode}
+% \subsubsection{Configuring \pkg{hyperref}}
+% Finally, we set up \pkg{hyperref} to also use our colors.
+%    \begin{macrocode}
+\hypersetup{
+    colorlinks=true,
+    linkcolor=intlink,
+    anchorcolor=intlink,
+    citecolor=black,
+    urlcolor=extlink
+}
+%    \end{macrocode}
+%
+% \subsection{Documentation macros}
+% We can now start defining the documentation macros.
+%
+% \subsubsection{Inline referencing}
+% We introduce a couple of macros for referencing various constructs
+% in running text, \emph{i.e.} \cs{cs}-like macros. The starred
+% variants will not index the use, the non-starred variants will.
+%
+% First, though, we introduce a toggle letting us permanently disable
+% indexing inside \emph{e.g.} the table of contents and index.
+%    \begin{macrocode}
+\newtoggle{skdoc@noindex}
+\togglefalse{skdoc@noindex}
+%    \end{macrocode}
+% \begin{macro}{\cs}[2]
+%   {True if this is the starred variant}
+%   {The macro name to be typeset}
+% The \cs{cs} macro typesets a macro.
+%    \begin{macrocode}
+\DeclareDocumentCommand\cs{sm}{
+    \texttt{\char`\\#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@macro{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\env}[2]
+%   {True if this is the starred variant}
+%   {The environment name to be typeset}
+% The \cs{env} macro typesets an environment.
+%    \begin{macrocode}
+\DeclareDocumentCommand\env{sm}{
+    \texttt{#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@environment{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\pkg}[2]
+%   {True if this is the starred variant}
+%   {The package name to be typeset}
+% The \cs{pkg} macro typesets a package.
+%    \begin{macrocode}
+\DeclareDocumentCommand\pkg{sm}{
+    \textsf{#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@package{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\opt}[2]
+%   {True if this is the starred variant}
+%   {The option name to be typeset}
+% The \cs{opt} macro typesets an option
+%    \begin{macrocode}
+\DeclareDocumentCommand\opt{sm}{
+    \texttt{#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@option{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\bib}[2]
+%   {True if this is the starred variant}
+%   {The \hologo{BibTeX} entry type name to be typeset}
+% The \cs{bib} macro typesets a \hologo{BibTeX} entry type.
+%    \begin{macrocode}
+\DeclareDocumentCommand\bib{sm}{
+    \texttt{@#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@bibentry{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\thm}[2]
+%   {True if this is the starred variant}
+%   {The theme name to be typeset}
+% The \cs{thm} macro typesets a theme of some sort.
+%    \begin{macrocode}
+\DeclareDocumentCommand\thm{sm}{
+    \textrm{#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@theme{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\file}[2]
+%   {True if this is the starred variant}
+%   {The file name to be typeset}
+% The \cs{file} macro typesets a file name.
+%    \begin{macrocode}
+\DeclareDocumentCommand\file{sm}{
+    \texttt{#2}
+    \iftoggle{skdoc@noindex}{}{
+        \IfBooleanTF{#1}{}{\index@file{#2}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Descriptional macros}
+% A range of descriptional macros are made available by the \pkg{ydoc}
+% package, but we need to redefine and extend them.
+%
+% We begin with extending.
+% \begin{macro}{\Describe@Macro}[1]
+%   {The macro name, including leading backslash}
+% The \cs{Describe@Macro} macro is changed to typeset its agument in
+% a \cs{marginnote} instead of an \cs{fbox}.
+%    \begin{macrocode}
+\def\Describe@Macro#1{%
+    \endgroup
+    \edef\name{\expandafter\@gobble\string#1}%
+    \global\@namedef{href@desc@\name}{}%
+    \immediate\write\@mainaux{%
+        \global\noexpand\@namedef{href@desc@\name}{}%
+    }%
+    \hbox\y@bgroup
+    \@ifundefined{href@impl@\name}{}{\hyperlink{impl:\name}}%
+    {%
+        \hbox{
+            \vbox to 0pt{
+                \vss\hbox{
+                    \raisebox{4ex}{\hypertarget{desc:\name}{}
+                }
+            }
+        }%
+        \marginnote{\llap{\PrintMacroName{#1}}}
+        }%
+    }%
+    \ydoc@macrocatcodes
+    \macroargsstyle
+    \read@Macro@arg
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\descframe}[1]
+%   {Contents to be framed}
+% Similarly, \cs{descframe} is changed to produce an \cs{mbox}
+% instead of an \cs{fbox}.
+%    \begin{macrocode}
+\def\descframe#1{%
+    \mbox{\hspace*{1.5\descsep}#1\hspace*{2\descsep}}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\PrintMacroName}[1]
+%   {Macro name to be printed}
+% \cs{PrintMacroName} is hooked to also index the macro name while
+% printing it.
+%    \begin{macrocode}
+\let\old@PrintMacroName\PrintMacroName
+\DeclareDocumentCommand\PrintMacroName{m}{%
+    \index@macro*{\expandafter\@gobble\string#1}
+    \old@PrintMacroName{#1}
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\PrintEnvName}[2]
+%   {Either \cs{end} or \cs{begin}}
+%   {Name of the environment to be printed}
+% Similarly to \cs{PrintMacroName}, the \cs{PrintEnvName} is hooked
+% to index the environment when printing the \cs{begin} part of the
+% environment.
+%    \begin{macrocode}
+\let\old@PrintEnvName\PrintEnvName
+\def\PrintEnvName#1#2{
+    \ifx#1\begin
+        \edef\skdoc@temp{\noexpand\index@environment*{#2}}
+        \skdoc@temp
+    \fi
+    \old@PrintEnvName{#1}{#2}
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\DescribeEnv}[2]
+%   {Environment body or \cs{NoValue}}
+%   {Environment name}
+%    \begin{macrocode}
+\DeclareDocumentCommand\DescribeEnv{om}{
+    \medskip\par\noindent
+    \marginnote{
+        \envcodestyle
+        \hfill\llap{\PrintEnvName{\begin}{#2}}\mbox{}\\
+        \IfNoValueTF{#1}{}{\hfill\llap{\MacroArgs#1}\mbox{}\\}
+        \hfill\llap{\PrintEnvName{\end}{#2}}\mbox{}\\
+    }
+    \begingroup
+    \def\after@Macro@args{\endDescribeEnv}
+    \y@bgroup
+    \ydoc@macrocatcodes
+    \macroargsstyle
+    \read@Macro@arg
+}
+\DeclareDocumentCommand\endDescribeEnv{}{
+    \endgroup
+    \smallskip\par\noindent
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% Then we add a few of our own. For instance, we add macros to
+% typeset descriptions of options. We also undefine the \cs{optpar}
+% macro defined by \pkg{ydoc}, since we supersede it with \cs{Option}.
+%    \begin{macrocode}
+\let\optpar\relax
+%    \end{macrocode}
+% \begin{macro}{\Options}[1]
+%   {A comma-separated list of options}
+%    \begin{macrocode}
+\DeclareDocumentCommand\Options{m}{
+    \clist_set:Nn\l_tmpa_clist{#1}
+    \marginnote{
+        \clist_map_inline:Nn\l_tmpa_clist{
+            \index@option*{####1}
+            \hfill
+            \llap{\textcolor{opt}{\opt{####1}}}
+            \mbox{}\\
+        }
+    }
+    \nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Option}[1]
+%   {And option}
+%    \begin{macrocode}
+\DeclareDocumentCommand\Option{m}{
+    \Options{#1}
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro*}{\skdoc@WithValues@peek}
+%    \begin{macrocode}
+\def\skdoc@WithValues@peek{
+    \ifx\@let@token\AndDefault\else\par\noindent\nobreak\fi
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro}{\WithValues}[1]
+%   {Values of a key-value option}
+% The \cs{WithValues} macro peeks ahead to see if there's an
+% \cs{AndDefault} macro further down. It typesets the values of 
+% a key-vaue option
+%    \begin{macrocode}
+\DeclareDocumentCommand\WithValues{m}{
+    \noindent\makebox[\linewidth][l]{\texttt{#1}}
+    \futurelet\@let@token\skdoc@WithValues@peek
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\AndDefault}[1]
+%   {The value of a key-value option}
+% Typesets the default value of a key-value option. To the far
+% right of the line.
+%    \begin{macrocode}
+\DeclareDocumentCommand\AndDefault{m}{
+    \llap{\textcolor{gray}{\texttt{(#1)}}}\par\noindent\nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% Similar macros are provided for \hologo{BibTeX} entries.
+% \begin{macro}{\BibEntry}[1]
+%   {The name of the \hologo{BibTeX} entry}
+%    \begin{macrocode}
+\DeclareDocumentCommand\BibEntry{m}{
+    \marginnote{
+        \index@bibentry*{#1}
+        \hfill\llap{\textcolor{macrodesc}{\bib{#1}}}
+    }
+    \nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\WithFields}[2]
+%   {Optional fields}
+%   {Mandatory fields}
+%    \begin{macrocode}
+\DeclareDocumentCommand\WithFields{om}{
+    \noindent\makebox[\linewidth]{
+        \texttt{#2}
+        \IfNoValueTF{#1}{}{
+            \textcolor{gray}{\texttt{,#2}}
+        }
+    }
+    \par\noindent\nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% A macro for describing themes is supplied.
+% \begin{macro}{\Theme}[1]
+%   {The theme name}
+%    \begin{macrocode}
+\DeclareDocumentCommand\Theme{m}{
+    \marginnote{
+        \index@theme*{#1}
+        \hfill\llap{\textcolor{macrodesc}{\thm{#1}}}
+    }
+    \nobreak\par\noindent\nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% And finally, a macro for describing files is provided.
+% \begin{macro}{\DescribeFile}[1]
+%   {The filename}
+%    \begin{macrocode}
+\DeclareDocumentCommand\DescribeFile{m}{
+    \marginnote{
+        \index@file*{#1}
+        \hfill\llap{\textcolor{macrodesc}{\file{#1}}}
+    }
+    \nobreak\par\noindent\nobreak
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Missing commands}
+% Descriptional commands for \hologo{BibTeX} entry types and themes
+% are not yet implemented.
+%
+% Lastly, we define an envionment for showing examples. It's
+% rediculously simple, really.
+% \begin{environment}{example}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{example}{}{
+    \minisec{Example:}
+}{}
+%    \end{macrocode}
+% \end{environment}
+%
+% \subsubsection{Implementation environment}
+% We define environments that encase the implementation of macros,
+% environments, options, \hologo{BibTeX} entry types and themes.
+% Watch out---there's a lot of duplicate code here.
+% \begin{environment}{macro}[3]
+%   {True if this is the starred variant}
+%   {Name of the macro being implemented}
+%   {If given, the number of arguments that
+%            \cs{macro@impl@args} will read}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{macro}{smo}{%
+    \@bsphack
+    \index@macro!{\expandafter\@gobble\string#2}
+    \@macroname{#2}%
+    \IfBooleanTF{#1}{
+        \IfNoValueTF{#3}{}{
+            \int_compare:nNnTF{#3}>{0}{
+                \cs:w use_none:\prg_replicate:nn{#3}{n}\cs_end:
+            }{}
+        }
+    }{
+        \PrintMacroImpl{#2}
+        \IfNoValueTF{#3}{
+            \macro@impl@argline@noarg{(no~arguments)}
+        }{\macro@impl@args[#3]}
+    }%
+}{
+    \let\skdoc@macroname@key\@empty
+    \IfBooleanTF{#1}{}{\@esphack}
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{environment}[3]
+%   {True if this is the starred variant}
+%   {Name of the environment being implemented}
+%   {If given, the number of arguments that
+%            \cs{macro@impl@args} will read}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{environment}{smo}{%
+    \@bsphack
+    \index@environment!{#2}
+    \@environmentname{#2}%
+    \IfBooleanTF{#1}{
+        \IfNoValueTF{#3}{}{
+            \int_compare:nNnTF{#3}>{0}{
+                \cs:w use_none:\prg_replicate:nn{#3}{n}\cs_end:
+            }{}
+        }
+    }{
+        \PrintEnvImplName{#2}
+        \IfNoValueTF{#3}{
+            \macro@impl@argline@noarg{(no~arguments)}
+        }{\macro@impl@args[#3]}
+    }%
+}{
+    \let\skdoc@macroname@key\@empty
+    \IfBooleanTF{#1}{}{\@esphack}
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{option}[3]
+%   {True if this is the starred variant}
+%   {Name of the option being implemented}
+%   {Values this key-value option can take}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{option}{smg}{%
+    \@bsphack
+    \index@option!{#2}
+    \@optionname{#2}%
+    \IfBooleanTF{#1}{}{
+        \PrintEnvImplName{#2}
+        \IfNoValueTF{#3}{
+            \macro@impl@argline@noarg{(option)}
+        }{
+            \macro@impl@argline@noarg{
+                Option~with~values~\texttt{\textcolor{gray}{#3}}
+            }
+        }
+    }%
+}{
+    \let\skdoc@macroname@key\@empty
+    \IfBooleanTF{#1}{}{\@esphack}
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{bibentry}[2]
+%   {True if this is the starred variant}
+%   {Name of the \hologo{BibTeX} entry type being implemented}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{bibentry}{sm}{%
+    \@bsphack
+    \index@bibentry!{\expandafter\@gobble\string#2}
+    \@bibentryname{#2}%
+    \IfBooleanTF{#1}{}{
+        \PrintEnvImplName{#2}
+        \macro@impl@argline@noarg{(\hologoRobust{BibTeX}~entry~type)}
+    }%
+}{
+    \let\skdoc@macroname@key\@empty
+    \IfBooleanTF{#1}{}{\@esphack}
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{theme}[2]
+%   {True if this is the starred variant}
+%   {Name of the theme being implemented}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{theme}{sm}{%
+    \@bsphack
+    \index@theme!{#2}
+    \@themename{#2}%
+    \IfBooleanTF{#1}{}{
+        \PrintEnvImplName{#2}
+        \macro@impl@argline@noarg{(theme)}
+    }%
+}{
+    \let\skdoc@macroname@key\@empty
+    \IfBooleanTF{#1}{}{\@esphack}
+}
+%    \end{macrocode}
+% \end{environment}
+% We also provide starred variants of the environments, which will
+% add the implementation to the index but not print anything.
+% \begin{environment}{macro*}[2]
+%   {Name of the macro being implemented}
+%   {If given, the number of arguments that
+%            \cs{macro@impl@args} will read}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{macro*}{mo}%
+    {\begin{macro}*{#1}[#2]}{\end{macro}}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{environment*}[2]
+%   {Name of the environment being implemented}
+%   {If given, the number of arguments that
+%            \cs{macro@impl@args} will read}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{environment*}{mo}%
+    {\begin{environment}*{#1}[#2]}{\end{environment}}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{option*}[2]
+%   {Name of the option being implemented}
+%   {Values this key-value option can take}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{option*}{mg}%
+    {\begin{option}*{#1}{#2}}{\end{option}}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{bibentry*}[1]
+%   {Name of the \hologo{BibTeX} entry type being implemented}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{bibentry*}{m}%
+    {\begin{bibentry}*{#1}}{\end{bibentry}}
+%    \end{macrocode}
+% \end{environment}
+% \begin{environment}{theme*}[1]
+%   {Name of the theme being implemented}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{theme*}{m}%
+    {\begin{theme}*{#1}}{\end{theme}}
+%    \end{macrocode}
+% \end{environment}
+% And finally, we redefine some of the underlying \pkg{ydoc} macros
+% to behave the way we want them to.
+% For instance, we redefine the commands that print environment and
+% macro implementation names so that they typeset the name i a
+% \cs{marginnote} rather than in an \cs{fbox}.
+% \begin{macro}{\PrintEnvImplName}[1]
+%   {The environment name to be printed}
+%    \begin{macrocode}
+\def\PrintEnvImplName#1{%
+    \par\mbox{}
+    \marginnote{\llap{\implstyle{#1}}}
+    \par
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\PrintMacroImpl}[1]
+%   {The macro name to be printed}
+%    \begin{macrocode}
+\def\PrintMacroImpl#1{%
+    \par
+    \hbox{%
+        \edef\name{\expandafter\@gobble\string#1}%
+        \global\@namedef{href@impl@\name}{}%
+        \immediate\write\@mainaux{%
+            \global\noexpand\@namedef{href@impl@\name}{}%
+        }%
+        \raisebox{4ex}[4ex]{\hypertarget{impl:\name}{}}%
+        \@ifundefined{href@desc@\name}{}{\hyperlink{desc:\name}}%
+        \marginnote{\llap{\PrintMacroImplName{#1}}}%
+    }%
+    \par
+}
+%    \end{macrocode}
+% \end{macro}
+% We also redefine the utility macros belonging to \cs{macro@impl@arg}.
+% \begin{macro*}{\macro@impl@argline}[2]
+%   {The argument number}
+%   {Description of the argument}
+%    \begin{macrocode}
+\def\macro@impl@argline#1#2{%
+    \par\noindent{\texttt{\##1}:~#2\strut}%
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\macro@impl@args}[1]
+%   {The number of arguments to read}
+%    \begin{macrocode}
+\def\macro@impl@args[#1]{%
+    \vspace*{-\baselineskip}
+    \begingroup
+    \let\macro@impl@argcnt\@tempcnta
+    \let\macro@impl@curarg\@tempcntb
+    \macro@impl@argcnt=#1\relax
+    \macro@impl@curarg=0\relax
+    \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
+        \expandafter\macro@impl@arg
+    \else
+        \expandafter\macro@impl@endargs
+    \fi
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\macro@impl@endargs}
+%    \begin{macrocode}
+\def\macro@impl@endargs{
+    \endgroup\par
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\macro@impl@argline@noarg}[1]
+%   {The line to print instead of an argument line}
+% This last macro is a replacement used when there are no arguments
+% or if the implementation is an option or something like that. It
+% behaves pretty much like \cs{macro@impl@args}, but with only one
+% argument to read.
+%    \begin{macrocode}
+\def\macro@impl@argline@noarg#1{%
+    \vspace*{-\baselineskip}
+    \par\noindent{#1\strut}\par\medskip%
+}
+%    \end{macrocode}
+% \end{macro*}
+%
+% \subsection{The index}
+%    \begin{macrocode}
+\prg_new_conditional:Nnn\__skdoc_do_index:{p}{
+    \iftoggle{skdoc@impl}{
+        \prg_return_true:
+    }{
+        \iftoggle{skdoc@in@impl}{
+            \prg_return_false:
+        }{
+            \prg_return_true:
+        }
+    }
+}
+%    \end{macrocode}
+% The index is based on \pkg{glossaries}, and as such the whole
+% process of adding entries to the index is reduced to adding
+% glossary entries. This is done through two wrapper macros around
+% the \cs{newglossaryentry} macro.
+% \begin{macro}{\@index@}[1]
+%   {The key of the index entry}
+%   {The text of the index entry}
+% What \cs{@index@} does is to decide wether we are hiding the
+% implementation part of the documentation (discussed later), and
+% wether we are in the actual implementation or not. If we are in
+% the implementation and aren't printing it, we shouldn't add an
+% index entry.
+%    \begin{macrocode}
+\DeclareDocumentCommand\@index@{mm}{
+    \if_predicate:w\__skdoc_do_index_p:
+        \@index@@{#1}{#2}
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@index@@}[2]
+%   {The key of the index entry}
+%   {The text of the index entry}
+% This macro does the actual adding to the glossary.
+%    \begin{macrocode}
+\DeclareDocumentCommand\@index@@{mm}{
+    \newglossaryentry{index-#1}{
+        type=index,
+        name={#2},
+        description={\nopostdesc},
+        sort={#1}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Adding index entries}
+% These macros add an index entry with different contents depending
+% on the thing (macro, environment, etc.) that is being indexed. They
+% all have non-starred variants which are used by the referring
+% macros (\cs{cs} \emph{et. al}), and starred variants used by the 
+% description macros (the star affects the style of the page number).
+% Each environment first test wether the given entry key exists, and
+% defines a new entry if it doesn't. Then, a usage of the entry is
+% recorded.
+% There is also a exclamation variant that is used by the implementation
+% environments, that typesets a normal use of the entity.
+%
+% Note the duplicate use of \cs{ifglsentryexists} --- this is needed
+% since \cs{@index@} doesn't always add the entity to the index
+% \emph{i.e.} nothing in the implementation is added when we're hiding
+% the implementation.
+% \begin{macro}{\index@macro}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the macro being indexed, without backslash}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@macro{st!m}{
+    \def\skdoc@temp{#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{#3}{\cs*{#3}}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@environment}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the environment being indexed}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@environment{st!m}{
+    \def\skdoc@temp{\string#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{\string#3}{\env*{\string#3}~(environment)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@option}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the option being indexed}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@option{st!m}{
+    \def\skdoc@temp{\string#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{\string#3}{\opt*{\string#3}~(option)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@bibentry}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the \hologo{BibTeX} entry type
+%       being indexed, without initial \texttt{@} sign}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@bibentry{st!m}{
+    \def\skdoc@temp{#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{#3}{\bib*{#3}~(\hologoRobust{BibTeX}~entry~type)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@theme}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the theme being indexed}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@theme{st!m}{
+    \def\skdoc@temp{\string#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{\string#3}{\thm*{\string#3}~(theme)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@package}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the package being indexed}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@package{st!m}{
+    \def\skdoc@temp{\string#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{\string#3}{\pkg*{\string#3}~(package)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\index@file}[3]
+%   {True if this is the starred variant}
+%   {True if this is the exclamation variant}
+%   {The name of the file being indexed}
+%    \begin{macrocode}
+\DeclareDocumentCommand\index@file{st!m}{
+    \def\skdoc@temp{\string#3}
+    \ifglsentryexists{index-\skdoc@temp}{}{
+        \@index@{\string#3}{\file*{\string#3}~(file)}
+    }
+    \if_predicate:w\__skdoc_do_index_p:
+        \IfBooleanTF{#2}{
+            \glsadd[types=index,format=hyperul]{index-\skdoc@temp}
+        }{
+            \IfBooleanTF{#1}{
+                \glsadd[types=index,format=hyperit]{index-\skdoc@temp}
+            }{
+                \glsadd[types=index]{index-\skdoc@temp}
+            }
+        }
+    \fi:
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% Notice the references to \cs{hyperul}? We need to define that as
+% well. It's simple enough. Note that \cs{GlsAddXdyAttribute} isn't
+% called until later.
+% \begin{macro}{\hyperul}[1]
+%   {Word to underline and link}
+%    \begin{macrocode}
+\ProvideDocumentCommand\hyperul{m}{
+    \underline{\hyperup{#1}}
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Displaying the index}
+% Displaying the index is very simple. We begin by defining
+% our own \pkg{glossaries} style.
+%    \begin{macrocode}
+\newglossarystyle{docindex}{
+    \glossarystyle{indexgroup}
+    \renewcommand*{\glspostdescription}{\unskip\leaders\hbox to 2.9mm{\hss.}\hfill\strut}
+    \renewenvironment{theglossary}{
+        \toggletrue{skdoc@noindex}
+        \begin{multicols}{2}
+        \setlength{\parindent}{0pt}
+        \setlength{\parskip}{0pt plus 0.3pt}
+        \let\item\@idxitem
+    }{
+        \end{multicols}
+        \togglefalse{skdoc@noindex}
+    }
+    \renewcommand*{\glossaryentryfield}[5]{
+        \item\glsentryitem{##1}\glstarget{##1}{##2}
+            \ifx\relax##4\relax\else\space(##4)\fi
+            ##3\glspostdescription\space ##5}
+    \renewcommand*{\glsgroupheading}[1]{
+        \IfStrEq{##1}{default}{
+            \item{\descfont\glssymbolsgroupname}
+        }{
+            \item{\descfont\glsgetgrouptitle{##1}}
+        }
+    }
+    \renewcommand*{\glsgroupskip}{
+        \par\vspace{15\p@}\relax
+    }
+}
+%    \end{macrocode}
+% We follow that up by defining the actual glossay, and making sure
+% to run \cs{makeglossaries} when the preamble is complete.
+%    \begin{macrocode}
+\newglossary{index}{ids}{ido}{Index}
+\AtBeginDocument{\makeglossaries}
+%    \end{macrocode}
+% \begin{macro}{\PrintIndex}
+% Finally, we define a command \cs{PrintIndex} that prints the index.
+% Note the preamble that describes how the index page numbers work.
+%    \begin{macrocode}
+\providecommand*\PrintIndex{%
+    \begingroup
+    \renewcommand*{\glossarypreamble}{
+        Numbers~written~in~boldface~refer~to~the~page~where~the~
+        corresponding~entry~is~described;~numbers~underlined~refer~
+        to~the~page~were~the~implementation~of~the~corresponding~
+        entry~is~discussed.~Numbers~in~roman~refer~to~other~
+        mentions~of~the~entry.\par
+    }
+    \printglossary[type=index,style=docindex]
+    \endgroup
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Hacking \pkg{glossaries}}
+% The following redefinition of an internal \pkg{glossaries} macro,
+% provided by \textcite{Talbot13}, makes sure that the underlined
+% and italic page numbers in the index have precedence over the plain
+% nubmer format. In the event that a macro is described and implemented
+% on the same page, the description format (italic) is used.
+% \begin{macro}{\@gls@addpredefinedattributes}
+%    \begin{macrocode}
+\RenewDocumentCommand\@gls@addpredefinedattributes{}{
+    \GlsAddXdyAttribute{hyperit}
+    \GlsAddXdyAttribute{hyperul}
+    \GlsAddXdyAttribute{glsnumberformat}
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{The changelog}
+% The changelog is implemented as a glossary using the
+% \pkg{glossaries} package. We begin by defining a name
+% for general changes, and commands that save the name of
+% the current macro, environment or similar for use by the
+% \cs{changes} macro.
+% \begin{macro}{\generalname}
+%    \begin{macrocode}
+\DeclareDocumentCommand\generalname{}{General}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro*}{\@macroname}[1]
+%   {Name of the macro being described}
+%    \begin{macrocode}
+\DeclareDocumentCommand\@macroname{m}{
+    \def\skdoc@macroname@stylized{\cs*{\expandafter\@gobble\string#1}}
+    \def\skdoc@macroname@key{macro-\expandafter\@gobble\string#1}
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\@environmentname}[1]
+%   {Name of the environment being described}
+%    \begin{macrocode}
+\DeclareDocumentCommand\@environmentname{m}{
+    \def\skdoc@macroname@stylized{\env*{\string#1}}
+    \def\skdoc@macroname@key{env-#1}
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\@optionname}[1]
+%   {Name of the option being described}
+%    \begin{macrocode}
+\DeclareDocumentCommand\@optionname{m}{
+    \def\skdoc@macroname@stylized{\opt*{\string#1}}
+    \def\skdoc@macroname@key{opt-#1}
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\@ebibentryname}[1]
+%   {Name of the \hologo{BibTeX} entry being described}
+%    \begin{macrocode}
+\DeclareDocumentCommand\@bibentryname{m}{
+    \def\skdoc@macroname@stylized{\bib*{\expandafter\@gobble\string#1}}
+    \def\skdoc@macroname@key{bibentry-\expandafter\@gobble\string#1}
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\@themename}[1]
+%   {Name of the theme being described}
+%    \begin{macrocode}
+\DeclareDocumentCommand\@themename{m}{
+    \def\skdoc@macroname@stylized{\thm*{\string#1}}
+    \def\skdoc@macroname@key{thm-#1}
+}
+%    \end{macrocode}
+% \end{macro*}
+% Along with these we also define the variables they affect as empty.
+%    \begin{macrocode}
+\def\skdoc@macroname@stylized{}
+\let\skdoc@macroname@key\@empty
+%    \end{macrocode}
+%
+% \subsubsection{Adding changes}
+% Since the changelog is based on \pkg{glossaries}, adding changes
+% amounts to simply adding a glossary entry.
+% \begin{macro}{\changes}[2]
+%   {The version in which the changes were made}
+%   {A short description of the changes}
+%    \begin{macrocode}
+\DeclareDocumentCommand\changes{mm}{%
+    \@bsphack
+    \ifglsentryexists{#1}{}{
+        \newglossaryentry{#1}{
+            type=changes,
+            name={v#1},
+            description={\nopostdesc},
+            nonumberlist=true
+        }
+    }
+    \ifx\skdoc@macroname@key\@empty
+        \newglossaryentry{#1-general}{
+            type=changes,
+            description={\generalname{}:~#2},
+            parent={#1},
+            sort={0},
+            nonumberlist=true
+        }
+        \glsadd[types=changes]{#1-general}
+    \else
+        \newglossaryentry{#1-\skdoc@macroname@key}{
+            type=changes,
+            description={\skdoc@macroname@stylized{}:~#2},
+            parent={#1},
+            sort={\skdoc@macroname@key},
+            nonumberlist=true
+        }
+        \glsadd[types=changes]{#1-\skdoc@macroname@key}
+    \fi
+    \@esphack
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Displaying the changelog}
+% Displaying the changelog is equally simple. We begin by defining
+% our own \pkg{glossaries} style.
+%    \begin{macrocode}
+\newglossarystyle{changelog}{
+    \glossarystyle{altlist}
+    \renewenvironment{theglossary}{
+        \toggletrue{skdoc@noindex}
+        \begin{multicols}{2}\begin{description}
+    }{
+        \end{description}\end{multicols}
+        \togglefalse{skdoc@noindex}
+    }
+    \renewcommand*{\glossaryentryfield}[5]{
+        \par\vspace{5\p@}\relax
+        \item[\glsentryitem{##1}\glstarget{##1}{##2}]
+                    \mbox{}\par\nobreak\@afterheading
+    }
+    \renewcommand{\glossarysubentryfield}[6]{%
+        \par\hspace*{\itemindent}
+        \glssubentryitem{##2}%
+        \glstarget{##2}{\strut}##4\glspostdescription\space ##6
+    }
+}
+%    \end{macrocode}
+% We follow that up by defining the actual glossay, and making sure
+% to run \cs{makeglossaries} when the preamble is complete.
+%    \begin{macrocode}
+\newglossary{changes}{gls}{glo}{Changes}
+\AtBeginDocument{\makeglossaries}
+%    \end{macrocode}
+% \begin{macro}{\PrintChanges}
+% Finally, we define a command \cs{PrintChanges} that prints the
+% list of changes.
+%    \begin{macrocode}
+\DeclareDocumentCommand\PrintChanges{}{%
+    \begingroup
+    \printglossary[type=changes,style=changelog]
+    \endgroup
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Hiding the implementation}
+% We define commands to hide the implementation from the documentation.
+% Here, the ``implementation'' is understood to be everything between
+% the \cs{Implementation} and \cs{Finale} macros. What we do is disable
+% and/or reset page and section counters for the duration of the
+% implementation, and set a shipout hook that simply discards the pages
+% while we are in the implementation. A consquence of this is that we
+% must force a page break between what's before the implementation and
+% what's after, which might look horrible.
+%
+% Anyway, we define two toggles that keep track of things. One keeps
+% track of wether to (not) hide the implementation, and one keeps track 
+% of wether we are in the implementation or not. These are provided with
+% sensible defaults (\emph{i.e.} true and false, respectively).
+% We also define a counter in which we save the page number we had when
+% the implementation started.
+%    \begin{macrocode}
+\newtoggle{skdoc@impl}
+\newtoggle{skdoc@in@impl}
+\toggletrue{skdoc@impl}
+\togglefalse{skdoc@in@impl}
+\newcounter{skdoc@impl@page}
+%    \end{macrocode}
+% Then we define the shipout hook. Fairly straight-forward.
+%    \begin{macrocode}
+\AtBeginShipout{
+    \iftoggle{skdoc@impl}{}{
+        \iftoggle{skdoc@in@impl}{\AtBeginShipoutDiscard}{}
+    }
+}
+%    \end{macrocode}
+% \begin{macro}{\OnlyDescription}
+% The \cs{OnlyDescription} macro simply toggles the appropriate toggle.
+%    \begin{macrocode}
+\DeclareDocumentCommand\OnlyDescription{}{\togglefalse{skdoc@impl}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Implementation}
+% The \cs{Implementation} macro defines all the sectioning commands
+% to be empty (saving the old ones), clears the page, saves the page
+% number and toggles the appropriate toggle.
+%    \begin{macrocode}
+\DeclareDocumentCommand\Implementation{}{
+    \iftoggle{skdoc@impl}{}{
+        \clearpage
+        \toggletrue{skdoc@in@impl}
+        \let\skdoc@old@part\part
+        \DeclareDocumentCommand\part{som}{}
+        \let\skdoc@old@section\section
+        \DeclareDocumentCommand\section{som}{}
+        \let\skdoc@old@subsection\subsection
+        \DeclareDocumentCommand\subsection{som}{}
+        \let\skdoc@old@subsubsection\subsubsection
+        \DeclareDocumentCommand\subsubsection{som}{}
+        \let\skdoc@old@paragraph\paragraph
+        \DeclareDocumentCommand\paragraph{som}{}
+        \let\skdoc@old@subparagraph\subparagraph
+        \DeclareDocumentCommand\subparagraph{som}{}
+        \setcounter{skdoc@impl@page}{\value{page}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Finale}
+% The \cs{Finale} macro basically just undoes what the 
+% \cs{Implementation} macro did.
+%    \begin{macrocode}
+\DeclareDocumentCommand\Finale{}{
+    \iftoggle{skdoc@impl}{}{
+        \clearpage
+        \togglefalse{skdoc@in@impl}
+        \let\part\skdoc@old@part
+        \let\section\skdoc@old@section
+        \let\subsection\skdoc@old@subsection
+        \let\subsubsection\skdoc@old@subsubsection
+        \let\paragraph\skdoc@old@paragraph
+        \let\subparagraph\skdoc@old@subparagraph
+        \setcounter{page}{\value{skdoc@impl@page}}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Document metadata}
+% \subsubsection{Setting metadata}
+% We override a bunch of the general titlepage macros and add a few
+% of our own. First, we initialize the underlying variables.
+%    \begin{macrocode}
+\let\@ctan\@empty%
+\let\@repository\@empty%
+\let\@plainemail\@empty%
+\let\@email\@empty%
+\let\@version\@empty%
+%    \end{macrocode}
+% Then, we define the actual macros.
+% \begin{macro}{\package}[2]
+%   {A list of key-value options}
+%   {The package name}
+% The \cs{package} macro sets the package name of the documentation.
+% The key-value options are \opt{vcs} and \opt{ctan}.
+%    \begin{macrocode}
+\DeclareDocumentCommand\package{om}{%
+    \keys_define:nn{skdoc@package}{%
+        vcs .value_required:,%
+        vcs .code:n = \repository{##1},%
+        ctan .code:n = \ctan{##1},%
+        ctan .default:n = #2%
+    }%
+    \IfNoValueTF{#1}{}{\keys_set:nn{skdoc@package}{#1}}%
+    \def\@package{#2}%
+    \title{The~\textbf{\pkg*{\@package}}~package}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ctan}[1]
+%   {The name of a package or bundle on CTAN}
+%    \begin{macrocode}
+\DeclareDocumentCommand\ctan{m}{%
+    \def\@ctan{\url{http://www.ctan.org/pkg/#1}}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\repository}[1]
+%   {The URI of an online repository}
+%    \begin{macrocode}
+\DeclareDocumentCommand\repository{m}{%
+    \def\@repository{\url{#1}}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\email}[1]
+%   {The email address of the author}
+%    \begin{macrocode}
+\DeclareDocumentCommand\email{m}{%
+    \def\@plainemail{#1}%
+    \def\@email{\href{mailto:\@plainemail}{\@plainemail}}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\version}[1]
+%   {The version of the package, with no leading ``v''}
+%    \begin{macrocode}
+\DeclareDocumentCommand\version{m}{%
+    \def\@version{#1}%
+}
+%    \end{macrocode}
+% \end{macro}
+% Finally, we set the default package name to \cs{jobname}.
+%    \begin{macrocode}
+\package{\jobname}
+%    \end{macrocode}
+%
+% \subsubsection{Using metadata}
+% We define two macros that read useful metadata; \cs{theversion}
+% and \cs{thepackage}. These are used internally by \cs{maketitle}.
+% \begin{macro}{\theversion}
+%    \begin{macrocode}
+\DeclareDocumentCommand\theversion{}{v\@version}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\thepackage}
+%    \begin{macrocode}
+\DeclareDocumentCommand\thepackage{}{\pkg*{\@package}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\thepkg}
+%    \begin{macrocode}
+\DeclareDocumentCommand\thepkg{}{\thepackage}
+%    \end{macrocode}
+% \end{macro}
+% Additionally we define \cs{skdocpdfsettings}, which is also used
+% by \cs{maketitle}, to include PDF metadata if the documentation
+% is being compiled using \hologo{pdfLaTeX}.
+%    \begin{macrocode}
+\ifpdf
+    \def\skdocpdfsettings{%
+        \hypersetup{%
+            pdfauthor   = {\@author\space<\@plainemail>},
+            pdftitle    = {\@title},
+            pdfsubject  = {Documentation~of~LaTeX~package~\@package},
+            pdfkeywords = {\@package,~LaTeX,~TeX}
+        }%
+    }%
+\else
+    \let\skdocpdfsettings\empty%
+\fi
+%    \end{macrocode}
+%
+% \subsection{General document commands}
+% Most of the general document commands are defined by the
+% \pkg{scrartcl} document class we base ourselves on, but a few
+% of them have to be redefined.
+%
+% \subsubsection{Notices and warnings}
+% We define macros to typeset notices and warnings in the documentation
+% text. Notices are typeset as \Notice{this is a notice}, and warnings
+% are typeset as follows: \Warning{this is a warning}
+% A macro for longer warnings is also available:
+% \LongWarning{This is a longer warning.}
+%
+% \begin{macro}{\Notice}[1]
+%   {Notice text}
+%    \begin{macrocode}
+\DeclareDocumentCommand\Notice{m}{
+    (\emph{\textbf{Note:}~#1})
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Warning}[1]
+%   {Warning text}
+%    \begin{macrocode}
+\DeclareDocumentCommand\Warning{+m}{
+    \vspace{\baselineskip}
+    \par\noindent
+    \fbox{\begin{minipage}[c]{\textwidth}
+        \centering
+        \textbf{Warning:}~#1
+    \end{minipage}}
+    \vspace{\baselineskip}
+    \par
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\LongWarning}[1]
+%   {Warning text}
+%    \begin{macrocode}
+\DeclareDocumentCommand\LongWarning{+m}{
+    \Warning{
+        \par\noindent
+        \begin{minipage}{\textwidth}
+            #1
+        \end{minipage}
+    }
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{The title page}
+% The title page consists of the \cs{maketitle} and the \env{abstract}.
+% We redefine both, inspired slightly by the Prac\TeX\ journal and the
+% \pkg{skrapport} document class.
+% \begin{macro}{\@maketitle}
+%    \begin{macrocode}
+\def\@maketitle{%
+    \newpage
+    \null
+    \begin{flushleft}%
+    {%
+        \Huge\sectfont\@title%
+        \ifx\@ctan\@empty\else%
+            \footnote{Available~on~\@ctan.}%
+        \fi
+        \ifx\@repository\@empty\else%
+            \footnote{Development~version~available~on~\@repository.}%
+        \fi%
+        \par%
+    }%
+    \vskip 1em
+    {%
+        \Large\@author
+        \ifx\@email\@empty\else%
+            \space
+            \newlength\skdoc@minipage@ew%
+            \settowidth{\skdoc@minipage@ew}{%
+                \normalsize{$\lceil${\@email}$\rfloor$}}
+            \begin{minipage}[b]{\skdoc@minipage@ew}
+                \normalsize{$\lceil${\@email}$\rfloor$}
+            \end{minipage}\par%
+        \fi%
+    }%
+    \ifx\@version\@empty\else
+        \vskip .5em
+        {%
+            \large Version~\@version\par%
+        }%
+    \fi
+    \end{flushleft}%
+    \par\bigskip%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\maketitle}
+%    \begin{macrocode}
+\def\maketitle{%
+    \begingroup
+    \skdocpdfsettings
+    \renewcommand\thefootnote{\@fnsymbol\c@footnote}
+    \@maketitle
+    \setcounter{footnote}{0}
+    \skdocpdfsettings
+    \endgroup
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{environment}{abstract}
+%    \begin{macrocode}
+\DeclareDocumentEnvironment{abstract}{}{
+    \newlength\skdoc@abstract@tw%
+    \newlength\skdoc@abstract@aw%
+    \settowidth{\skdoc@abstract@tw}{\descfont\abstractname}%
+    \setlength{\skdoc@abstract@aw}{\the\textwidth-\the\skdoc@abstract@tw-2em}%
+    \begin{minipage}{\textwidth}
+        \begin{minipage}[t]{\skdoc@abstract@tw}%
+            \begin{flushright}%
+                \leavevmode\descfont\abstractname%
+            \end{flushright}%
+        \end{minipage}%
+        \hspace{1em}%
+        \begin{minipage}[t]{\skdoc@abstract@aw}%
+}{
+        \end{minipage}
+    \end{minipage}
+}
+%    \end{macrocode}
+% \end{environment}
+%
+% \subsubsection{Table of contents}
+% The table of contents are redefined to imitate the excellent table
+% of contents of the \pkg{microtype} manual.
+% \begin{macro*}{\l@section}
+%    \begin{macrocode}
+\let\l@section@\l@section
+\def\l@section{\vskip -.75ex\l@section@}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\l@subsection}
+%    \begin{macrocode}
+\def\l@subsection{\vskip.35ex\penalty\@secpenalty\@dottedtocline{2}{1.5em}{2.7em}}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{l@subsubsection}
+%    \begin{macrocode}
+\def\l@subsubsection#1#2{
+    \leftskip 4.2em
+    \parindent 0pt
+    {\let\numberline\@gobble{\small #1~[#2]}}
+}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\l@table}
+%    \begin{macrocode}
+\def\l@table{\@dottedtocline{1}{0pt}{1.5em}}
+%    \end{macrocode}
+% \end{macro*}
+% \begin{macro*}{\l@figure}
+%    \begin{macrocode}
+\def\l@figure{\@dottedtocline{1}{0pt}{1.5em}}
+%    \end{macrocode}
+% \end{macro*}
+%    \begin{macrocode}
+\def\@pnumwidth{1.7em}
+\AtEndDocument{\addtocontents{toc}{\par}}
+%    \end{macrocode}
+% \begin{macro}{\tableofcontents}
+%    \begin{macrocode}
+\let\old@tableofcontents\tableofcontents
+\DeclareDocumentCommand\tableofcontents{}{
+    \toggletrue{skdoc@noindex}
+    \microtypesetup{protrusion=false}
+    \old@tableofcontents
+    \microtypesetup{protrusion=true}
+    \togglefalse{skdoc@noindex}
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Including the LPPL license}
+% A helper macro that includes the LPPL license is also provided.
+% \begin{macro}{\PrintLPPL}
+%    \begin{macrocode}
+\DeclareDocumentCommand\PrintLPPL{}{
+    \begingroup
+    \IfFileExists{lppl.tex}{
+        \let\old@verbatim@font\verbatim@font
+        \def\verbatim@font{
+            \old@verbatim@font\tiny
+        }
+        \def\LPPLicense{\begingroup\small}
+        \def\endLPPLicense{\endmulticols\endgroup}
+        \DeclareDocumentCommand\LPPLsection{m}{
+            \section{####1}
+        }
+        \DeclareDocumentCommand\skdoc@lppl@hack{m}{
+            \end{multicols}
+            \begin{multicols}{2}
+                [\subsection*{####1}][6\baselineskip]
+        }
+        \DeclareDocumentCommand\LPPLsubsection{m}{
+            \subsection*{####1}
+            \let\LPPLsubsection\skdoc@lppl@hack
+            \begin{multicols}{2}
+        }
+        \DeclareDocumentCommand\LPPLsubsubsection{m}{
+            \subsubsection*{####1}
+        }
+        \DeclareDocumentCommand\LPPLparagraph{m}{\paragraph*{####1}}
+        \DeclareDocumentCommand\LPPLfile{m}{\file{####1}}
+        \let\oldmakeatletter\makeatletter
+        \long\def\makeatletter####1\makeatother{
+            \let\makeatletter\oldmakeatletter
+        }
+        \setlength\leftmargini{15pt}
+        \setlength\leftmarginii{12.5pt}
+        \setlength\leftmarginiii{10pt}
+        \newenvironment{enum}[1][0]{
+            \list\labelenumi{
+                \usecounter{enumi}
+                \setcounter{enumi}{####1}
+                \addtocounter{enumi}{-1}
+                \leftmargin 30pt
+                \itemindent-15pt
+                \labelwidth 15pt
+                \labelsep 0pt
+                \def\makelabel########1{########1\hss}}
+        }{\endlist}
+        \input{lppl}
+    }{
+        \msg_warning:nn{skdoc}{no-lppl}
+    }
+    \endgroup
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Cosmetic changes}
+% We perform a couple of cosmetic changes to existing features as
+% well. First, we set a new header/footer style using the KOMA-script
+% \cs{deftripstyle} macro.
+%    \begin{macrocode}
+\deftripstyle{skdoc}%
+    {}{}{}%
+    {\small The~\textbf{\pkg*{\@package}}~package,~v\@version}{}{\small\pagemark}
+\AfterBeginDocument{\pagestyle{skdoc}}
+%    \end{macrocode}
+% We also redefine the section level format to set the section numbers
+% in the margin, much like the \pkg{microtype} manual.
+%    \begin{macrocode}
+\RenewDocumentCommand{\othersectionlevelsformat}{m}{%
+    \makebox[0pt][r]{%
+    \fontfamily{fos}\mdseries\selectfont
+    \csname the#1\endcsname\enskip}%
+}
+%    \end{macrocode}
+% Finally, we actually use \pkg{microtype} in the document class, and
+% make sure to disable it in the verbatim environments.
+% Set up microtype properly
+%    \begin{macrocode}
+\g@addto@macro\@verbatim{\microtypesetup{activate=false}}
+\microtypesetup{expansion,kerning,spacing,tracking}
+\DisableLigatures{family = tt*}
+%    \end{macrocode}
+% We also want numbers on the bibliography headings, if we are loading
+% \pkg{biblatex}.
+%    \begin{macrocode}
+\AtBeginDocument{
+    \ifdefined\defbibheading
+        \defbibheading{bibliography}[\bibname]{\section{#1}}
+    \fi
+}
+%    \end{macrocode}
+% Oh, and we want \cs{marginpar}s on the left, not on the right.
+%    \begin{macrocode}
+\AtBeginDocument{\reversemarginpar}
+%    \end{macrocode}
+%
+% That's it, we're done!
+%    \begin{macrocode}
+\endinput
+%    \end{macrocode}
+% \iffalse
+%</class>
+% \fi
+% \Finale
+%
+% \iffalse
+% \section{Known issues}
+% \fi
+%
+% \PrintChanges
+% \PrintIndex
+% \printbibliography
+% \endinput