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

README.md 6.67 KB
Newer Older
vermeul's avatar
vermeul committed
1
2
# YATA - Yet Another Text Annotation

vermeul's avatar
vermeul committed
3
4
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.
vermeul's avatar
vermeul committed
5
6
In addition, annotations might be either nested or overlapping. Because annotations become part of
the text, the text itself can be edited anytime, unlike most alternatives (see below).
vermeul's avatar
vermeul committed
7

vermeul's avatar
vermeul committed
8
If you want to annotate text which *cannot be edited after*, there are several alternatives:
9
10
11
12
- GATE (https://gate.ac.uk) – open source software capable of solving almost any text processing problem
- co-ment (http://www.co-ment.com) – co-ment is a web service for annotating, discussing and writing texts online
- CATMA (http://catma.de) – for undogmatic textual markup and analysis

vermeul's avatar
vermeul committed
13
14
## Annotation Syntax 

vermeul's avatar
vermeul committed
15
MediaWiki has the concept of **ParserFunctions** and offers the possibility to implement your own:
vermeul's avatar
vermeul committed
16
17
18
19
20

```
{{#myOwnParserFunction:}}
```

vermeul's avatar
vermeul committed
21
22
23
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
vermeul's avatar
vermeul committed
24
 
vermeul's avatar
vermeul committed
25
Annotations come in different flavors:
vermeul's avatar
vermeul committed
26
27
- `{{#annot: comment}}` basic annotation with just a comment
- `{{#annot: comment | category}}` categorized annotation
vermeul's avatar
vermeul committed
28
29
30
31
32
- `{{#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
vermeul's avatar
vermeul committed
33
- `{{#annotend: id}}` End-of-Annotation-Tag. The id must be present if the opening tag has one. 
vermeul's avatar
vermeul committed
34
- `{{annotend}}` or `{{#annotend}}` (without the colon) are allowed too.
vermeul's avatar
vermeul committed
35

vermeul's avatar
vermeul committed
36
37
## Annotation Categories

vermeul's avatar
vermeul committed
38
39
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.
vermeul's avatar
vermeul committed
40
If a category has both a parent and a child category, it is called a node.
vermeul's avatar
vermeul committed
41
Categories themselves don't have to be unique. In the example below, the category `examples` is not unique, one
vermeul's avatar
vermeul committed
42
belongs to its parent `written addition` and the other to `written subtraction`:
vermeul's avatar
vermeul committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

```
/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**
vermeul's avatar
vermeul committed
58

vermeul's avatar
vermeul committed
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
### 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
```

vermeul's avatar
vermeul committed
80

vermeul's avatar
vermeul committed
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
## 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 
 ```
 
vermeul's avatar
vermeul committed
105
## display all annotations of a given page
vermeul's avatar
vermeul committed
106
107
108
109
110
111
112
113
114
 
 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
vermeul's avatar
vermeul committed
115
116
 the extracted text.
 
vermeul's avatar
vermeul committed
117
# How to query annotations
vermeul's avatar
vermeul committed
118

vermeul's avatar
vermeul committed
119
120
121
122
123
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)

vermeul's avatar
vermeul committed
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

## annotask Query syntax
```
[[category: category_name1 ]]                             # this category (and all categories below it)
[[category: category_name1, category_name2 ]]             # category_name1 OR category_name2

[[category: category_name1 ]]                             # every line is AND'ed, so these two lines mean:
[[category: category_name2 ]]                             # category_name1 AND category_name2

[[category!: category_name1 ]]                            # category is NOT category_name1
[[wiki_text: %anything%* ]]                               # wikitext LIKE %anything%
[[wiki_text: %anyth_ng%* ]]                               # Underscore matches single characters
[[wiki_text!: %anything% ]]                               # wikitext NOT LIKE %anything%

! "not" ("unequal")
% match any number of characters
_ match any single character
```
vermeul's avatar
vermeul committed
142

vermeul's avatar
vermeul committed
143
144
## Query example

vermeul's avatar
vermeul committed
145
146
```
{{#annotask:
vermeul's avatar
vermeul committed
147
148
149
150
	[[category: parent_category1/child_category1 ]]
	[[category!: parent_category2/child_category2 ]]
	[[comment: %a part of my comment% ]]
	[[wiki_text: %this is somewhere in my text%]]
vermeul's avatar
vermeul committed
151
152
}}
```
vermeul's avatar
vermeul committed
153
154
155
156
157
158
Find all annotations
   * which belong to category `category parent_category1/child_category1`
   * but not to category `parent_category2/child_category2`
   * and contain the comment `a part of my comment`
   * and contain `this is somewhere in my text` in the extracted annotation

vermeul's avatar
vermeul committed
159

vermeul's avatar
vermeul committed
160
161
## annotask: Query result
The result is a sortable table containing the following data:
vermeul's avatar
vermeul committed
162

vermeul's avatar
vermeul committed
163
```Category | Comment | Link | Annotated Text | Last edited by | Modification date```
vermeul's avatar
vermeul committed
164

vermeul's avatar
vermeul committed
165
Because Pages can be