-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathstandoff-en.texi
1177 lines (907 loc) · 39.8 KB
/
standoff-en.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo.tex @c -*-texinfo-*-
@c Documentation for the standoff-mode Emacs package.
@setfilename standoff-en.info
@documentencoding UTF-8
@documentlanguage en
@include version.texi
@ifclear VERSION
@set VERSION
@end ifclear
@settitle Stand-Off Mode @value{VERSION} Manual (english)
@dircategory Emacs
@direntry
* Stand-Off Mode: (standoff-en).Creating stand-off markup. English manual.
@end direntry
@c semantic markup for this file
@alias emenu = samp @c menu entry
@alias markuptype = samp @c markup type
@alias markuplabel = samp @c markup label
@macro nsarb{TYPE}
@c @markuptype{http://beispiel.fernuni-hagen.de/ontologies/beispiel#\TYPE\}
@markuptype{http://arb.fernuni-hagen.de/owl/bsp#\TYPE\}
@end macro
@copying
Copyright @copyright{} 2015, 2021 Christian Lück
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation
@end copying
@titlepage
@title Stand-Off Mode
@subtitle User Manual
@author Christian Lück
@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@c Published by ...
@end titlepage
@c So the toc is printed at the start.
@contents
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Stand-Off Mode
User Manual for Stand-Off Mode, version @value{VERSION}.
@insertcopying
@end ifnottex
@menu
* Introduction::
* Starting and quitting stand-off mode::
* Markup elements::
* Relations::
* Attributes::
* Comments::
* Configuration::
* GNU Free Documentation License::
@detailmenu
--- The Detailed Node Listing ---
Introduction
* Summary::
* Installation::
* Common terms::
* Character offsets::
* Conventions::
Starting and quitting stand-off mode
* Activating stand-off mode::
* Readability of XML source documents::
* Performance::
* Saving annotations::
* Loading annotations::
Configuration
* Stand-Off mode for files of a specific type::
* Back-Ends::
* Annotation schema::
Back-Ends
* JSON file back-end::
* JSON object keys::
* Dummy back-end::
* Conversion::
JSON object keys
* JSON keys for markup ranges::
* JSON keys for relations::
* JSON keys for attributes::
* JSON keys for meta data::
Defining an annotation schema
* Strict or loose handling of an annotation schema::
* Defining a schema using Emacs lisp::
* Generating an annotation schema from OWL::
@end detailmenu
@end menu
@node Introduction, Starting and quitting stand-off mode, Top, Top
@chapter Introduction
@menu
* Summary::
* Installation::
* Common terms::
* Character offsets::
* Conventions::
@end menu
@node Summary, Installation, Introduction, Introduction
@section Summary
Standoff-mode turns Emacs into a tagger for annotating texts. In
contrast to internal markup, when creating stand-off markup, aka
external markup, no tags are inserted into the document. But the
annotations are stored somewhere else and refer the annotated file by
character offsets.
Standoff-mode lets you create different types of annotations: a)
@emph{markup elements}, i.e. passages or spans of your text, b)
@emph{relations}, which interrelate two such markup elements in a
directed fashion, c) @emph{Attributes} on markup elements, which are
key-value pairs, d) free text @emph{comments} on one (or more) markup
elements.
@node Installation, Common terms, Summary, Introduction
@section Installation
There are two ways to install standoff mode:
@itemize @bullet
@item
By using the Emacs package system (recommended).
@item
By using standoff mode's git repository.
@end itemize
@subheading Using the Emacs package system
standoff mode is on the Milkypostman's Emacs Lisp Package Archive
(MELPA), what makes it very easy to install.
If MELPA is not already in your list of package repositories add the
following line to your init file:
@example
(add-to-list 'package-archives
'("melpa" . "https://melpa.org/packages/"))
@end example
On windows you may run into problems using the @code{https}
location. Use @code{http} instead.
Then make the packages from melpa available using
@command{package-refresh-contents} and call @command{package-install}:
@example
M-x package-refresh-contents RET
M-x package-install RET standoff-mode RET
@end example
Alternatively you can use the menu for installing packages:
@example
M-x package-list-packages RET
@end example
Then search @code{standoff-mode}, use @kbd{i} to mark it for
installation and @kbd{x} to install the marked package(s).
@subheading Using standoff mode's git repository
You can clone the git repository like this:
@example
cd ~/src
git clone https://github.com/lueck/standoff-mode
make package
@end example
This makes a package file @file{standoff-mode-<VERSION>.tar}. Now,
install it:
@example
M-x package-install-file RET ~/src/standoff-mode/standoff-mode-<VERSION>.tar
@end example
You could also add @file{~src/standoff-mode/} to Emacs'
@code{load-path}. Then it's not required to use @code{package} at all.
@node Common terms, Character offsets, Installation, Introduction
@section Common terms
@subheading External markup
This manual makes use of some common terms regarding stand-off markup.
@table @b
@item source document
That's the document, the external annotations refer to. It may be a
plain text file, but may also contain markup, e.g. XML-Tags.
@item internal markup
That's the markup, which is already contained in the source document,
e.g. the XML-Tags contained there.
@item stand-off markup / annotations
That's the markup, which exits beside the source document. Stand-Off
mode produces this kind of markup.
@item external document
That's a document, that contains stand-off annotations, which refer an
other document.
@item internalizing
That's a procedure, which adds external annotations into a source
document, e.g. by producing a (new) XML document. This is not done by
standoff-mode, but by an other tool. See
@url{http://github.com/lueck/standoff-tools}.
@item externalizing
That's a procedure, which extracts annotations from a document and
generates external markup from them.
@end table
See also
@url{http://www.tei-c.org/release/doc/tei-p5-doc/de/html/SA.html#SASO}
and @url{http://www.openannotation.org/spec/core/}.
@subheading Emacs basics
Please skip this, if you're familiar with Emacs.
@table @b
@item Command
Do something but simply inserting characters into a file. A command is
called by typing a key sequence, by calling by it's name or by selecting
it from the menu.
@item Echo area
Messages, e.g. generated by commands, are displayed in the echo area at
the bottom of an Emacs windows.
@item @kbd{C-g}
Hold down @kbd{@key{Control}} and press @kbd{g} to quit a partially
executed command. The message ``Quit'' will show up in the echo
area. This is the most imported key binding in Emacs.
@item Minibuffer
When the minibuffer is in use, it appears in the echo area, with a
cursor. The minibuffer starts with a prompt, usually ending with a
colon. The prompt states what kind of input is expected, and how it will
be used.
@item Buffer
The buffer is the basic editing unit. One buffer corresponds to one
piece of text being edited. You can have several buffers open at once,
but can edit only one at a time. Exercise: Find out how to change
buffers.
@item read-only buffer
standoff mode make the buffer of the source document read only. Other
special buffers, e.g. for displaying relations, are read only, too.
@item Window
Several buffers can be visible at the same time when you're splitting
your window. Exercise: Find out how to split and unsplit a window.
@item Frame
In Emacs, frames are what window managers call windows. Exercise: Find
out how to display a new frame.
@item Point
Point is the position of the curser.
@item Mark
In a buffer, you can set marks, which you can return to by simple key
combinations.
@item Region
In Emacs, region is the name of the selection area of a buffer. It is
the text spanning between the last set mark and the point. It can be
selected with the keyboard and with the mouse.
@item Modeline
Each Emacs window (aside from minibuffer windows) typically has a mode
line at the bottom, which displays status information about the buffer
displayed in the window. The mode line contains information about the
buffer, such as its name, associated file and major and minor
modes. Some programs call this the status bar.
@item Mode
Emacs contains many editing modes that alter its basic behavior in
useful ways by provinding commands. standoff mode is a mode and the
behaviour it defines is described in this manual.
@item Menu
Each frame has a menu bar. You can select many, but not all commands
from it. Standoff mode adds the Stand-Off menu. It is gone, if the
minibuffer is active.
@item Key sequence
Some Emacs commands are invoked by just one input event; for example,
@kbd{C-f} moves forward one character in the buffer. Other commands take
two or more input events to invoke, such as @kbd{C-x C-f} and @kbd{C-x 4
C-f}. A key sequence, or key for short, is a sequence of one or more
input events that is meaningful as a unit.
@item Modifier keys @kbd{@key{C-}}, @kbd{@key{M-}}
To input the key sequence @kbd{@key{C-}f}, hold down @kbd{@key{Control}}
and then press @kbd{f}. @kbd{@key{Control}} is the first modifier key
in Emacs. The second modifier key is @kbd{@key{M-}}, which stands for
@kbd{@key{Meta}}. To input @kbd{@key{M-}x}, either hold down
@kbd{@key{Alt}} or--if you're on a keyboard without
@kbd{@key{Alt}}--press @kbd{@key{ESC}}, then press @kbd{x}.
@item @kbd{@key{M-}x command-name RET}
You can call a command by it's name instead of typing a key sequence or
selecting it from the menu. Type in the @kbd{@key{M-}x} key sequence
first, then call the command name and then press @kbd{@key{Return}}. In
short: @kbd{@key{M-}x command-name RET}.
In standoff-mode, there are only a few commands, that have to be called
by name. These are commands that could mess up your annotation data, so
you better know what you are doing. Most other commands can either be
called by key combinations or from the menus.
@end table
@ifinfo
@xref{(Emacs)Top}.
@end ifinfo
@ifnotinfo
For more information, see the
@uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/index.html,
Emacs manual}.
@end ifnotinfo
@node Character offsets, Conventions, Common terms, Introduction
@section Character offsets
An @emph{external document} produced by stand-off mode looks like this:
@example
(setq standoff-markup-read-function-dumped
(quote
(("ac06be81-d86e-4fe5-b84e-4952b1e571c9"
"http://beispiel.fernuni-hagen.de/ontologies/beispiel#beispiel"
28095
28100
"Dante")
("a29ca667-0f99-4933-b0aa-8a7b1c1929e9"
"http://beispiel.fernuni-hagen.de/ontologies/beispiel#konzept"
28057
28070
"Große Dichter")
...)))
(setq standoff-source-md5-dumped "a2997fcd8c318048abf34889212c1982")
@end example
That's a representation of the external markup in so called
s-expressions, which is used by the dummy back-end which simply dumps
emacs lisp data into a file. There is also a JSON back-end. See @c TODO
for more info about representation formats and back-ends.
All text spans from the source document, that where annotated, make up a
list of markup elements, stored in the variable
@code{standoff-markup-read-function-dumped}. Each markup element is
delimited by paratheses and has positional arguments.
The first positional arguments is made from 32 letters and digits,
separted by '-' into 5 blocks, and is a universally unique identifier
(UUID) of the markup element.
The second positional argument, which has the form of a URI, gives the
type or class of the markup element. In the first case, it's a
``beispiel'' (german for ``example'') from the namespace
@code{http://beispiel.fernuni-hagen.de/ontologies/beispiel}, in the
second case it is ``konzept'' (german for ``term'') from the same
namespace.
The next two positional arguments give the @emph{charater offsets} of
the start and end of the text span in the source document. Here, the
annotated passage spans from character 28095 to 28100.
The fifth positional entry is the string from the source document, that
spans from the start to the end character offset. The latin capital
letter @code{D} in @code{Dante} has position 28095, the @code{e} in the
end of the name has position 28099.
Further down there is the checksum for the source document. The checksum
is calculated, when the document is opened. As soon as the source
document is changed, the checksum changes and stand-off mode alarms you
with an error, because the @emph{character offsets} are likely to be
incorrect now.
@node Conventions, , Character offsets, Introduction
@section Conventions
This manual is available in three formats: PDF, HTML, and info files,
which can be read using Emacs' info browser.
Throughout this manual, commands offered by stand-off mode are
represented following the conventions:
@deffn Command standoff-some-command-name ARG1 ARG2
(@kbd{x}) (@emenu{Stand-Off->Some command}) Explanation what this
command does. Explanation of the Arguments ARG1 and ARG2.
@end deffn
Here is an example:
@deffn Command standoff-display-manual
@kindex ?
(@kbd{?}) (@emenu{Stand-Off->Manual}) Open the manual for standoff
mode. There are manuals in two languages: english and german. The
customization option @code{standoff-info-language} is used, to select a
language. If is set to ``de'', the german manual is opened. If it is
nil, then the @code{LANG} environment variable is evaluated. When the
result of the evaluation is not ``de'', the english manual is opened.
@vindex standoff-info-language
@end deffn
The command @command{standoff-display-manual} takes no arguments an is
bound to the key @kbd{?} and the menu entry @code{Manual} in the
@code{Stand-Off} menu.
You can call such a command in three ways. (1) Call it by name, (2) by
key code, (3) select it from the menu. The name is given in the first
line right after the keyword Command. Here, the command's name is
@code{standoff-display-manual}. The key code is given in the first
parentheses, here it is @kbd{?}. So you can call the manual by simply
pressing the @kbd{?} on your keyboard, provided that the current buffer
is in standoff mode. The menu entry is given in the second parenthesis,
here it is the menu entry ``Manual'' in the menu ``Stand-Off''.
@node Starting and quitting stand-off mode, Markup elements, Introduction, Top
@chapter Starting and quitting stand-off mode
@menu
* Activating stand-off mode::
* Readability of XML source documents::
* Performance::
* Saving annotations::
* Loading annotations::
@end menu
@node Activating stand-off mode, Readability of XML source documents, Starting and quitting stand-off mode, Starting and quitting stand-off mode
@section Activating stand-off mode
@deffn Command standoff-mode
Activate standoff mode for the file displayed in the current buffer.
@end deffn
After opening a file, standoff mode can be activated by @kbd{M-x
standoff-mode @kbd{RET}}. @xref{Stand-Off mode for files of a specific
type}, to configure Emacs to always open files with a specific suffix in
standoff mode.
In standoff mode, the buffer is read-only. This absolutely makes sense,
because the external markup references spans of the source document by
character offsets. Modifying the source document would break these
character offsets.
If standoff mode is active, ``Stand-Off'' shows up in the modeline and
the menu @emenu{Stand-Off} is present (not present if minibuffer is
active).
Right after activating, standoff mode tries to load existing
annotations. Depending on the back-end, standoff mode loads the
annotations of a file in the same directory and with the same file name
as the source document, but with the additional suffix @code{.json}
(JSON file back-end), or @code{.dump.el} (dummy back-end).
@xref{Back-Ends}.
Be aware, that a back-end has to be configured, before standoff mode is
ready to be used.
@node Readability of XML source documents, Performance, Activating stand-off mode, Starting and quitting stand-off mode
@section Readability of XML source documents
XML-Files often aren't friendly to the user's eye. Readability can be
improved by hiding XML tags like @code{<p>}. Also character references
of the form @code{&#xNNNN;} can be substituted with the corresponding
glyphs.
@deffn Command standoff-xml-tags-invisible
(@emenu{Stand-Off->Hide/Show XML-tags}) Hide XML tags when they are
visible, show them, when they are invisible.
@end deffn
@deffn Command standoff-xml-toggle-char-ref-glyph-substitute
(@emenu{Stand-Off->Substitute character references with glyphs}) Replace
XML character references with the corresponding glyph.
@end deffn
When executing, these commands take some time. On larger files (some
MBs), you might have to wait a minute.
Hiding these XML internals makes sense not only regarding human
readability. It also helps making the annotations syntactically
correct. Starting or ending a markup range inside an XML tag or
character reference would result in an error or in invalid XML, when
internalized. By hiding these internals, a markup range can never start
or end inside.
But hiding can result in bad performance of the editor. For solving
this, @ref{Performance}.
@node Performance, Saving annotations, Readability of XML source documents, Starting and quitting stand-off mode
@section Performance
Standoff mode generates tons of overlays. Overlays are an Emacs
technique to alter the visual appearance of a buffer's text on the
screen, for the sake of presentation features. Replacing XML character
references with the corresponding glyphs is done by overlays. Showing
markup ranges in the source document is also done by overlays, since
they allow adding visual features and even characters while not changing
the underlying text. (That's why the point can't be positioned over a
markup ranges' bounding bracket and number. They are not really in the
buffers text, but only seem to be there.)
When working with larger XML files, the tons of overlays may slow down
Emacs significantly, even render it unusable. But there is another
Emacs feature, to work around this: Narrowing the buffer down to a
portion of the file. When you run into performance problems with
standoff mode, please try narrowing.
@deffn Command narrow-to-region REGION
@kindex C-x n n
(@kbd{C-x n n}) Narrow the buffer to the region. The REGION must be
active when calling this command. Calling it the first time, you will
be asked if you really want to activate the narrowing feature.
@end deffn
@deffn Command widen
@kindex C-x n w
(@kbd{C-x n w}) Widen narrowed buffer to see the full file again.
@end deffn
@ifinfo
@xref{(Emacs)Narrowing}.
@end ifinfo
@ifnotinfo
For more information, consult the
@url{https://www.gnu.org/software/emacs/manual/html_node/emacs/Narrowing.html#Narrowing,
Emacs manual about narrowing}.
@end ifnotinfo
@node Saving annotations, Loading annotations, Performance, Starting and quitting stand-off mode
@section Saving annotations
Saving the external markup depends on the back-end, that is used in
standoff mode.
If the JSON file back-end is configured, the annotations are stored in a
separate buffer which references a file. The default file name is the
file name of the source document plus the suffix @code{.json}. Saving is
done by switching to this buffer and saving the json-file. Before
quitting Emacs, the editor asks if modified buffers should be saved to
disk.
If the dummy back-end is configured, the annotations are kept in memory
only, while annotating the source document. If Emacs quits, the
annotations are lost. But they can be dumped to disk by calling a dump
command and they can be loaded from the dump file in the next session.
@deffn Command standoff-dump-elisp FILENAME
@kindex u
(@kbd{u}) (@emenu{Stand-Off->Dump to file (SAVE)}) Save the annotations
as s-expressions in a Emacs lisp file. You will be prompted for a
FILENAME. It defaults to the file name of the source document, plus the
suffix @code{.dump.el}, since that's the name of the file that is
automatically loaded on activation.
@end deffn
Note, that this command is always present. So, whatever back-end is
used, you're able to dump the annotations to local disk. Use
@emph{standoff-tools} to generate various other formats from it:
@url{http://github.com/lueck/standoff-tools}.
@strong{Be aware to always dump your annotations, if the dummy back-end
is configured. They can't be recovered otherwise.}
When working with a back-end, that stores the annotations on local disk,
it is recommended to use the JSON file back-end. Reason: It always asks
you if you want to save your the json file before quitting Emacs.
@node Loading annotations, , Saving annotations, Starting and quitting stand-off mode
@section Loading annotations
One of the following load commands is called automatically after
standoff mode is activated. Which one, depends on the back-end used.
Automatic loading on activation succeeds, if a file matching the default
file name of the command (see below) is present.
The loading commands can even be called interactively by the user. They
are neither bound to the menu nor to a key code, since calling them
unwittingly might damage your annotation data. (Using the JSON backend,
there is only a minor risk.)
@deffn Command standoff-json-file/load-file FILENAME
Load annotations from a JSON file. You will be prompted for the
FILENAME. It defaults to the file name of the source document, plus the
suffix @code{.json}.
@end deffn
@deffn Command standoff-dummy-load-dumped FILENAME
Load annotations from a Emacs lisp file with dumped annotations. You
will be prompted for a FILENAME. It defaults to the file name of the
source document, plus the suffix @code{.dump.el}.
@end deffn
For more information on back-ends and configuration, @ref{Back-Ends}.
@node Markup elements, Relations, Starting and quitting stand-off mode, Top
@chapter Markup elements
@node Relations, Attributes, Markup elements, Top
@chapter Relations
@node Attributes, Comments, Relations, Top
@chapter Attributes
@node Comments, Configuration, Attributes, Top
@chapter Comments
@node Configuration, GNU Free Documentation License, Comments, Top
@chapter Configuration
@menu
* Stand-Off mode for files of a specific type::
* Back-Ends::
* Annotation schema::
@end menu
@node Stand-Off mode for files of a specific type, Back-Ends, Configuration, Configuration
@section Stand-Off mode for files of a specific type
You can configure Emacs to always activate standoff mode on certain file
types. In order to activate standoff mode for all files ending with
@code{.TEI-P5.xml}, put the following line into the init file.
@example
(add-to-list 'auto-mode-alist '("\\.TEI-P5\\.xml$" . standoff-mode))
@end example
@node Back-Ends, Annotation schema, Stand-Off mode for files of a specific type, Configuration
@section Back-Ends
With standoff mode you have some options where to store you annotations
and in which format. Storing annotations is done by a @dfn{back-end}.
Before working with standoff mode, it is required to choose a back-end.
The annotations can be stored in a file on the local disk or in a
central database. The @dfn{JSON file back-end} and the dummy back-end
store them locally on disk. The @dfn{JSON rest back-end} (under
development) stores them in a database communicating via a restful
web-service.
The JSON file back-end stores the annotations in JSON format, and the
names of keys of the JSON objects are configurable. The dummy back-end
stores the annotations as s-expressions known from programming languages
like LISP, in fact they are dumped Emacs-lisp expressions. The JSON rest
back-end uses JSON to communicate with the database.
@defopt standoff-backend
Configuring, which back-end to use, is simple. There are two ways: (1)
Customize the user option @code{standoff-backend}. You are
automatically directed to the customization dialog if you try working
with stand-off mode without a back-end. (2) Edit your Emacs startup
file by adding:
@vindex standoff-backend
@example
@code{(setq standoff-backend 'standoff-json-file)}
@end example
for using the JSON file back-end, or
@example
@code{(setq standoff-backend 'standoff-dummy)}
@end example
for using the dummy back-end.
Note, that the type of @code{standoff-backend} must be a feature, and
thus must be quoted like a symbol.
@end defopt
@menu
* JSON file back-end::
* JSON object keys::
* Dummy back-end::
* Conversion::
@end menu
@node JSON file back-end, JSON object keys, Back-Ends, Back-Ends
@subsection JSON file back-end
In order to configure Emacs to use the JSON file back-end, customize the
@code{standoff-backend} user option or put the following line in your
init fill:
@example
(setq standoff-backend 'standoff-json-file)
@end example
We recommend using this back-end, because you're always asked if you
want to save your annotations before quitting Emacs (while the dummy
back-end does not). As the annotations are stored in JSON format, they
can be processed by most programming languages. Moreover, there is no
further setup needed. But if you want (or need), you can configure the
names of the keys of a JSON object. @xref{JSON object keys}.
The backend provides the following interactive command:
@deffn Command standoff-dummy-load-dumped FILENAME
Load annotations from a Emacs lisp file with dumped annotations. You
will be prompted for a FILENAME. It defaults to the file name of the
source document, plus the suffix @code{.dump.el}.
@end deffn
@node JSON object keys, Dummy back-end, JSON file back-end, Back-Ends
@subsection JSON object keys
You can customize the keys of JSON objects to your needs. We recommend
setting them in the init file. Example:
@example
(setq standoff-json/markup-type-key "qualifiedName"
standoff-json/relation-predicate-key "qualifiedName"
standoff-json/attribute-name-key "qualifiedName")
@end example
Note that there standoff mode produces meta data on each object. The
keys for these meta data can be customized, too.
(TODO: implement all of the following!)
@menu
* JSON keys for markup ranges::
* JSON keys for relations::
* JSON keys for attributes::
* JSON keys for meta data::
@end menu
@node JSON keys for markup ranges, JSON keys for relations, JSON object keys, JSON object keys
@subsubsection JSON keys for markup ranges
@defopt standoff-json/markup-array-key
The JSON key of array of markup ranges/elements. Defaults to @code{MarkupRanges}.
@end defopt
@defopt standoff-json/markup-tag-key
The JSON key for the tag of a markup range/element. Defaults to @code{tag}.
@end defopt
@defopt standoff-json/markup-tag-value
The JSON value of the tag of a markup range/element. Defaults to
@code{MarkupRange}. The tag's value is used to identify, which type of
object this is.
@end defopt
@defopt standoff-json/markup-element-id-key
The JSON key of the Id of a markup element. Defaults to @code{elementId}.
@end defopt
@defopt standoff-json/markup-range-id-key
The JSON key of the Id of a markup range. Defaults to @code{rangeId}.
@end defopt
@defopt standoff-json/markup-type-key
The JSON key for the markup type. Defaults to @code{type}.
@end defopt
@defopt standoff-json/markup-start-key
The JSON key of the Id of the start character offset. Defaults to @code{sourceStart}.
@end defopt
@defopt standoff-json/markup-end-key
The JSON key of the Id of the end character offset. Defaults to @code{sourceEnd}.
@end defopt
@node JSON keys for relations, JSON keys for attributes, JSON keys for markup ranges, JSON object keys
@subsubsection JSON keys for relations
@defopt standoff-json/relation-id-key
The JSON key for the id of a relation. Defaults to @code{relationId}.
@end defopt
@defopt standoff-json/relation-subject-key
The JSON key for the Id of a relation's subject. Defaults to @code{subjectId}.
@end defopt
@defopt standoff-json/relation-predicate-key
The JSON key for the predicate of a relation. Defaults to @code{predicate}.
@end defopt
@defopt standoff-json/relation-object-key
The JSON key for the Id of a relation's object. Defaults to @code{objectId}.
@end defopt
@node JSON keys for attributes, JSON keys for meta data, JSON keys for relations, JSON object keys
@subsubsection JSON keys for attributes
@defopt standoff-json/attribute-element-key
The JSON key for the Id of the markup element the attribute refers to. Defaults to @code{elementId}.
@end defopt
@defopt standoff-json/attribute-name-key
The JSON key for the name of an attribute. Defaults to @code{name}.
@end defopt
@defopt standoff-json/attribute-value-key
The JSON key for the value of an attribute. Defaults to @code{value}.
@end defopt
@node JSON keys for meta data, , JSON keys for attributes, JSON object keys
@subsubsection JSON keys for meta data
@defopt standoff-json/created-by-key
The JSON key for meta data about the creator. Defaults to @code{createdBy}.
@end defopt
@defopt standoff-json/created-at-key
The JSON key for meta data about the creation time. Defaults to @code{createdAt}.
@end defopt
@node Dummy back-end, Conversion, JSON object keys, Back-Ends
@subsection Dummy back-end
The dummy back-end is a very simple implementation of the API for
standoff mode back-ends. We recommend using the JSON file back-end,
because with the dummy implementation, you can easily loose data.
Annotations are stored in memory, bot in a buffer visiting a file. So
when you quit Emacs, everything is lost, unless you dumped it before
quitting. So do not forget the following command:
@deffn Command standoff-dump-elisp FILENAME
(@kbd{u}) (@emenu{Stand-Off->Dump to file (SAVE)}) Save the annotations
as s-expressions in a Emacs lisp file. You will be prompted for a
FILENAME. It defaults to the file name of the source document, plus the
suffix @code{.dump.el}, since that's the name of the file that is
automatically loaded on activation.
@end deffn
@deffn Command standoff-dummy-load-dumped FILENAME
Load annotations from a Emacs lisp file with dumped annotations. You
will be prompted for a FILENAME. It defaults to the file name of the
source document, plus the suffix @code{.dump.el}.
@end deffn
Configuration options for the dummy backend:
@defopt standoff-dummy-create-id-function
Pointer to the function (actually the function symbol) for creating ids
used in the dummy backend. Defaults to @code{
'standoff-util/create-uuid}, which creates a universally unique id.
@end defopt
@defopt standoff-dummy-user-logging
Whether or not to log time and user meta data when creating markup. You
can keep out big brother by setting this to @code{nil}. Defaults to
@code{t}.
@end defopt
@node Conversion, , JSON object keys, Back-Ends
@subsection Conversion
Annotations stored in one backend format can be converted into an other
backends format. E.g. if you switched from the dummy backend to the
json-file backend, then you can convert your dumped annotations using
@code{standoff-dumped-json/dumped-to-json}. You have to load the module
@code{standoff-dumped-json} before.
@node Annotation schema, , Back-Ends, Configuration
@section Defining an annotation schema
An annotation schema defines, which markup types may be used, which
relation predicates can be used for a certain combination of subject and
object types, which names attributes of a certain type of markup element
are allowed.
@menu
* Strict or loose handling of an annotation schema::
* Defining a schema using Emacs lisp::
* Generating an annotation schema from OWL::
@end menu
@node Strict or loose handling of an annotation schema, Defining a schema using Emacs lisp, Annotation schema, Annotation schema
@subsection Strict or loose handling of an annotation schema
You can configure, how strict standoff mode enforces an annotation
schema. You can configure, to not restrict markup types, relation
predicates etc. at all. Then, the annotator is free to use what ever
type or predicate comes to his mind. But even then, a list of types,
predicates etc. he used before is presented to him on the UI; but he can
ignore it and type in a new type, predicate etc. Let's call this
process of implicitly generating an open annotation schema
@emph{a posteriori}.
The other alternative is to restrict the user input regarding markup
types, relation predicates etc. to an annotation schema given @emph{a
priori}.
@defopt standoff-markup-type-require-match
@defoptx standoff-predicate-require-match
@defoptx standoff-literal-key-require-match
These user options define how restrictive the markup schema is handled.
If set to @code{t} then the entered type must be amongst the members of
the list of markup types, relation predicates of attribute name defined
in the schema or so far used in the source document. If set to
@code{nil}, the user may exit his input with any type. If set to
@code{'confirm} (quoted symbol), the user may exit with any type, but is
asked to confirm his input. All these user options default to
@code{'confirm}.
@end defopt
@defopt standoff-markup-types-allowed
@defoptx standoff-relations-allowed
@defoptx standoff-literal-keys-allowed
These user options each take a list of allowed types, predicates of
attribute names. Default is the empty list @code{'()}.
@end defopt
@node Defining a schema using Emacs lisp, Generating an annotation schema from OWL, Strict or loose handling of an annotation schema, Annotation schema
@subsection Defining a schema using Emacs lisp
You can use Emacs lisp, a LISP dialect, to define an annotation schema.
We recommend @ref{Generating an annotation schema from OWL}, but even
then, you should have read about definition in lisp, because that is,
what standoff mode effectively reads. All of the code below must go
into your init file (or a file loaded by the init file).
@defopt standoff-markup-types-allowed
@defoptx standoff-relations-allowed
@defoptx standoff-literal-keys-allowed
These user options each take a list of allowed types, predicates of
attribute names. Default is the empty list @code{'()}. Here is an
example definition:
@end defopt
@example
(setq standoff-markup-types-allowed '(