documentation restructuring so we have saner chapters and the PDF loo…

…ks nice too #43

docs/source/annotation_declarations.rst

@@ -1,10 +1,7 @@
 .. _annotation_declarations:
 
 Annotation Declarations
-==========================
-
-Introduction
----------------
+--------------------------
 
 All annotation types that are used in a FoLiA document have to be *declared*. In the metadata block you will find the
 ``<annotations>`` block in which each annotation type that occurs in the document is mentioned, i.e. declared. So does
@@ -61,8 +58,7 @@ available: If you do not refer to processors for a certain annotation type and s
 * ``annotator`` - The name of the default annotator (either human or software)
 * ``annotatortype`` - Set to ``auto`` if the default annotator is automatic annotation by software or ``manual`` for human annotators
 
-
-More about set definitions
+Set definitions
 ---------------------------
 
 A *set definition* (see :ref:`set_definitions`) specifies exactly what classes are allowed in a particular vocabulary.

docs/source/foreign_annotation.rst

@@ -4,17 +4,17 @@ Foreign Annotation
 ==================================================================
 
 It may happen that you want to include annotations inside your FoLiA that are not actually in FoLiA, but in some other
-XML format. Though this is generally discouraged, even more so if FoLiA has proper facilities for your annotation needs,
-it may in rare cases be needed, for example if FoLiA has no support yet for a particular advanced
-type of annotation or if another scheme has already been in use. It is most
-suitable for attaching further metadata to arbitrary elements.
+XML format. Though **this is very much discouraged**, even more so if FoLiA has proper facilities for your annotation needs,
+it may in rare cases be needed; for example if FoLiA has no support yet for a particular advanced
+type of annotation or if another scheme has already been in use and conversion is not an option. It is most
+suitable for attaching further data to arbitrary elements, though for metadata :ref:`submetadata` should always be considered first!
 
 The higher-order annotation element ``<foreign-data>`` can be used to accomplish
-this. It acts as a container in which annotation must be in a different XML namespace,
+foreign annotations. It acts as a container in which annotation must be in a different XML namespace,
 rather than the FoLiA namespace. The element is allowed almost
 anywhere: inside structure annotation, inside inline/span annotation, inside
 other higher annotation elements, but
-\emph{not} inside text content (``<t>``), phonetic content (``<ph>``) or text-markup
+**not** inside text content (``<t>``), phonetic content (``<ph>``) or text-markup
 (``<t-*>``).
 
 In the following example we attach an annotation in a custom fictitious XML format and namespace to a FoLiA word:
@@ -28,8 +28,8 @@ In the following example we attach an annotation in a custom fictitious XML form
       </foreign-data>
    </w>
 
-Foreign annotation does not need to be declared and should really only be used when no proper
-FoLiA solution exists, and even in such cases it is preferable to contact the FoLiA developers and see if FoLiA can be
-extended for your needs.. Be aware that generic FoLiA tools and libraries will usually not process the contents of
-foreign-data, as it can contain anything by definition, and special-purpose tools need to be
-written for your specific use case if you use foreign-data.
+Foreign annotation does not need to be declared and, as can not be emphasised enough, should really only be used when no
+proper FoLiA solution exists, and even in such cases it is preferable to contact the FoLiA developers and see if FoLiA
+can be extended for your needs.. Be aware that generic FoLiA tools and libraries will usually not process the contents
+of foreign-data, as it can contain anything by definition, and special-purpose tools need to be written for your
+specific use case if you use foreign-data.

docs/source/hyperlinks.rst

@@ -1,7 +1,7 @@
 .. _hyperlinks:
 
 Hyperlinks
-====================================================
+----------------
 
 Hyperlinks are ubiquitous in documents from the web and are therefore supported
 in FoLiA as well. A hyperlink can be defined as a pointer from a span of text to an

docs/source/index.rst

