Eloquent

Eloquent is the new name for the Open Source Bible software for the Macintosh, MacSword. It is issued under the GNU General Public License, and is based on the Sword Project. Because of this, it is compatible with all of the Sword Project modules. (According to the MacSword/Eloquent web page, there are over 200 modules available in 50 languages.) The nature of the Sword Project is such that, with the right tools and a little effort, users can also create their own modules. It is the fact that MacSword/Eloquent is a part of the Sword Project that sets it apart from the other Bible software programs on the market. While all the rest rely on proprietary file formats, which are unique to themselves, MacSword/Eloquent, by relying on the Sword Project modules, enters the realm of cross-platform Bible tools, which allow for a common base of study tools, whether you are using a Mac, Windows-based or Linux-based computer. Furthermore, there are also programs for the iPhone (PocketSword) and Android (AndBible), which likewise use the Sword Project modules. Because of its open-source nature, MacSword/Eloquent tends to rely on older, out-of-copyright works, but it is entirely capable of opening protected, copyrighted works. For instance, it is possible to purchase the NETBible for the Sword Project and MacSword/Eloquent. (For the sake of simplicity, from this point forward, we will refer to MacSword only as Eloquent.)

Installing Eloquent

Installing Eloquent is as simple as downloading a dmg file from the Eloquent web site's Eloquent Download Page. This dmg download contains both the application and a movie that shows how to install modules. Of course, once you need to upgrade in the future, you don't need to download the dmg, and can just download the application file, which is about half the size, also from the same download page.

Updating from MacSword 2 to Eloquent

If you are upgrading an install of MacSword 2 to Eloquent, and want to keep all of your preferences and data, you will need to change the names of a couple items in your Finder. Here's what you need to do, according to the official web site:

Just rename the preference file org.crosswire.MacSword.plist to org.crosswire.Eloquent.plist. Also rename the “MacSword” part of the folder /Users//Application Support/MacSword before you start Eloquent for the first time. If you already started Eloquent and the folder “Eloquent” already exists, just copy all data into this folder.

Installing Modules

As stated, the full dmg download includes a movie showing how to install modules, but if you would like, you can watch the movie by clicking this link. It is not immediately apparent where Eloquent installs the modules, so I shall say a word or two here. By default, Eloquent installs its module files in the following folder:

/Users/<username>/Library/Application Support/Sword

Technical stuff you can ignore

The following section contains some technical information for more unusual uses or advanced usages of Eloquent. It is only of interest if you use other Sword Project applications, such as Bible Desktop or BibleTime on your Mac, or if you need to install unusual modules that are not available from the usual module sources. If you would like, you can skip this section and the next, and move to the section "Setting up Eloquent."

Unlike earlier versions of MacSword (1.4 and earlier), it is not possible to change this folder's location. However, with a little effort, and the usage of what are called "symbolic links", it is possible to store the files elsewhere. However, if you just want easier access to this folder, you can simply make an alias using the Finder, and drag the folder to a more convenient location (for instance, your user folder or your Documents folder).

It is also possible to install your own modules, but it is a bit more complicated to do so. In fact, it is not recommended that you do this unless you absolutely have to. For instance, if you have a module that is not found on any repository, you would need to manually install a module. In order to install your own modules, you really need to have a good understanding of your Mac's file structure, and how the Finder works. If you feel uncomfortable following these instructions, it would be best to ask on the Mac-Ministry mailing list for help.

The very first thing you need to do is to quit Eloquent if it's running. Any modules you manually install won't be available to Eloquent until it's restarted, so it's best to quit it before you start installing the module.

For the sake of this example, I have downloaded the OSX version of the SBLGNTApp file. When the zip file is unzipped, there are two folders inside the .swd folder. The first is named "mods.d", and the second is named "modules". The mods.d folder contains the configuration file for this module, and must be placed in the folder with the same name within Sword folder mentioned above. The "modules" folder contains a tree of folders. In this case, the structure looks like this: /modules/comments/zcom/sblgntapp/. Inside that last folder are three files, "nt.bzs", "nt.bzv", and "nt.bzz". What we need to know is this. You need to find the "modules" inside your Sword folder, then find the "comments" folder, and then the "zcom" folder. Inside that folder, you can drop the folder named "sblgntapp". It is possible that you do not have a folder named "zcom" or a folder named "comments". In such a circumstance, it would be easiest to navigate to the last folder you have and copy the remaining folders into that. For instance, if you have a "comments" folder, but no "zcom" folder inside that, copy the "zcom" folder from the sblgntapp.swd folder, into your Sword's "comments" folder. Once all the files are copied, you will want to launch Eloquent to see the modules you've installed.

