bibsearch FAQ

Installation | Usage

Basic Syntax

(normally, using bash script): bibsearch "command"
(using Perl program directly): bibsearch.pl -e "command"

Frequently Asked Question

What is bibsearch?
bibsearch is a simple command-line utility for searching the entirety of the Catholic Bible (that is, the normal Protestant Bible, plus what Catholics call the deuterocanonical, and Protestants the Apocryphal, books, such as Macchabees).
Isn't there already the kjv-bible program? Why this one?
There is already the kjv-bible program, and it's a well-written utility. But from the Catholic perspective, it's lacking in some ways.
- It doesn't contain the deuterocanonical books, and thus is missing several important books which have been considered canonical since long before the Nicene Council in 325.
- While it is, in principle, expandible to any given text, it's currently limited only to the English translation of the Bible comissioned by King James in the seventeenth century. This translation is sometimes problematic.
- It does not contain built-in support of any kind (that the current author could discover, anyway) for multiple languages.
So I decided that I ought to come up with something which addressed these issues.
So how does bibsearch address these issues?
bibsearch addresses these issues in the following ways:
- It contains the entirety of the canon of Scriptures, including the deuterocanonical books (though, by applying a different extension to the text (like "kjv"), it could easily be used for English-only versions like the King James).
- It uses different extensions on the text files to be searched to identify different translations of the Scriptures. So while the most obvious English-language extension ("eng") is taken by the Douay-Rheims version, different extensions could easily be applied, with trivial changes to the source, to make different translations easily searchable. (Though the Douay-Rheims is arguably the best existing English translation anyway.)
- The extension system also provides easy, built-in support for multilingual searching. E.g., right now there are two languages available, English and Latin. The English version is the Douay-Rheims, with extension "eng," and the Latin version is the Clementine Vulgate, with extension "lat." If a French translation were made available in appropriately formatted text files (the formatting is easily generated; each verse must simply be on its own line, beginning with its chapter and verse separated by a colon, something easily whipped together and applied by a script in any number of languages), only one function in the source need be changed to add "fr" to the list of permissible extensions (added in the -l declarations of the search queries) and that language is fully searchable and available to bibsearch.
So I think that these issues with kjv-bible are amply addressed by bibsearch.
What are some of the features of bibsearch?
The features of bibsearch are extensive:
- Easily grab any given verse, or range of verses within a chapter, or even range of chapters, with a short query (e.g., "g Gn1:1-10").
- Easily search for any sequence of letters or numbers, with the full and unadulterated power of regular expressions.
- Apply search queries to individual books; to series of books (e.g., the Books of Moses, the Epistles of Paul, the Gospels, etc.); to testaments; or to the entirety of the Bible, simply by changing a single query term.
- Saved the contents of any search to a buffer, which may be arbitrarily named.
- Apply searches to any buffer easily, searching them in the same way that any book or group of books is searched.
- Print the contents of any buffer.
- Easily obtain a list of all available buffers.
- Automatically deletes all buffers upon exit, except when those buffers are explicitly saved by the user, thus cleaning up after itself with some efficiency.
- Easily save any desired buffer for later reading, whether within or outside of bibsearch.
And things are only going to get better from here.
Where's the documentation for bibsearch?
Well, at the moment, this FAQ represents the best documentation. However, there is a man page included in the "man" directory, as well as a (outdated) copy of this FAQ. To read the man page, simply go to the man directory and type "man ./bibsearch.1". Alternatively, you can move it into your manpage directory, and then you'd get it simply by typing "man bibsearch." However, I'd advise waiting until version 1.0 for that. Features are still being added too quickly. Also, in session, you can type "h" and get a help screen, though the man page and this FAQ will be more helpful, ironically enough. Finally, typing "l" in session will give you a list of the book abbreviations (which are standard Vulgate abbreviations), if you can't remember them, plus a list of the groups you can search. This documentation should be sufficient; I hope to provide a sort of "user's manual" in the near future, as well.
What is the license for bibsearch?
bibsearch is released under the GNU General Public License, version 3. A copy of that license can easily be obtained from http://www.gnu.org/licenses/gpl-3.0.txt.
Does that mean that I can copy it and distribute it for free?
The short answer: yes, as long as you don't prevent others from doing the same. Read the license for a complete statement of your rights under it.
Why the GPL?
It's a complicated matter involving the nature of common as opposed to particular goods. Visit Goretti Publications's Publishing Philosophy page for a bit of decent, though because of its brevity necessarily inadequate, explanation.
Gah! Why is the source so hideous?
I know; it is pretty kludgey. Unnecessary variables, oversized functions, and so on. This is primarily due to two things: first, my own lack of programming ability, and second, the nature of the program in question. It doesn't do a lot of bouncing back and forth; it basically gives a prompt, takes the input, runs it through the program, then goes back tot he prompt and waits again. It's not complex enough to require careful data management, localized variables, and so on, though naturally that would make it better and faster. I hope to do this soon; right now, though, I was more concerned with just making it work, even if it is a bit of a kludge. One should note that, though the source is rather ugly, it's linearly and logically laid out, and the program runs more or less flawlessly.
Where did you get the texts?
The texts are owed entirely to the efforts of the author of the Vulsearch project, who has painstakingly prepared the texts from paper sources. The Vulgate text in particular is relatively inerrant; it has been read through in toto at least twice. Generously, this author released his excellent work into the public domain, allowing me to adopt it for bibsearch. I've made no alterations, except that I converted the Microsoft codepage 1252 encoded texts into UTF-8 with iconv.
How do I install bibsearch?
It should be pretty simple.
- Select the directory you want it installed in. This will depend on your system. If you're setting it up only for your personal use, and no other users will be touching it, just put it in a subdirectory of your home directory. If you're setting it up for all the users on your system, you probably want it in a more public place. I'd suggest /usr/share somewhere, but that's your decision.
- Copy the tarball (bibsearch-0.9.tar.gz) to your chosen directory.
- Unzip it and extract it (something like "tar -xzvvf bibsearch-1.0.tar.gz", sans quotation marks, should do the trick).
- Alter the "bibsearch" bash script to make $BIBPATH point to the directory in which you've installed bibsearch.
- Alter the path of the first line of bibsearch.pl if necessary to point to your Perl executable. Normally this is /usr/bin/perl or something similar.
- Copy the "bibsearch" script into some directory that's in your users' paths. Probably /bin or /usr/bin, or /usr/share/bin, or something/bin will do nicely.
- Make sure that the permissions on both the "bibsearch" bash script and bibsearch.pl are such to allow you to run the program. If you have to, chmod it to make it executable. "chmod +x bibsearch.pl", sans quotations marks, should do the trick.
- Run it and test things out; make sure that buffers are written properly and saved properly, and properly deleted at the end of a run in particular. If they're not, there's probably something wrong with the permissions on the directory bibsearch is trying to write to. I'm not sure what this might be, since bibsearch only writes to the /tmp directory (which is normally world writable) and the user's home directory. However, you may have to go into bibsearch.pl, the source, to fix this if you're not able to change your permissions appropriately.
- You should be up and running. May St. Jerome guide you in your study of the Scriptures.
If you have trouble, consult your system administrator. You may also consult the author of this program if that doesn't work, or if you are your system administrator and can't figure it out. I do reserve the right not to know how to fix it, though I'll do my best. My email can be found on the man page.
Why did you write it in Perl? Isn't C the UNIX language?
Well, yes, C is the UNIX language. And I did start it in C. But I stopped and rewrote it in Perl for a couple of reasons. First, I'm much more fluent in Perl than in C, and that made it much easier going. Second, Perl was built for processing text and producing reports in this way; C wasn't. The corresponding C program would have been much longer and more complicated---and this Perl program is far from streamlined, I can promise you. If you want to port it to C, be my guest; it would probably be a much faster program for it. Please send me a copy of the source, if you don't mind. But I didn't think it worth my own efforts.
What is the standard syntax for a command?
The standard syntax for a query comes in two parts:
1. The command. This is generally single-letter (though it can be more; that is, "print" and "p" are identical as far as the program is concerned) and it must come first in the query. Otherwise, bibsearch will gag on your query and tell you that it doesn't recognize the command. It does this because you didn't give it a proper command. See the man page for available commands; they basically come down to:
  - g --- get a citation; this retrieves whatever cite you ask it for.
  - ? --- search a database. You must tell bibsearch which database you want and, if it's not Latin, what language you want.
  - l --- list the available databases.
  - h --- prints a simple help message. Really, you're better off coming here; the help message is minimal. I hope to fix this in later versions.
  - p --- prints the contents of the buffer named after it. As always (except in the initial filling of the buffer), the buffer name must be preceded by an underscore (as in "_bufname").
  - b --- prints a list of available buffers.
  - w --- writes the buffer; prevents bibsearch from deleting the buffer when it closes.
