Debian Codegraph @

texmf-dist/source/latex/ydoc/ydoc.dtx

raw
1 % \iffalse
2 %<*driver>
3 \begingroup
4 \def\latexfmt{LaTeX2e}
5 \ifx\latexfmt\fmtname
6 \long\def\skip#1\NeedsTeXFormat{\endgroup\NeedsTeXFormat}
7 \expandafter\skip
8 \else
9 \endgroup
10 \let\NeedsTeXFormat\end
11 \fi
12 %</driver>
13 % \fi
14 %
15 % \iffalse
16 %<*ydocstrip.tex>
17 % \fi
18 %
19 % \iffalse
20 % \begin{macrocode}
21 \expandafter\ifx\csname ydocstripversion\endcsname\relax\else
22 \endinput
23 \fi
24
25 \chardef\ydocstripversion=1
26
27 \input docstrip
28
29
30 \def\checkOption<#1{%
31 \ifcase
32 \ifx*#10\else \ifx/#11\else
33 \ifx+#12\else \ifx-#13\else
34 \ifx<#14\else
35 \ifx=#15\else
36 \ifx!#16\else
37 10\fi\fi\fi\fi\fi\fi\fi\relax
38 \expandafter\starOption\or
39 \expandafter\slashOption\or
40 \expandafter\plusOption\or
41 \expandafter\minusOption\or
42 \expandafter\verbOption\or
43 \expandafter\varOption\or
44 \expandafter\valueOption\else
45 \expandafter\doOption\fi
46 #1}
47
48 \def\varOption =#1#2>#3\endLine{{%
49 \ifx*#1\relax
50 \edef\varStop{\perCent<=/#2>}%
51 \global\expandafter\let\csname ydocstrip@var@#2\endcsname\empty%
52 \expandafter\def\csname ydocstrip@var@#2\endcsname##1{}%
53 \loop
54 \ifeof\inFile
55 \errmessage{Source file ended while reading a multi-line variable content!}%
56 \fi
57 \read\inFile to \inLine
58 \if 1\ifx\inLine\varStop 0\fi 1% if not inLine==varStop
59 \expandafter\xdef\csname ydocstrip@var@#2\endcsname{\csname ydocstrip@var@#2\endcsname^^J\inLine}%
60 \maybeMsg{.}%
61 \repeat
62 \else
63 \ifx/#1\relax
64 \errmessage{Error in expression: spurious '<=/#2>'}%
65 \else
66 \ifx+#1\relax
67 \expandafter\ifx\csname ydocstrip@var@#2\endcsname\relax
68 \expandafter\xdef\csname ydocstrip@var@#2\endcsname{#3}%
69 \else
70 \expandafter\xdef\csname ydocstrip@var@#2\endcsname{\csname ydocstrip@var@#2\endcsname^^J#3}%
71 \fi
72 \else
73 \expandafter\gdef\csname ydocstrip@var@#1#2\endcsname{#3}%
74 \fi
75 \fi
76 \fi
77 }}
78
79
80 \def\valueOption !#1>#2\endLine{%
81 \begingroup
82 \expandafter\let\expandafter\var\csname ydocstrip@var@#1\endcsname
83 \ifx\var\relax
84 \errmessage{Used variable '#1' was never defined!}%
85 \else
86 \ifx\var\empty\else
87 \def\do##1##2##3{%
88 \StreamPut##1{\csname ydocstrip@var@#1\endcsname}%
89 }%
90 \activefiles
91 \fi
92 \fi
93 \endgroup
94 }
95 % \end{macrocode}
96 % \fi
97 % \iffalse
98 %</ydocstrip.tex>
99 % \fi
100 %
101 % \iffalse
102 %<*ydoc.ins>
103 % \fi
104 % \iffalse COPYRIGHT
105 %%
106 %% Copyright (c) 2010-2022 by Martin Scharrer <[email protected]>
107 %%
108 %% This work may be distributed and/or modified under the
109 %% conditions of the LaTeX Project Public License, either version 1.3c
110 %% of this license or (at your option) any later version.
111 %% The latest version of this license is in
112 %% http://www.latex-project.org/lppl.txt
113 %% and version 1.3 or later is part of all distributions of LaTeX
114 %% version 2005/12/01 or later.
115 %%
116 %% This work has the LPPL maintenance status `maintained'.
117 %%
118 %% The Current Maintainer of this work is Martin Scharrer.
119 %%
120 %% This work consists of the files ydoc.dtx and ydoc.ins
121 %% and the derived file ydoc.cls, ydoc.sty, ydoc-code.sty,
122 %% ydoc-expl.sty, ydoc-doc.sty and ydoc-desc.sty.
123 %%
124 % \fi
125 %
126 % \iffalse
127 \input ydocstrip
128
129 \preamble
130 \endpreamble
131
132 \keepsilent
133 \askforoverwritefalse
134
135 \generate{%
136 \file{ydocstrip.tex}{\from{ydoc.dtx}{ydocstrip.tex}}%
137 \file{ydocincl.tex} {\from{ydoc.dtx}{ydocincl.tex}}%
138 \file{ydoc.ins} {\from{ydoc.dtx}{ydoc.ins}}%
139 \file{ydoc.cls} {\from{ydoc.dtx}{ydoc.cls}}%
140 \file{ydoc.sty} {\from{ydoc.dtx}{ydoc.sty}}%
141 \file{ydoc.cfg} {\from{ydoc.dtx}{ydoc.cfg}}%
142 \file{ydoc-code.sty}{\from{ydoc.dtx}{ydoc-code.sty}}%
143 \file{ydoc-desc.sty}{\from{ydoc.dtx}{ydoc-desc.sty}}%
144 \file{ydoc-expl.sty}{\from{ydoc.dtx}{ydoc-expl.sty}}%
145 \file{ydoc-doc.sty} {\from{ydoc.dtx}{ydoc-doc.sty}}%
146 }
147
148 \begingroup
149 \obeyspaces
150 \Msg{*************************************************************}%
151 \Msg{* *}%
152 \Msg{* To finish the installation you have to move the following *}%
153 \Msg{* file into a directory searched by TeX: *}%
154 \Msg{* *}%
155 \Msg{* ydoc.cls *}%
156 \Msg{* ydoc.sty *}%
157 \Msg{* ydoc-code.sty *}%
158 \Msg{* ydoc-desc.sty *}%
159 \Msg{* ydoc-expl.sty *}%
160 \Msg{* ydoc-doc.sty *}%
161 \Msg{* ydocstrip.tex *}%
162 \Msg{* ydocincl.tex *}%
163 \Msg{* *}%
164 \Msg{* To produce the documentation run the file ydoc.dtx *}%
165 \Msg{* through LaTeX. *}%
166 \Msg{* *}%
167 \Msg{* Happy TeXing! *}%
168 \Msg{* *}%
169 \Msg{*************************************************************}%
170 \endgroup%
171
172 \endbatchfile
173 % vim: ft=tex
174 % \fi
175 % \iffalse
176 %</ydoc.ins>
177 % \fi
178 %
179 % \iffalse
180 %<*driver>
181 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
182 \ProvidesFile{ydoc.dtx}[%
183 %<=*DATE>
184 2022/10/26
185 %<=/DATE>
186 %<=*VERSION>
187 v0.7alpha
188 %<=/VERSION>
189 DTX file of ydoc]
190
191 \message{^^JRun this DTX file using 'tex' to extract all files!^^J}
192 \documentclass{ydoc}
193
194 \newdimen\tempskip
195
196 \def\tablecaption{%
197 \tempskip=\abovecaptionskip
198 \abovecaptionskip=\belowcaptionskip
199 \belowcaptionskip=\tempskip
200 \caption
201 }
202
203 %\OnlyDescription
204 \begin{document}
205 \DocInput{ydoc.dtx}
206 \PrintChanges
207 \PrintIndex
208 \end{document}
209 %</driver>
210 % \fi
211 %
212 % \CheckSum{0}
213 %
214 % \CharacterTable
215 % {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
216 % 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
217 % Digits \0\1\2\3\4\5\6\7\8\9
218 % Exclamation \! Double quote \" Hash (number) \#
219 % Dollar \$ Percent \% Ampersand \&
220 % Acute accent \' Left paren \( Right paren \)
221 % Asterisk \* Plus \+ Comma \,
222 % Minus \- Point \. Solidus \/
223 % Colon \: Semicolon \; Less than \<
224 % Equals \= Greater than \> Question mark \?
225 % Commercial at \@ Left bracket \[ Backslash \\
226 % Right bracket \] Circumflex \^ Underscore \_
227 % Grave accent \` Left brace \{ Vertical bar \|
228 % Right brace \} Tilde \~}
229 %
230 %
231 % \changes{v0.1alpha}{2010/04/10}{First released alpha version}
232 %
233 % \DoNotIndex{\newcommand,\newenvironment}
234 %
235 % \GetFileInfo{ydoc.dtx}
236 %
237 % \title{The \textsf{\textbf{ydoc}} Class and Packages}
238 % \author{Martin Scharrer}
239 % \repository{https://github.com/MartinScharrer/ydoc/}
240 % \github{MartinScharrer/ydoc}
241 % \email{[email protected]}
242 % \makeatletter
243 % \date{Version \expandafter\@gobble\fileversion\\[0.5ex]\filedate}
244 % \makeatother
245 %
246 % \maketitle
247 %
248 % \ifpdf
249 % \hypersetup{%
250 % pdfauthor = {Martin Scharrer <[email protected]>},
251 % pdftitle = {The ydoc package, \fileversion, \filedate},
252 % pdfsubject = {Documentation of LaTeX package ydoc.},
253 % pdfkeywords = {ydoc, documentation, LaTeX}
254 % }%
255 % \fi
256 %
257 %
258 % \begin{abstract}
259 % {\color{red}\bfseries This package bundle is currently under development.
260 % All functionality, settings and macro as well as file names can change in later versions and may be incomplete!
261 % It is not ready yet to be used for other packages.
262 % }
263 %
264 % The \pkg{ydoc} class and packages provide macros to document the functionality and implementation of \LaTeX{} classes and packages.
265 % It is similar to the \pkg{ltxdoc} class with the \pkg{doc} package, but uses more modern features/packages by default
266 % (e.g.\ \pkg{xcolor}, \pkg{hyperref}, \pkg{listings}). However, some of the features like code indexing is not yet included.
267 % \end{abstract}
268 %
269 % \section{Introduction}
270 % The \pkg{ydoc} packages allow the documentation of \LaTeX\ packages and classes.
271 % The name stands for ``\emph{Y}et another \emph{Doc}umentation Package'' and is a pun on
272 % the fact that there are several documentation packages written by package developers
273 % to document their own packages. All these packages didn't suited the author and therefore he,
274 % take a guess, wrote his own documentation package.
275 % It (will) support(s) all macros and environments (but not necessary with full/identical features) provided by the \pkg{doc}
276 % package to allow the fast adaption of existing |.dtx| files.
277 %
278 % This documentation uses the \pkg{ydoc} packages itself and therefore also acts as a live example.
279 %
280 % \subsection{\pkg{ydoc} Files}
281 % The \pkg{ydoc} bundle consists (at the moment, subject to change) of the \cls{ydoc} class and the packages \pkg{ydoc}, \pkg{ydoc-code},
282 % \pkg{ydoc-desc}, \pkg{ydoc-expl} and \pkg{ydoc-doc}. The \cls{ydoc} class and package allow the user the freedom to use the functionality with other classes if wanted.
283 % The class will load the package. The \pkg{ydoc} package loads the packages \pkg{ydoc-code}, \pkg{ydoc-desc}, \pkg{ydoc-expl} and \pkg{ydoc-doc}, which
284 % provide the functionality to document \LaTeX\ code implementation, describe the user-level macro, include live code examples and provide replacements for the
285 % macros of the \pkg{doc} package, respectively.
286 % This packages can be loaded on their own in other kind of \LaTeX\ documents if required.
287 %
288 % \subsection{Similar Packages}
289 % Other documentation related classes and packages are \pkg{ltxdoc}, \pkg{doc}, \pkg{dox}, \pkg{xdoc}, \pkg{gmdoc}, \pkg{pauldoc}, \pkg{hypdoc},
290 % \pkg{codedoc}, \pkg{nicetext} and \pkg{tkz-doc}.
291 %
292 %
293 % \section{Usage}
294 % (section incomplete)
295 %
296 % \subsection{Code Documentation Environments}
297 %
298 % \begin{DescribeEnv}{macro}{<macro>}[<\# of args>]!\optional!{<arg~1~description>}!\ldots!{<arg~$n$~description>}
299 % \MacroArgs<macro documentation>\\
300 % \begin{DescribeEnv}{macrocode}
301 % \MacroArgs<macro code>
302 % \end{DescribeEnv}\\
303 % \ldots
304 % \end{DescribeEnv}
305 % The implementation of macros can be documented using this environment. The actual \meta{macro code} must be placed in a \env{macrocode} environment.
306 % Longer macro definition can be split using multiple \env{macrocode} environments with interleaved documentation texts.
307 %
308 % The \pkg{ydoc} definition of the \env{macro} environment has an additional feature compare to \pkg{doc}. The arguments of the macro (|#1|, |#2|, \ldots) can be
309 % documented in a vertical list. The environment has an optional argument to declare the \meta{number of arguments} the macro implementation has.
310 % The descriptions of this macro arguments are read from the next arguments of the environment. If the \meta{number of arguments} is not given or zero (or less)
311 % no further arguments are read by the \env{macro} environment.
312 %
313 % \begin{DescribeEnv}{macrocode}
314 % \MacroArgs<macro code>
315 % \end{DescribeEnv}
316 % This environment wraps around any \TeX\ code and types it verbatim. The environment end is read verbatim as well and must be written on a separate
317 % line beginning with a percent followed by exactly four spaces: `\verb*+% \end{macrocode}+'.
318 %
319 % \begin{DescribeEnv}{environment}{<name>}[<\# of args>]!\optional!{<arg~1~description>}!\ldots!{<arg~$n$~description>}
320 % \MacroArgs<environment documentation>\\
321 % \begin{DescribeEnv}{macrocode}
322 % \MacroArgs<macro code>
323 % \end{DescribeEnv}\\
324 % \ldots
325 % \end{DescribeEnv}
326 % This environment provides the same functionality as the \env{macro} environment above, but for environments instead.
327 %
328 %
329 % \subsection{Description Macros and Environments}
330 %
331 % \DescribeMacro\DescribeMacro<\textbackslash macro><macro arguments>
332 % The \cs{DescribeMacro} is used to describe macros included their arguments.
333 % It takes the to be described \meta{\textbackslash macro} as first argument (can also be enclosed in |{ }|).
334 % The macro name can include `|@|'. Any number of \meta{macro arguments} (in a broad sense, see Table~\ref{tab:macroargs}) following it
335 % are formatted as arguments of this macro.
336 % Any following non-argument token (normal text, macro, etc.)\ will make \cs{DescribeMacro} stop collecting arguments.
337 % For example, if a \TeX\ group should be started using |{ }| direct after \cs{DescribeMacro} a |\relax| (or a similar macro) should be inserted
338 % between them, otherwise the group will be taken as mandatory argument of the described macro.
339 %
340 % Multiple \cs{DescribeMacro} in a row will automatically stacked inside one framed box. If this is not wanted simply separate them with |\relax|
341 % or any other macro or token. See also the \env{DescribeMacros} environment below.
342 %
343 % \subsubsection*{Examples:}
344 % \par\noindent |\DescribeMacro\mymacro*[<optional>]{<meta text>}| will result in\\
345 % \mbox{\Macro\mymacro*[<optional>]{<meta text>}} (inside a framed box).
346 % \par\medskip\noindent The above syntax description of \cs{DescribeMacro} itself was typeset with\\
347 % |\DescribeMacro\DescribeMacro<\textbackslash macro><macro arguments>|.
348 % \par\medskip\noindent Special macros with have a partner macro as end marker can be typeset like this:\\
349 % |\DescribeMacro\csname<text>\AlsoMacro\endcsname|, which will result in\\
350 % \mbox{\Macro\csname<text>\AlsoMacro\endcsname}.
351 %
352 % \DescribeMacro\Macro<\textbackslash macro><macro arguments>
353 % This macro is like an in-text version of \cs{DescribeMacro}.
354 % The macro description stays as part of the surrounding text and is not placed inside a framed box.
355 % The description can be broken between lines. This can be avoided by placing it inside a |\mbox{}|.
356 % \cs{Macro} is equivalent to \cs{MacroArgs}\cs{AlsoMacro}.
357 %
358 % \DescribeMacro\MacroArgs<macro arguments>
359 % This macro formats the \meta{macro arguments} the same way as \cs{DescribeMacro} and \cs{Macro} but without a macro name.
360 % Like \cs{Macro} the description is placed in-text.
361 %
362 % \DescribeMacro\AlsoMacro<\textbackslash macro><further macro arguments>
363 % This macro can only be used inside the \meta{macro arguments} of the above macros and typesets an additional macro as part
364 % of the syntax of the described macro. The additional macro is normally an end- or other marker of some kind. Further macro arguments may
365 % follow. Macros which are not part of the syntax but normal arguments should be written as
366 % |<\textbackslash name>| (yielding \MacroArgs<\textbackslash name>) instead.
367 % The `\verb+|+' character is an abbreviation of \Macro\AlsoMacro, but only at places where this can appear.
368 %
369 % \subsubsection*{Examples:}
370 % |\Macro\@for<\textbackslash var> ':=' <list> \AlsoMacro\do {<code>}|\\
371 % \Macro\@for<\textbackslash var> ':=' <list> \AlsoMacro\do {<code>}
372 % \par\medskip\noindent
373 % |\Macro\pgfkeys{<key1>'='<value1>','<key2>'/.code='{<code>}}|\\
374 % \Macro\pgfkeys{<key1>'='<value1>','<key2>'/.code='{<code>}}\\
375 %
376 % \DescribeMacro\MakeShortMacroArgs*{<char>}
377 % This macro is similar to \Macro\MakeShortVerb from the \pkg{shortvrb} package.
378 % It can be used to globally define one character to act like \Macro\MacroArgs till the same character is discovered again.
379 % Special characters must be escaped with an backslash for the definition.
380 % One additional benefit beside the shorter size is that the argument list is automatically terminated.
381 % For example |\MakeShortMacroArgs{\"}| will make `|"<arg>{<arg>}"|' act like `|\MacroArgs<arg>{<arg>}\relax|'.
382 % One side-effect is that should the argument list be terminated, e.g. by an unknown element or macro, then the rest of the
383 % text till the end-character is typeset as normal, but inside a group.
384 %
385 % The starred version will define the character equal to \Macro\Macro instead.
386 %
387 % \DescribeMacro\DeleteShortMacroArgs{<char>}
388 % Globally removes the special meaning from \meta{char} given to him by \Macro\MakeShortMacroArgs.
389 %
390 % Note that special characters like |`| are
391 % best defined |\AtBeginDocument| and deleted again |\AtEndDocument| to avoid issues if they are written to the |aux| file by some package.
392 %
393 % \begin{DescribeEnv}{DescribeMacros}
394 % \Macro\Macro<\textbackslash name><arguments>\\
395 % \Macro\Macro<\textbackslash name><arguments>\\
396 % \ldots
397 % \end{DescribeEnv}
398 % This environment can be used to place multiple macro description into the same framed box.
399 % The macros are described using \cs{Macro}, which has a slightly different definition than outside of this environment, to place the
400 % description into a |\hbox|. The environment stacks these |\hbox|es in a |\vbox|. The macros can also be placed freely using anything
401 % which produces a |\hbox|, e.g.\ |\hbox{\Macro\A ~~~ \Macro\B}| or using
402 % a |tabular| (see also \env{DescribeMacrosTab}).
403 %
404 % \DescribeEnv[<tabular content>]{DescribeMacrosTab}{<tabular column definition>}
405 % This is a special version of the \env{DescribeMacros} environment which adds a tabular environment around the content.
406 % This is useful if a large set of small macros should be desribed at once. Placing them all below each other would result in a very bad page layout.
407 % The environment has one argument which is passed to \env{tabular} as the column definition. A `|@{}|' is added before and after to remove any margins.
408 %
409 %
410 % \begin{DescribeEnv}{DescribeEnv}{<name>}<arguments>
411 % \MacroArgs<body content>\relax\space |\\|\\
412 % \MacroArgs<more body content>
413 % \end{DescribeEnv}
414 % \vspace{-\beforedescskip}
415 % \DescribeMacro\DescribeEnv[<body content>]{<name>}<arguments>
416 % The \env{DescribeEnv} can be used to describe environments in the same way the \cs{DescribeMacro} macro describes macros.
417 % Supported \meta{arguments} are shown in Table~\ref{tab:macroargs}.
418 % Potential \meta{body content} can be placed between the begin and end of the environment description to explain the user what kind of material
419 % should be placed inside it.
420 % The environment also exists in macro form as \cs{DescribeEnv}, which allows to provide small \meta{body content} as an optional argument.
421 % Please note that for this optional argument a \cs{MacroArgs} is automatically inserted, but not for the \cs{DescribeEnv} environment content.
422 %
423 % The body content is placed into a indented |\hbox{}| stacked inside a |\vbox{}| also holding the environment begin and end line.
424 % The |\\| macro is redefined to create a new indented |\hbox| acting as new code line.
425 % Therefore this environment is similar to a one-column \env{tabular}: all macros placed into a line are only valid up to the next line end.
426 %
427 % \begin{table}
428 % \tablecaption{Supported `arguments' for \cs{DescribeMacro}/\cs{DescribeEnv}/\cs{MacroArgs}.}\label{tab:macroargs}
429 % \begin{tabular}{llll}
430 % \toprule
431 % Description & Syntax & Result & Macro$^{a}$ \\
432 % \midrule
433 % Meta text & |<text>| & \MacroArgs<text> & \Macro\meta{<text>} \\
434 % Mandatory Argument & |{args}| & \MacroArgs{args} & \\
435 % ---, with meta text & |{<text>}| & \MacroArgs{<text>} & \Macro\marg{<text>} \\
436 % Optional Argument & |[args]| & \MacroArgs[args] & \\
437 % ---, with meta text & |[<text>]| & \MacroArgs[<text>] & \Macro\oarg{<text>} \\
438 % Picture Argument & |(args)| & \MacroArgs(args) & \\
439 % ---, with meta text & |(<text>)| & \MacroArgs(<text>) & \Macro\parg{<text>} \\
440 % Beamer Overlay Argument & |<<args>>| & \MacroArgs<<args>> \\
441 % ---, with meta text & |<< <text> >>| & \MacroArgs<<<text> >> & \Macro\aarg{<text>} \\
442 % Star & |*| & \MacroArgs* \\
443 % \midrule
444 % Verbatim content & |'$&^%_#$\'| & \MacroArgs'$&^%_#$\' \\
445 % ---, produce |'| char & |''| & \MacroArgs'' \\
446 % Insert any \TeX\ code & |!\fbox{T}!| & \MacroArgs!\fbox{T}! \\
447 % Unbreakable Space & |~| & \\
448 % Space (explicit macro) & |\space| & \\
449 % \midrule
450 % Second macro (e.g.\ endmarker) & |\AlsoMacro\macro| & \MacroArgs\AlsoMacro\macro \\
451 % \hfill short version: & \verb+|\macro+ & \MacroArgs|\macro \\
452 % \bottomrule
453 % \multicolumn{4}{l}{{\Large\strut}$^{a}$) As alternative to be used inside normal text.} \\
454 % \multicolumn{4}{l}{Note that `|args|' can itself be further macro arguments except true verbatim.}
455 % \end{tabular}
456 % \end{table}
457 %
458 % \DescribeMacro\DescribeLength<\textbackslash name>{<default value>}
459 % This macro can be used to describe \LaTeX\ lengths also known as dimensions. Multiple \cs{DescribeLength} macros in a row will automatically be grouped.
460 %
461 % \subsection{Format Macros}
462 % \begin{DescribeMacrosTab}{ll}
463 % \Macro\cs{<macro name>} & \Macro\env{<environment name>} \\
464 % \Macro\pkg{<package name>} & \Macro\cls{<class name>} \\
465 % \end{DescribeMacrosTab}
466 % This macros can be used to format names of macros, environments, packages and classes, respectively.
467 % At the moment they simply use |\texttt|.
468 %
469 % \DescribeMacros\hbox{\Macro\bslash~~~~\Macro\percent~~~~\Macro\braceleft~~~~\Macro\braceright}\endDescribeMacros
470 % This macros define expandable backslash (\texttt{\bslash}$_{12}$), percent char (\texttt{\percent}$_{12}$),
471 % and left (\texttt{\braceleft}$_{12}$) and right (\texttt{\braceright}$_{12}$) braces with catcode 12 (other), respectively.
472 % They should only be used with text-typer font when used in text, because other fonts might not have the
473 % correct characters. The macros must be protected when used in a moving argument.
474 %
475 % \DescribeMacrosTab{@{}ll@{}}
476 % \Macro\meta{<meta text>} &
477 % \Macro\marg{<argument text>} \\
478 % \Macro\oarg{<argument text>} &
479 % \Macro\parg{<argument text>} \\
480 % \Macro\aarg{<argument text>} &
481 % \Macro\sarg \\
482 % \endDescribeMacrosTab
483 % This macros allow to typeset meta text and mandatory, optional, picture and beamer overlay arguments as well as a star symbol.
484 % They are used internally by \cs{MacroArgs} and friends. See Table~\ref{tab:macroargs} for examples.
485 %
486 % \DescribeMacrosTab{ll}
487 % \Macro\metastyle &
488 % \Macro\margstyle \\
489 % \Macro\oargstyle &
490 % \Macro\pargstyle \\
491 % \Macro\aargstyle &
492 % \Macro\sargstyle \\
493 % \endDescribeMacrosTab
494 % This macros are used to define the style in which the corresponding macros above are being formatted.
495 % They are used like \MacroArgs '{'<\textbackslash stylemacro>{<material>}'}' to allow the styles to
496 % use macros like |\ttfamily| or |\texttt|\marg{material}. By default the optional argument and the also optional star are
497 % printed in the color `|optional|' which is a 65\% gray.
498 %
499 % \subsection{Settings}
500 % The following macro and dimensions can be redefined by the user to adjust the layout of the package documentation.
501 %
502 % \DescribeLength\descindent {-20pt}
503 % \DescribeLength\beforedescskip{~12pt plus 4pt minus 4pt}
504 % \DescribeLength\afterdescskip {~~6pt plus 2pt minus 2pt}
505 % These length define the indention and vertical distances before and after a \cs{Describe\ldots} macro or environment, respectively.
506 %
507 % \DescribeLength\descsep {1em in \texttt{tt} font = 10.5pt}
508 % This macro defines the space on the left and right side between the description text and the framed box.
509 %
510 % \subsection{Macros and Environments to include LaTeX Code Examples}
511 % \DescribeEnv{example}
512 % \DescribeEnv{examplecode}
513 %
514 % (to be written)
515 %
516 % \StopEventually{}
517 %
518 % \clearpage
519 % \section{Implementation}
520 %
521 % \iffalse
522 %<*ydoc.cls>
523 % \fi
524 % \subsection{Class File}
525 %
526 % \begin{macrocode}
527 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
528 \ProvidesClass{ydoc}[%
529 %<!DATE>
530 %<!VERSION>
531 %<*DRIVER>
532 2011/08/11 develop
533 %</DRIVER>
534 ydoc class: document LaTeX class and packages]
535 % \end{macrocode}
536 %
537 % At the moment simply load \cls{article} class with \opt{a4paper} option
538 % and load the \pkg{ydoc} package.
539 % \begin{macrocode}
540 \PassOptionsToClass{a4paper}{article}
541 \DeclareOption*{\expandafter\PassOptionsToClass\expandafter{\CurrentOption}{article}}
542 \ProcessOptions\relax
543 \LoadClass{article}
544 \RequirePackage{ydoc}
545 % \end{macrocode}
546 % \iffalse
547 %</ydoc.cls>
548 % \fi
549 %
550 % \iffalse
551 %<*ydoc.sty>
552 % \fi
553 % \subsection{Package File}
554 %
555 % \begin{macrocode}
556 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
557 \ProvidesPackage{ydoc}[%
558 %<!DATE>
559 %<!VERSION>
560 %<*DRIVER>
561 2011/08/11 develop
562 %</DRIVER>
563 ydoc package: document LaTeX class and packages]
564 % \end{macrocode}
565 %
566 % \begin{macrocode}
567 \RequirePackage{ydoc-code}
568 \RequirePackage{ydoc-expl}
569 \RequirePackage{ydoc-desc}
570 \RequirePackage{ydoc-doc}
571
572 \RequirePackage{newverbs}
573 \MakeSpecialShortVerb{\qverb}{\"}
574 \AtBeginDocument{\catcode`\^^A=14\relax}
575
576 \input{ydoc.cfg}
577 % \end{macrocode}
578 % \iffalse
579 %</ydoc.sty>
580 % \fi
581 %
582 % \iffalse
583 %<*ydoc.cfg>
584 % \fi
585 % \subsection{Config File}
586 % \begin{macrocode}
587 %% Please delete the following line on manual changes:
588 \ProvidesFile{ydoc.cfg}[%
589 %<!DATE>
590 %<!VERSION>
591 %<*DRIVER>
592 2011/08/11 develop
593 %</DRIVER>
594 Default config file for ydoc]
595 % \end{macrocode}
596 %
597 % \begin{macrocode}
598 \usepackage[T1]{fontenc}
599 \IfFileExists{fourier.sty}{%
600 \usepackage{fourier}
601 }{}
602 % \end{macrocode}
603 %
604 % Use 'lmodern' only for the 'tt' font if fourier is installed.
605 % \begin{macrocode}
606 \IfFileExists{lmodern.sty}{
607 \IfFileExists{fourier.sty}{
608 \renewcommand{\ttdefault}{lmtt}
609 }{
610 \usepackage{lmodern}
611 }
612 }{}
613 % \end{macrocode}
614 %
615 %
616 % \begin{macrocode}
617 \urlstyle{sf}
618 % \end{macrocode}
619 %
620 % Use micro-typesetting if pdftex is used:
621 % \begin{macrocode}
622 \usepackage{ifpdf}
623 \ifpdf
624 \usepackage{microtype}
625 \fi
626 % \end{macrocode}
627 % \begin{macrocode}
628 \usepackage{array}
629 \usepackage{booktabs}
630 \usepackage{multicol}
631 \usepackage{xcolor}
632 \usepackage{listings}
633 \usepackage{booktabs}
634 \usepackage{hyperref}
635 % \end{macrocode}
636 %
637 % \begin{macrocode}
638 \reversemarginpar
639 % \end{macrocode}
640 %
641 % \iffalse
642 %</ydoc.cfg>
643 % \fi
644 %
645 % \iffalse
646 %<*ydoc-code.sty>
647 % \fi
648 % \subsection{Macros and Environments to document Implementations}
649 %
650 % \begin{macrocode}
651 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
652 \ProvidesPackage{ydoc-code}[%
653 %<!DATE>
654 %<!VERSION>
655 %<*DRIVER>
656 2011/08/11 develop
657 %</DRIVER>
658 ydoc package to document macro code]
659 % \end{macrocode}
660 %
661 % \begin{macrocode}
662 \RequirePackage{hyperref}
663 \hypersetup{colorlinks=true,pdfborder=0 0 0,pdfborderstyle={}}
664 % \end{macrocode}
665 %
666 % \begin{macrocode}
667 \IfFileExists{needspace.sty}{%
668 \RequirePackage{needspace}
669 }{%
670 \def\Needspace{\@ifstar\@gobble\@gobble}
671 }
672 % \end{macrocode}
673 %
674 % \subsubsection{Color and style definitions}
675 % \begin{macrocode}
676 \RequirePackage{xcolor}
677 \definecolor{macroimpl}{rgb}{0.0,0.0,0.4}
678 % \end{macrocode}
679 %
680 % \subsubsection{General Macros}
681 %
682 % \begin{macro}{\ydocwrite}
683 % \begin{macrocode}
684 \@ifundefined{ydocwrite}{%
685 \newwrite\ydocwrite
686 }{}
687 % \end{macrocode}
688 % \end{macro}
689 %
690 % \begin{macro}{\ydocfname}
691 % \begin{macrocode}
692 \@ifundefined{ydocfname}{%
693 \def\ydocfname{\jobname.cod}%
694 }{}
695 % \end{macrocode}
696 % \end{macro}
697 %
698 % \begin{macro}{\ydoc@catcodes}
699 % \begin{macrocode}
700 \def\ydoc@catcodes{%
701 \let\do\@makeother
702 \dospecials
703 \catcode`\\=\active
704 \catcode`\^^M=\active
705 \catcode`\ =\active
706 }
707 % \end{macrocode}
708 % \end{macro}
709 %
710 % \subsubsection{Handling Macrocode}
711 % \begin{environment}{macrocode}
712 % \begin{macrocode}
713 \def\macrocode{%
714 \par\noindent
715 \begingroup
716 \ydoc@catcodes
717 \macro@code
718 }
719 \def\endmacrocode{}
720 % \end{macrocode}
721 % \end{environment}
722 %
723 % \begin{macro}{\macro@code}[1]{verbatim macro code}
724 % \begin{macrocode}
725 \begingroup
726 \endlinechar\m@ne
727 \@firstofone{%
728 \catcode`\|=0\relax
729 \catcode`\(=1\relax
730 \catcode`\)=2\relax
731 \catcode`\*=14\relax
732 \catcode`\{=12\relax
733 \catcode`\}=12\relax
734 \catcode`\ =12\relax
735 \catcode`\%=12\relax
736 \catcode`\\=\active
737 \catcode`\^^M=\active
738 \catcode`\ =\active
739 }*
740 |gdef|macro@code#1^^M% \end{macrocode}(*
741 |endgroup|expandafter|macro@@code|expandafter(|ydoc@removeline#1|noexpand|lastlinemacro)*
742 )*
743 |gdef|ydoc@removeline#1^^M(|noexpand|firstlinemacro)*
744 |gdef|ydoc@defspecialmacros(*
745 |def^^M(|noexpand|newlinemacro)*
746 |def (|noexpand|spacemacro)*
747 |def\(|noexpand|bslashmacro)*
748 )*
749 |gdef|ydoc@defrevspecialmacros(*
750 |def|newlinemacro(|noexpand^^M)*
751 |def|spacemacro(|noexpand )*
752 |def|bslashmacro(|noexpand\)*
753 )*
754 |endgroup
755 % \end{macrocode}
756 % \end{macro}
757 %
758 % \begin{macro}{\macro@@code}[1]{verbatim macro code}
759 % \begin{macrocode}
760 \def\macro@@code#1{%
761 {\ydoc@defspecialmacros
762 \xdef\themacrocode{#1}}%
763 \PrintMacroCode
764 \end{macrocode}%
765 }
766 % \end{macrocode}
767 % \end{macro}
768 %
769 % \begin{macro}{\linenumberbox}
770 % \begin{macrocode}
771 \def\newlinemacro{\\\null}
772 \def\spacemacro{\ }
773 \def\bslashmacro{\char92}
774 \def\lastlinemacro{}
775 \def\firstlinemacro{\linenumberbox}
776 \def\newlinemacro{\\\linenumberbox}
777 \newcounter{linenumber}
778 \def\linenumberbox{%
779 \hbox to 1.25em{}%
780 \llap{%
781 \stepcounter{linenumber}%
782 {\footnotesize\color{gray}\thelinenumber~}%
783 }%
784 }
785 % \end{macrocode}
786 % \end{macro}
787 %
788 % \begin{macro}{\PrintMacroCode}
789 % \begin{macrocode}
790 \def\PrintMacroCode{%
791 \begingroup
792 \ttfamily
793 \noindent\themacrocode
794 \endgroup
795 }
796 % \end{macrocode}
797 % \end{macro}
798 %
799 % \begin{macro}{\PrintMacroCode}
800 % \begin{macrocode}
801 \RequirePackage{listings}
802 % \end{macrocode}
803 % \begin{macrocode}
804 \def\PrintMacroCode{%
805 \begingroup
806 \let\firstlinemacro\empty
807 \let\lastlinemacro\empty
808 \def\newlinemacro{^^J}%
809 \let\bslashmacro\bslash
810 \let\spacemacro\space
811 \immediate\openout\ydocwrite=\ydocfname\relax
812 \immediate\write\ydocwrite{\themacrocode}%
813 \immediate\closeout\ydocwrite
814 \@nameuse{ydoc@countbslashes}%
815 \ydoclistingssettings
816 \let\input\@input
817 \lstinputlisting{\ydocfname}%
818 \endgroup
819 }
820 % \end{macrocode}
821 % \end{macro}
822 %
823 % \begin{macrocode}
824 \lstdefinestyle{ydoccode}{%
825 language=[latex]tex,basicstyle=\ttfamily,
826 numbers=left,numberstyle=\tiny\color{gray},firstnumber=last,
827 breaklines,prebreak={\mbox{\tiny$\swarrow$}},
828 commentstyle=\color{black!60},
829 }%
830 % \end{macrocode}
831 %
832 % \begin{macro}{\ydoclistingssettings}
833 % \begin{macrocode}
834 \def\ydoclistingssettings{%
835 \lstset{style=ydoccode}%
836 }
837 % \end{macrocode}
838 % \end{macro}
839 %
840 % \begin{macro}{\macro@impl@args}[1]{number of macro arguments}
841 % \begin{macrocode}
842 \def\macro@impl@args[#1]{%
843 \begingroup
844 \parindent=10pt\relax
845 \let\macro@impl@argcnt\@tempcnta
846 \let\macro@impl@curarg\@tempcntb
847 \macro@impl@argcnt=#1\relax
848 \macro@impl@curarg=0\relax
849 \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
850 \expandafter\macro@impl@arg
851 \else
852 \expandafter\macro@impl@endargs
853 \fi
854 }
855 % \end{macrocode}
856 % \end{macro}
857 %
858 % \begin{macro}{\macro@impl@endargs}
859 % \begin{macrocode}
860 \def\macro@impl@endargs{%
861 \endgroup
862 \unskip\par\noindent\ignorespaces
863 }
864 % \end{macrocode}
865 % \end{macro}
866 %
867 % \begin{macro}{\macro@impl@argline}[2]{argument number}{argument description}
868 % \begin{macrocode}
869 \def\macro@impl@argline#1#2{%
870 \par{\texttt{\##1}:~#2\strut}%
871 }
872 % \end{macrocode}
873 % \end{macro}
874 %
875 % \begin{macro}{\macro@impl@arg}[1]{argument description}
876 % \begin{macrocode}
877 \def\macro@impl@arg#1{%
878 \advance\macro@impl@curarg by\@ne\relax
879 \macro@impl@argline{\the\macro@impl@curarg}{#1}%
880 \ifnum\macro@impl@curarg<\macro@impl@argcnt\relax
881 \expandafter\macro@impl@arg
882 \else
883 \expandafter\macro@impl@endargs
884 \fi
885 }
886 % \end{macrocode}
887 % \end{macro}
888 %
889 % \begin{environment}{macro}[1]{implemented macro}
890 % \begin{macrocode}
891 \def\macro#1{%
892 \PrintMacroImpl{#1}%
893 \@ifnextchar[%]
894 {\macro@impl@args}%
895 {}%
896 }
897 \def\endmacro{}
898 % \end{macrocode}
899 % \end{environment}
900 %
901 % \begin{environment}{key}[2]{key family}{key name}
902 % \begin{macrocode}
903 \def\key#1#2{%
904 \PrintMacroImpl{KV@#1@#2}%
905 \@ifnextchar[%]
906 {\macro@impl@args}%
907 {}%
908 }
909 \def\endkey{}
910 % \end{macrocode}
911 % \end{environment}
912 %
913 % \begin{environment}{environment}[1]{environment name}
914 % \begin{macrocode}
915 \def\environment#1{%
916 \PrintEnvImplName{#1}%
917 \@ifnextchar[%]
918 {\macro@impl@args}%
919 {}%
920 }
921 \def\endenvironment{}
922 % \end{macrocode}
923 % \end{environment}
924 %
925 %
926 % \begin{environment}{style}[1]{style name}
927 % \begin{macrocode}
928 \def\style#1{%
929 \PrintStyleImplName{#1}%
930 \@ifnextchar[%]
931 {\macro@impl@args}%
932 {}%
933 }
934 \def\endstyle{}
935 \def\PrintStyleImplName{\PrintEnvImplName}
936 % \end{macrocode}
937 % \end{environment}
938 %
939 % \begin{macro}{\PrintMacroImpl}[1]{macro (token)}
940 % \begin{macrocode}
941 \def\PrintMacroImpl#1{%
942 \par\bigskip\noindent
943 \Needspace*{3\baselineskip}%
944 \hbox{%
945 \edef\name{\expandafter\@gobble\string#1}%
946 \global\@namedef{href@impl@\name}{}%
947 \immediate\write\@mainaux{%
948 \global\noexpand\@namedef{href@impl@\name}{}%
949 }%
950 \raisebox{4ex}[4ex]{\hypertarget{impl:\name}{}}%
951 \hspace*{\descindent}\fbox{%
952 \hspace*{\descsep}%
953 \@ifundefined{href@desc@\name}{}{\hyperlink{desc:\name}}%
954 {\PrintMacroImplName{#1}}%
955 \hspace*{\descsep}%
956 }%
957 }%
958 \par\medskip\noindent
959 }
960 % \end{macrocode}
961 % \end{macro}
962 %
963 % \begin{macro}{\PrintMacroImplName}[1]{macro (token)}
964 % \begin{macrocode}
965 \def\PrintMacroImplName#1{%
966 \implstyle{\string#1\strut}%
967 }
968 % \end{macrocode}
969 % \end{macro}
970 %
971 % \begin{macro}{\PrintEnvImplName}[1]{environment name}
972 % test
973 % \begin{macrocode}
974 \def\PrintEnvImplName#1{%
975 \par\bigskip\noindent
976 \hbox{\hspace*{\descindent}\fbox{{\implstyle{#1}}}}%
977 \par\medskip
978 }
979 % \end{macrocode}
980 % \end{macro}
981 %
982 % \begin{macro}{\implstyle}
983 % \begin{macrocode}
984 \def\implstyle{\ttfamily\bfseries\color{macroimpl}}
985 % \end{macrocode}
986 % \end{macro}
987 %
988 % \begin{macro}{\bslash}
989 % Defines an expandable backslash with catcode 12: `\texttt{\bslash}$_{12}$'.
990 % The |\@firstofone| trick is used to read the |\gdef\bslash| code before changing the catcode.
991 % \begin{macrocode}
992 {%
993 \@firstofone{%
994 \catcode`\\=12
995 \gdef\bslash
996 }{\}
997 }%}
998 % \end{macrocode}
999 % \end{macro}
1000 % \iffalse
1001 %</ydoc-code.sty>
1002 % \fi
1003 %
1004 % \iffalse
1005 %<*ydoc-doc.sty>
1006 % \fi
1007 % \subsection{Provide \pkg{doc} macros}
1008 % \begin{macrocode}
1009 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
1010 \ProvidesPackage{ydoc-doc}[%
1011 %<!DATE>
1012 %<!VERSION>
1013 %<*DRIVER>
1014 2099/01/01 develop
1015 %</DRIVER>
1016 ydoc package to provide 'doc' macros]
1017 % \end{macrocode}
1018 %
1019 % \begin{macro}{\ydoc@countbslashes}
1020 % Reads the macro code into a temp box. The backslashes are defined to increase a counter.
1021 % \begin{macrocode}
1022 \newcount\ydoc@bslashcnt
1023 \def\ydoc@countbslashes{%
1024 \begingroup
1025 \let\firstlinemacro\empty
1026 \let\lastlinemacro\empty
1027 \let\newlinemacro\empty
1028 \let\spacemacro\empty
1029 \def\bslashmacro{\global\advance\ydoc@bslashcnt by\@ne}%
1030 \setbox\@tempboxa\hbox{\themacrocode}%
1031 \endgroup
1032 }
1033 % \end{macrocode}
1034 % \end{macro}
1035 %
1036 % \begin{macro}{\CheckSum}
1037 % \begin{macrocode}
1038 \def\CheckSum#1{%
1039 \gdef\ydoc@checksum{#1}%
1040 }
1041 \let\ydoc@checksum\m@ne
1042 % \end{macrocode}
1043 % \end{macro}
1044 %
1045 % \begin{macro}{\AlsoImplementation}
1046 % \begin{macro}{\OnlyDescription}
1047 % \begin{macro}{\StopEventually}
1048 % \begin{macro}{\Finale}
1049 % The first two macros modify the \cs{StopEventually} macro which either
1050 % stores its argument in \cs{Final} or executes it itself.
1051 % \begin{macrocode}
1052 \def\AlsoImplementation{%
1053 \gdef\StopEventually##1{%
1054 \@bsphack
1055 \gdef\Finale{##1\ydoc@checkchecksum}%
1056 \@esphack
1057 }%
1058 }
1059 \AlsoImplementation
1060 \def\OnlyDescription{%
1061 \@bsphack
1062 \long\gdef\StopEventually##1{##1\endinput}%
1063 \@esphack
1064 }
1065 \let\Finale\relax
1066 % \end{macrocode}
1067 % \end{macro}
1068 % \end{macro}
1069 % \end{macro}
1070 % \end{macro}
1071 %
1072 % \begin{macro}{\MakePercentComment}
1073 % \begin{macro}{\MakePercentIgnore}
1074 % \begin{macrocode}
1075 \def\MakePercentIgnore{\catcode`\%9\relax}
1076 \def\MakePercentComment{\catcode`\%14\relax}
1077 % \end{macrocode}
1078 % \end{macro}
1079 % \end{macro}
1080 %
1081 % \begin{macro}{\DocInput}
1082 % \begin{macrocode}
1083 \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
1084 % \end{macrocode}
1085 % \end{macro}
1086 %
1087 % \begin{macro}{\CharacterTable}
1088 % \begin{macrocode}
1089 \providecommand*\CharacterTable{%
1090 \begingroup
1091 \CharTableChanges
1092 \@CharacterTable
1093 }
1094 \def\@CharacterTable#1{%
1095 \def\ydoc@used@CharacterTable{#1}%
1096 \@onelevel@sanitize\ydoc@used@CharacterTable
1097 \ifx\ydoc@used@CharacterTable\ydoc@correct@CharacterTable
1098 \typeout{***************************}%
1099 \typeout{* Character table correct *}%
1100 \typeout{***************************}%
1101 \else
1102 \PackageError{ydoc}{Character table corrupted}
1103 {\the\wrong@table}
1104 \show\ydoc@used@CharacterTable
1105 \show\ydoc@correct@CharacterTable
1106 \fi
1107 \endgroup
1108 }
1109 \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J
1110 I now \string\show\space you both tables for comparison.}
1111 \newcommand*\CharTableChanges{}
1112 % \end{macrocode}
1113 % \end{macro}
1114 %
1115 % \begin{macro}{\ydoc@correct@CharacterTable}
1116 % \begin{macrocode}
1117 \def\ydoc@correct@CharacterTable
1118 {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
1119 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
1120 Digits \0\1\2\3\4\5\6\7\8\9
1121 Exclamation \! Double quote \" Hash (number) \#
1122 Dollar \$ Percent \% Ampersand \&
1123 Acute accent \' Left paren \( Right paren \)
1124 Asterisk \* Plus \+ Comma \,
1125 Minus \- Point \. Solidus \/
1126 Colon \: Semicolon \; Less than \<
1127 Equals \= Greater than \> Question mark \?
1128 Commercial at \@ Left bracket \[ Backslash \\
1129 Right bracket \] Circumflex \^ Underscore \_
1130 Grave accent \` Left brace \{ Vertical bar \|
1131 Right brace \} Tilde \~}
1132 \@onelevel@sanitize\ydoc@correct@CharacterTable
1133 %
1134 % \end{macrocode}
1135 % \end{macro}
1136 %
1137 % \begin{macro}{\DoNotIndex}
1138 % \begin{macrocode}
1139 \providecommand*\DoNotIndex[1]{%
1140 \PackageWarning{ydoc}{Ignoring DoNotIndex - not implemented yet!}{}{}%
1141 }
1142 % \end{macrocode}
1143 % \end{macro}
1144 %
1145 % \begin{macro}{\changes}
1146 % \begin{macrocode}
1147 \providecommand*\changes[3]{%
1148 \PackageWarning{ydoc}{Ignoring changes - not implemented yet!}{}{}%
1149 }
1150 % \end{macrocode}
1151 % \end{macro}
1152 %
1153 % \begin{macro}{\RecordChanges}
1154 % \begin{macrocode}
1155 \providecommand*\RecordChanges{%
1156 \PackageWarning{ydoc}{List of changes not implemented yet!}{}{}%
1157 }
1158 % \end{macrocode}
1159 % \end{macro}
1160 %
1161 % \begin{macro}{\PrintChanges}
1162 % \begin{macrocode}
1163 \providecommand*\PrintChanges{%
1164 \PackageWarning{ydoc}{List of changes not implemented yet!}{}{}%
1165 }
1166 % \end{macrocode}
1167 % \end{macro}
1168 %
1169 % \begin{macro}{\PrintIndex}
1170 % \begin{macrocode}
1171 \providecommand*\PrintIndex{%
1172 \PackageWarning{ydoc}{Code index not implemented yet!}{}{}%
1173 }
1174 % \end{macrocode}
1175 % \end{macro}
1176 %
1177 % \begin{macro}{\CodelineIndex}
1178 % \begin{macrocode}
1179 \providecommand*\CodelineIndex{%
1180 \PackageWarning{ydoc}{Code line index not implemented yet!}{}{}%
1181 }
1182 % \end{macrocode}
1183 % \end{macro}
1184 %
1185 % \begin{macro}{\EnableCrossrefs}
1186 % \begin{macrocode}
1187 \providecommand*\EnableCrossrefs{%
1188 \PackageWarning{ydoc}{Cross references not implemented yet!}{}{}%
1189 }
1190 % \end{macrocode}
1191 % \end{macro}
1192 %
1193 % \begin{macro}{\GetFileInfo}
1194 % Current implementation taken from \pkg{doc} package.
1195 % \begin{macrocode}
1196 \providecommand*\GetFileInfo[1]{%
1197 \def\filename{#1}%
1198 \def\@tempb##1 ##2 ##3\relax##4\relax{%
1199 \def\filedate{##1}%
1200 \def\fileversion{##2}%
1201 \def\fileinfo{##3}}%
1202 \edef\@tempa{\csname ver@#1\endcsname}%
1203 \expandafter\@tempb\@tempa\relax? ? \relax\relax
1204 }
1205 % \end{macrocode}
1206 % \end{macro}
1207 %
1208 % \begin{macro}{\ydoc@checkchecksum}
1209 % \begin{macrocode}
1210 \def\ydoc@checkchecksum{%
1211 \ifnum\ydoc@checksum=\m@ne
1212 \message{^^J}%
1213 \message{**********************^^J}%
1214 \message{* No checksum found! *^^J}%
1215 \message{**********************^^J}%
1216 \GenericWarning{No checksum found}{Correct checksum is \the\ydoc@bslashcnt^^J}{}{}%
1217 \else
1218 \ifnum\ydoc@checksum=\z@
1219 \message{^^J}%
1220 \message{*********************^^J}%
1221 \message{* Checksum disabled *^^J}%
1222 \message{*********************^^J}%
1223 \GenericWarning{Checksum disabled}{Correct checksum is \the\ydoc@bslashcnt^^J}{}{}%
1224 \else
1225 \ifnum\ydoc@checksum=\ydoc@bslashcnt
1226 \message{^^J}%
1227 \message{*******************^^J}%
1228 \message{* Checksum passed *^^J}%
1229 \message{*******************^^J}%
1230 \else
1231 \message{^^J}%
1232 \message{****************************^^J}%
1233 \message{* Checksum wrong (\ydoc@checksum<>\the\ydoc@bslashcnt) ^^J}%
1234 \message{****************************^^J}%
1235 \GenericError{Checksum wrong}{Correct checksum is \the\ydoc@bslashcnt^^J}{}{}%
1236 \fi
1237 \fi
1238 \fi
1239 }
1240 % \end{macrocode}
1241 % \end{macro}
1242 %
1243 % \begin{macrocode}
1244 \RequirePackage{shortvrb}
1245 \AtBeginDocument{\MakeShortVerb{\|}}
1246 % \end{macrocode}
1247 %
1248 % \begin{macrocode}
1249 \RequirePackage{url}
1250
1251 \def\package{\def\@package}
1252 \package{\jobname}
1253
1254 \def\bundle{\def\@bundle}
1255 \let\@bundle\@empty
1256
1257
1258 \def\ctanlocation{\def\@ctanlocation##1}
1259 \ctanlocation{https://www.ctan.org/pkg/#1}
1260
1261 \date{Version \fileversion\space -- \filedate}
1262
1263 \def\@homepage{%
1264 CTAN: \@ctan
1265 }
1266
1267 \def\@ctan{%
1268 \ydoc@eurl{\@ctanlocation{\ifx\@bundle\@empty\@package\else\@bundle\fi}}%
1269 }
1270
1271 \def\@texdoc{%
1272 \ydoc@eurl{https://texdoc.org/pkg/\ifx\@bundle\@empty\@package\else\@bundle\fi}%
1273 }
1274
1275 \let\@repository\@empty
1276 \protected\def\repository{\urldef\@repository\url}
1277 \protected\def\homepage{\urldef\@homepage\url}
1278 \protected\def\email{\hyper@normalise\email@}
1279 \def\email@#1{\def\@plainemail{#1}\def\@email{\hyper@linkurl{\Hurl{#1}}{mailto:#1}}}
1280 \let\@email\empty
1281 \let\@plainemail\empty
1282
1283 \let\@github\empty
1284 \protected\def\github{\def\@github}
1285
1286 \title{The \texorpdfstring{\pkgtitle{\@package}}{\@package} Package}
1287 \def\@bundlesubtitle{Part of the \texorpdfstring{\pkgtitle{\@bundle}}{\@bundle} bundle}
1288
1289 \protected\def\pkgtitle#1{%
1290 \texorpdfstring{\textsf{#1}}{#1}%
1291 }
1292
1293 \def\@begintitlelinks{%
1294 \vskip .5em
1295 \begingroup
1296 \large \lineskip .5em%
1297 \begin{tabular}[t]{rl}%
1298 }
1299
1300 \def\@endtitlelinks{%
1301 \end{tabular}%
1302 \par
1303 \endgroup
1304 }
1305
1306 \def\@maketitlelink#1#2{%
1307 #1: & #2\\[\medskipamount]
1308 }
1309
1310 \def\@license{%
1311 \@maketitlelink{License}{\href{https://www.latex-project.org/lppl/lppl-1-3c/}{LPPL v1.3c or later}}%
1312 }
1313
1314 \def\ydoc@eurl#1{{\edef\URL{{#1}}\expandafter\url\URL}}
1315
1316 \def\@maketitle{%
1317 \newpage
1318 \null\vskip 2em
1319 \begin{center}%
1320 \let\footnote\thanks
1321 {\LARGE \@title \par }\vskip 1.5em%
1322 \ifx\@bundle\@empty\else
1323 {\large \@bundlesubtitle \par }\vskip 1.5em%
1324 \fi
1325 {\large \lineskip .5em%
1326 \begin{tabular}[t]{c}%
1327 \@author
1328 \end{tabular}%
1329 \par}%
1330 \ifx\@plainemail\empty\else
1331 {\large \lineskip .5em%
1332 \begin{tabular}[t]{c}%
1333 \@email
1334 \end{tabular}%
1335 \par}%
1336 \fi
1337 \vskip 1em
1338 {\large \@date }%
1339 \vskip 1em
1340 \ifx\@github\@empty
1341 {\large \lineskip .5em%
1342 \begin{tabular}[t]{c}%
1343 \@homepage
1344 \end{tabular}%
1345 \par}%
1346 \vskip 1em
1347 \ifx\@repository\@empty\else
1348 {\large \lineskip .5em%
1349 \begin{tabular}[t]{c}%
1350 VC: \@repository
1351 \end{tabular}%
1352 \par}%
1353 \fi
1354 \else
1355 \@begintitlelinks
1356 \@license
1357 \@maketitlelink{CTAN}{\@ctan}%
1358 \@maketitlelink{Texdoc}{\@texdoc}%
1359 \@maketitlelink{Homepage}{\ydoc@eurl{https://github.com/\@github}}%
1360 \@maketitlelink{Repository}{\ydoc@eurl{https://github.com/\@github.git}}%
1361 \@maketitlelink{Issue tracker}{\ydoc@eurl{https://github.com/\@github/issues}}%
1362 \@endtitlelinks
1363 \fi
1364 \end{center}%
1365 \par\vskip 1em
1366 \aftergroup\ydocpdfsettings
1367 }
1368
1369 \ifpdf
1370 \def\ydocpdfsettings{%
1371 \hypersetup{%
1372 pdfauthor = {\@author\space<\@plainemail>},
1373 pdftitle = {\@title},
1374 pdfsubject = {Documentation of LaTeX package \@package},
1375 pdfkeywords = {\@package, LaTeX, TeX}
1376 }%
1377 }
1378 \else
1379 \let\ydocpdfsettings\empty
1380 \fi
1381
1382 \let\orig@maketitle\maketitle
1383 \def\maketitle{%
1384 \ydocpdfsettings
1385 \orig@maketitle
1386 \let\orig@maketitle\relax
1387 }
1388 % \end{macrocode}
1389 % \iffalse
1390 %</ydoc-doc.sty>
1391 % \fi
1392 %
1393 % \iffalse
1394 %<*ydoc-desc.sty>
1395 % \fi
1396 % \subsection{Description Macros and Environments}
1397 %
1398 % \begin{macrocode}
1399 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
1400 \ProvidesPackage{ydoc-desc}[%
1401 %<!DATE>
1402 %<!VERSION>
1403 %<*DRIVER>
1404 2099/01/01 develop
1405 %</DRIVER>
1406 ydoc package to describe macros, environments, options etc.]
1407 % \end{macrocode}
1408 %
1409 % \begin{macrocode}
1410 \IfFileExists{needspace.sty}{%
1411 \RequirePackage{needspace}
1412 }{%
1413 \def\Needspace{\@ifstar\@gobble\@gobble}
1414 }
1415 % \end{macrocode}
1416 %
1417 % The short verbatim code is required for the similar macros provided here.
1418 % \begin{macrocode}
1419 \RequirePackage{shortvrb}
1420 % \end{macrocode}
1421 %
1422 % The \pkg{etoolbox} package is used mainly for |\newrobustcmd|.
1423 % \begin{macrocode}
1424 \RequirePackage{etoolbox}
1425 % \end{macrocode}
1426 %
1427 % \subsubsection{Color and style definitions}
1428 % \begin{macrocode}
1429 \RequirePackage{xcolor}
1430 % \end{macrocode}
1431 % Define special no-op `none' color which does not change the color.
1432 % This is not yet tested and may break output files, but seems to work fine with PDF.
1433 % \begin{macrocode}
1434 \expandafter\def\csname\string\color@none\endcsname{%
1435 \xcolor@ {}{}{}{}
1436 }
1437 % \end{macrocode}
1438 % \begin{macrocode}
1439 \definecolor{macrodesc}{rgb}{0,0.2,0.6}
1440 \definecolor{keydesc}{rgb}{0,0.4,0.9}
1441 \definecolor{macroimpl}{rgb}{0,0.1,0.3}
1442 \definecolor{meta}{rgb}{0,0.25,0.75}
1443 \definecolor{scriptcolor}{rgb}{0.2,0.6,0.2}
1444 \definecolor{optioncolor}{rgb}{0.3.0.2,0}
1445 \colorlet{optional}{black!65!white}
1446 \colorlet{metaoptional}{optional!50!meta}
1447 \providecolor{urlcolor}{named}{blue}
1448 \providecolor{linkcolor}{named}{blue}
1449 \providecolor{filecolor}{named}{blue}
1450 \providecolor{citecolor}{named}{blue}
1451 \providecolor{anchorcolor}{named}{blue}
1452 \providecolor{menucolor}{named}{blue}
1453 \providecolor{runcolor}{named}{blue}
1454
1455 % \end{macrocode}
1456 %
1457 % \begin{macrocode}
1458 \RequirePackage{hyperref}
1459 \hypersetup{%
1460 colorlinks=true,
1461 pdfborder=0 0 0,
1462 pdfborderstyle={},
1463 urlcolor=urlcolor,
1464 linkcolor=linkcolor,
1465 filecolor=filecolor,
1466 citecolor=citecolor,
1467 anchorcolor=anchorcolor,
1468 menucolor=menucolor,
1469 runcolor=runcolor,
1470 }
1471
1472 % \end{macrocode}
1473 %
1474 % \subsubsection{Text Formatting Macros}
1475 %
1476 % \begin{macro}{\meta}
1477 % Prints \meta{meta text}.
1478 % \begin{macrocode}
1479 \newrobustcmd*\meta[1]{%
1480 {\metastyle{%
1481 \ensuremath\langle
1482 #1\/%
1483 \ensuremath\rangle
1484 }}%
1485 }
1486 % \end{macrocode}
1487 % \end{macro}
1488 %
1489 % \begin{macro}{\marg}
1490 % Sets style and adds braces.
1491 % The text is formatted as separate set of macro arguments.
1492 % \begin{macrocode}
1493 \newrobustcmd*{\marg}[1]{%
1494 {\margstyle{%
1495 {\ttfamily\braceleft}%
1496 \meta{#1}%
1497 {\ttfamily\braceright}%
1498 }}%
1499 }
1500 % \end{macrocode}
1501 % \end{macro}
1502 %
1503 % \begin{macro}{\oarg}
1504 % Sets style and adds brackets.
1505 % The text is formatted as separate set of macro arguments.
1506 % \begin{macrocode}
1507 \newrobustcmd*{\oarg}[1]{%
1508 {\oargstyle{%
1509 {\ttfamily[}%
1510 \meta{#1}%
1511 {\ttfamily]}%
1512 }}%
1513 }
1514 % \end{macrocode}
1515 % \end{macro}
1516 %
1517 % \begin{macro}{\parg}
1518 % Sets style and adds parentheses.
1519 % \begin{macrocode}
1520 \newrobustcmd*{\parg}[1]{%
1521 {\pargstyle{%
1522 {\ttfamily(}%
1523 \meta{#1}%
1524 {\ttfamily)}%
1525 }}%
1526 }
1527 % \end{macrocode}
1528 % \end{macro}
1529 %
1530 % \begin{macro}{\aarg}
1531 % Sets style and adds angles.
1532 % \begin{macrocode}
1533 \newrobustcmd*{\aarg}[1]{%
1534 {\aargstyle{%
1535 {\ttfamily<}%
1536 \meta{#1}%
1537 {\ttfamily>}%
1538 }}%
1539 }
1540 % \end{macrocode}
1541 % \end{macro}
1542 %
1543 % \begin{macro}{\sarg}
1544 % Prints star with given style.
1545 % \begin{macrocode}
1546 \newrobustcmd*{\sarg}{{\sargstyle{*}}}
1547 % \end{macrocode}
1548 % \end{macro}
1549 %
1550 % \begin{macro}{\pkg}
1551 % \begin{macro}{\cls}
1552 % \begin{macro}{\lib}
1553 % \begin{macro}{\env}
1554 % \begin{macro}{\opt}
1555 % \begin{macro}{\file}
1556 % \begin{macrocode}
1557 \newrobustcmd*\pkg[1]{{\pkgstyle{#1}}}
1558 \newrobustcmd*\cls[1]{{\clsstyle{#1}}}
1559 \newrobustcmd*\lib[1]{{\libstyle{#1}}}
1560 \newrobustcmd*\env[1]{{\envstyle{#1}}}
1561
1562 \newrobustcmd*\opt{\@ifstar\ys@opt\y@opt}
1563 \def\y@opt#1{{\optstyle{#1}}}
1564 \def\ys@opt#1{{\optstyle{#1}}\optpar{#1}}
1565 \newrobustcmd*\optpar[1]{\marginpar{\hbox to \marginparwidth{\hss\y@opt{#1}}}}
1566
1567 \newrobustcmd*\file[1]{{\filestyle{#1}}}
1568 \newcommand*\pkgstyle[1]{\texttt{\textcolor{pkg}{#1}}}
1569 \newcommand*\clsstyle[1]{\texttt{\textcolor{cls}{#1}}}
1570 \newcommand*\libstyle[1]{\texttt{\textcolor{lib}{#1}}}
1571 \newcommand*\envstyle[1]{\texttt{\textcolor{env}{#1}}}
1572 \newcommand*\optstyle[1]{\textsf{\textcolor{opt}{#1}}}
1573 \newcommand*\filestyle[1]{\texttt{\textcolor{file}{#1}}}
1574 \colorlet{cls}{none}
1575 \colorlet{lib}{none}
1576 \colorlet{env}{none}
1577 \colorlet{file}{none}
1578 \colorlet{pkg}{none}
1579 \definecolor{opt}{rgb}{0.5,0.16666,0}
1580 % \end{macrocode}
1581 % \end{macro}
1582 % \end{macro}
1583 % \end{macro}
1584 % \end{macro}
1585 % \end{macro}
1586 % \end{macro}
1587 %
1588 % \begin{macro}{\cs}
1589 % \begin{macro}{\cmd}
1590 % \begin{macrocode}
1591 \newrobustcmd*\cs[1]{\texttt{\textbackslash #1}}
1592 \newrobustcmd*\cmd[1]{\texttt{{\escapechar=92\string#1}}}
1593 % \end{macrocode}
1594 % \end{macro}
1595 % \end{macro}
1596 %
1597 % \begin{macro}{\Key}
1598 % \begin{macrocode}
1599 \newrobustcmd*\Key[1]{\PrintKeyName{#1}\MacroArgs}
1600 % \end{macrocode}
1601 % \end{macro}
1602 %
1603 % \subsubsection{Text Formatting Styles}
1604 %
1605 % \begin{macro}{\macrodescstyle}
1606 % Style of described macro names.
1607 % \begin{macrocode}
1608 \def\macrodescstyle{\ttfamily\bfseries\color{macrodesc}}
1609 % \end{macrocode}
1610 % \end{macro}
1611 %
1612 % \begin{macro}{\macrodescstyle}
1613 % Style of described macro names.
1614 % \begin{macrocode}
1615 \def\keydescstyle{\ttfamily\bfseries\color{keydesc}}
1616 % \end{macrocode}
1617 % \end{macro}
1618 %
1619 % \begin{macro}{\macroargsstyle}
1620 % Default style for macro arguments (e.g.\ \cs{MacroArgs}).
1621 % \begin{macrocode}
1622 \def\macroargsstyle{\ttfamily}
1623 % \end{macrocode}
1624 % \end{macro}
1625 %
1626 % \begin{macro}{\envcodestyle}
1627 % Default style for code body content in described environments.
1628 % \begin{macrocode}
1629 \def\envcodestyle{\ttfamily}
1630 % \end{macrocode}
1631 % \end{macro}
1632 %
1633 % \begin{macro}{\verbstyle}
1634 % Style for verbatim text inside macro argument list.
1635 % \begin{macrocode}
1636 \def\verbstyle{\verbatim@font}
1637 % \end{macrocode}
1638 % \end{macro}
1639 %
1640 % \begin{macro}{\metastyle}
1641 % Meta text style. Because \cs{macroargsstyle} might be also active a |\normalfont| reset
1642 % the font.
1643 % \begin{macrocode}
1644 \def\metastyle{\normalfont\itshape\color{meta}}
1645 % \end{macrocode}
1646 % \end{macro}
1647 %
1648 % \begin{macro}{\margstyle}
1649 % Style for \cs{marg}.
1650 % \begin{macrocode}
1651 \def\margstyle{}
1652 % \end{macrocode}
1653 % \end{macro}
1654 %
1655 % \begin{macro}{\Optional}
1656 % \begin{macro}{\optional}
1657 % \begin{macro}{\optionalstyle}
1658 % \begin{macrocode}
1659 \protected\def\Optional{\optionalon\optional}
1660 \def\optionalstyle{\blendcolors*{!60!white}\color{black!75}}
1661 % \end{macrocode}
1662 % \end{macro}
1663 % \end{macro}
1664 % \end{macro}
1665 %
1666 % \begin{macro}{\optionalon}
1667 % \begin{macro}{\optionaloff}
1668 % \begin{macrocode}
1669 \def\optionalon{\protected\def\optional{\optionalstyle}}
1670 \def\optionaloff{\let\optional\relax}
1671 \optionalon
1672 % \end{macrocode}
1673 % \end{macro}
1674 % \end{macro}
1675 %
1676 % \begin{macro}{\oargstyle}
1677 % Style for \cs{oarg}. A special color is set to show the `optional' status.
1678 % \begin{macrocode}
1679 \def\oargstyle{\optional}
1680 % \end{macrocode}
1681 % \end{macro}
1682 %
1683 % \begin{macro}{\pargstyle}
1684 % Style for \cs{parg}.
1685 % \begin{macrocode}
1686 \def\pargstyle{}
1687 % \end{macrocode}
1688 % \end{macro}
1689 %
1690 % \begin{macro}{\aargstyle}
1691 % Style for \cs{aarg}.
1692 % \begin{macrocode}
1693 \def\aargstyle{}
1694 % \end{macrocode}
1695 % \end{macro}
1696 %
1697 % \begin{macro}{\sargstyle}
1698 % Style for \cs{sarg}. A special color is set to show the `optional' status.
1699 % \begin{macrocode}
1700 \def\sargstyle{\ttfamily\color{optional}}
1701 % \end{macrocode}
1702 % \end{macro}
1703 %
1704 % \subsubsection{Dimension Registers}
1705 %
1706 % \begin{macro}{\descindent}
1707 % \begin{macrocode}
1708 \newdimen\descindent
1709 \descindent=-\parindent
1710 % \end{macrocode}
1711 % \end{macro}
1712 %
1713 % \begin{macro}{\beforedescskip}
1714 % \begin{macrocode}
1715 \newdimen\beforedescskip
1716 \beforedescskip=\bigskipamount
1717 % \end{macrocode}
1718 % \end{macro}
1719 %
1720 % \begin{macro}{\afterdescskip}
1721 % \begin{macrocode}
1722 \newdimen\afterdescskip
1723 \afterdescskip=\medskipamount
1724 % \end{macrocode}
1725 % \end{macro}
1726 %
1727 % \begin{macro}{\descsep}
1728 % Set to |1em| in |tt| font.
1729 % \begin{macrocode}
1730 \newdimen\descsep
1731 \begingroup
1732 \ttfamily
1733 \global\descsep=1em\relax
1734 \endgroup
1735 % \end{macrocode}
1736 % \end{macro}
1737 %
1738 %
1739 % \subsubsection{Macro Argument Reading Mechanism}
1740 %
1741 % \begin{macro}{\read@Macro@arg}
1742 % Reads next token and calls second macro.
1743 % \begin{macrocode}
1744 \def\read@Macro@arg{%
1745 \futurelet\@let@token\handle@Macro@arg
1746 }
1747 % \end{macrocode}
1748 % \end{macro}
1749 %
1750 % \begin{macro}{\AlsoMacro}
1751 % Reads argument while |@| is a letter,
1752 % prints the macro name and reads further arguments.
1753 % \begin{macrocode}
1754 \newcommand*\AlsoMacro{%
1755 \begingroup\makeatletter
1756 \AlsoMacro@
1757 }
1758 \def\AlsoMacro@#1{%
1759 \endgroup
1760 %<*DEBUG>
1761 %\typeout{DEBUG: Macro: \string#1}%
1762 %</DEBUG>
1763 \PrintMacroName{#1}%
1764 \read@Macro@arg
1765 }
1766 % \end{macrocode}
1767 % \end{macro}
1768 %
1769 % \begin{macro}{\ydoc@short@AlsoMacro}
1770 % Makes |&| an alias for |\AlsoMacro|.
1771 % \begin{macrocode}
1772 \begingroup
1773 \catcode`\|\active
1774 \gdef\ydoc@short@AlsoMacro{%
1775 \catcode`\|\active
1776 \let|\AlsoMacro
1777 }
1778 \endgroup
1779 % \end{macrocode}
1780 % \end{macro}
1781 %
1782 %
1783 % \begin{macro}{\ydoc@macrocatcodes}
1784 % Sets the catcodes inside for |read@Macro@arg| material.
1785 % \begin{macrocode}
1786 \def\ydoc@macrocatcodes{%
1787 \ydoc@short@AlsoMacro
1788 \@makeother\'%
1789 \@makeother\!%
1790 \@makeother\[%
1791 \@makeother\]%
1792 \@makeother\(%
1793 \@makeother\)%
1794 }
1795 % \end{macrocode}
1796 % \end{macro}
1797 %
1798 %
1799 % \begin{macro}{\handle@Macro@arg}
1800 % Checks if next token is the begin of a valid macro argument and calls
1801 % the appropriate read macro or the end macro otherwise.
1802 % \begin{macrocode}
1803 \def\handle@Macro@arg{%
1804 \expandafter\let\expandafter\handler\csname handle@Macro@token@\meaning\@let@token\endcsname
1805 \ifx\handler\relax
1806 \def\handler{\ifhmode\unskip\fi\end@Macro@args}%
1807 %<*DEBUG>
1808 % \typeout{DEBUG: Stopped at: \expandafter\meaning\csname @let@token\endcsname}%
1809 % \typeout{}%
1810 %\else
1811 %\expandafter\ifx\csname @let@token\endcsname\AlsoMacro
1812 % \typeout{DEBUG: TOKEN: \string\AlsoMacro}%
1813 %\else
1814 % \typeout{DEBUG: TOKEN: \expandafter\meaning\csname @let@token\endcsname}%
1815 %\fi
1816 %</DEBUG>
1817 \fi
1818 \handler
1819 }
1820 \def\define@Macro@handler{%
1821 \begingroup
1822 \ydoc@macrocatcodes
1823 \define@Macro@handler@
1824 }
1825 \def\define@Macro@handler@#1{%
1826 \endgroup
1827 \@namedef{handle@Macro@token@\meaning#1}%
1828 }
1829 % \end{macrocode}
1830 % \end{macro}
1831 %
1832 % \begin{macro}{\end@Macro@args}
1833 % Closes box as calls hook. Might be locally redefined by some
1834 % macros calling \cs{read@Macro@arg}.
1835 % \begin{macrocode}
1836 \def\end@Macro@args{%
1837 \y@egroup
1838 \after@Macro@args
1839 }
1840 % \end{macrocode}
1841 % \end{macro}
1842 %
1843 % \begin{macro}{\after@Macro@args}
1844 % Hook to add additional commands in certain situations.
1845 % \begin{macrocode}
1846 \def\after@Macro@args{%
1847 }
1848 % \end{macrocode}
1849 % \end{macro}
1850 %
1851 % \subsubsection*{Macro argument reading macros}
1852 % This macros read the macro arguments and call the appropriate format macros.
1853 %
1854 % \begin{macro}{\read@Macro@marg}
1855 % \begin{macrocode}
1856 \define@Macro@handler{\bgroup}{%
1857 \begingroup
1858 \afterassignment\read@Macro@marg@
1859 \let\@let@token=%
1860 }
1861 \def\read@Macro@marg@{%
1862 \bgroup
1863 \margstyle{}%
1864 \let\end@Macro@args\empty%
1865 {\ttfamily\braceleft}%
1866 \aftergroup\read@Macro@marg@@
1867 \read@Macro@arg
1868 }
1869 \def\read@Macro@marg@@{%
1870 {\ttfamily\braceright}%
1871 \endgroup
1872 \read@Macro@arg
1873 }
1874 % \end{macrocode}
1875 % \end{macro}
1876 %
1877 % \begin{macro}{\read@Macro@oarg}
1878 % \begin{macrocode}
1879 \define@Macro@handler{[}[{%
1880 \begingroup
1881 \let\read@Macro@oarg@end\read@Macro@oarg@@end
1882 \let\end@Macro@args\read@Macro@oarg@end
1883 \oargstyle{}%
1884 {\ttfamily[}%]
1885 \read@Macro@arg
1886 }
1887 \define@Macro@handler{]}{%
1888 \read@Macro@oarg@end
1889 }
1890 \def\read@Macro@oarg@@end#1]{%
1891 #1%
1892 {\ttfamily]}%
1893 \endgroup
1894 \read@Macro@arg
1895 }
1896 \def\read@Macro@oarg@end{\end@Macro@args}
1897 \let\read@Macro@aarg@end\read@Macro@oarg@end
1898 \let\read@Macro@parg@end\read@Macro@oarg@end
1899 % \end{macrocode}
1900 % \end{macro}
1901 %
1902 % \begin{macro}{\read@Macro@parg}
1903 % \begin{macrocode}
1904 \define@Macro@handler{(}({%
1905 \begingroup
1906 \let\read@Macro@parg@end\read@Macro@parg@@end
1907 \let\end@Macro@args\read@Macro@parg@end
1908 \pargstyle{}%
1909 {\ttfamily(}%)
1910 \read@Macro@arg
1911 }
1912 \define@Macro@handler{)}{%
1913 \read@Macro@parg@end
1914 }
1915 \def\read@Macro@parg@@end#1){%
1916 #1%
1917 {\ttfamily)}%
1918 \endgroup
1919 \read@Macro@arg
1920 }
1921 % \end{macrocode}
1922 % \end{macro}
1923 %
1924 % \begin{macro}{\read@Macro@aarg}
1925 % \begin{macrocode}
1926 \def\read@Macro@aarg<{%
1927 \begingroup
1928 \let\read@Macro@aarg@end\read@Macro@aarg@@end
1929 \let\end@Macro@args\read@Macro@aarg@end
1930 \aargstyle{}%
1931 {\ttfamily<}%
1932 \read@Macro@arg
1933 }
1934 \define@Macro@handler{>}{%
1935 \read@Macro@aarg@end
1936 }
1937 \def\read@Macro@aarg@@end#1>>{%
1938 #1%
1939 {\ttfamily>}%
1940 \endgroup
1941 \read@Macro@arg
1942 }
1943 % \end{macrocode}
1944 % \end{macro}
1945 %
1946 % \begin{macro}{\read@Macro@angle}
1947 % \begin{macrocode}
1948 \define@Macro@handler{<}<{%
1949 \futurelet\@let@token\read@Macro@angle@
1950 }
1951 % \end{macrocode}
1952 % \end{macro}
1953 %
1954 % \begin{macro}{\read@Macro@angle@}
1955 % \begin{macrocode}
1956 \def\read@Macro@angle@{%
1957 \ifx\@let@token<%
1958 \expandafter\read@Macro@aarg
1959 \else
1960 \expandafter\read@Macro@meta
1961 \fi
1962 }
1963 % \end{macrocode}
1964 % \end{macro}
1965 %
1966 % \begin{macro}{\read@Macro@meta}
1967 % \begin{macrocode}
1968 \def\read@Macro@meta#1>{%
1969 \meta{#1}\read@Macro@arg
1970 }
1971 % \end{macrocode}
1972 % \end{macro}
1973 %
1974 % \begin{macro}{\read@Macro@sarg}
1975 % \begin{macrocode}
1976 \define@Macro@handler**{%
1977 \sarg\read@Macro@arg
1978 }
1979 % \end{macrocode}
1980 % \end{macro}
1981 %
1982 % Allows `|=|' to be used directly without switching to verbatim
1983 % mode. This is especially useful for keys.
1984 % \begin{macrocode}
1985 \define@Macro@handler{=}={%
1986 =\read@Macro@arg
1987 }
1988 % \end{macrocode}
1989 %
1990 % \begin{macro}{\read@Macro@verb}
1991 % Sets up verbatim mode calls second macro.
1992 % \begin{macrocode}
1993 \define@Macro@handler{'}'{%
1994 \begingroup
1995 \let\do\@makeother
1996 \dospecials
1997 \@noligs
1998 \@makeother\'%
1999 \obeyspaces
2000 \read@Macro@verb@
2001 }
2002 % \end{macrocode}
2003 % \end{macro}
2004 %
2005 % \begin{macro}{\read@Macro@verb@}
2006 % Closes verbatim mode and formats text.
2007 % If |#1| is empty (|''|) than a single |'| is printed.
2008 % \begin{macrocode}
2009 \begingroup
2010 \@makeother\'%
2011 \gdef\read@Macro@verb@#1'{%
2012 \endgroup
2013 \ifx\relax#1\relax
2014 {\verbstyle{\string'}}%
2015 \else
2016 {%
2017 \frenchspacing
2018 \@noligs\verbstyle{#1}}%
2019 \fi
2020 \read@Macro@arg
2021 }
2022 \endgroup
2023 % \end{macrocode}
2024 % \end{macro}
2025 %
2026 % \begin{macro}{\read@Macro@cmds}
2027 % Simply executes given code.
2028 % \begin{macrocode}
2029 \define@Macro@handler!!#1!{%
2030 #1\relax
2031 \read@Macro@arg
2032 }
2033 % \end{macrocode}
2034 % \end{macro}
2035 %
2036 % \begin{macro}{\read@Macro@rmspace}
2037 % Removes space. The |\@firstofone| is used to preserve the space in the macro definition.
2038 % \begin{macrocode}
2039 \define@Macro@handler{\@sptoken} {%
2040 \read@Macro@arg
2041 }
2042 % \end{macrocode}
2043 % \end{macro}
2044 %
2045 % \begin{macro}{\read@Macro@addtoken}
2046 % Takes token over from input to output `stream'. This is used for |\space| and |~|.
2047 % \begin{macrocode}
2048 \define@Macro@handler{~}#1{%
2049 #1\read@Macro@arg
2050 }
2051 \AtBeginDocument{%
2052 \define@Macro@handler{~}#1{%
2053 #1\read@Macro@arg
2054 }
2055 }
2056 \define@Macro@handler{\space}#1{%
2057 #1\read@Macro@arg
2058 }
2059 % \end{macrocode}
2060 % \end{macro}
2061 %
2062 % \subsubsection{Description Macros}
2063 % \subsubsection*{For Macros}
2064 %
2065 % \begin{macro}{\DescribeMacro}
2066 % \begin{macrocode}
2067 \@ifundefined{DescribeMacro}{}{%
2068 \PackageInfo{ydoc-desc}{Redefining \string\DescribeMacro}{}%
2069 }
2070 % \end{macrocode}
2071 % A \cs{DescribeMacro} places itself in a \env{DescribeMacros} environment.
2072 % Multiple \cs{DescribeMacro} macros will stack themselves inside this environment.
2073 % For this to work \cs{DescribeMacros} is locally defined to |\y@egroup| to close the
2074 % |\hbox| from the previous \cs{DescribeMacro}.
2075 % \begin{macrocode}
2076 \def\DescribeMacro{%
2077 \DescribeMacros
2078 \let\DescribeMacros\y@egroup
2079 \optionalon
2080 \def\after@Macro@args{\endDescribeMacros}%
2081 \begingroup\makeatletter
2082 \Describe@Macro
2083 }
2084 % \end{macrocode}
2085 % \end{macro}
2086 %
2087 % \begin{macro}{\DescribeScript}
2088 % \begin{macrocode}
2089 \def\DescribeScript#1{%
2090 \DescribeMacros
2091 \let\DescribeMacros\y@egroup
2092 \optionalon
2093 \def\after@Macro@args{\endDescribeMacros}%
2094 \hbox\y@bgroup
2095 \texttt{#1}%
2096 \ydoc@macrocatcodes
2097 \macroargsstyle
2098 \read@Macro@arg~%
2099 }
2100 % \end{macrocode}
2101 % \end{macro}
2102 %
2103 % \begin{macro}{\DescribeKey}
2104 % \begin{macrocode}
2105 \def\DescribeKey{%
2106 \DescribeKeys
2107 \let\DescribeKeys\y@egroup
2108 \optionalon
2109 \def\after@Macro@args{\endDescribeKeys}%
2110 \begingroup\makeatletter
2111 \Describe@Macro
2112 }
2113 % \end{macrocode}
2114 % \end{macro}
2115 %
2116 % \begin{macro}{\Describe@Macro}
2117 % \begin{macrocode}
2118 \def\Describe@Macro#1{%
2119 \endgroup
2120 \edef\name{\expandafter\@gobble\string#1}%
2121 \global\@namedef{href@desc@\name}{}%
2122 \immediate\write\@mainaux{%
2123 \global\noexpand\@namedef{href@desc@\name}{}%
2124 }%
2125 \hbox\y@bgroup
2126 \@ifundefined{href@impl@\name}{}{\hyperlink{impl:\name}}%
2127 {%
2128 \hbox{\vbox to 0pt{\vss\hbox{\raisebox{4ex}{\hypertarget{desc:\name}{}}}}%
2129 \PrintMacroName{#1}}%
2130 }%
2131 \ydoc@macrocatcodes
2132 \macroargsstyle
2133 \read@Macro@arg
2134 }
2135 % \end{macrocode}
2136 % \end{macro}
2137 %
2138 % \begin{macro}{\MakeShortMacroArgs}
2139 % Defines the given character as short version for |\MacroArgs|.
2140 % It is first define to be a short verbatim character to take
2141 % advantage of the house-keeping (save \& restore of the original
2142 % catcode and definition) of |shortvrb|.
2143 %
2144 % The starred version define the character to act like |\Macro| instead.
2145 % \begin{macrocode}
2146 \newcommand*\MakeShortMacroArgs{%
2147 \@ifstar
2148 {\@MakeShortMacroArgs\Macro}%
2149 {\@MakeShortMacroArgs\MacroArgs}%
2150 }
2151 \def\@MakeShortMacroArgs#1#2{%
2152 \MakeShortVerb{#2}
2153 \catcode`#2\active
2154 \begingroup
2155 \catcode`\~\active
2156 \lccode`\~`#2\relax
2157 \lowercase{\endgroup\gdef~{\bgroup\let~\egroup#1}}%
2158 }
2159 % \end{macrocode}
2160 % \end{macro}
2161 %
2162 % \begin{macro}{\DeleteShortMacroArgs}
2163 % \begin{macrocode}
2164 \newcommand*\DeleteShortMacroArgs[1]{%
2165 \DeleteShortVerb{#1}%
2166 }
2167 % \end{macrocode}
2168 % \end{macro}
2169 %
2170 % \begin{macro}{\Macro}
2171 % Simply uses the two macros below.
2172 % \begin{macrocode}
2173 \newcommand*\Macro{\MacroArgs\AlsoMacro}
2174 % \end{macrocode}
2175 % \end{macro}
2176 %
2177 % \begin{macro}{\@Macro}
2178 % Alternative definition of \cs{Macro} inside \env{DescribeMacros} environments.
2179 % \begin{macrocode}
2180 \def\@Macro{%
2181 \begingroup\makeatletter
2182 \Describe@Macro
2183 }
2184 % \end{macrocode}
2185 % \end{macro}
2186 %
2187 % \begin{macrocode}
2188 \define@Macro@handler\AlsoMacro{}
2189 \define@Macro@handler\DescribeMacro{}
2190 \define@Macro@handler\DescribeKey{}
2191 \define@Macro@handler\DescribeScript{}
2192 % \end{macrocode}
2193 %
2194 % \begin{macro}{\MacroArgs}
2195 % Uses the normal macro argument reading mechanism from \cs{DescribeMacro}.
2196 % Instead of a box a simple group is added.
2197 % \begin{macrocode}
2198 \newcommand*\MacroArgs{%
2199 \begingroup
2200 \def\end@Macro@args{\endgroup\xspace}%
2201 \ydoc@macrocatcodes
2202 \macroargsstyle
2203 %<*DEBUG>
2204 %\typeout{}%
2205 %\typeout{DEBUG: Start MacroArgs}%
2206 %</DEBUG>
2207 \read@Macro@arg
2208 }
2209 \RequirePackage{xspace}
2210 % \end{macrocode}
2211 % \end{macro}
2212 %
2213 % \begin{macro}{\DescribeMacros}
2214 % \begin{macrocode}
2215 \def\DescribeMacros{%
2216 \begingroup
2217 \let\Macro\@Macro
2218 \parindent=0pt\relax
2219 \setbox\descbox\vbox\y@bgroup
2220 }
2221 % \end{macrocode}
2222 % \end{macro}
2223 %
2224 % \begin{macro}{\endDescribeMacros}
2225 % \begin{macrocode}
2226 \def\endDescribeMacros{%
2227 \y@egroup
2228 \PrintMacros
2229 \endgroup
2230 }
2231 % \end{macrocode}
2232 % \end{macro}
2233 %
2234 % \begin{macro}{\DescribeKeys}
2235 % \begin{macrocode}
2236 \def\DescribeKeys{%
2237 \begingroup
2238 \let\PrintMacroName\PrintKeyName
2239 \let\Key\@Macro
2240 \parindent=0pt\relax
2241 \setbox\descbox\vbox\y@bgroup
2242 }
2243 % \end{macrocode}
2244 % \end{macro}
2245 %
2246 % \begin{macro}{\endDescribeKeys}
2247 % \begin{macrocode}
2248 \def\endDescribeKeys{%
2249 \y@egroup
2250 \PrintKeys
2251 \endgroup
2252 }
2253 \def\PrintKeys{\PrintMacros}
2254 % \end{macrocode}
2255 % \end{macro}
2256 %
2257 % \begin{macro}{\DescribeMacrosTabcolsep}
2258 % \begin{macrocode}
2259 \def\DescribeMacrosTabcolsep{\tabcolsep}
2260 % \end{macrocode}
2261 % \end{macro}
2262 %
2263 % \begin{macro}{\DescribeMacrosTab}
2264 % \begin{macrocode}
2265 \def\DescribeMacrosTab{%
2266 \DescribeMacros
2267 \hbox\y@bgroup
2268 \tabcolsep=\DescribeMacrosTabcolsep\relax
2269 \DescribeMacrosTab@
2270 }
2271 \def\DescribeMacrosTab@#1{\tabular{@{}#1@{}}}
2272 % \end{macrocode}
2273 % \end{macro}
2274 %
2275 % \begin{macro}{\endDescribeMacrosTab}
2276 % \begin{macrocode}
2277 \def\endDescribeMacrosTab{%
2278 \endtabular\y@egroup
2279 \endDescribeMacros
2280 }
2281 % \end{macrocode}
2282 % \end{macro}
2283 %
2284 % \subsubsection*{For Lengths}
2285 %
2286 % \begin{macro}{\DescribeLength}
2287 % \begin{macrocode}
2288 \newcommand*\DescribeLength{%
2289 \begingroup
2290 \let\DescribeLength\Describe@Length
2291 \setbox\descbox\hbox\y@bgroup
2292 \tabular{@{}l@{\hspace{2em}}l@{}}%
2293 \Describe@Length
2294 }
2295 % \end{macrocode}
2296 % \end{macro}
2297 %
2298 % \begin{macro}{\Describe@Length}
2299 % \begin{macrocode}
2300 \newcommand*\Describe@Length[2]{%
2301 \PrintLengthName{#1}&
2302 (Default: {\macroargsstyle#2\unskip})%
2303 \@ifnextchar\DescribeLength
2304 {\\}%
2305 {%
2306 \endtabular
2307 \y@egroup
2308 \PrintLength
2309 \endgroup
2310 }%
2311 }
2312 % \end{macrocode}
2313 % \end{macro}
2314 %
2315 % \subsubsection*{For Environments}
2316 %
2317 % \begin{macro}{\DescribeEnv}
2318 % \begin{macrocode}
2319 \@ifundefined{DescribeEnv}{}{%
2320 \PackageInfo{ydoc-desc}{Redefining \string\DescribeEnv}{}%
2321 }
2322 \let\DescribeEnv\relax
2323 % \end{macrocode}
2324 % \begin{macrocode}
2325 \newcommand*\DescribeEnv[2][]{%
2326 \begingroup
2327 \def\DescribeEnv@name{#2}%
2328 \let\\\DescribeEnv@newline
2329 % \end{macrocode}
2330 %
2331 % Sets after-macro-arguments hook.
2332 % First checks if the environment or macro version was used.
2333 % The environment starts a new line only if the next token isn't |\end|,
2334 % which is taken as end of the environment.
2335 % \begin{macrocode}
2336 \ifx\@currenvir\DescribeEnv@string
2337 \def\after@Macro@args{%
2338 \let\after@Macro@args\empty
2339 \setbox\@tempboxa\hbox\y@bgroup
2340 \@ifnextchar\end{}%
2341 {\DescribeEnv@newline}%
2342 #1%
2343 }%
2344 % \end{macrocode}
2345 % The macro version adds the optional argument as content line if given.
2346 % \begin{macrocode}
2347 \else
2348 \ifx\relax#1\relax
2349 \def\after@Macro@args{%
2350 \y@bgroup
2351 \endDescribeEnv
2352 }%
2353 \else
2354 \def\after@Macro@args{%
2355 \setbox\@tempboxa\hbox\y@bgroup
2356 \DescribeEnv@newline\MacroArgs#1%
2357 \endDescribeEnv
2358 }%
2359 \fi
2360 \fi
2361 % \end{macrocode}
2362 % Start |\vbox| and adds first line.
2363 % \begin{macrocode}
2364 \setbox\descbox\vbox\y@bgroup
2365 \envcodestyle
2366 \let\PrintEnv\PrintSubEnv
2367 \hbox\y@bgroup
2368 \PrintEnvName{\begin}{\DescribeEnv@name}%
2369 \ydoc@macrocatcodes
2370 \macroargsstyle
2371 \read@Macro@arg
2372 }
2373 % \end{macrocode}
2374 % \end{macro}
2375 %
2376 % \begin{macro}{\DescribeEnv@newline}
2377 % Closes existing and starts a new horizontal box representing a indented line.
2378 % The optional argument allows to add extra space between lines like the normal |\\|.
2379 % Negative values are not supported.
2380 % \begin{macrocode}
2381 \newcommand*\DescribeEnv@newline[1][0pt]{%
2382 \strut\y@egroup
2383 {\vskip#1}%
2384 \hbox\y@bgroup\strut
2385 \hspace*{\descsep}%
2386 \ignorespaces
2387 }%
2388 % \end{macrocode}
2389 % \end{macro}
2390 %
2391 % \begin{macro}{\DescribeEnv@string}
2392 % Holds the environment name for comparison.
2393 % \begin{macrocode}
2394 \def\DescribeEnv@string{DescribeEnv}
2395 % \end{macrocode}
2396 % \end{macro}
2397 %
2398 % \begin{macro}{\descbox}
2399 % Save box to store description content.
2400 % \begin{macrocode}
2401 \newbox\descbox
2402 % \end{macrocode}
2403 % \end{macro}
2404 %
2405 % \begin{macro}{\endDescribeEnv}
2406 % \begin{macrocode}
2407 \def\endDescribeEnv{%
2408 \y@egroup
2409 \begingroup
2410 \setbox\@tempboxa\lastbox
2411 \ifcase0%
2412 \ifdim\wd\@tempboxa>\descsep1\fi
2413 \ifdim\ht\@tempboxa>\ht\strutbox1\fi
2414 \ifdim\dp\@tempboxa>\dp\strutbox1\fi
2415 \else
2416 \box\@tempboxa
2417 \fi
2418 \endgroup
2419 \hbox\y@bgroup
2420 \PrintEnvName{\end}{\DescribeEnv@name}
2421 \y@egroup
2422 \y@egroup
2423 \PrintEnv
2424 \endgroup
2425 }
2426 % \end{macrocode}
2427 % \end{macro}
2428 %
2429 %
2430 % \subsubsection{Print Macros}
2431 %
2432 % \begin{macro}{\PrintMacroName}
2433 % Formats macro name. The backslash is forced to |tt| font.
2434 % \begin{macrocode}
2435 \def\PrintMacroName#1{%
2436 {\macrodescstyle{\strut
2437 \texttt{\char92}%
2438 \escapechar\m@ne
2439 \string#1\strut}}%
2440 }
2441 % \end{macrocode}
2442 % \end{macro}
2443 %
2444 % \begin{macro}{\PrintKeyName}
2445 % Formats macro name. The backslash is forced to |tt| font.
2446 % \begin{macrocode}
2447 \def\PrintKeyName#1{%
2448 {\keydescstyle{\strut
2449 #1\strut}}%
2450 }
2451 % \end{macrocode}
2452 % \end{macro}
2453 %
2454 % \begin{macro}{\PrintLengthName}
2455 % Formats length register name.
2456 % \begin{macrocode}
2457 \let\PrintLengthName\PrintMacroName
2458 % \end{macrocode}
2459 % \end{macro}
2460 %
2461 %
2462 % \begin{macro}{\PrintEnvName}
2463 % |#1| = `|\begin|' or `|\end|', |#2| = env name.
2464 % \begin{macrocode}
2465 \def\PrintEnvName#1#2{%
2466 \strut
2467 \string#1\braceleft
2468 {\macrodescstyle#2\strut}%
2469 \braceright
2470 }
2471 % \end{macrocode}
2472 % \end{macro}
2473 %
2474 % \begin{macro}{\PrintMacros}
2475 % Prints macros described using \cs{DescribeMacros}.
2476 % The actual content was stored inside \cs{descbox}.
2477 % If it is wider than the line width it is centered.
2478 % \begin{macrocode}
2479 \def\PrintMacros{%
2480 \par\vspace\beforedescskip
2481 \begingroup
2482 \sbox\@tempboxa{\descframe{\usebox{\descbox}}}%
2483 \Needspace*{\dimexpr\ht\@tempboxa+3\baselineskip\relax}%
2484 \par\noindent
2485 \ifdim\wd\@tempboxa>\dimexpr\linewidth-2\descindent\relax
2486 \makebox[\linewidth][c]{\usebox\@tempboxa}%
2487 \else
2488 \hspace*{\descindent}%
2489 \usebox\@tempboxa
2490 \fi
2491 \endgroup
2492 \par
2493 \vspace\afterdescskip
2494 \par\noindent
2495 }
2496 \def\descframe#1{%
2497 \fbox{\hspace*{\descsep}#1\hspace*{\descsep}}%
2498 }
2499 % \end{macrocode}
2500 % \end{macro}
2501 %
2502 % \begin{macro}{\PrintLength}
2503 % Prints lengths registers described using one or multiple \cs{DescribeLength}.
2504 % \begin{macrocode}
2505 \let\PrintLength\PrintMacros
2506 % \end{macrocode}
2507 % \end{macro}
2508 %
2509 % \begin{macro}{\PrintEnv}
2510 % Prints \env{DescribeEnv} environments.
2511 % The actual content was stored inside \cs{descbox}.
2512 % \begin{macrocode}
2513 \let\PrintEnv\PrintMacros
2514 % \end{macrocode}
2515 % \end{macro}
2516 %
2517 % \begin{macro}{\PrintSubEnv}
2518 % Prints sub environments, i.e.\ \env{DescribeEnv} environments
2519 % inside the body of another \env{DescribeEnv}.
2520 % The actual content was stored inside \cs{descbox}.
2521 % \begin{macrocode}
2522 \def\PrintSubEnv{%
2523 \hbox{\hbox{\usebox{\descbox}}}%
2524 }
2525 % \end{macrocode}
2526 % \end{macro}
2527 %
2528 %
2529 % \subsubsection{Special Character Macros}
2530 %
2531 % \begin{macro}{\bslash}
2532 % Defines an expandable backslash with catcode 12: `\texttt{\bslash}$_{12}$'.
2533 % The |\@firstofone| trick is used to read the |\gdef\bslash| code before changing the catcode.
2534 % \begin{macrocode}
2535 {%
2536 \@firstofone{%
2537 \catcode`\\=12
2538 \gdef\bslash
2539 }{\}
2540 }%}
2541 % \end{macrocode}
2542 % \end{macro}
2543 %
2544 % \begin{macro}{\percent}
2545 % Defines an expandable percent character with catcode 12: `\percent$_{12}$'.
2546 % \begin{macrocode}
2547 \begingroup
2548 \catcode`\%=12
2549 \gdef\percent{%}
2550 \endgroup
2551 % \end{macrocode}
2552 % \end{macro}
2553 %
2554 % \begin{macro}{\braceleft}
2555 % \begin{macro}{\braceright}
2556 % Defines expandable left and right braces with catcode 12: `\texttt{\braceleft}$_{12}$' `\texttt{\braceright}$_{12}$'.
2557 % \begin{macrocode}
2558 \begingroup
2559 \catcode`\<=1
2560 \catcode`\>=2
2561 \catcode`\{=12
2562 \catcode`\}=12
2563 \gdef\braceleft <{>
2564 \gdef\braceright<}>
2565 \endgroup
2566 % \end{macrocode}
2567 % \end{macro}
2568 % \end{macro}
2569 %
2570 % \subsubsection{Other Macros}
2571 %
2572 % \begin{macro}{\y@bgroup}
2573 % \begin{macro}{\y@egroup}
2574 % These macros are used to begin and end |\vbox|/|\hbox|-es.
2575 % \begin{macrocode}
2576 \def\y@bgroup{\bgroup\color@setgroup}
2577 \def\y@egroup{\color@endgroup\egroup}
2578 % \end{macrocode}
2579 % \end{macro}
2580 % \end{macro}
2581 %
2582 % \begin{macro}{\codeline}
2583 % \begin{macrocode}
2584 \newcommand*{\codeline}[1][c]{%
2585 \codelinebefore
2586 \hbox to \hsize\bgroup
2587 \ifx i#1\hspace*{\leftmargin}\else
2588 \ifx l#1\else\hss\fi
2589 \fi
2590 \let\xspace\relax
2591 \hbox\bgroup
2592 \aftergroup\codeline@end
2593 \aftergroup#1%
2594 \afterassignment\MacroArgs
2595 \let\@let@token=%
2596 }
2597 \def\codeline@end#1{%
2598 \ifx r#1\else\hss\fi
2599 \egroup
2600 \codelineafter
2601 }
2602 \newcommand*\codelinebefore{\par\smallskip\noindent}
2603 \newcommand*\codelineafter {\par\smallskip\noindent}
2604 % \end{macrocode}
2605 % \end{macro}
2606 %
2607 % \begin{environment}{codequote}
2608 % \begin{macrocode}
2609 \newenvironment{codequote}{%
2610 \def\\{\newline\relax\MacroArgs}%
2611 \par\smallskip\bgroup\leftskip=\leftmargin\rightskip=\rightmargin\noindent\MacroArgs}
2612 {\par\egroup\smallskip\noindent\ignorespacesafterend}
2613 % \end{macrocode}
2614 % \end{environment}
2615 %
2616 % \begin{environment}{macroquote}
2617 % \begin{macrocode}
2618 \newenvironment{macroquote}{%
2619 \def\\{\newline\relax\Macro}%
2620 \par\smallskip\bgroup\leftskip=\leftmargin\rightskip=\rightmargin\noindent\Macro}
2621 {\par\egroup\smallskip\noindent\ignorespacesafterend}
2622 % \end{macrocode}
2623 % \end{environment}
2624 % \iffalse
2625 %</ydoc-desc.sty>
2626 % \fi
2627 %
2628 % \iffalse
2629 %<*ydoc-expl.sty>
2630 % \fi
2631 % \subsection{Include Code Examples}
2632 %
2633 % \begin{macrocode}
2634 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
2635 \ProvidesPackage{ydoc-expl}[%
2636 %<!DATE>
2637 %<!VERSION>
2638 %<*DRIVER>
2639 2011/08/11 develop
2640 %</DRIVER>
2641 ydoc package to insert live examples of LaTeX code]
2642 % \end{macrocode}
2643 %
2644 % \iffalse
2645 %<*dontinclude>
2646 % \begin{macrocode}
2647 \newcounter{example}
2648 \def\examplename{Example}
2649 \newenvironment{example}[1]{%
2650 \par\bigskip\noindent
2651 \centerline{\examplename~\refstepcounter{example}\theexample: #1}%
2652 \smallskip
2653 \hrule
2654 \smallskip
2655 }{%
2656 \smallskip
2657 \hrule
2658 \par\bigskip
2659 }
2660 % \end{macrocode}
2661 %
2662 % \begin{macro}{\PrintExample}
2663 % \begin{macrocode}
2664 \def\PrintExample{%
2665 \usebox\examplecodebox
2666 \hfill
2667 \usebox\exampleresultbox
2668 }
2669 % \end{macrocode}
2670 % \end{macro}
2671 %</dontinclude>
2672 % \fi
2673 %
2674 % \begin{macrocode}
2675 \RequirePackage{listings}
2676 \lst@RequireAspects{writefile}
2677 \def\ydoc@exafile{\jobname.exa}
2678 % \end{macrocode}
2679 %
2680 % \begin{style}{examplecode}
2681 % \begin{macrocode}
2682 \lstdefinestyle{examplecode}{%
2683 language=[latex]tex,
2684 basicstyle=\ttfamily,
2685 columns=fullflexible,
2686 numbers=left,
2687 firstnumber=1,
2688 numberstyle=\tiny\color{gray}\sffamily,
2689 numbersep=5pt,
2690 breaklines,prebreak={\mbox{\tiny$\swarrow$}},
2691 commentstyle=\color{black!60},
2692 }%
2693 % \end{macrocode}
2694 % \end{style}
2695 %
2696 % \begin{style}{exampleresult}
2697 % \begin{macrocode}
2698 \lstdefinestyle{exampleresult}{%
2699 firstnumber=1,
2700 gobble=0,
2701 basicstyle=\ttfamily,
2702 columns=fullflexible,
2703 commentstyle=\color{black!60},
2704 }
2705 % \end{macrocode}
2706 % \end{style}
2707 %
2708 % \begin{style}{exampleextract}
2709 % \begin{macrocode}
2710 \lstdefinestyle{exampleextract}{gobble=4}%
2711 % \end{macrocode}
2712 % \end{style}
2713 %
2714 % \begin{macrocode}
2715 \newbox\examplecodebox
2716 \newbox\exampleresultbox
2717 % \end{macrocode}
2718 %
2719 % \begin{macro}{\BoxExample}
2720 % \begin{macrocode}
2721 \def\BoxExample{%
2722 \setbox\examplecodebox\hbox{\color@setgroup
2723 \lstinputlisting[style=examplecode,style=thisexampleprint]%
2724 {\ydoc@exafile}%
2725 \unskip\color@endgroup}%
2726 \setbox\exampleresultbox\hbox{\color@setgroup
2727 \lstset{style=exampleresult}%
2728 \@@input\ydoc@exafile\relax
2729 \unskip\color@endgroup}%
2730 }
2731 % \end{macrocode}
2732 % \end{macro}
2733 %
2734 % \begin{macro}{\PrintExample}
2735 % \begin{macrocode}
2736 %<*DISABLED>
2737 \RequirePackage{showexpl}
2738 \def\PrintExample{%
2739 \begingroup
2740 \lstset{style=examplecode}%
2741 \MakePercentComment
2742 \LTXinputExample[varwidth]{\ydoc@exafile}%
2743 \endgroup
2744 }
2745 %</DISABLED>
2746 % \end{macrocode}
2747 % \end{macro}
2748 %
2749 %
2750 %
2751 % \begin{macro}{\PrintExample}
2752 % \begin{macrocode}
2753 \def\PrintExample{%
2754 \begingroup
2755 \BoxExample
2756 \@tempdima=\textwidth
2757 \advance\@tempdima by -\wd\examplecodebox\relax
2758 \advance\@tempdima by -\wd\exampleresultbox\relax
2759 \advance\@tempdima by -15pt\relax
2760 \ifdim\@tempdima>\bigskipamount
2761 \hbox to \textwidth{%
2762 \null\hss
2763 \minipage[c]{\wd\exampleresultbox}\fbox{\usebox\exampleresultbox}\endminipage
2764 \hfill\hfill\hskip\bigskipamount\hskip15pt\hfill\hfill
2765 \minipage[c]{\wd\examplecodebox}\usebox\examplecodebox\endminipage
2766 \hss\null
2767 }%
2768 \else
2769 \vbox{%
2770 \centerline{\fbox{\usebox\exampleresultbox}}%
2771 \vspace{\bigskipamount}%
2772 \centerline{\usebox\examplecodebox}%
2773 }%
2774 \fi
2775 \endgroup
2776 }
2777 % \end{macrocode}
2778 % \end{macro}
2779 %
2780 % \begin{environment}{examplecode}
2781 % \begin{macrocode}
2782 \lstnewenvironment{examplecode}[1][]{%
2783 \lstdefinestyle{thisexampleprint}{#1}%
2784 \setbox\@tempboxa\hbox\bgroup
2785 \lstset{style=exampleextract,#1}%
2786 \lst@BeginWriteFile{\ydoc@exafile}%
2787 }
2788 {%
2789 \lst@EndWriteFile
2790 \egroup
2791 \begingroup
2792 \MakePercentComment
2793 \catcode`\^^M=5\relax
2794 \PrintExample
2795 \endgroup
2796 }
2797 % \end{macrocode}
2798 % \end{environment}
2799 %
2800 % \begin{macrocode}
2801 \RequirePackage{float}
2802 % \end{macrocode}
2803 %
2804 % \begin{environment}{example}
2805 % \begin{macrocode}
2806 \floatstyle{plain}
2807 \newfloat{example}{tbhp}{loe}
2808 \floatname{example}{\examplename}
2809 \def\examplename{Example}
2810 % \end{macrocode}
2811 % \end{environment}
2812 %
2813 % \begin{environment}{exampletable}
2814 % \begin{macrocode}
2815 \newenvironment{exampletable}{%
2816 \floatstyle{plaintop}%
2817 \restylefloat{example}%
2818 \example
2819 }{\endexample}
2820 % \end{macrocode}
2821 % \end{environment}
2822 % \iffalse
2823 %</ydoc-expl.sty>
2824 % \fi
2825 %
2826 % \iffalse
2827 %<*ydocincl.tex>
2828 % \fi
2829 %
2830 % \begin{macrocode}
2831 \expandafter\ifx\csname ydocinclversion\endcsname\relax\else
2832 \endinput
2833 \fi
2834
2835 \chardef\ydocinclversion=1
2836
2837 \newread\inFile
2838 \newread\subFile
2839 \newwrite\outFile
2840 \newif\ifContinue
2841 \newlinechar=`^^J
2842
2843 \def\makeOther#1{\catcode`#1=12\relax}
2844
2845 \let\inLine\relax
2846 \let\lastLine\relax
2847
2848 \def\includefiles#1#2{%
2849 \begingroup
2850 \immediate\openin\inFile#1\relax
2851 \immediate\openout\outFile#2\relax
2852 \makeOther\@%
2853 \makeOther\ \makeOther\\\makeOther\$%
2854 \makeOther\#\makeOther\^\makeOther\^^K%
2855 \makeOther\_\makeOther\^^A\makeOther\%%
2856 \makeOther\~\makeOther\{\makeOther\}\makeOther\&%
2857 \endlinechar-1\relax
2858 \Continuetrue
2859 \loop
2860 \let\lastLine\inLine
2861 \read\inFile to\inLine
2862 \ifeof\inFile
2863 \Continuefalse
2864 \else
2865 \expandafter\checkLine\inLine\empty\empty\empty\endLine
2866 \fi
2867 \ifContinue
2868 \repeat
2869 \immediate\closein\inFile
2870 \immediate\closeout\outFile
2871 \endgroup
2872 \end
2873 }
2874
2875 \def\copyline{%
2876 \immediate\write\outFile{\inLine}%
2877 }
2878
2879 \chardef\percentcharnum=`\%
2880
2881 \begingroup
2882 \makeOther\%\makeOther\@\relax
2883 \gdef\SubFileOptionString{%<@}\relax
2884 \gdef\CommentChar{%}\relax
2885 \catcode`\|=0
2886 \makeOther\ \makeOther\\|relax
2887 |gdef|IfFalseString{% \iffalse}|relax
2888 |gdef|FiString{% \fi}|relax
2889 |endgroup
2890
2891 \def\checkLine#1#2#3#4\endLine{%
2892 \def\firstthree{#1#2#3}%
2893 \ifx\firstthree\SubFileOptionString
2894 \readSubFile#4\endLine
2895 \else
2896 \copyline
2897 \fi
2898 }
2899
2900 \def\readSubFile#1>#2\endLine{%
2901 \immediate\openin\subFile=#1\relax
2902 \ifeof\subFile
2903 % File not found
2904 \else
2905 \message{^^JIncluding subfile '#1'^^J}%
2906 \immediate\write\outFile{\CommentChar<*#1>}%
2907 \ifx\lastLine\IfFalseString
2908 \immediate\write\outFile{\FiString}%
2909 \fi
2910 \copySubFile
2911 \ifx\lastLine\IfFalseString
2912 \immediate\write\outFile{\IfFalseString}%
2913 \fi
2914 \immediate\write\outFile{\CommentChar</#1>}%
2915 \fi
2916 \immediate\closein\subFile
2917 }
2918
2919 \def\copySubFile{%
2920 \read\subFile to\subLine
2921 \ifeof\subFile\else
2922 \immediate\write\outFile{\subLine}%
2923 \expandafter\copySubFile
2924 \fi
2925 }
2926 % \end{macrocode}
2927 %
2928 % \iffalse
2929 %</ydocincl.tex>
2930 % \fi
2931 %
2932 % \Finale
2933 % \endinput