Documentation for #33 (Syntax for milestones)

docs/about/releasenotes.rst

@@ -42,20 +42,20 @@ USFM 3.0 additions or revisions are highlighted throughout this documentation us
 
 * Support citation form for wordlist / glossary text (update :ref:`\\w ...\\w\* <usfmc_w>`).
 * Support for explicit :ref:`table cell <usfmc_tc#>` column :ref:`spanning <usfmc_table_colspan>`.
-* Revised syntax for figures / illustrations applying descriptive :doc:`attributes </characters/attributes>`: :ref:`\\fig ...\\fig\* <usfmc_fig-attr>`
+* Revised syntax for figures / illustrations applying descriptive :doc:`attributes </attributes/index>`: :ref:`\\fig ...\\fig\* <usfmc_fig-attr>`
 * *Deprecate* cross reference and footnote DC content markers: :ref:`\\xdc ...\\xdc\* <usfmc_xdc>` and :ref:`\\fdc ...\\fdc\* <usfmc_fdc>`
 * *Deprecate* combined marker for proper name within translator's addition: :ref:`\\addpn ...\\addpn\* <usfmc_addpn>`
 * *Deprecate* numbered running header: :ref:`\\h# <usfmp_h>`
 * *Deprecate* pronunciation info marker: :ref:`\\pro ...\\pro\* <usfmc_pro>` in favour of :ref:`ruby annotations <usfmc_rb>` proposal.
 
 **Syntax and Features**
 
-* Syntax for assigning word-level descriptive :doc:`attributes </characters/attributes>`.
+* Syntax for assigning word-level :doc:`descriptive attributes </attributes/index>`.
 
     - Descriptive attributes for :ref:`\\w ...\\w\* <usfmc_w-attr>`
     - Descriptive attributes for :ref:`\\fig ...\\fig\* <usfmc_fig-attr>`
 
-* Syntax for assigning word-level linking :doc:`attributes </characters/linking>`.
+* Syntax for assigning word-level :doc:`linking attributes </linking/index>`.
 * Syntax for peripheral (:doc:`\\periph </peripherals/index>`) :ref:`identifiers <periph_id>`.
 
 **Standard Reference**

docs/characters/attributes.rst → docs/attributes/index.rst

@@ -28,8 +28,7 @@ Within a character marker span, an attributes list is separated from the text co
 .. _attributes_default:
 .. index:: attributes; default
 
-Default Attribute
-^^^^^^^^^^^^^^^^^
+.. rubric:: Attributes |ico_Tag|
 
 When content is supplied in the position of a marker attribute, but without an explicit attribute name, the USFM specification defines a single default. Defaults are only provided for :ref:`markers <attributes_markersProviding>` which formally provide attributes in the current version of USFM.
 

docs/characters/index.rst

@@ -9,8 +9,6 @@ Words and Characters
    :maxdepth: 1
 
    Character Marker Nesting <nesting>
-   Word Level Attributes <attributes>
-   Linking Attributes <linking>
 
 -----
 
@@ -595,7 +593,7 @@ Special Features
 
 .. caution:: |badge_3.0| **Significant syntax change from USFM 1.x / 2.x**
 
-	The syntax for defining illustrations in USFM 3.0 follows the general syntax for providing :doc:`word level attributes </characters/attributes>`. In USFM 1.x and 2.x, markup for illustrations required a the content for a collection of parameters to be provided in a specific order, with items separated by a vertical bar (e.g ``\fig_DESC|FILE|SIZE|LOC|COPY|CAP|REF\fig*``). The use of marker attributes, and the use of a vertical bar as an attribute separator was unique to illustration markup in USFM 1.x and 2.x. In USFM 3.0 this syntax is deprecated in order to align the markup with the general syntax for :doc:`word level attributes </characters/attributes>`.
+	The syntax for defining illustrations in USFM 3.0 follows the general syntax for providing :doc:`word level attributes </attributes/index>`. In USFM 1.x and 2.x, markup for illustrations required a the content for a collection of parameters to be provided in a specific order, with items separated by a vertical bar (e.g ``\fig_DESC|FILE|SIZE|LOC|COPY|CAP|REF\fig*``). The use of marker attributes, and the use of a vertical bar as an attribute separator was unique to illustration markup in USFM 1.x and 2.x. In USFM 3.0 this syntax is deprecated in order to align the markup with the general syntax for :doc:`word level attributes </attributes/index>`.
 
 .. _usfmc_fig-attr:
 .. index:: attributes; \fig ...\fig*, figure; attributes, illustration; attributes
@@ -604,7 +602,7 @@ Special Features
 
 |badge_3.0|
 
-Following the syntax for :doc:`word level attributes </characters/attributes>`. Required attributes are indicated in the list below with a red asterisk :red:`*`.
+Following the syntax for :doc:`word level attributes </attributes/index>`. Required attributes are indicated in the list below with a red asterisk :red:`*`.
 
 * Multiple attributes are required. There is no single, un-named :ref:`default <attributes_default>`.
 * **Compatibility with USFM 1.x and 2.x:** If a USFM parser encounters a list of un-named attributes using a vertical bar separator within ``\fig ...\fig*`` these should be interpreted according to the strict USFM 2.x order.
