summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/yax
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-01-26 23:20:06 +0000
committerKarl Berry <karl@freefriends.org>2011-01-26 23:20:06 +0000
commit66c848bc93dc9fa2b85a8ad329ea12e2e0d0524b (patch)
treeee1214582fac18aca02c15125f4e2b13a6eb8824 /Master/texmf-dist/doc/generic/yax
parent556be84e15626e95b60d671dcedfad9856dc4a82 (diff)
yax (26jan11)
git-svn-id: svn://tug.org/texlive/trunk@21183 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/yax')
-rw-r--r--Master/texmf-dist/doc/generic/yax/README7
-rw-r--r--Master/texmf-dist/doc/generic/yax/yax-doc.pdfbin122924 -> 113177 bytes
-rw-r--r--Master/texmf-dist/doc/generic/yax/yax-doc.tex228
3 files changed, 175 insertions, 60 deletions
diff --git a/Master/texmf-dist/doc/generic/yax/README b/Master/texmf-dist/doc/generic/yax/README
index 8a87c10a42a..681393c8496 100644
--- a/Master/texmf-dist/doc/generic/yax/README
+++ b/Master/texmf-dist/doc/generic/yax/README
@@ -2,7 +2,7 @@ This is the README file for the YaX package.
Author: Paul Isambert.
E-mail: zappathustra AT free DOT fr
Comments and suggestions are welcome.
-Date: July 2010.
+Date: January 2011.
The package is a format-independent key system,
with some peculiarities.
@@ -20,6 +20,7 @@ yax-doc.pdf => The typeset documentation.
To process the documentation source, you need the
piTeX files (available on CTAN) on top of plain TeX
-with LuaTeX at least v.0.6. Non-free fonts are used.
+with LuaTeX at least v.0.6... except the current version
+of PiTeX on CTAN is too old.
-Licensing of this package is covered by LPPL. \ No newline at end of file
+Licensing of this package is covered by LPPL.
diff --git a/Master/texmf-dist/doc/generic/yax/yax-doc.pdf b/Master/texmf-dist/doc/generic/yax/yax-doc.pdf
index cb041e26689..f29485fc9ae 100644
--- a/Master/texmf-dist/doc/generic/yax/yax-doc.pdf
+++ b/Master/texmf-dist/doc/generic/yax/yax-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/generic/yax/yax-doc.tex b/Master/texmf-dist/doc/generic/yax/yax-doc.tex
index 8ac6af50695..01a0fd2604b 100644
--- a/Master/texmf-dist/doc/generic/yax/yax-doc.tex
+++ b/Master/texmf-dist/doc/generic/yax/yax-doc.tex
@@ -9,10 +9,13 @@
display = outlines
subject = "The YaX documentation."
+\setparameter navigator:
+ mode = outlines
+
\setparameter page:
- left = 5cm
- right = 3cm
- pageheight = 26cm
+ left = 5cm
+ right = 3cm
+ height = 26cm
\setparameter font :
command = \mainfont
@@ -36,12 +39,10 @@
\setparameter font:
command = \codefont
- name = ltype
+ name = lucon
size = 8.1pt
type = ttf
roman = {}
- bold = b
- italic = o
features = "\usevalue metafont:features -trep;"
\setparameter section:
@@ -49,6 +50,14 @@
number = none
color = ".8 0 0"
+\setparameter sectionbookmark:
+ meta = navigator
+ up = 15pt
+
+
+\pdfdef\ital#1{#1}
+
+
\def\yax{%
Y\kern-.1em \raise.15em\hbox{\sc a}\kern-.1em \lower.15em\hbox{X}%
\ifcatnext a { }{\iffnext({ }}%
@@ -64,14 +73,23 @@
\defarg\andvalue{value exists} \defarg\orvalue{no value}
\defarg\true{true} \defarg\false{false}
\defarg\codarg{code} \defarg\comarg{command}
+\newif\ifdescribebookmark
\def\describe{%
- \ifnext!{\gobbleoneand{\let\COM\ecom\Describe}}
- {\let\COM\com\Describe}%
+ \ifnext*{\describebookmarktrue\gobbleoneand\Describe}
+ {\describebookmarkfalse\Describe}%
+ }
+\def\Describe{%
+ \ifnext!{\gobbleoneand{\let\COM\ecom\DoDescribe}}
+ {\let\COM\com\DoDescribe}%
}
\def\ecom#1{{\mainfont\char"E01F}\com{#1}}
-\long\def\Describe#1#2.{%
+\long\def\DoDescribe#1#2.{%
\ifvmode \vskip\baselineskip \fi
- \noindent\llap{\color{.8 0 0}{\COM#1}\iffemptystring{#2}{\kern1em}}#2%
+ \noindent
+ \ifdescribebookmark
+ \outline[color = .4 .4 .4]{3}{\noexpand#1}%
+ \fi
+ \llap{\color{.8 0 0}{\COM#1}\iffemptystring{#2}{\kern1em}}#2%
\reverse\iffemptystring{#2}{\par\noindent}\ignorespaces
}
@@ -103,16 +121,27 @@
}
-\output{%
- \shipout\vbox to\dimexpr(\vsize+3\baselineskip){%
+%\output{%
+% \shipout\vbox to\dimexpr(\vsize+3\baselineskip){%
+% \box255
+% \vfil
+% \hbox to\hsize{\mainfont\hfil\the\pageno\hfil}%
+% }
+% \advancepageno
+% }
+%
+
+\gates def {headers}{%
+ \setbox255=\vbox to\dimexpr(\outputsize+3\baselineskip){%
\box255
\vfil
\hbox to\hsize{\mainfont\hfil\the\pageno\hfil}%
- }
- \advancepageno
+ }%
}
-
+\gates def {ship}{%
+ \shipout\box255
+ }
\vbox to 2\baselineskip{%
\vfil
@@ -169,8 +198,9 @@ has \ital{attributes} `\verb/firstname/', `\verb/motto/' and `\verb/hairstyle/'
with \ital{values} `\verb/Frank/', `\verb/Music is the best/' and `\verb/\moustache/'
respectively.
-\describe\setparameter.
-Here's how you set parameters more precisely. This command is the only way to set values.
+\describe*\setparameter.
+Here's how you set parameters more precisely. (This command is not the only way to set values.
+See below.)
Its simplified syntax is as follows:
\syntax
@@ -295,7 +325,6 @@ name. Hence, all the following are bad ideas:
two = \control sequence
% "\sequence" eats the delimitating space
three = control\sequence
-...
\example/
\noindent but they'd all be ok with quotes or braces (which
@@ -340,23 +369,96 @@ in an orderly fasion, e.g.:
\example/
\noindent Thus, I find commas to delimit values equally superfluous and find
-the odd quote better. Anyway setting parameters is far from the whole story.
-But before turning to how to use them, here's on fast way of setting a single attribute:
+the odd quote better.
+
+However, good old key-value pairs separated by commas happen to be useful
+too, for instance when a command takes some options. Hence the following
+was introduced in v.\yaxversion:
+
+\describe*\setparameterlist\paralist\oarg{optional macro}\arg{attribute(s) = value list}.
+This produces exactly the same thing as \com\setparameter, only the syntax
+changes. Ignoring the optional argument in the middle, our example just above
+would be rewritten as:
+
+\example
+\setparameterlist{page}{pagewidth = 32cm, pageheight = 30cm, whatever=\foo}
+\example/
+
+\noindent Here you can forget about how values are given: the delimiter is
+the comma, end of story. There can be several parameters in the first argument,
+and several attributes before each `\verb"="' sign in the second; in both cases,
+they are separated by spaces, as above. Also, each list of attributes can be
+prefixed with \verb"e:", \verb"g:" and \verb"x:", again as with \com\setparameter.
+Finally, as shown in the example, space is trimmed away.
+
+But \com\setparameterlist has a feature that \com\setparameter doesn't have.
+If one of the \attr = \value pair doesn't contain a `\verb"="', i.e. if it
+isn't a pair at all, then one of the following happens: if there is no
+\arg{optional macro}, then the default value `\verb"true"' is assigned to
+all the attributes mentionned; besides, the entry can still be prefixed with
+\verb"e:", \verb"g:" or \verb"x:". For instance, the following two statements
+are equivalent:
+
+\example
+\setparameterlist{Zappa}{guitarist composer}
+\setparameterlist{Zappa}{guitarist composer = true}
+\example/
-\describe\setattribute\paramatt=\value\arg{space}.
+On the other hand, if the \arg{optional macro} is present, then it should
+take one argument, and the entry is passed to it (trimmed, though). What
+happens then is none of \yax's concern, although of course the macro can
+itself set parameters. For instance, in the following, \verb"a" and \verb"b"
+will be set to `\verb"what"' and `\verb"are you kidding"', whereas `\verb"eddie?"'
+is passed to \com\dosomething.
+
+\example
+\def\dosomething#1{ ... #1 ... }
+\setparameter{whatever}[\dosomething]{a = what, b = are you kidding, eddie?}
+\example/
+
+Another way to set a parameter is as follows:
+
+\describe*\copyparameter\paralist:\param\arg{space}.
+\describe\gcopyparameter\paralist:\param\arg{space}.
+All the attributes of the parameters in \paralist are copied
+to \param; if the latter already has some attributes, they're
+aren't deleted (but you can use \com\deleteparameter beforehand,
+see below) although they might be overwritten. If several parameters
+in \paralist have the same attribute, the value of the last parameter
+in the list wins. The difference between the two versions is that
+the second is global. The space shouldn't be forgotten, it's the
+same as explained in the \paramatt syntax \jumplink{values}{\ital{below}}.
+
+
+Finally, here's one fast way of setting a single attribute:
+
+\describe*\setattribute\paramatt=\value\arg{space}.
\describe\esetattribute\paramatt=\value\arg{space}.
\describe\gsetattribute\paramatt=\value\arg{space}.
\describe\xsetattribute\paramatt=\value\arg{space}.
This sets \attr (no list) for \param (no list) to \value; see
-below for the \paramatt syntax. Note that the \arg{space} is for real,
+\jumplink{values}{\ital{below}} for the \paramatt syntax. Note that the \arg{space} is for real,
so don't forget it. The `=' sign may be surrounded by optional space.
This command can be used instead of \com\setparameter for two reasons:
first, it is much faster (because it doesn't take lists into account);
second, if \param is active it is \ital{not} executed (see the section
-\pdfstartlink attr{/B [0 0 0]} goto name{defpar} \ital{Defining parameters}\pdfendlink).
+\jumplink{defpar}{\ital{Defining parameters}}).
The \verb"e-", \verb"g-" and \verb"x-"versions sets the attribute
with the \verb"e:", \verb"g:" and \verb"x:" prefixes respectively.
+\describe*\deleteattribute\paramatt.
+\describe\gdeleteattribute\paramatt.
+This deletes \paramatt, which now responds negatively
+to all previous commands, as if it was never defined.
+The second version makes this deletion global, the first
+keeps it local.
+
+\describe*\deleteparameter\paralist:.
+\describe\gdeleteparameter\paralist:.
+This deletes all paramaters in \paralist; it is equivalent to using
+the previous command on all the parameters' attributes. The
+first version is local, the second is global. And yes, the colon is
+really there, although it might get away.
@@ -434,7 +536,7 @@ be freely set and queried.
-\section{Using values}
+\section{Using values}[values]
\noindent Once attributes have been set, they can be queried by the macros
that follow. But first, one last bit of odd syntax: \paramatt means anything
@@ -449,9 +551,8 @@ how to create commands with the same meaning but a different syntax.
In what follows, fully expandable commands are marked with \color{.8 0 0}{\char"E01F}.
-\describe!\nometa\arg{command}.
-All the commands that follow can be prefixed with \com\nometa, except
-\com\deleteattribute. In this case,
+\describe*!\nometa\arg{command}.
+All the commands that follow except \com\parameterloop can be prefixed with \com\nometa. In this case,
\yax will return the value of the attribute for the specified parameter,
as usual, or return no value, i.e. it will not search \verb/meta/ parameters.
So, in what follows, `\paramatt is defined' means two things. If \com\nometa
@@ -459,7 +560,7 @@ isn't used, it means that \param has \attr or it has a metaparameter with
\attr; on the other hand, if \com\nometa is used, it means that \param has
\attr, end of story.
-\describe!\ifattribute\paramatt\true\false.
+\describe*!\ifattribute\paramatt\true\false.
This returns \true if \paramatt is defined, \false otherwise. Since all
commands below always check whether \paramatt is defined before trying
to do anything with the value, this command can be avoided most of the
@@ -488,7 +589,7 @@ time.
-\describe!\usevalue\paramatt.
+\describe*!\usevalue\paramatt.
\describe!\usevalueor\paramatt\orvalue.
\describe!\usevalueand\paramatt\andvalue\orvalue.
The first macro returns the value of \paramatt if it exists, or
@@ -508,7 +609,8 @@ and he played the \usevalueor Zappa : instrument
\Example/
-\describe!\passvalue\codarg\paramatt.
+\iflines4{}{\breakpage}
+\describe*!\passvalue\codarg\paramatt.
\describe!\passvalueor\codarg\paramatt\orvalue.
\describe!\passvalueand\codarg\paramatt\andvalue\orvalue.
These return \codarg\barg{value} if \paramatt is defined,
@@ -522,7 +624,7 @@ occupation \nometa\passvalueor\whichwas Zappa : job
{(you know which)}.
\Example/
-\describe!\passvaluenobraces\codarg\paramatt.
+\describe*!\passvaluenobraces\codarg\paramatt.
\describe!\passvaluenobracesor\codarg\paramatt\orvalue.
\describe!\passvaluenobracesand\codarg\paramatt\andvalue\orvalue.
These are the same as \com\passvalue and variants except the
@@ -530,7 +632,7 @@ value of the attribute is concatenated to \codarg without braces
(which means that no braces are added in the process, not that
braces are removed from the value if it has any).
-\describe\settovalue\arg{dimen or count}\paramatt.
+\describe*\settovalue\arg{dimen or count}\paramatt.
\describe\settovalueor\arg{dimen or count}\paramatt\orvalue.
\describe\settovalueand\arg{dimen or count}\paramatt\andvalue\orvalue.
This sets the first argument to the value of \paramatt if it exists.
@@ -569,7 +671,7 @@ prophylactic \com\relax.
-\describe\storevalue\comarg\paramatt.
+\describe*\storevalue\comarg\paramatt.
\describe\storevalueor\comarg\paramatt\orvalue.
\describe\storevalueand\comarg\paramatt\andvalue\orvalue.
These define \comarg as the value of \paramatt if it exists.
@@ -582,7 +684,7 @@ These define \comarg as the value of \paramatt if it exists.
-\describe!\ifvalue\paramatt=\value\ \true\false.
+\describe*!\ifvalue\paramatt=\value\ \true\false.
This returns \true if the value of \paramatt is \value
and \false otherwise (including unexisting \paramatt).
Note that when comparing the value of \paramatt with
@@ -603,8 +705,7 @@ with an emptyness-tester (e.g. \verb/texapi/'s
\Example
\bgroup \catcode`\Z=13
-\setparameter foo :
- g: bar = Z \par
+\setparameter foo : g: bar = Z \par
\egroup
\edef\foobar{%
\ifvalue foo : bar = Z {yes}{no},
@@ -614,8 +715,8 @@ with an emptyness-tester (e.g. \verb/texapi/'s
-
-\describe!\ifcasevalue\paramatt.
+\iflines2{}{\breakpage}
+\describe*!\ifcasevalue\paramatt.
\describe\val\value\ \codarg.
\describe\val\value\ \codarg.
\verb/.../ \par\noindent
@@ -654,15 +755,27 @@ bumping into conditional structure.
\Example/
-\describe\deleteattribute\paramatt.
-This deletes \paramatt, which now responds negatively
-to all previous commands, as if it was never defined.
-If \paramatt doesn't exist, and if \param has \verb/meta/-parameters
-with \attr, those are not deleted. Hence \com\nometa can't be
-prefixed to \com\deleteattribute, because it doesn't make sense.
+\describe*!\parameterloop\paralist:\arg{code}.
+This loops on all the attributes for all the parameters in \paralist,
+and passes the following thing to \arg{code}: the parameter, the attribute,
+and the value. Hence \arg{code} can be anything, but it should be prepared
+to handle three arguments. The order in which parameters are enumerated is the
+order in \paralist, and for attributes it is the order in which they were set
+for a given parameter. Only actual attributes are enumerated: if you loop over
+\verb"ParameterA", which doesn't have \verb"AttributeA" but has a \verb"meta"
+parameter with that attribute, then \verb"AttributeA" will \emph{not} be
+enumerated in the loop.
+\Example
+\setparameter musician : job = music\par
+\setparameter zappa :
+ meta = musician
+ instrument = guitar
+\def\showvalues#1#2#3{#1 : #2 = #3\par}
+\parameterloop musician zappa : \showvalues
+\Example/
\section{Using another syntax}
@@ -690,7 +803,7 @@ time calling \com\usevalue (and what if it is redefined?) when
it could be in direct relation with internal code. So here's how
to circumvent \yax's syntax and/or create new names.
-\describe\newsyntax\arg{syntax}\barg{prefix}.
+\describe*\newsyntax\arg{syntax}\barg{prefix}.
This creates commands whose names are \verb/\/\arg{prefix}\comarg
and whose syntax for arguments is \arg{syntax}. The latter is
a parameter text which must contain \verb/#1/ and \verb/#2/ (for
@@ -718,11 +831,11 @@ and \verb/-and/ variants, which are created too, if any):
\com\deleteattribute and \com\restrictattribute (which you'll learn
about in the next section).
-\describe\copysyntax\arg{prefix1}\arg{prefix2}.
+\describe*\copysyntax\arg{prefix1}\arg{prefix2}.
This defines all the commands above with \arg{prefix1} as
those same commands with \arg{prefix2}.
-\describe\letyaxcommand\arg{command1}\arg{command2}.
+\describe*\letyaxcommand\arg{command1}\arg{command2}.
This at the very least \com\let \arg{command1} to \arg{command2}.
Besides, if \arg{command2} can take a \com\nometa prefix,
\arg{command1} can too. Finally, if \arg{command2} has
@@ -749,7 +862,7 @@ of course has the same syntax.
\section{Restrictions on parameters and attributes}
-\describe\restrictparameter\paralist:\attrlist\tcode{\char`\\par}.
+\describe*\restrictparameter\paralist:\attrlist\tcode{\char`\\par}.
After this declaration, the \param's in \paralist (where they are separated
by space as in \com\setparameter) can take only those \attr's in
\attrlist (which are also separated by space). It affects \com\setparameter
@@ -771,11 +884,11 @@ and \verb/four/ for \verb/foo/, and not only \verb/four/. The idea behind
as making the use of a parameter clearer by indicating which attributes
are in use with it, especially if it can be executed (see below).
-\describe\restrictattribute\paramatt\ \vallist\tcode{\char`\\par}.
+\describe*\restrictattribute\paramatt\ \vallist\tcode{\char`\\par}.
This restricts \paramatt to take only the values in \vallist (separated
by space).
-\describe\restrictallattributes\attr\ \vallist\tcode{\char`\\par}.
+\describe*\restrictallattributes\attr\ \vallist\tcode{\char`\\par}.
This restricts \attr, whatever the \param in which it appears, to
take only the values in \vallist. In this command, \attr is
found as anything before the first space, e.g.:
@@ -800,10 +913,9 @@ only the former restriction holds. E.g.:
-\section{Defining parameters}
-\pdfdest name {defpar} xyz
+\section{Defining parameters}[defpar]
-\describe\defparameter\paralist\barg{definition}.
+\describe*\defparameter\paralist\barg{definition}.
Parameters aren't just a way of organizing attributes. They
can have a definition and act as commands whose arguments
are the values of their attributes. The \paralist (with
@@ -835,7 +947,7 @@ to
...
\example/
-\describe!\executeparameter\param:.
+\describe*!\executeparameter\param:.
This executes the definition of \param with the the latest values
of its attributes. If \param hasn't been defined, nothing happens.
@@ -846,7 +958,7 @@ of its attributes. If \param hasn't been defined, nothing happens.
\Example/
-\describe\defactiveparameter\paralist\barg{definition}.
+\describe*\defactiveparameter\paralist\barg{definition}.
This does the same thing as \com\defparameter, i.e. define the
parameters in \paralist, but it also set them as `active,'
which means that they're automatically executed each time
@@ -870,7 +982,7 @@ Cool.
\Example/
-{\it\noindent See next page for the last example.}
+%{\it\noindent See next page for the last example.}
\Example
@@ -915,4 +1027,6 @@ Perhaps Do lore, aim... then, huh?
\section{New new ideas}
Etc.
\Example/
-\bye \ No newline at end of file
+
+\finishpdffile
+\bye