diff options
| -rw-r--r-- | Master/texmf-dist/doc/generic/texapi/README | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf | bin | 161785 -> 131636 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/generic/texapi/texapi-doc.tex | 246 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/generic/texapi/texapi.tex | 69 |
4 files changed, 240 insertions, 79 deletions
diff --git a/Master/texmf-dist/doc/generic/texapi/README b/Master/texmf-dist/doc/generic/texapi/README index e8104544660..4a23048bacf 100644 --- a/Master/texmf-dist/doc/generic/texapi/README +++ b/Master/texmf-dist/doc/generic/texapi/README @@ -2,7 +2,7 @@ This is the README file for the texapi package. Author: Paul Isambert. E-mail: zappathustra AT free DOT fr Comments and suggestions are welcome. -Date: January 2011. +Date: October 2011. The package is set of macros to write format-independent (and -aware) packages. @@ -17,7 +17,7 @@ texapi-doc.tex => The source of the documentation. texapi-doc.pdf => The typeset documentation. To process the documentation source, you need the -piTeX files (available on CTAN) on top of plain TeX +PiTeX files (available on CTAN) on top of plain TeX with LuaTeX at least v.0.6. Non-free fonts are used. ... err, no actually, don't typeset it, the PiTeX version on CTAN is way too old. It'll be updated someday. diff --git a/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf b/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf Binary files differindex 7e643911aab..c1a196bd7d6 100644 --- a/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf +++ b/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf diff --git a/Master/texmf-dist/doc/generic/texapi/texapi-doc.tex b/Master/texmf-dist/doc/generic/texapi/texapi-doc.tex index 83d0c3e47d7..fdc93eebd8a 100644 --- a/Master/texmf-dist/doc/generic/texapi/texapi-doc.tex +++ b/Master/texmf-dist/doc/generic/texapi/texapi-doc.tex @@ -1,10 +1,5 @@ \input pitex % which \input's texapi (and YaX) -\directlua{ - fonts.expansions.setups['threepercent'].shrink = 4 - fonts.expansions.setups['threepercent'].stretch = 4 - } - \setparameter document: author = "Paul Isambert" title = \texapi @@ -25,45 +20,26 @@ parindent = 2em \setparameter font: - command = \titlefont - name = ChaparralPro- - size = 20pt - roman = Regular - -\setparameter font: - command = \tmainfont - name = ChaparralPro- + command = \mainfont + name = "Chaparral Pro" size = 12pt - roman = Regular - bold = Bold - italic = Italic - -\setparameter font: - command = \csmainfont - name = ChaparralPro- - size = 11pt - roman = Italic - bold = Bold - italic = Regular - -\def\mainfont{% - \ifcslist \csmainfont - \else \tmainfont \fi} + small = 11pt + big = 20pt \setparameter font: command = \tcodefont - name = lucon + name = "Lucida Console" size = 9.5pt - type = ttf - roman = {} + bold italic = none + features = "space = mono" \setparameter font: command = \cscodefont - name = lucon + name = "Lucida Console" size = 8.5pt - type = ttf - roman = {} - + bold italic = none + features = "space = mono" + \def\codefont{% \ifcslist \cscodefont \else \tcodefont\fi} @@ -77,22 +53,24 @@ \newdimen\sepdim \sepdim=1.2pc +\pdfdef\&{&} +\newdimen\originalvsize +\originalvsize=\vsize + \output={% \setbox255=\vtop{\unvbox255} \setbox\codebox=\vtop{\unvbox\codebox} \ht255=\baselineskip \ht\codebox=\baselineskip - \unless\ifx\bookmarktitle\prevbookmarktitle - {\def\TeX{TeX}\pdfoutline goto num \count0 {\bookmarktitle}} - \fi - \global\let\prevbookmarktitle\bookmarktitle \shipout\vbox{% \vbox to 0pt{% \vss - \kern-20pt\hbox{\kern-120pt \pdfdest num \count0 xyz}\kern20pt \hbox to \hsize{% \spaceskip .8em plus .6em minus .3em - \titlefont\sc\descriptiontitle} + \mainfont\big\sc\descriptiontitle + \unless\ifx\bookmarktitle\prevbookmarktitle + \passexpanded{\outline0}{\bookmarktitle}% + \fi} \kern2\baselineskip}% \hbox{% \box255 @@ -107,6 +85,8 @@ }% } \advancepageno + \global\let\prevbookmarktitle\bookmarktitle + \global\vsize=\originalvsize } % @@ -200,7 +180,10 @@ % EXAMPLES % -\def\processexample{% +\newverbatim\example{\codefont\parindent0pt} + {\vskip\baselineskip\printverbatim\relax + \vskip\baselineskip\removenextindent} +\newverbatim\Example{}{% \global\setbox\codebox=\vbox{% \parindent0pt \ifvoid\codebox @@ -217,10 +200,10 @@ \let\exampleskip\relax \cslisttrue \codefont \overfullrule=0pt - \typesetexample + \printverbatim \vskip\baselineskip - \mainfont - \doexample + \mainfont\small + \doverbatim }% } @@ -244,22 +227,21 @@ \antigobblespace } - -\mainfont +\overfullrule=0pt \description{Writing macros with texapi} \setbox\codebox=\vbox to \hsize{% - \csmainfont + \small \hfill \vrule height\topskip width0pt Author: \usevalue document : author \par \hfill Version: \usevalue document : version \par \hfill Date: \usevalue document : date \par \vskip\baselineskip \noindent Typeset in Chaparral Pro (Carol Twombly) and Lucida Console\hfil\penalty-10000 (Charles Bigelow and Kris Holmes) - with Lua\TeX\ v.\the\luatexversion.\luatexrevision. + with Lua\TeX\ v.\directlua{tex.print(tex.luatexversion/100)}. } @@ -388,11 +370,12 @@ like Ti\ital{k}Z or \ital{librarian}. } This sends an error message according to the format's custom. In \tcode{plain} and \tcode{eplain} (and in an unknown format), it produces -\tcode{\com\errmessage\string{\arg{package} error: \arg{message}\string}}. -In La\TeX, we get \com\PackageError\barg{package}\barg{message}{\codefont\string{\string}} -(no help message) and in Con\TeX t -\tcode{\com\writestatus\string{\arg{package} error\string}}\barg{message} -(which is far from Con\TeX t's sophisticated communication system but, well...). +\tcode{\com\errmessage\string{\arg{package} error: \arg{message}\string}}. In +La\TeX, it produces +\com\PackageError\barg{package}\barg{message}{\codefont\string{\string}} (no +help message) and in Con\TeX t \tcode{\com\writestatus\string{\arg{package} +error\string}}\barg{message} (which is far from Con\TeX t's sophisticated +communication system but, well...). \description/ @@ -616,11 +599,18 @@ This returns the name of \comarg, i.e. \comarg\ without its backslash \cslist{ !\reverse } -Conditionals in \texapi\ (not only those on this page) can -be prefixed with \com\reverse, so that if they're true the -\false\ argument is executed (if specified), and if they're -false, the \true\ argument is executed. So this is equivalent -to \com\unless. +Conditionals in \texapi\ (not only those on this page) can be prefixed with +\com\reverse, so that if they're true the \false\ argument is executed (if +specified), and if they're false, the \true\ argument is executed. So this is +equivalent to \com\unless, to which \com\reverse defaults (since version +1.04) in case the following command isn't recognized as a \texapi conditional. + +\Example +\reverse\iffalse + Wow, \verb"\reverse" can replace \verb"\unless"! + We must be using version 1.04 at least! +\fi +\Example/ \cslist{ !\ifcommand\comarg\true\false, @@ -737,7 +727,7 @@ Apart from \com\ifdefined and \com\ifcsname\ (in the guise of \com\ifcommand and \com\ifcs respectively), none of \TeX's primitive conditionals are redefined in a straight fashion, i.e. with two arguments instead of \com\else ... \com\fi. -These commands let you use \TeX's conditional in such a way. +These commands let you use \TeX's conditionals in such a way. \arg{\TeX\ conditional} means such a primitive without a backslash (so this construction can be used inside real conditionals), e.g. \tcode{ifnum} or \tcode{ifvoid}. @@ -759,21 +749,128 @@ whole macro can be prefixed with \com\reverse. \straightenif{iftrue}{}{Good}{Bad}. \Example/ +\cslist{ + !\ifwhatever/conditional/\true\false, + !\iffwhatever/conditional/\true + } +This command (introduced in v.1.04) takes a \arg{conditional} which is +either a \TeX\ conditional (normally expecting \com\fi and perhaps \com\else +before that) or a conditional whose \true\ and \false\ parts are normally +given as arguments, like those created by \com\newife. In the first case, it +is equivalent to \com\straightenif, in the second case it is redundant. +However, it is useful when one is expecting a conditional whose nature is +unknown. If \arg{conditional} is a \TeX\ conditional, you're in charge of +adding space if needed, as with \com\straightenif; unlike the latter, though, +the \com\if... command itself is given as usual (i.e. no need to remove the +backslash), which also means it cannot be properly nested in a \TeX\ +conditional (unless itself is embedded in \com\straightenif). Finally, if +\arg{conditional} is an argument-taking conditional, the \tcode{iff} form (in +case it comes from \texapi) cannot be used, and conditionals poking at the +next token cannot be used either. The whole macro can be prefixed with +\com\reverse. + +\Example + % See this space too? +\ifwhatever{\ifnum5=5 }{True.}{False.} +\newife\iftest +\reverse\iffwhatever\iftest{True too.} +\Example/ + +\description/ + + + + + +\description{Conditional expressions} + +\cslist{ + !\ifexpression/expression/\true\false, + !\iffexpression/expression/\true + } +This (introduced in v.1.04) evaluates \arg{expression}, which is made of +subexpressions separated by \com& (and) or \com| (or), a subexpression being +either a conditional or a braced expression, possibly prefixed with \com- +(not). The `not' operator has precedence over `and', which has precedence over +`or', braces being used to group evaluation. The conditionals making up the +expressions are the same as those passed to \com\ifwhatever (which is used +internally), i.e. \TeX\ conditionals or argument-taking ones. Space is ignored +at the beginning of an operand, but not at the end, unless the operand is a +braced expression. However, such a space is often harmless there (if the +conditional is a \texapi conditional), and sometimes useful (to delimit for +instance a number in an \com\ifnum, see the example on the right); it should be +removed in the usual cases (e.g. after \com\ifcat\ \tcode{XY}). The macro can +be prefixed with \com\reverse. + +\Example +\def\iffibonacci#1{% + \ifexpression{% + -\ifnum#1<0 & -\ifnum#1>100 & + { \ifnum#1=0 | \ifnum#1=1 | + \ifnum#1=2 | \ifnum#1=3 | + \ifnum#1=5 | \ifnum#1=8 | + \ifnum#1=13 | \ifnum#1=21 | + \ifnum#1=34 | \ifnum#1=55 | + \ifnum#1=89 } + }{#1 is a Fibonacci number lower than 100.} + {#1 isn't a Fibonnaci number lower than 100.}% + } + +\iffibonacci{55} +\Example/ + +In the example on the right, the first two conditionals (excluding negative +numbers and numbers lower than 100) are logically useless, but they save time +(the third subexpression isn't evaluated in case one of the first two is +true), and they illustrate how negation and grouping work. \cslist{ + !\ifelseif/statements/ + } +This (introduced in v.1.04) is a simple way to evaluate successive +conditionals until one is found true; the \arg{statements} are any number of +pairs \arg{conditional}\arg{statement}; when the first true \arg{conditional} +is found, its associated \arg{statement} is executed and the rest is +discarded. The conditionals there are the same as with \com\ifwhatever. The +macro can be prefixed with \com\reverse, in which case the statement +associated with the first false conditional is executed. If no conditional is +true (or false, if \com\reverse is used), nothing happens; a default case can +nonetheless be constructed with a last statement whose conditional is +\com\iftrue (or \com\iffalse with \com\reverse), as illustrated in the example +on the right. Spaces are ignored. + +The construction is the same thing as embedding each conditional into the +\false\ part of the previous one; however, it is simpler to write and to read. + +\Example +\def\checkanswer#1{% + \ifelseif{% + {\ifexpression{ \ifstring{#1}{yes} | + \ifstring{#1}{true}} } + {You agree.} + {\ifexpression{ \ifstring{#1}{no} | + \ifstring{#1}{false}} } + {You disagree.} + \iftrue + {I don't understand your answer.}}% + } + ++\checkanswer{You bet!}+ +\Example/ + + +\cslist{ !\afterfi/code/, !\afterdummyfi/code/ } -You shouldn't use these. The first one closes the -current conditional and executes \arg{code}. The second -one lets go one \com\fi and executes \arg{code}. So these -are kinds of \com\expandafter's when \arg{code} isn't just -a command. Anything before the incoming \com\fi is gobbled. -The reason why you should use one or the other -should be clear to you, otherwise you'll probably be messing -with a conditional. +You shouldn't use these. The first one closes the current conditional and +executes \arg{code}. The second one lets go one \com\fi and executes +\arg{code}. So these are kinds of \com\expandafter's when \arg{code} isn't +just a command. Anything before the incoming \com\fi is gobbled. The reason +why you should use one or the other should be clear to you, otherwise you'll +probably be messing with a conditional. \Example \iftrue @@ -1034,7 +1131,7 @@ local. The \verb/#/ character requires a backslash (so do braces and the backslash itself, but that's obvious). \cslist{ - \resetcatcodes + \restorecatcodes } This restores the catcodes of the characters changed with the previous command, which is cumulative, i.e. @@ -1063,8 +1160,10 @@ And I'm not: z. \vskip\baselineskip -The trimming macros below are adapted from -Will Robertson's \tcode{trimspace} package. +The trimming macros below are adapted from Will Robertson's \tcode{trimspace} +package. Note that trimming on the right is dangerous for braces: +\verb"\trimright{{hello} }" and \verb"\trimright{{hello}}" both result in +\verb"hello", not \verb"{hello}". \cslist{ @@ -1420,6 +1519,7 @@ is not executed in the case the \ital{first} argument is empty. \description{For statements: interruptions} +\advance\vsize by 2\baselineskip \noindent (The commands on this page are the same as those introduced with \com\dofor; they're explained @@ -1531,10 +1631,8 @@ Passed arguments, if any, should follow \comarg\ after \com\resumefor. - - - \description{For statements: passed arguments} +\advance\vsize by \baselineskip Suppose you want to retrieve the largest number in diff --git a/Master/texmf-dist/tex/generic/texapi/texapi.tex b/Master/texmf-dist/tex/generic/texapi/texapi.tex index 28f33717fb3..0312d1aeb42 100644 --- a/Master/texmf-dist/tex/generic/texapi/texapi.tex +++ b/Master/texmf-dist/tex/generic/texapi/texapi.tex @@ -4,7 +4,7 @@ % Author: Paul Isambert. % E-mail: zappathustra AT free DOT fr % Comments and suggestions are welcome. -% Date: January 2011. +% Date: October 2011. % \ifx\texapialreadyloaded\somethingtotallyundefined \else @@ -16,7 +16,7 @@ \expandafter\endinput \fi % -\def\texapiversion{1.03} +\def\texapiversion{1.04} \expandafter\edef\csname pi@restorecatcodes\endcsname{% \catcode`\noexpand\@=\the\catcode`@\relax \catcode`\noexpand\_=\the\catcode`_\relax @@ -222,7 +222,7 @@ \def\reverse#1{% \ifcs{pi@reverse_\commandtoname#1} {\usecs{pi@reverse_\commandtoname#1}} - {\senderror{texapi}{You can't use `\string\reverse' before `\string#1'}#1}% + {\unless#1}% } % \def\pi@ifdef_simple#1#2{% @@ -354,6 +354,67 @@ \fi } % +\pi@ifdef_onearg\ifwhatever{% + #1% + \ifx\pi@ifwhatever_false aa% + \pi@ifwhatever_true + \else + \expandafter\expandafter\expandafter\firstoftwo + \fi + \else + \expandafter\secondoftwo + \fi + } +\def\pi@ifwhatever_false#1\fi#2\fi{\secondoftwo} +\def\pi@ifwhatever_true#1\fi#2\fi{\fi\firstoftwo} +% +\pi@ifdef_onearg\ifexpression{% + \pi@ifexpression_or#1|\pi@terminator + } +\def\pi@ifexpression_or#1|#2\pi@terminator{% + \ifemptystring{#2} + {\pi@ifexpression_and#1&\pi@terminator} + {\ifexpression{#1}{\firstoftwo}{\pi@ifexpression_removeor#2\pi@terminator}}% + } +\def\pi@ifexpression_and#1\pi@terminator{% + \ifemptystring{#2} + {\passtrimleft{#1}\pi@ifexpression_not} + {\ifexpression{#1}{\pi@ifexpression_removeand#2\pi@terminator}{\secondoftwo}}% + } +\def\pi@ifexpression_removeor#1|\pi@terminator{% + \pi@ifexpression_or#1|\pi@terminator + } +\def\pi@ifexpression_removeand#1&\pi@terminator{% + \pi@ifexpression_or#1|\pi@terminator + } +\def\pi@ifexpression_not#1{% + \ifprefix-{#1}% See line 858, where \newstring{-} is declared, so this remains expandable. + {\expandafter\pi@ifexpression_braces\gobbleone#1{}\pi@terminator + % Trimming will also remove braces. + {\expandafter\passtrimright\expandafter{\gobbleone#1}\ifexpression} + {\expandafter\ifwhatever\expandafter{\gobbleone#1}} + \secondoftwo\firstoftwo} + {\pi@ifexpression_braces#1{}\pi@terminator + {\passtrimright{#1}\ifexpression} + {\ifwhatever{#1}}}% + } +\def\pi@ifexpression_braces#1#{% + \pi@gobbletoterminator{% + \ifemptystring{#1}} + } +% +\long\def\ifelseif#1{% + \pi@ifelseif{}#1\iftrue{}\pi@terminator + } +\long\def\pi@reverse_ifelseif#1{% + \pi@ifelseif\reverse#1\iffalse{}\pi@terminator + } +\long\def\pi@ifelseif#1#2#3{% + #1\ifwhatever{#2} + {\pi@gobbletoterminator{#3}} + {\pi@ifelseif{#1}}% + } +% % % % @@ -795,6 +856,8 @@ ##3{##1}{##2}}% } % +\newstring{-}% This is for \ifprefix on line 391 above. +% \pi@ifdef_twoarg\ifprefix{% \ifemptystring{#1}\firstoftwo {\ifcs{pi@strings_ifprefix:\detokenize{#1}} |