Freely-Given.org Bible Drop Box Notes

Picture of the FG Logo

Import formats

The Bible Drop Box only accepts zip files for the Bible data. Import formats include:

This software has been successfully run on over 700 real Bible translations. Unfortunately however, most of the accepted input Bible formats do offer the opportunity for a lot of variation and for potential errors. It's always good to run the checks in your Bible editing software first. If a serious unexpected error occurs, this may require operator intervention on our server and so it could be a day or more before any software deficiency here can be fixed.

If you need to convert Scriptures that are in SFM files, but not in USFM format, that requires an extra conversion step with a lot of manual set up. We also have a script that exports USFM from word-processor documents (such as consistently formatted LibreOffice or MS-Word files) which can be customised for specific needs. Please contact us and let us know the details and we'll let you know if we're able to help.

Export processes

There are two main processes by which the Bible data is exported:

  1. Native exports: These are export functions that are written by us (in Python3) and which we have complete control over. These are likely to finish reliably, but unfortunately because there's a lot of them, not all of them have been tested thoroughly in the many various programs that use them. However, if you can give feedback on any shortcomings, we can often quickly fix such issues. Native exports are included in the Bible Organisational System (BOS) software if you install it on your system.
  2. External exports: These are separate programs from other sources that we run from inside our system. We don't have any control over what happens inside those programs and so they can be more fragile or likely to crash. However, the advantage is that we all benefit from the skills and testing that those developers have used to make their programs useful.

(All of the importers are our own (Python3) code and have been made robust from crashing by testing on several hundred actual Bible files. However the OSIS importer is the most complex and unreliable at this stage.)

Export formats

Currently this Bible Drop Box converts to USFM and ESFM, OSIS XML, USX XML (v2.0), Zefania and Haggai XML, OpenSong XML, theWord and e-Sword (MS-Windows) formats, MySword (Android) format, GoBible (Java) format, and both uncompressed and compressed Sword Modules produced by a variety of different methods.

Sword Modules can be used by many front-end applications on a wide range of desktop, laptop, netbook, phone, and tablet operating systems including Linux, Mac OS X, Windows, Android, and iOS. See here for a list of some of the possibilites. More instructions are given here.

The Bible Drop Box produces HTML5 files suitable for building into a website (just customise BibleBook.css to meet your needs). In addition, the Haiola export produces an alternative (and more developed) website.

The Bible Drop Box produces Open Document Format (ODF) document files used by LibreOffice and OpenOffice and other programs. It creates fully-styled .odt Writer files. So with only a few tweaks to the nested styles, you should be able to print a draft of a Bible suitable for your needs. In addition, this format provides additional paths for users to convert Bibles to PDF and HTML files.

There are two major eBook formats being the ePub and the Mobi formats. The former is produced by the Haiola export, and the latter is produced from that by the KindleGen program supplied by Amazon.

The Bible Drop Box attempts to produce a nice "typeset" output, available for direct use as a PDF file, or for tweaking by technical users via the TeX or Lout files.

For low-end non-Java phones, a simple PhotoBible is produced that exports the Bible text into a series of logically, numbered 240x320 jpeg picture files that can be loaded onto a cheap 1GB SD card and viewed in order on the phone. (Our implementation technology only works for languages without fancy scripting needs unfortunately, and thus far, only for left-to-right languages.) (Also see this site which has the WEB in this form.)

There's also a couple of plain text exports that aren't linked to from the main output page of the Bible Drop Box. To find these you have to go to the File listing link right at the bottom of your results page and then navigate to the plain text and SwordSearcher output folders.

Most of the export folders also contain a zipped version of the files for more convenient downloading.

Some of the conversion routines don’t handle all Bible formatting codes yet so please advise us if you detect a deficiency. (Of course, not all of the export formats can handle all fields, e.g., footnotes, glossaries, extra books, etc. so obviously they are intentionally omitted in that case.) Other input and output formats are planned for future updates.

The programme attempts to deduce vernacular book names and abbreviations from headers in the Bible files if they're not specifically designated. This is necessary so that any cross-references in the various Bible books can be automatically handled without an extra manual step.

Sample SFM2Web website

The Bible Drop Box script will also try to create a sample xHTML website using the SFM2Web programme. The sample website isn’t available for download to your own server—only for viewing on this site. (Because of the large size of the static xHTML website, you’ll need to contact us if you wish to upload it to your server or for Freely-Given.org to host it long-term on our server.)

See the MLCA website to get an idea of the full potential of the SFM2Web programme for linking USFM Bibles with MDF dictionaries, etc.

Bible checks

The Bible checks module attempts to thoroughly cross-check all of the Bible formatting markers and the text (but sorry, it can’t check the quality of your translation yet) and to present a number of pages of reports of potential errors. It also creates a number of helpful lists to scan through (for instance to easily notice inconsistencies in section heading or footnote formatting within or between books), as well as character and word counts, etc.

The normal/easiest way to check your Bible data is to run the inbuilt checks provided by your Bible editing programme and fix them from there. However, the limited inbuilt checks do not currently find all of the problems that will need to be fixed before typesetting is started. If you find a formatting error in your work that our checks don’t discover, please contact us and let us know the details so we can improve the checking module for everyone’s benefit.

Internationalisation Currently only Unicode (UTF-8) files will be processed correctly, although this could be expanded if there was enough demand for older encodings. Also, at this stage, this software works better for languages with Western style punctuation and writing conventions. We certainly would like to improve this area, but it’s dependant on being able to get test data (see below).

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. Also if you test any of our output and discover deficiencies, please contact us so we know what needs to be improved.

Future plans: At the moment, handling of less common Bible formatting markers is handled on a as required basis. If we detect that a module built has failed for this reason, we'll try to update our code as soon as possible. Current issues and planned future features can be viewed here. See the Opportunities Page to volunteer to help.

Open source: All of the software (mostly Python3) that we have written to operate this Bible Drop Box is freely available. Most of the XML data files and basic Python3 modules can be found at OpenScriptures (and also see the blog). We also use Crosswire utilities. The Bible website is produced with the old SFM2Web programme downloadable from here. Any of our code which is still in alpha or proof-of-concept stage and not yet publicly released can be requested using the Contact Page.

Acknowledgements.