% \iffalse meta-comment
%
% Copyright (C) 2018-2019 by Richard Grewe <r-g+tex@posteo.net>
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% 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.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{rgltxdoc.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{rgltxdoc}
%<*package>
    [2019/12/21 v1.3 Common documentation code used for Richard Grewe's packages]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\RequirePackage{rgltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{rgltxdoc.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1}{2019/01/05}{Initial version}
%
% \GetFileInfo{rgltxdoc.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
%
%
% \title{The \pkgname{rgltxdoc} package\thanks{This document
%   corresponds to \pkgname{rgltxdoc}~\fileversion, dated \filedate.
%   The package is available online at
%   \url{http://www.ctan.org/pkg/rgltxdoc} and
%   \url{https://github.com/Ri-Ga/rgltxdoc}.}}
% \author{Richard Grewe\\ \texttt{r-g+tex@posteo.net}}
%
% \maketitle
%
% \section{Introduction}
%
% This package combines several other packages and defines additional
% macros and environments for the purpose of documenting LaTeX code.
% The package mainly serves the purpose of combining the preferences
% used in the author's package documentations. However, others can
% use the package as well. Compatibility between versions cannot be
% guaranteed, however.
%
% \StopEventually{}
%\iffalse
%<*package>
%\fi
%
% \section{Basic Dependencies}
%
% Generally, the documentation can be compiled with \hologo{pdfLaTeX}
% and with \hologo{LuaLaTeX}. Other processors are untested. There is no
% assertion as to how close the \hologo{pdfLaTeX} and \hologo{LuaLaTeX}
% results are to each other.
%    \begin{macrocode}
\RequirePackage{ifluatex}
%    \end{macrocode}
% The \pkgname{etoolbox} package is used to simplify some of the
% package's code.
%    \begin{macrocode}
\RequirePackage{etoolbox}
%    \end{macrocode}
%
% \section{Documentation Input}
%
% The documentation is expected to be written in UTF-8 and in US-English
% language. If \pkgname{babel} is already loaded, it will not be loaded
% again, though. This is to support packages that use other languages
% than English in examples and load \pkgname{babel} accordingly.
% \changes{v1.1}{2019/01/12}{load babel only if not yet loaded}
%    \begin{macrocode}
\ifbool{luatex}{
  \RequirePackage[utf8]{luainputenc}
  \RequirePackage{polyglossia}
  \setmainlanguage[variant=american]{english}
}{
  \RequirePackage[utf8]{inputenc}
  \@ifpackageloaded{babel}{}
    {\RequirePackage[english]{babel}}
}
%    \end{macrocode}
%
% \section{General Appearance}
%
% Code in this section determines the general appearance of
% documentation text and is not specific to documenting \hologo{LaTeX}
% code.
%
% \subsection{Page Layout}
%
% For the page layout, A4 is used for the paper size.
% Border correction established wider left margins for typesetting long
% macro names.
% The |DIV| value is tuned to make the lines wide enough to support
% at least 72~characters in the package documentation code.
%    \begin{macrocode}
\RequirePackage[a4paper,twoside=false]{geometry}
\RequirePackage[DIV=9,BCOR=2.25cm]{typearea}
%    \end{macrocode}
%
% \subsection{Fonts}
%
% For the font, Latin Modern is used.
% Particularly, a light version of the typewriter font is used, such
% that highlighting in listings is possible via a bold font series.
%    \begin{macrocode}
\ifbool{luatex}{
  \RequirePackage{fontspec}
  \setmainfont[SmallCapsFont={* Caps}]{Latin Modern Roman}
  \setsansfont{Latin Modern Sans}
  \setmonofont[Scale=MatchLowercase,
               SmallCapsFont={Latin Modern Mono Caps}]
    {Latin Modern Mono Light}
}{
  \RequirePackage[T1]{fontenc}
  \RequirePackage[lighttt]{lmodern}
%    \end{macrocode}
% With just the above code, a construct like |\cs{foo\meta{bar}}| for
% documenting parameter-dependent macro names fails due to missing
% fonts.  The following two lines fix this.  The first line ensures that
% the typewriter font is loaded (via an |\hbox| with typewriter text
% that is not actually displayed) and the second line declares the
% required font shape (see
% \url{https://tex.stackexchange.com/questions/234003/italic-font-in-lmodern-lighttt}).
%    \begin{macrocode}
  \bgroup\setbox\z@\hbox{\ttfamily ignore}\egroup
  \DeclareFontShape{T1}{lmtt}{m}{it}{<->sub*lmtt/m/sl}{}
}
%    \end{macrocode}
% Finally, \pkgname{microtype} is used for small font improvements.
%    \begin{macrocode}
\RequirePackage{microtype}
%    \end{macrocode}
% We simplify quoting names through the \pkgname{csquotes} package and
% register |"| to produce double opening/closing quotation marks.
%    \begin{macrocode}
\RequirePackage[autostyle=true]{csquotes}
\MakeOuterQuote{"}
%    \end{macrocode}
%
% \subsection{Document Structure}
%
% For the most part, documentations are structured as usual, through a
% title as well as sections and sub-sections and so forth.
% The following two packages improve the possibilities for using lists
% in documentation and visually improve the index through a two-column
% layout.
%    \begin{macrocode}
\RequirePackage[inline]{enumitem}
\RequirePackage[columns=2]{idxlayout}
%    \end{macrocode}
%
% The \pkgname{cleveref} package now requires \pkgname{amsmath} to be
% loaded before. We actually do not need \pkgname{amsmath}, but it also
% should not harm to load it nonetheless to avoid that
% \pkgname{rgltxdoc} now has to be loaded after \pkgname{amsmath}.
% \changes{v1.3}{2019/12/21}{add \pkgname{amsmath} dependency}
%    \begin{macrocode}
\RequirePackage{amsmath}
%    \end{macrocode}
%
% The \pkgname{cleveref} and \pkgname{varioref} packages shall be used
% for referencing structural entities, such as sections and figures.
% Hyperlinks are enabled through \pkgname{hypdoc}.
%    \begin{macrocode}
\RequirePackage{varioref}
\RequirePackage{hypdoc}
\RequirePackage[capitalise,noabbrev,nameinlink]{cleveref}
%    \end{macrocode}
%
%
% \section{Documenting Things}
%
% This package builds on the \pkgname{doc} package for several
% documentation macros, such as |\marg|, |\oarg|, and |\meta|.
%    \begin{macrocode}
\RequirePackage{doc}
%    \end{macrocode}
%
% \subsection{Macros and Environments}\label{sec:MacrosEnvs}
%
% The main macros here, |\NiceDescribeMacro| and |\NiceDescribeEnv|, are
% references to |\DescribeMacro| and |\DescribeEnv| of the \pkgname{doc}
% package, with which they share the purpose.
% The main difference is the appearance in that the "nice" macros
% include the argument list.
%
% \NiceDescribeMacros{2}
%   {\NiceDescribeMacro}{\oarg{idx}\marg{macro}\marg{parameters}}
%   {\NiceDescribeMacros}{\marg{n}\oarg{idx$_1$}\marg{macro$_1$}\marg{params$_1$}\ldots\oarg{idx$_n$}\marg{macro$_n$}\marg{params$_n$}}
% These macros produce a description header for a single macro or,
% respectively, for multiple macros.
% The above two lines are an example of such a description header, which
% is produced by the following code:
% \begin{lstlisting}
% \NiceDescribeMacros{2}
%   {\NiceDescribeMacro}{\oarg{idx}\marg{macro}\marg{parameters}}
%   {\NiceDescribeMacros}{\marg{n}
%     \oarg{idx$_1$}\marg{macro$_1$}\marg{params$_1$}\ldots
%     \oarg{idx$_n$}\marg{macro$_n$}\marg{params$_n$}}
% \end{lstlisting}
% The arguments to the macro are described below:
% \begin{KeyValTable}{ArgDesc}
% \Row{arg=\meta{n},
%   desc={This argument specifies the number of macros to be
%   described.}}
% \Row{arg=\pbox[t]{\linewidth}{\meta{macro},\\\meta{macro$_1$},\ldots,\\\meta{macro$_n$}},
%   desc={These arguments specify the macros for which a description
%     header shall be produced.}}
% \Row{arg=\pbox[t]{\linewidth}{\meta{parameters},\\\meta{params$_1$},\ldots,\\\meta{params$_n$}},
%   desc={These arguments take the sequence that specifies all optional
%     and mandatory arguments of the respective \meta{macro}.
%     Typically, these would be sequences of \cs{oarg} and \cs{marg}
%     instances.}}
% \Row{arg=\pbox[t]{\linewidth}{\meta{idx},\\\meta{idx$_1$},\ldots,\\\meta{idx$_N$}},
%   desc={These optional arguments arguments specify which index entries
%     shall be documented, if they differ from the respective
%     \meta{macro} parameters. This, for instance allows \meta{macro} to
%     be "\texttt{\cs{foo}(*)}" whereas the \meta{idx} parameter could be
%     "\texttt{\cs{foo},\cs{foo}*}".}}
% \end{KeyValTable}
%
% \NiceDescribeMacros{2}
%   {\NiceDescribeEnv}{\oarg{idx}\marg{environment}\marg{parameters}}
%   {\NiceDescribeEnvs}{\marg{n}\oarg{idx$_1$}\marg{env$_1$}\marg{params$_1$}\ldots\oarg{idx$_n$}\marg{env$_n$}\marg{params$_n$}}
% These macros are the counterparts of |\NiceDescribeMacro| and,
% respectively, |\NiceDescribeMacros| when it comes to \hologo{LaTeX}
% environments.  The \meta{environment} (resp.\ \meta{env$_1$} to
% \meta{env$_n$}) parameters are the names of the respective environments.
% A usage example can be found in the implementation part of
% \vref{sec:KeysValues:impl}.
%
% \NiceDescribeMacros{2}
%   {\NiceDescribeCounter}{\oarg{idx}\marg{counter}\marg{qualifiers}}
%   {\NiceDescribeCounters}{\marg{n}\oarg{idx$_1$}\marg{ctr$_1$}\marg{qual$_1$}\ldots\oarg{idx$_n$}\marg{ctr$_n$}\marg{qual$_n$}}
% These macros are analogous to the above macros, but aimed for
% documenting \hologo{LaTeX} counters.
%
% \NiceDescribeMacros{2}
%   {\NiceDescribeKey}{\oarg{idx}\marg{keyname}\marg{keyconfig}}
%   {\NiceDescribeKeys}{\marg{n}\oarg{idx$_1$}\marg{name$_1$}\marg{cfg$_1$}\ldots\oarg{idx$_n$}\marg{name$_n$}\marg{cfg$_n$}}
% These macros are for documenting option keys, for instances of
% packages \pkgname{xkeyval} or \pkgname{pgfkeys}.
% The \meta{keyconfig} is a key-value list in which the keys "vals",
% "init", and "def" can be used to specify the range of
% expected/permitted values, the initial (preset) value, and the default
% (if the key is provided without a value).
%
% \NiceDescribeMacro{\NewNiceDescription}{\marg{type}\marg{efmt}\marg{afmt}\marg{icmd}}
% This macro is used internally for defining the above macros and can be
% used for defining new types of entity descriptions. The following
% table describes the arguments of the macro.
% \begin{KeyValTable}{ArgDesc}
% \Row{arg=\meta{type},
%   desc={The \meta{type} argument is the name of the type of entities.}}
% \Row{arg=\meta{efmt},
%   desc={The \meta{efmt} argument is \hologo{TeX} code that formats the
%     entities in the margin. It can -- and should -- reference the
%     positional parameter |\#1|, through which it is passed the name of
%     the entities.}}
% \Row{arg=\meta{afmt},
%   desc={The \meta{afmt} argument is \hologo{TeX} code that formats the
%     arguments or qualifiers of the entities in the body of the
%     documentation. Analogous to \meta{efmt}, also \meta{afmt} receives
%     the arguments/qualifiers through the positional parameter |\#1|.}}
% \Row{arg=\meta{icmd},
%   desc={The \meta{icmd} argument is \hologo{TeX} code that adds a
%     usage entry for the entity to the index. It takes one argument,
%     through which \meta{icmd} is passed the entity name.}}
% \end{KeyValTable}
% A usage example for |\NewNiceDescription| can be found in the
% implementation below.
%
%
% \paragraph{Implementation}
%
% \begin{macro}{\NewNiceDescription}
% The |\NewNiceDescription|\marg{type}\marg{efmt}\marg{afmt}\marg{icmd}
% macro defines the \cs{NiceDescribe\meta{type}} and
% \cs{NiceDescribe\meta{type}s} macros and saves the \meta{efmt} and
% \meta{afmt} parameters for use by \cs{NiceDescribe\meta{type}s}.
%    \begin{macrocode}
\newcommand\NewNiceDescription[4]{%
  \expandafter\newcommand\csname NiceDescribe#1\endcsname{%
    \csname NiceDescribe#1s\endcsname{1}}%
  \expandafter\newcommand\csname NiceDescribe#1s\endcsname{%
    \rgltxdoc@Desc
      {\csuse{rgltxdoc@@efmt@#1}}
      {\csuse{rgltxdoc@@afmt@#1}}
      {#4}}%
  \csdef{rgltxdoc@@efmt@#1}##1{#2}%
  \csdef{rgltxdoc@@afmt@#1}##1{#3}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NiceDescribeMacro}
% \begin{macro}{\NiceDescribeMacros}
% Macro names are formatted detokenized through |\string|.
% Arguments are formatted as is.
% For the index, |\SpecialUsageIndex| of the \pkgname{doc} package is
% used.
%    \begin{macrocode}
\NewNiceDescription{Macro}{\string#1}{#1}{\SpecialUsageIndex}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\NiceDescribeEnv}
% \begin{macro}{\NiceDescribeEnvs}
% Environment names are formatted with a gray |\begin| and |\end|.
% The arguments of environments are formatted as is.
% For the index, |\SpecialEnvIndex| of the \pkgname{doc} package is
% used.
%    \begin{macrocode}
\NewNiceDescription{Env}
  {\textcolor{gray}{\cs{begin}}\cmarg{#1}\\
   \textcolor{gray}{\cs{end}}\cmarg{#1}}
  {#1}{\SpecialEnvIndex}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\NiceDescribeCounter}
% \begin{macro}{\NiceDescribeCounters}
% Counter names are formatted as is. Arguments or qualifiers should
% usually not be present for counters, but if provided, they would be
% formatted as is.
% The index entry is produced through |\SpecialOtherIndex| (see its
% documentation below).
%    \begin{macrocode}
\NewNiceDescription{Counter}{#1}{#1}
                   {\SpecialOtherIndex{counter}{counters}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\NiceDescribeKey}
% \begin{macro}{\NiceDescribeKeys}
% Option-key names are formatted as is. Arguments are split into the range
% of values (|vals|), the initial value (|init|), and the default value
% (|def| -- the value used when only the key but no value is specified
% to the key). These three can be set as keys.  The index entry is
% produced through |\SpecialOtherIndex| (see its documentation below).
% \changes{v1.2}{2019/05/04}{macros added}
%    \begin{macrocode}
\NewNiceDescription{Key}{#1\,\textrm{=}\,\null}
  {\begingroup
   \newcommand\vmeta[1]{{\normalfont\meta{##1}}}%
   \setkeys[rgltxdoc]{DescOpt}{#1}%
   \setbox\z@\hbox{\qquad\let\rgltxdoc@@sep\@empty
     \rgltxdoc@opt{default}{\cmdrgltxdoc@DescOpt@def}%
     \rgltxdoc@opt{initially}{\cmdrgltxdoc@DescOpt@init}}%
   \parbox[t]{\linewidth-\wd\z@}{%
     \raggedright\cmdrgltxdoc@DescOpt@vals}%
   \box\z@\endgroup}
  {\SpecialOtherIndex{option-key}{option-keys}}
\usepackage{xkeyval,calc}
\define@key[rgltxdoc]{DescOpt}{vals}{%
  \def\cmdrgltxdoc@DescOpt@vals{}\let\rgltxdoc@@sep\@empty%
  \def\do##1{%
    \protected@eappto\cmdrgltxdoc@DescOpt@vals{\rgltxdoc@@sep\texttt{##1}}%
    \def\rgltxdoc@@sep{, }}%
  \docsvlist{#1}}
\define@cmdkey[rgltxdoc]{DescOpt}{init}{}
\define@cmdkey[rgltxdoc]{DescOpt}{def}{}
\newcommand\rgltxdoc@opt[2]{\ifdef{#2}
  {\rgltxdoc@@sep\textsl{#1: }\texttt{#2}%
   \def\rgltxdoc@@sep{, }}
  {}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\SpecialOtherIndex}
% The |\SpecialOtherIndex|\marg{type}\marg{types}\marg{name} macro
% adds an index entry of the given \meta{type} (with plural form
% \meta{types}) and given \meta{name}.
% The macro is a straightforward generalization of |\SpecialEnvIndex|
% (both from \pkgname{hypdoc} and from \pkgname{doc}).
% \changes{v1.2}{2019/05/04}{enabled \pkgname{hypdoc} support}
%    \begin{macrocode}
\newcommand*\SpecialOtherIndex[3]{%
  \@bsphack
  \begingroup
    \HD@target
    \let\HDorg@encapchar\encapchar
    \edef\encapchar usage{%
      \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage}%
    }%
    \rgltxdoc@nohyp@SpecialOtherIndex{#1}{#2}{#3}%
  \endgroup
  \@esphack}
\newcommand\rgltxdoc@nohyp@SpecialOtherIndex[3]{%
  \index{#3\actualchar{\protect\ttfamily#3}
    (#1)\encapchar usage}%
  \index{#2:\levelchar#3\actualchar
    {\protect\ttfamily#3}\encapchar usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rgltxdoc@DescRec}
% The
% |\rgltxdoc@Desc|\marg{efmt}\marg{afmt}\marg{icmd}\marg{n}\oarg{idx}\marg{entity}\marg{args}
% macro formats a description header for \meta{n} entities, of which the
% first are specified through \meta{idx}, \meta{entity}, and
% \meta{args}.
% The margin parts are formatted through the \meta{efmt}\marg{entity}
% macro, the parts in the text body through the \meta{afmt}\marg{args}
% macro. The index entries are created through the
% \meta{icmd}\marg{idx} macro.
% In its implementation, |\rgltxdoc@Desc| builds on |\pbox| from the
% \pkgname{pbox} package. It uses |\rgltxdoc@DescRec| and
% |\rgltxdoc@DescRec@i| (both with the same argument lists) for the
% parsing of arguments and for recursively grabbing the arguments for
% the \meta{n} entities.
% At first, |\rgltxdoc@Desc| creates some vertical space above a
% list of description headers. Afterwards it starts the recursion.
%    \begin{macrocode}
\RequirePackage{pbox}
\newcommand\rgltxdoc@Desc{\medskip\par\noindent\rgltxdoc@DescRec}
\newcommand\rgltxdoc@DescRec[4]{%
  \@ifnextchar[%]
    {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}}%
    {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}[]}}
\def\rgltxdoc@DescRec@i#1#2#3#4[#5]#6#7{%
%    \end{macrocode}
% The following code creates the "margin" text (more precisely, a box to
% the left of the text) and the \meta{args} next to it.
%    \begin{macrocode}
  \rgltxdoc@inmargin{\ttfamily #1{#6}}%
%    \end{macrocode}
% If there is no \meta{args}, then the margin part is moved towards the
% left by a |\quad|.
%    \begin{macrocode}
    {\ifstrempty{#7}{\quad}{}}%
  #2{#7}\relax
%    \end{macrocode}
% Next, the index entries are created, through the comma-separated
% \meta{idx} if this optional argument is given.
%    \begin{macrocode}
  \ifstrempty{#5}%
    {#3{#6}}%
    {\forcsvlist{#3}{#5}}%
%    \end{macrocode}
% Next, we check whether $\meta{n}>1$ and recurse, after a line break,
% if this is satisfied.
%    \begin{macrocode}
  \ifnumgreater{#4}{1}%
    {\\\rgltxdoc@DescRec{#1}{#2}{#3}{#4-1}}%
%    \end{macrocode}
% Finally, the following code ends a list of description headers, taking
% into account that an empty \meta{args} allows the documentation text
% to already start in the same line as the "margin" text.
%    \begin{macrocode}
    {\ifstrempty{#7}{}{\smallskip\par\noindent}\ignorespaces}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rgltxdoc@inmargin}
% The |\rgltxdoc@inmargin|\marg{text}\marg{spacing} macro puts
% \meta{text} into the margin of a newly started paragraph and uses
% \meta{spacing} to put additional horizontal spacing between
% \meta{text} and the left side of the paragraph.
%    \begin{macrocode}
\newcommand\rgltxdoc@inmargin[2]{%
  \leavevmode\null\hbox to\z@{\hss%
    \pbox[t]{3\marginparwidth}{#1}%
    #2}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Arguments, Keys, and Values}
%
% Longer descriptions of macro/environment arguments as well as of keys
% (in key-value lists) and special values can be typeset in tables.
% For a common appearance, the \pkgname{keyvaltable} package is used.
%
% \NiceDescribeEnv{KeyValTable}{\cmarg{KeyDesc}}
% This table is used for describing keys in key-value lists. It has
% three columns: |key|, |desc|, and |default|. The former two have the
% obvious meaning. The latter allows for specifying a default value for
% the key that is used when the key is not provided.
%
% \NiceDescribeEnv{KeyValTable}{\cmarg{ValDesc}}
% This table is used for describing special values (constants). It has
% two columns, |val| and |desc|, with their obvious meaning.
%
% \NiceDescribeEnv{KeyValTable}{\cmarg{ArgDesc}}
% This table is used for describing arguments of macros and environments
% in a structured fashion. It has two columns, |arg| and |desc|.
% Examples of this kind of table can be found in \cref{sec:MacrosEnvs}.
%
% \paragraph{Implementation}\label{sec:KeysValues:impl}
%
% The \pkgname{keyvaltable} package is used for creating the tables that
% document keys, values etc.
%    \begin{macrocode}
\RequirePackage{keyvaltable}
\kvtSet{headbg=black!10,rowbg=white..black!5}
%    \end{macrocode}
% The following code defines the table types. The code should be
% self-explanatory in terms of which columns exist and what their
% alignment and purpose is.
%    \begin{macrocode}
\NewKeyValTable{KeyDesc}{%
  key:  align=l,    format=\texttt, head=\textbf{Key};
  desc: align=X,    head=\textbf{Description and Possible Values};
  default: align=l, format=\texttt, head=\textbf{Default};
}
\NewKeyValTable[showhead=false]{ValDesc}{%
  val:  align=l,    format=\texttt, head=\textbf{Value};
  desc: align=X,                    head=\textbf{Description};
}
\NewKeyValTable[showhead=false]{ArgDesc}{%
  arg:  align=l, head=\textbf{Argument};
  desc: align=X, head=\textbf{Description};
}
%    \end{macrocode}
%
%
% \subsection{Individual Entities}
%
% \begin{macro}{\env}
% The |\env|\marg{environment} macro is the counterpart of |\cs| for
% environment names instead of command names.
%    \begin{macrocode}
\newcommand\env[1]{\texttt{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pkgname}
% The |\pkgname|\marg{package-name} macro typesets package names in a
% uniform font (sans-serif). Moreover, the package checks whether the
% package actually exists, in order to identify embarrassing typos in
% the package name.
%    \begin{macrocode}
\newrobustcmd\pkgname[1]{%
  \IfFileExists{#1.sty}
    {\textsf{#1}}
    {\rgltxdoc@err{Package `#1' not found. Spelling?}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\pkgnames}
% The |\pkgnames|\marg{package-names} macro typesets a comma-separated
% list of package names.
% \changes{v1.2}{2019/05/04}{macro added}
%    \begin{macrocode}
\newcommand\pkgnames{%
  \def\do##1{\pkgname{##1}\def\do####1{, \pkgname{####1}}}%
  \docsvlist}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cmarg}
% \begin{macro}{\coarg}
% The |\cmarg|\marg{const-arg} and |\coarg|\marg{const-arg} macros are
% counterparts for |\marg| and |\oarg|. They format constant argument
% values, though.
%    \begin{macrocode}
\newcommand\cmarg[1]{\mbox{\texttt{\string{#1\string}}}}
\newcommand\coarg[1]{\mbox{\texttt{[#1]}}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% The following enables references to various \hologo{LaTeX} tools in
% the common formatting of their names.
%    \begin{macrocode}
\RequirePackage{hologo}
%    \end{macrocode}
%
%
% \section{Typesetting Examples}
%
% For typesetting examples, the \pkgname{showexpl} package is used.
% Some specific settings for the appearance of the example listings are
% defined and some auxiliary macros simplify special examples.
%
% Generally, code examples shall be typeset in one of two ways:
% \begin{enumerate}
% \item through \env{lstlisting} environments, if only code shall be
%   displayed but no visualization of the code's output;
% \item through \env{LTXexample} environments, if the code as well as its
%   output shall be displayed.
% \end{enumerate}
% Below follows an example of \env{LTXexample} that uses some of the
% features provided by \pkgname{rgltxdoc} on top of \pkgname{showexpl}:
% Labels/references and sections.
% \begin{LTXexample}
%   \section{Test}
%   \label{sec:test}
%   \cref{sec:test} has number~\ref{sec:test}.
% \end{LTXexample}
%
% The following code performs the setup for both (because
% \env{LTXexample} builds on \env{lstlisting}).
%    \begin{macrocode}
\RequirePackage{showexpl}
\lstset{%
  gobble=2,
  frame=trbl,
  backgroundcolor=\color{black!5!white},
  explpreset={%
    numbers=none, columns=flexible, basicstyle=\footnotesize\ttfamily},
  numbers=none, columns=flexible, basicstyle=\footnotesize\ttfamily,
  preset={\rgltxdoc@ExampleFix\rgltxdoc@SaveSecs\small\sffamily},
  overhang=2cm,
  pos=r,
  captionpos=b}
%    \end{macrocode}
% The following enables references to \env{LTXexample} and
% \env{lstlisting} environments through |\cref| and |\vref|.
%    \begin{macrocode}
\crefname{lstlisting}{Listing}{Listings}
%    \end{macrocode}
%
% The following adds the |morepreset| key to \env{listing} environments,
% to allow for extending |preset| code rather than overwriting it.
%    \begin{macrocode}
\lst@Key{morepreset}\relax{\appto\SX@preset{#1}}
%    \end{macrocode}
%
% \begin{macro}{\rgltxdoc@ExampleFix}
% The |\rgltxdoc@ExampleFix| macro performs some setup to enable, to
% some extent, functionality that \pkgname{showexpl} disables or does
% not implement. Concretely,
% \begin{itemize}
% \item the macro simulates labels and references, as long as labels are
%   only referenced after they have been defined (in \env{LTXexample}
%   environments, the normal label and ref mechanism is otherwise
%   disabled);
% \item the macro re-enables the default |\marginpar| macro, which is
%   disabled by \env{LTXexample} presumably due to its suboptimal
%   appearance; for the cases in which the appearance can be justified,
%   the macro is enabled.
% \end{itemize}
%    \begin{macrocode}
\newcommand\rgltxdoc@ExampleFix{%
%    \end{macrocode}
% The fake |\label|\oarg{type}\marg{label} macro takes the optional
% \meta{type}, as the \pkgname{cleveref} package defines it. The macro
% first saves the current label value in a global macro for basic
% |\ref|s. Then, for |\cref|s, the macro also stores the label's type,
% either from \meta{type} or from \pkgname{cleveref}'s routines.
%    \begin{macrocode}
  \renewcommand\label[2][]{%
    \global\csletcs{rgltxdoc@@lbl@##2}{@currentlabel}%
    \ifstrempty{##1}
      {\csxdef{rgltxdoc@@lbltype@##2}{\rgltxdoc@curlbltype}}
      {\csgdef{rgltxdoc@@lbltype@##2}{##1}}}%
%    \end{macrocode}
% The |\ref| and |\cref| macros simply use the values stored by
% |\label|. Note that the multitude of further \pkgname{cleveref} and
% \pkgname{varioref} macros, e.g., |\crefrange| are currently not
% implemented. They would need to be defined when there is actual
% demand for them.
%    \begin{macrocode}
  \def\ref##1{\csuse{rgltxdoc@@lbl@##1}}%
  \def\cref##1{%
    \csuse{cref@\csuse{rgltxdoc@@lbltype@##1}@name}~\ref{##1}}%
  \let\marginpar=\rgltxdoc@@marginpar
}
\let\rgltxdoc@@marginpar=\marginpar
%    \end{macrocode}
% The |\rgltxdoc@curlbltype| and |\rgltxdoc@curlbltype@i| macros are
% auxiliary macros for parsing the content of |\cref@currentlabel|, as set
% by the \pkgname{cleveref} package. The first bracketet value in the
% content is the label type we're interested in here.
% If there's no current label type, we silently use the empty string.
%    \begin{macrocode}
\def\rgltxdoc@curlbltype{%
  \@ifundefined{cref@currentlabel}{}
    {\expandafter\rgltxdoc@curlbltype@i\cref@currentlabel\@nil}}
\def\rgltxdoc@curlbltype@i[#1][#2][#3]#4\@nil{#1}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rgltxdoc@SaveSecs}
% \begin{macro}{\rgltxdoc@RestoreSecs}
% The |\rgltxdoc@SaveSecs| macro saves the section counters and the
% |\rgltxdoc@RestoreSecs| macro restores the values of the section
% counters. This allows one to use sectioning commands in code examples
% without interfering with the section numbering in the documentation.
% The |\rgltxdoc@SaveSecs| macro additionally disables the TOC macro,
% such that example sections do not appear in the documentation's TOC.
% \changes{v1.2}{2019/05/04}{disabled contents lines}
%    \begin{macrocode}
\newcommand\rgltxdoc@SaveSecs{%
  \def\addcontentsline##1##2##3{}%
  \@for\SC:=chapter,section,subsection,subsubsection\do{%
    \@ifundefined{c@\SC}{}
      {\csedef{rgltx@@ctr@\SC}{\the\value{\SC}}%
       \setcounter{\SC}{0}}}}
\newcommand\rgltxdoc@RestoreSecs{%
  \@for\SC:=chapter,section,subsection,subsubsection\do{%
    \@ifundefined{c@\SC}{}
      {\setcounter{\SC}{\csuse{rgltx@@ctr@\SC}}}}}
\patchcmd{\SX@resultInput}{\par}{\rgltxdoc@RestoreSecs\par}
  {}
  {\rgltxdoc@warn{Could not patch showexpl to reset section counters.}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{Shared Internal Code}
%
% \begin{macro}{\rgltxdoc@err}
% \begin{macro}{\rgltxdoc@warn}
% The |\rgltxdoc@err|\marg{error} macro raises the given \meta{error}.
% The |\rgltxdoc@warn|\marg{warning} macro raises the given
% \meta{warning}.
%    \begin{macrocode}
\newcommand\rgltxdoc@err[1]{%
  \PackageError{rgltxdoc}{#1}{}}
\newcommand\rgltxdoc@warn[1]{%
  \PackageWarning{rgltxdoc}{#1}{}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{Future Work}
%
% \begin{itemize}
% \item Add keys, as listed in |KeyDesc| tables to the index
%   automatically.
% \end{itemize}
%
%\iffalse
%</package>
%\fi
% \Finale
\endinput