More on file locations

If you have BibleTime installed (or BibleDesktop), you may want to share your modules between the programs. This will require the usage of the command line to make your Sword folder available to these other applications. The exact commands will depend on which program you have installed first, and where your Sword modules have been installed.

Before we begin, however, it is worth saying a word about symbolic links. Symbolic links are similar to the Macintosh "aliases" that have been around since sometime around System 7. An alias is a pointer file that merely points to the actual file location. Wherever you move the file, the alias can find it. This is very convenient, but Eloquent and other Sword Project programs do not recognize these aliases properly, so you need to use another form of "alias" called a symbolic link. These links are more "hard-wired" and don't follow the file around if you move it. You would have to recreate the symbolic link were you to move the original file. However, the advantage of a symbolic link is that it is more transparent than aliases. Where an alias may not work, a symbolic link will.

There are a few ways to create symbolic links. MacPilot, for instance (which has been part of a MacHeist bundle in the past, and which you may have), can create symbolic links, as can SymbolicLinker (link to www.macupdate.com), which is freeware.

However, there also exists the simple commandline tool, which is built into every Macintosh computer, and works with any version of OSX. All you need to know are the two locations where you want to the Sword folder to be accessible, and which location from which you want to create your symbolic link. Once this is known, you simply need to paste the proper command into your Terminal.app, and hit return. The first thing you need to do is find and launch your Terminal.app. This is found inside the "Utilities" folder inside your "Applications" folder, where all your applications are stored. Once you have launched your Terminal.app, you will see a window, and a line of text that ends with a dollar sign: $. Next to that, you should see a block cursor. This is where you will paste in one of the following commands.

To start with the Eloquent's "Sword" folder, located in the Application Support folder, and to create the symbolic link to the invisible ".sword" folder inside your user's Home folder, copy, and paste the following command into your Terminal window and hit return:

ln -s ~/Library/Application\ Support/Sword ~/.sword

To start with the invisible ".sword" folder (used by BibleTime and other apps), and to create a symbolic link for Eloquent to use, inside the Application Support folder, copy, and paste the following command into your Terminal window and hit return:

ln -s ~/.sword ~/Library/Application\ Support/Sword

Setting up Eloquent

When you first launch Eloquent, if you haven't had a chance to install any modules, the first thing you will need to do is install modules. The screencast you want to watch to help you through this process has already been mentioned, so we will skip over the module installation. All that is worth mentioning here is that if you wish to add modules in the future, you can access the module installer by looking for it in the "Eloquent" menu. The keyboard shortcut for it is <shift>-<command>-M. The next thing you will want to do is look at the preferences. As is normal for Macintosh applications, these are found in the "Eloquent" menu. The first pane you will see is the "General" preferences. Here you will want to choose your default Bible (which will be the Bible version you see when you hover the mouse over hot-clickable references, as well as on other occasions). You may also wish to change your default dictionary, but not necessarily your default Greek and Hebrew dictionaries. If you want to use Eloquent for daily Bible reading, you can add this here as well, under the "Daily Devotion" popup menu. If you do choose one, you can also check on the "Show on startup" check box, to have your reading show up when you start Eloquent.

Under the "Display" preferences tab, under the sub-section titled "Display defaults", you can choose what default font to use, as well as whether to display verses together in paragraph form, or separately. This option is titled "Show Verses on one line." Checking this option will separate the verses. Unchecking it will display them unbroken, in paragraph form. Verses on one line is better for displaying multiple versions in parallel, and unchecking this option is good for reading passages in one version. This option can also be toggled in the main window, as can other options, including the ones displayed on this page. For verse numbering, you can choose to always show full verse numbering (including book and chapter), or just the verse numbers, or hide them all together. Combining this last one, together with unchecking "Show Verses on one line" provides the most seamless experience for reading, and is heartily recommended if you wish to read the text without distraction.

Under the second sub-section, titled "Text display" are options that are best to leave alone until you are more familiar with Eloquent. The defaults should work fine.

The next two preference panes–"Module fonts" and "Printing"–are also probably best left to explore later. The defaults should work for you. Under printing, you can change the margins, as well as change to printing centered both horizontally and vertically.

Understanding the interface

While Eloquent is simple enough to start working, but in order to get the most out of Eloquent, it is best to understand its understanding of windows, and the uses of each, as well as how to navigate around them.

To begin, it is best to understand a little big about the various kinds of Sword modules. There are four general kinds of Sword modules:

• Text modules: Bible texts in any of over 50 languages.
• Commentary: Bible commentaries, containing verse-by-verse or passage-by-passage comments. These can be displayed parallel with text modules.
• Dictionary: These are dictionary and glossary modules. They can be bi-lingual or for one language. The Strongs dictionaries and the KJV Dictionary are examples of the two different kinds of dictionary modules. These modules have a different kind of display window from text and commentary modules, and cannot be displayed in parallel with them.
• Genbook or general book. These are quite simply books. In the Sword project, these are frequently graphics and map resources, but there are also other general works available. One example is the book, The Pilgrim's Progress by John Bunyan.

Understanding WorkSpaces, Single windows and Sessions

There are two different kinds of windows in Eloquent. They are Workspace windows and Single windows. A Workspace window can contain multiple tabs, containing any one or more of the various types of Sword modules, hence the name "workspace" as you can contain several resources connected to a project in several tabs in one window. A Single window can only contain either text and commentaries, or a single commentary, or a single dictionary or general book. A single window is what opens when a link from another application is opened in Eloquent (more on that later), and is also useful if you wish to concentrate on book or text without distraction. We will be describing these two sorts of windows in greater detail below.

The Workspace Window

The Workspace window is the most flexible, and also potentially the most complicated. It also looks identical to a Single Bible host window, so we will cover that first. At the top of this window are several buttons, as well as a text entry box.

• Left Sidebar: toggles the display of installed modules, bookmarks and notes.
• Search type selector: Choose between verse reference or text search modes.
• Text entry box: Enter the reference text or search text, depending on mode selected.
• Add bookmark: Add a bookmark, or add a reference to a bookmark file.
• Refresh: Reloads the display in the window.
• Fullscreen: Turns on Fullscreen mode (option-command-F cancels this mode)
• Right sidebar: Toggles display of the table of contents for the current work.

Left Sidebar

The left sidebar contains a list of all installed modules beneath a hierarchy of disclosure triangles. Clicking on a triangle toggles the display of what's under it. The same is true for Bookmarks and Notes. Double-clicking on any item will open that item in a new tab. In a Single window, double-clicking will open a new Single window. It is worth noting that the two sidebars are both resizable by dragging the separator line between them and the main window.

Right Sidebar

The right sidebar displays a table of contents of the currently open work. For Scripture and commentaries, this displays the books and chapters of the Bible. For lexicons and dictionaries, this displays the entries, and for daily reading plans, the days of the year, and for general books, the original table of contents of the book.

Main Window

The main part of a Workspace window contains the text of whatever you are reading, while above the various toggles and options–module-specific options, display options, font size and for Scripture, text context. This last option is useful if you are searching or viewing single verses, and wish to see the verses surrounding the displayed verses. You can choose to view between no verses to an extra of ten verses before and after the displayed or found verses. This helps to see the context in which the verse lies, to aid in understanding, and without having to enlarge the selection or change modes or views.

Underneath these options are the tabs. Each tab can contain any module that Eloquent supports. Bible tabs can contain multiple versions displayed in parallel, as well as commentaries. The means of doing this is rather simple and obvious, but worth explaining.

First of all, under the tabs, there is a little text box, containing the short name of the displayed text. Clicking on this pops up a menu. Choosing an item from this popup will change the text displayed in the main window to that module. Next to that is a small plus sign. Clicking on that displays another popup menu. From this, you can choose either a new Bible text pane or a new commentary text pane. Bible text panes will display in parallel with the original text, and commentaries will display below. Once this happens, you will see these same elements repeated for the newly displayed module. Clicking on any plus sign displayed with a Scripture text pane will allow you to select either a new Bible or commentary to display. Clicking on the plus sign in a commentary pane will only allow opening a new commentary pane. You can display up to five texts in parallel, though on smaller screens, you will likely not want to have that many open. Next to the plus sign is an X. This allows for closing the particular module connected with the X. It is also worth noting that the separators between Scriptures and commentaries are grab-able, allowing for the resizing of each pane.

The Single Window

The single window for Bible texts is almost identical to the Workspace window with the exception that it is not possible to add tabs. You are limited to one tab.

There are, however, other kinds of windows available in Single window mode:

• Commentary host: allows showing of one commentary. The right sidebar defaults to being open.
• Dictionary host: Displays the selected dictionary, with the right sidebar also displayed by default, showing the entries contained in the current dictionary.
• Genbook (general book) host: Displays the text of the selected general book. Again, the right sidebar displays its table of contents.

An odd quirk of the program is that if you use the File menu to create a new Single window, you need to next select a module before anything actually displays, even though the first module of the selected type shows in the popup selector. If you open a new Single window, and wonder why it's blank, it's because you have not yet selected a module.

Sessions

Sessions are powerful tools which allow you to save all the currently open windows for use later. For instance, if you are working on three different sermons in a week, each of which is a multi-week series, and wish to keep them separate. You would use Sessions to accomplish this. When you wish to save your session, simply go to the File menu, and choose "Save Session As..." to give it a name, choose its location and save it. Now, you can later open the session, either by double-clicking on its file in the Finder, or by choosing "Open Session..." in the File menu. If you want to re-save a session, you will need to choose "Save Session As..." again. A shortcut to get the same name is to navigate to the file in the Save Session window, and click on the file name in the file list. This will automatically paste it into the "save as" name for you. Then it's a simple matter of clicking on "Save" to save the session. You can, of course, maintain multiple sessions. You might find it advantageous, if you find yourself using Sessions a lot, to create a folder just for your saved Session files.

Navigating the Bible view and Search modes

Eloquent has two different modes for finding and viewing Bible texts. You can either find Bible text by entering the reference or by doing a text search. At the top of a workspace or text window, and to the left of the text search box, is a double-button. Clicking on the left side so it looks indented, allows for typing in references. You can enter non-contiguous sections of Scripture. For instance, you can type "Gen 1; John 1:1-12; John 3:16; Psalm 1:1" and view these verses in the order you entered them. This allows for very flexible display of Bible text.

Working with tabs

Tabs are easy to work with. In fact, it's not even necessary to access the menu to create and delete them. Simply clicking on the small plus sign contained in a grey circle to the right of the last tab will create a new one, and clicking the X contained in a grey circle to the left of the tab's title will close that tab. While it is possible to right-click or control-click on a tab title and open a tab into its own Single window, it is not possible to rearrange tabs, nor move between workspaces. Also unfortunately, there is no way to navigate between tabs via the keyboard. Hopefully, these are features that will be added to a future version of the program.

Digging deeper

The following section shows how to get the most out of Eloquent. Like most useful software, there is a lot of power hidden under the simple interface. Unleashing this power is what this section is about.

Searching

Most people, when they think of Bible software, think of searching the Bible. Eloquent, of course, meets the basic needs, and does so in its own way. It is excellent at searching, but it helps to understand and know its unique ways.

To start off, it may be that you have closed the right sidebar in Eloquent while in Bible view mode. When you search, you will probably want the right sidebar visible. First, let's set the window to search mode by clicking on the right side of the "search mode" button next to the text entry area (the magnifying glass in the circle). Next you can click on the right sidebar button to make the right sidebar visible. You will see that you will no longer see the table of contents, but a list of the Bible book names, with check boxes next to them. Above them a pop-up menu displaying the text "Temporary." Let's click on that, and see some preset search range values. They should be familiar: "All, Law, Prophets, Scriptures, Gospels, Letters". The OT divisions are, of course, the ancient Hebrew divisions. Selecting one of these will check and uncheck Bible books in the list below to match your selection. These check-marked books define your search range for when you perform searches, as you probably already guessed. You can also define your own search ranges. Let's create a range of just Paul's epistles. Let's start by finding the text entry field at the bottom of the right sidebar, below the text "Name". Enter the name for your range, and click on the "Add" button. Next, click on the checkboxes next to each of Paul's letters. That's it. If you wish to modify your selection, simply choose your custom range from the popup, and make your modifications. That's it. it is a bit backward, in that you don't select your books first, and then name the selection, but create the custom range by naming it, and then "filling it in."

Now that we understand search ranges, we can also move beyond simple searches. It is worth pointing out, that Eloquent does not perform searches in the same way that Accordance does. Accordance searches are predisposed to find exact matches to the search text. In other words, if you search for the phrase "kingdom of heaven" (without the quotes), it will only find the exact phrase. In order to find verses that contain all three words, but not exactly in that order, one has to add search operators. This is not to say that there is anything wrong with Accordance's method, but it is different from how Eloquent performs searches. Eloquent is predisposed to performing searches more similar to how Google works, namely searching for all the words in your search criteria, but not an exact phrase match. So, "kingdom of heaven" (without the quotes) will find 2 Chronicles 2:12, which reads: "Huram said moreover, Blessed be the LORD God of Israel, that made heaven and earth, who hath given to David the king a wise son, endued with prudence and understanding, that might build an house for the LORD, and an house for his kingdom." Notice that all three words are in this verse, but in a completely different order, and not together. In order to search for an exact phrase in Eloquent, you need to surround the search text in quotation marks, like so: "kingdom of heaven" (with the quotes). Eloquent can use operators, namely AND and OR as well as AND NOT. Notice that they are in all capital letters, "AND" or "OR". Honestly, the AND operator is only essential if you use the OR and/or AND NOT operators in a search phrase as well. You can also use parentheses and the wildcard character (*) in search phrases. The wildcard needs to be either at the beginning or end of a word, and not in the middle. An example of a more complicated search is as such ["kingdom of" (heaven OR God)] A similar search, but one which will return a different result (101 hits instead of 105) is such: ["kingdom of heaven" OR "kingdom of God"]. This second search will only find exact matches, and is probably more what you would be interested in searching for, unless you actually wanted a broader search. The key to any complex search is to isolate the items you wish to search for. In our example above, we wanted to find "Kingdom of" in every verse, and then, either "Heaven" or "God" to find either "kingdom of heaven" or "kingdom of God". To achieve this, we isolated the first expression in quotes, as we needed to find these two words together. Then, we isolated via parentheses the next two words, and allowed the search to choose between either the one or the other with the OR operator. By putting them in the parentheses, we told Eloquent that one of the terms needed to be there, as well as the exact phrase that we isolated within the quotation marks. Now, if we had tried to put the quotation marks outside the entire phrase, the search would have failed to return any results. If we had removed the quotes (and kept the entire Bible as our search range, we would have gathered more results. This form of complex search certainly requires either a decent understanding of logic, or a lot of trial and error–or, more likely, both. But this is a problem that would occur regardless of which software you chose. The more complex the query, the more careful you have to be, and the more you have to think through the query format. In other words, feel free to experiment, and try not to get frustrated if you don't get the results you think you are asking for.

Using Bookmarks

The bookmark feature somewhat of a sleeper. By this, I mean that it hides a fair bit of power in a rather unassuming interface. You might not realize the power and flexibility contained therein. Hence this guide.

Overview

Let's start by looking quickly at the various elements you will see. Before you have added any bookmarks, all you will see in the left sidebar is the title "Bookmarks" with a disclosure triangle to its left. Clicking on the triangle to point it downwards will, of course, disclose nothing. We need to create a bookmark.

Creating a bookmark

There are two ways to create a new bookmark. The first is to first click on the "BOOKMARKS" sidebar text, then right-click or control-click on the title. This pops up a contextual menu, the first item of which is named "Add New Bookmark..." Choosing this opens a new window into which you can enter the Bookmark's name, its reference, and an optional comment field for comments. For instance, let's create a new one and call it "God so loved..." and for the reference, John 3:16. We can enter into the comments field whatever we like, but let's write "Verses concerning God's love toward mankind". Even better, you can see below the comments field the option to add highlight colors! You can choose both foreground and background using Apple's color picker tool. The default is, of course, the color wheel, but with its nearly infinite variety of colors, you may wish to choose another color palette. At the top of the color picker you should see several icons. Clicking on the icon with small blocks of color, you can choose among a few, simpler color palettes. I believe that Apple also provides a crayon box palette. This is a fun, and surprisingly simple palette from which to choose. With the ability to choose both foreground and background colors, the potential variety is endless–but it is best to not go overboard, and only save the highlight colors for more universal items, or potentially, for a long-term study project. But honestly, this depends on your imagination.

Adding verses to a bookmark

At this point you may ask, "How come, if we can only put one verse per bookmark, I named my bookmark as I did, and entered the comment field as I did?" The answer lies in the fact that bookmarks can contain any number of verses. Just like in the Scripture entry field above you can enter multiple references (using the normal conventions for separating verses, chapters and books), you can do this with bookmarks. But first, we will show you a simpler way to add verses to a bookmark. First, let's do a word search for "Christ AND love*". This returns several verses, starting with Romans 5:8. Suppose we want to add Rom. 5:8, 8:35 and 8:39 (I used the KJV text, so your search result may differ if you use a different version). Simply drag to highlight all three verses, making sure to include all three references in the selection. Now, you right-click or control-click to open the contextual menu, and find the "Add Verses to Bookmark" submenu, which will now show your Bookmark in the popup list. Select it, and the verses are now added. It's that simple. Any displayed verse can be added to any bookmark list on the fly with this method.

Editing a bookmark

Of course, you can also single-click to select the bookmark in the sidebar, and then right-click or control-click to open the contextual menu and manually edit a bookmark, but this method is much easier for adding. You will need to use the manual method to remove verses, so it is wise to remember this.

In fact, while we are looking at the contextual menu for the bookmark in the sidebar, notice all the options, including deleting, and opening a bookmark in a new view. Unless you always want to overwrite the current contents in a tab, you will want to remember this last option. The contextual menu is also the way you will delete a bookmark when it is no longer needed.

Creating Bookmark Folders

One last option in this contextual menu we have not yet discussed is that of folders. You can move bookmarks to folders you create using the contextual menu. With folders, you can group bookmarks based on topics, or maybe based on Bible books, or sections of the Bible, or based on sermons or Bible studies. Again, your imagination is the limit. As an example, I am doing a series of studies I call "Heroes of faith in the OT". Each person gets his own bookmark file in a folder I've titled "Bohaterowie wiary" (the Polish title). When I'm not working on this series, the folder is closed with the disclosure triangle, so I don't need to be distracted by them when I don't need them (I will be doing 12 different people by the time I'm done, so 12 different bookmarks always visible would be quite distracting).

Summary

So, you can see that the bookmark facility, while quite simple, is also quite flexible and powerful. Bookmarks is one of my favorite features of Eloquent.

Using Notes

The Notes feature is another unassuming and easily overlooked feature of Eloquent. However, it also hides a wealth of functionality that, while maybe not as simple in usage as the Bookmark feature, is nevertheless available. It also helps to be willing to navigate to a folder in your Library, should you ever want to view a particular note outside of Eloquent. Eloquent creates the notes as separate rtf files in its folder inside your user's Library's "Application Support" folder. The exact location path is this: [your user home folder]/Library/Application Support/Eloquent/Notes/. If this geeky way of writing it confuses you, go to your Finder, click on your home folder in your Finder's sidebar, and find your "Library" folder. Next, inside there, locate your "Application Support" folder. Inside that folder, find the "Eloquent" folder, and inside there, you should find a folder named "Notes". This is where Eloquent will store all your notes files as rtf (rich text format) files. This is the file format that TextEdit also uses, and is Apple's default text format for read me files, etc. It is a simple, and universally-recognized format that was originally created by Microsoft! But now it is an open and cross-platform format. This format, however, hides a lot of formatting power inside, which Eloquent is able to take advantage of. So, let's take a look at what you can do.

Creating a note

First, we need to create a new note. The most obvious way is, of course, to go to the "File" menu. However, instead of the normal "New" option, you will find the menu item, "Create Study Note". This is the menu item you want. Choosing this opens a new, blank window. An alternate method for creating a new Note is to single-click on the "NOTES" title in the left sidebar, and then right-click or control-click on it to open up the contextual menu. You will notice two items that you can choose: "Add new note" and "Add new folder". Folders work just the same for notes as they do for bookmarks, and pretty much everywhere folders are used on the Mac. If you were to single-click on an already-created note, you would have other options available when you right-click on its name in the sidebar, which options are currently greyed-out, but you can quickly see what those options are now, while you have the contextual menu open. We will discuss those in depth later. For now, you only need to know that you can create either a new note or new note folder with this contextual menu in the sidebar.

Editing a note

At its simplest, a note is text. You can write to your heart's content, and even add formatting using Apple's conventional keyboard shortcuts. But above the large text entry area are two items, Rulers and the Font popup menu. The Rulers item displays the formatting ruler. If you use TextEdit much, you will immediately recognize this ruler, and know how to use it–in fact if you have spent any time editing documents in a word processor, you will recognize the ruler and how to use it. One item of note, however, is the "Lists" popup menu. You can actually use Eloquent's notes to create outlines. It is quite flexible, and works identically to how TextEdit works, because it is based on Apple's TextEdit engine. In fact, if you navigate to the note file in your Finder (see above), and double-click the file, it will open in TextEdit, and you can edit the file there, even on a Mac that doesn't contain Eloquent. In fact, you can email these files to people who use Windows computers, and the files should open up with their formatting intact, or at least nearly so (depending on their software, of course–not all applications open rtf files properly, and sometimes ignore certain formatting features that rtf files are capable of–for instance, TextEdit and Eloquent ignore footnotes and endnotes, which rtf handles perfectly).

Using the various lists, once you choose a particular list format for a particular level, that format will remain until you leave the outline. So, for instance, choosing the Roman numeral list for the top level will retain that list until you leave the outline. Choosing the capital letters for the next level will retain that format for the second level, and so on. Of course you can choose whatever list format you wish. The lists feature for outlining is flexible, but not structured. You will have to create your structure. Some people require more structure from their outlining software, so this may not be for you, but if you appreciate this flexibility and simplicity, you will appreciate Eloquent's outlining capability.

Entering Scripture links

You may ask why bother using Eloquent to write your sermons, or create extensive notes. Well, one good reason is because of the ease with which one can create hot-links to Scripture references. We will talk more about how Eloquent takes full advantage of the sword url capability, but for now, let is suffice to say that if you wish to create links from within Eloquent, the program does all the dirty work for you. All you have to do is write the reference, even using the common abbreviations for book names, highlight the text, and then right-click or control-click on the highlighted text, and from the contextual menu, choose "Create verse link". Eloquent will auto-sense the reference, and create a hot-link for you. Now, when you click on the link, a new Eloquent single window will open with the reference(s) showing. Now, the downside of this method exists for those who wish to write in another language, or maybe use labels that don't contain the verse reference. In such cases, you will want to read below about how to create links within other programs.

Summary

One point worth remembering is that above the main text entry area is a "Save" button. You need to remember to click on that on occasion. It is not worth risking losing any amount of work forgetting to save. Save frequently, as with any word processing software. Since the Notes editor is based on TextEdit, and normal word processing principles, its use should be familiar to most of us, and again, its simplicity allows for much exploration and experimentation. Taking full advantage of this will reward greatly. It is also worth remembering and using the folders feature for Notes, just like for Bookmarks.

Even deeper

Personal Commentary

It is possible to create your own personal commentary. The best way to do this is to not download the personal commentary file from the Sword repositories, but to create one via the File menu. Under the File menu, you will see a menu item named, "Create module" This item has a submenu with one item in it–"Personal Commentary". You need to give your personal commentary a name, and then you will have created a personal commentary module. You can find this module under the "Commentaries" subsection under "MODULES" in the left sidebar. However, the best way to access your personal commentary is probably in parallel with a Scripture module. So, when you have a Scripture reference opened to where you want it, click on the plus sign next to its name, just like you would for opening any other Bible version or commentary module in parallel, and choose your personal commentary module.

When your personal commentary opens, you will notice one minor difference between its display and a normal module. Next to the X sign, to the right of the module's name, you will see the word "Edit". When you click on this, you will be able to edit your personal commentary module. The word "Edit" will turn red, thus indicating that you are in Edit mode. Simply write your text under the verse reference you want to write about, and when you are done, click on "Edit" again, and your changes will be saved, and the word "Edit" will change to black text again.

Unfortunately, I must give a very large caveat in regards to editing personal commentary modules. While the author of the app has been working hard to stamp out all the bugs related with editing commentary modules, it seems that they are not so easy to fix. Navigating away from the verse you are editing will lose any changes you have made, if you do not first turn off editing mode. Unfortunately, it is very easy to accidentally navigate away from your verse without thinking, so when editing personal commentary modules, be very sure to be very careful to save your changes frequently. In fact, I would encourage you, if you find odd behavior when editing modules, that you document what happened, and contact the author. He is eager to receive these bug reports, and wishes to clear up all problems with the program. So, with the huge caveat of save early and save often, and be careful what you do, let's create user notes.

Hot links within Personal commentary modules

We have already discussed how you create hot-links from within the Notes editor. But you can also create them from within the personal commentary module. However, the method for creating personal links while editing commentary modules is much different than from within Notes. The method for creating links within a personal commentary is done using Sword's url syntax. That's right, url syntax. In other words, you create a link, just like you would for a web page within html code. This may scare you at first, but honestly, it is very simple once you learn the syntax. The syntax, while simple, does need to be exact. A seemingly minor error (like forgetting to end a url with the quotation marks) can spell disaster, with further notes not appearing at all, in a worst-case scenario.

Here is the syntax: <a href="sword://[Bible version short name]/[reference]">Title</a>

Here is the breakdown of what you see:

"a href" means that the following text is a url link. You will notice that this begins with an open caret. Next, you will see the equal sign and a quote mark. After those two, you will see the actual link. It has to start with the "sword://" part. Next, you would need to replace the "[Bible version short name]" with the short name for the version you want to use. You can find this in the Bible texts section in the left sidebar. The text you see there is what you will want to use. Some that I have are ESV, KJV, WEB, NET, WHNU and Tyndale. Next, after the "/" character, is the [reference], which you replace with the scripture reference you want. Unfortunately, in the personal commentary section, I have been unable to enter more than one verse or verse range (e.g. John 1:1-18) in a reference at a time. So it seems you will need to enter each chapter and verse separately. However, it is worth experimenting and seeing what you can squeeze out. After the verse reference, is a closing quote and closing caret. These are essential. Do not forget them! After that, you enter your title, which should be the reference again, but you can give it another title if you wish. I have had mixed results with this. If I have to go back and edit later, sometimes the title I've given a reference has been replaced with the default verse reference. At the very end, you need to also ad the "/a" surrounded by the carets. This closes the "a href" code, and makes the link work. Again, DO NOT forget to add this!

Here is are some examples:

<a href="sword://KJV/John 1:1">John 1:1</a>

<a href="sword://ESV/Rom%208:28">Romans 8:28</a>

<a href="sword://PL_BW/Mat 6:33">Ewangelia Mateusza 6, 33</a>

A couple notes about the references above: In the second reference, you will see an odd bit of text added between the "Rom" and the verse numbers. ("%20"). This is html code and represents the space character. url links are not allowed to contain a space character, so this is necessary for the link to work. However, Eloquent will actually perform this service for you–adding in this code, so you don't have to. I added it here so you can see what your link will look like properly formatted. In the third link, I have referenced a Polish Bible, and in the title wrote my verse reference in Polish, with Polish verse notation. This is to show that one need not write the title in English, or even write the reference. That said, as I mentioned above, this feature is a bit buggy, and I have found my titles changed back to English verse notation for a reference on occasion.

Summary

The personal commentary feature is quite useful and powerful, once you learn how to enter Scripture references. Do this a few times, and the html code necessary to use will become second nature. But the best part about learning to use the "a href" code stems from the fact that you can use this in any program that allows entering url hotlinks! But we will discuss that in the next section.

Hot links from other programs

This feature is one feature that really sets Eloquent apart from all the competition in the Mac market. As far as I know, no other Bible software offers this option. To summarize, this feature allows you to add a url hyperlink into just about any application that allows hot links, and then be able to click on that link to open up Eloquent to the desired location in just about any Sword module that you have in Eloquent (certainly any that uses Scripture references). More useful is that if someone else has a Sword Project application installed, and the same module, they can also open the link.

Since my main word processor application is Nisus Writer Pro, I have found this feature to be an essential tool for when I am writing. I can enter Scripture references as I go, and quickly look up a verse reference as I need it. What makes Nisus especially powerful, however, is that while on-screen the hyperlinks are colored and underlined, when I print, these are not visible. The Scripture reference looks just like the surrounding text, so for my own use, I have the hot links, but for printing, I have perfect and normal printout.

I have also had success with the sword url working in DevonThink products, TextEdit, and pdfs in Preview. If you are able to get this to work in other applications, we would encourage you to add your contribution to this section of the page, or at least contact the editors so they can add in your contribution. Some other word processors that immediately come to mind that are worth learning about are Mellel, Mariner Write and Microsoft Office. We would appreciate contributions regarding these programs.

Unfortunately, it seems that Pages has a very limited ability to enter hyperlinks, allowing only web pages, emails, bookmarks within a document or to other Pages documents. There does not seem to be any ability to link to other resources (even such as ftp urls!). If you figure out a way to get the sword:// url to work in Pages, please edit this page to share how you get it to work.

Using hot links in Nisus

First of all, we need to remember the syntax necessary for creating the hyperlinks that will open Eloquent. The syntax is typical html code:

<a href="sword://[BibleVersionShortName]/[Reference 1:1">Link Title</a>

And an example:

<a href="sword://KJV/John 1:1">John 1:1</a>

Now, let's create this link in Nisus Writer.

The first step is to write what will be your link title: John 1:1.

Next, we will select this reference. Once the text is selected, we go to the "Insert" menu. At the bottom of this menu, you will see the "Hyperlinks" sub menu. The very first item in the sub-menu is "Add Link..." Choosing that pops up an drop-down pane where you can enter the actual link, and its link title. (The nomenclature in Nisus Writer Pro is "Link destination" and "Display text" Into the top field is where we enter the html code, and the bottom field is where you enter the link title (reference, or whatever you want). Now, when you've highlighted the text before invoking the "Insert Link" menu item, the bottom field will already be filled out for you. Enter your link, and click on the "Insert" button, and your hot link is now inserted into your text.

Now, you may ask if there is a keyboard shortcut. I don't remember if Nisus Writer Pro comes with one by default, but my copy uses Shift-Command-H. This is easy to add. First open Nisus' Preferences, and find the Menu Keys Preference Pane. Navigate to the "Insert" menu, and find the "Hyperlinks" sub-menu, and then the "Add link..." menu item, and add the keyboard shortcut you prefer.

External Links

• MacSword Home

• New Eloquent Home

Credits

This page was written by CATUG Board member Jon Glass in February–April 2011.