<!-- Modules -->

<!-- Introduction To Module Manager -->
	<sect2 id="module-introduction">
  		<title>Introduction To The Module Manager</title>
		<para>
		The "module" is the unit of content in <application>Xiphos</application>, and Sword generally; a Sword module is a resource
		available for viewing in Sword applications.  There are several varieties: Most importantly, Bible texts, as well as
		dictionaries and lexicons, commentaries, and general books, any of which may include image content (e.g. atlases).  They are
		installed either from a local directory structure (typically on removable media, such as a CDROM distribution) or remotely
		via ftp from a repository such as Crosswire, which is the home of Sword, and from which all officially Sword-sanctioned
		modules are available.  Also, many other modules are available from non-Crosswire repositories.  In particular, there is the
		Xiphos repository, containing a variety of otherwise-unofficial modules produced primarily by contributors to
		<application>Xiphos</application> itself.
		</para>
		<para>
		If you have other Sword applications installed, they will all share the same set of Sword modules that you install through
		the Module Manager.
		</para>
		<figure>
			<title>The Module Manager Dialog</title>
	        	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/module.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/module.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>The Module Manager Dialog</phrase> 
	    </textobject> 
	  </mediaobject> 
                        </screenshot>
		</figure>
		<para>
                Notice the <guibutton>View Intro</guibutton> button above.  You may see an introductory explanation of Module Manager
                operation at any time.
		</para>
	</sect2>
	
<!-- Sword Configure-->
	<sect2 id="sword-config">
	<title>Sword Module Configurations</title>
		<sect3 id="sword-sources">
			<title>Module Sources Settings</title>
			<figure>
				<title>Module Sources Settings</title>
	        	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/sword_sources.png" format="PNG" />
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/sword_sources.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>Module Installation</phrase> 
	    </textobject> 
	  </mediaobject> 
                        	</screenshot>

			</figure>
		<para>
		There are other repositories available besides CrossWire's own, though the modules available from other repositories do not
		represent content officially sanctioned by Crosswire.  On the web, see this page for list of those repositories known:
		<ulink type="http" url="http://www.crosswire.org/wiki/Module_Repositories">http://www.crosswire.org/wiki/Module_Repositories</ulink>		
		</para>
		<para>
		The list of standard repositories is maintained at CrossWire.  Xiphos normally auto-synchronizes with that list one time,
		when the user first puts the Module Manager to use.  The list may change, as new repositories come into existence;
		occasional re-synchronization with the list is suggested, which is accomplished by clicking <guibutton>Load Standard</guibutton>.
		</para>
		</sect3>
		<sect3 id="installation">
			<title>Sword Module Installations</title>
			<figure>
				<title>Sword Module Installations</title>
	        	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/sword_config.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/sword_config.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>Module Installation</phrase> 
	    </textobject> 
	  </mediaobject> 
                        </screenshot>
			</figure>
			<para>
			After you have selected your Install Source, click the <guimenuitem>Refresh</guimenuitem> button to cause
			<application>Xiphos</application> to find the module summary available from that source before moving on.
			</para>

			<para>
			Take note of the "Install Destination". In most cases, you will have a choice of a personal area or a system area. 
			The details vary according to your operating system.
			</para>
			
			<sect4 id="destination-linux">
				<title>Linux</title>
				<para>
    				Unless you run as root (via su or sudo) you will only be able to install in your personal area, under ~/.sword.
				If you run as root, or change permissions on the shared directory, you will also be able to install modules for
				all users, typically in /usr/share/sword. There have been some requests for Xiphos to provide a means by which
				an ordinary (non-root) user could start the program, gain temporary write access to the system area while installing
				modules, and then revoke that access after installation is complete.  Attempting to devise a scheme to do this has
				proven quite difficult, given the different superuser management schemes employed by various Linux distributions. 
				Therefore, at this time there are no ongoing plans to try to solve this problem, and users are advised to enable 
				write access to the system area outside Xiphos.
				</para>
			</sect4>
			
			<sect4 id="destination-xp">
				<title>Windows XP</title>
				<para>
				You may install modules to a shared folder so the modules are available to all users. If you have previously used
				"The Sword Project for Windows", this folder will be "C:\Program Files\Crosswire\The Sword Project\Sword". Otherwise
				it will be "C:\Documents and Settings\All Users\Application Data\Sword". You may also install modules to a location
				that can only be seen by you. This location is "C:\Documents and Settings\YOUR NAME\Application Data\Sword".
				</para>
			</sect4>
			
			<sect4 id="destination-vista">
				<title>Windows Vista</title>
				<para>
				Vista works much the same as XP, except for the locations. The private location is 
				"C:\Users\YOUR NAME\AppData\Roaming\Sword". The shared location is "C:\ProgramData\Sword".
				</para>
			</sect4>
			
		</sect3>
	</sect2>
	
