summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/dtxdescribe
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/dtxdescribe
Initial commit
Diffstat (limited to 'macros/latex/contrib/dtxdescribe')
-rw-r--r--macros/latex/contrib/dtxdescribe/README.txt20
-rw-r--r--macros/latex/contrib/dtxdescribe/dtxdescribe.dtx3179
-rw-r--r--macros/latex/contrib/dtxdescribe/dtxdescribe.ins47
-rw-r--r--macros/latex/contrib/dtxdescribe/dtxdescribe.pdfbin0 -> 334193 bytes
4 files changed, 3246 insertions, 0 deletions
diff --git a/macros/latex/contrib/dtxdescribe/README.txt b/macros/latex/contrib/dtxdescribe/README.txt
new file mode 100644
index 0000000000..60d788aa99
--- /dev/null
+++ b/macros/latex/contrib/dtxdescribe/README.txt
@@ -0,0 +1,20 @@
+The LaTeX dtxdescribe package
+Describe additional object types in dtx source files.
+
+v1.01 — 2019/03/22
+Copyright 2016–2019 Brian Dunn — www.BDTechConcepts.com
+LaTeX Project Public License, version 1.3
+
+The doc package includes tools for describing macros and environments in
+LATEX source dtx format. The dtxdescribe package adds additional tools for
+describing booleans, lengths, counters, keys, packages, classes, options, files,
+commands, arguments, and other objects.
+
+Each item is given a margin tag similar to \DescribeEnv, and is listed in
+the index by itself and also by category. Each item may be sorted further by
+an optional class. All index entries except code lines are hyperlinked.
+
+Descriptions are best accompanied by examples, so the environment
+dtxexample is provided. Contents are displayed verbatim along with a
+caption and cross-referencing. They are then \input and executed, and the
+result is shown.
diff --git a/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
new file mode 100644
index 0000000000..1c7ae225e3
--- /dev/null
+++ b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
@@ -0,0 +1,3179 @@
+
+% \iffalse meta-comment
+%
+% Copyright 2016-2019 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> [2019/07/16 v1.02 Describe additional object types in source files.]
+%
+%<*driver>
+\documentclass{ltxdoc}
+
+\newcommand*{\mypackagename}{dtxdescribe}
+\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.}
+
+
+% \usepackage{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}
+
+\usepackage{microtype}
+
+\usepackage{metalogo}
+\makeatletter
+\@ifpackageloaded{erewhon}{
+\setlogokern{Te}{-.08em}
+\setlogokern{eX}{-0.04em}
+\setlogokern{La}{-.25em}
+\setlogokern{aT}{-.08em}
+\setlogokern{Xe}{-.04em}
+\setlogokern{eL}{-.06em}
+\setlogodrop{0.27ex}
+}{}
+\makeatother
+
+\usepackage{etoolbox}
+
+\usepackage[log-declarations=false]{xparse}
+
+\usepackage{titleps}
+
+\newpagestyle{pageheadfoot}{
+ \headrule
+ \sethead{\pkg{\mypackagename}}{}{\thepage}
+% \renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}}
+ \setfoot{}{}{}
+}
+
+\pagestyle{pageheadfoot}
+
+
+
+% Better spacing for \Describe... margin tags:
+\setlength{\marginparsep}{1em}
+\setlength{\marginparpush}{.7ex}
+
+\setlength{\parindent}{0em}
+\setlength{\parskip}{2ex}
+
+\setlength{\IndexMin}{40ex}
+
+
+
+\usepackage{\mypackagename}
+
+\usepackage[pdftex,bookmarks=true,hidelinks,%
+colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,%
+pageanchor=true,hyperindex=true,
+]{hyperref}
+
+\hypersetup{%
+pdfinfo={%
+Title={The LaTeX \mypackagename\ package},%
+Author={Brian Dunn},%
+Subject={Describe additional object types in dtx source files.]},%
+Keywords={LaTeX, dtx, source, DescribeMacro}%
+}}
+
+
+\usepackage{cleveref}
+
+
+\setcounter{IndexColumns}{2}
+
+\DisableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{\mypackagename.dtx}
+\end{document}
+%
+%</driver>
+%
+% \fi
+%
+% \iffalse
+%<*package>
+% \fi
+%
+% \CheckSum{1118}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+
+% \changes{v0.10}{2016/12/08}{\ 2016/12/08 Initial ver}
+% \changes{v0.11}{2018/03/30}{\ 2018/03/30}
+% \changes{v1.00}{2019/01/11}{\ 2019/01/11}
+% \changes{v1.01}{2019/03/22}{\ 2019/03/22}
+% \changes{v1.02}{2019/07/16}{\ 2019/07/16}
+
+
+
+
+% \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--2018} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}
+%
+% \vspace{.5in}
+%
+% {\Large \textup{\quicksummary}}
+%
+% \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, keys, packages, classes, options,
+% files, commands, arguments, and other objects.
+% \pkg{dtxdescribe} also works with the regular document classes, for those
+% who do not wish to use the \pkg{ltxdoc} class and \filenm{.dtx} files.
+%
+% Each described item is given a margin tag similar to \cs{DescribeEnv},
+% and is listed in the index by itself and also by category.
+% Each item may be sorted further by an optional class.
+% All index entries except code lines are hyperlinked.
+%
+% The \env{dtxexample} environment is provided for typesetting example code and its results.
+% Contents are displayed verbatim along with a caption and cross-referencing.
+% They are then \cs{input} and executed, and the result is shown.
+%
+% Environments are also provided for displaying verbatim or formatted source code,
+% user-interface displays, and sidebars with titles.
+%
+% Macros are provided for formatting the names of inline \LaTeX\ objects such as
+% packages and booleans, as well as program and file names, file types, internet
+% objects, the names of certain programs, a number of logos, and inline dashes and slashes.
+%
+% \pkg{dtxdescribe} works with the \pkg{ltxdoc} class, but also
+% works with the standard classes as well, except that
+% the \env{macro} and \env{environment} environments are not supported.
+% Either \pkg{makeidx} or \pkg{splitidx} may be loaded by the user.
+% \pkg{makeidx} will be used by default.
+% \end{abstract}
+%
+%
+% \vfill
+%
+% \end{center}
+% \clearpage
+%
+% \tableofcontents
+% \listofdtxdexamples
+% \listoffigures
+% ^^A \listoftables
+%
+%
+%
+% \clearpage
+%
+%^^A \part{dtxdescribe.sty}
+%
+% \section{Introduction}
+%
+% The \pkg{doc} package provides \cs{DescribeMacro} and \cs{DescribeEnv}
+% to help document new macros and environments.
+% Each generates a heading in the documentation, to which \cs{marg},
+% \cs{oarg}, and \cs{parg} may be added to identify arguments to be
+% passed to the new object.
+% Their names are added to the margin, and index entries are added,
+% as well as group of entries for environments.
+%
+% \pkg{dtxdescribe} extends this concept to include a number of
+% additional objects, such as booleans and keys.
+% To help identify what is being described in the margin, small tags are
+% added to the name, such as ``Env'', ``Bool'', or ``Key''.
+% These new objects are also listed in the index with the same tag
+% shown after their names, and also by group.
+% Optional classes may be used to further categories index entries.
+%
+% Modifications have been made to interact with \pkg{hyperref} to
+% provide hyper links for regular index entries as well as the new
+% \cs{Describe} entries.
+%
+% Additional macros are provided to generate colored margin tags and
+% warnings, and a new |dtxexample| environment demonstrates code examples.
+%
+% This documentation and its index show examples of these macros in use.
+%
+% While the index may appear to be overkill for a small package,
+% keep in mind that it includes a number of fictional entries from the examples.
+% Extensive cross-referencing can be useful for larger works.
+% And, of course, you need not cross-reference everything!
+
+
+% \clearpage
+% \section{Using \pkg{dtxdescribe}}
+
+% Place |\usepackage{dtxdescribe}| in the |.dtx| file's driver section:
+% \begin{sourceverb}
+% %<*driver>
+% \documentclass{ltxdoc}
+% ...
+% \usepackage{lmodern}
+% ...
+% \usepackage{dtxdescribe}
+% ...
+% \usepackage{packagename} % the name of your new package
+% ...
+% \usepackage[...]{hyperref}
+% \usepackage[...]{cleveref}
+% ...
+% %</driver>
+% \end{sourceverb}
+
+% Various objects inside the |dtx| file may be described with \cs{DescribeBoolean},
+% \cs{DescribeLength}, \cs{DescribeCounter}, and related macros,
+% similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}.
+
+% Optional ``classes'' may be assigned to the objects being described, including the new versions
+% of \cs{DescribeMacro} and \cs{DescribeEnv}.
+% These classes are printed in the margin tag and index entry for each item,
+% and also generate additional index entries sorted by class. This is
+% especially useful for key/value sets, where several sets may appear in the same
+% document.
+%
+% The margin tag is not printed if
+% \margintag{inside a float}
+% the \cs{Describe} macros are used inside a float such as a table,
+% but the index entries are still made.
+%
+% |\margintag{text}| may be used to place a colored tag in
+% \margintag{\cs{margintag}\{text\}}
+% the margin to summarize paragraph
+% contents or draw attention to an index destination.
+%
+% |\watchout[optional text]| may be used to place a red warning sign
+% \watchout[\cs{watchout}{[}text{]}]
+% in the margin, along with optional text.
+%
+% The \env{dtxexample} environment may be used to typeset and execute small pieces of \LaTeX\ code
+% as examples of its use. Optional cross-referencing notes may be used to refer to any
+% example float being generated.
+
+
+
+% \clearpage
+% \section{The macros, and the \env{dtxexample} environment}
+
+
+
+% \subsection{Macros and environments}
+%
+% \DescribeEnv{macro}
+% \DescribeEnv{environment}
+% These are only provided by the \pkg{ltxdoc} class and \pkg{doc} package
+% \watchout[\filenm{.dtx} only]
+% to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
+% to disable these environments in the resulting \filenm{.sty} file.
+% When using the regular document classes, the \env{macro} and
+% \env{environment} environments would localize any definitions,
+% and \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
+%
+%
+% \DescribeMacro{\DescribeMacro} \oarg{class} \marg{\cs{name}}
+%
+% The preexisting macro from the \pkg{doc} package is redefined to
+% create hyperlinked index entries, and include an optional class.
+% A margin tag is created and an index entry is made.
+% When the optional class is used, it is displayed in front of
+% the margin tag, and is used to group an index entry by
+% macro name and another index entry by class.
+% An example would be to describe
+% the float creation and caption setup for a new class of float,
+% such as the |dtxexample| float and the example ``photograph'' float
+% both found in the index for this document.
+% See \cref{ex:macro} on \cpageref{ex:macro} for examples.
+%
+% \DescribeMacro{\DescribeEnv} \oarg{class} \marg{environment name}
+%
+% The preexisting macro from the \pkg{doc} package is redefined to
+% create hyperlinked index entries, include an optional class, and also to place
+% an `Env' tag in front of the name in the margin.
+% See \cref{ex:environment} on \cpageref{ex:environment}.
+%
+
+
+% \subsection{Arguments}
+%
+% The \cs{Describe\dots} macros
+% may be followed by \cs{marg}, \cs{oarg}, and \cs{parg} to
+% describe arguments passed to the macros.
+%
+% \DescribeMacro{\marg} \marg{text}
+%
+% Shows a mandatory argument for a macro or environment.
+%
+% The results looks like \marg{mandatory}.
+%
+
+% \DescribeMacro{\oarg} \marg{text}
+%
+% Shows an optional argument for a macro or environment.
+%
+% The results looks like \oarg{optional}.
+%
+
+% \DescribeMacro{\parg} \marg{text}
+%
+% Used for ``picture'' arguments, such as coordinates.
+%
+% The result looks like \parg{coordinate}.
+%
+
+% \DescribeMacro{\DescribeArgument} \oarg{class} \marg{argument}
+%
+% May be used to describe actions taken when given certain macro arguments.
+% These will be given an `Arg' margin tag and will appear in the index.
+% The |class| may be used to categorize arguments by their macro or environment name.
+% See \cref{ex:arguments} on \cpageref{ex:arguments}.
+
+
+% \subsection{Booleans, lengths, counters, keys}
+%
+% See \cref{ex:common} on \cpageref{ex:common}.
+%
+% \DescribeMacro{\DescribeBoolean} \oarg{class} \marg{name}
+%
+% Describes a boolean. Given a `Bool' tag in the margin and index.
+%
+%
+% \DescribeMacro{\DescribeLength} \oarg{class} \marg{name}
+%
+% Describes a length. Given a `Len' tag in the margin and index.
+%
+%
+% \DescribeMacro{\DescribeCounter} \oarg{class} \marg{name}
+%
+% Describes a counter. Given a `Ctr' tag in the margin and index.
+%
+%
+% \DescribeMacro{\DescribeKey} \oarg{class} \marg{name}
+%
+% Describes a key. Given a `Key' tag in the margin and index.
+% The |class| may be used to categorize keys by their kev/value group.
+% See \cref{ex:key} on \cpageref{ex:key}.
+
+
+% \subsection{Packages, classes, options}
+%
+% \DescribeMacro{\DescribePackage} \oarg{class} \marg{name}
+%
+% Describes a package. Given a `Pkg' tag in the margin and index.
+%
+%
+% \DescribeMacro{\DescribeClass} \oarg{class} \marg{name}
+%
+% Describes a \LaTeX\ class. Given a `Cls' tag in the margin and index.
+%
+%
+% \DescribeMacro{\DescribeOption} \oarg{class} \marg{name}
+%
+% Describes a \LaTeX\ package or class option. Given an `Opt' tag in the margin and index.
+%
+%
+
+% \subsection{Files, programs, commands}
+%
+% \DescribeMacro{\DescribeFile} \oarg{class} \marg{name}
+%
+% Describes an operating-system file. Given a `File' tag in the margin and index.
+% The filename may have underscores.
+%
+%
+% \DescribeMacro{\DescribeProgram} \oarg{class} \marg{name}
+%
+% Describes an operating-system program. Given a `Prog' tag in the margin and index.
+% The program name may have underscores.
+%
+%
+% \DescribeMacro{\DescribeCommand} \oarg{class} \marg{name}
+%
+% Describes an operating-system command. Given a `Cmd' tag in the margin and index.
+% The command name may have underscores.
+%
+%
+
+
+% \subsection{Other source objects}
+%
+% \DescribeMacro{\DescribeObject} \oarg{class} \marg{name}
+%
+% Describes an arbitrary programming object, such as a color definition or caption setup.
+% A margin tag and index entry are created with \cs{ttfamily} type.
+% When a class is used, it is pre-pended to the margin tag, appended to the
+% index entry, and a second index entry is created grouped by class.
+% If a macro name is to be described, use \cs{DescribeMacro} instead.
+% See \cref{ex:object} on \cpageref{ex:object}.
+%
+%
+% \DescribeMacro{\DescribeOther} \oarg{class} \marg{name}
+%
+% Describes an arbitrary non-programming object, such as a license agreement
+% or credits. A margin tag and index entry are created in roman type.
+% When a class is used, it is pre-pended to the margin tag, appended to the
+% index entry, and a second index entry is created grouped by class.
+% See \cref{ex:other} on \cpageref{ex:other}.
+
+
+% \subsection{In a \env{description} environment}
+%
+% To describe an object using a \env{description} environment, use the following.
+% See \cref{ex:description} on \cpageref{ex:description}.
+
+% \DescribeMacro{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}} A description.
+%
+% \DescribeMacro{\ItemDescribeEnv} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribeArgument} \oarg{class} \marg{argument} A description.
+%
+% \DescribeMacro{\ItemDescribeBoolean} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribeLength} \oarg{class} \marg{\cs{name}} A description.
+%
+% \DescribeMacro{\ItemDescribeCounter} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribeKey} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribePackage} \oarg{class} \marg{package\_name} With underscores.
+%
+% \DescribeMacro{\ItemDescribeClass} \oarg{class} \marg{class\_name} With underscores.
+%
+% \DescribeMacro{\ItemDescribeOption} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribeFile} \oarg{class} \marg{file\_name} With underscores.
+%
+% \DescribeMacro{\ItemDescribeProgram} \oarg{class} \marg{program\_name} With underscores.
+%
+% \DescribeMacro{\ItemDescribeCommand} \oarg{class} \marg{command\_name} With underscores.
+%
+% \DescribeMacro{\ItemDescribeObject} \oarg{class} \marg{name} A description.
+%
+% \DescribeMacro{\ItemDescribeOther} \oarg{class} \marg{name} A description.
+
+
+% \subsection{Defaults}
+
+% \DescribeMacro{\DescribeDefault} \marg{value}
+% \DescribeDefault{value}
+%
+% Shows the default value of a \cs{Describe\dots} item, such as displayed here.
+% Place this macro immediately after the \cs{Describe\dots} macro and any
+% arguments, but before the text description.
+
+% \DescribeMacro{\DescribeDefaultcolor}
+% The color of the margin tag used to show the default value.
+% This is used by \cs{textcolor} to create the margin tag.
+%
+% \DescribeDefault{green!50!black}
+
+
+% \subsection{\cs{margintag}, \cs{watchout}}
+%
+%
+% \DescribeMacro{\margintag} \marg{text}
+%
+% Creates a colored margin tag.
+% May be used to identify the topic of a paragraph or the destination of
+% an arbitrary index entry.\margintag{\cs{margintag}\{example\}}
+%
+% \DescribeMacro{\margintagcolor}
+% \DescribeDefault{blue!70!black}
+% The color of the \cs{margintag}.
+% \bigskip
+%
+% \DescribeMacro{\watchout} \oarg{text}
+%
+% Creates a red margin tag with a warning sign and
+% optional text. May be used to warn the reader of special instructions, etc.
+% \watchout[\cs{watchout}{[}example{]}]
+% Without the optional text the warning sign is displayed by itself.
+%
+% \DescribeMacro{\watchoutcolor}
+% \DescribeDefault{red!50!black}
+% The color of the \cs{watchout}.
+
+
+% \subsection{\env{dtxexample} environment}
+%
+% \DescribeEnv{dtxexample} * \oarg{Notes/cross-references} \marg{caption \& label}
+%
+% The \env{dtxexample} environment is useful for demonstrating a piece of \LaTeX\ code.
+% The example is a simulated float with its own caption and optional label,
+% along with optional notes and/or cross-referencing commands.
+% The contents of the \env{dtxexample} environment are printed verbatim, then
+% loaded and executed as \LaTeX\ code, showing the results just below the printed code.
+% In the case of float commands, the floats are generated as expected somewhere nearby,
+% and should be given their own labels.
+% References to the float's labels may be placed in the optional argument to
+% the \env{dtxexample} environment, and will be printed below the code.
+%
+% The unstarred version places the code inside a
+% minipage, forbidding a page break in the middle of the code listing. The starred
+% version does not use a minipage. This is required when the code is too large to fit
+% on a single page.
+%
+% See \cref{ex:dtxexample} for a demonstration of how \env{dtxexample} works.
+%
+% \DescribeMacro{\dtxexamplecodename}
+% \DescribeDefault{Code:}
+% The text name of the code section.
+%
+% \DescribeMacro{\dtxexampleresultname}
+% \DescribeDefault{Result:}
+% The text name of the result section.
+%
+%
+% \subsection{\env{noindmacro} and \env{noindenvironment} environments}
+%
+% These only make sense if using 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{noindmacro} and
+% \env{noindenvironment} environments would localize any definitions,
+% and \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
+%
+% \DescribeEnv{noindmacro} \marg{\cs{name}}
+% To document macros which should not be included in the index.
+%
+% \DescribeEnv{noindenvironment} \marg{name}
+% To document environments which should not be included in the index.
+%
+% Replace
+% \begin{sourceverb}
+% \begin{macro}{\macroname} \oarg{optional} \marg{mandatory}
+% ...
+% \end{macro}
+% \end{sourceverb}
+% with
+% \begin{sourceverb}
+% \begin{noindmacro}{\macroname} \oarg{optional} \marg{mandatory}
+% ...
+% \end{noindmacro}
+% \end{sourceverb}
+% and similarly for \env{noindenvironment}.
+%
+%
+% \subsection{\env{sourceverb}, \env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
+%
+% \DescribeEnv{sourceverb} \oarg{key/values}
+% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em} \qquad Display source code verbatim.
+% Uses optional \pkg{fancyvrb} keys. Includes |gobble=2| to absorb the
+% leading |%| and space character of a \filenm{dtx} file source format.
+% Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
+% \bigskip
+%
+% \DescribeEnv{fsourceverb} \oarg{key/values}
+% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em,frame=lines} \qquad Display source
+% code verbatim inside a frame.
+% A label may be included using the \optn{label} key.
+% Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
+% See \cref{ex:fsourceverb} on page \cpageref{ex:fsourceverb}.
+% \bigskip
+%
+% \DescribeEnv{sourcedisplay} Display source code with manual formatting.
+% This is not a verbatim environment.
+% \cs{textcolor}, \cs{textbf}, and \cs{emph} may be used to highlight text.
+% Macros must be escaped with \cs{cs}, characters such as \{ must be
+% produced with \cs{\{}, etc.
+% \cs{\textbackslash} must be used to force a new line.
+% \cs{fquad}, \cs{fqquad}, and \cs{fqqquad}
+% may be used to force indenting.
+% Because this is \emph{not} a verbatim environment,
+% it \emph{can} be used inside a macro.
+% See \cref{ex:sourcedisplay} on \cpageref{ex:sourcedisplay}.
+%
+% \DescribeMacro{\fquad} Single-level indent inside a \env{sourcedisplay}.
+%
+% \DescribeMacro{\fqquad} Double-level indent inside a \env{sourcedisplay}.
+%
+% \DescribeMacro{\fqqquad} Triple-level indent inside a \env{sourcedisplay}.
+%
+% \DescribeEnv{UIdisplay} Displays a user interface, such as a dialog box entry
+% or a menu selection. See \cref{ex:UIdisplay} on \cpageref{ex:UIdisplay}.
+% Also see the \cs{UI} macro..
+%
+% \DescribeMacro{\userentry} \marg{text to enter} \qquad
+% Typeset something for the user to enter.
+% Also see the \cs{cmds} macro.
+%
+% \DescribeMacro{\userentryname}
+% \DescribeDefault{Enter~$\Rightarrow$}
+% Text to tell the user to enter the following item.
+% Change with \cs{renewcommand}.
+% \bigskip
+%
+% \DescribeEnv{docsidebar} \oarg{title} \qquad Creates a sidebar within the document.
+% See \cref{ex:docsidebar} on \cpageref{ex:docsidebar}.
+%
+%
+%
+%
+% \subsection{Formatted objects}
+%
+% Macros to format references to various kinds of objects.
+%
+% This \pkg{dtxdescribe} package documentation uses \pkg{erewhon}, \pkg{roboto},
+% and \pkg{inconsolata}, along with \pkg{metalogo},
+% to demonstrate the following font effects.
+%
+%
+% \subsubsection{\LaTeX\ objects}
+%
+% \DescribeMacro{\pkg} \pkg{packagename}, also for a \pkg{classname}
+
+% \DescribeMacro{\env} \env{environment}
+
+% \DescribeMacro{\ctr} \ctr{counter}
+
+% \DescribeMacro{\bool} \bool{boolean}
+
+% \DescribeMacro{\optn} \optn{option}: 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} \progcode{inline program code}:
+% Escape underscores and other special characters such as \{, \%, \$.
+
+% \DescribeMacro{\prog} \prog{grep}, \prog{make}: A program name. Underscores allowed.
+
+% \DescribeMacro{\filenm} \filenm{file_name}: Underscores allowed.
+
+% \DescribeMacro{\UI} \UI{General user-interface text.} What the user sees on the display.
+% Also see the \env{UIdisplay} environment.
+%
+% \DescribeMacro{\cmds} \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} \element{element}: \HTML \Slash \CSS\ element
+
+% \DescribeMacro{\attribute} \attribute{attribute}: \HTML \Slash \CSS\ attribute
+
+% \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{\MathML} \MathML: Mathematical Markup Language
+
+% \DescribeMacro{\CTAN} \CTAN: Comprehensive \TeX\ Archive Network
+
+% \DescribeMacro{\TDS} \TDS: \TeX\ Directory Structure
+%
+%
+% \subsubsection{Acronyms, brand names, trademarks}
+%
+% \DescribeMacro{\brand} \brand{Brandname}, \brand{Company Name}
+
+% \DescribeMacro{\acro} \acro{acro}: Acronym
+
+% \DescribeMacro{\supregistered} Superscript trademark symbol\supregistered
+%
+%
+%
+%
+% \subsection{Logos}
+%
+% Several additional logos are provided:
+%
+% \DescribeMacro{\LuaTeX} \LuaTeX
+%
+% \DescribeMacro{\LuaLaTeX} \LuaLaTeX
+%
+% \DescribeMacro{\XeTeX} \XeTeX, with reversed E if \pkg{graphics} is loaded.
+%
+% \DescribeMacro{\XeLaTeX} \XeLaTeX, with reversed E if \pkg{graphics} is loaded.
+%
+% \DescribeMacro{\AmS} \AmS
+%
+% \DescribeMacro{\LyX} \LyX
+%
+% \DescribeMacro{\BibTeX} \BibTeX
+%
+% \DescribeMacro{\MakeIndex} \MakeIndex
+%
+% \DescribeMacro{\ConTeXt} \ConTeXt
+%
+% \DescribeMacro{\MiKTeX} \MiKTeX
+%
+%
+%
+%
+% \subsection{Dashes and slashes}
+%
+% \DescribeMacro{\thinskip} A breakable thin skip.
+%
+% \DescribeMacro{\endash} An endash: \endash
+%
+% \DescribeMacro{\emdash} An emdash: \emdash
+%
+% \DescribeMacro{\thinbrspace} A thin space which allows a line break.
+%
+% \DescribeMacro{\thinthinbrspace} A very thin space which allows a line break.
+%
+% \DescribeMacro{\Dash} An unbreakeable thin space, emdash, and breakable thin space:
+% A \Dash B
+%
+% \DescribeMacro{\dash} An unbreakeable thin space, endash, and breakable thin space:
+% A \dash B
+%
+% \DescribeMacro{\Slash} An unbreakable very thin space, a slash, and a breakable very thin space:
+%
+% \begin{tabular}{rll}
+% Command & Result \\ \hline
+% |A--B| & A--B & (not breakable) \\
+% |A \dash B| & A \dash B & (only breakable before the B) \\
+% |A -- B| & A -- B & (breakable before or after the dash) \\ \hline
+% |A---B| & A---B & (not breakable) \\
+% |A \Dash B| & A \Dash B & (only breakable before the B) \\
+% |A --- B| & A --- B & (breakable before or after the dash) \\ \hline
+% |A/B| & A/B & (not breakable) \\
+% |A \Slash B| & A \Slash B & (only breakable before the B) \\
+% |A / B| & A / B & (breakable before or after the slash) \\
+% |A~/~B| & A~/~B & (not breakable) \\
+% \end{tabular}
+%
+%
+% \clearpage
+%
+% \section{Examples}
+
+
+% \begin{dtxexample}{Macros\label{ex:macro}}
+% \DescribeMacro{\mymacro} \oarg{optional} \marg{mandatory}
+% A typical macro definition.
+%
+% \DescribeMacro[photograph]{\DeclareFloatingEnvironment}
+% Create a photograph float. \bigskip
+
+% \DescribeMacro[photograph]{\captionsetup}
+% Caption settings for a photograph float.
+
+% \DescribeMacro[photograph]{\cnameref}
+% \pkg{cleveref} name for the photograph float.
+% \end{dtxexample}
+%
+%
+% The optional class is used to label and group tags and index entries.
+% See this document's index entries for examples of this ``photograph''
+% class and the \env{dtxexample} class of macros.
+%
+% The re-defined \cs{DescribeMacro}, \cs{DescribeEnv}, and
+% all the following macros create hyperlinked index entries,
+% \margintag{hyperlinks}
+% along with regular uses of \cs{index}.
+%
+%
+% \clearpage
+%
+% \begin{dtxexample}{Environment\label{ex:environment}}
+% \DescribeEnv{myenvironment} \marg{argument} Short description.
+% \end{dtxexample}
+%
+% The re-defined \cs{DescribeEnv} adds an `Env' tag to the margin,
+% \margintag{add'l tags}
+% and adds ``(environment)'' to its own index entry.
+% Note that environments and all the other new objects
+% defined\margintag{index groups}\index{index>by group}\index{group of objects}
+% by this package each receives two index entries, one by name,
+% and one grouped with others of its kind.
+
+% \Cref{ex:environment} shows descriptive text
+% \watchout[too much text]
+% on the same line as the \cs{DescribeEnvironment}.
+% For macros and environments with many arguments after the name,
+% it may be better to place any additional text in a following paragraph.
+
+% \begin{dtxexample}{Second Environment}
+% \DescribeEnv[kindofenvironment]{otherenvironment}
+% \oarg{opt args} \parg{coordinates} A description.
+% \end{dtxexample}
+%
+% The \env{otherenvironment} will be indexed by itself and also
+% with \env{myenvironment} under the index entry ``environments'',
+% and also under the class |kindofenvironment|.
+%
+%
+% \clearpage
+%
+% \begin{dtxexample}{Booleans and Counters\label{ex:common}}
+% \DescribeBoolean[examples]{sampleboolean} Some description.
+%
+% \DescribeCounter[examples]{samplecounter} Some description.
+% \end{dtxexample}
+%
+% Most of the new \cs{Describe}\rule{.25in}{.4pt} macros behave like the
+% new \cs{DescribeEnv}, placing a tag in the margin, an index entry
+% by name, and another index entry by group.
+%
+
+
+% \begin{dtxexample}{Lengths\label{ex:length}}
+% \DescribeLength[photograph]{\photowidth} Some description.
+% \end{dtxexample}
+
+% Lengths have a leading backslash, but are otherwise described
+% the same as the rest of the objects.
+
+
+% \clearpage
+%
+%
+% \begin{dtxexample}{Packages, Classes, and Options}
+% \DescribePackage[examples]{samplepackage}
+% About a \LaTeX\ package.
+%
+% \DescribeClass[examples]{sample_class}
+% About a \LaTeX\ class.
+%
+% \DescribeOption[examples]{sampleoption}
+% About an option for a package or class.
+% \end{dtxexample}
+%
+%
+% \begin{dtxexample}{Files, Commands, and Programs\label{ex:file}}
+% \DescribeFile[bigfiles]{really_big_file.txt} Some description.
+%
+% \DescribeFile[bigfiles]{another_big_file.txt} Some description.
+%
+% \DescribeFile{lone_file.txt} Some description.
+%
+% \DescribeCommand{OS_command} An operating-system command.
+%
+% \DescribeProgram{program_name} An operating-system program.
+% \end{dtxexample}
+%
+% Filenames, program names, and command names may have underscores,
+% such as tested here.
+% A class is used to group ``bigfiles'' together in the index.
+
+
+% \clearpage
+%
+% \begin{dtxexample}{Keys\label{ex:key}}
+% \DescribeKey[groupofkeys]{firstkey} About the first key
+% of the |groupofkeys| set.
+%
+% \DescribeKey[groupofkeys]{secondkey} About the second key
+% of |groupofkeys|.
+%
+% \DescribeKey[examples]{samplekey} About some key of |otherkeys|.
+%
+% \DescribeKey[examples]{sampletwokey} About another key of |otherkeys|.
+%
+% \DescribeKey{lonekey} A key without a class.
+% \end{dtxexample}
+%
+% See the index key groups.
+%
+%
+% \clearpage
+%
+% \begin{dtxexample}{Arguments\label{ex:arguments}}
+% \DescribeArgument[figure]{[H]}
+% What happens when a figure is [H]ere.
+%
+% \DescribeArgument[figure]{[M]}
+% What happens when a figure is in the [M]argin.
+%
+% \DescribeArgument[\cs{mymacro}]{bold}
+% What happens when \cs{mymacro} is given the |bold| argument.
+% \end{dtxexample}
+%
+% Arguments behave like keys, and may have an optional class to
+% identify their macro or environment, and group their entries
+% in the index.
+%
+% Note the need to use |\cs{mymacro}| for the macro's name.
+% \watchout[macro names]
+%
+%
+% \clearpage
+%
+% \begin{dtxexample}{Object\label{ex:object}}
+% \DescribeObject[color]{somecolor}
+% The color of something.
+%
+% \DescribeObject[color]{othercolor}
+% The other color.
+%
+% \DescribeObject{randomobject} About some random object.
+% \end{dtxexample}
+%
+% Describes an arbitrary programming object, using \cs{ttfamily} text.
+
+
+% \begin{dtxexample}{Other\label{ex:other}}
+% \DescribeOther{license agreement}
+% The following is the fictional license agreement:
+%
+% \DescribeOther{Before \env{myenvironment}}
+% Actions to be done \cs{BeforeBeginEnvironment}.
+%
+% \DescribeOther[otherclass]{Other Item} About the other item.
+%
+% \DescribeOther[otherclass]{Additional Item} About the add'l item.
+% \end{dtxexample}
+%
+% Describes an arbitrary non-programming object, using roman text.
+
+
+% \clearpage
+%
+% \begin{dtxexample}{Description environments\label{ex:description}}
+% \begin{description}
+% \ItemDescribeMacro[descexamples]{\macroname} Describe the macro.
+% \ItemDescribeBoolean[descexamples]{booleanname} Describe the boolean.
+% \ItemDescribeLength[descexamples]{\lengthname} Describe the length.
+% \ItemDescribeKey[descexamples]{keyname} Describe the key.
+% \ItemDescribePackage[descexamples]{package_name} Describe the package.
+% \ItemDescribeClass[descexamples]{class_name} Describe the class.
+% \ItemDescribeFile[descexamples]{file_name} Describe the file.
+% \ItemDescribeProgram[descexamples]{program_name} Describe the program.
+% \ItemDescribeCommand[descexamples]{command_name} Describe the class.
+% \end{description}
+% \end{dtxexample}
+%
+% Uses a \env{description} environment to describe objects.
+
+
+
+% \clearpage
+%
+%
+% \begin{dtxexample}[See \cref{fig:afigure}]
+% {\env{dtxexample}\label{ex:dtxexample}}
+% \begin{figure}
+% \centering\fbox{Contents of the figure.}
+% \caption{A Figure}\label{fig:afigure}
+% \end{figure}
+% \end{dtxexample}
+
+% \Cref{ex:dtxexample}, typeset above, was created with the following code:
+% \begin{sourceverb}
+% \begin{dtxexample}[See \cref{fig:afigure}]
+% {\env{dtxexample}\label{ex:dtxexample}}
+% \begin{figure}
+% \centering\fbox{Contents of the figure.}
+% \caption{A Figure}\label{fig:afigure}
+% \end{figure}
+% \end{dtxexample}
+% \end{sourceverb}
+%
+% When the example was created:
+% \begin{enumerate}
+% \item The ``float'' of type |example| was created,
+% with the caption ``|dtxexample|''
+% and the label |ex:dtxexample|, which points to \cref{ex:dtxexample}.
+% \item The code was displayed verbatim.
+% \item The code was written to the file |dtxexample_cut.tex|.
+% \item The code was \cs{input} from |dtxexample_cut.tex|.
+% \item Executing the code created the figure with
+% caption ``A Figure'' and label |fig:afigure|, which
+% points to \cref{fig:afigure}.
+% \item The cross-reference to the figure was shown on the optional display line
+% by the optional argument to \env{dtxexample}.
+% \item The starred form of \env{dtxexample} was used to create the closing
+% rule below the code, since a float was being generated and nothing followed the
+% code inline. An unstarred version would have created an extra rule.
+% \end{enumerate}
+%
+%
+% \clearpage
+%
+%
+% \begin{dtxexample}
+% {\env{fsourceverb}\label{ex:fsourceverb}}
+% % \begin{fsourceverb}[label=An fsourceverb example]
+% % \newcommand{fdosomething}[1][whattodo]{
+% % doing #1
+% % }
+% % \end{fsourceverb}
+% \end{dtxexample}
+% (The leading |%| characters would be present in the \filenm{dtx} source.)
+% \bigskip
+
+% \begin{dtxexample}
+% {\env{sourcedisplay}\label{ex:sourcedisplay}}
+% \begin{sourcedisplay}
+% \cs{newcommand}\{dosomething\}[1][\textcolor{red}{whattodo}]\{\\
+% \fquad \textcolor{blue}{doing \textcolor{red}{\#1}}\\
+% \}
+% \end{sourcedisplay}
+% \end{dtxexample}
+%
+% \clearpage
+%
+% \begin{dtxexample}
+% {\env{UIdisplay}\label{ex:UIdisplay}}
+% Select:
+% \begin{UIdisplay}
+% \textsf{Preferences $\to$ Plugins $\to$ Files $\to$ HTML}
+% \end{UIdisplay}
+% For the field
+% \begin{UIdisplay}
+% Title heading:
+% \end{UIdisplay}
+% \userentry{H1}
+%
+% \end{dtxexample}
+%
+% \clearpage
+%
+% \begin{dtxexample}
+% {\env{docsidebar}\label{ex:docsidebar}}
+% Main text.
+%
+% More main text.
+%
+% \begin{docsidebar}[A title]
+% An aside, which may help explain something
+% incidental to the main text.
+% \end{docsidebar}
+%
+% Additional main text.
+% \end{dtxexample}
+
+
+
+
+% \clearpage
+%
+% \section{Usage notes}
+%
+% \begin{description}
+%
+% \item[Placement of \cs{Describe} macros:]
+% Typically \LaTeX\ macro and environment definitions are enclosed in
+% \env{macro} and \env{environment} environments at their place in the source code.
+% \cs{DescribeMacro} and \cs{DescribeEnv} would be used elsewhere in the manual
+% to describe how to use the code. \cs{DescribeBoolean} and such might be at
+% their place in the source code, unless they are worthy of discussion for the
+% end-user, in which case they should be in the ``User's Manual'' section of the
+% document.\footnote{Future versions may include \cs{DeclareBoolean} for
+% use at the point where the boolean is defined, creating an index entry
+% with a code line number, and \cs{DescribeBoolean} with a page number index entry for
+% the related discussion in the User's Manual portion of the document.}
+% It may be useful to use \cs{DeclareBoolean} and friends both at the code location
+% and also in the User's Manual section.
+%
+% \item[Extra spaces:] When placing multiple \cs{Describe}, \cs{index}, \cs{margintag}, and
+% \cs{watchout} macros
+% together, care must be taken to avoid extra space in the printed text where
+% these macros occur.
+% A trailing percent character may be used to
+% avoid the extra space:
+% \begin{sourceverb}
+% text text text% <-- avoids extra space
+% \margintag{A comment.}
+% \index{An entry}
+% \index{Another entry}
+% more inline text
+% \end{sourceverb}
+%
+% \item[Unwanted vertical space:] Other environments nested inside a \env{docsidebar}
+% may produce excessive vertical space. It may be required to insert
+% \begin{sourceverb}
+% \vspace*{-\baselineskip}
+% \end{sourceverb}
+%
+% \item[\cs{margintag} placement:] To have the margin tag appear next to the first
+% line of a paragraph, place the \cs{margintag} or \cs{watchout}
+% somewhere after the first few words
+% in the paragraph. The \cs{margintag} may be on its own line,
+% and the rest of the paragraph may follow on the next line.
+% If too many words are printed before the \cs{margintag},
+% the words may wrap to the next line before the tag occurs.
+%
+% \item[Margin tag overlap:] To keep margin tags in proper alignment,
+% use a new paragraph or multiple lines
+% between \cs{margintag}, \cs{watchout}, or \cs{Declare} macros
+%
+% \item[\cs{Describe} inside floats:] When these macros are used inside a float,
+% \margintag{missing tags}\index{margin tag missing}
+% the margin tag is supressed (there is no margin in a float), but the
+% index entries are still created.
+%
+% \end{description}
+
+
+
+
+
+% \clearpage
+
+% \StopEventually{\PrintChanges\PrintIndex}
+
+
+
+% \section{Code}
+
+
+% \subsection{Required packages}
+
+% \DescribePackage{makeidx} One of several index programs must be provided.
+% \DescribePackage{splitidx} One of several index programs must be provided.
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\AtBeginDocument{
+ \@ifpackageloaded{makeidx}{}{
+ \@ifpackageloaded{splitidx}{}{
+ \RequirePackage{makeidx}
+ \makeindex
+ }}
+}
+% \end{macrocode}
+
+% \DescribePackage{etoolbox} v2.6 or later
+% for \cs{BeforeBeginEnvironment}, \cs{AfterEndEnvironment}
+% \begin{macrocode}
+\RequirePackage{etoolbox}[2011/01/03]%
+% \end{macrocode}
+
+% \DescribePackage{xparse} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{xparse}
+% \end{macrocode}
+
+% \DescribePackage{xifthen} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{xifthen}
+% \end{macrocode}
+%
+%
+
+
+% \DescribePackage{xcolor} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{xcolor}
+\definecolor{myurlcolor}{rgb}{0,0,.7}
+\definecolor{mylinkcolor}{rgb}{.7,0,0}
+% \end{macrocode}
+
+
+% \DescribePackage{caption} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{caption}
+% \end{macrocode}
+
+
+% \DescribePackage{newfloat} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{newfloat}
+% \end{macrocode}
+
+
+% \DescribePackage{fancyvrb} Used for the examples.
+% \begin{macrocode}
+\RequirePackage{fancyvrb}
+% \end{macrocode}
+
+
+% \DescribePackage{xstring} Used for \cs{StrSubstitute} for \cs{DescribeFile}.
+% \begin{macrocode}
+\RequirePackage{xstring}
+% \end{macrocode}
+
+
+% \DescribePackage{hyperref}
+% If \pkg{hyperref} is loaded, disable some macros in \PDF\ bookmarks:
+% \margintag{\PDF\ bookmarks}
+% \changes{v1.01}{2019/01/20}{Sanitize \PDF\ bookmarks.}
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{hyperref} package.}
+% \begin{macrocode}
+\AtBeginDocument{
+ \@ifpackageloaded{hyperref}{
+ \pdfstringdefDisableCommands{%
+ \def\quad{ }%
+ \def\\{ }%
+ \def\pkg#1{#1}%
+ \def\ctr#1{#1}%
+ \def\bool#1{#1}%
+ \def\optn#1{#1}%
+ \def\env#1{#1}%
+ \def\cs#1{\textbackslash#1}%
+ \def\,{ }%
+ \def\LuaLaTeX{LuaLaTeX}%
+ \def\XeLaTeX{XeLaTeX}%
+ \def\TeX{TeX}%
+ \def\LaTeX{LaTeX}%
+ \def\LaTeXe{LaTeX2e}%
+ \def\LuaTeX{LuaTeX}%
+ \def\LuaLaTeX{LuaLaTeX}%
+ \def\XeTeX{XeTeX}%
+ \def\AmS{AMS}%
+ \def\Dash{ --- }%
+ \def\dash{ -- }%
+ \def\Slash{/}%
+ \def\prog#1{\detokenize{#1}}%
+ \def\progcode#1{#1}%
+ \def\filenm#1{\detokenize{#1}}%
+ \def\brand#1{#1}%
+ \def\acro#1{#1}%
+ \def\HTML{HTML}%
+ \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\HTML{HTML}%
+ \def\HTMLfive{HTML5}%
+ \def\CSS{CSS}%
+ \def\CSSthree{CSS3}%
+ \def\EPUB{EPUB}%
+ \def\TOC{TOC}%
+ \def\LOF{LOF}%
+ \def\LOT{LOT}%
+ }
+ }
+% \end{macrocode}
+% If \pkg{hyperref} is not loaded, emulate \cs{hyperpage} here.
+% \begin{macrocode}
+ {
+ \newcommand*{\hyperpage}[1]{#1}
+ }
+}
+% \end{macrocode}
+
+
+
+
+% ^^A Several versions of the \warningsign symbol:
+
+% ^^A This version relies on the presence of the fourier font:
+% ^^A \newcommand*{\TakeFourierOrnament}[1]{{%
+% ^^A \fontencoding{U}\fontfamily{futs}\selectfont\char#1}}
+%
+% ^^A \newcommand*{\warningsign}{\TakeFourierOrnament{66}}
+
+% ^^A from: http://tex.stackexchange.com/questions/159669/how-to-print-a-warning-sign-triangle-with-exclamation-point
+% ^^A This version copy/pastes extraneous characters:
+% ^^A \newcommand\warningsign{%
+% ^^A \makebox[1em][c]{%
+% ^^A \makebox[0pt][c]{\raisebox{.1em}{\textbf{\tiny!}}}%
+% ^^A \makebox[0pt][c]{$\bigtriangleup$}}}%
+
+
+% \DescribePackage{pict2e}
+% \begin{macrocode}
+\RequirePackage{pict2e}
+\setlength{\unitlength}{1pt}
+% \end{macrocode}
+
+% \begin{macro}{\warningsign} Prints an exclamation point inside a triangle.
+%
+% Creates a warning sign without relying on the presence of the fourier font.
+% During copy/paste, this shows up as a simple exclamation point.
+% \begin{macrocode}
+\newcommand*{\warningsign}{%
+\begin{picture}(10,9)
+\put(4,1){\scriptsize!}
+\put(0,0){\line(500,866){5}}
+\put(10,0){\line(-500,866){5}}
+\put(0,0){\line(1,0){10}}
+\end{picture}
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \subsection{Gobbling comment characters}
+%
+% \begin{macro}{DTXD@gobble}
+% The \filenm{.dtx} format uses leading percent characters for
+% code to be in the documentation only. Other classes do not.
+% \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
+% \begin{macrocode}
+\@ifpackageloaded{doc}{
+ \newcommand*{\DTXD@gobble}{2}
+}{
+ \newcommand*{\DTXD@gobble}{0}
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \subsection{Vertical spacing}
+% \begin{macrocode}
+\setlength{\marginparsep}{1em}
+\setlength{\marginparpush}{.7ex}
+
+\setlength{\parindent}{0em}
+\setlength{\parskip}{2ex}
+% \end{macrocode}
+%
+% \DescribeLength{\IndexMin} From \pkg{ltxdoc}.
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\ifdef{\IndexMin}
+ {\setlength{\IndexMin}{40ex}}
+ {\newlength{\IndexMin}}
+% \end{macrocode}
+
+
+% \subsection{\pkg{ltxdoc} emulation}
+%
+% If the \pkg{ltxdoc} class is not used, some of its macros are replicated here.
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\@ifclassloaded{ltxdoc}{}{
+ \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
+ \def\cmd@to@cs#1#2{\char\number`#2\relax}
+ \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
+ \providecommand\marg[1]{%
+ {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
+ \providecommand\oarg[1]{%
+ {\ttfamily[}\meta{#1}{\ttfamily]}}
+ \providecommand\parg[1]{%
+ {\ttfamily(}\meta{#1}{\ttfamily)}}
+ \providecommand\url{\texttt}
+}
+% \end{macrocode}
+
+
+% \subsection{\pkg{doc} emulation}
+%
+% If the \pkg{doc} class is not used, some of its macros are replicated here.
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{doc} package.}
+% \begin{macrocode}
+\AtBeginDocument{
+ \@ifpackageloaded{doc}{}{
+ \newenvironment*{macro}[1]{%
+ \PackageError{dtxdescribe}
+ {The 'macro' environment is only\MessageBreak
+ available when using the doc package\MessageBreak
+ with a .dtx source file}
+ {This environment only makes sense for .dtx source.}
+ }{}
+ \newenvironment*{environment}[1]{%
+ \PackageError{dtxdescribe}
+ {The 'environment' environment is only\MessageBreak
+ available when using the doc package\MessageBreak
+ with a .dtx source file}
+ {This environment only makes sense for .dtx source.}
+ }{}
+ \def\MacroFont{\fontencoding\encodingdefault
+ \fontfamily\ttdefault
+ \fontseries\mddefault
+ \fontshape\updefault
+ \small}%
+ \@ifundefined{actualchar}{\def\actualchar{@}}{}
+ \@ifundefined{quotechar}{\def\quotechar{"}}{}
+ \@ifundefined{levelchar}{\def\levelchar{!}}{}
+ \@ifundefined{encapchar}{\def\encapchar{|}}{}
+ \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
+ \setlength\marginparpush{0pt} \setlength\marginparwidth{8pc}
+ \reversemarginpar
+ \DeclareRobustCommand\meta[1]{%
+ \ensuremath\langle
+ \ifmmode \expandafter \nfss@text \fi
+ {%
+ \meta@font@select
+ \edef\meta@hyphen@restore
+ {\hyphenchar\the\font\the\hyphenchar\font}%
+ \hyphenchar\font\m@ne
+ \language\l@nohyphenation
+ #1\/%
+ \meta@hyphen@restore
+ }\ensuremath\rangle
+ }
+ \def\meta@font@select{\itshape}
+ }
+}
+% \end{macrocode}
+
+
+% \subsection{Support macros}
+
+% \begin{macro}{\PrintEnvName} \marg{name} \qquad Prints an environment name.
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\providecommand*{\PrintEnvName}{}
+\renewcommand*{\PrintEnvName}[1]
+ {\strut{\scriptsize{}Env}\quad\MacroFont#1\ }
+% \end{macrocode}
+% \end{macro}
+
+
+
+%
+% \begin{macro}{\DTXD@printtype} \marg{text}
+%
+% Used to print the object class in the margin:
+%
+% \changes{v1.00}{2019/01/09}{Sans tag font.}
+% \begin{macrocode}
+\newcommand*{\DTXD@printtype}[1]
+ {\raggedleft\strut{\scriptsize\sffamily#1}\quad\MacroFont}
+% \end{macrocode}
+% \end{macro}
+
+
+
+
+% \begin{macro}{\usage} \marg{text}
+%
+% Allow hyperlinks in the ``usage'' index entries:
+%
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\providecommand{\usage}{}
+\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\DTXD@origwrindex} Used to bypass \pkg{hyperref} index modifications.
+% \begin{macrocode}
+\let\DTXD@origwrindex\@wrindex
+% \end{macrocode}
+% \end{macro}
+
+
+
+% \begin{macro}{\DTXD@margintag} \marg{class} \marg{name} \marg{margin tag}
+%
+% Creates the margin tag for the object being described.
+%
+% The |class| is used to sub-categories keys into their key/value groups.
+%
+% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \begin{macrocode}
+\newcommand*{\DTXD@margintag}[3]{%
+\@ifundefined{@captype}{% not float?
+\leavevmode%
+\marginpar{%
+\DTXD@printtype{%
+#3% margintag
+\ifblank{#1}{}{ [#1]}% class
+}% Desc@Type
+\texttt{#2}% name
+}% marginpar
+}{}% not float?
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\DTXD@index}
+% \marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
+%
+% Creates the index entries for the object being described, where
+% name has no backslash or underscore.
+%
+% The |class| is used to sub-categories keys into their key/value groups.
+% |main| prints code lines in the index, and |usage| prints page numbers.
+%
+% \begin{macrocode}
+\newcommand*{\DTXD@index}[5]{%
+% \end{macrocode}
+% The |makeindex| program allows each index entry to call a macro by appending
+% a vertical bar and a macro name to each entry.
+% \pkg{hyperref} adds a call by \cs{hyperpage} to each index entry, by appending
+% the phrase \verb+|hyperpage+ to the entry in the |.idx| file.
+% The \pkg{doc} package uses the same mechanism to
+% distinguish between code line entries (\verb+|main+) and
+% references to the use of a macro (\verb+|usage+). The problem is that |makeindex|
+% can only handle one macro call, but \pkg{hyperref} tries to append its \verb+|hyperpage+
+% to the already-existing \verb+|usage+ or \verb+|main+.
+%
+% The solution used for \pkg{dtxdescribe} is to allow \pkg{hyperref} to modify all
+% regular index entries, but use the original definition of \cs{@wrindex}
+% for the \cs{Describe}\rule{.25in}{.4pt} macros, before \pkg{hyperref} modified it.
+% Then, the \cs{usage} macro, defined above, manually adds the hyperlink.
+%
+% Below, \cs{@bsphack} and \cs{@esphack} seem to be required for \cs{@wrindex} to work.
+% \cs{ignorespaces} is used in addition because \cs{Declare} and \cs{index} entries often
+% come in groups.
+% \begin{macrocode}
+\@bsphack%
+\begingroup%
+\DTXD@origwrindex{%
+% \end{macrocode}
+% Index by name:
+%
+% Write the name, the formatted name, the index tag, and the class:
+% \begin{macrocode}
+#2\actualchar{\protect\ttfamily#2} % name
+(#4)% index tag
+\ifblank{#1}{}{ [#1]}% class
+\encapchar #5}%
+% \end{macrocode}
+% Index by tag and class:
+%
+% Write the tag and class as a group, under which is the name and the formatted name.
+% \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
+% \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+#4:\levelchar% index tag
+\ifblank{#1}{}{[#1]:\levelchar}% class
+#2\actualchar{\protect\ttfamily#2}% name
+\encapchar #5}%
+% \end{macrocode}
+% Possibly index by class and name:
+% \begin{macrocode}
+\ifblank{#1}{}{% class given
+\begingroup%
+\DTXD@origwrindex{%
+#1\actualchar[#1]:\levelchar% class
+#2\actualchar{\protect\ttfamily#2} % name
+(#4)% index tag
+\encapchar #5}%
+}% class given
+% \@esphack%
+\@esphack%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\DTXD@margintagindex}
+% \marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
+%
+% Creates the margin tag and the index entries.
+% The |class| is used to sub-categories keys into their key/value groups.
+% \begin{macrocode}
+\newcommand*{\DTXD@margintagindex}[5]{%
+% \@bsphack%
+% \end{macrocode}
+% The margin tag and the name:
+% \begin{macrocode}
+\DTXD@margintag{#1}{#2}{#3}%
+% \end{macrocode}
+% The index entries:
+% \begin{macrocode}
+\DTXD@index{#1}{#2}{#3}{#4}{#5}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DTXD@macroname} \marg{control sequence}
+%
+% Given a control sequence such as \cs{name}, prints its name without the backslash.
+%
+% From:
+% \href{http://tex.stackexchange.com/questions/42318/removing-a-backslash-from-a-character-sequence}
+% {http://tex.stackexchange.com/questions/42318/\\
+% \hspace*{.5in}removing-a-backslash-from-a-character-sequence}
+% \begin{macrocode}
+\begingroup\lccode`\|=`\\
+\lowercase{\endgroup\def\removebs#1{\if#1|\else#1\fi}}
+\newcommand*{\DTXD@macroname}[1]{\expandafter\removebs\string#1}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\DTXD@verbatimcmd} \marg{\cs{name}}
+%
+% While printing to the index file,
+% prints the \cs{name} verbatim.
+% From \cs{SpecialIndex} in the \pkg{doc} package.
+% \begin{macrocode}
+\newcommand*{\DTXD@verbatimcmd}[1]{%
+\string\verb\quotechar*\verbatimchar\string#1\verbatimchar%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\DTXD@cmdmargintagindex}
+% \marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
+%
+% Creates the margin tag and index entries where name is a \cs{macro}.
+%
+% \changes{v1.00}{2019/01/09}{Sans tag font.}
+% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \begin{macrocode}
+\newcommand*{\DTXD@cmdmargintagindex}[5]{%
+\@bsphack%
+% \end{macrocode}
+% Create a margin tag with the name of the macro:
+% \begin{macrocode}
+\@ifundefined{@captype}{% not float?
+\leavevmode%
+\marginpar{%
+\DTXD@printtype{%
+#3% margin tag
+\ifblank{#1}{}{ [#1]}% class
+}% Desc@Type
+\cmd{#2}% name
+}% marginpar
+}{}% not float?
+% \end{macrocode}
+%
+% Create an index entry sorted by the name without its leading backslash,
+% followed by the macro name with the backslash, and the tag.
+% Prepend with the class if given.
+%
+% Write (class):>name=csname (indextag)\verb+|usage+
+% \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+\ifblank{#1}{}{#1\actualchar[#1]:\levelchar}% class
+\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2} % name
+(#4)% index tag
+\encapchar #5}%
+% \end{macrocode}
+% Create an index entry grouped by the tag,
+% then printed and sorted by the macro name with the backslash, and the tag.
+%
+% Write indextag:>(class):>csname\verb+|usage+
+% \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
+% \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+#4:\levelchar% index tag
+\ifblank{#1}{}{[#1]:\levelchar}% class
+\DTXD@verbatimcmd{#2}% name
+\encapchar #5}%
+\@esphack%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+%
+
+
+% \subsection{\cs{DescribeMacro} and \cs{DescribeEnvironment}}
+
+% \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}}
+%
+% Redefined to allow hyperlinked index entries and an optional class:
+%
+% \changes{v1.00}{2019/01/09}{Sans tag font.}
+% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\providecommand*{\DescribeMacro}{}
+\renewcommand*{\DescribeMacro}[2][]{%
+\@bsphack%
+% \end{macrocode}
+% Create the margin tag with the macro's name:
+% \begin{macrocode}
+\@ifundefined{@captype}{% not float?
+\leavevmode%
+\marginpar{%
+\raggedleft%
+\ifblank{#1}{}{{\scriptsize\textsf{[#1]}} }% class
+\cmd{#2}% name
+}% marginpar
+}{}% not float?
+% \end{macrocode}
+% Write the index sorted by the name without the backslash,
+% followed by the actual name with the backslash.
+% Append the class if given.
+%
+% Write name=csname>(class)\verb+|usage+
+% \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name
+\ifblank{#1}{}{\levelchar[#1]}% class
+\encapchar usage}%
+% \end{macrocode}
+% Only if a class was given:
+% \begin{macrocode}
+\ifblank{#1}%
+{}% no class
+{% class given
+% Again, and prepend the class:
+%
+% Write class=(class):>name=csname\verb+|usage+
+% \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+#1\actualchar[#1]:\levelchar%
+\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}%
+\encapchar usage}%
+}% class given
+\@esphack%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+
+% \begin{macro}{\DescribeEnv} \oarg{class} \marg{environment name}
+%
+% Redefined to allow hyperlinked index entries:
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \begin{macrocode}
+\providecommand*{\DescribeEnv}{}
+\renewcommand*{\DescribeEnv}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}
+% \end{macrocode}
+% \end{macro}
+
+
+
+
+% \subsection{New \cs{Describe\dots} macros}
+
+
+% \begin{macro}{\DTX@filename} Stores the filename with a sanitized underscore.
+% \begin{macrocode}
+\newcommand*{\DTXD@filename}{}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\DTXD@filemarginparindex}
+% \marg{class} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
+%
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@filemarginparindex}[5]{%
+% \end{macrocode}
+% Create a detokenized version of the filename\dots
+% \begin{macrocode}
+\renewcommand{\DTXD@filename}{\detokenize{#2}}%
+% \end{macrocode}
+% \dots\ then replace any underscores with a detokenized |\_|,
+% which will print as an underscore when read back from the index file:
+% \begin{macrocode}
+\StrSubstitute{\DTXD@filename}%
+{\detokenize{_}}{\detokenize{\_}}[\DTXD@filename]%
+% \end{macrocode}
+% The original filename is printed in the margin.
+% Any underscore characters have already been disabled
+% by the \cs{catcode} change.
+% \changes{v1.00}{2019/01/10}{Fix: File class.}
+% \begin{macrocode}
+\DTXD@margintag{#1}{#2}{#3}%
+% \end{macrocode}
+% The detokenized and sanitized version is sent to the index file:
+% \begin{macrocode}
+\DTXD@index{#1}{\DTXD@filename}{#3}{#4}{#5}%
+% \end{macrocode}
+% End the group with the disabled underscore,
+% and clean up the extra space from the \cs{catcode} command:
+% \begin{macrocode}
+\endgroup%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\DTXD@DescribeFile} \oarg{class} \marg{name}
+%
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@DescribeFile}[2][]{%
+\DTXD@filemarginparindex{#1}{#2}{File}{file}{usage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribeFile} \marg{name}
+%
+% The underscore character is temporarily disabled, then
+% the name is passed directly to \cs{DTXD@DescribeFile}.
+% \begin{macrocode}
+\newcommand*{\DescribeFile}{%
+\begingroup\catcode`\_=12 \DTXD@DescribeFile%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DTXD@DescribeProgram} \oarg{class} \marg{name}
+%
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@DescribeProgram}[2][]{%
+\DTXD@filemarginparindex{#1}{#2}{Prog}{program}{usage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribeProgram} \marg{name}
+%
+% The underscore character is temporarily disabled, then
+% the name is passed directly to \cs{DTXD@DescribeProgram}.
+% \begin{macrocode}
+\newcommand*{\DescribeProgram}{%
+\begingroup\catcode`\_=12 \DTXD@DescribeProgram%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\DTXD@DescribeCommand} \oarg{class} \marg{name}
+%
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@DescribeCommand}[2][]{%
+\DTXD@filemarginparindex{#1}{#2}{Cmd}{command}{usage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribeCommand} \marg{name}
+%
+% The underscore character is temporarily disabled, then
+% the name is passed directly to \cs{DTXD@DescribeCommand}.
+% \begin{macrocode}
+\newcommand*{\DescribeCommand}{%
+\begingroup\catcode`\_=12 \DTXD@DescribeCommand%
+}
+% \end{macrocode}
+% \end{macro}
+%
+
+
+% \begin{macro}{\DTXD@DescribePackage} \oarg{class} \marg{name}
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@DescribePackage}[2][]{%
+\DTXD@filemarginparindex{#1}{#2}{Pkg}{package}{usage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribePackage} \marg{name}
+%
+% The underscore character is temporarily disabled, then
+% the name is passed directly to \cs{DTXD@DescribePackage}.
+%
+% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
+% \begin{macrocode}
+\newcommand*{\DescribePackage}{%
+\begingroup\catcode`\_=12 \DTXD@DescribePackage%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\DTXD@DescribeClass} \oarg{class} \marg{name}
+%
+% The name may have underscores.
+% \begin{macrocode}
+\newcommand*{\DTXD@DescribeClass}[2][]{%
+\DTXD@filemarginparindex{#1}{#2}{Cls}{class}{usage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribeClass} \marg{name}
+%
+% The underscore character is temporarily disabled, then
+% the name is passed directly to \cs{DTXD@DescribeClass}.
+%
+% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
+% \begin{macrocode}
+\newcommand*{\DescribeClass}{%
+\begingroup\catcode`\_=12 \DTXD@DescribeClass%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\DescribeOption} \oarg{class} \marg{name}
+% \begin{macrocode}
+\newcommand*{\DescribeOption}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeArgument} \oarg{class} \marg{name}
+%
+% The |class| may be used to categorize arguments by their macro or environment name.
+% \begin{macrocode}
+\newcommand*{\DescribeArgument}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeBoolean} \oarg{class} \marg{name}
+% \begin{macrocode}
+\newcommand*{\DescribeBoolean}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeLength} \oarg{class} \marg{name}
+% \begin{macrocode}
+\newcommand*{\DescribeLength}[2][]
+ {\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeCounter} \oarg{class} \marg{name}
+% \begin{macrocode}
+\newcommand*{\DescribeCounter}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeKey} \oarg{class} \marg{name}
+%
+% The |class| may be used to categorize keys by their kev/value group.
+% \begin{macrocode}
+\newcommand*{\DescribeKey}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DescribeObject} \oarg{class} \marg{name}
+%
+% May be used to describe an arbitrary piece of code.
+% Creates a margin tag and index entries with \cs{ttfamily}.
+%
+% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
+% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
+% \begin{macrocode}
+\newcommand*{\DescribeObject}[2][]{%
+\@ifundefined{@captype}{% not float?
+\@bsphack%
+\leavevmode%
+\marginpar{%
+ \raggedleft%
+ \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }
+ \texttt{#2}%
+}%
+}{}% not float?
+\ifblank{#1}%
+{\begingroup%
+\DTXD@origwrindex{%
+#2\actualchar{\protect\ttfamily#2}%
+\encapchar usage%
+}%
+}%
+{%
+\begingroup%
+\DTXD@origwrindex{%
+#2\actualchar{\protect\ttfamily#2} [#1]%
+\encapchar usage%
+}%
+\begingroup%
+\DTXD@origwrindex{%
+#1\actualchar[#1]:\levelchar#2\actualchar{\protect\ttfamily#2}%
+\encapchar usage%
+}%
+}%
+\@esphack%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeOther} \oarg{class} \marg{name}
+%
+% May be used to describe an arbitrary non-programming object.
+% Creates a margin tag and index entries with roman type.
+% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
+% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
+% \begin{macrocode}
+\newcommand*{\DescribeOther}[2][]{%
+\@ifundefined{@captype}{% not float?
+\@bsphack%
+\leavevmode%
+\marginpar{%
+ \raggedleft%
+ \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
+ #2%
+}%
+}{}% not float?
+\ifblank{#1}%
+{%
+\begingroup%
+\DTXD@origwrindex{#2\encapchar usage}%
+}%
+{%
+\begingroup%
+\DTXD@origwrindex{#2 [#1]\encapchar usage}%
+\begingroup%
+\DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
+}%
+\@esphack%
+\ignorespaces%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \subsection{\cs{DescribeDefault}}
+
+% \begin{macro}{\DescribeDefaultcolor}
+% The color of the margin tag used to show the default value.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\DescribeDefaultcolor}{green!50!black}
+% \end{macrocode}
+% \end{macro}
+
+
+
+% \begin{macro}{\DescribeDefault} \marg{value}
+%
+% Creates a colored margin tag showing the booleandefault value.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DescribeDefault}[1]{%
+ \margintag{%
+ \footnotesize%
+ \textcolor{\DescribeDefaultcolor}{%
+ Default: \texttt{#1}%
+ }%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+
+% \subsection{\cs{ItemDescribeMacro}, etc.}
+%
+% The following are for use inside a \env{description}.
+%
+% \begin{macro}{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeMacro}[2][]{%
+\item[\cmd{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeMacro[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeEnv} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeEnv}[2][]{%
+\item[\env{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeEnv[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeArgument} \oarg{class} \marg{argument}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeArgument}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeArgument[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeBoolean} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeBoolean}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeBoolean[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeLength} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeLength}[2][]{%
+\item[\cmd{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeLength[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeCounter} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeCounter}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeCounter[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeKey} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeKey}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeKey[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribePackage} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DTXD@ItemDescribePackage}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribePackage[#1]{#2}%
+\endgroup
+}
+
+\newcommand{\ItemDescribePackage}{%
+\begingroup\catcode`\_=12 \DTXD@ItemDescribePackage%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeClass} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DTXD@ItemDescribeClass}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeClass[#1]{#2}%
+\endgroup
+}
+
+\newcommand{\ItemDescribeClass}{%
+\begingroup\catcode`\_=12 \DTXD@ItemDescribeClass%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeOption} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeOption}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeOption[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\ItemDescribeFile} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DTXD@ItemDescribeFile}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeFile[#1]{#2}%
+\endgroup
+}
+
+\newcommand{\ItemDescribeFile}{%
+\begingroup\catcode`\_=12 \DTXD@ItemDescribeFile%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeProgram} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DTXD@ItemDescribeProgram}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeProgram[#1]{#2}%
+\endgroup
+}
+
+\newcommand{\ItemDescribeProgram}{%
+\begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeCommand} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\DTXD@ItemDescribeCommand}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeCommand[#1]{#2}%
+\endgroup
+}
+
+\newcommand{\ItemDescribeCommand}{%
+\begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeObject} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeObject}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeObject[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeOther} \oarg{class} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeOther}[2][]{%
+\item[\texttt{#2}:]%
+\setlength{\parskip}{1.5ex}%
+\DescribeOther[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+
+
+
+
+
+% \subsection{\cs{margintag}, \cs{watchout}}
+
+
+% \begin{macro}{\margintagcolor}
+% The color of the \cs{margintag}.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\margintagcolor}{blue!70!black}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\margintag} \marg{text}
+%
+% Prints a colored margin tag.
+%
+% \changes{v1.00}{2019/01/09}{Uses \cs{margintacolor}.}
+% \begin{macrocode}
+\newcommand{\margintag}[1]{%
+\@ifundefined{@captype}{% not float?
+\marginpar{\raggedleft\textcolor{\margintagcolor}{#1}}%
+\ignorespaces%
+}{}% not float?
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\watchoutcolor}
+% The color of the \cs{watchout}.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\watchoutcolor}{red!50!black}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\watchout} \oarg{text}
+%
+% Prints a warning sign and optional text.
+%
+% \changes{v0.11}{2018/03/30}{Changed to \cs{raggedleft}.}
+% \begin{macrocode}
+\newcommand{\watchout}[1][]{%
+\@ifundefined{@captype}{% not float?
+ \marginpar{%
+ \raggedleft%
+ \textcolor{\watchoutcolor}{\warningsign\normalsize\quad#1}%
+ }%
+ \ignorespaces%
+}{}% not float?
+}
+% \end{macrocode}
+% \end{macro}
+
+
+% \subsection{The \env{dtxexample} environment}
+%
+% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}.
+%
+% \DescribeFile{dtxexample_cut.tex} Used to store then \cs{input} example code.
+% \changes{v1.00}{2019/01/11}{Cut file name changed to \filenm{dtxexample_cut.tex}}
+%
+% \DescribeObject[color]{DTXD@examplerulecolor} The color of the middle rule in the dtxexample.
+% \begin{macrocode}
+\definecolor{DTXD@examplerulecolor}{rgb}{.9,.9,.9}
+% \end{macrocode}
+%
+% \begin{macro}{\dtxexamplecodename} The text name of the code section.
+% \changes{v1.00}{2019/01/11}{Added.}
+% \begin{macrocode}
+\newcommand*{\dtxexamplecodename}{Code:}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\dtxexampleresultname} The text name of the result section.
+% \changes{v1.00}{2019/01/11}{Added.}
+% \begin{macrocode}
+\newcommand*{\dtxexampleresultname}{Result:}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{environment}{dtxexample} * \oarg{notes/cross-references} \marg{caption \& label}
+%
+% Reads the code listing as a verbatim input using
+% the \pkg{fancybox} package, then displays the code listing
+% as a verbatim output, and also executes the code
+% and displays the result.
+% A title caption is specified,
+% along with optional cross-referencing commands or notes to
+% refer to the results.
+% The unstarred version places the code inside a minipage, forbidding a page break in the
+% middle of the code listing.
+% The starred version does not use a minipage. This is required when the code is too large
+% to fit on a single page.
+%
+% \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
+% \begin{macrocode}
+\NewDocumentEnvironment{dtxexample}{s +O{} m}
+{% start dtxexample
+% \end{macrocode}
+% Copy the environment's contents to the file |dtxexample_cut.tex|:
+% \begin{macrocode}
+\VerbatimOut[gobble=\DTXD@gobble,tabsize=4]{dtxexample_cut.tex}%
+}% start dtxexample
+% \end{macrocode}
+% When the environment closes:
+% \begin{macrocode}
+{% end dtxexample
+% \end{macrocode}
+% Finish the verbatim output:
+% \begin{macrocode}
+\endVerbatimOut
+\par
+\addvspace{\bigskipamount}
+% \end{macrocode}
+% If unstarred, typeset the example in a minipage:
+% \begin{macrocode}
+\IfBooleanTF{#1}{\vspace{\bigskipamount}}{\minipage{\linewidth}}%
+% \end{macrocode}
+% Emulated a float of type ``example'':
+% \begin{macrocode}
+\captionsetup{type=dtxdexample}%
+\hrule\medskip
+\caption{#3}
+% \end{macrocode}
+% Typeset the contents as verbatim:
+% \begin{macrocode}
+\textcolor{DTXD@examplerulecolor}{\smallskip\hrule}
+\smallskip
+{\scriptsize\itshape\dtxexamplecodename}
+\VerbatimInput[tabsize=4]{dtxexample_cut.tex}
+\unskip
+\textcolor{DTXD@examplerulecolor}{\hrule}
+\smallskip
+{\scriptsize\itshape\dtxexampleresultname}
+
+% \end{macrocode}
+% Possible add the optional cross-references or notes:
+% \begin{macrocode}
+\ifstrempty{#2}
+{}
+{{\itshape\small #2}}
+% \end{macrocode}
+% If unstarred, close the \cs{minipage}.
+% \begin{macrocode}
+\IfBooleanTF{#1}{}{\endminipage}%
+} % end dtxexample
+% \end{macrocode}
+% \end{environment}
+
+
+% Outside of the environment's scope, input the example to generate its output
+% and labels:
+% \begin{macrocode}
+\AfterEndEnvironment{dtxexample}
+{%
+% \end{macrocode}
+% Execute the code:
+% \begin{macrocode}
+\par\unskip\input{dtxexample_cut.tex}%
+% \end{macrocode}
+% Closing rule::
+% \begin{macrocode}
+\medskip\hrule%
+}
+% \end{macrocode}
+
+
+% \DescribeMacro[dtxexample]{\DeclareFloatingEnvironment} A new float type for the examples.
+% \begin{macrocode}
+\DeclareFloatingEnvironment[
+fileext=lox,
+listname={List of Examples},
+name=Example,
+placement=hbp
+]{dtxdexample}
+% \end{macrocode}
+
+
+% \DescribeMacro[dtxexample]{\captionsetup} Caption setup for the examples.
+% \begin{macrocode}
+\captionsetup*[dtxdexample]{
+format=hang,
+font=bf,
+justification=raggedright,
+singlelinecheck=false,
+skip=0pt,
+position=top,
+}
+% \end{macrocode}
+
+% \DescribeMacro[dtxexample]{\crefname} Name for \pkg{cleveref}.
+% \begin{macrocode}
+\AtBeginDocument{
+\@ifpackageloaded{cleveref}{\crefname{dtxdexample}{example}{examples}}{}
+}
+% \end{macrocode}
+
+
+
+% \subsection{\env{noindmacro} and \env{noindenvironment}}
+%
+%
+% Similar to \env{macro} and \env{environment}, but not indexed.
+%
+% \begin{environment}{noindmacro} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newenvironment{noindmacro}[1]
+{
+ \setlength{\parskip}{\marginparpush}
+ \leavevmode\par\DTXD@margintag{}{\cmd{#1}}{}
+}
+{\unskip}
+% \end{macrocode}
+% \end{environment}
+%
+%
+% \begin{environment}{noindenvironment} \marg{name}
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newenvironment{noindenvironment}[1]
+{
+ \setlength{\parskip}{\marginparpush}
+ \leavevmode\par\DTXD@margintag{}{#1}{Env}
+}
+{\unskip}
+% \end{macrocode}
+% \end{environment}
+%
+%
+%
+% \subsection{\env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
+%
+% For use in a \env{sourcedisplay}:
+%
+% \begin{macro}{\fquad} Forces a quad indent.
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\fquad}{\hspace*{1em}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\fqquad} Forces a double-quad indent.
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\fqquad}{\hspace*{2em}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\fqqquad} Forces a triple-quad indent.
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\fqqquad}{\hspace*{3em}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{environment}{sourceverb}
+% To typeset a block of source code, verbatim.
+%
+% \changes{v1.00}{2019/01/11}{Added.}
+% \begin{macrocode}
+\DefineVerbatimEnvironment{sourceverb}{Verbatim}
+ {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em}
+\BeforeBeginEnvironment{sourceverb}{\vspace*{-.5\parskip}}
+% \end{macrocode}
+% \end{environment}
+
+% \begin{environment}{fsourceverb}
+% To typeset a framed block of source code, verbatim.
+%
+% \changes{v1.00}{2019/01/11}{Added.}
+% \begin{macrocode}
+ \DefineVerbatimEnvironment{fsourceverb}{Verbatim}
+ {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em,frame=lines}
+\BeforeBeginEnvironment{fsourceverb}{\vspace*{-.5\parskip}}
+% \end{macrocode}
+% \end{environment}
+
+
+% \begin{environment}{sourcedisplay}
+% To typeset a block of source code, allowing direct formatting.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \changes{v1.01}{2019/01/20}{Reduced width.}
+% \begin{macrocode}
+\newenvironment{sourcedisplay}
+{
+ \leavevmode
+ \par
+ \fqquad\minipage{\linewidth-4em}
+ \ttfamily
+}
+{%
+ \endminipage
+ \par
+}
+% \end{macrocode}
+% \end{environment}
+
+
+% \begin{environment}{UIdisplay}
+% To typeset a user interface display.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \changes{v1.01}{2019/01/20}{Reduced width.}
+% \begin{macrocode}
+\newenvironment{UIdisplay}
+{
+ \leavevmode
+ \par
+ \fqquad\minipage{\linewidth-4em}
+ \sffamily\bfseries
+}
+{
+ \endminipage
+ \par
+}
+% \end{macrocode}
+% \end{environment}
+
+
+% \begin{macro}{\userentryname}
+% Text to tell the user to enter the following item.
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand*{\userentryname}{Enter~$\Rightarrow$}
+% \end{macrocode}
+% \end{macro}
+
+
+% \begin{macro}{\userentry} \marg{text to enter}
+%
+% Typesets text to be entered by the users.
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newcommand{\userentry}[1]{%
+\par
+\fqquad%
+\begin{minipage}{\linewidth-2em}
+ {\footnotesize \userentryname}\quad\cmds{#1}
+\end{minipage}
+\par
+}
+% \end{macrocode}
+% \end{macro}
+
+
+
+% \begin{environment}{docsidebar}
+% To typeset a sidebar in the documentation.
+%
+% \changes{v1.00}{2019/01/09}{Added.}
+% \begin{macrocode}
+\newenvironment{docsidebar}[1][]
+{%
+ \quote\unskip\medskip
+ \setlength{\parskip}{1.5ex}%
+ \ifblank{#1}{}{\textit{#1}\newline}%
+ \rule[.5\bigskipamount]{\linewidth}{.4pt}%
+ \newline%
+}
+{%
+ \leavevmode\par
+ \rule[\bigskipamount]{\linewidth}{.4pt}
+ \endquote\unskip
+}
+% \end{macrocode}
+% \end{environment}
+%
+%
+%
+% \subsection{Formatted objects}
+%
+% Macros to format references to various kinds of objects.
+%
+% \changes{v1.00}{2019/01/11}{Added formatted objects.}
+%
+% \subsubsection{\LaTeX\ objects}
+%
+% \begin{macro}{\pkg} or class
+% \begin{macrocode}
+\providerobustcmd*{\pkg}[1]{\mbox{\textsf{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\env}
+% \begin{macrocode}
+\providerobustcmd*{\env}[1]{\mbox{\texttt{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ctr}
+% \begin{macrocode}
+\providerobustcmd*{\ctr}[1]{\mbox{\texttt{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\bool}
+% \begin{macrocode}
+\providerobustcmd*{\bool}[1]{\mbox{\texttt{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\optn}
+% \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}
+% \begin{macrocode}
+\providerobustcmd*{\cmds}[1]{\mbox{\textbf{\texttt{#1}}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\progcode}
+% \begin{macrocode}
+\providerobustcmd*{\progcode}[1]{\mbox{\texttt{#1}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\prog}
+% \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}
+% \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}
+% \begin{macrocode}
+\providerobustcmd*{\element}[1]{\texttt{<#1>}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\attribute}
+% \begin{macrocode}
+\providerobustcmd*{\attribute}[1]{\mbox{\texttt{#1}}}
+% \end{macrocode}
+% \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}
+% \begin{macrocode}
+\providerobustcmd*{\tikz}{Ti\textit{k}z}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\MathML}
+% \begin{macrocode}
+\providerobustcmd*{\MathML}{Math\acro{ML}}
+% \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}
+%
+%
+% \subsubsection{Acronyms, brand names, trademarks}
+%
+% \begin{macro}{\brand}
+% \begin{macrocode}
+\providerobustcmd*{\brand}[1]{\textsc{#1}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\acro}
+% \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}{\LuaTeX} \LuaTeX
+% \begin{macrocode}
+\providerobustcmd*{\LuaTeX}{\mbox{Lua\TeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LuaLaTeX} \LuaLaTeX
+% \begin{macrocode}
+\providerobustcmd*{\LuaLaTeX}{\mbox{Lua\LaTeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\XeTeX}
+% \begin{macro}{\XeLaTeX} \XeTeX, \XeLaTeX
+% \begin{macrocode}
+\providerobustcmd*{\XeTeXrevE}
+ {\hspace{-.1667em}\raisebox{-.5ex}{E}\hspace{-.125em}}
+
+\AtBeginDocument{
+\@ifpackageloaded{graphics}{
+ \renewrobustcmd*{\XeTeXrevE}
+ {\hspace{-.1667em}\raisebox{-.5ex}{\reflectbox{E}}\hspace{-.125em}}
+}{}
+}
+
+\providerobustcmd*{\XeTeX}{\mbox{X\XeTeXrevE\TeX}}
+\providerobustcmd*{\XeLaTeX}{\mbox{X\XeTeXrevE\LaTeX}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\AmS} \AmS
+% \begin{macrocode}
+\providerobustcmd*{\AmS}{%
+ \leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex%
+ \hbox{$\mathcal M$}\kern-.2em\mathcal S$}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LyX} \LyX
+% \begin{macrocode}
+\providerobustcmd*{\LyX}{\textsf{LyX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\BibTeX} \BibTeX
+% \begin{macrocode}
+\providerobustcmd*{\BibTeX}{\mbox{B\textsc{ib}\TeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\MakeIndex} \MakeIndex
+% \begin{macrocode}
+\providerobustcmd*{\MakeIndex}{\prog{MakeIndex}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ConTeXt} \ConTeXt
+% \begin{macrocode}
+\providerobustcmd*{\ConTeXt}{\mbox{Con\TeX{}t}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\MiKTeX} \MiKTeX
+% \begin{macrocode}
+\providerobustcmd*{\MiKTeX}{\mbox{MiK\TeX}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsection{Dashes and slashes}
+%
+% \begin{macro}{\thinskip} A breakable thin skip.
+% \begin{macrocode}
+\DeclareRobustCommand{\thinskip}{\hskip 0.16667em\relax}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endash} An endash: \endash
+% \begin{macrocode}
+\def\endash{–}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\emdash} An emdash: \emdash
+% \begin{macrocode}
+\def\emdash{—}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\thinbrspace} A thin space which allows a line break.
+% \begin{macrocode}
+\newcommand{\thinbrspace}{\hspace{.16667em}\penalty\exhyphenpenalty\hspace{0pt}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\thinthinbrspace} A thin space which allows a line break.
+% \begin{macrocode}
+\newcommand{\thinthinbrspace}{\hspace{.08333em}\penalty\exhyphenpenalty\hspace{0pt}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Dash} An unbreakeable thin space, emdash, and breakable thin space.
+% \begin{macrocode}
+\newrobustcmd{\Dash}{\unskip\thinspace\emdash\thinbrspace}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dash} An unbreakeable thin space, endash, and breakable thin space.
+% \begin{macrocode}
+\newrobustcmd{\dash}{\unskip\thinspace\endash\thinbrspace}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Slash} An unbreakable very thin space, a slash, and a breakable thin space.
+% \begin{macrocode}
+\newrobustcmd{\Slash}{\unskip\hspace{.08333em}/\thinthinbrspace}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \clearpage
+%
+% \section{Compiling \pkg{dtxdescribe}}
+%
+% To compile the \pkg{dtxdescribe} package:
+% \userentry{pdflatex dtxdescribe.ins}
+%
+% To compile the \pkg{dtxdescribe} documentation
+% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
+% \userentry{makeindex -s gglo.ist -o dtxdescribe.gls dtxdescribe.glo}
+% \userentry{makeindex -s gind.ist dtxdescribe}
+% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
+%
+%
+% \iffalse
+%</package>
+% \fi
+
+
+
+
+% \clearpage
+% \pagestyle{plain}
+%
+% \renewcommand{\partname}{}
+% \renewcommand{\thepart}{}
+% \part{Change History and Index}
+%
+%
+% \Finale
+%
+\endinput
diff --git a/macros/latex/contrib/dtxdescribe/dtxdescribe.ins b/macros/latex/contrib/dtxdescribe/dtxdescribe.ins
new file mode 100644
index 0000000000..21713e9840
--- /dev/null
+++ b/macros/latex/contrib/dtxdescribe/dtxdescribe.ins
@@ -0,0 +1,47 @@
+%% dtxdescribe.ins
+%% Copyright 2016 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.
+%%
+%% This work has the LPPL maintenance status `maintained'.
+%%
+%% The Current Maintainer of this work is Brian Dunn.
+%%
+%% This work consists of the files dtxdescribe.dtx and dtxdescribe.ins
+%% and the derived file dtxdescribe.sty.
+\input docstrip.tex
+\keepsilent
+\usedir{tex/latex/ package }
+\preamble
+This is a generated file.
+Copyright 2016 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.
+\endpreamble
+\askforoverwritefalse
+\generate{\file{dtxdescribe.sty}{\from{dtxdescribe.dtx}{package}}}
+\Msg{*********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the}
+\Msg{* following file into a directory searched by TeX:}
+\Msg{*}
+\Msg{* \space\space dtxdescribe.sty}
+\Msg{*}
+\Msg{* To produce the documentation run the file dtxdescribe.dtx}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{*********************************************************}
+\endbatchfile
diff --git a/macros/latex/contrib/dtxdescribe/dtxdescribe.pdf b/macros/latex/contrib/dtxdescribe/dtxdescribe.pdf
new file mode 100644
index 0000000000..25fb713686
--- /dev/null
+++ b/macros/latex/contrib/dtxdescribe/dtxdescribe.pdf
Binary files differ