summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/options/README
blob: 415a2f54a09d6cf107b233657e7aab0b1db2e818 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
This is the README file for the options package.

VERSION

Version 1.0, December 2015

SUMMARY

Provices convenient key-value options for LaTeX package writers.

It has a similar interface as `pgfkeys` with path options but comes with more
built-in data types and more convenient support for families and searching.
The main features of the `options` pckage are:

* Declare your options only once: in most packages you usually need to
  declare both a new command, and the option that sets it. In the
  `options` package you declare the option just once. For example,
    
      \options{/my/len/.new length} 

  and then use it anywhere else as
      
      \option{/my/len}

* _Use paths for keys_: just like `pgfkeys`, the `options` package uses
  paths (instead of families) to declare options and prevent name clashes
  between different packages. Paths are convenient for complex options,
  like `border/left/width`, and are also convenient to specify searches.

* _Many built-in data types_: the `options` library comes with many
  useful data types like `choice`, `list`, `toggle`, `num`, `dim`,
  `length`, `glue`, commands, and plain values, and it is easy to add
  your own. Also you can hook into existing definitions like an `if` or `counter`.

* _Value options_: You can define value-only options that start with a
  special character, like `"Georgia"` for a font option, or 
  `!8080FF` for a color option. 

* _Convenient searches_: you can specify paths that should be searched
  from other paths and redirect even from absolute paths. For complex
  packages this is very useful to inherit common options.

* _Easy filtering_: it is easy to collect unknown options and process
  them later. Combined with the search mechanism this makes it easy to 
  do custom processing.

* _It is fast_: for simple user options, the &options; package is a bit
  faster than `pgfkeys` and if searches or filters are involved it is
  usually about twice as fast as `pgfkeys` (and about six times faster
  as `xkeyval`).

* _Handles class and package options_: use the same option declarations
  to handle the options passed to a class or package.

LICENSE

Copyright (c) 2015 Daan Leijen.

This software is author-maintained. Permission is granted to copy,
distribute and/or modify this software under the terms of the
LaTeX Project Public License, version 1.3 or higher. This software
is provided 'as it is', without warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for any particular purpose.

RELATED PACKAGES

keyval, xkeyval, pgfkeys, longfbox

AUTHOR

Daan Leijen (daan@microsoft.com)