Eloquent

Mac Sword This page is a work in progress, but will hopefully be added to over the coming weeks.

About MacSword

First of all, what is MacSword?

MacSword is OpenSource Bible software, under the GNU General Public License for the Macintosh. It is based on the Sword Project. Because of this, it is compatible with all of the Sword Project modules. (According to the MacSword 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, one can also create their own modules. In fact, it is the fact that MacSword 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, 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, Window-based or Linux-based computer. Furthermore, there are also programs for the iPhone (PocketSword) and Android (AndBible), as well, which also use the Sword Project modules. Because of its open-source nature, MacSword 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.

Installing MacSword

Installing MacSword is as simple as downloading a dmg file from the MacSword web site's MacSword 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.

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: Module Installer Movie. It is not immediately apparent where MacSword installs the modules, so I shall say a word or two here. By default, MacSword 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 MacSword. 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 titled "Setting Up MacSword." (can this be made a link?)

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 MacSword if it's running. Any modules you manually install won't be available to MacSword 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 MacSword 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 MacSword 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 MacSword'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 MacSword 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 MacSword

When you first launch MacSword, 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 "MacSword" 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 "MacSword" 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 MacSword 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 MacSword.

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 MacSword. 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 MacSword is simple enough to start working, but in order to get the most out of MacSword, 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 MacSword. 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 MacSword (more on that later), and is also useful if you wish to concentrate on book or text without distraction.

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.

External Links

MacSword Home