The Holy Bible, English Standard Version

Technical Introduction to the ESV Online Edition

Stephen Smith
Webmaster, Good News Publishers (webmaster@gnpcb.org)
August 5, 2002. Updated July 10, 2006.

Introduction

The creation of the ESV Online Edition occurred in June and July 2002, driven by our twin goals of fidelity to the printed version and ease of use. In this document we reveal the justifications for our decisions from both usability and technical perspectives. We hope that future implementers of Bible sites will use this document as a baseline for development and will not have to rediscover the lessons we learned.

Creation of XML Files

The first step in developing the Online Edition lay in creating a set of XML files that accurately represented the text of the Bible. Working from a basic set of XML files, we added tags as necessary to ensure the online version reflected the printed version. Using these XML files as a base, we were able to transform the text easily into whatever format we needed.

Comparative Usability Study

Background

In July and August 2002, after the test version of the ESV went online, we conducted a small comparative usability study of the Bible search engines that existed on the Internet at that time. We wanted to ensure that the ESV’s usability equaled or exceeded that of other online Bible sites.

We followed standard usability testing methodology, including the use of think-aloud protocol. We tested four users on the following sites:

We did not test the NET Bible because it did not allow word searching. The order the users encountered the sites varied. Every user was a Good News Publishers employee, so we can hardly claim their impartiality; however, because we only wanted a general idea of the usability issues raised by current implementations, we deemed these users sufficient.

Each user completed the following four tasks:

  1. Show me 1 Timothy 3:15.
  2. Show me the rest of 1 Timothy 3.
  3. Where does Jesus say, “I am the light of the world?”
  4. Show me the first chapter of Mark.

We considered these tasks representative of what users would want to accomplish when visiting a Bible site: looking up a passage and locating a verse containing specific words. We also wanted to evaluate how the sites facilitated navigation between related tasks, such as moving from a single verse to seeing the verse in context.

Results

Because our intent in this document is to share considerations that designers should take into account when creating an online Bible, and not to discuss the weaknesses of specific sites, we are publishing only our recommendations. However, these recommendations reflect difficulties encountered by users at one or more sites.

Recommendations (Best Practices) for the Design of a Bible Site

Input Areas

Handling Input

Search Scope

Design of Passage and Search Result Pages

Terminology

Navigation

Displaying Content

Technical Issues

Implementation

This part of the document explains how the site works and reveals the justifications for our design.

Usability Perspective

Though we did not conduct the usability study until after posting a test version of the site online, we conducted small usability tests throughout the site’s development to ensure that the site’s structure and display made sense to users. Following are the key points we considered and the choices we made for the major pages in the site.

All pages

Search

Error Messages

Empty Search Results Page

“Too Many Results” Search Results Page

Normal Word-Search Results Page

Advanced Search Page

Passage Display Page

Coding Perspective

We wanted our code to be modular and interconnected, so a change in one location would not require changes in many locations.

Web Standards

Because we stored the text of the Bible in XML, we decided to code the site in XHTML 1.0 Transitional. We tried to avoid using presentational markup and tables for layout as much as possible, but in some cases browser limitations made them more attractive than strictly structural solutions. (At the time of this writing, most people are using Internet Explorer 6 and 5.) Dealing with browser quirks in displaying CSS probably added a couple of days to the development cycle, but using XHTML will save us time in the long run when we do not have to rip out our table-based layout and replace it with more logical markup. In time we hope to remove all presentational markup.

A benefit of using XHTML is its ability to display on a number of devices (such as mobile phones) without large changes. As mobile devices become a common means of accessing the Internet, this benefit will become increasingly important. We also believe that a site’s accessibility (for partially sighted users, for example) is important, and using logical markup facilitates accessibility.

We hid CSS stylesheets from Netscape 4 and other outdated browsers. They receive a plain but usable version of the site.

