Skip to content

Commit 385cf34

Browse files
ihermaniherman
authored
Merge pull request #410 from tcole3/gh-pages
Fixes per WG Call
2 parents 808e6cf + 492cc0b commit 385cf34

File tree

3 files changed

+106
-274
lines changed

3 files changed

+106
-274
lines changed

‎serialization-html-note/index-respec.html

Lines changed: 32 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,6 @@
111111
var respecConfig = {
112112
specStatus: "WG-NOTE",
113113
shortName: "html-web-annotations",
114-
subtitle: "Reference Note",
115114
errata: "https://www.w3.org/annotation/errata/",
116115
editors: [
117116
{ name: "Timothy W. Cole",
@@ -369,74 +368,6 @@

Motivation

369368
dl>
370369
p>
371370
section>
372-
373-
<section>
374-
<h3>Model and Vocabulary Conformanceh3>
375-
<p>The Web Annotation Recommendations constrain approaches used for embedding annotations in HTML:p>
376-
<ul>
377-
<li>An annotation must have exactly one IRI that identifies it. It is not required that this IRI be de-referenceable.li>
378-
<li>If an annotation is disseminated independently from the HTML document, the requirements of
379-
the Data Model [[annotation-model]] Section 3.3.7 (Other Identities) must be observed.li>
380-
<li>TODO? put here the salient points from the discussion of context documents and vocab from issue #347li>
381-
<li>TODO? RDF constraints?li>
382-
ul>
383-
section>
384-
385-
<section>
386-
<h3>Terminologyh3>
387-
<p>TODO: add / subtract additional terminology as needed.p>
388-
<dl>
389-
<dt><dfn data-lt="IRI|IRIs">IRIdfn>dt>
390-
<dd>An <a>IRIa>, or Internationalized Resource Identifier, is an extension to the URI specification to allow characters from Unicode, whereas URIs must be made up of a subset of ASCII characters. There is a mapping algorithm for translating between IRIs and the equivalent encoded URI form. IRIs are defined by [[rfc3987]].dd>
391-
392-
<dt><dfn data-lt="Resource|Resources">Resourcedfn>dt>
393-
<dd>An item of interest that MAY be identified by an <a>IRIa>.dd>
394-
395-
<dt><dfn data-lt="Web Resource|Web Resources">Web Resourcedfn>dt>
396-
<dd>A <a>Resourcea> that MUST be identified by an <a>IRIa>, as described in the Web Architecture [[webarch]]. Web Resources MAY be dereferencable via their IRI.dd>
397-
398-
<dt><dfn data-lt="External Web Resource|External Web Resources">External Web Resourcedfn>dt>
399-
<dd>A <a>Web Resourcea> which is not part of the representation the selection, such as a web page, image, or video. External Web Resources are dereferencable from their <a>IRIa>.dd>
400-
401-
<dt><dfn data-lt="segment">Segment (of Interest)dfn>dt>
402-
<dd>The part of the <a href="#dfn-source" class="internalDFN" data-link-type="dfn">Sourcea>
403-
resource that is selected using a Selector.
404-
dd>
405-
406-
<dt><dfn data-dfn-type="dfn" id="dfn-source">Sourcedfn>dt>
407-
<dd>The overall <a href="#dfn-web-resource" class="internalDFN" data-link-type="dfn">Web Resourcea>
408-
whose selection is refined through the usage of
409-
<a href="#dfn-selector" class="internalDFN" data-link-type="dfn">Selectorsa> or
410-
<a href="#dfn-state" class="internalDFN" data-link-type="dfn">Statesa>.
411-
dd>
412-
413-
<dt><dfn data-lt="Selector|Selectors">Selectordfn>dt>
414-
<dd>An object used to describe how to determine the Segment from within the
415-
<a href="#dfn-source" class="internalDFN" data-link-type="dfn">Sourcea> resource
416-
dd>
417-
418-
<dt><dfn data-lt="State|States">Statedfn>dt>
419-
<dd>object is used to describe how to determine the state of interest from within the
420-
<a href="#dfn-source" class="internalDFN" data-link-type="dfn">Sourcea> resource
421-
dd>
422-
423-
<dt><dfn data-lt="Property|Properties">Propertydfn>dt>
424-
<dd>A feature of a <a>Resourcea>, that often has a particular data type. In the model sections, the term "Property" is used to refer to only those features which are <em>notem> <a>Relationshipsa> and instead have a literal value such as a string, integer, or date. The valid values for a Property are thus any data type other than object, or an array containing members of that data type if more than one is allowed.dd>
425-
426-
<dt><dfn data-lt="Relationship|Relationships">Relationshipdfn>dt>
427-
<dd>In the model sections, the term "Relationship" is used to distinguish those features that refer to other <a>Resourcesa>, either by reference to the <a>Resourcea>'s <a>IRIa> or by including a description of the <a>Resourcea> in the representation. The valid values for a Relationship are: a quoted string containing an IRI, an object that has the "id" property, or an array containing either of these if more than one is allowed.dd>
428-
429-
<dt><dfn data-lt="Class|Classes">Classdfn>dt>
430-
<dd><a>Resourcesa> may be divided, conceptually, into groups called "classes"; members of a class are known as <a>Instancesa> of that class. Resources are associated with a particular class through <a>typinga>. Classes are identified by <a>IRIsa>, i.e., they are also <a>Web Resourcesa> themselves.dd>
431-
432-
<dt><dfn data-lt="type|types|typing">Typedfn>dt>
433-
<dd>A special <a>Relationshipa> that associates an <a>Instancea> of a class to the <a>Classa> it belongs to.dd>
434-
435-
<dt><dfn data-lt="Instance|Instances">Instancedfn>dt>
436-
<dd>An element of a group of <a>Resourcesa> represented by a particular <a>Classa>.dd>
437-
438-
dl>
439-
section>
440371
section>
441372

442373
<section>
@@ -449,20 +380,22 @@

Annotations Embedded as JSON-LD

449380

450381
<p>The following three annotations are all embedded in a single HTML document. This document describes a digital image created by
451382
scanning a page from a Renaissance-era book; the object scanned was known as an emblem. A JPEG image of the emblem is linked
452-
from the HTML document using an <code><img>code> element. A transcription of the German language text of the emblem
383+
from the HTML document using an <code><img>code> element. A transcription of the German language text of the emblem's
453384
motto (i.e., the emblem's caption) is included in the HTML document.
454385
p>
455386

456387
<section>
457-
<h3>Annotating the content of an HTML <code><div>code> elementh3>
458-
<p><span style="font-weight:bold">Use case for Example 1:span> Mara wants to annotate the transcription of the emblem motto
459-
with its Latin translation. The target of the annotation is the motto transcription which is contained in a
460-
<code><div>code> element within the HTML document that has an <code>idcode> attribute
461-
with the value <code>"mottoTranscription"code>.
462-
The body of the annotation is the plain text of the Latin translation. Because the target of the annotation is contained
463-
within an element of the HTML document which has an id attribute, a CSS Selector can be used to exactly identify the
464-
segment of the HTML document that is being targeted by the annotation. To embed the body of the annotation, a TextualBody is used.
465-
p>
388+
<h3>Annotating an HTML <code><div>code>h3>
389+
<p><span style="font-weight:bold">Use case for Example 1:span> Mara wants to annotate the transcription of the emblem motto
390+
with its Latin translation. The target of the annotation is the
391+
<code><div>code> node of the HTML document that has an <code>idcode> attribute
392+
with the value <code>"mottoTranscription"code>.
393+
Because the target of the annotation is
394+
a node which has an id attribute, a CSS Selector is appropriate.
395+
The body of the annotation is the plain text of the Latin translation. To embed the body in the annotation, a TextualBody is used.
396+
To identify the annotation itself, an IRI [[rfc3987]] is provided as the value of the annotation's id property.
397+
It is not required that this IRI be dereferenceable.
398+
p>
466399

467400
<h4>JSON-LD Example 1h4>
468401
<pre class="example highlight" title="Annotating a transcribed motto">
@@ -497,6 +430,13 @@

JSON-LD Example 1

497430
}
498431
</script>
499432
pre>
433+
434+
<p class="note"> While an HTML <code><script>code> node may itself have an <code>idcode>
435+
attribute, implementers are discouraged from using an HTML URL with fragment identifier to identify an annotation.
436+
An HTML fragment identifier is only intended to indicate and help navigate to a specific DOM node in an HTML document
437+
(see HTML5 Recommendation [[html5]] Section 5.6.9, "Navigating to a fragment identifier").
438+
A fragment identifier does not unambiguously identify the contents of this node as a separate resource.
439+
p>
500440
section>
501441

502442
<section>
@@ -536,13 +476,13 @@

JSON-LD Example 2

536476
section>
537477

538478
<section>
539-
<h3>Linking the <code><body>code> an HTML Documenth3>
540-
<p><span style="font-weight:bold">Use case for Example 3span>: Myung-Ja wants to link the description of this emblem
541-
to another emblem digitized at the University of Illinois. As with Example 1, a CSS Selector is
542-
used to express the target of this annotation. While HTML <code><script>code> elements
543-
are allowed in both the HTML <code><head>code> and the HTML <code><body>code> elements, it is suggested to
544-
add embedded annotations to the <code><head>code> element when targeting the whole or any part of the <code><body>code>
545-
element of an HTML document; this avoids any potential ambiguity that might arise from an annotation targeting itself.
479+
<h3>Annotating the <code><body>code> of an HTML documenth3>
480+
<p><span style="font-weight:bold">Use case for Example 3span>: Myung-Ja wants to link
481+
the description of this emblem with another digitized emblem at the University of Illinois.
482+
The other emblem, an external Web resource, is the body of the annotation.
483+
The motivation of the annotation is "linking".
484+
The entire <code><body>code> node of the HTML document serves as the target of this annotation.
485+
As with Example 1, a CSS Selector is used to express the target.
546486
p>
547487
<h4>JSON-LD Example 3h4>
548488
<pre class="example highlight" title="Annotating the body of a Web page">
@@ -572,6 +512,12 @@

JSON-LD Example 3

572512
}
573513
</script>
574514
pre>
515+
<p class="note">While HTML <code><script>code> elements
516+
are allowed in both the <code><head>code> node and the <code><body>code> node, it is suggested to
517+
add embedded annotations to the <code><head>code> node when targeting the whole
518+
of the <code><body>code> node of an HTML document; this avoids any potential ambiguity
519+
that might arise from an annotation targeting itself.
520+
p>
575521
section>
576522
section>
577523

0 commit comments

Comments
 (0)