<!-- Installing, Updating, and Maintaining Modules -->
	<sect2 id="module-management">
		<title>Installing, Updating, and Maintaining Modules</title>
		<sect3 id="add-module">
			<title>Installing, Updating, and Maintaining Modules</title>
			<figure>
				<title>Installing and Updating Modules</title>
	       		<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/sword_install.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/image.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>Module Installation</phrase> 
	    </textobject> 
	  </mediaobject> 
	
                        </screenshot>
			</figure>
		<para>
		The module manager generates both a per-type module list as well as a parallel availability list.  The latter is
		intended to make it easier to find new items without having to work one's way through the per-type list, one subtree at a
		time.  Modules which are either not yet installed or updated beyond what is currently installed will appear in both lists.
		</para>
		<para>
		Modules that are already installed will show a checkmark beside them.  If a fast search ("lucene") index is available, a magnifying glass will be
		displayed, otherwise an "X" will be shown; creation of the index is available on the Maintenance pane.  Locked modules, which require that you
		purchase an unlock key from the module's copyright holder, will show a lock symbol.  If there are modules installed for which a more recent
		version is available, a refresh icon will appear between the differing old and new version stamps.  There may be an approximate size displayed,
		if the repository management provides this information, otherwise a question mark ("-?-") will be shown.
		</para>
		<para>
		Select new modules to be installed by clicking the checkboxes and then the Install button at the bottom.  Any number of
		modules may be requested for installation at one time.
		</para>
		<para>
		If you acquire a locked module and have obtained the cipher key for it, the module is then unlocked in the main window: Open
		the module, which will probably appear blank, then using the right-click context menu, choose "Unlock This Module."
		</para>
		</sect3>
		<sect3 id="remove-module">
			<title>Module Maintenance</title>
			<figure>
				<title>Module Maintenance</title>
	       		<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/sword_remove.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/sword_remove.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>Module Maintenance</phrase> 
	    </textobject> 
	  </mediaobject> 
                        	</screenshot>
			</figure>
		<para>
		Several maintenance functions are available: Removal, archival, index, and index deletion.
		</para>
		<para>
		Removal disposes of a module entirely.  There is no recovery of the module unless you have previously archived a copy of it.
		</para>
		<para>
		Archival is available for any module, although it is provided with personal commentaries specifically in mind.  A *.zip of
		the module is left in the directory ~/.sword/zip.  Archival prior to removal of personal commentaries is recommended, in
		order to be available for future re-install if the subject matter of the personal commentary becomes important again.
		</para>
		<para>
		Indexing is provided so that the underlying Sword search support can create the index needed for the "lucene" fast-search
		functions.  If the index is not created, plain multi-word search will still be available, but it will be much slower.  With
		the index in place, searches through an entire Bible can take just a few seconds.
		</para>
		<para>
		Indexes may be deleted as well.
		</para>
		</sect3>
	</sect2>

<!-- Installing Non-Standard Modules -->
	<sect2 id="non-standard-modules">
		<title>Installing Non-Standard Modules</title>
		<para>
		Some resource modules in Sword Project format are available from sources other than Crosswire and not from a module manager-ready repository.
		Necessarily, installing such a module is a manual task.
		</para>
		<para>
		Modules are normally packaged as *.zip files; they contain a configuration file plus a number of data files.  Installation
		of such a module is done by cd'ing to your personal Sword (not <application>Xiphos</application>) configuration
		directory, ~/.sword, and unzipping the file there.  The configuration file will be left in "mods.d", and the module's data
		files will go into a subdirectory of "modules".  Alternatively, if you have write access to the system Sword directory,
		typically /usr/share/sword, you may cd there instead before unzipping.
		</para>
		<para>
		Restart <application>Xiphos</application> after installing such a module, so that a fresh instance of the program can
		notice the new module in place.
		</para>
	</sect2>