Our other reason in using stylesheets stemmed from a desire to avoid having a separate “printer-friendly” version of each page. All pages on the site use a print stylesheet that omits much web-specific navigation and changes fonts and spacing to make them better suited to print. (For reference, please see http://www.alistapart.com/stories/goingtoprint/.)

Database Schema

The MySQL database that powers the site has four tables, as described below.

The column unit_id is a zero-padded eight-digit number that uniquely identifies each verse in the Bible: The first two digits are the book number (01-66), the next three digits are the chapter number (001-150), and the last three digits are the verse number (001-176). Using this setup allows us to parse the string to determine which verse we are seeing, rather than having to go to the database and retrieve the related values. For example, John 3:16 has a unit_id of 43003016.

Table 1: esv_xml. The XML text of the Bible. The begin_ and end_ columns tell us whether the verse is in a paragraph and/or a block-indent, and thus whether we need to add the necessary <p> or <div> tags to the displayed html code so it displays properly. (If begin_paragraph is 2, it is in a line-group (making it essentially redundant with begin_indent), and if it is 3, it is in a line (e.g., Psalm 48:2). Similarly with end_paragraph.)
CREATE TABLE esv_xml (
book tinyint(3) unsigned NOT NULL default '0',
chapter tinyint(3) unsigned NOT NULL default '0',
verse tinyint(3) unsigned NOT NULL default '0',
unit_id int(8) unsigned zerofill NOT NULL default '00000000',
begin_par char(1) default NULL,
begin_indent char(1) default NULL,
end_par char(1) default NULL,
end_indent char(1) default NULL,
content text NOT NULL,
PRIMARY KEY (unit_id),
KEY book (book,chapter,verse),
KEY book_2 (book,unit_id)
)

Table 2: esv_text. The plain text of the Bible, which we use in searching.
CREATE TABLE esv_text (
unit_id int(8) unsigned zerofill NOT NULL default '00000000',
header varchar(255) NOT NULL default '',
content text NOT NULL,
footnote text NOT NULL,
PRIMARY KEY (unit_id),
FULLTEXT KEY header (header,content,footnote),
FULLTEXT KEY content (content),
FULLTEXT KEY footnote (footnote)
)

Table 3: esv_words. A listing of all the words in the text, which we use in spell-checking queries that return no results.
CREATE TABLE esv_words (
word varchar(20) NOT NULL default '',
phonetic varchar(10) default NULL,
occurrences smallint(5) unsigned NOT NULL default '0',
PRIMARY KEY (word),
KEY phonetic (phonetic)
)

Table 4: esv_books. General information about the books of the Bible.
CREATE TABLE esv_books (
book tinyint(4) NOT NULL default '0',
full_name varchar(15) NOT NULL default '',
short_name varchar(6) NOT NULL default '',
max_chapter tinyint(3) unsigned NOT NULL default '0',
testament char(3) NOT NULL default '',
section varchar(17) NOT NULL default ''
)

PHP Backend

We coded the site in PHP 4.2+, using Dreamweaver MX as our coding environment.

Available Source Code

Handling Input

The parsing engine needs to handle all of the following queries intelligently. While some of them fall into the realm of “corner cases,” others happen frequently. We believe our solutions accord with user expectations, but you may wish to handle certain cases differently.

Query What the ESV Online Edition does
mark Goes to Mark 1. Asks if the user instead wants to search for the string mark. Originally we designed the site so it would search for the word first and ask if the user wanted to see the passage. After reviewing our search logs, we decided that users expected the current behavior instead.
1 thess When the name of a book does not appear in the text, shows the first chapter of the book without asking if the user wants to search for the string.
II peter 1 Shows 2 Peter 1.
matthew 2, luke Shows Matthew 2, Luke 1.
luke 7 joy Shows Luke 7 and discards joy.
luke joy Searches for occurrences of luke and joy.
romans 55 Indicates that Romans 55 does not exist and offers to show Romans 16.
romans 3-2 Shows Romans 3:1 and gives an error about the 2.
romans 3-5 Shows Romans 3-5.
romans 16-20 Shows Romans 16 and silently ignores 17-20.
romans 12- Shows Romans 12-16.
romans 12-end Shows Romans 12-16.
romans 3:2-5 Shows Romans 3:2-3:5.
romans 3:5-4 Shows Romans 3:5-4:25.
romans 3:2-1 Shows Romans 3:2 and gives an error about the 1.
romans 3:2-500 Shows Romans 3:2-3:31. Silently ignores the 500. The silent ignoring of verses or chapters that run too high comes from how we handle the data in the program, rather than user-testing. Still, we consider this behavior acceptable.
romans 3:12- Shows Romans 3:12-3:31.
romans 3:12-end Shows Romans 3:12-3:31.
romans 3:2-1:6 Shows Romans 1:6-3:2.
romans 3:500 Indicates that Romans 3:500 does not exist and offers to show Romans 3.
romans 0 Shows Romans 1.
philemon 5 Shows Philemon 1:5. Similarly for other single-chapter books.
romans chapter 8 verse 28 Shows Romans 8:28.
romans 3:2b Shows Romans 3:2. Both a and b are ignored when they occur after a number and before a hyphen, colon, comma, space, or the end of the query.
romans 3:12ff Shows Romans 3:12-3:31.
john 3"16 Shows John 3:16. This typo happens often enough to warrant addressing.
acts 8:37 Shows Acts 8:36-38. Acts 8:37 is skipped in the ESV and appears in the footnote following 8:36. For minimum disorientation, we show the surrounding verses. Similarly with other skipped verses.
romans 3 12 Shows Romans 3:12. We decided on this behavior after reviewing our search logs.
ma 12 Shows Matthew 12. Because the abbreviation could be for Matthew or Mark, asks if the user meant Mark 12. Malachi 12 doesn't exist, so we don't ask about it. If it did exist, however (e.g., ma 2), we would ask about it.
mark 15 - luke 2 Shows Mark 15 - Luke 2. Although a query that spans more than one book happens infrequently (usually Genesis 1 - Revelation 22), the site’s previous behavior (showing Mark 15-16 and Luke 2) violated users’ expectations.
1 john - 3 john Shows 1 John 1 - 3 John 1. Even more rarely, someone will omit the beginning or ending chapter in a query spanning multiple books.

Other Features

Since the original writing of this article, we have implemented:

Future Directions

We may allow the saving of certain settings, such as “Show me red-letter text” and “Show me one verse per line, rather than in paragraphs.”

Bible Book Query Patterns

The table below shows the distribution pattern of inputs and abbreviations for all the books of the Bible, based on approximately 500,000 queries. In developing a Bible site, you should probably support any queries that account for over 1% of the queries for a given book. Known misspellings were converted to the closest form (e.g., Galations became part of the total for Galatians). If you're interested, download this Excel spreadsheet (44 KB) to see different ways of looking at the data.

Query Count % Query Count %
Genesis 29,679   Matthew 26,711  
genesis 16,607 56.0% matthew 20,255 75.8%
ge 10,808 36.4% matt 3,899 14.6%
gen 2,257 7.6% mt 1,793 6.7%
gn 7 0.0% mat 764 2.9%
Exodus 16,153   Mark 11,085  
ex 8,267 51.2% mark 10,062 90.8%
exodus 7,745 47.9% mk 982 8.9%
exo 68 0.4% mr 21 0.2%
exod 67 0.4% mar 19 0.2%
exd 6 0.0% mrk 1 0.0%
Leviticus 9,055   Luke 15,092  
lev 5,098 56.3% luke 13,497 89.4%
leviticus 3,909 43.2% lk 1,428 9.5%
le 33 0.4% luk 122 0.8%
levi 14 0.2% lu 45 0.3%
lv 1 0.0% John 26,069  
Numbers 10,675   john 24,405 93.6%
num 6,356 59.5% joh 1,157 4.4%
numbers 4,250 39.8% jn 495 1.9%
nu 57 0.5% jhn 7 0.0%
number 7 0.1% jo 5 0.0%
numb 5 0.0% Acts 16,611  
Deuteronomy 13,142   acts 15,439 92.9%
dt 6,125 46.6% ac 1,006 6.1%
deuteronomy 6,020 45.8% act 166 1.0%
deut 934 7.1% Romans 26,662  
deu 63 0.5% romans 21,683 81.3%
Joshua 8,011   rom 4,187 15.7%
jos 4,342 54.2% ro 724 2.7%
joshua 3,415 42.6% roman 55 0.2%
josh 254 3.2% rm 13 0.0%
Judges 7,025   1 Corinthians 16,336  
jdg 3,671 52.3% 1 corinthians 11,361 69.5%
judges 3,242 46.1% 1 cor 4,192 25.7%
judg 112 1.6% i corinthians 339 2.1%
Ruth 2,191   i cor 212 1.3%
ruth 1,179 53.8% corinthians 104 0.6%
ru 1,012 46.2% 1 co 50 0.3%
1 Samuel 10,154   1 corin 17 0.1%
1 sa 5,166 50.9% 1 corinth 13 0.1%
1 samuel 4,453 43.9% 1 corinthian 10 0.1%
1 sam 404 4.0% first corinthians 9 0.1%
i samuel 69 0.7% 1st corinthians 6 0.0%
samuel 44 0.4% 1st cor 6 0.0%
i sam 14 0.1% 1 corth 5 0.0%
1st samuel 3 0.0% corinthian 3 0.0%
isamuel 1 0.0% i corinth 2 0.0%
2 Samuel 7,476   1 corint 2 0.0%
2 sa 4,007 53.6% icor 2 0.0%
2 samuel 3,144 42.1% first cor 1 0.0%
2 sam 290 3.9% icorinthians 1 0.0%
ii samuel 23 0.3% i corint 1 0.0%
ii sam 4 0.1% 2 Corinthians 7,153  
2nd samuel 4 0.1% 2 corinthians 5,141 71.9%
seconds 2 0.0% 2 cor 1,828 25.6%
2nd sam 1 0.0% ii corinthians 77 1.1%
second samuel 1 0.0% ii cor 41 0.6%
1 Kings 6,994   2 co 31 0.4%
1 ki 3,722 53.2% 2 corin 7 0.1%
1 kings 3,093 44.2% 2 corinth 7 0.1%
1 kgs 54 0.8% 2 corinthian 5 0.1%
i kings 34 0.5% 2nd corinthians 4 0.1%
king 24 0.3% second corinthians 4 0.1%
1 king 23 0.3% 2nd cor 4 0.1%
kings 18 0.3% ii corinthian 2 0.0%
1st kings 10 0.1% iicor 1 0.0%
1 kin 4 0.1% ii co 1 0.0%
1 kn 3 0.0% Galatians 7,019  
1 k 3 0.0% galatians 5,149 73.4%
i kgs 2 0.0% gal 1,638 23.3%
kin 1 0.0% ga 226 3.2%
ikgs 1 0.0% galatian 4 0.1%
i kin 1 0.0% gala 1 0.0%
i ki 1 0.0% galat 1 0.0%
2 Kings 7,392   Ephesians 12,142  
2 ki 4,258 57.6% ephesians 8,418 69.3%
2 kings 3,054 41.3% eph 3,647 30.0%
2 kgs 50 0.7% ephesian 39 0.3%
ii kings 14 0.2% ep 17 0.1%
2 kin 6 0.1% ephes 11 0.1%
2 king 6 0.1% ephe 9 0.1%
iikgs 2 0.0% ephs 1 0.0%
2 k 1 0.0% Philippians 6,636  
2nd kings 1 0.0% philippians 4,712 71.0%
1 Chronicles 3,365   phil 1,688 25.4%
1 chronicles 3,072 91.3% php 134 2.0%
1 chron 210 6.2% philip 43 0.6%
i chronicles 19 0.6% ph 23 0.3%
1 ch 18 0.5% phi 21 0.3%
1 chr 17 0.5% philippian 8 0.1%
i chron 14 0.4% phl 4 0.1%
chronicles 10 0.3% philipp 3 0.0%
1 chronicle 2 0.1% Colossians 5,614  
i chr 1 0.0% colossians 3,730 66.4%
1st chronicles 1 0.0% col 1,869 33.3%
1st chron 1 0.0% colossian 13 0.2%
2 Chronicles 3,665   co 2 0.0%
2 chronicles 3,352 91.5% 1 Thessalonians 4,023  
2 chron 259 7.1% 1 thessalonians 2,343 58.2%
2 chr 14 0.4% 1 thess 711 17.7%
ii chronicles 13 0.4% i thessalonians 531 13.2%
2 ch 10 0.3% 1 thes 296 7.4%
ii chron 8 0.2% 1 th 41 1.0%
2 chro 4 0.1% i thess 37 0.9%
2nd chron 2 0.1% thessalonians 21 0.5%
2nd chronicles 1 0.0% i thes 21 0.5%
iichronicles 1 0.0% 1 thessalonian 7 0.2%
2 chronicle 1 0.0% 1 the 5 0.1%
Ezra 3,577   first thessalonians 5 0.1%
ezr 2,122 59.3% thes 1 0.0%
ezra 1,455 40.7% 1st thess 1 0.0%
Nehemiah 4,799   1st thes 1 0.0%
ne 2,780 57.9% thess 1 0.0%
nehemiah 1,831 38.2% 1st thessalonians 1 0.0%
neh 188 3.9% 2 Thessalonians 1,777  
Esther 3,415   2 thessalonians 1,017 57.2%
es 1,975 57.8% 2 thess 577 32.5%
esther 1,408 41.2% 2 thes 135 7.6%
esth 26 0.8% 2 th 20 1.1%
est 6 0.2% ii thessalonians 10 0.6%
Job 13,072   ii thess 8 0.5%
job 13,069 100.0% 2 the 5 0.3%
jb 3 0.0% ii thes 3 0.2%
Psalms 43,155   iithessalonians 1 0.1%
psalm 20,480 47.5% ii th 1 0.1%
ps 13,361 31.0% 1 Timothy 5,194  
psalms 8,425 19.5% 1 timothy 3,834 73.8%
psa 880 2.0% 1 tim 905 17.4%
psm 9 0.0% 1 ti 214 4.1%
Proverbs 11,497   i timothy 110 2.1%
proverbs 8,472 73.7% timothy 64 1.2%
pr 1,446 12.6% i tim 56 1.1%
prov 1,428 12.4% 1 timoth 4 0.1%
pro 125 1.1% 1 tm 3 0.1%
proverb 21 0.2% first timothy 1 0.0%
prv 4 0.0% timoth 1 0.0%
prvbs 1 0.0% 1st tim 1 0.0%
Ecclesiastes 3,708   1st timothy 1 0.0%
ecclesiastes 2,881 77.7% 2 Timothy 3,898  
ecc 643 17.3% 2 timothy 2,780 71.3%
eccl 122 3.3% 2 tim 880 22.6%
eccles 23 0.6% 2 ti 150 3.8%
ec 22 0.6% ii timothy 66 1.7%
ecl 15 0.4% ii tim 14 0.4%
ecclesiaste 2 0.1% 2 tm 4 0.1%
Song of Solomon 2,064   second timothy 2 0.1%
song of solomon 1,517 73.5% 2nd tim 1 0.0%
song 441 21.4% 2nd timothy 1 0.0%
song of songs 71 3.4% Titus 2,360  
so 9 0.4% titus 2,195 93.0%
son 9 0.4% tit 165 7.0%
songs 8 0.4% Philemon 698  
sos 4 0.2% philemon 503 72.1%
ss 4 0.2% phm 182 26.1%
song ofsolomon 1 0.0% phile 10 1.4%
Isaiah 15,756   philem 3 0.4%
isaiah 10,754 68.3% Hebrews 12,702  
isa 4,236 26.9% hebrews 9,427 74.2%
is 757 4.8% heb 3,194 25.1%
isah 5 0.0% hebrew 81 0.6%
isai 3 0.0% James 6,728  
ia 1 0.0% james 5,967 88.7%
Jeremiah 7,675   jas 701 10.4%
jeremiah 4,825 62.9% jam 45 0.7%
jer 2,821 36.8% jms 5 0.1%
je 19 0.2% jame 5 0.1%
jere 10 0.1% ja 4 0.1%
Lamentations 894   jm 1 0.0%
lamentations 666 74.5% 1 Peter 6,804  
la 128 14.3% 1 peter 5,118 75.2%
lam 96 10.7% 1 pet 1,132 16.6%
lamentation 4 0.4% 1 pe 230 3.4%
Ezekiel 6,186   i peter 181 2.7%
ezekiel 4,405 71.2% peter 88 1.3%
eze 1,374 22.2% i pet 16 0.2%
ezek 298 4.8% 1 pete 11 0.2%
ez 62 1.0% 1st peter 9 0.1%
ezk 47 0.8% 1 pt 9 0.1%
Daniel 3,275   first peter 7 0.1%
daniel 2,579 78.7% 1 p 1 0.0%
dan 351 10.7% ipeter 1 0.0%
dn 328 10.0% ip 1 0.0%
da 16 0.5% 2 Peter 3,033  
dl 1 0.0% 2 peter 2,263 74.6%
Hosea 2,074   2 pet 431 14.2%
hosea 1,592 76.8% ii peter 182 6.0%
ho 360 17.4% 2 pe 138 4.5%
hos 122 5.9% second peter 5 0.2%
Joel 875   2 p 4 0.1%
joel 634 72.5% 2 pete 3 0.1%
joe 239 27.3% ii pet 3 0.1%
jl 2 0.2% 2 pt 3 0.1%
Amos 1,587   2nd peter 1 0.0%
amos 1,229 77.4% 1 John 6,649  
am 357 22.5% 1 john 6,032 90.7%
amo 1 0.1% 1 jn 315 4.7%
Obadiah 302   i john 224 3.4%
obadiah 259 85.8% 1 jo 41 0.6%
ob 40 13.2% 1 joh 14 0.2%
obad 2 0.7% 1st john 8 0.1%
oba 1 0.3% first john 6 0.1%
Jonah 1,212   i jn 4 0.1%
jonah 1,092 90.1% ijohn 3 0.0%
jon 120 9.9% i jo 2 0.0%
Micah 1,419   2 John 465  
micah 1,138 80.2% 2 john 419 90.1%
mic 281 19.8% 2 jn 39 8.4%
Nahum 656   2 jo 3 0.6%
nahum 555 84.6% 2nd john 1 0.2%
na 82 12.5% iijohn 1 0.2%
nah 19 2.9% ii john 1 0.2%
Habakkuk 1,094   second john 1 0.2%
habakkuk 754 68.9% 3 John 570  
hab 340 31.1% 3 john 536 94.0%
Zephaniah 807   3 jn 29 5.1%
zephaniah 647 80.2% 3 jo 2 0.4%
zep 94 11.6% iii john 2 0.4%
zeph 66 8.2% 3rd john 1 0.2%
Haggai 497   Jude 1,388  
haggai 393 79.1% jude 1,347 97.0%
hag 102 20.5% jud 41 3.0%
hagg 2 0.4% Revelation 11,455  
Zechariah 2,364   revelation 7,944 69.3%
zechariah 1,596 67.5% rev 2,732 23.8%
zec 565 23.9% re 675 5.9%
zech 203 8.6% revelations 102 0.9%
Malachi 1,477   revel 1 0.0%
malachi 1,141 77.3% rv 1 0.0%
mal 336 22.7%      

Comments

Comments are welcome. Contact webmaster@gnpcb.org.

Credits

If you made it all the way down here, you might also be interested in The Development of Verse-Level Audio at the ESV Online Edition, which talks about the technology behind how we let people browse the ESV audio by verse.

Gospelcom.net Alliance Member