% \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 %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{dtxdescribe} % [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} % % % % \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} % ... % % % \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 % % \fi % \clearpage % \pagestyle{plain} % % \renewcommand{\partname}{} % \renewcommand{\thepart}{} % \part{Change History and Index} % % % \Finale % \endinput