2. The language flag. This may be omitted if you're searching a Latin database, as Latin is the default. Simply put in a "-l" followed by the identifer for the language you want. Currently supported are "l" (Latin) and "e" (English). Either "-le" or "-l e" are equally acceptable. This may go anywhere in your query except first.
3. The quantity flag. When searching (when your command is "?"), do you want just the citation (book name, chapter, and verse), or do you want the entire verse text as well? If the former, do nothing; that's the default. If the latter, stick a "-f" in there. This may go anywhere in the query except first.
4. The directory flag. When writing a temporary buffer to a permanent file with "w", you can write the buffer to any directory; simply list the path to the desired directory after a "-d", as in, "-d /home/username/bible". You may include or omit the trailing slash; you must, however, include the first slash, or bibsearch won't know what you're telling it and will therefore protest. If you omit the "-d" flag entirely, bibsearch will simply save to your home directory.
5. The database flag. If your command is "?" (in a search), you need to tell bibsearch what you want it to search. Enter the "l" command for a list of available databases to search. This can be entered with or without a space; that is, both "-dpaul" and "-d paul" search the Epistles of St. Paul.
6. The search term. This is delimited on either side by forward slashes ("/"). The full range of regular expressions is available to you within those slashes. So, for example, "/velam.n/" will match any word with those letters, with the "." being replaced by any character (e.g., it will match both "velamen" and "velaminis"). You can also search the contents of a buffer, but you must first inform bibsearch that you are doing so by prefixing the name of the buffer with an underscore character ("_"). As in, "-d _bufname".
7. Assignment to a buffer. This is done in the normal bash format, with a greater-than sign (">"). At the end of your query (both search and get queries can be saved to a buffer), simply type ">" plus the name you wish to give to the buffer. E.g., "> bufname". This will not only print your results to screen (the extent of which is determined by the presence or absence of the "-f" flag, in a "?" query), but will also print, as if there is an "-f" flag, to a file with your buffer name, and inform you of the name of the buffer and the name of the file containing the contents of that buffer (this will be slightly different from your buffer name, as it will contain a language suffix for its extension, such as ".lat" or ".eng"). You can also append to a buffer with ">>", just like in the shell. Assigning contents to a buffer in this way is the only time the buffer name does not need to contain an underscore ("_") prefix.
With this simple instruction sheet, you can take full advantage of the searching and citation power of bibsearch.