Release Notes

3.1

July 2024

Background on USFM 3.1

USFM (Unified Scripture Format Markup) 3.1 primarily represents an effort to standardize a single content model which can be equally expressed in backslash-based \ format markers (USFM-FM), XML (USFM-XML), or JSON (USFM-JSON). The common abbreviation for these expressions are USFM, USX, and USJ.

This documentation provides a summary of markup syntax, schema diagrams, and example texts for both USFM and USX. USJ is a newer expression. Equivalent example texts in USJ are also being added.

Previous release notes (3.0 and earlier) are expressed only in USFM-FM specific terms.

Summary of Updates

The key differences in the grammar from USFM 3.0 to 3.1.0 are:

BookTitles are optional.
BookHeaders include sts.
BookIdentification may be any 3 letter code (within reason).
Other peripherals may be of any type.
Section, Verse, and other Para (paragraphs) are seperated as different categories (internal).
The paragraph @vid attribute has an extended reference syntax.
Character markers and nesting:
- All character elements must be closed explicitly, with the exception of note structural elements (below).
- Note specific character elements (i.e. f… fr, fq, ft, or x… xo, xt etc.) are considered note submarker elements. They provide structure to the note content. These note submarker elements continue to support (and recommend) the common pratice of implicit closure.
- Note content must occur within a submarker element; there can be no unmarked note content only within the note container itself.
- fv is now just a character style and requires explicit closing.
- Use of the + prefix for nested USFM character markup is supported but is deprecated. Note that future versions of USFM may remove support for the \+ syntax entirely.
Markings scripture references — ref and xt:
- Added ref for marking scripture references in all contexts (including xt), with an optional machine-readable target location.
- Deprecated use of the attribute @link-href with xt. Use ref.
- Deprecated use of xt outside of cross-reference. Use: ref.
Deprecate the link- prefix in jmp attributes.
Add @key attribute to the k character element.
@sid and @eid attributes are not automatically available for all milestones, but may be used when specified directly (e.g. qt and ts)
\ escaping is required and supported for a number of key characters: \, ', ", |, ~, /
Whitespace rules are clarified and formalised.

3.0

April 2018

Additions

USFM version identifier: \usfm.
Alternate language table of contents texts: \toca#
Letter opening: \po
List header and footer elements: \lh and \lf
Embedded list: \lim#
Structured list items: \lik …\lik* and \liv# …\liv#*
List item total: \litl …\litl*
Hebrew note: \qd
Semantic division: \sd#
Aramaic wordlist entry: \wa …\wa*
Geographic proper name: \png …\png*
List of witnesses in footnotes (for critical editions): \fw …\fw*
Target references “added” text: \xta …\xta*
Published cross reference origin text: \xop …\xop*
Link text: \jmp …\jmp*
Ruby glosses (CJK texts): \rb …\rb*
Superscript: \sup …\sup*
Quotation start/end milestones: \qt#-s* and \qt#-e\*
Translator’s section (chunk) milestones: \ts-s* and \ts-e\*
Common peripheral identifiers.

Revisions

Restored \pr for use as “text refrain”.
Support for explicit table cell column spanning.
Support citation form for wordlist/glossary text (update \w …\w*).
Revised syntax for figures/illustrations - applying descriptive attributes: \fig …\fig*
Deprecated cross reference and footnote DC content markers: \xdc …\xdc* and \fdc …\fdc*
Deprecated combined marker for proper name within translator’s addition: \addpn …\addpn*
Deprecated numbered running header: \h#
Deprecated pronunciation info marker: \pro …\pro* in favour of ruby annotations \rb …\rb*

Syntax and Features

Syntax for assigning character-level attributes.
- Attributes for \w …\w*.
- Attributes for \fig …\fig*.
Syntax for assigning word-level linking attributes.
- Default link-href linking attribute for \xt …\xt*.
Syntax for milestones.
Syntax for peripheral (\periph) identifiers.

2.5

October 2013

Stylesheet only configuration update for Paratext 7.5 release.

2.4

June 2013

Additions

Support for nesting character markup.

2.3

July 2010

Additions

Added study Bible cross reference marker \ex for adding additional cross-references to the notes project.

Revisions

Deprecated - Study Bible footnote marker \fs for marking a footnote summary text.
Revised markup specification for study Bible sidebars (use any title, paragraph, poetry, table, or special text marker elements).

2.2

October 2008

Additions

Added character markers \xot …\xot* and \xnt …\xnt* for uniquely marking target references to OT and NT passages (use of these markers is optional)
Added \iqt …\iqt* to mark (scripture) quotations appearing in the introduction.

Revisions

\imte# now includes an optional numeric variable (multiple levels).
No-break space should now be marked using ~ (tilde), not !$

2.1

April 2007

Additions

Added \ili for marking introduction list items.
Reviewed and finalized Peripheral content markup:
- Added new back matter books CNC, GLO, TDX, NDX.
- Added INT book for scripture division Introductions.
- Updated scheme for marking content divisions in FRT, INT, BAK, OTH
- Added various new content division markers.

Revisions

Finalized Study Bible Content markup.
Reviewed and finalized Peripheral content markup.
Changed \rq …\rq* from paragraph to character level markup.
Changed \ca …\ca* from paragraph to character level markup.

2.05

June 2006

Additions

Added \rq for marking inline quotation references.

2.04

October 2005

Additions

Added \toc3 for providing the standard abbreviation for a book.

2.03

August 2005

Additions

Added \toc1 and \toc2 for providing and marking long and short table of contents texts.
Added \fl for marking footnote “label” text items.
Added \fp for marking footnote additional paragraphs.

2.0

October 2004

Changes in USFM from 1.53 to 2.0.

Additions

Add character style \em …\em* for “emphasis”.
In Peripherals:
- Add \intro section to Front Matter (in addition to Preface).
- Add \maps (Maps Index) section to Back Matter.
- Define books for FRT, BAK, and OTH rather than using the book names XXA, XXB, and XXC for these materials.
Add \sr for marking the text references range listed under a section heading \s.
Add the following markers for “embedded text” (see example references – not all versions mark these items the same).
- \pm - Embedded text paragraph
- \pmo - Embedded text opening
- \pmc - Embedded text closing
- \pmr - Embedded text refrain
- \qm# - Embedded text poetic line
Add character style \pro …\pro* for indicating pronunciation (in CJK texts). (Deprecated - See \rb …\rb*)
Add character style \wj …\wj* for marking words of Jesus.

Revisions

Removed \pdi and `\pde, and substitute with embedded text markup (see Additions, below)
Removed \wr …\wr*. This was really a duplicate of \w …w* used for marking words in the scripture text which are included in the wordlist.
Removed \ps. This is used in conjunction with \nb to indicate that the paragraph spans the chapter boundary. It should be sufficient to just start the new chapter with \nb and use the appropriate paragraph marker for the previous chapter (\p, \m etc.)