summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-04-07 22:47:28 +0000
committerKarl Berry <karl@freefriends.org>2010-04-07 22:47:28 +0000
commit3f1971c9b7717818766692c9aa497e20e7472f2c (patch)
tree678de0190b6643b1b21fd9441fa1387bce180726 /Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
parentc7c3b090320a234149dbe23315e2a15a2773ac79 (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.html62
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&rsquo;t very kind to the user, and that a package such as
+position, aren&#8217;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 &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
+This has defined two keys &#8216;<code>foo</code>&#8217; and &#8216;<code>bar</code>&#8217; in family
+&#8216;<code>my</code>&#8217;, and then executed them, the first with argument
+&#8216;<code>3</code>&#8217; and the second with no argument, so that the default
+value of &#8216;<code>99</code>&#8217; 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 &lsquo;<code>99</code>&rsquo; 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 &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>.)
+process each key &#8212; it is easy to regurgitate the structure of the
+command name, with family name (&#8216;<code>my</code>&#8217;, here) after the first
+&#8216;<code>@</code>&#8217;, and the key name after the second &#8216;<code>@</code>&#8217;. (The
+&#8216;<code>KV</code>&#8217; 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
+<p/>However, we need more if we&#8217;re to to have package options in
+&#8216;key-value&#8217; 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
+<code>\</code><code>ProcessOptions</code> time: <i>keyval</i> can&#8217;t do that on its own.
+<p/>Heiko Oberdiek&#8217;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
+or may be &#8216;cancelled&#8217; to avoid confusion. If you have loaded
+<i>kvoptions</i>, the LaTeX kernel&#8217;s <code>\</code><code>DeclareOption</code> becomes
+<code>\</code><code>DeclareVoidOption</code> (it&#8217;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
+<p/>Hendri Adriaens&#8217; <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,
-&ldquo;utilities&rdquo;) contains a useful comparison with other key-value
+&#8220;utilities&#8221;) 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.
-&hellip; and that code is also set up using <code>\</code><code>pgfkeys</code>:
+&#8230; 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 &rsquo;hi!&rsquo;.
+ The value is &#8217;hi!&#8217;.
</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,
+particular key sequences (which are called &#8220;styles&#8221;). 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
+isn&#8217;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&rsquo;s part of larger set of macros is
+<p/>Another key-value system that&#8217;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 &lsquo;key family&rsquo;. The user may define family
-&lsquo;members&rsquo; and keys are defined relative to the members. (For example,
+on the structure of the &#8216;key family&#8217;. The user may define family
+&#8216;members&#8217; 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
+of the package in terms of the package&#8217;s key family. Note that there
+is no special provision made for &#8220;traditional&#8221; 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>)