Skip to content

Commit

Permalink
Documentation: update chapter on annotations
Browse files Browse the repository at this point in the history
  • Loading branch information
@wolfgangmm
wolfgangmm committed Jan 25, 2024
1 parent 6207008 commit a57b645
Show file tree
Hide file tree
Showing 5 changed files with 81 additions and 79 deletions.
Binary file modified data/doc/ann-configure.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified data/doc/ann-details.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified data/doc/ann-nested.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified data/doc/ann-toolbar.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
160 changes: 81 additions & 79 deletions data/doc/documentation.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6561,8 +6561,13 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
<para>If matches can be found in other documents, a review panel will pop up, where you can review them
on a document-by-document and match-by-match basis. Each document is presented as a separate results page and you
can select or deselect occurrences depending where you want annotations to be applied.</para>
<para>Similarly to the conventions throughout the annotation editor, color coding is used to highlight existing
annotations and potential inconsistencies.</para>
<para>Similarly to the conventions throughout the annotation editor, color coding is used to highlight existing annotations and potential
inconsistencies. Clicking the disk icon will directly merge and save the checked annotations into the current document and remove it from the list of
items to review.</para>
<para>Alternatively you can click on the file's path in the header: this will open the corresponding document in a new annotation editor in a separate
browser tab. The selected annotations will be added to the document for review, but are not merged yet. You need to explicitely save them before
closing the additional tab.</para>
<para>Note that opening a document for review in an extra tab will also remove it from the list of pending documents in the dialog.</para>
<figure>
<title>Review matches across collection</title>
<mediaobject>
Expand Down Expand Up @@ -6610,9 +6615,8 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
<para>The toolbar at the bottom of the popup allows to delete or modify the annotation.
Clicking the delete button will immediately remove the annotation, without asking for
confirmation.</para>
<para>Clicking on the pen icon will open the annotation in the left sidebar, where you can
change it. For semantic annotations, the authority lookup dialog will pop up automatically
and you can change the connected authority entry by selecting a different one.</para>
<para>Clicking on the pen icon will open the annotation details in the right sidebar, where you can modify them. For semantic annotations, the authority
lookup panel will display automatically below and you can change the connected authority entry by selecting a different one.</para>
<para>Again, semantic annotations are applied immediately, while analytic and text critical
annotations require a click on the save button after making modifications.</para>
</section>
Expand Down Expand Up @@ -6648,59 +6652,53 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
</section>
<section>
<title>Merge, Export and Undo</title>
<para>The toolbar on top of the preview pane provides important actions: <figure>
<title>Toolbar</title>
<mediaobject>
<imageobject>
<imagedata fileref="ann-toolbar.png" width="500px"/>
</imageobject>
</mediaobject>
</figure>
<variablelist>
<varlistentry>
<term>Reload source TEI</term>
<listitem>
<para>This will reload the source TEI XML into the annotation view, discarding any
existing annotations. Use this if you had to change the TEI in an external editor
and want to continue annotating.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Merge and save annotations to TEI</term>
<listitem>
<para>Merges the current set of annotations into the TEI and saves it, establishing a
new version of the base document. The annotation view will be reloaded to reflect
the new base.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Save and export TEI to a local file</term>
<listitem>
<para>(Chrome only) As above, merges and saves the annotations, but additionally
prompts for a local file into which a copy of the resulting TEI will be
written.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Undo last change</term>
<listitem>
<para>Reverts the last action applied. For batch operations (if you clicked the "apply
all" button above the occurrences list) this may comprise multiple annotations. The
annotation view will be reloaded and the remaining annotations are
re-applied.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Preview merge results</term>
<listitem>
<para>Forces the preview pane to refresh.</para>
</listitem>
</varlistentry>
<para>The buttons to the right side of the main toolbar provide important functions for saving etc.: <figure>
<title>Toolbar</title>
<mediaobject>
<imageobject>
<imagedata fileref="ann-toolbar.png" width="500px"/>
</imageobject>
</mediaobject>
</figure> <variablelist>
<varlistentry>
<term>Reload source TEI</term>
<listitem>
<para>This will reload the source TEI XML into the annotation view, discarding any existing annotations. Use this if you had to change the TEI in an
external editor and want to continue annotating.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Merge and save annotations to TEI</term>
<listitem>
<para>Merges the current set of annotations into the TEI and saves it, establishing a new version of the base document. The annotation view will be
reloaded to reflect the new base.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Save and export TEI to a local file</term>
<listitem>
<para>(Chrome only) As above, merges and saves the annotations, but additionally prompts for a local file into which a copy of the resulting TEI
will be written.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Undo last change</term>
<listitem>
<para>Reverts the last action applied. For batch operations (if you clicked the "apply all" button above the occurrences list) this may comprise
multiple annotations. The annotation view will be reloaded and the remaining annotations are re-applied.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Display preview pane</term>
<listitem>
<para>Shows preview pane at the very bottom of the screen, floating above the page.</para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
<section>
<title>Named Entity Recognition</title>
<para>TEI Publisher 8 includes experimental support for detecting and tagging named entities in texts. The idea is to further simplify the work of editors when annotating documents via TEI Publisher’s web-based annotation editor by automatically identifying potential candidates for people, places etc.</para>
<para>TEI Publisher includes support for detecting and tagging named entities in texts. The idea is to further simplify the work of editors when annotating documents via TEI Publisher’s web-based annotation editor by automatically identifying potential candidates for people, places etc.</para>
<para>For named entity recognition to be available in the web-based annotation editor, a separate Python service
is needed: clone the <link xlink:href="https://github.com/eeditiones/tei-publisher-ner">tei-publisher-ner</link> repository and follow the instructions in the README.</para>
<figure>
Expand Down Expand Up @@ -7012,8 +7010,10 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
</section>
<section>
<title>Configuring Annotations</title>
<para>Adding new annotation types or modifying existing ones involves the following three
files within TEI Publisher or generated apps:</para>
<note>
<para>TEI Publisher 9 introduces various changes to the annotation editor, including a different page layout. It also uses a sophisticated framework for forms, called fore, which is in particular used for the custom entity editors, but also powers some of the functionality of the main editor page. The user-customizable parts more or less stayed the same though, so updating an existing annotation app should be fairly easy (see the chapter on updating from 8 to 9).</para>
</note>
<para>Adding new annotation types or modifying existing ones involves the following three files within TEI Publisher or generated apps:</para>
<variablelist>
<varlistentry>
<term><filename>templates/pages/annotate.html</filename></term>
Expand All @@ -7037,13 +7037,11 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
</variablelist>
<para>Let's assume we would like to support an annotation to tag foreign language passages
with the TEI <tag>foreign</tag> element:</para>
<para>First, open <filename>templates/pages/annotate.html</filename> in eXide and locate the
<tag> div</tag> with class <option>toolbar</option>. This contains a list of <tag>
paper-icon-button</tag> elements. Like many elements in TEI Publisher, <tag>
paper-icon-button</tag> is a webcomponent from the polymer library, which renders a button
compliant with Google's material design. You could use any other button-type element here,
but for consistency, let's stick with <tag>paper-icon-button</tag>. We define our new button
like this:</para>
<para>First, open <filename>templates/pages/annotate.html</filename> in eXide and locate the <tag> div</tag> with class <option>header-toolbar</option>.
This is the main toolbar and you'll find the list of <option>annotation-action</option> buttons in the second <option>span.icon-group</option>. Like
many elements in TEI Publisher, <tag> paper-icon-button</tag> is a webcomponent from the polymer library, which renders a button compliant with Google's
material design. You could use any other button-type element here, but for consistency, let's stick with <tag>paper-icon-button</tag>. We define our new
button like this:</para>
<programlisting>&lt;paper-icon-button class="annotation-action toggle" title="Foreign" data-type="foreign" icon="icons:language" data-shortcut="⌘+⇧+b,ctrl+⇧+b" disabled="disabled">&lt;/paper-icon-button></programlisting>
<figure>
<title>Configure a new annotation type</title>
Expand All @@ -7058,11 +7056,9 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
<varlistentry>
<term>class</term>
<listitem>
<para>must at least contain <option>annotation-action</option>. The
<option>toggle</option> indicates that this is a toggling annotation, which just
switches between on and off and does not need further input. For semantic annotations
you can also add <option> authority</option>, which would trigger the authority
lookup.</para>
<para>must at least contain <option>annotation-action</option>. The <option>toggle</option> indicates that this is a toggling annotation, which just
switches between on and off and does not need further input. For semantic annotations you can also add <option>authority</option>, which would
trigger the authority lookup.</para>
</listitem>
</varlistentry>
<varlistentry>
Expand Down Expand Up @@ -7144,19 +7140,19 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
parameter:</para>
<para>To achieve this, go back to <filename>templates/pages/annotate.html</filename> and
remove the <option>toggle</option> class from the <tag>paper-icon-button</tag>:</para>
<programlisting>&lt;paper-icon-button class="annotation-action" title="Foreign" data-type="foreign" icon="icons:language" data-shortcut="⌘+⇧+b,ctrl+⇧+b" disabled="disabled">&lt;/paper-icon-button></programlisting>
<para>We would also like to provide an input field into which the user can enter the language.
Scroll down to where the <tag>form</tag> is defined and add another input on top:</para>
<programlisting>&lt;paper-icon-button class="annotation-action" title="Foreign"
data-type="foreign" icon="icons:language" data-shortcut="⌘+⇧+b,ctrl+⇧+b"
disabled="disabled">&lt;/paper-icon-button></programlisting>
<para>We would also like to provide an input field into which the user can enter the language. Scroll down to the "Annotation Details" section in which
the <tag>form</tag> for the annotation types is defined and add another input on top:</para>
<programlisting>&lt;iron-form id="edit-form">
&lt;form action="">
&lt;paper-input class="annotation-form foreign" name="lang" label="Language">&lt;/paper-input>
...
&lt;/iron-form></programlisting>
<para>Again we're using a webcomponent for the input to get the material design look and feel.
The class attribute is particularly important: it must always contain <option>
annotation-form</option>, followed by the annotation type: <option>foreign</option>. The
name is arbitrary, but should be unique and we need to remember it for later. The label
should contain a short title, which will be shown next to the input.</para>
<para>Again we're using a webcomponent for the input to get the material design look and feel. The class attribute is particularly important: it must
always contain <option>annotation-form</option>, followed by the annotation type: <option>foreign</option>. The name is arbitrary, but should be unique
and we need to remember it for later. The label should contain a short title, which will be shown next to the input.</para>
<para>Finally, we need to change our rule in
<filename>modules/annotation-config.xqm</filename> to add the new parameter to the
generated <tag>foreign</tag> element. Navigate to the file and change the
Expand All @@ -7167,11 +7163,17 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
&lt;foreign xmlns="http://www.tei-c.org/ns/1.0" xml:lang="{$properties?lang}">{$content()}&lt;/foreign>
...
};</programlisting>
<para>The function receives all the parameters entered into the form fields in the <varname>
$properties</varname> map. In the form we used <code>name="lang"</code>, so the
corresponding value is retrieved from the map with <code>$properties?lang</code>.</para>
<para>The function receives all the parameters entered into the form fields in the <varname>$properties</varname> map. In the form we used
<code>name="lang"</code>, so the corresponding value is retrieved from the map with <code>$properties?lang</code>.</para>
<para>That's all. You should now be able to modify your existing foreign annotation, enter a
language and see how it is output into TEI.</para>
<section>
<title>Inserting an annotation before the selection</title>
<para>By default, the text currently selected on the page will become the content of the annotation. For some elements we don't want this though. A page
break (<tag>pb</tag>) or a note would be typical examples. The editor supports this: if you add a class <option>before</option> to the annotation
action button, TEI Publisher will not replace the text, but insert the new annotation before the selection:</para>
<synopsis language="xml">&lt;paper-icon-button class="annotation-action before">...&lt;/paper-icon-button></synopsis>
</section>

</section>
<section>
Expand Down

0 comments on commit a57b645

Please sign in to comment.