Various fixed in documentation, especially cross-references #43

docs/source/alternative_annotation.rst

@@ -17,7 +17,7 @@ Specification
 :Version History: Since the beginning, may carry set and classes since v2.0
 :**Element**: ``<alt>``
 :API Class: ``Alternative``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``processor`` -- This refers to the ID of a processor in the :ref:`provenance_data`. The processor in turn defines exactly who or what was the annotator of the annotation.
                       * ``annotator`` -- This is an older alternative to the ``processor`` attribute, without support for full provenance. The annotator attribute simply refers to the name o ID of the system or human annotator that made the annotation.
@@ -35,7 +35,7 @@ Specification
 .. foliaspec:specification_element(AlternativeLayers)
 :**Element**: ``<altlayers>``
 :API Class: ``AlternativeLayers``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``processor`` -- This refers to the ID of a processor in the :ref:`provenance_data`. The processor in turn defines exactly who or what was the annotator of the annotation.
                       * ``annotator`` -- This is an older alternative to the ``processor`` attribute, without support for full provenance. The annotator attribute simply refers to the name o ID of the system or human annotator that made the annotation.
@@ -190,6 +190,7 @@ identifier.
 Below is an example of a sentence that is chunked in two ways:
 
 .. code-block:: xml
+
     <s xml:id="example.p.1.s.1">
       <t>The Dalai Lama greeted him.</t>
       <w xml:id="example.p.1.s.1.w.1"><t>The</t></w>

docs/source/chunking_annotation.rst

@@ -18,8 +18,8 @@ Specification
 :**Element**: ``<chunk>``
 :API Class: ``Chunk``
 :Layer Element: chunking
-:Span Role Elements: 
-:Required Attributes: 
+:Span Role Elements:
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -42,7 +42,7 @@ Explanation
 
 .. note::
 
-    Please first ensure you are familiar with the general principles of :ref:`span_annotation` to make sense of this annotation type.
+    Please first ensure you are familiar with the general principles of :ref:`span_annotation_category` to make sense of this annotation type.
 
 Example
 -------------------------

docs/source/coreference_annotation.rst

@@ -19,7 +19,7 @@ Specification
 :API Class: ``CoreferenceChain``
 :Layer Element: coreferences
 :Span Role Elements: ``CoreferenceLink``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -42,7 +42,7 @@ Explanation
 
 .. note::
 
-    Please first ensure you are familiar with the general principles of :ref:`span_annotation` to make sense of this annotation type.
+    Please first ensure you are familiar with the general principles of :ref:`span_annotation_category` to make sense of this annotation type.
 
 Relations between words that refer to the same referent are expressed in FoLiA
 using the ``<coreferencechain>`` span annotation element and the ``<coreferencelink>``

docs/source/dependency_annotation.rst

@@ -19,7 +19,7 @@ Specification
 :API Class: ``Dependency``
 :Layer Element: dependencies
 :Span Role Elements: ``DependencyDependent``, ``Headspan``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -42,7 +42,7 @@ Explanation
 
 .. note::
 
-    Please first ensure you are familiar with the general principles of :ref:`span_annotation` to make sense of this annotation type.
+    Please first ensure you are familiar with the general principles of :ref:`span_annotation_category` to make sense of this annotation type.
 
 Dependency relations are syntactic relations between spans of tokens. A dependency relation takes a particular class and
 consists of a single head component and a single dependent component. In the

docs/source/entity_annotation.rst

@@ -18,8 +18,8 @@ Specification
 :**Element**: ``<entity>``
 :API Class: ``Entity``
 :Layer Element: entities
-:Span Role Elements: 
-:Required Attributes: 
+:Span Role Elements:
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -42,7 +42,7 @@ Explanation
 
 .. note::
 
-    Please first ensure you are familiar with the general principles of :ref:`span_annotation` to make sense of this annotation type.
+    Please first ensure you are familiar with the general principles of :ref:`span_annotation_category` to make sense of this annotation type.
 
 The ``entities`` layer offers a generic solution to encode various types
 of entities or *multi-word expressions*, including but not limited to named

docs/source/features.rst

@@ -6,7 +6,7 @@ Features
 In addition to a main class, an arbitrary number of *features* can be
 added to *any* annotation element that takes a set. Each feature pertains to a specific
 *subset* in that set and assigns a *class* in the subset. The subsets and classes therein are defined in the
-set definition (See :ref:`set_definition`), so may be entirely user-defined.
+set definition (See :ref:`set_definitions`), so may be entirely user-defined.
 
 The element ``<feat>`` is used to add features to any kind of annotation. In
 the following example we make use of a subset we invented which ties a lemma to
@@ -68,6 +68,7 @@ no longer suffices, and the ``<feat>`` element must be used explicitly.
 
 .. TODO: is this really implemented well in the libraries??
 .. code-block:: xml
+
     <event class="conversation">
      <feat subset="actor" class="John Doe" />
      <feat subset="actor" class="Jane Doe" />

