Laridian® VerseLinker

User's Guide

 

October 2012

 

Table of Contents

Overview

The Problem

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).

The Solution

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.

Philosophy and Implementation

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.

Preparing Your Text

Basic Text Editing Tips

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.

When to Run VerseLinker

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.

Running VerseLinker

Launch VerseLinker.

Observe the following areas of the program interface:

A. Version Header
Gives the date the program was built. This is useful for determining if you have the latest version of the program.
B. File Input Area
Contains a field for display of the file name you're processing. Select the Browse... button to select a file, then select either the Pre-Link or Go! button to start linking (see instructions below).
C. Recent Lines
The large box in the center of the dialog shows the last few lines that have been processed when the program stops to ask for your input. This is not an edit area; you can't change the text here. It is here only to show you the context of the line on which the program has stopped so you can better determine what to do.
D. Status Area
This area displays a progress bar representing your position in the input file, and any status messages from the program that might help you choose the correct book and chapter.
E. Context Area
Book Context and Chapter Context fields show you the name of the book and chapter in that book that the program considers the “context” of the potential verse reference it has stopped to ask you about. To change the book and chapter in the Accept text (see area I, below), it is best to change these Book Context and (optionally) Chapter Context fields, then select the Use This button to cause the book and chapter you've entered to be inserted into the Accept field.
F. My Last Entry Area
When you change the Book or Chapter Context fields, the text you enter is copied into My Last Book and My Last Chapter. This is sometimes helpful when you find yourself having to repeatedly type the same thing into VerseLinker because it is confused about the context. If you find that the Accept text should be using the book or chapter from this area, select the Restore Mine button. The values from My Last Book and My Last Chapter will be copied to the Book and Chapter Context fields and also inserted into the Accept text.
G. Last Context Tags
Displays the last explicit book or chapter context tag it has seen. For a Bible or commentary, these include the <pb_sync verse=...> tag. For all books, book and chapter context is set by the <pb_context> tag. This information may help you determine the correct context for the text. To replace the book and chapter in the Accept text with these values, select the Restore Cntxt button. The values from the Last Context Tag fields will be copied into the Book Context and Chapter Context fields, and will be inserted into the Accept text.
H. Options
An area of check boxes for setting program options. The version of VerseLinker you have may not have all these options.
I. Accept Text and Skip Text
The fields to the left of the Accept and Skip buttons show you the text that the program is going to use to replace the highlighted text in the Recent Lines window if you choose the button associated with that field.
J. Other Buttons
...As Chapter changes the Accept text to treat a number or range as if it was a chapter, not a verse. Undo will undo the last edit made. Quit will copy the rest of the book to the output file unchanged. When the program is done, Quit will change to Done and is used to exit the program.

Instructions

Automatic Backup Files

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.

Pre-Linking

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.

Pre-Linking Caveats

Verse Linking

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.

Keyboard Shortcuts

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.

ButtonShortcutDescription
Use ThisAlt+TUse the book and chapter from the Book Context and Chapter Context fields
Restore MineAlt+MUse the book and chapter from My Last Book and My Last Chapter fields
Restore CntxtAlt+RUse the book and chapter from the Last Context Tag fields
AcceptAlt+AReplace the highlighted text with the Accept Text
SkipAlt+SReplace the highlighted text with the Skip Text
As ChapterAlt+CMake the verse number in the Accept Text be a chapter number
UndoAlt+UUndo the last change (regardless of if it was an Accept or Skip)

Changing Program Options

VerseLinker has three checkboxes that affect its operation:

Skip parenthesized numbers

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.

Don't reset context after 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.)

No sound

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.

Linking in Two or More Sessions

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.

How VerseLinker Determines Context

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.

Explicit Context Changes

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.

Implicit Context Changes

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:

Ignored Words and Phrases

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.

Within Certain Tags

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.

Dates

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.

Time

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”.

Measurements

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.).

Numbers of things

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

Parenthesized numbers may or may not be linked, depending on the setting of the “Skip Parenthesized Numbers” checkbox.

Confusing Words

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”.

Pseudepigraphal References

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.

Error Messages

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.

Unterminated <a...> tag in this file!

There is an <a...> tag somewhere in the file that doesn't have a matching </a> tag.

This book ends in a non-English language (may be OK; may be missing tag)
This book ends in a non-Spanish language (may be OK; may be missing tag)
This book ends in a language other than that in which it began (may be OK; may be missing 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.

Unterminated <hn...> tag.

“n” will be a digit from 1-9. The corresponding closing tag is missing.

Unclosed <pb_context...> tag.

There must be a matching </pb_context> tag for each <pb_context> tag. You've left out the closing tag somewhere in your document.

Missing end of HTML tag on this line

The program has encountered a tag with no closing greater-than (>) symbol.

Nested heading tag inside <hn>

“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.

Saw </hm> tag after <hn>

“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>

Mismatched <pb_nolinks> and </pb_nolinks> in this book.

Either there's an extra or a missing </pb_nolinks> tag (which could be because there's an extra or missing <pb_nolinks> tag).

Unterminated <pb_context...> tag: ...

Missing </pb_context> tag.

Missing book= and chapter= attributes in <pb_context...> tag:...

Self-explanatory.

Unterminated quote in book name in <pb_context...> tag:...

Self-explanatory.

Unrecognized <pb_context...> tag book name contents:...

Self-explanatory.

Unterminated quote in chapter number in <pb_context...> tag:...

Self-explanatory.

Extra </pb_context> tag:...

Self-explanatory.

Bad or missing value attribute in <pb_sync...> tag:...

Self-explanatory.

Unrecognized verse sync verse:...

The verse in the value attribute of a <pb_sync type=verse value=...> tag is not a valid Bible verse.

Contents

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.