Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-rdf.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Resource Description Framework Library}
12 \label{section-library-rdf}
13 \label{section-tikz-rdf}
14
15 With \todosp{why two labels? Both don't seem to be used.} certain output
16 formats (in particular, with \textsc{svg}), \tikzname\ can add \emph{semantic
17 annotations} to an output file. Consider as an example the drawing of a finite
18 automaton. In your \TeX\ code, you might have a nice description of the
19 automaton like the following:
20 %
21 \begin{codeexample}[code only]
22 \tikz[automaton] \graph { a[state, initial] ->[transition] b [state] ->[transition] c[state, final] };
23 \end{codeexample}
24 %
25 This description of the automaton carries a lot of ``semantic information''
26 like the information that the node |a| is not just some node, but actually the
27 initial state of the automaton, while |c| is a final state. Unfortunately, in
28 the output produced by \tikzname, this information is normally ``lost'': In the
29 output, |a| is only a short text, possibly with a circle drawn around it; but
30 there is no information that \emph{this} text and \emph{this} circle together
31 form the state of an automaton.
32
33 As a human (more precisely, as a computer scientist), you might ``see'' that
34 the text and the circle form a state, but most software will have a very hard
35 time retrieving this semantic information from the output. In particular, it is
36 more or less impossible to design a search engine that you can query to find,
37 say, ``all automata with three states'' in a document.
38
39 This is the point were \emph{semantic annotations} come in. These are small
40 labels or ``hints'' in the \emph{output} that tell you (and, more importantly,
41 a program) that the text and the circle together form a state of an automaton.
42 There is a standard for specifying such annotations (``resource description
43 framework annotations'', abbreviated \textsc{rdf}a) and \tikzname\ provides a
44 way of adding such annotations to an output file using the |rdf engine| key,
45 explained in a moment. Note, however, that the output format must support such
46 annotations; currently \tikzname\ only supports \textsc{svg}.
47
48
49 \subsection{Starting the RDF Engine}
50
51 \begin{tikzlibrary}{rdf}
52 You need to load this library for the keys described in the following.
53 However, even when this library is loaded, \textsc{rdf} information is only
54 written to the output inside scopes where the following key is set:
55 %
56 \begin{key}{/tikz/rdf engine on}
57 Switches ``on'' the generation of \textsc{rdf} information for the
58 current \TeX\ scope. The idea is that libraries can internally use the
59 |rdf engine| key (explained below) a lot in order to provide good
60 semantic information in the output when desired, but need not worry
61 that this will bloat output files since users have to use this key
62 explicitly to include semantic information in the output.
63 \end{key}
64 \end{tikzlibrary}
65
66 \begin{key}{/tikz/rdf engine=\meta{rdf keys}}
67 This key only has an effect when |rdf engine on| is called, otherwise the
68 argument is silently ignored. The \meta{rdf keys} get executed with the
69 path prefix |/tikz/rdf engine| at the beginning of the current scope (for a
70 node, at the beginning of the node's scope). Depending on which keys are
71 used, semantic information gets to be added to the output.
72
73 Note that you cannot simply use the keys with path prefix |/tikz/rdf engine|
74 directly since they need to be executed at very specific times during
75 \tikzname's processing of scopes. Always call those keys via this key.
76 \end{key}
77
78 The following key is useful for generally setting the prefix for a larger
79 number of annotations:
80
81 \begin{key}{/tikz/rdf engine/prefix=\meta{prefix: iri}}
82 Inside the current scope, you can use \meta{prefix}|:| inside curies
83 (compact universal resource identifier expressions, see the \textsc{rdfa}
84 specification) as an abbreviation for the \meta{iri}. (It has the same
85 effect as the |prefix| attribute in \textsc{rdf}a.) You can use this key
86 several times for a given scope.
87 %
88 \begin{codeexample}[code only]
89 \scoped [rdf engine = {
90 prefix = {rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark},
91 prefix = {automata: http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/},
92 statement = { ..., predicate = rdf:type, object = automata:state },
93 statement = { ..., predicate = rdf:type, object = automata:final },
94 }] ...
95 \end{codeexample}
96 %
97 The above could also be written more verbosely as
98 %
99 \begin{codeexample}[code only]
100 \scoped [rdf engine = {
101 statement = { ...,
102 predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type,
103 object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/state }
104 },
105 statement = { ...,
106 predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type,
107 object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/final }
108 }] ...
109 \end{codeexample}
110
111 The use of the command |\tikzrdfhashmark| is necessary since \TeX\ assigns
112 a special meaning to hash marks. The command simple expands to a ``normal''
113 hash mark for use in texts.
114 %
115 \begin{command}{\tikzrdfhashmark}
116 Expands to |#| with catcode 11.
117 \end{command}
118 \end{key}
119
120
121 \subsection{Creating Statements}
122
123 \tikzname's method of adding semantic information to an output is based on the
124 principles underlying the \emph{resource description framework} (\textsc{rdf}).
125 In this framework, all semantic information is encoded using a large graph
126 consisting of nodes and connecting directed edges, but the nodes are called
127 \emph{resources} and the edges are called \emph{statements}. A resource is
128 identified by an \textsc{iri}, an \emph{internationalized resource identifier,}
129 which basically looks like the well-known \textsc{url}s, but allows additional
130 Unicode characters. Note that these \textsc{iri}s do not need to point to
131 ``real'' webpages, they are just a way of conceptually identifying resources
132 uniquely and permanently. Similarly, each edge (statement) of the \textsc{rdf}
133 graph has such an \textsc{iri} attached to it, which identifies the ``flavour''
134 of the arc.
135
136 In a ``mathematical'' graph, each edge has a ``tail'' and a ``head'' vertex and
137 a label, but in the context of the resource description framework these notions
138 are called differently: As mentioned before, an edge is called a
139 \emph{statement}, the tail of this edge is called the \emph{subject}, the head
140 is called the \emph{object} (in the linguistic sense), and the label is called
141 the \emph{predicate}. Thus, a statement is -- quite fittingly -- a triple
142 ``subject predicate object''.
143
144 Note that in the \textsc{rdf} framework \emph{all} semantic information must be
145 encoded using statements of this fixed kind. Many semantic notions are easy to
146 store in this way such as ``Albert Einstein was a physicist'' (``Albert
147 Einstein'' is the subject, ``was'' is the predicate, ``a physicist'' is the
148 object), but other notions do not fit well like ``The automaton has states
149 $q_1$, $q_2$, $q_a$, and $q_b$'' since there are several objects in the
150 statement. Nevertheless, all information must be encoded as simple statements
151 with a single subject, a single predicate, and a single object.
152
153 You add an \textsc{rdf} statement to the output file using the following key:
154
155 \begin{key}{/tikz/rdf engine/statement=\marg{options}}
156 Each use of this key will add one \textsc{rdf} statement to the output
157 file. The \meta{options} will be executed with the path prefix
158 |/tikz/rdf engine/statements| and must use the three keys |subject|,
159 |predicate|, and |object| to specify the three components of the statement
160 (these keys can, however, be called by styles internally, so not all
161 statements will explicitly set these three keys). Note that \emph{all three
162 must always be set}, it is \emph{not} possible to setup, say, just a
163 subject for a scope and then omit the subject for statements inside the
164 scope. (However, using styles you can setup things in such a way that a
165 certain subject is used for several statements.)
166 %
167 \begin{codeexample}[code only]
168 \tikz [rdf engine = {
169 statement = {
170 subject = http://www.example.org/persons/Einstein,
171 predicate = http://www.example.org/predicates/isA,
172 object = http://www.example.org/professions/physicist
173 },
174 statement = {
175 subject = http://www.example.org/persons/Curie,
176 predicate = http://www.example.org/predicates/isA,
177 object = http://www.example.org/professions/physicist
178 }}] { ... }
179 \end{codeexample}
180
181 The statements are normally added at the beginning of the scope where the
182 |rdf engine| command is used (except when the |object| is |scope content|,
183 which is explained later). This means that when you use |prefix| inside an
184 |rdf engine| command, it will apply to all statements, regardless of the
185 order.
186
187 \begin{key}{/tikz/rdf engine/statements/subject=\meta{subject}}
188 Sets the subject of the to-be-created statement. The \meta{subject} can
189 be in one of two possible formats:
190 %
191 \begin{enumerate}
192 \item A curie (a \emph{compact universal resource identifier
193 expression,} see the \textsc{rdfa} specification for details).
194 Examples are standard \textsc{url}s like
195 |http://www.example.org|, but also text like |#my_automaton|.
196 Note that in order to include a hashmark in a curie you should
197 use the command |\tikzrdfhashmark|, which expands to a hash
198 mark (\TeX\ treats hash marks in a special way, which is why
199 this command is used here).
200 \item When the \meta{subject} starts with an opening parenthesis,
201 that is, with ``|(|'', the \meta{subject} must have the form
202 |(|\meta{node or scope name}|)|. In this case, the \meta{node
203 or scope name} must be the name of an already existing node
204 (the current node or scope is considered as ``existing'' here).
205 Then, the curie |#|\meta{id} is used as subject, where the
206 \meta{id} is a unique internal identifier for the node.
207
208 As an example, suppose you wish to specify that a node has some
209 other node as child, you could write the following:
210 %
211 \begin{codeexample}[code only]
212 \tikz [ rdf engine = { prefix = { rels: http://www.example.org/relations/} } ] {
213 \node (fritz) { Fritz };
214 \node (heinz) at (2,0) { Heinz };
215 \draw [->] (fritz) -- (heinz)
216 [rdf engine = {
217 statement = {
218 subject = (fritz),
219 predicate = rels:isSonOf,
220 object = (heinz)
221 } } ];
222 }
223 \end{codeexample}
224 \end{enumerate}
225 %
226 You can use a macro as \meta{subject}, it will be expanded before the
227 above syntax check is done.
228
229 If you use the |subject| key several times inside a single |statement|
230 command, (only) the last subject is used.
231 \end{key}
232
233 \begin{key}{/tikz/rdf engine/statements/predicate=\meta{predicate}}
234 Sets the predicate for the statement. The syntax is exactly the same as
235 for the subject. Unlike for subjects, you can use the predicate key
236 several times inside a single statement and the uses will
237 ``accumulate'' and several statements are created, namely one statement
238 for each use of |predicate| for the subject and object specified inside
239 the use of |statement|. This behavior is not very systematic (it
240 violates the rule ``one statement per |statement|'') and you should
241 normally use the |statement| once for each use of the |predicate|
242 key. However, in conjunction with the object |scope content| it is
243 necessary to allow this behavior.
244 \end{key}
245
246 \begin{key}{/tikz/rdf engine/statements/object=\meta{object}}
247 Sets the object for the statement. The syntax allowed for the
248 \meta{object} is as follows:
249 %
250 \begin{enumerate}
251 \item As for |subject| and |predicate| you can use a curie here.
252 This is the default unless one of the following special cases
253 is used:
254 \item As for |subject| and |predicate|, you can use the syntax
255 |(|\meta{name of node or scope}|)| to create and use a curie
256 for the node or scope.
257 \item If the \meta{object} starts with |"| and is of the form
258 |"|\meta{literals}|"|, the object of the
259 statement is not a curie (not a normal ``resource'') but the
260 string of \meta{literals} given.
261 \item If the \meta{object} is the text ``|scope content|'', the
262 object of the statement is actually the whole contents of the
263 scope to which this statement is attached.
264 \item Finally if the \meta{object} is of the form
265 |"|\meta{literals}|" and scope content|, the contents of the
266 scope is ``normally'' the
267 object, but this gets ``overruled'' by the \meta{literals}.
268 Formally, this means that the object is the \meta{literals},
269 but the intended semantics is that the object is the scope
270 content, only for further processing it should be considered to
271 be \meta{literals}. A typical example is the case where the
272 scope content is, say, the text ``January 1st, 2000'' but the
273 \meta{literals} are set to |2000-01-01|, which is easier for
274 software to process:
275 %
276 \begin{codeexample}[code only]
277 \node [rdf engine = {
278 statement = {
279 subject = ...,
280 predicate = dc:Date,
281 object = "2000-01-01" and scope content
282 } } ] { January 1st, 2000 };
283 \end{codeexample}
284 \end{enumerate}
285 %
286 For the last two cases, only one statement may be given per scope that
287 has the |scope content| as its object; if more than one is given, the
288 last one wins. This is the reason why several uses of |predicate| are
289 allowed in a |statement|.
290 \end{key}
291
292 \begin{key}{/tikz/rdf engine/statements/has type=\meta{type}}
293 This style is a shorthand for |predicate=rdf:type| and
294 |object=|\meta{type}.
295 \end{key}
296 \end{key}
297
298
299 \subsection{Creating Resources}
300
301 In \textsc{rdf} statements, when you can use the name of a \tikzname\ scope or
302 node surrounded by parenthesis, a curie is inserted into the output that
303 references this scope or node. While this makes it easy to describe
304 relationships between existing nodes, in library code (\textsc{rdf} generation
305 code added to library styles and gets executed as a ``byproduct'') there are
306 two situations where this method is insufficient:
307 %
308 \begin{enumerate}
309 \item You may sometimes wish to create additional resources in the
310 \textsc{rdf} graph that are not represented by any concrete node or
311 scope in the \tikzname\ picture. For instance, a finite automaton has a
312 set of states and a set of transitions, but neither of these
313 ``containers'' has any concrete representation in the output. One
314 could, of course, create ``dummy scopes'' for this purpose, but this is
315 rather hard to do inside styles of a library.
316 \item You may not know the name of the current scope in library code. For
317 instance, a style like |state|, which can be added to a node to
318 indicate that the node is supposed to be a state in a finite automaton,
319 might contain something like the following code:
320 %
321 \begin{codeexample}[code only]
322 state/.style = {
323 draw, circle, minimum size = ...,
324 rdf engine = {
325 subject = ???,
326 predicate = rdf:type,
327 object = automata:state
328 }
329 }
330 \end{codeexample}
331 %
332 The problem is, of course, what should be passed to the |subject|. We
333 cannot even write something like |(\tikz@fig@name)| since no name may
334 have been set for the state.
335 \end{enumerate}
336
337 Each of the above problems is solved by a special keys:
338
339 \begin{key}{/tikz/rdf engine/get new resource curie=\meta{macro}}
340 The \meta{macro} will be set to a new unique curie that can be used
341 anywhere where a curie is allowed. Here is an example how we can add a
342 state and a transition container to an automaton, both of which have no
343 corresponding scope in \tikzname.
344 %
345 \begin{codeexample}[code only]
346 \tikz [ name = my automaton,
347 rdf engine = {
348 get new resource curie = \statecurie,
349 get new resource curie = \transitioncurie,
350 statement = {
351 subject = (my automaton),
352 predicate = automata:hasStateSet,
353 object = \statecurie },
354 statement = {
355 subject = \statecurie,
356 hat type = automata:stateSet },
357 statement = {
358 subject = (my automaton),
359 predicate = automata:hasTransitionSet,
360 object = \transitioncurie },
361 statement = {
362 subject = \transitioncurie,
363 hat type = automata:transitionSet } } ] { ... }
364 \end{codeexample}
365 %
366 The \meta{macro} will be valid for the whole scope.
367 \end{key}
368
369 \begin{key}{/tikz/rdf engine/get scope curie=\meta{macro}}
370 The \meta{macro} will be set to a unique curie that represents the scope or
371 node. If the scope is named (using the |name| key or the special
372 parenthesis syntax for nodes) and this name is later referenced in another
373 statement, the same curie will be generated. Note how in the following code
374 no name is given for the automaton, which means that the whole \textsc{rdf}
375 code could be moved inside a style like |finite automaton| or something
376 similar.
377 %
378 \begin{codeexample}[code only]
379 \tikz [ rdf engine = {
380 get new resource curie = \statecurie,
381 get new resource curie = \transitioncurie,
382 get scope curie = \automatoncurie,
383 statement = {
384 subject = \automatoncurie,
385 predicate = automata:hasStateSet,
386 object = \statecurie },
387 statement = {
388 subject = \statecurie,
389 hat type = automata:stateSet },
390 statement = {
391 subject = \automatoncurie,
392 predicate = automata:hasTransitionSet,
393 object = \transitioncurie },
394 statement = {
395 subject = \transitioncurie,
396 hat type = automata:transitionSet } } ] { ... }
397 \end{codeexample}
398 %
399 The \meta{macro} will be valid for the whole scope.
400 \end{key}
401
402 The following key builds on the above keys:
403 %
404 \begin{key}{/tikz/rdf engine/scope is new context}
405 This key executes |get scope curie=\tikzrdfcontext|, thereby setting the
406 macro |\tikzrdfcontext| to the current scope. The idea is the key is used
407 with ``major resources'' and that keys can use this macro as the |subject|
408 of statements if no subject is given explicitly. For instance, a |title|
409 key might be defined as follows:
410 %
411 \begin{codeexample}[code only]
412 title/.style = {
413 rdf engine = { statement = {
414 subject = \tikzrdfcontext,
415 predicate = dc:Title,
416 object = "#1"
417 } } }
418 \end{codeexample}
419 %
420 \end{key}
421
422
423 \subsection{Creating Containers}
424
425 A \emph{container} is a resource that represents a set or a sequence of
426 elements. In \textsc{rdf} this is modeled by having a statement say that the
427 type of the resource is something special like |rdf:Seq| and then for each
428 member resource of the container add a statement saying that the container has
429 as its $i$th member the member resource. Here is an example of a container
430 with two elements:
431 %
432 \begin{codeexample}[code only]
433 \tikz {
434 \node (safe) { Safe }
435 child { node (coins) {Coins} }
436 child { node (gold) {Gold} };
437
438 \scoped [rdf engine = {
439 statement = {
440 subject = (safe),
441 has type = rdf:Seq
442 },
443 statement = {
444 subject = (safe),
445 predicate = rdf:_1,
446 object = (coins)
447 },
448 statement = {
449 subject = (safe),
450 predicate = rdf:_2,
451 object = (gold)
452 } }];
453 }
454 \end{codeexample}
455
456 However, the above code is error-prone and does not integrate well with styles
457 and libraries. For this reason, \tikzname\ offers some styles that may help in
458 creating containers:
459
460 \begin{key}{/tikz/rdf engine/statements/is a container}
461 Add this key to a statement in order to tell \tikzname\ that it should
462 setup a special counter for the subject of the statement that keeps track
463 of the container's children.
464 \end{key}
465
466 \begin{key}{/tikz/rdf engine/statements/has as member}
467 This key may only be added to statements whose subject was previously used
468 as a subject in a statement containing the |is a container| key. In this
469 case, the internal counter will be increased and the predicate will be set
470 to |rdf:_|\meta{count}. This means that we can write the above code as:
471 %
472 \begin{codeexample}[code only]
473 \tikz { ...
474
475 \scoped [rdf engine = {
476 statement = {
477 subject = (safe),
478 has type = rdf:Seq,
479 is a container,
480 },
481 statement = {
482 subject = (safe),
483 has as member,
484 object = (coins)
485 },
486 statement = {
487 subject = (safe),
488 has as member,
489 object = (gold)
490 } }];
491 }
492 \end{codeexample}
493 %
494 \end{key}
495
496 \begin{key}{/tikz/rdf engine/statements/is a sequence}
497 This is a shorthand for |predicate = rdf:Seq, is a container|. In the above
498 example we could say:
499 %
500 \begin{codeexample}[code only]
501 \tikz { ...
502
503 \scoped [rdf engine = {
504 statement = {
505 subject = (safe),
506 is a sequence
507 },
508 ... } ]; }
509 \end{codeexample}
510 %
511 \end{key}
512
513 \begin{key}{/tikz/rdf engine/statements/is a bag}
514 This is a shorthand for |predicate = rdf:Bag, is a container|.
515 \end{key}
516
517 \begin{key}{/tikz/rdf engine/statements/is an alternative}
518 This is a shorthand for |predicate = rdf:Alt, is a container|.
519 \end{key}
520
521
522 \subsection{Creating Semantic Information Inside Styles and Libraries}
523
524 \begingroup
525
526 The \textsc{rdf} library was designed in such a way that normal document
527 authors do not need to use the keys of the library explicitly, except possibly
528 for saying |rdf engine on| somewhere at the beginning. Instead, library authors
529 should include the necessary commands to generate \textsc{rdf} information that
530 is then automatically included in the output. Furthermore, if the author does
531 not ``switch on'' the generation of \textsc{rdf} information, all uses of
532 |rdf engine| will simply be ignored silently and neither the speed of
533 compilation nor the size of the generated files is impacted.
534
535
536 \subsubsection{An Example Library for Drawing Finite Automata}
537
538 In the following, we have a look at how a library might be augmented by
539 \textsc{rdf} generation keys. The library we augment is a (fictitious) library
540 for drawing finite automata. The library offers the following styles:
541 %
542 \begin{enumerate}
543 \item |dfa| and |nfa| can be added to a scope to indicate that the scope
544 contains a deterministic or a nondeterministic finite automaton.
545 \item |state| can be added to a node to indicate that the node is a state
546 in the automaton.
547 \item |initial| and |final| are used to indicate that a state is an initial
548 or final state, which should be rendered in a special way.
549 \item |transition| can be added to an edge to indicate that there is a
550 transition in the automaton from the first state to the second state.
551 The style takes a parameter which is the symbol read by the automaton.
552 \end{enumerate}
553
554 Here are some possible definitions of these keys that do not (yet) generate
555 \textsc{rdf} information:
556 %
557 \begin{codeexample}[code only, setup code]
558 \tikzset {
559 dfa/.style = { semithick, > = To [sep] },
560 nfa/.style = { semithick, > = To [sep] },
561 state/.style = { circle, draw, minimum size = 1cm },
562 final/.style = { double },
563 initial/.style = { draw = red }, % to keep things simple
564 transition/.style = { edge label = {$#1$} } }
565 \end{codeexample}
566
567 The library could be used as follows:
568 %
569 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{graphs,rdf}}]
570 \tikz [dfa]
571 \graph [math nodes, grow right = 1.5cm] {
572 q_0 [state, initial] -> [transition = a]
573 q_1 [state] -> [transition = b, loop above]
574 q_1 -> [transition = a]
575 q_2 [state, final]
576 };
577 \end{codeexample}
578
579
580 \subsubsection{Adding Semantic Information About the Automata as a Whole}
581
582 Let us change the different keys so that they add \textsc{rdf} information to
583 the output. For this, we first need an ontology that defines notions like
584 ``state'' or ``deterministic finite automaton''. For the purposes of this
585 example, we just assume that such an ontology exists at
586 |http://www.tcs.uni-luebeck.de/ontologies/automata/|. The new definition of the
587 |dfa| key might start as follows (we will extend these later on):
588 %
589 \begin{codeexample}[code only]
590 dfa/.style = {
591 semithick, > = To [sep], % as before,
592 rdf engine = {
593 %
594 % Setup prefix:
595 prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
596 %
597 % Get the curie of the automaton and store it in a macro for later use:
598 get scope curie = \mylibAutomatonCurie,
599 %
600 % Make a statement that the resource is, indeed, an automaton:
601 statement = {
602 subject = \mylibAutomatonCurie,
603 has type = automata:types/automaton },
604 %
605 % Make a statement that the automaton is deterministic:
606 statement = {
607 subject = \mylibAutomatonCurie,
608 predicate = automata:properties/deterministic,
609 object = "yes" } } }
610 \end{codeexample}
611
612 The definition of the style |nfa| would be exactly the same as for |dfa|,
613 except, of course, that the last statement would have |"no"| as object. Note
614 that the original styles |dfa| and |nfa| has identical definitions since,
615 indeed, there is no ``visual'' difference between the two. In contrast, the
616 \textsc{rdf} information stores this information in the output.
617
618
619 \subsubsection{Adding Semantic Information About the States}
620
621 We next augment the styles for creating states and marking them as final or
622 initial. We could do the following (note that we do not setup the prefix since
623 this has been done by the surrounding |dfa| or |nfa| key):
624 %
625 \begin{codeexample}[code only]
626 state/.style = {
627 circle, draw, minimum size = 1cm, % as before,
628 rdf engine = {
629 get scope curie = \mylibStateCurie,
630 statement = {
631 subject = \mylibStateCurie,
632 has type = automata:types/state },
633 statement = {
634 subject = \mylibStateCurie,
635 predicate = rdf:value,
636 object = scope content } } }
637 \end{codeexample}
638
639 The first statement tells us that the circle with its contents is a state (and
640 not just ``any'' fancy circle). The second statement tells us that the
641 ``value'' of this state is the content. One might argue that, instead, only the
642 number itself (like ``$q_0$'' or perhaps only ``$0$'') should be the ``value''
643 or, perhaps, a different property should actually be used (like
644 |automata:stateNumber| or something like that). However, these are questions of
645 ontological modeling, not of the use of the \textsc{rdf} engine.
646
647 What is definitely missing from the above definition is a link between the
648 automaton resource and the state resource. Note that the state's rendering code
649 will be inside the scope of the automaton, so, in a sense, the state is
650 ``inside'' the automaton in the output. However, the nesting of scopes is
651 \emph{not} part of the \textsc{rdf} graph; we must make these relationships
652 explicit using statements. One way to achieve this would be to add the
653 following to the |state| style:
654 %
655 \begin{codeexample}[code only]
656 statement = {
657 subject = \mylibAutomatonCurie,
658 predicate = automata:hasAsAState,
659 object = \mylibStateCurie }
660 \end{codeexample}
661
662 Note that we can access the macro |\mylibAutomatonCurie| here since this will
663 have been setup by the surrounding |dfa| or |nfa| key. While the above is
664 possible and legitimate, we will see a better solution using containers in a
665 moment (``better'' in the sense that the ontological model is easier to process
666 by software).
667
668 The two styles |final| and |initial| are easy to augment:
669 %
670 \begin{codeexample}[code only]
671 final/.style = {
672 double, % as before,
673 rdf engine = {
674 get scope curie = \mylibStateCurie,
675 statement = {
676 subject = \mylibStateCurie,
677 has type = automata:properties/final } } }
678 \end{codeexample}
679
680 Note that when we write |node [state, final] ...| the state now has two types:
681 It has type |automata:types/state| and also |automata:properties/final|. This
682 is perfectly legitimate. Also note that I added |get scope curie| to the above
683 definition, which may seem superfluous since the |state| style already executes
684 this key to get a curie for the state resource. However, users should be free
685 to write |node [final, state] ...| and, now, the |final| key will be executed
686 first.
687
688 The style for |initial| is the same as for |final| only with a different type.
689
690
691 \subsubsection{Adding Semantic Information About the Transitions}
692
693 A transition is, essentially, a labeled edge from a state to another state. It
694 may seem tempting to model them as a statement with the first state as its
695 subject and the second state as the object and the transition's symbol as the
696 label (turned into a curie in some appropriate way). However, closer inspection
697 shows that this is not a good way of modeling transitions: In essence, it is
698 just coincidence that the \textsc{rdf} graph happens to be a directed graph
699 and, at the same time, the thing we describe by it (the automaton) can also be
700 viewed as a directed graph. If, for instance, we consider alternating automata
701 where a transition can involve more than two states, the simple model breaks
702 down.
703
704 The ``right'' way of modeling a transition is to treat the transition as a
705 resource of its own and then make statements like ``the transition has this
706 state as its old state''. This turns out to be relatively easy to achieve:
707 %
708 \begin{codeexample}[code only]
709 transition/.style = {
710 edge label = {#1}, % as before,
711 rdf engine = {
712 get scope curie = \mylibTransitionCurie,
713 statement = {
714 subject = \mylibTransitionCurie,
715 has type = automata:types/transition },
716 statement = {
717 subject = \mylibTransitionCurie,
718 predicate = automata:properties/symbolReadFromTape,
719 object = "#1" },
720 statement = {
721 subject = \mylibTransitionCurie,
722 predicate = automata:relations/oldState,
723 object = (\tikztostart) },
724 statement = {
725 subject = \mylibTransitionCurie,
726 predicate = automata:relations/newState,
727 object = (\tikztotarget) } } }
728 \end{codeexample}
729
730
731 \subsubsection{Using Containers}
732
733 As a last step we wish to organize the states and transitions using containers.
734 As explained earlier, we can easily add statements linking our automaton to the
735 states and to the transitions, but the \textsc{rdf} standard has standard way
736 of specifying that a set of resources form a logical sequence: containers.
737
738 In case automata contained \emph{only} states, we could setup the automaton
739 itself to be the container and the states to be its elements. However, the
740 automaton has states and transitions and in this example I would like to keep
741 these in separate containers. Thus, we must create two containers and then make
742 statements that the automaton contains these two containers. Since these
743 containers do not have any accompanying visual representation, we use the
744 |get new resource curie| key to create new resources that are purely for
745 descriptive purposes inside the \textsc{rdf} graph:
746 %
747 \begin{codeexample}[code only]
748 dfa/.style = {
749 semithick, > = To [sep], % as before,
750 rdf engine = {
751 prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
752 get scope curie = \mylibAutomatonCurie,
753 statement = { ... as before that automaton has type automata:types/automaton ... },
754 statement = { ... as before that automaton is deterministic ... },
755 get new resource curie = \mylibStateContainerCurie,
756 statement = {
757 subject = \mylibStateContainerCurie,
758 is a sequence },
759 statement = {
760 subject = \mylibAutomatonCurie,
761 predicate = automata:relations/hasAsStateContainer,
762 object = \mylibStateContainerCurie },
763 get new resource curie = \mylibTransitionContainerCurie,
764 statement = {
765 subject = \mylibTransitionContainerCurie,
766 is a sequence },
767 statement = {
768 subject = \mylibAutomatonCurie,
769 predicate = automata:relations/hasAsTransitionContainer,
770 object = \mylibTransitionContainerCurie } } }
771 \end{codeexample}
772
773 We can now modify the |state| style as follows:
774 %
775 \begin{codeexample}[code only]
776 state/.style = {
777 circle, draw, minimum size = 1cm, % as before,
778 rdf engine = {
779 get scope curie = \mylibStateCurie,
780 statement = { ... as before ... },
781 statement = { ... as before ... },
782 statement = {
783 subject = \mylibStateContainerCurie,
784 has as member,
785 object = \mylibStateCurie } } }
786 \end{codeexample}
787
788 The modification for the |transition| style is similar:
789 %
790 \begin{codeexample}[code only]
791 transition/.style = {
792 edge label = {#1}, % as before,
793 rdf engine = {
794 get scope curie = \mylibTransitionCurie,
795 statement = { ... as before ... },
796 statement = { ... as before ... },
797 statement = { ... as before ... },
798 statement = { ... as before ... },
799 statement = {
800 subject = \mylibTransitionContainerCurie,
801 has as member,
802 object = \mylibTransitionCurie } } }
803 \end{codeexample}
804
805
806 \subsubsection{The Resulting RDF Graph}
807
808 Putting it all together, we now get the following library code:
809 %
810 \begin{codeexample}[setup code, multipage]
811 \tikzset {
812 dfa/.style = {
813 semithick, > = To [sep], % as before,
814 rdf engine = {
815 prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
816 get scope curie = \mylibAutomatonCurie,
817 statement = {
818 subject = \mylibAutomatonCurie,
819 has type = automata:types/automaton },
820 statement = {
821 subject = \mylibAutomatonCurie,
822 predicate = automata:properties/deterministic,
823 object = "yes" },
824 get new resource curie = \mylibStateContainerCurie,
825 statement = {
826 subject = \mylibStateContainerCurie,
827 is a sequence },
828 statement = {
829 subject = \mylibAutomatonCurie,
830 predicate = automata:relations/hasAsStateContainer,
831 object = \mylibStateContainerCurie },
832 get new resource curie = \mylibTransitionContainerCurie,
833 statement = {
834 subject = \mylibTransitionContainerCurie,
835 is a sequence },
836 statement = {
837 subject = \mylibAutomatonCurie,
838 predicate = automata:relations/hasAsTransitionContainer,
839 object = \mylibTransitionContainerCurie } } },
840 state/.style = {
841 circle, draw, minimum size = 1cm, % as before,
842 rdf engine = {
843 get scope curie = \mylibStateCurie,
844 statement = {
845 subject = \mylibStateCurie,
846 has type = automata:types/state },
847 statement = {
848 subject = \mylibStateCurie,
849 predicate = rdf:value,
850 object = scope content },
851 statement = {
852 subject = \mylibStateContainerCurie,
853 has as member,
854 object = \mylibStateCurie } } },
855 initial/.style = {
856 draw = red, % as before,
857 rdf engine = {
858 get scope curie = \mylibStateCurie,
859 statement = {
860 subject = \mylibStateCurie,
861 has type = automata:properties/initial } } },
862 final/.style = {
863 double, % as before,
864 rdf engine = {
865 get scope curie = \mylibStateCurie,
866 statement = {
867 subject = \mylibStateCurie,
868 has type = automata:properties/final } } },
869 transition/.style = {
870 edge label = {$#1$}, % as before,
871 rdf engine = {
872 get scope curie = \mylibTransitionCurie,
873 statement = {
874 subject = \mylibTransitionCurie,
875 has type = automata:types/transition },
876 statement = {
877 subject = \mylibTransitionCurie,
878 predicate = automata:properties/symbolReadFromTape,
879 object = "#1" },
880 statement = {
881 subject = \mylibTransitionCurie,
882 predicate = automata:relations/oldState,
883 object = (\tikztostart) },
884 statement = {
885 subject = \mylibTransitionCurie,
886 predicate = automata:relations/newState,
887 object = (\tikztotarget) },
888 statement = {
889 subject = \mylibTransitionContainerCurie,
890 has as member,
891 object = \mylibTransitionCurie } } }
892 }
893 \end{codeexample}
894
895 \emph{Using} this code is still ``as easy as before'', indeed, the code for
896 creating the automaton is perfectly unchanged:
897 %
898 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{graphs,rdf}}]
899 \tikzset { rdf engine on }
900 \tikz [dfa]
901 \graph [math nodes, grow right = 1.5cm] {
902 q_0 [state, initial] -> [transition = a]
903 q_1 [state] -> [transition = b, loop above]
904 q_1 -> [transition = a]
905 q_2 [state, final]
906 };
907 \end{codeexample}
908
909 Let us now have a look at the result. If the above is processed using \TeX\ and
910 transformed to \textsc{svg} code, the following results (reformatted and
911 slightly simplified):
912 %
913 \begin{codeexample}[multipage]
914 <g id="pgf3" prefix=" automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ ">
915 <!-- The automaton -->
916 <g about="#pgf3" property="rdf:type" resource="automata:types/automaton" />
917 <g about="#pgf3" property="automata:properties/deterministic" content="yes" />
918 <g about="#pgf4" property="rdf:type" resource="rdf:Seq" />
919 <g about="#pgf3" property="automata:relations/hasAsStateContainer" resource="#pgf4" />
920 <g about="#pgf5" property="rdf:type" resource="rdf:Seq" />
921 <g about="#pgf3" property="automata:relations/hasAsTransitionContainer" resource="#pgf5" />
922 <g id="pgf6" about="#pgf6" property="rdf:value">
923 <!-- State $q_0$ -->
924 <g about="#pgf6" property="rdf:type" resource="automata:types/state" />
925 <g about="#pgf4" property="rdf:_1" resource="#pgf6" />
926 <g about="#pgf6" property="rdf:type" resource="automata:properties/initial" />
927 <g stroke="#f00"> <!-- Red Line -->
928 <path id="pgf6bp" d="M 14.22636 0.0 C 14.22636 7.8571 7.8571 14.22636 0.0 14.22636 ..." />
929 ...
930 </g>
931 </g>
932 <g id="pgf7" about="#pgf7" property="rdf:value">
933 <!-- State $q_1$ -->
934 <g about="#pgf7" property="rdf:type" resource="automata:types/state" />
935 <g about="#pgf4" property="rdf:_2" resource="#pgf7" />
936 <path id="pgf7bp" d="M 56.90549 0.0 C 56.90549 7.8571 50.53622 14.22636 42.67912 14.22636 ..." />
937 ...
938 </g>
939 <g id="pgf8" >
940 <!-- Transition from $q_0$ to $q_1$ -->
941 <g about="#pgf8" property="rdf:type" resource="automata:types/transition" />
942 <g about="#pgf8" property="automata:properties/symbolReadFromTape" content="a" />
943 <g about="#pgf8" property="automata:relations/oldState" resource="#pgf6" />
944 <g about="#pgf8" property="automata:relations/newState" resource="#pgf7" />
945 <g about="#pgf5" property="rdf:_1" resource="#pgf8" />
946 <path id="pgf8p" d="M 14.52637 0.0 L 26.49275 0.0"/>
947 ...
948 </g>
949 <g id="pgf11" >
950 <!-- Transition loop at $q_1$ -->
951 <g about="#pgf11" property="rdf:type" resource="automata:types/transition" />
952 <g about="#pgf11" property="automata:properties/symbolReadFromTape" content="b" />
953 <g about="#pgf11" property="automata:relations/oldState" resource="#pgf7" />
954 <g about="#pgf11" property="automata:relations/newState" resource="#pgf7" />
955 <g about="#pgf5" property="rdf:_2" resource="#pgf11" />
956 <path id="pgf11p" d="M 38.91211 14.05888 C 33.07051 35.8591 51.00113 36.72765 47.05392 16.66444"/>
957 ...
958 </g>
959 <g id="pgf12" about="#pgf12" property="rdf:value">
960 <!-- State $q_2$ -->
961 <g about="#pgf12" property="rdf:type" resource="automata:types/state" />
962 <g about="#pgf4" property="rdf:_3" resource="#pgf12" />
963 <g about="#pgf12" property="rdf:type" resource="automata:properties/final" />
964 <g stroke-width="1.80002"> <!-- Double Line -->
965 <path id="pgf12bp" d="M 99.58461 0.0 C 99.58461 7.8571 93.21535 14.22636 85.35825 14.22636 ..." />
966 ...
967 </g>
968 </g>
969 <g id="pgf13" >
970 <!-- Transition from $q_1$ to $q_2$ -->
971 <g about="#pgf13" property="rdf:type" resource="automata:types/transition" />
972 <g about="#pgf13" property="automata:properties/symbolReadFromTape" content="a" />
973 <g about="#pgf13" property="automata:relations/oldState" resource="#pgf7" />
974 <g about="#pgf13" property="automata:relations/newState" resource="#pgf12" />
975 <g about="#pgf5" property="rdf:_3" resource="#pgf13" />
976 <path id="pgf13p" d="M 57.20549 0.0 L 69.17188 0.0"/>
977 ...
978 </g>
979 </g>
980 \end{codeexample}
981
982 When this code is processed by some \textsc{rdf}a tool, the following graph
983 will result where the blue nodes represent resources:
984
985 \ifluatex
986 \else
987 This example can only be typeset using Lua\TeX.
988 \endgroup\expandafter\endinput
989 \fi
990
991 {
992 \newbox\myboxa
993 \setbox\myboxa=\hbox{\tiny {\tikz\node[circle, draw=red, fill=white] {$q_0$};}}
994 \newbox\myboxb
995 \setbox\myboxb=\hbox{\tiny {\tikz\node[circle, draw,fill=white] {$q_1$};}}
996 \newbox\myboxc
997 \setbox\myboxc=\hbox{\tiny {\tikz\node[circle, draw,fill=white, double] {$q_2$};}}
998 \catcode`\_=11
999 \begin{tikzpicture}[font=\tiny\ttfamily, > = {Stealth [round, sep]}]
1000 \graph [layered layout, sibling sep=1mm, sibling distance=0pt,
1001 resource/.style = {align=left,font=\footnotesize\ttfamily, draw = blue, thick, fill=blue!20, rounded corners},
1002 predicate/.style = {align=right,font=\scriptsize\ttfamily,fill=black!5,rotate=90,anchor=mid east, rounded corners},
1003 tail anchor=south, head anchor=north] {
1004 pgf3/\#pgf3[resource] -- /"rdf:type"[predicate] -> automaton[as={automata:\\types/\\automaton},resource];
1005 pgf3/\#pgf3[resource] -- /"automata:\\properties/deterministic"[predicate] -> /{"yes"}[resource];
1006 pgf4/\#pgf4[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource];
1007 pgf3/\#pgf3[resource] -- /"automata:\\relations/\\hasAsStateContainer"[predicate] -> pgf4[resource];
1008 pgf5/\#pgf5[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource];
1009 pgf3/\#pgf3[resource] -- /"atuomata:\\relations/\\hasAsTransitionContainer"[predicate] -> pgf5[resource];
1010 pgf6/\#pgf6[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxa},resource];
1011 pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
1012 pgf4/\#pgf4[resource] -- /"rdf:_1"[predicate] -> pgf6[resource];
1013 pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> initial/"automata:\\properties/\\initial"[resource];
1014 pgf7/\#pgf7[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxb},resource];
1015 pgf7/\#pgf7[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
1016 pgf4/\#pgf4[resource] -- /"rdf:_2"[predicate] -> pgf7[resource];
1017 pgf12/\#pgf12[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxc},resource];
1018 pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
1019 pgf4/\#pgf4[resource] -- /"rdf:_3"[predicate] -> pgf12[resource];
1020 pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> final/"automata:\\properties/\\final"[resource];
1021 pgf8/\#pgf8[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
1022 pgf8/\#pgf8[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource];
1023 pgf8/\#pgf8[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf6[resource];
1024 pgf8/\#pgf8[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource];
1025 pgf5/\#pgf5[resource] -- /"rdf:_1"[predicate] -> pgf8[resource];
1026 pgf11/\#pgf11[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
1027 pgf11/\#pgf11[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"b"}[resource];
1028 pgf11/\#pgf11[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource];
1029 pgf11/\#pgf11[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource];
1030 pgf5/\#pgf5[resource] -- /"rdf:_2"[predicate] -> pgf11[resource];
1031 pgf13/\#pgf13[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
1032 pgf13/\#pgf13[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource];
1033 pgf13/\#pgf13[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource];
1034 pgf13/\#pgf13[resource] -- /"automata:\\relations/newState"[predicate] -> pgf12[resource];
1035 pgf5/\#pgf5[resource] -- /"rdf:_3"[predicate] -> pgf13[resource];
1036 };
1037 \end{tikzpicture}
1038 }
1039
1040 \endgroup