diff options
author | Karl Berry <karl@freefriends.org> | 2009-09-05 22:54:26 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-09-05 22:54:26 +0000 |
commit | 874ece84a0d160db419570dff359a6e4c3c44063 (patch) | |
tree | 4ee6c8290f49de79ad922ba8f839da431c78aaad /Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx | |
parent | 427bf11201b13e9a0778a390b930f70f8b697b8e (diff) |
oberdiek update (5sep09)
git-svn-id: svn://tug.org/texlive/trunk@15145 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx | 189 |
1 files changed, 140 insertions, 49 deletions
diff --git a/Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx b/Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx index b4d0fd44084..c108ce24ecd 100644 --- a/Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx +++ b/Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx @@ -73,7 +73,7 @@ \input docstrip.tex \Msg{************************************************************************} \Msg{* Installation} -\Msg{* Package: kvoptions 2009/07/17 v3.2 Keyval support for LaTeX options (HO)} +\Msg{* Package: kvoptions 2009/08/13 v3.4 Keyval support for LaTeX options (HO)} \Msg{************************************************************************} \keepsilent @@ -148,7 +148,7 @@ and the derived files %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{kvoptions.drv}% - [2009/07/17 v3.2 Keyval support for LaTeX options (HO)]% + [2009/08/13 v3.4 Keyval support for LaTeX options (HO)]% \documentclass{ltxdoc} \usepackage{holtxdoc}[2008/08/11] \begin{document} @@ -157,7 +157,7 @@ and the derived files %</driver> % \fi % -% \CheckSum{2103} +% \CheckSum{2121} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z @@ -178,7 +178,7 @@ and the derived files % \GetFileInfo{kvoptions.drv} % % \title{The \xpackage{kvoptions} package} -% \date{2009/07/17 v3.2} +% \date{2009/08/13 v3.4} % \author{Heiko Oberdiek\\\xemail{oberdiek@uni-freiburg.de}} % % \maketitle @@ -195,9 +195,13 @@ and the derived files % % \section{Introduction} % +% First I want to recommend the very good review article +% ``A guide to key-value methods'' by Joseph Wright \cite{tb94wright}. +% It introduces the different key-value packages and compares them. +% % \subsection{The beginning} % -% This package addresses class or package writers +% This package \xpackage{kvoptions} addresses class or package writers % that want to allow their users to specify options % as key value pairs, e.g.: % \begin{quote} @@ -507,6 +511,16 @@ and the derived files % call \cs{OptionNotUsed}. Or the options can be passed to % another class that is later loaded. % +% \subsubsection{Local options} +% +% \begin{declcs}{DeclareLocalOption} \M{option}\\ +% \cs{DeclareLocalOptions} \M{option list} +% \end{declcs} +% Both macros mark package options as local options. That means +% that they are ignored by \cs{ProcessKeyvalOptions} if they are given +% as global options. \cs{DeclareLocalOptions} takes one option, +% \cs{DeclareLocalOptions} expects a comma separated list of options. +% % \subsubsection{Dynamic options} % % Options of \LaTeX's package/class system are cleared @@ -607,6 +621,42 @@ and the derived files %\end{verbatim} %\end{quote} % +% \subsection{Global vs. local options} +% +% Options that are given for \cs{documentclass} are called +% global options. They are known to the class and all packages. +% A package may make use of a global option and marks it as +% used. The advantage for the user is the freedom to specify +% options both in the \cs{documentclass} or \cs{usepackage} +% commands. +% +% However global options are shared with the class options +% and options of all other packages. Thus there can be the +% same option with different semantics for different +% packages and classes. As example, package \xpackage{bookmark} +% knows option \xoption{open} that specifies whether the bookmarks +% are opened or closed initially. It's values are |true| or |false|. +% Since KOMA-Script version 3.00 the KOMA classes also introduces +% option \xoption{open} with values |right| and |any| and a +% complete different meaning. +% +% Such conflicts can be resolved by marking all or part of options +% as local by \cs{DeclareLocalOption} or \cs{DeclareLocalOptions}. +% Then the packages ignores global occurences of these options. +% Package \xpackage{kvoptions} provides two methods: +% \begin{itemize} +% \item \cs{ProcessLocalKeyvalOptions} automatically uses all options +% as local options. It ignores all global options. +% \item \cs{DeclareLocalOption} or \cs{DeclareLocalOptions} marks +% options as local options. \cs{ProcessKeyvalOptions} will then +% ignore global occurences for these local options. +% \end{itemize} +% Since version 1.5 package \xpackage{bookmark} uses the latter +% method. It checks global and local option places for driver options +% and limits all other options as local options. Thus the class +% option \xoption{open} of KOMA-Script is not misread as +% option for package \xpackage{bookmark}. +% % \subsection{Summary of internal macros} % % The \cs{Declare}\texttt{\dots Option} commands define @@ -665,7 +715,7 @@ and the derived files % Package identification % ----------------------- \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{example-mycolorsetup}[2009/07/17 Managing my colors] +\ProvidesPackage{example-mycolorsetup}[2009/08/13 Managing my colors] \RequirePackage{ifpdf} \RequirePackage{kvoptions} @@ -981,29 +1031,26 @@ and the derived files \catcode46 12 % . \catcode58 12 % : \catcode64 11 % @ + \catcode123 1 % { + \catcode125 2 % } \expandafter\let\expandafter\x\csname ver@kvoptions.sty\endcsname - \ifcase 0% - \ifx\x\relax % plain + \ifx\x\relax % plain-TeX, first loading + \else + \def\empty{}% + \ifx\x\empty % LaTeX, first loading, + % variable is initialized, but \ProvidesPackage not yet seen \else - \ifx\x\empty % LaTeX + \catcode35 6 % # + \expandafter\ifx\csname PackageInfo\endcsname\relax + \def\x#1#2{% + \immediate\write-1{Package #1 Info: #2.}% + }% \else - 1% + \def\x#1#2{\PackageInfo{#1}{#2, stopped}}% \fi + \x{kvoptions}{The package is already loaded}% + \aftergroup\endinput \fi - \else - \catcode35 6 % # - \catcode123 1 % { - \catcode125 2 % } - \expandafter\ifx\csname PackageInfo\endcsname\relax - \def\x#1#2{% - \immediate\write-1{Package #1 Info: #2.}% - }% - \else - \def\x#1#2{\PackageInfo{#1}{#2, stopped}}% - \fi - \x{kvoptions}{The package is already loaded}% - \endgroup - \expandafter\endinput \fi \endgroup % \end{macrocode} @@ -1019,6 +1066,8 @@ and the derived files \catcode47 12 % / \catcode58 12 % : \catcode64 11 % @ + \catcode91 12 % [ + \catcode93 12 % ] \catcode123 1 % { \catcode125 2 % } \expandafter\ifx\csname ProvidesPackage\endcsname\relax @@ -1039,7 +1088,7 @@ and the derived files \fi \expandafter\x\csname ver@kvoptions.sty\endcsname \ProvidesPackage{kvoptions}% - [2009/07/17 v3.2 Keyval support for LaTeX options (HO)] + [2009/08/13 v3.4 Keyval support for LaTeX options (HO)] % \end{macrocode} % % \paragraph{Catcodes} @@ -1098,6 +1147,13 @@ and the derived files }{} % \end{macrocode} % +% Macro \cs{DeclareLocalOptions} parses a comma separated key list +% and uses \cs{comma@parse} of package \xpackage{kvsetkeys}, +% version 1.3. +% \begin{macrocode} +\RequirePackage{kvsetkeys}[2007/09/29] +% \end{macrocode} +% % \paragraph{Provide macros for \plainTeX.} % \begin{macrocode} \@ifundefined{@onelevel@sanitize}{% @@ -1133,7 +1189,7 @@ and the derived files % \begin{macrocode} \DeclareOption{patch}{% \AtEndOfPackage{% - \RequirePackage{kvoptions-patch}[2009/07/17]% + \RequirePackage{kvoptions-patch}[2009/08/13]% }% } % \end{macrocode} @@ -1508,6 +1564,23 @@ and the derived files % \end{macrocode} % \end{macro} % +% \subsubsection{\cs{DeclareLocalOptions}} +% +% \begin{macro}{\DeclareLocalOptions} +% \begin{macrocode} +\newcommand*{\DeclareLocalOptions}[1]{% + \comma@parse{#1}\KVO@DeclareLocalOption +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\KVO@DeclareLocalOption} +% \begin{macrocode} +\def\KVO@DeclareLocalOption#1{% + \expandafter\def\csname KVO@local@\KVO@family @#1\endcsname{}% +} +% \end{macrocode} +% \end{macro} +% % \subsection{Dynamic options} % % \subsubsection{\cs{DisableKeyvalOption}} @@ -1648,7 +1721,7 @@ and the derived files % % \subsection{Process options} % -% \subsection{\cs{ProcessKeyvalOptions}} +% \subsubsection{\cs{ProcessKeyvalOptions}} % % \begin{macro}{\ProcessKeyvalOptions} % If the optional star is given, we get the family @@ -1684,28 +1757,31 @@ and the derived files \@ifundefined{KV@#1@\expandafter\KVO@getkey \KVO@CurrentOption=\@nil}{% }{% - \ifx\KVO@Patch Y% - \edef\KVO@temp{% - \etex@unexpanded\expandafter{% - \KVO@temp + \@ifundefined{KVO@local@#1@\expandafter\KVO@getkey + \KVO@CurrentOption=\@nil}{% + \ifx\KVO@Patch Y% + \edef\KVO@temp{% + \etex@unexpanded\expandafter{% + \KVO@temp + }% + ,% + \etex@unexpanded\expandafter{% + \KVO@CurrentOption + }% + ,% }% - ,% - \etex@unexpanded\expandafter{% + \@onelevel@sanitize\KVO@CurrentOption + \else + \edef\KVO@temp{% + \KVO@temp + ,% \KVO@CurrentOption + ,% }% - ,% - }% - \@onelevel@sanitize\KVO@CurrentOption - \else - \edef\KVO@temp{% - \KVO@temp - ,% - \KVO@CurrentOption - ,% - }% - \fi - \@expandtwoargs\@removeelement\KVO@CurrentOption - \@unusedoptionlist\@unusedoptionlist + \fi + \@expandtwoargs\@removeelement\KVO@CurrentOption + \@unusedoptionlist\@unusedoptionlist + }{}% }% }% \fi @@ -1796,7 +1872,7 @@ and the derived files } % \end{macrocode} % -% \subsection{\cs{ProcessLocalKeyvalOptions}} +% \subsubsection{\cs{ProcessLocalKeyvalOptions}} % % \begin{macro}{\ProcessLocalKeyvalOptions} % If the optional star is given, we get the family @@ -2002,7 +2078,7 @@ and the derived files \noexpand\endinput } \ProvidesPackage{kvoptions-patch}% - [2009/07/17 v3.2 LaTeX patch for keyval options (HO)]% + [2009/08/13 v3.4 LaTeX patch for keyval options (HO)]% % \end{macrocode} % % Check for \eTeX. @@ -2835,10 +2911,14 @@ and the derived files % \newcommand*{\bibpackage}[4]{^^A % \bibitem{#1} % Package \xpackage{#1}, #2, #3.^^A -% \ifx\\#4\\\else#4\fi\par +% \ifx\\#4\\\else\space#4\fi\par % } % % \begin{thebibliography}{99} +% \bibitem{tb94wright} +% A guide to key-value methods, Joseph Wright, second draft for +% \href{http://www.tug.org/tugboat}{TUGBoat}, 2009-03-17. +% \url{http://www.texdev.net/wp-content/uploads/2009/03/keyval.pdf} % \bibpackage{ifthen}{David Carlisle}{2001/05/26} % {\CTAN{macros/latex/base/ifthen.dtx}} % \bibpackage{helvet}{Sebastian Rahtz, Walter Schmidt}{2004/01/26} @@ -2953,6 +3033,17 @@ and the derived files % \cs{DisableKeyvalOption} with the \texttt{action=ignore} option % fixed (Joseph Wright). % \end{Version} +% \begin{Version}{2009/07/21 v3.3} +% \item +% \cs{DeclareLocalOption}, \cs{DeclareLocalOptions} added. +% \end{Version} +% \begin{Version}{2009/08/13 v3.4} +% \item +% Documentation addition: recommendation for Joseph Wright's +% review article. +% \item +% Documentation addition: local/global options. +% \end{Version} % \end{History} % % \PrintIndex |