Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/3/3586

Text File | 1991-07-02 | 20KB | 466 lines

Newsgroups: alt.sources
From: [e-mail] (Richard L. Goerwitz)
Subject: kjv browser, part 10 of 11
Message-ID: <[e-mail]>
Date: Wed, 3 Jul 1991 06:53:17 GMT

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is bibleref.10 (part 10 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file README continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 10; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping README'
else
echo 'x - continuing file README'
sed 's/^X//' << 'SHAR_EOF' >> 'README' &&
X
X
XProgram:   Bibleref
XLanguage:  Icon
XPurpose:   Perform word and passage-based retrievals on the King
X       James Bible
X
X
X--------
X
X
XOverview:
X
X    This package, Bibleref, offers simple tools for word and
Xpassage-based access to the King James Bible on UNIX platforms.
XBibleref is fast, and easy to install (assuming you possess a King
XJames Bible text).  It will also run with stock terminals - even nasty
Xold ones that leave magic cookies on your screen.  Bibleref will,
Xhowever, put a significant dent in your mass storage resources.  Along
Xwith the 4-5 megabytes of King James Bible text, you'll need to house
Xsome 2 megabytes of indices, and also the 150k icode file (more if you
Xcompile, rather than interpret).  In brief:  Bibleref has a large
Xappetite for memory.  Once set up, though, it can operate with fairly
Xminimal impact on the CPU.
X    With Bibleref, you can perform most of the more basic,
Xlow-level functions commercial Bible browsing packages offer (and
Xperhaps a few not found in some of the commercial packages).  You can,
Xfor example,
X
X    -  retrieve any passage in the Bible instantaneously
X    -  move forward or backward relative to the retrieved passage
X    -  search the entire Bible for words and/or word-patterns
X    -  search for word co-occurrences (or the absence thereof)
X    -  save passages and/or passage-lists for use with an editor
X
XAlthough this program is hardly the product of any major research
Xeffort :-), it should prove sophisticated enough for quick lookup of
Xpassages whose precise location you have forgotten, for research on
Xsermons and Bible study classes, and for general topical perusal of
Xthe biblical text.
X
X
X--------
X
X
XInstallation:
X
X    To install Bibleref, you'll need to get a hold of the King
XJames Bible text as packaged in the PC-SIG disk set (19 discs), which
Xis available from wsmr-simtel20.army.mil.  I happen to have gotten my
Xtext (very similar to the PC-SIG version) from helens.stanford.edu
X(36.0.2.99; kjv.tar.Z).  This one works as well.  There are a number
Xof KJV texts floating around which are derivative of the PC-SIG disk
Xset.  Only ones which have not been edited too severely, though, will
Xwork with the bibleref installation programs.
X    Once you've gotten a hold of a King James Bible text, locate
Xthe Makefile.dist file included with this package and read it.  If you
Xfind you must modify any of the user-configurable sections, then copy
Xit to Makefile, and edit it as you see fit.  Pay special attention to
Xthe DESTDIR and LIBDIR targets.  Also, be sure to change USER and
XGROUP targets to an appropriate value for your machine (in most cases
Xroot or bin; if the executables will be private, then use your login
XID and default group ID).  Finally, check to be certain that the
Xcorrect names are used for your raw King James Bible file(s), and that
Xthe target CAT is set to either "cat" or "zcat," depending on whether
Xyou have compressed the raw files or not.
X    Assuming you've modified the Makefile correctly, you can then
Xsimply type "make."  After this, you might as well go off and have
Xdinner or something.  Better yet, go to bed.  The entire reformatting,
Xcollating, and indexing process takes as many as a three or four hours
Xon a medium-range workstation.  Don't even *think* of indexing on a
Xsystem with less than 8 meg of core memory and a lot of swap space.
XThe main setup program may, for a brief while, swallow up as much as
X15 megabytes of your precious RAM.
X    Once you've gotten past the indexing "hump" (which I might
Xsmooth out some time, if I have a few days free), you can now install.
XSu root first, if you plan on making the executables public, then
X"make install."
X    Please note that Bibleref assumes the existence on your
Xsystem, not only of Icon interpreter or compiler, but also of an
Xup-to-date Icon Program Library.  There are several routines included
Xin the IPL which Bibleref uses.  Any IPL material that I've written
Xmyself has been packed with Bibleref, by the way.  I'm constantly
Xtweaking these programs, and I just want to be sure everyone has the
Xlatest version.  Programs written by other people, though, I have not
Xbuilt into the Bibleref distribution.  If you don't have them, ftp
Xthem from cs.arizona.edu along with the full Icon distribution, and
Xget the updates as well (~ftp/icon/library).  If all else fails, write
Xto me and I'll package them up for you.  In general, the best solution
Xis simply to keep your Icon run-time and support systems fully
Xup-to-date.
X
X
X--------
X
X
XRunning Bibleref:
X
X    There is precious little in the way of documentation on
Xrunning Bibleref.  This is it.  I wrote the program as a test wrapper
Xto put around some software I'm using for personal research purposes.
XThe package has been tried out here at home by my wife and 5 year-old.
XThe 5 year-old likes to break programs I write.  He's seen to it that
Xthe visual interface has had most of the bugs worked out :-).  I've
Xchecked its retrieval facilities against Young's and Strong's
Xconcordances, and they seem to work fine.  Other functions have been
Xtested using similar heuristics.  I have no fantasies that all the
Xbugs have been worked out.
X    When it is first invoked, Bibleref will print a little message
Xabout initializing one or another of its auxiliary files.  After a few
Xseconds, this message will disappear - replaced by a prompt which asks
Xfor a passage reference or "f" (to find a word or word-pattern).
X    If you are interested in looking at a specific passage in the
XBible, type it in.  Just about anything is okay.  Genesis 1:1 can be
Xviewed, for instance, by typing:
X
X    Genesis 1:1
X    Ge 1,1
X    gen 1 1
X    etc.
X
Xlikewise, you can look at the Song of Solomon, by using any one of
Xseveral standard abbreviations or names:
X
X    Solomon 1:1
X    Canticles 1:1
X    cant 1,1
X    etc.
X
XI've tried to make things as flexible as possible, so as to avoid any
Xcumbersome input restrictions which make using a browser a chore
Xrather than a pleasure.
X    If it is a word or word-pattern you want to look for, then
Xtype "f" and press return.  Just about every command in Bibleref
Xconsists of a single letter.  It's simple and consistent, and lets me
Xkeep the terminal in its normal mode.  If at any time you must type in
Xadditional input, Bibleref will ask you for that input.  The "f"
X(find) command is just such a case.
X    After you press f+return, Bibleref will ask you to input a
Xword.  This "word" can be a simple string.  It can also be an
Xegrep-style pattern:
X
X    love|charity
X    faith
X    hope
X    kind.*
X    etc.
X
XNote that the pattern you specify must match words in their entirety.
XFor instance
X
X    help
X
Xwill only match "help."  That is, it will cause Bibleref to retrieve
Xonly those passages which contain the word help.  To catch "helper"
Xtoo, you need to input a regular expression which will match this
Xstring in full as well (e.g. "help.*").
X    When you are done typing in a word or word-pattern, Bibleref
Xwill ask you if you are done.  If you are, then press the appropriate
Xkey, then hit a carriage return.  In less than a second, you should
Xsee a list of passages which contain the word or pattern which you
Xspecified (if in fact any such passages were found).  Along with this
Xlist comes a new set of options, including ! (escape to a shell), a
X(append the current list to a file), b (back up), c (clear and redraw
Xscreen), m (view next screen), and several others.  Try the various
Xoptions out and see what they do.  In particular, try out the "v"
Xcommand, which lets you view any of the passages in the list.  After
Xhitting "v" you are prompted for a passage number.  If you enter one,
Xthen hit return, you will see a printout of that passage in full, just
Xas if you had entered its book chapter:verse reference at the main
Xprompt.
X    While viewing a passage here, or from the main prompt, you may
Xmove to the next passage in the text (+) or to the previous one (-).
XYou may also either write (w) or append (a) it to a file.  Again, try
Xout the various options.  When you are done, type "q" and press
Xreturn.  You will be brought back to the previous menu, where you can
X*v*iew another passage, or quit back to the main menu.
X    At the main menu, you can invoke several additional functions
Xbeyond retrieving specific passages or passage lists.  Bibleref keeps
Xa resume of all passage lists you have retrieved, storing this resume
Xin a globally accessible structure.  You can look at this structure by
Xtyping "l" (for "list") at the main menu prompt.  From the resulting
Xdisplay menu, you can then *v*iew any of your previous passage lists
X(i.e. "hit lists" resulting from invocation of the *f*ind function).
XWhen you are done, you can once again press "q"+return, and go back to
Xthe main command loop.
X    The final function which Bibleref offers is geared for manual
Xdisplay of passage lists.  As noted above, all your passage lists are
Xall kept in memory, and you can view the list of available ones by
Xtyping "l" at the main prompt.  If this seems too cumbersome, though,
Xyou can simply type "d" and return.  Bibleref will retrieve and
X*d*isplay the last passage list you created.
X
X
X--------
X
X
XAdditional Notes:
X
X    As noted above, this package is just a wrapper around a more
Xgeneral set of indexing and retrieval utilities I'm using for personal
Xresearch.  These utilities are set up so that they can actually be
Xused with just about any text broken up - like the King James Bible -
Xinto hierarchically arranged divisions.  If, for instance, you don't
Xlike Renaissance English, and have a more modern translation online,
Xyou can certainly use that instead.  All you'll need to do is copy the
Xkjv2rtv.icn file to, say, kjv2rsv.icn, edit it to reflect the text you
Xare using, run it on your text, and then index it as you would have
Xdone for the King James text.  You can tell Bibleref to use this text
Xinstead of the King James text either by modifying bibleref.icn to
Xpoint to the new file, or by giving it a filename argument, a la
X"bibleref -f your.indexed.bible.text."
X    If you need help integrating a new biblical text into the
Xretrieve package, drop me a line.  If I'm not busy, and the job looks
Xto be one I can help you out with, I'll be glad to do so.
X
X
X--------
X
X
XProblems:
X
X    Doubtless you will find problems, options not discussed in the
Xdocumentation, and just general indications that this program was
Xwritten late at night one week after I was done all my serious work
Xfor the day.  If - no, when - this happens, I encourage you to drop me
Xa line.  I'd like to know about any flaws you run into, especially
Xmajor systemic ones.
X    I really hope that the bugs will not prove too annoying, and
Xthat the package will prove generally useful to you the user, and, if
Xyou place it in a public directory, to anyone else who might happen to
Xtry it out.
X
X
X   -Richard L. Goerwitz              [e-mail]
X   [e-mail]         rutgers!oddjob!gide!sophist!goer
SHAR_EOF
echo 'File README is complete' &&
true || echo 'restore of README failed'
rm -f _shar_wnt_.tmp
fi
# ============= README.rtv ==============
if test -f 'README.rtv' -a X"$1" != X"-c"; then
    echo 'x - skipping README.rtv (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting README.rtv (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'README.rtv' &&
