
% \iffalse meta-comment
%
% Copyright 2016-2022 Brian Dunn
%
% 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.
%
% \fi
%
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{dtxdescribe}
%<package>    [2022/09/08 v1.05 Describe additional object types in source files.]
%
%<*driver>
\documentclass{ltxdoc}

\newcommand*{\mypackagename}{dtxdescribe}
\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.}


\usepackage{iftex}

\ifpdftex

% \usepackage{lmodern}
% \usepackage{libertine}
\usepackage[space]{erewhon}
% \usepackage{sourceserifpro}
\usepackage{cabin}
% \usepackage{sourcesanspro}
% \usepackage{sourcecodepro}
\usepackage{inconsolata}
% \usepackage{tgcursor}
% \usepackage{dejavu}

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp}	% provides \degree, \textquotesingle, \textmu

% copy/paste special unicode symbols:
\input{glyphtounicode}
\pdfglyphtounicode{prime}{2032}% hex
\pdfglyphtounicode{diameter}{2300}% diameter
\pdfglyphtounicode{warningsign}{26A0}% warning sign
\pdfgentounicode=1

\usepackage{newunicodechar}
\newunicodechar{ﬀ}{ff}
\newunicodechar{ﬁ}{fi}
\newunicodechar{ﬂ}{fl}
\newunicodechar{ﬃ}{ffi}
\newunicodechar{ﬄ}{ffl}
% \newunicodechar{°}{\degree}
\newunicodechar{ρ}{\ensuremath{\rho}}
\newunicodechar{⨯}{\texttimes}
\newunicodechar{⁄}{\textfractionsolidus}
% \newunicodechar{®}{\textregistered}
% \newunicodechar{©}{\textcopyright}
\newunicodechar{—}{---}
\newunicodechar{–}{--}
% \newunicodechar{”}{''}
% \newunicodechar{“}{``}
% \newunicodechar{§}{\S}
% \newunicodechar{¶}{\P}
% \newunicodechar{†}{\dag}
\newunicodechar{‡}{\ddag}
\newunicodechar{⚠}{\warningsign}

\else

\usepackage{fontspec}

\setmainfont{Erewhon-Regular}
\setsansfont{Cabin}
\setmonofont{inconsolata}

\fi


\usepackage{etoolbox}

\usepackage{xparse}



\usepackage{microtype}

\usepackage{metalogox}

\usepackage{titleps}

\newpagestyle{pageheadfoot}{
	\headrule
	\sethead{\pkg{\mypackagename}}{}{\thepage}
% 	\renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}}
	\setfoot{}{}{}
}

\pagestyle{pageheadfoot}



% Better spacing for \Describe... margin tags:
\setlength{\marginparsep}{1em}
\setlength{\marginparpush}{.7ex}

\setlength{\parindent}{0em}
\setlength{\parskip}{2ex}

\setlength{\IndexMin}{40ex}



\usepackage{\mypackagename}

\usepackage[bookmarks=true,hidelinks,%
colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,%
pageanchor=true,hyperindex=true,
]{hyperref}

\hypersetup{%
pdfinfo={%
Title={The LaTeX \mypackagename\ package},%
Author={Brian Dunn},%
Subject={Describe additional object types in dtx source files.]},%
Keywords={LaTeX, dtx, source, DescribeMacro}%
}}


\usepackage{cleveref}


\renewenvironment{abstract}
    {
        \bigskip
        \begin{center}
        \textbf{\abstractname}
        \end{center}
%         \small
        \setlength{\parindent}{2em}
        \setlength{\parskip}{0ex}
    }
    {
        \bigskip
    }


\setcounter{IndexColumns}{2}

\DisableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{\mypackagename.dtx}
\end{document}
%
%</driver>
% 
% \fi
%
% \iffalse
%<*package>
% \fi
%
% \CheckSum{1211}
%
% \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{v0.10}{2016/12/08}{\ 2016/12/08 Initial ver}
% \changes{v0.11}{2018/03/30}{\ 2018/03/30}
% \changes{v1.00}{2019/01/11}{\ 2019/01/11}
% \changes{v1.01}{2019/03/22}{\ 2019/03/22}
% \changes{v1.02}{2019/07/16}{\ 2019/07/16}
% \changes{v1.03}{2022/02/01}{\ 2022/02/01}
% \changes{v1.04}{2022/02/01}{\ 2022/02/01}
% \changes{v1.04}{2022/02/01}{\ Corrected copyright date.}
% \changes{v1.05}{2022/09/08}{\ 2022/09/08}




% \GetFileInfo{\mypackagename.sty}
%
% \DoNotIndex{\newcommand,\renewcommand,\addtocounter,\begin,\end,\begingroup,\endgroup}
% \DoNotIndex{\global,\ifbool,\ifthenelse,\isequivalentto,\let}
% \DoNotIndex{\booltrue,\boolfalse}
% \expandafter\DoNotIndex\expandafter{\detokenize{\(,\),\,,\\,\#,\$,\%,\^,\_,\~,\ ,\&,\{,\}}}
%
%
% \thispagestyle{empty}
% \begin{center}
% \vfill
% ^^A \includegraphics[width=.3\linewidth]{\mypackagename_logo.pdf}
% \vfill
% {\Huge The \LaTeX\ \pkg{\mypackagename} Package}
% \bigskip
%
% \fileversion{} --- \filedate
%
% \bigskip
%
% {\small\textcopyright{} 2016--2022} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}
%
% \vspace{.5in}
%
% {\Large \textup{\quicksummary}}
%
% \end{center}
%
% \vfill
%
%
% \begin{abstract}
% \noindent
% The \pkg{doc} package includes tools for describing macros and environments
% in \LaTeX\ source \filenm{.dtx} format.
% The \pkg{dtxdescribe} package adds additional tools for describing
% booleans, lengths, counters, hooks, keys, packages, classes, options,
% files, commands, arguments, and other objects.
% \pkg{dtxdescribe} also works with the regular document classes, for those
% who do not wish to use the \pkg{ltxdoc} class and \filenm{.dtx} files.
%
% Each described item is given a margin tag similar to \cs{DescribeEnv},
% and is listed in the index by itself and also by category.
% Each item may be sorted further by an optional class.
% All index entries except code lines are hyperlinked.
%
% The \env{dtxexample} environment is provided for typesetting example code and its results.
% Contents are displayed verbatim along with a caption and cross-referencing.
% They are then \cs{input} and executed, and the result is shown.
%
% Environments are also provided for displaying verbatim or formatted source code,
% user-interface displays, and sidebars with titles.
%
% Macros are provided for formatting the names of inline \LaTeX\ objects such as
% packages and booleans, as well as program and file names, file types, internet
% objects, the names of certain programs, a number of logos, and inline dashes and slashes.
%
% \pkg{dtxdescribe} works with the \pkg{ltxdoc} class, but also
% works with the standard classes as well, except that
% the \env{macro} and \env{environment} environments are not supported.
% Either \pkg{makeidx} or \pkg{splitidx} may be loaded by the user.
% \pkg{makeidx} will be used by default.
%
% \pkg{dtxdescribe} works with pdf\TeX, \XeTeX, and \LuaTeX, and perhaps other engines
% as well.
% \end{abstract}
%
% \vfill
%
% \clearpage
%
% \tableofcontents
% \listofdtxdexamples
% \listoffigures
% ^^A \listoftables
%
%
%
% \clearpage
%
%^^A \part{dtxdescribe.sty}
%
% \section{Introduction}
%
% The \pkg{doc} package provides \cs{DescribeMacro} and \cs{DescribeEnv}
% to help document new macros and environments.
% Each generates a heading in the documentation, to which \cs{marg},
% \cs{oarg}, and \cs{parg} may be added to identify arguments to be
% passed to the new object.
% Their names are added to the margin, and index entries are added,
% as well as group of entries for environments.
%
% \pkg{dtxdescribe} extends this concept to include a number of
% additional objects, such as booleans and keys.
% To help identify what is being described in the margin, small tags are
% added to the name, such as ``Env'', ``Bool'', or ``Key''.
% These new objects are also listed in the index with the same tag
% shown after their names, and also by group.
% Optional classes may be used to further categories index entries.
%
% Modifications have been made to interact with \pkg{hyperref} to
% provide hyper links for regular index entries as well as the new
% \cs{Describe} entries.
%
% Additional macros are provided to generate colored margin tags and
% warnings, and a new |dtxexample| environment demonstrates code examples.
%
% This documentation and its index show examples of these macros in use.
%
% While the index may appear to be overkill for a small package,
% keep in mind that it includes a number of fictional entries from the examples.
% Extensive cross-referencing can be useful for larger works.
% And, of course, you need not cross-reference everything!


% \clearpage
% \section{Using \pkg{dtxdescribe}}

% Place |\usepackage{dtxdescribe}| in the |.dtx| file's driver section:
% \begin{sourceverb}
% %<*driver>
% \documentclass{ltxdoc}
% 	...
% \usepackage{lmodern}
% 	...
% \usepackage{dtxdescribe}
% 	...
% \usepackage{packagename} % the name of your new package
% 	...
% \usepackage[...]{hyperref}
% \usepackage[...]{cleveref}
% 	...
% %</driver>
% \end{sourceverb}

% Various objects inside the |dtx| file may be described with new
% macros such as \cs{DescribeBoolean}, \cs{DescribeLength}, \cs{DescribeCounter},
% similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}.

% Optional ``classes'' may be assigned to the objects being described, including the new versions
% of \cs{DescribeMacro} and \cs{DescribeEnv}.
% These classes are printed in the margin tag and index entry for each item,
% and also generate additional index entries sorted by class.  This is
% especially useful for key/value sets, where several sets may appear in the same
% document.
%
% The margin tag is not printed if
% \margintag{inside a float}
% the \cs{Describe} macros are used inside a float such as a table,
% but the index entries are still made.
%
% |\margintag{text}| may be used to place a colored tag in
% \margintag{\cs{margintag}\{text\}}
% the margin to summarize paragraph
% contents or draw attention to an index destination.
%
% |\watchout[optional text]| may be used to place a red warning sign
% \watchout[\cs{watchout}{[}text{]}]
% in the margin, along with optional text.
%
% The \env{dtxexample} environment may be used to typeset and execute small pieces of \LaTeX\ code
% as examples of its use.  Optional cross-referencing notes may be used to refer to any
% example float being generated.



% \clearpage
% \section{The macros, and the \env{dtxexample} environment}



% \subsection{Macros and environments}
%
% \DescribeEnv{macro}
% \DescribeEnv{environment}
% These are only provided by the \pkg{ltxdoc} class and \pkg{doc} package
% \watchout[\filenm{.dtx} only]
% to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
% to disable these environments in the resulting \filenm{.sty} file.
% When using the regular document classes, the \env{macro} and
% \env{environment} environments would localize any definitions,
% and \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
%
%
% \DescribeMacro{\DescribeMacro} \oarg{class} \marg{\cs{name}}
%
% The preexisting macro from the \pkg{doc} package is redefined to
%	create hyperlinked index entries, and include an optional class.
%	A margin tag is created and an index entry is made.
%	When the optional class is used, it is displayed in front of
%	the margin tag, and is used to group an index entry by
%	macro name and another index entry by class.
%	An example would be to describe
%	the float creation and caption setup for a new class of float,
%	such as the |dtxexample| float and the example ``photograph'' float
%	both found in the index for this document.
%	See \cref{ex:macro} on \cpageref{ex:macro} for examples.
%
% \DescribeMacro{\DescribeEnv} \oarg{class} \marg{environment name}
%
% The preexisting macro from the \pkg{doc} package is redefined to
%	create hyperlinked index entries, include an optional class, and also to place
%	an `Env' tag in front of the name in the margin.
%	See \cref{ex:environment} on \cpageref{ex:environment}.
%


% \subsection{Arguments}
%
% The \cs{Describe\dots} macros
% may be followed by \cs{marg}, \cs{oarg}, and \cs{parg} to
% describe arguments passed to the macros.
%
% \DescribeMacro{\marg} \marg{text}
%
% Shows a mandatory argument for a macro or environment.
%
% The results looks like \marg{mandatory}.
%

% \DescribeMacro{\oarg} \marg{text}
%
% Shows an optional argument for a macro or environment.
%
% The results looks like \oarg{optional}.
%

% \DescribeMacro{\parg} \marg{text}
%
% Used for ``picture'' arguments, such as coordinates.
%
% The result looks like \parg{coordinate}.
% 

% \DescribeMacro{\DescribeArgument} \oarg{class} \marg{argument}
%
% May be used to describe actions taken when given certain macro arguments.
% These will be given an `Arg' margin tag and will appear in the index.
% The |class| may be used to categorize arguments by their macro or environment name.
% See \cref{ex:arguments} on \cpageref{ex:arguments}.


