metanorma-standoc 2.9.5 → 2.9.7

Sign up to get free protection for your applications and to get access to all the features.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/lib/isodoc/html/htmlstyle.css +4 -1
  3. data/lib/metanorma/standoc/base.rb +8 -8
  4. data/lib/metanorma/standoc/basicdoc.rng +909 -464
  5. data/lib/metanorma/standoc/biblio-standoc.rng +87 -20
  6. data/lib/metanorma/standoc/biblio.rng +884 -325
  7. data/lib/metanorma/standoc/blocks.rb +1 -1
  8. data/lib/metanorma/standoc/cleanup.rb +4 -2
  9. data/lib/metanorma/standoc/cleanup_bibitem.rb +18 -6
  10. data/lib/metanorma/standoc/cleanup_boilerplate.rb +9 -93
  11. data/lib/metanorma/standoc/cleanup_inline.rb +1 -1
  12. data/lib/metanorma/standoc/cleanup_maths.rb +51 -101
  13. data/lib/metanorma/standoc/cleanup_mathvariant.rb +88 -0
  14. data/lib/metanorma/standoc/cleanup_terms.rb +4 -1
  15. data/lib/metanorma/standoc/cleanup_terms_boilerplate.rb +106 -0
  16. data/lib/metanorma/standoc/cleanup_terms_designations.rb +1 -2
  17. data/lib/metanorma/standoc/cleanup_text.rb +11 -4
  18. data/lib/metanorma/standoc/cleanup_xref.rb +1 -1
  19. data/lib/metanorma/standoc/converter.rb +2 -0
  20. data/lib/metanorma/standoc/datamodel/plantuml_renderer.rb +1 -1
  21. data/lib/metanorma/standoc/init.rb +23 -4
  22. data/lib/metanorma/standoc/inline.rb +27 -14
  23. data/lib/metanorma/standoc/isodoc.rng +1031 -912
  24. data/lib/metanorma/standoc/localbib.rb +1 -1
  25. data/lib/metanorma/standoc/macros.rb +1 -1
  26. data/lib/metanorma/standoc/macros_inline.rb +11 -9
  27. data/lib/metanorma/standoc/macros_plantuml.rb +1 -1
  28. data/lib/metanorma/standoc/ref.rb +1 -1
  29. data/lib/metanorma/standoc/ref_queue.rb +1 -1
  30. data/lib/metanorma/standoc/ref_utility.rb +7 -6
  31. data/lib/metanorma/standoc/reqt.rng +94 -72
  32. data/lib/metanorma/standoc/section.rb +2 -2
  33. data/lib/metanorma/standoc/term_lookup_cleanup.rb +2 -2
  34. data/lib/metanorma/standoc/utils.rb +4 -2
  35. data/lib/metanorma/standoc/version.rb +1 -1
  36. metadata +4 -2
@@ -24,44 +24,62 @@
24
24
  Somewhat dumbed down for XSD regex:
25
25
  -->
26
26
  <define name="ISO8601DateTime">
27
+ <a:documentation>Date/Time conforming with ISO 8601</a:documentation>
27
28
  <data type="string">
