How Accordance Imports HTML
Last Friday, we imported an HTML file we downloaded from Project Gutenberg into Accordance as a User Tool. Today, I want to look at some of the ways Accordance interprets the HTML tags so that you can better understand how the HTML import works. Some people have been waiting with bated breath for this kind of documentation. I hope I don't disappoint.
The <title> tag. The first thing Accordance looks for is the <title> tag. This is the tag that specifies the name which appears in the Title bar of your web browser. Accordance automatically converts the Title into the first title of your User Tool. Since many e-texts will have the title within the body of the web-page as well, this conversion of the Title tag can lead to redundancy. For example, in the Companion to the Bible tool we created last Friday, you'll see that the first title in the browser is "The Project Gutenberg eBook of Companion To The Bible, by E. P. Barrows." Just below it is the title "Companion to the Bible" which was taken from the actual body of the HTML document. The first thing I would do with this User Tool is open the Edit window and delete the first title and all the Project Gutenberg license information. That will eliminate the redundancy in the browser and get rid of all the legalese.
The irony of Accordance's conversion of the <title> tag is that in well-formatted e-texts it will create a redundancy that you'll almost always want to remove. Still, including the <title> tag ensures that nearly all e-texts start out with at least one appropriate title.
The Header (<H1>, <H2>, etc.) tags. In HTML, header tags are used for merely cosmetic purposes, to create boldfaced headlines at various sizes. When Accordance imports header tags, it interprets them both cosmetically and structurally. In other words, it uses the header tags to identify the text which will appear in the User Tool's Titles field and to assign a browser hierarchy level. Thus, any text tagged with <H1> is assigned to the Titles field and placed at the top level of the browser hierarchy, just as if you had placed the red T in the margin of the tool's Edit window. Accordingly, <H2> is placed at the second level of the browser hierarchy (as if you had placed a red "1" in the margin of the Edit window); <H2> is placed at the third level of the browser hierarchy (as if you had placed a red "2" in the margin); etc.
When it came to how to display the various titles, we departed from the way HTML headings are usually formatted. Instead, we used a standardized system of descending formats.
<H1> 18 point bold, centered
<H2> 14 point bold
<H3> 12 point bold
<H4> 12 point italic.
Header tags <H5> through <H9> are also formatted as 12 point italic, but are placed at successively lower levels in the browser hierarchy. Any header tags beyond <H9> are ignored.
Since HTML Header tags are used primarily just for looks, Accordance's reliance on these tags to create the browser hierarchy can lead to hierarchy levels where none should exist. For example, it is common for e-texts to do something like this:
In this case "Introductory Remarks" is really the title of "Chapter One", rather than the beginning of a new subarticle. You'll probably want to fix things like this either before the import (using a text editor to edit the actual HTML file) or after the import (in the Edit window of the User Tool).
I hope this is helpful to some of you. We'll look at how other HTML tags get imported into Accordance later this week.
Atlas: Custom Site Layers and Site Sets
I'm sorry for the lack of posts this week. I've got a post about HTML import of User Tools waiting in the wings, but I want to verify some things before I post it. In the meantime, here's an interesting question I received from a user about the Accordance Bible Atlas. Hopefully some of you will find my answer helpful:
Questions concerning Atlas
1) Can you edit site names? Change font color, bold italics, etc.
I am trying to create a map of the cities that Joshua defeated. I would like to highlight by chapters as we go through the book of Joshua, i.e. chapter 11 site names in red, chapter 12 in blue, etc.
2) Will any version of Atlas allow me to do that?
The answer to these questions is, "Yes! You can do what you're asking with any version of the Atlas."
You can set up a layer of sites in a couple different ways, and can customize the font, size, style, color, marker, etc. of all the sites in that layer.
First, you can set up a regular Site Layer by going into the Sites pop-up menu and choosing Define Site Layer. In the dialog that appears, you can create a new layer, set up the look of the labels, and specify which sites you want to appear using a database of Biblical and Archaeological criteria. The advantage of this approach is that it is quick and easy. The disadvantage is that you cannot pick the sites you want to appear by name.
To create a layer displaying a specific list of sites, you can choose Custom Site Layer from the Sites pop-up menu. In the dialog that appears, you can create a new layer, give it a name (Joshua 11, for example), set up the look of the labels, and then pick the sites you want to include.
An even better way to do it is to use the following shortcut:
- Start with the text of the Bible, and as you're reading through Joshua 11, select each site name and click the Map button on the Resource palette. A Map window will open displaying that site highlighted in red. Now go back to the text of the Bible, select the name of the next site you run across, and click the Map button again. Now two sites will be highlighted on the Map. Continue this process until you've gotten through the entire chapter.
- Now open the Sites pop-up menu on the Map window and choose "Convert to Custom Layer." This will take all the highlighted sites and add them to a new custom layer. You just give it a name and set the font, size, and style characteristics.
- Next, go to chapter 12 and repeat the process. You will soon have a separate site layer for each chapter of Joshua, each with labels in different colors or styles.
- Now, what if you want to view all of these separate layers at the same time? First, hold down the shift key and select each layer. In this way, you can display multiple layers on the map at the same time. You can then choose Convert to Site Set from the Sites pop-up menu to create a single set which combines all of these individual layers. Call it something like "Cities in Joshua," and you'll have a single menu item which will display all those layers at once.
Obviously, not all of you are going to want to color-code cities in Joshua by chapter, but I hope you can see how easy it is to set up Custom site layers in the Atlas and even to combine multiple layers into sets. You can do the same thing with Region and Route layers as well.
Oh, and by the way, if you want to see the events of Joshua 11 unfold before your eyes, be sure to choose the animated Route layer entitled "Battle of the Waters of Merom."
Importing HTML Documents into User Tools
For the past week or so, I've been talking about User Tools. So far, we've explored how to create a user tool from scratch and how to merge multiple user tools together. Today, we'll look at one of the coolest features of user tools: the ability to import html documents into a user tool.
Depending on your point of view, this feature of Accordance can be one of the most exciting, and one of the most frustrating. The reason for excitement is obvious. With this feature, you can potentially download all kinds of resources from the web and convert them into fully-searchable Accordance modules. The frustrations can come when you actually import an html document and find that there are still numerous issues you need to fix. I'll discuss some of the specific issues involved with importing user tools in future posts, but for now, I just want to show you how it's done.
Rather than just talking about importing an html document in the abstract, let's actually import the same html file together. We'll use as our sample a book called A Companion to the Bible by E.P. Barrows which is available from Project Gutenberg. Please note that I found this text simply by going to Project Gutenberg and doing a search for books with "Bible" in the title. I know nothing about the particulars of this book or its author, so please don't send me angry letters complaining about the theological perspective of something I told you to import into Accordance. :-)
To download this html file, just go to this page. At the bottom of the page you'll see a list of different file formats and links where they can be downloaded. If you control-click on the "main site" link beside either the compressed or uncompressed HTML files, you'll get a contextual menu with a choice to "Download Linked File." This will download a file named "17265-h.htm" to your hard drive.
Okay, now that you have the cryptically-named html file on your hard drive, open Accordance and go to File-->User Files-->Import User Tool...
A dialog box will appear giving you the option to import from plain text, HTML, or (for those who have purchased the option) TLG. Make sure HTML is selected. You also have the option to create a new User tool, or to add the file you're importing to the end of an existing User Tool. Select Create a new User Tool and click OK.
An alert dialog box will then appear reminding you that the HTML import feature should not be used to violate copyright. So if your conscience is clear, click OK to dismiss the alert and continue.
The next dialog box to appear is a standard Open dialog box asking you to locate the HTML file you want to import. For most people, the file you downloaded from the web will be located on your desktop. Use command-D to navigate to the desktop quickly (this tip works with any Mac program) and select the file named "17265-h.htm."
The next dialog box to appear is a standard Save dialog box asking you to name your User Tool and decide where you want to save it. I named mine "Companion to the Bible" and saved it in the User Tools folder inside the Accordance Files folder inside my Documents folder.
That's all there is to it! A progress dialog will appear showing the progress of the import, which can take a few minutes depending on the size of the file. Once it's done, a new User Tool window will open displaying the User Tool.
If you open the browser, you'll see that most of the titles have been formatted as such and even assigned a basic browser hierarchy. Look through the tool and you'll see that most of the obvious Scripture references have automatically been hypertexted. You can now search your tool, browse and read it, or edit it to your liking.
Next week, we'll look at the specifics of what the HTML import did and how it interpreted the HTML tags—something we admittedly have not documented as well as we should. But in the meantime, try importing other HTML files and see what happens. You can also save word processing documents as HTML files and then import them into Accordance. It's a great way to add new materials to your Accordance library.
P.S.: If you're using Accordance 7, please make sure you've downloaded the free update to Accordance 7.1. There was a bug in 7.0 which messed up some HTML imports.
Merging User Tools
On Monday I discussed the pros and cons of creating a single User Tool containing multiple resources or creating a separate User Tool for each resource. I tend to think a few large user tools are more convenient than a bunch of little ones.
Now, what if you've created fifty tiny user tools and, persuaded by my brilliant reasoning, now wish you had just combined all those little resources into a single user tool? What do you do now?
Well, fortunately, we anticipated the possibility that you might eventually want to combine two or more separate user tools into a single module. To do that, simply go to File-->User Files-->Merge User Tool...
A dialog box will appear displaying two lists labeled Merge and Into. The user tool you select from the first list will be merged into—that is, added to the end of—the user tool you select from the second list. When you click OK, an alert will appear asking if you're sure you want to do this. Simply click OK, and the two modules will be merged together. It's important to note that the user tool which you choose to be merged into the other one will automatically be removed from Accordance after it is merged.
So if you created a separate user tool for each of last year's sermons, and you now want to keep them all together, simply merge them together and you're good to go.
Valentine's Day Verses
Looking for that perfect message to send this Valentine's Day? Sick of sing-songy greeting card poems in iambic tetrameter? Why not look to the Bible for inspiration? Don't just use Accordance to finish your dissertation or pull together a sermon; use it to score points with the one you love.
Toward that end, here are a few verses which you may find useful this Valentine's Day:
For anyone in a relationship: "Place me like a seal over your heart, like a seal on your arm; for love is as strong as death, its jealousy unyielding as the grave. It burns like blazing fire, like a mighty flame. Many waters cannot quench love; rivers cannot wash it away. If one were to give all the wealth of his house for love, it would be utterly scorned." (Song of Solomon 8:6-7, NIV).
For married couples: Song of Solomon 5 and 7. (Sorry, no quotes. This blog is G-Rated!)
For couples facing a major decision: "Do what is in your heart. You choose. I'm right here with you whatever you decide." (1 Samuel 14:7, HCSB). (Sounds a lot better than "Yes, dear" doesn't it?)
For the person who is lonely this Valentine's Day: "Wait for the LORD; be courageous and let your heart be strong. Wait for the LORD." (Psalm 27:14, HCSB).
When you suspect they've "lost that lovin' feelin'": "Never let loyalty and faithfulness leave you. Tie them around your neck; write them on the tablet of your heart." (Proverbs 3:3, HCSB).
For long-distance relationships: "May the LORD keep watch between you and me when we are away from each other" (Genesis 31:49, NIV).
For the guy who forgot that today is Valentine's Day: "I am a worm and not a man!" (Psalm 22:6, HCSB).
Happy Valentine's Day, whatever your situation! ;-)
Browser Shortcut Confusion
In the comments on yesterday's post, someone mentioned that option-clicking a disclosure triangle in the tool browser doesn't seem to work as he had expected. So let me take a break from user tools to explain how this works.
I'll begin by how it doesn't work. If you use the List view in the Finder, and you option-click the disclosure triangle beside a folder, every subfolder within that folder will be completely expanded. This saves you having to drill down through a series of nested folders.
Option-clicking a disclosure triangle in the Tool browser is a little different. It's not designed to help you drill down through articles that you're browsing. Rather, it is designed to help you see the structure of the article you're viewing.
For example, let's say I do a search for the word "dove" in the Entry field of Anchor Bible Dictionary. I end up looking at a deeply nested subarticle entitled "8. The Dove." That's great, but I want to know where I am in the context of the entire Dictionary. I can tell by looking at the Go To Box in the bottom right corner of the window that I am in the article on "Art and Architecture," but I still don't know where this particular subarticle fits into the overall structure of the article.
If I simply click to open the Tool Browser, I see the alphabetical listing by which Anchor Bible Dictionary is arranged, and the "A" section is highlighted to indicate that the article I am viewing is in that section of the Tool.
If I click the disclosure triangle beside the "A," I get all the main articles that begin with that letter. I could then scroll the browser past hundreds of articles until I see that the "Art and Architecture" article is highlighted, then click that disclosure triangle to drill down further. As you can see, the manual process of drilling down to the current article would take me all day, just to see how the subarticle I am currently viewing fits into the structure of the larger article.
That's where our option-click trick comes in. Instead of drilling down through all those articles and subarticles, I can simply option-click the disclosure triangle to open the Browser, and it will automatically display all the articles and subarticles which contain the current article I'm viewing.
Note, however, that any subarticles beneath the current subarticle are not automatically expanded by this trick. For example, if there were a disclosure triangle beside "9. The Olive Branch," that triangle would remain closed, because it does not contain the article I am currently viewing in the display pane. In other words, the option-click expands all the levels of the browser up to the current article, but does not expand any of the levels beyond the current article.
I know by now this is probably as clear as mud, especially for those of you who weren't confused by how this works. Still, I hope it's helpful to some of you—especially those who weren't yet aware of this shortcut.
One User Tool or Many?
In the comments on my last blog post, a couple of people asked if I plan on putting all my college papers into a single user tool or if I'm going to create a separate user tool for each paper. The same question applies if you're wanting to archive the text or notes of your sermons, create a journal, import multiple books by a single author, etc. My answer to that question is clear and definitive: it depends.
In my case, the college papers I'm archiving are relatively short and address a variety of topics. I don't want twenty or so separate user tools cluttering up my menus, so I'm including them all in a single user tool. However, among my papers is a daily Bible study I wrote during college which I think makes more sense standing on its own. For that I intend to create a separate user tool.
The decision of whether to include multiple works in a single user tool or to create multiple user tools is similar to the decision process we go through when developing full-blown Accordance modules. In general, we tend to favor creating large modules which contain multiple works, rather than a bunch of little modules. After all, more modules mean more items in your menus. They also require more effort to search related resources.
For example, you know that there is an article in Biblical Archaeology Review which discusses the water-tunnel at Megiddo, but you have no idea which issue it's in. If we had created separate modules for every issue or every year of issues, you would have to group all those modules into a single BAR Archive tool set in order to be able to search the whole archive in a single pass. Since we created a single module for the entire Archive, you have one menu item to deal with and one module to search.
So when deciding whether to create one user tool or many, consider how you are going to use it. Are you going to want this resource to stand alone, or to be grouped together with related resources? Do you want to be able to zero in on a single resource or do you want to be able to search them all together?
In the case of archiving the notes or text of one's sermons, I would probably group them all together into a single user tool. If you want to narrow your searches to a particular sermon or a particular year's worth of preaching, you can always option-click that section of the browser to set a range (for more on how that works, see the section of this blog post entitled Using the Browser to set a "Range").
In short, my tendency would always be to create the fewest possible user tools by grouping like resources together. For the most part, it's easier and more convenient to manage.
Creating a User Tool from Scratch
Monday I mentioned that I'm using the User Tools feature of Accordance to create searchable versions of some old papers from college. So how do you create a new user tool? Here's a quick rundown of the basics:
1. Create a New User Tool. Go to the section of the Resource palette labeled "My Stuff," then click and hold on the My Tools icon. This is the icon of the blue book with the pen over it. (The plain blue book indicates that User Tools function much like Accordance General Tools, and the pen indicates that you can write to them.) The menu that appears when you click and hold on this icon will list all of your currently installed User Tools, and at the bottom of this menu you'll find an item labeled "New User Tool..." Select this item and a dialog box will appear asking you to give your User Tool a name. Simply enter a name and click OK. I gave my college paper user tool a brilliantly creative name: "Papers."
2. Edit Your New User Tool. Your new User Tool will open as a blank window. You can begin editing it either by selecting Edit User Tool from the Selection menu (the keyboard equivalent of which is command-U) or by clicking in the display portion of the tool and beginning to type. Either way, a new Edit window will open in the top right corner of the screen.
The first line of the Edit window has a red T in the margin, indicating that this paragraph will constitute your tool's first title. In my "Papers" tool, I entered the Title of my first paper, "Fleshing Out Jacob and Esau." I then hit return twice and began typing the body of the paper.
3. Format Your User Tool. When I'm entering the text, I can format it by using all the standard keyboard shortcuts: command-B for bold, command-I for italic, etc. To change font size, center justify a paragraph, etc., I usually open the Text Palette from the Window menu. This handy little palette has accessible buttons and menus for formatting text in User Tool and User Note Edit windows. I could also control- or right-click a selection of text and select various formatting options from the contextual menu. Finally, I could select those formatting options from the Display menu at the top of the screen, but that is by far the least convenient method.
4. Add Titles and Subtitles. As mentioned above, the first line of your user tool is automatically set as a title. To add additional titles and subtitles, you simply drag your cursor into the margin to the left of a paragraph. You'll notice the cursor change to a capital T. If you click in the margin at that point, a red T will appear next to the paragraph, and the text of that paragraph will appear at the top level of your User Tool's browser.
If you want that paragraph to appear as a subarticle of another article, hold down the option key when you drag over the margin. You'll notice the cursor change to a capital T with a plus sign (+) beside it. If you click in the margin, a red "1" will be placed there, indicating that this is the first sublevel in the hierarchical browser. If you hold down the option key the next time you click in the margin, a "2" will appear, indicating that this article will be at the second sublevel of the browser.
If you want to go up a level, simply hold the shift and option keys down while dragging over the margin of the browser. In that case, the cursor will change to a capital T with a minus sign (-) beside it, and clicking will result in a lower number (or a capital T at the top level) being placed beside that paragraph.
5. Add Scripture Links. To format a Scripture reference as a hypertext link, simply select it and click the Scripture Link button at the bottom left corner of the Edit window (or use the keyboard shortcut command-L). The selected text will appear in the Edit window in a blue underline style, but it is important to understand that it is not an actual link in the Edit window. When you update your user tool, the link will be parsed and checked to see if it is a valid reference. If it is, it will appear as a live link when you view it in the User Tool window.
6. Update Your User Tool. When you're finished editing, you can update the user tool and save your changes by clicking the update button in the lower right corner of the Edit window, or by using the familiar keyboard shortcut for saving: command-s.
That's pretty much all there is to creating a user tool from scratch. You can, of course, copy and paste text into a user tool rather than typing it, and there are some other tricks I'll discuss in a later post. I'll also cover the ins and outs of importing User Tools from html. But that's pretty much how I'm tackling the task of re-typing all those old college papers.
Resurrecting College Papers as User Tools
I'm really not much of a pack-rat, but I have spent the last sixteen years hanging on to a pile of papers from college which I felt were particularly noteworthy and which I've been unwilling to toss. I didn't own a computer in college, so these papers are not in electronic format at all: they are either handwritten (back then a few profs would actually allow such a thing!) or typed (usually by female friends who took pity on me). I'd like to be rid of the pile of tree-pulp, but I don't want to lose the thoughts recorded there. And more than just wanting to archive these papers, I want them in a form I can actually use from time to time.
My solution is to re-type them into Accordance as user tools. I suppose I could scan and OCR them, but I'm also editing and revising them as I type, so it's just as easy to key them in; and in the case of the handwritten papers, I have to key them in.
The advantages of having these papers in an Accordance user tool are that I can hypertext the Scripture references, I can quickly search them or amplify to them, and I can organize them so that they have a hierarchical browser. Besides, most of these papers deal with Biblical or religious themes, so where better to have access to them than in my Bible study software?
The Selection Menu
Ever noticed that "Selection" menu in the Accordance menu bar? Ever wondered what it's there for? Well, as its name implies, it is there to help you select material and then do something with it. Here's are some of the highlights of the Selection menu.
The first thing to realize is that when it comes to the text of the Bible, you can select material in the traditional way (dragging the mouse across the text), or you can "bookmark" an entire verse. Let's say you've done a search and you get thirty verses. You go through the hit verses and decide that ten of them are appropriate to your sermon, Bible study lesson, etc. You can quickly "mark" each of these verses by holding down the option key and clicking anywhere in the verse. You'll notice the cursor change to a bookmark when you press the option key, and when you click on the verse, a blue bookmark will appear next to the verse.
As soon as you add at least one mark, two additional text access buttons labeled "Mark" will appear next to the Verse, Chapter, and Book buttons. You can use these buttons to jump to the next or previous marked verse.
If you happen to run into five verses in a row which you want to bookmark, and you don't feel like option-clicking each one, you can drag a selection across all those verses and then choose the first item in the Selection menu: Mark Selection (or use the keyboard shortcut command-7). Presto change-o! A bookmark will appear next to all the verses you selected.
Now that you've marked the verses you're interested in, what do you do with them? Well, one thing you can do is to add them to a Verse Reference List. A Reference List window is a special container window that displays a list of verses. You add verses to a Reference List by selecting or marking the verses you want, then choosing either a new Reference List window or an open Reference List window from the submenus labeled Add Selection To and Add Marked Verses To.
The Reference List window has a text field at the top where you can enter a description of the verses it contains, and like any window, you can rename the Reference List by going to Window-->Set-->Name...
What are the advantages of collecting verses in a Reference List? Well, the first advantage is that the Reference List window can be saved as an individual window or as part of a session. Bookmarks are not saved between sessions, so if you want to keep the verses you've marked, you need to move them into a Reference List.
Now, let's say you want to cite all these verses you've collected in a word processing document. You can Select All and then choose Copy As References to create a nicely formatted list of references to those verses.
Another thing you can do with a Reference List is to search the verses it contains using the CONTENTS command. Simply set up a Search window, enter the search criteria you want to find, then choose AND and CONTENTS from the Enter Command submenu of the Search menu. Using the CONTENTS command in conjunction with a Reference List is a little like creating a very specific search range.
In addition to the commands I've highlighted in this post, the Selection menu also contains the Edit User Note command, which you use to add a note to any verse you select, and the Group and Ungroup commands, which enable you to join or separate items in the Diagram window.
Hidden in the shadow of Accordance's flashier features, the options in the Selection menu can easily get lost, but bookmarks and Reference Lists are useful tools for keeping track of the verses you're most interested in.