summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/keyreader
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-11-06 22:34:41 +0000
committerKarl Berry <karl@freefriends.org>2012-11-06 22:34:41 +0000
commit2f6000f28f9662342c1cfe6e59abfdf345bd3a23 (patch)
tree355599dfbcbd8d58bafc0f0b60dd720bed14d8f5 /Master/texmf-dist/doc/latex/keyreader
parent342ef68b3bd1c09a3acb309fbd8d9c253cbcefc4 (diff)
keyreader (6nov12)
git-svn-id: svn://tug.org/texlive/trunk@28195 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/keyreader')
-rw-r--r--Master/texmf-dist/doc/latex/keyreader/README8
-rw-r--r--Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex58
-rw-r--r--Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg61
-rw-r--r--Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdfbin232171 -> 232150 bytes
-rw-r--r--Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex26
5 files changed, 75 insertions, 78 deletions
diff --git a/Master/texmf-dist/doc/latex/keyreader/README b/Master/texmf-dist/doc/latex/keyreader/README
index 25603641d83..af74a37d0ea 100644
--- a/Master/texmf-dist/doc/latex/keyreader/README
+++ b/Master/texmf-dist/doc/latex/keyreader/README
@@ -6,7 +6,11 @@ Ahmed Musa
VERSION
-Version 0.5, October 2012
+Version 0.5b, 2012/11/06
+
+LOCATION ON CTAN
+
+macros/latex/contrib/keyreader
SUMMARY
@@ -28,7 +32,7 @@ shortcomings not withstanding).
RELATED PACKAGES
-xkeyval, ltxkeys, skeyval
+xkeyval, ltxkeys, skeyval
LICENSE
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex b/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex
index bf8c56d5348..6ca57dc2ac2 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-example1.tex
@@ -1,24 +1,59 @@
\documentclass{article}
-\usepackage{keyreader}
+\usepackage{keyreader}[2012/11/01]
\usepackage{xcolor}
\usepackage{graphicx}
\makeatletter
+
+% Choice keys with braced default:
+\krddefinekeys[JKV]{jorg}{%
+ choice/key1/{A/X}/{
+ A/X.do=\def\currcolor{blue},
+ A/Y.do=\def\currcolor{green},
+ B/X.do=\def\currcolor{red},
+ B/Y.do=\def\currcolor{magenta}
+ }
+ /\def\val{Value of key1: #1}
+ ;
+ choice/align/justified/{
+ center.do=\def\curralign##1{\hfil##1\hfil},
+ right.do=\def\curralign##1{\hfill##1},
+ left.do=\def\curralign##1{##1\hfill},
+ justified.do=\let\curralign\@iden
+ }
+ ;
+}
+\krdpresetkeys[JKV]{jorg}{key1=A/X,align=justified}
+\newcommand\jorgcommand[2][]{%
+ \krdsetkeys[JKV]{jorg}{#1}%
+ \endgraf\bigskip
+ \parbox{\hsize}{\centering\textbf{\textcolor{\currcolor}{\val}}}%
+ \endgraf
+ \parbox{\hsize}{\curralign{\textcolor{\currcolor}{#2}}}%
+}
+
+% Shadow box:
\newdimen\shadowsize
\krddefinekeys*[KV]{ebox}[mp@]{%
bool/frame/true;
- bool/shadow/true;
+ bool+/shadow/true//
+ \mp@shadowtrue
+ \@@warning{Invalid value for 'shadow': 'true' assumed}
+ ;
cmd/framecolor/black;
cmd/shadecolor/white;
cmd/shadowcolor/gray;
cmd/framesize/.4pt;
cmd/boxsize/.1\columnwidth;
cmd/shadowsize/1pt;
- choice/align/center/
+ choice+/align/center/
center.do=\let\mp@alignright\hfil\let\mp@alignleft\hfil,
right.do=\let\mp@alignright\hfill\let\mp@alignleft\relax,
left.do=\let\mp@alignright\relax\let\mp@alignleft\hfill,
justified.do=\let\mp@alignright\relax\let\mp@alignleft\relax
- //\@@warning{Invalid value for 'align'};
+ //
+ \let\mp@alignright\hfil\let\mp@alignleft\hfil
+ \@@warning{Invalid value for 'align'; 'center' used}
+ ;
}
\savevaluekeys[KV]{ebox}{frame,framecolor,framesize}
\krdpresetkeys[KV]{ebox}{%
@@ -58,6 +93,7 @@
\begin{document}
\parindent-60pt
+% Shadow boxes:
\scalebox{2}{%
\ebox[shadecolor=brown!70]{ebox1}%
\ebox[framecolor=magenta,boxsize=2cm,align=right]{ebox2}%
@@ -65,4 +101,18 @@
\ebox[framesize=1pt,framecolor=green,shadowcolor=blue]{ebox4}%
\ebox[frame=false,shadow,shadowcolor=yellow,framesize=.5pt]{ebox5}%
}
+
+% Choice keys:
+\def\name#1{\texttt{\textcolor{black}{#1}}}
+\def\atext{%
+ \name{choice} keys of the \name{keyreader} package.
+}
+\jorgcommand[key1=A/X,align=justified]{\atext}
+\jorgcommand[key1=A/Y,align=center]{\atext}
+\jorgcommand[key1=B/X,align=right]{\atext}
+\jorgcommand[key1=B/Y,align=left]{\atext}
+\jorgcommand{\atext}
+% Invalid value for key1 ('x+y' not allowed):
+% \jorgcommand[key1=x+y]{\atext}
+
\end{document}
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg
deleted file mode 100644
index af803ae50e3..00000000000
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.cfg
+++ /dev/null
@@ -1,61 +0,0 @@
-\ProvidesFile{keyreader-guide.cfg}%
- [2012/10/10 v0.5 Configuration file for keyreader-guide (AM)]
-
-\amltxoptions{%
- geometryoptions = {left=3cm,right=3cm,top=2.5cm,%
- bottom=2.5cm,includeheadfoot},
- reviewdocument = false,
- parindent = false,
- toc = false,
- frontpagestyle = empty,
- pretitleskip = 0ex,
- posttitleskip = 1ex,
- presuptitleskip = 0ex,
- postsuptitleskip = 0ex,
- presubtitleskip = 0ex,
- postsubtitleskip = 0ex,
- natbiboptions = {numbers,sort&compress},
- cmdcolor = xmagenta1,
- stylecolor = xgreen1,
- speccolor = teal,
- sectionheadcolor = blue
-}
-
-\fancypagenos[%
- textalign = center,
- show-on-page-one = false,
- show-page-numbers = true,
- show-headrule = true,
- show-footrule = false,
- y-position = -.44\paperheight,
- x-position = 0,
- scale = 1,
- angle = 0,
- style = \textsc{Page~\thepage~of~\pageref{xwmlastpage}},
- left-header = The \textcolor{macrocolor}{keyreader} package,
- right-header = \ttcl{black}{\today}
-]
-
-\newwatermark[page=1,fontfamily=phv,fontsize=11pt,fontseries=m,align=center,
- coordunit=pc,width=.978\paperwidth,angle=0,scale=1,xpos=-.62,ypos=31.2]{%
- \xwmcolorbox[framesep=5pt,framerule=2pt,fillcolor=white,
- outerframecolor=Orange,innerframecolor=brown,textalign=justified,
- width=.978\paperwidth]{%
- \normalfont\small\color{black}\vspace*{-1ex}%
- \parbox{.95\paperwidth}{%
- \vspace*{2ex}%
- \begin{center}%
- \sffamily\bfseries
- \scalebox{4}{The \textcolor{blue}{keyreader} Package\titleref{t1,t2}}%
- \endgraf\vspace*{1ex}%
- \scalebox{2}{A robust interface to \pkg'{xkeyval}}%
- \endgraf\vspace*{1ex}%
- {\normalsize\normalfont\sffamily
- \copyright\ Ahmed Musa 2010-\number\year}%
- \end{center}%
- \vspace*{2ex}%
- }%
- }%
-}
-
-\endinput
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
index 2dd2392b7c4..ed0c6538c91 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
index 23eaf5618f5..2d0490d9c2b 100644
--- a/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
+++ b/Master/texmf-dist/doc/latex/keyreader/keyreader-guide.tex
@@ -40,7 +40,7 @@
\def\abstractname{\textsf{Summary}}
\begin{abstract}
\small
- The \pkg{keyreader} bundle is platform independent and provides robustness and some extensions to the \pkg'{xkeyval}. However, it is completely independent of the \pkg'{xkeyval}. It preserves braces in key values throughout parsing and saves estate when defining keys. Also, the command \fx{\krdsetkeys} allows unbalanced conditionals to be parsed as values of keys. Furthermore, when the command \fx{\krddefinekeys} is used, keys are initialized as soon as they are defined, and, unlike in the \pkg'{xkeyval}, admissible alternate values of choice keys can have individual callbacks. The looping macros of the \pkg'{xkeyval} are redefined, to increase robustness. The command \fx{\define@key} of the \pkg'{xkeyval} has had two of its subordinate commands redefined, to offset a complaint about the grabbing of the key's callback when defining keys with \fx{\define@key}. This user manual assumes that the reader is familiar with some of the functions and user interfaces of the \pkg'{xkeyval}. The \fx{\krdkeys} command ... Unlike the \pkg'{xkeyval}, the \pkg'{keyreader} can be loaded before \hx{\documentclass} and this feature doesn't affect its ability to later filter class options-list for options that have values.
+ The \pkg{keyreader} bundle is platform independent \latex package that provides robustness and some extensions to the \pkg'{xkeyval}. However, it isn't completely independent of the \pkg'{xkeyval}. It preserves braces in key values throughout parsing and saves estate when defining keys. Also, the command \fx{\krdsetkeys} allows unbalanced conditionals to be parsed as values of keys. Furthermore, when the command \fx{\krddefinekeys} is used, keys are initialized as soon as they are defined, and, unlike in the \pkg'{xkeyval}, admissible alternate values of choice keys can have individual callbacks. The looping macros of the \pkg'{xkeyval} are redefined, to increase robustness. The command \fx{\define@key} of the \pkg'{xkeyval} has had two of its subordinate commands redefined, to offset a complaint about the grabbing of the key's callback when defining keys with \fx{\define@key}. This user manual assumes that the reader is familiar with some of the functions and user interfaces of the \pkg'{xkeyval}. The \fx{\krdkeys} command ... Unlike the \pkg'{xkeyval}, the \pkg'{keyreader} can be loaded before \hx{\documentclass} and this feature doesn't affect its ability to later filter class options-list for options that have values.
\end{abstract}
\let\licensename\relax
@@ -69,8 +69,7 @@
The \pkg'{keyreader} predated the \pkg'{ltxkeys} and was developed to make key parsing by the \pkg'{xkeyval} robust (in the sense of preserving outer braces in key values throughout parsing and enabling the parsing of key values with unbalanced conditionals), as well as reduce the amount of typing that is required for defining several keys. To achieve robustness in key parsing, the \fx{\setkeys} command of the \pkg'{xkeyval} has been patched and renamed \fx{\krdsetkeys}. The \pkg'{xkeyval}'s \fx{\setkeys} remains unchanged, to avoid breaking existing codes that rely on it's current form. Some other low-level commands of \pkg'{xkeyval} have been patched and renamed. The \pkg'{keyreader} provides commands for compactly defining and setting all types of key (ordinary, command, boolean, and choice). Also, the \pkg'{keyreader} introduces the concept of callbacks for the alternate/admissible values of choice keys defined via the command \fx{\krddefinekeys}. Moreover, when \fx{\krddefinekeys} is used, keys are automatically set/initialized as soon as they are defined. This provides default definitions for the key macros and functions. Boolean keys are initialized with a value of \hx{false} irrespective of their default values.
-The \pkg'{keyreader} has been used as a development platform for the \pkg'{ltxkeys} because the \pkg'{xkeyval}, on which the \pkg'{keyreader} is based, has been quite stable for some years, its inherent
-shortcomings not withstanding. Has the user ever tried to pass to \pkg'{xkeyval}'s \fx{\setkeys} an unbalanced conditional as the value of a key? He/she will quickly be hit by the error message \quoted{! Incomplete \hx{\ifx}; all text was ignored after line \ldots}, or something similar. This limitation has been removed by the \pkg'{keyreader}.
+The \pkg'{keyreader} has been used as a development platform for the \pkg'{ltxkeys} because the \pkg'{xkeyval}, on which the \pkg'{keyreader} is based, has been quite stable for some years, its inherent shortcomings not withstanding. Has the user ever tried to pass to \pkg'{xkeyval}'s \fx{\setkeys} an unbalanced conditional as the value of a key? He/she will quickly be hit by the error message \quoted{! Incomplete \hx{\ifx}; all text was ignored after line \ldots}, or something similar. This limitation has been removed by the \pkg'{keyreader}\footnote{But, in general, parsing unbalanced conditionals isn't advisable in \tex.}.
The packages in the \pkg{keyreader} bundle are ...
@@ -190,7 +189,8 @@ The commands \ffxi'{\krdDeclareOption, \krdExecuteOptions, \krdProcessOptions} a
center.do=\def\vcp@align{center}\def\w##1{#1##1},
left.do=\def\vcp@align{flushleft},
right.do=\def\vcp@align{flushright},
- justified.do=\def\vcp@align{relax}/
+ justified.do=\def\vcp@align{relax}
+ /
\ifkrdindef\else
\def\xa##1{#1##1}
\fi;
@@ -200,20 +200,22 @@ The commands \ffxi'{\krdDeclareOption, \krdExecuteOptions, \krdProcessOptions} a
|com(Setting keys with values having unbalanced conditionals:)
\krdsetkeys[KV]{fam}{keye={\iffalse keye-value}}
-\let\warning\@latex@warning@no@line
\krddefinekeys*[KV]{fam}[mp@]{%
ord/keya/default-a/\def\x##1{#1*##1};
bool/keyb/true/;
- bool+/keyc/true//\@latexerr{Invalid value for keyc};
+ bool+/keyc/true//\@latexerr{Invalid value for keyc}\@ehd;
cmd/keyd/black;
choice+/keye/center/
center.do=\let\mp@alignright\hfil\let\mp@alignleft\hfil,
right.do=\let\mp@alignright\hfill\let\mp@alignleft\relax,
left.do=\let\mp@alignright\relax\let\mp@alignleft\hfill,
- justified.do=\let\mp@alignright\relax\let\mp@alignleft\relax
- //\warning{Invalid value for keye};
+ //
+ \let\mp@alignright\hfil\let\mp@alignleft\hfil
+ \@@warning{Invalid value for 'align'; 'center' assumed}
+ ;
+ ord/keyf/.na/\def\y##1{#1*##1}; |com(No default.)
+ bool+/keyg/true; |com(Will raise error when user input is invalid.)
}
-
\finish{example}
The braces around \quoted{green}, the value of \fx{keya}, will be preserved throughout parsing. It should be remembered that keys are automatically set as soon as they are defined by \fx{\krddefinekeys}. The boolean \fx{\ifkrdindef} is true when \fx{\krddefinekeys} is defining keys, and false otherwise. The essence of it is that since keys are set as soon as they are defined by \fx{\krddefinekeys}, some actions should not be executed at this time, until the keys are being set by the user.
@@ -315,8 +317,7 @@ The output of the following example is shown in \sref{fig:1}:
\begin{figure}[h!]
\caption{Output of \sref{example:1}\label{fig:1}}
\centerline{%
- \includegraphics[viewport=141 642 416 674,clip,scale=1]
- {keyreader-example1}%
+ \includegraphics[viewport=141 642 416 674,clip,scale=1]{keyreader-example1}%
}
\end{figure}
@@ -326,6 +327,9 @@ The output of the following example is shown in \sref{fig:1}:
The following change history highlights significant changes that affect user utilities and interfaces; changes of technical nature are not documented in this section.
\begin{versionhist}
+ \begin{version}{0.5b}{2012/11/06}
+ \item Choice keys can't have outer-braced default or user-supplied values. Outer-braced values may not have been given in the state pattern. Hence the outer braces are removed automatically internally before matching the value against the singleton. Also, key values are no longer converted into lowercase before matching against the state pattern.
+ \end{version}
\begin{version}{0.5}{2012/10/10}
\item The \pkg'{keyreader} can now be loaded before \fx{\documentclass}.
\end{version}