To receive notifications about scheduled maintenance, please subscribe to the mailing-list gitlab-operations@sympa.ethz.ch. You can subscribe to the mailing-list at https://sympa.ethz.ch

Commit 99491145 authored by vermeul's avatar vermeul
Browse files

Merge branch 'master' of https://gitlab.ethz.ch/vermeul/YATA

parents 55bedf9b 6b1fdaaf
# YATA - Yet Another Text Annotation
YATA is a text annotation plugin for MediaWiki. It allows to annotate text passages with comments.
Each annotation can belong to a category. And categories can be organized in a hierarchical way.
In addition, annotations might be either nested or overlapping.
## Annotation Syntax
MediaWiki has the concept of **ParserFunctions** and offers the possibility to implement your own:
```
{{#myOwnParserFunction:}}
```
We use this facility to define our own ParserFunctions to offer annotations:
- `{{#annot:}}`: opening tag, which marks the beginning of an annotation
- `{{#annotend:}}`: closing tag, which marks the end of an annotation
Annotations come in different flavors:
- `{{#annot: comment}}` basic annotation with just a comment
- `{{#annot: comment | category}}` categorized annotation
- `{{#annot: comment | cat_parent/cat_child}}` annotation with a specific category identified by a `cat_parent/cat_child` pair
- `{{#annot: comment | category1, category2}}` annotation with more than one category
- `{{#annot: comment | category | some_id}}` an id is used to identify the proper end of the annotation when nesting. Annotation end must contain the same id: `{{#annotend: some_id}}`
- `{{#annot: | category}}` just specifiying the category a text belongs to, with no comment
- `{{#annot: comment | | some_id}}` nested annotation with an id to identify its ending, without any category
- `{{#annotend: id}}` End-of-Annotation-Tag. The id must be present if the opening tag has one.
- `{{annotend}}` or `{{#annotend}}` (without the colon) are allowed too.
## Annotation Categories
Annotations can be categorized, but don't have to be. The categories themselves are organized hierarchically.
If a category has no parent category, it is a top category. If a category has no child category, it is called a leaf.
If a category has both a parent and a child category, it is called a node.
Categories themselves don't have to be unique. In the example below, the category `examples` is not unique, one
belongs to its parent `written addition` and the other to `written sutraction`:
```
/addition
/written addition
/examples
/subtraction
/written subtraction
/examples
```
So if we want to annotate a written subtraction example, we simply write:
```
{{#annot: my comment | written subtraction/examples}}
```
Note: **the combination of parent_category/child_category must be unique**
### insert new category
To insert a new category into the categories table, we simply add one of the following anywhere in a Wiki Page:
```
{{#annotcat: add | new top category:description }}
{{#annotcat: add | new category:description | parent_category }} # add to an existing top category
{{#annotcat: add | new category:description | grandparent_category/parent_category}} # identify a node
{{#annotcat: del | kat_parent/kat_child }}
```
Before page gets saved, and after these categories are added/removed,
these parser functions are removed from the Wiki Page source.
### list existing categories
```
{{#annotcat: list }} # lists all categories
{{#annotcat: list | top_cat }} # start with top_cat (which must have no parent)
{{#annotcat: list | parent_cat/child_cat }} # start list with node parent_cat/child_cat
```
## Nested or overlapping annotations: Examples
The vertical bars are used to supply a number of different arguments. Because annotations can be even nested or overlapping,
we need to add an identifier to be sure the start and endings are connected together correctly. For example:
```
Here is some {{#annot: comment1 | category1 | a}} more text
which has even {{#annot: comment2 | category2 | b}} overlapping
comments{{#annotend: a}}, which means we need {{#annotend: b}} to
connect start and ending of every comment.
```
Annotation (a) then contains:
```
more text
which has even overlapping
comments
```
while annotation (b) will contain this part of the WikiText:
```
overlapping
comments, which means we need
```
## display all annotations of a given page
To display all annotations on a page, just add
```
{{#annotlist:}}
```
somewhere in your Wikicode, preferably at the beginning or end of your page.
The output will be a sortable Wikitable which contains comment, category and
the extracted text.
# query annotations
To get specific annotations we are interested in, we need a small query language
which allow us to find a text passage in a page anywhere in the Wiki. Our goal is
to define the query language similar to the Semantic Media Wiki query language {{#ask:}}.
See the [SMW concepts](https://www.semantic-mediawiki.org/wiki/Help:Concepts)
**Example**: find all annotations
- with category `kat_parent1/kat_child1`
- but not `kat_parent2/kat_child2`
- comment contains either «comment1» or «comment2»
- wiki_text contains the word «bla»
```
{{#annotask:
[[category:kat_parent1/kat_child1]]
[[category!:kat_parent2/kat_child2]]
[[comment:comment1, comment2]]
[[wiki_text~:*bla*]]
}}
```
The result should be a sortable table containing the following data:
```link to page and section | comment | category | wiki_text```
**Problem**: how to provide a deep link, not just to the page but to the right paragraph which was annotated.
**Possible Solutions**:
- Maybe search for the text?
- Can we add a unique ID to the function hook? Difficult.
- We now start_char and end_char in the source. Maybe we can add a marker at the given spots?
- we should always include the next previous title to the annotation. We then could use this title to add an anchor to the URL and thus be redirected to the right paragraph.
```
[[category:kat_parent1/kat_child1]] # this and all categories below
[[category:kat_parent1/kat_child1 || kat_parent2/kat_child2]] # OR
[[category:kat_parent1/kat_child1 && kat_parent2/kat_child2]] # AND
[[category!:kat_parent1/kat_child1 ]] # category is NOT kat_parent1/kat_child1
[[wikitext~*anything*]] # wikitext LIKE %anything%
[[wikitext!~*anything*]] # wikitext NOT LIKE %anything%
> and <: "greater than" and "less than"
≥ and ≤: "greater than or equal" and "less than or equal"
!: "not" ("unequal")
~: «like» comparison for strings
!~: «not like» comparison for strings
?: match any single character
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment