summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/dtxdescribe/dtxdescribe.dtx')
-rw-r--r--macros/latex/contrib/dtxdescribe/dtxdescribe.dtx730
1 files changed, 675 insertions, 55 deletions
diff --git a/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
index a45f996734..0d3d54db2f 100644
--- a/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
+++ b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
@@ -17,13 +17,13 @@
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{dtxdescribe}
-%<package> [2022/09/08 v1.05 Describe additional object types in source files.]
+%<package> [2022/12/07 v1.06 Describe additional object types in source files.]
%
%<*driver>
\documentclass{ltxdoc}
\newcommand*{\mypackagename}{dtxdescribe}
-\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.}
+\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} or \texttt{tex} source files.}
\usepackage{iftex}
@@ -121,22 +121,27 @@
\usepackage{\mypackagename}
-\usepackage[bookmarks=true,hidelinks,%
-colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,%
-pageanchor=true,hyperindex=true,
-]{hyperref}
-
+\AtBeginDocument{
\hypersetup{%
pdfinfo={%
Title={The LaTeX \mypackagename\ package},%
Author={Brian Dunn},%
Subject={Describe additional object types in dtx source files.]},%
-Keywords={LaTeX, dtx, source, DescribeMacro}%
+Keywords={LaTeX, dtx, source, DescribeMacro},%
+colorlinks,%
+linkcolor=mylinkcolor,%
+urlcolor=myurlcolor,%
+pageanchor=true,
}}
+}
+% \crefname here is required to compile the dtxdescribe documentation
+% using the doc class:
+\AddToHook{begindocument/before}{% Before .aux file is loaded.
\usepackage{cleveref}
-
+\crefname{dtxexamplefloat}{example}{examples}
+}
\renewenvironment{abstract}
{
@@ -170,7 +175,10 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%<*package>
% \fi
%
-% \CheckSum{1211}
+% ^^A *88* remove:
+% \CheckSum{1704}
+%
+% ^^A *88* remove:
%
% \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
@@ -197,6 +205,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.04}{2022/02/01}{\ 2022/02/01}
% \changes{v1.04}{2022/02/01}{\ Corrected copyright date.}
% \changes{v1.05}{2022/09/08}{\ 2022/09/08}
+% \changes{v1.06}{2022/12/07}{\ 2022/12/07}
@@ -270,10 +279,19 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \vfill
%
+% \textcolor{red}{The \pkg{doc} package has changed, and
+% \pkg{dtxdescribe} is not yet fully compatible.
+% When \pkg{dtxdescribe} is used with \pkg{doc},
+% the optional object ``class'' is currently ignored for macros,
+% and not all classes are indexed.}
+%
+% \textcolor{red}{Also, see change in setup of \pkg{hyperref} and \pkg{cleveref}:
+% \Cref{sec:usage} on \cpageref{sec:usage}.}
+%
% \clearpage
%
% \tableofcontents
-% \listofdtxdexamples
+% \listofdtxexamplefloats
% \listoffigures
% ^^A \listoftables
%
@@ -318,8 +336,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \clearpage
% \section{Using \pkg{dtxdescribe}}
+% \label{sec:usage}
-% Place |\usepackage{dtxdescribe}| in the |.dtx| file's driver section:
+% To use \pkg{dtxdescribe} with the \pkg{ltxdoc} classa and \filenm{.dtx} files:
% \begin{sourceverb}
% %<*driver>
% \documentclass{ltxdoc}
@@ -330,18 +349,50 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% ...
% \usepackage{packagename} % the name of your new package
% ...
-% \usepackage[...]{hyperref}
-% \usepackage[...]{cleveref}
+%
+% % hyperref now automatically loaded by \pkg{ltxdoc}.
+%
+% \AtBeginDocument{
+% \hypersetup{...}% If needed.
+% \pdfstringdefDisableCommands{ ... }% If needed.
+% }
+%
+% \AddToHook{begindocument/before}{% Before .aux file is loaded.
+% \usepackage{cleveref}% If needed.
+% \crefname{somename}{name}{names}% If needed.
+% }
+%
% ...
% %</driver>
% \end{sourceverb}
-% Various objects inside the |dtx| file may be described with new
+% To use \pkg{dtxdescribe} with the regular classes, such as \pkg{article},
+% use:
+%
+% \begin{sourceverb}
+% \documentclass{article}
+%
+% \usepackage{dtxdescribe}
+%
+% \usepackage{hyperref}% If needed.
+% \hypersetup{...}% If needed.
+% \pdfstringdefDisableCommands{ ... }% If needed.
+%
+% \usepackage{cleveref}% If needed.
+% \crefname{somename}{name}{names}% If needed.
+%
+% \begin{document}
+% ...
+% \end{document}
+% \end{sourceverb}
+
+
+% Various objects inside the |dtx| or |tex| file may be described with new
% macros such as \cs{DescribeBoolean}, \cs{DescribeLength}, \cs{DescribeCounter},
% similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}.
-% Optional ``classes'' may be assigned to the objects being described, including the new versions
-% of \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
@@ -720,7 +771,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% 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}.
+% See \cref{ex:fsourceverb} on \cpageref{ex:fsourceverb}.
% \bigskip
%
% \DescribeEnv{sourcedisplay} Display source code with manual formatting.
@@ -969,13 +1020,13 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \DescribeMacro{\mymacro} \oarg{optional} \marg{mandatory}
% A typical macro definition.
%
-% \DescribeMacro[photograph]{\DeclareFloatingEnvironment}
-% Create a photograph float. \bigskip
+% \DescribeMacro[photograph]{\DeclareFloatingPhoto}
+% Create a photograph float environment.
-% \DescribeMacro[photograph]{\captionsetup}
+% \DescribeMacro[c=photograph]{\photocaptionsetup}
% Caption settings for a photograph float.
-% \DescribeMacro[photograph]{\cnameref}
+% \DescribeMacro[photograph]{\cphotonameref}
% \pkg{cleveref} name for the photograph float.
% \end{dtxexample}
%
@@ -1102,7 +1153,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \DescribeArgument[figure]{[M]}
% What happens when a figure is in the [M]argin.
%
-% \DescribeArgument[\cs{mymacro}]{bold}
+% \DescribeArgument[\mymacro]{bold}
% What happens when \cs{mymacro} is given the |bold| argument.
% \end{dtxexample}
%
@@ -1110,7 +1161,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% identify their macro or environment, and group their entries
% in the index.
%
-% Note the need to use |\cs{mymacro}| for the macro's name.
+% Note you may need to use |\cs{mymacro}| for the macro's name.
% \watchout[macro names]
%
%
@@ -1133,7 +1184,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \DescribeOther{license agreement}
% The following is the fictional license agreement:
%
-% \DescribeOther{Before \env{myenvironment}}
+% \DescribeOther{Before myenvironment}
% Actions to be done \cs{BeforeBeginEnvironment}.
%
% \DescribeOther[otherclass]{Other Item} About the other item.
@@ -1213,7 +1264,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% When the example was created:
% \begin{enumerate}
-% \item The ``float'' of type |example| was created,
+% \item The ``float'' of type |dtxexamplefloat| was created,
% with the caption ``|dtxexample|''
% and the label |ex:dtxexample|, which points to \cref{ex:dtxexample}.
% \item The code was displayed verbatim.
@@ -1349,14 +1400,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
-
-
% \clearpage
% \StopEventually{\PrintChanges\PrintIndex}
-
+% ^^A *source
% \section{Code}
@@ -1483,11 +1532,11 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\def\LOF{LOF}%
\def\LOT{LOT}%
}
- }
+ }% yes hyperref
% \end{macrocode}
% If \pkg{hyperref} is not loaded, emulate \cs{hyperpage} here.
% \begin{macrocode}
- {
+ {% no hyperref
\newcommand*{\hyperpage}[1]{#1}
}
}
@@ -1518,7 +1567,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\setlength{\unitlength}{1pt}
% \end{macrocode}
+
+
+% \subsection{Warning sign}
+
% \begin{macro}{\warningsign} Prints an exclamation point inside a triangle.
+% Displays as: \warningsign
%
% Creates a warning sign without relying on the presence of the fourier font.
% During copy/paste, this shows up as a simple exclamation point.
@@ -1535,6 +1589,77 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \end{macro}
+% \subsection{Special character handling}
+
+% The literal backslash character:
+% \begin{macrocode}
+\begingroup
+\catcode`\|=0
+\catcode`\\=12
+|gdef|DTXD@backslash{\}
+|endgroup
+% \end{macrocode}
+
+
+
+% \subsection{Patching \pkg{hypdoc}}
+%
+% If \pkg{hyperref} is disabled (by \pkg{lwarp}) then define the
+% missing \cs{hdclindex}.
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\@ifpackageloaded{doc}{
+\@ifpackageloaded{hypdoc}{
+\AddToHook{begindocument/before}[doc/hyperref]{%
+ \ifdoc@hyperref
+ \else
+ \def\hdclindex#1#2{%
+ \ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi%
+ }%
+ \fi
+}
+}{}% hypdoc loaded
+}{}% doc loaded
+% \end{macrocode}
+
+% \pkg{splitidx} is modified to add \verb+|hdpindex{}+ to work with \pkg{hypdoc}.
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\AtBeginDocument{
+\@ifpackageloaded{hypdoc}{
+\@ifpackageloaded{splitidx}{
+\renewcommand*{\@wrsindex}[2][]{%
+ \ifx\relax#1\relax
+ \if@splitidx
+ \@wrsindex[idx]{#2}%
+ \else
+ \def\@tempa{#2}%
+ \if@verbindex\@onelevel@sanitize\@tempa\fi
+ \@wrindex{\@tempa}%
+ \fi
+ \else
+%
+% \def\@tempa{#2}%
+ \def\@tempa{#2\encapchar hdpindex{}}% dtxdescribe
+%
+ \csname index@#1@hook\endcsname
+ \expandafter\ifx\csname @@wrsindex\endcsname\relax
+ \@@@wrsindex{#1}{{\@tempa}{\thepage}}%
+ \else
+ \def\@tempb{\@@wrsindex{#1}}%
+ \expandafter\@tempb\@tempa||\\%
+ \fi
+ \endgroup
+ \@esphack
+ \fi
+}
+}{}% splitidx loaded
+}{}% hypdoc loaded
+}% AtBeginDocument
+% \end{macrocode}
+
+
+
% \subsection{Gobbling comment characters}
%
% \begin{macro}{DTXD@gobble}
@@ -1636,8 +1761,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
}\ensuremath\rangle
}
\def\meta@font@select{\itshape}
- }
-}
+ }% doc loaded
+}% AtBeginDocument
% \end{macrocode}
@@ -1653,7 +1778,6 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \end{macro}
-
%
% \begin{macro}{\DTXD@printtype} \marg{text}
%
@@ -1675,8 +1799,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{}{% not doc package
+
\providecommand{\usage}{}
\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
+
+}% not doc package
% \end{macrocode}
% \end{macro}
@@ -1693,7 +1821,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% Creates the margin tag for the object being described.
%
-% The |class| is used to sub-categories keys into their key/value groups.
+% The |class| is used to sub-categorize keys into their key/value groups.
%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
@@ -1753,15 +1881,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\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
+\ifblank{#1}{}{ [#1]}%
\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.
@@ -1770,10 +1900,11 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\begingroup%
\DTXD@origwrindex{%
#4:\levelchar% index tag
-\ifblank{#1}{}{[#1]:\levelchar}% class
+\ifblank{#1}{}{[#1]:\levelchar}%
#2\actualchar{\protect\ttfamily#2}% name
\encapchar #5}%
% \end{macrocode}
+%
% Possibly index by class and name:
% \begin{macrocode}
\ifblank{#1}{}{% class given
@@ -1800,10 +1931,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\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}%
@@ -1851,6 +1984,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\newcommand*{\DTXD@cmdmargintagindex}[5]{%
\@bsphack%
% \end{macrocode}
+%
% Create a margin tag with the name of the macro:
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
@@ -1883,6 +2017,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
(#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.
%
@@ -1903,6 +2038,267 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
+% \subsection{Key handling for object classes}
+
+% If using \pkg{doc}, the optional key \Slash value argument may also
+% include an object class. This is supported by assigning any unknown
+% key to be the class.
+%
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\ExplSyntaxOn
+\IfPackageLoadedTF{doc}{
+
+\newcommand*{\DTXD@category}{}
+
+\keys_define:nn {doc}
+{
+ c .cs_set:Np = \DTXD@category,
+ unknown .code:n = {%
+ \renewcommand*{\DTXD@category}{\l_keys_key_str}%
+ },
+}
+
+}{}% doc loaded
+\ExplSyntaxOff
+% \end{macrocode}
+
+
+% \subsection{Handling \cs{marginpar} inside a float}
+
+% To avoid a floats lost error, do not print margin tags if inside a float.
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\def\@doc@describe#1#2{% dtxdescribe
+ \ifdoc@noprint\else
+ \@ifundefined{@captype}{% not float? dtxdescribe
+ \marginpar{\raggedleft
+ \strut
+ \doc@providetarget
+ \@nameuse{PrintDescribe#1}{#2}%
+ \ifdefvoid{\DTXD@category}{}{% dtxdescribe
+ \space{\footnotesize[\mbox{\DTXD@category}]}%
+ }%
+ }
+ }{}%
+ \fi
+ \ifdoc@noindex\else
+ \@nameuse{Special#1Index}{#2}%
+ \fi
+ \@esphack
+ \endgroup
+ \ignorespaces}
+% \end{macrocode}
+
+
+
+% \subsection{Handling glossary}
+
+% Fix for \cs{StopEventually} in some conditions:
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\AtBeginDocument{
+\def\HD@guesstoclevel#1{1}
+}
+% \end{macrocode}
+
+
+% \subsection{Catcode handling to support underscores}
+%
+% File names and such may include underscores, so they must be neutralized
+% before processing.
+%
+% \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
+% \begin{macrocode}
+\IfPackageLoadedTF{doc}{%
+
+\def\@NewDocElement#1#2#3{%
+ \doc@macrolikefalse
+ \doc@topleveltrue
+ \def\doc@idxtype{#3}%
+ \def\doc@idxgroup{#3s}%
+ \let\doc@printtype\@empty
+ \csname keys_set:nn\endcsname{doc}{#1}%
+ \ifx\doc@printtype\@empty
+ \@temptokena{}%
+ \else
+ \@temptokena\expandafter{\expandafter
+ \textnormal\expandafter{\expandafter
+ \space\expandafter
+ (\doc@printtype)}}%
+ \fi
+ \@nameedef{Print#2Name}##1{%
+ {\noexpand\MacroFont
+ \ifdoc@macrolike
+ \noexpand\string##1% dtxdescribe
+ \else
+ \noexpand\detokenize\expandafter{##1}% dtxdescribe
+ \fi
+ \the\@temptokena
+ }}%
+ \expandafter\let\csname PrintDescribe#2\expandafter\endcsname
+ \csname Print#2Name\endcsname
+ \edef\doc@expr{%
+ \ifdoc@macrolike
+ \noexpand\doc@createspecialmacrolikeindexes
+ \else
+ \noexpand\doc@createspecialindexes
+ \fi
+ {#2}%
+ }%
+ \expandafter\expandafter\expandafter
+ \doc@expr
+ \expandafter\expandafter\expandafter
+ {\expandafter\doc@idxtype\expandafter}\expandafter
+ {\doc@idxgroup}%
+ \doc@createdescribe{#2}%
+ \ifdoc@macrolike
+ \doc@createenv{TT}{#2}{#3}%
+ \else
+ \doc@createenv{TF}{#2}{#3}%
+ \fi
+}
+
+\newcommand*{\DTXD@maybecategory}{%
+ \ifdefvoid{\DTXD@category}%
+ {}%
+ {\space[%
+ \string\verb%
+ \verbatimchar\DTXD@category\verbatimchar%
+ ]}%
+}
+
+\newcommand*{\DTXD@macrotocsname}[1]{%
+ \ifcat\relax\noexpand#1%
+ \expandafter\expandafter\expandafter\@gobble\expandafter\string
+ \fi
+ #1%
+}
+
+\newcommand*{\DTXD@categorylevelname}
+
+\newcommand*{\DTXD@maybecategorylevel}[1]{%
+ \ifdefvoid{\DTXD@categorylevelname}%
+ {}
+ {%
+ \index{%
+ \DTXD@categorylevelname%
+ \noexpand\actualchar%
+ \string\verb*% %
+ \noexpand\verbatimchar
+ [\DTXD@category]:%
+ \verbatimchar%
+ \noexpand\levelchar%
+\@gtempa\noexpand\actualchar%
+\string\verb% % to fool emacs highlighting
+\noexpand\quotechar%
+%*
+\noexpand\verbatimchar%
+%\noexpand\bslash
+\@gtempa\noexpand\verbatimchar%
+ \ifx\@nil#1\@nil\else \the\@temptokena \fi
+ \noexpand\doc@handleencap{usage}
+ }%
+ }%
+}
+
+
+\newcommand*{\DTXD@findcategorylevelname}{%
+ \edef\DTXD@categorylevelname{\DTXD@category}%
+ \edef\DTXD@categorylevelname{\detokenize\expandafter{\DTXD@categorylevelname}}%
+ \IfBeginWith{\DTXD@categorylevelname}{\DTXD@backslash}
+ {\StrGobbleLeft{\DTXD@categorylevelname}{1}[\DTXD@categorylevelname]}
+ {}
+}
+
+\def\doc@createspecialindexes#1#2#3{%
+ \@temptokena{\space (#2)}%
+ \@temptokenb{#3:}%
+ \@nameedef{SpecialMain#1Index}##1{%
+ \noexpand\@SpecialIndexHelper@##1\noexpand\@nil% dtxdescribe
+ \noexpand\@bsphack
+ \noexpand\DTXD@findcategorylevelname% dtxdescribe
+ \ifdoc@toplevel
+% \noexpand\special@index{##1\noexpand\actualchar
+%
+%
+ \noexpand\special@index{\noexpand\@gtempa\noexpand\actualchar%
+% {\string\ttfamily\space##1}%
+\string\verb% % to fool emacs highlighting% dtxdescribe
+\noexpand\quotechar%
+%*
+\noexpand\verbatimchar% dtxdescribe
+%\noexpand\bslash
+\noexpand\@gtempa\noexpand\verbatimchar% dtxdescribe
+ \ifx\@nil#2\@nil\else \the\@temptokena \fi
+ \noexpand\DTXD@maybecategory% dtxdescribe
+ \noexpand\encapchar main}%
+ \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
+ \fi
+%
+%
+ \ifx\@nil#3\@nil\else
+ \noexpand\special@index{\the\@temptokenb\noexpand\levelchar%
+% ##1\noexpand\actualchar{\string\ttfamily\space##1}%
+\noexpand\@gtempa\noexpand\actualchar% dtxdescribe
+\string\verb% % to fool emacs highlighting% dtxdescribe
+\noexpand\quotechar%
+%*
+\noexpand\verbatimchar% dtxdescribe
+%\noexpand\bslash
+\noexpand\@gtempa\noexpand\verbatimchar% dtxdescribe
+ \noexpand\DTXD@maybecategory% dtxdescribe
+ \noexpand\encapchar main}%
+ \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
+ \fi
+ \noexpand\@esphack}%
+%
+%
+ \@nameedef{Special#1Index}##1{%
+ \noexpand\@SpecialIndexHelper@##1\noexpand\@nil% dtxdescribe
+ \noexpand\@bsphack
+ \noexpand\DTXD@findcategorylevelname% dtxdescribe
+%
+%
+ \ifdoc@toplevel
+ \noexpand\doc@providetarget
+% \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}%
+ \noexpand\index{\noexpand\@gtempa\noexpand\actualchar% dtxdescribe
+\string\verb% % to fool emacs highlighting% dtxdescribe
+\noexpand\quotechar%
+%*
+\noexpand\verbatimchar% dtxdescribe
+%\noexpand\bslash
+\noexpand\@gtempa\noexpand\verbatimchar% dtxdescribe
+ \ifx\@nil#2\@nil\else \the\@temptokena \fi
+ \noexpand\DTXD@maybecategory% dtxdescribe
+ \noexpand\doc@handleencap{usage}}%
+ \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
+ \fi
+%
+%
+ \ifx\@nil#3\@nil\else
+ \noexpand\index{\the\@temptokenb\noexpand\levelchar%
+% ##1\noexpand\actualchar{\string\ttfamily\space##1}
+\noexpand\@gtempa\noexpand\actualchar% dtxdescribe
+\string\verb% % to fool emacs highlighting% dtxdescribe
+\noexpand\quotechar
+%*
+\noexpand\verbatimchar% dtxdescribe
+%\noexpand\bslash
+\noexpand\@gtempa\noexpand\verbatimchar% dtxdescribe
+ \noexpand\DTXD@maybecategory% dtxdescribe
+ \noexpand\doc@handleencap{usage}}%
+ \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
+ \fi
+%
+%
+ \noexpand\@esphack}}
+
+}{}% doc loaded
+% \end{macrocode}
+
+
% \subsection{\cs{DescribeMacro} and \cs{DescribeEnvironment}}
% \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}}
@@ -1914,6 +2310,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{
+}{% not doc
+
\providecommand*{\DescribeMacro}{}
\renewcommand*{\DescribeMacro}[2][]{%
\@bsphack%
@@ -1965,6 +2364,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\@esphack%
\ignorespaces%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
@@ -1975,9 +2376,13 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% Redefined to allow hyperlinked index entries:
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{}{% not doc
+
\providecommand*{\DescribeEnv}{}
\renewcommand*{\DescribeEnv}[2][]
{\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
@@ -2008,8 +2413,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \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]%
+\StrSubstitute{\DTXD@filename}{\detokenize{_}}{\detokenize{\_}}[\DTXD@filename]%
% \end{macrocode}
% The original filename is printed in the margin.
% Any underscore characters have already been disabled
@@ -2049,9 +2453,23 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeFile}.
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=file,
+ idxgroup=Files,
+ printtype=\textit{file}
+]{File}{file}
+
+}{% not doc
+
\newcommand*{\DescribeFile}{%
-\begingroup\catcode`\_=12 \DTXD@DescribeFile%
+ \begingroup\catcode`\_=12 \DTXD@DescribeFile%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2072,9 +2490,23 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeProgram}.
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=program,
+ idxgroup=Programs,
+ printtype=\textit{Prog}
+]{Program}{program}
+
+}{% not doc
+
\newcommand*{\DescribeProgram}{%
\begingroup\catcode`\_=12 \DTXD@DescribeProgram%
}
+}% not doc
+
% \end{macrocode}
% \end{macro}
@@ -2095,9 +2527,23 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% The underscore character is temporarily disabled, then
% the name is passed directly to \cs{DTXD@DescribeCommand}.
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=command,
+ idxgroup=Commands,
+ printtype=\textit{Cmd}
+]{Command}{command}
+
+}{% not doc
+
\newcommand*{\DescribeCommand}{%
\begingroup\catcode`\_=12 \DTXD@DescribeCommand%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2120,9 +2566,24 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=package,
+ idxgroup=Packages,
+ printtype=\textit{Pkg}
+]{Package}{package}
+
+}{% not doc
+
\newcommand*{\DescribePackage}{%
\begingroup\catcode`\_=12 \DTXD@DescribePackage%
}
+
+}% not doc
+
% \end{macrocode}
% \end{macro}
@@ -2144,16 +2605,44 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=class,
+ idxgroup=Classes,
+ printtype=\textit{Cls}
+]{Class}{class}
+
+}{% not doc
+
\newcommand*{\DescribeClass}{%
\begingroup\catcode`\_=12 \DTXD@DescribeClass%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
% \begin{macro}{\DescribeOption} \oarg{class} \marg{name}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=option,
+ idxgroup=Options,
+ printtype=\textit{Opt}
+]{Option}{option}
+
+}{% not doc
+
\newcommand*{\DescribeOption}[2][]
{\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2161,37 +2650,107 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% The |class| may be used to categorize arguments by their macro or environment name.
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=argument,
+ idxgroup=Arguments,
+ printtype=\textit{Arg}
+]{Argument}{argument}
+
+}{% not doc
+
\newcommand*{\DescribeArgument}[2][]
{\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeBoolean} \oarg{class} \marg{name}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=boolean,
+ idxgroup=Booleans,
+ printtype=\textit{bool}
+]{Boolean}{boolenv}
+
+}{% not doc
+
\newcommand*{\DescribeBoolean}[2][]
{\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeLength} \oarg{class} \marg{name}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=true,
+ toplevel=false,
+ idxtype=length,
+ idxgroup=Lengths,
+ printtype=\textit{Len}
+]{Length}{length}
+
+}{% not doc
+
\newcommand*{\DescribeLength}[2][]
{\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeCounter} \oarg{class} \marg{name}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=counter,
+ idxgroup=Counters,
+ printtype=\textit{Ctr}
+]{Counter}{counter}
+
+}{% not doc
+
\newcommand*{\DescribeCounter}[2][]
{\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DescribeHook} \oarg{class} \marg{name}
% \changes{v1.03}{2021/12/18}{Added.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=hook,
+ idxgroup=Hooks,
+ printtype=\textit{Hook}
+]{Hook}{hook}
+
+}{% not doc
+
\newcommand*{\DescribeHook}[2][]
{\DTXD@margintagindex{#1}{#2}{Hook}{hook}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2200,8 +2759,22 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% The |class| may be used to categorize keys by their kev/value group.
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=key,
+ idxgroup=Keys,
+ printtype=\textit{Key}
+]{Key}{key}
+
+}{% not doc
+
\newcommand*{\DescribeKey}[2][]
{\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2216,6 +2789,18 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=object,
+ idxgroup=Objects,
+ printtype=,
+]{Object}{object}
+
+}{% not doc
+
\newcommand*{\DescribeObject}[2][]{%
\@ifundefined{@captype}{% not float?
\@bsphack%
@@ -2251,6 +2836,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\@esphack%
\ignorespaces%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
%
@@ -2263,6 +2850,18 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
+\IfPackageLoadedTF{doc}{% doc
+
+\NewDocElement[
+ macrolike=false,
+ toplevel=false,
+ idxtype=other,
+ idxgroup=Other,
+ printtype=,
+]{Other}{other}
+
+}{% not doc
+
\newcommand*{\DescribeOther}[2][]{%
\@ifundefined{@captype}{% not float?
\@bsphack%
@@ -2289,6 +2888,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\@esphack%
\ignorespaces%
}
+
+}% not doc
% \end{macrocode}
% \end{macro}
@@ -2625,9 +3226,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \subsection{The \env{dtxexample} environment}
%
-% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}.
+% Also see \cref{ex:dtxexample} on \cpageref{ex:dtxexample}.
%
-% \DescribeFile{dtxexample_cut.tex} Used to store then \cs{input} example code.
+% \DescribeFile{dtxexample_cut.tex} Used to store the \cs{input} example code.
% \changes{v1.00}{2019/01/11}{Cut file name changed to \filenm{dtxexample_cut.tex}}
%
% \DescribeObject[color]{DTXD@examplerulecolor} The color of the middle rule in the dtxexample.
@@ -2668,31 +3269,41 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\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:
+%
+% If unstarred, typeset the example in a minipage, else use a float:
% \begin{macrocode}
-\IfBooleanTF{#1}{\vspace{\bigskipamount}}{\minipage{\linewidth}}%
+\IfBooleanTF{#1}%
+ {% minipage
+ \minipage{\linewidth}%
+ \captionsetup{type=dtxexamplefloat}%
+ }%
+ {% float
+ \begin{dtxexamplefloat}%
+ }%
% \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}
@@ -2705,15 +3316,19 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
{\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}.
+%
+% If unstarred, close the float or \cs{minipage}.
% \begin{macrocode}
-\IfBooleanTF{#1}{}{\endminipage}%
+\IfBooleanTF{#1}%
+ {\endminipage}%
+ {\end{dtxexamplefloat}}%
} % end dtxexample
% \end{macrocode}
% \end{environment}
@@ -2725,10 +3340,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\AfterEndEnvironment{dtxexample}
{%
% \end{macrocode}
+%
% Execute the code:
% \begin{macrocode}
\par\unskip\input{dtxexample_cut.tex}%
% \end{macrocode}
+%
% Closing rule::
% \begin{macrocode}
\medskip\hrule%
@@ -2736,20 +3353,20 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \end{macrocode}
-% \DescribeMacro[dtxexample]{\DeclareFloatingEnvironment} A new float type for the examples.
+% \DescribeMacro[dtxexamplefloat]{\DeclareFloatingEnvironment} A new float type for the examples.
% \begin{macrocode}
\DeclareFloatingEnvironment[
fileext=lox,
listname={List of Examples},
name=Example,
placement=hbp
-]{dtxdexample}
+]{dtxexamplefloat}
% \end{macrocode}
-% \DescribeMacro[dtxexample]{\captionsetup} Caption setup for the examples.
+% \DescribeMacro[dtxexamplefloat]{\captionsetup} Caption setup for the examples.
% \begin{macrocode}
-\captionsetup*[dtxdexample]{
+\captionsetup*[dtxexamplefloat]{
format=hang,
font=bf,
justification=raggedright,
@@ -2759,10 +3376,13 @@ position=top,
}
% \end{macrocode}
-% \DescribeMacro[dtxexample]{\crefname} Name for \pkg{cleveref}.
+% \DescribeMacro[dtxexamplefloat]{\crefname} Name for \pkg{cleveref}.
+% \cs{crefname} here is required for documents not using the doc class:
% \begin{macrocode}
-\AtBeginDocument{
-\@ifpackageloaded{cleveref}{\crefname{dtxdexample}{example}{examples}}{}
+\AddToHook{begindocument/before}{% Before .aux file is loaded.
+ \ifdef{\crefname}{
+ \crefname{dtxexamplefloat}{example}{examples}
+ }{}
}
% \end{macrocode}