X--------
X
X
XName: retrieve
XLanguage: Icon
XContents: tools for word-based, indexed access to text files
XRequires: up-to-date Icon Program Library, up-to-date iconc/icont, UNIX
X
X
X--------
X
X
XOverview:
X
X    Scholars have traditionally split so-called "Classics," the
XQuran, the Bible, and generally any closely studied literary or
Xreligious text, into hierarchically arranged divisions (in the case of
Xthe Bible, these are books, chapters, and verses).  Such divisions
Xdrastically simplify the process of citation and reference.
XFortunately for those of us who need electronic access to these files,
Xthis hierarchical system of divisions permits easy representation
Xusing bit-fields, i.e. fixed-width series' of binary digits.  Such
Xrepresentations are compact, and allow the programmer to implement
Xhigh-level boolean operations and range-based searches using simple
Xshifts, additions, and subtractions.
X    The package in which this README file comes - "retrieve" -
Xoffers a naive, but generalized and fairly high-level tool for
Xindexing texts which are divided up in the manner just described, and
Xfor performing word-based searches on them.  These word-based searches
Xoffer wildcard-based access to word patterns (e.g. "give me every
Xpassage containing a word with the letters 'NIX'").  The search
Xfacilities also permit boolean and range-based specifications (e.g.
X"give me every instance of word X occurring within eleven sections of
Xthe word Y").  One can also access passages by both absolute (e.g.
X"give me book 1, chapter 3, verse 4"), and relative, location (e.g.
X"give me the passage occurring before/after the one I just looked
Xat").
X    Retrieve does no compression of any kind, and is written
Xentirely in Icon.  As a result it is something of a disk hog, and
Xtakes a long time to index files.  Surprisingly, though, once set up,
Xfiles incorporated into the retrieve package can be accessed quite
Xrapidly.  After a brief initialization process (takes 2-4 seconds on a
XSun4), absolute locations can be retrieved with no perceptible delay.
XThe same is true of relative locations (again, after a lag on first
Xinvocation).  Regular expression based searches appear instantaneous
Xon a fast machine (there is a just perceptible delay on a Sun4 for a
Xfour megabyte indexed file, five to ten seconds on a Xenix/386 box
Xwith a relatively slow disk).  Boolean and range-based searches take
Xthe longest, varying widely according to their complexity and the
Xnumber of "hits."
X
X
X--------
X
X
XInstallation:
X
X    Retrieve is really not a program as such.  It is a set of
Xtools for indexing, and accessing indexed, files.  Installation
Xconsists of four basic steps:
X
X    1) creating an indexable file
X    2) indexing that file
X    3) writing a program using the retrieve interface
X    4) compiling and running what you wrote in (3)
X
XThese steps are discussed in detail in the following sections.
X
X
X--------
X
X
XStep 1:  Creating an Indexable File
X
X    The format for indexable files must conform to a simple, but
Xstrict, set of guidelines.  Basically, they must interleave series' of
Xlocation designators (internally represented by so-called "bitmaps")
Xwith actual text:
X
X    ::001:001:001
X    This is text.
X    ::001:001:002
X    This is more text.
X
XThe initial :: (double colon) delimits lines containing the location
Xdesignators.  These designators translate into integers dividable
Xinternally into (in this case) three bit-fields of length 10 (enough
Xto handle 999:999:999), which serve as a location markers for the text
Xthat goes with them.  Note that the translation process is invisible.
XAll you need to do is make sure,
X
X    a) that the location designators are correctly paired with
X       blocks of text, and
X    b) that the fields are numbered consistently, beginning with
X       the same low value (usually 1 or 0), and continuing in
X       ascending order until they roll over again to their low
X       value
X
X    Rather than speak merely in the abstract about the format, let
Xme offer a simple illustration taken from the King James Bible.  The
Xfirst verse in the Bible is Genesis chapter 1 verse 1.  This passage
Xmight be designated 1:1:1.  Verses in Genesis chapter 1 would continue
Xin ascending order to verse 31 (1:1:31), after which chapter 2 would
Xbegin (i.e. 1:2:1).  The resulting text would look like:
X
X    ::1:1:1
X    In the beginning God created the heaven and the earth.
X    ::1:1:2
X    And the earth was without form, and void; and darkness was
X    upon the face of the deep. And the Spirit of God moved upon
X    the face of the waters.
X    ::1:1:3
X    And God said, Let there be light: and there was light.
X    ::1:1:4
X    And God saw the light, that it was good: and God divided the
X    light from the darkness.
X    ::1:1:5
X    And God called the light Day, and the darkness he called
X    Night. And the evening and the morning were the first day.
X
X    ...
X
X    ::1:2:1
X    Thus the heavens and the earth were finished, and all the host
X    of them.
X
XAlthough you can use any number of fields you want or need, and can
Xuse any nonnumeric separator (e.g. 01-01-01-05-03), lines containing
Xlocation designators *must* begin with "::," and must be ordered
Xsequentially throughout the input file, paired with the correct text
Xblock in each instance.
X
X
X--------
X
X
XStep 2:  Indexing the File
X
X    Indexing the file created in step (1) entails compiling and
Xinvoking a program called "makeind."  The compilation end of this
Xprocess would typically be achieved by typing:
X
X    icont -o makeind makeind.icn gettokens.icn indexutl.icn
X
XOne of the files listed just above, gettokens.icn, is of particular
Xinterest.  It contains the tokenizing routine to be used in creating
Xthe main word index.  Should this routine prove unsatisfactory for one
Xreason or another you are free to replace it with something more to
Xyour liking.  Just comment out the old gettokens() routine, and insert
Xthe new one in its place.  Then recompile.
X    Once you have compiled makeind, you must invoke it for the
Xtext file you created in step (1).  Invoking makeind involves
Xspecifying a file to be indexed, the number of fields in location
Xmarkers for that file, and the maximum value for fields.  If you plan
Xon invoking passages by relative location, you must also use the -l
Xoption, which tells makeind to build a .LIM file, which records the
Xhigh values for a specific field throughout the file being indexed.
XLet us say you have examined Genesis 1:31 in the Bible, and want to
Xlook at the next verse.  The only easy way the procedure that handles
Xthis particular chore can know the maximum verse value for Genesis
Xchapter 1 (31) is to store this maximum value in a file.  By supplying
Xmakeind with an -l argument, you are telling it to create a file to
Xstore such values.
X    Just for illustration's sake, let us suppose you want to index
Xthe King James Version (KJV).  How might you invoke makeind to
Xaccomplish this?  First you would need to determine the maximum field
Xvalue for your text.  In the case of the Christian English Bible, this
Xis 176.  The English Bible (including Apocrypha) contains 73 books.
XThe Protestant KJV contains 66.  The maximum number of chapters in any
Xbook is 150 (Psalms).  The maximum number of verses in any one chapter
Xin any one book is 176 (Psalm 119).  176 would therefore be the
Xmaximum value any field would have to contain.  You would pass this
Xinformation to makeind via the -m option.  The total number of fields
Xis three, naturally (book, chapter, and verse).  This value would be
Xpassed using the -n option.  As noted above, in order to use relative
Xlocations you would need to tell makeind what field to record max
SHAR_EOF
true || echo 'restore of README.rtv failed'
fi
echo 'End of  part 10'
echo 'File README.rtv is continued in part 11'
echo 11 > _shar_seq_.tmp
exit 0
--

   -Richard L. Goerwitz              [e-mail]
   [e-mail]         rutgers!oddjob!gide!sophist!goer