docs/source/gap_annotation.rst

@@ -20,7 +20,7 @@ Structure Element
 :Version History: Since the beginning
 :**Element**: ``<gap>``
 :API Class: ``Gap``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -41,7 +41,7 @@ Text markup Element
 .. foliaspec:specification_element(TextMarkupGap)
 :**Element**: ``<t-gap>``
 :API Class: ``TextMarkupGap``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -58,7 +58,7 @@ Text markup Element
                       * ``xlink:href`` -- Turns this element into a hyperlink to the specified URL
                       * ``xlink:type`` -- The type of link (you'll want to use ``simple`` in almost all cases).
 :Accepted Data: ``<comment>`` (:ref:`comment_annotation`), ``<desc>`` (:ref:`description_annotation`), ``<br>`` (:ref:`linebreak_annotation`)
-:Valid Context: 
+:Valid Context:
 
 Explanation
 -------------------------
@@ -69,7 +69,7 @@ user-defined set. Common omissions are for example front-matter and back-matter,
 a foreign language. Again, the semantics depend on your set.
 
 Although a gap skips over content, you may still want to explicitly add the raw content, this is done with the ``<content>``
-element (see :ref:`content_annotation`). As this concerns raw content, it can not be annotated any
+element (see :ref:`rawcontent_annotation`). As this concerns raw content, it can not be annotated any
 further and we use XML CDATA type here to include it verbatim.
 
 The following example shows the the use of ``<gap>``:

docs/source/hyperlinks.rst

@@ -36,7 +36,7 @@ references (``<ref>`` elements) that are actual structure elements. The
 hyperlinking method described in this section is of a more text-mark-up or stylistic
 nature. Actual references are usually preferred when applicable.
 
-Another notion of linking is implemented using FoLiA's *relations* (:ref:`relation_annotatation`).  Relations are actual
+Another notion of linking is implemented using FoLiA's *relations* (:ref:`relation_annotation`).  Relations are actual
 higher-order annotations that can link anything but it needs not be reflected in the actual text, whereas the hyperlinks
 described here and the references of :ref:`reference_annotation` do always show in the text.
 

docs/source/observation_annotation.rst

@@ -18,8 +18,8 @@ Specification
 :**Element**: ``<observation>``
 :API Class: ``Observation``
 :Layer Element: observations
-:Span Role Elements: 
-:Required Attributes: 
+:Span Role Elements:
+:Required Attributes:
 :Optional Attributes: * ``xml:id`` -- The ID of the element; this has to be a unique in the entire document or collection of documents (corpus). All identifiers in FoLiA are of the `XML NCName <https://www.w3.org/TR/1999/WD-xmlschema-2-19990924/#NCName>`_ datatype, which roughly means it is a unique string that has to start with a letter (not a number or symbol), may contain numers, but may never contain colons or spaces. FoLiA does not define any naming convention for IDs.
                       * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
@@ -42,7 +42,7 @@ Explanation
 
 .. note::
 
-    Please first ensure you are familiar with the general principles of :ref:`span_annotation` to make sense of this annotation type.
+    Please first ensure you are familiar with the general principles of :ref:`span_annotation_category` to make sense of this annotation type.
 
 The ``<observation>`` element is a span annotation element that makes an observation
 pertaining to one or more word tokens. It is embedded in an

docs/source/phon_annotation.rst

@@ -17,7 +17,7 @@ Specification
 :Version History: Since v0.12
 :**Element**: ``<ph>``
 :API Class: ``PhonContent``
-:Required Attributes: 
+:Required Attributes:
 :Optional Attributes: * ``set`` -- The set of the element, ideally a URI linking to a set definition (see :ref:`set_definitions`) or otherwise a uniquely identifying string. The ``set`` must be referred to also in the :ref:`annotation_declarations` for this annotation type.
                       * ``class`` -- The class of the annotation, i.e. the annotation tag in the vocabulary defined by ``set``.
                       * ``processor`` -- This refers to the ID of a processor in the :ref:`provenance_data`. The processor in turn defines exactly who or what was the annotator of the annotation.
@@ -31,7 +31,7 @@ Specification
 Explanation
 -------------------------
 
-Written text is always contained in the text content element (``<t>``, see :ref:`text_content`), for
+Written text is always contained in the text content element (``<t>``, see :ref:`text_annotation`), for
 phonology there is a similar counterpart that behaves almost identically: ``<ph>``. This element
 holds a phonetic or phonological transcription. It is used in a very similar fashion:
 

docs/source/provenance_data.rst

@@ -93,10 +93,11 @@ edit a FoLiA document and add/edit annotations:
         </processor>
     </provenance>
 
-From the :ref:`annotation declarations`, we can then also refer directly to subprocessors. Moreover, a processor can be
+From the :ref:`annotation_declarations`, we can then also refer directly to subprocessors. Moreover, a processor can be
 referred to from multiple annotation types/sets:
 
 .. code-block:: xml
+
     <annotations>
       ...
       <pos-annotation set="...">