Difference between revisions of "Frontends:Eloquent"

From CrossWire Bible Society
Jump to: navigation, search
(Search index)
Line 1: Line 1:
'''MacSword''' is an open source Study Bible software that uses the [[DevTools:SWORD|SWORD API]]. It was made for Mac OS X.
+
'''Eloquent''' is an open source Study Bible software that uses the [[DevTools:SWORD|SWORD API]]. It was made for Mac OS X.
  
 
Anyone willing to provide screenshots should do so below, or edit this further.
 
Anyone willing to provide screenshots should do so below, or edit this further.
Line 17: Line 17:
 
* Commentaries
 
* Commentaries
 
* Dictionaries
 
* Dictionaries
* Development is ongoing on both SWORD libs and MacSword, so check back every so often.
+
* Development is ongoing on both SWORD libs and Eloquent, so check back every so often.
  
 
== Installation notes ==
 
== Installation notes ==
Line 26: Line 26:
  
 
===Manually installing modules===
 
===Manually installing modules===
The download of MacSword application does not include any modules (bibles, dictionaries, etc.). You need to download them manually from the Crosswire website.
+
The download of Eloquent application does not include any modules (bibles, dictionaries, etc.). You need to download them manually from the Crosswire website.
For MacSword special modules (.swd) are available which have to be placed into the folder (if the folder does not exist, please create it first):
+
For Eloquent special modules (.swd) are available which have to be placed into the folder (if the folder does not exist, please create it first):
  
 
/Users/<username>/Library/Application Support/Sword
 
/Users/<username>/Library/Application Support/Sword
Line 34: Line 34:
 
For MacSword version 1.3.1b2 and above this location is preset and it does not need to be changed. Just place your downloaded modules in the above mentioned folder.
 
For MacSword version 1.3.1b2 and above this location is preset and it does not need to be changed. Just place your downloaded modules in the above mentioned folder.
  
MacSword 2 does not have this setting in preferences. This path is the only pre-defined module path in MacSword 2.
+
Eloquent does not have this setting in preferences. This path is the only pre-defined module path in Eloquent.
  
 
===Using the automatic module installer===
 
===Using the automatic module installer===
 
Since MacSword version 1.4 a remote module installer is available for your convenience. It is accessible right below the "Preferences" menu item in the main menu bar of the application.
 
Since MacSword version 1.4 a remote module installer is available for your convenience. It is accessible right below the "Preferences" menu item in the main menu bar of the application.
 
The principal workflow is that you have at least one "install source" which are displayed on the left side. Each install source can have available modules which can be installed.
 
The principal workflow is that you have at least one "install source" which are displayed on the left side. Each install source can have available modules which can be installed.
On the first start of MacSword the default install source ("CrossWire") is automatically created for you. However you still need to refresh the install source in order to load module informations.
+
On the first start of Eloquent the default install source ("CrossWire") is automatically created for you. However you still need to refresh the install source in order to load module informations.
  
 
'''Refreshing install sources:'''
 
'''Refreshing install sources:'''
Line 56: Line 56:
 
== Creating/Editing Personal Commentary modules ==
 
== Creating/Editing Personal Commentary modules ==
  
Both MacSword 1.4 and MacSword 2 support creating new personal commentary modules and editing them.
+
Both MacSword 1.4 and Eloquent support creating new personal commentary modules and editing them.
  
 
===Creating personal commentary modules===
 
===Creating personal commentary modules===
Line 68: Line 68:
 
The name should if possible not contain special characters and no spaces. Instead of spaces use underscore "_" or use a camel case naming scheme like "MyPersComment".
 
The name should if possible not contain special characters and no spaces. Instead of spaces use underscore "_" or use a camel case naming scheme like "MyPersComment".
  
''MacSword 2 series:''
+
''Eloquent series:''
  
 
In the main menu choose File->"Create Module"->"Personal Commentary". You are then asked for a module name (please see the naming scheme above).
 
In the main menu choose File->"Create Module"->"Personal Commentary". You are then asked for a module name (please see the naming scheme above).
Line 78: Line 78:
 
Open the personal commentary module. Navigate to a Bible chapter/Verse you want to comment. To start editing choose Edit->"Edit module" from the main menu. Enter your comments and choose Edit->"Edit module" again to end the editing. Your comment should now be saved.
 
