Debian Codegraph @

texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx

raw
1
2 % \iffalse meta-comment
3 %
4 % Copyright 2016-2024 Brian Dunn
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % http://www.latex-project.org/lppl.txt
11 % and version 1.3 or later is part of all distributions of LaTeX
12 % version 2005/12/01 or later.
13 %
14 % \fi
15 %
16 %
17 % \iffalse
18 %<package>\NeedsTeXFormat{LaTeX2e}
19 %<package>\ProvidesPackage{dtxdescribe}
20 %<package> [2024/01/20 v1.09 Describe additional object types in source files.]
21 %
22 %<*driver>
23 \documentclass{ltxdoc}
24
25 \newcommand*{\mypackagename}{dtxdescribe}
26 \newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} or \texttt{tex} source files.}
27
28
29 \usepackage{iftex}
30
31 \ifpdftex
32
33 % \usepackage{lmodern}
34 % \usepackage{libertine}
35 \usepackage[space]{erewhon}
36 % \usepackage{sourceserifpro}
37 \usepackage{cabin}
38 % \usepackage{sourcesanspro}
39 % \usepackage{sourcecodepro}
40 \usepackage{inconsolata}
41 % \usepackage{tgcursor}
42 % \usepackage{dejavu}
43
44 \usepackage[T1]{fontenc}
45 \usepackage[utf8]{inputenc}
46 \usepackage{textcomp} % provides \degree, \textquotesingle, \textmu
47
48 % copy/paste special unicode symbols:
49 \input{glyphtounicode}
50 \pdfglyphtounicode{prime}{2032}% hex
51 \pdfglyphtounicode{diameter}{2300}% diameter
52 \pdfglyphtounicode{warningsign}{26A0}% warning sign
53 \pdfgentounicode=1
54
55 \usepackage{newunicodechar}
56 \newunicodechar{ff}{ff}
57 \newunicodechar{fi}{fi}
58 \newunicodechar{fl}{fl}
59 \newunicodechar{ffi}{ffi}
60 \newunicodechar{ffl}{ffl}
61 % \newunicodechar{°}{\degree}
62 \newunicodechar{ρ}{\ensuremath{\rho}}
63 \newunicodechar{⨯}{\texttimes}
64 \newunicodechar{⁄}{\textfractionsolidus}
65 % \newunicodechar{®}{\textregistered}
66 % \newunicodechar{©}{\textcopyright}
67 \newunicodechar{—}{---}
68 \newunicodechar{–}{--}
69 % \newunicodechar{”}{''}
70 % \newunicodechar{“}{``}
71 % \newunicodechar{§}{\S}
72 % \newunicodechar{¶}{\P}
73 % \newunicodechar{†}{\dag}
74 \newunicodechar{‡}{\ddag}
75 \newunicodechar{⚠}{\warningsign}
76
77 \else
78
79 \usepackage{fontspec}
80
81 \setmainfont{Erewhon-Regular}
82 \setsansfont{Cabin}
83 \setmonofont{inconsolata}
84
85 \fi
86
87
88 \usepackage{etoolbox}
89
90 \usepackage{xparse}
91
92
93
94 \usepackage{microtype}
95
96 \usepackage{metalogox}
97
98 \usepackage{titleps}
99
100 \newpagestyle{pageheadfoot}{
101 \headrule
102 \sethead{\pkg{\mypackagename}}{}{\thepage}
103 % \renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}}
104 \setfoot{}{}{}
105 }
106
107 \pagestyle{pageheadfoot}
108
109
110
111 % Better spacing for \Describe... margin tags:
112 \setlength{\marginparsep}{1em}
113 \setlength{\marginparpush}{.7ex}
114
115 \setlength{\parindent}{0em}
116 \setlength{\parskip}{2ex}
117
118 \setlength{\IndexMin}{40ex}
119
120
121
122 \usepackage{\mypackagename}
123
124 \AtBeginDocument{
125 \hypersetup{%
126 pdfinfo={%
127 Title={The LaTeX \mypackagename\ package},%
128 Author={Brian Dunn},%
129 Subject={Describe additional object types in dtx source files.]},%
130 Keywords={LaTeX, dtx, source, DescribeMacro},%
131 colorlinks,%
132 linkcolor=mylinkcolor,%
133 urlcolor=myurlcolor,%
134 pageanchor=true,
135 }}
136 }
137
138
139 % \crefname here is required to compile the dtxdescribe documentation
140 % using the doc class:
141 \AddToHook{begindocument/before}{% Before .aux file is loaded.
142 \usepackage{cleveref}
143 \crefname{dtxexamplefloat}{example}{examples}
144 }
145
146 \renewenvironment{abstract}
147 {
148 \bigskip
149 \begin{center}
150 \textbf{\abstractname}
151 \end{center}
152 % \small
153 \setlength{\parindent}{2em}
154 \setlength{\parskip}{0ex}
155 }
156 {
157 \bigskip
158 }
159
160
161 \setcounter{IndexColumns}{2}
162
163 \DisableCrossrefs
164 \CodelineIndex
165 \RecordChanges
166 \begin{document}
167 \DocInput{\mypackagename.dtx}
168 \end{document}
169 %
170 %</driver>
171 %
172 % \fi
173 %
174 % \iffalse
175 %<*package>
176 % \fi
177 %
178
179 % \changes{v0.10}{2016/12/08}{\ 2016/12/08 Initial ver}
180 % \changes{v0.11}{2018/03/30}{\ 2018/03/30}
181 % \changes{v1.00}{2019/01/11}{\ 2019/01/11}
182 % \changes{v1.01}{2019/03/22}{\ 2019/03/22}
183 % \changes{v1.02}{2019/07/16}{\ 2019/07/16}
184 % \changes{v1.03}{2022/02/01}{\ 2022/02/01}
185 % \changes{v1.04}{2022/02/01}{\ 2022/02/01}
186 % \changes{v1.04}{2022/02/01}{\ Corrected copyright date.}
187 % \changes{v1.05}{2022/09/08}{\ 2022/09/08}
188 % \changes{v1.06}{2022/12/07}{\ 2022/12/07}
189 % \changes{v1.07}{2023/01/03}{\ 2023/01/03}
190 % \changes{v1.08}{2024/01/08}{\ 2024/01/08}
191 % \changes{v1.08}{2024/01/08}{\ Updated contact info.}
192 % \changes{v1.09}{2024/01/18}{Improved TOC change log and index entries.}
193 % \changes{v1.09}{2024/01/20}{2024/01/20}
194
195
196
197
198 % \GetFileInfo{\mypackagename.sty}
199 %
200 % \DoNotIndex{\newcommand,\renewcommand,\addtocounter,\begin,\end,\begingroup,\endgroup}
201 % \DoNotIndex{\global,\ifbool,\ifthenelse,\isequivalentto,\let}
202 % \DoNotIndex{\booltrue,\boolfalse}
203 % \expandafter\DoNotIndex\expandafter{\detokenize{\(,\),\,,\\,\#,\$,\%,\^,\_,\~,\ ,\&,\{,\}}}
204 %
205 %
206 % \thispagestyle{empty}
207 % \begin{center}
208 % \vfill
209 % ^^A \includegraphics[width=.3\linewidth]{\mypackagename_logo.pdf}
210 % \vfill
211 % {\Huge The \LaTeX\ \pkg{\mypackagename} Package}
212 % \bigskip
213 %
214 % \fileversion{} --- \filedate
215 %
216 % \bigskip
217 %
218 % {\small\textcopyright{} 2016--2024} Brian Dunn\\
219 % \small \url{https://github.com/bdtc/dtxdescribe}
220 %
221 % \vspace{.5in}
222 %
223 % {\Large \textup{\quicksummary}}
224 %
225 % \end{center}
226 %
227 % \vfill
228 %
229 %
230 % \begin{abstract}
231 % \noindent
232 % The \pkg{doc} package includes tools for describing macros and environments
233 % in \LaTeX\ source \filenm{.dtx} format.
234 % The \pkg{dtxdescribe} package adds additional tools for describing
235 % booleans, lengths, counters, hooks, sockets, plugs, keys, packages, classes, options,
236 % files, commands, arguments, and other objects.
237 % \pkg{dtxdescribe} also works with the regular document classes, for those
238 % who do not wish to use the \pkg{ltxdoc} class and \filenm{.dtx} files.
239 %
240 % Each described item is given a margin tag similar to \cs{DescribeEnv},
241 % and is listed in the index by itself and also by type of object
242 % displayed in parentheses (length, filename, etc).
243 % Each item may be sorted further by an optional category displayed in brackets,
244 % such as |[category_name]|.
245 %
246 % The \env{dtxexample} environment is provided for typesetting example code and its results.
247 % Contents are displayed verbatim along with a caption and cross-referencing.
248 % They are then \cs{input} and executed, and the result is shown.
249 %
250 % Environments are also provided for displaying verbatim or formatted source code,
251 % user-interface displays, and sidebars with titles.
252 %
253 % Macros are provided for formatting the names of inline \LaTeX\ objects such as
254 % packages and booleans, as well as program and file names, file types, internet
255 % objects, the names of certain programs, a number of logos, and inline dashes and slashes.
256 %
257 % \pkg{dtxdescribe} works with the \pkg{ltxdoc} class, but also
258 % works with the standard classes as well, except that
259 % the \env{macro} and \env{environment} environments are not supported.
260 % Either \pkg{makeidx} or \pkg{splitidx} may be loaded by the user.
261 % \pkg{makeidx} will be used by default.
262 %
263 % \pkg{dtxdescribe} works with pdf\TeX, \XeTeX, and \LuaTeX, and perhaps other engines
264 % as well.
265 % \end{abstract}
266 %
267 % \vfill
268 %
269 % \textcolor{red}{See change in setup of \pkg{hyperref} and \pkg{cleveref}:
270 % \Cref{sec:usage} on \cpageref{sec:usage}.}
271 %
272 % \clearpage
273 %
274 % \tableofcontents
275 % \listofdtxexamplefloats
276 % \listoffigures
277 % ^^A \listoftables
278 %
279 %
280 %
281 % \clearpage
282 %
283 %^^A \part{dtxdescribe.sty}
284 %
285 % \section{Introduction}
286 %
287 % The \pkg{doc} package provides \cs{DescribeMacro} and \cs{DescribeEnv}
288 % to help document new macros and environments.
289 % Each generates a heading in the documentation, to which \cs{marg},
290 % \cs{oarg}, and \cs{parg} may be added to identify arguments to be
291 % passed to the new object.
292 % Their names are added to the margin, and index entries are added,
293 % as well as group of entries for environments.
294 %
295 % \pkg{dtxdescribe} extends this concept to include a number of
296 % additional objects, such as booleans and keys.
297 % To help identify what is being described in the margin, small tags are
298 % added to the name, such as ``Env'', ``Bool'', or ``Key''.
299 % These new objects are also listed in the index with the same tag
300 % shown after their names, and also by group.
301 % Optional categories may be used to further sort index entries.
302 %
303 % Modifications have been made to interact with \pkg{hyperref} to
304 % provide hyper links for regular index entries as well as the new
305 % \cs{Describe} entries.
306 %
307 % Additional macros are provided to generate colored margin tags and
308 % warnings, and a new |dtxexample| environment demonstrates code examples.
309 %
310 % This documentation and its index show examples of these macros in use.
311 %
312 % While the index may appear to be overkill for a small package,
313 % keep in mind that it includes a number of fictional entries from the examples.
314 % Extensive cross-referencing can be useful for larger works.
315 % And, of course, you need not cross-reference everything!
316
317
318 % \clearpage
319 % \section{Using \pkg{dtxdescribe}}
320 % \label{sec:usage}
321
322 % To use \pkg{dtxdescribe} with the \pkg{ltxdoc} class and \filenm{.dtx} files:
323 % \begin{sourceverb}
324 % %<*driver>
325 % \documentclass{ltxdoc}
326 % ...
327 % \usepackage{lmodern}
328 % ...
329 % \usepackage{dtxdescribe}
330 % ...
331 % \usepackage{packagename} % the name of your new package
332 % ...
333 %
334 % % hyperref now automatically loaded by \pkg{ltxdoc}.
335 %
336 % \AtBeginDocument{
337 % \hypersetup{...}% If needed.
338 % \pdfstringdefDisableCommands{ ... }% If needed.
339 % }
340 %
341 % \AddToHook{begindocument/before}{% Before .aux file is loaded.
342 % \usepackage{cleveref}% If needed.
343 % \crefname{somename}{name}{names}% If needed.
344 % }
345 %
346 % ...
347 % %</driver>
348 % \end{sourceverb}
349
350 % To use \pkg{dtxdescribe} with the regular classes, such as \pkg{article},
351 % use:
352 %
353 % \begin{sourceverb}
354 % \documentclass{article}
355 %
356 % \usepackage{dtxdescribe}
357 %
358 % \usepackage{hyperref}% If needed.
359 % \hypersetup{...}% If needed.
360 % \pdfstringdefDisableCommands{ ... }% If needed.
361 %
362 % \usepackage{cleveref}% If needed.
363 % \crefname{somename}{name}{names}% If needed.
364 %
365 % \begin{document}
366 % ...
367 % \end{document}
368 % \end{sourceverb}
369
370
371 % Various objects inside the |dtx| or |tex| file may be described with new
372 % macros such as \cs{DescribeBoolean}, \cs{DescribeLength}, \cs{DescribeCounter},
373 % similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}.
374
375 % Optional ``categories'' may be assigned to the objects being described,
376 % including the new versions of \cs{DescribeMacro} and \cs{DescribeEnv}.
377 % These categories are printed in the margin tag and index entry for each item,
378 % and also generate additional index entries sorted by category. This is
379 % especially useful for key/value sets, where several sets may appear in the same
380 % document.
381 %
382 % The margin tag is not printed if
383 % \margintag{inside a float}
384 % the \cs{Describe} macros are used inside a float such as a table,
385 % but the index entries are still made.
386 %
387 % |\margintag{text}| may be used to place a colored tag in
388 % \margintag{\cs{margintag}\{text\}}
389 % the margin to summarize paragraph
390 % contents or draw attention to an index destination.
391 %
392 % |\watchout[optional text]| may be used to place a red warning sign
393 % \watchout[\cs{watchout}{[}text{]}]
394 % in the margin, along with optional text.
395 %
396 % The \env{dtxexample} environment may be used to typeset and execute small pieces of \LaTeX\ code
397 % as examples of its use. Optional cross-referencing notes may be used to refer to any
398 % example float being generated.
399 % \cs{listofdtxexamplefloats} prints the list of examples.
400
401
402
403
404 % \clearpage
405 % \section{The macros, and the \env{dtxexample} environment}
406
407
408
409 % \subsection{Macros and environments}
410 %
411 % \DescribeEnv{macro}
412 % \DescribeEnv{environment}
413 % These are only provided by the \pkg{ltxdoc} class and \pkg{doc} package
414 % \watchout[\filenm{.dtx} only]
415 % to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
416 % to disable these environments in the resulting \filenm{.sty} file.
417 % When using the regular document classes, the \env{macro} and
418 % \env{environment} environments would localize any definitions,
419 % and \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
420 %
421 %
422 % \DescribeMacro{\DescribeMacro} \oarg{category} \marg{\cs{name}}
423 %
424 % The preexisting macro from the \pkg{doc} package is redefined to
425 % create hyperlinked index entries, and include an optional category.
426 % A margin tag is created and an index entry is made.
427 % When the optional category is used, it is displayed along with
428 % the margin tag, and is used to group an index entry by
429 % macro name and another index entry by category.
430 % An example would be to describe
431 % the float creation and caption setup for a new category of float,
432 % such as the |dtxexample| float and the example ``photograph'' float
433 % both found in the index for this document.
434 % See \cref{ex:macro} on \cpageref{ex:macro} for examples.
435 %
436 % \DescribeMacro{\DescribeEnv} \oarg{category} \marg{environment name}
437 %
438 % The preexisting macro from the \pkg{doc} package is redefined to
439 % create hyperlinked index entries, include an optional category, and also to place
440 % an `Env' tag in front of the name in the margin.
441 % See \cref{ex:environment} on \cpageref{ex:environment}.
442 %
443
444
445 % \subsection{Arguments}
446 %
447 % The \cs{Describe\dots} macros
448 % may be followed by \cs{marg}, \cs{oarg}, and \cs{parg} to
449 % describe arguments passed to the macros.
450 %
451 % \DescribeMacro{\marg} \marg{text}
452 %
453 % Shows a mandatory argument for a macro or environment.
454 %
455 % The results looks like \marg{mandatory}.
456 %
457
458 % \DescribeMacro{\oarg} \marg{text}
459 %
460 % Shows an optional argument for a macro or environment.
461 %
462 % The results looks like \oarg{optional}.
463 %
464
465 % \DescribeMacro{\parg} \marg{text}
466 %
467 % Used for ``picture'' arguments, such as coordinates.
468 %
469 % The result looks like \parg{coordinate}.
470 %
471
472 % \DescribeMacro{\DescribeArgument} \oarg{category} \marg{argument}
473 %
474 % May be used to describe actions taken when given certain macro arguments.
475 % These will be given an `Arg' margin tag and will appear in the index.
476 % The |category| may be used to categorize arguments by their macro or environment name.
477 % See \cref{ex:arguments} on \cpageref{ex:arguments}.
478
479
480 % \subsection{Booleans, lengths, counters, hooks, sockets, plugs, keys}
481 %
482 % See \cref{ex:common} on \cpageref{ex:common}.
483 %
484 % \DescribeMacro{\DescribeBoolean} \oarg{category} \marg{name}
485 %
486 % Describes a boolean. Given a `Bool' tag in the margin and index.
487 %
488 %
489 % \DescribeMacro{\DescribeLength} \oarg{category} \marg{name}
490 %
491 % Describes a length. Given a `Len' tag in the margin and index.
492 %
493 %
494 % \DescribeMacro{\DescribeCounter} \oarg{category} \marg{name}
495 %
496 % Describes a counter. Given a `Ctr' tag in the margin and index.
497 %
498 %
499 % \DescribeMacro{\DescribeHook} \oarg{category} \marg{name}
500 %
501 % Describes a hook. Given a `Hook' tag in the margin and index.
502 % The |category| may be used to categorize hooks by package.
503 % The hook name may or may not have a backslash.
504 % Example:
505 % \begin{sourceverb}
506 % \DescribeHook{\hookname}
507 % \DescribeHook[LaTeX]{para/begin}
508 % \end{sourceverb}
509 %
510 %
511 % \DescribeMacro{\DescribeSocket} \oarg{category} \marg{name}
512 %
513 % \DescribeMacro{\DescribePlug} \oarg{category} \marg{name}
514 %
515 % Describes a socket or plug. Given a `Socket' or 'Plug' tag in the margin and index.
516 % The |category| may be used to categorize sockets and plugs by package.
517 % Example:
518 % \begin{sourceverb}
519 % \DescribeSocket{socketname}
520 % \DescribePlug{plugname}
521 % \end{sourceverb}
522 %
523 %
524 % \DescribeMacro{\DescribeKey} \oarg{category} \marg{name}
525 %
526 % Describes a key. Given a `Key' tag in the margin and index.
527 % The |category| may be used to categorize keys by their kev/value group.
528 % See \cref{ex:key} on \cpageref{ex:key}.
529
530
531 % \subsection{Packages, classes, options}
532 %
533 % \DescribeMacro{\DescribePackage} \oarg{category} \marg{name}
534 %
535 % Describes a package. Given a `Pkg' tag in the margin and index.
536 %
537 %
538 % \DescribeMacro{\DescribeClass} \oarg{category} \marg{name}
539 %
540 % Describes a \LaTeX\ class. Given a `Cls' tag in the margin and index.
541 %
542 %
543 % \DescribeMacro{\DescribeOption} \oarg{category} \marg{name}
544 %
545 % Describes a \LaTeX\ package or class option.
546 % Given an `Opt' tag in the margin and index.
547 %
548 %
549
550 % \subsection{Files, programs, commands}
551 %
552 % \DescribeMacro{\DescribeFile} \oarg{category} \marg{name}
553 %
554 % Describes an operating-system file. Given a `File' tag in the margin and index.
555 % The filename may have underscores.
556 %
557 %
558 % \DescribeMacro{\DescribeProgram} \oarg{category} \marg{name}
559 %
560 % Describes an operating-system program. Given a `Prog' tag in the margin and index.
561 % The program name may have underscores.
562 %
563 %
564 % \DescribeMacro{\DescribeCommand} \oarg{category} \marg{name}
565 %
566 % Describes an operating-system command. Given a `Cmd' tag in the margin and index.
567 % The command name may have underscores.
568 %
569 %
570
571
572 % \subsection{Other source objects}
573 %
574 % \DescribeMacro{\DescribeObject} \oarg{category} \marg{name}
575 %
576 % Describes an arbitrary programming object, such as a color definition or caption setup.
577 % A margin tag and index entry are created with \cs{ttfamily} type.
578 % When a category is used, it is added to the margin tag, appended to the
579 % index entry, and a second index entry is created grouped by category.
580 % If a macro name is to be described, use \cs{DescribeMacro} instead.
581 % See \cref{ex:object} on \cpageref{ex:object}.
582 %
583 %
584 % \DescribeMacro{\DescribeOther} \oarg{category} \marg{name}
585 %
586 % Describes an arbitrary non-programming object, such as a license agreement
587 % or credits. A margin tag and index entry are created in roman type.
588 % When a category is used, it is added to the margin tag, appended to the
589 % index entry, and a second index entry is created grouped by category.
590 % See \cref{ex:other} on \cpageref{ex:other}.
591
592
593 % \subsection{In a \env{description} environment}
594 %
595 % To describe an object using a \env{description} environment, use the following.
596 % See \cref{ex:description} on \cpageref{ex:description}.
597
598 % \DescribeMacro{\ItemDescribeMacro} \oarg{category} \marg{\cs{name}} A description.
599 %
600 % \DescribeMacro{\ItemDescribeEnv} \oarg{category} \marg{name} A description.
601 %
602 % \DescribeMacro{\ItemDescribeArgument} \oarg{category} \marg{argument} A description.
603 %
604 % \DescribeMacro{\ItemDescribeBoolean} \oarg{category} \marg{name} A description.
605 %
606 % \DescribeMacro{\ItemDescribeLength} \oarg{category} \marg{\cs{name}} A description.
607 %
608 % \DescribeMacro{\ItemDescribeCounter} \oarg{category} \marg{name} A description.
609 %
610 % \DescribeMacro{\ItemDescribeHook} \oarg{category} \marg{name} A description.
611 %
612 % \DescribeMacro{\ItemDescribeSocket} \oarg{category} \marg{name} A description.
613 %
614 % \DescribeMacro{\ItemDescribePlug} \oarg{category} \marg{name} A description.
615 %
616 % \DescribeMacro{\ItemDescribeKey} \oarg{category} \marg{name} A description.
617 %
618 % \DescribeMacro{\ItemDescribePackage} \oarg{category} \marg{package\_name} With underscores.
619 %
620 % \DescribeMacro{\ItemDescribeClass} \oarg{category} \marg{class\_name} With underscores.
621 %
622 % \DescribeMacro{\ItemDescribeOption} \oarg{category} \marg{name} A description.
623 %
624 % \DescribeMacro{\ItemDescribeFile} \oarg{category} \marg{file\_name} With underscores.
625 %
626 % \DescribeMacro{\ItemDescribeProgram} \oarg{category} \marg{program\_name} With underscores.
627 %
628 % \DescribeMacro{\ItemDescribeCommand} \oarg{category} \marg{command\_name} With underscores.
629 %
630 % \DescribeMacro{\ItemDescribeObject} \oarg{category} \marg{name} A description.
631 %
632 % \DescribeMacro{\ItemDescribeOther} \oarg{category} \marg{name} A description.
633
634
635 % \subsection{Defaults}
636
637 % \DescribeMacro{\DescribeDefault} \marg{value}
638 % \DescribeDefault{value}
639 %
640 % Shows the default value of a \cs{Describe\dots} item, such as displayed here.
641 % Place this macro immediately after the \cs{Describe\dots} macro and any
642 % arguments, but before the text description.
643
644 % \DescribeMacro{\DescribeDefaultcolor}
645 % The color of the margin tag used to show the default value.
646 % This is used by \cs{textcolor} to create the margin tag.
647 %
648 % \DescribeDefault{green!50!black}
649
650
651 % \subsection{Nesting}
652 %
653 % \DescribeMacro{\shownesting}
654 % * \oarg{fraction of \cs{linewidth}} \marg{container name} \marg{contents}
655 %
656 % It may be useful to show which objects contain which other objects.
657 % \cs{shownesting} shows a box enclosing a name for the container,
658 % and the container's contents.
659 % \cs{shownesting} be nested, showing boxes inside other boxes,
660 % which displays how each environment and macro is fit together inside each other.
661 %
662 % The optional argument is the fraction of \cs{linewidth} to use for the box,
663 % from |[0]| to |[1]|.
664 % The default is |[1]|.
665 % Each \cs{shownesting} starts its own paragraph, unless the star |*| is used,
666 % in which case the \cs{shownesting*} appears inline with previous text.
667 % To place two \cs{shownesting} boxes side-by-side, use optional arguments to
668 % specify less than full \cs{linewidth} for each box, and use \cs{shownesting*} for
669 % the second box to place it inline.
670 %
671 % See \cref{ex:nesting} on \cpageref{ex:nesting} for an example.
672
673
674 % \subsection{\cs{margintag}, \cs{watchout}}
675 %
676 %
677 % \DescribeMacro{\margintag} \marg{text}
678 %
679 % Creates a colored margin tag.
680 % May be used to identify the topic of a paragraph or the destination of
681 % an arbitrary index entry.\margintag{\cs{margintag}\{example\}}
682 %
683 % \DescribeMacro{\margintagcolor}
684 % \DescribeDefault{blue!70!black}
685 % The color of the \cs{margintag}.
686 % \bigskip
687 %
688 % \DescribeMacro{\watchout} \oarg{text}
689 %
690 % Creates a red margin tag with a warning sign and
691 % optional text. May be used to warn the reader of special instructions, etc.
692 % \watchout[\cs{watchout}{[}example{]}]
693 % Without the optional text the warning sign is displayed by itself.
694 %
695 % \DescribeMacro{\watchoutcolor}
696 % \DescribeDefault{red!50!black}
697 % The color of the \cs{watchout}.
698
699
700 % \subsection{\env{dtxexample} environment}
701 %
702 % \DescribeEnv{dtxexample} * \oarg{Notes/cross-references} \marg{caption \& label}
703 %
704 % The \env{dtxexample} environment is useful for demonstrating a piece of \LaTeX\ code.
705 % The example is a simulated float with its own caption and optional label,
706 % along with optional notes and/or cross-referencing commands.
707 % The contents of the \env{dtxexample} environment are printed verbatim, then
708 % loaded and executed as \LaTeX\ code, showing the results just below the printed code.
709 % In the case of float commands, the floats are generated as expected somewhere nearby,
710 % and should be given their own labels.
711 % References to the float's labels may be placed in the optional argument to
712 % the \env{dtxexample} environment, and will be printed below the code.
713 %
714 % The unstarred version places the code inside a
715 % minipage, forbidding a page break in the middle of the code listing. The starred
716 % version does not use a minipage. This is required when the code is too large to fit
717 % on a single page.
718 %
719 % \DescribeMacro{listofdtxexamplefloats} Prints the list of examples.
720 %
721 % See \cref{ex:dtxexample} for a demonstration of how \env{dtxexample} works.
722 %
723 % The examples may be customized by redefining the following,
724 % perhaps for another language:
725
726 % \DescribeMacro{\dtxexamplecodename}
727 % \DescribeDefault{Code:}
728 % The text name of the code section.
729 %
730 % \DescribeMacro{\dtxexampleresultname}
731 % \DescribeDefault{Result:}
732 % The text name of the result section.
733 %
734 %
735 % \subsection{\env{noindmacro} and \env{noindenvironment} environments}
736 %
737 % These are like \env{macro} and \env{environment}, but not indexed.
738 % \watchout[\filenm{.dtx} only]
739 % These only make sense if using the \pkg{ltxdoc} class and \pkg{doc} package
740 % to document a \filenm{.dtx} file, where comments are used by \prog{docstrip}
741 % to disable these environments in the resulting \filenm{.sty} file.
742 % When using the regular document classes, \env{noindmacro} and
743 % \env{noindenvironment} environments should not be used, as they
744 % would localize any definitions.
745 % \cs{DescribeMacro} and \cs{DescribeEnv} should be used instead.
746 %
747 % \DescribeEnv{noindmacro} \marg{\cs{name}}
748 % To document macros which should not be included in the index.
749 %
750 % \DescribeEnv{noindenvironment} \marg{name}
751 % To document environments which should not be included in the index.
752 %
753 % Replace
754 % \begin{sourceverb}
755 % \begin{macro}{\macroname} \oarg{optional} \marg{mandatory}
756 % ...
757 % \end{macro}
758 % \end{sourceverb}
759 % with
760 % \begin{sourceverb}
761 % \begin{noindmacro}{\macroname} \oarg{optional} \marg{mandatory}
762 % ...
763 % \end{noindmacro}
764 % \end{sourceverb}
765 % and similarly for \env{noindenvironment}.
766 %
767 %
768 % \subsection{\env{sourceverb}, \env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
769 %
770 % \DescribeEnv{sourceverb} \oarg{key/values}
771 % \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em} \qquad Display source code verbatim.
772 % Uses optional \pkg{fancyvrb} keys. Includes |gobble=2| to absorb the
773 % leading |%| and space character of a \filenm{dtx} file source format.
774 % Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
775 % \bigskip
776 %
777 % \DescribeEnv{fsourceverb} \oarg{key/values}
778 % \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em,frame=lines} \qquad Display source
779 % code verbatim inside a frame.
780 % A label may be included using the \optn{label} key.
781 % Because this is a verbatim environment, it \emph{cannot} be used inside a macro.
782 % See \cref{ex:fsourceverb} on \cpageref{ex:fsourceverb}.
783 % \bigskip
784 %
785 % \DescribeEnv{sourcedisplay} Display source code with manual formatting.
786 % This is not a verbatim environment.
787 % \cs{textcolor}, \cs{textbf}, and \cs{emph} may be used to highlight text.
788 % Macros must be escaped with \cs{cs}, characters such as \{ must be
789 % produced with \cs{\{}, etc.
790 % \cs{\textbackslash} must be used to force a new line.
791 % \cs{fquad}, \cs{fqquad}, and \cs{fqqquad}
792 % may be used to force indenting.
793 % Because this is \emph{not} a verbatim environment,
794 % it \emph{can} be used inside a macro.
795 % See \cref{ex:sourcedisplay} on \cpageref{ex:sourcedisplay}.
796 %
797 % \DescribeMacro{\fquad} Single-level indent inside a \env{sourcedisplay}.
798 %
799 % \DescribeMacro{\fqquad} Double-level indent inside a \env{sourcedisplay}.
800 %
801 % \DescribeMacro{\fqqquad} Triple-level indent inside a \env{sourcedisplay}.
802 %
803 % \DescribeEnv{UIdisplay} Displays a user interface, such as a dialog box entry
804 % or a menu selection. See \cref{ex:UIdisplay} on \cpageref{ex:UIdisplay}.
805 % Also see the \cs{UI} macro..
806 %
807 % \DescribeMacro{\userentry} \marg{text to enter} \qquad
808 % Typeset something for the user to enter.
809 % Also see the \cs{cmds} macro.
810 %
811 % \DescribeMacro{\userentryname}
812 % \DescribeDefault{Enter~$\Rightarrow$}
813 % Text to tell the user to enter the following item.
814 % Change with \cs{renewcommand}.
815 % \bigskip
816 %
817 % \DescribeEnv{docsidebar} \oarg{title} \qquad Creates a sidebar within the document.
818 % See \cref{ex:docsidebar} on \cpageref{ex:docsidebar}.
819 %
820 %
821 %
822 %
823 % \subsection{Formatted objects}
824 %
825 % Macros to format references to various kinds of objects.
826 %
827 % This \pkg{dtxdescribe} package documentation uses \pkg{erewhon}, \pkg{cabin},
828 % and \pkg{inconsolata}, along with \pkg{metalogox},
829 % to demonstrate the following font effects.
830 %
831 %
832 % \subsubsection{\LaTeX\ objects}
833 %
834 % \DescribeMacro{\pkg} \marg{packagename} \quad Prints as \pkg{packagename}.
835 % Also for a \pkg{classname}.
836
837 % \DescribeMacro{\cs} \marg{csname} \quad Prints as \cs{csname}.
838
839 % \DescribeMacro{\env} \marg{environment} \quad Prints as \env{environment}.
840
841 % \DescribeMacro{\marg} \marg{argument} \quad Prints \marg{arg}. Mandatory argument.
842
843 % \DescribeMacro{\oarg} \marg{argument} \quad Prints \oarg{arg}. Optional argument.
844
845 % \DescribeMacro{\parg} \marg{argument} \quad Prints \parg{arg}. Picture-mode argument.
846
847 % \DescribeMacro{\ctr} \marg{counter} \quad Prints as \ctr{counter}.
848
849 % \DescribeMacro{\bool} \marg{boolean} \quad Prints as \bool{boolean}.
850
851 % \DescribeMacro{\optn} \marg{option} \quad Prints as \optn{option},
852 % for example to a macro, package, class.
853
854 % \DescribeMacro{\TOC} \TOC: Table of contents.
855
856 % \DescribeMacro{\LOF} \LOF: List of figures.
857
858 % \DescribeMacro{\LOT} \LOT: List of tables.
859
860
861 % \subsubsection{Programs and commands}
862
863 % \DescribeMacro{\progcode} Prints as \progcode{inline program code}:
864 % Escape underscores and other special characters such as \{, \%, \$.
865
866 % \DescribeMacro{\prog} Prints as \prog{grep}, \prog{make}: A program name. Underscores allowed.
867
868 % \DescribeMacro{\filenm} Prints as \filenm{file_name}: Underscores allowed.
869
870 % \DescribeMacro{\UI} Prints as \UI{General user-interface text.} What the user sees on the display.
871 % Also see the \env{UIdisplay} environment.
872 %
873 % \DescribeMacro{\cmds} Prints as \cmds{Commands to be entered}: What the user enters.
874 % Escape underscores and other special characters such as \{, \%, \$.
875 % Also see the \cs{userentry} macro.
876 %
877 %
878 % \subsubsection{File types}
879 %
880 % \DescribeMacro{\ODT} \ODT\ OpenDocument Format word processing document
881
882 % \DescribeMacro{\SVG} \SVG\ image format
883
884 % \DescribeMacro{\PNG} \PNG\ image format
885
886 % \DescribeMacro{\GIF} \GIF\ image format
887
888 % \DescribeMacro{\JPG} \JPG\ image format
889
890 % \DescribeMacro{\EPS} \EPS\ image format
891
892 % \DescribeMacro{\PDF} \PDF\ image format
893
894 % \DescribeMacro{\DVI} \DVI\ image format
895 %
896 %
897 % \subsubsection{Internet}
898 %
899 % \DescribeMacro{\UTF} \UTF: Unicode
900
901 % \DescribeMacro{\URL} \URL: Uniform Resource Locator
902
903 % \DescribeMacro{\element} \marg{element name} \quad Prints as \element{element},
904 % an \HTML \Slash \CSS\ element
905
906 % \DescribeMacro{\attribute} \marg{attribute name} \quad Prints as \attribute{attribute},
907 % an \HTML \Slash \CSS\ attribute.
908 % pdf\TeX\ and \XeTeX\ only.
909 % \textcolor{\watchoutcolor}{Not for \LuaTeX.}
910
911 % \DescribeMacro{\attrib} \marg{attribute name} \quad Prints as \attribute{attribute},
912 % an \HTML \Slash \CSS\ attribute.
913 % pdf\TeX, \XeTeX, or \LuaTeX.
914
915 % \DescribeMacro{\HTML} \HTML: Hypertext Markup Language
916
917 % \DescribeMacro{\HTMLfive} \HTMLfive: Old-style figure if font supports
918
919 % \DescribeMacro{\CSS} \CSS: Cascading Style Sheet
920
921 % \DescribeMacro{\CSSthree} \CSSthree: Old-style figure if font supports
922
923 % \DescribeMacro{\EPUB} \EPUB: E-book file format
924 %
925 %
926 % \subsubsection{Specific programs}
927 %
928 % \DescribeMacro{\TikZ} \TikZ: Package logo
929
930 % \DescribeMacro{\CTAN} \CTAN: Comprehensive \TeX\ Archive Network
931
932 % \DescribeMacro{\TDS} \TDS: \TeX\ Directory Structure
933 %
934 % \DescribeMacro{\MathML} \MathML: Mathematical Markup Language
935 %
936 % \DescribeMacro{\MathJax} \MathJax: Math on the web.
937 %
938 %
939 % \subsubsection{Acronyms, brand names, trademarks}
940 %
941 % \DescribeMacro{\brand} \marg{name} \quad \brand{Brandname}, \brand{Company Name}
942
943 % \DescribeMacro{\acro} \marg{acronym} \quad \acro{acro}: Acronym
944
945 % \DescribeMacro{\supregistered} Superscript trademark symbol\supregistered
946 %
947 %
948 %
949 %
950 % \subsection{Logos}
951 %
952 % Several additional logos are provided.
953 %
954 % Also see the \pkg{metalogo} and \pkg{metalogox} packages.
955 %
956 % \DescribeMacro{\dviTeX} \dviTeX
957 %
958 % \DescribeMacro{\dviLaTeX} \dviLaTeX
959 %
960 % \DescribeMacro{\pdfTeX} \pdfTeX
961 %
962 % \DescribeMacro{\pdfLaTeX} \pdfLaTeX
963 %
964 % \DescribeMacro{\LuaTeX} \LuaTeX
965 %
966 % \DescribeMacro{\LuaLaTeX} \LuaLaTeX
967 %
968 % \DescribeMacro{\XeTeX} \XeTeX, with reversed E if \pkg{graphics} is loaded.
969 %
970 % \DescribeMacro{\XeLaTeX} \XeLaTeX, with reversed E if \pkg{graphics} is loaded.
971 %
972 % \DescribeMacro{\AmS} \AmS
973 %
974 % \DescribeMacro{\LyX} \LyX
975 %
976 % \DescribeMacro{\BibTeX} \BibTeX
977 %
978 % \DescribeMacro{\MakeIndex} \MakeIndex
979 %
980 % \DescribeMacro{\ConTeXt} \ConTeXt
981 %
982 % \DescribeMacro{\MiKTeX} \MiKTeX
983 %
984 %
985 %
986 %
987 % \subsection{Dashes and slashes}
988 %
989 % \DescribeMacro{\thinskip} A breakable thin skip.
990 %
991 % \DescribeMacro{\endash} An endash: \endash
992 %
993 % \DescribeMacro{\emdash} An emdash: \emdash
994 %
995 % \DescribeMacro{\thinbrspace} A thin space which allows a line break.
996 %
997 % \DescribeMacro{\thinthinbrspace} A very thin space which allows a line break.
998 %
999 % \DescribeMacro{\Dash} An unbreakeable thin space, emdash, and breakable thin space:
1000 % A \Dash B
1001 %
1002 % \DescribeMacro{\dash} An unbreakeable thin space, endash, and breakable thin space:
1003 % A \dash B
1004 %
1005 % \DescribeMacro{\Slash} An unbreakable very thin space, a slash, and a breakable very thin space:
1006 %
1007 % \begin{tabular}{rll}
1008 % Command & Result \\ \hline
1009 % |A--B| & A--B & (not breakable) \\
1010 % |A \dash B| & A \dash B & (only breakable before the B) \\
1011 % |A -- B| & A -- B & (breakable before or after the dash) \\ \hline
1012 % |A---B| & A---B & (not breakable) \\
1013 % |A \Dash B| & A \Dash B & (only breakable before the B) \\
1014 % |A --- B| & A --- B & (breakable before or after the dash) \\ \hline
1015 % |A/B| & A/B & (not breakable) \\
1016 % |A \Slash B| & A \Slash B & (only breakable before the B) \\
1017 % |A / B| & A / B & (breakable before or after the slash) \\
1018 % |A~/~B| & A~/~B & (not breakable) \\
1019 % \end{tabular}
1020 %
1021 %
1022 % \clearpage
1023 %
1024 % \section{Examples}
1025
1026
1027 % \begin{dtxexample}{Macros\label{ex:macro}}
1028 % \DescribeMacro{\mymacro} \oarg{optional} \marg{mandatory}
1029 % A typical macro definition.
1030 %
1031 % \DescribeMacro[photograph]{\DeclareFloatingPhoto}
1032 % Create a photograph float environment.
1033
1034 % \DescribeMacro[c=photograph]{\photocaptionsetup}
1035 % Caption settings for a photograph float.
1036
1037 % \DescribeMacro[photograph]{\cphotonameref}
1038 % \pkg{cleveref} name for the photograph float.
1039 % \end{dtxexample}
1040 %
1041 %
1042 % The optional category is used to label and group tags and index entries.
1043 % See this document's index entries for examples of this ``photograph''
1044 % category and the \env{dtxexample} category of macros.
1045 %
1046 % The re-defined \cs{DescribeMacro}, \cs{DescribeEnv}, and
1047 % all the following macros create hyperlinked index entries,
1048 % \margintag{hyperlinks}
1049 % along with regular uses of \cs{index}.
1050 %
1051 %
1052 % \clearpage
1053 %
1054 % \begin{dtxexample}{Environment\label{ex:environment}}
1055 % \DescribeEnv{myenvironment} \marg{argument} Short description.
1056 % \end{dtxexample}
1057 %
1058 % The re-defined \cs{DescribeEnv} adds an `Env' tag to the margin,
1059 % \margintag{add'l tags}
1060 % and adds ``(environment)'' to its own index entry.
1061 % Note that environments and all the other new objects
1062 % defined\margintag{index groups}\index{index>by group}\index{group of objects}
1063 % by this package each receives two index entries, one by name,
1064 % and one grouped with others of its kind.
1065
1066 % \Cref{ex:environment} shows descriptive text
1067 % \watchout[too much text]
1068 % on the same line as the \cs{DescribeEnvironment}.
1069 % For macros and environments with many arguments after the name,
1070 % it may be better to place any additional text in a following paragraph.
1071
1072 % \begin{dtxexample}{Second Environment}
1073 % \DescribeEnv[kindofenvironment]{otherenvironment}
1074 % \oarg{opt args} \parg{coordinates} A description.
1075 % \end{dtxexample}
1076 %
1077 % The \env{otherenvironment} will be indexed by itself and also
1078 % with \env{myenvironment} under the index entry ``environments'',
1079 % and also under the category |kindofenvironment|.
1080 %
1081 %
1082 % \clearpage
1083 %
1084 % \begin{dtxexample}{Booleans and Counters\label{ex:common}}
1085 % \DescribeBoolean[examples]{sampleboolean} Some description.
1086 %
1087 % \DescribeCounter[examples]{samplecounter} Some description.
1088 % \end{dtxexample}
1089 %
1090 % Most of the new \cs{Describe}\rule{.25in}{.4pt} macros behave like the
1091 % new \cs{DescribeEnv}, placing a tag in the margin, an index entry
1092 % by name, and another index entry by group.
1093 %
1094
1095
1096 % \begin{dtxexample}{Lengths\label{ex:length}}
1097 % \DescribeLength[photograph]{\photowidth} Some description.
1098 % \end{dtxexample}
1099
1100 % Lengths have a leading backslash, but are otherwise described
1101 % the same as the rest of the objects.
1102
1103
1104 % \begin{dtxexample}{Hooks and Sockets\label{ex:hook}}
1105 % \DescribeHook{\hookname} A hook with a backslash.
1106
1107 % \DescribeHook{para/begin} A hook without a backslash.
1108
1109 % \DescribeSocket{socketname} A socket.
1110
1111 % \DescribePlug{plugname} A socket plug.
1112
1113 % \end{dtxexample}
1114
1115 % Hooks may or may not have a leading backslash.
1116
1117
1118
1119 % \clearpage
1120 %
1121 %
1122 % \begin{dtxexample}{Packages, Classes, and Options}
1123 % \DescribePackage[examples]{samplepackage}
1124 % About a \LaTeX\ package.
1125 %
1126 % \DescribeClass[examples]{sample_class}
1127 % About a \LaTeX\ class.
1128 %
1129 % \DescribeOption[examples]{sampleoption}
1130 % About an option for a package or class.
1131 % \end{dtxexample}
1132 %
1133 %
1134 % \begin{dtxexample}{Files, Commands, and Programs\label{ex:file}}
1135 % \DescribeFile[bigfiles]{really_big_file.txt} Some description.
1136 %
1137 % \DescribeFile[bigfiles]{another_big_file.txt} Some description.
1138 %
1139 % \DescribeFile{lone_file.txt} Some description.
1140 %
1141 % \DescribeCommand{OS_command} An operating-system command.
1142 %
1143 % \DescribeProgram{program_name} An operating-system program.
1144 % \end{dtxexample}
1145 %
1146 % Filenames, program names, and command names may have underscores,
1147 % such as tested here.
1148 % A category is used to group ``bigfiles'' together in the index.
1149
1150
1151 % \clearpage
1152 %
1153 % \begin{dtxexample}{Keys\label{ex:key}}
1154 % \DescribeKey[groupofkeys]{firstkey} About the first key
1155 % of the |groupofkeys| set.
1156 %
1157 % \DescribeKey[groupofkeys]{secondkey} About the second key
1158 % of |groupofkeys|.
1159 %
1160 % \DescribeKey[examples]{samplekey} About some key of |otherkeys|.
1161 %
1162 % \DescribeKey[examples]{sampletwokey} About another key of |otherkeys|.
1163 %
1164 % \DescribeKey{lonekey} A key without a category.
1165 % \end{dtxexample}
1166 %
1167 % See the index key groups.
1168 %
1169 %
1170 % \clearpage
1171 %
1172 % \begin{dtxexample}{Arguments\label{ex:arguments}}
1173 % \DescribeArgument[figure]{[H]}
1174 % What happens when a figure is [H]ere.
1175 %
1176 % \DescribeArgument[figure]{[M]}
1177 % What happens when a figure is in the [M]argin.
1178 %
1179 % \DescribeArgument[\mymacro]{bold}
1180 % What happens when \cs{mymacro} is given the |bold| argument.
1181 % \end{dtxexample}
1182 %
1183 % Arguments behave like keys, and may have an optional category to
1184 % identify their macro or environment, and group their entries
1185 % in the index.
1186 %
1187 % Note you may need to use |\cs{mymacro}| for the macro's name.
1188 % \watchout[macro names]
1189 %
1190 %
1191 % \clearpage
1192 %
1193 % \begin{dtxexample}{Object\label{ex:object}}
1194 % \DescribeObject[color]{somecolor}
1195 % The color of something.
1196 %
1197 % \DescribeObject[color]{othercolor}
1198 % The other color.
1199 %
1200 % \DescribeObject{randomobject} About some random object.
1201 % \end{dtxexample}
1202 %
1203 % Describes an arbitrary programming object, using \cs{ttfamily} text.
1204
1205
1206 % \begin{dtxexample}{Other\label{ex:other}}
1207 % \DescribeOther{license agreement}
1208 % The following is the fictional license agreement:
1209 %
1210 % \DescribeOther{Before myenvironment}
1211 % Actions to be done \cs{BeforeBeginEnvironment}.
1212 %
1213 % \DescribeOther[othercategory]{Other Item} About the other item.
1214 %
1215 % \DescribeOther[othercategory]{Additional Item} About the add'l item.
1216 % \end{dtxexample}
1217 %
1218 % Describes an arbitrary non-programming object, using roman text.
1219
1220
1221 % \clearpage
1222 %
1223 % \begin{dtxexample}{Description environments\label{ex:description}}
1224 % \begin{description}
1225 % \ItemDescribeMacro[descexamples]{\macroname} Describe the macro.
1226 % \ItemDescribeBoolean[descexamples]{booleanname} Describe the boolean.
1227 % \ItemDescribeLength[descexamples]{\lengthname} Describe the length.
1228 % \ItemDescribeKey[descexamples]{keyname} Describe the key.
1229 % \ItemDescribePackage[descexamples]{package_name} Describe the package.
1230 % \ItemDescribeClass[descexamples]{class_name} Describe the class.
1231 % \ItemDescribeFile[descexamples]{file_name} Describe the file.
1232 % \ItemDescribeProgram[descexamples]{program_name} Describe the program.
1233 % \ItemDescribeCommand[descexamples]{command_name} Describe the command.
1234 % \end{description}
1235 % \end{dtxexample}
1236 %
1237 % Uses a \env{description} environment to describe objects.
1238
1239
1240 % \clearpage
1241 %
1242 % \begin{dtxexample}{Nesting\label{ex:nesting}}
1243 % \shownesting{\env{environmentA}}{
1244 % \shownesting{\cs{macroB}}{
1245 % \shownesting{\env{environmentC}}{
1246 % The contents.
1247 % }
1248 % }
1249 % }
1250 %
1251 % \shownesting{\env{sidebyside}}{
1252 % \shownesting[.35]{minipage}{
1253 % Left contents.
1254 % }
1255 % \hfill \cs{hfill} \hfill
1256 % \shownesting*[.35]{minipage}{
1257 % Right contents.
1258 % }
1259 % }
1260 % \end{dtxexample}
1261 %
1262 % Note the use of the optional arguments to select less than full \cs{linewidth},
1263 % and the starred form for the second box to place it inline with the \cs{hfill} text.
1264
1265
1266 % \clearpage
1267 %
1268 %
1269 % \begin{dtxexample}[See \cref{fig:afigure}]
1270 % {\env{dtxexample}\label{ex:dtxexample}}
1271 % \begin{figure}
1272 % \centering\fbox{Contents of the figure.}
1273 % \caption{A Figure}\label{fig:afigure}
1274 % \end{figure}
1275 % \end{dtxexample}
1276
1277 % \Cref{ex:dtxexample}, typeset above, was created with the following code:
1278 % \begin{sourceverb}
1279 % \begin{dtxexample}[See \cref{fig:afigure}]
1280 % {\env{dtxexample}\label{ex:dtxexample}}
1281 % \begin{figure}
1282 % \centering\fbox{Contents of the figure.}
1283 % \caption{A Figure}\label{fig:afigure}
1284 % \end{figure}
1285 % \end{dtxexample}
1286 % \end{sourceverb}
1287 %
1288 % When the example was created:
1289 % \begin{enumerate}
1290 % \item The ``float'' of type |dtxexamplefloat| was created,
1291 % with the caption ``|dtxexample|''
1292 % and the label |ex:dtxexample|, which points to \cref{ex:dtxexample}.
1293 % \item The code was displayed verbatim.
1294 % \item The code was written to the file |dtxexample_cut.tex|.
1295 % \item The code was \cs{input} from |dtxexample_cut.tex|.
1296 % \item Executing the code created the figure with
1297 % caption ``A Figure'' and label |fig:afigure|, which
1298 % points to \cref{fig:afigure}.
1299 % \item The cross-reference to the figure was shown on the optional display line
1300 % by the optional argument to \env{dtxexample}.
1301 % \item The starred form of \env{dtxexample} was used to create the closing
1302 % rule below the code, since a float was being generated and nothing followed the
1303 % code inline. An unstarred version would have created an extra rule.
1304 % \end{enumerate}
1305 %
1306 %
1307 % \clearpage
1308 %
1309 %
1310 % \begin{dtxexample}
1311 % {\env{fsourceverb}\label{ex:fsourceverb}}
1312 % % \begin{fsourceverb}[label=An fsourceverb example]
1313 % % \newcommand{fdosomething}[1][whattodo]{
1314 % % doing #1
1315 % % }
1316 % % \end{fsourceverb}
1317 % \end{dtxexample}
1318 % (The leading |%| characters would be present in the \filenm{dtx} source.)
1319 % \bigskip
1320
1321 % \begin{dtxexample}
1322 % {\env{sourcedisplay}\label{ex:sourcedisplay}}
1323 % \begin{sourcedisplay}
1324 % \cs{newcommand}\{dosomething\}[1][\textcolor{red}{whattodo}]\{\\
1325 % \fquad \textcolor{blue}{doing \textcolor{red}{\#1}}\\
1326 % \}
1327 % \end{sourcedisplay}
1328 % \end{dtxexample}
1329 %
1330 % \clearpage
1331 %
1332 % \begin{dtxexample}
1333 % {\env{UIdisplay}\label{ex:UIdisplay}}
1334 % Select:
1335 % \begin{UIdisplay}
1336 % \textsf{Preferences $\to$ Plugins $\to$ Files $\to$ HTML}
1337 % \end{UIdisplay}
1338 % For the field
1339 % \begin{UIdisplay}
1340 % Title heading:
1341 % \end{UIdisplay}
1342 % \userentry{H1}
1343 %
1344 % \end{dtxexample}
1345 %
1346 % \clearpage
1347 %
1348 % \begin{dtxexample}
1349 % {\env{docsidebar}\label{ex:docsidebar}}
1350 % Main text.
1351 %
1352 % More main text.
1353 %
1354 % \begin{docsidebar}[A title]
1355 % An aside, which may help explain something
1356 % incidental to the main text.
1357 % \end{docsidebar}
1358 %
1359 % Additional main text.
1360 % \end{dtxexample}
1361
1362
1363
1364
1365 % \clearpage
1366 %
1367 % \section{Usage notes}
1368 %
1369 % \begin{description}
1370 %
1371 % \item[Placement of \cs{Describe} macros:]
1372 % Typically \LaTeX\ macro and environment definitions are enclosed in
1373 % \env{macro} and \env{environment} environments at their place in the source code.
1374 % \cs{DescribeMacro} and \cs{DescribeEnv} would be used elsewhere in the manual
1375 % to describe how to use the code. \cs{DescribeBoolean} and such might be at
1376 % their place in the source code, unless they are worthy of discussion for the
1377 % end-user, in which case they should be in the ``User's Manual'' section of the
1378 % document.\footnote{Future versions may include \cs{DeclareBoolean} for
1379 % use at the point where the boolean is defined, creating an index entry
1380 % with a code line number, and \cs{DescribeBoolean} with a page number index entry for
1381 % the related discussion in the User's Manual portion of the document.}
1382 % It may be useful to use \cs{DeclareBoolean} and friends both at the code location
1383 % and also in the User's Manual section.
1384 %
1385 % \item[Extra spaces:] When placing multiple uses of \cs{Describe}, \cs{index}, \cs{margintag}, and
1386 % \cs{watchout} macros
1387 % together, care must be taken to avoid extra space in the printed text where
1388 % these macros occur.
1389 % A trailing percent character may be used to
1390 % avoid the extra space:
1391 % \begin{sourceverb}
1392 % text text text% <-- avoids extra space
1393 % \margintag{A comment.}
1394 % \index{An entry}
1395 % \index{Another entry}
1396 % more inline text
1397 % \end{sourceverb}
1398 %
1399 % \item[Unwanted vertical space:] Other environments nested inside a \env{docsidebar}
1400 % may produce excessive vertical space. It may be required to insert
1401 % \begin{sourceverb}
1402 % \vspace*{-\baselineskip}
1403 % \end{sourceverb}
1404 %
1405 % \item[\cs{margintag} placement:] To have the margin tag appear next to the first
1406 % line of a paragraph, place the \cs{margintag} or \cs{watchout}
1407 % somewhere after the first few words
1408 % in the paragraph. The \cs{margintag} may be on its own line,
1409 % and the rest of the paragraph may follow on the next line.
1410 % If too many words are printed before the \cs{margintag},
1411 % the words may wrap to the next line before the tag occurs.
1412 %
1413 % \item[Margin tag overlap:] To keep margin tags in proper alignment,
1414 % use a new paragraph or multiple lines
1415 % between \cs{margintag}, \cs{watchout}, or \cs{Declare} macros
1416 %
1417 % \item[\cs{Describe} inside floats:] When these macros are used inside a float,
1418 % \margintag{missing tags}\index{margin tag missing}
1419 % the margin tag is supressed (there is no margin in a float), but the
1420 % index entries are still created.
1421 %
1422 % \end{description}
1423
1424
1425
1426 % \clearpage
1427
1428 % \StopEventually{
1429 % \appendix
1430 % \GlossaryPrologue{\section{Change History}}
1431 % \PrintChanges
1432 % \IndexPrologue{\section{Index}}
1433 % \PrintIndex}
1434
1435
1436 % ^^A *source
1437 % \section{Code}
1438
1439
1440 % \subsection{Required packages}
1441
1442 % \DescribePackage{makeidx} One of several index programs must be provided.
1443 % \DescribePackage{splitidx} One of several index programs must be provided.
1444 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
1445 % \begin{macrocode}
1446 \AtBeginDocument{
1447 \IfPackageLoadedTF{makeidx}{}{
1448 \IfPackageLoadedTF{splitidx}{}{
1449 \RequirePackage{makeidx}
1450 \makeindex
1451 }}
1452 }
1453 % \end{macrocode}
1454
1455 % \DescribePackage{etoolbox} v2.6 or later
1456 % for \cs{BeforeBeginEnvironment}, \cs{AfterEndEnvironment}
1457 % \begin{macrocode}
1458 \RequirePackage{etoolbox}[2011/01/03]%
1459 % \end{macrocode}
1460
1461 % \DescribePackage{xparse} Used for the examples.
1462 % \begin{macrocode}
1463 \RequirePackage{xparse}
1464 % \end{macrocode}
1465
1466 % \changes{v1.03}{2021/09/02}{No longer requires \pkg{xifthen}.}
1467
1468 % \DescribePackage{calc} Used for \cs{shownesting}.
1469 % \begin{macrocode}
1470 \RequirePackage{calc}
1471 % \end{macrocode}
1472
1473
1474 % \DescribePackage{xcolor} Used for the examples.
1475 % \begin{macrocode}
1476 \RequirePackage{xcolor}
1477 \definecolor{myurlcolor}{rgb}{0,0,.7}
1478 \definecolor{mylinkcolor}{rgb}{.7,0,0}
1479 % \end{macrocode}
1480
1481
1482 % \DescribePackage{caption} Used for the examples.
1483 % \begin{macrocode}
1484 \RequirePackage{caption}
1485 % \end{macrocode}
1486
1487
1488 % \DescribePackage{newfloat} Used for the examples.
1489 % \begin{macrocode}
1490 \RequirePackage{newfloat}
1491 % \end{macrocode}
1492
1493
1494 % \DescribePackage{fancyvrb} Used for the examples.
1495 % \begin{macrocode}
1496 \RequirePackage{fancyvrb}
1497 % \end{macrocode}
1498
1499
1500 % \DescribePackage{xstring} Used for \cs{StrSubstitute} for \cs{DescribeFile}.
1501 % \begin{macrocode}
1502 \RequirePackage{xstring}
1503 % \end{macrocode}
1504
1505
1506 % \DescribePackage{hyperref}
1507 % If \pkg{hyperref} is loaded, disable some macros in \PDF\ bookmarks:
1508 % \margintag{\PDF\ bookmarks}
1509 % \changes{v1.01}{2019/01/20}{Sanitize \PDF\ bookmarks.}
1510 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{hyperref} package.}
1511 % \begin{macrocode}
1512 \AtBeginDocument{
1513 \IfPackageLoadedTF{hyperref}{
1514 \pdfstringdefDisableCommands{%
1515 \def\quad{ }%
1516 \def\\{ }%
1517 \def\pkg#1{#1}%
1518 \def\ctr#1{#1}%
1519 \def\bool#1{#1}%
1520 \def\optn#1{#1}%
1521 \def\env#1{#1}%
1522 \def\cs#1{\textbackslash#1}%
1523 \def\,{ }%
1524 \def\LuaLaTeX{LuaLaTeX}%
1525 \def\XeLaTeX{XeLaTeX}%
1526 \def\TeX{TeX}%
1527 \def\LaTeX{LaTeX}%
1528 \def\LaTeXe{LaTeX2e}%
1529 \def\LuaTeX{LuaTeX}%
1530 \def\LuaLaTeX{LuaLaTeX}%
1531 \def\XeTeX{XeTeX}%
1532 \def\AmS{AMS}%
1533 \def\Dash{ --- }%
1534 \def\dash{ -- }%
1535 \def\Slash{/}%
1536 \def\prog#1{\detokenize{#1}}%
1537 \def\progcode#1{#1}%
1538 \def\filenm#1{\detokenize{#1}}%
1539 \def\brand#1{#1}%
1540 \def\acro#1{#1}%
1541 \def\ODT{ODT}%
1542 \def\SVG{SVG}%
1543 \def\PNG{PNG}%
1544 \def\GIF{GIF}%
1545 \def\JPG{JPG}%
1546 \def\EPS{EPS}%
1547 \def\PDF{PDF}%
1548 \def\DVI{DVI}%
1549 \def\UTF{UTF}%
1550 \def\URL{URL}%
1551 \def\element#1{#1}%
1552 \def\attribute#1{#1}%
1553 \def\attrib#1{#1}%
1554 \def\HTML{HTML}%
1555 \def\HTMLfive{HTML5}%
1556 \def\CSS{CSS}%
1557 \def\CSSthree{CSS3}%
1558 \def\EPUB{EPUB}%
1559 \def\TOC{TOC}%
1560 \def\LOF{LOF}%
1561 \def\LOT{LOT}%
1562 }
1563 }% yes hyperref
1564 % \end{macrocode}
1565 % If \pkg{hyperref} is not loaded, emulate \cs{hyperpage} here.
1566 % \begin{macrocode}
1567 {% no hyperref
1568 \newcommand*{\hyperpage}[1]{#1}
1569 }
1570 }
1571 % \end{macrocode}
1572
1573
1574
1575
1576 % ^^A Several versions of the \warningsign symbol:
1577
1578 % ^^A This version relies on the presence of the fourier font:
1579 % ^^A \newcommand*{\TakeFourierOrnament}[1]{{%
1580 % ^^A \fontencoding{U}\fontfamily{futs}\selectfont\char#1}}
1581 %
1582 % ^^A \newcommand*{\warningsign}{\TakeFourierOrnament{66}}
1583
1584 % ^^A from: http://tex.stackexchange.com/questions/159669/how-to-print-a-warning-sign-triangle-with-exclamation-point
1585 % ^^A This version copy/pastes extraneous characters:
1586 % ^^A \newcommand\warningsign{%
1587 % ^^A \makebox[1em][c]{%
1588 % ^^A \makebox[0pt][c]{\raisebox{.1em}{\textbf{\tiny!}}}%
1589 % ^^A \makebox[0pt][c]{$\bigtriangleup$}}}%
1590
1591
1592 % \DescribePackage{pict2e}
1593 % \begin{macrocode}
1594 \RequirePackage{pict2e}
1595 \setlength{\unitlength}{1pt}
1596 % \end{macrocode}
1597
1598
1599
1600 % \subsection{Warning sign}
1601
1602 % \begin{macro}{\warningsign} Prints an exclamation point inside a triangle.
1603 % Displays as: \warningsign
1604 %
1605 % Creates a warning sign without relying on the presence of the fourier font.
1606 % During copy/paste, this shows up as a simple exclamation point.
1607 % \begin{macrocode}
1608 \newcommand*{\warningsign}{%
1609 \begin{picture}(10,9)
1610 \put(4,1){\scriptsize!}
1611 \put(0,0){\line(500,866){5}}
1612 \put(10,0){\line(-500,866){5}}
1613 \put(0,0){\line(1,0){10}}
1614 \end{picture}
1615 }
1616 % \end{macrocode}
1617 % \end{macro}
1618
1619
1620 % \subsection{Special character handling}
1621
1622 % The literal backslash character:
1623 % \begin{macrocode}
1624 \begingroup
1625 \catcode`\|=0
1626 \catcode`\\=12
1627 |gdef|DTXD@backslash{\}
1628 |endgroup
1629 % \end{macrocode}
1630
1631
1632
1633 % \subsection{Patching \pkg{hypdoc}, \pkg{splitidx}, \pkg{doc}}
1634 %
1635 % If \pkg{hyperref} is disabled (by \pkg{lwarp}) then define the
1636 % missing \cs{hdclindex}.
1637 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
1638 % \begin{macrocode}
1639 \IfPackageLoadedTF{doc}{
1640 \IfPackageLoadedTF{hypdoc}{
1641 \AddToHook{begindocument/before}[doc/hyperref]{%
1642 \ifdoc@hyperref
1643 \else
1644 \def\hdclindex#1#2{%
1645 \ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi%
1646 }%
1647 \fi
1648 }
1649 }{}% hypdoc loaded
1650 }{}% doc loaded
1651 % \end{macrocode}
1652
1653
1654 % Several changes for when \pkg{hypdoc} and \pkg{splitidx} are used together:
1655 % \begin{macrocode}
1656 \AtBeginDocument{
1657 \IfPackageLoadedTF{doc}{
1658 \IfPackageLoadedTF{hypdoc}{
1659 \IfPackageLoadedTF{splitidx}{
1660 % \end{macrocode}
1661 %
1662 %
1663 % \pkg{splitidx} is modified to add \verb+|hdpindex{}+ to work with \pkg{hypdoc}.
1664 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
1665 % \begin{macrocode}
1666 \renewcommand*{\@wrsindex}[2][]{%
1667 \ifx\relax#1\relax%
1668 \if@splitidx%
1669 \@wrsindex[idx]{#2}%
1670 \else%
1671 \def\@tempa{#2}%
1672 \if@verbindex\@onelevel@sanitize\@tempa\fi%
1673 \@wrindex{\@tempa}%
1674 \fi%
1675 \else%
1676 %
1677 % \def\@tempa{#2}%
1678 \def\@tempa{#2\encapchar hdpindex{}}% dtxdescribe
1679 %
1680 \csname index@#1@hook\endcsname%
1681 \expandafter\ifx\csname @@wrsindex\endcsname\relax%
1682 \@@@wrsindex{#1}{{\@tempa}{\thepage}}%
1683 \else%
1684 \def\@tempb{\@@wrsindex{#1}}%
1685 \expandafter\@tempb\@tempa||\\%
1686 \fi%
1687 \endgroup%
1688 \@esphack%
1689 \fi%
1690 }
1691 % \end{macrocode}
1692
1693
1694 % \pkg{hypdoc} guesses the \TOC\ level for the \PDF\ bookmarks,
1695 % but its algorithm seems to fail at \cs{StopEventually} for split indices.
1696 %
1697 % ``|Paragraph ended before \HD@@guesstoclevel was complete.|''
1698 %
1699 % Its guess is fixed to level 1 until \cs{PrintChanges} or \cs{printindex}.
1700 %
1701 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
1702 % \begin{macrocode}
1703 \def\HD@guesstoclevel#1{1}
1704 % \end{macrocode}
1705
1706 % \changes{v1.07}{2022/12/19}{Improved \PDF\ bookmarks.}
1707 % Patch \pkg{doc}'s \cs{PrintChanges} to reset the \TOC\ guess to top level.
1708 % \begin{macrocode}
1709 \preto\PrintChanges{\def\HD@guesstoclevel#1{0}}
1710 % \end{macrocode}
1711
1712
1713 % \pkg{hypdoc} adds \PDF\ bookmarks to letter groups in the index.
1714 % \pkg{hypdoc} must take into account multiple indexes,
1715 % otherwise, followup indices will have duplicate bookmarks.
1716 %
1717 % Increment the index number at the start of each index,
1718 % and append the index number to the \PDF\ bookmark.
1719 %
1720 % Also, change the \TOC\ guess to top level from now on, presuming that
1721 % the indices are at the end.
1722 %
1723 % \changes{v1.07}{2022/12/19}{Improved \PDF\ bookmarks.}
1724 % \begin{macrocode}
1725 \newcounter{DTXD@indexnumber}
1726
1727 \extendtheindex
1728 {%
1729 \addtocounter{DTXD@indexnumber}{1}%
1730 \def\HD@guesstoclevel##1{0}%
1731 }
1732 {}
1733 {}
1734 {}
1735
1736 \def\HD@@@bfseries\hfil#1\hfil{%
1737 \ifx\\#1\\%
1738 \else%
1739 \raisebox{\baselineskip}[0pt]{%
1740 \kern-\HD@margin\relax%
1741 % \pdfbookmark[\HD@toclevel@subindex]{#1}{HD.#1}}%
1742 \pdfbookmark[\HD@toclevel@subindex]{#1}% dtxdescribe
1743 {HD.#1.\arabic{DTXD@indexnumber}}% dtxdescribe
1744 \kern\HD@margin\relax%
1745 }%
1746 \fi%
1747 \hfil#1\hfil%
1748 }%
1749 % \end{macrocode}
1750
1751 % \begin{macrocode}
1752 }{}% splitidx loaded
1753 }{}% hypdoc loaded
1754 }{}% doc loaded
1755 }% AtBeginDocument
1756 % \end{macrocode}
1757
1758
1759
1760 % \subsection{Gobbling comment characters}
1761 %
1762 % \begin{macro}{DTXD@gobble}
1763 % The \filenm{.dtx} format uses leading percent characters for
1764 % code to be in the documentation only. Other classes do not.
1765 % \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
1766 % \begin{macrocode}
1767 \IfPackageLoadedTF{doc}{
1768 \newcommand*{\DTXD@gobble}{2}
1769 }{
1770 \newcommand*{\DTXD@gobble}{0}
1771 }
1772 % \end{macrocode}
1773 % \end{macro}
1774
1775
1776 % \subsection{Vertical spacing}
1777 % \begin{macrocode}
1778 \setlength{\marginparsep}{1em}
1779 \setlength{\marginparpush}{.7ex}
1780
1781 \setlength{\parindent}{0em}
1782 \setlength{\parskip}{2ex}
1783 % \end{macrocode}
1784 %
1785 % \DescribeLength{\IndexMin} From \pkg{ltxdoc}.
1786 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
1787 % \begin{macrocode}
1788 \ifdef{\IndexMin}
1789 {\setlength{\IndexMin}{40ex}}
1790 {\newlength{\IndexMin}}
1791 % \end{macrocode}
1792
1793
1794 % \subsection{Not \pkg{ltxdoc}: \pkg{ltxdoc} emulation}
1795 %
1796 % If the \pkg{ltxdoc} class is not used, some of its macros are replicated here.
1797 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
1798 % \begin{macrocode}
1799 \@ifclassloaded{ltxdoc}{}{
1800 \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
1801 \def\cmd@to@cs#1#2{\char\number`#2\relax}
1802 \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
1803 \providecommand\marg[1]{%
1804 {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
1805 \providecommand\oarg[1]{%
1806 {\ttfamily[}\meta{#1}{\ttfamily]}}
1807 \providecommand\parg[1]{%
1808 {\ttfamily(}\meta{#1}{\ttfamily)}}
1809 \providecommand\url{\texttt}
1810 }
1811 % \end{macrocode}
1812
1813
1814 % \subsection{Not \pkg{doc}: \pkg{doc} emulation}
1815 %
1816 % If the \pkg{doc} class is not used, some of its macros are replicated here.
1817 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{doc} package.}
1818 % \begin{macrocode}
1819 \AtBeginDocument{
1820 \IfPackageLoadedTF{doc}{}{% not doc
1821 \newenvironment*{macro}[1]{%
1822 \PackageError{dtxdescribe}
1823 {The 'macro' environment is only\MessageBreak
1824 available when using the doc package\MessageBreak
1825 with a .dtx source file}
1826 {This environment only makes sense for .dtx source.}
1827 }{}
1828 \newenvironment*{environment}[1]{%
1829 \PackageError{dtxdescribe}
1830 {The 'environment' environment is only\MessageBreak
1831 available when using the doc package\MessageBreak
1832 with a .dtx source file}
1833 {This environment only makes sense for .dtx source.}
1834 }{}
1835 \def\MacroFont{\fontencoding\encodingdefault
1836 \fontfamily\ttdefault
1837 \fontseries\mddefault
1838 \fontshape\updefault
1839 \small}%
1840 \@ifundefined{actualchar}{\def\actualchar{@}}{}
1841 \@ifundefined{quotechar}{\def\quotechar{"}}{}
1842 \@ifundefined{levelchar}{\def\levelchar{!}}{}
1843 \@ifundefined{encapchar}{\def\encapchar{|}}{}
1844 \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
1845 \setlength\marginparpush{0pt} \setlength\marginparwidth{8pc}
1846 \reversemarginpar
1847 \DeclareRobustCommand\meta[1]{%
1848 \ensuremath\langle
1849 \ifmmode \expandafter \nfss@text \fi
1850 {%
1851 \meta@font@select
1852 \edef\meta@hyphen@restore
1853 {\hyphenchar\the\font\the\hyphenchar\font}%
1854 \hyphenchar\font\m@ne
1855 \language\l@nohyphenation
1856 #1\/%
1857 \meta@hyphen@restore
1858 }\ensuremath\rangle
1859 }
1860 \def\meta@font@select{\itshape}
1861 }% not doc
1862 }% AtBeginDocument
1863 % \end{macrocode}
1864
1865
1866 % \subsection{Support macros}
1867
1868 % \begin{macro}{\PrintEnvName} \marg{name} \qquad Prints an environment name.
1869 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
1870 % \begin{macrocode}
1871 \providecommand*{\PrintEnvName}{}
1872 \renewcommand*{\PrintEnvName}[1]
1873 {\strut{\scriptsize{}Env}\quad\MacroFont#1\ }
1874 % \end{macrocode}
1875 % \end{macro}
1876
1877
1878 %
1879 % \begin{macro}{\DTXD@printtype} \marg{text}
1880 %
1881 % Used to print the object category in the margin:
1882 %
1883 % \changes{v1.00}{2019/01/09}{Sans tag font.}
1884 % \begin{macrocode}
1885 \newcommand*{\DTXD@printtype}[1]
1886 {\raggedleft\strut{\scriptsize\sffamily#1}\quad\MacroFont}
1887 % \end{macrocode}
1888 % \end{macro}
1889
1890
1891
1892
1893 % \begin{macro}{\usage} \marg{text}
1894 %
1895 % Allow hyperlinks in the ``usage'' index entries:
1896 %
1897 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
1898 % \begin{macrocode}
1899 \IfPackageLoadedTF{doc}{}{% not doc package
1900
1901 \providecommand{\usage}{}
1902 \renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
1903
1904 }% not doc package
1905 % \end{macrocode}
1906 % \end{macro}
1907
1908
1909 % \begin{macro}{\DTXD@origwrindex} Used to bypass \pkg{hyperref} index modifications.
1910 % \begin{macrocode}
1911 \let\DTXD@origwrindex\@wrindex
1912 % \end{macrocode}
1913 % \end{macro}
1914
1915
1916
1917 % \begin{macro}{\DTXD@margintag} \marg{category} \marg{name} \marg{margin tag}
1918 %
1919 % Creates the margin tag for the object being described.
1920 %
1921 % The |category| is used to sub-categorize keys into their key/value groups.
1922 %
1923 % \changes{v1.01}{2019/01/20}{Put margin tag category in brackets.}
1924 % \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
1925 % \begin{macrocode}
1926 \newcommand*{\DTXD@margintag}[3]{%
1927 \@ifundefined{@captype}{% not float?
1928 \leavevmode%
1929 \marginpar{%
1930 {%
1931 \hbadness=10000%
1932 \hfuzz=5em%
1933 \DTXD@printtype{%
1934 #3% margintag
1935 \ifblank{#1}{}{ [#1]}% category
1936 }%
1937 \texttt{#2}% name
1938 }%
1939 }% marginpar
1940 }{}% not float?
1941 }
1942 % \end{macrocode}
1943 % \end{macro}
1944
1945
1946 % \begin{macro}{\DTXD@index}
1947 % \marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
1948 %
1949 % Creates the index entries for the object being described, where
1950 % name has no backslash or underscore.
1951 %
1952 % The |category| is used to sub-categorize keys into their key/value groups.
1953 % |main| prints code lines in the index, and |usage| prints page numbers.
1954 %
1955 % \begin{macrocode}
1956 \newcommand*{\DTXD@index}[5]{%
1957 % \end{macrocode}
1958 % The |makeindex| program allows each index entry to call a macro by appending
1959 % a vertical bar and a macro name to each entry.
1960 % \pkg{hyperref} adds a call by \cs{hyperpage} to each index entry, by appending
1961 % the phrase \verb+|hyperpage+ to the entry in the |.idx| file.
1962 % The \pkg{doc} package uses the same mechanism to
1963 % distinguish between code line entries (\verb+|main+) and
1964 % references to the use of a macro (\verb+|usage+). The problem is that |makeindex|
1965 % can only handle one macro call, but \pkg{hyperref} tries to append its \verb+|hyperpage+
1966 % to the already-existing \verb+|usage+ or \verb+|main+.
1967 %
1968 % The solution used for \pkg{dtxdescribe} is to allow \pkg{hyperref} to modify all
1969 % regular index entries, but use the original definition of \cs{@wrindex}
1970 % for the \cs{Describe}\rule{.25in}{.4pt} macros, before \pkg{hyperref} modified it.
1971 % Then, the \cs{usage} macro, defined above, manually adds the hyperlink.
1972 %
1973 % Below, \cs{@bsphack} and \cs{@esphack} seem to be required for \cs{@wrindex} to work.
1974 % \cs{ignorespaces} is used in addition because \cs{Declare} and \cs{index} entries often
1975 % come in groups.
1976 % \begin{macrocode}
1977 \@bsphack%
1978 \begingroup%
1979 \DTXD@origwrindex{%
1980 % \end{macrocode}
1981 %
1982 % Index by name:
1983 %
1984 % Write the name, the formatted name, the index tag, and the category:
1985 % \begin{macrocode}
1986 #2\actualchar{\protect\ttfamily#2} % name
1987 (#4)% index tag
1988 \ifblank{#1}{}{ [#1]}%
1989 \encapchar #5}%
1990 % \end{macrocode}
1991 %
1992 % Index by tag and category:
1993 %
1994 % Write the tag and category as a group, under which is the name and the formatted name.
1995 % \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
1996 % \begin{macrocode}
1997 \begingroup%
1998 \DTXD@origwrindex{%
1999 #4:\levelchar% index tag
2000 \ifblank{#1}{}{[#1]:\levelchar}%
2001 #2\actualchar{\protect\ttfamily#2}% name
2002 \encapchar #5}%
2003 % \end{macrocode}
2004 %
2005 % Possibly index by category and name:
2006 % \begin{macrocode}
2007 \ifblank{#1}{}{% category given
2008 \begingroup%
2009 \DTXD@origwrindex{%
2010 #1\actualchar[#1]:\levelchar% category
2011 #2\actualchar{\protect\ttfamily#2} % name
2012 (#4)% index tag
2013 \encapchar #5}%
2014 }% category given
2015 % \@esphack%
2016 \@esphack%
2017 \ignorespaces%
2018 }
2019 % \end{macrocode}
2020 % \end{macro}
2021
2022 % \begin{macro}{\DTXD@margintagindex}
2023 % \marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
2024 %
2025 % Creates the margin tag and the index entries.
2026 % The |category| is used to sub-categorize keys into their key/value groups.
2027 % \begin{macrocode}
2028 \newcommand*{\DTXD@margintagindex}[5]{%
2029 % \@bsphack%
2030 % \end{macrocode}
2031 %
2032 % The margin tag and the name:
2033 % \begin{macrocode}
2034 \DTXD@margintag{#1}{#2}{#3}%
2035 % \end{macrocode}
2036 %
2037 % The index entries:
2038 % \begin{macrocode}
2039 \DTXD@index{#1}{#2}{#3}{#4}{#5}%
2040 }
2041 % \end{macrocode}
2042 % \end{macro}
2043 %
2044 %
2045 % \begin{macro}{\DTXD@macroname} \marg{control sequence}
2046 %
2047 % Given a control sequence such as \cs{name}, prints its name without the backslash.
2048 %
2049 % From:
2050 % \href{http://tex.stackexchange.com/questions/42318/removing-a-backslash-from-a-character-sequence}
2051 % {http://tex.stackexchange.com/questions/42318/\\
2052 % \hspace*{.5in}removing-a-backslash-from-a-character-sequence}
2053 % \begin{macrocode}
2054 \begingroup\lccode`\|=`\\
2055 \lowercase{\endgroup\def\removebs#1{\if#1|\else#1\fi}}
2056 \newcommand*{\DTXD@macroname}[1]{\expandafter\removebs\string#1}
2057 % \end{macrocode}
2058 % \end{macro}
2059
2060
2061 % \begin{macro}{\DTXD@verbatimcmd} \marg{\cs{name}}
2062 %
2063 % While printing to the index file,
2064 % prints the \cs{name} verbatim.
2065 % From \cs{SpecialIndex} in the \pkg{doc} package.
2066 % \begin{macrocode}
2067 \newcommand*{\DTXD@verbatimcmd}[1]{%
2068 \string\verb\quotechar*\verbatimchar\string#1\verbatimchar%
2069 }
2070 % \end{macrocode}
2071 % \end{macro}
2072
2073 % \begin{macro}{\DTXD@cmdmargintagindex}
2074 % \marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
2075 %
2076 % Creates the margin tag and index entries where name is a \cs{macro}.
2077 %
2078 % \changes{v1.00}{2019/01/09}{Sans tag font.}
2079 % \changes{v1.01}{2019/01/20}{Put margin tag category in brackets.}
2080 % \begin{macrocode}
2081 \newcommand*{\DTXD@cmdmargintagindex}[5]{%
2082 \@bsphack%
2083 % \end{macrocode}
2084 %
2085 % Create a margin tag with the name of the macro:
2086 % \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
2087 % \begin{macrocode}
2088 \@ifundefined{@captype}{% not float?
2089 \leavevmode%
2090 \marginpar{%
2091 {%
2092 \hbadness=10000%
2093 \hfuzz=5em%
2094 \DTXD@printtype{%
2095 #3% margin tag
2096 \ifblank{#1}{}{ [#1]}% category
2097 }%
2098 \cmd{#2}% name
2099 }%
2100 }% marginpar
2101 }{}% not float?
2102 % \end{macrocode}
2103 %
2104 % Create an index entry sorted by the name without its leading backslash,
2105 % followed by the macro name with the backslash, and the tag.
2106 % Prepend with the category if given.
2107 %
2108 % Write [category]:>name=csname (indextag)\verb+|usage+
2109 % \begin{macrocode}
2110 \begingroup%
2111 \DTXD@origwrindex{%
2112 \ifblank{#1}{}{#1\actualchar[#1]:\levelchar}% category
2113 \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2} % name
2114 (#4)% index tag
2115 \encapchar #5}%
2116 % \end{macrocode}
2117 %
2118 % Create an index entry grouped by the tag,
2119 % then printed and sorted by the macro name with the backslash, and the tag.
2120 %
2121 % Write indextag:>[category]:>csname\verb+|usage+
2122 % \changes{v0.11}{2018/02/05}{Index tag no longer plural.}
2123 % \begin{macrocode}
2124 \begingroup%
2125 \DTXD@origwrindex{%
2126 #4:\levelchar% index tag
2127 \ifblank{#1}{}{[#1]:\levelchar}% category
2128 \DTXD@verbatimcmd{#2}% name
2129 \encapchar #5}%
2130 \@esphack%
2131 \ignorespaces%
2132 }
2133 % \end{macrocode}
2134 % \end{macro}
2135 %
2136
2137
2138 % \subsection{\pkg{doc}: Key handling for object categories}
2139
2140 % If using \pkg{doc}, the optional key \Slash value argument may also
2141 % include an object category. This is supported by assigning any unknown
2142 % key to be the category.
2143 %
2144 % The category may be given using the key |c|, or as the default action
2145 % when an unknown key is given.
2146 %
2147 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
2148 % \begin{macrocode}
2149 \ExplSyntaxOn
2150 \IfPackageLoadedTF{doc}{
2151
2152 \newcommand*{\DTXD@category}{}
2153
2154 \keys_define:nn {doc}
2155 {
2156 c .cs_set:Np = \DTXD@category,
2157 unknown .code:n = {%
2158 \renewcommand*{\DTXD@category}{\l_keys_key_str}%
2159 },
2160 }
2161
2162 }{}% doc loaded
2163 \ExplSyntaxOff
2164 % \end{macrocode}
2165
2166
2167 % \subsection{\pkg{doc}: Handling \cs{marginpar} inside a float}
2168
2169 % To avoid a floats lost error, do not print margin tags if inside a float.
2170 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
2171 % \changes{v1.09}{2024/01/20}{Removed extra spaces.}
2172 % \begin{macrocode}
2173 \IfPackageLoadedTF{doc}{
2174
2175 \def\@doc@describe#1#2{% dtxdescribe
2176 \ifdoc@noprint\else%
2177 \@ifundefined{@captype}{% not float? dtxdescribe
2178 \marginpar{\raggedleft%
2179 \strut%
2180 \doc@providetarget%
2181 \@nameuse{PrintDescribe#1}{#2}%
2182 \ifdefvoid{\DTXD@category}{}{% dtxdescribe
2183 \space{\footnotesize[\mbox{\DTXD@category}]}%
2184 }%
2185 }%
2186 }{}%
2187 \fi%
2188 \ifdoc@noindex\else%
2189 \@nameuse{Special#1Index}{#2}%
2190 \fi%
2191 \@esphack%
2192 \endgroup%
2193 \ignorespaces%
2194 }
2195
2196 }{}% doc loaded
2197 % \end{macrocode}
2198
2199
2200
2201
2202 % \subsection{\pkg{doc}: Handling categories and detokenizing names}
2203 %
2204 % \begin{macro}{\@NewDocElement}
2205 % File names and such may include underscores or other characters,
2206 % so patch \pkg{doc} to neutralized while processing.
2207 %
2208 % \changes{v1.06}{2022/12/06}{Fixed for updated \pkg{doc}.}
2209 % \begin{macrocode}
2210 \IfPackageLoadedTF{doc}{%
2211
2212 \def\@NewDocElement#1#2#3{%
2213 \doc@macrolikefalse%
2214 \doc@topleveltrue%
2215 \def\doc@idxtype{#3}%
2216 \def\doc@idxgroup{#3s}%
2217 \let\doc@printtype\@empty%
2218 \csname keys_set:nn\endcsname{doc}{#1}%
2219 \ifx\doc@printtype\@empty%
2220 \@temptokena{}%
2221 \else%
2222 \@temptokena\expandafter{\expandafter%
2223 \textnormal\expandafter{\expandafter%
2224 \space\expandafter%
2225 (\doc@printtype)}}%
2226 \fi%
2227 \@nameedef{Print#2Name}##1{%
2228 {\noexpand\MacroFont%
2229 \ifdoc@macrolike%
2230 \noexpand\string##1% dtxdescribe
2231 \else%
2232 \noexpand\detokenize\expandafter{##1}% dtxdescribe
2233 \fi%
2234 \the\@temptokena%
2235 }}%
2236 \expandafter\let\csname PrintDescribe#2\expandafter\endcsname%
2237 \csname Print#2Name\endcsname%
2238 \edef\doc@expr{%
2239 \ifdoc@macrolike%
2240 \noexpand\doc@createspecialmacrolikeindexes%
2241 \else%
2242 \noexpand\doc@createspecialindexes%
2243 \fi%
2244 {#2}%
2245 }%
2246 \expandafter\expandafter\expandafter%
2247 \doc@expr%
2248 \expandafter\expandafter\expandafter%
2249 {\expandafter\doc@idxtype\expandafter}\expandafter%
2250 {\doc@idxgroup}%
2251 \doc@createdescribe{#2}%
2252 \ifdoc@macrolike%
2253 \doc@createenv{TT}{#2}{#3}%
2254 \else%
2255 \doc@createenv{TF}{#2}{#3}%
2256 \fi
2257 }
2258 % \end{macrocode}
2259 % \end{macro}
2260
2261
2262 % \begin{macro}{\DTXDbreak} Inserts a possible line break point.
2263 % Used in the index to allow line breaks before verbatim category names.
2264 % \changes{v1.07}{2022/12/24}{Improved line breaks.}
2265 % \begin{macrocode}
2266 \newcommand*{\DTXDbreak}{\space\penalty200}
2267 % \end{macrocode}
2268 % \end{macro}
2269
2270 % \begin{macro}{\DTXD@printobjectname} \marg{name w/o backslash} \marg{name} \quad
2271 % Adds the object name to the index in verbatim.
2272 % These are passed as arguments instead of directly used here because they must
2273 % have their value when the index is written instead of when \cs{DTXD@printobjectname}
2274 % is used when the index is read back.
2275 %
2276 % \begin{macrocode}
2277 \newcommand*{\DTXD@printobjectname}[2]{%
2278 #1%
2279 \actualchar%
2280 \string\verb% %
2281 \quotechar%
2282 *%
2283 \verbatimchar%
2284 #2%
2285 \verbatimchar%
2286 }
2287 % \end{macrocode}
2288 % \end{macro}
2289
2290 % \begin{macro}{\DTXD@maybecategory} If there is a category, it is added verbatim.
2291 % \begin{macrocode}
2292 \newcommand*{\DTXD@maybecategory}{%
2293 \ifdefvoid{\DTXD@category}%
2294 {}%
2295 {%
2296 % \end{macrocode}
2297 %
2298 % \cs{DTXDbreak} inserts a possible line break here,
2299 % allowing a break if the following verbatim is too long.
2300 % \changes{v1.07}{2022/12/24}{Improved line breaks.}
2301 % \begin{macrocode}
2302 \string\DTXDbreak%
2303 % \end{macrocode}
2304 % \begin{macrocode}
2305 [%
2306 \string\verb%
2307 \noexpand\quotechar%
2308 % \end{macrocode}
2309 % \changes{v1.07}{2022/12/19}{\cs{verb}*.}
2310 % \begin{macrocode}
2311 *%
2312 \verbatimchar\DTXD@category\verbatimchar%
2313 ]}%
2314 }
2315 % \end{macrocode}
2316 % \end{macro}
2317
2318 % \begin{macro}{\DTXD@categorylevelname} The simplified name, without backslash.
2319 % \begin{macrocode}
2320 \newcommand*{\DTXD@categorylevelname}
2321 % \end{macrocode}
2322 % \end{macro}
2323
2324
2325 % \begin{macro}{\DTXD@maybecategorylevel} \marg{object\_type}
2326 % \quad If a category is assigned, index by category.
2327 %
2328 % \begin{description}
2329 % \item [arg 1:] Type of object, shown between parens (), such as |macro|, |boolean|, etc.
2330 % \item [\cs{DTXD@category}:] The name of the category, printed in brackets [],
2331 % such as \cs{macroname}.
2332 % \item [\cs{DTXD@categorylevelname}:] The simplified name of the category, such as |macroname|.
2333 % \item [\cs{@gtempa}:] The name of this particular object.
2334 % \end{description}
2335 %
2336 % \changes{v1.07}{2022/12/19}{\cs{verb}*.}
2337 % \begin{macrocode}
2338 \newcommand*{\DTXD@maybecategorylevel}[1]{%
2339 \ifdefvoid{\DTXD@categorylevelname}%
2340 {}%
2341 {%
2342 % \end{macrocode}
2343 % Index: \\
2344 % |categorylevelname=\verb!*+[category]:+>name=\verb!*+<prefix>name+<break>(type)|
2345 % \begin{macrocode}
2346 \index{%
2347 \DTXD@categorylevelname%
2348 \noexpand\actualchar%
2349 \string\verb% % to fool emacs highlighting
2350 \noexpand\quotechar%
2351 *%
2352 \noexpand\verbatimchar%
2353 [\DTXD@category]:%
2354 \verbatimchar%
2355 \noexpand\levelchar%
2356 \noexpand\DTXD@printobjectname{\DTXD@gtempa@nobackslash}{\@gtempa}%
2357 \ifblank{#1}{}{\string\DTXDbreak (#1)}%
2358 % \end{macrocode}
2359 %
2360 % \cs{the}\cs{@temptokena} is not used here.
2361 % \changes{v1.07}{2022/12/19}{Fix occasional crash.}
2362 %
2363 % \begin{macrocode}
2364 \noexpand\doc@handleencap{usage}%
2365 }% index
2366 }%
2367 }
2368 % \end{macrocode}
2369 % \end{macro}
2370
2371 % \begin{macro}{\DTXD@findcategorylevelname}
2372 % Given \cs{DTXD@category}, create \cs{DTXD@categorylevelname},
2373 % a detokenized name without backslash.
2374 % \begin{macrocode}
2375 \newcommand*{\DTXD@findcategorylevelname}{%
2376 \edef\DTXD@categorylevelname{\DTXD@category}%
2377 \edef\DTXD@categorylevelname{\detokenize\expandafter{\DTXD@categorylevelname}}%
2378 \IfBeginWith{\DTXD@categorylevelname}{\DTXD@backslash}%
2379 {\StrGobbleLeft{\DTXD@categorylevelname}{1}[\DTXD@categorylevelname]}%
2380 {}%
2381 }
2382 % \end{macrocode}
2383 % \end{macro}
2384
2385
2386 % \begin{macro}{\DTXD@gtempa@nobackslash} A version without the leading backslash.
2387 % \begin{macrocode}
2388 \newcommand*{\DTXD@gtempa@nobackslash}{}
2389 % \end{macrocode}
2390 % \end{macro}
2391
2392 % \begin{macro}{\DTXD@findgtempa} Detokenize \cs{@gtempa} and
2393 % also find another version without any leading backslash.
2394 % \changes{v1.07}{2022/12/19}{Detokenized names.}
2395 % \begin{macrocode}
2396 \newcommand*{\DTXD@findgtempa}[1]{%
2397 \edef\@gtempa{\detokenize{#1}}%
2398 \IfEndWith{\@gtempa}{ }{\StrGobbleRight{\@gtempa}{1}[\@gtempa]}{}%
2399 \IfBeginWith{\@gtempa}{\DTXD@backslash}%
2400 {\StrGobbleLeft{\@gtempa}{1}[\DTXD@gtempa@nobackslash]}%
2401 {\edef\DTXD@gtempa@nobackslash{\@gtempa}}%
2402 }
2403 % \end{macrocode}
2404 % \end{macro}
2405
2406 % \begin{macro}{\doc@createspecialindexes}
2407 % \marg{1: name} \marg{2: index type} \marg{3: index group}
2408 % \begin{macrocode}
2409 \def\doc@createspecialindexes#1#2#3{%
2410 \@temptokena{\space (#2)}%
2411 \@temptokenb{#3:}%
2412 % \end{macrocode}
2413 %
2414 % \textbf{Define \cs{SpecialMain<name>Index} \marg{1: name}}
2415 % \begin{macrocode}
2416 \@nameedef{SpecialMain#1Index}##1{%
2417 % \end{macrocode}
2418 %
2419 % Find \cs{@gtempa}, the name of the object.
2420 % \begin{macrocode}
2421 \noexpand\DTXD@findgtempa{##1}%
2422 % \end{macrocode}
2423 %
2424 % \begin{description}
2425 % \item[\cs{@temptokena}:] Index (type).
2426 % \item[\cs{@temptokenb}:] Index group.
2427 % \item[\cs{@gtempa}:] Detokenized name of the particular object.
2428 % \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
2429 % \end{description}
2430 %
2431 % \begin{macrocode}
2432 \noexpand\@bsphack%
2433 \noexpand\DTXD@findcategorylevelname% dtxdescribe
2434 % \end{macrocode}
2435 % \begin{macrocode}
2436 \ifdoc@toplevel%
2437 % \noexpand\special@index{##1\noexpand\actualchar
2438 %
2439 %
2440 % \end{macrocode}
2441 %
2442 % Index: \\
2443 % \verb?name=\verb!*+name+ (type) [category]|main?
2444 % \begin{macrocode}
2445 \noexpand\special@index{%
2446 \noexpand\DTXD@printobjectname% dtxdescribe
2447 {\noexpand\DTXD@gtempa@nobackslash}%
2448 {\noexpand\@gtempa}%
2449 \ifx\@nil#2\@nil\else \the\@temptokena \fi%
2450 \noexpand\DTXD@maybecategory% dtxdescribe
2451 \noexpand\encapchar main%
2452 }%
2453 % \end{macrocode}
2454 %
2455 % Maybe add the category index entry:
2456 % \begin{macrocode}
2457 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2458 \fi%
2459 %
2460 %
2461 % \end{macrocode}
2462 %
2463 % If group is not empty, index: \\
2464 % \verb?group:>name=\verb!*+name+ [category]|main?
2465 %
2466 % \begin{macrocode}
2467 \ifx\@nil#3\@nil\else%
2468 \noexpand\special@index{%
2469 \the\@temptokenb\noexpand\levelchar%
2470 % ##1\noexpand\actualchar{\string\ttfamily\space##1}%
2471 \noexpand\DTXD@printobjectname% dtxdescribe
2472 {\noexpand\DTXD@gtempa@nobackslash}%
2473 {\noexpand\@gtempa}%
2474 \noexpand\DTXD@maybecategory% dtxdescribe
2475 \noexpand\encapchar main%
2476 }%
2477 % \end{macrocode}
2478 %
2479 % Maybe add the category index entry:
2480 % \begin{macrocode}
2481 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2482 \fi%
2483 \noexpand\@esphack}%
2484 % \end{macrocode}
2485 %
2486 % \textbf{Define \cs{Special<name>Index} \marg{1: name}}
2487 %
2488 % \changes{v1.09}{2024/01/20}{Removed extra spaces.}
2489 % \begin{macrocode}
2490 \@nameedef{Special#1Index}##1{%
2491 \noexpand\DTXD@findgtempa{##1}%
2492 % \end{macrocode}
2493 %
2494 % \begin{description}
2495 % \item[\cs{@temptokena}:] Index (type).
2496 % \item[\cs{@temptokenb}:] Index group.
2497 % \item[\cs{@gtempa}:] Detokenized name of the particular object.
2498 % \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
2499 % \end{description}
2500 %
2501 % \begin{macrocode}
2502 \noexpand\@bsphack%
2503 \noexpand\DTXD@findcategorylevelname% dtxdescribe
2504 % \end{macrocode}
2505 %
2506 % If is a top level object, index:\\
2507 % \verb?name=\verb!*+name+ (type) [category]|usage?
2508 % \begin{macrocode}
2509 \ifdoc@toplevel%
2510 \noexpand\doc@providetarget%
2511 % \end{macrocode}
2512 % \begin{macrocode}
2513 % \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}%
2514 \noexpand\index{%
2515 \noexpand\DTXD@printobjectname% dtxdescribe
2516 {\noexpand\DTXD@gtempa@nobackslash}%
2517 {\noexpand\@gtempa}%
2518 \ifx\@nil#2\@nil\else \the\@temptokena \fi%
2519 \noexpand\DTXD@maybecategory% dtxdescribe
2520 \noexpand\doc@handleencap{usage}%
2521 }%
2522 % \end{macrocode}
2523 %
2524 % Maybe add the category index entry:
2525 % \begin{macrocode}
2526 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2527 \fi%
2528 %
2529 %
2530 % \end{macrocode}
2531 %
2532 % If group is not empty, index: \\
2533 % \verb?group:>name=\verb!*+name+ [category]|usage?
2534 % \begin{macrocode}
2535 \ifx\@nil#3\@nil\else%
2536 \noexpand\index{%
2537 \the\@temptokenb\noexpand\levelchar%
2538 % ##1\noexpand\actualchar{\string\ttfamily\space##1}
2539 \noexpand\DTXD@printobjectname% dtxdescribe
2540 {\noexpand\DTXD@gtempa@nobackslash}%
2541 {\noexpand\@gtempa}%
2542 \noexpand\DTXD@maybecategory% dtxdescribe
2543 \noexpand\doc@handleencap{usage}%
2544 }%
2545 % \end{macrocode}
2546 %
2547 % Maybe add the category index entry:
2548 % \begin{macrocode}
2549 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2550 \fi%
2551 %
2552 %
2553 \noexpand\@esphack}}
2554 % \end{macrocode}
2555 % \end{macro}
2556
2557
2558 % \begin{macro}{\doc@createspecialmacrolikeindexes}
2559 % \marg{1: name} \marg{2: index type} \marg{3: index group}
2560 % \changes{v1.07}{2022/12/24}{Added category names for macros.}
2561 % \begin{macrocode}
2562 \def\doc@createspecialmacrolikeindexes#1#2#3{%
2563 \@temptokena{\space (#2)}%
2564 \@temptokenb{#3:}%
2565 % \end{macrocode}
2566 %
2567 % \textbf{Define \cs{Code<name>Index} \marg{1: |main| or |usage|} \marg{2: name}}
2568 %
2569 % \begin{macrocode}
2570 \@nameedef{Code#1Index}##1##2{%
2571 \noexpand\DTXD@findgtempa{##2}%
2572 % \end{macrocode}
2573 %
2574 % \begin{description}
2575 % \item[\cs{@temptokena}:] Index type.
2576 % \item[\cs{@temptokenb}:] Index group.
2577 % \item[\cs{@gtempa}:] Detokenized name of the particular object.
2578 % \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
2579 % \end{description}
2580 %
2581 % \begin{macrocode}
2582 \noexpand\@bsphack%
2583 \noexpand\DTXD@findcategorylevelname% dtxdescribe
2584 % \end{macrocode}
2585 % \begin{macrocode}
2586 \noexpand\ifdoc@noindex\noexpand\else%
2587 % \end{macrocode}
2588 %
2589 % If a top level object, index:\\
2590 % \verb?name=\verb!*+\name+ (type) [category]|<main or usage>?
2591 % \begin{macrocode}
2592 \ifdoc@toplevel%
2593 \noexpand\special@index{%
2594 \noexpand\DTXD@printobjectname% dtxdescribe
2595 {\noexpand\DTXD@gtempa@nobackslash}%
2596 {\noexpand\@gtempa}%
2597 \ifx\@nil#2\@nil\else \the\@temptokena \fi%
2598 \noexpand\DTXD@maybecategory% dtxdescribe
2599 \noexpand\encapchar ##1%
2600 }%
2601 % \end{macrocode}
2602 %
2603 % Maybe add the category index entry:
2604 % \begin{macrocode}
2605 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2606 \fi%
2607 % \end{macrocode}
2608 %
2609 % If group is not empty, index: \\
2610 % \verb?group:>name=\verb!*+\name+ [category]|<main or usage>?
2611 % \begin{macrocode}
2612 \ifx\@nil#3\@nil\else%
2613 \noexpand\special@index{%
2614 \the\@temptokenb\noexpand\levelchar%
2615 \noexpand\DTXD@printobjectname% dtxdescribe
2616 {\noexpand\DTXD@gtempa@nobackslash}%
2617 {\noexpand\@gtempa}%
2618 \noexpand\DTXD@maybecategory% dtxdescribe
2619 \noexpand\encapchar ##1%
2620 }%
2621 % \end{macrocode}
2622 %
2623 % Maybe add the category index entry:
2624 % \begin{macrocode}
2625 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2626 \fi%
2627 \noexpand\fi%
2628 \noexpand\@esphack}%
2629 % \end{macrocode}
2630 %
2631 % \textbf{Define \cs{SpecialMain<name>Index} \marg{1: name}}
2632 % \begin{macrocode}
2633 \@nameedef{SpecialMain#1Index}##1{%
2634 \expandafter\noexpand\csname Code#1Index\endcsname%
2635 {main}{##1}}%
2636 % \end{macrocode}
2637 %
2638 % \textbf{Define \cs{Special<name>Index} \marg{1: name}}
2639 % \changes{v1.09}{2024/01/20}{Removed extra spaces.}
2640 % \begin{macrocode}
2641 \@nameedef{Special#1Index}##1{%
2642 \noexpand\DTXD@findgtempa{##1}%
2643 % \end{macrocode}
2644 %
2645 % \begin{description}
2646 % \item[\cs{@temptokena}:] Index type.
2647 % \item[\cs{@temptokenb}:] Index group.
2648 % \item[\cs{@gtempa}:] Detokenized name of the particular object.
2649 % \item[\cs{DTXD@gtempa@nobackslash}:] Detokenized name without backslash.
2650 % \end{description}
2651 %
2652 % \begin{macrocode}
2653 \noexpand\@bsphack%
2654 \noexpand\DTXD@findcategorylevelname% dtxdescribe
2655 % \end{macrocode}
2656 % \begin{macrocode}
2657 \noexpand\ifdoc@noindex\noexpand\else%
2658 % \end{macrocode}
2659 %
2660 % If a top level object, index:\\
2661 % \verb?name=\verb!*+\name+ (type) [category]|usage?
2662 % \begin{macrocode}
2663 \ifdoc@toplevel%
2664 \noexpand\doc@providetarget%
2665 \noexpand\index{%
2666 \noexpand\DTXD@printobjectname% dtxdescribe
2667 {\noexpand\DTXD@gtempa@nobackslash}%
2668 {\noexpand\@gtempa}%
2669 \ifx\@nil#2\@nil\else \the\@temptokena \fi%
2670 \noexpand\DTXD@maybecategory% dtxdescribe
2671 \noexpand\doc@handleencap{usage}%
2672 }%
2673 % \end{macrocode}
2674 %
2675 % Maybe add the category index entry:
2676 % \begin{macrocode}
2677 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2678 \fi%
2679 % \end{macrocode}
2680 %
2681 % If group is not empty, index: \\
2682 % \verb?group:>name=\verb!*+\name+ [category]|usage?
2683 % \begin{macrocode}
2684 \ifx\@nil#3\@nil\else%
2685 \noexpand\index{%
2686 \the\@temptokenb\noexpand\levelchar%
2687 \noexpand\DTXD@printobjectname% dtxdescribe
2688 {\noexpand\DTXD@gtempa@nobackslash}%
2689 {\noexpand\@gtempa}%
2690 \noexpand\DTXD@maybecategory% dtxdescribe
2691 \noexpand\doc@handleencap{usage}%
2692 }%
2693 % \end{macrocode}
2694 %
2695 % Maybe add the category index entry:
2696 % \begin{macrocode}
2697 \noexpand\DTXD@maybecategorylevel{#2}% dtxdescribe
2698 \fi%
2699 \noexpand\fi%
2700 \noexpand\@esphack}}
2701
2702 }{}% doc loaded
2703 % \end{macrocode}
2704 % \end{macro}
2705
2706
2707 % \subsection{Not \pkg{doc}: \cs{DescribeMacro} and \cs{DescribeEnvironment}}
2708
2709 % \begin{macro}{\DescribeMacro} \oarg{category} \marg{\cs{name}}
2710 %
2711 % Redefined to allow hyperlinked index entries and an optional category:
2712 %
2713 % \changes{v1.00}{2019/01/09}{Sans tag font.}
2714 % \changes{v1.01}{2019/01/20}{Put margin tag category in brackets.}
2715 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
2716 % \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
2717 % \begin{macrocode}
2718 \IfPackageLoadedTF{doc}{}{% not doc
2719
2720 \providecommand*{\DescribeMacro}{}
2721 \renewcommand*{\DescribeMacro}[2][]{%
2722 \@bsphack%
2723 % \end{macrocode}
2724 % Create the margin tag with the macro's name:
2725 % \begin{macrocode}
2726 \@ifundefined{@captype}{% not float?
2727 \leavevmode%
2728 \marginpar{%
2729 {%
2730 \hbadness=10000%
2731 \hfuzz=5em%
2732 \raggedleft%
2733 \ifblank{#1}{}{{\scriptsize\textsf{[#1]}} }% category
2734 \cmd{#2}% name
2735 }%
2736 }% marginpar
2737 }{}% not float?
2738 % \end{macrocode}
2739 %
2740 % Write the index sorted by the name without the backslash,
2741 % followed by the actual name with the backslash.
2742 % Append the category if given.
2743 %
2744 % Write name=csname>[category]\verb+|usage+
2745 % \begin{macrocode}
2746 \begingroup%
2747 \DTXD@origwrindex{%
2748 \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name
2749 \ifblank{#1}{}{\levelchar[#1]}% category
2750 \encapchar usage%
2751 }%
2752 % \end{macrocode}
2753 % Only if a category was given:
2754 % \begin{macrocode}
2755 \ifblank{#1}%
2756 {}% no category
2757 {% category given
2758 % Again, and prepend the category:
2759 %
2760 % Write category=[category]:>name=csname\verb+|usage+
2761 % \begin{macrocode}
2762 \begingroup%
2763 \DTXD@origwrindex{%
2764 #1\actualchar[#1]:\levelchar%
2765 \DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}%
2766 \encapchar usage}%
2767 }% category given
2768 \@esphack%
2769 \ignorespaces%
2770 }
2771
2772 }% not doc
2773 % \end{macrocode}
2774 % \end{macro}
2775
2776
2777
2778 % \begin{macro}{\DescribeEnv} \oarg{category} \marg{environment name}
2779 %
2780 % Redefined to allow hyperlinked index entries:
2781 % \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
2782 % \begin{macrocode}
2783 \IfPackageLoadedTF{doc}{}{% not doc
2784
2785 \providecommand*{\DescribeEnv}{}
2786 \renewcommand*{\DescribeEnv}[2][]
2787 {\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}}
2788
2789 }% not doc
2790 % \end{macrocode}
2791 % \end{macro}
2792
2793
2794
2795
2796 % \subsection{New \cs{Describe\dots} macros}
2797
2798
2799 % \begin{macro}{\DTXD@filemarginparindex}
2800 % \marg{category} \marg{name} \marg{margin tag} \marg{index tag} \marg{main/usage}
2801 %
2802 % The name may have underscores.
2803 % \begin{macrocode}
2804 \IfPackageLoadedTF{doc}{}{% not doc
2805 \newcommand*{\DTXD@filename}{}
2806
2807 \newcommand*{\DTXD@filemarginparindex}[5]{%
2808 % \end{macrocode}
2809 % Create a detokenized version of the filename\dots
2810 % \begin{macrocode}
2811 \renewcommand{\DTXD@filename}{\detokenize{#2}}%
2812 % \end{macrocode}
2813 % \dots\ then replace any underscores with a detokenized |\_|,
2814 % which will print as an underscore when read back from the index file:
2815 % \begin{macrocode}
2816 \StrSubstitute{\DTXD@filename}{\detokenize{_}}{\detokenize{\_}}[\DTXD@filename]%
2817 % \end{macrocode}
2818 % The original filename is printed in the margin.
2819 % Any underscore characters have already been disabled
2820 % by the \cs{catcode} change.
2821 % \changes{v1.00}{2019/01/10}{Fix: File category.}
2822 % \begin{macrocode}
2823 \DTXD@margintag{#1}{#2}{#3}%
2824 % \end{macrocode}
2825 % The detokenized and sanitized version is sent to the index file:
2826 % \begin{macrocode}
2827 \DTXD@index{#1}{\DTXD@filename}{#3}{#4}{#5}%
2828 % \end{macrocode}
2829 % End the group with the disabled underscore,
2830 % and clean up the extra space from the \cs{catcode} command:
2831 % \begin{macrocode}
2832 \endgroup%
2833 \ignorespaces%
2834 }
2835 }% not doc
2836 % \end{macrocode}
2837 % \end{macro}
2838 %
2839 %
2840 % \begin{macro}{\DescribeMacro} \quad Redefine with new definitions.
2841 % \begin{macro}{\DescribeEnvironment} \quad Redefine with new definitions.
2842 % \begin{macrocode}
2843 \IfPackageLoadedTF{doc}{% doc
2844
2845 \RenewDocElement[macrolike = true ,
2846 idxtype = ,
2847 idxgroup = ,
2848 printtype =
2849 ]{Macro}{macro}
2850
2851 \RenewDocElement[macrolike = false ,
2852 idxtype = env. ,
2853 idxgroup = environments ,
2854 printtype = \textit{env.}
2855 ]{Env}{environment}
2856
2857 }{}% doc
2858 % \end{macrocode}
2859 % \end{macro}
2860 % \end{macro}
2861 %
2862 %
2863 %
2864 % \begin{macro}{\DescribeFile} \marg{name}
2865 %
2866 % The underscore character is temporarily disabled, then
2867 % the name is passed directly to \cs{DTXD@DescribeFile}.
2868 % \begin{macrocode}
2869 \IfPackageLoadedTF{doc}{% doc
2870
2871 \NewDocElement[
2872 macrolike=false,
2873 toplevel=true,
2874 idxtype=file,
2875 idxgroup=Files,
2876 printtype=\textit{file}
2877 ]{File}{file}
2878
2879 }{% not doc
2880
2881 \newcommand*{\DTXD@DescribeFile}[2][]{%
2882 \DTXD@filemarginparindex{#1}{#2}{File}{file}{usage}%
2883 }
2884
2885 \newcommand*{\DescribeFile}{%
2886 \begingroup\catcode`\_=12 \DTXD@DescribeFile%
2887 }
2888
2889 }% not doc
2890 % \end{macrocode}
2891 % \end{macro}
2892 %
2893 %
2894 %
2895 %
2896 % \begin{macro}{\DescribeProgram} \marg{name}
2897 %
2898 % The underscore character is temporarily disabled, then
2899 % the name is passed directly to \cs{DTXD@DescribeProgram}.
2900 % \begin{macrocode}
2901 \IfPackageLoadedTF{doc}{% doc
2902
2903 \NewDocElement[
2904 macrolike=false,
2905 toplevel=true,
2906 idxtype=program,
2907 idxgroup=Programs,
2908 printtype=\textit{Prog}
2909 ]{Program}{program}
2910
2911 }{% not doc
2912
2913 \newcommand*{\DTXD@DescribeProgram}[2][]{%
2914 \DTXD@filemarginparindex{#1}{#2}{Prog}{program}{usage}%
2915 }
2916
2917 \newcommand*{\DescribeProgram}{%
2918 \begingroup\catcode`\_=12 \DTXD@DescribeProgram%
2919 }
2920 }% not doc
2921
2922 % \end{macrocode}
2923 % \end{macro}
2924
2925
2926 %
2927 % \begin{macro}{\DescribeCommand} \marg{name}
2928 %
2929 % The underscore character is temporarily disabled, then
2930 % the name is passed directly to \cs{DTXD@DescribeCommand}.
2931 % \begin{macrocode}
2932 \IfPackageLoadedTF{doc}{% doc
2933
2934 \NewDocElement[
2935 macrolike=false,
2936 toplevel=true,
2937 idxtype=command,
2938 idxgroup=Commands,
2939 printtype=\textit{Cmd}
2940 ]{Command}{command}
2941
2942 }{% not doc
2943
2944 \newcommand*{\DTXD@DescribeCommand}[2][]{%
2945 \DTXD@filemarginparindex{#1}{#2}{Cmd}{command}{usage}%
2946 }
2947
2948 \newcommand*{\DescribeCommand}{%
2949 \begingroup\catcode`\_=12 \DTXD@DescribeCommand%
2950 }
2951
2952 }% not doc
2953 % \end{macrocode}
2954 % \end{macro}
2955 %
2956
2957
2958 % \begin{macro}{\DescribePackage} \marg{name}
2959 %
2960 % The underscore character is temporarily disabled, then
2961 % the name is passed directly to \cs{DTXD@DescribePackage}.
2962 %
2963 % \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
2964 % \begin{macrocode}
2965 \IfPackageLoadedTF{doc}{% doc
2966
2967 \NewDocElement[
2968 macrolike=false,
2969 toplevel=true,
2970 idxtype=package,
2971 idxgroup=Packages,
2972 printtype=\textit{Pkg}
2973 ]{Package}{package}
2974
2975 }{% not doc
2976
2977 \newcommand*{\DTXD@DescribePackage}[2][]{%
2978 \DTXD@filemarginparindex{#1}{#2}{Pkg}{package}{usage}%
2979 }
2980
2981 \newcommand*{\DescribePackage}{%
2982 \begingroup\catcode`\_=12 \DTXD@DescribePackage%
2983 }
2984
2985 }% not doc
2986
2987 % \end{macrocode}
2988 % \end{macro}
2989
2990 %
2991 % \begin{macro}{\DescribeClass} \marg{name}
2992 %
2993 % The underscore character is temporarily disabled, then
2994 % the name is passed directly to \cs{DTXD@DescribeClass}.
2995 %
2996 % \changes{v1.00}{2019/01/10}{Fix: Allow underscore.}
2997 % \begin{macrocode}
2998 \IfPackageLoadedTF{doc}{% doc
2999
3000 \NewDocElement[
3001 macrolike=false,
3002 toplevel=true,
3003 idxtype=class,
3004 idxgroup=Classes,
3005 printtype=\textit{Cls}
3006 ]{Class}{class}
3007
3008 }{% not doc
3009
3010 \newcommand*{\DTXD@DescribeClass}[2][]{%
3011 \DTXD@filemarginparindex{#1}{#2}{Cls}{class}{usage}%
3012 }
3013
3014 \newcommand*{\DescribeClass}{%
3015 \begingroup\catcode`\_=12 \DTXD@DescribeClass%
3016 }
3017
3018 }% not doc
3019 % \end{macrocode}
3020 % \end{macro}
3021
3022 % \begin{macro}{\DescribeOption} \oarg{category} \marg{name}
3023 % \begin{macrocode}
3024 \IfPackageLoadedTF{doc}{% doc
3025
3026 \NewDocElement[
3027 macrolike=false,
3028 toplevel=true,
3029 idxtype=option,
3030 idxgroup=Options,
3031 printtype=\textit{Opt}
3032 ]{Option}{option}
3033
3034 }{% not doc
3035
3036 \newcommand*{\DescribeOption}[2][]
3037 {\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}}
3038
3039 }% not doc
3040 % \end{macrocode}
3041 % \end{macro}
3042 %
3043 % \begin{macro}{\DescribeArgument} \oarg{category} \marg{name}
3044 %
3045 % The |category| may be used to categorize arguments by their macro or environment name.
3046 % \begin{macrocode}
3047 \IfPackageLoadedTF{doc}{% doc
3048
3049 \NewDocElement[
3050 macrolike=false,
3051 toplevel=true,
3052 idxtype=argument,
3053 idxgroup=Arguments,
3054 printtype=\textit{Arg}
3055 ]{Argument}{argument}
3056
3057 }{% not doc
3058
3059 \newcommand*{\DescribeArgument}[2][]
3060 {\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}}
3061
3062 }% not doc
3063 % \end{macrocode}
3064 % \end{macro}
3065 %
3066 % \begin{macro}{\DescribeBoolean} \oarg{category} \marg{name}
3067 % \begin{macrocode}
3068 \IfPackageLoadedTF{doc}{% doc
3069
3070 \NewDocElement[
3071 macrolike=false,
3072 toplevel=true,
3073 idxtype=boolean,
3074 idxgroup=Booleans,
3075 printtype=\textit{bool}
3076 ]{Boolean}{boolenv}
3077
3078 }{% not doc
3079
3080 \newcommand*{\DescribeBoolean}[2][]
3081 {\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}}
3082
3083 }% not doc
3084 % \end{macrocode}
3085 % \end{macro}
3086 %
3087 % \begin{macro}{\DescribeLength} \oarg{category} \marg{name}
3088 % \begin{macrocode}
3089 \IfPackageLoadedTF{doc}{% doc
3090
3091 \NewDocElement[
3092 macrolike=true,
3093 toplevel=true,
3094 idxtype=length,
3095 idxgroup=Lengths,
3096 printtype=\textit{Len}
3097 ]{Length}{length}
3098
3099 }{% not doc
3100
3101 \newcommand*{\DescribeLength}[2][]
3102 {\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}}
3103
3104 }% not doc
3105 % \end{macrocode}
3106 % \end{macro}
3107 %
3108 % \begin{macro}{\DescribeCounter} \oarg{category} \marg{name}
3109 % \begin{macrocode}
3110 \IfPackageLoadedTF{doc}{% doc
3111
3112 \NewDocElement[
3113 macrolike=false,
3114 toplevel=true,
3115 idxtype=counter,
3116 idxgroup=Counters,
3117 printtype=\textit{Ctr}
3118 ]{Counter}{counter}
3119
3120 }{% not doc
3121
3122 \newcommand*{\DescribeCounter}[2][]
3123 {\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}}
3124
3125 }% not doc
3126 % \end{macrocode}
3127 % \end{macro}
3128 %
3129 % \begin{macro}{\DescribeHook} \oarg{category} \marg{name}
3130 % \changes{v1.03}{2021/12/18}{Added.}
3131 % \begin{macrocode}
3132 \IfPackageLoadedTF{doc}{% doc
3133
3134 \NewDocElement[
3135 macrolike=true,
3136 toplevel=true,
3137 idxtype=hook,
3138 idxgroup=Hooks,
3139 printtype=\textit{Hook}
3140 ]{Hook}{hook}
3141
3142 }{% not doc
3143
3144 \newcommand*{\DescribeHook}[2][]
3145 {\DTXD@margintagindex{#1}{#2}{Hook}{hook}{usage}}
3146
3147 }% not doc
3148 % \end{macrocode}
3149 % \end{macro}
3150 %
3151 %
3152 % \begin{macro}{\DescribeSocket} \oarg{category} \marg{name}
3153 % \changes{v1.08}{2024/01/08}{Added.}
3154 % \begin{macrocode}
3155 \IfPackageLoadedTF{doc}{% doc
3156
3157 \NewDocElement[
3158 macrolike=false,
3159 toplevel=true,
3160 idxtype=socket,
3161 idxgroup=Sockets,
3162 printtype=\textit{Socket}
3163 ]{Socket}{socket}
3164
3165 }{% not doc
3166
3167 \newcommand*{\DescribeSocket}[2][]
3168 {\DTXD@margintagindex{#1}{#2}{Socket}{socket}{usage}}
3169
3170 }% not doc
3171 % \end{macrocode}
3172 % \end{macro}
3173 %
3174 %
3175 % \begin{macro}{\DescribePlug} \oarg{category} \marg{name}
3176 % \changes{v1.08}{2024/01/08}{Added.}
3177 % \begin{macrocode}
3178 \IfPackageLoadedTF{doc}{% doc
3179
3180 \NewDocElement[
3181 macrolike=false,
3182 toplevel=true,
3183 idxtype=plug,
3184 idxgroup=Plugs,
3185 printtype=\textit{Plug}
3186 ]{Plug}{plug}
3187
3188 }{% not doc
3189
3190 \newcommand*{\DescribePlug}[2][]
3191 {\DTXD@margintagindex{#1}{#2}{Plug}{plug}{usage}}
3192
3193 }% not doc
3194 % \end{macrocode}
3195 % \end{macro}
3196 %
3197 %
3198 % \begin{macro}{\DescribeKey} \oarg{category} \marg{name}
3199 %
3200 % The |category| may be used to categorize keys by their kev/value group.
3201 % \begin{macrocode}
3202 \IfPackageLoadedTF{doc}{% doc
3203
3204 \NewDocElement[
3205 macrolike=false,
3206 toplevel=true,
3207 idxtype=key,
3208 idxgroup=Keys,
3209 printtype=\textit{Key}
3210 ]{Key}{key}
3211
3212 }{% not doc
3213
3214 \newcommand*{\DescribeKey}[2][]
3215 {\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}}
3216
3217 }% not doc
3218 % \end{macrocode}
3219 % \end{macro}
3220 %
3221 %
3222 % \begin{macro}{\DescribeObject} \oarg{category} \marg{name}
3223 %
3224 % May be used to describe an arbitrary piece of code.
3225 % Creates a margin tag and index entries with \cs{ttfamily}.
3226 %
3227 % \changes{v1.01}{2019/01/20}{Put margin tag category in brackets.}
3228 % \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
3229 % \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
3230 % \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
3231 % \begin{macrocode}
3232 \IfPackageLoadedTF{doc}{% doc
3233
3234 \NewDocElement[
3235 macrolike=false,
3236 toplevel=true,
3237 idxtype=object,
3238 idxgroup=Objects,
3239 printtype=,
3240 ]{Object}{object}
3241
3242 }{% not doc
3243
3244 \newcommand*{\DescribeObject}[2][]{%
3245 \@ifundefined{@captype}{% not float?
3246 \@bsphack%
3247 \leavevmode%
3248 \marginpar{%
3249 \hbadness=10000%
3250 \hfuzz=5em%
3251 \raggedleft%
3252 \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
3253 \texttt{#2}%
3254 }%
3255 }{}% not float?
3256 \ifblank{#1}%
3257 {%
3258 \begingroup%
3259 \DTXD@origwrindex{%
3260 #2\actualchar{\protect\ttfamily#2}%
3261 \encapchar usage%
3262 }%
3263 }%
3264 {%
3265 \begingroup%
3266 \DTXD@origwrindex{%
3267 #2\actualchar{\protect\ttfamily#2} [#1]%
3268 \encapchar usage%
3269 }%
3270 \begingroup%
3271 \DTXD@origwrindex{%
3272 #1\actualchar[#1]:\levelchar#2\actualchar{\protect\ttfamily#2}%
3273 \encapchar usage%
3274 }%
3275 }%
3276 \@esphack%
3277 \ignorespaces%
3278 }
3279
3280 }% not doc
3281 % \end{macrocode}
3282 % \end{macro}
3283 %
3284 % \begin{macro}{\DescribeOther} \oarg{category} \marg{name}
3285 %
3286 % May be used to describe an arbitrary non-programming object.
3287 % Creates a margin tag and index entries with roman type.
3288 % \changes{v1.01}{2019/01/20}{Put margin tag category in brackets.}
3289 % \changes{v1.02}{2019/07/14}{Added \cs{ignorespaces}.}
3290 % \changes{v1.02}{2019/07/16}{\cs{raggedleft} margin par.}
3291 % \changes{v1.03}{2022/01/08}{Reduce hbox warnings.}
3292 % \begin{macrocode}
3293 \IfPackageLoadedTF{doc}{% doc
3294
3295 \NewDocElement[
3296 macrolike=false,
3297 toplevel=true,
3298 idxtype=other,
3299 idxgroup=Other,
3300 printtype=,
3301 ]{Other}{other}
3302
3303 }{% not doc
3304
3305 \newcommand*{\DescribeOther}[2][]{%
3306 \@ifundefined{@captype}{% not float?
3307 \@bsphack%
3308 \leavevmode%
3309 \marginpar{%
3310 \hbadness=10000%
3311 \hfuzz=5em%
3312 \raggedleft%
3313 \ifblank{#1}{}{\raggedleft{\scriptsize[#1]} }%
3314 #2%
3315 }%
3316 }{}% not float?
3317 \ifblank{#1}%
3318 {%
3319 \begingroup%
3320 \DTXD@origwrindex{#2\encapchar usage}%
3321 }%
3322 {%
3323 \begingroup%
3324 \DTXD@origwrindex{#2 [#1]\encapchar usage}%
3325 \begingroup%
3326 \DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
3327 }%
3328 \@esphack%
3329 \ignorespaces%
3330 }
3331
3332 }% not doc
3333 % \end{macrocode}
3334 % \end{macro}
3335
3336
3337 % \subsection{\cs{DescribeDefault}}
3338
3339 % \begin{macro}{\DescribeDefaultcolor}
3340 % The color of the margin tag used to show the default value.
3341 %
3342 % \changes{v1.00}{2019/01/09}{Added.}
3343 % \begin{macrocode}
3344 \newcommand*{\DescribeDefaultcolor}{green!50!black}
3345 % \end{macrocode}
3346 % \end{macro}
3347
3348
3349
3350 % \begin{macro}{\DescribeDefault} \marg{value}
3351 %
3352 % Creates a colored margin tag showing the booleandefault value.
3353 %
3354 % \changes{v1.00}{2019/01/09}{Added.}
3355 % \begin{macrocode}
3356 \newcommand{\DescribeDefault}[1]{%
3357 \margintag{%
3358 \footnotesize%
3359 \textcolor{\DescribeDefaultcolor}{%
3360 Default: \texttt{#1}%
3361 }%
3362 }%
3363 }
3364 % \end{macrocode}
3365 % \end{macro}
3366
3367
3368
3369 % \subsection{\cs{ItemDescribeMacro}, etc.}
3370 %
3371 % The following are for use inside a \env{description}.
3372 %
3373 % \begin{macro}{\ItemDescribeMacro} \oarg{category} \marg{\cs{name}}
3374 % \changes{v1.00}{2019/01/09}{Added.}
3375 % \begin{macrocode}
3376 \newcommand{\ItemDescribeMacro}[2][]{%
3377 \item[\cmd{#2}:]%
3378 \setlength{\parskip}{1.5ex}%
3379 \DescribeMacro[#1]{#2}%
3380 }
3381 % \end{macrocode}
3382 % \end{macro}
3383
3384 % \begin{macro}{\ItemDescribeEnv} \oarg{category} \marg{name}
3385 % \changes{v1.00}{2019/01/09}{Added.}
3386 % \begin{macrocode}
3387 \newcommand{\ItemDescribeEnv}[2][]{%
3388 \item[\env{#2}:]%
3389 \setlength{\parskip}{1.5ex}%
3390 \DescribeEnv[#1]{#2}%
3391 }
3392 % \end{macrocode}
3393 % \end{macro}
3394
3395 % \begin{macro}{\ItemDescribeArgument} \oarg{category} \marg{argument}
3396 % \changes{v1.00}{2019/01/09}{Added.}
3397 % \begin{macrocode}
3398 \newcommand{\ItemDescribeArgument}[2][]{%
3399 \item[\texttt{#2}:]%
3400 \setlength{\parskip}{1.5ex}%
3401 \DescribeArgument[#1]{#2}%
3402 }
3403 % \end{macrocode}
3404 % \end{macro}
3405
3406 % \begin{macro}{\ItemDescribeBoolean} \oarg{category} \marg{name}
3407 % \changes{v1.00}{2019/01/09}{Added.}
3408 % \begin{macrocode}
3409 \newcommand{\ItemDescribeBoolean}[2][]{%
3410 \item[\texttt{#2}:]%
3411 \setlength{\parskip}{1.5ex}%
3412 \DescribeBoolean[#1]{#2}%
3413 }
3414 % \end{macrocode}
3415 % \end{macro}
3416
3417 % \begin{macro}{\ItemDescribeLength} \oarg{category} \marg{name}
3418 % \changes{v1.00}{2019/01/09}{Added.}
3419 % \begin{macrocode}
3420 \newcommand{\ItemDescribeLength}[2][]{%
3421 \item[\cmd{#2}:]%
3422 \setlength{\parskip}{1.5ex}%
3423 \DescribeLength[#1]{#2}%
3424 }
3425 % \end{macrocode}
3426 % \end{macro}
3427
3428 % \begin{macro}{\ItemDescribeCounter} \oarg{category} \marg{name}
3429 % \changes{v1.00}{2019/01/09}{Added.}
3430 % \begin{macrocode}
3431 \newcommand{\ItemDescribeCounter}[2][]{%
3432 \item[\texttt{#2}:]%
3433 \setlength{\parskip}{1.5ex}%
3434 \DescribeCounter[#1]{#2}%
3435 }
3436 % \end{macrocode}
3437 % \end{macro}
3438
3439 % \begin{macro}{\ItemDescribeHook} \oarg{category} \marg{name}
3440 % \changes{v1.03}{2021/12/18}{Added.}
3441 % \begin{macrocode}
3442 \newcommand{\ItemDescribeHook}[2][]{%
3443 \item[\texttt{#2}:]%
3444 \setlength{\parskip}{1.5ex}%
3445 \DescribeHook[#1]{#2}%
3446 }
3447 % \end{macrocode}
3448 % \end{macro}
3449
3450 % \begin{macro}{\ItemDescribeSocket} \oarg{category} \marg{name}
3451 % \changes{v1.08}{2024/01/08}{Added.}
3452 % \begin{macrocode}
3453 \newcommand{\ItemDescribeSocket}[2][]{%
3454 \item[\texttt{#2}:]%
3455 \setlength{\parskip}{1.5ex}%
3456 \DescribeSocket[#1]{#2}%
3457 }
3458 % \end{macrocode}
3459 % \end{macro}
3460
3461 % \begin{macro}{\ItemDescribePlug} \oarg{category} \marg{name}
3462 % \changes{v1.08}{2024/01/08}{Added.}
3463 % \begin{macrocode}
3464 \newcommand{\ItemDescribePlug}[2][]{%
3465 \item[\texttt{#2}:]%
3466 \setlength{\parskip}{1.5ex}%
3467 \DescribePlug[#1]{#2}%
3468 }
3469 % \end{macrocode}
3470 % \end{macro}
3471
3472 % \begin{macro}{\ItemDescribeKey} \oarg{category} \marg{name}
3473 % \changes{v1.00}{2019/01/09}{Added.}
3474 % \begin{macrocode}
3475 \newcommand{\ItemDescribeKey}[2][]{%
3476 \item[\texttt{#2}:]%
3477 \setlength{\parskip}{1.5ex}%
3478 \DescribeKey[#1]{#2}%
3479 }
3480 % \end{macrocode}
3481 % \end{macro}
3482
3483 % \begin{macro}{\ItemDescribePackage} \oarg{category} \marg{name}
3484 % \changes{v1.00}{2019/01/09}{Added.}
3485 % \begin{macrocode}
3486 \newcommand{\DTXD@ItemDescribePackage}[2][]{%
3487 \item[\texttt{#2}:]%
3488 \setlength{\parskip}{1.5ex}%
3489 \DescribePackage[#1]{#2}%
3490 \endgroup%
3491 }
3492
3493 \newcommand{\ItemDescribePackage}{%
3494 \begingroup\catcode`\_=12 \DTXD@ItemDescribePackage%
3495 }
3496 % \end{macrocode}
3497 % \end{macro}
3498
3499 % \begin{macro}{\ItemDescribeClass} \oarg{category} \marg{name}
3500 % \changes{v1.00}{2019/01/09}{Added.}
3501 % \begin{macrocode}
3502 \newcommand{\DTXD@ItemDescribeClass}[2][]{%
3503 \item[\texttt{#2}:]%
3504 \setlength{\parskip}{1.5ex}%
3505 \DescribeClass[#1]{#2}%
3506 \endgroup%
3507 }
3508
3509 \newcommand{\ItemDescribeClass}{%
3510 \begingroup\catcode`\_=12 \DTXD@ItemDescribeClass%
3511 }
3512 % \end{macrocode}
3513 % \end{macro}
3514
3515 % \begin{macro}{\ItemDescribeOption} \oarg{category} \marg{name}
3516 % \changes{v1.00}{2019/01/09}{Added.}
3517 % \begin{macrocode}
3518 \newcommand{\ItemDescribeOption}[2][]{%
3519 \item[\texttt{#2}:]%
3520 \setlength{\parskip}{1.5ex}%
3521 \DescribeOption[#1]{#2}%
3522 }
3523 % \end{macrocode}
3524 % \end{macro}
3525
3526
3527 % \begin{macro}{\ItemDescribeFile} \oarg{category} \marg{name}
3528 % \changes{v1.00}{2019/01/09}{Added.}
3529 % \begin{macrocode}
3530 \newcommand{\DTXD@ItemDescribeFile}[2][]{%
3531 \item[\texttt{#2}:]%
3532 \setlength{\parskip}{1.5ex}%
3533 \DescribeFile[#1]{#2}%
3534 \endgroup%
3535 }
3536
3537 \newcommand{\ItemDescribeFile}{%
3538 \begingroup\catcode`\_=12 \DTXD@ItemDescribeFile%
3539 }
3540 % \end{macrocode}
3541 % \end{macro}
3542
3543 % \begin{macro}{\ItemDescribeProgram} \oarg{category} \marg{name}
3544 % \changes{v1.00}{2019/01/09}{Added.}
3545 % \begin{macrocode}
3546 \newcommand{\DTXD@ItemDescribeProgram}[2][]{%
3547 \item[\texttt{#2}:]%
3548 \setlength{\parskip}{1.5ex}%
3549 \DescribeProgram[#1]{#2}%
3550 \endgroup%
3551 }
3552
3553 \newcommand{\ItemDescribeProgram}{%
3554 \begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram%
3555 }
3556 % \end{macrocode}
3557 % \end{macro}
3558
3559 % \begin{macro}{\ItemDescribeCommand} \oarg{category} \marg{name}
3560 % \changes{v1.00}{2019/01/09}{Added.}
3561 % \begin{macrocode}
3562 \newcommand{\DTXD@ItemDescribeCommand}[2][]{%
3563 \item[\texttt{#2}:]%
3564 \setlength{\parskip}{1.5ex}%
3565 \DescribeCommand[#1]{#2}%
3566 \endgroup%
3567 }
3568
3569 \newcommand{\ItemDescribeCommand}{%
3570 \begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand%
3571 }
3572 % \end{macrocode}
3573 % \end{macro}
3574
3575 % \begin{macro}{\ItemDescribeObject} \oarg{category} \marg{name}
3576 % \changes{v1.00}{2019/01/09}{Added.}
3577 % \begin{macrocode}
3578 \newcommand{\ItemDescribeObject}[2][]{%
3579 \item[\texttt{#2}:]%
3580 \setlength{\parskip}{1.5ex}%
3581 \DescribeObject[#1]{#2}%
3582 }
3583 % \end{macrocode}
3584 % \end{macro}
3585
3586 % \begin{macro}{\ItemDescribeOther} \oarg{category} \marg{name}
3587 % \changes{v1.00}{2019/01/09}{Added.}
3588 % \begin{macrocode}
3589 \newcommand{\ItemDescribeOther}[2][]{%
3590 \item[\texttt{#2}:]%
3591 \setlength{\parskip}{1.5ex}%
3592 \DescribeOther[#1]{#2}%
3593 }
3594 % \end{macrocode}
3595 % \end{macro}
3596
3597
3598
3599
3600
3601
3602 % \subsection{\cs{margintag}, \cs{watchout}}
3603
3604
3605 % \begin{macro}{\margintagcolor}
3606 % The color of the \cs{margintag}.
3607 %
3608 % \changes{v1.00}{2019/01/09}{Added.}
3609 % \begin{macrocode}
3610 \newcommand*{\margintagcolor}{blue!70!black}
3611 % \end{macrocode}
3612 % \end{macro}
3613
3614
3615 % \begin{macro}{\margintag} \marg{text}
3616 %
3617 % Prints a colored margin tag.
3618 %
3619 % \changes{v1.00}{2019/01/09}{Uses \cs{margintacolor}.}
3620 % \begin{macrocode}
3621 \newcommand{\margintag}[1]{%
3622 \@ifundefined{@captype}{% not float?
3623 \marginpar{\raggedleft\textcolor{\margintagcolor}{#1}}%
3624 \ignorespaces%
3625 }{}% not float?
3626 }
3627 % \end{macrocode}
3628 % \end{macro}
3629
3630
3631 % \begin{macro}{\watchoutcolor}
3632 % The color of the \cs{watchout}.
3633 %
3634 % \changes{v1.00}{2019/01/09}{Added.}
3635 % \begin{macrocode}
3636 \newcommand*{\watchoutcolor}{red!50!black}
3637 % \end{macrocode}
3638 % \end{macro}
3639
3640
3641 % \begin{macro}{\watchout} \oarg{text}
3642 %
3643 % Prints a warning sign and optional text.
3644 %
3645 % \changes{v0.11}{2018/03/30}{Changed to \cs{raggedleft}.}
3646 % \begin{macrocode}
3647 \newcommand{\watchout}[1][]{%
3648 \@ifundefined{@captype}{% not float?
3649 \marginpar{%
3650 \raggedleft%
3651 \textcolor{\watchoutcolor}{\warningsign\normalsize\quad#1}%
3652 }%
3653 \ignorespaces%
3654 }{}% not float?
3655 }
3656 % \end{macrocode}
3657 % \end{macro}
3658
3659
3660 % \subsection{Nesting}
3661 %
3662 % Shows a box enclosing a label for the container, and the container's contents.
3663 % May be nested.
3664 %
3665 % \begin{macro}{\shownesting}
3666 % \oarg{fraction of \cs{linewidth}} \marg{container} \marg{contents}
3667 % \changes{v1.03}{2021/09/01}{Added.}
3668 % \begin{macrocode}
3669 \NewDocumentCommand{\shownesting}{s O{1} m m}{
3670 \IfBooleanF{#1}{
3671 \par\smallskip
3672 }
3673 \fbox{
3674 \begin{minipage}{#2\linewidth-2em}
3675 \hbadness=10000\relax%
3676 #3\par\smallskip
3677 \hspace{1em}
3678 \begin{minipage}{\linewidth-1.5em}
3679 #4
3680 \end{minipage}
3681 \end{minipage}
3682 }
3683 }
3684 % \end{macrocode}
3685 % \end{macro}
3686
3687
3688
3689 % \subsection{The \env{dtxexample} environment}
3690 %
3691 % Also see \cref{ex:dtxexample} on \cpageref{ex:dtxexample}.
3692 %
3693 % \DescribeFile{dtxexample_cut.tex} Used to store the \cs{input} example code.
3694 % \changes{v1.00}{2019/01/11}{Cut file name changed to \filenm{dtxexample_cut.tex}}
3695 %
3696 % \DescribeObject[color]{DTXD@examplerulecolor} The color of the middle rule in the dtxexample.
3697 % \begin{macrocode}
3698 \definecolor{DTXD@examplerulecolor}{rgb}{.9,.9,.9}
3699 % \end{macrocode}
3700 %
3701 % \begin{macro}{\dtxexamplecodename} The text name of the code section.
3702 % \changes{v1.00}{2019/01/11}{Added.}
3703 % \begin{macrocode}
3704 \newcommand*{\dtxexamplecodename}{Code:}
3705 % \end{macrocode}
3706 % \end{macro}
3707
3708 % \begin{macro}{\dtxexampleresultname} The text name of the result section.
3709 % \changes{v1.00}{2019/01/11}{Added.}
3710 % \begin{macrocode}
3711 \newcommand*{\dtxexampleresultname}{Result:}
3712 % \end{macrocode}
3713 % \end{macro}
3714
3715 % \begin{environment}{dtxexample} * \oarg{notes/cross-references} \marg{caption \& label}
3716 %
3717 % Reads the code listing as a verbatim input using
3718 % the \pkg{fancybox} package, then displays the code listing
3719 % as a verbatim output, and also executes the code
3720 % and displays the result.
3721 % A title caption is specified,
3722 % along with optional cross-referencing commands or notes to
3723 % refer to the results.
3724 % The unstarred version places the code inside a minipage, forbidding a page break in the
3725 % middle of the code listing.
3726 % The starred version does not use a minipage. This is required when the code is too large
3727 % to fit on a single page.
3728 %
3729 % \changes{v1.02}{2019/07/16}{Fix if not \pkg{doc} package.}
3730 % \begin{macrocode}
3731 \NewDocumentEnvironment{dtxexample}{s +O{} m}
3732 {% start dtxexample
3733 % \end{macrocode}
3734 %
3735 % Copy the environment's contents to the file |dtxexample_cut.tex|:
3736 % \begin{macrocode}
3737 \VerbatimOut[gobble=\DTXD@gobble,tabsize=4]{dtxexample_cut.tex}%
3738 }% start dtxexample
3739 % \end{macrocode}
3740 %
3741 % When the environment closes:
3742 % \begin{macrocode}
3743 {% end dtxexample
3744 % \end{macrocode}
3745 %
3746 % Finish the verbatim output:
3747 % \begin{macrocode}
3748 \endVerbatimOut
3749 \par
3750 \addvspace{\bigskipamount}
3751 % \end{macrocode}
3752 %
3753 % If unstarred, typeset the example in a minipage, else use a float:
3754 % \begin{macrocode}
3755 \IfBooleanTF{#1}%
3756 {% minipage
3757 \minipage{\linewidth}%
3758 \captionsetup{type=dtxexamplefloat}%
3759 }%
3760 {% float
3761 \begin{dtxexamplefloat}%
3762 }%
3763 % \end{macrocode}
3764 % \begin{macrocode}
3765 \hrule\medskip
3766 \caption{#3}
3767 % \end{macrocode}
3768 %
3769 % Typeset the contents as verbatim:
3770 % \begin{macrocode}
3771 \textcolor{DTXD@examplerulecolor}{\smallskip\hrule}
3772 \smallskip
3773 {\scriptsize\itshape\dtxexamplecodename}
3774 \VerbatimInput[tabsize=4]{dtxexample_cut.tex}
3775 \unskip
3776 \textcolor{DTXD@examplerulecolor}{\hrule}
3777 \smallskip
3778 {\scriptsize\itshape\dtxexampleresultname}
3779
3780 % \end{macrocode}
3781 %
3782 % Possible add the optional cross-references or notes:
3783 % \begin{macrocode}
3784 \ifstrempty{#2}
3785 {}
3786 {{\itshape\small #2}}
3787 % \end{macrocode}
3788 %
3789 % If unstarred, close the float or \cs{minipage}.
3790 % \begin{macrocode}
3791 \IfBooleanTF{#1}%
3792 {\endminipage}%
3793 {\end{dtxexamplefloat}}%
3794 } % end dtxexample
3795 % \end{macrocode}
3796 % \end{environment}
3797
3798
3799 % Outside of the environment's scope, input the example to generate its output
3800 % and labels:
3801 % \begin{macrocode}
3802 \AfterEndEnvironment{dtxexample}
3803 {%
3804 % \end{macrocode}
3805 %
3806 % Execute the code:
3807 % \begin{macrocode}
3808 \par\unskip\input{dtxexample_cut.tex}%
3809 % \end{macrocode}
3810 %
3811 % Closing rule::
3812 % \begin{macrocode}
3813 \medskip\hrule%
3814 }
3815 % \end{macrocode}
3816
3817
3818 % \DescribeMacro[dtxexamplefloat]{\DeclareFloatingEnvironment}
3819 % A new float type for the examples.
3820 % \begin{macrocode}
3821 \DeclareFloatingEnvironment[
3822 fileext=lox,
3823 listname={List of Examples},
3824 name=Example,
3825 placement=hbp
3826 ]{dtxexamplefloat}
3827 % \end{macrocode}
3828
3829
3830 % \DescribeMacro[dtxexamplefloat]{\captionsetup} Caption setup for the examples.
3831 % \begin{macrocode}
3832 \captionsetup*[dtxexamplefloat]{
3833 format=hang,
3834 font=bf,
3835 justification=raggedright,
3836 singlelinecheck=false,
3837 skip=0pt,
3838 position=top,
3839 }
3840 % \end{macrocode}
3841
3842 % \DescribeMacro[dtxexamplefloat]{\crefname} Name for \pkg{cleveref}.
3843 % \cs{crefname} here is required for documents not using the doc class:
3844 % \begin{macrocode}
3845 %\AddToHook{begindocument/after}{% Before .aux file is loaded.
3846 \AtBeginDocument{
3847 \ifdef{\crefname}{
3848 \crefname{dtxexamplefloat}{example}{examples}
3849 }{}
3850 }
3851 % \end{macrocode}
3852
3853
3854
3855 % \subsection{\env{noindmacro} and \env{noindenvironment}}
3856 %
3857 %
3858 % Similar to \env{macro} and \env{environment}, but not indexed.
3859 %
3860 % \begin{environment}{noindmacro} \marg{name}
3861 % \changes{v1.00}{2019/01/09}{Added.}
3862 % \begin{macrocode}
3863 \newenvironment{noindmacro}[1]
3864 {
3865 \setlength{\parskip}{\marginparpush}
3866 \leavevmode\par\DTXD@margintag{}{\cmd{#1}}{}
3867 }
3868 {\unskip}
3869 % \end{macrocode}
3870 % \end{environment}
3871 %
3872 %
3873 % \begin{environment}{noindenvironment} \marg{name}
3874 % \changes{v1.00}{2019/01/09}{Added.}
3875 % \begin{macrocode}
3876 \newenvironment{noindenvironment}[1]
3877 {
3878 \setlength{\parskip}{\marginparpush}
3879 \leavevmode\par\DTXD@margintag{}{#1}{Env}
3880 }
3881 {\unskip}
3882 % \end{macrocode}
3883 % \end{environment}
3884 %
3885 %
3886 %
3887 % \subsection{\env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}}
3888 %
3889 % For use in a \env{sourcedisplay}:
3890 %
3891 % \begin{macro}{\fquad} Forces a quad indent.
3892 % \changes{v1.00}{2019/01/09}{Added.}
3893 % \begin{macrocode}
3894 \newcommand*{\fquad}{\hspace*{1em}}
3895 % \end{macrocode}
3896 % \end{macro}
3897
3898 % \begin{macro}{\fqquad} Forces a double-quad indent.
3899 % \changes{v1.00}{2019/01/09}{Added.}
3900 % \begin{macrocode}
3901 \newcommand*{\fqquad}{\hspace*{2em}}
3902 % \end{macrocode}
3903 % \end{macro}
3904
3905 % \begin{macro}{\fqqquad} Forces a triple-quad indent.
3906 % \changes{v1.00}{2019/01/09}{Added.}
3907 % \begin{macrocode}
3908 \newcommand*{\fqqquad}{\hspace*{3em}}
3909 % \end{macrocode}
3910 % \end{macro}
3911 %
3912 %
3913 % \begin{environment}{sourceverb}
3914 % To typeset a block of source code, verbatim.
3915 %
3916 % \changes{v1.00}{2019/01/11}{Added.}
3917 % \begin{macrocode}
3918 \DefineVerbatimEnvironment{sourceverb}{Verbatim}
3919 {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em}
3920 \BeforeBeginEnvironment{sourceverb}{\vspace*{-.5\parskip}}
3921 % \end{macrocode}
3922 % \end{environment}
3923
3924 % \begin{environment}{fsourceverb}
3925 % To typeset a framed block of source code, verbatim.
3926 %
3927 % \changes{v1.00}{2019/01/11}{Added.}
3928 % \begin{macrocode}
3929 \DefineVerbatimEnvironment{fsourceverb}{Verbatim}
3930 {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em,frame=lines}
3931 \BeforeBeginEnvironment{fsourceverb}{\vspace*{-.5\parskip}}
3932 % \end{macrocode}
3933 % \end{environment}
3934
3935
3936 % \begin{environment}{sourcedisplay}
3937 % To typeset a block of source code, allowing direct formatting.
3938 %
3939 % \changes{v1.00}{2019/01/09}{Added.}
3940 % \changes{v1.01}{2019/01/20}{Reduced width.}
3941 % \begin{macrocode}
3942 \newenvironment{sourcedisplay}
3943 {
3944 \leavevmode
3945 \par
3946 \fqquad\minipage{\linewidth-4em}
3947 \ttfamily
3948 }
3949 {%
3950 \endminipage
3951 \par
3952 }
3953 % \end{macrocode}
3954 % \end{environment}
3955
3956
3957 % \begin{environment}{UIdisplay}
3958 % To typeset a user interface display.
3959 %
3960 % \changes{v1.00}{2019/01/09}{Added.}
3961 % \changes{v1.01}{2019/01/20}{Reduced width.}
3962 % \begin{macrocode}
3963 \newenvironment{UIdisplay}
3964 {
3965 \leavevmode
3966 \par
3967 \fqquad\minipage{\linewidth-4em}
3968 \sffamily\bfseries
3969 }
3970 {
3971 \endminipage
3972 \par
3973 }
3974 % \end{macrocode}
3975 % \end{environment}
3976
3977
3978 % \begin{macro}{\userentryname}
3979 % Text to tell the user to enter the following item.
3980 % \changes{v1.00}{2019/01/09}{Added.}
3981 % \begin{macrocode}
3982 \newcommand*{\userentryname}{Enter~$\Rightarrow$}
3983 % \end{macrocode}
3984 % \end{macro}
3985
3986
3987 % \begin{macro}{\userentry} \marg{text to enter}
3988 %
3989 % Typesets text to be entered by the users.
3990 % \changes{v1.00}{2019/01/09}{Added.}
3991 % \begin{macrocode}
3992 \newcommand{\userentry}[1]{%
3993 \par
3994 \fqquad%
3995 \begin{minipage}{\linewidth-2em}
3996 {\footnotesize \userentryname}\quad\cmds{#1}
3997 \end{minipage}
3998 \par
3999 }
4000 % \end{macrocode}
4001 % \end{macro}
4002
4003
4004
4005 % \begin{environment}{docsidebar}
4006 % To typeset a sidebar in the documentation.
4007 %
4008 % \changes{v1.00}{2019/01/09}{Added.}
4009 % \begin{macrocode}
4010 \newenvironment{docsidebar}[1][]
4011 {%
4012 \quote\unskip\medskip
4013 \setlength{\parskip}{1.5ex}%
4014 \ifblank{#1}{}{\textit{#1}\newline}%
4015 \rule[.5\bigskipamount]{\linewidth}{.4pt}%
4016 \newline%
4017 }
4018 {%
4019 \leavevmode\par
4020 \rule[\bigskipamount]{\linewidth}{.4pt}
4021 \endquote\unskip
4022 }
4023 % \end{macrocode}
4024 % \end{environment}
4025 %
4026 %
4027 %
4028 % \subsection{Formatted objects}
4029 %
4030 % Macros to format references to various kinds of objects.
4031 %
4032 % \changes{v1.00}{2019/01/11}{Added formatted objects.}
4033 %
4034 % \subsubsection{\LaTeX\ objects}
4035 %
4036 % \begin{macro}{\pkg} \marg{name} \quad Also useable for class names.
4037 % \begin{macrocode}
4038 \providerobustcmd*{\pkg}[1]{\mbox{\textsf{#1}}}
4039 % \end{macrocode}
4040 % \end{macro}
4041
4042 % \begin{macro}{\cs} \marg{csname} \quad From \pkg{ltxdoc}.
4043 % \changes{v1.03}{2021/09/02}{Provided.}
4044 % \begin{macrocode}
4045 \providerobustcmd*{\cs}[1]{\texttt{\char`\\#1}}
4046 % \end{macrocode}
4047 % \end{macro}
4048
4049 % \begin{macro}{\env} \marg{name}
4050 % \begin{macrocode}
4051 \providerobustcmd*{\env}[1]{\mbox{\texttt{#1}}}
4052 % \end{macrocode}
4053 % \end{macro}
4054
4055 % \begin{macro}{\marg} \marg{argument} \quad From \pkg{ltxdoc}.
4056 % \changes{v1.03}{2021/09/02}{Provided.}
4057 % \begin{macrocode}
4058 \providecommand\marg[1]{%
4059 {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
4060 % \end{macrocode}
4061 % \end{macro}
4062
4063 % \begin{macro}{\oarg} \oarg{argument} \quad From \pkg{ltxdoc}.
4064 % \changes{v1.03}{2021/09/02}{Provided.}
4065 % \begin{macrocode}
4066 \providecommand\oarg[1]{%
4067 {\ttfamily[}\meta{#1}{\ttfamily]}}
4068 % \end{macrocode}
4069 % \end{macro}
4070
4071 % \begin{macro}{\parg} \parg{argument} \quad From \pkg{ltxdoc}.
4072 % \changes{v1.03}{2021/09/02}{Provided.}
4073 % \begin{macrocode}
4074 \providecommand\parg[1]{%
4075 {\ttfamily(}\meta{#1}{\ttfamily)}}
4076 % \end{macrocode}
4077 % \end{macro}
4078
4079 % \begin{macro}{\ctr} \marg{name}
4080 % \begin{macrocode}
4081 \providerobustcmd*{\ctr}[1]{\mbox{\texttt{#1}}}
4082 % \end{macrocode}
4083 % \end{macro}
4084
4085 % \begin{macro}{\bool} \marg{name}
4086 % \begin{macrocode}
4087 \providerobustcmd*{\bool}[1]{\mbox{\texttt{#1}}}
4088 % \end{macrocode}
4089 % \end{macro}
4090
4091 % \begin{macro}{\optn} \marg{name}
4092 % \begin{macrocode}
4093 \providerobustcmd*{\optn}[1]{\mbox{\texttt{#1}}}
4094 % \end{macrocode}
4095 % \end{macro}
4096
4097 % \begin{macro}{\TOC}
4098 % \begin{macrocode}
4099 \providerobustcmd*{\TOC}{\acro{TOC}}
4100 % \end{macrocode}
4101 % \end{macro}
4102
4103 % \begin{macro}{\LOF}
4104 % \begin{macrocode}
4105 \providerobustcmd*{\LOF}{\acro{LOF}}
4106 % \end{macrocode}
4107 % \end{macro}
4108
4109 % \begin{macro}{\LOT}
4110 % \begin{macrocode}
4111 \providerobustcmd*{\LOT}{\acro{LOT}}
4112 % \end{macrocode}
4113 % \end{macro}
4114
4115
4116 % \subsubsection{Programs and commands}
4117
4118 % \begin{macro}{\cmds} \marg{commands to print}
4119 % \quad No processing is provided for special characters.
4120 % \begin{macrocode}
4121 \providerobustcmd*{\cmds}[1]{\mbox{\textbf{\texttt{#1}}}}
4122 % \end{macrocode}
4123 % \end{macro}
4124
4125 % \begin{macro}{\progcode} \marg{code to print}
4126 % \quad No processing is provided for special characters.
4127 % \begin{macrocode}
4128 \providerobustcmd*{\progcode}[1]{\mbox{\texttt{#1}}}
4129 % \end{macrocode}
4130 % \end{macro}
4131
4132 % \begin{macro}{\prog} \marg{program name} \quad Underscores are allowed.
4133 % \begin{macrocode}
4134 \newcommand*{\DTXD@prog}[1]{%
4135 \mbox{\textsf{\textsl{\detokenize{#1}}}}%
4136 \endgroup%
4137 }
4138
4139 \providerobustcmd*{\prog}{%
4140 \begingroup%
4141 \catcode`\_=12%
4142 \DTXD@prog%
4143 }
4144 % \end{macrocode}
4145 % \end{macro}
4146
4147 % \begin{macro}{\filenm} \marg{file name} \quad Underscores are allowed.
4148 % \begin{macrocode}
4149 \newcommand*{\DTXD@filenm}[1]{%
4150 \mbox{\texttt{\detokenize{#1}}}%
4151 \endgroup%
4152 }
4153
4154 \providerobustcmd*{\filenm}{%
4155 \begingroup%
4156 \catcode`\_=12%
4157 \DTXD@filenm%
4158 }
4159 % \end{macrocode}
4160 % \end{macro}
4161
4162 % \begin{macro}{\UI} General user-interface text.
4163 % \begin{macrocode}
4164 \providerobustcmd*{\UI}[1]{\textbf{\textsf{#1}}}
4165 % \end{macrocode}
4166 % \end{macro}
4167 %
4168 %
4169 % \subsubsection{File types}
4170 %
4171 % \begin{macro}{\ODT}
4172 % \begin{macrocode}
4173 \providerobustcmd*{\ODT}{\acro{ODT}}
4174 % \end{macrocode}
4175 % \end{macro}
4176
4177 % \begin{macro}{\SVG}
4178 % \begin{macrocode}
4179 \providerobustcmd*{\SVG}{\acro{SVG}}
4180 % \end{macrocode}
4181 % \end{macro}
4182
4183 % \begin{macro}{\PNG}
4184 % \begin{macrocode}
4185 \providerobustcmd*{\PNG}{\acro{PNG}}
4186 % \end{macrocode}
4187 % \end{macro}
4188
4189 % \begin{macro}{\GIF}
4190 % \begin{macrocode}
4191 \providerobustcmd*{\GIF}{\acro{GIF}}
4192 % \end{macrocode}
4193 % \end{macro}
4194
4195 % \begin{macro}{\JPG}
4196 % \begin{macrocode}
4197 \providerobustcmd*{\JPG}{\acro{JPG}}
4198 % \end{macrocode}
4199 % \end{macro}
4200
4201 % \begin{macro}{\EPS}
4202 % \begin{macrocode}
4203 \providerobustcmd*{\EPS}{\acro{EPS}}
4204 % \end{macrocode}
4205 % \end{macro}
4206
4207 % \begin{macro}{\PDF}
4208 % \begin{macrocode}
4209 \providerobustcmd*{\PDF}{\acro{PDF}}
4210 % \end{macrocode}
4211 % \end{macro}
4212
4213 % \begin{macro}{\DVI}
4214 % \begin{macrocode}
4215 \providerobustcmd*{\DVI}{\acro{DVI}}
4216 % \end{macrocode}
4217 % \end{macro}
4218 %
4219 %
4220 % \subsubsection{Internet}
4221 %
4222 % \begin{macro}{\UTF}
4223 % \begin{macrocode}
4224 \providerobustcmd*{\UTF}{\acro{UTF}}
4225 % \end{macrocode}
4226 % \end{macro}
4227
4228 % \begin{macro}{\URL}
4229 % \begin{macrocode}
4230 \providerobustcmd*{\URL}{\acro{URL}}
4231 % \end{macrocode}
4232 % \end{macro}
4233
4234 % \begin{macro}{\element} \marg{name}
4235 % \begin{macrocode}
4236 \providerobustcmd*{\element}[1]{\texttt{<#1>}}
4237 % \end{macrocode}
4238 % \end{macro}
4239
4240 % \begin{macro}{\attribute} \marg{name}
4241 % \begin{macro}{\attrib} \marg{name}
4242 %
4243 % Each of these is ``provided'', and any prior meaning will
4244 % be unchanged.
4245 % In particular, \LuaTeX\ uses \cs{attribute}, so its meaning
4246 % is unchanged if using \LuaTeX.
4247 % \changes{v1.03}{2021/09/01}{For \LuaTeX.}
4248 % \begin{macrocode}
4249 \providerobustcmd*{\attrib}[1]{\mbox{\texttt{#1}}}
4250
4251 \providerobustcmd*{\attribute}[1]{\mbox{\texttt{#1}}}
4252 % \end{macrocode}
4253 % \end{macro}
4254 % \end{macro}
4255
4256 % \begin{macro}{\HTML}
4257 % \begin{macrocode}
4258 \providerobustcmd*{\HTML}{\acro{HTML}}
4259 % \end{macrocode}
4260 % \end{macro}
4261
4262 % \begin{macro}{\HTMLfive}
4263 % \begin{macrocode}
4264 \providerobustcmd*{\HTMLfive}{\HTML\textsc{5}}
4265 % \end{macrocode}
4266 % \end{macro}
4267
4268 % \begin{macro}{\CSS}
4269 % \begin{macrocode}
4270 \providerobustcmd*{\CSS}{\acro{CSS}}
4271 % \end{macrocode}
4272 % \end{macro}
4273
4274 % \begin{macro}{\CSSthree}
4275 % \begin{macrocode}
4276 \providerobustcmd*{\CSSthree}{\CSS\textsc{3}}
4277 % \end{macrocode}
4278 % \end{macro}
4279
4280 % \begin{macro}{\EPUB}
4281 % \begin{macrocode}
4282 \providerobustcmd*{\EPUB}{\acro{EPUB}}
4283 % \end{macrocode}
4284 % \end{macro}
4285 %
4286 %
4287 % \subsubsection{Specific programs}
4288 %
4289 % \begin{macro}{\TikZ}
4290 % \changes{v1.05}{2022/09/08}{Renamed from \cs{tikz}, cap Z.}
4291 % \begin{macrocode}
4292 \providerobustcmd*{\TikZ}{Ti\emph{k}Z}
4293 % \end{macrocode}
4294 % \end{macro}
4295
4296 % \begin{macro}{\CTAN}
4297 % \begin{macrocode}
4298 \providerobustcmd*{\CTAN}{\acro{CTAN}}
4299 % \end{macrocode}
4300 % \end{macro}
4301
4302 % \begin{macro}{\TDS}
4303 % \begin{macrocode}
4304 \providerobustcmd*{\TDS}{\acro{TDS}}
4305 % \end{macrocode}
4306 % \end{macro}
4307 %
4308 % \begin{macro}{\MathML}
4309 % \begin{macrocode}
4310 \providerobustcmd*{\MathML}{Math\acro{ML}}
4311 % \end{macrocode}
4312 % \end{macro}
4313 %
4314 % \begin{macro}{\MathJax}
4315 % \changes{v1.03}{2021/09/02}{Added.}
4316 % \begin{macrocode}
4317 \providerobustcmd*{\MathJax}{\brand{MathJax}}
4318 % \end{macrocode}
4319 % \end{macro}
4320 %
4321 %
4322 % \subsubsection{Acronyms, brand names, trademarks}
4323 %
4324 % \begin{macro}{\brand} \marg{name}
4325 % \begin{macrocode}
4326 \providerobustcmd*{\brand}[1]{\textsc{#1}}
4327 % \end{macrocode}
4328 % \end{macro}
4329
4330 % \begin{macro}{\acro} \marg{acronym}
4331 % \begin{macrocode}
4332 \providerobustcmd*{\acro}[1]{\textsc{\lowercase{#1}}}
4333 % \end{macrocode}
4334 % \end{macro}
4335
4336 % \begin{macro}{\supregistered} Superscript trademark symbol.
4337 % \begin{macrocode}
4338 \providerobustcmd*{\supregistered}{\textsuperscript{\textregistered}}
4339 % \end{macrocode}
4340 % \end{macro}
4341 %
4342 %
4343 %
4344 %
4345 % \subsection{Logos}
4346 %
4347 % \changes{v1.00}{2019/01/11}{Added logos.}
4348 %
4349 % \begin{macro}{\dviTeX} \dviTeX
4350 % \changes{v1.03}{2021/09/02}{Added.}
4351 % \begin{macrocode}
4352 \providerobustcmd*{\dviTeX}{\mbox{\DVI\,\TeX}}
4353 % \end{macrocode}
4354 % \end{macro}
4355 %
4356 % \begin{macro}{\dviLaTeX} \dviLaTeX
4357 % \changes{v1.03}{2021/09/02}{Added.}
4358 % \begin{macrocode}
4359 \providerobustcmd*{\dviLaTeX}{\mbox{\DVI\,\LaTeX}}
4360 % \end{macrocode}
4361 % \end{macro}
4362 %
4363 % \begin{macro}{\pdfTeX} \pdfTeX
4364 % \changes{v1.03}{2021/09/02}{Added.}
4365 % \begin{macrocode}
4366 \providerobustcmd*{\pdfTeX}{\mbox{\PDF\,\TeX}}
4367 % \end{macrocode}
4368 % \end{macro}
4369 %
4370 % \begin{macro}{\pdfLaTeX} \pdfLaTeX
4371 % \changes{v1.03}{2021/09/02}{Added.}
4372 % \begin{macrocode}
4373 \providerobustcmd*{\pdfLaTeX}{\mbox{\PDF\,\LaTeX}}
4374 % \end{macrocode}
4375 % \end{macro}
4376 %
4377 % \begin{macro}{\LuaTeX} \LuaTeX
4378 % \begin{macrocode}
4379 \providerobustcmd*{\LuaTeX}{\mbox{Lua\TeX}}
4380 % \end{macrocode}
4381 % \end{macro}
4382 %
4383 % \begin{macro}{\LuaLaTeX} \LuaLaTeX
4384 % \begin{macrocode}
4385 \providerobustcmd*{\LuaLaTeX}{\mbox{Lua\LaTeX}}
4386 % \end{macrocode}
4387 % \end{macro}
4388 %
4389 % \begin{macro}{\XeTeX}
4390 % \begin{macro}{\XeLaTeX} \XeTeX, \XeLaTeX
4391 % \begin{macrocode}
4392 \providerobustcmd*{\XeTeXrevE}
4393 {\hspace{-.1667em}\raisebox{-.5ex}{E}\hspace{-.125em}}
4394
4395 \AtBeginDocument{
4396 \IfPackageLoadedTF{graphics}{
4397 \renewrobustcmd*{\XeTeXrevE}
4398 {\hspace{-.1667em}\raisebox{-.5ex}{\reflectbox{E}}\hspace{-.125em}}
4399 }{}
4400 }
4401
4402 \providerobustcmd*{\XeTeX}{\mbox{X\XeTeXrevE\TeX}}
4403 \providerobustcmd*{\XeLaTeX}{\mbox{X\XeTeXrevE\LaTeX}}
4404 % \end{macrocode}
4405 % \end{macro}
4406 % \end{macro}
4407 %
4408 % \begin{macro}{\AmS} \AmS
4409 % \begin{macrocode}
4410 \providerobustcmd*{\AmS}{%
4411 \leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex%
4412 \hbox{$\mathcal M$}\kern-.2em\mathcal S$}%
4413 }
4414 % \end{macrocode}
4415 % \end{macro}
4416 %
4417 % \begin{macro}{\LyX} \LyX
4418 % \begin{macrocode}
4419 \providerobustcmd*{\LyX}{\textsf{LyX}}
4420 % \end{macrocode}
4421 % \end{macro}
4422 %
4423 % \begin{macro}{\BibTeX} \BibTeX
4424 % \begin{macrocode}
4425 \providerobustcmd*{\BibTeX}{\mbox{B\textsc{ib}\TeX}}
4426 % \end{macrocode}
4427 % \end{macro}
4428 %
4429 % \begin{macro}{\MakeIndex} \MakeIndex
4430 % \begin{macrocode}
4431 \providerobustcmd*{\MakeIndex}{\prog{MakeIndex}}
4432 % \end{macrocode}
4433 % \end{macro}
4434 %
4435 % \begin{macro}{\ConTeXt} \ConTeXt
4436 % \begin{macrocode}
4437 \providerobustcmd*{\ConTeXt}{\mbox{Con\TeX{}t}}
4438 % \end{macrocode}
4439 % \end{macro}
4440 %
4441 % \begin{macro}{\MiKTeX} \MiKTeX
4442 % \begin{macrocode}
4443 \providerobustcmd*{\MiKTeX}{\mbox{MiK\TeX}}
4444 % \end{macrocode}
4445 % \end{macro}
4446 %
4447 %
4448 %
4449 % \subsection{Dashes and slashes}
4450 %
4451 % \begin{macro}{\thinskip} A breakable thin skip.
4452 % \begin{macrocode}
4453 \DeclareRobustCommand{\thinskip}{\hskip 0.16667em\relax}
4454 % \end{macrocode}
4455 % \end{macro}
4456 %
4457 % \begin{macro}{\endash} An endash: \endash
4458 % \begin{macrocode}
4459 \def\endash{–}
4460 % \end{macrocode}
4461 % \end{macro}
4462 %
4463 % \begin{macro}{\emdash} An emdash: \emdash
4464 % \begin{macrocode}
4465 \def\emdash{—}
4466 % \end{macrocode}
4467 % \end{macro}
4468 %
4469 % \begin{macro}{\thinbrspace} A thin space which allows a line break.
4470 % \begin{macrocode}
4471 \newcommand{\thinbrspace}{%
4472 \hspace{.16667em}\penalty\exhyphenpenalty\hspace{0pt}%
4473 }
4474 % \end{macrocode}
4475 % \end{macro}
4476 %
4477 % \begin{macro}{\thinthinbrspace} A thin space which allows a line break.
4478 % \begin{macrocode}
4479 \newcommand{\thinthinbrspace}{%
4480 \hspace{.08333em}\penalty\exhyphenpenalty\hspace{0pt}%
4481 }
4482 % \end{macrocode}
4483 % \end{macro}
4484 %
4485 % \begin{macro}{\Dash} An unbreakeable thin space, emdash, and breakable thin space.
4486 % \begin{macrocode}
4487 \newrobustcmd{\Dash}{\unskip\thinspace\emdash\thinbrspace}
4488 % \end{macrocode}
4489 % \end{macro}
4490 %
4491 % \begin{macro}{\dash} An unbreakeable thin space, endash, and breakable thin space.
4492 % \begin{macrocode}
4493 \newrobustcmd{\dash}{\unskip\thinspace\endash\thinbrspace}
4494 % \end{macrocode}
4495 % \end{macro}
4496 %
4497 % \begin{macro}{\Slash} An unbreakable very thin space, a slash, and a breakable thin space.
4498 % \begin{macrocode}
4499 \newrobustcmd{\Slash}{\unskip\hspace{.08333em}/\thinthinbrspace}
4500 % \end{macrocode}
4501 % \end{macro}
4502 %
4503 %
4504 % \clearpage
4505 %
4506 % \section{Compiling \pkg{dtxdescribe}}
4507 %
4508 % To compile the \pkg{dtxdescribe} package:
4509 % \userentry{pdflatex dtxdescribe.ins}
4510 %
4511 % To compile the \pkg{dtxdescribe} documentation
4512 % \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
4513 % \userentry{makeindex -s gglo.ist -o dtxdescribe.gls dtxdescribe.glo}
4514 % \userentry{makeindex -s gind.ist dtxdescribe}
4515 % \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
4516 %
4517 %
4518 % \iffalse
4519 %</package>
4520 % \fi
4521
4522
4523
4524
4525 % \clearpage
4526 % \pagestyle{plain}
4527 %
4528 %
4529 % \Finale
4530 %
4531 \endinput