Skip to content

Commit

Permalink
Minor editorial changes before finalizing the text for publication
Browse files Browse the repository at this point in the history
  • Loading branch information
@iherman
iherman committed Feb 4, 2017
1 parent 385cf34 commit e4146d2
Showing 1 changed file with 39 additions and 44 deletions.
83 changes: 39 additions & 44 deletions serialization-html-note/index-turtle-not-highlight.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@
<script class='remove'>
var respecConfig = {
specStatus: "WG-NOTE",
shortName: "html-web-annotations",
shortName: "annotation-html",
errata: "https://www.w3.org/annotation/errata/",
editors: [
{ name: "Timothy W. Cole",
Expand Down Expand Up @@ -163,7 +163,7 @@
rawDate: "2016-04-26",
status: "Unofficial Draft"
},
"selector-note": {
"selectors-states": {
"authors": [
"Ivan Herman",
"Robert Sanderson",
Expand Down Expand Up @@ -204,7 +204,7 @@
<p>This Note describes and illustrates potential approaches for including annotations
within HTML documents. Examples also are included illustrating the use within an HTML document
of annotation Selectors as fragment identifiers. (The Working Group's Selectors and States Reference
Note [[selector-note]] defines the syntax used for Selectors as fragment identifiers.)</p>
Note [[selectors-states]] defines the syntax used for Selectors as fragment identifiers.)</p>

<p>The approaches described in this document are incomplete and preliminary. They do not exhaust the full range of feasible options.
The approaches discussed in this note have emerged from Working Group discussions and should be considered no more
Expand Down Expand Up @@ -241,14 +241,14 @@ <h2>Introduction</h2>
that references a segment of an HTML document might usefully be embedded within the same or another HTML document.
In addition to text embedded within the DOM, HTML documents often reference external resources such as
images that are meant to be considered integral parts of an HTML Document when viewed on the Web,
e.g., through the use of the HTML <code>&lt;img&gt;</code> element's src attribute. Approaches discussed in this Note
e.g., through the use of the HTML <code>&lt;img&gt;</code> element's <code>src</code> attribute. Approaches discussed in this Note
would facilitate embedding in HTML an annotation targeting (in the context or scope of a Web page) an image
or other similar Web page component resource external to an HTML document. </p>

<section>
<h3>Scope</h3>
<p>Pending further experimentation, use-case development, incubation and broader collaborative efforts,
this Note stops short of proposing any new, annotation-specific extensions to HTML 5 [[html]].
this Note stops short of proposing any new, annotation-specific extensions to HTML [[html]].
Nor does it propose any new, annotation-specific HTML elements or attributes. To address specific
use cases, possible extensions of HTML have been discussed within the Web Annotation Working Group
and elsewhere, e.g., an informal proposal for new note, notegroup, and noteref HTML elements to better handle
Expand Down Expand Up @@ -304,7 +304,7 @@ <h3>Motivation</h3>

<section>
<h3 id="embed-json-ld">Annotations Embedded as JSON-LD</h3>
<p>JSON-LD [[json-ld]] is the serialization format specified in the Web Annotation Data Model [[annotation-model]].
<p>JSON-LD [[json-ld]] is the serialization format used in the Web Annotation Data Model [[annotation-model]].
HTML can accommodate this serialization format directly via the use of the HTML <code>&lt;script&gt;</code> element with its
<code>type</code> attribute assigned the media type for a Web Annotation:
<code>application/ld+json;profile="http://www.w3.org/ns/anno.jsonld"</code>.
Expand All @@ -319,13 +319,13 @@ <h3 id="embed-json-ld">Annotations Embedded as JSON-LD</h3>
<section>
<h3>Annotating an HTML <code>&lt;div&gt;</code></h3>
<p><span style="font-weight:bold">Use case for Example 1:</span> Mara wants to annotate the transcription of the emblem motto
with its Latin translation. The target of the annotation is the
with its Latin translation. The target of the annotation is the
<code>&lt;div&gt;</code> node of the HTML document that has an <code>id</code> attribute
with the value <code>"mottoTranscription"</code>.
Because the target of the annotation is
a node which has an id attribute, a CSS Selector is appropriate.
The body of the annotation is the plain text of the Latin translation. To embed the body in the annotation, a TextualBody is used.
To identify the annotation itself, an IRI [[rfc3987]] is provided as the value of the annotation's id property.
Because the target of the annotation is
a node which has an <code>id</code> attribute, a CSS Selector is appropriate.
The body of the annotation is the plain text of the Latin translation. To embed the body in the annotation, a <code>TextualBody</code> is used.
To identify the annotation itself, an IRI [[rfc3987]] is provided as the value of the annotation's <code>id</code> property.
It is not required that this IRI be dereferenceable.
</p>

Expand Down Expand Up @@ -362,21 +362,21 @@ <h4>JSON-LD Example 1</h4>
}
&lt;/script&gt;
</pre>
<p class="note"> While an HTML <code>&lt;script&gt;</code> node may itself have an <code>id</code>
attribute, implementers are discouraged from using an HTML URL with fragment identifier to identify an annotation.

<p class="note"> While an HTML <code>&lt;script&gt;</code> node may itself have an <code>id</code>
attribute, implementers are discouraged from using an HTML URL with fragment identifier to identify an annotation.
An HTML fragment identifier is only intended to indicate and help navigate to a specific DOM node in an HTML document
(see HTML5 Recommendation [[html5]] Section 5.6.9, "Navigating to a fragment identifier").
A fragment identifier does not unambiguously identify the contents of this node as a separate resource.
</p>
(see HTML5 Recommendation [[html5]] Section 5.6.9, "Navigating to a fragment identifier").
A fragment identifier does not unambiguously identify the contents of this node as a separate resource.
</p>
</section>

<section>
<h3>Annotating a Web page image</h3>
<p><span style="font-weight:bold">Use case for Example 2</span>: Tim wants to tag the emblem image linked from the
HTML document with an Iconclass descriptor. (Iconclass [[iconclass]] is a linked open data friendly, multilingual classification
system for cultural content.) The body of this annotation is therefore an External Web Resource. To make clear that the image is
being annotated within the context of the Web page describing the emblem, a SpecificResource with a scope property is used
being annotated within the context of the Web page describing the emblem, a <code>SpecificResource</code> with a <code>scope</code> property is used
to express the target of the annotation.
</p>

Expand Down Expand Up @@ -409,12 +409,12 @@ <h4>JSON-LD Example 2</h4>

<section>
<h3>Annotating the <code>&lt;body&gt;</code> of an HTML document</h3>
<p><span style="font-weight:bold">Use case for Example 3</span>: Myung-Ja wants to link
the description of this emblem with another digitized emblem at the University of Illinois.
The other emblem, an external Web resource, is the body of the annotation.
The motivation of the annotation is "linking".
<p><span style="font-weight:bold">Use case for Example 3</span>: Myung-Ja wants to link
the description of this emblem with another digitized emblem at the University of Illinois.
The other emblem, an external Web resource, is the body of the annotation.
The motivation of the annotation is "linking".
The entire <code>&lt;body&gt;</code> node of the HTML document serves as the target of this annotation.
As with Example 1, a CSS Selector is used to express the target.
As with Example 1, a CSS Selector is used to express the target.
</p>
<h4>JSON-LD Example 3</h4>
<pre class="example highlight" title="Annotating the body of a Web page">
Expand Down Expand Up @@ -445,11 +445,11 @@ <h4>JSON-LD Example 3</h4>
&lt;/script&gt;
</pre>
<p class="note">While HTML <code>&lt;script&gt;</code> elements
are allowed in both the <code>&lt;head&gt;</code> node and the <code>&lt;body&gt;</code> node, it is suggested to
add embedded annotations to the <code>&lt;head&gt;</code> node when targeting the whole
of the <code>&lt;body&gt;</code> node of an HTML document; this avoids any potential ambiguity
that might arise from an annotation targeting itself.
</p>
are allowed in both the <code>&lt;head&gt;</code> and the <code>&lt;body&gt;</code> elements, it is suggested to
add embedded annotations to the <code>&lt;head&gt;</code> element when targeting the whole
of the <code>&lt;body&gt;</code> element of an HTML document; this avoids any potential ambiguity
that might arise from an annotation targeting itself.
</p>
</section>
</section>

Expand All @@ -460,13 +460,13 @@ <h3>Annotations Embedded as RDFa</h3>
Instead point to the application...</p>
<p>TODO: Summarize comparitive advantages of this approach, e.g., markup of the target with attributes, etc. ...</p> -->

<p>Another approach of embedding annotations into HTML is to use RDFa [[rdfa-primer]]. The advantage of using RDFa is that the annotation features are mixed with the core HTML content, meaning that, for example, the text in the HTML source can be also re-used as an annotation textual body. In other words, a single resource may become both human visible as well as machine-readable. On the other hand, RDFa is an RDF serialization syntax: the RDF vocabulary described in [[annotation-vocab]] must thefore be used instead of the JSON-LD encoding used in the [[annotation-model]] document. This requirement may be problematic for some users.</p>
<p>Another approach of embedding annotations into HTML is to use RDFa [[rdfa-primer]]. The advantage of using RDFa is that the annotation terms are mixed with the core HTML content, meaning that, for example, the text in the HTML source can be also re-used as an annotation textual body. In other words, a single resource may become both human visible as well as machine-readable. On the other hand, RDFa is an RDF serialization syntax: the RDF vocabulary described in [[annotation-vocab]] must thefore be used instead of the JSON-LD encoding used in the [[annotation-model]] document. This requirement may be problematic for some users.</p>

<h4>Example</h4>

<p>This example is a significantly simplified version of a more complex application that uses an RDFa encoding of annotations within a framework for decentralised article authoring and annotation (see <a href="https://dokie.li/"> for further details</a>). The example shows one of the advantages of RDFa: the “Communities have various…” text, while readable when the corresponding HTML page is displayed, automatically provides the textual body of the annotation. However, the relative complexity of mixing complex RDFa structures with HTML makes it more suitable for automatic code generation (e.g., through authoring systems) rather than manual editing.</p>
<p>This example is a significantly simplified version of a more complex application that uses an RDFa encoding of annotations within a framework for decentralised article authoring and annotation (see <a href="https://dokie.li/"> for further details</a>). The example shows one of the advantages of RDFa: the “Communities have various…” text, while readable when the corresponding HTML page is displayed, automatically provides the textual body of the annotation. The relative complexity of mixing complex RDFa structures with HTML makes it more suitable for automatic code generation (e.g., through authoring systems) rather than manual editing.</p>

<p class="note">The example below assumes that RDFa parsers use the <a href="https://www.w3.org/2011/rdfa-context/rdfa-1.1">RDFa Core Initial Context</a> to understand the predefined prefixes.</p>
<p class="note">The example below relies on the fact that RDFa parsers use the <a href="https://www.w3.org/2011/rdfa-context/rdfa-1.1">RDFa Core Initial Context</a> to understand the predefined prefixes.</p>

<pre id="dokieli-example" class="example" title="Simplified dokieli example">&lt;article resource="" typeof="oa:Annotation"&gt;
&lt;h1 property="schema:name"&gt;Sarven Capadisli &lt;span property="oa:motivatedBy"
Expand Down Expand Up @@ -501,15 +501,12 @@ <h4>Example</h4>
&lt;/section&gt;
&lt;/article&gt;</pre>

<p>This yields, in [[turtle]]:</p>
<p>Interpreting this HTML content yields, in [[turtle]]:</p>

<pre id="dokieli-example-turtle" class="example nohighlight turtle" title="dokieli example in Turtle">
@prefix oa: &lt;http://www.w3.org/ns/oa#&gt; .
@prefix schema: &lt;http://schema.org/&gt; .
@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt; .
@prefix rdfs: &lt;http://www.w3.org/2000/01/rdf-schema#&gt; .
@prefix xml: &lt;http://www.w3.org/XML/1998/namespace&gt; .
@prefix xsd: &lt;http://www.w3.org/2001/XMLSchema#&gt; .

&lt;https://example.org/art&gt; a oa:Annotation ;
schema:name "Sarven Capadisli comments" ;
Expand All @@ -535,12 +532,10 @@ <h4>Example</h4>
oa:renderedVia &lt;https://dokie.li/&gt; .
</pre>

<p>Care should be taken, however, that the exact specification of what it means to mix both RDFa and embedded contents within the same HTML file is not (yet) formally specified. Tools that do understand this type </p>

<section>
<h4>Mixing RDFa with embedded RDF content</h4>

<p>The approach used in <a href="#embed-json-ld"></a> can be combined, within the same HTML content, with the usage of RDFa. It is also possible to use the same approach (i.e., a <code>&lt;script&gt;</code> element with an appropriate media type) to include RDF using other serializations, most notably Turtle (see <a href="https://www.w3.org/TR/turtle/#in-html">Appendix A</a> of the [[turtle]] specification for more details). I.e, it is possible to modify the <a href="#dokieli-example">dokieli example</a> above as follows:</p>
<p>The approach used in <a href="#embed-json-ld"></a> can be combined, within the same HTML content, with the usage of RDFa. It is also possible to use the same approach (namely using a <code>&lt;script&gt;</code> element with an appropriate media type) to include RDF using other serializations, for exaple Turtle (see <a href="https://www.w3.org/TR/turtle/#in-html">Appendix A</a> of the [[turtle]] specification for more details). I.e, it is possible to modify the <a href="#dokieli-example">dokieli example</a> above as follows:</p>

<pre id="dokieli-example-modified" class="example" title="Simplified dokieli example with embedded turtle">&lt;script type="text/turtle"&gt;
@prefix oa: &lt;http://www.w3.org/ns/oa#&gt; .
Expand Down Expand Up @@ -579,16 +574,16 @@ <h4>Mixing RDFa with embedded RDF content</h4>
&lt;/section&gt;
&lt;/article&gt;</pre>

<p>With an appropriate tools, understanding both RDFa and the embedded Turtle, the results would be identical to <a href="#dokieli-example-turtle">Example 5</a>.</p>
<p>With an appropriate tools that understand both RDFa and the embedded Turtle the results is identical to <a href="#dokieli-example-turtle">Example 5</a>.</p>

<p>Care should be taken, however, that the exact details of what it means to mix both RDFa and embedded contents within the same HTML file is not (yet) formally specified. Tools that do understand this type of mix usually parse the various syntaxes into separate RDF Graphs (see [[rdf11-concepts]]) which are then merged following the rules described in the RDF Semantics document&nbsp;[[rdf11-mt]]. This means that, for example, blank nodes are not shared, nor are namespace declarations among the different serializations.</p>
<p>Care should be taken, however, that the exact details of what it means to mix both RDFa and embedded RDF contents within the same HTML file is not (yet) formally specified. Tools that do understand this type of mix usually parse the various syntaxes into separate RDF Graphs (see [[rdf11-concepts]]) which are then merged following the rules described in the RDF Semantics document&nbsp;[[rdf11-mt]]. This means that, for example, blank nodes are not shared, nor are namespace declarations among the different serializations.</p>
</section>
</section>

<section>
<h3>Web Annotation-based Citation URLs</h3>
<p>The Selectors and States Note [[selector-note]] published by the Web Annotation Working Group includes information on encoding
<a data-cite="selector-note#frags">Web Annotation Selectors and State classes as IRI Fragment Identifiers</a>. The following
<p>The Selectors and States Note [[selectors-states]] published by the Web Annotation Working Group includes information on encoding
<a data-cite="selectors-states#frags">Web Annotation Selectors and State classes as IRI Fragment Identifiers</a>. The following
examples show how these URLs could be used to reference portions of a Specific Resource on the Web via IRIs:
</p>
<section>
Expand Down Expand Up @@ -616,7 +611,7 @@ <h3>Example using <code>&lt;blockquote&gt;</code> and <code>&lt;q&gt;</code> tag
all of the quotations (within the <code>&lt;q&gt;</code> tags) exist within the <code>#introduction</code> section referenced
by the surrounding <code>&lt;blockquote&gt;</code>.

<p>The Selectors and States Note [[selector-note]] explains that fragment identifiers are technically defined when the media
<p>The Selectors and States Note [[selectors-states]] explains that fragment identifiers are technically defined when the media
type is specified. However in practice the utilization of fragment identifiers by publishers and developers ranges from
browser state handling to anchoring highlights of quotations (as seen here).</p>

Expand All @@ -625,7 +620,7 @@ <h3>Example using <code>&lt;blockquote&gt;</code> and <code>&lt;q&gt;</code> tag
browser, server, and JavaScript developers may take advantage of these citations identifiers for re-anchoring selection
or extracting (and verifying) quotations made within an HTML document which uses this method.</p>
</section>
<section>
<section>
<h3>Example using an <code>&lt;a&gt;</code> tag</h3>

<p>Using the same methods described above, <code>&lt;a&gt;</code> tags may also be used to express a desired highlight or reference. However,
Expand Down

0 comments on commit e4146d2

Please sign in to comment.