|
|
|
Quran Browser Users' GuideContents
IntroductionThe Quran Browser is a World-Wide Web front end to a small, fast full-text retrieval system. The Quran Browser allows you to look up Quranic passages 1) directly, 2) by keyword, and 3) by substring, and 4) by word-pattern, i.e., regular expression. It also allows you to perform logical operations on groups of passages, to retrieve passages from several different translations, and to limit in various ways the quantity and range of material retrieved. This documentation applies only to the Quran Browser, as visible from its advanced home page. It does not apply to the basic home page, which is pretty much self-explanatory. If you haven't seen either of these home pages, take a look at them now. For general information on how the Quran Browser works, where it is housed, etc., see my brief About the Quran Browser blurb. The Quran Browser's maintenance and overall system design is handled by Brown Univesity's Scholarly Technology Group (STG), specifically by Richard Goerwitz. Looking Up Passages DirectlyTo look up a passage directly, just enter its sura/verse reference (e.g., Al-Imran 3:31, Al-Imran 31, or 3:31) into the Quran Browser's search string(s) field. Then go to the right and hit the retrieve button. If you like, you can specify more than one verse at a time. Al-Imran 3:29-30, Al-Imran 29-30, and 3:29-30 are all are fine, for example - as are references with English names (e.g., The Family of Imran 3:29-30). Stay away from English names if you can, though, because they vary so greatly, and because the Quran Browser obviously can't recognize every possible one. The system currently recognizes all of Dawood's English sura names, and most of Shakir's. I will add others if people want them (and if they don't conflict with existing ones). Since the Web is still set up primarily for ISO 8859-1, I have not attempted to transliterate Arabic sura names exactly. Rather, I have configured the system to use the Anglicized Arabic spellings similar to those given in Dawood's translation. The system is not pedantic, though. For example, you can use Aal-`Imran 31, or even something like aali-`imraan 31, to refer to Al-Imran 31. On output, though, the system will turn these references back into Al-Imran 3:31, which is the standard format I use. One easy mistake to make when formatting passage references for the Quran Browser is to insert extra spaces after commas in passage lists. A typical example of this would be for someone to write al-Kafirun 109:2-3, 6 (= al-Kafirun, verses one and two and all of sura six, al-An`am) when he or she really meant to write al-Kafirun 109:2-3,6 (al-Kafirun, verses one, two, and six). Note the absence of the extra space after the 3 in this second reference. It is okay to abbreviate sura names - but only if the abbreviations you use are not ambiguous. For example, al-Fal 113:1 is fine. But al-Fa 113:1 is not, because the first part could be al-Falaq, al-Fatiha, etc. If you're sure that you want sura 113, then don't bother writing out its name. Just type in 113:1. The sura name is redundant, anyway. If you're sure of the sura name, but not its number, then type in, say, al-Falaq 1. The system will know you mean sura 113. Note that if you type in al-Falaq alone, you'll get the entire text of that sura (just six verses). If you aren't sure about an abbreviation, or if you get an unexpected "pQuran, invalid passage reference" error, just type out the full sura name. If you are not sure what the sura names are, or if you're confused by how I've rendered them in Latin characters, then type in all as your passage reference (try this and watch what happens). Keyword or Exact String SearchesTo look up passages by keyword, i.e., to find passages containing an exact string, select exact from the consider your search type... menu on the advanced home page, then enter the keyword you are looking for into the search string(s) field. Finally, hit the retrieve button. This is the method you would use, for example, to obtain a list of every passage containing the word Adam. Keyword searches are not case sensitive, so a search for the word adam would generate the same list of passages as a search for Adam. Note that neither of these searches will turn up passages containing the word Adam's. To generate a list of passages containing Adam's as well as Adam, use a substring search. When the list of passages containing your keyword comes up, you will notice that the locations use an extended notation system: Sura-name sura-number:verse-number.word. E.g., you might see a reference to al-Baqara 2:31.4 in place of the usual al-Baqara 2:31. The extra .3 simply tells you where in al-Baqara, the Cow, verse 31 your keyword occurs (here, word number three). Substring SearchesIf you are interested in several keywords that contain a common sequence (e.g., king, as in king, kings, kingdom, etc.), select substring as your search type in the consider your search type... section of the advanced home page, then enter the common sequence (here king) into the search string(s) field. Finally, hit the retrieve button. Unfortunately, a substring search for king will also turn up words like taking and speaking, which will not always be what you want. To exclude these spurious words, consider a regular expression search. On the extended format used for verse references in passage lists generated by substring or other searches, see above. Pattern or Regular Expression SearchesIf you find that simple keyword and substring searches are too confining, try a regular expression search instead. To do a regular expression search, select regular expression as your search type, then enter a pattern into the search string(s) field. Finally, click on the retrieve button. Regular expressions are a special language for describing abstract letter sequences. Here are a few examples of how regular expressions might be used to look for groups of words that cannot easily be specified with keyword or substring searches:
Note well: The syntax of parentheses and the vertical slash vary from site to site, depending on how regular expression pattern matching is implemented in the underlying C libraries. Depending on where the Quran Browser is housed, it might be necessary to prepend "\\" to your parentheses and vertical slashes (e.g. "king\\(s\\|dom\\)"). The specific meanings of the special characters used above are:
On the extended format used for verse references in passage lists generated by regular expression or other such searches, see above. Logical OperationsSometimes even regular expressions will not be powerful enough to do what you want. Sometimes, for example, you will want to search, not just for a single string or pattern, but for verses that contain several strings or patterns, or ones that contain one string or pattern but not another. You might, for example, want to search for verses that contain both last and day (an important concept in the Quran), or ones that mention Jews but not Christians. It is for such situations that the Quran Browser provides logical and, or, and and not operators. To use them, just type as many space-separated search strings into the search string(s) field as you need to do your search. Then select either exact, substring, or regular expression as your search type. Afterwards, select and, or, or and not from the for multi-word searches... menu. The labels on the buttons there are self-explanatory. Finally, hit the retrieve button. For those who remember something about set theory from their high school math classes, logical operations can be thought of as set intersections, unions, and complements. For example, if you search for, say, fathers sons using and as your logical operation, you can think of yourself as asking for the intersection of the set of passages containing the word fathers and the set of passages containing the word sons. Logical ors can be thought of similarly, except that in this case you are asking for the union of the two sets. Logical and nots can be viewed as the union of the set of all passages containing your first search term (in the above case, fathers) and the complement of the set of all passages containing any of your remaining search terms (in the above case, just sons). See below on further logical operations for a more in-depth discussion of how logical operations are actually implemented, and of how you can take your level of control down to the point where you can specify searches like, "Give me a list of every passage where fathers occurs within two words of sons." Phrase SearchesLogical ands (on which, see above) operate, by default, on entire verses. In other words, a search for over and all will turn up verses in which both of these words occur - somewhere. But what if you want verses where they both occur, one right after the other, e.g., in the phrase, Witness over all? In this case what you want is a phrase search. To execute a phrase search, type a phrase in as your search string, and select exact as your search type. Choose phrase from the for multi-word searches... menu, and change other options according to your taste. Finally, hit the retrieve button. Up will come a list of passages where the words you typed in occur. It's just as if you had chosen and from the for multi-word searches... menu (see above), except that verses will only be displayed where the words you typed in occur one right after the other. To keep from cluttering the passage list up with superfluous references to the same verses, references are shown only for the first two words typed. That is, for blessed be Allah, e.g., everything after be (here, the name of God, Allah) will be omitted from the print-out. Try a phrase search, and you'll see what I'm talking about. Further Logical OperationsSometimes you will find that gathering the exact passages you want into a single list simply cannot be achieved in a single search operation, however complex. Suppose, for example, that you want a list of every verse where man occurs within four words of woman. If the exact range did not matter, i.e., if all you wanted was a list of verses where both of these words occurred, you could simply type in man woman (separated by a space) as your search string, select and from the multi-word searches menu, then hit the retrieve button. To narrow the list down to places where man occurs within four words of woman, however, you need finer control over both the units (words vs. verses) and the ranges (4 words vs. 0 verses) than the Quran Browser's standard search options provide. In fact, this finer level of control is available. But to access it, you must first understand how co-occurrence searches like these are implemented by the Quran Browser. When you do a straight search for, say, all verses where the words man and woman both occur, what the Quran Browser does is take the intersection of two sets, namely the set of all verses where man occurs, and the set of all verses where woman occurs. The intersection of these two sets is the set of all verses where both man and woman occur. Put in logical terms, what the Quran Browser does in this case is and together each member of the one set with each member of the other, keeping those instances for which the and operation's result is true. (A logical or, by way of contrast, would yield a set union, that is, a list of all verses containing either man or woman - which would be much larger.) If you are interested in words, rather than verses, however - and if you are interested in specifying a range like four words before or after - you must go through the above steps manually, indicating an explicit unit (e.g., a word) and range (e.g., from 4 units before to 4 units after). To do this for woman and man, first do a search for woman. Then, when the passage list comes up on your screen, go to the end of that list and select further logical operations from the menu there. This will get you to another search screen where you can specify
Leave the default operation (and) alone. But change the unit to word, and make the range 4 preceding, 4 following. Then enter man as your search string, and hit the retrieve button. The result will be a list of passages where woman occurs anwhere from four words before to four words after man! The reason the Quran Browser implements further logical operations this way is to allow you to stack as many searches as you like, using whatever units and ranges you need. It also enables you to modify and refine passage lists on the fly, deciding at each step along the way whether, and if so, how, you want to proceed. By the way, there is no reason you can't switch versions in midstream. In fact, doing so lets you do interesting things like find all the verses in Shakir that mention struggle and correspond to verses in Pickthall containing the word strive. I will leave it as one of those proverbial "exercizes for the reader" to figure out exactly how to do this. Note, though, that when you join passage lists from different versions (as you would need to do in this instance), some of the extended passage references will be wrong. Why? Because if, say, struggle is the last word in a verse in Shakir, and the corresponding verse in Pickthall has fewer words, then if you try to look at the passage in Pickthall using Shakir's passage reference you'll get an error message - because, of course, the Shakir reference points to a word that has no correspondent in Pickthall. Raw pQuran CommandsAnother way to search the database, far more flexible and powerful than anything discussed above, is to send raw commands to the Quran Browser's underlying full-text retrieval system, i.e., to the so-called daemon that does the actual work when you execute a search. This daemon, called pQuran, is normally hidden from you. By setting your search type to raw, however, you can talk directly to it. Talking directly to the pQuran daemon requires that you use a special retrieval language that is beyond the scope of this guide. If, after having mastered the rest of the Quran Browser interface, you find that there are still things you want to do but can't, then this special language is what you should learn. See the pQuran Command Language Guide for more discussion. TranslationsThe particular versions used in the Quran Browser's database have been chosen for three reasons: 1) they are freely available, 2) they are easy to convert into the Quran Browser's native format, 3) they are public domain or free for noncommercial use, and 4) they utilize Latin script, and therefore can be displayed by any Web browser. Some users may miss having the Arabic online. To display Arabic would, unfortunately, push me beyond the capabilities of generic Web browsers - which still officially support only the ISO 8859-1 character encoding standard. For the present, then, I will stick primarily with English versions. Note that when you first call up the Quran Browser home page, all passage, keyword, and regular expression retrievals operate on one particular version - the default. To change this default, just select the version you would like to use in its place from the retrieve from which translation menu. After this, passage, keyword, and regular expression retrievals done from that Quran Browser home page will operate on the new default version. Limiting the Size of Passage ListsSearches for keywords, patterns, etc. can often turn up a lot of material. For example, a substring search for believe in Pickthall's translation will turn up 1133 passages. In general, you will not be examining more than a few passages at a time. So the Quran Browser automatically cuts passage lists down to a manageable number of "hits" - by default 50. You can adjust this limit downward to as few as 10 and upward to as many as 5000 through the don't let passage lists exceed... option on the advanced home page. You can also adjust the amount of context that gets displayed with individual words and verses. By default if you fetch, for example, al-Baqara 2:3, al-Baqara 2:3 will be displayed all by itself (along with a list of further menu options). You can, however, arrange to have the passages on either side of it displayed as well. Just go down to the other options menu, and pick the "additional context" option. Note that, when searching for keywords, patterns, etc., asking for additional context causes the Quran Browser to display the entire verse in which the keyword or pattern occurs and to highlight the appropriate word. However you retrieve them, once your passage(s) are on screen, you can select one of the further menu options that appear beneath the text of those passage(s). These options will vary, depending on how many passages you retrieve, what your maxhits setting is, and so on. Possible options include:
From-To RangesAnother way to limit the size of passage lists is to restrict search results to a specific range within the corpus. By default, search results cover the whole corpus. This will often turn up more material than you are interested in. If, say, you are only looking at the first five suras, you can just enter al-Fatiha (sura 1) and al-Ma'ida (sura 5) into the from and to fields down in the search only from... section of the Quran Browser home page. Numbers are also okay. That is, you can enter 1 and 5 in place of the full sura names. You can even use full sura-verse references, such as 2:1 and 2:256 - which would confine searches to al-Baqara 2:1-256. Sura OrderSuras are ordered as in traditional Qurans - not, e.g., as in the earlier Dawood editions, which ordered things in a way that was supposed to be more useful to unitiated readers. For a list of sura names, both in English and Arabic, see the supplemental documentation on this subject. Richard L. Goerwitz Richard_Goerwitz@Brown.EDU |