dtxdescribe (9dec16)

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

2 files changed, 1818 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx
new file mode 100644
index 00000000000..95790045699
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx
@@ -0,0 +1,1771 @@
+
+% \iffalse meta-comment
+%
+% 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.
+%
+% \fi
+
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{dtxdescribe}
+%<package>    [2016/12/08 v0.10 Describe additional object types in dtx source files.]
+%
+%<*driver>
+\documentclass{ltxdoc}
+
+\newcommand*{\mypackagename}{dtxdescribe}
+\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.}
+
+
+\usepackage{lmodern}
+% \usepackage{libertine}
+\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}
+
+% widows and orphans:
+\usepackage[all,defaultlines=2]{nowidow}
+
+
+\usepackage{etoolbox}
+
+\usepackage[log-declarations=false]{xparse}
+
+
+
+% \usepackage{graphicx}
+% \graphicspath{{images/}}
+
+% \usepackage{enumitem}
+
+% \usepackage{array}
+% \usepackage{booktabs}
+% \usepackage{threeparttable}
+
+% \usepackage{fancybox}% must be loaded before fancyvrb
+% \usepackage{fancyvrb}
+
+
+
+% \captionsetup{labelfont={small,bf},textfont={small,bf}}
+% 
+% \captionsetup*[figure]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=2ex,
+% 	labelfont={small,bf},textfont={small,bf}
+% }
+% 
+% \captionsetup*[table]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=1ex,
+% 	labelfont={small,bf},textfont={small,bf}
+% }
+% 
+% \captionsetup*[subfigure]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=2ex,
+% 	labelfont={small},textfont={small}
+% }
+% 
+% \captionsetup*[subtable]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=1ex,
+% 	labelfont={small},textfont={small}
+% }
+% 
+% \captionsetup*[example]{
+% 	format=plain, justification=justified,
+% 	margin=0pt, parskip=0pt, skip=0ex,
+% 	labelfont={bf},textfont={bf}
+% }
+% 
+% \captionsetup*[wrapfigure]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=2ex,
+% 	labelfont={small,bf},textfont={small,bf}
+% }
+% 
+% \captionsetup*[wraptable]{
+% 	style=default, justification=centering,
+% 	margin=0pt, parskip=0pt, skip=1ex,
+% 	labelfont={small,bf},textfont={small,bf}
+% }
+
+
+
+% \usepackage{lipsum}
+
+
+
+% \usepackage{tikz}
+% \usetikzlibrary{positioning,fit,backgrounds,calc,shapes.geometric,shadows}
+% 
+% \usepackage[framemethod=tikz]{mdframed}
+% 
+% \mdfdefinestyle{boxroundshadow}{linewidth=1pt,innerleftmargin=0in,innerrightmargin=0in,%
+% innertopmargin=0in,innerbottommargin=0in,%
+% align=center,roundcorner=3pt,shadow=true,shadowcolor=black!50,shadowsize=4pt,%
+% leftmargin=0pt,rightmargin=0pt,%
+% frametitlebackgroundcolor=black!15,%
+% skipabove=0ex,skipbelow=0ex,%
+% frametitlerulewidth=1pt,frametitleaboveskip=5pt,%
+% }
+% 
+% \newmdenv[style=boxroundshadow,align=center]{mdtightframe}
+% 
+% \newmdenv[style=boxroundshadow,align=center,%
+% 	innertopmargin=3pt,innerbottommargin=3pt,%
+% 	innerleftmargin=3pt,innerrightmargin=3pt]{mdlooseframe}
+
+
+% \usepackage[normalem]{ulem}
+
+
+% \usepackage{comment}
+% \excludecomment{testing}
+
+% \usepackage{morefloats}
+% \usepackage{marginfix}
+
+\usepackage{tocloft}
+\setlength{\cftsubsecnumwidth}{3em}
+\setlength{\cftsubsubsecindent}{2.8em}
+\setlength{\cftsubsubsecnumwidth}{4em}
+\setlength{\cftbeforesubsecskip}{1ex}
+
+% \usepackage{titletoc}
+
+
+
+
+\usepackage{titleps}
+
+\newpagestyle{pageheadfoot}{
+	\headrule
+	\sethead{\pkg{\mypackagename}}{}{\thepage}
+% 	\renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}}
+	\setfoot{}{}{}
+}
+
+\pagestyle{pageheadfoot}
+
+
+
+
+\newcommand*{\lmacro}[1]{\textbackslash#1}
+\newcommand*{\cmds}[1]{\texttt{#1}}
+\newcommand*{\env}[1]{\texttt{#1}}
+\newcommand*{\pkg}[1]{\textsf{#1}}
+\newcommand*{\acro}[1]{\textsc{\lowercase{#1}}}
+
+
+
+
+
+
+
+
+% % \newcommand*{\tikz}{Ti\textit{k}z}
+% \newcommand*{\htmlfive}{\acro{HTML}\oldstylenums{5}}
+% \newcommand*{\cssthree}{\acro{CSS}\oldstylenums{3}}
+% 
+% \newcommand*{\goesto}{$\Rightarrow$}
+
+% \newenvironment{docsidebar}[1][]
+% {\par\addvspace{1.5ex}%
+% \hfill\minipage{.9\linewidth}\raggedright#1\smallskip\hrule\medskip}
+% {\smallskip\hrule\endminipage\hspace*{\fill}\par\addvspace{1.5ex}}
+
+
+
+
+
+% \setlength{\marginparsep}{1em}
+% \setlength{\marginparpush}{2ex}
+\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{369}
+%
+% \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}
+
+
+
+
+% \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\copyright{} 2016} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}
+%
+% \vspace{.5in}
+%
+% {\Large \textup{\quicksummary}}
+%
+%
+% 
+% ^^A % \title{The \pkg{keyfloat} package\thanks{This document
+% ^^A %   corresponds to \pkg{keyfloat}~\fileversion,
+% ^^A %   dated \filedate.}}
+% ^^A % \author{{\small\copyright{} 2016} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}}
+% ^^A % \published{}
+% ^^A % \subtitle{\textup{Subtitle}}
+% ^^A %
+% ^^A % \maketitle
+%
+% \vfill
+%
+%
+% \begin{abstract}
+% \noindent
+% The \pkg{doc} package includes tools for describing macros and environments
+% in \LaTeX\ source |dtx| format.
+% The \pkg{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 \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.
+%
+% Descriptions are best accompanied by examples, so the
+% environment \env{dtxexample} is provided.
+% Contents are displayed verbatim along with a caption and cross-referencing.
+% They are then \cs{input} and executed, and the result is shown.
+% \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
+% 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,
+% \margintag{Too much!}
+% 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{verbatim}
+% %<*driver>
+% \documentclass{ltxdoc}
+% 	...
+% \usepackage{lmodern}
+% 	...
+% \usepackage{dtxdescribe}
+% 	...
+% \usepackage{packagename} % the name of your new package
+% 	...
+% \usepackage[...]{hyperref}
+% \usepackage{...]{cleveref}
+% 	...
+% %</driver>
+% \end{verbatim}
+
+% 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 verisons
+% 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{Pre-existing Macros}
+%
+% \DescribeMacro{\DescribeMacro} \oarg{class} \marg{\cs{name}}
+%
+% The pre-existing macro from the \pkg{doc} is redefined to
+%	allow hyperlinked index entries and 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 pre-existing macro from the \pkg{doc} is redefined to
+%	allow hyperlinked index entries, and also to place
+%	an `Env' tag in front of the name in the margin.
+%	See \cref{ex:environment} on \cpageref{ex:environment}.
+%
+
+
+% \subsection{Macro Arguments}
+%
+% The \cs{Describe}\rule{.25in}{.4pt} 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{Common \LaTeX\ Elements}
+%
+% 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{References to External Packages and Classes}
+%
+% \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, and 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{Additional Tags}
+%
+%
+% \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.
+
+%
+% \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.
+
+
+% \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.
+
+
+
+% \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]{sampleclass}
+% 	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.
+% \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}[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{verbatim}
+% \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{verbatim}
+%
+% 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 |ex_cut.tex|.
+% \item The code was \cs{input} from |ex_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
+%
+% \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.  Try to place the first one directly connected to a word,
+% and the others may follow on the next line if necessary.
+% \begin{verbatim}
+% text text text\margintag{A comment.}\index{An entry}
+% \index{Another entry}
+% more inline text text text
+% \end{verbatim}
+%
+% \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{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}
+
+
+
+
+% ^^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{Support Macros}
+
+
+%    \begin{macrocode}
+\renewcommand*{\PrintEnvName}[1]
+	{\strut{\scriptsize{}Env}\quad\MacroFont#1\ }
+%    \end{macrocode}
+
+
+
+
+%
+% \begin{macro}{\DTXD@printtype} \marg{text}
+%
+% Used to print the object class in the margin:
+%    \begin{macrocode}
+\newcommand*{\DTXD@printtype}[1]
+	{\raggedleft\strut{\scriptsize#1}\quad\MacroFont}
+%    \end{macrocode}
+% \end{macro}
+
+
+
+
+% \begin{macro}{\usage} \marg{text}
+%
+% Allow hyperlinks in the ``usage'' index entries:
+%    \begin{macrocode}
+\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.
+%
+%    \begin{macrocode}
+\newcommand*{\DTXD@margintag}[3]{%
+\@ifundefined{@captype}{% not float?
+\leavevmode%
+\marginpar{%
+\DTXD@printtype{%
+#3% margintag
+\ifblank{#1}{}{ \texttt{#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.
+%    \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+#4s:\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}.
+%
+%    \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}{}{ \texttt{#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+
+%    \begin{macrocode}
+\begingroup%
+\DTXD@origwrindex{%
+#4s:\levelchar% index tag
+\ifblank{#1}{}{[#1]:\levelchar}% class
+\DTXD@verbatimcmd{#2}% name
+\encapchar #5}%
+\@esphack%
+\ignorespaces%
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+
+
+% \subsection{Pre-existing Macros}
+
+% \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}}
+%
+% Redefined to allow hyperlinked index entries and an optional class:
+%    \begin{macrocode}
+\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#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}
+\ifthenelse{\isempty{#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:
+%    \begin{macrocode}
+\renewcommand*{\DescribeEnv}[2][]
+	{\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}
+%    \end{macrocode}
+% \end{macro}
+
+
+
+
+% \subsection{New Describe 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.
+%    \begin{macrocode}
+\DTXD@margintag{}{#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}{\DescribePackage} \oarg{class} \marg{name}
+%    \begin{macrocode}
+\newcommand*{\DescribePackage}[2][]
+	{\DTXD@margintagindex{#1}{#2}{Pkg}{package}{usage}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DescribeClass} \oarg{class} \marg{name}
+%    \begin{macrocode}
+\newcommand*{\DescribeClass}[2][]
+	{\DTXD@margintagindex{#1}{#2}{Cls}{class}{usage}}
+%    \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}.
+%    \begin{macrocode}
+\newcommand*{\DescribeObject}[2][]{%
+\@ifundefined{@captype}{% not float?
+\@bsphack%
+\leavevmode\marginpar{\raggedleft{\scriptsize#1} \texttt{#2}}%
+}{}% not float?
+\ifthenelse{\isempty{#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.
+%    \begin{macrocode}
+\newcommand*{\DescribeOther}[2][]{%
+\@ifundefined{@captype}{% not float?
+\@bsphack%
+\leavevmode\marginpar{\raggedleft{\scriptsize#1} #2}%
+}{}% not float?
+\ifthenelse{\isempty{#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{New Margin Tags}
+
+% \begin{macro}{\margintag} \marg{text}
+%
+% Prints a colored margin tag.
+%    \begin{macrocode}
+\newcommand{\margintag}[1]{%
+\@ifundefined{@captype}{% not float?
+\marginpar{\raggedleft\textcolor{blue!70!black}{#1}}%
+\ignorespaces%
+}{}% not float?
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\watchout} \oarg{text}
+%
+% Prints a warning sign and optional text.
+%    \begin{macrocode}
+\newcommand{\watchout}[1][]{%
+\@ifundefined{@captype}{% not float?
+% \@bsphack%
+\marginpar{\hspace*{\fill}%
+\textcolor{red!50!black}{\warningsign\normalsize\quad#1}}%
+% \@esphack%
+\ignorespaces%
+}{}% not float?
+}
+%    \end{macrocode}
+% \end{macro}
+%
+
+
+% \subsection{The \env{dtxexample} Environment}
+%
+% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}.
+%
+% \DescribeFile{ex_cut.tex} Used to store then \cs{input} example code.
+
+% \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{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.
+
+
+%    \begin{macrocode}
+\NewDocumentEnvironment{dtxexample}{s +O{} m}
+{% start dtxexample
+%    \end{macrocode}
+% Copy the environment's contents to the file |ex_cut.tex|:
+%    \begin{macrocode}
+\VerbatimOut[gobble=2,tabsize=4]{ex_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 Code:}
+\VerbatimInput[tabsize=4]{ex_cut.tex}
+\unskip
+\textcolor{DTXD@examplerulecolor}{\hrule}
+\smallskip
+{\scriptsize\itshape Result:}
+
+%    \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{ex_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}
+
+
+%
+%
+% \iffalse
+%</package>
+% \fi
+
+
+
+
+% \clearpage
+% \pagestyle{plain}
+%
+% \renewcommand{\partname}{}
+% \renewcommand{\thepart}{}
+% \part{Change History and Index}
+%
+%
+% \Finale
+%
+\endinput
diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.ins b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.ins
new file mode 100644
index 00000000000..21713e98406
--- /dev/null
+++ b/Master/texmf-dist/source/latex/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