Bible Door app

You should have read this user overview page first as a background before reading these detailed specifications.

Overview

Bible Door is Freely-Given.org’s name for a family of open-licensed Bible reader apps which use a short key code (like concrete-402-625) to open the door to display a particular Bible version.
There are two main use cases for the app:
- For community testing of an in-progress Bible translation that has been submitted to our Bible Drop Box
- To display freely-available/open-licensed Bibles which have already been pre-compiled on Freely-Given-org and have publicly available key codes
- Could also be used for private distribution of a non-open Bible translation to a restricted audience (as long as they don’t publicly post the key code).
There will be multiple versions of the app in the Bible Door family (with slightly different names like Bible Door Single and Bible Door Dual or Bible Door (ASV) and Bible Door (YLT), and eventually maybe Bible Door Plus or Bible Door Study).
The initial versions of the app will only be a code shell without any Bible data included, i.e., they will require either both a key code and internet access, or else access to sideloading a friend’s files before a Bible will be able to be displayed inside the app.
The source code will be publicly available on GitHub and anyone will be able to fork this repo and/or release their own versions with the app name changed. However, of course, we would prefer general improvements to be upstreamed to our own app.
This page is, in fact, a request for help and an admission that we are unable to devote enough dedicated time and focus to continue to develop the app ourselves. Thus we are looking for volunteer programmers to partner with us in producing this family of apps.

Key distinctives of this app family

They display pre-compiled Bible data which is normally downloaded from Freely-Given-org, although some versions of the app may have one or more Bibles included with the app distribution.
Once downloaded, the Bible data may normally be easily shared peer-to-peer.
Defaults to downplaying of chapter/verse containers, i.e., saying "this verse says." (We teach that verse numbers should be used to help you find content, i.e., as an index into the Bible, not used as containers that "contain" text. This "container" view has led to the unfortunately common practice of Bible readers quoting "verses" -- even partial sentences -- out of context. Even chapter divisions are not always in sensible places in the discourse.)
Defaults to displaying by section (not chapter or book) whenever the translation has section headings. Also has navigation by topic / section heading.
At least some versions of the Bible Door apps are designed to showcase our forthcoming Open English Translation (OET) of the Bible. In fact, this is also another major driver behind the entire family of apps. The OET has a Literal Version (LV) and a Readers’ Version (RV) that are designed to be displayed (and thus scroll) together. Most of the time the LV will be shorter than the RV, so can be displayed in a slightly smaller window.

Developers’ Overview

Anyone who helps or volunteers must first agree in writing that their contribution is donated to Freely-Given-org, who in turn strive to make it freely available to all via an open licence.
A list of contributors is to be maintained in the code repository in a separate text or markdown file or similar, and will be displayable via the About feature of the app. Alternatively the list can be determined by something like this.
At this stage, we are inclined towards a Flutter3/Dart2 app, which would run on Android, iOS, and on Ubuntu and possibly Windows desktop. If desperate enough, we would also accept help from those with expertise in Java/Kotlin traditional Android apps, and maybe even in React Native or similar. If there was enough interest, we would even entertain the possibility of multiple competing app designs in order to then allow consumers to choose the one that they find most helpful.
We wish to make full use of modern testing frameworks and use automated checking features to check code quality before it is committed.
Anyone wishing to help should first become familiar with other open Bible apps, including one of our favourites here. You should also read about Scripture App Builder to see the kinds of features that Bible translators may want, although Bible Door is intended to remain much, much simpler to deploy.
If you’re in a position to volunteer but money is the only stumbling block, please do go ahead and at least start a conversation with us.

General specifications

