Freely-Given.org USFM Bibles

Picture of the FG Logo

More than you wanted to know about USFM 2 Bibles

USFM 2 (Unified Standard Format Marker) Bibles were usually created by a program such as UBS/SIL Paratext, Bibledit, our own Biblelator, or even Toolbox or (horrors!) a text editor or word processor (cringe!). They normally consist of one file per book (although older systems used one file per chapter). They only contain the Bible text and a few extras like book titles and introductions, but a lot of other necessary information (metadata) is not defined or included in the USFM format, thus they are not sufficient for typesetting from directly.

The current version of USFM is v2.4, but v3.0 was released in April 2018, although the current Paratext 8.0 version doesn't yet use it.

Paratext provides some additional information in a .ssf file, and this information can be used by the Bible Drop Box if included. However, even with the SSF file, USFM Bibles don't specify things like which order to include the books (believe it or not, not all Christian traditions put Bible books in the same order), nor does it carefully define the short names of the books or the book abbreviations which will be used in section references and cross-references, etc. For this reason, the Bible Drop Box tries to make some intelligent guesses as to how to best format your data. In the future, we hope to find an easy way for you to specify some of this additional information. (Suggestions happily accepted.)

Depending on how the files were formed and what checks have been made on them, USFM Bible files can easily contain MANY errors, e.g., fields like \v 7And Jesus said… (missing space after the verse number) or a cross-reference like Maat 3:7 (instead of Mat) or missing USFM closing markers such as in Jesus said, \wj"Go." (missing \wj* and failure to use proper “quotation” characters). The Bible Drop Box software attempts to find and inform you of such errors and inconsistencies, at the same time trying to guess how to best handle them without just giving up. This may or may not be successful. (Your mileage may vary.) Of course, you will have the best result if you take the time to fix the issues in your files.

Identifying a USFM 2 Bible book file

The text file will begin with the following lines:
\id <CODE>
where <CODE> is a three character Paratext book code from here.

It will NOT contain a line
\usfm 3.0
and will only contain USFM paragraph and character codes.

USFM Bible translation editors

The UBS/SIL Paratext editor is the main one used by professional Bible translators around the world (but with somewhat restricted distribution). Others prefer the open-source Bibledit, and our own Biblelator is under development (but already usable by the adventurous).

Submitting USFM 2 Bible files to the Bible Drop Box

If you run UBS/SIL Paratext, the easiest way to produce a suitable zip file to submit, is to open Paratext and click on the window for your project. Then use the File / Backup Project / To File… command to make the zip file. For best results, make sure that the Include project properties and settings checkbox is ticked. The filename must have a .zip extension. Take careful note of which folder you are saving your backup zip file into, because you will need that information in order to submit the file.

If you are not a Paratext user, you should go into your My Paratext Projects folder and select the folder for your project. While holding down the Control key, also click on the .ssf file for your project if you have one (so that both the folder and the .ssf file are selected). Then create a .zip file by using right-click / Send To / Compressed (zipped) Folder in Windows, or right-click / Compress… or similar in Linux. Again the filename must have a .zip extension and you must note what folder it is saved into because you will need that information down below in order to submit the file.

Test data: If you are able to provide any kinds of Bible files for automated testing purposes, please contact us and let us know the details so we can improve the internationalisation and ruggedness of the software for everyone’s benefit.