dtxdescribe (16jul19)

git-svn-id: svn://tug.org/texlive/trunk@51652 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 240 insertions, 66 deletions

diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx
index d73ecf95392..1c7ae225e36 100644
--- a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx
+++ b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx
@@ -17,7 +17,7 @@
 % \iffalse
 %<package>\NeedsTeXFormat{LaTeX2e}
 %<package>\ProvidesPackage{dtxdescribe}
-%<package>    [2019/03/22 v1.01 Describe additional object types in dtx source files.]
+%<package>    [2019/07/16 v1.02 Describe additional object types in source files.]
 %
 %<*driver>
 \documentclass{ltxdoc}
@@ -28,9 +28,9 @@
 
 % \usepackage{lmodern}
 % \usepackage{libertine}
-\usepackage[osf]{erewhon}
+\usepackage[space]{erewhon}
 % \usepackage{sourceserifpro}
-\usepackage{roboto}
+\usepackage{cabin}
 % \usepackage{sourcesanspro}
 % \usepackage{sourcecodepro}
 \usepackage{inconsolata}
@@ -153,7 +153,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 %<*package>
 % \fi
 %
-% \CheckSum{978}
+% \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
@@ -175,6 +175,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % \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}
 
 
 
@@ -211,12 +212,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % \begin{abstract}
 % \noindent
 % The \pkg{doc} package includes tools for describing macros and environments
-% in \LaTeX\ source |dtx| format.
+% 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 item is given a margin tag similar to \cs{DescribeEnv},
+% 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.
@@ -231,8 +234,15 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % 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}
@@ -340,6 +350,17 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 
 % \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
@@ -595,6 +616,14 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 %
 % \subsection{\env{noindmacro} and \env{noindenvironment} environments}
 %
+% These only make sense if using the \pkg{ltxdoc} class and \pkg{doc} package
+% \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.
 %
@@ -1216,7 +1245,20 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 
 
 % \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}
@@ -1272,57 +1314,66 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % 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{
-\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}
-}
+    \@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}
 
@@ -1368,6 +1419,22 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % \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}
@@ -1375,19 +1442,99 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 
 \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}
 
-\setlength{\IndexMin}{40ex}
+
+% \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}
 
 
 
@@ -1409,7 +1556,10 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % \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}
@@ -1635,7 +1785,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 %
 % \changes{v1.00}{2019/01/09}{Sans tag font.}
 % \changes{v1.01}{2019/01/20}{Put margin tag class in brackets.}
+% \changes{v1.02}{2019/07/14}{Fix if not \pkg{ltxdoc} class.}
 %    \begin{macrocode}
+\providecommand*{\DescribeMacro}{}
 \renewcommand*{\DescribeMacro}[2][]{%
 \@bsphack%
 %    \end{macrocode}
@@ -1688,7 +1840,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % \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}
@@ -1909,18 +2063,22 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 %    \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}%
 }%
@@ -1945,7 +2103,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 }%
 }%
 \@esphack%
-% \ignorespaces%
+\ignorespaces%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -1955,12 +2113,15 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % 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%
 }%
@@ -1977,7 +2138,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 \DTXD@origwrindex{#1\actualchar[#1]:\levelchar#2\encapchar usage}%
 }%
 \@esphack%
-% \ignorespaces%
+\ignorespaces%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -2312,15 +2473,15 @@ Keywords={LaTeX, dtx, source, DescribeMacro}%
 % 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=2,tabsize=4]{dtxexample_cut.tex}%
+\VerbatimOut[gobble=\DTXD@gobble,tabsize=4]{dtxexample_cut.tex}%
 }% start dtxexample
 %    \end{macrocode}
 % When the environment closes:
@@ -2482,7 +2643,7 @@ position=top,
 % \changes{v1.00}{2019/01/11}{Added.}
 %    \begin{macrocode}
 \DefineVerbatimEnvironment{sourceverb}{Verbatim}
-    {gobble=2,tabsize=4,xleftmargin=2em}
+    {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em}
 \BeforeBeginEnvironment{sourceverb}{\vspace*{-.5\parskip}}
 %    \end{macrocode}
 % \end{environment}
@@ -2492,8 +2653,8 @@ position=top,
 %
 % \changes{v1.00}{2019/01/11}{Added.}
 %    \begin{macrocode}
-\DefineVerbatimEnvironment{fsourceverb}{Verbatim}
-    {gobble=2,tabsize=4,xleftmargin=2em,frame=lines}
+    \DefineVerbatimEnvironment{fsourceverb}{Verbatim}
+        {gobble=\DTXD@gobble,tabsize=4,xleftmargin=2em,frame=lines}
 \BeforeBeginEnvironment{fsourceverb}{\vspace*{-.5\parskip}}
 %    \end{macrocode}
 % \end{environment}
@@ -2984,6 +3145,19 @@ position=top,
 % \end{macro}
 %
 %
+% \clearpage
+%
+% \section{Compiling \pkg{dtxdescribe}}
+%
+% To compile the \pkg{dtxdescribe} package:
+% \userentry{pdflatex dtxdescribe.ins}
+%
+% To compile the \pkg{dtxdescribe} documentation
+% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
+% \userentry{makeindex -s gglo.ist -o dtxdescribe.gls dtxdescribe.glo}
+% \userentry{makeindex -s gind.ist dtxdescribe}
+% \userentry{pdflatex dtxdescribe.dtx} \fqqquad (Several times)
+%
 %
 % \iffalse
 %</package>