Documentation for #28 (syntax for peripheral identifiers)

ubsicap · Aug 15, 2016 · 8e0cbbe · 8e0cbbe
1 parent 519077a
commit 8e0cbbe
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 18 deletions.
diff --git a/docs/identification/books.rst b/docs/identification/books.rst
@@ -4,7 +4,7 @@
 
 Book Identifiers
 ================
-This table lists all the standard 3-character book identifiers that can be entered after \id marker at the top of each USFM file. Some scripture editors like `Paratext <http://paratext.org>`_ may also include the number shown for each book in the filename for that book.
+This table lists all the standard 3-character book identifiers that can be entered after the \\id marker at the top of each USFM file. Some scripture editors like `ParaTExt <http://paratext.org>`_ may also include the number shown for each book in the filename for that book.
 
 .. csv-table::
 	:header: "Number", "Identifier", "English Name", "Alternative name / Notes"
@@ -170,3 +170,11 @@ This table lists all the standard 3-character book identifiers that can be enter
 	as chapter 1, used in the Ethiopian Bible"
 	"C3", "LAO", "Letter to the Laodiceans", "A Latin Vulgate book, found in the Vulgate |br|
 	and some medieval Catholic translations"
+	"A0", "FRT", "Front Matter"
+	"A1", "BAK", "Back Matter"
+	"A2", "OTH", "Other Matter"
+	"A7", "INT", "Introduction Matter"
+	"A8", "CNC", "Concordance"
+	"A9", "GLO", "Glossary / Wordlist"
+	"B0", "TDX", "Topical Index"
+	"B1", "NDX", "Names Index"
diff --git a/docs/peripherals/index.rst b/docs/peripherals/index.rst
@@ -1,61 +1,120 @@
 .. include:: /_static/inc_styles.txt
 
-.. index:: peripherals, peripherals (books), peripherals (divisions), marker (\periph), periph
+.. index:: peripherals, marker (\periph), periph
 
 Peripherals
 ===========
 
-The following represents a strategy for applying USFM markup to various peripheral content elements which may be prepared for publication in addition to the scripture body text. Peripheral content markup is accomplished through re-purposing the most appropriate existing USFM marker for the current content type.
+The following strategy should be used for applying USFM markup to project peripheral contents.
 
-As with scripture text books, an :ref:`\\id <usfmp_id>` marker is used for identifying the content of the peripheral file. Content should be created in separate book files according to the following general groupings. Within each book, divisions (sub-sections) of content are denoted using the marker ``\periph`` followed by an additional division argument/title. In practice we find that some back matter content is large enough to require storing it in its own book file (Concordance, Glossary, Topical Index, Names Index).
+Content should be created in separate :doc:`book </identification/books>` files according to the general groupings presented in the table below. As with scripture text books, an :ref:`\\id <usfmp_id>` marker is used for identifying the overall content of the peripheral file. Within each book, divisions (sub-sections) of content are denoted using the marker ``\periph`` followed by an additional division title. Content is added to books and divisions by re-purposing the most appropriate existing USFM marker for the selected content.
+
+Some back matter content is large enough that it is most practical to store it within its own book file (Concordance, Glossary, Topical Index, Names Index). Content self contained within a separate book file does not require an additional identifier (only :ref:`\\id <usfmp_id>`).
+
+.. _periph_div:
+.. index:: peripherals (books), peripherals (divisions)
 
 Peripheral Books and Divisions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 +-------------------------------+----------------------------------+------------------------------+
-| :doc:`Front Matter <front>`   | :doc:`Introductions <intros>`    | :doc:`BackMatter <back>`     |
+| :doc:`Front Matter <front>`   | :doc:`Introductions <intros>`    | :doc:`Back Matter <back>`    |
 | (\\id FRT)                    | (\\id INT)                       | (\\id BAK)                   |
 +===============================+==================================+==============================+
 | **Divisions**                 | **Divisions**                    | **Divisions**                |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Title Page``        | ``\periph Bible Intorduction``   | ``\periph Chronology Test``  |
+| |br| ``|id="title"``          | |br| ``|id="intbible"``          | |br| ``|id="chron"``         |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Half Title Page``   | ``\periph Old Testament          | ``\periph Weights and        |
-|                               | Introduction``                   | Measures``                   |
+| |br| ``|id="halftitle"``      | Introduction``                   | Measures``                   |
+|                               | |br| ``|id="intot"``             | |br| ``|id="measures"``      |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Promotional Page``  | ``\periph Pentateuch             | ``\periph Map Index``        |
-|                               | Introduction``                   |                              |
+| |br| ``|id="promo"``          | Introduction``                   | |br| ``|id="maps"``          |
+|                               | |br| ``|id="intpent"``           |                              |
 +-------------------------------+----------------------------------+------------------------------+
