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.

Credits

This page is a work in progress written by CMUG Board member Jon Glass in February 2011, and will hopefully be added to over the coming weeks.

External Links

MacSword Home

New Eloquent Home