Scripture translation projects working in Paratext 9 can choose to use new and updated USFM markup available in USFM 3. Publishing Assistant 6.1 has added support for USFM 3.
This article presents a summary of new USFM 3 markup which you may encounter when typesetting a project from Paratext 9 (or newer). It is not an exhaustive summary of USFM 3 changes, but focuses on the changes and additions which will be of particular interest to a Bible typesetter.
For a complete list of changes in USFM, please refer to the release notes found in the online USFM documentation.
New Paragraph Types
\po – Used to identify text for the opening / introductory text of a letter.
\c 1
\po
\v 1 From Paul, a servant of Christ Jesus and an apostle chosen and called by God to preach his Good News.
\p
\v 2 The Good News was promised long ago by God through his prophets, as written in the Holy Scriptures.
...
\po
\v 7 And so I write to all of you in Rome whom God loves and has called to be his own people:
\po May God our Father and the Lord Jesus Christ give you grace and peace.
\qd – Hebrew note. A Hebrew musical performance comment similar in content to many of the Hebrew Psalm titles (\d), but placed at the end of the poetic section.
\q1
\v 18 yet I will rejoice in the \nd Lord\nd*,
\q2 I will be joyful in God my Savior.
\b
\q1
\v 19 The Sovereign \nd Lord\nd* is my strength;
\q2 he makes my feet like the feet of a deer,
\q2 he enables me to tread on the heights.
\b
\qd For the director of music. On my stringed instruments.
Restored \pr – Text refrain. Commonly set right aligned. The companion \pmr marker may exist in a project for an “embedded text refrain”. This marker was previously deprecated.
\p
\v 15 “ ‘God's curse on anyone who makes an idol of stone, wood, or metal and secretly worships it; the \nd Lord\nd* hates idolatry.’
\pr “And all the people will answer, ‘Amen!’
\p
\v 16 “ ‘God's curse on anyone who dishonors his father or mother.’
\pr “And all the people will answer, ‘Amen!’
\p
\v 17 “ ‘God's curse on anyone who moves a neighbor's property line.’
\pr “And all the people will answer, ‘Amen!’
\sd# – Semantic division (semantic space). If you encounter this marker, the purpose is to identify a location for meaningful vertical white-space. It is used to divide the text into sections, in a manner similar to the structure added through the use of heading texts like \ms# and \s#. The purpose of \sd# is distinct from \b which primarily denotes whitespace (most commonly at poetic stanza breaks) and not hierarchy or division.
\v 51 “Have you understood all these things?” Jesus asked.
\p “Yes,” they replied.
\p
\v 52 He said to them, “Therefore every teacher of the law who has been instructed about the kingdom of heaven is like the owner of a house who brings out of his storeroom new treasures as well as old.”
\sd2
\p
\v 53 When Jesus had finished these parables, he moved on from there.
\v 54 Coming to his hometown, he began teaching the people in their synagogue, and they were amazed. “Where did this man get this wisdom and these miraculous powers?” they asked.This example is taken from NIV “Books of the Bible”. The chapter and verse numbers suppressed in the layout. New sections (after the \sd#) begin with a drop capital.
New Character Types
\rb …\rb* – Ruby annotations / glossing (CJK texts). This character marker pair is used to identify the base text being annotated with ruby characters, and to provide the annotation text. With the CJK feature set enabled, InDesign provides native support for formatting ruby. A project with ruby markup will need to be typeset using InDesign CJK.
\p
\v 1 まだ\rb 何|なに\rb*もなかった\rb 時|とき\rb*、\rb 神|かみ\rb*は\rb 天|てん\rb*と\rb 地|ち\rb*を\rb 造|つく\rb*りました。
\v 2 \rb 地|ち\rb*は\rb 形|かたち\rb*も\rb 定|さだ\rb*まらず、\rb 闇|やみ\rb*に\rb 包|つつ\rb*まれた\rb 水|みず\rb*の\rb 上|うえ\rb*を、さらに\rb 神|かみ\rb*の\rb 霊|れい\rb*が\rb 覆|おお\rb*っていました。
\xop …\xop* – Published cross reference origin text. In some texts, the content intended to be published in the position of the cross reference origin text \xo does not follow the typical <chapter><separator><verse> pattern. An origin reference following this pattern is required for Paratext checks to validate the cross reference location. \xop ...\xop* can be used in order to supply the content intended for publishing, similar to the use of \cp and vp …vp*.
\xta …\xta* – Target reference(s) extra / added text. This character marker can be used for marking text which should be ignored when identifying cross reference target references. If a project uses this marker, it may be of interest to format the enclosed text in some way which distinguishes it from the target references themselves.
\c 3
\s1 The Preaching of John the Baptist\x * \xo 3.0: \xop Chapter 3.1-12:\xop* \xta Compare with the parallel passages at \xt Mk 1.1-8; Lk 3.1-18; \xta and \xt Jn 1.19-28.\x*
\p
\v 1 At that time John the Baptist came to the desert of Judea and started preaching.
\v 2 “Turn away from your sins,” he said, “because the Kingdom of heaven is near!”
New Markup for Managing Lists
\lh and \lf – List header and footer elements. Some lists include an introductory and concluding remark. Although they are an integral part of the list content, they not list items, and will likely require some alternative formatting.
\s1 Administration of the Tribes of Israel
\lh
\v 16-22 This is the list of the administrators of the tribes of Israel:
\li1 Reuben - Eliezer son of Zichri
\li1 Simeon - Shephatiah son of Maacah
\li1 Levi - Hashabiah son of Kemuel
\li1 Aaron - Zadok
\li1 Judah - Elihu, one of King David's brothers
\li1 Issachar - Omri son of Michael
\li1 Zebulun - Ishmaiah son of Obadiah
\li1 Naphtali - Jeremoth son of Azriel
\li1 Ephraim - Hoshea son of Azaziah
\li1 West Manasseh - Joel son of Pedaiah
\li1 East Manasseh - Iddo son of Zechariah
\li1 Benjamin - Jaasiel son of Abner
\li1 Dan - Azarel son of Jeroham
\lf This was the list of the administrators of the tribes of Israel.
\lik …\lik* and \liv# …\liv#* – Structured list items. USFM table structures can be challenging to display on small page sizes (or digital devices). Scripture content is sometimes encoded within a table in order to create a meaningful presentation. However, the table presentation may only be rendered accurately (or legibly) in a larger format. The \lik ...\lik* and \liv# ...\liv#* character markers may be used in a project in order to create structured list entries – which identify a set of related content, but do not encode a specific table presentation.
\s1 Administration of the Tribes of Israel
\lh
\v 16-22 This is the list of the administrators of the tribes of Israel:
\li1 \lik Reuben\lik* \liv1 Eliezer son of Zichri\liv1*
\li1 \lik Simeon\lik* \liv1 Shephatiah son of Maacah\liv1*
\li1 \lik Levi\lik* \liv1 Hashabiah son of Kemuel\liv1*
\li1 \lik Aaron\lik* \liv1 Zadok\liv1*
\li1 \lik Judah\lik* \liv1 Elihu, one of King David's brothers\liv1*
\li1 \lik Issachar\lik* \liv1 Omri son of Michael\liv1*
\li1 \lik Zebulun\lik* \liv1 Ishmaiah son of Obadiah\liv1*
\li1 \lik Naphtali\lik* \liv1 Jeremoth son of Azriel\liv1*
\li1 \lik Ephraim\lik* \liv1 Hoshea son of Azaziah\liv1*
\li1 \lik West Manasseh\lik* \liv1 Joel son of Pedaiah\liv1*
\li1 \lik East Manasseh\lik* \liv1 Iddo son of Zechariah\liv1*
\li1 \lik Benjamin\lik* \liv1 Jaasiel son of Abner\liv1*
\li1 \lik Dan\lik* \liv1 Azarel son of Jeroham\liv1*
\lf This was the list of the administrators of the tribes of Israel.
\litl …\litl* – List entry total. This character marker may be used in “accounting” lists for denoting the total component of the text within a list item (\li). It is an alternative to using tables for the same content.
\pm
\v 6 These are the people of the province who came up from the captivity of the exiles whom Nebuchadnezzar king of Babylon had taken captive (they returned to Jerusalem and Judah, each to his own town,
\v 7 in company with Zerubbabel, Jeshua, Nehemiah, Azariah, Raamiah, Nahamani, Mordecai, Bilshan, Mispereth, Bigvai, Nehum and Baanah):
\b
\pm The list of the men of Israel:
\b
\lim1
\v 8 the descendants of Parosh \litl 2,172\litl*
\lim1
\v 9 of Shephatiah \litl 372\litl*
\lim1
\v 10 of Arah \litl 652\litl*
\lim1
\v 11 of Pahath-Moab (through the line of Jeshua and Joab) \litl 2,818\litl*
\lim1
\v 12 of Elam \litl 1,254\litl*
\lim1
\v 13 of Zattu \litl 845\litl*
\lim1
\v 14 of Zaccai \litl 760\litl*
...
\lim# – Embedded list entry. The example for “List entry total” (above) taken from Nehemiah 7 shows an embedded list.
Tables
Support for explicit table cell column spanning. In USFM 3, a table cell marked with \th#, \thr#, \tc# or \tcr# may use a dash - between a range of column numbers in order to indicate that the columns should be spanned.
\p
\v 10-16 On the east side, those under the banner of the division of Judah shall camp in their groups, under their leaders, as follows:
\tr \th1 Tribe \th2 Leader \thr3 Number
\tr \tc1 Judah \tc2 Nahshon son of Amminadab \tcr3 74,600
\tr \tc1 Issachar \tc2 Nethanel son of Zuar \tcr3 54,400
\tr \tc1 Zebulun \tc2 Eliab son of Helon \tcr3 57,400
\tr \tcr1-2 Total: \tcr3 186,400
Syntax Additions & Changes
Character marker attributes. USFM 3.0 provides a general syntax for adding named attributes to character markers. Attributes define additional properties of the marked content. The addition of marker attributes is a means of extending the meta information contained within in a USFM text.
Within a character marker span, an attributes list is separated from the text content by a vertical bar |. Attributes are listed as pairs of name and corresponding value. A common example would be the lemma attribute for a word marked in a project text as as a wordlist / glossary entry.
\w gracious|lemma="grace"\w*or possibly
\w gracious|grace\w*Attributes are normally not publishable text. When Publishing Assistant converts the contents of an attributes list to InDesign tagged text format, it uses InDesign “conditional text” to retain the content, but hide it from the formatted layout. This means that it can still be safely round-tripped back to USFM if necessary. In the InDesign Conditional Text palette, you will find HiddenAttribute and HiddenMilestone if the project you are typesetting contains any USFM attributes or milestones. The visibility of of both of these should always remain disabled.
Milestones. 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.
Peripherals
Peripheral identifiers. USFM provides a syntax for identifying peripheral divisions within book files such as FRT, INT, BAK, OTH. Within each book, divisions (sub-sections) of content are denoted using them marker \periph followed by an additional division title. The division title is free-form, and may be expressed in the vernacular language. In USFM 3.0 an attribute (see also above) named id is used to uniquely identify each peripheral division. USFM 3.0 provides a list of standardized identifiers for common peripheral divisions.
To illustrate this update, an example from the text for the FRT book in USFM 2.x is shown below:
\id FRT
...
\periph Title Page
\mt1 Holy Bible
\mt3 with
\mt2 Deuterocanonicals/Apocrypha
...
\periph 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
\periph Abbreviations
...In a USFM 3 project, the \periph divisions include an id attribute. The vernacular text after \periph might vary from one project to another. Publishing Assistant will still recognize which content is title page, the foreword, or the table of contents.
\id FRT
...
\periph Pagina del titulo|id="title"
...
\periph Prefacio|id="foreword"
...
\periph Tabla de contenido|id="contents"
...
\periph Abreviaturas|id="abbreviations"
...It will produce a separate document for each peripheral division found in FRT, using the \periph id attribute at the end of each document’s name.
