USFM Information


#1

USFM Documentation

Categories of Tags

There are 3 broad categories of USFM tags, “paragraph styles”, “character styles” and “note styles.”

  1. Paragraph styles are what the name suggests - when it is printed there will be a line break at the end. These tags cannot be nested inside other tags. A paragraph style tag always closes the previous paragraph style block.
  2. Character styles are inline elements that are contained within a paragraph style block. Unlike paragraph style tags, character style tags can be nested inside other tags. When this occurs, a closing tag is required. The closing tag is formed by appending an asterisk to the opening tag, for example, the \em tag is closed by \em*.
  3. Note styles are used to identify and markup extra-biblical material like footnotes and tables.

Opening tags are always followed by a single white space that is not considered to be part of the text of scripture. This can be a new line or a space character.

Closing tags do not need to be followed by white space.

Paratext implementation

The most obvious deviation from the published USFM standard (version 2.4) is Paratext does not require ending or closing markers in many situations. For paragraph styles (\p, \q etc) closing tags are never used since paragraphs cannot be nested; a paragraph style marker automatically closes the previous paragraph block.

However, closing markers are required for most character styles. Since they can span paragraphs, character markers need to have an explicit closer. The 3.0 documentation has made this more clear.

Note styles are a little different. The opening note tag requires a closing tag, but any tags inside it do not because they are automatically closed by another opening tag, or by the closing tag for the whole note block. For example:

\f + \fr 5.12: \fk make me clean: \ft This disease was considered to make a person ritually unclean.\f*

The most notable exception to these rules is the verse marker, \v. Even though the verse marker is a character style, there is no closing marker. A verse is closed by the next verse marker, a chapter marker, or the end of the book.