From 4d0cb3164bdec74c01f560fe6fa184314ac063d7 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 12 Jan 2019 23:07:09 +0000 Subject: dtxdescribe (12jan19) git-svn-id: svn://tug.org/texlive/trunk@49682 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/dtxdescribe/dtxdescribe.dtx | 1622 +++++++++++++++++--- 1 file changed, 1413 insertions(+), 209 deletions(-) (limited to 'Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx') diff --git a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx index d72f69c6f1d..a4d54e98fe0 100644 --- a/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx +++ b/Master/texmf-dist/source/latex/dtxdescribe/dtxdescribe.dtx @@ -1,7 +1,7 @@ % \iffalse meta-comment % -% Copyright 2016 Brian Dunn +% Copyright 2016-2019 Brian Dunn % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -17,7 +17,7 @@ % \iffalse %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{dtxdescribe} -% [2018/03/30 v0.11 Describe additional object types in dtx source files.] +% [2019/01/11 v1.00 Describe additional object types in dtx source files.] % %<*driver> \documentclass{ltxdoc} @@ -26,8 +26,17 @@ \newcommand{\quicksummary}{Describe additional object types in \texttt{dtx} source files.} -\usepackage{lmodern} +% \usepackage{lmodern} % \usepackage{libertine} +\usepackage[osf]{erewhon} +% \usepackage{sourceserifpro} +\usepackage{roboto} +% \usepackage{sourcesanspro} +% \usepackage{sourcecodepro} +\usepackage{inconsolata} +% \usepackage{tgcursor} +% \usepackage{dejavu} + \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{textcomp} % provides \degree, \textquotesingle, \textmu @@ -67,114 +76,23 @@ \usepackage{microtype} -% widows and orphans: -\usepackage[all,defaultlines=2]{nowidow} - +\usepackage{metalogo} +\makeatletter +\@ifpackageloaded{erewhon}{ +\setlogokern{Te}{-.08em} +\setlogokern{eX}{-0.04em} +\setlogokern{La}{-.25em} +\setlogokern{aT}{-.08em} +\setlogokern{Xe}{-.04em} +\setlogokern{eL}{-.06em} +\setlogodrop{0.27ex} +}{} +\makeatother \usepackage{etoolbox} \usepackage[log-declarations=false]{xparse} - - -% \usepackage{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{titleps} \newpagestyle{pageheadfoot}{ @@ -188,36 +106,19 @@ -\providerobustcmd*{\lmacro}[1]{\textbackslash#1} -\providerobustcmd*{\cmds}[1]{\texttt{#1}} -\providerobustcmd*{\env}[1]{\texttt{#1}} -\providerobustcmd*{\ctr}[1]{\texttt{#1}} -\providerobustcmd*{\pkg}[1]{\textsf{#1}} -\providerobustcmd*{\prog}[1]{\texttt{#1}} - - -% \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}} +% Better spacing for \Describe... margin tags: +\setlength{\marginparsep}{1em} +\setlength{\marginparpush}{.7ex} - - - - -% \setlength{\marginparsep}{1em} -% \setlength{\marginparpush}{2ex} \setlength{\parindent}{0em} \setlength{\parskip}{2ex} -\setlength{\IndexMin}{40ex} - +\setlength{\IndexMin}{40ex} \usepackage{\mypackagename} - \usepackage[pdftex,bookmarks=true,hidelinks,% colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,% pageanchor=true,hyperindex=true, @@ -231,6 +132,24 @@ Subject={Describe additional object types in dtx source files.]},% Keywords={LaTeX, dtx, source, DescribeMacro}% }} +\pdfstringdefDisableCommands{ +\def\quad{ } +\def\\{ } +\def\pkg#1{#1} +\def\cs#1{\textbackslash#1} +\def\env#1{#1} +\def\,{ } +\def\prog#1{#1} +\def\LuaLaTeX{LuaLaTeX} +\def\XeLaTeX{XeLaTeX} +\def\TeX{TeX} +\def\LaTeX{LaTeX} +\def\Dash{ --- } +\def\dash{ -- } +\def\element#1{#1} +\def\attribute#1{#1} +} + \usepackage{cleveref} @@ -252,7 +171,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% %<*package> % \fi % -% \CheckSum{368} +% \CheckSum{0} % % \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 @@ -272,6 +191,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \changes{v0.10}{2016/12/08}{\ 2016/12/08 Initial ver} % \changes{v0.11}{2018/03/30}{\ 2018/03/30} +% \changes{v1.00}{2019/01/11}{\ 2019/01/11} @@ -296,7 +216,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % \bigskip % -% {\small\copyright{} 2016--2018} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com} +% {\small\textcopyright{} 2016--2018} Brian Dunn\\ \small \texttt{bd@BDTechConcepts.com} % % \vspace{.5in} % @@ -318,10 +238,16 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % 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. +% The \env{dtxexample} environment is provided for typesetting example code and its results. % Contents are displayed verbatim along with a caption and cross-referencing. % They are then \cs{input} and executed, and the result is shown. +% +% Environments are also provided for displaying verbatim or formatted source code, +% user-interface displays, and sidebars with titles. +% +% Macros are provided for formatting the names of inline \LaTeX\ objects such as +% packages and booleans, as well as program and file names, file types, internet +% objects, the names of certain programs, a number of logos, and inline dashes and slashes. % \end{abstract} % % \vfill @@ -377,7 +303,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \section{Using \pkg{dtxdescribe}} % Place |\usepackage{dtxdescribe}| in the |.dtx| file's driver section: -% \begin{verbatim} +% \begin{sourceverb} % %<*driver> % \documentclass{ltxdoc} % ... @@ -388,16 +314,16 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \usepackage{packagename} % the name of your new package % ... % \usepackage[...]{hyperref} -% \usepackage{...]{cleveref} +% \usepackage[...]{cleveref} % ... % % -% \end{verbatim} +% \end{sourceverb} % Various objects inside the |dtx| file may be described with \cs{DescribeBoolean}, % \cs{DescribeLength}, \cs{DescribeCounter}, and related macros, % similar to the already-familiar \cs{DescribeMacro} and \cs{DescribeEnv}. -% Optional ``classes'' may be assigned to the objects being described, including the new verisons +% Optional ``classes'' may be assigned to the objects being described, including the new versions % of \cs{DescribeMacro} and \cs{DescribeEnv}. % These classes are printed in the margin tag and index entry for each item, % and also generate additional index entries sorted by class. This is @@ -410,12 +336,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % but the index entries are still made. % % |\margintag{text}| may be used to place a colored tag in -% \margintag{\cs{margintag} text} +% \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] +% \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 @@ -425,16 +351,16 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \clearpage -% \section{The Macros, and the \env{dtxexample} Environment} +% \section{The macros, and the \env{dtxexample} environment} -% \subsection{Pre-existing Macros} +% \subsection{Macros and environments} % % \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. +% The preexisting macro from the \pkg{doc} package is redefined to +% create hyperlinked index entries, and include an optional class. % A margin tag is created and an index entry is made. % When the optional class is used, it is displayed in front of % the margin tag, and is used to group an index entry by @@ -447,16 +373,16 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % \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 +% The preexisting macro from the \pkg{doc} package is redefined to +% create hyperlinked index entries, include an optional class, and also to place % an `Env' tag in front of the name in the margin. % See \cref{ex:environment} on \cpageref{ex:environment}. % -% \subsection{Macro Arguments} +% \subsection{Arguments} % -% The \cs{Describe}\rule{.25in}{.4pt} macros +% The \cs{Describe\dots} macros % may be followed by \cs{marg}, \cs{oarg}, and \cs{parg} to % describe arguments passed to the macros. % @@ -489,7 +415,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % See \cref{ex:arguments} on \cpageref{ex:arguments}. -% \subsection{Common \LaTeX\ Elements} +% \subsection{Booleans, lengths, counters, keys} % % See \cref{ex:common} on \cpageref{ex:common}. % @@ -515,7 +441,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % See \cref{ex:key} on \cpageref{ex:key}. -% \subsection{References to External Packages and Classes} +% \subsection{Packages, classes, options} % % \DescribeMacro{\DescribePackage} \oarg{class} \marg{name} % @@ -533,7 +459,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % -% \subsection{Files, Programs, and Commands} +% \subsection{Files, programs, commands} % % \DescribeMacro{\DescribeFile} \oarg{class} \marg{name} % @@ -555,7 +481,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % -% \subsection{Other Source Objects} +% \subsection{Other source objects} % % \DescribeMacro{\DescribeObject} \oarg{class} \marg{name} % @@ -576,23 +502,85 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % See \cref{ex:other} on \cpageref{ex:other}. -% \subsection{Additional Tags} +% \subsection{In a \env{description} environment} +% +% To describe an object using a \env{description} environment, use the following. +% See \cref{ex:description} on \cpageref{ex:description}. + +% \DescribeMacro{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}} A description. +% +% \DescribeMacro{\ItemDescribeEnv} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribeArgument} \oarg{class} \marg{argument} A description. +% +% \DescribeMacro{\ItemDescribeBoolean} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribeLength} \oarg{class} \marg{\cs{name}} A description. +% +% \DescribeMacro{\ItemDescribeCounter} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribeKey} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribePackage} \oarg{class} \marg{package\_name} With underscores. +% +% \DescribeMacro{\ItemDescribeClass} \oarg{class} \marg{class\_name} With underscores. +% +% \DescribeMacro{\ItemDescribeOption} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribeFile} \oarg{class} \marg{file\_name} With underscores. +% +% \DescribeMacro{\ItemDescribeProgram} \oarg{class} \marg{program\_name} With underscores. +% +% \DescribeMacro{\ItemDescribeCommand} \oarg{class} \marg{command\_name} With underscores. +% +% \DescribeMacro{\ItemDescribeObject} \oarg{class} \marg{name} A description. +% +% \DescribeMacro{\ItemDescribeOther} \oarg{class} \marg{name} A description. + + +% \subsection{Defaults} + +% \DescribeMacro{\DescribeDefault} \marg{value} +% \DescribeDefault{value} +% +% Shows the default value of a \cs{Describe\dots} item, such as displayed here. +% Place this macro immediately after the \cs{Describe\dots} macro and any +% arguments, but before the text description. + +% \DescribeMacro{\DescribeDefaultcolor} +% The color of the margin tag used to show the default value. +% This is used by \cs{textcolor} to create the margin tag. +% +% \DescribeDefault{green!50!black} + + +% \subsection{\cs{margintag}, \cs{watchout}} % % % \DescribeMacro{\margintag} \marg{text} % % Creates a colored margin tag. % May be used to identify the topic of a paragraph or the destination of -% an arbitrary index entry. - +% an arbitrary index entry.\margintag{\cs{margintag}\{example\}} +% +% \DescribeMacro{\margintagcolor} +% \DescribeDefault{blue!70!black} +% The color of the \cs{margintag}. +% \bigskip % % \DescribeMacro{\watchout} \oarg{text} % % Creates a red margin tag with a warning sign and % optional text. May be used to warn the reader of special instructions, etc. +% \watchout[\cs{watchout}{[}example{]}] +% Without the optional text the warning sign is displayed by itself. +% +% \DescribeMacro{\watchoutcolor} +% \DescribeDefault{red!50!black} +% The color of the \cs{watchout}. -% \subsection{\env{dtxexample} Environment} +% \subsection{\env{dtxexample} environment} % % \DescribeEnv{dtxexample} * \oarg{Notes/cross-references} \marg{caption \& label} % @@ -606,16 +594,269 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % References to the float's labels may be placed in the optional argument to % the \env{dtxexample} environment, and will be printed below the code. % -% % The unstarred version places the code inside a % minipage, forbidding a page break in the middle of the code listing. The starred % version does not use a minipage. This is required when the code is too large to fit % on a single page. % % See \cref{ex:dtxexample} for a demonstration of how \env{dtxexample} works. +% +% \DescribeMacro{\dtxexamplecodename} +% \DescribeDefault{Code:} +% The text name of the code section. +% +% \DescribeMacro{\dtxexampleresultname} +% \DescribeDefault{Result:} +% The text name of the result section. +% +% +% \subsection{\env{noindmacro} and \env{noindenvironment} environments} +% +% \DescribeEnv{noindmacro} \marg{\cs{name}} +% To document macros which should not be included in the index. +% +% \DescribeEnv{noindenvironment} \marg{name} +% To document environments which should not be included in the index. +% +% Replace +% \begin{sourceverb} +% \begin{macro}{\macroname} \oarg{optional} \marg{mandatory} +% ... +% \end{macro} +% \end{sourceverb} +% with +% \begin{sourceverb} +% \begin{noindmacro}{\macroname} \oarg{optional} \marg{mandatory} +% ... +% \end{noindmacro} +% \end{sourceverb} +% and similarly for \env{noindenvironment}. +% +% +% \subsection{\env{sourceverb}, \env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}} +% +% \DescribeEnv{sourceverb} \oarg{key/values} +% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em} \qquad Display source code verbatim. +% Uses optional \pkg{fancyvrb} keys. Includes |gobble=2| to absorb the +% leading |%| and space character of a \filenm{dtx} file source format. +% Because this is a verbatim environment, it \emph{cannot} be used inside a macro. +% \bigskip +% +% \DescribeEnv{fsourceverb} \oarg{key/values} +% \DescribeDefault{gobble=2,\\tabsize=4,\\xleftmargin=2em,frame=lines} \qquad Display source +% code verbatim inside a frame. +% A label may be included using the \optn{label} key. +% Because this is a verbatim environment, it \emph{cannot} be used inside a macro. +% See \cref{ex:fsourceverb} on page \cpageref{ex:fsourceverb}. +% \bigskip +% +% \DescribeEnv{sourcedisplay} Display source code with manual formatting. +% This is not a verbatim environment. +% \cs{textcolor}, \cs{textbf}, and \cs{emph} may be used to highlight text. +% Macros must be escaped with \cs{cs}, characters such as \{ must be +% produced with \cs{\{}, etc. +% \cs{\textbackslash} must be used to force a new line. +% \cs{fquad}, \cs{fqquad}, and \cs{fqqquad} +% may be used to force indenting. +% Because this is \emph{not} a verbatim environment, +% it \emph{can} be used inside a macro. +% See \cref{ex:sourcedisplay} on \cpageref{ex:sourcedisplay}. +% +% \DescribeMacro{\fquad} Single-level indent inside a \env{sourcedisplay}. +% +% \DescribeMacro{\fqquad} Double-level indent inside a \env{sourcedisplay}. +% +% \DescribeMacro{\fqqquad} Triple-level indent inside a \env{sourcedisplay}. +% +% \DescribeEnv{UIdisplay} Displays a user interface, such as a dialog box entry +% or a menu selection. See \cref{ex:UIdisplay} on \cpageref{ex:UIdisplay}. +% Also see the \cs{UI} macro.. +% +% \DescribeMacro{\userentry} \marg{text to enter} \qquad +% Typeset something for the user to enter. +% Also see the \cs{cmds} macro. +% +% \DescribeMacro{\userentryname} +% \DescribeDefault{Enter~$\Rightarrow$} +% Text to tell the user to enter the following item. +% Change with \cs{renewcommand}. +% \bigskip +% +% \DescribeEnv{docsidebar} \oarg{title} \qquad Creates a sidebar within the document. +% See \cref{ex:docsidebar} on \cpageref{ex:docsidebar}. +% +% +% +% +% \subsection{Formatted objects} +% +% Macros to format references to various kinds of objects. +% +% This \pkg{dtxdescribe} package documentation uses \pkg{erewhon}, \pkg{roboto}, +% and \pkg{inconsolata}, along with \pkg{metalogo}, +% to demonstrate the following font effects. +% +% +% \subsubsection{\LaTeX\ objects} +% +% \DescribeMacro{\pkg} \pkg{packagename}, also for a \pkg{classname} + +% \DescribeMacro{\env} \env{environment} + +% \DescribeMacro{\ctr} \ctr{counter} + +% \DescribeMacro{\bool} \bool{boolean} + +% \DescribeMacro{\optn} \optn{option}: to a macro, package, class + +% \DescribeMacro{\TOC} \TOC: Table of contents. + +% \DescribeMacro{\LOF} \LOF: List of figures. + +% \DescribeMacro{\LOT} \LOT: List of tables. + + +% \subsubsection{Programs and commands} + +% \DescribeMacro{\progcode} \progcode{inline program code}: +% Escape underscores and other special characters such as \{, \%, \$. + +% \DescribeMacro{\prog} \prog{grep}, \prog{make}: A program name. Underscores allowed. + +% \DescribeMacro{\filenm} \filenm{file_name}: Underscores allowed. + +% \DescribeMacro{\UI} \UI{General user-interface text.} What the user sees on the display. +% Also see the \env{UIdisplay} environment. +% +% \DescribeMacro{\cmds} \cmds{commands to be entered}: What the user enters. +% Escape underscores and other special characters such as \{, \%, \$. +% Also see the \cs{userentry} macro. +% +% +% \subsubsection{File types} +% +% \DescribeMacro{\ODT} \ODT\ OpenDocument Format word processing document + +% \DescribeMacro{\SVG} \SVG\ image format +% \DescribeMacro{\PNG} \PNG\ image format +% \DescribeMacro{\GIF} \GIF\ image format +% \DescribeMacro{\JPG} \JPG\ image format + +% \DescribeMacro{\EPS} \EPS\ image format + +% \DescribeMacro{\PDF} \PDF\ image format + +% \DescribeMacro{\DVI} \DVI\ image format +% +% +% \subsubsection{Internet} +% +% \DescribeMacro{\UTF} \UTF: Unicode + +% \DescribeMacro{\URL} \URL: Uniform Resource Locator + +% \DescribeMacro{\element} \element{element}: \HTML \Slash \CSS\ element + +% \DescribeMacro{\attribute} \attribute{attribute}: \HTML \Slash \CSS\ attribute + +% \DescribeMacro{\HTML} \HTML: Hypertext Markup Language + +% \DescribeMacro{\HTMLfive} \HTMLfive: Old-style figure if font supports + +% \DescribeMacro{\CSS} \CSS: Cascading Style Sheet + +% \DescribeMacro{\CSSthree} \CSSthree: Old-style figure if font supports + +% \DescribeMacro{\EPUB} \EPUB: E-book file format +% +% +% \subsubsection{Specific programs} +% +% \DescribeMacro{\tikz} \tikz: Package logo + +% \DescribeMacro{\MathML} \MathML: Mathematical Markup Language + +% \DescribeMacro{\CTAN} \CTAN: Comprehensive \TeX\ Archive Network + +% \DescribeMacro{\TDS} \TDS: \TeX\ Directory Structure +% +% +% \subsubsection{Acronyms, brand names, trademarks} +% +% \DescribeMacro{\brand} \brand{Brandname}, \brand{Company Name} + +% \DescribeMacro{\acro} \acro{acro}: Acronym + +% \DescribeMacro{\supregistered} Superscript trademark symbol\supregistered +% +% +% +% +% \subsection{Logos} +% +% Several additional logos are provided: +% +% \DescribeMacro{\LuaTeX} \LuaTeX +% +% \DescribeMacro{\LuaLaTeX} \LuaLaTeX +% +% \DescribeMacro{\XeTeX} \XeTeX, with reversed E if \pkg{graphics} is loaded. +% +% \DescribeMacro{\XeLaTeX} \XeLaTeX, with reversed E if \pkg{graphics} is loaded. +% +% \DescribeMacro{\AmS} \AmS +% +% \DescribeMacro{\LyX} \LyX +% +% \DescribeMacro{\BibTeX} \BibTeX +% +% \DescribeMacro{\MakeIndex} \MakeIndex +% +% \DescribeMacro{\ConTeXt} \ConTeXt +% +% \DescribeMacro{\MiKTeX} \MiKTeX +% +% +% +% +% \subsection{Dashes and slashes} +% +% \DescribeMacro{\thinskip} A breakable thin skip. +% +% \DescribeMacro{\endash} An endash: \endash +% +% \DescribeMacro{\emdash} An emdash: \emdash +% +% \DescribeMacro{\thinbrspace} A thin space which allows a line break. +% +% \DescribeMacro{\thinthinbrspace} A very thin space which allows a line break. +% +% \DescribeMacro{\Dash} An unbreakeable thin space, emdash, and breakable thin space: +% A \Dash B +% +% \DescribeMacro{\dash} An unbreakeable thin space, endash, and breakable thin space: +% A \dash B +% +% \DescribeMacro{\Slash} An unbreakable very thin space, a slash, and a breakable very thin space: +% +% \begin{tabular}{rll} +% Command & Result \\ \hline +% |A--B| & A--B & (not breakable) \\ +% |A \dash B| & A \dash B & (only breakable before the B) \\ +% |A -- B| & A -- B & (breakable before or after the dash) \\ \hline +% |A---B| & A---B & (not breakable) \\ +% |A \Dash B| & A \Dash B & (only breakable before the B) \\ +% |A --- B| & A --- B & (breakable before or after the dash) \\ \hline +% |A/B| & A/B & (not breakable) \\ +% |A \Slash B| & A \Slash B & (only breakable before the B) \\ +% |A / B| & A / B & (breakable before or after the slash) \\ +% |A~/~B| & A~/~B & (not breakable) \\ +% \end{tabular} +% +% % \clearpage % % \section{Examples} @@ -705,7 +946,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \DescribePackage[examples]{samplepackage} % About a \LaTeX\ package. % -% \DescribeClass[examples]{sampleclass} +% \DescribeClass[examples]{sample_class} % About a \LaTeX\ class. % % \DescribeOption[examples]{sampleoption} @@ -778,6 +1019,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % \DescribeObject[color]{othercolor} % The other color. +% +% \DescribeObject{randomobject} About some random object. % \end{dtxexample} % % Describes an arbitrary programming object, using \cs{ttfamily} text. @@ -797,6 +1040,27 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % Describes an arbitrary non-programming object, using roman text. + +% \clearpage +% +% \begin{dtxexample}{Description environments\label{ex:description}} +% \begin{description} +% \ItemDescribeMacro[descexamples]{\macroname} Describe the macro. +% \ItemDescribeBoolean[descexamples]{booleanname} Describe the boolean. +% \ItemDescribeLength[descexamples]{\lengthname} Describe the length. +% \ItemDescribeKey[descexamples]{keyname} Describe the key. +% \ItemDescribePackage[descexamples]{package_name} Describe the package. +% \ItemDescribeClass[descexamples]{class_name} Describe the class. +% \ItemDescribeFile[descexamples]{file_name} Describe the file. +% \ItemDescribeProgram[descexamples]{program_name} Describe the program. +% \ItemDescribeCommand[descexamples]{command_name} Describe the class. +% \end{description} +% \end{dtxexample} +% +% Uses a \env{description} environment to describe objects. + + + % \clearpage % % @@ -809,7 +1073,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \end{dtxexample} % \Cref{ex:dtxexample}, typeset above, was created with the following code: -% \begin{verbatim} +% \begin{sourceverb} % \begin{dtxexample}[See \cref{fig:afigure}] % {\env{dtxexample}\label{ex:dtxexample}} % \begin{figure} @@ -817,7 +1081,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \caption{A Figure}\label{fig:afigure} % \end{figure} % \end{dtxexample} -% \end{verbatim} +% \end{sourceverb} % % When the example was created: % \begin{enumerate} @@ -825,8 +1089,8 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % 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 The code was written to the file |dtxexample_cut.tex|. +% \item The code was \cs{input} from |dtxexample_cut.tex|. % \item Executing the code created the figure with % caption ``A Figure'' and label |fig:afigure|, which % points to \cref{fig:afigure}. @@ -836,14 +1100,69 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % rule below the code, since a float was being generated and nothing followed the % code inline. An unstarred version would have created an extra rule. % \end{enumerate} +% +% +% \clearpage +% +% +% \begin{dtxexample} +% {\env{fsourceverb}\label{ex:fsourceverb}} +% % \begin{fsourceverb}[label=An fsourceverb example] +% % \newcommand{fdosomething}[1][whattodo]{ +% % doing #1 +% % } +% % \end{fsourceverb} +% \end{dtxexample} +% (The leading |%| characters would be present in the \filenm{dtx} source.) +% \bigskip +% \begin{dtxexample} +% {\env{sourcedisplay}\label{ex:sourcedisplay}} +% \begin{sourcedisplay} +% \cs{newcommand}\{dosomething\}[1][\textcolor{red}{whattodo}]\{\\ +% \fquad \textcolor{blue}{doing \textcolor{red}{\#1}}\\ +% \} +% \end{sourcedisplay} +% \end{dtxexample} +% +% \clearpage +% +% \begin{dtxexample} +% {\env{UIdisplay}\label{ex:UIdisplay}} +% Select: +% \begin{UIdisplay} +% \textsf{Preferences $\to$ Plugins $\to$ Files $\to$ HTML} +% \end{UIdisplay} +% For the field +% \begin{UIdisplay} +% Title heading: +% \end{UIdisplay} +% \userentry{H1} +% +% \end{dtxexample} +% +% \clearpage +% +% \begin{dtxexample} +% {\env{docsidebar}\label{ex:docsidebar}} +% Main text. +% +% More main text. +% +% \begin{docsidebar}[A title] +% An aside, which may help explain something +% incidental to the main text. +% \end{docsidebar} +% +% Additional main text. +% \end{dtxexample} % \clearpage % -% \section{Usage Notes} +% \section{Usage notes} % % \begin{description} % @@ -864,13 +1183,22 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \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} +% these macros occur. +% A trailing percent character may be used to +% avoid the extra space: +% \begin{sourceverb} +% text text text% <-- avoids extra space +% \margintag{A comment.} +% \index{An entry} % \index{Another entry} -% more inline text text text -% \end{verbatim} +% more inline text +% \end{sourceverb} +% +% \item[Unwanted vertical space:] Other environments nested inside a \env{docsidebar} +% may produce excessive vertical space. It may be required to insert +% \begin{sourceverb} +% \vspace*{-\baselineskip} +% \end{sourceverb} % % \item[\cs{margintag} placement:] To have the margin tag appear next to the first % line of a paragraph, place the \cs{margintag} or \cs{watchout} @@ -904,7 +1232,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \section{Code} -% \subsection{Required Packages} +% \subsection{Required packages} % % \DescribePackage{etoolbox} v2.6 or later % for \cs{BeforeBeginEnvironment}, \cs{AfterEndEnvironment} @@ -998,10 +1326,21 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \end{macro} +% \subsection{Vertical spacing} +% \begin{macrocode} +\setlength{\marginparsep}{1em} +\setlength{\marginparpush}{.7ex} + +\setlength{\parindent}{0em} +\setlength{\parskip}{2ex} + +\setlength{\IndexMin}{40ex} +% \end{macrocode} -% \subsection{Support Macros} +% \subsection{Support macros} + % \begin{macrocode} \renewcommand*{\PrintEnvName}[1] {\strut{\scriptsize{}Env}\quad\MacroFont#1\ } @@ -1014,9 +1353,11 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \begin{macro}{\DTXD@printtype} \marg{text} % % Used to print the object class in the margin: +% +% \changes{v1.00}{2019/01/09}{Sans tag font.} % \begin{macrocode} \newcommand*{\DTXD@printtype}[1] - {\raggedleft\strut{\scriptsize#1}\quad\MacroFont} + {\raggedleft\strut{\scriptsize\sffamily#1}\quad\MacroFont} % \end{macrocode} % \end{macro} @@ -1053,7 +1394,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \marginpar{% \DTXD@printtype{% #3% margintag -\ifblank{#1}{}{ \texttt{#1}}% class +\ifblank{#1}{}{ #1}% class }% Desc@Type \texttt{#2}% name }% marginpar @@ -1190,6 +1531,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % % Creates the margin tag and index entries where name is a \cs{macro}. % +% \changes{v1.00}{2019/01/09}{Sans tag font.} % \begin{macrocode} \newcommand*{\DTXD@cmdmargintagindex}[5]{% \@bsphack% @@ -1201,7 +1543,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \marginpar{% \DTXD@printtype{% #3% margin tag -\ifblank{#1}{}{ \texttt{#1}}% class +\ifblank{#1}{}{ #1}% class }% Desc@Type \cmd{#2}% name }% marginpar @@ -1241,11 +1583,13 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % -% \subsection{Pre-existing Macros} +% \subsection{\cs{DescribeMacro} and \cs{DescribeEnvironment}} % \begin{macro}{\DescribeMacro} \oarg{class} \marg{\cs{name}} % % Redefined to allow hyperlinked index entries and an optional class: +% +% \changes{v1.00}{2019/01/09}{Sans tag font.} % \begin{macrocode} \renewcommand*{\DescribeMacro}[2][]{% \@bsphack% @@ -1256,7 +1600,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \leavevmode% \marginpar{% \raggedleft% -\ifblank{#1}{}{{\scriptsize#1} }% class +\ifblank{#1}{}{{\scriptsize\textsf{#1}} }% class \cmd{#2}% name }% marginpar }{}% not float? @@ -1275,7 +1619,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \end{macrocode} % Only if a class was given: % \begin{macrocode} -\ifthenelse{\isempty{#1}}% +\ifblank{#1}% {}% no class {% class given % Again, and prepend the class: @@ -1308,10 +1652,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% -% \subsection{New Describe Macros} - - - +% \subsection{New \cs{Describe\dots} macros} % \begin{macro}{\DTX@filename} Stores the filename with a sanitized underscore. @@ -1341,8 +1682,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % The original filename is printed in the margin. % Any underscore characters have already been disabled % by the \cs{catcode} change. +% \changes{v1.00}{2019/01/10}{Fix: File class.} % \begin{macrocode} -\DTXD@margintag{}{#2}{#3}% +\DTXD@margintag{#1}{#2}{#3}% % \end{macrocode} % The detokenized and sanitized version is sent to the index file: % \begin{macrocode} @@ -1403,7 +1745,6 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% } % \end{macrocode} % \end{macro} -% % \begin{macro}{\DTXD@DescribeCommand} \oarg{class} \marg{name} @@ -1430,23 +1771,53 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % - +% \begin{macro}{\DTXD@DescribePackage} \oarg{class} \marg{name} +% The name may have underscores. +% \begin{macrocode} +\newcommand*{\DTXD@DescribePackage}[2][]{% +\DTXD@filemarginparindex{#1}{#2}{Pkg}{package}{usage}% +} +% \end{macrocode} +% \end{macro} % % -% \begin{macro}{\DescribePackage} \oarg{class} \marg{name} +% \begin{macro}{\DescribePackage} \marg{name} +% +% The underscore character is temporarily disabled, then +% the name is passed directly to \cs{DTXD@DescribePackage}. +% +% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.} % \begin{macrocode} -\newcommand*{\DescribePackage}[2][] - {\DTXD@margintagindex{#1}{#2}{Pkg}{package}{usage}} +\newcommand*{\DescribePackage}{% +\begingroup\catcode`\_=12 \DTXD@DescribePackage% +} % \end{macrocode} % \end{macro} + +% \begin{macro}{\DTXD@DescribeClass} \oarg{class} \marg{name} % -% \begin{macro}{\DescribeClass} \oarg{class} \marg{name} +% The name may have underscores. % \begin{macrocode} -\newcommand*{\DescribeClass}[2][] - {\DTXD@margintagindex{#1}{#2}{Cls}{class}{usage}} +\newcommand*{\DTXD@DescribeClass}[2][]{% +\DTXD@filemarginparindex{#1}{#2}{Cls}{class}{usage}% +} % \end{macrocode} % \end{macro} % +% +% \begin{macro}{\DescribeClass} \marg{name} +% +% The underscore character is temporarily disabled, then +% the name is passed directly to \cs{DTXD@DescribeClass}. +% +% \changes{v1.00}{2019/01/10}{Fix: Allow underscore.} +% \begin{macrocode} +\newcommand*{\DescribeClass}{% +\begingroup\catcode`\_=12 \DTXD@DescribeClass% +} +% \end{macrocode} +% \end{macro} + % \begin{macro}{\DescribeOption} \oarg{class} \marg{name} % \begin{macrocode} \newcommand*{\DescribeOption}[2][] @@ -1503,7 +1874,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \@bsphack% \leavevmode\marginpar{\raggedleft{\scriptsize#1} \texttt{#2}}% }{}% not float? -\ifthenelse{\isempty{#1}} +\ifblank{#1}% {\begingroup% \DTXD@origwrindex{% #2\actualchar{\protect\ttfamily#2}% @@ -1538,7 +1909,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \@bsphack% \leavevmode\marginpar{\raggedleft{\scriptsize#1} #2}% }{}% not float? -\ifthenelse{\isempty{#1}} +\ifblank{#1}% {% \begingroup% \DTXD@origwrindex{#2\encapchar usage}% @@ -1556,22 +1927,277 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \end{macro} +% \subsection{\cs{DescribeDefault}} -% \subsection{New Margin Tags} - -% \begin{macro}{\margintag} \marg{text} +% \begin{macro}{\DescribeDefaultcolor} +% The color of the margin tag used to show the default value. % -% Prints a colored margin tag. +% \changes{v1.00}{2019/01/09}{Added.} % \begin{macrocode} -\newcommand{\margintag}[1]{% +\newcommand*{\DescribeDefaultcolor}{green!50!black} +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}{\DescribeDefault} \marg{value} +% +% Creates a colored margin tag showing the booleandefault value. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DescribeDefault}[1]{% + \margintag{% + \footnotesize% + \textcolor{\DescribeDefaultcolor}{% + Default: \texttt{#1}% + }% + }% +} +% \end{macrocode} +% \end{macro} + + + +% \subsection{\cs{ItemDescribeMacro}, etc.} +% +% The following are for use inside a \env{description}. +% +% \begin{macro}{\ItemDescribeMacro} \oarg{class} \marg{\cs{name}} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeMacro}[2][]{% +\item[\cmd{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeMacro[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeEnv} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeEnv}[2][]{% +\item[\env{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeEnv[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeArgument} \oarg{class} \marg{argument} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeArgument}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeArgument[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeBoolean} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeBoolean}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeBoolean[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeLength} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeLength}[2][]{% +\item[\cmd{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeLength[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeCounter} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeCounter}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeCounter[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeKey} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeKey}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeKey[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribePackage} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DTXD@ItemDescribePackage}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribePackage[#1]{#2}% +\endgroup +} + +\newcommand{\ItemDescribePackage}{% +\begingroup\catcode`\_=12 \DTXD@ItemDescribePackage% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeClass} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DTXD@ItemDescribeClass}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeClass[#1]{#2}% +\endgroup +} + +\newcommand{\ItemDescribeClass}{% +\begingroup\catcode`\_=12 \DTXD@ItemDescribeClass% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeOption} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeOption}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeOption[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + + +% \begin{macro}{\ItemDescribeFile} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DTXD@ItemDescribeFile}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeFile[#1]{#2}% +\endgroup +} + +\newcommand{\ItemDescribeFile}{% +\begingroup\catcode`\_=12 \DTXD@ItemDescribeFile% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeProgram} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DTXD@ItemDescribeProgram}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeProgram[#1]{#2}% +\endgroup +} + +\newcommand{\ItemDescribeProgram}{% +\begingroup\catcode`\_=12 \DTXD@ItemDescribeProgram% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeCommand} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\DTXD@ItemDescribeCommand}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeCommand[#1]{#2}% +\endgroup +} + +\newcommand{\ItemDescribeCommand}{% +\begingroup\catcode`\_=12 \DTXD@ItemDescribeCommand% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeObject} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeObject}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeObject[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ItemDescribeOther} \oarg{class} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\ItemDescribeOther}[2][]{% +\item[\texttt{#2}:]% +\setlength{\parskip}{1.5ex}% +\DescribeOther[#1]{#2}% +} +% \end{macrocode} +% \end{macro} + + + + + + +% \subsection{\cs{margintag}, \cs{watchout}} + + +% \begin{macro}{\margintagcolor} +% The color of the \cs{margintag}. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\margintagcolor}{blue!70!black} +% \end{macrocode} +% \end{macro} + + +% \begin{macro}{\margintag} \marg{text} +% +% Prints a colored margin tag. +% +% \changes{v1.00}{2019/01/09}{Uses \cs{margintacolor}.} +% \begin{macrocode} +\newcommand{\margintag}[1]{% \@ifundefined{@captype}{% not float? -\marginpar{\raggedleft\textcolor{blue!70!black}{#1}}% +\marginpar{\raggedleft\textcolor{\margintagcolor}{#1}}% \ignorespaces% }{}% not float? } % \end{macrocode} % \end{macro} + +% \begin{macro}{\watchoutcolor} +% The color of the \cs{watchout}. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\watchoutcolor}{red!50!black} +% \end{macrocode} +% \end{macro} + + % \begin{macro}{\watchout} \oarg{text} % % Prints a warning sign and optional text. @@ -1580,28 +2206,42 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \begin{macrocode} \newcommand{\watchout}[1][]{% \@ifundefined{@captype}{% not float? -% \@bsphack% -\marginpar{\raggedleft% -\textcolor{red!50!black}{\warningsign\normalsize\quad#1}}% -% \@esphack% -\ignorespaces% + \marginpar{% + \raggedleft% + \textcolor{\watchoutcolor}{\warningsign\normalsize\quad#1}% + }% + \ignorespaces% }{}% not float? } % \end{macrocode} % \end{macro} -% \subsection{The \env{dtxexample} Environment} +% \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. - +% \DescribeFile{dtxexample_cut.tex} Used to store then \cs{input} example code. +% \changes{v1.00}{2019/01/11}{Cut file name changed to \filenm{dtxexample_cut.tex}} +% % \DescribeObject[color]{DTXD@examplerulecolor} The color of the middle rule in the dtxexample. % \begin{macrocode} \definecolor{DTXD@examplerulecolor}{rgb}{.9,.9,.9} % \end{macrocode} +% +% \begin{macro}{\dtxexamplecodename} The text name of the code section. +% \changes{v1.00}{2019/01/11}{Added.} +% \begin{macrocode} +\newcommand*{\dtxexamplecodename}{Code:} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\dtxexampleresultname} The text name of the result section. +% \changes{v1.00}{2019/01/11}{Added.} +% \begin{macrocode} +\newcommand*{\dtxexampleresultname}{Result:} +% \end{macrocode} +% \end{macro} % \begin{environment}{dtxexample} * \oarg{notes/cross-references} \marg{caption \& label} % @@ -1622,9 +2262,9 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% \NewDocumentEnvironment{dtxexample}{s +O{} m} {% start dtxexample % \end{macrocode} -% Copy the environment's contents to the file |ex_cut.tex|: +% Copy the environment's contents to the file |dtxexample_cut.tex|: % \begin{macrocode} -\VerbatimOut[gobble=2,tabsize=4]{ex_cut.tex}% +\VerbatimOut[gobble=2,tabsize=4]{dtxexample_cut.tex}% }% start dtxexample % \end{macrocode} % When the environment closes: @@ -1651,12 +2291,12 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \begin{macrocode} \textcolor{DTXD@examplerulecolor}{\smallskip\hrule} \smallskip -{\scriptsize\itshape Code:} -\VerbatimInput[tabsize=4]{ex_cut.tex} +{\scriptsize\itshape\dtxexamplecodename} +\VerbatimInput[tabsize=4]{dtxexample_cut.tex} \unskip \textcolor{DTXD@examplerulecolor}{\hrule} \smallskip -{\scriptsize\itshape Result:} +{\scriptsize\itshape\dtxexampleresultname} % \end{macrocode} % Possible add the optional cross-references or notes: @@ -1681,7 +2321,7 @@ Keywords={LaTeX, dtx, source, DescribeMacro}% % \end{macrocode} % Execute the code: % \begin{macrocode} -\par\unskip\input{ex_cut.tex}% +\par\unskip\input{dtxexample_cut.tex}% % \end{macrocode} % Closing rule:: % \begin{macrocode} @@ -1721,6 +2361,570 @@ position=top, % \end{macrocode} + +% \subsection{\env{noindmacro} and \env{noindenvironment}} +% +% +% Similar to \env{macro} and \env{environment}, but not indexed. +% +% \begin{environment}{noindmacro} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newenvironment{noindmacro}[1] +{ + \setlength{\parskip}{\marginparpush} + \leavevmode\par\DTXD@margintag{}{\cmd{#1}}{} +} +{\unskip} +% \end{macrocode} +% \end{environment} +% +% +% \begin{environment}{noindenvironment} \marg{name} +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newenvironment{noindenvironment}[1] +{ + \setlength{\parskip}{\marginparpush} + \leavevmode\par\DTXD@margintag{}{#1}{Env} +} +{\unskip} +% \end{macrocode} +% \end{environment} +% +% +% +% \subsection{\env{sourcedisplay}, \env{UIdisplay}, \env{docsidebar}} +% +% For use in a \env{sourcedisplay}: +% +% \begin{macro}{\fquad} Forces a quad indent. +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\fquad}{\hspace*{1em}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\fqquad} Forces a double-quad indent. +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\fqquad}{\hspace*{2em}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\fqqquad} Forces a triple-quad indent. +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\fqqquad}{\hspace*{3em}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{environment}{sourceverb} +% To typeset a block of source code, verbatim. +% +% \changes{v1.00}{2019/01/11}{Added.} +% \begin{macrocode} +\DefineVerbatimEnvironment{sourceverb}{Verbatim} + {gobble=2,tabsize=4,xleftmargin=2em} +\BeforeBeginEnvironment{sourceverb}{\vspace*{-.5\parskip}} +% \end{macrocode} +% \end{environment} + +% \begin{environment}{fsourceverb} +% To typeset a framed block of source code, verbatim. +% +% \changes{v1.00}{2019/01/11}{Added.} +% \begin{macrocode} +\DefineVerbatimEnvironment{fsourceverb}{Verbatim} + {gobble=2,tabsize=4,xleftmargin=2em,frame=lines} +\BeforeBeginEnvironment{fsourceverb}{\vspace*{-.5\parskip}} +% \end{macrocode} +% \end{environment} + + +% \begin{environment}{sourcedisplay} +% To typeset a block of source code, allowing direct formatting. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newenvironment{sourcedisplay} +{ + \leavevmode + \par + \fqquad\minipage{\linewidth-2em} + \ttfamily +} +{% + \endminipage + \par +} +% \end{macrocode} +% \end{environment} + + +% \begin{environment}{UIdisplay} +% To typeset a user interface display. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newenvironment{UIdisplay} +{ + \leavevmode + \par + \fqquad\minipage{\linewidth-2em} + \sffamily\bfseries +} +{ + \endminipage + \par +} +% \end{macrocode} +% \end{environment} + + +% \begin{macro}{\userentryname} +% Text to tell the user to enter the following item. +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand*{\userentryname}{Enter~$\Rightarrow$} +% \end{macrocode} +% \end{macro} + + +% \begin{macro}{\userentry} \marg{text to enter} +% +% Typesets text to be entered by the users. +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newcommand{\userentry}[1]{% +\par +\fqquad% +\begin{minipage}{\linewidth-2em} + {\footnotesize \userentryname}\quad\cmds{#1} +\end{minipage} +\par +} +% \end{macrocode} +% \end{macro} + + + +% \begin{environment}{docsidebar} +% To typeset a sidebar in the documentation. +% +% \changes{v1.00}{2019/01/09}{Added.} +% \begin{macrocode} +\newenvironment{docsidebar}[1][] +{% + \quote\unskip\medskip + \setlength{\parskip}{1.5ex}% + \ifblank{#1}{}{\textit{#1}\newline}% + \rule[.5\bigskipamount]{\linewidth}{.4pt}% + \newline% +} +{% + \leavevmode\par + \rule[\bigskipamount]{\linewidth}{.4pt} + \endquote\unskip +} +% \end{macrocode} +% \end{environment} +% +% +% +% \subsection{Formatted objects} +% +% Macros to format references to various kinds of objects. +% +% \changes{v1.00}{2019/01/11}{Added formatted objects.} +% +% \subsubsection{\LaTeX\ objects} +% +% \begin{macro}{\pkg} or class +% \begin{macrocode} +\providerobustcmd*{\pkg}[1]{\mbox{\textsf{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\env} +% \begin{macrocode} +\providerobustcmd*{\env}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\ctr} +% \begin{macrocode} +\providerobustcmd*{\ctr}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\bool} +% \begin{macrocode} +\providerobustcmd*{\bool}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\optn} +% \begin{macrocode} +\providerobustcmd*{\optn}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\TOC} +% \begin{macrocode} +\providerobustcmd*{\TOC}{\acro{TOC}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\LOF} +% \begin{macrocode} +\providerobustcmd*{\LOF}{\acro{LOF}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\LOT} +% \begin{macrocode} +\providerobustcmd*{\LOT}{\acro{LOT}} +% \end{macrocode} +% \end{macro} + + +% \subsubsection{Programs and commands} + +% \begin{macro}{\cmds} +% \begin{macrocode} +\providerobustcmd*{\cmds}[1]{\mbox{\textbf{\texttt{#1}}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\progcode} +% \begin{macrocode} +\providerobustcmd*{\progcode}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\prog} +% \begin{macrocode} +\newcommand*{\DTXD@prog}[1]{% + \mbox{\textsf{\textsl{\detokenize{#1}}}}% + \endgroup% +} + +\providerobustcmd*{\prog}{% + \begingroup% + \catcode`\_=12% + \DTXD@prog% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\filenm} +% \begin{macrocode} +\newcommand*{\DTXD@filenm}[1]{% + \mbox{\texttt{\detokenize{#1}}}% + \endgroup% +} + +\providerobustcmd*{\filenm}{% + \begingroup% + \catcode`\_=12% + \DTXD@filenm% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\UI} General user-interface text. +% \begin{macrocode} +\providerobustcmd*{\UI}[1]{\textbf{\textsf{#1}}} +% \end{macrocode} +% \end{macro} +% +% +% \subsubsection{File types} +% +% \begin{macro}{\ODT} +% \begin{macrocode} +\providerobustcmd*{\ODT}{\acro{ODT}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\SVG} +% \begin{macrocode} +\providerobustcmd*{\SVG}{\acro{SVG}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\PNG} +% \begin{macrocode} +\providerobustcmd*{\PNG}{\acro{PNG}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\GIF} +% \begin{macrocode} +\providerobustcmd*{\GIF}{\acro{GIF}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\JPG} +% \begin{macrocode} +\providerobustcmd*{\JPG}{\acro{JPG}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\EPS} +% \begin{macrocode} +\providerobustcmd*{\EPS}{\acro{EPS}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\PDF} +% \begin{macrocode} +\providerobustcmd*{\PDF}{\acro{PDF}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\DVI} +% \begin{macrocode} +\providerobustcmd*{\DVI}{\acro{DVI}} +% \end{macrocode} +% \end{macro} +% +% +% \subsubsection{Internet} +% +% \begin{macro}{\UTF} +% \begin{macrocode} +\providerobustcmd*{\UTF}{\acro{UTF}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\URL} +% \begin{macrocode} +\providerobustcmd*{\URL}{\acro{URL}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\element} +% \begin{macrocode} +\providerobustcmd*{\element}[1]{\texttt{<#1>}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\attribute} +% \begin{macrocode} +\providerobustcmd*{\attribute}[1]{\mbox{\texttt{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\HTML} +% \begin{macrocode} +\providerobustcmd*{\HTML}{\acro{HTML}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\HTMLfive} +% \begin{macrocode} +\providerobustcmd*{\HTMLfive}{\HTML\textsc{5}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\CSS} +% \begin{macrocode} +\providerobustcmd*{\CSS}{\acro{CSS}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\CSSthree} +% \begin{macrocode} +\providerobustcmd*{\CSSthree}{\CSS\textsc{3}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\EPUB} +% \begin{macrocode} +\providerobustcmd*{\EPUB}{\acro{EPUB}} +% \end{macrocode} +% \end{macro} +% +% +% \subsubsection{Specific programs} +% +% \begin{macro}{\tikz} +% \begin{macrocode} +\providerobustcmd*{\tikz}{Ti\textit{k}z} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\MathML} +% \begin{macrocode} +\providerobustcmd*{\MathML}{Math\acro{ML}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\CTAN} +% \begin{macrocode} +\providerobustcmd*{\CTAN}{\acro{CTAN}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\TDS} +% \begin{macrocode} +\providerobustcmd*{\TDS}{\acro{TDS}} +% \end{macrocode} +% \end{macro} +% +% +% \subsubsection{Acronyms, brand names, trademarks} +% +% \begin{macro}{\brand} +% \begin{macrocode} +\providerobustcmd*{\brand}[1]{\textsc{#1}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\acro} +% \begin{macrocode} +\providerobustcmd*{\acro}[1]{\textsc{\lowercase{#1}}} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\supregistered} Superscript trademark symbol. +% \begin{macrocode} +\providerobustcmd*{\supregistered}{\textsuperscript{\textregistered}} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \subsection{Logos} +% +% \changes{v1.00}{2019/01/11}{Added logos.} +% +% \begin{macro}{\LuaTeX} \LuaTeX +% \begin{macrocode} +\providerobustcmd*{\LuaTeX}{\mbox{Lua\TeX}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\LuaLaTeX} \LuaLaTeX +% \begin{macrocode} +\providerobustcmd*{\LuaLaTeX}{\mbox{Lua\LaTeX}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\XeTeX} +% \begin{macro}{\XeLaTeX} \XeTeX, \XeLaTeX +% \begin{macrocode} +\providerobustcmd*{\XeTeXrevE} + {\hspace{-.1667em}\raisebox{-.5ex}{E}\hspace{-.125em}} + +\AtBeginDocument{ +\@ifpackageloaded{graphics}{ + \renewrobustcmd*{\XeTeXrevE} + {\hspace{-.1667em}\raisebox{-.5ex}{\reflectbox{E}}\hspace{-.125em}} +}{} +} + +\providerobustcmd*{\XeTeX}{\mbox{X\XeTeXrevE\TeX}} +\providerobustcmd*{\XeLaTeX}{\mbox{X\XeTeXrevE\LaTeX}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\AmS} \AmS +% \begin{macrocode} +\providerobustcmd*{\AmS}{% + \leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex% + \hbox{$\mathcal M$}\kern-.2em\mathcal S$}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\LyX} \LyX +% \begin{macrocode} +\providerobustcmd*{\LyX}{\textsf{LyX}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\BibTeX} \BibTeX +% \begin{macrocode} +\providerobustcmd*{\BibTeX}{\mbox{B\textsc{ib}\TeX}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\MakeIndex} \MakeIndex +% \begin{macrocode} +\providerobustcmd*{\MakeIndex}{\prog{MakeIndex}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ConTeXt} \ConTeXt +% \begin{macrocode} +\providerobustcmd*{\ConTeXt}{\mbox{Con\TeX{}t}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\MiKTeX} \MiKTeX +% \begin{macrocode} +\providerobustcmd*{\MiKTeX}{\mbox{MiK\TeX}} +% \end{macrocode} +% \end{macro} +% +% +% +% \subsection{Dashes and slashes} +% +% \begin{macro}{\thinskip} A breakable thin skip. +% \begin{macrocode} +\DeclareRobustCommand{\thinskip}{\hskip 0.16667em\relax} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\endash} An endash: \endash +% \begin{macrocode} +\def\endash{–} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\emdash} An emdash: \emdash +% \begin{macrocode} +\def\emdash{—} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\thinbrspace} A thin space which allows a line break. +% \begin{macrocode} +\newcommand{\thinbrspace}{\hspace{.16667em}\penalty\exhyphenpenalty\hspace{0pt}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\thinthinbrspace} A thin space which allows a line break. +% \begin{macrocode} +\newcommand{\thinthinbrspace}{\hspace{.08333em}\penalty\exhyphenpenalty\hspace{0pt}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\Dash} An unbreakeable thin space, emdash, and breakable thin space. +% \begin{macrocode} +\newrobustcmd{\Dash}{\unskip\thinspace\emdash\thinbrspace} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\dash} An unbreakeable thin space, endash, and breakable thin space. +% \begin{macrocode} +\newrobustcmd{\dash}{\unskip\thinspace\endash\thinbrspace} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\Slash} An unbreakable very thin space, a slash, and a breakable thin space. +% \begin{macrocode} +\newrobustcmd{\Slash}{\unskip\hspace{.08333em}/\thinthinbrspace} +% \end{macrocode} +% \end{macro} +% % % % \iffalse -- cgit v1.2.3