% \iffalse meta-comment
% An Infrastructure for extending macros by general metadata keys
% $URL: https://svn.kwarc.info/repos/stex/trunk/sty/rdfmeta/rdfmeta.dtx $ 
% $Rev: 1671 $; last modified by $Author: kohlhase $ 
% $Date: 2010-11-06 08:05:15 +0100 (Sat, 06 Nov 2010) $
% Copyright (c) 2007 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{rdfmeta}[2010/09/01 v0.2 Metadata key upgrades]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[sectioning]{rdfmeta}
\usepackage{url,array,float,stex-logo}
\usepackage[show]{ed}
\usepackage{listings}
\lstset{basicstyle=\scriptsize\tt,columns=flexible}
\lstset{frame=none,numbers=none,lineskip=-.7ex,aboveskip=-.5ex,belowskip=-.5ex}
\usepackage[hyperref=auto,style=alphabetic]{biblatex}
\bibliography{kwarc}
\usepackage{../ctansvn}
\usepackage{hyperref}
\usepackage[eso-foot,today]{svninfo}
\svnInfo $Id: rdfmeta.dtx 1671 2010-11-06 07:05:15Z kohlhase $
\svnKeyword $HeadURL: https://svn.kwarc.info/repos/stex/trunk/sty/rdfmeta/rdfmeta.dtx $
\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}}
\begin{document}\DocInput{rdfmeta.dtx}\end{document}
%</driver>
% \fi
%
%\iffalse\CheckSum{1}\fi
%
% \changes{v0.1}{2010/03/05}{new}
% \changes{v0.2}{2010/09/01}{starred forms work now, more documentation}
% 
% \GetFileInfo{rdfmeta.sty}
% 
% \MakeShortVerb{\|}
% \def\latexml{{\LaTeX}ML}
%
% \title{RDFa Metadata in {\LaTeX}\thanks{Version {\fileversion} (last revised
%        {\filedate})}}
% \author{Michael Kohlhase \\
%         Jacobs University, Bremen\\
%         \url{http://kwarc.info/kohlhase}}
% \maketitle
% \begin{abstract}
%   The |rdfmeta| package allows mark up Ontology-based Metadata in {\LaTeX} documents
%   that can be harvested by automated tools or exported to PDF.
% \end{abstract}
%
% \setcounter{tocdepth}{2}\tableofcontents
%\begin{center}\bf\Huge
%  Experimental!\\
%  do not use!
%\end{center}\newpage
%
% \section[id=intro]{Introduction}
%
% The |rdfmeta| package allows mark up extensible metadata in \stex documents, so that
% that it can be harvested by automated tools or exported to PDF;
% see~\cite{KohKohLan:ssffld10:biblatex} for an application. The main idea is that
% metadata are annotated as key value pairs in the semantic environments provided by
% \stex. In most markup formats, the metadata vocabularies are fixed by the language
% designer. In \stex, the |rdfmeta| package allows the user to extend the metadata
% vocabulary.
% 
% \begin{exfig}[ht]
% \begin{verbatim}
% \importmodule[../ontologies/cert]{certification}
% ... 
% \section[id=userreq,hasState=$\statedocrd{\tuev}$]{User Requirements}
% ...
% \end{verbatim}
% \vspace*{-1.5em}\hrule
% \lstinputlisting[language=XMl,morekeywords={imports,metadata,resource,link,omgroup},aboveskip=.5ex]{hasstate.omdoc}
% \caption{Metadata for Certification}\label{fig:hasState}
% \end{exfig}
% 
% Take, for instance, the case where we want to use metadata for the certification status
% of document fragments. In Figure~\ref{fig:hasState} we use the |hasState| key to say
% that a section has been approved by the T\"UV, a specific certification agency. There
% are two concerns here. First, the |hasState| key has to be introduced and given a
% meaning, and same for the (complex) value |\statedocrd{\tuev}|. This meaning is given in
% the |certifiation| ontology which we imported via the |\importmodule| command. The
% ontology can be marked up in \stex (see Figure~\ref{fig:certification}), with the
% exception that we use the |\keydef| macro for the definition of the |hasState| relation
% so that it also defines the key. For the details of this see the next section.
%
% \section[id=user]{User Interface}
%
% We now document the specifics of the environments and macros provided by the |rdfmeta|
% package from a user perspective. 
%
% \subsection[id=sec:user:options]{Package Options}
% 
% The |rdfmeta| package takes the option: \DescribeMacro{showmeta}|showmeta|. If this is
% set, then the metadata keys are shown (see~\cite{Kohlhase:metakeys:ctan} for details and
% customization options).
% 
% The remaining options can be used to specify metadata upgrades of standard keys. The
% \DescribeMacro{sectioning}|sectioning| option upgrades the |\part|, |\chapter|,
% |\section|, |\subsection|, |\subsubsection|, |\paragraph| macros (and of course their
% starred variants). 
%
% \subsection[id=sec:user:keydef]{Extending Macros and Environments by Metadata Keys}
% 
% The main user-visible feature of the |rdfmeta| package is the
% \DescribeMacro{\keydef}|keydef| macro. It takes two arguments, a key set
% identifier\footnote{In a nutshell, every \stex command that takes metadata keys comes
% with a ``key set identifier'' that identifies the set of admissible keys;
% see~\cite{Kohlhase:metakeys:ctan} for details on this concept}\ednote{introduce this in
% the \texttt{metakeys} package also give an overview over the keysets in \stex} and a key
% name. Semantically, |\keydef{|\meta{keyset}|}{|\meta{key}|}| defines a symbol just like
% the |\symdef| macro from the |modules| package~\cite{KohAmb:smmssl:ctan}\ednote{as I
% have not been able to make the keyset a list of keysets, we have to have a non-defining
% version of this macro probably \texttt{\textbackslash keydef*}.}. But it also extends
% the syntax of \stex itself: it adds a key \meta{key} to \meta{keyset}, which allows to
% state the corresponding metadata as a key/value pair in the \stex macro or
% environment. Following the ideas from~\cite{LK:MathOntoAuthDoc09}, the metadata is
% transformed to RDFa metadata~\cite{w3c:WD-rdfa-core-20100803} in {\omdoc}, where the
% identifiers of relations are exactly the symbols introduced by the corresponding
% |\keydef|. 
% 
% \begin{exfig}[ht]
% \lstinputlisting[language=TeX,morekeywords={metalanguage}]{certification}
% \caption{A simple Ontology on Certification}\label{fig:certification}
% \end{exfig}
%
% In our example in Figure~\ref{fig:certification} we have defined a key |hasstate| in the
% |omtext| key set\footnote{For the \texttt{\textbackslash omtext} environment and key set
% see~\cite{Kohlhase:smmtf:ctan}} and a symbol |hasstate| via
% |\addkey{omtext}{hasstate}|. Furthermore, we have defined the meaning of the relation
% expressed by the |hasstate| symbol informally and specified some possible objects for
% the relation (that could of course have been done in other documents as well). We have
% made use\ednote{this does not quite work yet, since we do not know where the prefix
% \texttt{cert:} comes from. I guess we need to provide a variant of \texttt{importmodule}
% for certification that allows to specify the prefix. Of course this only affects the
% latexml transformation} of this metadata ontology and the new key |hasstate| in the
% example in Figure~\ref{fig:hasState}. 
%
% \subsection{Redefinitions of Common {\LaTeX} Macros and Environments} 
%
% The |rdfmeta| package redefines common {\LaTeX} commands (e.\,g.\ the sectioning macros)
% so that they include optional KeyVal arguments that can be extended by |\keydef|
% commands. With this extension, we can add RDFa metadata to any existing {\LaTeX}
% document and generate linked data (XHTML+RDFa documents) via the {\latexml}
% translator. The only thing needed\ednote{continue}
% 
% \subsection[id=redefining]{Extending Packages with \texttt{rdfmeta}}
% 
% The |rdfameta| package also exposes its internal infrastructure for extending the
% redefinitions. Note that the upgrade macros can only be used in {\LaTeX} packages, as
% the macro names contain |@|. Consequently, this section is only addressed at package
% developers who want to extend existing (i.e. not written by them) packages with flexible
% metadata functionality.
% 
% \DescribeMacro{\rdfmeta@upgrade}|\rdfmeta@upgrade| is the basic upgrade macro. It takes
% an optional keyval argument an a command sequence \meta{cseq} as a proper argument and
% (if that is defined), redefines |\|\meta{cseq} to take a keyval argument.  There is a
% variant \DescribeMacro{\rdfmeta@upgrade*}|\rdfmeta@upgrade*| that has to be used to
% upgrade macros that have a starred form (e.g. |\section| and friends). Note that
% |\rdfmeta@upgrade*| upgrades both forms (e.g. |\section| and |\section*|).
%
% |\rdfmeta@upgrade| uses four keys to specify the behavior in the case the the macro to
% be upgraded already has an optional argument. For concreteness, we introduce them using
% the |\section| macro from standard {\LaTeX} as an example. |\section| has an optional
% argument for the ``short title'', which will appear in the table of contents. The
% \DescribeMacro{optarg}|optarg| key can be used to specify a key for the existing
% optional argument. Thus, after upgrading it via
% |\rdfmeta@upgrade*[optarg=short]{section}|, we can use the updated form
% |\section[short=|\meta{toctitle}|]{|\meta{title}|}| instead of the old
% |\section[|\meta{toctitle}|]{|\meta{title}|}|. Actually, this still has a problem: the
% |\section*| would also be given the |short| key and would be passed an optional argument
% (which it does not accept). To remedy this we can set the
% \DescribeMacro{optargstar}|optargstar| key to |no|. In summary, the correct upgrade
% command for |\section| and |\section*| would be
% \begin{verbatim}
% \rdfmeta@upgrade*[optarg=short,optargstar=no]{section}
% \end{verbatim}
% The |\rdfmeta@upgrade*| macro also initializes a metadata key-group (a named set of
% keys and their handlers; see~\cite{Kohlhase:metakeys:svn} for details) for the section
% macro with an |id| key for identification (see~\cite{Kohlhase:sref*} for
% details). Often, the name of the key-group is the same as the command sequence, so we
% take this as the default, if we want to specify a different metadata key-group name, we
% can do so with the |keygroup| key in |\rdfmeta@upgrade*|.
% 
% \begin{oldpart}{not implemented or tested yet.}
%   If \DescribeMacro{label}|idlabel| is set to \meta{prefix}, then the {\LaTeX} label is
%   set to the value \meta{prefix}|.|\meta{id}, where \meta{id} is the value given in the
%   RDFa |id| key. This allows to use the normal {\LaTeX} referencing mechanism in
%   addition to the semantic referencing mechanism provided by the |sref|
%   package~\ctancite{Kohlhase:sref}.
% \end{oldpart}
% 
% \subsection[id=limitations]{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 Currently the coverage of the redefinitions of standard commands in the
%   \url{rdfmeta} package is minimal; we will extend this in the future.
% \item The |\rdfmeta@upgrade| macro only works with single arguments, this should be easy
%   to fix with |\case| for the argument string. 
% \item I am not sure |\rdfmeta@upgrade| works with environments.
% \end{compactenum}
% 
% \StopEventually{\printbibliography}
% 
% \section[id=impl]{The Implementation}
% 
% The |sref| 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.
%
% We first set up header information for the {\latexml} binding file. 
%    \begin{macrocode}
%<*ltxml>
package LaTeXML::Package::Pool;
use strict;
use LaTeXML::Package;
%</ltxml>
%    \end{macrocode}
% 
% \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).\ednote{need an implementation for {\latexml}}
%
%    \begin{macrocode}
%<*package>
\DeclareOption{showmeta}{\PassOptionsToPackage{\CurrentOption}{metakeys}}
\newif\if@rdfmeta@sectioning\@rdfmeta@sectioningfalse
\DeclareOption{sectioning}{\@rdfmeta@sectioningtrue}
\ProcessOptions
%</package>
%<*ltxml>
DeclareOption('showmeta','');
DeclareOption('sectioning','');
%</ltxml>
%    \end{macrocode}
%
% The first measure is to ensure that the right packages are loaded.
%    \begin{macrocode}
%<*package>
\RequirePackage{sref}
%</package>
%    \end{macrocode}
%
% \subsection[id=impl:upgrade]{RDFa upgrade Facilities}
% 
% We first define the keys for the |\rdfmeta@upgrade| macro. 
%    \begin{macrocode}
%<*package>
\def\@yes@{yes}
\addmetakey*{upgrade}{idlabel}
\addmetakey*{upgrade}{optarg}
\addmetakey*[yes]{upgrade}{optargstar}
\addmetakey*{upgrade}{keygroup}
%    \end{macrocode}
%
% \begin{macro}{\rdfmeta@upgrade}
%   This upgrade macro gives extended functionality according to the optional keys. The
%   top-level invocation just differentiates on whether a star is following:
%    \begin{macrocode}
\def\rdfmeta@upgrade{\@ifstar\rdfmeta@upgrade@star\rdfmeta@upgrade@nostar}
%    \end{macrocode}
% Both cases are almost the same, they only differ in the third line where they call
% |\rdfmeta@upgrade@base| or |\rdfmeta@upgrade@base@star| defined above. In particular,
% both take the arguments originally intended for |\rdfmeta@upgrade|.
%    \begin{macrocode}
\newcommand\rdfmeta@upgrade@nostar[2][]{\metasetkeys{upgrade}{#1}%
\ifx\upgrade@keygroup\@empty\def\@@group{#2}\else\def\@@group{\upgrade@keygroup}\fi
\rdfmeta@upgrade@base{#2}{\@nameuse{\@@group @\upgrade@optarg}}}
%    \end{macrocode}
% They set the metakeys from the second argument, then set |\@@group| to be the intended
% group (if the |keygroup| key was specified, it takes precedence over the default
% |#2|).
%    \begin{macrocode}
\newcommand\rdfmeta@upgrade@star[2][]{\metasetkeys{upgrade}{#1}%
\ifx\upgrade@keygroup\@empty\def\@@group{#2}\else\def\@@group{\upgrade@keygroup}\fi
\rdfmeta@upgrade@base@star{#2}{\@nameuse{\@@group @\upgrade@optarg}}}
%</package>
%<*ltxml>
%</ltxml>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rdfmeta@upgrade@base}
%   This auxiliary macro and is invoked as
%   |\rdfmeta@upgrade@base{|\meta{cseq}|}{|\meta{optarg}|}|, where \meta{cseq} is a
%   command sequence name. It checks if |\|\meta{cseq} is defined (if not it does
%   nothing), saves the old behavior of |\|\meta{cseq} as |\rdfmeta@|\meta{cseq}|@old|,
%   and then redefines |\|\meta{cseq} to take a keyval argument and passes \meta{optarg}
%   as the optional argument.
%    \begin{macrocode}
%<*package>
\newcommand{\rdfmeta@upgrade@base}[2]{\@ifundefined{#1}{}%
{\srefaddidkey{#1}%
\expandafter\let\csname rdfmeta@#1@old\expandafter\endcsname\csname #1\endcsname%
\expandafter\renewcommand\csname #1\endcsname[2][]%
{\metasetkeys{#1}{##1}\@nameuse{rdfmeta@#1@old}[#2]{##2}}
\addmetakey*\@@group{\upgrade@optarg}}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\rdfmeta@upgrade@base@star}
%   This is a variant of |\rdfmeta@upgrade@base|, which also takes care of the starred
%   variants of a macro.
%    \begin{macrocode}
\newcommand{\rdfmeta@upgrade@base@star}[2]{\@ifundefined{#1}{}%
{\srefaddidkey{#1}% 
\expandafter\let\csname rdfmeta@#1@old\expandafter\endcsname\csname #1\endcsname%
%    \end{macrocode}
% In this case, we cannot just use |\newcommand| for dealing with the optional argument
% because the star is between the command sequence and the arguments. So we make a case
% distinction on the presence of the star. 
% |\rdfmeta@|\meta{cseq}|@old|.
%    \begin{macrocode}
\expandafter\def\csname #1\endcsname%
{\@ifstar{\@nameuse{rdfmeta@#1@star}}{\@nameuse{rdfmeta@#1@nostar}}}%
%    \end{macrocode}
% the macros |\rdfmeta@|\meta{cseq}|@star| and |\rdfmeta@|\meta{cseq}|@nostar| that are
% defined in terms of |\rdfmeta@|\meta{cseq}|@old| handle the necessary cases. The second
% one is simple:
%    \begin{macrocode}
\expandafter\newcommand\csname rdfmeta@#1@nostar\endcsname[2][]%
{\metasetkeys{#1}{##1}\@nameuse{rdfmeta@#1@old}[#2]{##2}}%
%    \end{macrocode}
% For |\rdfmeta@|\meta{cseq}|@star| we have to take care of the optional argument of the
% old macro: if the |optargstar| key was set, then we pass the second argument of
% |\rdfmeta@upgrade@base| as an optional argument to it as above. 
%    \begin{macrocode}
\ifx\upgrade@optargstar\@yes@%
\expandafter\newcommand\csname rdfmeta@#1@star\endcsname[2][]%
{\metasetkeys{#1}{##1}\@nameuse{rdfmeta@#1@old}*[#2]{##2}}%
\else%
\expandafter\newcommand\csname rdfmeta@#1@star\endcsname[2][]%
{\metasetkeys{#1}{##1}\@nameuse{rdfmeta@#1@old}*{##2}}%
\fi%
\addmetakey*\@@group{\upgrade@optarg}}}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \subsection[id=impl:keydef]{Key Definitions}
%
% \begin{macro}{\keydef}
%   The |\keydef| macro is rather simple, we just add a key to the respective environment
%   and do a |\symdef|.
%    \begin{macrocode}
%<*package>
\newcommand\keydef[2]{\addmetakey{#1}{#2}\symdef{#2}{\text{#2}}}
%</package>
%<*ltxml>
%</ltxml>
%    \end{macrocode}
% \end{macro}
%
% \subsection[id=impl:redef]{Redefinitions}
%
% If the |sectioning| macro is set, we redefine the respective commands
%
%    \begin{macrocode}
%<*package>
\if@rdfmeta@sectioning
\rdfmeta@upgrade*[optarg=short,optargstar=no]{part}
\rdfmeta@upgrade*[optarg=short,optargstar=no]{chapter}
\rdfmeta@upgrade*[optarg=short,optargstar=no]{section}
\rdfmeta@upgrade*[optarg=short,optargstar=no]{subsection}
\rdfmeta@upgrade*[optarg=short,optargstar=no]{subsubsection}
\rdfmeta@upgrade*[optarg=short,optargstar=no]{paragraph}
\fi
%</package>
%<*ltxml>
%</ltxml>
%    \end{macrocode}
% \subsection{Finale}
%
% Finally, we need to terminate the file with a success mark for perl.
%    \begin{macrocode}
%<ltxml>1;
%    \end{macrocode}
% \Finale
\endinput
% \iffalse
% LocalWords:  GPL structuresharing STR LaTeX dcm dtx keyval sref CPERL url qw
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: 
% \fi

% LocalWords:  RequirePackage birthdate personaltitle academictitle workaddress
% LocalWords:  privaddress worktel privtel workfax privfax worktelfax noDelim
% LocalWords:  privtelfax getKeyValue valuelist ToString getValue affill STDERR
% LocalWords:  ExportMetadata AssignValue DCMperson DefConstructor afterDigest
% LocalWords:  getArg setValue FishOutMetadata keyvals foreach idlist tabline
% LocalWords:  LookupValue insertElement atabline bitabline shorttitle nc args
% LocalWords:  sharealike noderivativeworks DefMacro authorblock subsubsection
% LocalWords:  contribs OptionalKeyVals omgroup omdoc srcref locator xml RawTeX
% LocalWords:  openElement iffalse kohlhase Thu rdfmeta latexml fileversion omd
% LocalWords:  maketitle setcounter tocdepth tableofcontents newpage section
% LocalWords:  stex exfig vspace hrule lstinputlisting morekeywords aboveskip
% LocalWords:  hasstate.omdoc statedocrd tuev certifiation keydef ednote texttt
% LocalWords:  keysets rdfameta cseq idlabel ctancite ifundefined impl ltxml
% LocalWords:  printbibliography newcommand srefaddidkey expandafter csname ifx
% LocalWords:  expandafter endcsname csname endcsname renewcommand  showmeta
% LocalWords:  symdef redef doctex showmeta metakeys keyset textbackslash cert
% LocalWords:  MathOntoAuthDoc09 WD-rdfa-core-20100803 hasstate omtext omtext
% LocalWords:  addkey optarg optarg toctitle optargstar optargstar keygroup
% LocalWords:  oldpart textsf langle textsf langle newif sectioningfalse ifstar
% LocalWords:  sectioningtrue metasetkeys nameuse addmetakey nostar
