You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@annotator.apache.org by ge...@apache.org on 2020/04/16 14:24:50 UTC
[incubator-annotator.wiki] branch master updated: Further cleanup
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 7658eec Further cleanup
7658eec is described below
commit 7658eece251e52be49b397a09c409dbddf96e469
Author: Gerben <ge...@treora.com>
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 | 12 +++---
LDP-and-Web-Annotation-Protocol-Implementations.md | 10 -----
Overview-(WIP).md | 48 ----------------------
Planning.md | 14 +++++--
Project overview.md | 26 ++++++++++++
5 files changed, 43 insertions(+), 67 deletions(-)
diff --git a/Home.md b/Home.md
index 6e4bda0..879b076 100644
--- a/Home.md
+++ b/Home.md
@@ -1,12 +1,14 @@
> 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/list.html?dev@annotator.apache.org). 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
+* [[LDP and Web Annotation Protocol Implementations]]
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.