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.dtx658
1 files changed, 463 insertions, 195 deletions
diff --git a/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
index 1c7ae225e3..0f12529663 100644
--- a/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
+++ b/macros/latex/contrib/dtxdescribe/dtxdescribe.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
-% Copyright 2016-2019 Brian Dunn
+% Copyright 2016-2022 Brian Dunn
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
@@ -17,7 +17,7 @@
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{dtxdescribe}
-%<package> [2019/07/16 v1.02 Describe additional object types in source files.]
+%<package> [2022/02/01 v1.03 Describe additional object types in source files.]
%
%<*driver>
\documentclass{ltxdoc}
@@ -26,6 +26,10 @@
\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.}
+\usepackage{iftex}
+
+\ifpdftex
+
% \usepackage{lmodern}
% \usepackage{libertine}
\usepackage[space]{erewhon}
@@ -41,10 +45,6 @@
\usepackage[utf8]{inputenc}
\usepackage{textcomp} % provides \degree, \textquotesingle, \textmu
-
-
-
-
% copy/paste special unicode symbols:
\input{glyphtounicode}
\pdfglyphtounicode{prime}{2032}% hex
@@ -74,24 +74,26 @@
\newunicodechar{‡}{\ddag}
\newunicodechar{⚠}{\warningsign}
-\usepackage{microtype}
+\else
+
+\usepackage{fontspec}
+
+\setmainfont{Erewhon-Regular}
+\setsansfont{Cabin}
+\setmonofont{inconsolata}
+
+\fi
-\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{xparse}
+
+
+
+\usepackage{microtype}
+
+\usepackage{metalogox}
\usepackage{titleps}
@@ -119,7 +121,7 @@
\usepackage{\mypackagename}
-\usepackage[pdftex,bookmarks=true,hidelinks,%
+\usepackage[bookmarks=true,hidelinks,%
colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,%
pageanchor=true,hyperindex=true,
]{hyperref}
@@ -136,6 +138,21 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\usepackage{cleveref}
+\renewenvironment{abstract}
+ {
+ \bigskip
+ \begin{center}
+ \textbf{\abstractname}
+ \end{center}
+% \small
+ \setlength{\parindent}{2em}
+ \setlength{\parskip}{0ex}
+ }
+ {
+ \bigskip
+ }
+
+
\setcounter{IndexColumns}{2}
\DisableCrossrefs
@@ -153,7 +170,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%<*package>
% \fi
%
-% \CheckSum{1118}
+% \CheckSum{1211}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -176,6 +193,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/11}{\ 2019/01/11}
% \changes{v1.01}{2019/03/22}{\ 2019/03/22}
% \changes{v1.02}{2019/07/16}{\ 2019/07/16}
+% \changes{v1.03}{2022/02/01}{\ 2022/02/01}
@@ -200,12 +218,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \bigskip
%
-% {\small\textcopyright{} 2016--2018} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}
+% {\small\textcopyright{} 2016--2022} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}
%
% \vspace{.5in}
%
% {\Large \textup{\quicksummary}}
%
+% \end{center}
+%
% \vfill
%
%
@@ -214,7 +234,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% 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,
+% booleans, lengths, counters, hooks, keys, packages, classes, options,
% files, commands, arguments, and other objects.
% \pkg{dtxdescribe} also works with the regular document classes, for those
% who do not wish to use the \pkg{ltxdoc} class and \filenm{.dtx} files.
@@ -240,12 +260,13 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% 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}
%
+% \pkg{dtxdescribe} works with pdf\TeX, \XeTeX, and \LuaTeX, and perhaps other engines
+% as well.
+% \end{abstract}
%
% \vfill
%
-% \end{center}
% \clearpage
%
% \tableofcontents
@@ -312,8 +333,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% %</driver>
% \end{sourceverb}
-% Various objects inside the |dtx| file may be described with \cs{DescribeBoolean},
-% \cs{DescribeLength}, \cs{DescribeCounter}, and related macros,
+% Various objects inside the |dtx| file may be described with new
+% macros such as \cs{DescribeBoolean}, \cs{DescribeLength}, \cs{DescribeCounter},
% similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}.
% Optional ``classes'' may be assigned to the objects being described, including the new versions
@@ -419,7 +440,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% See \cref{ex:arguments} on \cpageref{ex:arguments}.
-% \subsection{Booleans, lengths, counters, keys}
+% \subsection{Booleans, lengths, counters, hooks, keys}
%
% See \cref{ex:common} on \cpageref{ex:common}.
%
@@ -438,6 +459,16 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% Describes a counter. Given a `Ctr' tag in the margin and index.
%
%
+% \DescribeMacro{\DescribeHook} \oarg{class} \marg{name}
+%
+% Describes a hook. Given a `Hook' tag in the margin and index.
+% The |class| may be used to categorize hooks by package.
+% Example:
+% \begin{sourceverb}
+% \DescribeHook[LaTeX]{para/begin}
+% \end{sourceverb}
+%
+%
% \DescribeMacro{\DescribeKey} \oarg{class} \marg{name}
%
% Describes a key. Given a `Key' tag in the margin and index.
@@ -523,6 +554,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \DescribeMacro{\ItemDescribeCounter} \oarg{class} \marg{name} A description.
%
+% \DescribeMacro{\ItemDescribeHook} \oarg{class} \marg{name} A description.
+%
% \DescribeMacro{\ItemDescribeKey} \oarg{class} \marg{name} A description.
%
% \DescribeMacro{\ItemDescribePackage} \oarg{class} \marg{package\_name} With underscores.
@@ -558,6 +591,29 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \DescribeDefault{green!50!black}
+% \subsection{Nesting}
+%
+% \DescribeMacro{\shownesting}
+% * \oarg{fraction of \cs{linewidth}} \marg{container name} \marg{contents}
+%
+% It may be useful to show which objects contain which other objects.
+% \cs{shownesting} shows a box enclosing a name for the container,
+% and the container's contents.
+% \cs{shownesting} be nested, showing boxes inside other boxes,
+% which displays how each environment and macro is fit together inside each other.
+%
+% The optional argument is the fraction of \cs{linewidth} to use for the box,
+% from |[0]| to |[1]|.
+% The default is |[1]|.
+% Each \cs{shownesting} starts its own paragraph, unless the star |*| is used,
+% in which case the \cs{shownesting*} appears inline with previous text.
+% To place two \cs{shownesting} boxes side-by-side, use optional arguments to
+% specify less than full \cs{linewidth} for each box, and use \cs{shownesting*} for
+% the second box to place it inline.
+%
+% See \cref{ex:nesting} on \cpageref{ex:nesting} for an example.
+
+
% \subsection{\cs{margintag}, \cs{watchout}}
%
%
@@ -616,13 +672,15 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \subsection{\env{noindmacro} and \env{noindenvironment} environments}
%
-% These only make sense if using the \pkg{ltxdoc} class and \pkg{doc} package
+% These are like \env{macro} and \env{environment}, but not indexed.
% \watchout[\filenm{.dtx} only]
+% These only make sense if using the \pkg{ltxdoc} class and \pkg{doc} package
% to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
% to disable these environments in the resulting \filenm{.sty} file.
-% When using the regular document classes, the \env{noindmacro} and
-% \env{noindenvironment} environments would localize any definitions,
-% and \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
+% When using the regular document classes, \env{noindmacro} and
+% \env{noindenvironment} environments should not be used, as they
+% would localize any definitions.
+% \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
%
% \DescribeEnv{noindmacro} \marg{\cs{name}}
% To document macros which should not be included in the index.
@@ -704,22 +762,32 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% 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},
+% This \pkg{dtxdescribe} package documentation uses \pkg{erewhon}, \pkg{cabin},
+% and \pkg{inconsolata}, along with \pkg{metalogox},
% to demonstrate the following font effects.
%
%
% \subsubsection{\LaTeX\ objects}
%
-% \DescribeMacro{\pkg} \pkg{packagename}, also for a \pkg{classname}
+% \DescribeMacro{\pkg} \marg{packagename} \quad Prints as \pkg{packagename}.
+% Also for a \pkg{classname}.
+
+% \DescribeMacro{\cs} \marg{csname} \quad Prints as \cs{csname}.
+
+% \DescribeMacro{\env} \marg{environment} \quad Prints as \env{environment}.
+
+% \DescribeMacro{\marg} \marg{argument} \quad Prints \marg{arg}. Mandatory argument.
-% \DescribeMacro{\env} \env{environment}
+% \DescribeMacro{\oarg} \marg{argument} \quad Prints \oarg{arg}. Optional argument.
-% \DescribeMacro{\ctr} \ctr{counter}
+% \DescribeMacro{\parg} \marg{argument} \quad Prints \parg{arg}. Picture-mode argument.
-% \DescribeMacro{\bool} \bool{boolean}
+% \DescribeMacro{\ctr} \marg{counter} \quad Prints as \ctr{counter}.
-% \DescribeMacro{\optn} \optn{option}: to a macro, package, class
+% \DescribeMacro{\bool} \marg{boolean} \quad Prints as \bool{boolean}.
+
+% \DescribeMacro{\optn} \marg{option} \quad Prints as \optn{option},
+% for example to a macro, package, class.
% \DescribeMacro{\TOC} \TOC: Table of contents.
@@ -730,17 +798,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \subsubsection{Programs and commands}
-% \DescribeMacro{\progcode} \progcode{inline program code}:
+% \DescribeMacro{\progcode} Prints as \progcode{inline program code}:
% Escape underscores and other special characters such as \{, \%, \$.
-% \DescribeMacro{\prog} \prog{grep}, \prog{make}: A program name. Underscores allowed.
+% \DescribeMacro{\prog} Prints as \prog{grep}, \prog{make}: A program name. Underscores allowed.
-% \DescribeMacro{\filenm} \filenm{file_name}: Underscores allowed.
+% \DescribeMacro{\filenm} Prints as \filenm{file_name}: Underscores allowed.
-% \DescribeMacro{\UI} \UI{General user-interface text.} What the user sees on the display.
+% \DescribeMacro{\UI} Prints as \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.
+% \DescribeMacro{\cmds} Prints as \cmds{Commands to be entered}: What the user enters.
% Escape underscores and other special characters such as \{, \%, \$.
% Also see the \cs{userentry} macro.
%
@@ -770,9 +838,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \DescribeMacro{\URL} \URL: Uniform Resource Locator
-% \DescribeMacro{\element} \element{element}: \HTML \Slash \CSS\ element
+% \DescribeMacro{\element} \marg{element name} \quad Prints as \element{element},
+% an \HTML \Slash \CSS\ element
+
+% \DescribeMacro{\attribute} \marg{attribute name} \quad Prints as \attribute{attribute},
+% an \HTML \Slash \CSS\ attribute.
+% pdf\TeX\ and \XeTeX\ only.
+% \textcolor{\watchoutcolor}{Not for \LuaTeX.}
-% \DescribeMacro{\attribute} \attribute{attribute}: \HTML \Slash \CSS\ attribute
+% \DescribeMacro{\attrib} \marg{attribute name} \quad Prints as \attribute{attribute},
+% an \HTML \Slash \CSS\ attribute.
+% pdf\TeX, \XeTeX, or \LuaTeX.
% \DescribeMacro{\HTML} \HTML: Hypertext Markup Language
@@ -789,18 +865,20 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \DescribeMacro{\tikz} \tikz: Package logo
-% \DescribeMacro{\MathML} \MathML: Mathematical Markup Language
-
% \DescribeMacro{\CTAN} \CTAN: Comprehensive \TeX\ Archive Network
% \DescribeMacro{\TDS} \TDS: \TeX\ Directory Structure
%
+% \DescribeMacro{\MathML} \MathML: Mathematical Markup Language
+%
+% \DescribeMacro{\MathJax} \MathJax: Math on the web.
+%
%
% \subsubsection{Acronyms, brand names, trademarks}
%
-% \DescribeMacro{\brand} \brand{Brandname}, \brand{Company Name}
+% \DescribeMacro{\brand} \marg{name} \quad \brand{Brandname}, \brand{Company Name}
-% \DescribeMacro{\acro} \acro{acro}: Acronym
+% \DescribeMacro{\acro} \marg{acronym} \quad \acro{acro}: Acronym
% \DescribeMacro{\supregistered} Superscript trademark symbol\supregistered
%
@@ -809,7 +887,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% \subsection{Logos}
%
-% Several additional logos are provided:
+% Several additional logos are provided.
+%
+% Also see the \pkg{metalogo} and \pkg{metalogox} packages.
+%
+% \DescribeMacro{\dviTeX} \dviTeX
+%
+% \DescribeMacro{\dviLaTeX} \dviLaTeX
+%
+% \DescribeMacro{\pdfTeX} \pdfTeX
+%
+% \DescribeMacro{\pdfLaTeX} \pdfLaTeX
%
% \DescribeMacro{\LuaTeX} \LuaTeX
%
@@ -1072,6 +1160,31 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% Uses a \env{description} environment to describe objects.
+% \clearpage
+%
+% \begin{dtxexample}{Nesting\label{ex:nesting}}
+% \shownesting{\env{environmentA}}{
+% \shownesting{\cs{macroB}}{
+% \shownesting{\env{environmentC}}{
+% The contents.
+% }
+% }
+% }
+%
+% \shownesting{\env{sidebyside}}{
+% \shownesting[.35]{minipage}{
+% Left contents.
+% }
+% \hfill \cs{hfill} \hfill
+% \shownesting*[.35]{minipage}{
+% Right contents.
+% }
+% }
+% \end{dtxexample}
+%
+% Note the use of the optional arguments to select less than full \cs{linewidth},
+% and the starred form for the second box to place it inline with the \cs{hfill} text.
+
% \clearpage
%
@@ -1192,7 +1305,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% 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
+% \item[Extra spaces:] When placing multiple uses of \cs{Describe}, \cs{index}, \cs{margintag}, and
% \cs{watchout} macros
% together, care must be taken to avoid extra space in the printed text where
% these macros occur.
@@ -1270,12 +1383,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\RequirePackage{xparse}
% \end{macrocode}
-% \DescribePackage{xifthen} Used for the examples.
+% \changes{v1.03}{2021/09/02}{No longer requires \pkg{xifthen}.}
+
+% \DescribePackage{calc} Used for \cs{shownesting}.
% \begin{macrocode}
-\RequirePackage{xifthen}
+\RequirePackage{calc}
% \end{macrocode}
-%
-%
% \DescribePackage{xcolor} Used for the examples.
@@ -1345,7 +1458,6 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\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}%
@@ -1358,6 +1470,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\def\URL{URL}%
\def\element#1{#1}%
\def\attribute#1{#1}%
+ \def\attrib#1{#1}%
\def\HTML{HTML}%
\def\HTMLfive{HTML5}%
\def\CSS{CSS}%
@@ -1580,18 +1693,23 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% The |class| is used to sub-categories keys into their key/value groups.
%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
\newcommand*{\DTXD@margintag}[3]{%
-\@ifundefined{@captype}{% not float?
-\leavevmode%
-\marginpar{%
-\DTXD@printtype{%
-#3% margintag
-\ifblank{#1}{}{ [#1]}% class
-}% Desc@Type
-\texttt{#2}% name
-}% marginpar
-}{}% not float?
+ \@ifundefined{@captype}{% not float?
+ \leavevmode%
+ \marginpar{%
+ {%
+ \hbadness=10000%
+ \hfuzz=5em%
+ \DTXD@printtype{%
+ #3% margintag
+ \ifblank{#1}{}{ [#1]}% class
+ }%
+ \texttt{#2}% name
+ }%
+ }% marginpar
+ }{}% not float?
}
% \end{macrocode}
% \end{macro}
@@ -1731,15 +1849,20 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\@bsphack%
% \end{macrocode}
% Create a margin tag with the name of the macro:
+% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
\@ifundefined{@captype}{% not float?
\leavevmode%
\marginpar{%
-\DTXD@printtype{%
-#3% margin tag
-\ifblank{#1}{}{ [#1]}% class
-}% Desc@Type
-\cmd{#2}% name
+ {%
+ \hbadness=10000%
+ \hfuzz=5em%
+ \DTXD@printtype{%
+ #3% margin tag
+ \ifblank{#1}{}{ [#1]}% class
+ }%
+ \cmd{#2}% name
+ }%
}% marginpar
}{}% not float?
% \end{macrocode}
@@ -1786,6 +1909,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Sans tag font.}
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
+% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
\providecommand*{\DescribeMacro}{}
\renewcommand*{\DescribeMacro}[2][]{%
@@ -1796,12 +1920,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
\@ifundefined{@captype}{% not float?
\leavevmode%
\marginpar{%
-\raggedleft%
-\ifblank{#1}{}{{\scriptsize\textsf{[#1]}} }% class
-\cmd{#2}% name
+ {%
+ \hbadness=10000%
+ \hfuzz=5em%
+ \raggedleft%
+ \ifblank{#1}{}{{\scriptsize\textsf{[#1]}} }% class
+ \cmd{#2}% name
+ }%
}% marginpar
}{}% not float?
% \end{macrocode}
+%
% Write the index sorted by the name without the backslash,
% followed by the actual name with the backslash.
% Append the class if given.
@@ -1810,9 +1939,10 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \begin{macrocode}
\begingroup%
\DTXD@origwrindex{%
-\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name
-\ifblank{#1}{}{\levelchar[#1]}% class
-\encapchar usage}%
+ \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}
@@ -1823,11 +1953,11 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
%
% 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}%
+ \begingroup%
+ \DTXD@origwrindex{%
+ #1\actualchar[#1]:\levelchar%
+ \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}%
+ \encapchar usage}%
}% class given
\@esphack%
\ignorespaces%
@@ -2054,6 +2184,15 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\DescribeHook} \oarg{class} \marg{name}
+% \changes{v1.03}{2021/12/18}{Added.}
+% \begin{macrocode}
+\newcommand*{\DescribeHook}[2][]
+ {\DTXD@margintagindex{#1}{#2}{Hook}{hook}{usage}}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \begin{macro}{\DescribeKey} \oarg{class} \marg{name}
%
% The |class| may be used to categorize keys by their kev/value group.
@@ -2072,35 +2211,39 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
+% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
\newcommand*{\DescribeObject}[2][]{%
\@ifundefined{@captype}{% not float?
-\@bsphack%
-\leavevmode%
-\marginpar{%
- \raggedleft%
- \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }
- \texttt{#2}%
-}%
+ \@bsphack%
+ \leavevmode%
+ \marginpar{%
+ \hbadness=10000%
+ \hfuzz=5em%
+ \raggedleft%
+ \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }
+ \texttt{#2}%
+ }%
}{}% not float?
\ifblank{#1}%
-{\begingroup%
-\DTXD@origwrindex{%
-#2\actualchar{\protect\ttfamily#2}%
-\encapchar usage%
-}%
-}%
{%
-\begingroup%
-\DTXD@origwrindex{%
-#2\actualchar{\protect\ttfamily#2} [#1]%
-\encapchar usage%
-}%
-\begingroup%
-\DTXD@origwrindex{%
-#1\actualchar[#1]:\levelchar#2\actualchar{\protect\ttfamily#2}%
-\encapchar usage%
+ \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%
@@ -2115,27 +2258,30 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
% \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
% \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
+% \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
% \begin{macrocode}
\newcommand*{\DescribeOther}[2][]{%
\@ifundefined{@captype}{% not float?
-\@bsphack%
-\leavevmode%
-\marginpar{%
- \raggedleft%
- \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
- #2%
-}%
+ \@bsphack%
+ \leavevmode%
+ \marginpar{%
+ \hbadness=10000%
+ \hfuzz=5em%
+ \raggedleft%
+ \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
+ #2%
+ }%
}{}% not float?
\ifblank{#1}%
{%
-\begingroup%
-\DTXD@origwrindex{#2\encapchar usage}%
+ \begingroup%
+ \DTXD@origwrindex{#2\encapchar usage}%
}%
{%
-\begingroup%
-\DTXD@origwrindex{#2 [#1]\encapchar usage}%
-\begingroup%
-\DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
+ \begingroup%
+ \DTXD@origwrindex{#2 [#1]\encapchar usage}%
+ \begingroup%
+ \DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
}%
\@esphack%
\ignorespaces%
@@ -2184,9 +2330,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeMacro}[2][]{%
-\item[\cmd{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeMacro[#1]{#2}%
+ \item[\cmd{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeMacro[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2195,9 +2341,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeEnv}[2][]{%
-\item[\env{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeEnv[#1]{#2}%
+ \item[\env{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeEnv[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2206,9 +2352,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeArgument}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeArgument[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeArgument[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2217,9 +2363,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeBoolean}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeBoolean[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeBoolean[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2228,9 +2374,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeLength}[2][]{%
-\item[\cmd{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeLength[#1]{#2}%
+ \item[\cmd{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeLength[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2239,9 +2385,20 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeCounter}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeCounter[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeCounter[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ItemDescribeHook} \oarg{class} \marg{name}
+% \changes{v1.03}{2021/12/18}{Added.}
+% \begin{macrocode}
+\newcommand{\ItemDescribeHook}[2][]{%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeHook[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2250,9 +2407,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeKey}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeKey[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeKey[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2261,14 +2418,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\DTXD@ItemDescribePackage}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribePackage[#1]{#2}%
-\endgroup
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribePackage[#1]{#2}%
+ \endgroup%
}
\newcommand{\ItemDescribePackage}{%
-\begingroup\catcode`\_=12 \DTXD@ItemDescribePackage%
+ \begingroup\catcode`\_=12 \DTXD@ItemDescribePackage%
}
% \end{macrocode}
% \end{macro}
@@ -2277,14 +2434,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\DTXD@ItemDescribeClass}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeClass[#1]{#2}%
-\endgroup
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeClass[#1]{#2}%
+ \endgroup%
}
\newcommand{\ItemDescribeClass}{%
-\begingroup\catcode`\_=12 \DTXD@ItemDescribeClass%
+ \begingroup\catcode`\_=12 \DTXD@ItemDescribeClass%
}
% \end{macrocode}
% \end{macro}
@@ -2293,9 +2450,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeOption}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeOption[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeOption[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2305,14 +2462,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\DTXD@ItemDescribeFile}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeFile[#1]{#2}%
-\endgroup
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeFile[#1]{#2}%
+ \endgroup%
}
\newcommand{\ItemDescribeFile}{%
-\begingroup\catcode`\_=12 \DTXD@ItemDescribeFile%
+ \begingroup\catcode`\_=12 \DTXD@ItemDescribeFile%
}
% \end{macrocode}
% \end{macro}
@@ -2321,14 +2478,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\DTXD@ItemDescribeProgram}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeProgram[#1]{#2}%
-\endgroup
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeProgram[#1]{#2}%
+ \endgroup%
}
\newcommand{\ItemDescribeProgram}{%
-\begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram%
+ \begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram%
}
% \end{macrocode}
% \end{macro}
@@ -2337,14 +2494,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\DTXD@ItemDescribeCommand}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeCommand[#1]{#2}%
-\endgroup
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeCommand[#1]{#2}%
+ \endgroup%
}
\newcommand{\ItemDescribeCommand}{%
-\begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand%
+ \begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand%
}
% \end{macrocode}
% \end{macro}
@@ -2353,9 +2510,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeObject}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeObject[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeObject[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2364,9 +2521,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \changes{v1.00}{2019/01/09}{Added.}
% \begin{macrocode}
\newcommand{\ItemDescribeOther}[2][]{%
-\item[\texttt{#2}:]%
-\setlength{\parskip}{1.5ex}%
-\DescribeOther[#1]{#2}%
+ \item[\texttt{#2}:]%
+ \setlength{\parskip}{1.5ex}%
+ \DescribeOther[#1]{#2}%
}
% \end{macrocode}
% \end{macro}
@@ -2434,6 +2591,35 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
% \end{macro}
+% \subsection{Nesting}
+%
+% Shows a box enclosing a label for the container, and the container's contents.
+% May be nested.
+%
+% \begin{macro}{\shownesting}
+% \oarg{fraction of \cs{linewidth}} \marg{container} \marg{contents}
+% \changes{v1.03}{2021/09/01}{Added.}
+% \begin{macrocode}
+\NewDocumentCommand{\shownesting}{s O{1} m m}{
+ \IfBooleanF{#1}{
+ \par\smallskip
+ }
+ \fbox{
+ \begin{minipage}{#2\linewidth-2em}
+ \hbadness=10000\relax%
+ #3\par\smallskip
+ \hspace{1em}
+ \begin{minipage}{\linewidth-1.5em}
+ #4
+ \end{minipage}
+ \end{minipage}
+ }
+}
+% \end{macrocode}
+% \end{macro}
+
+
+
% \subsection{The \env{dtxexample} environment}
%
% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}.
@@ -2760,31 +2946,62 @@ position=top,
%
% \subsubsection{\LaTeX\ objects}
%
-% \begin{macro}{\pkg} or class
+% \begin{macro}{\pkg} \marg{name} \quad Also useable for class names.
% \begin{macrocode}
\providerobustcmd*{\pkg}[1]{\mbox{\textsf{#1}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\env}
+% \begin{macro}{\cs} \marg{csname} \quad From \pkg{ltxdoc}.
+% \changes{v1.03}{2021/09/02}{Provided.}
+% \begin{macrocode}
+\providerobustcmd*{\cs}[1]{\texttt{\char`\\#1}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\env} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\env}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\ctr}
+% \begin{macro}{\marg} \marg{argument} \quad From \pkg{ltxdoc}.
+% \changes{v1.03}{2021/09/02}{Provided.}
+% \begin{macrocode}
+\providecommand\marg[1]{%
+ {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\oarg} \oarg{argument} \quad From \pkg{ltxdoc}.
+% \changes{v1.03}{2021/09/02}{Provided.}
+% \begin{macrocode}
+\providecommand\oarg[1]{%
+ {\ttfamily[}\meta{#1}{\ttfamily]}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\parg} \parg{argument} \quad From \pkg{ltxdoc}.
+% \changes{v1.03}{2021/09/02}{Provided.}
+% \begin{macrocode}
+\providecommand\parg[1]{%
+ {\ttfamily(}\meta{#1}{\ttfamily)}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\ctr} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\ctr}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\bool}
+% \begin{macro}{\bool} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\bool}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\optn}
+% \begin{macro}{\optn} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\optn}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
@@ -2811,19 +3028,21 @@ position=top,
% \subsubsection{Programs and commands}
-% \begin{macro}{\cmds}
+% \begin{macro}{\cmds} \marg{commands to print}
+% \quad No processing is provided for special characters.
% \begin{macrocode}
\providerobustcmd*{\cmds}[1]{\mbox{\textbf{\texttt{#1}}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\progcode}
+% \begin{macro}{\progcode} \marg{code to print}
+% \quad No processing is provided for special characters.
% \begin{macrocode}
\providerobustcmd*{\progcode}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\prog}
+% \begin{macro}{\prog} \marg{program name} \quad Underscores are allowed.
% \begin{macrocode}
\newcommand*{\DTXD@prog}[1]{%
\mbox{\textsf{\textsl{\detokenize{#1}}}}%
@@ -2838,7 +3057,7 @@ position=top,
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\filenm}
+% \begin{macro}{\filenm} \marg{file name} \quad Underscores are allowed.
% \begin{macrocode}
\newcommand*{\DTXD@filenm}[1]{%
\mbox{\texttt{\detokenize{#1}}}%
@@ -2925,17 +3144,27 @@ position=top,
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\element}
+% \begin{macro}{\element} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\element}[1]{\texttt{<#1>}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\attribute}
+% \begin{macro}{\attribute} \marg{name}
+% \begin{macro}{\attrib} \marg{name}
+%
+% Each of these is ``provided'', and any prior meaning will
+% be unchanged.
+% In particular, \LuaTeX\ uses \cs{attribute}, so its meaning
+% is unchanged if using \LuaTeX.
+% \changes{v1.03}{2021/09/01}{For \LuaTeX.}
% \begin{macrocode}
+\providerobustcmd*{\attrib}[1]{\mbox{\texttt{#1}}}
+
\providerobustcmd*{\attribute}[1]{\mbox{\texttt{#1}}}
% \end{macrocode}
% \end{macro}
+% \end{macro}
% \begin{macro}{\HTML}
% \begin{macrocode}
@@ -2976,12 +3205,6 @@ position=top,
% \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}}
@@ -2994,16 +3217,29 @@ position=top,
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\MathML}
+% \begin{macrocode}
+\providerobustcmd*{\MathML}{Math\acro{ML}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\MathJax}
+% \changes{v1.03}{2021/09/02}{Added.}
+% \begin{macrocode}
+\providerobustcmd*{\MathJax}{\brand{MathJax}}
+% \end{macrocode}
+% \end{macro}
+%
%
% \subsubsection{Acronyms, brand names, trademarks}
%
-% \begin{macro}{\brand}
+% \begin{macro}{\brand} \marg{name}
% \begin{macrocode}
\providerobustcmd*{\brand}[1]{\textsc{#1}}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\acro}
+% \begin{macro}{\acro} \marg{acronym}
% \begin{macrocode}
\providerobustcmd*{\acro}[1]{\textsc{\lowercase{#1}}}
% \end{macrocode}
@@ -3022,6 +3258,34 @@ position=top,
%
% \changes{v1.00}{2019/01/11}{Added logos.}
%
+% \begin{macro}{\dviTeX} \dviTeX
+% \changes{v1.03}{2021/09/02}{Added.}
+% \begin{macrocode}
+\providerobustcmd*{\dviTeX}{\mbox{\DVI\,\TeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dviLaTeX} \dviLaTeX
+% \changes{v1.03}{2021/09/02}{Added.}
+% \begin{macrocode}
+\providerobustcmd*{\dviLaTeX}{\mbox{\DVI\,\LaTeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pdfTeX} \pdfTeX
+% \changes{v1.03}{2021/09/02}{Added.}
+% \begin{macrocode}
+\providerobustcmd*{\pdfTeX}{\mbox{\PDF\,\TeX}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\pdfLaTeX} \pdfLaTeX
+% \changes{v1.03}{2021/09/02}{Added.}
+% \begin{macrocode}
+\providerobustcmd*{\pdfLaTeX}{\mbox{\PDF\,\LaTeX}}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\LuaTeX} \LuaTeX
% \begin{macrocode}
\providerobustcmd*{\LuaTeX}{\mbox{Lua\TeX}}
@@ -3116,13 +3380,17 @@ position=top,
%
% \begin{macro}{\thinbrspace} A thin space which allows a line break.
% \begin{macrocode}
-\newcommand{\thinbrspace}{\hspace{.16667em}\penalty\exhyphenpenalty\hspace{0pt}}
+\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}}
+\newcommand{\thinthinbrspace}{%
+ \hspace{.08333em}\penalty\exhyphenpenalty\hspace{0pt}%
+}
% \end{macrocode}
% \end{macro}
%