Open the personal commentary module. Navigate to a Bible chapter/Verse you want to comment. To start editing choose Edit->"Edit module" from the main menu. Enter your comments and choose Edit->"Edit module" again to end the editing. Your comment should now be saved.
  
''MacSword 2 series:''
+
''Eloquent series:''
  
 
Open your personal commentary module. Navigate to a Bible chapter/verse. Press the "Edit" field which is on top of your text view next to the "+" and "x" fields. When in editing mode the "Edit" field should be in red color. Now enter your text between the verses. To store your text press the red "Edit" button again.
 
Open your personal commentary module. Navigate to a Bible chapter/verse. Press the "Edit" field which is on top of your text view next to the "+" and "x" fields. When in editing mode the "Edit" field should be in red color. Now enter your text between the verses. To store your text press the red "Edit" button again.
Line 85: Line 85:
  
 
=== Apple SearchKit searching (default) ===
 
=== Apple SearchKit searching (default) ===
MacSword relies on Apple SearchKit to interpret queries, to find matching terms. SearchKit interprets queries like this:
+
Eloquent relies on Apple SearchKit to interpret queries, to find matching terms. SearchKit interprets queries like this:
  
 
Searching for a single word will find terms where the name contains exactly that word. There is no implicit wild-card or stemming. For example, a search for ‘health’ will match ‘health’, ‘health matters’ and ‘good health’ but will not match ‘healthy living’.
 
Searching for a single word will find terms where the name contains exactly that word. There is no implicit wild-card or stemming. For example, a search for ‘health’ will match ‘health’, ‘health matters’ and ‘good health’ but will not match ‘healthy living’.
Line 119: Line 119:
 
=== Enabling the background indexer ===
 
=== Enabling the background indexer ===
  
From MacSword 2.2.11 on the background indexer feature can be re-enabled by modifying the MacSword defaults.
+
From MacSword 2.2.11 on and Eloquent the background indexer feature can be re-enabled by modifying the MacSword/Eloquent defaults.
 
The following command line will enable the background indexer:
 
The following command line will enable the background indexer:
  
 
defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled yes
 
defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled yes
 +
or
 +
defaults write org.crosswire.Eloquent DefaultsBackgroundIndexerEnabled yes
  
 
This will disable it again:
 
This will disable it again:
  
 
defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled no
 
defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled no
 +
or
 +
defaults write org.crosswire.Eloquent DefaultsBackgroundIndexerEnabled no
  
 
== Renaming Notes and Folders ==
 
== Renaming Notes and Folders ==
Line 135: Line 139:
 
* hit return on a selected Folder or Note   
 
* hit return on a selected Folder or Note   
  
== MacSword files and folders ==
+
== Eloquent files and folders ==
  
MacSword creates and uses certain files and folders on your hard drive.
+
Eloquent creates and uses certain files and folders on your hard drive.
  
 
==== Module database ====
 
==== Module database ====
Line 143: Line 147:
 
Are stored under ''~/Library/Application Support/Sword'' (where "~" is your home folder). These are mostly modules either manually copied there or downloaded using the module installer.
 
Are stored under ''~/Library/Application Support/Sword'' (where "~" is your home folder). These are mostly modules either manually copied there or downloaded using the module installer.
  
=== MacSword files ===
+
=== Eloquent files ===
  
Are stored and created under ''~/Library/Application Support/MacSword''. Those files are:
+
Are stored and created under ''~/Library/Application Support/Eloquent''. Those files are:
 
==== Module search index files ====
 
==== Module search index files ====
* Module index files. MacSword 1.4 and below store the module index files in folders directly under "MacSword" for example: "Index-KJV". MacSword 2.0 and above store all index files in a separate folder "Index".
+
* Module index files. MacSword 1.4 and below store the module index files in folders directly under "MacSword" for example: "Index-KJV". Eloquent stores all index files in a separate folder "Index".
Index files can easily be deleted. They are then simply re-created from within MacSword.
+
Index files can easily be deleted. They are then simply re-created from within Eloquent.
 
==== Dictionary caches ====
 
==== Dictionary caches ====
 
* Dictionary module caches: ''cache-<modulename>. Those file also can be deleted without problems. They are used to speedup the dictionary lookup and are re-created if they don't exist.
 
* Dictionary module caches: ''cache-<modulename>. Those file also can be deleted without problems. They are used to speedup the dictionary lookup and are re-created if they don't exist.
 
