NAME
    biblelink (v1.28) - Create hyperlinks to Bible references on input files

USAGE
      GENERAL:  biblelink [-options] file1*.* [file2*.htm* file3.as* ...]

      EXAMPLE:  biblelink -b Galatians  u1*.php v2*.*
                biblelink -b John -c 15 -p somefile.htm

OPTIONS
    Options may be clustered (e.g., "-sb Deut.").

    -a (automatic links)
         Intead of prompting the user for "chapter" and "verse" links, create
         them automatically without prompting. This may result in some false
         matches, which is why it is off by default. Bare references like
         "cf. 14:6" are always interactive.

    -b "1 Samuel"
         Change default book to 1 Samuel (default is Genesis). Abbreviations
         and lowercase are okay. E.g., "1sa" or "1 sam" are recognized.

    -c 12
         Change default chapter to 12 (default is 1).

    -d (debug)
         Print script debug info to stdout to track down script problems.

    -h (help)
         Issue help message in perldoc, and exit. Cancels all other options.

    -l (change l to 1)
         Silently changes occurrences of letter 'l' (lowercase L) where the
         number 1 (one) was expected. Sometimes needed where input files
         come from OCR scanning.

    -m (make links anyway)
         The default behavior is to skip the file if BibleLinks are detected,
         since this might re-link (or double-link) some Bible references. If
         the -m switch is used, this overrides the default and processes the
         file normally. Use this switch when a few links are already coded
         in the input file. NB: Double-linking MAY occur with this switch!

    -p (pause)
         Send output to the screen, pausing each screenful. Pipes the output
         to the pager specified by the enviroment variable %PAGER, or to LIST
         (if 4DOS or 4NT are active), or to LESS or MORE (in that order). This
         option does not alter the input file.  When -p is used, only one
         filename may be given on the command line.

    -s (stdout)
         Send output to standard output device (the screen), without paging.
         This option does not alter the input file. When -s is used, only one
         filename may be passed on the command line. If no filename is passed
         on the command line, input comes from stdin (usually, piped input).

