diff options
Diffstat (limited to 'Master/texmf-dist')
| -rw-r--r-- | Master/texmf-dist/doc/latex/dtxdescribe/README | 20 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/dtxdescribe/dtxdescribe.pdf | bin | 0 -> 620831 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx | 1771 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.ins | 47 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/dtxdescribe/dtxdescribe.sty | 385 |
5 files changed, 2223 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/dtxdescribe/README b/Master/texmf-dist/doc/latex/dtxdescribe/README new file mode 100644 index 00000000000..fa8adaa2991 --- /dev/null +++ b/Master/texmf-dist/doc/latex/dtxdescribe/README @@ -0,0 +1,20 @@ +The LaTeX dtxdescribe package +Describe additional object types in dtx source files. + +v0.10 — 2016/12/08 +Copyright 2016 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/Master/texmf-dist/doc/latex/dtxdescribe/dtxdescribe.pdf b/Master/texmf-dist/doc/latex/dtxdescribe/dtxdescribe.pdf Binary files differnew file mode 100644 index 00000000000..17ab09790b1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/dtxdescribe/dtxdescribe.pdf diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx new file mode 100644 index 00000000000..95790045699 --- /dev/null +++ b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx @@ -0,0 +1,1771 @@ + +% \iffalse meta-comment +% +% 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. +% +% \fi + +% +% \iffalse +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{dtxdescribe} +%<package> [2016/12/08 v0.10 Describe additional object types in dtx source files.] +% +%<*driver> +\documentclass{ltxdoc} + +\newcommand*{\mypackagename}{dtxdescribe} +\newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.} + + +\usepackage{lmodern} +% \usepackage{libertine} +\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} + +% widows and orphans: +\usepackage[all,defaultlines=2]{nowidow} + + +\usepackage{etoolbox} + +\usepackage[log-declarations=false]{xparse} + + + +% \usepackage{graphicx} +% \graphicspath{{images/}} + +% \usepackage{enumitem} + +% \usepackage{array} +% \usepackage{booktabs} +% \usepackage{threeparttable} + +% \usepackage{fancybox}% must be loaded before fancyvrb +% \usepackage{fancyvrb} + + + +% \captionsetup{labelfont={small,bf},textfont={small,bf}} +% +% \captionsetup*[figure]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=2ex, +% labelfont={small,bf},textfont={small,bf} +% } +% +% \captionsetup*[table]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=1ex, +% labelfont={small,bf},textfont={small,bf} +% } +% +% \captionsetup*[subfigure]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=2ex, +% labelfont={small},textfont={small} +% } +% +% \captionsetup*[subtable]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=1ex, +% labelfont={small},textfont={small} +% } +% +% \captionsetup*[example]{ +% format=plain, justification=justified, +% margin=0pt, parskip=0pt, skip=0ex, +% labelfont={bf},textfont={bf} +% } +% +% \captionsetup*[wrapfigure]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=2ex, +% labelfont={small,bf},textfont={small,bf} +% } +% +% \captionsetup*[wraptable]{ +% style=default, justification=centering, +% margin=0pt, parskip=0pt, skip=1ex, +% labelfont={small,bf},textfont={small,bf} +% } + + + +% \usepackage{lipsum} + + + +% \usepackage{tikz} +% \usetikzlibrary{positioning,fit,backgrounds,calc,shapes.geometric,shadows} +% +% \usepackage[framemethod=tikz]{mdframed} +% +% \mdfdefinestyle{boxroundshadow}{linewidth=1pt,innerleftmargin=0in,innerrightmargin=0in,% +% innertopmargin=0in,innerbottommargin=0in,% +% align=center,roundcorner=3pt,shadow=true,shadowcolor=black!50,shadowsize=4pt,% +% leftmargin=0pt,rightmargin=0pt,% +% frametitlebackgroundcolor=black!15,% +% skipabove=0ex,skipbelow=0ex,% +% frametitlerulewidth=1pt,frametitleaboveskip=5pt,% +% } +% +% \newmdenv[style=boxroundshadow,align=center]{mdtightframe} +% +% \newmdenv[style=boxroundshadow,align=center,% +% innertopmargin=3pt,innerbottommargin=3pt,% +% innerleftmargin=3pt,innerrightmargin=3pt]{mdlooseframe} + + +% \usepackage[normalem]{ulem} + + +% \usepackage{comment} +% \excludecomment{testing} + +% \usepackage{morefloats} +% \usepackage{marginfix} + +\usepackage{tocloft} +\setlength{\cftsubsecnumwidth}{3em} +\setlength{\cftsubsubsecindent}{2.8em} +\setlength{\cftsubsubsecnumwidth}{4em} +\setlength{\cftbeforesubsecskip}{1ex} + +% \usepackage{titletoc} + + + + +\usepackage{titleps} + +\newpagestyle{pageheadfoot}{ + \headrule + \sethead{\pkg{\mypackagename}}{}{\thepage} +% \renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}} + \setfoot{}{}{} +} + +\pagestyle{pageheadfoot} + + + + +\newcommand*{\lmacro}[1]{\textbackslash#1} +\newcommand*{\cmds}[1]{\texttt{#1}} +\newcommand*{\env}[1]{\texttt{#1}} +\newcommand*{\pkg}[1]{\textsf{#1}} +\newcommand*{\acro}[1]{\textsc{\lowercase{#1}}} + + + + + + + + +% % \newcommand*{\tikz}{Ti\textit{k}z} +% \newcommand*{\htmlfive}{\acro{HTML}\oldstylenums{5}} +% \newcommand*{\cssthree}{\acro{CSS}\oldstylenums{3}} +% +% \newcommand*{\goesto}{$\Rightarrow$} + +% \newenvironment{docsidebar}[1][] +% {\par\addvspace{1.5ex}% +% \hfill\minipage{.9\linewidth}\raggedright#1\smallskip\hrule\medskip} +% {\smallskip\hrule\endminipage\hspace*{\fill}\par\addvspace{1.5ex}} + + + + + +% \setlength{\marginparsep}{1em} +% \setlength{\marginparpush}{2ex} +\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{369} +% +% \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} + + + + +% \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\copyright{} 2016} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com} +% +% \vspace{.5in} +% +% {\Large \textup{\quicksummary}} +% +% +% +% ^^A % \title{The \pkg{keyfloat} package\thanks{This document +% ^^A % corresponds to \pkg{keyfloat}~\fileversion, +% ^^A % dated \filedate.}} +% ^^A % \author{{\small\copyright{} 2016} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com}} +% ^^A % \published{} +% ^^A % \subtitle{\textup{Subtitle}} +% ^^A % +% ^^A % \maketitle +% +% \vfill +% +% +% \begin{abstract} +% \noindent +% The \pkg{doc} package includes tools for describing macros and environments +% in \LaTeX\ source |dtx| format. +% The \pkg{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 \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. +% +% Descriptions are best accompanied by examples, so the +% environment \env{dtxexample} is provided. +% Contents are displayed verbatim along with a caption and cross-referencing. +% They are then \cs{input} and executed, and the result is shown. +% \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 +% 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, +% \margintag{Too much!} +% 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{verbatim} +% %<*driver> +% \documentclass{ltxdoc} +% ... +% \usepackage{lmodern} +% ... +% \usepackage{dtxdescribe} +% ... +% \usepackage{packagename} % the name of your new package +% ... +% \usepackage[...]{hyperref} +% \usepackage{...]{cleveref} +% ... +% %</driver> +% \end{verbatim} + +% 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 verisons +% 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{Pre-existing Macros} +% +% \DescribeMacro{\DescribeMacro} \oarg{class} \marg{\cs{name}} +% +% The pre-existing macro from the \pkg{doc} is redefined to +% allow hyperlinked index entries and 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 pre-existing macro from the \pkg{doc} is redefined to +% allow hyperlinked index entries, and also to place +% an `Env' tag in front of the name in the margin. +% See \cref{ex:environment} on \cpageref{ex:environment}. +% + + +% \subsection{Macro Arguments} +% +% The \cs{Describe}\rule{.25in}{.4pt} 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{Common \LaTeX\ Elements} +% +% 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{References to External Packages and Classes} +% +% \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, and 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{Additional Tags} +% +% +% \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. + +% +% \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. + + +% \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. + + + +% \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]{sampleclass} +% 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. +% \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}[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{verbatim} +% \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{verbatim} +% +% 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 |ex_cut.tex|. +% \item The code was \cs{input} from |ex_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 +% +% \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. Try to place the first one directly connected to a word, +% and the others may follow on the next line if necessary. +% \begin{verbatim} +% text text text\margintag{A comment.}\index{An entry} +% \index{Another entry} +% more inline text text text +% \end{verbatim} +% +% \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{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} + + + + +% ^^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{Support Macros} + + +% \begin{macrocode} +\renewcommand*{\PrintEnvName}[1] + {\strut{\scriptsize{}Env}\quad\MacroFont#1\ } +% \end{macrocode} + + + + +% +% \begin{macro}{\DTXD@printtype} \marg{text} +% +% Used to print the object class in the margin: +% \begin{macrocode} +\newcommand*{\DTXD@printtype}[1] + {\raggedleft\strut{\scriptsize#1}\quad\MacroFont} +% \end{macrocode} +% \end{macro} + + + + +% \begin{macro}{\usage} \marg{text} +% +% Allow hyperlinks in the ``usage'' index entries: +% \begin{macrocode} +\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. +% +% \begin{macrocode} +\newcommand*{\DTXD@margintag}[3]{% +\@ifundefined{@captype}{% not float? +\leavevmode% +\marginpar{% +\DTXD@printtype{% +#3% margintag +\ifblank{#1}{}{ \texttt{#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. +% \begin{macrocode} +\begingroup% +\DTXD@origwrindex{% +#4s:\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}. +% +% \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}{}{ \texttt{#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+ +% \begin{macrocode} +\begingroup% +\DTXD@origwrindex{% +#4s:\levelchar% index tag +\ifblank{#1}{}{[#1]:\levelchar}% class +\DTXD@verbatimcmd{#2}% name +\encapchar #5}% +\@esphack% +\ignorespaces% +} + +% \end{macrocode} +% \end{macro} +% + + +% \subsection{Pre-existing Macros} + +% \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}} +% +% Redefined to allow hyperlinked index entries and an optional class: +% \begin{macrocode} +\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#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} +\ifthenelse{\isempty{#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: +% \begin{macrocode} +\renewcommand*{\DescribeEnv}[2][] + {\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}} +% \end{macrocode} +% \end{macro} + + + + +% \subsection{New Describe 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. +% \begin{macrocode} +\DTXD@margintag{}{#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}{\DescribePackage} \oarg{class} \marg{name} +% \begin{macrocode} +\newcommand*{\DescribePackage}[2][] + {\DTXD@margintagindex{#1}{#2}{Pkg}{package}{usage}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DescribeClass} \oarg{class} \marg{name} +% \begin{macrocode} +\newcommand*{\DescribeClass}[2][] + {\DTXD@margintagindex{#1}{#2}{Cls}{class}{usage}} +% \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}. +% \begin{macrocode} +\newcommand*{\DescribeObject}[2][]{% +\@ifundefined{@captype}{% not float? +\@bsphack% +\leavevmode\marginpar{\raggedleft{\scriptsize#1} \texttt{#2}}% +}{}% not float? +\ifthenelse{\isempty{#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. +% \begin{macrocode} +\newcommand*{\DescribeOther}[2][]{% +\@ifundefined{@captype}{% not float? +\@bsphack% +\leavevmode\marginpar{\raggedleft{\scriptsize#1} #2}% +}{}% not float? +\ifthenelse{\isempty{#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{New Margin Tags} + +% \begin{macro}{\margintag} \marg{text} +% +% Prints a colored margin tag. +% \begin{macrocode} +\newcommand{\margintag}[1]{% +\@ifundefined{@captype}{% not float? +\marginpar{\raggedleft\textcolor{blue!70!black}{#1}}% +\ignorespaces% +}{}% not float? +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\watchout} \oarg{text} +% +% Prints a warning sign and optional text. +% \begin{macrocode} +\newcommand{\watchout}[1][]{% +\@ifundefined{@captype}{% not float? +% \@bsphack% +\marginpar{\hspace*{\fill}% +\textcolor{red!50!black}{\warningsign\normalsize\quad#1}}% +% \@esphack% +\ignorespaces% +}{}% not float? +} +% \end{macrocode} +% \end{macro} +% + + +% \subsection{The \env{dtxexample} Environment} +% +% Also see \cref{ex:dtxexample} on page \cpageref{ex:dtxexample}. +% +% \DescribeFile{ex_cut.tex} Used to store then \cs{input} example code. + +% \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{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. + + +% \begin{macrocode} +\NewDocumentEnvironment{dtxexample}{s +O{} m} +{% start dtxexample +% \end{macrocode} +% Copy the environment's contents to the file |ex_cut.tex|: +% \begin{macrocode} +\VerbatimOut[gobble=2,tabsize=4]{ex_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 Code:} +\VerbatimInput[tabsize=4]{ex_cut.tex} +\unskip +\textcolor{DTXD@examplerulecolor}{\hrule} +\smallskip +{\scriptsize\itshape Result:} + +% \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{ex_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} + + +% +% +% \iffalse +%</package> +% \fi + + + + +% \clearpage +% \pagestyle{plain} +% +% \renewcommand{\partname}{} +% \renewcommand{\thepart}{} +% \part{Change History and Index} +% +% +% \Finale +% +\endinput diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.ins b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.ins new file mode 100644 index 00000000000..21713e98406 --- /dev/null +++ b/Master/texmf-dist/source/latex/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/Master/texmf-dist/tex/latex/dtxdescribe/dtxdescribe.sty b/Master/texmf-dist/tex/latex/dtxdescribe/dtxdescribe.sty new file mode 100644 index 00000000000..e6d503be509 --- /dev/null +++ b/Master/texmf-dist/tex/latex/dtxdescribe/dtxdescribe.sty @@ -0,0 +1,385 @@ +%% +%% This is file `dtxdescribe.sty', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% dtxdescribe.dtx (with options: `package') +%% 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. + + +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{dtxdescribe} + [2016/12/08 v0.10 Describe additional object types in dtx source files.] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +\RequirePackage{etoolbox}[2011/01/03]% + +\RequirePackage{xparse} + +\RequirePackage{xifthen} + +\RequirePackage{xcolor} +\definecolor{myurlcolor}{rgb}{0,0,.7} +\definecolor{mylinkcolor}{rgb}{.7,0,0} + +\RequirePackage{caption} + +\RequirePackage{newfloat} + +\RequirePackage{fancyvrb} + +\RequirePackage{xstring} + + + + +\RequirePackage{pict2e} +\setlength{\unitlength}{1pt} + +\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} +} + + +\renewcommand*{\PrintEnvName}[1] +{\strut{\scriptsize{}Env}\quad\MacroFont#1\ } + +\newcommand*{\DTXD@printtype}[1] +{\raggedleft\strut{\scriptsize#1}\quad\MacroFont} + +\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}} + +\let\DTXD@origwrindex\@wrindex + +\newcommand*{\DTXD@margintag}[3]{% +\@ifundefined{@captype}{% not float? +\leavevmode% +\marginpar{% +\DTXD@printtype{% +#3% margintag +\ifblank{#1}{}{ \texttt{#1}}% class +}% Desc@Type +\texttt{#2}% name +}% marginpar +}{}% not float? +} + +\newcommand*{\DTXD@index}[5]{% +\@bsphack% +\begingroup% +\DTXD@origwrindex{% +#2\actualchar{\protect\ttfamily#2} % name +(#4)% index tag +\ifblank{#1}{}{ [#1]}% class +\encapchar #5}% +\begingroup% +\DTXD@origwrindex{% +#4s:\levelchar% index tag +\ifblank{#1}{}{[#1]:\levelchar}% class +#2\actualchar{\protect\ttfamily#2}% name +\encapchar #5}% +\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% +\ignorespaces% +} + +\newcommand*{\DTXD@margintagindex}[5]{% +\DTXD@margintag{#1}{#2}{#3}% +\DTXD@index{#1}{#2}{#3}{#4}{#5}% +} +\begingroup\lccode`\|=`\\ +\lowercase{\endgroup\def\removebs#1{\if#1|\else#1\fi}} +\newcommand*{\DTXD@macroname}[1]{\expandafter\removebs\string#1} + +\newcommand*{\DTXD@verbatimcmd}[1]{% +\string\verb\quotechar*\verbatimchar\string#1\verbatimchar% +} + +\newcommand*{\DTXD@cmdmargintagindex}[5]{% +\@bsphack% +\@ifundefined{@captype}{% not float? +\leavevmode% +\marginpar{% +\DTXD@printtype{% +#3% margin tag +\ifblank{#1}{}{ \texttt{#1}}% class +}% Desc@Type +\cmd{#2}% name +}% marginpar +}{}% not float? +\begingroup% +\DTXD@origwrindex{% +\ifblank{#1}{}{#1\actualchar[#1]:\levelchar}% class +\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2} % name +(#4)% index tag +\encapchar #5}% +\begingroup% +\DTXD@origwrindex{% +#4s:\levelchar% index tag +\ifblank{#1}{}{[#1]:\levelchar}% class +\DTXD@verbatimcmd{#2}% name +\encapchar #5}% +\@esphack% +\ignorespaces% +} + + + +\renewcommand*{\DescribeMacro}[2][]{% +\@bsphack% +\@ifundefined{@captype}{% not float? +\leavevmode% +\marginpar{% +\raggedleft% +\ifblank{#1}{}{{\scriptsize#1} }% class +\cmd{#2}% name +}% marginpar +}{}% not float? +\begingroup% +\DTXD@origwrindex{% +\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% name +\ifblank{#1}{}{\levelchar[#1]}% class +\encapchar usage}% +\ifthenelse{\isempty{#1}}% +{}% no class +{% class given +\begingroup% +\DTXD@origwrindex{% +#1\actualchar[#1]:\levelchar% +\DTXD@macroname{#2}\actualchar\DTXD@verbatimcmd{#2}% +\encapchar usage}% +}% class given +\@esphack% +\ignorespaces% +} + +\renewcommand*{\DescribeEnv}[2][] +{\DTXD@margintagindex{#1}{#2}{Env}{environment}{usage}} + + +\newcommand*{\DTXD@filename}{} + +\newcommand*{\DTXD@filemarginparindex}[5]{% +\renewcommand{\DTXD@filename}{\detokenize{#2}}% +\StrSubstitute{\DTXD@filename}% +{\detokenize{_}}{\detokenize{\_}}[\DTXD@filename]% +\DTXD@margintag{}{#2}{#3}% +\DTXD@index{#1}{\DTXD@filename}{#3}{#4}{#5}% +\endgroup% +\ignorespaces% +} +\newcommand*{\DTXD@DescribeFile}[2][]{% +\DTXD@filemarginparindex{#1}{#2}{File}{file}{usage}% +} +\newcommand*{\DescribeFile}{% +\begingroup\catcode`\_=12 \DTXD@DescribeFile% +} +\newcommand*{\DTXD@DescribeProgram}[2][]{% +\DTXD@filemarginparindex{#1}{#2}{Prog}{program}{usage}% +} +\newcommand*{\DescribeProgram}{% +\begingroup\catcode`\_=12 \DTXD@DescribeProgram% +} + +\newcommand*{\DTXD@DescribeCommand}[2][]{% +\DTXD@filemarginparindex{#1}{#2}{Cmd}{command}{usage}% +} +\newcommand*{\DescribeCommand}{% +\begingroup\catcode`\_=12 \DTXD@DescribeCommand% +} + +\newcommand*{\DescribePackage}[2][] +{\DTXD@margintagindex{#1}{#2}{Pkg}{package}{usage}} +\newcommand*{\DescribeClass}[2][] +{\DTXD@margintagindex{#1}{#2}{Cls}{class}{usage}} +\newcommand*{\DescribeOption}[2][] +{\DTXD@margintagindex{#1}{#2}{Opt}{option}{usage}} +\newcommand*{\DescribeArgument}[2][] +{\DTXD@margintagindex{#1}{#2}{Arg}{argument}{usage}} +\newcommand*{\DescribeBoolean}[2][] +{\DTXD@margintagindex{#1}{#2}{Bool}{boolean}{usage}} +\newcommand*{\DescribeLength}[2][] +{\DTXD@cmdmargintagindex{#1}{#2}{Len}{length}{usage}} +\newcommand*{\DescribeCounter}[2][] +{\DTXD@margintagindex{#1}{#2}{Ctr}{counter}{usage}} +\newcommand*{\DescribeKey}[2][] +{\DTXD@margintagindex{#1}{#2}{Key}{key}{usage}} +\newcommand*{\DescribeObject}[2][]{% +\@ifundefined{@captype}{% not float? +\@bsphack% +\leavevmode\marginpar{\raggedleft{\scriptsize#1} \texttt{#2}}% +}{}% not float? +\ifthenelse{\isempty{#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% +} +\newcommand*{\DescribeOther}[2][]{% +\@ifundefined{@captype}{% not float? +\@bsphack% +\leavevmode\marginpar{\raggedleft{\scriptsize#1} #2}% +}{}% not float? +\ifthenelse{\isempty{#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% +} + + +\newcommand{\margintag}[1]{% +\@ifundefined{@captype}{% not float? +\marginpar{\raggedleft\textcolor{blue!70!black}{#1}}% +\ignorespaces% +}{}% not float? +} + +\newcommand{\watchout}[1][]{% +\@ifundefined{@captype}{% not float? +\marginpar{\hspace*{\fill}% +\textcolor{red!50!black}{\warningsign\normalsize\quad#1}}% +\ignorespaces% +}{}% not float? +} + + +\definecolor{DTXD@examplerulecolor}{rgb}{.9,.9,.9} + + +\NewDocumentEnvironment{dtxexample}{s +O{} m} +{% start dtxexample +\VerbatimOut[gobble=2,tabsize=4]{ex_cut.tex}% +}% start dtxexample +{% end dtxexample +\endVerbatimOut +\par +\addvspace{\bigskipamount} +\IfBooleanTF{#1}{\vspace{\bigskipamount}}{\minipage{\linewidth}}% +\captionsetup{type=dtxdexample}% +\hrule\medskip +\caption{#3} +\textcolor{DTXD@examplerulecolor}{\smallskip\hrule} +\smallskip +{\scriptsize\itshape Code:} +\VerbatimInput[tabsize=4]{ex_cut.tex} +\unskip +\textcolor{DTXD@examplerulecolor}{\hrule} +\smallskip +{\scriptsize\itshape Result:} + +\ifstrempty{#2} +{} +{{\itshape\small #2}} +\IfBooleanTF{#1}{}{\endminipage}% +} % end dtxexample + +\AfterEndEnvironment{dtxexample} +{% +\par\unskip\input{ex_cut.tex}% +\medskip\hrule% +} + +\DeclareFloatingEnvironment[ +fileext=lox, +listname={List of Examples}, +name=Example, +placement=hbp +]{dtxdexample} + +\captionsetup*[dtxdexample]{ +format=hang, +font=bf, +justification=raggedright, +singlelinecheck=false, +skip=0pt, +position=top, +} + +\AtBeginDocument{ +\@ifpackageloaded{cleveref}{\crefname{dtxdexample}{example}{examples}}{} +} + + +\endinput +%% +%% End of file `dtxdescribe.sty'. |