% \iffalse meta-comment
%
% Copyright 2016-2024 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>    [2024/01/20 v1.09 Describe additional object types in source files.]
%
%<*driver>
\documentclass{ltxdoc}

\newcommand*{\mypackagename}{dtxdescribe}
\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} or \texttt{tex} 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}{ff}
\newunicodechar{fi}{fi}
\newunicodechar{fl}{fl}
\newunicodechar{ffi}{ffi}
\newunicodechar{ffl}{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}

\AtBeginDocument{
\hypersetup{%
pdfinfo={%
Title={The LaTeX \mypackagename\ package},%
Author={Brian Dunn},%
Subject={Describe additional object types in dtx source files.]},%
Keywords={LaTeX, dtx, source, DescribeMacro},%
colorlinks,%
linkcolor=mylinkcolor,%
urlcolor=myurlcolor,%
pageanchor=true,
}}
}


% \crefname here is required to compile the dtxdescribe documentation
% using the doc class:
\AddToHook{begindocument/before}{% Before .aux file is loaded.
\usepackage{cleveref}
\crefname{dtxexamplefloat}{example}{examples}
}

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

% \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}
% \changes{v1.06}{2022/12/07}{\ 2022/12/07}
% \changes{v1.07}{2023/01/03}{\ 2023/01/03}
% \changes{v1.08}{2024/01/08}{\ 2024/01/08}
% \changes{v1.08}{2024/01/08}{\ Updated contact info.}
% \changes{v1.09}{2024/01/18}{Improved TOC change log and index entries.}
% \changes{v1.09}{2024/01/20}{2024/01/20}




% \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--2024} Brian Dunn\\
% \small \url{https://github.com/bdtc/dtxdescribe}
%
% \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, sockets, plugs, 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 type of object
% displayed in parentheses (length, filename, etc).
% Each item may be sorted further by an optional category displayed in brackets,
% such as |[category_name]|.
%
% 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
%
% \textcolor{red}{See change in setup of \pkg{hyperref} and \pkg{cleveref}:
%       \Cref{sec:usage} on \cpageref{sec:usage}.}
%
% \clearpage
%
% \tableofcontents
% \listofdtxexamplefloats
% \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 categories may be used to further sort 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}}
% \label{sec:usage}

% To use \pkg{dtxdescribe} with the \pkg{ltxdoc} class and \filenm{.dtx} files:
% \begin{sourceverb}
% %<*driver>
% \documentclass{ltxdoc}
% 	...
% \usepackage{lmodern}
% 	...
% \usepackage{dtxdescribe}
% 	...
% \usepackage{packagename} % the name of your new package
% 	...
%
% % hyperref now automatically loaded by \pkg{ltxdoc}.
%
% \AtBeginDocument{
%    \hypersetup{...}%                      If needed.
%    \pdfstringdefDisableCommands{ ... }%   If needed.
% }
%
% \AddToHook{begindocument/before}{% Before .aux file is loaded.
%   \usepackage{cleveref}%                  If needed.
%   \crefname{somename}{name}{names}%       If needed.
% }
%
% 	...
% %</driver>
% \end{sourceverb}

% To use \pkg{dtxdescribe} with the regular classes, such as \pkg{article},
% use:
%
% \begin{sourceverb}
% \documentclass{article}
%
% \usepackage{dtxdescribe}
% 
% \usepackage{hyperref}%                    If needed.
%    \hypersetup{...}%                      If needed.
%    \pdfstringdefDisableCommands{ ... }%   If needed.
% 
% \usepackage{cleveref}%                    If needed.
%   \crefname{somename}{name}{names}%       If needed.
%
% \begin{document}
% ...
% \end{document}
% \end{sourceverb}


% Various objects inside the |dtx| or |tex| 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 ``categories'' may be assigned to the objects being described,
% including the new versions of \cs{DescribeMacro} and \cs{DescribeEnv}.
% These categories are printed in the margin tag and index entry for each item,
% and also generate additional index entries sorted by category.  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.
% \cs{listofdtxexamplefloats} prints the list of examples.




