summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/dtxdescribe
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-07-16 21:13:53 +0000
committerKarl Berry <karl@freefriends.org>2019-07-16 21:13:53 +0000
commitd2055c0169cf583fb9af2de4061319e5b31a4303 (patch)
treed83d9c6ad15e0b0d5748a0db5cc6c75cb5c1e179 /Master/texmf-dist/source/latex/dtxdescribe
parent444bab00733dfef06cba9e2ba93c8f63fb00a014 (diff)
dtxdescribe (16jul19)
git-svn-id: svn://tug.org/texlive/trunk@51652 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/dtxdescribe')
-rw-r--r--Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx306
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>