DESCRIPTION
    Given a list of input files on the command line (ambiguous filespecs
    okay), BIBLELINK first checks to see that the list of files is valid.
    Files named *.BAK are skipped. The file is changed in-place with the
    same filename. The original file is saved as "sourcefile.type.BAK". If a
    file does not exist, such as a command line like:

        biblelink *.htm ooops!-a-typo.htm

    the mistaken word or filename is echoed to STDERR (the screen) with a
    beep, while the other files are modified. Files with the following file
    extensions are always skipped (case-insensitive match), even if they are
    explicitly listed on the command line:

    BAK EXE DLL LNK COM SYS BAT PL JS DOC PDF RTF JPG PNG GIF SWF FLA ZIP
    TAR GZ

    Wherever a valid Bible reference occurs (eg., Rom 6:10, 23), the entire
    reference is changed to an HTML hyperlink of the following form:

        <a href="javascript:bible('Romans+6:10,+23')">Rom 6:10, 23</a>

    All standard abbreviations of books of the Bible are recognized. A
    period is ignored when making the link, but is retained in the text. To
    make the finished file work in the HTML output files, insert the
    following script in the HEAD section of the HTML document:

      <SCRIPT LANGUAGE="JavaScript">
      <!-- BibleWindow function
      function bible(passage) {
        search="http://www.biblegateway.com/bible?"+passage
        bibleWindow=window.open(search,'Bible',"width=600,height=350,scrollbars,resizable")
        bibleWindow.focus()
      }
      // -->
      </SCRIPT>

    SILENT CORRECTIONS: Roman numerals (I Tim., II Cor.) before books of the
    Bible are automatically changed to digits. Many of our input files are
    generated by Microsoft Word ("Save As Web Page" or "Save As HTML"),
    which does not convert the en dash to a hyphen, resulting in "Gen.
    1:26?28" instead of "Gen. 1:26-28" as expected. Any question mark
    between two digits ("2?3" or "8?4") is silently changed to a hyphen.

    BIBLELINK uses a default book (Genesis) and default chapter (1). These
    are used because BIBLELINK will also generate links for all these:

        verse 14   vv. 19-22   (cf. 22:8-10)   (10:9-10)   chapters 2-3

    The default book or chapter may be changed from the command line via an
    option switch (-b or -c, followed by a string), or in the middle of a
    match at a user prompt. The default chapter is also automatically
    changed each time it finds a particular subheading declaration,
    described next.

    SUBHEADING DEFINITIONS: A large expository document will sometimes need
    to change the default chapter several times as it works through
    successive portions of a book. A single input file is usually broken
    into sections, each section dealing with a certain chapter or set of
    chapters in one of the books of the Bible. At Moody, we use stylesheet
    "classes" to change the appearance of heading titles. The heading title
    usually signals when a new chapter is required. For example:

       <P class='subheading'>The Word Became Flesh (John 1:1-18)</P>
       <H2 class="subheading2">The Millennial Temple (40-48)</H2>

    The string "subheading" followed by digits in parenthesis forms a
    pattern to indicate when the default chapter should be changed. The
    first string of digits with parentheses resets the default chapter. The
    "subheading" pattern MUST be followed by a closing tag such as </P>,
    </SPAN>, </Hn>. If the closing tag cannot be found, the script reads one
    more line to find it. Any new default chapter continues until the next
    "class=.subheading" is encountered.

    NORMAL MODE OF OPERATION: The script looks for digits (2), digit spans
    (2-4), chapt:verse (5:6), with spans or additions (, 7:8-9:10), and then
    looks backward for books of the Bible or words like "vv", "verse",
    "chapter", etc. Clear matches ("Gen. 3:15") are automatically linked
    without user input.

    User intervention is requested when matching "vv.", "chapter", etc.,
    since these usually require reading the context to determine which book
    and chapter is intended. However, if the -a switch is used,
    chapter-and-verse linking is done automatically, without prompting. If
    you use the -a switch, you should use the -b (book) and -c (chapter)
    switches as well.

    Thus, to set the default to John, chapter 10, linking chapter and verse
    references automatically, enter this:

        perl biblelink -ab John -c 10 John*.htm

    This script also links "bare references", which must be specified
    item-by-item from the console. A "bare reference" to a passage occurs
    without a book name at all. For example:

        The construction of 2:13 is significant.

    The user is prompted to link "2:13" to something. The last three lines
    of context are displayed on screen, and then the user is prompted with a
    suggestion, using the default book value:

        Should I link "2:13" as "Genesis 2:13"?

        Press  Y<ENTER>       to accept the link we suggest,
               <ENTER>        to skip it and go to the next item,
               L<ENTER>       to skip it and all other bare references
                                on this line,
               B book<ENTER>  to change the default bookname,
               C num<ENTER>   to change the default chapter,
        Or enter a substitute reference (e.g., Acts 4:12):

    Note in particular that 'b luke'<ENTER> will change the default book to
    Luke for the rest of the session. Likewise, the user may choose to skip
    this particular reference or all remaining references on the line.

    If the user enters a substitute reference ("Mark 51:99"), the title is
    checked to see if the name of the book is valid, but no further checking
    is done to confirm the validity of the chapter or verse.

    As currently configured, the script looks for references that roughly
    match this regular expression (in the code, it's far more complex):

        ([1-3] )?[A-Z][a-z]+\.? [1-9]

    but skips them if the "word pattern" isn't in its table of books of the
    Bible. For example, the string "Romns. 3:10" is not a valid abbreviation
    for the book of Romans. The script will not prompt you for a different
    spelling, and ALSO will not try to match the bare reference "3:10". As
    currently configured, the script does not recognize books of the
    Apocrypha, the Qur'an, the Book of Mormon, or other nonbiblical works.

    MASTER TRICKS: There is no easy way to save your work halfway through a
    file, quit, and resume later where you left off. Pressing Control-C will
    abort the script. Any lines processed up to that point will be saved in
    a temporary file called "filename.NEW", which you may examine if you
    wish. The original file will be unchanged. This could be construed as a
    feature, since the script halts if it finds the "javascript:bible"
    pattern in the input file, in order to prevent rematching verses that
    are already linked (unless the -m switch was used).

    Sometimes while generating links, you may notice a typo in the text. To
    flag the error without quitting, select "Enter a substitute reference."
    If the verse was James 1:5, enter "Job 99999". This will be accepted as
    valid and you will proceed to the next line of input. When finished,
    edit the file and search for "99999". This way, you have marked the spot
    and can make any corrections necessary.

BUGS
    (1) Ambiguous filenames with embedded spaces are probably supported, but
    have never been tested. You shouldn't use spaces in web filenames,
    anyway.

    (2) The -p switch often doesn't work properly. If it doesn't work well
    for you, use the -s switch instead and pipe the output through MORE /E:

        biblelink -s filename.htm | more /e

AUTHOR
    Written by Eric Pement (eric.pement@moody.edu, pemente@northpark.edu) in
    July-September 2002. Home page:
    http://www.student.northpark.edu/pemente/ This script was prepared for
    the staff of the Education Technology Services department of Moody Bible
    Institute (http://www.moody.edu). It works for us. If you decide to
    improve upon it, please let me know.

COPYRIGHT
    Copyleft (c) 2002 by Eric Pement. This program is free software and may
    be freely copied and modified under the terms of the GNU General Public
    License, version 2. Details at http://www.gnu.org/licenses/gpl.html.