summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/texapi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-10-02 23:04:11 +0000
committerKarl Berry <karl@freefriends.org>2011-10-02 23:04:11 +0000
commitbb33b6aa379703cfbc67cab3ceace446e594fa3b (patch)
tree4c08d23164f533a068cf9106a6e44bb07ac737c8 /Master/texmf-dist/doc/generic/texapi
parentaf940299969ece442832d1700f8359006f70dff7 (diff)
texapi 1.04 (2oct11)
git-svn-id: svn://tug.org/texlive/trunk@24170 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/texapi')
-rw-r--r--Master/texmf-dist/doc/generic/texapi/README4
-rw-r--r--Master/texmf-dist/doc/generic/texapi/texapi-doc.pdfbin161785 -> 131636 bytes
-rw-r--r--Master/texmf-dist/doc/generic/texapi/texapi-doc.tex246
3 files changed, 174 insertions, 76 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
index 7e643911aab..c1a196bd7d6 100644
--- a/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf
+++ b/Master/texmf-dist/doc/generic/texapi/texapi-doc.pdf
Binary files differ
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