summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-09-05 22:54:26 +0000
committerKarl Berry <karl@freefriends.org>2009-09-05 22:54:26 +0000
commit874ece84a0d160db419570dff359a6e4c3c44063 (patch)
tree4ee6c8290f49de79ad922ba8f839da431c78aaad /Master/texmf-dist/source/latex/oberdiek/kvoptions.dtx
parent427bf11201b13e9a0778a390b930f70f8b697b8e (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.dtx189
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