summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-rdf.tex
blob: 1e9debff4361802aaf7eddf9b6ba9271363a734f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
% Copyright 2019 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,preamble={\usetikzlibrary{graphs,rdf}}]
\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,preamble={\usetikzlibrary{graphs,rdf}}]
\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