October 2012
One of the things that gives electronic Bible study an advantage over using printed books are the links that can be created between reference books and Bibles. While this is a great advantage, it is also a great burden on reference book authors and editors, who have to manually “tag” the text to create those links. That is, they insert special codes into the text to tell the Bible reader software that a particular word or reference in the text should be linked to a particular Bible verse.
Authors of new reference books can structure their text to simplify the tagging process. For example, always fully specifying a reference (like saying “John 3:16” instead of “verse 16”) helps automated tools find and tag references automatically. But those working with existing manuscripts from authors who were not bound by the rigors of creating well formed documents that are easy to processes electronically find themselves mired in various conventions with respect to Bible verse citations.
In short, VerseLinker is a tool that takes text like this:
In John 3:16 we find the motive for God's gift...
verse 17 emphasizes Jesus' role as savior, not as judge, for those
who believe.
... and turns it into:
In John 3:16 we find the motive for God's gift... verse 17 emphasizes Jesus' role as savior, not as judge, for those who believe.
... without turning this:
Jesus had over 100 disciples who followed him in the 3 short years of his ministry. Among these he chose 12 we know by name, and from the 12, 3 as his inner circle.
... into this:
Jesus had over 100 disciples who followed him in the 3 short years of his ministry. Among these he chose 12 we know by name, and from the 12, 3 as his inner circle.
(where all the numbers have been linked to Bible verses because the program couldn't distinguish between verse numbers and other uses of numbers in the text).
VerseLinker is a tool we developed to help our editors find and tag Bible references in a document so that those Bible references can be linked to the Bibles in our electronic Bible readers. VerseLinker uses sophisticated algorithms to seek out Bible references within a document and surrounds them with tags that make it easy for our BookBuilder™ program to create links to the Bible itself.
In reviewing the processes used by our friends at other Bible software companies to solve this problem, we found a couple of approaches:
We found both of these approaches unacceptable. We needed at least a semi-automated tool so that we wouldn't be wasting hours performing a repetitive manual task. But we didn't want it so automated that it made gross mistakes no matter how quickly it ran.
Because we want accurate results, VerseLinker is an interactive program. It requires your concentration but in the end gives you a very accurately tagged book — at least if you were paying attention in the process. It will automatically link unambiguous references like “John 3:16” and even complex references like “Gen 1:1-2:3; Ps 102:25; Jn 1:1-2”. It's smart enough to know that “10 kings” is not a Bible references, but that “1 Kings 10” is. And it can even understand that parenthesized numbers like (1) this and (2) this may not be references to verses 1 and 2.
When it encounters an ambiguous situation like “10:10” it stops and asks you what to do. It reads the text and picks up context so that it can guess what book of the Bible “10:10” may refer to. It gives you its best guess and allows you to choose that with one keystroke or click of the mouse. It also gives you the ability to manually override its guess or to tell it that this isn't a Bible reference at all.
The program is designed to be run in several sessions if you have a very large source document. At any time in the process you can stop what you're doing. The program will save a partially tagged version of your file. When you are ready to continue, just run the program again and it picks up where you left off.
If you are an author creating a document from scratch, there are some things you can do to improve the performance of VerseLinker and save yourself a lot of time when linking Bible references. Some of these ideas can also be applied when you're the editor of an existing text and trying to improve its chances of running through VerseLinker with as little manual intervention as possible.
We've found it's best to do all the rest of your tagging and editing before running VerseLinker. There are several reasons for this:
So get your book so it builds with BookBuilder, works well in PocketBible or MyBible, and, if it's a commentary, has all the correct synchronization tags so you can sync it to your Bible and have it follow along. Then run VerseLinker and do your final pass through BookBuilder, followed by a thorough proofreading pass that exercises as many links as you have time for.
Launch VerseLinker.
Observe the following areas of the program interface:
Launch the program and use the Browse button to select a file to operate on. When you select either Pre-Link or Go!, the program will immediately make a copy of your file called filename (1).ext. It then uses this back-up file as its input, and writes output to your original file. If you stop in the middle of this session and continue later, then filename (1).ext becomes filename (2).ext, the file you select with Browse becomes filename (1).ext, and the program operates as before. Nine back-up versions of your file are retained in this way.
Just remember, you're always working on the file as it was originally named (what we'll refer to as filename.ext).
If you ever need to restore a backup, you should delete filename.ext and rename the appropriate backup file to be the new filename.ext. So if you discover that you've made a bunch of changes incorrectly and you just want to get back to where you started the current VerseLinker session, exit the program and delete your main file (filename.ext). Then rename filename (1).ext to filename.ext and continue processing that file.
There are two ways to use VerseLinker. The traditional way is interactive -- you select the Go! button and the program links what it can and stops to ask for your help when it can't determine what the link should be. For large files, it may be quicker to “pre-link” the file before going through the interactive phase.
When you select a file and choose the Pre-Link button, VerseLinker goes through the file and links everything it knows for sure how to link. It then marks everything about which it has a question. When the Pre-Link pass is done, you can select Go! and the program will only stop at those places where it wasn't sure how to create the link. (Those places are marked in your file with <pb_prelink> tags so that VerseLinker can quickly find them.)
The reason pre-linking the file is faster is because you can go do something else while it does the pre-linking pass through the file. When you come back you move very quickly through each point in the text where there is some confusion about the context of the numbers VerseLinker finds. You don't have to wait for it to do the parsing of the file; that is already done during pre-linking. This makes better use of your time.
You don't have to do the interactive phase of verse linking immediately after you do the pre-link phase. You can pre-link a file, do some other tasks or even edit the file, then come back and run VerseLinker again and this time select Go! to do the normal verse linking phase.
After you select Go!, the program begins linking all the references it sees that it can be confident are Bible references (if this hasn't already been done during the pre-linking phase). If you have a very well-formed document, it may never stop and ask for your help. It will simply process the entire file and tell you when its done by putting a message in the Status Line and changing the text of the Quit button to Done.
It's more likely, however, that the program will eventually stop and show you a highlighted portion of text from your file that it doesn't know how to handle. You'll see the last few lines of text it's processed in the Recent Lines window, the current book and chapter context (if any) in the Context Area, and the text it's going to use if you select Accept or Skip in the Accept Text and Skip Text fields to the left of their associated buttons.
At this point you should examine the text and determine to what Bible verse the author is refering. Then examine the Accept Text. If the tag is correct, select the Accept button. If necessary, make changes directly to the Accept Text to make it read the way you want, then select Accept. You can do any of the following:
If the program has selected a completely incorrect piece of text to replace, you'll have to stop VerseLinker and edit the file to correct the problem. Or you can select Skip for now and make a note to go back and correct the file when you're done. This rarely happens. It is usually associated with some kind of ambiguous piece of text like “Jn 3 16” where the author has left out a colon. Another way this can happen is if the author uses an unusual abbreviation, such as “Numb” for “Numbers”. When VerseLinker sees “Numb. 1:1” it will skip “Numb.” and ask you how to link “1:1”. You can either link the text to Num 1:1 or (better yet) exit VerseLinker and edit the file to change “Numb.” to “Num” or “Num.”.
If you examine the text and discover that the number the program has highlighted isn't a Bible reference at all, select Skip. The program will output the highlighted text unchanged (unless you change it in the Skip Text field, which you shouldn't normally do) and continue to the next problem.
Sometimes, especially in commentary refering to Psalms, a number will appear that is a reference to a chapter. The program will often interpret these as a reference to a verse and use any existing chapter context to provide a chapter number. Rather than manually editing the Accept Text to make it correct, it's easier to select the As Chapter button. This will change the tags and text in the Accept Text field to assume that the numbers it found are actually chapter numbers. So, for example, “1-3” will now refer to “Psalm 1-3” instead of “Psalm 1:1-3”.
While examining a reference you may realize that you've been tagging references incorrectly. You can use the Undo button to go back to a previous position in the file and start again from there. There are only about ten levels of undo, so if you've made a large mistake you might want to follow the instructions above to go back to the beginning of your session by renaming one of the back-up files.
Note that the changes you make with the Accept and Skip buttons are not reflected in the recent lines as displayed in the large text field (area C above). The recent lines box always shows you the lines as they appear in the original file. The changes you make are being made to a new version of the file.
If you pre-linked the file, the <pb_prelink> tags will be removed from the text you see in the Recent Lines box, but only for the text you have already linked or are in the process of linking. You may see those tags in text that comes later in the document, but they will disappear when you get to the point where you are linking the number(s) contained in the <pb_prelink>...</pb_prelink> tag.
Note that all the buttons in VerseLinker have shortcut keys associated with them. These are indicated by underlined letters in the title of the button, just like in all your other Windows applications.
| Button | Shortcut | Description |
| Use This | Alt+T | Use the book and chapter from the Book Context and Chapter Context fields |
| Restore Mine | Alt+M | Use the book and chapter from My Last Book and My Last Chapter fields |
| Restore Cntxt | Alt+R | Use the book and chapter from the Last Context Tag fields |
| Accept | Alt+A | Replace the highlighted text with the Accept Text |
| Skip | Alt+S | Replace the highlighted text with the Skip Text |
| As Chapter | Alt+C | Make the verse number in the Accept Text be a chapter number |
| Undo | Alt+U | Undo the last change (regardless of if it was an Accept or Skip) |
VerseLinker has three checkboxes that affect its operation:
Some reference books include hundreds of little lists within the text, designated with parenthesized numbers. These lists look (1) like (2) this. Check this box ignore any numbers that are enclosed in parenthesis. Note that the text in parenthesis must all be digits in order for it to be ignored. So if you check this box and the program encounters “(see also verse 3)”, it will link the “3” even though it occurs in parenthesis.
Some reference books contain lists of cross-references in parenthesis, and the text is written in such a way that the context is better determined by ignoring the text in parenthesis. An example would be a list of verse numbers, each followed by a cross-reference specific to that verse, as in: “See how this topic is addressed in verses 3 (Gen 1:1), 5 (Exo 20:2), 19 (Dt 6:6), and 27 (Josh 1:6)”. If an author makes frequent use of this technique, using VerseLinker on the book can be very tedious, as every parenthesized reference changes the context unnecessarily. Check this box to ignore references in parenthesis for the purpose of setting context. (Parenthesized references will still be linked.)
VerseLinker issues a system notification sound when there's something you should notice about a particular link. For example, if there's no way to determine the book or chapter context. Some books have many “false alarms”, though, and playing the sound can slow down the process of linking. Checking this box allows you to turn those sounds off so the program will run faster. And it's slightly less annoying.
It's not necessary to complete your verse linking in one session. If you want to stop and continue at another time, just select Quit. The program will copy the rest of the file to the output file unchanged. If you stop the program with Windows Task Manager or exit Windows without first exiting this program, the unprocessed portion of the file will not be copied to the output file and you will have to carefully restore it from backups. Always exit the program using the Quit button.
VerseLinker “reads” your book and picks up context as it goes along. So if you're creating a commentary, it helps to have the synchronization tags (<pb_sync...>) in place before running VerseLinker. When it encounters synchronization tags it updates its internal book and chapter context so the next time it encounters a number standing alone it can build a likely link.
Consider the following:
<p><pb_sync type=verse value="John 3:16">... this thought is continued in 18....
The digits “18” must refer to John 3:18 even though the “John 3” part is missing. VerseLinker knows this because it picked up the book and chapter from the <pb_sync...> tag.
So if VerseLinker knows that “18” refers to “John 3” why does it stop and ask you to accept this link?
Consider a couple different possibilities:
<p><pb_sync type=verse value="John 3:16">... Romans 5:8 describes the love that John speaks of in this verse.... this thought is continued in 18.
In the example above, the verse linker will automatically link “Romans 5:8” then change its internal context to Romans 5 knowing that future verse references will likely be referring to the same book and chapter as a previous reference. So when it reaches the digits “18” it assumes you want to link to Romans 5:18, which is incorrect.
<p><pb_sync type=verse value="John 3:16">... this thought is continued in 18 journal entries the author made in the month of July, 1841.
In the example above, it turns out the “18” isn't referring to a Bible verse at all, but rather what you're seeing is an excerpt of a sentence in which the author of the commentary is describing the comments a famous preacher recorded in his journal. Since the VerseLinker program didn't anticipate a phrase like “18 journal entries”, it assumes the “18” is a verse reference and asks you if you want to link it.
So we've seen a couple examples of why the program couldn't be made to automatically link every number in a reference book to a Bible verse. There are well-known commercial Bible software vendors who would place this link and simply hope you didn't ever see it. VerseLinker gives you the power to decide what is a real Bible reference and what is not.
The <pb_context> tag explicitly sets the context to a particular book and chapter. See the BookBuilder documentation for details of this tag.
Note that inside the block of text surrounded by <pb_context>...</pb_context>, VerseLinker will automatically link even ambiguous numbers. If you surround a large block of text with explicit context tags, make sure that every number inside the block is meant to be linked to the Bible.
The <pb_sync> tag explicitly sets the context to the first book and chapter in the reference in the tag. See the BookBuilder documentation for details of this tag.
The book and chapter context can be explicitly changed by the user any time the program pauses to ask for input. The Book Context and Chapter Context fields are read when either the Accept or Skip button is pressed, and the values in those fields replace any current context information the program is carrying.
The user can also force the context back to the last explicit context tag seen by pressing the Restore Cntxt button when the program is stopped, awaiting input.
Any well-formed Bible reference that is automatically tagged by VerseLinker will set the context to the first book and chapter in the reference. So encountering “John 3:16” in the text sets the book context to John and the chapter context to 3. Encountering “Gen 1:1; John 1:1” sets the context to Gen 1, not John 1.
Any mention of a book of the Bible sets the book context to that book. There are some exceptions to this that include:
The program will generally stop at a number unless it sees something in the surrounding context that indicates that this number can't be a verse. So when it sees “20 tons” or “60 men” it knows not to try to link the “20” or “60” to a Bible verse. But if it encounters “20” in the text and there's nothing to indicate it's not a verse reference, it will try to use its context to link it to a Bible verse.
Listed below are samples of the kinds of things that the VerseLinker recognizes and doesn't link. In each case it's looking for these words following a number.
Not all recognized words are listed. In some cases there are hundreds of words like those listed that the program recognizes. Enough are listed below to give you an idea of the kinds of terms that are ignored in the linking process. So if you see “18 kesitahs” in your text and wonder why the VerseLinker didn't stop on “18”, it's because it recognizes “kesitahs”.
Note that in most cases, the plural, singular, and hyphenated form of the word is recognized. So when you see “days” below, it actually means that “3 days”, “1 day” and “30-day” are all recognized and not linked.
Non-English text is not linked. Note that if you do not properly end <pb_lang> tag, VerseLinker could skip the rest of your document. In that case it will give you a warning message to tell you that the book you're processing ended in a non-English language. This should be your clue that something is wrong.
Text within <pb_nolinks>...</pb_nolinks> is not linked.
Text within <a...>...</a> is not linked.
Text within headings (<h1>, <h2>, <h3>, ..., <h9>) is not linked.
This program inserts <pb_vlskip>...</pb_vlskip> tags around sections of text that you've asked it not to link during a previous session. These tags remain in the file until you remove them, and cause future sessions to skip these same portions of text so that you don't have to answer the same question over and over again.
This program inserts <pb_link...>...</pb_link> tags around verses it links. These are skipped on subsequent sessions of VerseLinker. You can use these tags to manually link verses as well, and they will be skipped by VerseLinker.
Years are generally skipped because they're out-of-range. There is no verse “2005”, for example.
Years that are preceeded or followed by “AD”, “BC”, or “BCE” are not linked.
Days of the month that are preceeded or followed by the name of the month are not linked. Some common abbreviations are recognized for month names. Note that “Mar.” is recognized as an abbreviation for March, not the book of Mark. So “Mar. 1:1” will appear to VerseLinker as “March 1” followed by a colon and a 1. It will try to link the final 1 to whatever book and chapter are in context.
Numbers followed by words like “years”, “days”, “months”, “hours”, “minutes”, “seconds”, etc. are not linked.
Numbers followed by “A.M.” or “P.M.” are not linked. Note that “PM” is recognized but “AM” is not because it's an abbreviation for “Amos”. You should use “A.M.” and “P.M.” in your documents rather than “AM” and “PM”.
Most common measurements of distance (“feet”, “cubits”, “miles”, “stadia”, etc.) are recognized and numbers preceeding them are not linked.
Most common measurements of area (“acres”, “square miles”, “hectares”, etc.) are recognized, as are measurements of volume (“cubic feet”, “gallons”, “baths”, “bushels”, etc.). These will not be linked.
Most common measurements of weight and money are not linked (“tons”, “pounds”, “ounces”, “talents”, “drachma”, etc.).
Many descriptions of people are recognized and not linked (“boys”, “women”, “horsemen”, “satraps”, “descendants”, “disciples”, etc.).
Many places and things are recognized and are not linked (“provinces”, “chariots”, “towers”, “bowls”, “garments”, etc.)
Many names of animals are recognized and are not linked (“oxen”, “sheep”, “cattle”, etc.).
Some adjectives are recognized regardless of the nouns they modify (“silver”, “adult”, “Jewish”). So “3 Jewish men” is ignored, as is “30 silver coins”.
Descriptions of books and manuscripts are not linked (“books”, “bibles”, “words”, “miniscules”, etc.).
Numbers and ordinals are not linked (“million”, “degrees”, “%”, “st”, “rd”, etc.).
Pages and page numbers are not linked (“page”, “pages”, “pp”, “p”, “p.”, etc.).
Large numbers, like “5,000” and “180” are not linked. Numbers must be larger than the maximum number of chapters in a book (151) or verses in a chapter (176), depending on context.
Parenthesized numbers may or may not be linked, depending on the setting of the “Skip Parenthesized Numbers” checkbox.
Words like “prove” and “lame”, which look like abbreviations for “Proverbs” and “Lamentations” are ignored. There are several other words in this category, like “am”, “numb”, and “song”.
When book names like “3 Corinthians”, “Pseudo-Philo”, or “Sibylline Oracles” are followed by numbers that look like a chapter/verse reference, the numbers are ignored.
Note that VerseLinker recognizes the older PocketBible 2.x style tags even though they are not documented here. Error messages may vary from what is documented below if the older style tags are used.
There is an <a...> tag somewhere in the file that doesn't have a matching </a> tag.
This message indicates that you may have turned on a language that you did not later turn off. If the last word in your book is in a language other than that of the book itself, then this could be OK. Normally, this is an error and you need to investigate it.
“n” will be a digit from 1-9. The corresponding closing tag is missing.
There must be a matching </pb_context> tag for each <pb_context> tag. You've left out the closing tag somewhere in your document.
The program has encountered a tag with no closing greater-than (>) symbol.
“n” will be a digit from 1-9. You've placed a heading tag inside another heading tag, as in:
<h1>This heading
<h2>Contains this one</h2>
The second heading is contained in the first because the closing </h1> tag is missing from the first.
“m” and “n” are different values. You've closed a heading tag incorrectly as in:
<h1>This is a h1 but is closed with h2</h2>
Either there's an extra or a missing </pb_nolinks> tag (which could be because there's an extra or missing <pb_nolinks> tag).
Missing </pb_context> tag.
Self-explanatory.
Self-explanatory.
Self-explanatory.
Self-explanatory.
Self-explanatory.
Self-explanatory.
The verse in the value attribute of a <pb_sync type=verse value=...> tag is not a valid Bible verse.
Copyright © 2012 by Laridian, Inc. All Rights Reserved. Laridian, PocketBible, and MyBible are registered trademarks of Laridian, Inc. BookBuilder, VerseLinker, and DocAnalyzer are trademarks of Laridian, Inc. Other marks are the property of their respective owners.