.. include:: /_static/inc_styles.txt .. _usx_elementIndex: Elements ======== .. contents:: :depth: 2 .. index:: usx .. _usx-element_root: ----- :Element: usx |req| |br| *empty* :Added: 1.0 :Use: Root element for USX scripture file. :@version: USX version identifier. |req| |br| xsd:decimal |br| Only the specific USX version number for scripture data contained in the file is allowed (1.0, 2.0, 2.5 etc.). :Parent: **ROOT** The following schema diagram displays the document structure of a USX scripture file. Diagram """"""" .. image:: images/usx_usx-document.png Sample """""" .. code-block:: xml .. index:: usx .. _usx-element_book: ------ :Element: book |req| |br| xsd:string :Added: 1.0 :Use: Brief description of scripure translation. :@code: 3-letter book code for the scripture content in the USX document. |req| |br| one of :ref:`bookCode ` :@style: Content type. |req| |br| ``id`` :Valid in: :ref:`usx-div_bookIdentification` :Parent: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-element_book.png Sample """""" .. code-block:: xml English: Good News Translation 2nd Ed. 1992 .. index:: usx .. _usx-element_chapter: --------- :Element: chapter |req| |br| *empty* :Added: 1.0 :Use: Initial element within each chapter text division. Marks the start of a new chapter. :@style: Content type. |req| |br| ``c`` :@number: Current chapter number (sequential; according to versification definition for the scripture text). |req| |br| xsd:integer :@altnumber: Alternate chapter number. (Used to supply the chapter number for an alternate versification scheme. This is required when the numbering for an alternate versification tradition need to be maintained within the same translation text.) |br| xsd:string of pattern ``[0-9]+\w?(\u200F?[\-,][0-9]+\w?)*`` :@pubnumber: Published chapter character. (The chapter character(s) (a string - number, letter or both) which should be displayed in a published version of the scripture text, where the published chapter character is different than the sequential chapter number used within the translation editing environment, as defined by the project versification.) |req| |br| xsd:string :Valid in: :ref:`usx-div_chapterText` :Parent: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-element_chapter.png Sample """""" Code examples for chapter and verse are provided after the definition for element :ref:`verse` (below). .. index:: usx .. _usx-element_verse: ------- :Element: verse |req| |br| *empty* :Added: 1.0 :Use: Marks the start of a new verse. :@style: Content type. |req| |br| ``v`` :@number: Current verse number (sequential; according to versification definition for the scripture text). |req| |br| xsd:string of pattern ``[0-9]+\w?(‏?[\-,][0-9]+\w?)*`` :@altnumber: Alternate verse number. (Used to supply the verse number for an alternate versification scheme. This is required when the numbering for an alternate versification tradition need to be maintained within the same translation text.) |br| xsd:string of pattern ``[0-9]+\w?(‏?[\-,][0-9]+\w?)*`` :@pubnumber: Published chapter character. (The chapter character(s) (a string - number, letter or both) which should be displayed in a published version of the scripture text, where the published chapter character is different than the sequential chapter number used within the translation editing environment, as defined by the project versification.) |br| xsd:string :Valid in: :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_para`, :ref:`usx-element_row`, :ref:`usx-element_cell` Diagram """"""" .. image:: images/usx-element_verse.png Samples """"""" **chapter and verse (MAT 5:1, with preceding and following context)** .. code-block:: xml ... Large crowds followed him from Galilee and the Ten Towns, from Jerusalem, Judea, and the land on the other side of the Jordan. The Sermon on the Mount Jesus saw the crowds and went up a hill, where he sat down. His disciples gathered around him, and he began to teach them: ... An additional six chapters appear interspersed in Esther in the Septuagint. There are 3 common approaches to handling the Greek additions (and many additional variations!). Although Paratext requires sequential chapter and verse numbers to be used within the translation editing environment – as defined by the project versification – in numerous places this is not the string to be published for the chapter and/or verse identifiers at these locations. Examples from Esther Greek are shown below to highlight the application of the @pubnumber attribute for :ref:`chapter ` and :ref:`verse `. The following example of the text for Esther Greek chapter 1 is taken from the English Good News Bible text. This text follows a versification scheme for Esther Greek which may be referred to as "modern scholars" configuration. Some versions following this scheme include English Good News, French La Bible en francais courant, and German Gute Nachricht Bible. * In the first portion of this example, you can see a chapter element with the sequential @number "1" which includes a @pubnumber "A". *The "A" should be presented to the reader*. * In the second portion of this example, a para element with @style "cp" is found. Although a sequential chapter element is not present at this location, *a chapter heading or other appropriate chapter style showing "1" should be presented to the reader*. * In the second portion of this example you can also see verse elements with sequential @number "18-19", "20", "21", "22". *The corresponding @pubnumber "1-2", "3", "4", and "5" should be presented to the reader*. **chapter and verse (ESG 1, showing chapter, @pubnumber A, and cp 1; verse 18-19 @pubnumber 1-2 etc.)** .. code-block:: xml Mordecai's Strange Dream Mordecai, a Jew who belonged to the tribe of Benjamin, was taken into exile, along with King Jehoiachin of Judah, when King Nebuchadnezzar of Babylonia captured Jerusalem... ... 1 Queen Vashti Defies King Xerxes These things happened in the time of King Xerxes, who ruled 127 provinces, all the way from India to Ethiopia, from his royal throne in Susa, Persia's capital city. In the third year of his reign, the king gave a banquet for all his advisers, the representatives of the other countries, the noblemen from Persia and Media, and the governors of the provinces. For six whole months he made a show of the riches of the imperial court with magnificent and expensive celebrations. After the feast the king gave a banquet for the people of other nations who were in the city... ... The following example is taken from the English Contemporary English Version (CEV) text, which applies a different versification scheme to Esther Greek following the Vulgate. The NRSV Anglicised Edition is another example following this scheme. **chapter and verse (ESG 1, showing chapter 1 @pubnumber 11, cp 12, and 1; verse 1-3 @pubnumber 2-4, verse 4 @pubnumber 5, verse 12 @pubnumber 1 etc.)** .. code-block:: xml Addition A Mordecai's Dream Mordecai son of Jair was a Jew from the Benjamin tribe, and he lived in the city of Susa in Persia. Mordecai had been taken away from Jerusalem as a prisoner, when King Nebuchadnezzar of Babylonia had captured King Jehoiachin. ... In Mordecai's dream, there was confusion and unrest all over the world. He heard crashing thunder, and the earth shook with an earthquake as two huge dragons went toward each other, ready to fight... ... Mordecai woke up, but he knew that in his dream he had seen what God was planning to do. And so, Mordecai thought about his dream all day, trying to understand exactly what it meant. 12 Mordecai Saves the King's Life That night, Mordecai was in the palace courtyard. He was resting not far from Gabatha and Tharra, the two officers who were on guard duty. Mordecai overheard them talking, and as he listened carefully, he realized they were planning to murder King Artaxerxes. ... End of Addition A 1 Queen Vashti Disobeys King Artaxerxes King Artaxerxes lived in his capital city of Susa and ruled 127 provinces from India to Ethiopia. An example from Psalms (modified French TOB) showing an alternate chapter and verse numbering scheme encoded within the text. **chapter and verse (PSA 42, showing chapter @altnumber and verse @altnumber)** .. code-block:: xml DEUXIÈME LIVRE (Ps 42–72) PSAUME 42 1 Du chef de chœur. Instruction des fils de Coré. Comme une biche se tourne vers les cours d'eau, ainsi mon âme se tourne vers toi, mon Dieu. J'ai soif de Dieu, du Dieu vivant: Quand pourrai-je entrer et paraître face à Dieu? .. index:: usx .. _usx-element_para: ------ |ico_R| Schema pattern name: **Para** :Element: para |br| xsd:string :Added: 1.0 :Use: Paragraph content. :@style: Content type. |req| |br| Permitted values vary for each document division. The :doc:`para @style types ` list presents an itemization of style values by category (paragraphs, poetry, titles etc.) and indicates the :doc:`document divisions ` in which each type is valid. :Valid in: :ref:`usx-div_bookHeader`, :ref:`usx-div_bookTitles`, :ref:`usx-div_bookIntroduction`, :ref:`usx-div_introductionEndTitles`, :ref:`usx-div_bookChapterLabel`, :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-element_para.png Sample """""" .. code-block:: xml This is the Good News about Jesus Christ, the Son of God ... “God said, ‘I will send my messenger ahead of you to open the way for you.’ The Sermon on the Mount Jesus saw the crowds and went up a hill, where he sat down. His disciples gathered around him, and he began to teach them: Salt and Light (Mark 9.50; Luke 14.34,35) “You are like salt for the whole human race... .. index:: usx .. _usx-element_table:
------- |ico_R| Schema pattern name: **Table** :Element: table |br| *empty* :Added: 1.0 :Use: Contains :ref:`usx-element_row` and :ref:`usx-element_cell` child elements which compose the structure of a USX :ref:`usx-element_table`. Tables are composed of a vertical sequence of one or more rows. Rows are composed of a horizontal sequence of one of more cells. :Valid in: :ref:`usx-div_bookIntroduction`, :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-element_table.png .. index:: usx .. _usx-element_row: ----- :Element: row (|req| within :ref:`usx-element_table`) |br| *empty* :Added: 1.0 :Use: Contains a horizontal sequence of table :ref:`usx-element_cell` elements. The horizontal position of a table cell relates to its corresponding table column. :Valid in: Any valid :ref:`usx-element_table` :Parents: :ref:`usx-element_table` .. index:: usx .. _usx-element_cell: ------ |Ico_R| Schema pattern name: **TableContent** :Element: cell (|req| within usx-element_row) |br| xsd:string :Added: 1.0 :Use: Table cell content. Contains the cell text and and child elements. :@style: Cell column and alignment (legacy). |req| |br| ``th#`` | ``thr#`` | ``tc#`` | ``tcr#`` |br| The variable represents the table column number. *See "About cell @style" note below.* :@align: Cell alignment. |req| |br| ``start`` | ``center`` | ``end`` |br| Represents “left”, “center”, and “right” respectively in left-to-right direction texts, and “right”, “center”, “left” in right-to-left direction texts. :Valid in: Any valid :ref:`usx-element_row` :Parents: :ref:`usx-element_row` .. note:: Like the @style attribute applied to other USX elements, the cell @style value is a reference to the source text USFM marker in Paratext, from which USX encoded text is often derived. In USFM text, the table cell markers define the column to which they belong. The variable # represents the table column number. Strictly speaking @style is redundant information in USX. It is used by Paratext for round-tripping USX to USFM. In USX, the position of a :ref:`usx-element_cell` in its sequence defines its respective column, and the @align attribute is the primary source of cell alignment information. Diagram """"""" .. image:: images/usx-element_cell.png Sample """""" **NUM 2:3-9** .. code-block:: xml
Tribe Leader Number Judah Nahshon son of Amminadab 74,600 Issachar Nethanel son of Zuar 54,400 Zebulun Eliab son of Helon 57,400 Total: 186,400
.. index:: usx .. _usx-element_char: ------ |ico_R| Schema pattern name: **Char** :Element: char |br| xsd:string :Added: 1.0 :Use: An element for marking character level content types within :ref:`para `, table :ref:`cell ` and :ref:`note ` elements. :@style: Content type. |req| |br| Permitted values vary for each document division. The :doc:`char @style types ` list presents an itemization of style values by category and indicates the :doc:`document divisions ` in which each type is valid. :Valid in: :ref:`usx-div_bookTitles`, :ref:`usx-div_bookIntroduction`, :ref:`usx-div_introductionEndTitles`, :ref:`usx-div_bookChapterLabel`, :ref:`usx-div_chapterText` |br| A limited subset of @style types are valid within :ref:`note ` (Footnote, CrossReference) :Parents: :ref:`usx-element_para`, :ref:`usx-element_cell`, :ref:`usx-element_note` Diagram """"""" .. image:: images/usx-element_char.png Sample """""" .. code-block:: xml The name Genesis means “origin.” Then the Lord God took some soil from the ground and formed a man This is the Good News about Jesus Christ, the Son of God. It began as the prophet Isaiah had written: “God said, ‘I will send my messenger ahead of you to open the way for you.’ ... .. index:: usx .. _usx-element_note: ------ The USX note element is used to contain the content for any :ref:`footnotes ` or :ref:`cross references ` content. Different note *types* are distinguished by the note **@style** attribute. The content for each note type is marked using :ref:`usx-element_char` with a specific subset of @style types for the chosen note type. To help make things clear in this document, the markup for :ref:`footnotes ` and :ref:`cross references ` are described in separate sections because they use different char @style types within them. |Ico_See| **See:** :doc:` Types ` .. index:: usx .. _usx-element_sidebar: --------- |Ico_R| Schema pattern name: **Sidebar** :Element: sidebar |br| *empty* :Added: 2.0 :Use: Contains :ref:`usx-element_para` (@style types :ref:`usx-parastyles_titles_headings`, :ref:`usx-parastyles_paragraphs`, :ref:`usx-parastyles_poetry`), :ref:`usx-element_table` and :ref:`usx-element_char` elements to contain the content for a sidebar. Sidebars are larger sections of topical content, or information for more in-depth study. This content is associated with a general area in the scripture reference text, but not necessarily a specific verse or word. :@style: Content type |req| |br| ``esb`` :@category: Optional attribute used to tag the :ref:`usx-element_sidebar` as belonging to a specific category of study content (e.g. Ideas, People, Places, Objects etc.). :Valid in: :ref:`usx-div_bookIntroduction`, :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-pattern_Sidebar.png Samples """"""" **Matthew 2** .. code-block:: xml Dates in B.C. and A.D. The initials b.c. have traditionally been an abbreviation for “Before Christ.” If Luke's dating is correct, then Jesus was born at least four years before the years known as a.d. began. (a.d. stands for the Latin phrase “in the year of our Lord”). Christian dating was actually not introduced until a.d. 526 by a monk named Dionysius Exiguus. He was given the job of creating a calendar for the feasts of the church. He fixed the birth of Jesus in the Roman year 754, which was selected as the first year of the Christian era beginning on January 1. Dionysius apparently misjudged Herod's reign by about five years. The initials b.c.e. (Before the Common Era) and c.e. (in the Common Era) are sometimes used for the traditional b.c. and a.d. **Galatians 3** .. code-block:: xml Abraham The list of the descendants of Noah's sons comes to an end (Gen 11.26) with Abram (“exalted father”). He later became known as Abraham (“father of many”). God told Abram (Gen 12.1-3) to move from his home in Ur of the Chaldees (in southern Mesopotamia) to the land of Canaan. God promised that his family would become “a great nation” with a special relationship to God. And all nations would be blessed because of Abraham and his wife Sarah and their descendants (Gen 12.1-3; 15.1-21). So Abraham went with Sarah and his nephew Lot. ... .. index:: usx
.. _usx-element_figure:
-------- |Ico_R| Schema pattern name: **Figure** :Element: figure |br| xsd:string :Added: 1.0 :Use: Definition for an illustration which could be formatted at or near to this location in a publication. |br| The element's text content is the caption for the illustration. |br| xsd:string :@style: Content type. |req| |br| ``fig`` :@desc: Illustration description. This text is not normally rendered within a publication. |req| |br| xsd:string | *empty* :@file: Illustration filename or URI. |req| |br| xsd:string | *empty* :@size: Illustration relative size. |req| |br| ``col`` | ``span`` | xsd:string | *empty* |br| **col** - Illustration should be inserted inline within the space for the current text column. |br| **span** - Illustration should be inserted across (spanning) all text columns (i.e. the maximum available page or screen width). :@loc: Illustration location/range. |req| |br| xsd:string | *empty* :@copy: Copyright information. |req| |br| xsd:string | *empty* :@ref: Illustration reference. This text will commonly be rendered together with the illustration caption. |req| xsd:string | *empty* :Valid in: :ref:`usx-div_bookIntroduction`, :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_root` Diagram """"""" .. image:: images/usx-element_figure.png Sample """""" .. code-block:: xml
At once they left their nets.
.. index:: usx .. _usx-element_optbreak: ---------- :Element: optbreak |br| *empty* :Added: 2.0 :Use: Discretionary (optional) line break location. |br| Primarily used in :ref:`poetic ` text, but could also be used for marking optional breaks for :ref:`titles `, :ref:`headings `, or table :ref:`usx-element_cell` content. :Valid in: :ref:`usx-div_bookTitles`, :ref:`usx-div_bookIntroduction`, :ref:`usx-div_introductionEndTitles`, :ref:`usx-div_bookChapterLabel`, :ref:`usx-div_chapterText` :Parents: :ref:`usx-element_para`, :ref:`usx-element_cell` Sample """""" .. code-block:: xml Jesus Heals a Man Who Could Not Walk .. index:: usx .. _usx-element_ref: ----- :Element: ref :Added: 2.0 :Use: Scripture reference. |br| When :ref:`usx-element_ref` is used with a USX encoded text, each segment of a scripture reference should be wrapped in a :ref:`usx-element_ref` element. |br| xsd:string :@loc: A parsable (machine-readable) representation of the vernacular text for the scripture reference. Book names must be one of :ref:`bookCode `. Chapter verse separator is always a colon (:). :Valid in: :Parents: Diagram """"""" .. image:: images/usx-element_ref.png Sample """""" .. code-block:: xml Mt 3.1-4,7-13 Mt 3.4—4.5 Lk 3—5 Mt—Lk Matthew 3.4—5.6; Luke 7 Sample Details """""""""""""" Example: .. code-block:: xml Mt 3.4-5 becomes: .. code-block:: xml Mt 3.4-5 **Comma-delimited verses and chapters are split up as much as possible:** Example: .. code-block:: xml Mt 3.4-5,6 becomes: .. code-block:: xml Mt 3.4-5,6 Example: .. code-block:: xml Mt 3.4-5.7 becomes: .. code-block:: xml Mt 3.4-5.7 **Chapter ranges are acceptable:** Example: .. code-block:: xml Mt 3-5 becomes: .. code-block:: xml Mt 3-5 **Book ranges are encoded as first reference only:** Example: .. code-block:: xml Mt-Lk becomes: .. code-block:: xml Mt-Lk