--------------------------------------------------------------------------- THE TRADITIONAL BALLAD INDEX SOFTWARE ReadMe for WINDOWS --------------------------------------------------------------------------- (Updated July 11, 2007) These are all the instructions you're gonna get :-), so reading them is strongly suggested. This is particularly so because the Ballad Index software is a cross-platform application (for PC, Macintosh, and UNIX), and has no PC-specific features. The Ballad Index software was written by Bob Waltz, waltzmn@yahoo.com (who is also responsible for the Macintosh version) with a lot (and I mean a lot) of help from Don Nichols (it wouldn't have been possible without his help, and he also supplied the UNIX features). The PC version is a direct port to Windows of the unix application, managed by Ben Schwartz, and runs under a Linux-like emulator. The program is compiled with the Cygwin gcc compiler and the load module includes Cygwin routines. The Ballad Index software is free, but is protected by the GNU Public License. (See Appendix III.) ------------------- SYSTEM REQUIREMENTS ------------------- To run the Ballad Index software, you will need at least the following: * An IBM PC-compatible computer with an 80386 or higher processor. * RAM: bi.exe currently runs in 2.2Mb memory * Minimum free hard disk space for Ballad Index and Cygwin software .2Mb bi.exe 13.0Mb Ballad Index data files 64.0Mb Cygwin 13.0Mb temporary during Cygwin installation 1.8Mb local copy of cygwin1.dll (optional) ------ 86.0Mb ] * Cygwin currently runs in Microsoft Windows 95 and all later versions. (The Index software has not been tested with versions older than XP) -------------- REQUIRED FILES -------------- To install and use the Traditional Ballad Index, you should have received or downloaded the following files: * This instructions file, READMEPC.TXT * The Ballad Index text database, BALLDIDX.TXT * The Ballad Index keywords file, KEYWORDS.TXT * The Ballad Index software, shipped as BI.EXE though you may give it another name if you wish. * The Ballad Index supplement file, supptrad.txt, to allow looking up some song texts (the Index will function without this file, but some features will be disabled). * If you wish to use the Ballad Index internal help, you will also need the help file BDIDXHLP.HLP. (Use of this file is strongly recommended, as it contains descriptions of some features not found in this ReadMe, along with the latest bug reports). All of these files except BALLDIDX.TXT and supptrad.txt should be in a single compressed package. BALLDIDX.TXT and supptrad.txt are packaged separately, as they will be updated independently of the Ballad Index software. If you are missing any of these pieces, you may download them, or check for updated versions, at our web site, http://www.balladindex.org/BalladIndexTOC.html All of these files have been compressed using the ZIP algorithm. You will need a "unzipper," such as PKUNZIP, to decompress the software. If you want more information about the Index than is found in this ReadMe file or in the internal help, see the HTML help files on the Ballad Index web site. ------------------------- INSTALLATION INSTRUCTIONS ------------------------- Start by downloading and unstuffing all the files listed above. Once you have these files, you are ready to install the Index software. To install the Ballad Index, create a directory for the files ("BALLDIDX" or "Ballad_Index" would be good names; do not use directory names with embedded blanks). In this directory, place the relevant files: BI.EXE, BALLDIDX.TXT, KEYWORDS.TXT, and (if desired) supptrad.txt and BDIDXHLP.HLP. Once you have installed the files in the directory (note that they MUST all be in THE SAME directory), you need only run the Index if * Cygwin is already installed on your system and * cygwin1.dll is in a directory in your System or User PATH. ------------------------- CYGWIN INSTALLATION ------------------------- Skip this section of Cygwin is already installed. Currently the PC version of bi.exe is compiled and runs under Cygwin. You can find information about Cygwin at http://www.cygwin.com/ but, for now, it is sufficient to note that "Cygwin is a Linux-like environment for Windows. It consists of a DLL (cygwin1.dll), which acts as an emulation layer providing substantial POSIX (Portable Operating System Interface) system call functionality, and a collection of tools, which provide a Linux look and feel. The Cygwin DLL works with all x86 versions of Windows since Windows 95." (from the Cygwin "Quick Start Guide"). Assume bi.exe and the other files are stored in directory Ballad_Index. Follow the download and install instructions at cygwin.com. http://www.cygwin.com/ *01* By selecting "Install Cygwin now" you will download only setup.exe. Given the option "Do you want to run or save this file" I have had the best luck selecting "Run" (because setup.exe may not be executable locally). If you decide to "Save", save setup.exe and execute it. The remaining steps are not affected by that choice. *02* If you get the Internet Explorer Security Warning "The publisher could not be verified. Are you sure you want to run this software?" select "Run". *03* Cygwin setup starts. *04* For the "Cygwin Net Release Setup Program" panel select "Next". *05* For "Choose A Download Source" Mark "Install from Internet" Select "Next" *06* Select the Cygwin root directory (no blanks in the name; C:\CYGWIN is reasonable)(currently 58Mb); Select "Next" *07* You are asked to select some options. Select as the "Default Text File Type": "Unix/binary (RECOMMENDED}" Select "Install for All Users (RECOMMENDED)" Select "Next" *08* If the library defined in the "INSTALLATION INSTRUCTIONS" section above, is named, for example, C:\Ballad_Index then for "Select Local Package Directory" enter "C:\Ballad_Index\HOME_CYGWIN\DOWNLOAD" Select "Next" *09* For "Select Your Internet Connection" mark the appropriate response ("Direct Connection" for me). Select "Next" *10* If you get a security package message "Security Alert ... What do you want to do?" ` select "Allow this instance (recommended)" Select "OK" *11* For "Choose A Download Site" select any one. I selected the first, "http://cygwin.mirrors.hoobly.com" Select "Next" *12* For "Select Packages" Mark "Curr" Make no other changes (This is a confusing panel; every option should be marked "Default"; this installs the minimum required software) Select "Next" *13* If you get a security package message "Security Alert ... What do you want to do?" Select "OK" *14* On 2MHz DLL system download and installation took about 10 minutes. *15* For "Create Icons", uncheck all options Select "Finish" *16* Copy cygwin1.dll to C:\Ballad_Index (whatever library you used for step *08*) from C:\CYGWIN\bin (currently 1.8Mb) *17* Create a "CYGWIN" system variable as follows. From "Start" select "Control Panel" From "Control Panel" select "System" On the "System Properties" panel select the "Advanced" tab On the "Advanced" panel select "Environment Variables" The "Environment Variables" panel has a "User variables ..." and a "System variables" section; under "System variables" select "New" For "New System Variable" For "Variable name:" enter "CYGWIN" For "Variable value:" enter "tty notitle glob" Select "OK" On the "Environment Variables" panel, "CYGWIN tty notitle glob" should be in the list of "System variables" Select "OK" *18* Optional cleanup Delete the "DOWNLOAD" directory (currently 15Mb) from "C:\Ballad_Index\HOME_CYGWIN\DOWNLOAD" created in *08* Tested July 6, 2007 with CYGWIN 1.5.24-4. (Note that this is the first CYGWIN release supported on 64-bit Windows operating systems). ------------------------------ IF CYGWIN IS ALREADY INSTALLED ------------------------------ If Cygwin is already installed you have a number of options. * If cygwin1.dll is in a directory on your PATH try "THE FIRST INDEX EXECUTION" * If "THE FIRST INDEX EXECUTION" fails for "cygwin1.dll not found" you can copy cygwin1.dll to Ballad_Index from C:\CYGWIN\bin * If you want to download a current version of cygwin1.dll without risking affecting current Cygwin applications by updating Cygwin you can simply download cygwin1.dll from a site such as DLL-files.com. At http://www.dll-files.com/dllindex search for "cygwin1". There you can download a zipped cygwin1.dll. Unzip it into Ballad_Index. Tested March 3, 2006 with current DLL-files.com download. ------------------------- THE FIRST INDEX EXECUTION ------------------------- The first time you run the Index, or any time you update the data file BALLDIDX.TXT, the Index will create a series of refence files, BIFILENO.IDX, BIKEYWRD.IDX, BITITLES.IDX, and (usually) BIHELP.IDX and STSong.IDX. This may take some time (depending, of course, on how fast your computer is), but it will only happen the first time you run the Index. Once you've done this, the Ballad Index is fully installed. You may, however, customize the Index using the Preferences command. Also, you might want to check the internal help (invoked with the "H" command). One of the sections in the Help file lists known bugs in the Index, and it may be more current than what is listed here. ---------------------- USING THE BALLAD INDEX ---------------------- In using the Ballad Index, keep in mind that the software is designed to be run on three different platforms. There is no PC customization at all. The result is a program driven by keyboard commands almost exclusively. The Index is menu-driven for the most part: You type in a one-character command, followed by a return, and the Index responds by doing something. The basic purpose of the Index is to perform searches and display the results. In fact, that's all it does. The general sequence of operations is: 1. You create a search: Tell the Index what to look for 2. The Index displays a list of songs meeting your criteria 3. You choose a song to examine in more detail. Repeat as needed. 4. Create a new search (or modify your existing search) and return to Step 2. When you start up the Index, the Ballad Index window will open. (Note: It is best that you not resize this window during operations The Ballad Index reads the screen size when you start up, and may not correctly update if you change the window size.) The following command line will appear at the bottom of your window: ------------------------------------COMMAND------------------------------------ Options: S=(New) Search C=Change search P=Prefs H=Help Q=Quit. Enter selection [S]: The second line shows you the list of available commands. They include: S=(New) Search Allows you to enter search criteria to find a list of songs. This is pretty much why you're here. The others options are window dressing. To choose this option, type S (you can also type "Search" if you really want to, but I don't know why you would want to), then Return. If you don't want even to type "S," you can skip it. The letter in square brackets ("[S]") tells you that this is the default -- press return and the Index will treat it as if you had entered "S." C=Change Search If you already have a set of search parameters defined, this lets you change them. (More on this later.) P=Prefs This allows you to change your user preferences. Preferences determine the way searches are conducted and displayed. You generally won't change these very often. H=Help Allows you to see the online help. It may not be good for much, but at least it will remind you of which keystrokes do what. It also contains bug reports, hints on how to conduct searches, and other things that we, at least, find interesting. You can enter the help command from almost any prompt to see the help file (the help is not context-sensitive). Q=Quit I'll bet you can figure out what this does. Like the H for Help command, Q is available almost anywhere prompts are shown. We'll assume you chose S for search. (Since it's much more interesting than the other choices.) You will be told that you are starting a New Search, and shown this prompt: Search in: T=song TITLES, K=Keywords, A=ALL text [T]: This allows you to decide what sort of search you wish to perform. The Ballad Index allows you to look for songs based on their titles, a special list of keywords, or the entire text of the entry. Searching by titles or keywords is much faster than searching the whole text (these are "indexed" searches, and take only about a tenth the time a full-text search requires), but they only work if you know the song's title or can guess at the keywords. Once you've decided which sort of search you want to do, type in the command (T, K, or A) and then press return. In this case, let's try T for titles. The software will proceed to the amazingly obvious question prompt: Enter title string: That is, you should type the word or phrase you want to look for. If you want to search for all songs with the word "Golden" in the title, for example, you would type in "golden" (no quotes!) then return. That is all there is to starting up a search! Of course, you have to tell the Index that you're done creating the search. As soon as you have pressed Return, you will enter the Search Editor. In the Editor, you can add more search criteria, change what you just entered, or otherwise change your search. If you in fact entered the search command "golden," the search editor would look like this: 1 search Song titles for "golden" ------------------------------------ Search type: &=And, O=Or, !=Not Or enter command: R=Remove Line E=Exchange I=Insert line G=Go Search, Q=Quit H=Help S=New Search. M=Main Menu. Enter command [G]: The first line, 1 search Song titles for "golden" shows the search command you have already created. The first part tells you what you are searching, and the phrase in quotes tells you the string you're searching for. Below this you see the search editor commands. For the moment, let's assume you just want to search for "Golden." So you don't need to edit your search, you just need to do it. In that case, you're ready to "Go Search." So press the "G" command, then press return. Having been told what to look for, the Ballad Index will get busy doing the looking. Depending on the speed of your computer and hard disk, a title search will take anything from no noticeable time at all to a few seconds. Then you will see the song list (only a subset is shown below): Total records found = 40 1 search Song titles for "Golden" 1 Bold Trellitee, The: see The Golden Vanity [Child 286] (File: C286) 2 Climbing Up the Golden Stairs 3 Dog and Gun: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) 4 Dog and the Gun (II), The: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) 5 Farmer and His Bride, The: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) 6 Gallant Victory, The: see The Golden Vanity [Child 286] (File: C286) 7 Going Up (Golden Slippers II) 8 Golden Axe, The 9 Golden Ball, The: see The Maid Freed from the Gallows [Child 95] (File: C095) 10 Golden Carol, The (The Three Kings) 11 Golden Glove, The (Dog and Gun) [Laws N20] 12 Golden Gullies of the Palmer, The 13 Golden Hind, The 14 Golden Ring Around My Susan Girl 15 Golden Ring Around Susan Girl: see Golden Ring Around My Susan Girl (File: RitS029) 16 Golden Slippers (I) 17 Golden Slippers (II): see Going Up (Golden Slippers II) (File: Br3571) 18 Golden Vallady: see The Golden Vanity [Child 286] (File: C286) 19 Golden Vanitee: see The Golden Vanity [Child 286] (File: C286) 20 Golden Vanity, The [Child 286] 21 Goulden Vanitee, The: see The Golden Vanity [Child 286] (File: C286) 22 Goulden Vanitie, The: see The Golden Vanity [Child 286] (File: C286) 23 Granny and the Golden Ball: see The Maid Freed from the Gallows [Child 95] (File: C095) 24 Green Willow Tree (I), The: see The Golden Vanity [Child 286] (File: C286) 25 Lady and the Glove, The: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) 26 Little Golden Ring, The 27 Lowlands Low (I), The: see The Golden Vanity [Child 286] (File: C286) 28 Merry Golden Lee, The: see The Golden Vanity [Child 286] (File: C286) 29 Merry Golden Tree, The: see The Golden Vanity [Child 286] (File: C286) 30 Oh dem Golden Slippers: see Golden Slippers (File: RJ19144) 31 Plain Golden Band, The [Laws H17] 32 Robin Hood and the Golden Arrow [Child 152] 33 Robin Hood's Golden Prize [Child 147] 34 Squire's Bride, The: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) 35 Sweet Kumadee, The: see The Golden Vanity [Child 286] (File: C286) 36 Sweet Trinity, The: see The Golden Vanity [Child 286] (File: C286) 37 We'll Roll the Golden Chariot Along: see We'll Roll the Old Chariot Along (File: Doe049) 38 Weep-Willow Tree, The: see The Golden Vanity [Child 286] (File: C286) 39 Weeping Willow Tree, The: see The Golden Vanity [Child 286] (File: C286) 40 With Her Dog and Gun: see The Golden Glove (Dog and Gun) [Laws N20] (File: LN20) Commands: D=Scroll Down, U=Scroll Up, F=Save to file, X to exit, Q to quit Enter command or song number to display [D]: If you want to view one of these songs (say #8, "The Golden Axe"), that's easy enough: Just enter the number of the song and press return, and voila! NAME: Golden Axe, The DESCRIPTION: Recitation: "What you goin' to do?" Sung: "Why, knock you in the head with a golden axe!" AUTHOR: unknown EARLIEST_DATE: 1922 (Randolph) KEYWORDS: violence FOUND_IN: US(So) REFERENCES: (1 citation) Randolph 284, "The Golden Axe" (1 fragment, 1 tune) Roud #7785 File: R284 === Enter Command: M=Main Menu X=Return to Song List F=Save to File Q=Quit: [ X ]: Which probably isn't the song you wanted. So you can go back to the song list by pressing the X command (or simply pressing return). X is another of those good keys to remember (like H for help and Q for Quit); it will usually back you up one level. In this case, it takes you back to the song list. When you're at the list, you may want to scroll up or down or look at other songs. But it's an awfully long list; it would probably be easier to try to narrow down the list of songs a bit. (Or maybe a lot....) The trick to this is a command we saw way back at the opening screen: The "Change Search" (C) command. If, from the song list or the main menu, you choose the C command, you will drop back into the search editor: 1 search Song titles for "golden" ------------------------------------ Search type: &=And, O=Or, !=Not Or enter command: R=Remove Line E=Exchange I=Insert line G=Go Search, Q=Quit H=Help S=New Search. M=Main Menu. Enter command: You see that you still have your first search item, looking for "golden." But you want to add something more -- say, all Child ballads with "Golden" in the title. Adding an item to the search is really quite easy. What you want to do is search the titles for "golden" and also for "Child." So you want to add an "AND" search. The menu gives you the clue: type "&" then return to add an AND. From there on, things are about what you've seen before. You'll be asked whether to search titles or keywords or all text, and then what search string to search for. Once you've done that, your command screen will look like this: 1 search Song titles for "golden" 2 and search Song titles for "Child" ------------------------------------ Search type: &=And, O=Or, !=Not Or enter command: R=Remove Line E=Exchange I=Insert line G=Go Search, Q=Quit H=Help S=New Search. M=Main Menu. Enter command [G]: You can, in fact, add even more searches (the maximum number of parameters is eight). Searches can be AND, OR, or NOT searches, and you can search a mixture of titles and keywords and all text. Running the above search will produce a list rather like the following: Total records found = 19 1 search Song titles for "golden" 2 and search Song titles for "Child" 1 Bold Trellitee, The: see The Golden Vanity [Child 286] (File: C286) 2 Gallant Victory, The: see The Golden Vanity [Child 286] (File: C286) 3 Golden Ball, The: see The Maid Freed from the Gallows [Child 95] (File: C095) 4 Golden Vallady: see The Golden Vanity [Child 286] (File: C286) 5 Golden Vanitee: see The Golden Vanity [Child 286] (File: C286) 6 Golden Vanity, The [Child 286] 7 Goulden Vanitee, The: see The Golden Vanity [Child 286] (File: C286) 8 Goulden Vanitie, The: see The Golden Vanity [Child 286] (File: C286) 9 Granny and the Golden Ball: see The Maid Freed from the Gallows [Child 95] (File: C095) 10 Green Willow Tree (I), The: see The Golden Vanity [Child 286] (File: C286) 11 Lowlands Low (I), The: see The Golden Vanity [Child 286] (File: C286) 12 Merry Golden Lee, The: see The Golden Vanity [Child 286] (File: C286) 13 Merry Golden Tree, The: see The Golden Vanity [Child 286] (File: C286) 14 Robin Hood and the Golden Arrow [Child 152] 15 Robin Hood's Golden Prize [Child 147] 16 Sweet Kumadee, The: see The Golden Vanity [Child 286] (File: C286) 17 Sweet Trinity, The: see The Golden Vanity [Child 286] (File: C286) 18 Weep-Willow Tree, The: see The Golden Vanity [Child 286] (File: C286) 19 Weeping Willow Tree, The: see The Golden Vanity [Child 286] (File: C286) Commands: F=Save to file, X to exit, Q to quit, S=New Search, C=Modify Search Enter command or song number to display [ X ]: We have, obviously, narrowed the search considerably. There are actually only three songs that meet this description; the other eleven are different titles by which "The Golden Vanity" is known. You can tell which are the main entries by the fact that they are shown in bold; cross-reference entries are in ordinary type. Of course, you're not limited to adding new search parameters in the search editor. You can also add or subtract or change your parameters. Look again at your options: Search type: &=And, O=Or, !=Not Or enter command: R=Remove Line E=Exchange I=Insert line G=Go Search, Q=Quit H=Help S=New Search. M=Main Menu. Enter command [G]: Note the options available: You can press "R" to remove a line. "I" lets you add a line somewhere other than the end of the list. "E" lets you exchange lines -- that is, for instance, swap line 1 and line 2. Search order actually is important if you have a mixed set of searches. If you do nothing but AND searches, the order of the searches does not matter, but if you combine AND, OR, and NOT searches, order becomes significant. (You can see examples of this in Appendix II.) This probably requires some explanation. If you have used programs like databases before, you may have encountered things like "Boolean searches." These let you use all sorts of parentheses and complicated syntax. But don't worry; you don't have to know that. The Ballad Index uses a much simpler method: It does searches just the way you tell it to. The way it works is this: If you have multiple searches, it starts by doing the first search. This produces a list of songs which meet the particular criterion. The Ballad Index then conducts the second search. It then compares the search lists. If you use an AND search, only songs found by both searches are retained. If you do an OR search, then any song found in either list is kept. If you do a NOT search, then the only songs you get are those found by the first search and not by the second. This means that the order in which you do things matters. A lot. For example, if you want to search for all the Barbara Allen variants with either "Allan" or "Ellen" in the title, you can't search titles for "Barbara" AND "Allan" OR "Ellen." If you try that search, you'll get all the Barbara Allan songs -- but you'll also get every song with "Ellen" in the title, from "Barbara Ellen" to "Ellen Munn" to "Poor Ellen Smith." The right way to conduct that particular search is to look for "Allan" OR "Ellen" AND "Barbara." (And relax; it's not as complicated as it sounds. You'll get the hang of it with a little practice. Just remember: The Index searches for things in the order they appear in your search list.) One thing you'll need to keep in mind is the presence of "cross-reference" entries. Note the third item in the list above: 3 Golden Ball, The: see The Maid Freed from the Gallows [Child 95] (File: C0 This is a "cross-reference" entry. If you looked it up, you wouldn't see an actual entry; instead, you would see a pointer to an actual entry: NAME: Golden Ball, The: see The Maid Freed from the Gallows [Child 95] (File: C095) === Enter Command: L=Lookup main entry X=Return to Song List Q=Quit [ L ]: Knowing that "The Golden Ball" is a version of "The Maid Freed from the Gallows" is all very well, but chances are that you'd like to see "The Maid Freed...," not just know about it. That's where the L (Lookup) command comes in. If you see a cross-reference entry (one of these tiny little one or two line entries), press "L" and you will go to the corresponding main entry, saving you the effort of doing a whole new search. Once you've mastered that, you really know all there is to know about the Index. The rest is all window dressing. For instance, you can save files from the Index. This is done with the "F" command. You can use this command while looking at a list of songs or while looking at an individual song. (The File command even has some advantages over viewing the list or record on-screen, as it will save the entire list, not just what you can see on-screen.) Once you enter the "F" command, you will be asked to type a file name (and directory path, if you want to save it somewhere other than the default location). The file command saves the records as text files; you can open them in any editor which handles text, including the Windows Notepad or just about any word processor ever invented. To set the preferences, enter the "P" (for Preferences) command at the main menu. The Index will start asking you questions. Here, for example, are the preferences I am using this week (next week may be a different matter...). SEARCH PARAMETERS presently shown above Found List. Do you want to display the parameters in the found list (Y/N) [ Y ]: Searches DO NOT MATCH CASE (i.e. u and U are the same). Do you want to match case (Y/N) [ N ]: MATCHED TEXT presently shown in song display. Do you want to highlight found text in song displays (Y/N) [ Y ]: Each preference has its own particular purpose. SEARCH PARAMETERS ABOVE FOUND LIST lets you "see what you are looking for." For examples, suppose you search for "engineer." If SEARCH PARAMETERS are turned on, you will see this: Total records found = 6 1 search Song titles for "engineer" 1 Child of the Railroad Engineer, The (The Two Lanterns) 2 Engineer, The 3 Engineer's Child, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 4 Red and Green Signal Lights, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 5 Two Lanterns, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 6 Zack, the Mormon Engineer Commands: F=Save to file, X to exit, Q to quit, S=New Search, C=Modify Search Enter command or song number to display [ X ]: If you turn SEARCH PARAMETERS off, this becomes: Total records found = 6 1 Child of the Railroad Engineer, The (The Two Lanterns) 2 Engineer, The 3 Engineer's Child, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 4 Red and Green Signal Lights, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 5 Two Lanterns, The: see The Child of the Railroad Engineer (The Two Lanterns) (File: R685) 6 Zack, the Mormon Engineer Commands: F=Save to file, X to exit, Q to quit, S=New Search, C=Modify Search Enter command or song number to display [ X ]: (Note the lack of a line or lines listing what you were looking for.) MATCH CASE actually controls the way searches are performed. If you match case, it means (for example) that "This is a Song Title" is not the same as "This is a song title," because the words "song" and "title" are capitalized in the first instance and not in the second. For this reason, MATCH CASE defaults to off, so that "Song" and "song" are the same, as are "Boat" and "boat," and "US" and "us," and even "case" and "caSE." But you might perhaps want to distinguish sometimes (e.g. "Polish" is not the same word as "polish," though I really doubt that you will ever find a case where that distinction matters in traditional song). Let's take another example to demonstrate one last feature: The Supplemental Tradition. Suppose you do an ordinary title search for "Aginc" (short for "Agincourt," after the famous battle won by the English King Henry V). You will find this list of hits: Total records found = 3 1 search Song titles for "aginc" 1 Agincourt Carol, The 2 For the Victory at Agincourt: see The Agincourt Carol (File: MEL51) 3 Song of Agincourt, The: see The Agincourt Carol (File: MEL51) If you look up song 1, the Agincout carol, you'll see something like this: NAME: Agincourt Carol, The DESCRIPTION: King Henry (V) travels to France "wyth grace and myght of chyvalry," captures Harfleur, and wins a great victory at Agincourt, "Wherfore Englonde may call and cry, 'Deo gracias (x2) anglia Rede pro victoria.'" AUTHOR: unknown EARLIEST_DATE: before 1500 (Bodleian MS Selden B. 26); hints in chronicles imply that it was sung at Henry V's return to England 1415/16 KEYWORDS: England France battle royalty HISTORICAL_REFERENCES: 1413 - Accession of Henry V Aug 11, 1415 - Invasion of France Sept 22, 1415 - Surrender of Harfleur Oct 25, 1415 - Battle of Agincourt. Henry V, outnumbered by about 10 to 1, defeats the French, inflicting casualties in the same 10:1 ratio 1422 - Death of Henry V FOUND_IN: REFERENCES: (6 citations) Percy/Wheatley II, pp. 29-31, "For the Victory at Agincourt" (1 text) Stevick-100MEL 51, "(The Agincourt Carol)" (1 text) Chappell/Wooldridge I, pp. 25-30, "The Song of Agincourt" (1 text, 1 tune) ADDITIONAL: Brown/Robbins, _Index of Middle English Verse_, #2716 Noah Greenberg, ed., An Anthology of English Medieval and Renaissance Vocal Music, pp. 62-65 (1 text, 1 tune with harmonization) DT, AGINCRT1* ST MEL51 (Full) CROSS_REFERENCES: --MORE-- Scroll Commands: U=Scroll Up D=Scroll Down. Enter Command: M=Main Menu X=Song List F=Save to File V=Show SuppTrad Q=Quit: [ D ]: If you look at the command list, you'll see that there is a new entry, "V=Show SuppTrad." This is available because there is an entry in the REFERENCES: field, "ST MEL51 (Full)." What this means is that you can actually look up a text of The Agincourt Carol, to let you know what this particular song looks like. In ths case, what you would see looks something like this: Agincourt Carol, The Complete text(s) *** A *** The Song of Agincourt From the Bodleian Library (Cambridge), MS. Selden B. 26 As transcribed in Chappell/Wooldridge, pp. 25-26. Collated against the version in Robert D. Stevick, One Hundred Middle English Lyrics, #51 (S), the version in Percy/Wheatley, II.i.5 (P), and that in R. T. Davies, Medieval English Lyrics, #80 (D), all of these being versions of the same text but with different modernizations. (It appears that the original probably used the letter yogh (3). Chappell, Davies, Stevick have transcribed this as gh; Percy uses y. I suspect the manuscript had thorn also, but this cannot be proved from the transcriptions. Chappell/Wooldridge report that Percy's source was from a copy of the Cambridge MS.) The Song of Agincourt Deo gracias anglia, Redde pro victoria 1 Owre kynge went forth to normandy, With grace and myght of chyvalry: Ther god for him wrought mervelusly. Wherfore englonde may calle and cry Deo gracias.... Press any key to continue; B returns to top., X exits... [ ]: You can use this to scroll through the song text if it's available. The Supplemental Tradition is a rather mixed bag, since the first few hundred texts were assembled for other purposes. But we're making increasing effort to include at least representative stanzas of the songs in the Ballad Index not easily accessible elsewhere. That's about it. The above covers just about every function of the Ballad Index. For further information, see the online help or the files on the web site (both of which explain the material in the Ballad Index; this ReadMe is concerned entirely with the software used to search the Index). You can find a complete list of commands in Appendix I below. ------------------------------------------------- APPENDIX I: THE COMMANDS USED IN THE BALLAD INDEX ------------------------------------------------- The following list shows all the keystroke command presently defined in the Ballad Index, along with their purposes. Note that a particular keystroke command will only have a use in particular places in the Index. A: Search All Text Used only in the search editor. Tells the Index to search entire records (as opposed to titles or keywords) B: Beginning of List Used only when displaying a song or song list. Moves to the top of the display. C: Change/Modify Search From the main menu or song list, lets you modify the search parameters you have entered. If you just want to start over from scratch, use S (New Search) instead. D: Page Down When displaying a song or song list, move down 12 lines (approximately) toward the end of the song. E: Exchange Lines From the Search Editor, exchange the order of two particular search parameters. F: Save to File When displaying a song or a song list, save that entry to a text file for use in other programs. G: Go Search From the search editor (or the main menu if you already have a search defined), proceeds to perform your specified search. H: Help Displays the Ballad Index internal help. Available from most prompt lines. I: Insert Line Used in the search editor to add another parameter. (Note: You only need to do this to add an item before the end of the search list. To add a parameter at the end, use the And, Or, Not keys). K: Search in Keywords Specifies that you wish to search in keywords (as opposed to titles or all text) L: Lookup Main Entry When looking at a cross-reference entry (a short entry advising you to "see" another entry), looks up the related main entry. M: Main Menu From most menus, returns to the Main Menu P: Preferences From the main menu, lets you set your preferences Q: Quit From any command line, lets you quit the Ballad Index R: Remove Line From the search editor, lets you remove a search parameter S: Search (New Search) From the main menu or lower-level menus, create a new set of search parameters T: Search Titles Only Specifies that you wish to search in titles (as opposed to keywords or all text) U: Page Up Used only when displaying a song or song list. Moves up 12 lines or to the top of the display. V: Show Supplemental Tradition Enabled only for songs which have a Supplemental Tradition entry. This lets you call up that entry to see the text of the song. W: List Keywords Displays a list of the Ballad Index Keywords. (You can also view the keywords in any text editor, or edit them to suit your needs. Details on editing the keyword list are found in the internal help.) X: Abort/Exit/Back One From any command line, moves back up one level toward the main menu &: AND AND command for searches. (You can also use "A," but elsewhere that command means for "All Text") |: OR OR command for searches. (You can also use "O") !: NOT NOT command for searches. (You can also use "N," but elsewhere that command means "No") or Selects the default command (the thing enclosed in brackets []). ----------------------------------------------------- APPENDIX II: FURTHER EXAMPLES AND HINTS FOR SEARCHING ----------------------------------------------------- This appendix shows you how you can set up searches to find particular songs. The key thing to remember is that searches are conducted in the order specified. This means that rearranging your searches can produce different (sometimes very different) results. Let's take examples by pretending the Ballad Index has only a handful of titles (as opposed to the 6000+ it actually contains): Barbara Allen Barbara Ellen Barbara Buck Barbary Allen Barbary Allan Poor Ellen Smith Suppose you search for Barbara AND Allen OR Ellen. What you will get is not "Barbara Allen" and "Barbara Ellen." Instead, your search will turn up "Barbara Allen," "Barbara Ellen," and "Poor Ellen Smith." Why? Consider what you looked for. The search for "Barbara" would turn up three songs: "Barbara Allen," "Barbara Ellen," and "Barbara Buck." The second search, for "Allen" would pick up "Barbara Allen" and "Barbary Allen." AND-ing these two lists together (that is, finding the songs which are in both lists) leaves us with only one song: "Barbara Allen." Having finished the first two searches, the Index keeps the result of the AND, then searches for "Ellen." It finds "Barbara Ellen" and "Poor Ellen Smith." OR-ing these two with the previous list, containing "Barbara Allen," will produce the list we specified. But chances are that you were looking for all songs with Barbara and EITHER Allen OR Ellen in the title. To find these, rearrange the searches. What you want is not Barbara AND Allen OR Ellen, but rather Allen OR Ellen AND Barbara. Now you may have noticed that these searches didn't turn up the "Barbary" references. There is a trick here: You don't have to search for whole words. If you don't know whether a name is spelled "Barbara" or "Barbary," just use "Barbar" or even "Barb." Some other examples of the "wrong way" to search is something like Barbara NOT Allen OR Ellen. That search will get you "Barbara Allen," "Barbara Ellen," "Barbara Buck," and "Poor Ellen Smith." Whereas what you wanted was probably all the songs with Barbara in the title that didn't contain Allen or Ellen. The correct search for that would be Barbara NOT Allen NOT Ellen. That would produce the result you want: "Barbara Buck" and nothing else. Keep in mind that every search (except the first) operates on two lists: The list of songs found in your most recent search, and the list of songs found by all the searches prior to that one. AND takes only the songs found in both lists. OR produces every song found in either list. NOT produces the songs found in the first list but not the second. ---------------------------------------- Appendix III: Distributing This Software ---------------------------------------- The Ballad Index software is distributed under the GNU License, which is included with the source code on this web site. Specifically, it is made available under Release 2 of the GNU license (1991). Key provisions of the GNU License include the following: * The Ballad Index is made available free of charge. You may give away as many copies as you like, but you may not charge for them other than nominal duplication fees. ("[Y]ou must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.") * There is no warranty at all provided with this software. You got it for nothing, so we can't guarantee that it will work for you. If you find a bug, we will probably look into it, but cannot guarantee a fix. * You may modify the Ballad Index for your own purposes, or use portions of it in your own work, but you may not sell the result. If you do modify the Ballad Index source code, we'd like to hear about it. (Not a requirement, but a request.) What is useful to you may well prove useful to others.