Difference between revisions of "Frontends:Eloquent"

From CrossWire Bible Society
Jump to: navigation, search
(→‎What do I do if there are problems/crashes)
 
(61 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
'''MacSword''' is an open source Study Bible software that uses [[The Sword Project]]. 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 14: Line 14:
 
* Search function
 
* Search function
 
* Non-Latin script (Hebrew, Greek, etc)
 
* Non-Latin script (Hebrew, Greek, etc)
−
* Different [[Bible]] translations
+
* Different Bible translations
−
*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 ==
 +
 +
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.
 +
 +
== Speed tuning ==
 +
 +
Bookmark highlighting as well as displaying Strong's numbers is very time consuming. You will realize this especially when displaying whole Bible books. If you don't need it, switch it off.
 +
 +
== 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 via the mailing list or write an email to one of the developers.
  
 
== External links ==
 
== External links ==
−
*[http://www.macsword.com MacSword home page]
+
*[https://github.com/mdbergmann/Eloquent GitHub project page] &ndash; ''2015-3-21 moved from Launchpad''
 +
*[https://launchpad.net/eloquent Launchpad project page] &ndash; ''2012-12-22 moved from SourgeForge''
 +
*[http://wiki.catug.org/Eloquent Brilliant information on this wiki by catug]
 +
 
 +
[[Category:SWORD Frontends|Eloquent]]

Latest revision as of 19:28, 26 February 2017

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.

Speed tuning

Bookmark highlighting as well as displaying Strong's numbers is very time consuming. You will realize this especially when displaying whole Bible books. If you don't need it, switch it off.

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 via the mailing list or write an email to one of the developers.

External links

Retrieved from "https://wiki.crosswire.org/index.php?title=Frontends:Eloquent&oldid=15412"