summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-11-12 00:31:31 +0000
committerKarl Berry <karl@freefriends.org>2010-11-12 00:31:31 +0000
commit70e387eb63ce4723858c48592208e193dec294f3 (patch)
tree61ec42df871a70687151ed4a6d1bc6a5c81dc53c /Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx
parent2cee8f6dcf8e9596b5cfe9d1f3e55c61b261a320 (diff)
stex 0.9.3 (11nov10)
git-svn-id: svn://tug.org/texlive/trunk@20410 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.dtx372
1 files changed, 372 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..c8ce7762f59
--- /dev/null
+++ b/Master/texmf-dist/source/latex/stex/metakeys/metakeys.dtx
@@ -0,0 +1,372 @@
+% \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: 1671 $; last modified by $Author: kohlhase $
+% $Date: 2010-11-06 08:05:15 +0100 (Sat, 06 Nov 2010) $
+% 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}[2010/09/02 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 1671 2010-11-06 07:05:15Z 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
+%
+%\iffalse\CheckSum{58}\fi
+%
+% \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}
+%
+% The |metakeys| package supplies the infrastructure for extending {\sTeX} macros with
+% ontology-based metadata. The |metakeys| infrastructure is intended to support the new
+% metadata infrastructure for the {\omdoc} format~\cite{Kohlhase:omdoc1.2} introduced in
+% {\omdocv{1.3}}~\cite{Kohlhase:OMDoc1.3}.
+%
+% \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}
+%
+% If \meta{group} is the name of a metadata key-group \meta{key} is a metadata keyword
+% name, then \DescribeMacro{\addmetakey}
+% \begin{quote}
+% |\addmetakey[|\meta{default}|]{|\meta{group}|}{|\meta{key}|}|
+% \end{quote}
+% registers \meta{key} in the metadata group \meta{group}, with an optional value
+% \meta{default} for \meta{key}. 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}. With these definitions in a used package\footnote{The \texttt\@
+% character is only allowed in packages.} |\foo[type=bar,id=f4711]| is formatted to
+% \begin{quote}
+% \addmetakey{foo}{id}\addmetakey{foo}{type}\makeatletter
+% \newcommand\foo[1][]{\metasetkeys{foo}{#1} I have seen a \emph{foo} of type \texttt{\foo@type}
+% with identifier \texttt{\foo@id}!}\makeatother
+% \foo[type=bar,id=f4711]
+% \end{quote}
+%
+% \begin{exfig}[ht]
+% \begin{verbatim}
+% \addmetakey{foo}{id}
+% \addmetakey{foo}{type}
+% \addmetakey[yes]{foo}{visible}
+% \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!
+% \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][]{\metakeys@ext@clear@keys{#2}{#3}{#1}%
+\metakeys@initialize@showkeys{#2}%
+\define@key{#2}{#3}[#1]{\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\def\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}
+%
+% \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}
+%<ltxml>DefConstructor('\showmetakeys','');
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hidemetakeys}
+% \begin{macrocode}
+%<package>\newcommand\hidemetakeys{\metakeys@showmetafalse}
+%<ltxml>DefConstructor('\hidemetakeys','');
+% \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