% \subsection{Booleans, lengths, counters, hooks, keys}
%
% See \cref{ex:common} on \cpageref{ex:common}.
%
% \DescribeMacro{\DescribeBoolean} \oarg{class} \marg{name}
%
% Describes a boolean.  Given a `Bool' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeLength} \oarg{class} \marg{name}
% 
% Describes a length.  Given a `Len' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeCounter} \oarg{class} \marg{name}
% 
% Describes a counter.  Given a `Ctr' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeHook} \oarg{class} \marg{name}
% 
% Describes a hook.  Given a `Hook' tag in the margin and index.
% The |class| may be used to categorize hooks by package.
% Example:
% \begin{sourceverb}
% \DescribeHook[LaTeX]{para/begin}
% \end{sourceverb}
%
%
% \DescribeMacro{\DescribeKey} \oarg{class} \marg{name}
% 
% Describes a key.  Given a `Key' tag in the margin and index.
% The |class| may be used to categorize keys by their kev/value group.
% See \cref{ex:key} on \cpageref{ex:key}.


% \subsection{Packages, classes, options}
%
% \DescribeMacro{\DescribePackage} \oarg{class} \marg{name}
% 
% Describes a package.  Given a `Pkg' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeClass} \oarg{class} \marg{name}
% 
% Describes a \LaTeX\ class.  Given a `Cls' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeOption} \oarg{class} \marg{name}
% 
% Describes a \LaTeX\ package or class option.  Given an `Opt' tag in the margin and index.
%
%

