The
ydoc
Class and Packages
Martin Scharrer
martin@scharrer.de
CTAN:
http://www.ctan.org/pkg/ydoc
VC:
https://bitbucket.org/martin_scharrer/ydoc/
Version
AbstractThis package bundle is currently under development. All functionality, set-tings and macro as well as file names can change in later versions and may be incomplete! It is not ready yet to be used for other packages.
Theydocclass and packages provide macros to document the functionality and implementation of LATEX classes and packages. It is similar to theltxdoc class with thedocpackage, but uses more modern features/packages by default (e.g.xcolor,hyperref,listings). However, some of the features like code indexing is not yet included.
1 Introduction
Theydocpackages allow the documentation of LATEX packages and classes. The name stands for “Y et another Documentation Package” and is a pun on the fact that there are several documentation packages written by package developers to document their own packages. All these packages didn’t suited the author and therefore he, take a guess, wrote his own documentation package. It (will) support(s) all macros and environments (but not necessary with full/identical features) provided by thedoc package to allow the fast adaption of existing.dtxfiles.
This documentation uses theydocpackages itself and therefore also acts as a live example.
1.1
ydoc
Files
1.2 Similar Packages
Other documentation related classes and packages are ltxdoc,doc, dox,xdoc, gmdoc,pauldoc,hypdoc,codedoc,nicetextandtkz-doc.
2 Usage
(section incomplete)
2.1 Code Documentation Environments
\begin{macro}{〈macro〉}[〈# of args〉]{〈arg 1 description〉}...{〈arg n description〉}
〈macro documentation〉 \begin{macrocode} 〈macro code〉 \end{macrocode} ... \end{macro}
The implementation of macros can be documented using this environment. The actual〈macro code〉must be placed in amacrocodeenvironment. Longer macro definition can be split using multiplemacrocodeenvironments with interleaved documentation texts.
Theydocdefinition of themacroenvironment has an additional feature compare todoc. The arguments of the macro (#1,#2, . . . ) can be documented in a vertical list. The environment has an optional argument to declare the〈number of arguments〉
the macro implementation has. The descriptions of this macro arguments are read from the next arguments of the environment. If the〈number of arguments〉is not given or zero (or less) no further arguments are read by themacroenvironment.
\begin{macrocode}
〈macro code〉
\end{macrocode}
This environment wraps around any TEX code and types it verbatim. The environ-ment end is read verbatim as well and must be written on a separate line beginning with a percent followed by exactly four spaces: ‘%␣␣␣␣\end{macrocode}’.
\begin{environment}{〈name〉}[〈# of args〉]{〈arg 1 description〉}...{〈arg n description〉}
〈environment documentation〉 \begin{macrocode} 〈macro code〉 \end{macrocode} ... \end{environment}
2.2 Description Macros and Environments
\DescribeMacro〈\macro〉〈macro arguments〉
The\DescribeMacrois used to describe macros included their arguments. It takes the to be described〈\macro〉as first argument (can also be enclosed in{ }). The macro name can include ‘@’. Any number of〈macro arguments〉(in a broad sense, see Table1) following it are formatted as arguments of this macro. Any following non-argument token (normal text, macro, etc.) will make\DescribeMacrostop collecting arguments. For example, if a TEX group should be started using{ }direct after\DescribeMacroa\relax(or a similar macro) should be inserted between them, otherwise the group will be taken as mandatory argument of the described macro.
Multiple\DescribeMacroin a row will automatically stacked inside one framed box. If this is not wanted simply separate them with\relaxor any other macro or token. See also theDescribeMacrosenvironment below.
Examples:
\DescribeMacro\mymacro*[<optional>]{<meta text>}will result in
\mymacro*[〈optional〉]{〈meta text〉}(inside a framed box).
The above syntax description of\DescribeMacroitself was typeset with
\DescribeMacro\DescribeMacro<\textbackslash macro><macro arguments>. Special macros with have a partner macro as end marker can be typeset like this: \DescribeMacro\csname<text>\AlsoMacro\endcsname, which will result in
\csname〈text〉\endcsname.
\Macro〈\macro〉〈macro arguments〉
This macro is like an in-text version of\DescribeMacro. The macro description stays as part of the surrounding text and is not placed inside a framed box. The description can be broken between lines. This can be avoided by placing it inside a \mbox{}.\Macrois equivalent to\MacroArgs\AlsoMacro.
\MacroArgs〈macro arguments〉
This macro formats the〈macro arguments〉the same way as\DescribeMacroand \Macrobut without a macro name. Like\Macrothe description is placed in-text.
\AlsoMacro〈\macro〉〈further macro arguments〉
Examples:
\Macro\@for<\textbackslash var> ’:=’ <list> \AlsoMacro\do {<code>}
\@for〈\var〉:=〈list〉\do{〈code〉}
\Macro\pgfkeys{<key1>’=’<value1>’,’<key2>’/.code=’{<code>}}
\pgfkeys{〈key1〉=〈value1〉,〈key2〉/.code={〈code〉}}
\MakeShortMacroArgs*{〈char〉}
This macro is similar to\MakeShortVerbfrom theshortvrbpackage. It can be used to globally define one character to act like\MacroArgstill the same character is discovered again. Special characters must be escaped with an backslash for the definition. One additional benefit beside the shorter size is that the argument list is automatically terminated. For example\MakeShortMacroArgs{\"}will make ‘"<arg>{<arg>}"’ act like ‘\MacroArgs<arg>{<arg>}\relax’. One side-effect is that should the argument list be terminated, e.g. by an unknown element or macro, then the rest of the text till the end-character is typeset as normal, but inside a group.
The starred version will define the character equal to\Macroinstead.
\DeleteShortMacroArgs{〈char〉}
Globally removes the special meaning from〈char〉given to him by\MakeShortMacroArgs. Note that special characters like‘are best defined \AtBeginDocumentand deleted again\AtEndDocumentto avoid issues if they are written to theauxfile by some package. \begin{DescribeMacros} \Macro〈\name〉〈arguments〉 \Macro〈\name〉〈arguments〉 ... \end{DescribeMacros}
This environment can be used to place multiple macro description into the same framed box. The macros are described using\Macro, which has a slightly different definition than outside of this environment, to place the description into a\hbox. The environment stacks these\hboxes in a\vbox. The macros can also be placed freely using anything which produces a\hbox, e.g.\hbox{\Macro\A ~~~ \Macro\B} or using atabular(see alsoDescribeMacrosTab).
\begin{DescribeMacrosTab}{〈tabular column definition〉}
〈tabular content〉
\end{DescribeMacrosTab}
Table 1: Supported ‘arguments’ for\DescribeMacro/\DescribeEnv/\MacroArgs.
Description Syntax Result Macroa
Meta text <text> 〈text〉 \meta{〈text〉}
Mandatory Argument {args} {args}
—, with meta text {<text>} {〈text〉} \marg{〈text〉}
Optional Argument [args] [args]
—, with meta text [<text>] [〈text〉] \oarg{〈text〉}
Picture Argument (args) (args)
—, with meta text (<text>) (〈text〉) \parg{〈text〉} Beamer Overlay Argument <<args>> <args>
—, with meta text << <text> >> <〈text〉> \aarg{〈text〉}
Star * *
Verbatim content ’$&^%_#$\’ $&^%_#$\
—, produce’char ’’ ’
Insert any TEX code !\fbox{T}! T
Unbreakable Space ~
Space (explicit macro) \space
Second macro (e.g. endmarker) \AlsoMacro\macro \macro
short version: |\macro \macro a) As alternative to be used inside normal text.
Note that ‘args’ can itself be further macro arguments except true verbatim.
\begin{DescribeEnv}{〈name〉}〈arguments〉 〈body content〉 \\
〈more body content〉
\end{DescribeEnv}
\DescribeEnv[〈body content〉]{〈name〉}〈arguments〉
TheDescribeEnvcan be used to describe environments in the same way the\DescribeMacro macro describes macros. Supported〈arguments〉are shown in Table1. Potential
〈body content〉can be placed between the begin and end of the environment de-scription to explain the user what kind of material should be placed inside it. The environment also exists in macro form as\DescribeEnv, which allows to provide small〈body content〉as an optional argument. Please note that for this optional argument a\MacroArgsis automatically inserted, but not for the\DescribeEnv environment content.
\DescribeLength〈\name〉{〈default value〉}
This macro can be used to describe LATEX lengths also known as dimensions. Multiple \DescribeLengthmacros in a row will automatically be grouped.
2.3 Format Macros
\cs{〈macro name〉} \env{〈environment name〉}
\pkg{〈package name〉} \cls{〈class name〉}
This macros can be used to format names of macros, environments, packages and classes, respectively. At the moment they simply use\texttt.
\bslash \percent \braceleft \braceright
This macros define expandable backslash (\12), percent char (%12), and left ({12) and right (}12) braces with catcode 12 (other), respectively. They should only be used with text-typer font when used in text, because other fonts might not have the correct characters. The macros must be protected when used in a moving argument.
\meta{〈meta text〉} \marg{〈argument text〉}
\oarg{〈argument text〉} \parg{〈argument text〉}
\aarg{〈argument text〉} \sarg
This macros allow to typeset meta text and mandatory, optional, picture and beamer overlay arguments as well as a star symbol. They are used internally by\MacroArgs and friends. See Table1for examples.
\metastyle \margstyle \oargstyle \pargstyle \aargstyle \sargstyle
This macros are used to define the style in which the corresponding macros above are being formatted. They are used like{〈\stylemacro〉{〈material〉}}to allow the styles to use macros like\ttfamilyor\texttt{〈material〉}. By default the optional argument and the also optional star are printed in the color ‘optional’ which is a 65% gray.
2.4 Settings
The following macro and dimensions can be redefined by the user to adjust the layout of the package documentation.
\descindent (Default:-20pt)
\beforedescskip (Default: 12pt plus 4pt minus 4pt)
\afterdescskip (Default: 6pt plus 2pt minus 2pt)
\descsep (Default:1em in tt font = 10.5pt)
This macro defines the space on the left and right side between the description text and the framed box.
2.5 Macros and Environments to include LaTeX Code Examples
\begin{example} \end{example}
\begin{examplecode} \end{examplecode}
3 Implementation
3.1 Class File
1 \ N e e d s T e X F o r m a t { L a T e X 2 e } [ 1 9 9 9 / 1 2 / 0 1 ] 2 \ P r o v i d e s C l a s s { y d o c }[% 3 % <! DATE > 4 % <! VERSION > 5 % <* DRIVER > 6 2 0 1 1 / 0 8 / 1 1 d e v e l o p 7 % </ DRIVER > 8 y d o c c l a s s : d o c u m e n t L a T e X c l a s s and p a c k a g e s ]33 % % P l e a s e d e l e t e the f o l l o w i n g l i n e on m a n u a l c h a n g e s. : 34 \ P r o v i d e s F i l e { y d o c . cfg }[% 35 % <! DATE > 36 % <! VERSION > 37 % <* DRIVER > 38 2 0 1 1 / 0 8 / 1 1 d e v e l o p 39 % </ DRIVER > 40 D e f a u l t c o n f i g f i l e for y d o c ] 41 \ u s e p a c k a g e [ T 1]{ f o n t e n c } 42 \ I f F i l e E x i s t s { f o u r i e r . sty }{% 43 \ u s e p a c k a g e { f o u r i e r } 44 }{}
Use ’lmodern’ only for the ’tt’ font if fourier is installed.
45 \ I f F i l e E x i s t s { l m o d e r n . sty }{ 46 \ I f F i l e E x i s t s { f o u r i e r . sty }{ 47 \ r e n e w c o m m a n d {\ t t d e f a u l t }{ l m t t } 48 }{ 49 \ u s e p a c k a g e { l m o d e r n } 50 } 51 }{} 52 \ u r l s t y l e { sf }
Use micro-typesetting if pdftex is used:
53 \ u s e p a c k a g e { i f p d f } 54 \ i f p d f 55 \ u s e p a c k a g e { m i c r o t y p e } 56 \ fi 57 \ u s e p a c k a g e { a r r a y } 58 \ u s e p a c k a g e { b o o k t a b s } 59 \ u s e p a c k a g e { m u l t i c o l } 60 \ u s e p a c k a g e { x c o l o r } 61 \ u s e p a c k a g e { l i s t i n g s } 62 \ u s e p a c k a g e { b o o k t a b s } 63 \ u s e p a c k a g e { h y p e r r e f } 64 \ r e v e r s e m a r g i n p a r
3.4 Macros and Environments to document Implementations
65 \ N e e d s T e X F o r m a t { L a T e X 2 e } [ 1 9 9 9 / 1 2 / 0 1 ] 66 \ P r o v i d e s P a c k a g e { ydoc - c o d e }[%
70 2 0 1 1 / 0 8 / 1 1 d e v e l o p 71 % </ DRIVER > 72 y d o c p a c k a g e to d o c u m e n t m a c r o c o d e ] 73 \ R e q u i r e P a c k a g e { h y p e r r e f } 74 \ h y p e r s e t u p { c o l o r l i n k s = true , p d f b o r d e r =0 0 0 ,. p d f b o r d e r s t y l e = { } } 75 \ I f F i l e E x i s t s { n e e d s p a c e . sty }{% 76 \ R e q u i r e P a c k a g e { n e e d s p a c e } 77 }{% 78 \ def \ N e e d s p a c e {\ @ i f s t a r \ @ g o b b l e \ @ g o b b l e } 79 }
3.4.1 Color and style definitions
3.4.3 Handling Macrocode macrocode 95 \ def \ m a c r o c o d e {% 96 \ par \ n o i n d e n t 97 \ b e g i n g r o u p 98 \ y d o c @ c a t c o d e s 99 \ m a c r o @ c o d e 100 } 101 \ def \ e n d m a c r o c o d e {} \macro@code
#1: verbatim macro code
\macro@@code
#1: verbatim macro code
163 \ def \ n e w l i n e m a c r o {^^ J }% 164 \ let \ b s l a s h m a c r o \ b s l a s h 165 \ let \ s p a c e m a c r o \ s p a c e 166 \ i m m e d i a t e \ o p e n o u t \ y d o c w r i t e =\ y d o c f n a m e \ r e l a x 167 \ i m m e d i a t e \ w r i t e \ y d o c w r i t e {\ t h e m a c r o c o d e }% 168 \ i m m e d i a t e \ c l o s e o u t \ y d o c w r i t e 169 \ @ n a m e u s e { y d o c @ c o u n t b s l a s h e s }% 170 \ y d o c l i s t i n g s s e t t i n g s 171 \ let \ i n p u t \ @ i n p u t 172 \ l s t i n p u t l i s t i n g {\ y d o c f n a m e }% 173 \ e n d g r o u p 174 } 175 \ l s t d e f i n e s t y l e { y d o c c o d e }{% 176 l a n g u a g e =[ l a t e x ] tex , b a s i c s t y l e =\ t t f a m i l y , 177 n u m b e r s = left , n u m b e r s t y l e =\ t i n y \ c o l o r { g r a y } ,. f i r s t n u m b e r = last , 178 b r e a k l i n e s , p r e b r e a k ={\ m b o x {\ t i n y $\ s w a r r o w $}} , 179 c o m m e n t s t y l e =\ c o l o r { b l a c k !60} , 180 }% \ydoclistingssettings 181 \ def \ y d o c l i s t i n g s s e t t i n g s {% 182 \ l s t s e t { s t y l e = y d o c c o d e }% 183 } \macro@impl@args
#1: number of macro arguments
254 \ @ i f u n d e f i n e d { h r e f @ d e s c @ \ n a m e } { } { \ h y p e r l i n k {. d e s c :\ n a m e }}% 255 {\ P r i n t M a c r o I m p l N a m e { # 1 } }% 256 \ h s p a c e *{\ d e s c s e p }% 257 }% 258 }% 259 \ par \ m e d s k i p \ n o i n d e n t 260 } \PrintMacroImplName #1: macro (token) 261 \ def \ P r i n t M a c r o I m p l N a m e #1{% 262 \ i m p l s t y l e {\ s t r i n g #1\ s t r u t }% 263 } \PrintEnvImplName #1: environment name test 264 \ def \ P r i n t E n v I m p l N a m e #1{% 265 \ par \ b i g s k i p \ n o i n d e n t 266 \ h b o x {\ h s p a c e *{\ d e s c i n d e n t }\ f b o x {{\ i m p l s t y l e { # 1 } } } }. % 267 \ par \ m e d s k i p 268 } \implstyle 269 \ def \ i m p l s t y l e {\ t t f a m i l y \ b f s e r i e s \ c o l o r { m a c r o i m p l }} \bslash
Defines an expandable backslash with catcode 12: ‘\12’. The\@firstofonetrick is used to read the\gdef\bslashcode before changing the catcode.
3.5 Provide
doc
macros
276 \ N e e d s T e X F o r m a t { L a T e X 2 e } [ 1 9 9 9 / 1 2 / 0 1 ] 277 \ P r o v i d e s P a c k a g e { ydoc - doc }[% 278 % <! DATE > 279 % <! VERSION > 280 % <* DRIVER > 281 2 0 9 9 / 0 1 / 0 1 d e v e l o p 282 % </ DRIVER > 283 y d o c p a c k a g e to p r o v i d e ’ doc ’ m a c r o s ] \ydoc@countbslashes\Finale
The first two macros modify the\StopEventuallymacro which either stores its argument in\Finalor executes it itself.
\EnableCrossrefs 374 \ p r o v i d e c o m m a n d *\ E n a b l e C r o s s r e f s {% 375 \ P a c k a g e W a r n i n g { y d o c }{ C r o s s r e f e r e n c e s not . i m p l e m e n t e d yet ! } { } { }% 376 } \GetFileInfo
Current implementation taken fromdocpackage.
408 \ m e s s a g e { * * * * * * * * * * * * * * * * * * * * * * * * * * * * ^ ^ J }% 409 \ m e s s a g e {* C h e c k s u m w r o n g (\ y d o c @ c h e c k s u m < >\ the \. y d o c @ b s l a s h c n t ) ^^ J }% 410 \ m e s s a g e { * * * * * * * * * * * * * * * * * * * * * * * * * * * * ^ ^ J }% 411 \ G e n e r i c E r r o r { C h e c k s u m w r o n g }{ C o r r e c t c h e c k s u m is. \ the \ y d o c @ b s l a s h c n t ^^ J } { } { }% 412 \ fi 413 \ fi 414 \ fi 415 } 416 \ R e q u i r e P a c k a g e { s h o r t v r b } 417 \ A t B e g i n D o c u m e n t {\ M a k e S h o r t V e r b { \ | } } 418 \ R e q u i r e P a c k a g e { url } 419 420 \ def \ p a c k a g e {\ def \ @ p a c k a g e } 421 \ p a c k a g e {\ j o b n a m e } 422 423 \ def \ b u n d l e {\ def \ @ b u n d l e } 424 \ let \ @ b u n d l e \ @ e m p t y 425 426 427 \ def \ c t a n l o c a t i o n {\ def \ @ c t a n l o c a t i o n # # 1 } 428 \ c t a n l o c a t i o n { h t t p :// www . c t a n . org / pkg / # 1 } 429 430 \ d a t e { V e r s i o n \ f i l e v e r s i o n \ s p a c e - - \ f i l e d a t e } 431 432 \ def \ @ h o m e p a g e {% 433 \ b e g i n g r o u p 434 \ e d e f \ @ t e m p a {% 435 \ e n d g r o u p 436 C T A N : 437 \ n o e x p a n d \ url 438 {\ @ c t a n l o c a t i o n {\ ifx \ @ b u n d l e \ @ e m p t y \ @ p a c k a g e \. e l s e \ @ b u n d l e \ fi }}% 439 }% 440 \ @ t e m p a 441 } 442 443 \ let \ @ r e p o s i t o r y \ @ e m p t y 444 \ p r o t e c t e d \ def \ r e p o s i t o r y {\ u r l d e f \ @ r e p o s i t o r y \ url } 445 \ p r o t e c t e d \ def \ h o m e p a g e {\ u r l d e f \ @ h o m e p a g e \ url } 446 \ p r o t e c t e d \ def \ e m a i l {\ h y p e r @ n o r m a l i s e \ e m a i l @ } 447 \ def \ e m a i l @ # 1 { \ def \ @ p l a i n e m a i l { # 1 } \ def \ @ e m a i l {\.
h y p e r @ l i n k u r l {\ H u r l { # 1 } } { m a i l t o : # 1 } } }
448
449 \ let \ @ e m a i l \ e m p t y 450
500 \ a f t e r g r o u p \ y d o c p d f s e t t i n g s 501 } 502 503 \ i f p d f 504 \ def \ y d o c p d f s e t t i n g s {% 505 \ h y p e r s e t u p {% 506 p d f a u t h o r = {\ @ a u t h o r \ space <\ @ p l a i n e m a i l >} , 507 p d f t i t l e = {\ @ t i t l e } , 508 p d f s u b j e c t = { D o c u m e n t a t i o n of L a T e X p a c k a g e. \ @ p a c k a g e } , 509 p d f k e y w o r d s = {\ @ p a c k a g e , LaTeX , TeX } 510 }% 511 } 512 \ e l s e 513 \ let \ y d o c p d f s e t t i n g s \ e m p t y 514 \ fi 515 516 \ let \ o r i g @ m a k e t i t l e \ m a k e t i t l e 517 \ def \ m a k e t i t l e {% 518 \ y d o c p d f s e t t i n g s 519 \ o r i g @ m a k e t i t l e 520 \ let \ o r i g @ m a k e t i t l e \ r e l a x 521 }
3.6 Description Macros and Environments
522 \ N e e d s T e X F o r m a t { L a T e X 2 e } [ 1 9 9 9 / 1 2 / 0 1 ] 523 \ P r o v i d e s P a c k a g e { ydoc - d e s c }[% 524 % <! DATE > 525 % <! VERSION > 526 % <* DRIVER > 527 2 0 9 9 / 0 1 / 0 1 d e v e l o p 528 % </ DRIVER > 529 y d o c p a c k a g e to d e s c r i b e macros , e n v i r o n m e n t s , . o p t i o n s etc .] 530 \ I f F i l e E x i s t s { n e e d s p a c e . sty }{% 531 \ R e q u i r e P a c k a g e { n e e d s p a c e } 532 }{% 533 \ def \ N e e d s p a c e {\ @ i f s t a r \ @ g o b b l e \ @ g o b b l e } 534 }
The short verbatim code is required for the similar macros provided here.
535 \ R e q u i r e P a c k a g e { s h o r t v r b }
Theetoolboxpackage is used mainly for\newrobustcmd.
3.6.1 Color and style definitions
537 \ R e q u i r e P a c k a g e { x c o l o r }
Define special no-op ‘none’ color which does not change the color. This is not yet tested and may break output files, but seems to work fine with PDF.
538 \ e x p a n d a f t e r \ def \ c s n a m e \ s t r i n g \ c o l o r @ n o n e \ e n d c s n a m e {% 539 \ x c o l o r @ { } { } { } { } 540 } 541 \ d e f i n e c o l o r { m a c r o d e s c }{ rgb } { 0 , 0 . 2 , 0 . 6 } 542 \ d e f i n e c o l o r { k e y d e s c }{ rgb } { 0 , 0 . 4 , 0 . 9 } 543 \ d e f i n e c o l o r { m a c r o i m p l }{ rgb } { 0 , 0 . 1 , 0 . 3 } 544 \ d e f i n e c o l o r { m e t a }{ rgb } { 0 , 0 . 2 5 , 0 . 7 5 } 545 \ d e f i n e c o l o r { s c r i p t c o l o r }{ rgb } { 0 . 2 , 0 . 6 , 0 . 2 } 546 \ d e f i n e c o l o r { o p t i o n c o l o r }{ rgb } { 0 . 3 . 0 . 2 , 0 } 547 \ c o l o r l e t { o p t i o n a l }{ b l a c k ! 6 5 ! w h i t e } 548 \ c o l o r l e t { m e t a o p t i o n a l }{ o p t i o n a l ! 5 0 ! m e t a } 549 \ p r o v i d e c o l o r { u r l c o l o r }{ n a m e d }{ b l u e } 550 \ p r o v i d e c o l o r { l i n k c o l o r }{ n a m e d }{ b l u e } 551 \ p r o v i d e c o l o r { f i l e c o l o r }{ n a m e d }{ b l u e } 552 \ p r o v i d e c o l o r { c i t e c o l o r }{ n a m e d }{ b l u e } 553 \ p r o v i d e c o l o r { a n c h o r c o l o r }{ n a m e d }{ b l u e } 554 \ p r o v i d e c o l o r { m e n u c o l o r }{ n a m e d }{ b l u e } 555 \ p r o v i d e c o l o r { r u n c o l o r }{ n a m e d }{ b l u e } 557 \ R e q u i r e P a c k a g e { h y p e r r e f } 558 \ h y p e r s e t u p {% 559 c o l o r l i n k s = true , 560 p d f b o r d e r =0 0 0 , 561 p d f b o r d e r s t y l e ={} , 562 u r l c o l o r = u r l c o l o r , 563 l i n k c o l o r = l i n k c o l o r , 564 f i l e c o l o r = f i l e c o l o r , 565 c i t e c o l o r = c i t e c o l o r , 566 a n c h o r c o l o r = a n c h o r c o l o r , 567 m e n u c o l o r = m e n u c o l o r , 568 r u n c o l o r = r u n c o l o r , 569 }
3.6.2 Text Formatting Macros
\meta
Prints〈meta text〉.
571 \ n e w r o b u s t c m d *\ m e t a [ 1 ] {% 572 {\ m e t a s t y l e {%
574 # 1 \ /%
575 \ e n s u r e m a t h \ r a n g l e 576 }}%
577 }
\marg
Sets style and adds braces. The text is formatted as separate set of macro arguments.
578 \ n e w r o b u s t c m d *{\ m a r g } [ 1 ] {% 579 {\ m a r g s t y l e {% 580 {\ t t f a m i l y \ b r a c e l e f t }% 581 \ m e t a { # 1 }% 582 {\ t t f a m i l y \ b r a c e r i g h t }% 583 }}% 584 } \oarg
Sets style and adds brackets. The text is formatted as separate set of macro arguments.
585 \ n e w r o b u s t c m d *{\ o a r g } [ 1 ] {% 586 {\ o a r g s t y l e {% 587 {\ t t f a m i l y [}% 588 \ m e t a { # 1 }% 589 {\ t t f a m i l y ]}% 590 }}% 591 } \parg
Sets style and adds parentheses.
592 \ n e w r o b u s t c m d *{\ p a r g } [ 1 ] {% 593 {\ p a r g s t y l e {% 594 {\ t t f a m i l y (}% 595 \ m e t a { # 1 }% 596 {\ t t f a m i l y ) }% 597 }}% 598 } \aarg
599 \ n e w r o b u s t c m d *{\ a a r g } [ 1 ] {% 600 {\ a a r g s t y l e {% 601 {\ t t f a m i l y <}% 602 \ m e t a { # 1 }% 603 {\ t t f a m i l y >}% 604 }}% 605 } \sarg
Prints star with given style.
619 \ n e w c o m m a n d *\ c l s s t y l e [ 1 ] { \ t e x t t t {\ t e x t c o l o r { cls. } { # 1 } } } 620 \ n e w c o m m a n d *\ l i b s t y l e [ 1 ] { \ t e x t t t {\ t e x t c o l o r { lib. } { # 1 } } } 621 \ n e w c o m m a n d *\ e n v s t y l e [ 1 ] { \ t e x t t t {\ t e x t c o l o r { env. } { # 1 } } } 622 \ n e w c o m m a n d *\ o p t s t y l e [ 1 ] { \ t e x t s f {\ t e x t c o l o r { opt. } { # 1 } } } 623 \ n e w c o m m a n d *\ f i l e s t y l e [ 1 ] { \ t e x t t t {\ t e x t c o l o r { f i l e. } { # 1 } } } 624 \ c o l o r l e t { cls }{ n o n e } 625 \ c o l o r l e t { lib }{ n o n e } 626 \ c o l o r l e t { env }{ n o n e } 627 \ c o l o r l e t { f i l e }{ n o n e } 628 \ c o l o r l e t { pkg }{ n o n e } 629 \ d e f i n e c o l o r { opt }{ rgb } { 0 . 5 , 0 . 1 6 6 6 6 , 0 } \cs \cmd 630 \ n e w r o b u s t c m d *\ cs [ 1 ] { \ t e x t t t {\ t e x t b a c k s l a s h # 1 } } 631 \ n e w r o b u s t c m d *\ cmd [ 1 ] { \ t e x t t t {{\ e s c a p e c h a r = 9 2 \ s t r i n g. # 1 } } } \Key 632 \ n e w r o b u s t c m d *\ Key [ 1 ] { \ P r i n t K e y N a m e { # 1 } \ M a c r o A r g s }
3.6.3 Text Formatting Styles
\macrodescstyle
Style of described macro names.
633 \ def \ m a c r o d e s c s t y l e {\ t t f a m i l y \ b f s e r i e s \ c o l o r {. m a c r o d e s c }}
\macrodescstyle
Style of described macro names.
\macroargsstyle
Default style for macro arguments (e.g.\MacroArgs).
635 \ def \ m a c r o a r g s s t y l e {\ t t f a m i l y }
\envcodestyle
Default style for code body content in described environments.
636 \ def \ e n v c o d e s t y l e {\ t t f a m i l y }
\verbstyle
Style for verbatim text inside macro argument list.
637 \ def \ v e r b s t y l e {\ v e r b a t i m @ f o n t }
\metastyle
Meta text style. Because\macroargsstylemight be also active a\normalfont reset the font.
638 \ def \ m e t a s t y l e {\ n o r m a l f o n t \ i t s h a p e \ c o l o r { m e t a }}
\margstyle Style for\marg.
\optionalon \optionaloff 642 \ def \ o p t i o n a l o n {\ p r o t e c t e d \ def \ o p t i o n a l {\. o p t i o n a l s t y l e }} 643 \ def \ o p t i o n a l o f f {\ let \ o p t i o n a l \ r e l a x } 644 \ o p t i o n a l o n \oargstyle
Style for\oarg. A special color is set to show the ‘optional’ status.
645 \ def \ o a r g s t y l e {\ o p t i o n a l }
\pargstyle Style for\parg.
646 \ def \ p a r g s t y l e {}
\aargstyle Style for\aarg.
647 \ def \ a a r g s t y l e {}
\sargstyle
Style for\sarg. A special color is set to show the ‘optional’ status.
648 \ def \ s a r g s t y l e {\ t t f a m i l y \ c o l o r { o p t i o n a l }}
3.6.4 Dimension Registers
\descindent
\beforedescskip 651 \ n e w d i m e n \ b e f o r e d e s c s k i p 652 \ b e f o r e d e s c s k i p =\ b i g s k i p a m o u n t \afterdescskip 653 \ n e w d i m e n \ a f t e r d e s c s k i p 654 \ a f t e r d e s c s k i p =\ m e d s k i p a m o u n t \descsep
Set to1eminttfont.
655 \ n e w d i m e n \ d e s c s e p 656 \ b e g i n g r o u p
657 \ t t f a m i l y
658 \ g l o b a l \ d e s c s e p =1 em \ r e l a x 659 \ e n d g r o u p
3.6.5 Macro Argument Reading Mechanism
\read@Macro@arg
Reads next token and calls second macro.
660 \ def \ r e a d @ M a c r o @ a r g {%
661 \ f u t u r e l e t \ @ l e t @ t o k e n \ h a n d l e @ M a c r o @ a r g 662 }
\AlsoMacro
\ydoc@short@AlsoMacro Makes&an alias for\AlsoMacro.
675 \ b e g i n g r o u p 676 \ catcode ‘ \ | \ a c t i v e 677 \ g d e f \ y d o c @ s h o r t @ A l s o M a c r o {% 678 \ catcode ‘ \ | \ a c t i v e 679 \ let |\ A l s o M a c r o 680 } 681 \ e n d g r o u p \ydoc@macrocatcodes
Sets the catcodes inside forread@Macro@argmaterial.
682 \ def \ y d o c @ m a c r o c a t c o d e s {% 683 \ y d o c @ s h o r t @ A l s o M a c r o 684 \ @ m a k e o t h e r \ ’% 685 \ @ m a k e o t h e r \!% 686 \ @ m a k e o t h e r \[% 687 \ @ m a k e o t h e r \]% 688 \ @ m a k e o t h e r \(% 689 \ @ m a k e o t h e r \)% 690 } \handle@Macro@arg
Checks if next token is the begin of a valid macro argument and calls the appropriate read macro or the end macro otherwise.
705 \ fi 706 \ h a n d l e r 707 } 708 \ def \ d e f i n e @ M a c r o @ h a n d l e r {% 709 \ b e g i n g r o u p 710 \ y d o c @ m a c r o c a t c o d e s 711 \ d e f i n e @ M a c r o @ h a n d l e r @ 712 } 713 \ def \ d e f i n e @ M a c r o @ h a n d l e r @ #1{% 714 \ e n d g r o u p 715 \ @ n a m e d e f { h a n d l e @ M a c r o @ t o k e n @ \ m e a n i n g #1}% 716 } \end@Macro@args
Closes box as calls hook. Might be locally redefined by some macros calling\read@Macro@arg.
717 \ def \ e n d @ M a c r o @ a r g s {% 718 \ y @ e g r o u p
719 \ a f t e r @ M a c r o @ a r g s 720 }
\after@Macro@args
Hook to add additional commands in certain situations.
721 \ def \ a f t e r @ M a c r o @ a r g s {% 722 }
Macro argument reading macros
This macros read the macro arguments and call the appropriate format macros.
\read@Macro@sarg
808 \ d e f i n e @ M a c r o @ h a n d l e r **{% 809 \ s a r g \ r e a d @ M a c r o @ a r g 810 }
Allows ‘=’ to be used directly without switching to verbatim mode. This is espe-cially useful for keys.
811 \ d e f i n e @ M a c r o @ h a n d l e r { = } = {% 812 =\ r e a d @ M a c r o @ a r g
813 }
\read@Macro@verb
Sets up verbatim mode calls second macro.
814 \ d e f i n e @ M a c r o @ h a n d l e r { ’} ’{% 815 \ b e g i n g r o u p 816 \ let \ do \ @ m a k e o t h e r 817 \ d o s p e c i a l s 818 \ @ n o l i g s 819 \ @ m a k e o t h e r \ ’% 820 \ o b e y s p a c e s 821 \ r e a d @ M a c r o @ v e r b @ 822 } \read@Macro@verb@
Closes verbatim mode and formats text. If#1is empty (’’) than a single’is printed.
\read@Macro@cmds Simply executes given code.
837 \ d e f i n e @ M a c r o @ h a n d l e r ! ! # 1 ! {% 838 #1\ r e l a x
839 \ r e a d @ M a c r o @ a r g 840 }
\read@Macro@rmspace
Removes space. The\@firstofoneis used to preserve the space in the macro definition.
841 \ d e f i n e @ M a c r o @ h a n d l e r {\ @ s p t o k e n } {% 842 \ r e a d @ M a c r o @ a r g
843 }
\read@Macro@addtoken
Takes token over from input to output ‘stream’. This is used for\spaceand~.
844 \ d e f i n e @ M a c r o @ h a n d l e r { ~ } # 1 {% 845 #1\ r e a d @ M a c r o @ a r g 846 } 847 \ A t B e g i n D o c u m e n t {% 848 \ d e f i n e @ M a c r o @ h a n d l e r { ~ } # 1 {% 849 #1\ r e a d @ M a c r o @ a r g 850 } 851 } 852 \ d e f i n e @ M a c r o @ h a n d l e r {\ s p a c e } # 1 {% 853 #1\ r e a d @ M a c r o @ a r g 854 } 3.6.6 Description Macros For Macros \DescribeMacro 855 \ @ i f u n d e f i n e d { D e s c r i b e M a c r o } { } {% 856 \ P a c k a g e I n f o { ydoc - d e s c }{ R e d e f i n i n g \ s t r i n g \. D e s c r i b e M a c r o }{}% 857 }
893 \ @ i f u n d e f i n e d { h r e f @ i m p l @ \ n a m e } { } { \ h y p e r l i n k { i m p l :\. n a m e }}% 894 {% 895 \ h b o x {\ v b o x to 0 pt {\ vss \ h b o x {\ r a i s e b o x {4 ex }{\. h y p e r t a r g e t { d e s c :\ n a m e } { } } } }% 896 \ P r i n t M a c r o N a m e { # 1 } }% 897 }% 898 \ y d o c @ m a c r o c a t c o d e s 899 \ m a c r o a r g s s t y l e 900 \ r e a d @ M a c r o @ a r g 901 } \MakeShortMacroArgs
Defines the given character as short version for\MacroArgs. It is first define to be a short verbatim character to take advantage of the house-keeping (save & restore of the original catcode and definition) ofshortvrb.
The starred version define the character to act like\Macroinstead.
902 \ n e w c o m m a n d *\ M a k e S h o r t M a c r o A r g s {% 903 \ @ i f s t a r 904 {\ @ M a k e S h o r t M a c r o A r g s \ M a c r o }% 905 {\ @ M a k e S h o r t M a c r o A r g s \ M a c r o A r g s }% 906 } 907 \ def \ @ M a k e S h o r t M a c r o A r g s # 1 # 2 {% 908 \ M a k e S h o r t V e r b { # 2 } 909 \ catcode ‘ # 2 \ a c t i v e 910 \ b e g i n g r o u p 911 \ catcode ‘ \ ~ \ a c t i v e 912 \ lccode ‘\~ ‘#2\ r e l a x 913 \ l o w e r c a s e {\ e n d g r o u p \ g d e f ~{\ b g r o u p \ let ~\ e g r o u p # 1 } }% 914 } \DeleteShortMacroArgs 915 \ n e w c o m m a n d *\ D e l e t e S h o r t M a c r o A r g s [ 1 ] {% 916 \ D e l e t e S h o r t V e r b { # 1 }% 917 } \Macro
Simply uses the two macros below.
\@Macro
Alternative definition of\MacroinsideDescribeMacrosenvironments.
919 \ def \ @ M a c r o {% 920 \ b e g i n g r o u p \ m a k e a t l e t t e r 921 \ D e s c r i b e @ M a c r o 922 } 923 \ d e f i n e @ M a c r o @ h a n d l e r \ A l s o M a c r o {} 924 \ d e f i n e @ M a c r o @ h a n d l e r \ D e s c r i b e M a c r o {} 925 \ d e f i n e @ M a c r o @ h a n d l e r \ D e s c r i b e K e y {} 926 \ d e f i n e @ M a c r o @ h a n d l e r \ D e s c r i b e S c r i p t {} \MacroArgs
Uses the normal macro argument reading mechanism from\DescribeMacro. In-stead of a box a simple group is added.
\DescribeLength 975 \ n e w c o m m a n d *\ D e s c r i b e L e n g t h {% 976 \ b e g i n g r o u p 977 \ let \ D e s c r i b e L e n g t h \ D e s c r i b e @ L e n g t h 978 \ s e t b o x \ d e s c b o x \ h b o x \ y @ b g r o u p 979 \ t a b u l a r { @ {} l@ {\ h s p a c e {2 em }} l@ {}}% 980 \ D e s c r i b e @ L e n g t h 981 } \Describe@Length 982 \ n e w c o m m a n d *\ D e s c r i b e @ L e n g t h [ 2 ] {% 983 \ P r i n t L e n g t h N a m e { # 1 } & 984 ( D e f a u l t : {\ m a c r o a r g s s t y l e #2\ u n s k i p })% 985 \ @ i f n e x t c h a r \ D e s c r i b e L e n g t h 986 { \ \ }% 987 {% 988 \ e n d t a b u l a r 989 \ y @ e g r o u p 990 \ P r i n t L e n g t h 991 \ e n d g r o u p 992 }% 993 } For Environments \DescribeEnv 994 \ @ i f u n d e f i n e d { D e s c r i b e E n v } { } {% 995 \ P a c k a g e I n f o { ydoc - d e s c }{ R e d e f i n i n g \ s t r i n g \. D e s c r i b e E n v }{}% 996 } 997 \ let \ D e s c r i b e E n v \ r e l a x 998 \ n e w c o m m a n d *\ D e s c r i b e E n v [ 2 ] [ ] {% 999 \ b e g i n g r o u p 1000 \ def \ D e s c r i b e E n v @ n a m e { # 2 }% 1001 \ let \\\ D e s c r i b e E n v @ n e w l i n e
1002 \ ifx \ @ c u r r e n v i r \ D e s c r i b e E n v @ s t r i n g 1003 \ def \ a f t e r @ M a c r o @ a r g s {% 1004 \ let \ a f t e r @ M a c r o @ a r g s \ e m p t y 1005 \ s e t b o x \ @ t e m p b o x a \ h b o x \ y @ b g r o u p 1006 \ @ i f n e x t c h a r \ end {}% 1007 {\ D e s c r i b e E n v @ n e w l i n e }% 1008 #1% 1009 }%
The macro version adds the optional argument as content line if given.
1010 \ e l s e 1011 \ ifx \ r e l a x #1\ r e l a x 1012 \ def \ a f t e r @ M a c r o @ a r g s {% 1013 \ y @ b g r o u p 1014 \ e n d D e s c r i b e E n v 1015 }% 1016 \ e l s e 1017 \ def \ a f t e r @ M a c r o @ a r g s {% 1018 \ s e t b o x \ @ t e m p b o x a \ h b o x \ y @ b g r o u p 1019 \ D e s c r i b e E n v @ n e w l i n e \ M a c r o A r g s #1% 1020 \ e n d D e s c r i b e E n v 1021 }% 1022 \ fi 1023 \ fi
Start\vboxand adds first line.
1024 \ s e t b o x \ d e s c b o x \ v b o x \ y @ b g r o u p 1025 \ e n v c o d e s t y l e 1026 \ let \ P r i n t E n v \ P r i n t S u b E n v 1027 \ h b o x \ y @ b g r o u p 1028 \ P r i n t E n v N a m e {\ b e g i n }{\ D e s c r i b e E n v @ n a m e }% 1029 \ y d o c @ m a c r o c a t c o d e s 1030 \ m a c r o a r g s s t y l e 1031 \ r e a d @ M a c r o @ a r g 1032 } \DescribeEnv@newline
Closes existing and starts a new horizontal box representing a indented line. The op-tional argument allows to add extra space between lines like the normal\\. Negative values are not supported.
\DescribeEnv@string
Holds the environment name for comparison.
1040 \ def \ D e s c r i b e E n v @ s t r i n g { D e s c r i b e E n v }
\descbox
Save box to store description content.
1041 \ n e w b o x \ d e s c b o x \endDescribeEnv 1042 \ def \ e n d D e s c r i b e E n v {% 1043 \ y @ e g r o u p 1044 \ b e g i n g r o u p 1045 \ s e t b o x \ @ t e m p b o x a \ l a s t b o x 1046 \ i f c a s e 0% 1047 \ i f d i m \ wd \ @ t e m p b o x a >\ d e s c s e p 1\ fi 1048 \ i f d i m \ ht \ @ t e m p b o x a >\ ht \ s t r u t b o x 1\ fi 1049 \ i f d i m \ dp \ @ t e m p b o x a >\ dp \ s t r u t b o x 1\ fi 1050 \ e l s e 1051 \ box \ @ t e m p b o x a 1052 \ fi 1053 \ e n d g r o u p 1054 \ h b o x \ y @ b g r o u p 1055 \ P r i n t E n v N a m e {\ end }{\ D e s c r i b e E n v @ n a m e } 1056 \ y @ e g r o u p 1057 \ y @ e g r o u p 1058 \ P r i n t E n v 1059 \ e n d g r o u p 1060 } 3.6.7 Print Macros \PrintMacroName
Formats macro name. The backslash is forced tottfont.
\PrintKeyName
Formats macro name. The backslash is forced tottfont.
1067 \ def \ P r i n t K e y N a m e #1{% 1068 {\ k e y d e s c s t y l e {\ s t r u t 1069 #1\ s t r u t }}%
1070 }
\PrintLengthName
Formats length register name.
1071 \ let \ P r i n t L e n g t h N a m e \ P r i n t M a c r o N a m e
\PrintEnvName
#1= ‘\begin’ or ‘\end’,#2= env name.
1072 \ def \ P r i n t E n v N a m e # 1 # 2 {% 1073 \ s t r u t 1074 \ s t r i n g #1\ b r a c e l e f t 1075 {\ m a c r o d e s c s t y l e #2\ s t r u t }% 1076 \ b r a c e r i g h t 1077 } \PrintMacros
Prints macros described using\DescribeMacros. The actual content was stored inside\descbox. If it is wider than the line width it is centered.
1093 \ par \ n o i n d e n t 1094 } 1095 \ def \ d e s c f r a m e #1{% 1096 \ f b o x {\ h s p a c e *{\ d e s c s e p } # 1 \ h s p a c e *{\ d e s c s e p }}% 1097 } \PrintLength
Prints lengths registers described using one or multiple\DescribeLength.
1098 \ let \ P r i n t L e n g t h \ P r i n t M a c r o s
\PrintEnv
PrintsDescribeEnvenvironments. The actual content was stored inside\descbox.
1099 \ let \ P r i n t E n v \ P r i n t M a c r o s
\PrintSubEnv
Prints sub environments, i.e.DescribeEnvenvironments inside the body of another DescribeEnv. The actual content was stored inside\descbox.
1100 \ def \ P r i n t S u b E n v {%
1101 \ h b o x {\ h b o x {\ u s e b o x {\ d e s c b o x }}}% 1102 }
3.6.8 Special Character Macros
\bslash
Defines an expandable backslash with catcode 12: ‘\12’. The\@firstofonetrick is used to read the\gdef\bslashcode before changing the catcode.
1103 {% 1104 \ @ f i r s t o f o n e {% 1105 \ catcode ‘ \ \ = 1 2 1106 \ g d e f \ b s l a s h 1107 } { \ } 1108 }% } \percent
Defines an expandable percent character with catcode 12: ‘%12’.
\braceleft
\braceright
Defines expandable left and right braces with catcode 12: ‘{12’ ‘}12’.
1113 \ b e g i n g r o u p 1114 \ catcode ‘\ <=1 1115 \ catcode ‘\ >=2 1116 \ catcode ‘ \ { = 1 2 1117 \ catcode ‘ \ } = 1 2 1118 \ g d e f \ b r a c e l e f t <{ > 1119 \ g d e f \ b r a c e r i g h t <} > 1120 \ e n d g r o u p 3.6.9 Other Macros \y@bgroup \y@egroup
These macros are used to begin and end\vbox/\hbox-es.
1139 \ c o d e l i n e a f t e r 1140 } 1141 \ n e w c o m m a n d *\ c o d e l i n e b e f o r e {\ par \ s m a l l s k i p \ n o i n d e n t } 1142 \ n e w c o m m a n d *\ c o d e l i n e a f t e r {\ par \ s m a l l s k i p \ n o i n d e n t } codequote 1143 \ n e w e n v i r o n m e n t { c o d e q u o t e }{% 1144 \ def \ \ { \ n e w l i n e \ r e l a x \ M a c r o A r g s }% 1145 \ par \ s m a l l s k i p \ b g r o u p \ l e f t s k i p =\ l e f t m a r g i n \. r i g h t s k i p =\ r i g h t m a r g i n \ n o i n d e n t \ M a c r o A r g s } 1146 {\ par \ e g r o u p \ s m a l l s k i p \ n o i n d e n t \. i g n o r e s p a c e s a f t e r e n d } macroquote 1147 \ n e w e n v i r o n m e n t { m a c r o q u o t e }{% 1148 \ def \ \ { \ n e w l i n e \ r e l a x \ M a c r o }% 1149 \ par \ s m a l l s k i p \ b g r o u p \ l e f t s k i p =\ l e f t m a r g i n \. r i g h t s k i p =\ r i g h t m a r g i n \ n o i n d e n t \ M a c r o } 1150 {\ par \ e g r o u p \ s m a l l s k i p \ n o i n d e n t \. i g n o r e s p a c e s a f t e r e n d }