@@ -20,13 +20,9 @@ Get started with this FoLiA documentation by reading the full :ref:`introduction
     :includehidden:
 
     introduction
-    annotation_declarations
-    set_definitions
     metadata
-    provenance_data
-    speech
+    set_definitions
     annotation_types
-    hyperlinks
     foreign_annotation
     querying
     implementations

docs/source/introduction.rst

@@ -343,7 +343,7 @@ attributes per annotation type. Altogether, we distinguish the following:
 * ``datetime`` -- The date and time when this annotation was recorded, the format is ``YYYY-MM-DDThh:mm:ss`` (note the literal T in the middle to separate date from time), as per the XSD Datetime data type.
 * ``n`` -- A number in a sequence, corresponding to a number in the original document, for example chapter numbers, section numbers, list item numbers. This this not have to be an actual number but other sequence identifiers are also possible (think alphanumeric characters or roman numerals).
 * ``textclass`` -- Refers to the text class this annotation is based on. This is an advanced attribute, if not specified, it defaults to ``current``. See :ref:`textclass_attribute`.
-* ``space`` -- This attribute indicates whether spacing should be inserted after this element (it's default value is always ``yes``, so it does not need to be specified in that case), but if tokens or other structural elements are glued together then the value should be set to ``no``. This allows for reconstruction of the detokenised original text. 
+* ``space`` -- This attribute indicates whether spacing should be inserted after this element (it's default value is always ``yes``, so it does not need to be specified in that case), but if tokens or other structural elements are glued together then the value should be set to ``no``. This allows for reconstruction of the detokenised original text.
 
 **Speech attributes**, the following attributes apply mostly in a speech context (please read :ref:`speech` for more):
 
@@ -386,3 +386,6 @@ Certain FoLiA elements take an ``id`` attribute in the FoLiA XML
 namespace instead of the ``XML`` namespace, these are
 always *references* to the ID of another element. It's important not to confuse the two.
 
+.. include:: speech.rst
+
+.. include:: hyperlinks.rst

docs/source/metadata.rst

@@ -3,9 +3,21 @@
 Metadata
 ========================
 
-FoLiA supports associating metadata with your document. An extensive and mandatory part of the metadata is the
-:ref:`annotation_declarations` block (``<annotations>``), and optionally also the block for :ref:`provenance_data`
-(``<provenance>``). To associate other arbitrary metadata with a FoLiA document, there is FoLiA's native metadata system,
+FoLiA supports associating metadata with your document, you will find this in the ``<metadata>`` document at the very
+beginning of the document. An extensive and mandatory part of this metadata is the
+:ref:`annotation_declarations` block (``<annotations>``), and second (optionally) the block for :ref:`provenance_data`
+(``<provenance>``). The remainder of the ``<metadata>`` block may be filled with Document Metadata as described in
+:ref:`document_metadata` later.
+on.
+
+.. include:: annotation_declarations.rst
+
+.. _document_metadata:
+
+Document Metadata
+-----------------------
+
+To associate other arbitrary metadata with a FoLiA document, there is FoLiA's native metadata system,
 in which simple metadata fields can be defined and used at will through the ``<meta>`` element. The following example shows
 document-wide metadata:
 
@@ -120,3 +132,5 @@ multiple structural elements if there is no catch-all structure).
 
 Submetadata is inherited (recursively), i.e. it is not necessary to explicitly assign the ``metadata`` attribute to the children
 of an element that already has such an assignment.
+
+.. include:: provenance_data.rst

docs/source/provenance_data.rst

@@ -1,7 +1,7 @@
 .. _provenance_data:
 
 Provenance Data
-========================
+----------------------
 
 It is often desireable to know exactly what tools (and what versions thereof and even with what parameters) were invoked
 in which order to produce a FoLiA document, this is called **provenance data**. In the metadata section, right after the

docs/source/speech.rst

@@ -1,7 +1,7 @@
 .. _speech:
 
 Speech
-===========
+---------
 
 FoLiA is also suited for annotation of speech data. The following additional
 generic FoLiA attributes are available for *all* structure annotation elements in
@@ -39,7 +39,7 @@ should still use the normal :ref:`text_annotation` for a normal textual transcri
 For further segmentation of speech into phonemes, you can use :ref:`phonological_annotation`.
 
 Example
------------
+~~~~~~~~~
 
 An example of a simple speech document: