Skip to content

Commit bcff328

Browse files
ihermanmattgarrish
iherman
and
mattgarrish
authored
Added dfn-s to terms, and updated the serialization section (#2880)
* Added dfn-s to terms, and updated the serialization section * Update epub34/annotations/index.html Co-authored-by: Matt Garrish <mattgarrish@users.noreply.github.com> * changed the context URL --------- Co-authored-by: Matt Garrish <mattgarrish@users.noreply.github.com>
1 parent 54c821c commit bcff328

File tree

1 file changed

+41
-70
lines changed

1 file changed

+41
-70
lines changed

‎epub34/annotations/index.html‎

Lines changed: 41 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
profile: "web-platform",
3737
specs:[ "epub-34"]
3838
},
39+
lint: { "no-unused-dfns": false },
3940
localBiblio: {
4041
"epub-ann-ucr": {
4142
"authors": [
@@ -105,8 +106,8 @@ <h1> Subset of the Web Annotation Data Model </h1>
105106
<h2 id="1-annotation"> Annotation </h2>
106107
<section>
107108
<h3 id="1-1-annotation-object"> Annotation Object </h3>
108-
<p> This document retains the following annotation properties from the
109-
<a data-cite="annotation-model#annotations">Annotation object</a> [[annotation-model]]:
109+
<p> The <dfn>Annotation object</dfn> retains the following annotation properties from the
110+
<a data-cite="annotation-model#annotations">Web Annotation object</a> [[annotation-model]]:
110111
</p>
111112
<table class="zebra">
112113
<thead>
@@ -136,51 +137,51 @@ <h3 id="1-1-annotation-object"> Annotation Object </h3>
136137
</tr>
137138
<tr>
138139
<td>
139-
<code> motivation </code>
140+
<code> <dfn>motivation</dfn> </code>
140141
</td>
141142
<td>The motivation for the annotation's creation.</td>
142143
<td>"bookmarking" | "commenting" | "highlighting"</td>
143144
<td>No</td>
144145
</tr>
145146
<tr>
146147
<td>
147-
<code> created </code>
148+
<code> <dfn>created</dfn> </code>
148149
</td>
149150
<td>The time when the annotation was created.</td>
150151
<td> ISO 8601 datetime </td>
151152
<td> Yes </td>
152153
</tr>
153154
<tr>
154155
<td>
155-
<code> modified </code>
156+
<code> <dfn>modified</dfn> </code>
156157
</td>
157158
<td>The time the annotation was modified after creation.</td>
158159
<td> ISO 8601 datetime </td>
159160
<td> No </td>
160161
</tr>
161162
<tr>
162163
<td>
163-
<code> creator </code>
164+
<code> <dfn>creator</dfn> </code>
164165
</td>
165166
<td>The creator of the annotation. This may be a human, an
166167
organization or a software agent.<br></td>
167-
<td> [=Creator=] </td>
168+
<td> [=Creator object=] </td>
168169
<td> No </td>
169170
</tr>
170171
<tr>
171172
<td>
172-
<code> target </code>
173+
<code> <dfn>target</dfn> </code>
173174
</td>
174175
<td>The target content of the annotation.</td>
175-
<td> [=Target=] </td>
176+
<td> [=Target object=] </td>
176177
<td> Yes </td>
177178
</tr>
178179
<tr>
179180
<td>
180-
<code> body </code>
181+
<code> <dfn>body</dfn> </code>
181182
</td>
182183
<td>The annotation body.</td>
183-
<td> [=Body=] </td>
184+
<td> [=Body object=] </td>
184185
<td> No </td>
185186
</tr>
186187
</tbody>
@@ -207,10 +208,7 @@ <h3 id="1-1-annotation-object"> Annotation Object </h3>
207208
<aside class="example" title="Core structure of an EPUB annotation">
208209
<pre>
209210
{
210-
"@context": [
211-
"http://www.w3.org/ns/anno.jsonld",
212-
"https://wwww.w3.org/ns/epub/anno.jsonld"
213-
],
211+
"@context": "https://www.w3.org/ns/epub-anno.jsonld",
214212
"id": "urn:uuid:123-123-123-123",
215213
"type": "Annotation",
216214
"created": "2023-10-14T15:13:28Z",
@@ -228,7 +226,7 @@ <h3 id="1-1-annotation-object"> Annotation Object </h3>
228226
</section>
229227
<section>
230228
<h3 id="1-2-creator"> Creator </h3>
231-
<p> The <dfn>Creator</dfn> of an annotation is a person, an organization or a software agent. </p>
229+
<p> The <dfn>Creator object</dfn> of an annotation is a person, an organization or a software agent. </p>
232230
<p> This document defines the following creator properties: </p>
233231
<table class="zebra">
234232
<thead>
@@ -270,7 +268,7 @@ <h3 id="1-2-creator"> Creator </h3>
270268

271269
<section>
272270
<h3 id="1-3-target"> Target </h3>
273-
<p>The <dfn>Target</dfn> of an annotation associates the annotation with a specific segment of a
271+
<p>The <dfn>Target object</dfn> of an annotation associates the annotation with a specific segment of a
274272
resource in the current publication.</p>
275273
<p> This document defines three target sub-properties: </p>
276274
<table class="zebra">
@@ -285,23 +283,23 @@ <h3 id="1-3-target"> Target </h3>
285283
<tbody>
286284
<tr>
287285
<td>
288-
<code> source </code>
286+
<code> <dfn>source</dfn> </code>
289287
</td>
290288
<td> The identity of the target EPUB resource. </td>
291289
<td> URI </td>
292290
<td> Yes </td>
293291
</tr>
294292
<tr>
295293
<td>
296-
<code> selector </code>
294+
<code> <dfn>selector</dfn> </code>
297295
</td>
298296
<td> The segment of the target EPUB resource that is annotated. </td>
299297
<td> Array of Selector objects </td>
300298
<td> No </td>
301299
</tr>
302300
<tr>
303301
<td>
304-
<code> meta </code>
302+
<code> <dfn>meta</dfn> </code>
305303
</td>
306304
<td> Indications that help locate the segment in the resource. </td>
307305
<td> Meta </td>
@@ -320,10 +318,7 @@ <h4 id="1-3-1-source"> Source </h4>
320318
<aside class="example" title=" the source of the annotation is the relative URL identifying an HTML document in an EPUB">
321319
<pre>
322320
{
323-
"@context": [
324-
"http://www.w3.org/ns/anno.jsonld",
325-
"https://wwww.w3.org/ns/epub/anno.jsonld"
326-
],
321+
"@context": "https://www.w3.org/ns/epub-anno.jsonld",
327322
"type": "Annotation",
328323
"target": {
329324
"source": "OEBPS/text/chapter1.html",
@@ -563,7 +558,7 @@ <h5 id="1-3-3-1-headings"> Headings </h5>
563558
<section>
564559

565560
<h3 id="1-4-body"> Body </h3>
566-
<p>The <dfn>Body</dfn> of an annotation contains plain text, style, and optional tags.</p>
561+
<p>The <dfn>Body object</dfn> of an annotation contains plain text, style, and optional tags.</p>
567562
<p>This document specifies the following sub-properties:</p>
568563
<table class="zebra">
569564
<thead>
@@ -602,15 +597,15 @@ <h3 id="1-4-body"> Body </h3>
602597
</tr>
603598
<tr>
604599
<td>
605-
<code> color </code>
600+
<code> <dfn>color</dfn> </code>
606601
</td>
607602
<td> The color of the annotation; yellow by default. </td>
608603
<td> "pink" | "orange" | "yellow" | "green" | "blue" | "purple" </td>
609604
<td> No </td>
610605
</tr>
611606
<tr>
612607
<td>
613-
<code> highlight </code>
608+
<code> <dfn>highlight</dfn> </code>
614609
</td>
615610
<td> The style of the annotation; solid background by default. </td>
616611
<td> "solid" | "underline" | "strikethrough" | "outline" </td>
@@ -634,7 +629,7 @@ <h3 id="1-4-body"> Body </h3>
634629
</tr>
635630
<tr>
636631
<td>
637-
<code> tags </code>
632+
<code> <dfn>tags</dfn> </code>
638633
</td>
639634
<td> Free text categorizing the annotation. </td>
640635
<td> Array of string </td>
@@ -648,7 +643,7 @@ <h3 id="1-4-body"> Body </h3>
648643
<aside class="example" title="An annotation Body">
649644
<pre>
650645
{
651-
"@context": "http://www.w3.org/ns/anno.jsonld",
646+
"@context": "https://www.w3.org/ns/epub-anno.jsonld",,
652647
"type": "Annotation",
653648
"body": {
654649
"type": "TextualBody",
@@ -679,7 +674,7 @@ <h2 id="2-annotation-set"> Annotation Set </h2>
679674
a Zip package. The <code>AnnotationCollection</code> provides a
680675
way to retrieve annotations via a REST API and is, therefore, intrinsically paginated.</p>
681676

682-
<p> The <dfn>AnnotationSet</dfn> object contains: </p>
677+
<p> The <dfn>AnnotationSet</dfn> contains: </p>
683678
<table class="zebra">
684679
<thead>
685680
<tr>
@@ -709,15 +704,15 @@ <h2 id="2-annotation-set"> Annotation Set </h2>
709704
</tr>
710705
<tr>
711706
<td>
712-
<code>generator</code>
707+
<code><dfn>generator</dfn></code>
713708
</td>
714709
<td> The agent responsible for the generation of the object serialization. </td>
715710
<td> [=Generator=] </td>
716711
<td> No </td>
717712
</tr>
718713
<tr>
719714
<td>
720-
<code>about</code>
715+
<code><dfn>about</dfn></code>
721716
</td>
722717
<td> Information relative to the publication. </td>
723718
<td> [=About=] </td>
@@ -733,15 +728,15 @@ <h2 id="2-annotation-set"> Annotation Set </h2>
733728
</tr>
734729
<tr>
735730
<td>
736-
<code>title</code>
731+
<code><dfn>title</dfn></code>
737732
</td>
738733
<td> A title to help identifying the set. </td>
739734
<td> string </td>
740735
<td> No </td>
741736
</tr>
742737
<tr>
743738
<td>
744-
<code>items</code>
739+
<code><dfn>items</dfn></code>
745740
</td>
746741
<td> The annotations of the set. </td>
747742
<td> Array of Annotation objects </td>
@@ -752,7 +747,7 @@ <h2 id="2-annotation-set"> Annotation Set </h2>
752747

753748
<section>
754749
<h3 id="2-1-generator"> Generator </h3>
755-
<p>The <dfn>Generator</dfn> object contains information relative to the software from which the
750+
<p>The <dfn>Generator object</dfn> contains information relative to the software from which the
756751
serialized annotation has been produced.</p>
757752
<table class="zebra">
758753
<thead>
@@ -802,7 +797,7 @@ <h3 id="2-1-generator"> Generator </h3>
802797
</section>
803798
<section>
804799
<h3 id="2-2-about"> About </h3>
805-
<p> The <dfn>About</dfn> object contains information relative to the publication. Such metadata is
800+
<p> The <dfn>About object</dfn> contains information relative to the publication. Such metadata is
806801
intended to help associate an annotation set with a publication: </p>
807802
<table class="zebra">
808803
<thead>
@@ -870,10 +865,7 @@ <h3 id="2-2-about"> About </h3>
870865
<aside class="example" title="An AnnotationSet containing one annotation">
871866
<pre>
872867
{
873-
"@context": [
874-
"http://www.w3.org/ns/anno.jsonld",
875-
"https://wwww.w3.org/ns/epub/anno.jsonld"
876-
],
868+
"@context": "https://www.w3.org/ns/epub-anno.jsonld",
877869
"id": "urn:uuid:123-123-123-123",
878870
"type": "AnnotationSet",
879871
"generator": "https://github.com/edrlab/thorium-reader/releases/tag/v3.1.0",
@@ -918,31 +910,19 @@ <h3 id="2-3-serialization"> Serialization </h3>
918910
</p>
919911

920912
<p>
921-
Following the requirements of JSON-LD, each annotation file (whether a single annotation or an annotation set) MUST start with a context declaration referring to the following contexts:
913+
Following the requirements of JSON-LD, each annotation file (whether a single annotation or an annotation set) MUST
914+
start with a context declaration referring to the following, EPUB Annotation specific context:
915+
<code>https://www.w3.org/ns/epub-anno.jsonld</code>.
916+
This context file imports (using the <a data-cite="json-ld11#imported-contexts">imported contexts</a> feature of JSON-LD)
917+
the "core" context file of the [[[annotation-model]]] [[annotation-model]], i.e., <code>https://www.w3.org/ns/anno.jsonld</code>.
918+
The EPUB Annotation specific context file contains terms extending, an sometimes overriding the terms
919+
in the core annotation context file, as defined in this specification.
922920
</p>
923921

924-
<table class="zebra">
925-
<tr>
926-
<th>Context URL</th>
927-
<th>Description</th>
928-
</tr>
929-
<tr>
930-
<td><code>http://www.w3.org/ns/anno.jsonld</code></td>
931-
<td>Core context file for the [[[annotation-model]]].</td>
932-
</tr>
933-
<tr>
934-
<td><code>https://wwww.w3.org/ns/epub/anno.jsonld</code></td>
935-
<td>Specific terms for EPUB Annotions extending, an sometimes overriding the terms in the core context file.</td>
936-
</tr>
937-
</table>
938-
939922
<aside class="example" title="Required context declaration">
940923
<pre>
941924
{
942-
"@context": [
943-
"http://www.w3.org/ns/anno.jsonld",
944-
"https://wwww.w3.org/ns/epub/anno.jsonld"
945-
],
925+
"@context": "https://www.w3.org/ns/epub-anno.jsonld",
946926
"id": "urn:uuid:123-123-123-123",
947927
…
948928
}
@@ -954,16 +934,7 @@ <h3 id="2-3-serialization"> Serialization </h3>
954934
based on the shape of the annotation or the annotation set. Such implementations may safely ignore the context
955935
declarations and are not required to dereference the respective URLs.
956936
</p>
957-
958-
959-
<p class="issue">The problem has been raised that implementers/users will forget to add two context declarations.
960-
A possibility is to use the <a data-cite="json-ld11#imported-contexts">imported contexts</a> feature of JSON-LD, where the
961-
new context file would import the first one. <br>
962-
In theory, it is also possible to copy the relevant declarations of the core annotation context into the new one, but that approach may be too brittle (and would also require manual, and error prone, editorial work).
963-
<br>
964-
Both approaches would, however, simplify the structure of this section, too.
965-
</p>
966-
</section>
937+
</section>
967938

968939
<section>
969940
<h1 id="3-embedding-annotations-in-publications"> Embedding annotations in

0 commit comments

Comments
 (0)