==== Bookmarks ====
 
==== Bookmarks ====
* Bookmarks are stored in a file: ''Bookmarklist.plist'' for MacSword >= 2.0 and ''Bookmarks.plist'' for MacSword <= 1.4. These files shouldn't be deleted otherwise you will loose your bookmarks.
+
* Bookmarks are stored in a file: ''Bookmarklist.plist'' for Eloquent >= 2.3 and ''Bookmarks.plist'' for MacSword <= 1.4. These files shouldn't be deleted otherwise you will loose your bookmarks.
 
==== Session files ====
 
==== Session files ====
* MacSword 2 default session file is: ''DefaultSession.plist''. This file stores you last opened session which includes open windows, positions, open modules and such...
+
* Eloquent default session file is: ''DefaultSession.plist''. This file stores you last opened session which includes open windows, positions, open modules and such...
* MacSword 2 also stores a file called: ''DefaultSearchBookSets.plist''. In this file custom, user defined search book sets for indexed search are stored.
+
* Eloquent also stores a file called: ''DefaultSearchBookSets.plist''. In this file custom, user defined search book sets for indexed search are stored.
  
 
=== Preferences ===  
 
=== Preferences ===  
 
Are stored under ''~/Library/Preferences'':
 
Are stored under ''~/Library/Preferences'':
 
* ''"MacSword.plist"'' for MacSword < 2.0
 
* ''"MacSword.plist"'' for MacSword < 2.0
* ''"org.crosswire.MacSword.plist"'' for MacSword >= 2.0
+
* ''"org.crosswire.Eloquent.plist"'' for Eloquent >= 2.3
  
 
== Module creator/developer support ==
 
== Module creator/developer support ==
  
MacSword 2.0.0 now bundles universal binaries of the SWORD module command line tools.
+
From MacSword 2.0 on it bundles universal binaries of the SWORD module command line tools.
 
Those tools can be found in the Application bundle under "Contents/Resources/bin".
 
Those tools can be found in the Application bundle under "Contents/Resources/bin".
  
Line 172: Line 176:
 
== What do I do if there are problems/crashes ==
 
== What do I do if there are problems/crashes ==
  
Experience shows that there are mainly two reasons which can cause a crash of MacSword 2.x:
+
Experience shows that there are mainly two reasons which can cause a crash of Eloquent:
* An old module installation causes MacSword to crash when this database is read on startup. This can be solved by deleting the folder: ''~/Library/Application Support/Sword''. See above for more information on files and folder in general.  
+
* An old MacSword 1.x module installation causes Eloquent to crash when this database is read on startup. This can be solved by deleting the folder: ''~/Library/Application Support/Sword''. See above for more information on files and folder in general.  
 
Versions from 2.2.2 will notify the user on startup if such a problem could occur, due to a detected old module installation. However, if you have run MacSword 2.x successfully before then this is not the reason of the crash.
 
Versions from 2.2.2 will notify the user on startup if such a problem could occur, due to a detected old module installation. However, if you have run MacSword 2.x successfully before then this is not the reason of the crash.
 
* The session file which stores windows and positions and other things got corrupted. This can also be solved by deleting the session file. See above where to find this file.
 
* The session file which stores windows and positions and other things got corrupted. This can also be solved by deleting the session file. See above where to find this file.
Line 182: Line 186:
  
 
== External links ==
 