@@ -754,7 +752,7 @@ Following the syntax for :doc:`word level attributes </characters/attributes>`.
 
 |badge_3.0|
 
-Following the syntax for :doc:`word level attributes </characters/attributes>`.
+Following the syntax for :doc:`word level attributes </attributes/index>`.
 
 :lemma: Citation form for the term in the glossary *(default)*
 

docs/index.rst

@@ -30,8 +30,11 @@ USFM Documentation
    Footnotes <notes_basic/fnotes>
    Cross References <notes_basic/xrefs>
    Words and Characters <characters/index>
-   Peripherals <peripherals/index>
+   Word Level Attributes <attributes/index>
+   Linking Attributes <linking/index>
+   Milestones <milestones/index>
    Extended Study Content <notes_study/index>
+   Peripherals <peripherals/index>
 
 .. Character Marker Attributes <characters/attributes>
    Linking <characters/linking>

docs/milestones/index.rst

@@ -0,0 +1,83 @@
+.. include:: /_static/inc_styles.txt
+
+.. index:: milestones, speaker; start/end markup
+
+Milestones
+==========
+
+|badge_3.0|
+
+USFM 3.0 provides a general syntax for indicating the start and ending milestones for a span of text, where the boundaries of the content being marked may cross one or more paragraph boundaries.
+
+A milestone type markup is required when a document has two or more structures that interact in a non-hierarchical manner. This is also referred to as *overlapping* or *concurrent* markup. A principle example of this type of overlapping structure in scripture text is the contrast between 1) the paragraph structures used to express the discourse / narrative of the text and 2) the division of the text into books, chapters and verses. In scripture texts encoded using USFM (and similarly also in `USX <https://ubsicap.github.io/usx/index.html>`_), the paragraph level markup forms the main structure of the document, while :ref:`chapter <usfmp_c>` and :ref:`verse <usfmc_v>` markers are effectively a milestone type.
+
+Another example of an overlapping structure exists when there is a need to indicate the start and end of the quotations of the "actors" who are speaking within the text. These spans of text will commonly cross paragraph boundaries.
+
+.. _milestones_syntax:
+.. index:: miletones; syntax
+
+General Syntax
+^^^^^^^^^^^^^^
+
+Milestones follow a syntax similar to the current :doc:`character level markup </characters/index>`. The significant distinguishing feature is that milestones introduce a new **self-closing** syntax. This self-closing syntax is the feature which identifies the marker as a milestone. The milestone will mark the *position* of the start or end of a span of text, but it does not strictly *contain* the text, as with a regular character level markup.
+
+A benefit of the self-closing marker syntax is that it also results in a shorter marker string.
+
+Self closing markup is indicated by immediately terminating the marker, and any attributes, with a backslash plus asterisk.
+
+**Example:** (milestone for the start of a quotation / speaker)
+
+.. code-block:: text
+
+    \qts\*
+
+.. _milestones_startend:
+.. index:: miletones; start and end
+
+Indicating Start and End Milestones
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A milestone marker must always end with either ``s`` or ``e``
+
+* ``s`` indicates that the milestone is for marking the **start** of a span of text.
+* ``e`` indicates that the marker is an **end** milestone.
+
+**Example:** (milestone for the end of a quotation / speaker)
+
+.. code-block:: text
+
+    \qte\*
+
+.. _milestones_attributes:
+.. index:: milestones; attributes
+
+Attributes
+^^^^^^^^^^
+
+Following the syntax for :doc:`word level attributes </attributes/index>`, the following optional attributes can be added to *any* USFM milestone marker.
+
+:id: A unique identifier which can be used to unambiguously associate the start and ending milestone marker. |br|
+	The id can be composed of any mixture of numbers, letters, and underscores, and should be unique throughout the scripture text for the selected milestone type.
+
+**Example:**
+
+.. code-block:: text
+
+    \qts |id="123" who="Pilate"\*“Are you the king of the Jews?”\qte |id="123"\*
+
+Additional attributes may be available for or required by a specific USFM milestone marker (e.g the use of the ``who`` attribute in the above :ref:`quotation milestone <usfmm_qt#s>` example).
+
+Levels
+^^^^^^
+
+As with other USFM :ref:`numbered markers <syntax_numberedMarkers>`, a numeric variable may be added to a milestone marker to indicate a relative weighting or level. In the example of the quotation / speaker milestone, a numbered version of the marker may be used to indicate the level of nesting of the quotation being marked (i.e. a quote within a quote).
+
+The unnumbered version may be used when only one level of marker exists within the project text. Numbers should always be included when more than one level of the marker exists within the project text.
+
+-----
+
+.. _usfmm_qt#s:
+.. index:: marker; \qt#s\*, marker; \qt#e\*, milestone; \qt#s\*, milestone; \qt1e\* 
+
+\\qt#s\\*
+^^^^^^^^^