summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/keys3/README38
-rw-r--r--Master/texmf-dist/doc/latex/keys3/keys3-test.tex394
-rw-r--r--Master/texmf-dist/doc/latex/keys3/keys3.pdfbin0 -> 444041 bytes
-rw-r--r--Master/texmf-dist/doc/latex/keys3/keys3opts2.pdfbin0 -> 313237 bytes
4 files changed, 432 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/keys3/README b/Master/texmf-dist/doc/latex/keys3/README
new file mode 100644
index 00000000000..b79a089d7dc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keys3/README
@@ -0,0 +1,38 @@
+---------------------------------------------------------------
+The keys3 package --- Key management for LaTeX3
+Maintained by Joseph Wright
+E-mail: joseph.wright@morningstar2.co.uk
+Released under the LaTeX Project Public License v1.3c or later
+See http://www.latex-project.org/lppl.txt
+---------------------------------------------------------------
+
+The keys3 package is an experimental implementation of key
+management for LaTeX3. The entire package is written in
+expl3 code rather than in traditional TeX/LaTeX. The key
+module used by keys3 is based on that introduced by the
+pgfkeys package from the pgf/TiKZ bundle. Keys are thus
+addressed in a path-like manner, and are controlled by key
+properties:
+
+/module/key/.code:n = <code>,
+/module/key/.value_required:,
+/module/key = <value>
+
+The keys3 package is intended as a method for testing how key
+management might be implemented in LaTeX3. Both the methods
+used inside the package and the interface provided are intended
+to be discussed. Feedback is welcomed either by e-mail
+(joseph.wright@morningstar2.co.uk) or at the package website
+(http://keys3.berlios.de).
+
+The experimental nature of keys3 and the underlying expl3
+system means that it should not be used in production
+documents. However, programmers testing expl3, or keen to work
+on improved key management systems, are encouraged to try the
+package and provide feedback.
+
+keys3 is *not* an official LaTeX3 team package. Whether any of
+the ideas explored here will be taken up by the team is
+therefore unknown. However, the keys3 package should provide
+ideas on what needs to be available for key management and how
+it can be implemented.
diff --git a/Master/texmf-dist/doc/latex/keys3/keys3-test.tex b/Master/texmf-dist/doc/latex/keys3/keys3-test.tex
new file mode 100644
index 00000000000..2715d0f8a91
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keys3/keys3-test.tex
@@ -0,0 +1,394 @@
+% !TEX program = pdflatex
+%
+% This is a test file demonstrating the keys3 experimental LaTeX3
+% package. This file illustrates the methods made available by keys3
+% for managing key-value input. It also acts as a check, as almost all
+% of the keys3 methods are used (with known output) and because a number
+% of errors are deliberately raised.
+
+\documentclass{article}
+\usepackage{keys3,xparse}
+\usepackage[parfill]{parskip}
+
+% The document commands for creating keys is very simple. A generic
+% one is created to set any modules keys, and one specific to the module
+% used here.
+\ExplSyntaxOn
+
+\DeclareDocumentCommand{\SetModuleKeys}{m}{
+ \keys_manage:n{
+ module~name/.cd:,
+ #1}
+}
+
+\DeclareDocumentCommand{\SetKeys}{m}{
+ \keys_manage:n{#1}
+}
+
+\ExplSyntaxOff
+
+\begin{document}
+
+% Each test starts with a short piece of text explaining the property
+% being used. Under this, the expected output is given, followed
+% if relevant by the text of any error messages expected.
+
+% Test one: Simply creating a key with one argument and then using it.
+% Notice that the text length determines the limits of the argument:
+% spaces at either end are ignored. Literal spaces between text are
+% counted, as are those enclosed in braces.
+% ----------------------------------------------------------------------
+% You said: `Hello World'
+% You said: ` Hello World '
+% You said: `'
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key/.code:n = {You said: `#1'\\},
+ key = Hello World ,
+ key = { Hello World },
+ key
+}
+
+% Test two: Creating a multiple-argument key. Here, the arguments
+% given need to be at least as many as those required by the code!
+% ----------------------------------------------------------------------
+% You said: `A', `B', `C', D'.
+% You said: `AAA', `BBB', `CCC', ` DDD'.
+% You said: `', `', `', `'.
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key/.code:Nn = 4 {You said: `#1', `#2', `#3', `#4'.\\},
+ key = ABCD,
+ key = {AAA}{BBB} {CCC} { DDD},
+ key =,
+}
+
+% Test three: The ability to change the key path is available with the
+% .cd: property. The following moves from the key root to two separate
+% paths, creating keys with the same names.
+% ----------------------------------------------------------------------
+% A key in path one
+% A key in path two
+% A key in path two
+% A key in path one
+% ----------------------------------------------------------------------
+\SetKeys{
+ /path one/.cd:,
+ key/.code:n = A key in path one\\,
+ /path two/.cd:,
+ key/.code:n = A key in path two\\,
+ /path one/key,
+ /path two/key,
+ key,
+ /path one/.cd:,
+ key
+}
+
+% Test four: Variants of .code:n and .code:Nn exist which carry out a
+% full expansion on code definition. First the :x variant is tested.
+% ----------------------------------------------------------------------
+% Temp holds: ABC
+% Temp hold: 123
+% ----------------------------------------------------------------------
+\newcommand*{\temp}{123}
+\SetModuleKeys{
+ key one/.code:n = Temp holds: \temp\\,
+ key two/.code:x = Temp holds: \temp,
+}
+\renewcommand*{\temp}{ABC}
+\SetModuleKeys{
+ key one,
+ key two
+}
+% Now the :Nx version
+% ----------------------------------------------------------------------
+% Arguments: A, B. Temp holds: ABC
+% Arguments: 1, 2. Temp hold: 123
+% ----------------------------------------------------------------------
+\renewcommand*{\temp}{123}
+\SetModuleKeys{
+ key one/.code:Nn = 2 {Arguments: #1, #2. Temp holds: \temp\\},
+ key two/.code:Nx = 2 {Arguments: #1, #2. Temp holds: \temp},
+}
+
+\renewcommand*{\temp}{ABC}
+\SetModuleKeys{
+ key one = {A} {B},
+ key two = {1} {2}
+}
+
+% Test five: Values can be required and forbidden with the
+% .value_required: and .value_forbidden: properties.
+% ----------------------------------------------------------------------
+% All okay
+% All okay
+% ----------------------------------------------------------------------
+% The key `/module name/key' cannot taken a value:
+% the given input `Not allowed' is being ignored.
+%
+% The key `/module name/key' requires a value
+% and is being ignored.
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key/.code:n = {All okay\\},
+ key/.value_forbidden:,
+ key,
+ key = Not allowed,
+ key/.code:n = #1,
+ key/.value_required:,
+ key = {All okay},
+ key
+}
+
+% Test six: Keys can be given a default value, to be used if nothing is
+% specified by the user.
+% ----------------------------------------------------------------------
+% Default
+% Real
+% Default
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key/.code:n = {#1\\},
+ key/.default:n = Default,
+ key,
+ key = Real,
+ key
+}
+
+% Test seven: Keys can be created to store data tl variable both
+% locally and globally.
+% ----------------------------------------------------------------------
+% Some content
+% Outside
+% Some content
+% Some content
+% ----------------------------------------------------------------------
+\renewcommand*{\temp}{Outside}
+\SetModuleKeys{
+ key one/.tl_set:N = \temp,
+}
+\begingroup
+\SetModuleKeys{
+ key = Some content
+}
+\temp\\
+\endgroup
+\temp\\
+\SetModuleKeys{
+ key/.tl_gset:N = \temp
+}
+\begingroup
+\SetModuleKeys{
+ key = Some content
+}
+\temp\\
+\endgroup
+\temp\\
+
+% Test eight: An expanded version of .tkp_set:N is available.
+% ----------------------------------------------------------------------
+% Unexpanded
+% Expanded
+% ----------------------------------------------------------------------
+\renewcommand*{\temp}{Expanded}
+\newcommand*{\tempa}{}
+\newcommand*{\tempb}{}
+\SetModuleKeys{
+ key one/.tl_set:N = \tempa,
+ key two/.tl_set_x:N = \tempb,
+ key one = \temp,
+ key two = \temp,
+}
+\renewcommand*{\temp}{Unexpanded}
+\tempa\\
+\tempb\\
+
+% Test nine: Storage functions for int, skip and toks variables are also
+% available. Both local and global setting is possible, although there
+% are no "x" versions.
+% ----------------------------------------------------------------------
+% 12345
+% 10.00002pt
+% abc
+% ----------------------------------------------------------------------
+\newcount\tempint
+\newskip\tempskip
+\newtoks\temptoks
+\SetModuleKeys{
+ key/.int_set:N = \tempint,
+ key = 12345,
+ key/.skip_set:N = \tempskip,
+ key = 1 em,
+ key/.toks_set:N = \temptoks,
+ key = abc
+}
+\the\tempint\\
+\the\tempskip\\
+\the\temptoks
+
+% Test ten: Variables can be identified only by the unique part of their
+% name, provided that /keys/current_module:n has been set with the
+% appropriate information. Both local and global names can be used in
+% this way.
+% ----------------------------------------------------------------------
+% Local
+% Global
+% ----------------------------------------------------------------------
+\ExplSyntaxOn
+\tl_new:N \l_module_local_tl
+\tl_new:N \g_module_global_tl
+\ExplSyntaxOff
+\SetModuleKeys{
+ /keys/current_module:n = module,
+ key one/.tl_set:n = local,
+ key two/.tl_gset:n = global,
+ key one = Local,
+ key two = Global
+}
+\ExplSyntaxOn
+\l_module_local_tl \\
+\g_module_global_tl
+\ExplSyntaxOff
+
+% Test eleven: Boolean keys are created in the same way as other storage
+% keys. However, the key will then only accept "true" and "false" as
+% input. The key name can be given alone, resulting in the switch being
+% set "true".
+% ----------------------------------------------------------------------
+% Local switch true
+% Global switch true
+% ----------------------------------------------------------------------
+% Key `/module name/key one' takes the Boolean values
+% `true' and `false' only.
+% The given value `rubbish' is being ignored.
+% ----------------------------------------------------------------------
+\ExplSyntaxOn
+\bool_new:N \localbool
+\bool_new:N \g_module_global_bool
+\ExplSyntaxOff
+\SetModuleKeys{
+ /keys/current_module:n = module,
+ key one/.bool_set:N = \localbool,
+ key two/.bool_gset:n = global,
+ key one = true,
+ key two = false,
+ key two,
+ key one = rubbish
+}
+\ExplSyntaxOn
+\bool_if:NTF \localbool { Local~switch~true } { Local~switch~false } \\
+\bool_if:NTF \g_module_global_bool
+ { Global~switch~true } { Global~switch~false }
+\ExplSyntaxOff
+
+% Test twelve: The logic for Boolean keys can be reversed using the
+% .bool_set_inverse:N and related properties. This can be used with
+% in concert with .bool_set:N to create complementary keys.
+% ----------------------------------------------------------------------
+% Hello World
+% Hello User
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ /keys/current_module:n = module,
+ key one/.bool_set_inverse:N = \localbool,
+ key two/.bool_gset_inverse:n = global,
+ key one,
+ key two = true,
+}
+\ExplSyntaxOn
+\bool_if:NTF \localbool { Local~switch~true } { Local~switch~false } \\
+\bool_if:NTF \g_module_global_bool
+ { Global~switch~true } { Global~switch~false }
+\ExplSyntaxOff
+
+% Test thirteen: Choices can be created either from a list of options or
+% one by one. Both are tested here by creating a list then adding to it
+% with an extra key. Unknown choices lead to an error message.
+% ----------------------------------------------------------------------
+% Choice `a' is number 1
+% Choice `b' is number 2
+% Choice `c' is number 3
+% An extra choice
+% ----------------------------------------------------------------------
+% Choice `e' unknown for key `/module name/key/e':
+% the key is being ignored.
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key/.create_choices:nn = {a,b,c}
+ {Choice `\csname l_keys_current_choice_tl\endcsname' is number
+ \the\csname l_keys_current_choice_int\endcsname \\},
+ key/d/.code:n = {An extra choice \\},
+ key = a,
+ key = b,
+ key = c,
+ key = d,
+ key = e
+}
+
+% Test fourteen: Keys can be used to set other keys. One or more
+% arguments can be accepted when this happens, allowing complex key
+% setting to be carried out easily. There are expanded versions of these
+% properties, which work similarly.
+% ----------------------------------------------------------------------
+% Hello Fred.
+% How are you, Fred?
+% Hello Fred.
+% How are you, Ginger?
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key one/.code:n = {Hello #1.\\},
+ key two/.code:n = {How are you, #1?\\},
+ key three/.use_keys:n = { key one = #1, key two = #1},
+ key three = Fred,
+ key three/.use_keys:Nn = 2 { key one = #1, key two = #2},
+ key three = {Fred} {Ginger}
+}
+
+% Test fifteen: The .try:w and .retry:w properties attempt to set a key
+% only if it exists. The .try:w property does this for every key it
+% is given, whereas .retry: only works if the previous .try:w failed.
+% ----------------------------------------------------------------------
+% Hello
+% World
+% Seen
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key one/.code:n = {#1\\},
+ key two/.code:n = {#1\\},
+ key one/.try:n = Hello,
+ key ten/.try:n = Rubbish,
+ key two/.try:n = World,
+ key two/.retry:n = Not seen,
+ key ten/.try:n = Rubbish,
+ key two/.retry:n = Seen,
+}
+
+% Test sixteen: Two programmers tools, .show_code: and .show_key:, do
+% pretty much what might be expected. .show_key: is mainly useful for
+% internal keys.
+% ----------------------------------------------------------------------
+% a or b
+% ----------------------------------------------------------------------
+% > \keys-root/module name/key one/._cmd:w=\long macro:
+% #1#2->#1 or #2.
+%
+% > \keys-root/module name/key one/._num_args_tl=macro:
+% ->2.
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ key one/.code:Nn = 2 {#1 or #2},
+ key one = ab,
+ key one/.show_code:,
+ key one/._num_args_tl/.show_key:,
+}
+
+% Test seventeen: A completely unknown key should cause an error.
+% ----------------------------------------------------------------------
+% The key `/module name/unknown key' is unknown and is being ignored
+% ----------------------------------------------------------------------
+\SetModuleKeys{
+ unknown key = some value
+}
+
+\end{document}
+
diff --git a/Master/texmf-dist/doc/latex/keys3/keys3.pdf b/Master/texmf-dist/doc/latex/keys3/keys3.pdf
new file mode 100644
index 00000000000..3d26fd7fdfe
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keys3/keys3.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf
new file mode 100644
index 00000000000..cdc4783125a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf
Binary files differ