diff options
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.html | 157 |
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’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 ‘<code>foo</code>’ and ‘<code>bar</code>’ in family +‘<code>my</code>’, and then executed them, the first with argument +‘<code>3</code>’ and the second with no argument, so that the default +value of ‘<code>99</code>’ 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 — it is easy to regurgitate the structure of the +command name, with family name (‘<code>my</code>’, here) after the first +‘<code>@</code>’, and the key name after the second ‘<code>@</code>’. (The +‘<code>KV</code>’ 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’re to to have package options in +‘key-value’ 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’t do that on its own. +<p/>Heiko Oberdiek’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 ‘cancelled’ to avoid confusion. If you have loaded +<i>kvoptions</i>, the LaTeX kernel’s <code>\</code><code>DeclareOption</code> becomes +<code>\</code><code>DeclareVoidOption</code> (it’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’ <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, +“utilities”) 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 ’hi!’. +</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 “styles”). All in all, +it seems a well thought-out system, offering a lot of flexibility that +isn’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’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 ‘key family’. The user may define family +‘members’ 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’s key family. Note that there +is no special provision made for “traditional” 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’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> |