== External links ==
*[http://www.macsword.com MacSword home page]
+
*[http://www.eloquent-bible-study.eu/ Eloquent home page]
 
*[https://sourceforge.net/projects/macsword/ SourceForge project page]
 
*[https://sourceforge.net/projects/macsword/ SourceForge project page]
 +
*[http://wiki.catug.org/Mac_Sword Brilliant information on this wiki by catug]
  
 
[[Category:SWORD Frontends|MacSword]]
 
[[Category:SWORD Frontends|MacSword]]

Revision as of 21:36, 4 May 2011

Eloquent is an open source Study Bible software that uses the SWORD API. It was made for Mac OS X.

Anyone willing to provide screenshots should do so below, or edit this further.

Features:

  • Supports multiple bible versions
  • Parallel view (up to five versions)
  • Commentaries, Dictionaries, General Books
  • Footnotes, Text notes, Cross References
  • Strongs Hebrew/Greek numbers
  • Morphological Analysis codes
  • Headings and other text formatting (Words of Christ in red)
  • Search function
  • Non-Latin script (Hebrew, Greek, etc)
  • Different Bible translations
  • Commentaries
  • Dictionaries
  • Development is ongoing on both SWORD libs and Eloquent, so check back every so often.

Installation notes

MacSword downloads from SourceForge for version 1.3.1b1 and above (see links below) is the application only. You can drop the application (once unzipped) anywhere on your hard disk.

Module installation

Manually installing modules

The download of Eloquent application does not include any modules (bibles, dictionaries, etc.). You need to download them manually from the Crosswire website. For Eloquent special modules (.swd) are available which have to be placed into the folder (if the folder does not exist, please create it first):

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

In MacSword under Preferences->Module you need to point the Modules location folder to be the folder mentioned above and then restart. For MacSword version 1.3.1b2 and above this location is preset and it does not need to be changed. Just place your downloaded modules in the above mentioned folder.

Eloquent does not have this setting in preferences. This path is the only pre-defined module path in Eloquent.

Using the automatic module installer

Since MacSword version 1.4 a remote module installer is available for your convenience. It is accessible right below the "Preferences" menu item in the main menu bar of the application. The principal workflow is that you have at least one "install source" which are displayed on the left side. Each install source can have available modules which can be installed. On the first start of Eloquent the default install source ("CrossWire") is automatically created for you. However you still need to refresh the install source in order to load module informations.

Refreshing install sources: After Install sources have been created or added they need to be refreshed first. The refresh action downloads available module descriptions onto your hard disk. Also, if you want to update the install source to recognise updated modules, refresh it. After it has been refreshed and you click on it, all available modules are displayed in the table view on the right.

Marking modules for installation: Search the module(s) you want to install and select the "Install" task in the "Task" column of the table. The "Task" column rows contain a popup menu which shows available tasks for the chosen module. Alternatively do right-click the module and select "Install". If you made your selection, choose "Process Tasks" from the toolbar. This will download and install your selected modules.

Marking modules for removal: Modules that are install and have the "Installed" status can be removed. This works similar as for installing modules, you just use the "Remove" task. After you marked all modules for removal, choose "Process Tasks" from the toolbar.

Creating/Editing Personal Commentary modules

Both MacSword 1.4 and Eloquent support creating new personal commentary modules and editing them.

Creating personal commentary modules

MacSword 1 series:

In the main menu choose File->"New Module". This will open a file panel. The preset path where the new module is stored should be: "/Users/<yourlogin>/Library/Application Support/Sword". If that's not the case, navigate to this folder. Then just enter a module name in the top text field and press Ok.

The name should if possible not contain special characters and no spaces. Instead of spaces use underscore "_" or use a camel case naming scheme like "MyPersComment".

Eloquent series:

In the main menu choose File->"Create Module"->"Personal Commentary". You are then asked for a module name (please see the naming scheme above).

Editing personal commentary modules

MacSword 1 series:

Open the personal commentary module. Navigate to a Bible chapter/Verse you want to comment. To start editing choose Edit->"Edit module" from the main menu. Enter your comments and choose Edit->"Edit module" again to end the editing. Your comment should now be saved.

Eloquent series:

Open your personal commentary module. Navigate to a Bible chapter/verse. Press the "Edit" field which is on top of your text view next to the "+" and "x" fields. When in editing mode the "Edit" field should be in red color. Now enter your text between the verses. To store your text press the red "Edit" button again.

Search index

Apple SearchKit searching (default)

Eloquent relies on Apple SearchKit to interpret queries, to find matching terms. SearchKit interprets queries like this:

Searching for a single word will find terms where the name contains exactly that word. There is no implicit wild-card or stemming. For example, a search for ‘health’ will match ‘health’, ‘health matters’ and ‘good health’ but will not match ‘healthy living’.

Asterisks can be used as wildcards, providing that they are at the beginning and/or end of a word:

Searching for ‘hea*’ will match ‘health’ and ‘heart’. Searching for ‘*lth’ will match ‘health’ and ‘wealth’. Searching for ‘*eal*’ will match both ‘health’ and ‘wealth’. Note that an asterisk can not be embedded within a word. Searching for ‘he*lth’ is interpreted as being a search for ‘he*’.

Spaces between words in a query imply OR. A search for ‘health wealth’ is the same as a search for ‘health OR wealth’ and will match both ‘health matters’ and ‘wealth matters not’.

Enclosing words in double-quotes implies AND. A search for “health wealth” is the same as a search for ‘health AND wealth’ and will only return terms containing both words.

You can use parentheses to construct more complex queries. For example:

(life AND health) OR (wealth AND happiness) To exclude a word, use AND NOT as in ‘wealth AND NOT happiness’.

Searches are case-insensitive. A search for ‘health’ will match ‘Health’ and ‘HEALTH’. However, the Boolean operators AND, OR and NOT are case sensitive and must be typed in upper case.

Searching for Strong's numbers

The Strong's number you are looking for has to be prefixed by "h" or "g". For example, to search for the Strong's number "07225" for "beginning" in Gen 1:1 you'll search for "h07225".

Creating Clucene index

Since MacSword 2.2.4 it is possible to create a Clucene index which can be used else where for example to upload it to PocketSword.

To create this index you have to right-click on any module in left side bar tree view and choose "Create Clucene index". The index will be created in the module data folder. For example: if you create an index for ESV then the clucene index files are at ~/Library/Application Support/Sword/modules/texts/ztext/esv/lucene (where "~" is your home folder).

Enabling the background indexer

From MacSword 2.2.11 on and Eloquent the background indexer feature can be re-enabled by modifying the MacSword/Eloquent defaults. The following command line will enable the background indexer:

defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled yes or defaults write org.crosswire.Eloquent DefaultsBackgroundIndexerEnabled yes

This will disable it again:

defaults write org.crosswire.MacSword DefaultsBackgroundIndexerEnabled no or defaults write org.crosswire.Eloquent DefaultsBackgroundIndexerEnabled no

Renaming Notes and Folders

Renaming Notes and Folders works similar to renaming Files in Finder:

  • double click but with a delay that doesn't open them
  • hit return on a selected Folder or Note

Eloquent files and folders

Eloquent creates and uses certain files and folders on your hard drive.

Module database

Are stored under ~/Library/Application Support/Sword (where "~" is your home folder). These are mostly modules either manually copied there or downloaded using the module installer.

Eloquent files

Are stored and created under ~/Library/Application Support/Eloquent. Those files are:

Module search index files

  • Module index files. MacSword 1.4 and below store the module index files in folders directly under "MacSword" for example: "Index-KJV". Eloquent stores all index files in a separate folder "Index".

Index files can easily be deleted. They are then simply re-created from within Eloquent.

Dictionary caches

  • Dictionary module caches: cache-<modulename>. Those file also can be deleted without problems. They are used to speedup the dictionary lookup and are re-created if they don't exist.

Bookmarks

  • Bookmarks are stored in a file: Bookmarklist.plist for Eloquent >= 2.3 and Bookmarks.plist for MacSword <= 1.4. These files shouldn't be deleted otherwise you will loose your bookmarks.

Session files

  • Eloquent default session file is: DefaultSession.plist. This file stores you last opened session which includes open windows, positions, open modules and such...
  • Eloquent also stores a file called: DefaultSearchBookSets.plist. In this file custom, user defined search book sets for indexed search are stored.

Preferences

Are stored under ~/Library/Preferences:

  • "MacSword.plist" for MacSword < 2.0
  • "org.crosswire.Eloquent.plist" for Eloquent >= 2.3

Module creator/developer support

From MacSword 2.0 on it bundles universal binaries of the SWORD module command line tools. Those tools can be found in the Application bundle under "Contents/Resources/bin".

From version 2.1 main menu items (under Help) are provided which create symbolic links (aliases) in /usr/local/bin. This path should be in your executable search path $PATH and the SWORD utilities can be executed right away from the console.


What do I do if there are problems/crashes

Experience shows that there are mainly two reasons which can cause a crash of Eloquent:

  • An old MacSword 1.x module installation causes Eloquent to crash when this database is read on startup. This can be solved by deleting the folder: ~/Library/Application Support/Sword. See above for more information on files and folder in general.

Versions from 2.2.2 will notify the user on startup if such a problem could occur, due to a detected old module installation. However, if you have run MacSword 2.x successfully before then this is not the reason of the crash.

  • The session file which stores windows and positions and other things got corrupted. This can also be solved by deleting the session file. See above where to find this file.


There have not been any other causes and reports of crashes so far. If the above solutions do not work then get in contact to us in our forum, the mailing list or write an email to one of the developers.

External links