This is an automated email from the ASF dual-hosted git repository. randall pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-annotator.git
commit 832a66417f367b2fabb1101159a741d4ae7aaf83 Author: Randall Leeds <[email protected]> AuthorDate: Sat Sep 19 21:28:43 2020 -0700 Update the README --- README.md | 72 +++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index a7d0698..7f850ec 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,44 @@ # [Apache Annotator](http://annotator.apache.org/) (incubating) [](https://travis-ci.org/apache/incubator-annotator) -> Apache Annotator provides annotation enabling code for browsers, servers, -> and humans. - -* [`dev@` Mailing List archive](http://mail-archives.apache.org/mod_mbox/incubator-annotator-dev/) -* [Issue Tracker](https://github.com/apache/incubator-annotator/issues) -* [Wiki](https://github.com/apache/incubator-annotator/wiki) +Apache Annotator (incubating) provides libraries to enable annotation related +software, with an initial focus on identification of textual fragments in +browser environments. ## Usage -We're currently pre-releasing development copies of each library that makes up -the sum total of Apache Annotator's code. You can grab any of them from our -[npm organization](https://www.npmjs.com/org/annotator). +The Apache Annotator project is written in TypeScript, but the project is +compiled and distributed in CommonJS and ECMAScript Module formats. -```sh -$ # for example... -$ npm install --save @annotator/dom -``` +The project is made up of multiple packages. Install the `apache-annotator` +package, which includes all sub-packages, or install individual packages from +the `@annotator` scope. -##### Requirements +Import packages from either `apache-annotator/package` or `@annotator/package`. -- [node](https://nodejs.org) ^10 || ^11 || ^12 || >=13.7 -- [yarn](https://www.yarnpkg.com/) ^1.5 +Currently, the following sub-packages are part of the project: + +### `@annotator/dom` + +This package contains functions for creating and resolving Web Annotation +Selectors in DOM environments. + +### `@annotator/selector` +This package contains generic utilities for composing functions that create +and resolve Web Annotation Selectors. -## Development +## Getting Involved -##### Requirements +* Join the [mailing list]. Send an email to [email protected] + to subscribe. +* Browse the [issue tracker] and file new issues if you encounter problems. +* Read or contribute to the [wiki]. + +[mailing list]: http://mail-archives.apache.org/mod_mbox/incubator-annotator-dev/ +[issue tracker](https://github.com/apache/incubator-annotator/issues) +[wiki](https://github.com/apache/incubator-annotator/wiki) + +### Requirements We use [Lerna](https://lernajs.io/) to juggle the various Apache Annotator libraries. If you'd like to contribute, you'll need the following: @@ -34,27 +46,24 @@ libraries. If you'd like to contribute, you'll need the following: - [node](https://nodejs.org) ^10 || ^11 || ^12 || >=13.7 - [yarn](https://www.yarnpkg.com/) ^1.5 -##### Setup +#### Setup ```sh $ yarn install ``` -##### Test +#### Test ```sh $ yarn test ``` -##### Run localhost demo server +#### Start a local test project ```sh $ yarn start ``` -Once the test server has started, you can browse a local demo, and run tests in -a browser by visiting `http://localhost:8080/`. - ## Selectors Many Annotations refer to part of a resource, rather than all of it, as the Target. We call that part of the resource a Segment (of Interest). A Selector is used to describe how to determine the Segment from within the Source resource. @@ -84,7 +93,7 @@ $ yarn validate --url https://raw.githubusercontent.com/w3c/web-annotation-tests With the `--url` option you can pass in a URL or a local path to a JSON file. -##### Examples +### Examples Valid: @@ -100,20 +109,9 @@ Invalid: Apache License 2.0 -#### Validate Licensing - -[Apache Rat (Release Audit Tool)](https://creadur.apache.org/rat/) is a -preferred code license checking tool used by [the ASF](https://apache.org/). -The included `.ratignore` file contains a list of files to exclude from scans. - -To check for included licenses, run the following and view the output report: -```sh -java -jar ~/bin/apache-rat-0.13/apache-rat-0.13.jar -E .ratignore -d . > rat_report.txt -``` - # Disclaimer Apache Annotator is currently undergoing incubation at The Apache Software Foundation. -See the accompanying [DISCLAIMER](./DISCLAIMER) file for details. +See the accompanying [DISCLAIMER](./DISCLAIMER-WIP) file for details.