28
29
  <param name="pattern">([\+\-]?\d{4})((-?)((0[1-9]|1[0-2])((-?)([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24:?00)([\.,]\d+)?)?((:?)[0-5]\d([.,]\d+)?)?([zZ]|([\+\-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?</param>
29
30
  </data>
30
31
  </define>
31
32
  <define name="ISO8601Date">
33
+ <a:documentation>Date conforming with ISO 8601</a:documentation>
32
34
  <data type="string">
33
35
  <param name="pattern">([\+\-]?\d{4})((-?)((0[1-9]|1[0-2])((-?)([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6]))))?</param>
34
36
  </data>
35
37
  </define>
36
- <!-- start = bibitem -->
37
38
  <define name="BibData">
38
39
  <ref name="BibliographicItem"/>
39
40
  </define>
40
41
  <define name="status">
42
+ <a:documentation>The publication or preparation status of a document</a:documentation>
41
43
  <element name="status">
42
- <ref name="stage"/>
44
+ <ref name="stage">
45
+ <a:documentation>The stage of the document status, e.g. "Published", "Unpublished", "Committee Draft", "Preprint"</a:documentation>
46
+ </ref>
43
47
  <optional>
44
- <ref name="substage"/>
48
+ <ref name="substage">
49
+ <a:documentation>The substage of the document status. These are used particularly in Standards Defining Organizations</a:documentation>
50
+ </ref>
45
51
  </optional>
46
52
  <optional>
47
- <ref name="iteration"/>
53
+ <ref name="iteration">
54
+ <a:documentation>The iteration of the given status that the document is currently in (e.g. "3" for a third draft)</a:documentation>
55
+ </ref>
48
56
  </optional>
49
57
  </element>
50
58
  </define>
51
59
  <define name="stage">
60
+ <a:documentation>The stage of the document status, e.g. "Published", "Unpublished", "Committee Draft", "Preprint"</a:documentation>
52
61
  <element name="stage">
53
62
  <optional>
54
- <attribute name="abbreviation"/>
63
+ <attribute name="abbreviation">
64
+ <a:documentation>A canonical abbreviation of the document stage</a:documentation>
65
+ </attribute>
55
66
  </optional>
56
- <text/>
67
+ <text>
68
+ <a:documentation>The name of the document stage</a:documentation>
69
+ </text>
57
70
  </element>
58
71
  </define>
59
72
  <define name="substage">
73
+ <a:documentation>The substage of the document status. These are used particularly in Standards Defining Organizations</a:documentation>
60
74
  <element name="substage">
61
75
  <optional>
62
- <attribute name="abbreviation"/>
76
+ <attribute name="abbreviation">
77
+ <a:documentation>A canonical abbreviation of the document substage</a:documentation>
78
+ </attribute>
63
79
  </optional>
64
- <text/>
80
+ <text>
81
+ <a:documentation>The name of the documen substage</a:documentation>
82
+ </text>
65
83
  </element>
66
84
  </define>
67
85
  <define name="iteration">
@@ -71,100 +89,84 @@
71
89
  </define>
72
90
  <define name="language">
73
91
  <element name="language">
74
- <text/>
92
+ <ref name="LanguageType"/>
75
93
  </element>
76
94
  </define>
77
95
  <define name="locale">
78
- <a:documentation>ISO-639</a:documentation>
79
96
  <element name="locale">
80
- <text/>
97
+ <ref name="LocaleType"/>
81
98
  </element>
82
99
  </define>
83
100
  <define name="script">
84
- <a:documentation>ISO-3166</a:documentation>
85
101
  <element name="script">
86
- <text/>
102
+ <ref name="ScriptType"/>
87
103
  </element>
88
104
  </define>
89
105
  <define name="edition">
90
- <a:documentation>ISO-15924: Latn</a:documentation>
106
+ <a:documentation>Edition of a bibliographic item</a:documentation>
91
107
  <element name="edition">
92
108
  <optional>
93
- <attribute name="number"/>
109
+ <attribute name="number">
110
+ <a:documentation>Number of edition.
111
+ NOTE: The number attribute can be used to represent the numeric equivalent of the edition string</a:documentation>
112
+ </attribute>
94
113
  </optional>
95
- <text/>
114
+ <text>
115
+ <a:documentation>Formatted, human-readable edition string</a:documentation>
116
+ </text>
96
117
  </element>
97
118
  </define>
98
- <define name="LocalizedStringAttrs">
119
+ <define name="LocalizedStringAttributes">
120
+ <a:documentation>multiple values are comma-delimited</a:documentation>
99
121
  <optional>
100
- <!-- multiple languages and scripts possible: comma delimit them if so -->
101
- <attribute name="language"/>
122
+ <attribute name="language">
123
+ <ref name="LanguageType"/>
124
+ </attribute>
102
125
  </optional>
103
126
  <optional>
104
- <attribute name="locale"/>
127
+ <attribute name="locale">
128
+ <ref name="LocaleType"/>
129
+ </attribute>
105
130
  </optional>
106
131
  <optional>
107
- <attribute name="script"/>
132
+ <attribute name="script">
133
+ <ref name="ScriptType"/>
134
+ </attribute>
108
135
  </optional>
109
136
  </define>
110
- <define name="LocalizedString1">
111
- <!-- multiple languages and scripts possible: comma delimit them if so -->
112
- <ref name="LocalizedStringAttrs"/>
113
- <text/>
114
- </define>
115
137
  <define name="LocalizedString">
116
- <choice>
117
- <ref name="LocalizedString1"/>
118
- <oneOrMore>
119
- <element name="variant">
120
- <ref name="LocalizedString1"/>
121
- </element>
122
- </oneOrMore>
123
- </choice>
138
+ <ref name="LocalizedStringAttributes"/>
139
+ <text/>
124
140
  </define>
125
- <define name="LocalizedMarkedUpString1">
126
- <!-- multiple languages and scripts possible: comma delimit them if so -->
127
- <ref name="LocalizedStringAttrs"/>
141
+ <!--
142
+ LocalizedString =
143
+ LocalizedStringAttributes,
144
+ text
145
+
146
+ LocalizedString =
147
+ LocalizedString1 |
148
+ element variant { LocalizedString1 }+
149
+ -->
150
+ <define name="LocalizedMarkedUpString">
151
+ <ref name="LocalizedStringAttributes"/>
128
152
  <oneOrMore>
129
- <ref name="TextElement"/>
153
+ <ref name="PureTextElement"/>
130
154
  </oneOrMore>
131
155
  </define>
132
- <define name="LocalizedMarkedUpString">
133
- <choice>
134
- <ref name="LocalizedMarkedUpString1"/>
135
- <oneOrMore>
136
- <element name="variant">
137
- <ref name="LocalizedMarkedUpString1"/>
138
- </element>
139
- </oneOrMore>
140
- </choice>
141
- </define>
156
+ <!--
157
+ LocalizedMarkedUpString =
158
+ LocalizedMarkedUpString1 |
159
+ Variants of the string, with the same content, but in different language, script, or format
160
+ element variant { LocalizedMarkedUpString1 }+
161
+ -->
142
162
  <!--
143
163
  Unlike UML, change type to format: type is overloaded
144
164
  Would be need if plain were default value and could omit the attribute
145
165
  Added LocalizedStringOrXsAny
146
166
  -->
147
- <define name="FormattedString">
148
- <optional>
149
- <!-- attribute format { ( "plain" | "html" | "docbook" | "tei" | "asciidoc" | "markdown" ) }?, -->
150
- <attribute name="format">
151
- <choice>
152
- <value>text/plain</value>
153
- <value>text/html</value>
154
- <value>application/docbook+xml</value>
155
- <value>application/tei+xml</value>
156
- <value>text/x-asciidoc</value>
157
- <value>text/markdown</value>
158
- <value>application/x-metanorma+xml</value>
159
- <text/>
160
- </choice>
161
- </attribute>
162
- </optional>
163
- <ref name="LocalizedStringOrXsAny"/>
164
- </define>
165
- <define name="LocalizedStringOrXsAny1">
166
- <!-- multiple languages and scripts possible: comma delimit them if so -->
167
- <ref name="LocalizedStringAttrs"/>
167
+ <!-- LocalizedStringOrXsAny1 = -->
168
+ <define name="LocalizedStringOrXsAny">
169
+ <ref name="LocalizedStringAttributes"/>
168
170
  <oneOrMore>
169
171
  <choice>
170
172
  <text/>
@@ -172,27 +174,43 @@
172
174
  </choice>
173
175
  </oneOrMore>
174
176
  </define>
175
- <define name="LocalizedStringOrXsAny">
176
- <choice>
177
- <ref name="LocalizedStringOrXsAny1"/>
178
- <oneOrMore>
179
- <element name="variant">
180
- <ref name="LocalizedStringOrXsAny1"/>
181
- </element>
182
- </oneOrMore>
183
- </choice>
184
- </define>
177
+ <!--
178
+ LocalizedStringOrXsAny =
179
+ LocalizedStringOrXsAny1 |
180
+ element variant { LocalizedStringOrXsAny1 }+
181
+ -->
185
182
  <define name="contributor">
183
+ <a:documentation>String which is formatted according to conventions specified in a named MIME type </a:documentation>
184
+ <!-- FormattedString = -->
185
+ <a:documentation>MIME type for string (defailts to text/plain).
186
+ NOTE: `docbook`, `AsciiDoc`, `Metanorma` are not registered IANA Media Types</a:documentation>
187
+ <!--
188
+ attribute format {
189
+ "text/plain" | "text/html" | "application/docbook+xml" |
190
+ "application/tei+xml" | "text/x-asciidoc" | "text/markdown" | "application/x-metanorma+xml" | text
191
+ }?,
192
+ -->
193
+ <a:documentation>String</a:documentation>
194
+ <!-- LocalizedStringOrXsAny -->
195
+ <a:documentation>Description of a contributor to the production of the bibliographic item</a:documentation>
186
196
  <element name="contributor">
187
197
  <oneOrMore>
188
- <ref name="role"/>
198
+ <ref name="role">
199
+ <a:documentation>A description of the role of the contributor in the production of the bibliographic item</a:documentation>
200
+ </ref>
189
201
  </oneOrMore>
190
- <ref name="ContributorInfo"/>
202
+ <ref name="ContributorInfo">
203
+ <a:documentation>The contributor involved in the production of the bibliographic item.
204
+ May be either a person or an organization</a:documentation>
205
+ </ref>
191
206
  </element>
192
207
  </define>
193
208
  <define name="role">
209
+ <a:documentation>A description of the role of the contributor in the production of a bibliographic item</a:documentation>
194
210
  <element name="role">
195
211
  <attribute name="type">
212
+ <a:documentation>The broad class of role of the contributor. Mandatory in order to enforce orderly management of contributors.
213
+ Detailed in https://www.relaton.org/model/creator/</a:documentation>
196
214
  <choice>
197
215
  <value>author</value>
198
216
  <value>performer</value>
@@ -209,7 +227,9 @@
209
227
  </choice>
210
228
  </attribute>
211
229
  <zeroOrMore>
212
- <ref name="roledescription"/>
230
+ <ref name="roledescription">
231
+ <a:documentation>A more detailed description of the role of the contributor</a:documentation>
232
+ </ref>
213
233
  </zeroOrMore>
214
234
  </element>
215
235
  </define>
@@ -225,25 +245,37 @@
225
245
  </element>
226
246
  </define>
227
247
  <define name="person">
248
+ <a:documentation>Person associated with a bibliographic item</a:documentation>
228
249
  <element name="person">
229
250
  <optional>
230
- <ref name="fullname"/>
251
+ <ref name="fullname">
252
+ <a:documentation>The name of the person</a:documentation>
253
+ </ref>
231
254
  </optional>
232
255
  <zeroOrMore>
233
- <ref name="credential"/>
256
+ <ref name="credential">
257
+ <a:documentation>Credentials given for the person postnominally, e.g. "PhD"</a:documentation>
258
+ </ref>
234
259
  </zeroOrMore>
235
260
  <zeroOrMore>
236
- <ref name="affiliation"/>
261
+ <ref name="affiliation">
262
+ <a:documentation>The affiliation of the person within an organization</a:documentation>
263
+ </ref>
237
264
  </zeroOrMore>
238
265
  <zeroOrMore>
239
- <ref name="person-identifier"/>
266
+ <ref name="person-identifier">
267
+ <a:documentation>An identifier of the person according to an international identifier scheme</a:documentation>
268
+ </ref>
240
269
  </zeroOrMore>
241
270
  <zeroOrMore>
242
- <ref name="contact"/>
271
+ <ref name="contact">
272
+ <a:documentation>Contact information for the person, including URI, address, phone number, and email</a:documentation>
273
+ </ref>
243
274
  </zeroOrMore>
244
275
  </element>
245
276
  </define>
246
277
  <define name="fullname">
278
+ <a:documentation>The name of a person</a:documentation>
247
279
  <element name="name">
248
280
  <ref name="FullNameType"/>
249
281
  </element>
@@ -255,31 +287,56 @@
255
287
  </define>
256
288
  <define name="FullNameType">
257
289
  <optional>
258
- <ref name="name_abbreviation"/>
290
+ <ref name="name_abbreviation">
291
+ <a:documentation>The initials of the person, used as an abbreviation for the person, and including the
292
+ surname. Can be used instead of the complete name. Distinct from formatted-initials,
293
+ which are the initials only of the forenames of the person</a:documentation>
294
+ </ref>
259
295
  </optional>
260
- <choice>
261
- <group>
262
- <zeroOrMore>
263
- <ref name="prefix"/>
264
- </zeroOrMore>
265
- <zeroOrMore>
266
- <ref name="forename"/>
267
- </zeroOrMore>
268
- <optional>
269
- <ref name="formatted-initials"/>
270
- </optional>
271
- <ref name="surname"/>
272
- <zeroOrMore>
273
- <ref name="addition"/>
274
- </zeroOrMore>
275
- </group>
276
- <ref name="completeName"/>
277
- </choice>
296
+ <group>
297
+ <zeroOrMore>
298
+ <ref name="prefix">
299
+ <a:documentation>A prefixed addition to the name of the person, such as "Dr"</a:documentation>
300
+ </ref>
301
+ </zeroOrMore>
302
+ <zeroOrMore>
303
+ <ref name="forename">
304
+ <a:documentation>A forename or given name of the person. Includes middle names</a:documentation>
305
+ </ref>
306
+ </zeroOrMore>
307
+ <optional>
308
+ <ref name="formatted-initials">
309
+ <a:documentation>The initials of the person, as a formatted string, including punctuation, dropping
310
+ punctuation as desired, and including hyphens where necessary. For example,
311
+ the initial set for Jean-Paul would be J, P; the formatted initials would be "J.-P."
312
+ or "J-P.". Can be used instead of forenames</a:documentation>
313
+ </ref>
314
+ </optional>
315
+ <optional>
316
+ <ref name="surname">
317
+ <a:documentation>The surname, family name, or equivalent of the person</a:documentation>
318
+ </ref>
319
+ </optional>
320
+ <zeroOrMore>
321
+ <ref name="addition">
322
+ <a:documentation>A suffixed addition to the name of the person, such as "Jr"</a:documentation>
323
+ </ref>
324
+ </zeroOrMore>
325
+ <optional>
326
+ <ref name="completeName">
327
+ <a:documentation>A preformatted version of the name of the person, not broken down into its component parts</a:documentation>
328
+ </ref>
329
+ </optional>
330
+ </group>
278
331
  <zeroOrMore>
279
- <ref name="biblionote"/>
332
+ <ref name="biblionote">
333
+ <a:documentation>An additional note about the name of the person</a:documentation>
334
+ </ref>
280
335
  </zeroOrMore>
281
336
  <zeroOrMore>
282
- <ref name="variantname"/>
337
+ <ref name="variantname">
338
+ <a:documentation>A variant name of the person</a:documentation>
339
+ </ref>
283
340
  </zeroOrMore>
284
341
  </define>
285
342
  <define name="name_abbreviation">
@@ -308,11 +365,19 @@
308
365
  </element>
309
366
  </define>
310
367
  <define name="forename">
368
+ <a:documentation>A forename of a person</a:documentation>
311
369
  <element name="forename">
312
370
  <optional>
313
- <attribute name="initial"/>
371
+ <attribute name="initial">
372
+ <a:documentation>An individual initial of the person, corresponding to the given forename.
373
+ Does not include final punctuation, but can include hyphens.
374
+ Can be used instead of forenames, if formatted-initials are not provided
375
+ (in which case each initial will be punctuated following local practice).</a:documentation>
376
+ </attribute>
314
377
  </optional>
315
- <ref name="LocalizedString"/>
378
+ <ref name="LocalizedString">
379
+ <a:documentation>A forename or given name of the person. Includes middle names</a:documentation>
380
+ </ref>
316
381
  </element>
317
382
  </define>
318
383
  <define name="completeName">
@@ -321,21 +386,34 @@
321
386
  </element>
322
387
  </define>
323
388
  <define name="variantname">
389
+ <a:documentation>A variant name of a person</a:documentation>
324
390
  <element name="variant">
325
- <attribute name="type"/>
326
- <ref name="FullNameType"/>
391
+ <attribute name="type">
392
+ <a:documentation>The type of variant name for the person. Examples include pseudonyms; user names (online);
393
+ real names (if the person is named with a pseudonym or user name); previous legal names</a:documentation>
394
+ </attribute>
395
+ <ref name="FullNameType">
396
+ <a:documentation>The variant name itself</a:documentation>
397
+ </ref>
327
398
  </element>
328
399
  </define>
329
400
  <define name="affiliation">
401
+ <a:documentation>The affiliation of a person with an organization</a:documentation>
330
402
  <element name="affiliation">
331
403
  <optional>
332
- <ref name="affiliationname"/>
404
+ <ref name="affiliationname">
405
+ <a:documentation>The name of the affiliation of the person with the organization; typically a position title</a:documentation>
406
+ </ref>
333
407
  </optional>
334
408
  <zeroOrMore>
335
- <ref name="affiliationdescription"/>
409
+ <ref name="affiliationdescription">
410
+ <a:documentation>A more detailed description of the affiliation of the person</a:documentation>
411
+ </ref>
336
412
  </zeroOrMore>
337
413
  <optional>
338
- <ref name="organization"/>
414
+ <ref name="organization">
415
+ <a:documentation>The organization with which the person is affiliated</a:documentation>
416
+ </ref>
339
417
  </optional>
340
418
  </element>
341
419
  </define>
@@ -350,47 +428,64 @@
350
428
  </element>
351
429
  </define>
352
430
  <define name="organization">
431
+ <a:documentation>Organization associated with a bibliographic item</a:documentation>
353
432
  <element name="organization">
354
433
  <ref name="OrganizationType"/>
355
434
  </element>
356
435
  </define>
357
436
  <define name="OrganizationType">
358
437
  <oneOrMore>
359
- <ref name="orgname"/>
438
+ <ref name="orgname">
439
+ <a:documentation>The name of the organization</a:documentation>
440
+ </ref>
360
441
  </oneOrMore>
361
442
  <zeroOrMore>
362
- <ref name="subdivision"/>
443
+ <ref name="subdivision">
444
+ <a:documentation>The subdivision of the organization directly involved with the production of the bibliographic item</a:documentation>
445
+ </ref>
363
446
  </zeroOrMore>
364
447
  <optional>
365
- <ref name="abbreviation"/>
448
+ <ref name="abbreviation">
449
+ <a:documentation>Abbreviation under which the organization is known</a:documentation>
450
+ </ref>
366
451
  </optional>
367
452
  <zeroOrMore>
368
- <ref name="uri"/>
369
- </zeroOrMore>
370
- <zeroOrMore>
371
- <ref name="org-identifier"/>
453
+ <ref name="org-identifier">
454
+ <a:documentation>An identifier of the organization according to an international identifier scheme</a:documentation>
455
+ </ref>
372
456
  </zeroOrMore>
373
457
  <zeroOrMore>
374
- <ref name="contact"/>
458
+ <ref name="contact">
459
+ <a:documentation>Contact information for the organization, including address, phone number, and email</a:documentation>
460
+ </ref>
375
461
  </zeroOrMore>
376
462
  <optional>
377
- <ref name="logo"/>
463
+ <ref name="logo">
464
+ <a:documentation>A logo for the organization</a:documentation>
465
+ </ref>
378
466
  </optional>
379
467
  </define>
380
468
  <define name="orgname">
381
469
  <element name="name">
382
- <choice>
383
- <ref name="LocalizedString"/>
384
- <ref name="NameWithVariants"/>
385
- </choice>
470
+ <optional>
471
+ <attribute name="type">
472
+ <a:documentation>Type of organisation name, to differentiate variant names</a:documentation>
473
+ </attribute>
474
+ </optional>
475
+ <ref name="LocalizedString"/>
386
476
  </element>
387
477
  </define>
388
478
  <define name="subdivision">
479
+ <a:documentation>Subdivision of organization associated with a bibliographic item</a:documentation>
389
480
  <element name="subdivision">
390
481
  <optional>
391
- <attribute name="type"/>
482
+ <attribute name="type">
483
+ <a:documentation>The type of subdivision</a:documentation>
484
+ </attribute>
392
485
  </optional>
393
- <ref name="OrganizationType"/>
486
+ <ref name="OrganizationType">
487
+ <a:documentation>The subdivision, modelled recursively as an organization</a:documentation>
488
+ </ref>
394
489
  </element>
395
490
  </define>
396
491
  <define name="logo">
@@ -399,51 +494,52 @@
399
494
  </element>
400
495
  </define>
401
496
  <define name="depiction">
497
+ <a:documentation>Depiction of the bibliographic item</a:documentation>
402
498
  <element name="depiction">
403
499
  <optional>
404
- <attribute name="scope"/>
500
+ <attribute name="scope">
501
+ <a:documentation>Description of what is being depicted</a:documentation>
502
+ </attribute>
405
503
  </optional>
406
504
  <zeroOrMore>
407
- <ref name="image-no-id"/>
505
+ <ref name="image-no-id">
506
+ <a:documentation>A visual depiction of the bibliographic item</a:documentation>
507
+ </ref>
408
508
  </zeroOrMore>
409
509
  </element>
410
510
  </define>
411
- <define name="NameWithVariants">
412
- <element name="primary">
413
- <ref name="LocalizedString"/>
414
- </element>
415
- <zeroOrMore>
416
- <element name="variant">
417
- <ref name="NameWithVariants1"/>
418
- </element>
419
- </zeroOrMore>
420
- </define>
421
- <define name="NameWithVariants1">
422
- <attribute name="type"/>
423
- <element name="primary">
424
- <ref name="LocalizedString"/>
425
- </element>
426
- <zeroOrMore>
427
- <element name="variant">
428
- <ref name="NameWithVariants1"/>
429
- </element>
430
- </zeroOrMore>
431
- </define>
511
+ <!--
512
+ NameWithVariants =
513
+ element primary { LocalizedString },
514
+ element variant { NameWithVariants1 }*
515
+
516
+ NameWithVariants1 =
517
+ attribute type { text },
518
+ element primary { LocalizedString },
519
+ element variant { NameWithVariants1 }*
520
+ -->
432
521
  <define name="abbreviation">
433
522
  <element name="abbreviation">
434
523
  <ref name="LocalizedString"/>
435
524
  </element>
436
525
  </define>
437
526
  <define name="uri">
527
+ <a:documentation>URI associated with a type</a:documentation>
438
528
  <element name="uri">
439
529
  <optional>
440
- <attribute name="type"/>
530
+ <attribute name="type">
531
+ <a:documentation>The types of URI are open-ended, but include the IANA link relations specified in RFC 8288</a:documentation>
532
+ </attribute>
441
533
  </optional>
442
- <data type="anyURI"/>
534
+ <ref name="LocalizedStringAttributes"/>
535
+ <data type="anyURI">
536
+ <a:documentation>URI content</a:documentation>
537
+ </data>
443
538
  </element>
444
539
  </define>
445
540
  <!-- TODO may change -->
446
541
  <define name="contact">
542
+ <a:documentation>Contact information for a person or organization</a:documentation>
447
543
  <choice>
448
544
  <ref name="address"/>
449
545
  <ref name="phone"/>
@@ -452,37 +548,58 @@
452
548
  </choice>
453
549
  </define>
454
550
  <define name="phone">
551
+ <a:documentation>The phone number associated with a person or organization</a:documentation>
455
552
  <element name="phone">
456
553
  <optional>
457
- <attribute name="type"/>
554
+ <attribute name="type">
555
+ <a:documentation>The type of phone number; can include "Fax" and "Mobile"</a:documentation>
556
+ </attribute>
458
557
  </optional>
459
- <text/>
558
+ <text>
559
+ <a:documentation>The phone number itself</a:documentation>
560
+ </text>
460
561
  </element>
461
562
  </define>
462
563
  <define name="email">
564
+ <a:documentation>Email address</a:documentation>
463
565
  <element name="email">
464
566
  <text/>
465
567
  </element>
466
568
  </define>
467
569
  <define name="address">
570
+ <a:documentation>An address for a person or organization</a:documentation>
468
571
  <element name="address">
469
- <choice>
572
+ <zeroOrMore>
470
573
  <!-- iso191606 TODO -->
471
- <group>
472
- <zeroOrMore>
473
- <ref name="street"/>
474
- </zeroOrMore>
475
- <ref name="city"/>
476
- <optional>
477
- <ref name="state"/>
478
- </optional>
479
- <ref name="country"/>
480
- <optional>
481
- <ref name="postcode"/>
482
- </optional>
483
- </group>
484
- <ref name="formattedAddress"/>
485
- </choice>
574
+ <ref name="street">
575
+ <a:documentation>The street and street number or equivalent in the address, as one or more lines of text</a:documentation>
576
+ </ref>
577
+ </zeroOrMore>
578
+ <optional>
579
+ <ref name="city">
580
+ <a:documentation>The settlement or municipality in the address</a:documentation>
581
+ </ref>
582
+ </optional>
583
+ <optional>
584
+ <ref name="state">
585
+ <a:documentation>The region of the country in the address</a:documentation>
586
+ </ref>
587
+ </optional>
588
+ <optional>
589
+ <ref name="country">
590
+ <a:documentation>The country in the address</a:documentation>
591
+ </ref>
592
+ </optional>
593
+ <optional>
594
+ <ref name="postcode">
595
+ <a:documentation>The postal code or equivalent in the address</a:documentation>
596
+ </ref>
597
+ </optional>
598
+ <optional>
599
+ <ref name="formattedAddress">
600
+ <a:documentation>Preformatted version of the address, not decomposed into its component parts</a:documentation>
601
+ </ref>
602
+ </optional>
486
603
  </element>
487
604
  </define>
488
605
  <define name="street">
@@ -512,48 +629,77 @@
512
629
  </define>
513
630
  <define name="formattedAddress">
514
631
  <element name="formattedAddress">
515
- <text/>
632
+ <oneOrMore>
633
+ <choice>
634
+ <text/>
635
+ <ref name="br"/>
636
+ </choice>
637
+ </oneOrMore>
516
638
  </element>
517
639
  </define>
518
640
  <define name="person-identifier">
641
+ <a:documentation>An identifier of a person according to an international identifier scheme</a:documentation>
519
642
  <element name="identifier">
520
643
  <attribute name="type">
521
- <choice>
522
- <value>isni</value>
523
- <value>orcid</value>
524
- <value>uri</value>
525
- </choice>
644
+ <a:documentation>The international identifier scheme for the identifier of the person.
645
+ Examples include "isni", "orcid", "uri"</a:documentation>
526
646
  </attribute>
527
- <text/>
647
+ <text>
648
+ <a:documentation>The identifier value</a:documentation>
649
+ </text>
528
650
  </element>
529
651
  </define>
530
652
  <define name="org-identifier">
653
+ <a:documentation>An identifier of an organization according to an international identifier scheme</a:documentation>
531
654
  <element name="identifier">
532
- <attribute name="type">
533
- <data type="string" datatypeLibrary=""/>
534
- </attribute>
535
- <text/>
655
+ <optional>
656
+ <attribute name="type">
657
+ <a:documentation>The international identifier scheme for the identifier of the organization.
658
+ Examples include GRID, LEI, CrossRef, and Ringgold</a:documentation>
659
+ </attribute>
660
+ </optional>
661
+ <text>
662
+ <a:documentation>The identifier value</a:documentation>
663
+ </text>
536
664
  </element>
537
665
  </define>
538
666
  <define name="citation">
667
+ <a:documentation>Representation of a citation of a bibliographic item, typically within a document</a:documentation>
539
668
  <element name="citation">
540
669
  <ref name="CitationType"/>
541
670
  </element>
542
671
  </define>
543
672
  <define name="CitationType">
544
673
  <attribute name="bibitemid">
674
+ <a:documentation>Bibliographic item that the citation applies to, referenced as the anchor of a bibliographic description</a:documentation>
545
675
  <data type="IDREF"/>
546
676
  </attribute>
547
677
  <choice>
548
678
  <zeroOrMore>
549
- <ref name="locality"/>
679
+ <ref name="locality">
680
+ <a:documentation>Describes the location of the cited information resource within the subject of the bibliographic item.
681
+ Multiple ``bibLocality``s are interpreted as discontinuous references.</a:documentation>
682
+ </ref>
550
683
  </zeroOrMore>
551
684
  <zeroOrMore>
552
- <ref name="localityStack"/>
685
+ <ref name="localityStack">
686
+ <a:documentation>Describes the location of the cited information resource within the subject of the bibliographic item in a multi-level manner.
687
+ For example, the hierarchical specification "Part IV, Chapter 3, Paragraphs 22-24"
688
+ is represented as a single `bibLocalityStack`, composed of those three localities
689
+ (as opposed to three `bibLocality` references, which would be treated as three discontinuous references).
690
+ Multiple ``bibLocalityStack``s are themselves interpreted as discontinuous references</a:documentation>
691
+ </ref>
553
692
  </zeroOrMore>
554
693
  </choice>
555
694
  <optional>
556
- <ref name="date"/>
695
+ <ref name="date">
696
+ <a:documentation>Date of the citation, typically date of publication.
697
+ A combination of the date time elements year, month and day should be specified.
698
+ Specification of month and day are optional.
699
+ This date is not intended for disambiguation, since `bibitemid`
700
+ already identifies the source unambiguously; it is added for ease of processing, in case author-date
701
+ citations cannot straightforwardly extract the date from the bibliographic source</a:documentation>
702
+ </ref>
557
703
  </optional>
558
704
  </define>
559
705
  <define name="date">
@@ -562,14 +708,20 @@
562
708
  </element>
563
709
  </define>
564
710
  <define name="locality">
711
+ <a:documentation>The extent or location of a bibliographic item being referred to.
712
+ A sequence of locality elements is meant to indicate hierarchical ordering, from greater to smaller.
713
+ e.g. Chapter, then page, then paragraph.
714
+ A discontinuous range can be represented by using two adjacent localities with the same type</a:documentation>
565
715
  <element name="locality">
566
716
  <ref name="BibItemLocality"/>
567
717
  </element>
568
718
  </define>
569
719
  <define name="localityStack">
720
+ <a:documentation>Hierarchical arrangement of bibliographic localities, to refer to a single span of text in a bibliographic item</a:documentation>
570
721
  <element name="localityStack">
571
722
  <optional>
572
723
  <attribute name="connective">
724
+ <a:documentation>Logical connective linking localities. If not supplied, "and" is understood</a:documentation>
573
725
  <choice>
574
726
  <value>and</value>
575
727
  <value>or</value>
@@ -580,16 +732,23 @@
580
732
  </attribute>
581
733
  </optional>
582
734
  <zeroOrMore>
583
- <ref name="locality"/>
735
+ <ref name="locality">
736
+ <a:documentation>Component bibliographic localities which group together to designate a single span of text.
737
+ Earlier localities are assumed to include later localities, and be of different types;
738
+ e.g. "Chapter 7, paragraph 9–11"</a:documentation>
739
+ </ref>
584
740
  </zeroOrMore>
585
741
  </element>
586
742
  </define>
587
743
  <define name="sourceLocality">
744
+ <a:documentation>The extent or location of a source bibliographic item being related to a target bibliographic item</a:documentation>
588
745
  <element name="sourceLocality">
589
746
  <ref name="BibItemLocality"/>
590
747
  </element>
591
748
  </define>
592
749
  <define name="sourceLocalityStack">
750
+ <a:documentation>Hierarchical arrangement of bibliographic localities, to refer to a single span of text in a source bibliographic item,
751
+ being related to a target bibliographic item</a:documentation>
593
752
  <element name="sourceLocalityStack">
594
753
  <optional>
595
754
  <attribute name="connective">
@@ -609,16 +768,30 @@
609
768
  </define>
610
769
  <define name="BibItemLocality">
611
770
  <attribute name="type">
771
+ <a:documentation>The type of extent of a locality (e.g. section, clause, page)</a:documentation>
612
772
  <ref name="LocalityType"/>
613
773
  </attribute>
614
774
  <optional>
615
- <ref name="referenceFrom"/>
775
+ <ref name="referenceFrom">
776
+ <a:documentation>The starting value of the extent, or point location</a:documentation>
777
+ </ref>
616
778
  </optional>
617
779
  <optional>
618
- <ref name="referenceTo"/>
780
+ <ref name="referenceTo">
781
+ <a:documentation>The end value of the extent as a range, if applicable</a:documentation>
782
+ </ref>
619
783
  </optional>
620
784
  </define>
621
785
  <define name="LocalityType">
786
+ <a:documentation>Type of indicator of a location or extent within a bibliographic item.
787
+ When the value `whole` or `title` is used, the corresponding `BibItemLocality`
788
+ attribute `identifier` should be empty
789
+ `whole` refers to the entire document.
790
+ `list` is used for ordered lists in standards documents
791
+ `time` is used for timestamps in audio and visual media
792
+ `anchor` is used for locations within web pages
793
+ `line` is a line number, dependent on printed form of document
794
+ `locality:...` is an extension point: it allows a free-form text string that is human-readable</a:documentation>
622
795
  <data type="string">
623
796
  <param name="pattern">section|clause|part|paragraph|chapter|page|title|line|whole|table|annex|figure|note|list|example|volume|issue|time|anchor|locality:[a-zA-Z0-9_]+</param>
624
797
  </data>
@@ -635,6 +808,7 @@
635
808
  </define>
636
809
  <!-- unlike UML, has id attribute; that results from including bibitem in a docmodel -->
637
810
  <define name="bibitem">
811
+ <a:documentation>Description of a bibliographic item</a:documentation>
638
812
  <element name="bibitem">
639
813
  <attribute name="id">
640
814
  <data type="ID"/>
@@ -643,162 +817,310 @@
643
817
  </element>
644
818
  </define>
645
819
  <define name="bibitem_no_id">
820
+ <a:documentation>Description of a bibliographic item: no ID attribute (for use in Relaton, metadata)</a:documentation>
646
821
  <element name="bibitem">
647
822
  <ref name="BibliographicItem"/>
648
823
  </element>
649
824
  </define>
650
825
  <define name="relaton_collection">
826
+ <a:documentation>Used to present a group of bibliographic items as a single group;
827
+ e.g. when summarising the collection of standards created by a standards body.
828
+ A collection may be used for bibliographic exchange but is typically not necesary for citation purposes</a:documentation>
651
829
  <element name="relaton-collection">
652
830
  <optional>
653
- <attribute name="type"/>
831
+ <attribute name="type">
832
+ <a:documentation>The type of grouping of bibliographic items</a:documentation>
833
+ </attribute>
654
834
  </optional>
655
- <ref name="btitle"/>
835
+ <ref name="btitle">
836
+ <a:documentation>The title given to the grouping of bibliographic items</a:documentation>
837
+ </ref>
656
838
  <zeroOrMore>
657
- <ref name="contributor"/>
839
+ <ref name="contributor">
840
+ <a:documentation>Contributors to the production of the bibliographic items as a grouping,
841
+ with corporate responsibility for all the items in the group
842
+ (e.g. as compilers of a collection or corporate authors)</a:documentation>
843
+ </ref>
658
844
  </zeroOrMore>
659
845
  <zeroOrMore>
660
- <ref name="docrelation"/>
846
+ <ref name="docrelation">
847
+ <a:documentation>The individual items which constitute the group, expressed as relations to the
848
+ document group. The `type` attribute of each relation is expected to be either `includes` or `hasPart`,
849
+ depending on whether the items exist as independent documents, or are parts of a multi-part document</a:documentation>
850
+ </ref>
661
851
  </zeroOrMore>
662
852
  </element>
663
853
  </define>
664
854
  <define name="BibItemType" combine="choice">
855
+ <a:documentation>Type of bibliographic item.
856
+ The value list complies with the types provided in ISO 690:2021.
857
+ NOTE: These values represent a strict superset to BibTeX
858
+ publication types, and therefore any BibTeX type value can be
859
+ mapped to these values. Some values here do not have a corresponding
860
+ entry in BibTeX, for instance, "standard" and "website".</a:documentation>
665
861
  <choice>
666
862
  <value>article</value>
863
+ <a:documentation>An article from a journal or magazine</a:documentation>
667
864
  <value>book</value>
865
+ <a:documentation>A monograph</a:documentation>
668
866
  <value>booklet</value>
867
+ <a:documentation>A booklet or pamphlet. The distinction between book and booklet is not made frequently</a:documentation>
669
868
  <value>manual</value>
869
+ <a:documentation>A manual</a:documentation>
670
870
  <value>proceedings</value>
871
+ <a:documentation>A conference proceedings</a:documentation>
671
872
  <value>presentation</value>
873
+ <a:documentation>A presentation given in a formal meeting</a:documentation>
672
874
  <value>thesis</value>
875
+ <a:documentation>A dissertation given in an academic institution, as a summation of research</a:documentation>
673
876
  <value>techreport</value>
877
+ <a:documentation>A technical report</a:documentation>
674
878
  <value>standard</value>
879
+ <a:documentation>A standard, a document issued by a Standards Defining Organization</a:documentation>
675
880
  <value>unpublished</value>
881
+ <a:documentation>An intellectual creation which has not been published, e.g. a manuscript.
882
+ NOTE: Properly this does not represent a distinct bibliographic type, and it
883
+ should be avoided in favour of using the `status` element of `BibliographicItem`</a:documentation>
676
884
  <value>map</value>
885
+ <a:documentation>A map or other cartographic resource</a:documentation>
677
886
  <value>electronic resource</value>
887
+ <a:documentation>A resource avaiulable in digital form
888
+ NOTE: The overloaded type `electronicResource` should be avoided where possible, particularly if the
889
+ resource corresponds closely to a paper bibliographic type, such as `book` or `article`.
890
+ The distinction between offline and online resources should be made through `medium` (electronic vs physical).
891
+ Specialisations of `electronicResource` include `dataset`, `webResource`, `website`,
892
+ `socialMedia`, and `software`.</a:documentation>
678
893
  <value>audiovisual</value>
894
+ <a:documentation>An audiovisual resource. Is a superclass of other types such as `video` and `music`</a:documentation>
679
895
  <value>film</value>
896
+ <a:documentation>A film</a:documentation>
680
897
  <value>video</value>
898
+ <a:documentation>A video</a:documentation>
681
899
  <value>broadcast</value>
900
+ <a:documentation>A broadcast made through mass media, including radio and television</a:documentation>
682
901
  <value>software</value>
902
+ <a:documentation>Computer executable code, not itself human-readable text (though it may generate such text)</a:documentation>
683
903
  <value>graphic_work</value>
904
+ <a:documentation>A graphic work, a work with two-dimensional or three-dimensional content</a:documentation>
684
905
  <value>music</value>
906
+ <a:documentation>A musical work. Includes both notated music and music performances:
907
+ The two are differentiated through `BibliographicItem/medium/content` as "notated music" vs "performed music"</a:documentation>
685
908
  <value>patent</value>
909
+ <a:documentation>A patent</a:documentation>
686
910
  <value>inbook</value>
911
+ <a:documentation>A (typically untitled) part of a book. May be a chapter (or section, etc.) and/or a range of pages</a:documentation>
687
912
  <value>incollection</value>
913
+ <a:documentation>A part of a book having its own title, and typically having distinct authorship</a:documentation>
688
914
  <value>inproceedings</value>
915
+ <a:documentation>An article in a conference proceedings</a:documentation>
689
916
  <value>journal</value>
917
+ <a:documentation>A journal or periodical publication</a:documentation>
690
918
  <value>website</value>
919
+ <a:documentation>A collection of web resources, presented under the same URL domain and under the same (individual or corporate) authorship</a:documentation>
691
920
  <value>webresource</value>
921
+ <a:documentation>A human-readable or consumable web resource, a single item accessible online via a web browser,
922
+ which is not composed of components all of which can be accessed in the same way.
923
+ Includes media files, as well as individual web pages</a:documentation>
692
924
  <value>dataset</value>
925
+ <a:documentation>An electronic dataset, a collection of data that is not meant to be human-readable, and which is typically only machine readable</a:documentation>
693
926
  <value>archival</value>
927
+ <a:documentation>A instance of a resource curated and preserved in an archive, which mediates any access to it.
928
+ Typically it is physical, unique, and unpublished.
929
+ NOTE: The content of the resource may be published separately,
930
+ but that makes it a distinct bibliographic item, as access to it is no longer mediated through the archive</a:documentation>
694
931
  <value>social_media</value>
932
+ <a:documentation>One or more resources within a collection that is typically collectively authored by member users.
933
+ Includes blog posts, forum posts, social media posts, tweets. Is usually a `webResource`,
934
+ but not always (e.g. blogs on WeChat are only accessible within the WeChat app.)</a:documentation>
695
935
  <value>alert</value>
936
+ <a:documentation>A single communication intended for multiple persons, and publicly accessible.
937
+ May be electronic (e.g. Facebook status update) or voice (e.g. evacuation alert), but is typically not print</a:documentation>
696
938
  <value>message</value>
939
+ <a:documentation>A single communication intended for a restricted number of authorised persons (typically one).
940
+ May be electronic (e.g. Twitter direct message, email) or voice (e.g. a remark made to someone,
941
+ typically cited as "personal communication")</a:documentation>
697
942
  <value>conversation</value>
943
+ <a:documentation>An exchange of messages between two or more persons. May be electronic (e.g. web chat) or voice (e.g. phone call)</a:documentation>
698
944
  <value>misc</value>
945
+ <a:documentation>Bibliographic type not adequately described in the foregoing</a:documentation>
699
946
  </choice>
700
947
  </define>
701
948
  <define name="BibliographicItem">
949
+ <a:documentation>Description of a bibliographic resource</a:documentation>
702
950
  <optional>
703
951
  <attribute name="type">
952
+ <a:documentation>The type of the bibliographic item</a:documentation>
704
953
  <ref name="BibItemType"/>
705
954
  </attribute>
706
955
  </optional>
707
956
  <optional>
708
- <attribute name="schema-version"/>
957
+ <attribute name="schema-version">
958
+ <a:documentation>The version of the Relaton schema that this description conforms to</a:documentation>
959
+ </attribute>
709
960
  </optional>
710
961
  <optional>
711
- <ref name="fetched"/>
962
+ <ref name="fetched">
963
+ <a:documentation>The date at which the bibliographic item was last updated</a:documentation>
964
+ </ref>
712
965
  </optional>
713
966
  <optional>
714
- <ref name="formattedref"/>
967
+ <ref name="formattedref">
968
+ <a:documentation>A pre-formatted version of the full bibliographic item reference,
969
+ rendered for human reading, and used to sidestep the rendering of the reference out of its component parts</a:documentation>
970
+ </ref>
715
971
  </optional>
716
972
  <oneOrMore>
717
- <ref name="btitle"/>
973
+ <ref name="btitle">
974
+ <a:documentation>The title(s) of the bibliographic item</a:documentation>
975
+ </ref>
718
976
  </oneOrMore>
719
977
  <zeroOrMore>
720
- <ref name="bsource"/>
978
+ <ref name="bsource">
979
+ <a:documentation>The URI(s) associated with the bibliographic item</a:documentation>
980
+ </ref>
721
981
  </zeroOrMore>
722
982
  <oneOrMore>
723
- <ref name="docidentifier"/>
983
+ <ref name="docidentifier">
984
+ <a:documentation>The identifier(s) of the bibliographic item in an international standard scheme</a:documentation>
985
+ </ref>
724
986
  </oneOrMore>
725
987
  <optional>
726
- <ref name="docnumber"/>
988
+ <ref name="docnumber">
989
+ <a:documentation>Unprefixed, preferably numeric version of an identifier of the bibliographic item, intended for sorting of bibliography</a:documentation>
990
+ </ref>
727
991
  </optional>
728
992
  <zeroOrMore>
729
- <ref name="bdate"/>
993
+ <ref name="bdate">
994
+ <a:documentation>One or more date-times associated with the production of or access to the bibliographic item</a:documentation>
995
+ </ref>
730
996
  </zeroOrMore>
731
997
  <zeroOrMore>
732
- <ref name="contributor"/>
998
+ <ref name="contributor">
999
+ <a:documentation>Contributors to the production of the bibliographic item</a:documentation>
1000
+ </ref>
733
1001
  </zeroOrMore>
734
1002
  <optional>
735
- <ref name="edition"/>
1003
+ <ref name="edition">
1004
+ <a:documentation>The edition of the bibliographic item</a:documentation>
1005
+ </ref>
736
1006
  </optional>
737
1007
  <zeroOrMore>
738
- <ref name="version"/>
1008
+ <ref name="version">
1009
+ <a:documentation>The version of the bibliographic item (within an edition). Can be used for drafts.
1010
+ Can be more than one, in case of multiple versioning schemes</a:documentation>
1011
+ </ref>
739
1012
  </zeroOrMore>
740
1013
  <zeroOrMore>
741
- <ref name="biblionote"/>
1014
+ <ref name="biblionote">
1015
+ <a:documentation>Note(s) associated with the bibliographic item</a:documentation>
1016
+ </ref>
742
1017
  </zeroOrMore>
743
1018
  <zeroOrMore>
744
- <ref name="language"/>
1019
+ <ref name="language">
1020
+ <a:documentation>The language(s) in which the bibliographic item is expressed</a:documentation>
1021
+ </ref>
745
1022
  </zeroOrMore>
746
1023
  <zeroOrMore>
747
- <ref name="locale"/>
1024
+ <ref name="locale">
1025
+ <a:documentation>The locale(s) in which the bibliographic item is expressed</a:documentation>
1026
+ </ref>
748
1027
  </zeroOrMore>
749
1028
  <zeroOrMore>
750
- <ref name="script"/>
1029
+ <ref name="script">
1030
+ <a:documentation>The script(s) in which the bibliographic item is written</a:documentation>
1031
+ </ref>
751
1032
  </zeroOrMore>
752
1033
  <zeroOrMore>
753
- <ref name="bibabstract"/>
1034
+ <ref name="bibabstract">
1035
+ <a:documentation>The abstract of the bibliographic item</a:documentation>
1036
+ </ref>
754
1037
  </zeroOrMore>
755
1038
  <optional>
756
- <ref name="status"/>
1039
+ <ref name="status">
1040
+ <a:documentation>The publication or preparation status of the bibliographic item</a:documentation>
1041
+ </ref>
757
1042
  </optional>
758
1043
  <zeroOrMore>
759
- <ref name="copyright"/>
1044
+ <ref name="copyright">
1045
+ <a:documentation>The copyright status of the bibliographic item</a:documentation>
1046
+ </ref>
760
1047
  </zeroOrMore>
761
1048
  <zeroOrMore>
762
- <ref name="docrelation"/>
1049
+ <ref name="docrelation">
1050
+ <a:documentation>The relation(s) of the bibliographic item to other bibliographic items</a:documentation>
1051
+ </ref>
763
1052
  </zeroOrMore>
764
1053
  <zeroOrMore>
765
- <ref name="series"/>
1054
+ <ref name="series">
1055
+ <a:documentation>The series of the bibliographic item</a:documentation>
1056
+ </ref>
766
1057
  </zeroOrMore>
767
1058
  <optional>
768
- <ref name="medium"/>
1059
+ <ref name="medium">
1060
+ <a:documentation>The medium the subject is realized on.
1061
+ Medium can be used to differentiate between "electronic" and "physical" manifestations of an information resource.</a:documentation>
1062
+ </ref>
769
1063
  </optional>
770
1064
  <zeroOrMore>
771
- <ref name="bplace"/>
1065
+ <ref name="bplace">
1066
+ <a:documentation>The geographic location associated with the production of the bibliographic item</a:documentation>
1067
+ </ref>
772
1068
  </zeroOrMore>
773
1069
  <zeroOrMore>
774
- <ref name="bprice"/>
1070
+ <ref name="bprice">
1071
+ <a:documentation>The price set on accessing the bibliographic item.
1072
+ The price should be treated as nominal, rather than capturing all possible pricings at a given time</a:documentation>
1073
+ </ref>
775
1074
  </zeroOrMore>
776
1075
  <zeroOrMore>
777
- <ref name="extent"/>
1076
+ <ref name="extent">
1077
+ <a:documentation>The extent of the bibliographic item, if reference is not being made to the entirety of the item described.
1078
+ Repeats for different levels of granularity (e.g. volume number, page number), or for discontinuous ranges
1079
+ (e.g. multiple page ranges, pages plus plates)</a:documentation>
1080
+ </ref>
778
1081
  </zeroOrMore>
779
1082
  <optional>
780
- <ref name="bibliographic_size"/>
1083
+ <ref name="bibliographic_size">
1084
+ <a:documentation>The bibliographic size of the bibliographic item, measured in the same units as extent (i.e. pages, volumes,
1085
+ megabytes, hours, rather than cm^2.) Distinct from the physical size of the bibliographic item, captured in medium/size</a:documentation>
1086
+ </ref>
781
1087
  </optional>
782
1088
  <zeroOrMore>
783
- <ref name="accesslocation"/>
1089
+ <ref name="accesslocation">
1090
+ <a:documentation>The location where the bibliographic item may be accessed.
1091
+ Used for archival resources. Also used for pathways to access digital resources, where a URI is not practical</a:documentation>
1092
+ </ref>
784
1093
  </zeroOrMore>
785
1094
  <zeroOrMore>
786
- <ref name="license"/>
1095
+ <ref name="license">
1096
+ <a:documentation>A license under which the bibliographic item has been issued.
1097
+ NOTE: This should preferably be encoded as a URI or short identifier, rather than descriptive text</a:documentation>
1098
+ </ref>
787
1099
  </zeroOrMore>
788
1100
  <zeroOrMore>
789
- <ref name="bclassification"/>
1101
+ <ref name="bclassification">
1102
+ <a:documentation>The classification of the bibliographic item according to a standard classification scheme</a:documentation>
1103
+ </ref>
790
1104
  </zeroOrMore>
791
1105
  <zeroOrMore>
792
- <ref name="bkeyword"/>
1106
+ <ref name="bkeyword">
1107
+ <a:documentation>Keyword(s) for the bibliographic item</a:documentation>
1108
+ </ref>
793
1109
  </zeroOrMore>
794
1110
  <optional>
795
- <ref name="validity"/>
1111
+ <ref name="validity">
1112
+ <a:documentation>Information about how long the current description of the bibliographic item is valid for</a:documentation>
1113
+ </ref>
796
1114
  </optional>
797
1115
  <optional>
798
- <ref name="depiction"/>
1116
+ <ref name="depiction">
1117
+ <a:documentation>Depiction of the bibliographic item, typically an image</a:documentation>
1118
+ </ref>
799
1119
  </optional>
800
1120
  </define>
801
1121
  <define name="ReducedBibliographicItem">
1122
+ <a:documentation>Reduced description of a bibliographic resource, without mandatory title and docidentifier, used for document relations
1123
+ Refer to `BibliographicItem` for definitions</a:documentation>
802
1124
  <optional>
803
1125
  <attribute name="type">
804
1126
  <ref name="BibItemType"/>
@@ -899,6 +1221,7 @@
899
1221
  </optional>
900
1222
  </define>
901
1223
  <define name="btitle">
1224
+ <a:documentation>A title of a bibliographic item, associated with a type of title</a:documentation>
902
1225
  <element name="title">
903
1226
  <ref name="TypedTitleString"/>
904
1227
  </element>
@@ -926,15 +1249,23 @@
926
1249
  </element>
927
1250
  </define>
928
1251
  <define name="validity">
1252
+ <a:documentation>The time interval for which a bibliographic item is determined valid, and the associated revision date</a:documentation>
929
1253
  <element name="validity">
930
1254
  <optional>
931
- <ref name="validityBegins"/>
1255
+ <ref name="validityBegins">
1256
+ <a:documentation>The date and time when this bibliographic item becomes valid</a:documentation>
1257
+ </ref>
932
1258
  </optional>
933
1259
  <optional>
934
- <ref name="validityEnds"/>
1260
+ <ref name="validityEnds">
1261
+ <a:documentation>The date and time when this bibliographic item becomes invalid</a:documentation>
1262
+ </ref>
935
1263
  </optional>
936
1264
  <optional>
937
- <ref name="validityRevision"/>
1265
+ <ref name="validityRevision">
1266
+ <a:documentation>The date and time of issuance of the version of the document
1267
+ for which this claim of validity is made, if applicable</a:documentation>
1268
+ </ref>
938
1269
  </optional>
939
1270
  </element>
940
1271
  </define>
@@ -955,80 +1286,130 @@
955
1286
  </define>
956
1287
  <define name="TypedTitleString">
957
1288
  <optional>
958
- <attribute name="type"/>
1289
+ <attribute name="type">
1290
+ <a:documentation>Type of title given to a bibliographic item. Indicative values include:
1291
+ "alternative": alternate title for the item
1292
+ "original": The original title of the item. Includes the source language title of a translated item
1293
+ "unofficial": A title that has become prevalent but has never been the official or intended title of the item
1294
+ "subtitle": Subsidiary title of the item
1295
+ "main": The default title of the item, privileged in citation</a:documentation>
1296
+ </attribute>
1297
+ </optional>
1298
+ <optional>
1299
+ <attribute name="format">
1300
+ <a:documentation>(legacy attribute) format; can have value text/plain</a:documentation>
1301
+ </attribute>
959
1302
  </optional>
960
- <ref name="LocalizedMarkedUpString"/>
1303
+ <ref name="LocalizedMarkedUpString">
1304
+ <a:documentation>Content of title</a:documentation>
1305
+ </ref>
961
1306
  </define>
962
1307
  <!-- TitleType = ( "alternative" | "original" | "unofficial" | "subtitle" | "main" ) -->
963
1308
  <define name="TypedUri">
1309
+ <a:documentation>URI with type</a:documentation>
964
1310
  <optional>
965
- <attribute name="type"/>
966
- </optional>
967
- <optional>
968
- <attribute name="language"/>
969
- </optional>
970
- <optional>
971
- <attribute name="locale"/>
972
- </optional>
973
- <optional>
974
- <attribute name="script"/>
1311
+ <attribute name="type">
1312
+ <a:documentation>Type of URI</a:documentation>
1313
+ </attribute>
975
1314
  </optional>
1315
+ <ref name="LocalizedStringAttributes"/>
976
1316
  <data type="anyURI"/>
977
1317
  </define>
978
1318
  <define name="DateType">
1319
+ <a:documentation>Type which allows date and time to be specified as either a Gregorian
1320
+ date and time, as specified in ISO 8601, as text, or as both</a:documentation>
979
1321
  <optional>
980
- <attribute name="text"/>
1322
+ <attribute name="text">
1323
+ <a:documentation>Date and time, as specified in text</a:documentation>
1324
+ </attribute>
981
1325
  </optional>
982
1326
  <optional>
983
- <ref name="ISO8601Date"/>
1327
+ <group>
1328
+ <a:documentation>Gregorian date and time, as specified in ISO 8601. Can be used
1329
+ as a canonical interpretation of the date and time given in `text`</a:documentation>
1330
+ <ref name="ISO8601Date"/>
1331
+ </group>
984
1332
  </optional>
985
1333
  </define>
986
1334
  <define name="BibliographicDateType">
1335
+ <a:documentation>Indicates type of date within a bibliographic lifecycle.
1336
+ NOTE: Typically only the `published` date is of interest</a:documentation>
987
1337
  <choice>
988
1338
  <value>published</value>
1339
+ <a:documentation>The date on which the document was published (distributed by the publisher)</a:documentation>
989
1340
  <value>accessed</value>
1341
+ <a:documentation>Date a document was last accessed by the compiler of the bibliographic record; routinely used for online publications.
1342
+ NOTE: Unlike in ISO 690:2021, no distinction is made between
1343
+ "viewed" and "accessed" based on whether the resource is human-readable or machine-readable.)</a:documentation>
990
1344
  <value>created</value>
1345
+ <a:documentation>The date on which the first version of the document was created</a:documentation>
991
1346
  <value>implemented</value>
1347
+ <a:documentation>The date on which the document takes effect. Applies to normative documents</a:documentation>
992
1348
  <value>obsoleted</value>
1349
+ <a:documentation>The date on which the document was obsoleted/</a:documentation>
993
1350
  <value>confirmed</value>
1351
+ <a:documentation>The date on which the document was reviewed and approved by the issuing authority</a:documentation>
994
1352
  <value>updated</value>
1353
+ <a:documentation>The date on which the current version of the document was updated</a:documentation>
995
1354
  <value>corrected</value>
1355
+ <a:documentation>The date on which the current version of the document was corrected, without that correction considered to amount to a full document update</a:documentation>
996
1356
  <value>issued</value>
1357
+ <a:documentation>The date on which the document was issued (authorised for publication by the issuing authority).
1358
+ Is typically differentiated from `published` for normative documents, such as standards and legislation</a:documentation>
997
1359
  <value>transmitted</value>
1360
+ <a:documentation>The date on which the document was broadcast</a:documentation>
998
1361
  <value>copied</value>
1362
+ <a:documentation>The date on which the document physically copied, or recreated without any substantial change in content (allowing for change in medium)</a:documentation>
999
1363
  <value>unchanged</value>
1364
+ <a:documentation>The date on which the document was last renewed or reprinted without any changes in content</a:documentation>
1000
1365
  <value>circulated</value>
1366
+ <a:documentation>The date on which the unpublished document was last circulated officially as a preprint.
1367
+ For standards, this is associated with the latest transition to a formally defined preparation stage,
1368
+ such as Working Draft or Committee Draft</a:documentation>
1001
1369
  <value>adapted</value>
1370
+ <a:documentation>The date on which a document adapted for a new purpose or audience, with some change in content (includes translation)</a:documentation>
1002
1371
  <value>vote-started</value>
1372
+ <a:documentation>The date on which a formal process for approval of a document was initiated. Typically applies to standards documents in draft</a:documentation>
1003
1373
  <value>vote-ended</value>
1374
+ <a:documentation>The date on which a formal process for approval of a document was closed. Typically applies to standards documents in draft</a:documentation>
1004
1375
  <value>announced</value>
1376
+ <a:documentation>The date on which the existence of a document is made public.
1377
+ Applies whether the resource has already been created or not, and whether it is to be published or not</a:documentation>
1005
1378
  <value>stable-until</value>
1379
+ <a:documentation>The document is guaranteed not to be changed or updated until this date</a:documentation>
1006
1380
  </choice>
1007
1381
  </define>
1008
1382
  <define name="bdate">
1383
+ <a:documentation>Significant date in the lifecycle of the bibliographic item, including its production and its access</a:documentation>
1009
1384
  <element name="date">
1010
1385
  <attribute name="type">
1386
+ <a:documentation>The phase of the production of or access to a bibliographic item</a:documentation>
1011
1387
  <choice>
1012
1388
  <ref name="BibliographicDateType"/>
1013
1389
  <text/>
1014
1390
  </choice>
1015
1391
  </attribute>
1016
1392
  <optional>
1017
- <attribute name="text"/>
1393
+ <attribute name="text">
1394
+ <a:documentation>An optional textual description of the date, especially when a Gregorian date is not applicable</a:documentation>
1395
+ </attribute>
1018
1396
  </optional>
1019
1397
  <optional>
1020
1398
  <choice>
1021
1399
  <group>
1022
1400
  <element name="from">
1401
+ <a:documentation>The start of the date range described</a:documentation>
1023
1402
  <ref name="ISO8601Date"/>
1024
1403
  </element>
1025
1404
  <optional>
1026
1405
  <element name="to">
1406
+ <a:documentation>The end of the date range described</a:documentation>
1027
1407
  <ref name="ISO8601Date"/>
1028
1408
  </element>
1029
1409
  </optional>
1030
1410
  </group>
1031
1411
  <element name="on">
1412
+ <a:documentation>The point date described</a:documentation>
1032
1413
  <ref name="ISO8601Date"/>
1033
1414
  </element>
1034
1415
  </choice>
@@ -1036,21 +1417,34 @@
1036
1417
  </element>
1037
1418
  </define>
1038
1419
  <define name="docidentifier">
1420
+ <a:documentation>An identifier of a bibliographic item in an international standard scheme</a:documentation>
1039
1421
  <element name="docidentifier">
1040
- <optional>
1041
- <attribute name="type"/>
1042
- </optional>
1043
- <optional>
1044
- <attribute name="scope"/>
1045
- </optional>
1046
- <optional>
1047
- <attribute name="primary">
1048
- <data type="boolean"/>
1049
- </attribute>
1050
- </optional>
1051
- <ref name="LocalizedMarkedUpString"/>
1422
+ <ref name="DocIdentifierType"/>
1052
1423
  </element>
1053
1424
  </define>
1425
+ <define name="DocIdentifierType">
1426
+ <optional>
1427
+ <attribute name="type">
1428
+ <a:documentation>The scheme or namespace of the identifier</a:documentation>
1429
+ </attribute>
1430
+ </optional>
1431
+ <optional>
1432
+ <attribute name="scope">
1433
+ <a:documentation>The scope of the identifier, in case the identifier does not apply to the document
1434
+ but to a superset or subset of entities; or in case the identifier
1435
+ is for a particular instance of the document, e.g. for a particular format or edition of the document</a:documentation>
1436
+ </attribute>
1437
+ </optional>
1438
+ <optional>
1439
+ <attribute name="primary">
1440
+ <a:documentation>This is a primary identifier for the item, to be used in citation</a:documentation>
1441
+ <data type="boolean"/>
1442
+ </attribute>
1443
+ </optional>
1444
+ <ref name="LocalizedMarkedUpString">
1445
+ <a:documentation>The identifier string</a:documentation>
1446
+ </ref>
1447
+ </define>
1054
1448
  <define name="docnumber">
1055
1449
  <element name="docnumber">
1056
1450
  <text/>
@@ -1058,26 +1452,37 @@
1058
1452
  </define>
1059
1453
  <define name="bclassification">
1060
1454
  <element name="classification">
1061
- <optional>
1062
- <attribute name="type"/>
1063
- </optional>
1064
- <text/>
1455
+ <ref name="DocIdentifierType"/>
1065
1456
  </element>
1066
1457
  </define>
1067
1458
  <define name="bplace">
1459
+ <a:documentation>Place associated with the production of a bibliographic item</a:documentation>
1068
1460
  <element name="place">
1069
- <choice>
1070
- <text/>
1071
- <group>
1072
- <ref name="bibliocity"/>
1073
- <zeroOrMore>
1074
- <ref name="biblioregion"/>
1075
- </zeroOrMore>
1076
- <zeroOrMore>
1077
- <ref name="bibliocountry"/>
1078
- </zeroOrMore>
1079
- </group>
1080
- </choice>
1461
+ <optional>
1462
+ <ref name="bibliocity">
1463
+ <a:documentation>City</a:documentation>
1464
+ </ref>
1465
+ </optional>
1466
+ <zeroOrMore>
1467
+ <ref name="biblioregion">
1468
+ <a:documentation>Region that city is located in, given for disambiguation purposes.</a:documentation>
1469
+ </ref>
1470
+ </zeroOrMore>
1471
+ <zeroOrMore>
1472
+ <ref name="bibliocountry">
1473
+ <a:documentation>Country that city is located in, given for disambiguation purposes.</a:documentation>
1474
+ </ref>
1475
+ </zeroOrMore>
1476
+ <optional>
1477
+ <ref name="formattedPlace">
1478
+ <a:documentation>Name of the place, not broken down semantically</a:documentation>
1479
+ </ref>
1480
+ </optional>
1481
+ <optional>
1482
+ <ref name="uri">
1483
+ <a:documentation>URI in a geographical registry identifying the place</a:documentation>
1484
+ </ref>
1485
+ </optional>
1081
1486
  </element>
1082
1487
  </define>
1083
1488
  <define name="bibliocity">
@@ -1085,6 +1490,11 @@
1085
1490
  <text/>
1086
1491
  </element>
1087
1492
  </define>
1493
+ <define name="formattedPlace">
1494
+ <element name="formattedPlace">
1495
+ <text/>
1496
+ </element>
1497
+ </define>
1088
1498
  <define name="biblioregion">
1089
1499
  <element name="region">
1090
1500
  <ref name="RegionType"/>
@@ -1096,41 +1506,90 @@
1096
1506
  </element>
1097
1507
  </define>
1098
1508
  <define name="RegionType">
1509
+ <a:documentation>Encoding of region in bibliographic `place`. ISO 3166 encoding is recommended</a:documentation>
1099
1510
  <optional>
1100
- <attribute name="iso"/>
1511
+ <attribute name="iso">
1512
+ <a:documentation>ISO 3166 encoding</a:documentation>
1513
+ </attribute>
1101
1514
  </optional>
1102
1515
  <optional>
1103
1516
  <attribute name="recommended">
1517
+ <a:documentation>Whether the region should be included in rendering of the place, for disambiguation</a:documentation>
1104
1518
  <data type="boolean"/>
1105
1519
  </attribute>
1106
1520
  </optional>
1521
+ <optional>
1522
+ <text>
1523
+ <a:documentation>Name of the region</a:documentation>
1524
+ </text>
1525
+ </optional>
1526
+ </define>
1527
+ <define name="CurrencyType">
1528
+ <a:documentation>Code for currencies, taken from ISO 4217</a:documentation>
1107
1529
  <text/>
1108
1530
  </define>
1109
1531
  <define name="bprice">
1532
+ <a:documentation>The price set on accessing the bibliographic item</a:documentation>
1110
1533
  <element name="price">
1111
- <attribute name="currency"/>
1112
- <text/>
1534
+ <attribute name="currency">
1535
+ <a:documentation>The currency denomination for the price</a:documentation>
1536
+ <ref name="CurrencyType"/>
1537
+ </attribute>
1538
+ <text>
1539
+ <a:documentation>The currency amount for the price</a:documentation>
1540
+ </text>
1113
1541
  </element>
1114
1542
  </define>
1115
1543
  <define name="medium">
1544
+ <a:documentation>Information about the medium and transmission of a bibliographic item</a:documentation>
1116
1545
  <element name="medium">
1117
1546
  <optional>
1118
- <ref name="bcontent"/>
1547
+ <ref name="bcontent">
1548
+ <a:documentation>The content type of the bibliographic item, reflecting the form of
1549
+ communication with which it is expressed and perceived. For example,
1550
+ `text`, `video`, `audio`.</a:documentation>
1551
+ <a:documentation>NOTE: This field is intended to convey the
1552
+ Content attribute of the MARC and Resource Description and Access
1553
+ standards, although its values are not restricted to that
1554
+ vocabulary; see http://www.loc.gov/standards/valuelist/rdacontent.html</a:documentation>
1555
+ </ref>
1119
1556
  </optional>
1120
1557
  <optional>
1121
- <ref name="genre"/>
1558
+ <ref name="genre">
1559
+ <a:documentation>The genre of the bibliographic item, as a classification of the
1560
+ type of communication it represents that is more specific than `content` or `BibliographicItem/type`.
1561
+ For example, "statistical dataset"</a:documentation>
1562
+ </ref>
1122
1563
  </optional>
1123
1564
  <optional>
1124
- <ref name="form"/>
1565
+ <ref name="form">
1566
+ <a:documentation>The media type of the bibliographic item, used to access the content
1567
+ of the item, including file format for electronic media.</a:documentation>
1568
+ <a:documentation>NOTE: This field is intended to convey the
1569
+ Media attribute of the MARC and Resource Description and Access
1570
+ standards, although its values are not restricted to that
1571
+ vocabulary; see http://www.loc.gov/standards/valuelist/rdamedia.html
1572
+ IANA Media Types are recommended for electronic resources</a:documentation>
1573
+ </ref>
1125
1574
  </optional>
1126
1575
  <optional>
1127
- <ref name="carrier"/>
1576
+ <ref name="carrier">
1577
+ <a:documentation>The storage medium of the physical representation of the bibliographic item.</a:documentation>
1578
+ <a:documentation>NOTE: This field is intended to convey the
1579
+ Carrier attribute of the MARC and Resource Description and Access
1580
+ standards, although its values are not restricted to that
1581
+ vocabulary; see https://www.loc.gov/standards/valuelist/rdacarrier.html</a:documentation>
1582
+ </ref>
1128
1583
  </optional>
1129
1584
  <optional>
1130
- <ref name="size"/>
1585
+ <ref name="size">
1586
+ <a:documentation>The size of the physical representation of the bibliographic item</a:documentation>
1587
+ </ref>
1131
1588
  </optional>
1132
1589
  <optional>
1133
- <ref name="scale"/>
1590
+ <ref name="scale">
1591
+ <a:documentation>The scale of the cartographic material in the bibliographic item</a:documentation>
1592
+ </ref>
1134
1593
  </optional>
1135
1594
  </element>
1136
1595
  </define>
@@ -1170,9 +1629,19 @@
1170
1629
  </element>
1171
1630
  </define>
1172
1631
  <define name="sizevalue">
1632
+ <a:documentation>The size of a bibliographic item being referred to.
1633
+ A sequence of sizes can be used to indicate different numberings, e.g. xii + 40 pp.,
1634
+ or different kinds of measures, e.g. pages + plates</a:documentation>
1173
1635
  <element name="value">
1174
- <attribute name="type"/>
1175
- <text/>
1636
+ <attribute name="type">
1637
+ <a:documentation>The type of size. Recommended values: page, volume, time (in ISO 8601 duration values),
1638
+ data (including unit), value (free-form string)</a:documentation>
1639
+ </attribute>
1640
+ <optional>
1641
+ <text>
1642
+ <a:documentation>The quantity of the size</a:documentation>
1643
+ </text>
1644
+ </optional>
1176
1645
  </element>
1177
1646
  </define>
1178
1647
  <define name="bibliographic_size">
@@ -1195,46 +1664,80 @@
1195
1664
  </element>
1196
1665
  </define>
1197
1666
  <define name="series">
1667
+ <a:documentation>Series to which a bibliographic item belongs. Series is to be understood broadly,
1668
+ and it includes monograph series, journals, newspapers, and report series within
1669
+ which the bibliographic item has appeared</a:documentation>
1198
1670
  <element name="series">
1199
1671
  <optional>
1200
1672
  <attribute name="type">
1673
+ <a:documentation>The type of series description expressed in this container</a:documentation>
1201
1674
  <ref name="SeriesType"/>
1202
1675
  </attribute>
1203
1676
  </optional>
1204
1677
  <optional>
1205
- <ref name="formattedref"/>
1678
+ <ref name="formattedref">
1679
+ <a:documentation>A pre-formatted version of the series description, incorporating
1680
+ all needed disambiguating information in human-readable format</a:documentation>
1681
+ </ref>
1206
1682
  </optional>
1207
- <ref name="btitle"/>
1683
+ <oneOrMore>
1684
+ <ref name="btitle">
1685
+ <a:documentation>The title of the series</a:documentation>
1686
+ </ref>
1687
+ </oneOrMore>
1208
1688
  <optional>
1209
- <ref name="bplace"/>
1689
+ <ref name="bplace">
1690
+ <a:documentation>The place where the series is issued; used for disambiguation</a:documentation>
1691
+ </ref>
1210
1692
  </optional>
1211
1693
  <optional>
1212
- <ref name="seriesorganization"/>
1694
+ <ref name="seriesorganization">
1695
+ <a:documentation>The organization issuing the series; used for disambiguation</a:documentation>
1696
+ </ref>
1213
1697
  </optional>
1214
1698
  <optional>
1215
- <ref name="abbreviation"/>
1699
+ <ref name="abbreviation">
1700
+ <a:documentation>The abbreviation under which the series is known</a:documentation>
1701
+ </ref>
1216
1702
  </optional>
1217
1703
  <optional>
1218
- <ref name="seriesfrom"/>
1704
+ <ref name="seriesfrom">
1705
+ <a:documentation>The start of the date range when the series has been known under the given title</a:documentation>
1706
+ </ref>
1219
1707
  </optional>
1220
1708
  <optional>
1221
- <ref name="seriesto"/>
1709
+ <ref name="seriesto">
1710
+ <a:documentation>The end of the date range when the series has been known under the given title</a:documentation>
1711
+ </ref>
1222
1712
  </optional>
1223
1713
  <optional>
1224
- <ref name="seriesnumber"/>
1714
+ <ref name="seriesnumber">
1715
+ <a:documentation>The number of the bibliographic item within the series</a:documentation>
1716
+ </ref>
1225
1717
  </optional>
1226
1718
  <optional>
1227
- <ref name="seriespartnumber"/>
1719
+ <ref name="seriespartnumber">
1720
+ <a:documentation>The part-number of the bibliographic item within the series. For example,
1721
+ if the series is a journal, the number is the volume number, and the partnumber is the issue number</a:documentation>
1722
+ </ref>
1228
1723
  </optional>
1229
1724
  <optional>
1230
- <ref name="seriesrun"/>
1725
+ <ref name="seriesrun">
1726
+ <a:documentation>An iteration of numbering of the series, if the series has restarted numbering
1727
+ (as occurs in some journals); referred to as "series" in the context of journals.
1728
+ For example, "n.s." (new series) or "2" indicates
1729
+ that the `number` given for the series applies to the second iteration of numbering</a:documentation>
1730
+ </ref>
1231
1731
  </optional>
1232
1732
  </element>
1233
1733
  </define>
1234
1734
  <define name="SeriesType">
1735
+ <a:documentation>The type of series description given</a:documentation>
1235
1736
  <choice>
1236
1737
  <value>main</value>
1738
+ <a:documentation>Default type: The current, authoritative series description</a:documentation>
1237
1739
  <value>alt</value>
1740
+ <a:documentation>An alternative, potentially historical series description</a:documentation>
1238
1741
  <text/>
1239
1742
  </choice>
1240
1743
  </define>
@@ -1269,40 +1772,63 @@
1269
1772
  </element>
1270
1773
  </define>
1271
1774
  <define name="biblionote">
1775
+ <a:documentation>A note associated with the bibliographic item</a:documentation>
1272
1776
  <element name="note">
1273
1777
  <optional>
1274
- <attribute name="type"/>
1778
+ <attribute name="type">
1779
+ <a:documentation>The class of the note associated with the bibliographic item.
1780
+ May be used to differentiate rendering of notes in bibliographies</a:documentation>
1781
+ </attribute>
1275
1782
  </optional>
1276
- <ref name="LocalizedMarkedUpString"/>
1783
+ <ref name="LocalizedMarkedUpString">
1784
+ <a:documentation>The content of the note</a:documentation>
1785
+ </ref>
1277
1786
  </element>
1278
1787
  </define>
1279
1788
  <define name="bibabstract">
1789
+ <a:documentation>Abstract of bibliographic item</a:documentation>
1280
1790
  <element name="abstract">
1281
- <ref name="LocalizedStringAttrs"/>
1791
+ <ref name="LocalizedStringAttributes"/>
1282
1792
  <choice>
1283
1793
  <oneOrMore>
1284
- <ref name="BasicBlockNoId"/>
1794
+ <ref name="BasicBlockNoId">
1795
+ <a:documentation>Multiple blocks of content</a:documentation>
1796
+ </ref>
1285
1797
  </oneOrMore>
1286
1798
  <oneOrMore>
1287
- <ref name="TextElement"/>
1799
+ <ref name="TextElement">
1800
+ <a:documentation>Single block of content</a:documentation>
1801
+ </ref>
1288
1802
  </oneOrMore>
1289
1803
  </choice>
1290
1804
  </element>
1291
1805
  </define>
1292
1806
  <define name="copyright">
1807
+ <a:documentation>The copyright status of a bibliographic item.</a:documentation>
1293
1808
  <element name="copyright">
1294
- <ref name="from"/>
1809
+ <ref name="from">
1810
+ <a:documentation>The copyright date of the bibliographic item</a:documentation>
1811
+ </ref>
1295
1812
  <optional>
1296
- <ref name="to"/>
1813
+ <ref name="to">
1814
+ <a:documentation>The date when the copyright of the bibliographic item expires</a:documentation>
1815
+ </ref>
1297
1816
  </optional>
1298
1817
  <oneOrMore>
1299
- <ref name="owner"/>
1818
+ <ref name="owner">
1819
+ <a:documentation>The copyright owner for the bibliographic item.</a:documentation>
1820
+ </ref>
1300
1821
  </oneOrMore>
1301
1822
  <optional>
1302
- <ref name="copyright_scope"/>
1823
+ <ref name="copyright_scope">
1824
+ <a:documentation>The extent of the bibliographic item, or contexts of use, for which this
1825
+ assertion of copyright applies. For example, this description may only apply
1826
+ to the preface of a book</a:documentation>
1827
+ </ref>
1303
1828
  </optional>
1304
1829
  </element>
1305
1830
  </define>
1831
+ <!-- TODO potentially should be locality | localityStack -->
1306
1832
  <define name="copyright_scope">
1307
1833
  <element name="scope">
1308
1834
  <text/>
@@ -1319,11 +1845,14 @@
1319
1845
  </element>
1320
1846
  </define>
1321
1847
  <define name="owner">
1848
+ <a:documentation>Copyright owner</a:documentation>
1322
1849
  <element name="owner">
1323
1850
  <ref name="ContributorInfo"/>
1324
1851
  </element>
1325
1852
  </define>
1326
1853
  <define name="DocRelationType">
1854
+ <a:documentation>Type of the relationship between a main document (described in `BibliographicItem`) and a target document
1855
+ Detailed in https://www.relaton.org/model/relations/</a:documentation>
1327
1856
  <choice>
1328
1857
  <value>includes</value>
1329
1858
  <value>includedIn</value>
@@ -1385,19 +1914,25 @@
1385
1914
  </choice>
1386
1915
  </define>
1387
1916
  <define name="docrelation">
1917
+ <a:documentation>Relation between a bibliographic item and another bibliographic item</a:documentation>
1388
1918
  <element name="relation">
1389
1919
  <attribute name="type">
1920
+ <a:documentation>The type of document relation described, using a controlled vocabulary</a:documentation>
1390
1921
  <ref name="DocRelationType"/>
1391
1922
  </attribute>
1392
1923
  <optional>
1393
1924
  <element name="description">
1925
+ <a:documentation>A more complete description of the type of document relation described</a:documentation>
1394
1926
  <ref name="LocalizedMarkedUpString"/>
1395
1927
  </element>
1396
1928
  </optional>
1397
1929
  <element name="bibitem">
1930
+ <a:documentation>The target bibliographic item to which this bibliographic item is described as related to</a:documentation>
1398
1931
  <ref name="ReducedBibliographicItem"/>
1399
1932
  </element>
1400
1933
  <choice>
1934
+ <a:documentation>The extent of the target bibliographic item which is related to this bibliographic item,
1935
+ provided that it is not the entire bibliographic item that is so related</a:documentation>
1401
1936
  <zeroOrMore>
1402
1937
  <ref name="locality"/>
1403
1938
  </zeroOrMore>
@@ -1406,6 +1941,8 @@
1406
1941
  </zeroOrMore>
1407
1942
  </choice>
1408
1943
  <choice>
1944
+ <a:documentation>The extent of this bibliographic item which is related to the target bibliographic item,
1945
+ provided that it is not the entire bibliographic item that is so related</a:documentation>
1409
1946
  <zeroOrMore>
1410
1947
  <ref name="sourceLocality"/>
1411
1948
  </zeroOrMore>
@@ -1416,12 +1953,17 @@
1416
1953
  </element>
1417
1954
  </define>
1418
1955
  <define name="version">
1956
+ <a:documentation>A version of the bibliographic item (within an edition). Can be used for drafts</a:documentation>
1419
1957
  <element name="version">
1420
1958
  <optional>
1421
- <ref name="revision-date"/>
1959
+ <ref name="revision-date">
1960
+ <a:documentation>The date at which the current version of the bibliographic item was produced</a:documentation>
1961
+ </ref>
1422
1962
  </optional>
1423
1963
  <optional>
1424
- <ref name="draft"/>
1964
+ <ref name="draft">
1965
+ <a:documentation>The identifier for the current draft of the bibliographic item</a:documentation>
1966
+ </ref>
1425
1967
  </optional>
1426
1968
  </element>
1427
1969
  </define>
@@ -1440,46 +1982,63 @@
1440
1982
  <text/>
1441
1983
  </element>
1442
1984
  </define>
1985
+ <!--
1986
+ bkeyword = element keyword {
1987
+ LocalizedString |
1988
+ (
1989
+ element vocab { LocalizedString },
1990
+ vocabid+
1991
+ ) |
1992
+ (
1993
+ element taxon { LocalizedString }+,
1994
+ vocabid+
1995
+ )
1996
+ }
1997
+ -->
1443
1998
  <define name="bkeyword">
1999
+ <a:documentation>Keyword for a bibliographic item</a:documentation>
1444
2000
  <element name="keyword">
1445
- <choice>
1446
- <ref name="LocalizedString"/>
1447
- <group>
1448
- <element name="vocab">
1449
- <ref name="LocalizedString"/>
1450
- </element>
1451
- <oneOrMore>
1452
- <ref name="vocabid"/>
1453
- </oneOrMore>
1454
- </group>
1455
- <group>
1456
- <oneOrMore>
1457
- <element name="taxon">
1458
- <ref name="LocalizedString"/>
1459
- </element>
1460
- </oneOrMore>
1461
- <oneOrMore>
1462
- <ref name="vocabid"/>
1463
- </oneOrMore>
1464
- </group>
1465
- </choice>
2001
+ <optional>
2002
+ <element name="vocab">
2003
+ <a:documentation>The keyword as a single, controlled or uncontrolled vocabulary item</a:documentation>
2004
+ <ref name="LocalizedString"/>
2005
+ </element>
2006
+ </optional>
2007
+ <oneOrMore>
2008
+ <element name="taxon">
2009
+ <a:documentation>The keywords as a hierarchical taxonomy. For example, the sequence of `taxon` elements
2010
+ `pump`, `centrifugal pump`, `line shaft pump` represents a taxonomic classification</a:documentation>
2011
+ <ref name="LocalizedString"/>
2012
+ </element>
2013
+ </oneOrMore>
2014
+ <zeroOrMore>
2015
+ <ref name="vocabid">
2016
+ <a:documentation>Identifiers for the keyword as a controlled vocabulary</a:documentation>
2017
+ </ref>
2018
+ </zeroOrMore>
1466
2019
  </element>
1467
2020
  </define>
1468
2021
  <define name="vocabid">
2022
+ <a:documentation>Item in a controlled vocabulary</a:documentation>
1469
2023
  <element name="vocabid">
1470
- <attribute name="type"/>
2024
+ <attribute name="type">
2025
+ <a:documentation>A label for the controlled vocabulary</a:documentation>
2026
+ </attribute>
1471
2027
  <optional>
1472
2028
  <attribute name="uri">
2029
+ <a:documentation>A URI for the controlled vocabulary item</a:documentation>
1473
2030
  <data type="anyURI"/>
1474
2031
  </attribute>
1475
2032
  </optional>
1476
2033
  <optional>
1477
2034
  <element name="code">
2035
+ <a:documentation>The code or identifier for the controlled vocabulary item</a:documentation>
1478
2036
  <text/>
1479
2037
  </element>
1480
2038
  </optional>
1481
2039
  <optional>
1482
2040
  <element name="term">
2041
+ <a:documentation>The term itself for the controlled vocabulary item</a:documentation>
1483
2042
  <text/>
1484
2043
  </element>
1485
2044
  </optional>