diff options
author | Karl Berry <karl@freefriends.org> | 2010-04-07 22:47:28 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-04-07 22:47:28 +0000 |
commit | 3f1971c9b7717818766692c9aa497e20e7472f2c (patch) | |
tree | 678de0190b6643b1b21fd9441fa1387bce180726 /Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html | |
parent | c7c3b090320a234149dbe23315e2a15a2773ac79 (diff) |
FAQ-en 3.19d (7apr10)
git-svn-id: svn://tug.org/texlive/trunk@17742 c570f23f-e606-0410-a88d-b1316a301751
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 | 62 |
1 files changed, 31 insertions, 31 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 index 1781ef5dc91..12dd6fc6bb7 100644 --- a/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html +++ b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html @@ -5,7 +5,7 @@ <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 +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. @@ -26,10 +26,10 @@ will produce output saying: 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 +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> @@ -38,34 +38,34 @@ value of ‘<code>99</code>’ is picked up. In effect, the two calls t </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>.) +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 +<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 +<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 +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 +<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 @@ -76,7 +76,7 @@ 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 +“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 @@ -99,7 +99,7 @@ added automatically. So a <code>\</code><code>pgfkeys</code> command might be: </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>: +… and that code is also set up using <code>\</code><code>pgfkeys</code>: <blockquote> <pre> \pgfkeys{/my key/.code=The value is '#1'.} @@ -113,13 +113,13 @@ after which </blockquote><p> will produce just <blockquote> - The value is ’hi!’. + 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, +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 +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/>The <i>expl3</i> programming layer for <a href="FAQ-LaTeX3.html">LaTeX3</a> @@ -131,7 +131,7 @@ for defining and setting keys. There is also a support package, options to be processed using <i>l3keys</i>. The <i>expl3</i> code can be used within existing LaTeX2e documents, so <i>l3keys</i> is available to the LaTeX2e programmer. -<p/>Another key-value system that’s part of larger set of macros is +<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 @@ -139,25 +139,25 @@ 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, +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 +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. <dl> -<dt><tt><i>keyval.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/required/graphics.zip">macros/latex/required/graphics</a> (or <a href="http://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/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://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/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>) +<dt><tt><i>keyval.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/required/graphics.zip">macros/latex/required/graphics</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/required/graphics/">browse the directory</a>)[keyval +<dt><tt><i>kvoptions.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>); <a href="http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/kvoptions.html">catalogue entry</a> +<dt><tt><i>kvsetkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>); <a href="http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/kvsetkeys.html">catalogue entry</a> <dt><tt><i>l3keys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/expl3.zip">macros/latex/contrib/expl3</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/expl3/">browse the directory</a>) -<dt><tt><i>l3keys2e.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/expl3.zip">macros/latex/contrib/expl3</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/expl3/">browse the directory</a>) +<dt><tt><i>l3keys2e.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/xpackages.zip">macros/latex/contrib/xpackages</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/xpackages/">browse the directory</a>) <dt><tt><i>pgfkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/tex-archive/graphics/pgf.zip">graphics/pgf</a> (or <a href="http://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/tex-archive/macros/latex/contrib/koma-script.zip">macros/latex/contrib/koma-script</a> (or <a href="http://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/tex-archive/macros/latex/contrib/xkeyval.zip">macros/latex/contrib/xkeyval</a> (or <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/xkeyval/">browse the directory</a>) |