% \iffalse meta-comment
% An Infrastructure for marking up Metadata in LaTeX documents
% $URL: https://svn.kwarc.info/repos/stex/trunk/sty/metakeys/metakeys.dtx $ 
% $Rev: 1999 $; last modified by $Author: kohlhase $ 
% $Date: 2012-01-28 08:32:11 +0100 (Sat, 28 Jan 2012) $
% Copyright (c) 2009 Michael Kohlhase, all rights reserved
%               this file is released under the
%               LaTeX Project Public License (LPPL)
% \fi
% 
% \iffalse
%<*package>
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{metakeys}[2012/01/28 v0.9 Framework for Metadata Keys]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage{stex-logo,url,array,float}
\usepackage[show]{ed}
\usepackage{../ctansvn}
\usepackage[eso-foot,today]{svninfo}
\usepackage[hyperref=auto,style=alphabetic]{biblatex}
\bibliography{kwarc}
\svnInfo $Id: metakeys.dtx 1999 2012-01-28 07:32:11Z kohlhase $
\svnKeyword $HeadURL: https://svn.kwarc.info/repos/stex/trunk/sty/metakeys/metakeys.dtx $
\usepackage{hyperref}
%\makeindex
\floatstyle{boxed}
\newfloat{exfig}{thp}{lop}
\floatname{exfig}{Example}
\def\tracissue#1{\cite{sTeX:online}, \hyperlink{http://trac.kwarc.info/sTeX/ticket/#1}{issue #1}}
\usepackage[showmeta]{metakeys}
\begin{document}\DocInput{metakeys.dtx}\end{document}
%</driver>
% \fi
%
%\CheckSum{176}
%
% \changes{v0.1}{2009/12/14}{First version}
% \changes{v0.8}{2010/06/18}{This is almost done}
% \changes{v0.9}{2010/09/02}{make sure that showkeys is always initialized}
% 
% \GetFileInfo{metakeys.sty}
% 
% \MakeShortVerb{\|}
% \def\scsys#1{{{\sc #1}}\index{#1@{\sc #1}}}
% \def\latexml{\scsys{LaTeXML}}
% \def\omdoc{OMDoc}
% \def\omdocv#1{\omdoc{#1}}
%
% \title{{\texttt{metakeys.sty}}: A generic framework for extensible Metadata in {\LaTeX}\thanks{Version {\fileversion} (last revised
%        {\filedate})}}
%    \author{Michael Kohlhase\\
%            Jacobs University, Bremen\\
%            \url{http://kwarc.info/kohlhase}}
% \maketitle
% \begin{abstract}
%   The |metakeys| package is part of the {\sTeX} collection, a version of {\TeX/\LaTeX} that
%   allows to markup {\TeX/\LaTeX} documents semantically without leaving the document
%   format, essentially turning {\TeX/\LaTeX} into a document format for mathematical
%   knowledge management (MKM).
%
%   This package supplies the infrastructure for extending {\sTeX} macros with {\omdoc}
%   metadata. This package is mainly intended for authors of {\sTeX} extension packages.
% \end{abstract}
%
% \setcounter{tocdepth}{2}\tableofcontents\newpage
%
% \section{The User Interface}\label{sec:user}
%
% Many of the {\stex} macros and environments take an optional first argument which uses
% key/value pairs to specify metadata relations of the marked up objects. The |metakeys|
% package supplies the infrastructure managing these key/value pairs. It also forms the
% basis for the |rdfmeta| package which allows to use these for flexible, user-extensible
% metadata relations (see~\ctancite{Kohlhase:rdfmeta} for details).
%
% \subsection{Package Options}\label{sec:user:options}
% 
% The |metakeys| package takes a single option: \DescribeMacro{showmeta}|showmeta|. If
% this is set, then the metadata keys defined by the |\addmetakey| are shown
% (see~\ref{sec:user:showmeta})
% 
% \subsection{Adding Metadata Keys to Commands}\label{sec:user:keys}
%
% Key/value pairs in \stex are organized in \textbf{key groups}: every {\stex} macro and
% environment that takes a key/value argument has an associtated key group, and only keys
% that are registered in this group can be utilized. The |metakeys| package supplies the
% \DescribeMacro{\addmetakey}|\addmetakey| macro to add a new key to a key group: If
% \meta{group} is the name of a key group \meta{key} is a metadata keyword name, then
% \begin{quote}
% |\addmetakey[|\meta{default}|]{|\meta{group}|}{|\meta{key}|}[|\meta{dval}|]|
% \end{quote}
% registers \meta{key} in the metadata group \meta{group}, with an optional values
% \meta{default} and \meta{dval} for \meta{key}. The \meta{default} is the default value
% for \meta{key}, if it is not specified, and \meta{dval} the value it gets, if \meta{key}
% is given without specifying a value. These two defaults are often used as
% \begin{quote}
% |\addmetakey[false]{|\meta{group}|}{|\meta{key}|}[true]|
% \end{quote}
% Then, the value of \meta{key} is |false| if \meta{key} is not given and |true|, if
% \meta{key} is specified without value. This is often the best way if we want to use
% \meta{key} as an indicator to have a feature of name \meta{key} (we can test that with
% |\ifx\|\meta{group}|@|\meta{key}|\@true|, if we prepared the macro |\def\@true{true}|
% earlier).
% 
% The keys registered for a metadata group can be used for defining macros with a
% key/value arguments via the \DescribeMacro{\metasetkeys}|\metasetkeys| macro, see for
% instance the the definition in Figure~\ref{fig:foo}.
%
% The \DescribeMacro{\addmetalistkey}|\addmetalistkey| macro is a variant of |\addmetakey|
% that adds a list-valued metadata key. The |\addmetalistkey{foo}{val}| in
% Figure~\ref{fig:foo} would allows to use multiple occurrences of teh |val| keys in the
% metadata argument of |\foo|, the values of the |val| keys are collected as a
% comma-separated list in the token register |\foo@vals|. Note that the |val| key can also
% deal with comma-separated lists for convenience.
%
% With these definitions in a used package\footnote{\makeatletter Recall that the
% \texttt{@} character is only allowed in packages, where comma-separated lists can be
% iterated over e.g. by the \texttt{\textbackslash{@}for} macro.}  an invocation of
% \begin{quote}
% |\foo[type=bar,id=f4711,val=4,val=7,val={1,1}]|
% \end{quote}
% is formatted to
% \begin{quote}
% \addmetakey{foo}{id}\addmetakey{foo}{type}\addmetalistkey{foo}{val}\makeatletter
% \newcommand\foo[1][]{\metasetkeys{foo}{#1} I have seen a \emph{foo} of type \texttt{\foo@type}
% with identifier \texttt{\foo@id} and values
% \let\@join=\relax\def\@thejoin{, and }
% \@for\@I:=\foo@vals\do{\@join\@I\let\@join=\@thejoin}!}\makeatother 
% \foo[type=bar,id=f4711,val=4,val=7,val=1,val=1]
% \end{quote}
% 
% \begin{exfig}[ht]
% \begin{verbatim}
% \addmetakey{foo}{id}
% \addmetakey{foo}{type}
% \addmetakey[yes]{foo}{visible}
% \addmetalistkey{foo}{val}
% \def\@yes{yes}
% \newcommand\foo[1][]{\metasetkeys{foo}{#1}
% \ifx\foo@visible\@yes % testing for visibility
% I have seen a \emph{foo} of type \texttt{\foo@type} with identifier 
% \texttt\foo@id and values \texttt\foo@vals.
% \let\@join=\relax\def\@thejoin{, and }
% \@for\@I:=\foo@vals\do{\@join\@I\let\@join=\@thejoin}!
% \fi}
% \end{verbatim}
% \vspace*{-2em}
% \caption{Defining a macro with metadata}
% \label{fig:foo}
% \end{exfig}
%
% \subsection{Showing Metadata Keys/Values}\label{sec:user:showmeta}
%
% If the |showmeta| package option is set, the |metakeys| package sets an internal switch that
% shows the values of all keys specified with the |\addmetakey| macro. The default behavior
% is to write the key/value pairs into the margin as \meta{key}|:|\meta{value}. Package
% designers can customize this behavior by redefining the |\metakeys@show@key| and
% |\metakeys@show@keys| macro.
%
% \DescribeMacro{\metakeys@show@key}|\metakeys@show@key{|\meta{key}|}{|\meta{value}|}| shows the a
% single key value pair, and
% \DescribeMacro{\metakeys@show@keys}|\metakeys@show@keys{|\meta{group}|}{|\meta{keys}|}| shows the
% a list of keys metadata, by default we disregard the \meta{group} and show \meta{keys}
% in a marginpar.
% 
% For keys that should not be shown in this manner, the |\addmetakey| macro has a variant
% \DescribeMacro{\addmetakey*}|\addmetakey*|. Its behavior is exactly the same, only that
% it keeps the key from being shown by the |showmeta| option.
%
% Note that setting the |showmeta| option will enable metadata presentation on the whole
% document. But sometimes we want to disable that, e.g. inside figures, where |\marginpar|
% is not allowed. Therefore the |metakeys| package provides the
% \DescribeMacro{\hidemetakeys}|\hidemetakeys| macro that reverses this. The
% \DescribeMacro{\showmetakeys}|\showmetakeys| macro re-enables metadata presentation.
%
%
% \section{Limitations}\label{sec:limitations}
% 
% In this section we document known limitations. If you want to help alleviate them,
% please feel free to contact the package author. Some of them are currently discussed in
% the \sTeX TRAC~\cite{sTeX:online}. 
% \begin{compactenum}
% \item none reported yet
% \end{compactenum}
% 
% \StopEventually{\newpage\PrintChanges\printbibliography}
% 
% \section{The Implementation}\label{sec:impl}
% 
% The |metakeys| package generates two files: the {\LaTeX} package (all the code between
% {\textsf{$\langle$*package$\rangle$}} and {\textsf{$\langle$/package$\rangle$}}) and the
% {\latexml} bindings (between {\textsf{$\langle$*ltxml$\rangle$ and
% $\langle$/ltxml$\rangle$}}). We keep the corresponding code fragments together, since
% the documentation applies to both of them and to prevent them from getting out of sync.
%
% \subsection{Package Options}\label{sec:impl:options}
%
% We declare some switches which will modify the behavior according to the package
% options. Generally, an option |xxx| will just set the appropriate switches to true
% (otherwise they stay false). First we have the general options
%    \begin{macrocode}
%<*package>
\newif\ifmetakeys@showmeta\metakeys@showmetafalse
\DeclareOption{showmeta}{\metakeys@showmetatrue}
%    \end{macrocode}
%    Finally, we need to declare the end of the option declaration section to {\LaTeX}.
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
% 
% We build on the |keyval| package which we first need to load.
%    \begin{macrocode}
\RequirePackage{keyval}[1997/11/10]
%</package>
%    \end{macrocode}
%
% \subsection{Adding Metadata Keys}\label{sec:impl:keys}
%
% \begin{macro}{\addmetakey}
%   The |\addmetakey| macro looks at the next character and invokes helper macros accordingly.
%    \begin{macrocode}
%<*package>
\newcommand\addmetakey{\@ifstar\addmetakey@star\addmetakey@nostar}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addmetakey@star}
%   |\addmetakey@star| takes care of the starred form of |\addmetakey|. An invocation of
%   |\addmetakey@star{|\meta{default}|}{|\meta{group}|}{|\meta{key}|}| macro first extends the
%   |\metakeys@clear@|\meta{group}|@keys| macro then defines the key \meta{key} with the
%   |\define@key| macro from the |keyval| package. This stores the key value given in the
%   local macro |\|\meta{group}|@|\meta{key}.
%    \begin{macrocode}
%<*package>
\newcommand\addmetakey@star[3][]%
{\@ifnextchar[{\addmetakey@star@aux[#1]{#2}{#3}}{\addmetakey@star@aux[#1]{#2}{#3}[]}}
\def\addmetakey@star@aux[#1]#2#3[#4]{\metakeys@ext@clear@keys{#2}{#3}{#1}%
\metakeys@initialize@showkeys{#2}%
\define@key{#2}{#3}[#4]{\expandafter\gdef\csname #2@#3\endcsname{##1}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addmetakey@nostar}
%   |\addmetakey@nostar| takes care of the starred form of |\addmetakey| by first extending the
%   |\metakeys@|\meta{group}|@showkeys| macro which contains those keys that should be
%   shown and then calling |\addmetakey@star|.
%    \begin{macrocode}
\newcommand\addmetakey@nostar[3][]%
{\metakeys@ext@showkeys{#2}{#3}\addmetakey@star[#1]{#2}{#3}}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metasetkeys}
% The |\metasetkeys{|\meta{group}|}| clears/presets the key of \meta{group} via
% |\clear@|\meta{group}|@clearkeys|, (if the |showmeta| option is set) shows them, and
% then sets the keys via |keyval|s |\setkeys| command.
%    \begin{macrocode}
%<*package>
\newcommand\metasetkeys[2]{\@nameuse{clear@#1@keys}\setkeys{#1}{#2}%
\ifmetakeys@showmeta%
\edef\@@keys{\@nameuse{#1@showkeys}}%
\metakeys@show@keys{#1}{\@for\@I:=\@@keys\do{\metakeys@show@keyval{#1}{\@I}}}%
\fi}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeys@ext@clear@keys}
%   |\metakeys@ext@clear@keys{|\meta{group}|}{|\meta{key}|}{|\meta{default}|}| extends (or
%   sets up if this is the first |\addmetakey| for \meta{group}) the
%   |\clear@|\meta{group}|@keys| macro to set the default value \meta{default} for
%   \meta{key}. The |\clear@|\meta{group}|@keys| macro is used in the generic
%   |\metasetkeys| macro below. The variant |\@metakeys@ext@clear@keys| is provided for
%   use in the |sref| package.
%    \begin{macrocode}
%<*package>
\newcommand\metakeys@ext@clear@keys[3]{\@metakeys@ext@clear@keys{#1}{#1@#2}{#3}}
\newcommand\@metakeys@ext@clear@keys[3]{\@ifundefined{clear@#1@keys}%
{\expandafter\gdef\csname clear@#1@keys\endcsname%
{\expandafter\gdef\csname #2\endcsname{#3}}}%
{\expandafter\g@addto@macro\csname clear@#1@keys\endcsname%
{\expandafter\gdef\csname #2\endcsname{#3}}}}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addmetalistkey}
%    \begin{macrocode}
%<*package>
\newcommand\addmetalistkey{\@ifstar\addmetalistkey@star\addmetalistkey@nostar}
\newcommand\addmetalistkey@star[3][]{\metakeys@ext@clear@keys{#2}{#3}{#1}%
\metakeys@initialize@showkeys{#2}%
\expandafter\gdef\csname #2@#3s\endcsname{}
\define@key{#2}{#3}[#1]{%
\expandafter\ifx\csname #2@#3s\endcsname\@empty\expandafter\gdef\csname #2@#3s\endcsname{##1}%
\else\expandafter\xdef\csname #2@#3s\endcsname{\csname #2@#3s\endcsname,##1}%
\fi}}
\newcommand\addmetalistkey@nostar[3][]%
{\metakeys@ext@showkeys{#2}{#3}\addmetalistkey@star[#1]{#2}{#3}}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \subsection{Showing Metadata Keys/Values}\label{sec:impl:showmeta}
%
% \begin{macro}{\metakeys@initialize@showkeys}
%   |\metakeys@initialize@showkeys{|\meta{group}|}| sets up the |\|\meta{group}|@showkeys|
%   macro which is is used to store the keys to be shown of the metadata in in the generic
%   |\setmetakeys| macro below.
%    \begin{macrocode}
%<*package>
\newcommand\metakeys@initialize@showkeys[1]%
{\@ifundefined{#1@showkeys}{\expandafter\def\csname #1@showkeys\endcsname{}}{}}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeys@ext@showkeys}
%   |\metakeys@ext@showkeys{|\meta{group}|}{|\meta{key}|}| extends (or sets up) the
%   |\|\meta{group}|@showkeys| macro which is is used to store the keys to be shown of the
%   metadata in in the generic |\setmetakeys| macro below.
%    \begin{macrocode}
\newcommand\metakeys@ext@showkeys[2]{\@ifundefined{#1@showkeys}%
{\expandafter\def\csname #1@showkeys\endcsname{#2}}%
{\expandafter\edef\csname #1@showkeys\endcsname{\csname #1@showkeys\endcsname,#2}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeys@show@key}
%   |\metakeys@show@key{|\meta{key}|}{|\meta{value}|}| shows the a single key value pair, as a
%   default we just write \meta{key}|:|\meta{value}.
%    \begin{macrocode}
\newcommand\@metakeys@show@key[2]{\metakeys@show@key{#2}{#1}}
\newcommand\metakeys@show@key[2]{\edef\@test{#2}\ifx\@test\@empty\else #1:#2\quad\fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeys@show@keys}
%   |\metakeys@show@keys{|\meta{group}|}{|\meta{keys}|}| shows the metadata, by default we
%   disregard the \meta{group} and show \meta{keys} in a marginpar. 
%    \begin{macrocode}
\newcommand\metakeys@show@keys[2]{\marginpar{{\scriptsize #2}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeys@show@keyval}
%   |\metakeys@show@keyval{|\meta{group}|}|{|\meta{key}|} shows the key/value pair of a given key \meta{key}.
%    \begin{macrocode}
\newcommand\metakeys@show@keyval[2]%
{\expandafter\@metakeys@show@key\csname #1@#2\endcsname{#2}}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\showmetakeys}
%    \begin{macrocode}
%<*package>
\newcommand\showmetakeys{\metakeys@showmetatrue}
%</package>
%<*ltxml> 
DefConstructor('\showmetakeys','');
%</ltxml>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\hidemetakeys}
%    \begin{macrocode}
%<*package>
\newcommand\hidemetakeys{\metakeys@showmetafalse}
%</package>
%<*ltxml> 
DefConstructor('\hidemetakeys','');
%</ltxml>
%    \end{macrocode}
% \end{macro}
%
% \subsection{Using better defaults than empty}
% 
% \begin{macro}{\addmetakeynew}
%   |\addmetakeynew| is an experimental version of |\addmetakey| which gives
%   |\omd@unspecified| as an optional argument, so that it is used as the default value
%   here and then test for it in |\omfidus|. But unfortunately, this does not work yet.
%    \begin{macrocode}
%<*package>
\newcommand\addmetakeynew[3][]{\metakeys@ext@clear@keys{#2}{#3}{#1}%
\define@key{#2}{#3}{\expandafter\gdef\csname #2@#3\endcsname{##1}}}
%    \end{macrocode}
% \end{macro}
%
% 
% \begin{macro}{\metakeys@unspecified}
%   Ain internal macro for unspecified values. It is used to initialize keys.\ednote{MK:
%   we could probably embed an package error or warning in here}
%    \begin{macrocode}
\newcommand\metakeys@unspecified{an metakeys-defined key left unspecified}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\metakeysifus}
%   This just tests for equality of the first arg with |\metakeys@unspecified|
%    \begin{macrocode}
\newcommand\metakeysifus[4]{\message{testing #1@#2=\csname#1@#2\endcsname}%
\expandafter\ifx\csname #1@#2\endcsname\metakeys@unspecified{#3}\else{#4}\fi}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \subsection{Finale}
%
% Finally, we need to terminate the file with a success mark for perl.
%    \begin{macrocode}
%<ltxml>1;
%    \end{macrocode}
% \Finale
\endinput
% \iffalse
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: 
% \fi


% LocalWords:  iffalse kohlhase Thu metakeys metakeys.dtx scsys sc sc latexml omdoc foo
% LocalWords:  omdocv texttt fileversion maketitle setcounter tocdepth newpage
% LocalWords:  tableofcontents ednote showmeta
% LocalWords:  makeatletter newcommand emph makeatother exfig vspace impl ltxml
% LocalWords:  printbibliography keyval clearkeys expandafter gdef csname ifx
% LocalWords:  endcsname setkeys ifundefined omfidus metakeysifus addmetakey
% LocalWords:  doctex metasetkeys metasetkeys marginpar hidemetakeys textsf omd
% LocalWords:  hidemetakeys showmetakeys showmetakeys langle textsf langle
% LocalWords:  newif ifmetakeys showmetafalse showmetatrue ifstar showkeys
% LocalWords:  nameuse setmetakeys addmetakeynew