diff options
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/README | 38 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3-test.tex | 394 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3.pdf | bin | 0 -> 444041 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf | bin | 0 -> 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 Binary files differnew file mode 100644 index 00000000000..3d26fd7fdfe --- /dev/null +++ b/Master/texmf-dist/doc/latex/keys3/keys3.pdf diff --git a/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf Binary files differnew file mode 100644 index 00000000000..cdc4783125a --- /dev/null +++ b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf |