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
|
#!/usr/bin/env python
# vim: set fileencoding=UTF-8:
# Copyright 2013 Red Hat, Inc.
# Author: Jan Pokorný <jpokorny at redhat dot com>
"""Documentation vocabulary for semantic highlights of eligible properties
This vocabulary serves a purpose of annotating specific notable semantic
properties accompanied with (optional) textual details or just standalone
hints connected with annotated entity, both of which are typically reflected
in some form of documentation (hence a4doc as typical prefix).
Primarily created for custom RELAX NG schema annotations via elements and
attributes in the external namespace (see the example).
"""
__author__ = u"Jan Pokorný"
from sys import argv
#from genshi.input import XML
from ontogen.ontogen import Property, Class, Example, OntologyWithFigure, \
Ontologies
#from ontogen.ontogen import log
#log.setLevel('DEBUG')
base_uri = 'http://purl.org/net/a4doc'
#
# classes
#
# v0.2
# TODO: limit occurrences to 1 towards
class AnnotationItem(Class):
"""abstract annotation item, use only its subclasses"""
#@AnnotationItem.isSuperclassOf
class Hint(AnnotationItem):
"""hint-like annotation item
The content serves to express the hint itself in a text form.
There are various types defined to optionally carry extra semantics.
"""
#
# properties
#
# v0.1
class hint(Property):
"""plain note-like annotation
Standalone side notes for the item.
"""
range = "http://www.w3.org/2001/XMLSchema#string"
class dangerHint(hint):
"""annotates something dangerous
Explaining what is dangerous about touching this item (when used,
even if with an empty string, marks the current item as
dangerous/experimental).
"""
class deprecationHint(hint):
"""annotates something deprecated
Details about item deprecation (when used, even if with an empty
string, marks the current item as deprecated).
"""
class discretionHint(hint):
"""annotates something one should treat with care
Explaining why extra caution about touching this item (when used, even
if with an empty string, marks the current item as requiring discretion).
"""
# v0.2
@AnnotationItem.inRangeOf
class annotation(Property):
"""connects annotation item(s) to the annotated entity"""
@AnnotationItem.inDomainOf
class Type(Property):
"""defines type of the hint
Expressed as a short symbolic string; recognized values include
'danger', 'deprecation', and 'discretion'
"""
@AnnotationItem.inDomainOf
class content(Property):
"""the actual content implicitly attached to the annotation item"""
range = "http://www.w3.org/2000/01/rdf-schema#Literal" # like RDF Schema
#range = "http://www.w3.org/1999/02/22-rdf-syntax-ns#PlainLiteral"
#range = "http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral"
#
# examples
#
class ex_relaxng_0_1(Example):
"""An example snippet within RELAX NG schema.
<optional>
<attribute name="rrp_token_expired_timeout" a:defaultValue="47"
a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
<a:documentation>
This specifies the time in milliseconds to increment the problem
counter for the redundant ring protocol after not having received a
token from all rings for a particular processor.
This value will automatically be calculated from the *token* timeout
and *problem_count_threshold* but may be overridden.
</a:documentation>
<data type="unsignedInt"/>
</attribute>
</optional>
"""
pfx = 'a4doc:'
class ex_relaxng_0_2(Example):
"""An example snippet within RELAX NG schema.
<optional>
<attribute name="rrp_token_expired_timeout" a:defaultValue="47">
<a:documentation>
This specifies the time in milliseconds to increment the problem
counter for the redundant ring protocol after not having received
a token from all rings for a particular processor.
This value will automatically be calculated from the *token*
timeout and *problem_count_threshold* but may be overridden.
</a:documentation>
<a4doc:annotation>
<a4doc:hint type="danger">
It is not recommended to override this value without guidance from
the corosync community.
</a4doc:hint>
</a4doc:annotation>
<data type="unsignedInt"/>
</attribute>
</optional>
"""
pfx = 'a4doc:'
#
# ontology + versions
#
ontologies = Ontologies()
class a4doc(OntologyWithFigure):
#creator = XML('''\
# <dc:foo xmlns:dc="http://purl.org/dc/elements/1.1/"
# >Jan Pokorný</dc:foo>''')
pass
@ontologies.include
class a4doc_0_1(a4doc):
version = '0.1'
issued = '2013-02-19'
modified = '2013-03-20'
properties = [
dangerHint,
deprecationHint,
discretionHint,
hint,
]
examples = [
ex_relaxng_0_1,
]
# different strategy than v0.1, hence no inheritance
@ontologies.include
@a4doc_0_1.supersededBy
class a4doc_0_2(a4doc):
version = '0.2'
issued = '2013-03-20'
modified = '2013-03-21'
classes = [
AnnotationItem,
Hint,
]
properties = [
annotation,
content,
Type,
]
examples = [
ex_relaxng_0_2,
]
if __name__ == '__main__':
ontologies.generate_latest(**(len(argv) > 1 and {'outfile': argv[1]} or {}))
|
