diff options
author | Karl Berry <karl@freefriends.org> | 2012-03-30 23:23:02 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-03-30 23:23:02 +0000 |
commit | 849996eca72af498b48b10fbea7f14c4b9d21b8f (patch) | |
tree | 2d40d42dfc9fc0b0622212cc220868f98345305f /Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx | |
parent | d82e1c23973fd0271f93686f487bd1cee8dcd947 (diff) |
restore stex (ca. 28jan12)
git-svn-id: svn://tug.org/texlive/trunk@25792 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx b/Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx new file mode 100644 index 00000000000..0222eb14161 --- /dev/null +++ b/Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx @@ -0,0 +1,435 @@ +% \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 |