Open source: Source code will be open source and freely available. It must be logical and commented to make it as easy to understand as possible.
Native Android: Must be a native Android app that will run nicely on modern phones and tablets, as well as on devices released within the last five years. Desktop and iOS may follow.
Multiple versions: Bible Door Single and Dual must come from the same source code. Update: Seems easier just to have one version and allow the user to enter either one or two key codes. This also has the advantage of being able to do a split screen even with just one version, and to display different two parts of the Bible at once.
Downplay chapters and verses: Unlike most Bible apps, don’t display by chapter (except for books like Psalms and Lamentations where chapter breaks match the original text breaks) but rather by section.
Handle missing verses: Remember that some Bible translations might not include a particular verse (or part of a verse, or series of verses). This can happen either a/ if the original text is disputed, or b/ if the translation of a Bible book is not yet fully completed.
Additional text: Allow access to Bible and book introductions, along with section headings.
Bible helps: Allow access to footnotes, cross-references, glossary entries, and maps.
Words of Jesus: May be displayed in a different colour, e.g., red, or with a reddish background (although we don’t actually recommend it).
Localisation: Bible book names should be in the Bible language; prompts and menu might be in yet another (e.g., trade or area) language.
Easy to use: The basic functionality must be easily/quickly accessible and not complex for an unskilled user. (Advanced features can be accessed by menus.)
Stored data: Bible data must be stored unencrypted and in a logical, easy-to-find location. If multiple apps are installed from the Bible Door family, they should all be able to share the same downloaded Bibles.
Search function: (Undecided yet whether the indexing is done by the Bible Drop Box or on the mobile device, but probably the former.)
Easy sharing: Must facilitate the sharing of the Bible data to peers via SD cards and Bluetooth.
Start with basics: Version 1.0 only needs basic features— advanced features will come in successive versions.
Theming and branding: Default colours should match this website. (Also open to improving the website to match the app if you can convince me with a nicer scheme.)
Possible future features:
- Allow custom notes stored to the cloud???
- Facilitate sharing Scriptures or notes on social networks???
- Morph into a Bible editor (or maybe a separate app)???
Going wider: Need to keep in mind the possible development for desktop and iOS, plus smaller or newer operating systems if they catch on (perhaps even just in third-world markets) such as Ubuntu Phone, Amazon Fire Phone, etc.
No analytics: We have no desire to track the users’ use of the app, in fact it might be dangerous for users in some environments (although of course, some versions of the app can be tracked fetching data from our server), and so we don’t perceive any need to include any analytics in the app.

Tentative release schedule

v0.1: App runs, has setup screen to accept key code, opens at a small book like Titus 1:1, downloads and saves the book file, and displays the whole book as a scrolling (portrait mode) document below a header line. Available on Google Play as a limited test app.
v0.2: Adds BCV=book, chapter, and optional verse (i.e., if skipped, go to v1) navigation and can do the above for any Bible book available in the requested version. (Remember for the future that book names will differ in different languages, that translations may have different numbers of books, and some translations may display the books in a different order.) When text is scrolled up/down, BCV display in top heading line updates to match the first verse being displayed. Publicly available on Google Play. Left/right flicks to previous/next chapters then previous/next book.
v0.3: When entering the key code, allow the user to request the entire translation to be downloaded in the background. Switches smoothly back and forth between portrait and landscape modes.
v0.4: Adds a slide-in menu which allows the user to display the program about page and list of contributors
v0.5: Adds an options menu which allows the user to select the font, and the font-size on a sliding scale. Dark mode and foreground text and background colours can be selected. Also words of Jesus in red (even though we don’t recommend it).
v0.6: Add a way to navigate to and display a/ the Bible introduction, b/ introductions for each book, and c/ a text appendix.
v0.7: Add book then section (heading) navigation. Left/right flicks to previous/next sections then previous/next book. Ensure back button works for both BCV and section navigation. On all navigation pages, display recent books, e.g., if was in Matthew, then in Ruth, then in Genesis, when selecting a new book, show those three recent books above the full matrix of books available to be selected.
v0.8: Takes full advantage of increased screen area on tablets and for desktop situations. Allows text to be selected and copied to the clipboard. Allows bible references, e.g., John 3:16 to be pasted in and then navigated to.
v0.9: Handles Greek original Bibles (NT & LXX)
v1.0: Word search added. (Requires indexing of the text.)
v2.0: Handles variable text, i.e., option to display Yahweh instead of the LORD. (The file format for allowing that is still not defined.)
Handles Hebrew and Arabic (i.e., RTL languages)
v3.0: Handles two Bibles with different versifications via mapping files, e.g., Psalm a:b in one, might be Psalm a+1:d in another.
v4.0: Lexicon lookups added
v5.0: Allow syncing of options and Bibles between devices. Note-taking works and saves to the cloud.