This is an automated email from the ASF dual-hosted git repository.
gerben pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-annotator.wiki.git
The following commit(s) were added to refs/heads/master by this push:
new a738931 Further cleanup
a738931 is described below
commit a738931f9cf8b22525843d570fc529c24ca221c9
Author: Gerben <[email protected]>
AuthorDate: Thu Apr 16 16:23:54 2020 +0200
Further cleanup
Note the page LDP-and-Web-Annotation-Protocol-Implementations has moved to
become issue #70.
---
Home.md | 11 ++---
LDP-and-Web-Annotation-Protocol-Implementations.md | 10 -----
Overview-(WIP).md | 48 ----------------------
Planning.md | 14 +++++--
Project overview.md | 26 ++++++++++++
5 files changed, 42 insertions(+), 67 deletions(-)
diff --git a/Home.md b/Home.md
index 6e4bda0..5a83d2e 100644
--- a/Home.md
+++ b/Home.md
@@ -1,12 +1,13 @@
> Apache Annotator provides annotation enabling code for browsers, servers,
> and humans.
-Annotator has been incubating since 2016-08-30 following this
[[proposal|Proposal]] ([original
location](https://wiki.apache.org/incubator/AnnotatorProposal)).
+The main places for information are the website
<https://annotator.apache.org>, and [developer mailing
list](https://lists.apache.org/[email protected]). This wiki
is mainly used for keeping shared notes and collaborative drafting.
-## [[Planning|Planning]]
+## About this project
-The [[Planning page|Planning]] has our basic road map (for now). Please send
your feedback to the dev@ list! We'd love to hear from you!
+* A preliminary [[Project overview]].
+* The [[Planning]] page sketches a possible road map.
+* Annotator has been incubating since 2016-08-30 following this [[Proposal]].
-## Friends and Neighbors
+## About related projects
* [[Other Web Annotation Projects]] - other folks using Web Annotation Data
Model documents as input or output
-* [[LDP and Web Annotation Protocol Implementations]]
\ No newline at end of file
diff --git a/LDP-and-Web-Annotation-Protocol-Implementations.md
b/LDP-and-Web-Annotation-Protocol-Implementations.md
deleted file mode 100644
index 3bbbd0b..0000000
--- a/LDP-and-Web-Annotation-Protocol-Implementations.md
+++ /dev/null
@@ -1,10 +0,0 @@
-We are currently considering using [LDP](https://www.w3.org/TR/ldp/) (or
potentially [Web Annotation
Protocol](https://www.w3.org/TR/annotation-protocol/), which is an extension to
LDP) as our persistence abstraction. This is a page for notes about interesting
implementations of those specs or other related information.
-
-### Web Annotation Protocol implementations
- - https://github.com/azaroth42/MangoServer
-
-### LDP implementations
- - https://www.trellisldp.org/
- - http://marmotta.apache.org/
- - http://callimachusproject.org/
- - https://virtuoso.openlinksw.com/
diff --git a/Overview-(WIP).md b/Overview-(WIP).md
deleted file mode 100644
index fc73bb0..0000000
--- a/Overview-(WIP).md
+++ /dev/null
@@ -1,48 +0,0 @@
-With Web Annotation systems, we often talk about at least three different
aspects:
-1. Managing annotations: finding, obtaining, storing, publishing.
-2. (De)referencing selectors:
- - Describing a specific segment of a document to refer to it unambiguously,
thus creating a [selector](https://www.w3.org/TR/annotation-model/#selectors).
- - Anchoring a selector on a given document, to find back the segment it
points to.
-3. The human interface design for viewing and creating annotations.
-
-These can be considered as orthogonal problems, asking for orthogonal
solutions.
-
-## Referencing/Dereferencing selectors
-
-This project initially focusses on the second aspect, referencing &
dereferencing. Correspondingly, it provides functions of two types:
-
-```
-anchorSelector({document, selector}) => segment
-
-createSelector({document, segment}) => selector
-```
-
-In the case of an HTML DOM, a `segment` corresponds to a
[`Range`](https://developer.mozilla.org/en-US/docs/Web/API/Range) object.
-**Question**: Should this be a list of Ranges, or an object that can be
converted into Range(s) (`anchorSelector(args).toRange()`)? Do we want to plan
ahead for e.g. a composite selector that targets both a piece of text and some
pixels inside an image?
-
-There are two 'magic' functions, that do a best-effort job to handle any type
of selectors and content type. Depending on these types, they invoke different
functions to find/describe the segment in the DOM. For more control, these
functions can also be called directly, e.g.:
-```
-anchorTextQuoteSelector({document, selector}) => segment
-```
-
-Selectors can refine other selectors, and anchoring can thus also be performed
within a segment of a document:
-```
-anchorTextQuoteSelector({document, selector, segment}) => segment
-```
-
-**Q**: Do we want more complexity here, to allow for e.g. backtracking when a
refinement cannot anchor?
-
-**Q**: @tilgovi: Didn't we come up with some beautiful abstraction, a bit like
middleware/monoids/something? Is that relevant here?
-
-**Q**: How do we run createSelector with more control? E.g. preferences for
robustness vs conciseness?
-
-
-## Specific Resources(?)
-
-- Converting a SpecificResource to a URL with fragment identifier, and vice
versa.
-```
-urlToSpecificResource({url}) => specificResource
-
-specificResourceToUrl({specificResource}) => url
-```
-**Q**: or do we rather have this convert between selector and fragId? That
gets a bit weird when both selectors and states are to be supported; given a
fragId, it would have to return a SelectorOrState object; and given a
selectorOrState it would have to guess from its `type` which one it is (unless
we make separate functions: `selectorToFragId`, `stateToFragId`).
diff --git a/Planning.md b/Planning.md
index 5dc3140..e22c280 100644
--- a/Planning.md
+++ b/Planning.md
@@ -1,12 +1,14 @@
The foundation laid by Annotator.js, the Open Annotation Community Group, the
Web Annotation Working Group, and their surrounding communities has generated
increasing interest in Web Annotation tooling (on and off the Web). Apache
Annotator appears in this timeline now to provide "minimal effort" integration
for the core components of Web Annotation. Below is a **proposed** plan for
building off that foundation and history and toward a diverse world of
implementations and usage scenarios.
+Please send your feedback to the developer mailing list! We'd love to hear
from you!
+
### Web Annotation in the Browser
#### Phase 0
-**annotation.js -** parses and manipulates a [Web Annotation Data Model
JSON-LD document](https://www.w3.org/TR/annotation-model/)
+**annotation.js ** - parses and manipulates a [Web Annotation Data Model
JSON-LD document](https://www.w3.org/TR/annotation-model/)
-* provides minimal interface for reading and manipulating the JSON-LD
+* provides minimal interface for reading and manipulating the JSON-LD
* uses selector.js and resource.js helper libraries
**selector.js** - manipulates [Web Annotation
Selectors](https://www.w3.org/TR/annotation-model/#selectors) and their
connection/relationship to the DOM
@@ -17,14 +19,18 @@ The foundation laid by Annotator.js, the Open Annotation
Community Group, the We
* can determine if Selector is "orphaned" (unable to be re-anchored)
* can return [Web Annotation Fragment
Identifiers](http://w3c.github.io/web-annotation/selector-note/#frags)
+<!-- (this is no longer discussed?)
**resource.js** - parses and manipulates External and [Specific
Resource](https://www.w3.org/TR/annotation-model/#specific-resources) data
* utility for building and managing Web Resource (external or specific)
related information
* works for generating both Target and Body data
+-->
#### Phase **1**
-...build utilities for State, Style, Choice, List, Composite, etc.
+...build tools for managing a collection of annotations relating to a
document; anchoring all at once or sequentially, efficiently re-anchoring them
when the document changes, etc.
+
+...build utilities for other parts of the Web Annotation spec, such as State,
Style, Choice, List, Composite, etc.
### Web Annotation on the Server
@@ -38,4 +44,4 @@ Utilities and tools for working with Web Annotation data
wherever people find it
* email?
* phones?
* encoded in HTML? EPUB?
-* extracted from PDFs?
\ No newline at end of file
+* extracted from PDFs?
diff --git a/Project overview.md b/Project overview.md
new file mode 100644
index 0000000..cb6dd94
--- /dev/null
+++ b/Project overview.md
@@ -0,0 +1,26 @@
+*This is a preliminary overview of the scope of the project, and is open to
change*
+
+With Web Annotation systems, we often talk about at least three different
aspects:
+1. Managing annotations: finding, obtaining, storing, publishing.
+2. (De)referencing selectors:
+ - Describing a specific segment of a document to refer to it unambiguously,
thus creating a [selector](https://www.w3.org/TR/annotation-model/#selectors).
+ - Anchoring a selector on a given document, to find back the segment it
points to.
+3. The human interface design for viewing and creating annotations.
+
+These can be considered as orthogonal problems, asking for orthogonal
solutions.
+
+This project initially focusses on the second aspect, referencing &
dereferencing, as this is a shared concern for many applications, and important
to collaborate on to ensure applications’ interoperability. The other two
mentioned aspects are more often dependent on an application’s specific design,
the frameworks it uses, etcetera.
+
+## Referencing/Dereferencing selectors
+
+This means that we create functions for transforming between selector (JSON)
objects and some environment-specific object representing the specific segment
of the document. In the case of an HTML DOM (our main focus), a `segment` would
be a [`Range`](https://developer.mozilla.org/en-US/docs/Web/API/Range) object.
+
+The rough API may thus look like this:
+
+```
+anchorSelector({ document, selector }) => segment
+
+createSelector({ document, segment }) => selector
+```
+
+As there are different types of selectors (e.g. TextQuoteSelector,
CssSelector), there should be functions for each, which can be composed to
create a function that can handle various types.