% \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{category} \marg{\cs{name}}
%
% The preexisting macro from the \pkg{doc} package is redefined to
%	create hyperlinked index entries, and include an optional category.
%	A margin tag is created and an index entry is made.
%	When the optional category is used, it is displayed along with
%	the margin tag, and is used to group an index entry by
%	macro name and another index entry by category.
%	An example would be to describe
%	the float creation and caption setup for a new category 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{category} \marg{environment name}
%
% The preexisting macro from the \pkg{doc} package is redefined to
%	create hyperlinked index entries, include an optional category, 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{category} \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 |category| 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, sockets, plugs, keys}
%
% See \cref{ex:common} on \cpageref{ex:common}.
%
% \DescribeMacro{\DescribeBoolean} \oarg{category} \marg{name}
%
% Describes a boolean.  Given a `Bool' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeLength} \oarg{category} \marg{name}
% 
% Describes a length.  Given a `Len' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeCounter} \oarg{category} \marg{name}
% 
% Describes a counter.  Given a `Ctr' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeHook} \oarg{category} \marg{name}
% 
% Describes a hook.  Given a `Hook' tag in the margin and index.
% The |category| may be used to categorize hooks by package.
% The hook name may or may not have a backslash.
% Example:
% \begin{sourceverb}
% \DescribeHook{\hookname}
% \DescribeHook[LaTeX]{para/begin}
% \end{sourceverb}
%
%
% \DescribeMacro{\DescribeSocket} \oarg{category} \marg{name}
%
% \DescribeMacro{\DescribePlug} \oarg{category} \marg{name}
% 
% Describes a socket or plug.  Given a `Socket' or 'Plug' tag in the margin and index.
% The |category| may be used to categorize sockets and plugs by package.
% Example:
% \begin{sourceverb}
% \DescribeSocket{socketname}
% \DescribePlug{plugname}
% \end{sourceverb}
%
%
% \DescribeMacro{\DescribeKey} \oarg{category} \marg{name}
% 
% Describes a key.  Given a `Key' tag in the margin and index.
% The |category| 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{category} \marg{name}
% 
% Describes a package.  Given a `Pkg' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeClass} \oarg{category} \marg{name}
% 
% Describes a \LaTeX\ class.  Given a `Cls' tag in the margin and index.
%
%
% \DescribeMacro{\DescribeOption} \oarg{category} \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{category} \marg{name}
% 
% Describes an operating-system file.  Given a `File' tag in the margin and index.
% The filename may have underscores.
%
%
% \DescribeMacro{\DescribeProgram} \oarg{category} \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{category} \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{category} \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 category is used, it is added to the margin tag, appended to the
% index entry, and a second index entry is created grouped by category.
% If a macro name is to be described, use \cs{DescribeMacro} instead.
% See \cref{ex:object} on \cpageref{ex:object}.
%
%
% \DescribeMacro{\DescribeOther} \oarg{category} \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 category is used, it is added to the margin tag, appended to the
% index entry, and a second index entry is created grouped by category.
% 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{category} \marg{\cs{name}} A description.
%
% \DescribeMacro{\ItemDescribeEnv} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeArgument} \oarg{category} \marg{argument} A description.
%
% \DescribeMacro{\ItemDescribeBoolean} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeLength} \oarg{category} \marg{\cs{name}} A description.
%
% \DescribeMacro{\ItemDescribeCounter} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeHook} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeSocket} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribePlug} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeKey} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribePackage} \oarg{category} \marg{package\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeClass} \oarg{category} \marg{class\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeOption} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeFile} \oarg{category} \marg{file\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeProgram} \oarg{category} \marg{program\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeCommand} \oarg{category} \marg{command\_name} With underscores.
%
% \DescribeMacro{\ItemDescribeObject} \oarg{category} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribeOther} \oarg{category} \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.
%
% \DescribeMacro{listofdtxexamplefloats} Prints the list of examples.
%
% See \cref{ex:dtxexample} for a demonstration of how \env{dtxexample} works.
%
% The examples may be customized by redefining the following,
% perhaps for another language:

% \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 \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]{\DeclareFloatingPhoto}
%	Create a photograph float environment.

% \DescribeMacro[c=photograph]{\photocaptionsetup}
%	Caption settings for a photograph float.

% \DescribeMacro[photograph]{\cphotonameref}
%	\pkg{cleveref} name for the photograph float.
% \end{dtxexample}
%
%
% The optional category is used to label and group tags and index entries.
% See this document's index entries for examples of this ``photograph''
% category and the \env{dtxexample} category 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 category |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.


% \begin{dtxexample}{Hooks and Sockets\label{ex:hook}}
% \DescribeHook{\hookname} A hook with a backslash.

% \DescribeHook{para/begin} A hook without a backslash.

% \DescribeSocket{socketname} A socket.

% \DescribePlug{plugname} A socket plug.

% \end{dtxexample}

% Hooks may or may not have a leading backslash.



% \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 category 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 category.
% \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[\mymacro]{bold}
% What happens when \cs{mymacro} is given the |bold| argument.
% \end{dtxexample}
%
% Arguments behave like keys, and may have an optional category to
% identify their macro or environment, and group their entries
% in the index.
%
% Note you may 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 myenvironment}
% 	Actions to be done \cs{BeforeBeginEnvironment}.
%
% \DescribeOther[othercategory]{Other Item} About the other item.
%
% \DescribeOther[othercategory]{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 command.
% \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 |dtxexamplefloat| 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{
% \appendix
% \GlossaryPrologue{\section{Change History}}
% \PrintChanges
% \IndexPrologue{\section{Index}}
% \PrintIndex}
 

% ^^A *source
% \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{
    \IfPackageLoadedTF{makeidx}{}{
    \IfPackageLoadedTF{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{
    \IfPackageLoadedTF{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}%
        }
    }% yes hyperref
%    \end{macrocode}
% If \pkg{hyperref} is not loaded, emulate \cs{hyperpage} here.
%    \begin{macrocode}
    {% no hyperref
        \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}



% \subsection{Warning sign}

% \begin{macro}{\warningsign} Prints an exclamation point inside a triangle.
%   Displays as: \warningsign
%
% 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{Special character handling}

% The literal backslash character:
%    \begin{macrocode}
\begingroup
\catcode`\|=0
\catcode`\\=12
|gdef|DTXD@backslash{\}
|endgroup
%    \end{macrocode}



% \subsection{Patching \pkg{hypdoc}, \pkg{splitidx}, \pkg{doc}}
%
% If \pkg{hyperref} is disabled (by \pkg{lwarp}) then define the
% missing \cs{hdclindex}.
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{
\IfPackageLoadedTF{hypdoc}{
\AddToHook{begindocument/before}[doc/hyperref]{%
 \ifdoc@hyperref
 \else
  \def\hdclindex#1#2{%
    \ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi%
  }%
 \fi
}
}{}% hypdoc loaded
}{}% doc loaded
%    \end{macrocode}


% Several changes for when \pkg{hypdoc} and \pkg{splitidx} are used together:
%    \begin{macrocode}
\AtBeginDocument{
\IfPackageLoadedTF{doc}{
\IfPackageLoadedTF{hypdoc}{
\IfPackageLoadedTF{splitidx}{
%    \end{macrocode}
%
%
% \pkg{splitidx} is modified to add \verb+|hdpindex{}+ to work with \pkg{hypdoc}.
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
%    \begin{macrocode}
\renewcommand*{\@wrsindex}[2][]{%
  \ifx\relax#1\relax%
    \if@splitidx%
      \@wrsindex[idx]{#2}%
    \else%
      \def\@tempa{#2}%
      \if@verbindex\@onelevel@sanitize\@tempa\fi%
      \@wrindex{\@tempa}%
    \fi%
  \else%
%
%    \def\@tempa{#2}%
    \def\@tempa{#2\encapchar hdpindex{}}%       dtxdescribe
%
    \csname index@#1@hook\endcsname%
    \expandafter\ifx\csname @@wrsindex\endcsname\relax%
      \@@@wrsindex{#1}{{\@tempa}{\thepage}}%
    \else%
      \def\@tempb{\@@wrsindex{#1}}%
      \expandafter\@tempb\@tempa||\\%
    \fi%
    \endgroup%
    \@esphack%
  \fi%
}
%    \end{macrocode}


% \pkg{hypdoc} guesses the \TOC\ level for the \PDF\ bookmarks,
% but its algorithm seems to fail at \cs{StopEventually} for split indices.
%
% ``|Paragraph ended before \HD@@guesstoclevel was complete.|''
%
% Its guess is fixed to level 1 until \cs{PrintChanges} or \cs{printindex}.
%
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
%    \begin{macrocode}
\def\HD@guesstoclevel#1{1}
%    \end{macrocode}

% \changes{v1.07}{2022/12/19}{Improved \PDF\ bookmarks.}
% Patch \pkg{doc}'s \cs{PrintChanges} to reset the \TOC\ guess to top level.
%    \begin{macrocode}
\preto\PrintChanges{\def\HD@guesstoclevel#1{0}}
%    \end{macrocode}


% \pkg{hypdoc} adds \PDF\ bookmarks to letter groups in the index.
% \pkg{hypdoc} must take into account multiple indexes,
% otherwise, followup indices will have duplicate bookmarks.
%
% Increment the index number at the start of each index,
% and append the index number to the \PDF\ bookmark.
%
% Also, change the \TOC\ guess to top level from now on, presuming that
% the indices are at the end.
%
% \changes{v1.07}{2022/12/19}{Improved \PDF\ bookmarks.}
%    \begin{macrocode}
\newcounter{DTXD@indexnumber}

\extendtheindex
    {%
        \addtocounter{DTXD@indexnumber}{1}%
        \def\HD@guesstoclevel##1{0}%
    }
    {}
    {}
    {}

\def\HD@@@bfseries\hfil#1\hfil{%
  \ifx\\#1\\%
  \else%
    \raisebox{\baselineskip}[0pt]{%
      \kern-\HD@margin\relax%
%      \pdfbookmark[\HD@toclevel@subindex]{#1}{HD.#1}}%
      \pdfbookmark[\HD@toclevel@subindex]{#1}%      dtxdescribe
        {HD.#1.\arabic{DTXD@indexnumber}}%          dtxdescribe
      \kern\HD@margin\relax%
    }%
  \fi%
  \hfil#1\hfil%
}%
%    \end{macrocode}

%    \begin{macrocode}
}{}% splitidx loaded
}{}% hypdoc loaded
}{}% doc loaded
}% AtBeginDocument
%    \end{macrocode}



% \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}
\IfPackageLoadedTF{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{Not \pkg{ltxdoc}: \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{Not \pkg{doc}: \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{
    \IfPackageLoadedTF{doc}{}{% not 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}
    }% not doc
}% AtBeginDocument
%    \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 category 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}
\IfPackageLoadedTF{doc}{}{% not doc package

\providecommand{\usage}{}
\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}

}% not doc package
%    \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{category} \marg{name} \marg{margin tag}
%
% Creates the margin tag for the object being described.
%
% The |category| is used to sub-categorize keys into their key/value groups.
%
% \changes{v1.01}{2019/01/20}{Put margin tag category 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]}% category
                }%
                \texttt{#2}% name
            }%
        }% marginpar
    }{}% not float?
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@index}
%	\marg{category} \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 |category| is used to sub-categorize 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 category:
%    \begin{macrocode}
#2\actualchar{\protect\ttfamily#2} % name
(#4)% index tag
\ifblank{#1}{}{ [#1]}%
\encapchar #5}%
%    \end{macrocode}
%
% Index by tag and category:
%
% Write the tag and category 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}%
#2\actualchar{\protect\ttfamily#2}% name
\encapchar #5}%
%    \end{macrocode}
%
% Possibly index by category and name:
%    \begin{macrocode}
\ifblank{#1}{}{% category given
\begingroup%
\DTXD@origwrindex{%
#1\actualchar[#1]:\levelchar% category
#2\actualchar{\protect\ttfamily#2} % name
(#4)% index tag
\encapchar #5}%
}% category given
% \@esphack%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@margintagindex}
%	\marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% Creates the margin tag and the index entries.
% The |category| is used to sub-categorize 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{category} \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 category 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]}% category
        }%
        \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 category if given.
%
% Write [category]:>name=csname (indextag)\verb+|usage+
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
\ifblank{#1}{}{#1\actualchar[#1]:\levelchar}% category
\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:>[category]:>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}% category
\DTXD@verbatimcmd{#2}% name
\encapchar #5}%
\@esphack%
\ignorespaces%
}
%    \end{macrocode}
% \end{macro}
%


% \subsection{\pkg{doc}: Key handling for object categories}

% If using \pkg{doc}, the optional key \Slash value argument may also
% include an object category.  This is supported by assigning any unknown
% key to be the category.
%
% The category may be given using the key |c|, or as the default action
% when an unknown key is given.
%
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
%    \begin{macrocode}
\ExplSyntaxOn
\IfPackageLoadedTF{doc}{

\newcommand*{\DTXD@category}{}

\keys_define:nn {doc}
{
    c .cs_set:Np = \DTXD@category,
    unknown .code:n = {%
        \renewcommand*{\DTXD@category}{\l_keys_key_str}%
    },
}

}{}% doc loaded
\ExplSyntaxOff
%    \end{macrocode}


% \subsection{\pkg{doc}: Handling \cs{marginpar} inside a float}

% To avoid a floats lost error, do not print margin tags if inside a float.
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
% \changes{v1.09}{2024/01/20}{Removed extra spaces.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{

\def\@doc@describe#1#2{%                    dtxdescribe
    \ifdoc@noprint\else%
      \@ifundefined{@captype}{% not float?  dtxdescribe
          \marginpar{\raggedleft%
                     \strut%
                     \doc@providetarget%
                     \@nameuse{PrintDescribe#1}{#2}%
                \ifdefvoid{\DTXD@category}{}{%  dtxdescribe
                    \space{\footnotesize[\mbox{\DTXD@category}]}%
                }%
          }%
      }{}%
    \fi%
    \ifdoc@noindex\else%
      \@nameuse{Special#1Index}{#2}%
    \fi%
  \@esphack%
  \endgroup%
  \ignorespaces%
}

}{}% doc loaded
%    \end{macrocode}




% \subsection{\pkg{doc}: Handling categories and detokenizing names}
%
% \begin{macro}{\@NewDocElement}
% File names and such may include underscores or other characters,
% so patch \pkg{doc} to neutralized while processing.
%
% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{%

\def\@NewDocElement#1#2#3{%
  \doc@macrolikefalse%
  \doc@topleveltrue%
  \def\doc@idxtype{#3}%
  \def\doc@idxgroup{#3s}%
  \let\doc@printtype\@empty%
  \csname keys_set:nn\endcsname{doc}{#1}%
  \ifx\doc@printtype\@empty%
    \@temptokena{}%
  \else%
    \@temptokena\expandafter{\expandafter%
         \textnormal\expandafter{\expandafter%
         \space\expandafter%
         (\doc@printtype)}}%
  \fi%
  \@nameedef{Print#2Name}##1{%
     {\noexpand\MacroFont%
      \ifdoc@macrolike%
         \noexpand\string##1%                           dtxdescribe
      \else%
         \noexpand\detokenize\expandafter{##1}%         dtxdescribe
      \fi%
      \the\@temptokena%
     }}%
  \expandafter\let\csname PrintDescribe#2\expandafter\endcsname%
                  \csname Print#2Name\endcsname%
  \edef\doc@expr{%
     \ifdoc@macrolike%
       \noexpand\doc@createspecialmacrolikeindexes%
     \else%
       \noexpand\doc@createspecialindexes%
     \fi%
     {#2}%
    }%
   \expandafter\expandafter\expandafter%
   \doc@expr%
   \expandafter\expandafter\expandafter%
     {\expandafter\doc@idxtype\expandafter}\expandafter%
     {\doc@idxgroup}%
  \doc@createdescribe{#2}%
    \ifdoc@macrolike%
      \doc@createenv{TT}{#2}{#3}%
    \else%
      \doc@createenv{TF}{#2}{#3}%
    \fi
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXDbreak} Inserts a possible line break point.
%       Used in the index to allow line breaks before verbatim category names.
% \changes{v1.07}{2022/12/24}{Improved line breaks.}
%    \begin{macrocode}
\newcommand*{\DTXDbreak}{\space\penalty200}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@printobjectname} \marg{name w/o backslash} \marg{name} \quad
% Adds the object name to the index in verbatim.
% These are passed as arguments instead of directly used here because they must
% have their value when the index is written instead of when \cs{DTXD@printobjectname}
% is used when the index is read back.
%
%    \begin{macrocode}
\newcommand*{\DTXD@printobjectname}[2]{%
    #1%
    \actualchar%
    \string\verb% %
    \quotechar%
    *%
    \verbatimchar%
    #2%
    \verbatimchar%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@maybecategory} If there is a category, it is added verbatim.
%    \begin{macrocode}
\newcommand*{\DTXD@maybecategory}{%
    \ifdefvoid{\DTXD@category}%
        {}%
        {%
%    \end{macrocode}
%
% \cs{DTXDbreak} inserts a possible line break here,
% allowing a break if the following verbatim is too long.
% \changes{v1.07}{2022/12/24}{Improved line breaks.}
%    \begin{macrocode}
            \string\DTXDbreak%
%    \end{macrocode}
%    \begin{macrocode}
            [%
            \string\verb%
            \noexpand\quotechar%
%    \end{macrocode}
% \changes{v1.07}{2022/12/19}{\cs{verb}*.}
%    \begin{macrocode}
            *%
            \verbatimchar\DTXD@category\verbatimchar%
        ]}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@categorylevelname} The simplified name, without backslash.
%    \begin{macrocode}
\newcommand*{\DTXD@categorylevelname}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@maybecategorylevel} \marg{object\_type}
%       \quad If a category is assigned, index by category.
%
% \begin{description}
% \item [arg 1:] Type of object, shown between parens (), such as |macro|, |boolean|, etc.
% \item [\cs{DTXD@category}:] The name of the category, printed in brackets [],
%                                   such as \cs{macroname}.
% \item [\cs{DTXD@categorylevelname}:] The simplified name of the category, such as |macroname|.
% \item [\cs{@gtempa}:] The name of this particular object.
% \end{description}
%
% \changes{v1.07}{2022/12/19}{\cs{verb}*.}
%    \begin{macrocode}
\newcommand*{\DTXD@maybecategorylevel}[1]{%
    \ifdefvoid{\DTXD@categorylevelname}%
        {}%
        {%
%    \end{macrocode}
% Index: \\
% |categorylevelname=\verb!*+[category]:+>name=\verb!*+<prefix>name+<break>(type)|
%    \begin{macrocode}
            \index{%
                \DTXD@categorylevelname%
                \noexpand\actualchar%
                \string\verb% % to fool emacs highlighting
                \noexpand\quotechar%
                *%
                \noexpand\verbatimchar%
                [\DTXD@category]:%
                \verbatimchar%
                \noexpand\levelchar%
                \noexpand\DTXD@printobjectname{\DTXD@gtempa@nobackslash}{\@gtempa}%
                \ifblank{#1}{}{\string\DTXDbreak (#1)}%
%    \end{macrocode}
%
% \cs{the}\cs{@temptokena} is not used here.
% \changes{v1.07}{2022/12/19}{Fix occasional crash.}
%
%    \begin{macrocode}
           \noexpand\doc@handleencap{usage}%
            }% index
        }%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@findcategorylevelname}
%       Given \cs{DTXD@category}, create \cs{DTXD@categorylevelname},
%       a detokenized name without backslash.
%    \begin{macrocode}
\newcommand*{\DTXD@findcategorylevelname}{%
    \edef\DTXD@categorylevelname{\DTXD@category}%
    \edef\DTXD@categorylevelname{\detokenize\expandafter{\DTXD@categorylevelname}}%
    \IfBeginWith{\DTXD@categorylevelname}{\DTXD@backslash}%
        {\StrGobbleLeft{\DTXD@categorylevelname}{1}[\DTXD@categorylevelname]}%
        {}%
}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\DTXD@gtempa@nobackslash} A version without the leading backslash.
%    \begin{macrocode}
\newcommand*{\DTXD@gtempa@nobackslash}{}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DTXD@findgtempa} Detokenize \cs{@gtempa} and
%   also find another version without any leading backslash.
% \changes{v1.07}{2022/12/19}{Detokenized names.}
%    \begin{macrocode}
\newcommand*{\DTXD@findgtempa}[1]{%
    \edef\@gtempa{\detokenize{#1}}%
    \IfEndWith{\@gtempa}{ }{\StrGobbleRight{\@gtempa}{1}[\@gtempa]}{}%
    \IfBeginWith{\@gtempa}{\DTXD@backslash}%
        {\StrGobbleLeft{\@gtempa}{1}[\DTXD@gtempa@nobackslash]}%
        {\edef\DTXD@gtempa@nobackslash{\@gtempa}}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\doc@createspecialindexes}
%       \marg{1: name} \marg{2: index type} \marg{3: index group}
%    \begin{macrocode}
\def\doc@createspecialindexes#1#2#3{%
  \@temptokena{\space (#2)}%
  \@temptokenb{#3:}%
%    \end{macrocode}
%
% \textbf{Define \cs{SpecialMain<name>Index} \marg{1: name}}
%    \begin{macrocode}
  \@nameedef{SpecialMain#1Index}##1{%
%    \end{macrocode}
%
% Find \cs{@gtempa}, the name of the object.
%    \begin{macrocode}
    \noexpand\DTXD@findgtempa{##1}%
%    \end{macrocode}
%
% \begin{description}
% \item[\cs{@temptokena}:] Index (type).
% \item[\cs{@temptokenb}:] Index group.
% \item[\cs{@gtempa}:] Detokenized name of the particular object.
% \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
% \end{description}
%
%    \begin{macrocode}
    \noexpand\@bsphack%
    \noexpand\DTXD@findcategorylevelname%                   dtxdescribe
%    \end{macrocode}
%    \begin{macrocode}
  \ifdoc@toplevel%
%    \noexpand\special@index{##1\noexpand\actualchar
%
%
%    \end{macrocode}
%
% Index: \\
% \verb?name=\verb!*+name+ (type) [category]|main?
%    \begin{macrocode}
    \noexpand\special@index{%
        \noexpand\DTXD@printobjectname%                     dtxdescribe
            {\noexpand\DTXD@gtempa@nobackslash}%
            {\noexpand\@gtempa}%
        \ifx\@nil#2\@nil\else \the\@temptokena \fi%
        \noexpand\DTXD@maybecategory%                       dtxdescribe
        \noexpand\encapchar main%
    }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
    \noexpand\DTXD@maybecategorylevel{#2}%                  dtxdescribe
  \fi%
%
%
%    \end{macrocode}
%
% If group is not empty, index: \\
% \verb?group:>name=\verb!*+name+ [category]|main?
%
%    \begin{macrocode}
  \ifx\@nil#3\@nil\else%
    \noexpand\special@index{%
        \the\@temptokenb\noexpand\levelchar%
%      ##1\noexpand\actualchar{\string\ttfamily\space##1}%
        \noexpand\DTXD@printobjectname%                     dtxdescribe
            {\noexpand\DTXD@gtempa@nobackslash}%
            {\noexpand\@gtempa}%
        \noexpand\DTXD@maybecategory%                       dtxdescribe
        \noexpand\encapchar main%
    }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
    \noexpand\DTXD@maybecategorylevel{#2}%                  dtxdescribe
  \fi%
  \noexpand\@esphack}%
%    \end{macrocode}
%
% \textbf{Define \cs{Special<name>Index}  \marg{1: name}}
%
% \changes{v1.09}{2024/01/20}{Removed extra spaces.}
%    \begin{macrocode}
  \@nameedef{Special#1Index}##1{%
    \noexpand\DTXD@findgtempa{##1}%
%    \end{macrocode}
%
% \begin{description}
% \item[\cs{@temptokena}:] Index (type).
% \item[\cs{@temptokenb}:] Index group.
% \item[\cs{@gtempa}:] Detokenized name of the particular object.
% \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
% \end{description}
%
%    \begin{macrocode}
    \noexpand\@bsphack%
    \noexpand\DTXD@findcategorylevelname%                   dtxdescribe
%    \end{macrocode}
%
% If is a top level object, index:\\
% \verb?name=\verb!*+name+ (type) [category]|usage?
%    \begin{macrocode}
  \ifdoc@toplevel%
        \noexpand\doc@providetarget%
%    \end{macrocode}
%    \begin{macrocode}
%    \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}%
        \noexpand\index{%
            \noexpand\DTXD@printobjectname%                 dtxdescribe
                {\noexpand\DTXD@gtempa@nobackslash}%
                {\noexpand\@gtempa}%
            \ifx\@nil#2\@nil\else \the\@temptokena \fi%
            \noexpand\DTXD@maybecategory%                   dtxdescribe
            \noexpand\doc@handleencap{usage}%
        }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
        \noexpand\DTXD@maybecategorylevel{#2}%              dtxdescribe
  \fi%
%
%
%    \end{macrocode}
%
% If group is not empty, index: \\
% \verb?group:>name=\verb!*+name+ [category]|usage?
%    \begin{macrocode}
  \ifx\@nil#3\@nil\else%
    \noexpand\index{%
        \the\@temptokenb\noexpand\levelchar%
%       ##1\noexpand\actualchar{\string\ttfamily\space##1}
        \noexpand\DTXD@printobjectname%                     dtxdescribe
            {\noexpand\DTXD@gtempa@nobackslash}%
            {\noexpand\@gtempa}%
        \noexpand\DTXD@maybecategory%                       dtxdescribe
        \noexpand\doc@handleencap{usage}%
    }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
    \noexpand\DTXD@maybecategorylevel{#2}%                  dtxdescribe
  \fi%
%
%
    \noexpand\@esphack}}
%    \end{macrocode}
% \end{macro}


% \begin{macro}{\doc@createspecialmacrolikeindexes}
%       \marg{1: name} \marg{2: index type} \marg{3: index group}
% \changes{v1.07}{2022/12/24}{Added category names for macros.}
%    \begin{macrocode}
\def\doc@createspecialmacrolikeindexes#1#2#3{%
  \@temptokena{\space (#2)}%
  \@temptokenb{#3:}%
%    \end{macrocode}
%
% \textbf{Define \cs{Code<name>Index} \marg{1: |main| or |usage|} \marg{2: name}}
%
%    \begin{macrocode}
  \@nameedef{Code#1Index}##1##2{%
    \noexpand\DTXD@findgtempa{##2}%
%    \end{macrocode}
%
% \begin{description}
% \item[\cs{@temptokena}:] Index type.
% \item[\cs{@temptokenb}:] Index group.
% \item[\cs{@gtempa}:] Detokenized name of the particular object.
% \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
% \end{description}
%
%    \begin{macrocode}
    \noexpand\@bsphack%
    \noexpand\DTXD@findcategorylevelname%                   dtxdescribe
%    \end{macrocode}
%    \begin{macrocode}
  \noexpand\ifdoc@noindex\noexpand\else%
%    \end{macrocode}
%
% If a top level object, index:\\
% \verb?name=\verb!*+\name+ (type) [category]|<main or usage>?
%    \begin{macrocode}
    \ifdoc@toplevel%
      \noexpand\special@index{%
            \noexpand\DTXD@printobjectname%                 dtxdescribe
                {\noexpand\DTXD@gtempa@nobackslash}%
                {\noexpand\@gtempa}%
            \ifx\@nil#2\@nil\else \the\@temptokena \fi%
            \noexpand\DTXD@maybecategory%                   dtxdescribe
            \noexpand\encapchar ##1%
      }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
      \noexpand\DTXD@maybecategorylevel{#2}%                dtxdescribe
    \fi%
%    \end{macrocode}
%
% If group is not empty, index: \\
% \verb?group:>name=\verb!*+\name+ [category]|<main or usage>?
%    \begin{macrocode}
    \ifx\@nil#3\@nil\else%
      \noexpand\special@index{%
            \the\@temptokenb\noexpand\levelchar%
            \noexpand\DTXD@printobjectname%                 dtxdescribe
                {\noexpand\DTXD@gtempa@nobackslash}%
                {\noexpand\@gtempa}%
            \noexpand\DTXD@maybecategory%                   dtxdescribe
            \noexpand\encapchar ##1%
      }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
      \noexpand\DTXD@maybecategorylevel{#2}%                dtxdescribe
    \fi%
  \noexpand\fi%
    \noexpand\@esphack}%
%    \end{macrocode}
%
% \textbf{Define \cs{SpecialMain<name>Index} \marg{1: name}}
%    \begin{macrocode}
  \@nameedef{SpecialMain#1Index}##1{%
    \expandafter\noexpand\csname Code#1Index\endcsname%
        {main}{##1}}%
%    \end{macrocode}
%
% \textbf{Define \cs{Special<name>Index} \marg{1: name}}
% \changes{v1.09}{2024/01/20}{Removed extra spaces.}
%    \begin{macrocode}
  \@nameedef{Special#1Index}##1{%
    \noexpand\DTXD@findgtempa{##1}%
%    \end{macrocode}
%
% \begin{description}
% \item[\cs{@temptokena}:] Index type.
% \item[\cs{@temptokenb}:] Index group.
% \item[\cs{@gtempa}:] Detokenized name of the particular object.
% \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
% \end{description}
%
%    \begin{macrocode}
    \noexpand\@bsphack%
    \noexpand\DTXD@findcategorylevelname%                   dtxdescribe
%    \end{macrocode}
%    \begin{macrocode}
  \noexpand\ifdoc@noindex\noexpand\else%
%    \end{macrocode}
%
% If a top level object, index:\\
% \verb?name=\verb!*+\name+ (type) [category]|usage?
%    \begin{macrocode}
    \ifdoc@toplevel%
      \noexpand\doc@providetarget%
      \noexpand\index{%
            \noexpand\DTXD@printobjectname%                 dtxdescribe
                {\noexpand\DTXD@gtempa@nobackslash}%
                {\noexpand\@gtempa}%
            \ifx\@nil#2\@nil\else \the\@temptokena \fi%
            \noexpand\DTXD@maybecategory%                   dtxdescribe
            \noexpand\doc@handleencap{usage}%
      }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
    \noexpand\DTXD@maybecategorylevel{#2}%                  dtxdescribe
    \fi%
%    \end{macrocode}
%
% If group is not empty, index: \\
% \verb?group:>name=\verb!*+\name+ [category]|usage?
%    \begin{macrocode}
    \ifx\@nil#3\@nil\else%
      \noexpand\index{%
            \the\@temptokenb\noexpand\levelchar%
            \noexpand\DTXD@printobjectname%                 dtxdescribe
                {\noexpand\DTXD@gtempa@nobackslash}%
                {\noexpand\@gtempa}%
            \noexpand\DTXD@maybecategory%                   dtxdescribe
            \noexpand\doc@handleencap{usage}%
      }%
%    \end{macrocode}
%
% Maybe add the category index entry:
%    \begin{macrocode}
      \noexpand\DTXD@maybecategorylevel{#2}%                dtxdescribe
    \fi%
  \noexpand\fi%
    \noexpand\@esphack}}

}{}% doc loaded
%    \end{macrocode}
% \end{macro}


% \subsection{Not \pkg{doc}: \cs{DescribeMacro} and \cs{DescribeEnvironment}}

% \begin{macro}{\DescribeMacro} \oarg{category} \marg{\cs{name}}
%
% Redefined to allow hyperlinked index entries and an optional category:
%
% \changes{v1.00}{2019/01/09}{Sans tag font.}
% \changes{v1.01}{2019/01/20}{Put margin tag category 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}
\IfPackageLoadedTF{doc}{}{% not doc

\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]}} }% category
        \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 category if given.
%
% Write name=csname>[category]\verb+|usage+
%    \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
    \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name
    \ifblank{#1}{}{\levelchar[#1]}% category
    \encapchar usage%
}%
%    \end{macrocode}
% Only if a category was given:
%    \begin{macrocode}
\ifblank{#1}%
{}% no category
{% category given
% Again, and prepend the category:
%
% Write category=[category]:>name=csname\verb+|usage+
%    \begin{macrocode}
    \begingroup%
    \DTXD@origwrindex{%
    #1\actualchar[#1]:\levelchar%
    \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}%
    \encapchar usage}%
}% category given
\@esphack%
\ignorespaces%
}

}% not doc
%    \end{macrocode}
% \end{macro}



% \begin{macro}{\DescribeEnv} \oarg{category} \marg{environment name}
%
% Redefined to allow hyperlinked index entries:
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{}{% not doc

\providecommand*{\DescribeEnv}{}
\renewcommand*{\DescribeEnv}[2][]
	{\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}




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


% \begin{macro}{\DTXD@filemarginparindex}
%	\marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
%
% The name may have underscores.
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{}{% not doc
\newcommand*{\DTXD@filename}{}

\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 category.}
%    \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%
}
}% not doc
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeMacro}             \quad Redefine with new definitions.
% \begin{macro}{\DescribeEnvironment}       \quad Redefine with new definitions.
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\RenewDocElement[macrolike = true ,
                idxtype   = ,
                idxgroup  = ,
                printtype =
               ]{Macro}{macro}

\RenewDocElement[macrolike = false ,
                idxtype   = env.  ,
                idxgroup  = environments ,
                printtype = \textit{env.}
               ]{Env}{environment}

}{}% doc
%    \end{macrocode}
% \end{macro}
% \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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=file,
    idxgroup=Files,
    printtype=\textit{file}
]{File}{file}

}{% not doc

\newcommand*{\DTXD@DescribeFile}[2][]{%
    \DTXD@filemarginparindex{#1}{#2}{File}{file}{usage}%
}

\newcommand*{\DescribeFile}{%
    \begingroup\catcode`\_=12 \DTXD@DescribeFile%
}

}% not doc
%    \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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=program,
    idxgroup=Programs,
    printtype=\textit{Prog}
]{Program}{program}

}{% not doc

\newcommand*{\DTXD@DescribeProgram}[2][]{%
    \DTXD@filemarginparindex{#1}{#2}{Prog}{program}{usage}%
}

\newcommand*{\DescribeProgram}{%
    \begingroup\catcode`\_=12 \DTXD@DescribeProgram%
}
}% not doc

%    \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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=command,
    idxgroup=Commands,
    printtype=\textit{Cmd}
]{Command}{command}

}{% not doc

\newcommand*{\DTXD@DescribeCommand}[2][]{%
    \DTXD@filemarginparindex{#1}{#2}{Cmd}{command}{usage}%
}

\newcommand*{\DescribeCommand}{%
    \begingroup\catcode`\_=12 \DTXD@DescribeCommand%
}

}% not doc
%    \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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=package,
    idxgroup=Packages,
    printtype=\textit{Pkg}
]{Package}{package}

}{% not doc

\newcommand*{\DTXD@DescribePackage}[2][]{%
    \DTXD@filemarginparindex{#1}{#2}{Pkg}{package}{usage}%
}

\newcommand*{\DescribePackage}{%
    \begingroup\catcode`\_=12 \DTXD@DescribePackage%
}

}% not doc

%    \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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=class,
    idxgroup=Classes,
    printtype=\textit{Cls}
]{Class}{class}

}{% not doc

\newcommand*{\DTXD@DescribeClass}[2][]{%
    \DTXD@filemarginparindex{#1}{#2}{Cls}{class}{usage}%
}

\newcommand*{\DescribeClass}{%
    \begingroup\catcode`\_=12 \DTXD@DescribeClass%
}

}% not doc
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\DescribeOption} \oarg{category} \marg{name}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=option,
    idxgroup=Options,
    printtype=\textit{Opt}
]{Option}{option}

}{% not doc

\newcommand*{\DescribeOption}[2][]
	{\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeArgument} \oarg{category} \marg{name}
%
% The |category| may be used to categorize arguments by their macro or environment name.
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=argument,
    idxgroup=Arguments,
    printtype=\textit{Arg}
]{Argument}{argument}

}{% not doc

\newcommand*{\DescribeArgument}[2][]
	{\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeBoolean} \oarg{category} \marg{name}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=boolean,
    idxgroup=Booleans,
    printtype=\textit{bool}
]{Boolean}{boolenv}

}{% not doc

\newcommand*{\DescribeBoolean}[2][]
	{\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeLength} \oarg{category} \marg{name}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=true,
    toplevel=true,
    idxtype=length,
    idxgroup=Lengths,
    printtype=\textit{Len}
]{Length}{length}

}{% not doc

\newcommand*{\DescribeLength}[2][]
	{\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeCounter} \oarg{category} \marg{name}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=counter,
    idxgroup=Counters,
    printtype=\textit{Ctr}
]{Counter}{counter}

}{% not doc

\newcommand*{\DescribeCounter}[2][]
	{\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeHook} \oarg{category} \marg{name}
% \changes{v1.03}{2021/12/18}{Added.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=true,
    toplevel=true,
    idxtype=hook,
    idxgroup=Hooks,
    printtype=\textit{Hook}
]{Hook}{hook}

}{% not doc

\newcommand*{\DescribeHook}[2][]
    {\DTXD@margintagindex{#1}{#2}{Hook}{hook}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeSocket} \oarg{category} \marg{name}
% \changes{v1.08}{2024/01/08}{Added.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=socket,
    idxgroup=Sockets,
    printtype=\textit{Socket}
]{Socket}{socket}

}{% not doc

\newcommand*{\DescribeSocket}[2][]
    {\DTXD@margintagindex{#1}{#2}{Socket}{socket}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribePlug} \oarg{category} \marg{name}
% \changes{v1.08}{2024/01/08}{Added.}
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=plug,
    idxgroup=Plugs,
    printtype=\textit{Plug}
]{Plug}{plug}

}{% not doc

\newcommand*{\DescribePlug}[2][]
    {\DTXD@margintagindex{#1}{#2}{Plug}{plug}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeKey} \oarg{category} \marg{name}
%
% The |category| may be used to categorize keys by their kev/value group.
%    \begin{macrocode}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=key,
    idxgroup=Keys,
    printtype=\textit{Key}
]{Key}{key}

}{% not doc

\newcommand*{\DescribeKey}[2][]
	{\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}}

}% not doc
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\DescribeObject} \oarg{category} \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 category 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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=object,
    idxgroup=Objects,
    printtype=,
]{Object}{object}

}{% not doc

\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%
}

}% not doc
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeOther} \oarg{category} \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 category 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}
\IfPackageLoadedTF{doc}{% doc

\NewDocElement[
    macrolike=false,
    toplevel=true,
    idxtype=other,
    idxgroup=Other,
    printtype=,
]{Other}{other}

}{% not doc

\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%
}

}% not doc
%    \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{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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}{\ItemDescribeSocket} \oarg{category} \marg{name}
% \changes{v1.08}{2024/01/08}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribeSocket}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribeSocket[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribePlug} \oarg{category} \marg{name}
% \changes{v1.08}{2024/01/08}{Added.}
%    \begin{macrocode}
\newcommand{\ItemDescribePlug}[2][]{%
    \item[\texttt{#2}:]%
    \setlength{\parskip}{1.5ex}%
    \DescribePlug[#1]{#2}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ItemDescribeKey} \oarg{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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{category} \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 \cpageref{ex:dtxexample}.
%
% \DescribeFile{dtxexample_cut.tex} Used to store the \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, else use a float:
%    \begin{macrocode}
\IfBooleanTF{#1}%
    {% minipage
        \minipage{\linewidth}%
        \captionsetup{type=dtxexamplefloat}%
    }%
    {% float
        \begin{dtxexamplefloat}%
    }%
%    \end{macrocode}
%    \begin{macrocode}
\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 float or \cs{minipage}.
%    \begin{macrocode}
\IfBooleanTF{#1}%
    {\endminipage}%
    {\end{dtxexamplefloat}}%
} % 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[dtxexamplefloat]{\DeclareFloatingEnvironment}
%       A new float type for the examples.
%    \begin{macrocode}
\DeclareFloatingEnvironment[
fileext=lox,
listname={List of Examples},
name=Example,
placement=hbp
]{dtxexamplefloat}
%    \end{macrocode}


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

% \DescribeMacro[dtxexamplefloat]{\crefname} Name for \pkg{cleveref}.
% \cs{crefname} here is required for documents not using the doc class:
%    \begin{macrocode}
%\AddToHook{begindocument/after}{% Before .aux file is loaded.
\AtBeginDocument{
    \ifdef{\crefname}{
        \crefname{dtxexamplefloat}{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{
\IfPackageLoadedTF{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}
%
%
% \Finale
%
\endinput