summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html157
1 files changed, 157 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
new file mode 100644
index 00000000000..6ca8497270c
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
@@ -0,0 +1,157 @@
+<head>
+<title>UK TeX FAQ -- question label keyval</title>
+</head><body>
+<h3>Key-value input for macros and package options</h3>
+<p/>When we discussed
+<a href="FAQ-moren9.html">extending the number of arguments to a macro</a>, we
+suggested that large numbers of arguments, distinguished only by their
+position, aren&rsquo;t very kind to the user, and that a package such as
+<i>keyval</i> offers a more attractive user interface. We now
+consider the packages that the macro programmer might use, to create
+such a user interface.
+<p/>The simplest key-value processor remains <i>keyval</i>; it has a
+command <code>\</code><code>define@key</code> to declare a key and a <em>handler</em> to
+process it, and a macro <code>\</code><code>setkeys</code> to offer values to the handler
+of one or more keys. Thus:
+<blockquote>
+<pre>
+\define@key{my}{foo}{Foo is #1\par}
+\define@key{my}{bar}[99]{Bar is #1\par}
+...
+\setkeys{my}{foo=3,bar}
+</pre>
+</blockquote><p>
+will produce output saying:
+<blockquote>
+ Foo is 3<br/>
+ Bar is 99
+</blockquote><p>
+This has defined two keys &lsquo;<code>foo</code>&rsquo; and &lsquo;<code>bar</code>&rsquo; in family
+&lsquo;<code>my</code>&rsquo;, and then executed them, the first with argument
+&lsquo;<code>3</code>&rsquo; and the second with no argument, so that the default
+value of &lsquo;<code>99</code>&rsquo; is picked up. In effect, the two calls to
+<code>\</code><code>define@key</code> are simply defining commands, as (for example):
+<blockquote>
+<pre>
+\newcommand{\KV@my@foo}[1]{Foo is #1}
+</pre>
+</blockquote><p>
+(the definition of <code>\</code><code>KV@my@bar</code> is similar, but trickier). The
+command <code>\</code><code>setkeys</code> knows how to find those commands when it needs to
+process each key &mdash; it is easy to regurgitate the structure of the
+command name, with family name (&lsquo;<code>my</code>&rsquo;, here) after the first
+&lsquo;<code>@</code>&rsquo;, and the key name after the second &lsquo;<code>@</code>&rsquo;. (The
+&lsquo;<code>KV</code>&rsquo; part is fixed, in <i>keyval</i>.)
+<p/>These simple commands are enough, in fact, to process the botanical
+example offered as replacement for multi-argument commands in
+<a href="FAQ-moren9.html">the question mentioned above</a>, or the
+optional arguments of the <code>\</code><code>includegraphics</code> command of the
+<i>graphicx</i> package. (The last is, in fact, what
+<i>keyval</i> was designed to do.)
+<p/>However, we need more if we&rsquo;re to to have package options in
+&lsquo;key-value&rsquo; form. Packages like <i>hyperref</i> have enormously
+complicated package options which need key-value processing at
+<code>\</code><code>ProcessOptions</code> time: <i>keyval</i> can&rsquo;t do that on its own.
+<p/>Heiko Oberdiek&rsquo;s <i>kvoptions</i> package comes to our help: it
+enables the programmer to declare class or package options that
+operate as key and value pairs. The package defines commands
+<code>\</code><code>DeclareBoolOption</code> for options whose value should be either
+<em>true</em> or <em>false</em>, and <code>\</code><code>DeclareStringOption</code> for all
+other options that have a value. Keys are declared using
+<i>keyval</i> and may remain available for use within the document,
+or may be &lsquo;cancelled&rsquo; to avoid confusion. If you have loaded
+<i>kvoptions</i>, the LaTeX kernel&rsquo;s <code>\</code><code>DeclareOption</code> becomes
+<code>\</code><code>DeclareVoidOption</code> (it&rsquo;s an option with no value), and
+<code>\</code><code>DeclareOption*</code> becomes <code>\</code><code>DeclareDefaultOption</code>.
+<p/>Heiko also provides <i>kvsetkeys</i> which is a more robust version
+of <i>setkeys</i>, with some of the rough edges made smoother.
+<p/>Hendri Adriaens&rsquo; <i>xkeyval</i> offers more flexibility than
+the original <i>keyval</i> and is more robust than the original,
+too. Like <i>kvoptions</i>, the package also has mechanisms to
+allow class and package options in key-value form (macros
+<code>\</code><code>DeclareOptionX</code>, <code>\</code><code>ExecuteOptionsX</code> and <code>\</code><code>ProcessOptionsX</code>.
+<i>Pstricks</i> bundle packages use a <i>xkeyval</i> derivative
+called <i>pst-xkey</i> for their own key-value manipulation.
+
+<p/>The (widely-respected) <i>pgf</i> graphics package has its own
+key-value package called <i>pgfkeys</i>. The documentation of the
+package (part of the huge <i>pgf</i> manual, in part 5,
+&ldquo;utilities&rdquo;) contains a useful comparison with other key-value
+systems; some notable differences are:
+<ul>
+<li> key organisation: <i>pgfkeys</i> uses a tree structure, while
+ <i>keyval</i> and <i>xkeyval</i> both associate keys with a family;
+<li> <i>pgfkeys</i> supports multi-argument key code; and
+<li> <i>pgfkeys</i> can support call-backs when an unknown key
+ appears (these things are called <em>handlers</em>.
+</ul>
+Keys are organized in a tree that is reminiscent of the Unix fille
+tree. A typical key might be, <i>/tikz/coordinate system/x</i> or
+just <i>/x</i>. When you specify keys you can provide the complete
+path of the key, but you usually just provide the name of the key
+(corresponding to the file name without any path) and the path is
+added automatically. So a <code>\</code><code>pgfkeys</code> command might be:
+<blockquote>
+<pre>
+\pgfkeys{/my key=hello,/your keys/main key=something\strange,
+ key name without path=something else}
+</pre>
+</blockquote><p>
+
+and for each key mentioned, the associated code will be executed.
+... and that code is also set up using <code>\</code><code>pgfkeys</code>:
+<blockquote>
+<pre>
+\pgfkeys{/my key/.code=The value is '#1'.}
+</pre>
+</blockquote><p>
+after which
+<blockquote>
+<pre>
+\pgfkeys{/my key=hi!}
+</pre>
+</blockquote><p>
+will produce just
+<blockquote>
+ The value is &rsquo;hi!&rsquo;.
+</blockquote><p>
+The manual goes on, showing how to define a key with two arguments,
+how to provide default value for a key, and how to define aliases for
+particular key sequences (which are called &ldquo;styles&rdquo;). All in all,
+it seems a well thought-out system, offering a lot of flexibility that
+isn&rsquo;t available with the other keys packages. However, there seems to
+be no mechanism for using <i>pgfkeys</i> keys as part of the
+options of another package, in the way that <i>kvoptions</i> does.
+<p/>Another key-value system that&rsquo;s part of larger set of macros is
+<i>scrbase</i>, which uses the facilities of <i>keyval</i> to
+build a larger set of facilities, originally for use within the
+<i>KOMA-script</i> bundle. For English-speaking authors, there are
+difficulties from the German-only documentation; however, from a
+partial translation available to the author of this answer, a summary
+is possible. The package may build on the facilities either of
+<i>kyeval</i> or of <i>xkeyval</i>, and builds its functionality
+on the structure of the &lsquo;key family&rsquo;. The user may define family
+&lsquo;members&rsquo; and keys are defined relative to the members. (For example,
+the package <i>scrbase</i> is part of the <i>KOMA-script</i>
+bundle; so its keys are all members of the <i>scrbase.sty</i>
+family within the <i>KOMA</i> family. The function
+<code>\</code><code>FamilyProcessOptions</code> allows the programmer to decode the options
+of the package in terms of the package&rsquo;s key family. Note that there
+is no special provision made for &ldquo;traditional&rdquo; package options, as
+in the <i>kvoptions</i> package.
+<p/>This brief summary was guided by input from two sources: a draft article
+for <i>TUGboat</i> by Joseph Wright, and the partial translation of the
+documentation of package <i>scrbase</i> prepared by Philipp
+Stephani. At Joseph&rsquo;s suggestion, discussion of his <i>keys3</i>
+package, which is designed for use with the experimental LaTeX3,
+has been omitted.
+<dl>
+<dt><tt><i>keyval.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/required/graphics.zip">macros/latex/required/graphics</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/required/graphics/">browse the directory</a>)
+<dt><tt><i>kvoptions.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>)
+<dt><tt><i>kvsetkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>)
+<dt><tt><i>pgfkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/graphics/pgf.zip">graphics/pgf</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/graphics/pgf/">browse the directory</a>)
+<dt><tt><i>scrbase.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/koma-script.zip">macros/latex/contrib/koma-script</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/koma-script/">browse the directory</a>)
+<dt><tt><i>xkeyval.sty</i></tt><dd><a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/xkeyval.zip">macros/latex/contrib/xkeyval</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk tex-archive/macros/latex/contrib/xkeyval/">browse the directory</a>)
+</dl>
+<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=keyval">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=keyval</a>
+</body>