diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-rdf.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-rdf.tex | 1040 |
1 files changed, 1040 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-rdf.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-rdf.tex new file mode 100644 index 00000000000..d972c80c5ae --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-rdf.tex @@ -0,0 +1,1040 @@ +% Copyright 2016 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Resource Description Framework Library} +\label{section-library-rdf} +\label{section-tikz-rdf} + +With \todosp{why two labels? Both don't seem to be used.} certain output +formats (in particular, with \textsc{svg}), \tikzname\ can add \emph{semantic +annotations} to an output file. Consider as an example the drawing of a finite +automaton. In your \TeX\ code, you might have a nice description of the +automaton like the following: +% +\begin{codeexample}[code only] +\tikz[automaton] \graph { a[state, initial] ->[transition] b [state] ->[transition] c[state, final] }; +\end{codeexample} +% +This description of the automaton carries a lot of ``semantic information'' +like the information that the node |a| is not just some node, but actually the +initial state of the automaton, while |c| is a final state. Unfortunately, in +the output produced \tikzname, this information is normally ``lost'': In the +output, |a| is only a short text, possibly with a circle drawn around it; but +there is no information that \emph{this} text and \emph{this} circle together +form the state of an automaton. + +As a human (more precisely, as a computer scientist), you might ``see'' that +the text and the circle form a state, but most software will have a very hard +time retrieving this semantic information from the output. In particular, it is +more or less impossible to design a search engine that you can query to find, +say, ``all automata with three states'' in a document. + +This is the point were \emph{semantic annotations} come in. These are small +labels or ``hints'' in the \emph{output} that tell you (and, more importantly, +a program) that the text and the circle together form a state of an automaton. +There is a standard for specifying such annotations (``resource description +framework annotations'', abbreviated \textsc{rdf}a) and \tikzname\ provides a +way of adding such annotations to an output file using the |rdf engine| key, +explained in a moment. Note, however, that the output format must support such +annotations; currently \tikzname\ only supports \textsc{svg}. + + +\subsection{Starting the RDF Engine} + +\begin{tikzlibrary}{rdf} + You need to load this library for the keys described in the following. + However, even when this library is loaded, \textsc{rdf} information is only + written to the output inside scopes where the following key is set: + % + \begin{key}{/tikz/rdf engine on} + Switches ``on'' the generation of \textsc{rdf} information for the + current \TeX\ scope. The idea is that libraries can internally use the + |rdf engine| key (explained below) a lot in order to provide good + semantic information in the output when desired, but need not worry + that this will bloat output files since users have to use this key + explicitly to include semantic information in the output. + \end{key} +\end{tikzlibrary} + +\begin{key}{/tikz/rdf engine=\meta{rdf keys}} + This key only has an effect when |rdf engine on| is called, otherwise the + argument is silently ignored. The \meta{rdf keys} get executed with the + path prefix |/tikz/rdf engine| at the beginning of the current scope (for a + node, at the beginning of the node's scope). Depending on which keys are + used, semantic information gets to be added to the output. + + Note that you cannot simply the keys with path prefix |/tikz/rdf engine| + directly since they need to be executed at very specific times during + \tikzname's processing of scopes. Always call those keys via this key. +\end{key} + +The following key is useful for generally setting the prefix for a larger +number of annotations: + +\begin{key}{/tikz/rdf engine/prefix=\meta{prefix: iri}} + Inside the current scope, you can use \meta{prefix}|:| inside curies + (compact universal resource identifier expressions, see the \textsc{rdfa} + specification) as an abbreviation for the \meta{iri}. (It has the same + effect as the |prefix| attribute in \textsc{rdf}a.) You can use this key + several times for a given scope. + % +\begin{codeexample}[code only] +\scoped [rdf engine = { + prefix = {rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark}, + prefix = {automata: http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/}, + statement = { ..., predicate = rdf:type, object = automata:state }, + statement = { ..., predicate = rdf:type, object = automata:final }, + }] ... +\end{codeexample} + % + The above could also be written more verbosely as + % +\begin{codeexample}[code only] +\scoped [rdf engine = { + statement = { ..., + predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type, + object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/state } + }, + statement = { ..., + predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type, + object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/final } + }] ... +\end{codeexample} + + The use of the command |\tikzrdfhashmark| is necessary since \TeX\ assigns + a special meaning to hash marks. The command simple expands to a ``normal'' + hash mark for use in texts. + % + \begin{command}{\tikzrdfhashmark} + Expands to |#| with catcode 11. + \end{command} +\end{key} + + +\subsection{Creating Statements} + +\tikzname's method of adding semantic information to an output is based on the +principles underlying the \emph{resource description framework} (\textsc{rdf}). +In this framework, all semantic information is encoded using a large graph +consisting of nodes and connecting directed edges, but the nodes are called +\emph{resources} and the edges are called \emph{statements}. A resource is +identified by an \textsc{iri}, an \emph{internationalized resource identifier,} +which basically looks like the well-known \textsc{url}s, but allows additional +Unicode characters. Note that these \textsc{iri}s do not need to point to +``real'' webpages, they are just a way of conceptually identifying resources +uniquely and permanently. Similarly, each edge (statement) of the \textsc{rdf} +graph has such an \textsc{iri} attached to it, which identifies the ``flavour'' +of the arc. + +In a ``mathematical'' graph, each edge has a ``tail'' and a ``head'' vertex and +a label, but in the context of the resource description framework these notions +are called differently: As mentioned before, an edge is called a +\emph{statement}, the tail of this edge is called the \emph{subject}, the head +is called the \emph{object} (in the linguistic sense), and the label is called +the \emph{predicate}. Thus, a statement is -- quite fittingly -- a triple +``subject predicate object''. + +Note that in the \textsc{rdf} framework \emph{all} semantic information must be +encoded using statements of this fixed kind. Many semantic notions are easy to +store in this way such as ``Albert Einstein was a physicist'' (``Albert +Einstein'' is the subject, ``was'' is the predicate, ``a physicist'' is the +object), but other notions do not fit well like ``The automaton has states +$q_1$, $q_2$, $q_a$, and $q_b$'' since there are several objects in the +statement. Nevertheless, all information must be encoded as simple statements +with a single subject, a single predicate, and a single object. + +You add an \textsc{rdf} statement to the output file using the following key: + +\begin{key}{/tikz/rdf engine/statement=\marg{options}} + Each use of this key will add one \textsc{rdf} statement to the output + file. The \meta{options} will be executed with the path prefix + |/tikz/rdf engine/statements| and must use the three keys |subject|, + |predicate|, and |object| to specify the three components of the statement + (these keys can, however, be called by styles internally, so not all + statements will explicitly set these three keys). Note that \emph{all three + must always be set}, it is \emph{not} possible to setup, say, just a + subject for a scope and then omit the subject for statements inside the + scope. (However, using styles you can setup things in such a way that a + certain subject is used for several statements.) + % +\begin{codeexample}[code only] +\tikz [rdf engine = { + statement = { + subject = http://www.example.org/persons/Einstein, + predicate = http://www.example.org/predicates/isA, + object = http://www.example.org/professions/physicist + }, + statement = { + subject = http://www.example.org/persons/Curie, + predicate = http://www.example.org/predicates/isA, + object = http://www.example.org/professions/physicist + }}] { ... } +\end{codeexample} + + The statements are normally added at the beginning of the scope where the + |rdf enging| command is used (except when the |object| is |scope content|, + which is explained later). This means that when you use |prefix| inside an + |rdf engine| command, it will apply to all statements, regardless of the + order. + + \begin{key}{/tikz/rdf engine/statements/subject=\meta{subject}} + Sets the subject of the to-be-created statement. The \meta{subject} can + be in one of two possible formats: + % + \begin{enumerate} + \item A curie (a \emph{compact universal resource identifier + expression,} see the \textsc{rdfa} specification for details). + Examples are standard \textsc{url}s like + |http://www.example.org|, but also text like |#my_automaton|. + Note that in order to include a hashmark in a curie you should + use the command |\tikzrdfhashmark|, which expands to a hash + mark (\TeX\ treats hash marks in a special way, which is why + this command is used here). + \item When the \meta{subject} starts with an opening parenthesis, + that is, with ``|(|'', the \meta{subject} must have the form + |(|\meta{node or scope name}|)|. In this case, the \meta{node + or scope name} must be the name of an already existing node + (the current node or scope is considered as ``existing'' here). + Then, the curie |#|\meta{id} is used as subject, where the + \meta{id} is a unique internal identifier for the node. + + As an example, suppose you wish to specify that a node has some + other node as child, you could write the following: + % +\begin{codeexample}[code only] +\tikz [ rdf engine = { prefix = { rels: http://www.example.org/relations/} } ] { + \node (fritz) { Fritz }; + \node (heinz) at (2,0) { Heinz }; + \draw [->] (fritz) -- (heinz) + [rdf engine = { + statement = { + subject = (fritz), + predicate = rels:isSonOf, + object = (heinz) + } } ]; +} +\end{codeexample} + \end{enumerate} + % + You can use a macro as \meta{subject}, it will be expanded before the + above syntax check is done. + + If you use the |subject| key several times inside a single |statement| + command, (only) the last subject is used. + \end{key} + + \begin{key}{/tikz/rdf engine/statements/predicate=\meta{predicate}} + Sets the predicate for the statement. The syntax is exactly the same as + for the subject. Unlike for subjects, you can use the predicate key + several times inside a single statement and the uses will + ``accumulate'' and several statements are created, namely one statement + for each use of |predicate| for the subject and object specified inside + the use of |statement|. This behavior is not very systematic (it + violates the rule ``one statement per |statement|'') and you should + normally use the |statement| once for each use of the |predicate| + key. However, in conjunction with the object |scope content| it is + necessary to allow this behavior. + \end{key} + + \begin{key}{/tikz/rdf engine/statements/object=\meta{object}} + Sets the object for the statement. The syntax allowed for the + \meta{object} is as follows: + % + \begin{enumerate} + \item As for |subject| and |predicate| you can use a curie here. + This is the default unless one of the following special cases + is used: + \item As for |subject| and |predicate|, you can use the syntax + |(|\meta{name of node or scope}|)| to create and use a curie + for the node or scope. + \item If the \meta{object} starts with |"|, it must have the syntax + |"|\meta{literals}|"|. In this case, the object of the + statement is not a curie (not a normal ``resource'') but the + string of \meta{literals} given. + \item If the \meta{object} is the text ``|scope content|'', the + object of the statement is actually the whole contents of the + scope to which this statement is attached. + \item The two previous cases can be combined in the form of an + object of the form |"|\meta{literals}|" and scope content|. In + this case, the contents of the scope is ``normally'' the + object, but this gets ``overruled'' by the \meta{literals}. + Formally, this means that the object is the \meta{literals}, + but the intended semantics is that the object is the scope + content, only for further processing it should be considered to + be \meta{literals}. A typical example is the case where the + scope content is, say, the text ``January 1st, 2000'' but the + \meta{literals} are set to |2000-01-01|, which is easier for + software to process: + % +\begin{codeexample}[code only] +\node [rdf engine = { + statement = { + subject = ..., + predicate = dc:Date, + object = "2000-01-01" and scope content + } } ] { January 1st, 2000 }; +\end{codeexample} + \end{enumerate} + % + For the last two cases, only one statement may be given per scope that + has the |scope content| as its object; if more than one is given, the + last one wins. This is the reason why several uses of |predicate| are + allowed in a |statement|. + \end{key} + + \begin{key}{/tikz/rdf engine/statements/has type=\meta{type}} + This style is a shorthand for |predicate=rdf:type| and + |object=|\meta{type}. + \end{key} +\end{key} + + +\subsection{Creating Resources} + +In \textsc{rdf} statements, when you can use the name of a \tikzname\ scope or +node surrounded by parenthesis, a curie is inserted into the output that +references this scope or node. While this makes it easy to describe +relationships between existing nodes, in library code (\textsc{rdf} generation +code added to library styles and gets executed as a ``byproduct'') there are +two situations where this method is insufficient: +% +\begin{enumerate} + \item You may sometimes wish to create additional resources in the + \textsc{rdf} graph that are not represented by any concrete node or + scope in the \tikzname\ picture. For instance, a finite automaton has a + set of states and a set of transitions, but neither of these + ``containers'' has any concrete representation in the output. One + could, of course, create ``dummy scopes'' for this purpose, but this is + rather hard to do inside styles of a library. + \item You may not know the name of the current scope in library code. For + instance, a style like |state|, which can be added to a node to + indicate that the node is supposed to be a state in a finite automaton, + might contain something like the following code: + % +\begin{codeexample}[code only] +state/.style = { + draw, circle, minimum size = ..., + rdf engine = { + subject = ???, + predicate = rdf:type, + object = automata:state + } +} +\end{codeexample} + % + The problem is, of course, what should be passed to the |subject|. We + cannot even write something like |(\tikz@fig@name)| since no name may + have been set for the state. +\end{enumerate} + +Each of the above problems is solved by a special keys: + +\begin{key}{/tikz/rdf engine/get new resource curie=\meta{macro}} + The \meta{macro} will be set to a new unique curie that can be used + anywhere where a curie is allowed. Here is an example how we can add a + state and a transition container to an automaton, both of which have no + corresponding scope in \tikzname. + % +\begin{codeexample}[code only] +\tikz [ name = my automaton, + rdf engine = { + get new resource curie = \statecurie, + get new resource curie = \transitiocurie, + statement = { + subject = (my automaton), + predicate = automata:hasStateSet, + object = \statecurie }, + statement = { + subject = \statecurie, + hat type = automata:stateSet }, + statement = { + subject = (my automaton), + predicate = automata:hasTransitionSet, + object = \transitiocurie }, + statement = { + subject = \transitiocurie, + hat type = automata:transitionSet } } ] { ... } +\end{codeexample} + % + The \meta{macro} will be valid for the whole scope. +\end{key} + +\begin{key}{/tikz/rdf engine/get scope curie=\meta{macro}} + The \meta{macro} will be set to a unique curie that represents the scope or + node. If the scope is named (using the |name| key or the special + parenthesis syntax for nodes) and this name is later referenced in another + statement, the same curie will be generated. Note how in the following code + no name is given for the automaton, which means that the whole \textsc{rdf} + code could be moved inside a style like |finite automaton| or something + similar. + % +\begin{codeexample}[code only] +\tikz [ rdf engine = { + get new resource curie = \statecurie, + get new resource curie = \transitiocurie, + get scope curie = \automatoncurie, + statement = { + subject = \automatoncurie, + predicate = automata:hasStateSet, + object = \statecurie }, + statement = { + subject = \statecurie, + hat type = automata:stateSet }, + statement = { + subject = \automatoncurie, + predicate = automata:hasTransitionSet, + object = \transitiocurie }, + statement = { + subject = \transitiocurie, + hat type = automata:transitionSet } } ] { ... } +\end{codeexample} + % + The \meta{macro} will be valid for the whole scope. +\end{key} + +The following key builds on the above keys: +% +\begin{key}{/tikz/rdf engine/scope is new context} + This key executes |get scope curie=\tikzrdfcontext|, thereby setting the + macro |\tikzrdfcontext| to the current scope. The idea is the key is used + with ``major resources'' and that keys can use this macro as the |subject| + of statements if no subject is given explicitly. For instance, a |title| + key might be defined as follows: + % +\begin{codeexample}[code only] +title/.style = { + rdf engine = { statement = { + subject = \tikzrdfcontext, + predicate = dc:Title, + object = "#1" +} } } +\end{codeexample} + % +\end{key} + + +\subsection{Creating Containers} + +A \emph{container} is a resource that represents a set or a sequence of +elements. In \textsc{rdf} this is modeled by having a statement say that the +type of the resource is something special like |rdf:Seq| and then for each +member resource of the container add a statement saying that the container has +as its $i$th member the member resource. Here is an example of a container +with two elements: +% +\begin{codeexample}[code only] +\tikz { + \node (safe) { Safe } + child { node (coins) {Coins} } + child { node (gold) {Gold} }; + + \scoped [rdf engine = { + statement = { + subject = (safe), + has type = rdf:Seq + }, + statement = { + subject = (safe), + predicate = rdf:_1, + object = (coins) + }, + statement = { + subject = (safe), + predicate = rdf:_2, + object = (gold) + } }]; +} +\end{codeexample} + +However, the above code is error-prone and does not integrate well with styles +and libraries. For this reason, \tikzname\ offers some styles that may help in +creating containers: + +\begin{key}{/tikz/rdf engine/statements/is a container} + Add this key to a statement in order to tell \tikzname\ that it should + setup a special counter for the subject of the statement that keeps track + of the container's children. +\end{key} + +\begin{key}{/tikz/rdf engine/statements/has as member} + This key may only be added to statements whose subject was previously used + as a subject in a statement containing the |is a container| key. In this + case, the internal counter will be increased and the predicate will be set + to |rdf:_|\meta{count}. This means that we can write the above code as: + % +\begin{codeexample}[code only] +\tikz { ... + + \scoped [rdf engine = { + statement = { + subject = (safe), + has type = rdf:Seq, + is a container, + }, + statement = { + subject = (safe), + has as member, + object = (coins) + }, + statement = { + subject = (safe), + has as member, + object = (gold) + } }]; +} +\end{codeexample} + % +\end{key} + +\begin{key}{/tikz/rdf engine/statements/is a sequence} + This is a shorthand for |predicate = rdf:Seq, is a container|. In the above + example we could say: + % +\begin{codeexample}[code only] +\tikz { ... + + \scoped [rdf engine = { + statement = { + subject = (safe), + is a sequence + }, + ... } ]; } +\end{codeexample} + % +\end{key} + +\begin{key}{/tikz/rdf engine/statements/is a bag} + This is a shorthand for |predicate = rdf:Bag, is a container|. +\end{key} + +\begin{key}{/tikz/rdf engine/statements/is an alternative} + This is a shorthand for |predicate = rdf:Alt, is a container|. +\end{key} + + +\subsection{Creating Semantic Information Inside Styles and Libraries} + +\begingroup + +The \textsc{rdf} library was designed in such a way that normal document +authors do not need to use the keys of the library explicitly, except possibly +for saying |rdf engine on| somewhere at the beginning. Instead, library authors +should include the necessary commands to generate \textsc{rdf} information that +is then automatically included in the output. Furthermore, if the author does +not ``switch on'' the generation of \textsc{rdf} information, all uses of +|rdf engine| will simply be ignored silently and neither the speed of +compilation nor the size of the generated files is impacted. + + +\subsubsection{An Example Library for Drawing Finite Automata} + +In the following, we have a look at how a library might be augmented by +\textsc{rdf} generation keys. The library we augment is a (fictitious) library +for drawing finite automata. The library offers the following styles: +% +\begin{enumerate} + \item |dfa| and |nfa| can be added to a scope to indicate that the scope + contains a deterministic or a nondeterministic finite automaton. + \item |state| can be added to a node to indicate that the node is a state + in the automaton. + \item |initial| and |final| are used to indicate that a state is an initial + or final state, which should be rendered in a special way. + \item |transition| can be added to an edge to indicate that there is a + transition in the automaton from the first state to the second state. + The style takes a parameter which is the symbol read by the automaton. +\end{enumerate} + +Here are some possible definitions of these keys that do not (yet) generate +\textsc{rdf} information: +% +\begin{codeexample}[code only, setup code] +\tikzset { + dfa/.style = { semithick, > = To [sep] }, + nfa/.style = { semithick, > = To [sep] }, + state/.style = { circle, draw, minimum size = 1cm }, + final/.style = { double }, + initial/.style = { draw = red }, % to keep things simple + transition/.style = { edge label = {$#1$} } } +\end{codeexample} + +The library could be used as follows: +% +\begin{codeexample}[width=5cm] +\tikz [dfa] + \graph [math nodes, grow right = 1.5cm] { + q_0 [state, initial] -> [transition = a] + q_1 [state] -> [transition = b, loop above] + q_1 -> [transition = a] + q_2 [state, final] + }; +\end{codeexample} + + +\subsubsection{Adding Semantic Information About the Automata as a Whole} + +Let us change the different keys so that they add \textsc{rdf} information to +the output. For this, we first need an ontology that defines notions like +``state'' or ``deterministic finite automaton''. For the purposes of this +example, we just assume that such an ontology exists at +|http://www.tcs.uni-luebeck.de/ontologies/automata/|. The new definition of the +|dfa| key might start as follows (we will extend these later on): +% +\begin{codeexample}[code only] +dfa/.style = { + semithick, > = To [sep], % as before, + rdf engine = { + % + % Setup prefix: + prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ }, + % + % Get the curie of the automaton and store it in a macro for later use: + get scope curie = \mylibAutomatonCurie, + % + % Make a statement that the resource is, indeed, an automaton: + statement = { + subject = \mylibAutomatonCurie, + has type = automata:types/automaton }, + % + % Make a statement that the automaton is deterministic: + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:properties/deterministic, + object = "yes" } } } +\end{codeexample} + +The definition of the style |nfa| would be exactly the same as for |dfa|, +except, of course, that the last statement would have |"no"| as object. Note +that the original styles |dfa| and |nfa| has identical definitions since, +indeed, there is no ``visual'' difference between the two. In contrast, the +\textsc{rdf} information stores this information in the output. + + +\subsubsection{Adding Semantic Information About the States} + +We next augment the styles for creating states and marking them as final or +initial. We could do the following (note that we do not setup the prefix since +this has been done by the surrounding |dfa| or |nfa| key): +% +\begin{codeexample}[code only] +state/.style = { + circle, draw, minimum size = 1cm, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { + subject = \mylibStateCurie, + has type = automata:types/state }, + statement = { + subject = \mylibStateCurie, + predicate = rdf:value, + object = scope content } } } +\end{codeexample} + +The first statement tells us that the circle with its contents is a state (and +not just ``any'' fancy circle). The second statement tells us that the +``value'' of this state is the content. One might argue that, instead, only the +number itself (like ``$q_0$'' or perhaps only ``$0$'') should be the ``value'' +or, perhaps, a different property should actually be used (like +|automata:stateNumber| or something like that). However, these are questions of +ontological modeling, not of the use of the \textsc{rdf} engine. + +What is definitely missing from the above definition is a link between the +automaton resource and the state resource. Note that the state's rendering code +will be inside the scope of the automaton, so, in a sense, the state is +``inside'' the automaton in the output. However, the nesting of scopes is +\emph{not} part of the \textsc{rdf} graph; we must make these relationships +explicit using statements. One way to achieve this would be to add the +following to the |state| style: +% +\begin{codeexample}[code only] + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:hasAsAState, + object = \mylibStateCurie } +\end{codeexample} + +Note that we can access the macro |\mylibAutomatonCurie| here since this will +have been setup by the surrounding |dfa| or |nfa| key. While the above is +possible and legitimate, we will see a better solution using containers in a +moment (``better'' in the sense that the ontological model is easier to process +by software). + +The two styles |final| and |initial| are easy to augment: +% +\begin{codeexample}[code only] +final/.style = { + double, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { + subject = \mylibStateCurie, + has type = automata:properties/final } } } +\end{codeexample} + +Note that when we write |node [state, final] ...| the state now has two types: +It has type |automata:types/state| and also |automata:properties/final|. This +is perfectly legitimate. Also note that I added |get scope curie| to the above +definition, which may seem superfluous since the |state| style already executes +this key to get a curie for the state resource. However, users should be free +to write |node [final, state] ...| and, now, the |final| key will be executed +first. + +The style for |initial| is the same as for |final| only with a different type. + + +\subsubsection{Adding Semantic Information About the Transitions} + +A transition is, essentially, a labeled edge from a state to another state. It +may seem tempting to model them as a statement with the first state as its +subject and the second state as the object and the transition's symbol as the +label (turned into a curie in some appropriate way). However, closer inspection +shows that this is not a good way of modeling transitions: In essence, it is +just coincidence that the \textsc{rdf} graph happens to be a directed graph +and, at the same time, the thing we describe by it (the automaton) can also be +viewed as a directed graph. If, for instance, we consider alternating automata +where a transition can involve more than two states, the simple model breaks +down. + +The ``right'' way of modeling a transition is to treat the transition as a +resource of its own and then make statements like ``the transition has this +state as its old state''. This turns out to be relatively easy to achieve: +% +\begin{codeexample}[code only] +transition/.style = { + edge label = {#1}, % as before, + rdf engine = { + get scope curie = \mylibTransitionCurie, + statement = { + subject = \mylibTransitionCurie, + has type = automata:types/transition }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:properties/symbolReadFromTape, + object = "#1" }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:relations/oldState, + object = (\tikztostart) }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:relations/newState, + object = (\tikztotarget) } } } +\end{codeexample} + + +\subsubsection{Using Containers} + +As a last step we wish to organize the states and transitions using containers. +As explained earlier, we can easily add statements linking our automaton to the +states and to the transitions, but the \textsc{rdf} standard has standard way +of specifying that a set of resources form a logical sequence: containers. + +In case automata contained \emph{only} states, we could setup the automaton +itself to be the container and the states to be its elements. However, the +automaton has states and transitions and in this example I would like to keep +these in separate containers. Thus, we must create two containers and then make +statements that the automaton contains these two containers. Since these +containers do not have any accompanying visual representation, we use the +|get new resource curie| key to create new resources that are purely for +descriptive purposes inside the \textsc{rdf} graph: +% +\begin{codeexample}[code only] +dfa/.style = { + semithick, > = To [sep], % as before, + rdf engine = { + prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ }, + get scope curie = \mylibAutomatonCurie, + statement = { ... as before that automaton has type automata:types/automaton ... }, + statement = { ... as before that automaton is deterministic ... }, + get new resource curie = \mylibStateContainerCurie, + statement = { + subject = \mylibStateContainerCurie, + is a sequence }, + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:relations/hasAsStateContainer, + object = \mylibStateContainerCurie }, + get new resource curie = \mylibTransitionContainerCurie, + statement = { + subject = \mylibTransitionContainerCurie, + is a sequence }, + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:relations/hasAsTransitionContainer, + object = \mylibTransitionContainerCurie } } } +\end{codeexample} + +We can now modify the |state| style as follows: +% +\begin{codeexample}[code only] +state/.style = { + circle, draw, minimum size = 1cm, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { ... as before ... }, + statement = { ... as before ... }, + statement = { + subject = \mylibStateContainerCurie, + has as member, + object = \mylibStateCurie } } } +\end{codeexample} + +The modification for the |transition| style is similar: +% +\begin{codeexample}[code only] +transition/.style = { + edge label = {#1}, % as before, + rdf engine = { + get scope curie = \mylibTransitionCurie, + statement = { ... as before ... }, + statement = { ... as before ... }, + statement = { ... as before ... }, + statement = { ... as before ... }, + statement = { + subject = \mylibTransitionContainerCurie, + has as member, + object = \mylibTransitionCurie } } } +\end{codeexample} + + +\subsubsection{The Resulting RDF Graph} + +Putting it all together, we now get the following library code: +% +\begin{codeexample}[setup code, multipage] +\tikzset { + dfa/.style = { + semithick, > = To [sep], % as before, + rdf engine = { + prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ }, + get scope curie = \mylibAutomatonCurie, + statement = { + subject = \mylibAutomatonCurie, + has type = automata:types/automaton }, + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:properties/deterministic, + object = "yes" }, + get new resource curie = \mylibStateContainerCurie, + statement = { + subject = \mylibStateContainerCurie, + is a sequence }, + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:relations/hasAsStateContainer, + object = \mylibStateContainerCurie }, + get new resource curie = \mylibTransitionContainerCurie, + statement = { + subject = \mylibTransitionContainerCurie, + is a sequence }, + statement = { + subject = \mylibAutomatonCurie, + predicate = automata:relations/hasAsTransitionContainer, + object = \mylibTransitionContainerCurie } } }, + state/.style = { + circle, draw, minimum size = 1cm, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { + subject = \mylibStateCurie, + has type = automata:types/state }, + statement = { + subject = \mylibStateCurie, + predicate = rdf:value, + object = scope content }, + statement = { + subject = \mylibStateContainerCurie, + has as member, + object = \mylibStateCurie } } }, + initial/.style = { + draw = red, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { + subject = \mylibStateCurie, + has type = automata:properties/initial } } }, + final/.style = { + double, % as before, + rdf engine = { + get scope curie = \mylibStateCurie, + statement = { + subject = \mylibStateCurie, + has type = automata:properties/final } } }, + transition/.style = { + edge label = {$#1$}, % as before, + rdf engine = { + get scope curie = \mylibTransitionCurie, + statement = { + subject = \mylibTransitionCurie, + has type = automata:types/transition }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:properties/symbolReadFromTape, + object = "#1" }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:relations/oldState, + object = (\tikztostart) }, + statement = { + subject = \mylibTransitionCurie, + predicate = automata:relations/newState, + object = (\tikztotarget) }, + statement = { + subject = \mylibTransitionContainerCurie, + has as member, + object = \mylibTransitionCurie } } } +} +\end{codeexample} + +\emph{Using} this code is still ``as easy as before'', indeed, the code for +creating the automaton is perfectly unchanged: +% +\begin{codeexample}[width=5cm] +\tikzset { rdf engine on } +\tikz [dfa] + \graph [math nodes, grow right = 1.5cm] { + q_0 [state, initial] -> [transition = a] + q_1 [state] -> [transition = b, loop above] + q_1 -> [transition = a] + q_2 [state, final] + }; +\end{codeexample} + +Let us now have a look at the result. If the above is processed using \TeX\ and +transformed to \textsc{svg} code, the following results (reformatted and +slightly simplified): +% +\begin{codeexample}[multipage] +<g id="pgf3" prefix=" automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ "> + <!-- The automaton --> + <g about="#pgf3" property="rdf:type" resource="automata:types/automaton" /> + <g about="#pgf3" property="automata:properties/deterministic" content="yes" /> + <g about="#pgf4" property="rdf:type" resource="rdf:Seq" /> + <g about="#pgf3" property="automata:relations/hasAsStateContainer" resource="#pgf4" /> + <g about="#pgf5" property="rdf:type" resource="rdf:Seq" /> + <g about="#pgf3" property="automata:relations/hasAsTransitionContainer" resource="#pgf5" /> + <g id="pgf6" about="#pgf6" property="rdf:value"> + <!-- State $q_0$ --> + <g about="#pgf6" property="rdf:type" resource="automata:types/state" /> + <g about="#pgf4" property="rdf:_1" resource="#pgf6" /> + <g about="#pgf6" property="rdf:type" resource="automata:properties/initial" /> + <g stroke="#f00"> <!-- Red Line --> + <path id="pgf6bp" d="M 14.22636 0.0 C 14.22636 7.8571 7.8571 14.22636 0.0 14.22636 ..." /> + ... + </g> + </g> + <g id="pgf7" about="#pgf7" property="rdf:value"> + <!-- State $q_1$ --> + <g about="#pgf7" property="rdf:type" resource="automata:types/state" /> + <g about="#pgf4" property="rdf:_2" resource="#pgf7" /> + <path id="pgf7bp" d="M 56.90549 0.0 C 56.90549 7.8571 50.53622 14.22636 42.67912 14.22636 ..." /> + ... + </g> + <g id="pgf8" > + <!-- Transition from $q_0$ to $q_1$ --> + <g about="#pgf8" property="rdf:type" resource="automata:types/transition" /> + <g about="#pgf8" property="automata:properties/symbolReadFromTape" content="a" /> + <g about="#pgf8" property="automata:relations/oldState" resource="#pgf6" /> + <g about="#pgf8" property="automata:relations/newState" resource="#pgf7" /> + <g about="#pgf5" property="rdf:_1" resource="#pgf8" /> + <path id="pgf8p" d="M 14.52637 0.0 L 26.49275 0.0"/> + ... + </g> + <g id="pgf11" > + <!-- Transition loop at $q_1$ --> + <g about="#pgf11" property="rdf:type" resource="automata:types/transition" /> + <g about="#pgf11" property="automata:properties/symbolReadFromTape" content="b" /> + <g about="#pgf11" property="automata:relations/oldState" resource="#pgf7" /> + <g about="#pgf11" property="automata:relations/newState" resource="#pgf7" /> + <g about="#pgf5" property="rdf:_2" resource="#pgf11" /> + <path id="pgf11p" d="M 38.91211 14.05888 C 33.07051 35.8591 51.00113 36.72765 47.05392 16.66444"/> + ... + </g> + <g id="pgf12" about="#pgf12" property="rdf:value"> + <!-- State $q_2$ --> + <g about="#pgf12" property="rdf:type" resource="automata:types/state" /> + <g about="#pgf4" property="rdf:_3" resource="#pgf12" /> + <g about="#pgf12" property="rdf:type" resource="automata:properties/final" /> + <g stroke-width="1.80002"> <!-- Double Line --> + <path id="pgf12bp" d="M 99.58461 0.0 C 99.58461 7.8571 93.21535 14.22636 85.35825 14.22636 ..." /> + ... + </g> + </g> + <g id="pgf13" > + <!-- Transition from $q_1$ to $q_2$ --> + <g about="#pgf13" property="rdf:type" resource="automata:types/transition" /> + <g about="#pgf13" property="automata:properties/symbolReadFromTape" content="a" /> + <g about="#pgf13" property="automata:relations/oldState" resource="#pgf7" /> + <g about="#pgf13" property="automata:relations/newState" resource="#pgf12" /> + <g about="#pgf5" property="rdf:_3" resource="#pgf13" /> + <path id="pgf13p" d="M 57.20549 0.0 L 69.17188 0.0"/> + ... + </g> +</g> +\end{codeexample} + +When this code is processed by some \textsc{rdf}a tool, the following graph +will result where the blue nodes represent resources: + +\ifluatex +\else + This example can only be typeset using Lua\TeX. + \endgroup\expandafter\endinput +\fi + +{ + \newbox\myboxa + \setbox\myboxa=\hbox{\tiny {\tikz\node[circle, draw=red, fill=white] {$q_0$};}} + \newbox\myboxb + \setbox\myboxb=\hbox{\tiny {\tikz\node[circle, draw,fill=white] {$q_1$};}} + \newbox\myboxc + \setbox\myboxc=\hbox{\tiny {\tikz\node[circle, draw,fill=white, double] {$q_2$};}} + \catcode`\_=11 + \begin{tikzpicture}[font=\tiny\ttfamily, > = {Stealth [round, sep]}] + \graph [layered layout, sibling sep=1mm, sibling distance=0pt, + resource/.style = {align=left,font=\footnotesize\ttfamily, draw = blue, thick, fill=blue!20, rounded corners}, + predicate/.style = {align=right,font=\scriptsize\ttfamily,fill=black!5,rotate=90,anchor=mid east, rounded corners}, + tail anchor=south, head anchor=north] { + pgf3/\#pgf3[resource] -- /"rdf:type"[predicate] -> automaton[as={automata:\\types/\\automaton},resource]; + pgf3/\#pgf3[resource] -- /"automata:\\properties/deterministic"[predicate] -> /{"yes"}[resource]; + pgf4/\#pgf4[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource]; + pgf3/\#pgf3[resource] -- /"automata:\\relations/\\hasAsStateContainer"[predicate] -> pgf4[resource]; + pgf5/\#pgf5[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource]; + pgf3/\#pgf3[resource] -- /"atuomata:\\relations/\\hasAsTransitionContainer"[predicate] -> pgf5[resource]; + pgf6/\#pgf6[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxa},resource]; + pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource]; + pgf4/\#pgf4[resource] -- /"rdf:_1"[predicate] -> pgf6[resource]; + pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> initial/"automata:\\properties/\\initial"[resource]; + pgf7/\#pgf7[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxb},resource]; + pgf7/\#pgf7[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource]; + pgf4/\#pgf4[resource] -- /"rdf:_2"[predicate] -> pgf7[resource]; + pgf12/\#pgf12[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxc},resource]; + pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource]; + pgf4/\#pgf4[resource] -- /"rdf:_3"[predicate] -> pgf12[resource]; + pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> final/"automata:\\properties/\\final"[resource]; + pgf8/\#pgf8[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource]; + pgf8/\#pgf8[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource]; + pgf8/\#pgf8[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf6[resource]; + pgf8/\#pgf8[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource]; + pgf5/\#pgf5[resource] -- /"rdf:_1"[predicate] -> pgf8[resource]; + pgf11/\#pgf11[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource]; + pgf11/\#pgf11[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"b"}[resource]; + pgf11/\#pgf11[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource]; + pgf11/\#pgf11[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource]; + pgf5/\#pgf5[resource] -- /"rdf:_2"[predicate] -> pgf11[resource]; + pgf13/\#pgf13[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource]; + pgf13/\#pgf13[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource]; + pgf13/\#pgf13[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource]; + pgf13/\#pgf13[resource] -- /"automata:\\relations/newState"[predicate] -> pgf12[resource]; + pgf5/\#pgf5[resource] -- /"rdf:_3"[predicate] -> pgf13[resource]; + }; +\end{tikzpicture} +} + +\endgroup |