APPENDIX ONE

How to Use phpBible

This portion of this document duplicated directly from the phpBibles documentation.
phpBible has two primary search interfaces, Basic and Advanced. A link to the Search Hints page is provided on each interface; its contents will not be duplicated here. The Basic interface permits users to select a document and enter a query string. When submitted, phpBible will parse the query and try to figure out whether the user requested 1) a keyword search, 2) a passage lookup, or 3) a Table of Contents request. It then performs the query and displays the results. The Advanced Search page has three separate forms, one for each of the above options. On this page, multiple documents may be selected for the Passage Lookup form. Thus, users may see the same passage in multiple documents simultaneously. The Keyword Search form permits users to select many related options that for which only default values are assumed in the Basic Search.

Besides the Basic and Advanced Search screens, phpBible may be used in other ways:
- Blocks
- Popup Referencing

This section describes these functions in general terms. See the wrapper documentation for any extra details.

Blocks:
A Search Interface Block permits users to enter a query and jump directly to phpBible's Search Results page. There is also a Quote Block which displays any one of a list of passages you specify, plus an optional commentary. Multiple lists may be defined, so you can have multiple Quote Blocks pulling from different lists. Starting with phpBible 0.9.1, all passages in a document may be specified without entering them individually. There are three options for how this block may choose and rotate its selections:

- Randomly selected passage that changes each day
- Sequentially selected passage that changes each day
- Randomly selected passage that changes every time a page is loaded

Popup Referencing:
With phpBible's popup referencing system, you can include links on your site that open popup windows containing the results of phpBible queries. This is useful, for example, if you have articles on your site that discuss Bible passages. Instead of quoting the entire passage inline with your article, you may include a direct link to the text of the passage. The only thing required to set this up is to include a link to phpBible's JavaScript Popup function. This is described in the documentation for your CMS.

To make a Popup reference, put the following tag in your HTML:

foobar

where,
"short_name" is the short name of the document to look in. Short names may be
found in the Documents List within phpBible Administration.
"query" is the passage or keyword search you want to display in the popup window.
This follows the same conventions as on the Basic Search Interface.
Use HTML special characters for characters that would mess up a URL. For
example, use ' instead of a " and a + instead of a space.
"foobar" is the text that the user will click.


Obtaining and Using OSIS Documents
phpBible exclusively uses XML documents in the OSIS (Open Scriptural Information Standard) format. As the name implies, this is an open standard that is free for anyone to use and to create documents in. Thus, this kind of document may be found anywhere on the web. Following are some sites we know about:

http://www.bibletechnologieswg.org/osis/docs/
http://www.ccel.org/osis/xml/" TARGET="_BLANK"
http://whi.wts.edu/OSIS/Projects/Markup/docs

phpBible can use these documents in raw format (with .xml extension) or compressed GZIP format (with .xml.gz extension). Depending upon where you got your documents, you may need to re-package them. We HIGHLY RECOMMEND you compress them with GZIP in order to save server space.

Place your OSIS documents on your web server in the folder specified in phpBible Admin->Configuration. Typically, it is a folder named "texts/" in the same folder as the admin script. Now, from phpBible Administration, click "Regenerate Documents".

Note that Bibles are typically VERY LARGE, and the installation routine can take over a minute to complete. The routine monitors its execution time and gracefully pauses if it runs up against your script execution time limit. Just press "Continue" as many times as it takes to get the text installed.

phpBible is able to detect "corpus" documents - those that have multiple documents in a single file. However, the presence of these documents causes Document Regeneration to take a lot longer. Please be patient.

The Administration screen lists each document it has detected, with appropriate options depending on each document's state. phpBible now monitors its own execution time when initializing a document. If it gets too close to PHP's script execution time limit, it saves its state and stops. The "Initialize" link is then replaced with a "Continue" link. Thus, though it may take extra clicks, large documents and/or slow servers will not generate the problems encountered in previous versions of our Bible software.