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