% \subsection{Files, programs, commands}
%
% \DescribeMacro{\DescribeFile} \oarg{class} \marg{name}
% 
% Describes an operating-system file.  Given a `File' tag in the margin and index.
% The filename may have underscores.
%
%
% \DescribeMacro{\DescribeProgram} \oarg{class} \marg{name}
% 
% Describes an operating-system program.  Given a `Prog' tag in the margin and index.
% The program name may have underscores.
%
%
% \DescribeMacro{\DescribeCommand} \oarg{class} \marg{name}
% 
% Describes an operating-system command.  Given a `Cmd' tag in the margin and index.
% The command name may have underscores.
%
%


% \subsection{Other source objects}
%
% \DescribeMacro{\DescribeObject} \oarg{class} \marg{name}
%
% Describes an arbitrary programming object, such as a color definition or caption setup.
% A margin tag and index entry are created with \cs{ttfamily} type.
% When a class is used, it is pre-pended to the margin tag, appended to the
% index entry, and a second index entry is created grouped by class.
% If a macro name is to be described, use \cs{DescribeMacro} instead.
% See \cref{ex:object} on \cpageref{ex:object}.
%
%
% \DescribeMacro{\DescribeOther} \oarg{class} \marg{name}
%
% Describes an arbitrary non-programming object, such as a license agreement
% or credits.  A margin tag and index entry are created in roman type.
% When a class is used, it is pre-pended to the margin tag, appended to the
% index entry, and a second index entry is created grouped by class.
% See \cref{ex:other} on \cpageref{ex:other}.


% \subsection{In a \env{description} environment}
%
% To describe an object using a \env{description} environment, use the following.
% See \cref{ex:description} on \cpageref{ex:description}.

% \DescribeMacro{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}} A description.
%
% \DescribeMacro{\ItemDescribeEnv} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeArgument} \oarg{class} \marg{argument} A description.
%
% \DescribeMacro{\ItemDescribeBoolean} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeLength} \oarg{class} \marg{\cs{name}} A description.
%
% \DescribeMacro{\ItemDescribeCounter} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeHook} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeKey} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribePackage} \oarg{class} \marg{package\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeClass} \oarg{class} \marg{class\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeOption} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeFile} \oarg{class} \marg{file\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeProgram} \oarg{class} \marg{program\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeCommand} \oarg{class} \marg{command\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeObject} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeOther} \oarg{class} \marg{name} A description.


% \subsection{Defaults}

% \DescribeMacro{\DescribeDefault} \marg{value}
% \DescribeDefault{value}
%
% Shows the default value of a \cs{Describe\dots} item, such as displayed here.
% Place this macro immediately after the \cs{Describe\dots} macro and any
% arguments, but before the text description.

% \DescribeMacro{\DescribeDefaultcolor}
% The color of the margin tag used to show the default value.
% This is used by \cs{textcolor} to create the margin tag.
%
% \DescribeDefault{green!50!black}


% \subsection{Nesting}
%
% \DescribeMacro{\shownesting}
%       * \oarg{fraction of \cs{linewidth}} \marg{container name} \marg{contents}
%
% It may be useful to show which objects contain which other objects.
% \cs{shownesting} shows a box enclosing a name for the container,
% and the container's contents.
% \cs{shownesting} be nested, showing boxes inside other boxes,
% which displays how each environment and macro is fit together inside each other.
%
% The optional argument is the fraction of \cs{linewidth} to use for the box,
% from |[0]| to |[1]|.
% The default is |[1]|.
% Each \cs{shownesting} starts its own paragraph, unless the star |*| is used,
% in which case the \cs{shownesting*} appears inline with previous text.
% To place two \cs{shownesting} boxes side-by-side, use optional arguments to
% specify less than full \cs{linewidth} for each box, and use \cs{shownesting*} for
% the second box to place it inline.
%
% See \cref{ex:nesting} on \cpageref{ex:nesting} for an example.


% \subsection{\cs{margintag}, \cs{watchout}}
%
%
% \DescribeMacro{\margintag} \marg{text}
%
% Creates a colored margin tag.
% May be used to identify the topic of a paragraph or the destination of
% an arbitrary index entry.\margintag{\cs{margintag}\{example\}}
%
% \DescribeMacro{\margintagcolor}
% \DescribeDefault{blue!70!black}
% The color of the \cs{margintag}.
% \bigskip
%
% \DescribeMacro{\watchout} \oarg{text}
%
% Creates a red margin tag with a warning sign and
% optional text.  May be used to warn the reader of special instructions, etc.
% \watchout[\cs{watchout}{[}example{]}]
% Without the optional text the warning sign is displayed by itself.
%
% \DescribeMacro{\watchoutcolor}
% \DescribeDefault{red!50!black}
% The color of the \cs{watchout}.


% \subsection{\env{dtxexample} environment}
%
% \DescribeEnv{dtxexample} * \oarg{Notes/cross-references} \marg{caption \& label}
%
% The \env{dtxexample} environment is useful for demonstrating a piece of \LaTeX\ code.
% The example is a simulated float with its own caption and optional label,
% along with optional notes and/or cross-referencing commands.
% The contents of the \env{dtxexample} environment are printed verbatim, then
% loaded and executed as \LaTeX\ code, showing the results just below the printed code.
% In the case of float commands, the floats are generated as expected somewhere nearby,
% and should be given their own labels.
% References to the float's labels may be placed in the optional argument to
% the \env{dtxexample} environment, and will be printed below the code.
%
% The unstarred version places the code inside a
% minipage, forbidding a page break in the middle of the code listing. The starred
% version does not use a minipage. This is required when the code is too large to fit
% on a single page.
%
% See \cref{ex:dtxexample} for a demonstration of how \env{dtxexample} works.
%
% \DescribeMacro{\dtxexamplecodename}
% \DescribeDefault{Code:}
%   The text name of the code section.
%
% \DescribeMacro{\dtxexampleresultname}
% \DescribeDefault{Result:}
%   The text name of the result section.
%
%
% \subsection{\env{noindmacro} and \env{noindenvironment} environments}
%
% These are like \env{macro} and \env{environment}, but not indexed.
% \watchout[\filenm{.dtx} only]
% These only make sense if using the \pkg{ltxdoc} class and \pkg{doc} package
% to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
% to disable these environments in the resulting \filenm{.sty} file.
% When using the regular document classes, \env{noindmacro} and
% \env{noindenvironment} environments should not be used, as they
% would localize any definitions.
% \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
%
% \DescribeEnv{noindmacro} \marg{\cs{name}}
% To document macros which should not be included in the index.
%
% \DescribeEnv{noindenvironment} \marg{name}
% To document environments which should not be included in the index.
%
% Replace
% \begin{sourceverb}
% \begin{macro}{\macroname} \oarg{optional} \marg{mandatory}
% ...
% \end{macro}
% \end{sourceverb}
% with
% \begin{sourceverb}
% \begin{noindmacro}{\macroname} \oarg{optional} \marg{mandatory}
% ...
% \end{noindmacro}
% \end{sourceverb}
% and similarly for \env{noindenvironment}.
%
%
% \subsection{\env{sourceverb}, \env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
%
% \DescribeEnv{sourceverb} \oarg{key/values}
% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em} \qquad Display source code verbatim.
%   Uses optional \pkg{fancyvrb} keys.  Includes |gobble=2| to absorb the
%   leading |%| and space character of a \filenm{dtx} file source format.
%   Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
% \bigskip
%
% \DescribeEnv{fsourceverb} \oarg{key/values}
% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em,frame=lines} \qquad Display source
% code verbatim inside a frame.
% A label may be included using the \optn{label} key.
% Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
% See \cref{ex:fsourceverb} on page \cpageref{ex:fsourceverb}.
% \bigskip
%
% \DescribeEnv{sourcedisplay} Display source code with manual formatting.
% This is not a verbatim environment.
% \cs{textcolor}, \cs{textbf}, and \cs{emph} may be used to highlight text.
% Macros must be escaped with \cs{cs}, characters such as \{ must be
% produced with \cs{\{}, etc.
% \cs{\textbackslash} must be used to force a new line.
% \cs{fquad}, \cs{fqquad}, and \cs{fqqquad}
% may be used to force indenting.
% Because this is \emph{not} a verbatim environment,
% it \emph{can} be used inside a macro.
% See \cref{ex:sourcedisplay} on \cpageref{ex:sourcedisplay}.
%
% \DescribeMacro{\fquad} Single-level indent inside a \env{sourcedisplay}.
%
% \DescribeMacro{\fqquad} Double-level indent inside a \env{sourcedisplay}.
%
% \DescribeMacro{\fqqquad} Triple-level indent inside a \env{sourcedisplay}.
%
% \DescribeEnv{UIdisplay} Displays a user interface, such as a dialog box entry
% or a menu selection.  See \cref{ex:UIdisplay} on \cpageref{ex:UIdisplay}.
% Also see the \cs{UI} macro..
%
% \DescribeMacro{\userentry} \marg{text to enter} \qquad
% Typeset something for the user to enter.
% Also see the \cs{cmds} macro.
%
% \DescribeMacro{\userentryname}
% \DescribeDefault{Enter~$\Rightarrow$}
% Text to tell the user to enter the following item.
% Change with \cs{renewcommand}.
% \bigskip
%
% \DescribeEnv{docsidebar} \oarg{title} \qquad Creates a sidebar within the document.
% See \cref{ex:docsidebar} on \cpageref{ex:docsidebar}.
%
%
%
%
% \subsection{Formatted objects}
%
% Macros to format references to various kinds of objects.
%
% This \pkg{dtxdescribe} package documentation uses \pkg{erewhon}, \pkg{cabin},
% and \pkg{inconsolata}, along with \pkg{metalogox},
% to demonstrate the following font effects.
%
%
% \subsubsection{\LaTeX\ objects}
%
% \DescribeMacro{\pkg} \marg{packagename} \quad Prints as \pkg{packagename}.
%       Also for a \pkg{classname}.

% \DescribeMacro{\cs} \marg{csname}  \quad Prints as \cs{csname}.

% \DescribeMacro{\env} \marg{environment}   \quad Prints as \env{environment}.

% \DescribeMacro{\marg} \marg{argument} \quad Prints \marg{arg}.  Mandatory argument.

% \DescribeMacro{\oarg} \marg{argument} \quad Prints \oarg{arg}.  Optional argument.

% \DescribeMacro{\parg} \marg{argument} \quad Prints \parg{arg}.  Picture-mode argument.

% \DescribeMacro{\ctr} \marg{counter} \quad Prints as \ctr{counter}.

% \DescribeMacro{\bool} \marg{boolean}  \quad Prints as \bool{boolean}. 

% \DescribeMacro{\optn} \marg{option}   \quad Prints as \optn{option},
%       for example to a macro, package, class.

% \DescribeMacro{\TOC} \TOC: Table of contents.

% \DescribeMacro{\LOF} \LOF: List of figures.

% \DescribeMacro{\LOT} \LOT: List of tables.


% \subsubsection{Programs and commands}

% \DescribeMacro{\progcode} Prints as \progcode{inline program code}:
% Escape underscores and other special characters such as \{, \%, \$.

% \DescribeMacro{\prog} Prints as \prog{grep}, \prog{make}: A program name.  Underscores allowed.

% \DescribeMacro{\filenm} Prints as \filenm{file_name}: Underscores allowed.

% \DescribeMacro{\UI} Prints as \UI{General user-interface text.} What the user sees on the display.
% Also see the \env{UIdisplay} environment.
%
% \DescribeMacro{\cmds} Prints as \cmds{Commands to be entered}: What the user enters.
% Escape underscores and other special characters such as \{, \%, \$.
% Also see the \cs{userentry} macro.
%
%
% \subsubsection{File types}
%
% \DescribeMacro{\ODT} \ODT\ OpenDocument Format word processing document

% \DescribeMacro{\SVG} \SVG\ image format

% \DescribeMacro{\PNG} \PNG\ image format

% \DescribeMacro{\GIF} \GIF\ image format

% \DescribeMacro{\JPG} \JPG\ image format

% \DescribeMacro{\EPS} \EPS\ image format

% \DescribeMacro{\PDF} \PDF\ image format

% \DescribeMacro{\DVI} \DVI\ image format
%
%
% \subsubsection{Internet}
%
% \DescribeMacro{\UTF} \UTF: Unicode

% \DescribeMacro{\URL} \URL: Uniform Resource Locator

% \DescribeMacro{\element} \marg{element name}  \quad Prints as \element{element},
%       an \HTML \Slash \CSS\ element

% \DescribeMacro{\attribute} \marg{attribute name} \quad Prints as \attribute{attribute},
%       an \HTML \Slash \CSS\ attribute.
%       pdf\TeX\ and \XeTeX\ only.
%       \textcolor{\watchoutcolor}{Not for \LuaTeX.}

% \DescribeMacro{\attrib} \marg{attribute name} \quad Prints as \attribute{attribute},
%       an \HTML \Slash \CSS\ attribute.
%       pdf\TeX, \XeTeX, or \LuaTeX.

% \DescribeMacro{\HTML} \HTML: Hypertext Markup Language

% \DescribeMacro{\HTMLfive} \HTMLfive: Old-style figure if font supports

% \DescribeMacro{\CSS} \CSS: Cascading Style Sheet

% \DescribeMacro{\CSSthree} \CSSthree: Old-style figure if font supports

% \DescribeMacro{\EPUB} \EPUB: E-book file format
%
%
% \subsubsection{Specific programs}
%
% \DescribeMacro{\TikZ} \TikZ: Package logo

% \DescribeMacro{\CTAN} \CTAN: Comprehensive \TeX\ Archive Network

% \DescribeMacro{\TDS} \TDS: \TeX\ Directory Structure
%
% \DescribeMacro{\MathML} \MathML: Mathematical Markup Language
%
% \DescribeMacro{\MathJax} \MathJax: Math on the web.
%
%
% \subsubsection{Acronyms, brand names, trademarks}
%
% \DescribeMacro{\brand} \marg{name} \quad \brand{Brandname}, \brand{Company Name}

% \DescribeMacro{\acro} \marg{acronym} \quad \acro{acro}: Acronym

% \DescribeMacro{\supregistered} Superscript trademark symbol\supregistered
%
%
%
%
% \subsection{Logos}
%
% Several additional logos are provided.
%
% Also see the \pkg{metalogo} and \pkg{metalogox} packages.
%
% \DescribeMacro{\dviTeX}  \dviTeX
%
% \DescribeMacro{\dviLaTeX}  \dviLaTeX
%
% \DescribeMacro{\pdfTeX}  \pdfTeX
%
% \DescribeMacro{\pdfLaTeX}  \pdfLaTeX
%
% \DescribeMacro{\LuaTeX} \LuaTeX
%
% \DescribeMacro{\LuaLaTeX} \LuaLaTeX
%
% \DescribeMacro{\XeTeX} \XeTeX, with reversed E if \pkg{graphics} is loaded.
%
% \DescribeMacro{\XeLaTeX} \XeLaTeX, with reversed E if \pkg{graphics} is loaded.
%
% \DescribeMacro{\AmS} \AmS
%
% \DescribeMacro{\LyX} \LyX
%
% \DescribeMacro{\BibTeX} \BibTeX
%
% \DescribeMacro{\MakeIndex} \MakeIndex
%
% \DescribeMacro{\ConTeXt} \ConTeXt
%
% \DescribeMacro{\MiKTeX} \MiKTeX
%
%
%
%
% \subsection{Dashes and slashes}
%
% \DescribeMacro{\thinskip} A breakable thin skip.
%
% \DescribeMacro{\endash} An endash: \endash
%
% \DescribeMacro{\emdash} An emdash: \emdash
%
% \DescribeMacro{\thinbrspace} A thin space which allows a line break.
%
% \DescribeMacro{\thinthinbrspace} A very thin space which allows a line break.
%
% \DescribeMacro{\Dash} An unbreakeable thin space, emdash, and breakable thin space:
%   A \Dash B
%
% \DescribeMacro{\dash} An unbreakeable thin space, endash, and breakable thin space:
%   A \dash B
%
% \DescribeMacro{\Slash} An unbreakable very thin space, a slash, and a breakable very thin space:
%
%   \begin{tabular}{rll}
%   Command & Result \\ \hline
%   |A--B| & A--B & (not breakable) \\
%   |A \dash B| & A \dash B & (only breakable before the B) \\
%   |A -- B| & A -- B & (breakable before or after the dash) \\ \hline
%   |A---B| & A---B & (not breakable) \\
%   |A \Dash B| & A \Dash B & (only breakable before the B) \\
%   |A --- B| & A --- B & (breakable before or after the dash) \\ \hline
%   |A/B| & A/B & (not breakable) \\
%   |A \Slash B| & A \Slash B & (only breakable before the B) \\
%   |A / B| & A / B & (breakable before or after the slash) \\
%   |A~/~B| & A~/~B & (not breakable) \\
%   \end{tabular}
%
%
% \clearpage
%
% \section{Examples}


% \begin{dtxexample}{Macros\label{ex:macro}}
% \DescribeMacro{\mymacro} \oarg{optional} \marg{mandatory}
% 	A typical macro definition.
%
% \DescribeMacro[photograph]{\DeclareFloatingEnvironment}
%	Create a photograph float. \bigskip

% \DescribeMacro[photograph]{\captionsetup}
%	Caption settings for a photograph float.

% \DescribeMacro[photograph]{\cnameref}
%	\pkg{cleveref} name for the photograph float.
% \end{dtxexample}
%
%
% The optional class is used to label and group tags and index entries.
% See this document's index entries for examples of this ``photograph''
% class and the \env{dtxexample} class of macros.
%
% The re-defined \cs{DescribeMacro}, \cs{DescribeEnv}, and
% all the following macros create hyperlinked index entries,
% \margintag{hyperlinks}
% along with regular uses of \cs{index}.
%
%
% \clearpage
%
% \begin{dtxexample}{Environment\label{ex:environment}}
% \DescribeEnv{myenvironment} \marg{argument} Short description.
% \end{dtxexample}
%
% The re-defined \cs{DescribeEnv} adds an `Env' tag to the margin,
% \margintag{add'l tags}
% and adds ``(environment)'' to its own index entry.
% Note that environments and all the other new objects
% defined\margintag{index groups}\index{index>by group}\index{group of objects}
% by this package each receives two index entries, one by name,
% and one grouped with others of its kind.

% \Cref{ex:environment} shows descriptive text
% \watchout[too much text]
% on the same line as the \cs{DescribeEnvironment}.
% For macros and environments with many arguments after the name,
% it may be better to place any additional text in a following paragraph.

% \begin{dtxexample}{Second Environment}
% \DescribeEnv[kindofenvironment]{otherenvironment}
% 	\oarg{opt args} \parg{coordinates} A description.
% \end{dtxexample}
%
% The \env{otherenvironment} will be indexed by itself and also
% with \env{myenvironment} under the index entry ``environments'',
% and also under the class |kindofenvironment|.
%
%
% \clearpage
%
% \begin{dtxexample}{Booleans and Counters\label{ex:common}}
% \DescribeBoolean[examples]{sampleboolean} Some description.
%
% \DescribeCounter[examples]{samplecounter} Some description.
% \end{dtxexample}
%
% Most of the new \cs{Describe}\rule{.25in}{.4pt} macros behave like the
% new \cs{DescribeEnv}, placing a tag in the margin, an index entry
% by name, and another index entry by group.
%


% \begin{dtxexample}{Lengths\label{ex:length}}
% \DescribeLength[photograph]{\photowidth} Some description.
% \end{dtxexample}

% Lengths have a leading backslash, but are otherwise described
% the same as the rest of the objects.


% \clearpage
%
%
% \begin{dtxexample}{Packages, Classes, and Options}
% \DescribePackage[examples]{samplepackage}
% 	About a \LaTeX\ package.
%
% \DescribeClass[examples]{sample_class}
% 	About a \LaTeX\ class.
%
% \DescribeOption[examples]{sampleoption}
% 	About an option for a package or class.
% \end{dtxexample}
%
%
% \begin{dtxexample}{Files, Commands, and Programs\label{ex:file}}
% \DescribeFile[bigfiles]{really_big_file.txt} Some description.
%
% \DescribeFile[bigfiles]{another_big_file.txt} Some description.
%
% \DescribeFile{lone_file.txt} Some description.
%
% \DescribeCommand{OS_command} An operating-system command.
%
% \DescribeProgram{program_name} An operating-system program.
% \end{dtxexample}
%
% Filenames, program names, and command names may have underscores,
% such as tested here.
% A class is used to group ``bigfiles'' together in the index.


% \clearpage
%
% \begin{dtxexample}{Keys\label{ex:key}}
% \DescribeKey[groupofkeys]{firstkey} About the first key
% 	of the |groupofkeys| set.
%
% \DescribeKey[groupofkeys]{secondkey} About the second key
% 	of |groupofkeys|.
%
% \DescribeKey[examples]{samplekey} About some key of |otherkeys|.
%
% \DescribeKey[examples]{sampletwokey} About another key of |otherkeys|.
%
% \DescribeKey{lonekey} A key without a class.
% \end{dtxexample}
%
% See the index key groups.
%
%
% \clearpage
%
% \begin{dtxexample}{Arguments\label{ex:arguments}}
% \DescribeArgument[figure]{[H]}
% What happens when a figure is [H]ere.
%
% \DescribeArgument[figure]{[M]}
% What happens when a figure is in the [M]argin.
%
% \DescribeArgument[\cs{mymacro}]{bold}
% What happens when \cs{mymacro} is given the |bold| argument.
% \end{dtxexample}
%
% Arguments behave like keys, and may have an optional class to
% identify their macro or environment, and group their entries
% in the index.
%
% Note the need to use |\cs{mymacro}| for the macro's name.
% \watchout[macro names]
%
%
% \clearpage
%
% \begin{dtxexample}{Object\label{ex:object}}
% \DescribeObject[color]{somecolor}
% 	The color of something.
%
% \DescribeObject[color]{othercolor}
% 	The other color.
%
% \DescribeObject{randomobject} About some random object.
% \end{dtxexample}
%
% Describes an arbitrary programming object, using \cs{ttfamily} text.


% \begin{dtxexample}{Other\label{ex:other}}
% \DescribeOther{license agreement}
%	The following is the fictional license agreement:
%
% \DescribeOther{Before \env{myenvironment}}
% 	Actions to be done \cs{BeforeBeginEnvironment}.
%
% \DescribeOther[otherclass]{Other Item} About the other item.
%
% \DescribeOther[otherclass]{Additional Item} About the add'l item.
% \end{dtxexample}
%
% Describes an arbitrary non-programming object, using roman text.


% \clearpage
%
% \begin{dtxexample}{Description environments\label{ex:description}}
% \begin{description}
% \ItemDescribeMacro[descexamples]{\macroname} Describe the macro.
% \ItemDescribeBoolean[descexamples]{booleanname} Describe the boolean.
% \ItemDescribeLength[descexamples]{\lengthname} Describe the length.
% \ItemDescribeKey[descexamples]{keyname} Describe the key.
% \ItemDescribePackage[descexamples]{package_name} Describe the package.
% \ItemDescribeClass[descexamples]{class_name} Describe the class.
% \ItemDescribeFile[descexamples]{file_name} Describe the file.
% \ItemDescribeProgram[descexamples]{program_name} Describe the program.
% \ItemDescribeCommand[descexamples]{command_name} Describe the class.
% \end{description}
% \end{dtxexample}
%
% Uses a \env{description} environment to describe objects.


% \clearpage
%
% \begin{dtxexample}{Nesting\label{ex:nesting}}
% \shownesting{\env{environmentA}}{
%       \shownesting{\cs{macroB}}{
%           \shownesting{\env{environmentC}}{
%               The contents.
%           }
%       }
% }
%
% \shownesting{\env{sidebyside}}{
%       \shownesting[.35]{minipage}{
%           Left contents.
%       }
%       \hfill \cs{hfill} \hfill
%       \shownesting*[.35]{minipage}{
%           Right contents.
%       }
% }
% \end{dtxexample}
%
% Note the use of the optional arguments to select less than full \cs{linewidth},
% and the starred form for the second box to place it inline with the \cs{hfill} text.


% \clearpage
%
%
% \begin{dtxexample}[See \cref{fig:afigure}]
% 	{\env{dtxexample}\label{ex:dtxexample}}
% \begin{figure}
% 	\centering\fbox{Contents of the figure.}
% 	\caption{A Figure}\label{fig:afigure}
% \end{figure}
% \end{dtxexample}

% \Cref{ex:dtxexample}, typeset above, was created with the following code:
% \begin{sourceverb}
% \begin{dtxexample}[See \cref{fig:afigure}]
%     {\env{dtxexample}\label{ex:dtxexample}}
% \begin{figure}
%     \centering\fbox{Contents of the figure.}
%     \caption{A Figure}\label{fig:afigure}
% \end{figure}
% \end{dtxexample}
% \end{sourceverb}
%
% When the example was created:
% \begin{enumerate}
% \item The ``float'' of type |example| was created,
%	with the caption ``|dtxexample|''
%	and the label |ex:dtxexample|, which points to \cref{ex:dtxexample}.
% \item The code was displayed verbatim.
% \item The code was written to the file |dtxexample_cut.tex|.
% \item The code was \cs{input} from |dtxexample_cut.tex|.
% \item Executing the code created the figure with
%	caption ``A Figure'' and label |fig:afigure|, which
%	points to \cref{fig:afigure}.
% \item The cross-reference to the figure was shown on the optional display line
% 	by the optional argument to \env{dtxexample}.
% \item The starred form of \env{dtxexample} was used to create the closing
%	rule below the code, since a float was being generated and nothing followed the
%	code inline.  An unstarred version would have created an extra rule.
% \end{enumerate}
%
%
% \clearpage
%
%
% \begin{dtxexample}
%   {\env{fsourceverb}\label{ex:fsourceverb}}
% % \begin{fsourceverb}[label=An fsourceverb example]
% % \newcommand{fdosomething}[1][whattodo]{
% %    doing #1
% % }
% % \end{fsourceverb}
% \end{dtxexample}
% (The leading |%| characters would be present in the \filenm{dtx} source.)
% \bigskip

% \begin{dtxexample}
%   {\env{sourcedisplay}\label{ex:sourcedisplay}}
% \begin{sourcedisplay}
% \cs{newcommand}\{dosomething\}[1][\textcolor{red}{whattodo}]\{\\
% \fquad \textcolor{blue}{doing \textcolor{red}{\#1}}\\
% \}
% \end{sourcedisplay}
% \end{dtxexample}
%
% \clearpage
%
% \begin{dtxexample}
%   {\env{UIdisplay}\label{ex:UIdisplay}}
% Select:
% \begin{UIdisplay}
%   \textsf{Preferences $\to$ Plugins $\to$ Files $\to$ HTML}
% \end{UIdisplay}
% For the field
% \begin{UIdisplay}
% Title heading:
% \end{UIdisplay}
% \userentry{H1}
%
% \end{dtxexample}
%
% \clearpage
%
% \begin{dtxexample}
%   {\env{docsidebar}\label{ex:docsidebar}}
% Main text.
%
% More main text.
%
% \begin{docsidebar}[A title]
% An aside, which may help explain something
% incidental to the main text.
% \end{docsidebar}
%
% Additional main text.
% \end{dtxexample}




% \clearpage
%
% \section{Usage notes}
%
% \begin{description}
%
% \item[Placement of \cs{Describe} macros:]
% Typically \LaTeX\ macro and environment definitions are enclosed in
% \env{macro} and \env{environment} environments at their place in the source code.
% \cs{DescribeMacro} and \cs{DescribeEnv} would be used elsewhere in the manual
% to describe how to use the code.  \cs{DescribeBoolean} and such might be at
% their place in the source code, unless they are worthy of discussion for the
% end-user, in which case they should be in the ``User's Manual'' section of the
% document.\footnote{Future versions may include \cs{DeclareBoolean} for
% use at the point where the boolean is defined, creating an index entry
% with a code line number, and \cs{DescribeBoolean} with a page number index entry for
% the related discussion in the User's Manual portion of the document.}
% It may be useful to use \cs{DeclareBoolean} and friends both at the code location
% and also in the User's Manual section.
%
% \item[Extra spaces:] When placing multiple uses of \cs{Describe}, \cs{index}, \cs{margintag}, and
% \cs{watchout} macros
% together, care must be taken to avoid extra space in the printed text where
% these macros occur.
% A trailing percent character may be used to
% avoid the extra space:
% \begin{sourceverb}
% text text text% <-- avoids extra space
% \margintag{A comment.}
% \index{An entry}
% \index{Another entry}
% more inline text
% \end{sourceverb}
%
% \item[Unwanted vertical space:] Other environments nested inside a \env{docsidebar}
% may produce excessive vertical space.  It may be required to insert
% \begin{sourceverb}
% \vspace*{-\baselineskip}
% \end{sourceverb}
%
% \item[\cs{margintag} placement:] To have the margin tag appear next to the first
% line of a paragraph, place the \cs{margintag} or \cs{watchout}
% somewhere after the first few words
% in the paragraph.  The \cs{margintag} may be on its own line,
% and the rest of the paragraph may follow on the next line.
% If too many words are printed before the \cs{margintag},
% the words may wrap to the next line before the tag occurs.
%
% \item[Margin tag overlap:] To keep margin tags in proper alignment,
% use a new paragraph or multiple lines
% between \cs{margintag}, \cs{watchout}, or \cs{Declare} macros
% 
% \item[\cs{Describe} inside floats:] When these macros are used inside a float,
% \margintag{missing tags}\index{margin tag missing}
% the margin tag is supressed (there is no margin in a float), but the
% index entries are still created.
%
% \end{description}





% \clearpage

% \StopEventually{\PrintChanges\PrintIndex}
 


% \section{Code}


% \subsection{Required packages}

% \DescribePackage{makeidx} One of several index programs must be provided.
% \DescribePackage{splitidx} One of several index programs must be provided.
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\AtBeginDocument{
    \@ifpackageloaded{makeidx}{}{
    \@ifpackageloaded{splitidx}{}{
        \RequirePackage{makeidx}
        \makeindex
    }}
}
%    \end{macrocode}

% \DescribePackage{etoolbox} v2.6 or later
%	for \cs{BeforeBeginEnvironment}, \cs{AfterEndEnvironment}
%    \begin{macrocode}
\RequirePackage{etoolbox}[2011/01/03]%
%    \end{macrocode}

% \DescribePackage{xparse} Used for the examples.
%    \begin{macrocode}
\RequirePackage{xparse}
%    \end{macrocode}

% \changes{v1.03}{2021/09/02}{No longer requires \pkg{xifthen}.}

% \DescribePackage{calc} Used for \cs{shownesting}.
%    \begin{macrocode}
\RequirePackage{calc}
%    \end{macrocode}


% \DescribePackage{xcolor} Used for the examples.
%    \begin{macrocode}
\RequirePackage{xcolor}
\definecolor{myurlcolor}{rgb}{0,0,.7}
\definecolor{mylinkcolor}{rgb}{.7,0,0}
%    \end{macrocode}


% \DescribePackage{caption} Used for the examples.
%    \begin{macrocode}
\RequirePackage{caption}
%    \end{macrocode}


% \DescribePackage{newfloat} Used for the examples.
%    \begin{macrocode}
\RequirePackage{newfloat}
%    \end{macrocode}


% \DescribePackage{fancyvrb} Used for the examples.
%    \begin{macrocode}
\RequirePackage{fancyvrb}
%    \end{macrocode}


% \DescribePackage{xstring} Used for \cs{StrSubstitute} for \cs{DescribeFile}.
%    \begin{macrocode}
\RequirePackage{xstring}
%    \end{macrocode}


% \DescribePackage{hyperref}
% If \pkg{hyperref} is loaded, disable some macros in \PDF\ bookmarks:
% \margintag{\PDF\ bookmarks}
% \changes{v1.01}{2019/01/20}{Sanitize \PDF\ bookmarks.}
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{hyperref} package.}
%    \begin{macrocode}
\AtBeginDocument{
    \@ifpackageloaded{hyperref}{
        \pdfstringdefDisableCommands{%
            \def\quad{ }%
            \def\\{ }%
            \def\pkg#1{#1}%
            \def\ctr#1{#1}%
            \def\bool#1{#1}%
            \def\optn#1{#1}%
            \def\env#1{#1}%
            \def\cs#1{\textbackslash#1}%
            \def\,{ }%
            \def\LuaLaTeX{LuaLaTeX}%
            \def\XeLaTeX{XeLaTeX}%
            \def\TeX{TeX}%
            \def\LaTeX{LaTeX}%
            \def\LaTeXe{LaTeX2e}%
            \def\LuaTeX{LuaTeX}%
            \def\LuaLaTeX{LuaLaTeX}%
            \def\XeTeX{XeTeX}%
            \def\AmS{AMS}%
            \def\Dash{ --- }%
            \def\dash{ -- }%
            \def\Slash{/}%
            \def\prog#1{\detokenize{#1}}%
            \def\progcode#1{#1}%
            \def\filenm#1{\detokenize{#1}}%
            \def\brand#1{#1}%
            \def\acro#1{#1}%
            \def\ODT{ODT}%
            \def\SVG{SVG}%
            \def\PNG{PNG}%
            \def\GIF{GIF}%
            \def\JPG{JPG}%
            \def\EPS{EPS}%
            \def\PDF{PDF}%
            \def\DVI{DVI}%
            \def\UTF{UTF}%
            \def\URL{URL}%
            \def\element#1{#1}%
            \def\attribute#1{#1}%
            \def\attrib#1{#1}%
            \def\HTML{HTML}%
            \def\HTMLfive{HTML5}%
            \def\CSS{CSS}%
            \def\CSSthree{CSS3}%
            \def\EPUB{EPUB}%
            \def\TOC{TOC}%
            \def\LOF{LOF}%
            \def\LOT{LOT}%
        }
    }
%    \end{macrocode}
% If \pkg{hyperref} is not loaded, emulate \cs{hyperpage} here.
%    \begin{macrocode}
    {
        \newcommand*{\hyperpage}[1]{#1}
    }
}
%    \end{macrocode}




% ^^A Several versions of the \warningsign symbol:

% ^^A This version relies on the presence of the fourier font:
% ^^A \newcommand*{\TakeFourierOrnament}[1]{{%
% ^^A \fontencoding{U}\fontfamily{futs}\selectfont\char#1}}
% 
% ^^A \newcommand*{\warningsign}{\TakeFourierOrnament{66}}

% ^^A from: http://tex.stackexchange.com/questions/159669/how-to-print-a-warning-sign-triangle-with-exclamation-point
% ^^A This version copy/pastes extraneous characters:
% ^^A \newcommand\warningsign{%
% ^^A  \makebox[1em][c]{%
% ^^A  \makebox[0pt][c]{\raisebox{.1em}{\textbf{\tiny!}}}%
% ^^A  \makebox[0pt][c]{$\bigtriangleup$}}}%


% \DescribePackage{pict2e}
%    \begin{macrocode}
\RequirePackage{pict2e}
\setlength{\unitlength}{1pt}
%    \end{macrocode}

% \begin{macro}{\warningsign} Prints an exclamation point inside a triangle.
%
% Creates a warning sign without relying on the presence of the fourier font.
% During copy/paste, this shows up as a simple exclamation point.
%    \begin{macrocode}
\newcommand*{\warningsign}{%
\begin{picture}(10,9)
\put(4,1){\scriptsize!}
\put(0,0){\line(500,866){5}}
\put(10,0){\line(-500,866){5}}
\put(0,0){\line(1,0){10}}
\end{picture}
}
%    \end{macrocode}
% \end{macro}


% \subsection{Gobbling comment characters}
%
% \begin{macro}{DTXD@gobble}
% The \filenm{.dtx} format uses leading percent characters for
% code to be in the documentation only.  Other classes do not.
% \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
%    \begin{macrocode}
\@ifpackageloaded{doc}{
    \newcommand*{\DTXD@gobble}{2}
}{
    \newcommand*{\DTXD@gobble}{0}
}
%    \end{macrocode}
% \end{macro}


% \subsection{Vertical spacing}
%    \begin{macrocode}
\setlength{\marginparsep}{1em}
\setlength{\marginparpush}{.7ex}

\setlength{\parindent}{0em}
\setlength{\parskip}{2ex}
%    \end{macrocode}
%
% \DescribeLength{\IndexMin} From \pkg{ltxdoc}.
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\ifdef{\IndexMin}
    {\setlength{\IndexMin}{40ex}}
    {\newlength{\IndexMin}}
%    \end{macrocode}


% \subsection{\pkg{ltxdoc} emulation}
%
% If the \pkg{ltxdoc} class is not used, some of its macros are replicated here.
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\@ifclassloaded{ltxdoc}{}{
    \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
    \def\cmd@to@cs#1#2{\char\number`#2\relax}
    \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
    \providecommand\marg[1]{%
        {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
    \providecommand\oarg[1]{%
        {\ttfamily[}\meta{#1}{\ttfamily]}}
    \providecommand\parg[1]{%
        {\ttfamily(}\meta{#1}{\ttfamily)}}
    \providecommand\url{\texttt}
}
%    \end{macrocode}


% \subsection{\pkg{doc} emulation}
%
% If the \pkg{doc} class is not used, some of its macros are replicated here.
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{doc} package.}
%    \begin{macrocode}
\AtBeginDocument{
    \@ifpackageloaded{doc}{}{
        \newenvironment*{macro}[1]{%
            \PackageError{dtxdescribe}
                {The 'macro' environment is only\MessageBreak
                    available when using the doc package\MessageBreak
                    with a .dtx source file}
                {This environment only makes sense for .dtx source.}
        }{}
        \newenvironment*{environment}[1]{%
            \PackageError{dtxdescribe}
                {The 'environment' environment is only\MessageBreak
                    available when using the doc package\MessageBreak
                    with a .dtx source file}
                {This environment only makes sense for .dtx source.}
        }{}
        \def\MacroFont{\fontencoding\encodingdefault
                    \fontfamily\ttdefault
                    \fontseries\mddefault
                    \fontshape\updefault
                    \small}%
        \@ifundefined{actualchar}{\def\actualchar{@}}{}
        \@ifundefined{quotechar}{\def\quotechar{"}}{}
        \@ifundefined{levelchar}{\def\levelchar{!}}{}
        \@ifundefined{encapchar}{\def\encapchar{|}}{}
        \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
        \setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
        \reversemarginpar
        \DeclareRobustCommand\meta[1]{%
            \ensuremath\langle
            \ifmmode \expandafter \nfss@text \fi
            {%
            \meta@font@select
            \edef\meta@hyphen@restore
                {\hyphenchar\the\font\the\hyphenchar\font}%
            \hyphenchar\font\m@ne
            \language\l@nohyphenation
            #1\/%
            \meta@hyphen@restore
            }\ensuremath\rangle
        }
        \def\meta@font@select{\itshape}
    }
}
%    \end{macrocode}


% \subsection{Support macros}

% \begin{macro}{\PrintEnvName} \marg{name} \qquad Prints an environment name.
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\providecommand*{\PrintEnvName}{}
\renewcommand*{\PrintEnvName}[1]
	{\strut{\scriptsize{}Env}\quad\MacroFont#1\ }
%    \end{macrocode}
% \end{macro}



%
% \begin{macro}{\DTXD@printtype} \marg{text}
%
% Used to print the object class in the margin:
%
% \changes{v1.00}{2019/01/09}{Sans tag font.}
%    \begin{macrocode}
\newcommand*{\DTXD@printtype}[1]
	{\raggedleft\strut{\scriptsize\sffamily#1}\quad\MacroFont}
%    \end{macrocode}
% \end{macro}




% \begin{macro}{\usage} \marg{text}
%
% Allow hyperlinks in the ``usage'' index entries:
%
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\providecommand{\usage}{}
\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@origwrindex} Used to bypass \pkg{hyperref} index modifications.
%    \begin{macrocode}
\let\DTXD@origwrindex\@wrindex
%    \end{macrocode}
% \end{macro}



% \begin{macro}{\DTXD@margintag} \marg{class} \marg{name} \marg{margin tag}
%
% Creates the margin tag for the object being described.
%
% The |class| is used to sub-categories keys into their key/value groups.
%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
%    \begin{macrocode}
\newcommand*{\DTXD@margintag}[3]{%
    \@ifundefined{@captype}{% not float?
        \leavevmode%
        \marginpar{%
            {%
                \hbadness=10000%
                \hfuzz=5em%
                \DTXD@printtype{%
                    #3% margintag
                    \ifblank{#1}{}{ [#1]}% class
                }%
                \texttt{#2}% name
            }%
        }% marginpar
    }{}% not float?
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@index}
%	\marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% Creates the index entries for the object being described, where
% name has no backslash or underscore.
%
% The |class| is used to sub-categories keys into their key/value groups.
% |main| prints code lines in the index, and |usage| prints page numbers.
%
%    \begin{macrocode}
\newcommand*{\DTXD@index}[5]{%
%    \end{macrocode}
% The |makeindex| program allows each index entry to call a macro by appending
% a vertical bar and a macro name to each entry.
% \pkg{hyperref} adds a call by \cs{hyperpage} to each index entry, by appending
% the phrase \verb+|hyperpage+ to the entry in the |.idx| file.
% The \pkg{doc} package uses the same mechanism to
% distinguish between code line entries (\verb+|main+) and
% references to the use of a macro (\verb+|usage+).  The problem is that |makeindex|
% can only handle one macro call, but \pkg{hyperref} tries to append its \verb+|hyperpage+
% to the already-existing \verb+|usage+ or \verb+|main+.
%
% The solution used for \pkg{dtxdescribe} is to allow \pkg{hyperref} to modify all
% regular index entries, but use the original definition of \cs{@wrindex}
% for the \cs{Describe}\rule{.25in}{.4pt} macros, before \pkg{hyperref} modified it.
% Then, the \cs{usage} macro, defined above, manually adds the hyperlink.
%
% Below, \cs{@bsphack} and \cs{@esphack} seem to be required for \cs{@wrindex} to work.
% \cs{ignorespaces} is used in addition because \cs{Declare} and \cs{index} entries often
% come in groups.
%    \begin{macrocode}
\@bsphack%
\begingroup%
\DTXD@origwrindex{%
%    \end{macrocode}
% Index by name:
%
% Write the name, the formatted name, the index tag, and the class:
%    \begin{macrocode}
#2\actualchar{\protect\ttfamily#2} % name
(#4)% index tag
\ifblank{#1}{}{ [#1]}% class
\encapchar #5}%
%    \end{macrocode}
% Index by tag and class:
%
% Write the tag and class as a group, under which is the name and the formatted name.
% \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
#4:\levelchar% index tag
\ifblank{#1}{}{[#1]:\levelchar}% class
#2\actualchar{\protect\ttfamily#2}% name
\encapchar #5}%
%    \end{macrocode}
% Possibly index by class and name:
%    \begin{macrocode}
\ifblank{#1}{}{% class given
\begingroup%
\DTXD@origwrindex{%
#1\actualchar[#1]:\levelchar% class
#2\actualchar{\protect\ttfamily#2} % name
(#4)% index tag
\encapchar #5}%
}% class given
% \@esphack%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@margintagindex}
%	\marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% Creates the margin tag and the index entries.
% The |class| is used to sub-categories keys into their key/value groups.
%    \begin{macrocode}
\newcommand*{\DTXD@margintagindex}[5]{%
% \@bsphack%
%    \end{macrocode}
% The margin tag and the name:
%    \begin{macrocode}
\DTXD@margintag{#1}{#2}{#3}%
%    \end{macrocode}
% The index entries:
%    \begin{macrocode}
\DTXD@index{#1}{#2}{#3}{#4}{#5}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DTXD@macroname} \marg{control sequence}
%
% Given a control sequence such as \cs{name}, prints its name without the backslash.
%
% From:
% \href{http://tex.stackexchange.com/questions/42318/removing-a-backslash-from-a-character-sequence}
%	{http://tex.stackexchange.com/questions/42318/\\
%		\hspace*{.5in}removing-a-backslash-from-a-character-sequence}
%    \begin{macrocode}
\begingroup\lccode`\|=`\\
\lowercase{\endgroup\def\removebs#1{\if#1|\else#1\fi}}
\newcommand*{\DTXD@macroname}[1]{\expandafter\removebs\string#1}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@verbatimcmd} \marg{\cs{name}}
%
% While printing to the index file,
% prints the \cs{name} verbatim.
% From \cs{SpecialIndex} in the \pkg{doc} package.
%    \begin{macrocode}
\newcommand*{\DTXD@verbatimcmd}[1]{%
\string\verb\quotechar*\verbatimchar\string#1\verbatimchar%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@cmdmargintagindex}
%	\marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% Creates the margin tag and index entries where name is a \cs{macro}.
%
% \changes{v1.00}{2019/01/09}{Sans tag font.}
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
%    \begin{macrocode}
\newcommand*{\DTXD@cmdmargintagindex}[5]{%
\@bsphack%
%    \end{macrocode}
% Create a margin tag with the name of the macro:
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
%    \begin{macrocode}
\@ifundefined{@captype}{% not float?
\leavevmode%
\marginpar{%
    {%
        \hbadness=10000%
        \hfuzz=5em%
        \DTXD@printtype{%
            #3% margin tag
            \ifblank{#1}{}{ [#1]}% class
        }%
        \cmd{#2}% name
    }%
}% marginpar
}{}% not float?
%    \end{macrocode}
%
% Create an index entry sorted by the name without its leading backslash,
% followed by the macro name with the backslash, and the tag.
% Prepend with the class if given.
%
% Write (class):>name=csname (indextag)\verb+|usage+
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
\ifblank{#1}{}{#1\actualchar[#1]:\levelchar}% class
\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2} % name
(#4)% index tag
\encapchar #5}%
%    \end{macrocode}
% Create an index entry grouped by the tag,
%	then printed and sorted by the macro name with the backslash, and the tag.
%
% Write indextag:>(class):>csname\verb+|usage+
% \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
#4:\levelchar% index tag
\ifblank{#1}{}{[#1]:\levelchar}% class
\DTXD@verbatimcmd{#2}% name
\encapchar #5}%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}
%


% \subsection{\cs{DescribeMacro} and \cs{DescribeEnvironment}}

% \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}}
%
% Redefined to allow hyperlinked index entries and an optional class:
%
% \changes{v1.00}{2019/01/09}{Sans tag font.}
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
%    \begin{macrocode}
\providecommand*{\DescribeMacro}{}
\renewcommand*{\DescribeMacro}[2][]{%
\@bsphack%
%    \end{macrocode}
% Create the margin tag with the macro's name:
%    \begin{macrocode}
\@ifundefined{@captype}{% not float?
\leavevmode%
\marginpar{%
    {%
        \hbadness=10000%
        \hfuzz=5em%
        \raggedleft%
        \ifblank{#1}{}{{\scriptsize\textsf{[#1]}} }% class
        \cmd{#2}% name
    }%
}% marginpar
}{}% not float?
%    \end{macrocode}
%
% Write the index sorted by the name without the backslash,
% followed by the actual name with the backslash.
% Append the class if given.
%
% Write name=csname>(class)\verb+|usage+
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
    \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name
    \ifblank{#1}{}{\levelchar[#1]}% class
    \encapchar usage%
}%
%    \end{macrocode}
% Only if a class was given:
%    \begin{macrocode}
\ifblank{#1}%
{}% no class
{% class given
% Again, and prepend the class:
%
% Write class=(class):>name=csname\verb+|usage+
%    \begin{macrocode}
    \begingroup%
    \DTXD@origwrindex{%
    #1\actualchar[#1]:\levelchar%
    \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}%
    \encapchar usage}%
}% class given
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}



% \begin{macro}{\DescribeEnv} \oarg{class} \marg{environment name}
%
% Redefined to allow hyperlinked index entries:
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\providecommand*{\DescribeEnv}{}
\renewcommand*{\DescribeEnv}[2][]
	{\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}
%    \end{macrocode}
% \end{macro}




% \subsection{New \cs{Describe\dots} macros}


% \begin{macro}{\DTX@filename} Stores the filename with a sanitized underscore.
%    \begin{macrocode}
\newcommand*{\DTXD@filename}{}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@filemarginparindex}
%	\marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@filemarginparindex}[5]{%
%    \end{macrocode}
% Create a detokenized version of the filename\dots
%    \begin{macrocode}
\renewcommand{\DTXD@filename}{\detokenize{#2}}%
%    \end{macrocode}
% \dots\ then replace any underscores with a detokenized |\_|,
% which will print as an underscore when read back from the index file:
%    \begin{macrocode}
\StrSubstitute{\DTXD@filename}%
{\detokenize{_}}{\detokenize{\_}}[\DTXD@filename]%
%    \end{macrocode}
% The original filename is printed in the margin.
% Any underscore characters have already been disabled
% by the \cs{catcode} change.
% \changes{v1.00}{2019/01/10}{Fix: File class.}
%    \begin{macrocode}
\DTXD@margintag{#1}{#2}{#3}%
%    \end{macrocode}
% The detokenized and sanitized version is sent to the index file:
%    \begin{macrocode}
\DTXD@index{#1}{\DTXD@filename}{#3}{#4}{#5}%
%    \end{macrocode}
% End the group with the disabled underscore,
% and clean up the extra space from the \cs{catcode} command:
%    \begin{macrocode}
\endgroup%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\DTXD@DescribeFile} \oarg{class} \marg{name}
%
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@DescribeFile}[2][]{%
\DTXD@filemarginparindex{#1}{#2}{File}{file}{usage}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeFile} \marg{name}
%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeFile}.
%    \begin{macrocode}
\newcommand*{\DescribeFile}{%
\begingroup\catcode`\_=12 \DTXD@DescribeFile%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DTXD@DescribeProgram} \oarg{class} \marg{name}
%
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@DescribeProgram}[2][]{%
\DTXD@filemarginparindex{#1}{#2}{Prog}{program}{usage}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeProgram} \marg{name}
%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeProgram}.
%    \begin{macrocode}
\newcommand*{\DescribeProgram}{%
\begingroup\catcode`\_=12 \DTXD@DescribeProgram%
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@DescribeCommand} \oarg{class} \marg{name}
%
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@DescribeCommand}[2][]{%
\DTXD@filemarginparindex{#1}{#2}{Cmd}{command}{usage}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeCommand} \marg{name}
%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeCommand}.
%    \begin{macrocode}
\newcommand*{\DescribeCommand}{%
\begingroup\catcode`\_=12 \DTXD@DescribeCommand%
}
%    \end{macrocode}
% \end{macro}
%


% \begin{macro}{\DTXD@DescribePackage} \oarg{class} \marg{name}
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@DescribePackage}[2][]{%
\DTXD@filemarginparindex{#1}{#2}{Pkg}{package}{usage}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribePackage} \marg{name}
%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribePackage}.
%
% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
%    \begin{macrocode}
\newcommand*{\DescribePackage}{%
\begingroup\catcode`\_=12 \DTXD@DescribePackage%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@DescribeClass} \oarg{class} \marg{name}
%
% The name may have underscores.
%    \begin{macrocode}
\newcommand*{\DTXD@DescribeClass}[2][]{%
\DTXD@filemarginparindex{#1}{#2}{Cls}{class}{usage}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeClass} \marg{name}
%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeClass}.
%
% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
%    \begin{macrocode}
\newcommand*{\DescribeClass}{%
\begingroup\catcode`\_=12 \DTXD@DescribeClass%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DescribeOption} \oarg{class} \marg{name}
%    \begin{macrocode}
\newcommand*{\DescribeOption}[2][]
	{\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeArgument} \oarg{class} \marg{name}
%
% The |class| may be used to categorize arguments by their macro or environment name.
%    \begin{macrocode}
\newcommand*{\DescribeArgument}[2][]
	{\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeBoolean} \oarg{class} \marg{name}
%    \begin{macrocode}
\newcommand*{\DescribeBoolean}[2][]
	{\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeLength} \oarg{class} \marg{name}
%    \begin{macrocode}
\newcommand*{\DescribeLength}[2][]
	{\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeCounter} \oarg{class} \marg{name}
%    \begin{macrocode}
\newcommand*{\DescribeCounter}[2][]
	{\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeHook} \oarg{class} \marg{name}
% \changes{v1.03}{2021/12/18}{Added.}
%    \begin{macrocode}
\newcommand*{\DescribeHook}[2][]
    {\DTXD@margintagindex{#1}{#2}{Hook}{hook}{usage}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeKey} \oarg{class} \marg{name}
%
% The |class| may be used to categorize keys by their kev/value group.
%    \begin{macrocode}
\newcommand*{\DescribeKey}[2][]
	{\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeObject} \oarg{class} \marg{name}
%
% May be used to describe an arbitrary piece of code.
% Creates a margin tag and index entries with \cs{ttfamily}.
%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
%    \begin{macrocode}
\newcommand*{\DescribeObject}[2][]{%
\@ifundefined{@captype}{% not float?
    \@bsphack%
    \leavevmode%
    \marginpar{%
        \hbadness=10000%
        \hfuzz=5em%
        \raggedleft%
        \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }
        \texttt{#2}%
    }%
}{}% not float?
\ifblank{#1}%
{%
    \begingroup%
    \DTXD@origwrindex{%
        #2\actualchar{\protect\ttfamily#2}%
        \encapchar usage%
    }%
}%
{%
    \begingroup%
    \DTXD@origwrindex{%
        #2\actualchar{\protect\ttfamily#2} [#1]%
        \encapchar usage%
    }%
    \begingroup%
    \DTXD@origwrindex{%
        #1\actualchar[#1]:\levelchar#2\actualchar{\protect\ttfamily#2}%
        \encapchar usage%
    }%
}%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeOther} \oarg{class} \marg{name}
%
% May be used to describe an arbitrary non-programming object.
% Creates a margin tag and index entries with roman type.
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
%    \begin{macrocode}
\newcommand*{\DescribeOther}[2][]{%
\@ifundefined{@captype}{% not float?
    \@bsphack%
    \leavevmode%
    \marginpar{%
        \hbadness=10000%
        \hfuzz=5em%
        \raggedleft%
        \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
        #2%
    }%
}{}% not float?
\ifblank{#1}%
{%
    \begingroup%
    \DTXD@origwrindex{#2\encapchar usage}%
}%
{%
    \begingroup%
    \DTXD@origwrindex{#2 [#1]\encapchar usage}%
    \begingroup%
    \DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
}%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}


% \subsection{\cs{DescribeDefault}}

% \begin{macro}{\DescribeDefaultcolor}
% The color of the margin tag used to show the default value.
%
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\DescribeDefaultcolor}{green!50!black}
%    \end{macrocode}
% \end{macro}



% \begin{macro}{\DescribeDefault} \marg{value}
%
% Creates a colored margin tag showing the booleandefault value.
%
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DescribeDefault}[1]{%
    \margintag{%
        \footnotesize%
        \textcolor{\DescribeDefaultcolor}{%
            Default: \texttt{#1}%
        }%
    }%
}
%    \end{macrocode}
% \end{macro}



% \subsection{\cs{ItemDescribeMacro}, etc.}
%
% The following are for use inside a \env{description}.
%
% \begin{macro}{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeMacro}[2][]{%
    \item[\cmd{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeMacro[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeEnv} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeEnv}[2][]{%
    \item[\env{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeEnv[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeArgument} \oarg{class} \marg{argument}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeArgument}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeArgument[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeBoolean} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeBoolean}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeBoolean[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeLength} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeLength}[2][]{%
    \item[\cmd{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeLength[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeCounter} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeCounter}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeCounter[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeHook} \oarg{class} \marg{name}
% \changes{v1.03}{2021/12/18}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeHook}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeHook[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeKey} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeKey}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeKey[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribePackage} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DTXD@ItemDescribePackage}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribePackage[#1]{#2}%
    \endgroup%
}

\newcommand{\ItemDescribePackage}{%
    \begingroup\catcode`\_=12 \DTXD@ItemDescribePackage%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeClass} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DTXD@ItemDescribeClass}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeClass[#1]{#2}%
    \endgroup%
}

\newcommand{\ItemDescribeClass}{%
    \begingroup\catcode`\_=12 \DTXD@ItemDescribeClass%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeOption} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeOption}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeOption[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\ItemDescribeFile} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DTXD@ItemDescribeFile}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeFile[#1]{#2}%
    \endgroup%
}

\newcommand{\ItemDescribeFile}{%
    \begingroup\catcode`\_=12 \DTXD@ItemDescribeFile%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeProgram} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DTXD@ItemDescribeProgram}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeProgram[#1]{#2}%
    \endgroup%
}

\newcommand{\ItemDescribeProgram}{%
    \begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeCommand} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\DTXD@ItemDescribeCommand}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeCommand[#1]{#2}%
    \endgroup%
}

\newcommand{\ItemDescribeCommand}{%
    \begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeObject} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeObject}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeObject[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeOther} \oarg{class} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeOther}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeOther[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}






% \subsection{\cs{margintag}, \cs{watchout}}


% \begin{macro}{\margintagcolor}
% The color of the \cs{margintag}.
%
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\margintagcolor}{blue!70!black}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\margintag} \marg{text}
%
% Prints a colored margin tag.
%
% \changes{v1.00}{2019/01/09}{Uses \cs{margintacolor}.}
%    \begin{macrocode}
\newcommand{\margintag}[1]{%
\@ifundefined{@captype}{% not float?
\marginpar{\raggedleft\textcolor{\margintagcolor}{#1}}%
\ignorespaces%
}{}% not float?
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\watchoutcolor}
% The color of the \cs{watchout}.
%
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\watchoutcolor}{red!50!black}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\watchout} \oarg{text}
%
% Prints a warning sign and optional text.
%
% \changes{v0.11}{2018/03/30}{Changed to \cs{raggedleft}.}
%    \begin{macrocode}
\newcommand{\watchout}[1][]{%
\@ifundefined{@captype}{% not float?
    \marginpar{%
        \raggedleft%
        \textcolor{\watchoutcolor}{\warningsign\normalsize\quad#1}%
    }%
    \ignorespaces%
}{}% not float?
}
%    \end{macrocode}
% \end{macro}


% \subsection{Nesting}
%
% Shows a box enclosing a label for the container, and the container's contents.
% May be nested.
%
% \begin{macro}{\shownesting}
%                   \oarg{fraction of \cs{linewidth}} \marg{container} \marg{contents}
% \changes{v1.03}{2021/09/01}{Added.}
%    \begin{macrocode}
\NewDocumentCommand{\shownesting}{s O{1} m m}{
    \IfBooleanF{#1}{
        \par\smallskip
    }
    \fbox{
        \begin{minipage}{#2\linewidth-2em}
            \hbadness=10000\relax%
            #3\par\smallskip
            \hspace{1em}
            \begin{minipage}{\linewidth-1.5em}
                #4
            \end{minipage}
        \end{minipage}
    }
}
%    \end{macrocode}
% \end{macro}



% \subsection{The \env{dtxexample} environment}
%
% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}.
%
% \DescribeFile{dtxexample_cut.tex} Used to store then \cs{input} example code.
% \changes{v1.00}{2019/01/11}{Cut file name changed to \filenm{dtxexample_cut.tex}}
%
% \DescribeObject[color]{DTXD@examplerulecolor} The color of the middle rule in the dtxexample.
%    \begin{macrocode}
\definecolor{DTXD@examplerulecolor}{rgb}{.9,.9,.9}
%    \end{macrocode}
%
% \begin{macro}{\dtxexamplecodename} The text name of the code section.
% \changes{v1.00}{2019/01/11}{Added.}
%    \begin{macrocode}
\newcommand*{\dtxexamplecodename}{Code:}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\dtxexampleresultname} The text name of the result section.
% \changes{v1.00}{2019/01/11}{Added.}
%    \begin{macrocode}
\newcommand*{\dtxexampleresultname}{Result:}
%    \end{macrocode}
% \end{macro}

% \begin{environment}{dtxexample} * \oarg{notes/cross-references} \marg{caption \& label}
%
% Reads the code listing as a verbatim input using
% the \pkg{fancybox} package, then displays the code listing
% as a verbatim output, and also executes the code
% and displays the result.
% A title caption is specified,
% along with optional cross-referencing commands or notes to
% refer to the results.
% The unstarred version places the code inside a minipage, forbidding a page break in the
% middle of the code listing.
% The starred version does not use a minipage.  This is required when the code is too large
% to fit on a single page.
%
% \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
%    \begin{macrocode}
\NewDocumentEnvironment{dtxexample}{s +O{} m}
{% start dtxexample
%    \end{macrocode}
% Copy the environment's contents to the file |dtxexample_cut.tex|:
%    \begin{macrocode}
\VerbatimOut[gobble=\DTXD@gobble,tabsize=4]{dtxexample_cut.tex}%
}% start dtxexample
%    \end{macrocode}
% When the environment closes:
%    \begin{macrocode}
{% end dtxexample
%    \end{macrocode}
% Finish the verbatim output:
%    \begin{macrocode}
\endVerbatimOut
\par
\addvspace{\bigskipamount}
%    \end{macrocode}
% If unstarred, typeset the example in a minipage:
%    \begin{macrocode}
\IfBooleanTF{#1}{\vspace{\bigskipamount}}{\minipage{\linewidth}}%
%    \end{macrocode}
% Emulated a float of type ``example'':
%    \begin{macrocode}
\captionsetup{type=dtxdexample}%
\hrule\medskip
\caption{#3}
%    \end{macrocode}
% Typeset the contents as verbatim:
%    \begin{macrocode}
\textcolor{DTXD@examplerulecolor}{\smallskip\hrule}
\smallskip
{\scriptsize\itshape\dtxexamplecodename}
\VerbatimInput[tabsize=4]{dtxexample_cut.tex}
\unskip
\textcolor{DTXD@examplerulecolor}{\hrule}
\smallskip
{\scriptsize\itshape\dtxexampleresultname}

%    \end{macrocode}
% Possible add the optional cross-references or notes:
%    \begin{macrocode}
\ifstrempty{#2}
{}
{{\itshape\small #2}}
%    \end{macrocode}
% If unstarred, close the \cs{minipage}.
%    \begin{macrocode}
\IfBooleanTF{#1}{}{\endminipage}%
} % end dtxexample
%    \end{macrocode}
% \end{environment}


% Outside of the environment's scope, input the example to generate its output
% and labels:
%    \begin{macrocode}
\AfterEndEnvironment{dtxexample}
{%
%    \end{macrocode}
% Execute the code:
%    \begin{macrocode}
\par\unskip\input{dtxexample_cut.tex}%
%    \end{macrocode}
% Closing rule::
%    \begin{macrocode}
\medskip\hrule%
}
%    \end{macrocode}


% \DescribeMacro[dtxexample]{\DeclareFloatingEnvironment} A new float type for the examples.
%    \begin{macrocode}
\DeclareFloatingEnvironment[
fileext=lox,
listname={List of Examples},
name=Example,
placement=hbp
]{dtxdexample}
%    \end{macrocode}


% \DescribeMacro[dtxexample]{\captionsetup} Caption setup for the examples.
%    \begin{macrocode}
\captionsetup*[dtxdexample]{
format=hang,
font=bf,
justification=raggedright,
singlelinecheck=false,
skip=0pt,
position=top,
}
%    \end{macrocode}

% \DescribeMacro[dtxexample]{\crefname} Name for \pkg{cleveref}.
%    \begin{macrocode}
\AtBeginDocument{
\@ifpackageloaded{cleveref}{\crefname{dtxdexample}{example}{examples}}{}
}
%    \end{macrocode}



% \subsection{\env{noindmacro} and \env{noindenvironment}}
%
%
% Similar to \env{macro} and \env{environment}, but not indexed.
%
% \begin{environment}{noindmacro} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newenvironment{noindmacro}[1]
{
    \setlength{\parskip}{\marginparpush}
    \leavevmode\par\DTXD@margintag{}{\cmd{#1}}{}
}
{\unskip}
%    \end{macrocode}
% \end{environment}
%
%
% \begin{environment}{noindenvironment} \marg{name}
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newenvironment{noindenvironment}[1]
{
    \setlength{\parskip}{\marginparpush}
    \leavevmode\par\DTXD@margintag{}{#1}{Env}
}
{\unskip}
%    \end{macrocode}
% \end{environment}
%
%
%
% \subsection{\env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
%
% For use in a \env{sourcedisplay}:
%
% \begin{macro}{\fquad} Forces a quad indent.
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\fquad}{\hspace*{1em}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\fqquad} Forces a double-quad indent.
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\fqquad}{\hspace*{2em}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\fqqquad} Forces a triple-quad indent.
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\fqqquad}{\hspace*{3em}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{environment}{sourceverb}
% To typeset a block of source code, verbatim.
%
% \changes{v1.00}{2019/01/11}{Added.}
%    \begin{macrocode}
\DefineVerbatimEnvironment{sourceverb}{Verbatim}
    {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em}
\BeforeBeginEnvironment{sourceverb}{\vspace*{-.5\parskip}}
%    \end{macrocode}
% \end{environment}

% \begin{environment}{fsourceverb}
% To typeset a framed block of source code, verbatim.
%
% \changes{v1.00}{2019/01/11}{Added.}
%    \begin{macrocode}
    \DefineVerbatimEnvironment{fsourceverb}{Verbatim}
        {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em,frame=lines}
\BeforeBeginEnvironment{fsourceverb}{\vspace*{-.5\parskip}}
%    \end{macrocode}
% \end{environment}


% \begin{environment}{sourcedisplay}
% To typeset a block of source code, allowing direct formatting.
%
% \changes{v1.00}{2019/01/09}{Added.}
% \changes{v1.01}{2019/01/20}{Reduced width.}
%    \begin{macrocode}
\newenvironment{sourcedisplay}
{
    \leavevmode
    \par
    \fqquad\minipage{\linewidth-4em}
    \ttfamily
}
{%
    \endminipage
    \par
}
%    \end{macrocode}
% \end{environment}


% \begin{environment}{UIdisplay}
% To typeset a user interface display.
%
% \changes{v1.00}{2019/01/09}{Added.}
% \changes{v1.01}{2019/01/20}{Reduced width.}
%    \begin{macrocode}
\newenvironment{UIdisplay}
{
    \leavevmode
    \par
    \fqquad\minipage{\linewidth-4em}
    \sffamily\bfseries
}
{
    \endminipage
    \par
}
%    \end{macrocode}
% \end{environment}


% \begin{macro}{\userentryname}
% Text to tell the user to enter the following item.
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand*{\userentryname}{Enter~$\Rightarrow$}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\userentry} \marg{text to enter}
%
% Typesets text to be entered by the users.
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newcommand{\userentry}[1]{%
\par
\fqquad%
\begin{minipage}{\linewidth-2em}
    {\footnotesize \userentryname}\quad\cmds{#1}
\end{minipage}
\par
}
%    \end{macrocode}
% \end{macro}



% \begin{environment}{docsidebar}
% To typeset a sidebar in the documentation.
%
% \changes{v1.00}{2019/01/09}{Added.}
%    \begin{macrocode}
\newenvironment{docsidebar}[1][]
{%
    \quote\unskip\medskip
    \setlength{\parskip}{1.5ex}%
    \ifblank{#1}{}{\textit{#1}\newline}%
    \rule[.5\bigskipamount]{\linewidth}{.4pt}%
    \newline%
}
{%
    \leavevmode\par
    \rule[\bigskipamount]{\linewidth}{.4pt}
    \endquote\unskip
}
%    \end{macrocode}
% \end{environment}
%
%
%
% \subsection{Formatted objects}
%
% Macros to format references to various kinds of objects.
%
% \changes{v1.00}{2019/01/11}{Added formatted objects.}
%
% \subsubsection{\LaTeX\ objects}
%
% \begin{macro}{\pkg} \marg{name} \quad Also useable for class names.
%    \begin{macrocode}
\providerobustcmd*{\pkg}[1]{\mbox{\textsf{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\cs} \marg{csname}  \quad From \pkg{ltxdoc}.
% \changes{v1.03}{2021/09/02}{Provided.}
%    \begin{macrocode}
\providerobustcmd*{\cs}[1]{\texttt{\char`\\#1}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\env} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\env}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\marg} \marg{argument}  \quad From \pkg{ltxdoc}.
% \changes{v1.03}{2021/09/02}{Provided.}
%    \begin{macrocode}
\providecommand\marg[1]{%
  {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\oarg} \oarg{argument}  \quad From \pkg{ltxdoc}.
% \changes{v1.03}{2021/09/02}{Provided.}
%    \begin{macrocode}
\providecommand\oarg[1]{%
  {\ttfamily[}\meta{#1}{\ttfamily]}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\parg} \parg{argument}  \quad From \pkg{ltxdoc}.
% \changes{v1.03}{2021/09/02}{Provided.}
%    \begin{macrocode}
\providecommand\parg[1]{%
  {\ttfamily(}\meta{#1}{\ttfamily)}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ctr} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\ctr}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\bool} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\bool}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\optn} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\optn}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\TOC}
%    \begin{macrocode}
\providerobustcmd*{\TOC}{\acro{TOC}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\LOF}
%    \begin{macrocode}
\providerobustcmd*{\LOF}{\acro{LOF}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\LOT}
%    \begin{macrocode}
\providerobustcmd*{\LOT}{\acro{LOT}}
%    \end{macrocode}
% \end{macro}


% \subsubsection{Programs and commands}

% \begin{macro}{\cmds} \marg{commands to print}
%   \quad No processing is provided for special characters.
%    \begin{macrocode}
\providerobustcmd*{\cmds}[1]{\mbox{\textbf{\texttt{#1}}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\progcode} \marg{code to print}
%   \quad No processing is provided for special characters.
%    \begin{macrocode}
\providerobustcmd*{\progcode}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\prog} \marg{program name}  \quad Underscores are allowed.
%    \begin{macrocode}
\newcommand*{\DTXD@prog}[1]{%
    \mbox{\textsf{\textsl{\detokenize{#1}}}}%
    \endgroup%
}

\providerobustcmd*{\prog}{%
    \begingroup%
    \catcode`\_=12%
    \DTXD@prog%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\filenm} \marg{file name}  \quad Underscores are allowed.
%    \begin{macrocode}
\newcommand*{\DTXD@filenm}[1]{%
    \mbox{\texttt{\detokenize{#1}}}%
    \endgroup%
}

\providerobustcmd*{\filenm}{%
    \begingroup%
    \catcode`\_=12%
    \DTXD@filenm%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\UI} General user-interface text.
%    \begin{macrocode}
\providerobustcmd*{\UI}[1]{\textbf{\textsf{#1}}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsubsection{File types}
%
% \begin{macro}{\ODT}
%    \begin{macrocode}
\providerobustcmd*{\ODT}{\acro{ODT}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\SVG}
%    \begin{macrocode}
\providerobustcmd*{\SVG}{\acro{SVG}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\PNG}
%    \begin{macrocode}
\providerobustcmd*{\PNG}{\acro{PNG}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\GIF}
%    \begin{macrocode}
\providerobustcmd*{\GIF}{\acro{GIF}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\JPG}
%    \begin{macrocode}
\providerobustcmd*{\JPG}{\acro{JPG}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\EPS}
%    \begin{macrocode}
\providerobustcmd*{\EPS}{\acro{EPS}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\PDF}
%    \begin{macrocode}
\providerobustcmd*{\PDF}{\acro{PDF}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DVI}
%    \begin{macrocode}
\providerobustcmd*{\DVI}{\acro{DVI}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsubsection{Internet}
%
% \begin{macro}{\UTF}
%    \begin{macrocode}
\providerobustcmd*{\UTF}{\acro{UTF}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\URL}
%    \begin{macrocode}
\providerobustcmd*{\URL}{\acro{URL}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\element} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\element}[1]{\texttt{<#1>}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\attribute} \marg{name}
% \begin{macro}{\attrib} \marg{name}
%
% Each of these is ``provided'', and any prior meaning will
% be unchanged.
% In particular, \LuaTeX\ uses \cs{attribute}, so its meaning
% is unchanged if using \LuaTeX.
% \changes{v1.03}{2021/09/01}{For \LuaTeX.}
%    \begin{macrocode}
\providerobustcmd*{\attrib}[1]{\mbox{\texttt{#1}}}

\providerobustcmd*{\attribute}[1]{\mbox{\texttt{#1}}}
%    \end{macrocode}
% \end{macro}
% \end{macro}

% \begin{macro}{\HTML}
%    \begin{macrocode}
\providerobustcmd*{\HTML}{\acro{HTML}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\HTMLfive}
%    \begin{macrocode}
\providerobustcmd*{\HTMLfive}{\HTML\textsc{5}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\CSS}
%    \begin{macrocode}
\providerobustcmd*{\CSS}{\acro{CSS}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\CSSthree}
%    \begin{macrocode}
\providerobustcmd*{\CSSthree}{\CSS\textsc{3}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\EPUB}
%    \begin{macrocode}
\providerobustcmd*{\EPUB}{\acro{EPUB}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsubsection{Specific programs}
%
% \begin{macro}{\TikZ}
% \changes{v1.05}{2022/09/08}{Renamed from \cs{tikz}, cap Z.}
%    \begin{macrocode}
\providerobustcmd*{\TikZ}{Ti\emph{k}Z}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\CTAN}
%    \begin{macrocode}
\providerobustcmd*{\CTAN}{\acro{CTAN}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\TDS}
%    \begin{macrocode}
\providerobustcmd*{\TDS}{\acro{TDS}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MathML}
%    \begin{macrocode}
\providerobustcmd*{\MathML}{Math\acro{ML}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MathJax}
% \changes{v1.03}{2021/09/02}{Added.}
%    \begin{macrocode}
\providerobustcmd*{\MathJax}{\brand{MathJax}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsubsection{Acronyms, brand names, trademarks}
%
% \begin{macro}{\brand} \marg{name}
%    \begin{macrocode}
\providerobustcmd*{\brand}[1]{\textsc{#1}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\acro} \marg{acronym}
%    \begin{macrocode}
\providerobustcmd*{\acro}[1]{\textsc{\lowercase{#1}}}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\supregistered} Superscript trademark symbol.
%    \begin{macrocode}
\providerobustcmd*{\supregistered}{\textsuperscript{\textregistered}}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Logos}
%
% \changes{v1.00}{2019/01/11}{Added logos.}
%
% \begin{macro}{\dviTeX} \dviTeX
% \changes{v1.03}{2021/09/02}{Added.}
%    \begin{macrocode}
\providerobustcmd*{\dviTeX}{\mbox{\DVI\,\TeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\dviLaTeX} \dviLaTeX
% \changes{v1.03}{2021/09/02}{Added.}
%    \begin{macrocode}
\providerobustcmd*{\dviLaTeX}{\mbox{\DVI\,\LaTeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pdfTeX} \pdfTeX
% \changes{v1.03}{2021/09/02}{Added.}
%    \begin{macrocode}
\providerobustcmd*{\pdfTeX}{\mbox{\PDF\,\TeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pdfLaTeX} \pdfLaTeX
% \changes{v1.03}{2021/09/02}{Added.}
%    \begin{macrocode}
\providerobustcmd*{\pdfLaTeX}{\mbox{\PDF\,\LaTeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LuaTeX} \LuaTeX
%    \begin{macrocode}
\providerobustcmd*{\LuaTeX}{\mbox{Lua\TeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LuaLaTeX} \LuaLaTeX
%    \begin{macrocode}
\providerobustcmd*{\LuaLaTeX}{\mbox{Lua\LaTeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\XeTeX}
% \begin{macro}{\XeLaTeX} \XeTeX, \XeLaTeX
%    \begin{macrocode}
\providerobustcmd*{\XeTeXrevE}
    {\hspace{-.1667em}\raisebox{-.5ex}{E}\hspace{-.125em}}

\AtBeginDocument{
\@ifpackageloaded{graphics}{
    \renewrobustcmd*{\XeTeXrevE}
        {\hspace{-.1667em}\raisebox{-.5ex}{\reflectbox{E}}\hspace{-.125em}}
}{}
}

\providerobustcmd*{\XeTeX}{\mbox{X\XeTeXrevE\TeX}}
\providerobustcmd*{\XeLaTeX}{\mbox{X\XeTeXrevE\LaTeX}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\AmS} \AmS
%    \begin{macrocode}
\providerobustcmd*{\AmS}{%
    \leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex%
    \hbox{$\mathcal M$}\kern-.2em\mathcal S$}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LyX} \LyX
%    \begin{macrocode}
\providerobustcmd*{\LyX}{\textsf{LyX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\BibTeX} \BibTeX
%    \begin{macrocode}
\providerobustcmd*{\BibTeX}{\mbox{B\textsc{ib}\TeX}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MakeIndex} \MakeIndex
%    \begin{macrocode}
\providerobustcmd*{\MakeIndex}{\prog{MakeIndex}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ConTeXt} \ConTeXt
%    \begin{macrocode}
\providerobustcmd*{\ConTeXt}{\mbox{Con\TeX{}t}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MiKTeX} \MiKTeX
%    \begin{macrocode}
\providerobustcmd*{\MiKTeX}{\mbox{MiK\TeX}}
%    \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Dashes and slashes}
%
% \begin{macro}{\thinskip} A breakable thin skip.
%    \begin{macrocode}
\DeclareRobustCommand{\thinskip}{\hskip 0.16667em\relax}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\endash} An endash: \endash
%    \begin{macrocode}
\def\endash{–}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\emdash} An emdash: \emdash
%    \begin{macrocode}
\def\emdash{—}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thinbrspace} A thin space which allows a line break.
%    \begin{macrocode}
\newcommand{\thinbrspace}{%
    \hspace{.16667em}\penalty\exhyphenpenalty\hspace{0pt}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thinthinbrspace} A thin space which allows a line break.
%    \begin{macrocode}
\newcommand{\thinthinbrspace}{%
    \hspace{.08333em}\penalty\exhyphenpenalty\hspace{0pt}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Dash} An unbreakeable thin space, emdash, and breakable thin space.
%    \begin{macrocode}
\newrobustcmd{\Dash}{\unskip\thinspace\emdash\thinbrspace}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\dash} An unbreakeable thin space, endash, and breakable thin space.
%    \begin{macrocode}
\newrobustcmd{\dash}{\unskip\thinspace\endash\thinbrspace}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Slash} An unbreakable very thin space, a slash, and a breakable thin space.
%    \begin{macrocode}
\newrobustcmd{\Slash}{\unskip\hspace{.08333em}/\thinthinbrspace}
%    \end{macrocode}
% \end{macro}
%
%
% \clearpage
%
% \section{Compiling \pkg{dtxdescribe}}
%
% To compile the \pkg{dtxdescribe} package:
% \userentry{pdflatex dtxdescribe.ins}
%
% To compile the \pkg{dtxdescribe} documentation
% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
% \userentry{makeindex -s gglo.ist -o dtxdescribe.gls dtxdescribe.glo}
% \userentry{makeindex -s gind.ist dtxdescribe}
% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
%
%
% \iffalse
%</package>
% \fi




% \clearpage
% \pagestyle{plain}
%
% \renewcommand{\partname}{}
% \renewcommand{\thepart}{}
% \part{Change History and Index}
%
%
% \Finale
%
\endinput