-| ``\periph Imprimatur``        | ``\periph History Introduction`` | ``\periph NT Quotes in LXX`` |
+| ``\periph Imprimatur``        | ``\periph History Introduction`` | ``\periph LXX Quotes in NT`` |
+| |br| ``|id="imprimatur"``     | |br| ``|id="inthistory"``        | |br| ``|id="lxxquotes"``     |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Publication Data``  | ``\periph Poetry Introduction``  | **Additional Back Matter**   |
+| |br| ``|id="pubdata"``        | |br| ``|id="intpoetry"``         |                              |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Foreword``          | ``\periph Prophecy               | Concordance (\\id CNC)       |
-|                               | Introduction``                   |                              |
+| |br| ``|id="foreword"``       | Introduction``                   |                              |
+|                               | |br| ``|id="intprophesy"``       |                              |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Preface``           | ``\periph Deuterocanon           | Glossary (\id GLO)           |
-|                               | Introduction``                   |                              |
+| |br| ``|id="preface"``        | Introduction``                   |                              |
+|                               | |br| ``|id="intdc"``             |                              |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Table of Contents`` | ``\periph New Testament          | Topical Index (\id TDX)      |
-|                               | Introduction``                   |                              |
+| |br| ``|id="contents"``       | Introduction``                   |                              |
+|                               | |br| ``|id="intnt"``             |                              |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Alphabetical        | ``\periph Gospels Introduction`` | Names Index (\id NDX)        |
-| Contents``                    |                                  |                              |
+| Contents``                    | |br| ``|id="intgospels"``        |                              |
+| |br| ``|id="alphacontents"``  |                                  |                              |
 +-------------------------------+----------------------------------+------------------------------+
 | ``\periph Table of            | ``\periph Epistles               | :doc:`Other <other>`         |
-| Abbreviations``               | Introduction``                   |                              |
+| Abbreviations``               | Introduction``                   | **(\\id OTH)**               |
+| |br| ``|id="abbreviations"``  | |br| ``|id="intepistles"``       |                              |
 +-------------------------------+----------------------------------+------------------------------+
 |                               | ``\periph Letters Introduction`` | **Divisions**                |
+|                               | |br| ``|id="intletters"``        |                              |
 +-------------------------------+----------------------------------+------------------------------+
 |                               |                                  | ``\periph Cover``            |
+|                               |                                  | |br| ``|id="cover"``         |
 +-------------------------------+----------------------------------+------------------------------+
 |                               |                                  | ``\periph Spine``            |
+|                               |                                  | |br| ``|id="spine"``         |
 +-------------------------------+----------------------------------+------------------------------+
 
-User defined peripheral content divisions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. index:: peripherals (identifiers)
+.. _periph_id:
+
+Peripheral Identifiers
+^^^^^^^^^^^^^^^^^^^^^^
+
+|badge_3.0|
+
+For peripheral books containing :ref:`divisions <periph_div>`, the division title is free-form, and may be expressed in the vernacular language. Whenever possible, a peripheral identifier should be associated with a ``\periph`` division marker. A set of standardized identifiers allow software processes to easily select content for recognized peripheral divisions. The syntax for peripheral identifiers follows the syntax for :doc:`word level attributes </characters/attributes>`: attribute = "value". The attribute name is ``id``. The value is wrapped in quotes.
+
+**Text sample with division identifier attributes:**
+
+.. code-block:: text
+
+	\id FRT
+	...
+	\periph Title Page|id="title"
+	\mt1 Holy Bible
+	\mt3 with
+	\mt2 Deuterocanonicals/Apocrypha
+	...
+	\periph Foreword|id="foreword"
+	\h Foreword
+	\mt1 Foreword
+	\p The \bk Good News Translation\bk* of the Bible is a translation which seeks to state 
+	clearly and accurately the meaning of the original texts in words and forms that are widely 
+	accepted by people who use English as a means of communication.
+	...
+	\periph Table of Contents|id="contents"
+	\h Table of Contents
+	\mt Contents
+	\s Old Testament
+	\tr  \th1 Name  \thr2 Page \th3 Name \thr4 Page
+	\tr \tc1 Genesis \tcr2 # \tc3 Ecclesiastes \tcr4 #
+	...
+
+Defined peripheral ``id`` values are shown in the peripheral :ref:`divisions <periph_div>` table above.
+
+.. index:: peripherals (user defined divisions)
+.. _periph_div-user:
+
+User Defined Peripheral Divisions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-As needed, a user may add peripheral content for a division not defined in the list above. The new division should begin with \periph, plus a division argument/title. However, USFM compliant publishing applications should use the list presented here as a reference for content to support.
+A project may add peripheral content for a division not defined in the current USFM set. The new division should begin with ``\periph``, plus a division title, and a user defined identifier using the prefix ``x-`` to a user defined ``id`` value. However, USFM compliant publishing applications should consider the defined :ref:`divisions <periph_div>` and identifiers as a reference for content to support.
 
 Markup for Peripheral Divisions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -71,6 +130,6 @@ In the following topics there is a recommendation and a brief description of the
 
 Any non-standard markers used in these books will need to be added to the stylesheet associated with the project.
 
-Authoring peripheral materials within Paratext
+Authoring peripheral materials within ParaTExt
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-ParaTExt includes the named peripheral books FRT, INT, BAK, CNC, GLO, TDX, NDX, and OTH in addition to a set of books named from XXA to XXG. These non-Biblical books appear at the end of a project's list of books, and may be used to author the non-biblical text for Front Matter, Back Matter, Introductions, or any other kind of text which should be stored as part of the translation project.
+ParaTExt includes the named peripheral :doc:`books </identification/books>` FRT, INT, BAK, CNC, GLO, TDX, NDX, and OTH in addition to a set of books named from XXA to XXG. These non-Biblical books appear at the end of a project's list of books, and may be used to author the non-biblical text for Front Matter, Back Matter, Introductions, or any other kind of text which should be stored as part of the translation project.