bibletime/docs/handbook/unicode/hdbk-operation.docbook

<chapter id="hdbk-op"><title>Program operation</title>

<sect1 id="hdbk-op-overview">
<title>Program overview</title>

<para>This is how a typical &bibletime; session looks like:

<mediaobject>
<imageobject>
<imagedata fileref="ss_mainterms.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The &bibletime; application window</phrase> </textobject>
</mediaobject>

You can easily see the different parts of the application. The Bookshelf on the left side is used to open works and to manage your bookmarks. The little "Mag" window below the Bookshelf is used to display extra information that is embedded in documents. When you move your mouse over a footnote marker, for example, then the Mag will display the actual content of the footnote. The toolbar gives you quick access to important functions, and the Desk on the right side is where you do your real work.</para>
<para>Let us now proceed by looking at the different parts of the application individually.</para>
</sect1>

<sect1 id="hdbk-op-parts">
<title>Parts of the &bibletime; application window</title>

<sect2 id="hdbk-op-parts-bookshelf">
<title>The Bookshelf</title>
<para>The Bookshelf lists all installed works, sorted by category and language. It also has a category called "Bookmarks". This is where you can store and access your own bookmarks.
</para>

<sect3 id="hdbk-op-parts-bookshelf-open">
<title>Reading works</title>
<para>To open a work from the bookshelf for reading, simply click with the <mousebutton>left mouse button</mousebutton> on the desired
category (Bibles, Commentaries, Lexicons, Books, Devotionals or Glossaries) to display its contents. Then just click on one of the works to open it for reading. A read window will appear in the Desk area.
</para>
<tip><para>Drag &amp; Drop Works Here</para></tip>
<para>
If you are reading a certain work, and want to open another work at the passage you are reading, you can use a shortcut. Simply click with the <mousebutton>left mouse button</mousebutton> on the verse/passage reference (pointer changes to hand) and drag it to the
Bookshelf. Drop it on the work you want to open, and it will be opened for reading at the specified location. You can also drag a verse reference into an existing read window, then it will jump to the specified location.</para>
</sect3>

<sect3 id="hdbk-op-parts-bookshelf-metainfo">
<title>Additional information about works</title>
<para>
If you click with the <mousebutton>right</mousebutton> mouse button on
the symbol of a work, you will see a menu with additional entries that are relevant for this work. <guimenuitem>"About this work"</guimenuitem> opens a window with lots of interesting information about the selected work. <guimenuitem>"Unlock this work"</guimenuitem> opens a small dialog for encrypted documents, where you can enter the unlock key to access the work.  
For additional information on locked works, please see <ulink url="http://www.crosswire.org/sword/modules/aboutlocked.jsp">this page</ulink> on the Crosswire Bible Society web site.
</para>
</sect3>

<sect3 id="hdbk-op-parts-bookshelf-search">
<title>Searching in works</title> <para>
You can search in a work by clicking with the <mousebutton>right</mousebutton>
mouse button on its symbol and selecting <guimenuitem>"Search in work(s)"</guimenuitem>. By pressing &Shift; and clicking on other works you can select more than one.  Then follow the same procedure to open the search dialog. You will be searching in all of these documents. A complete description of the operation of the search features can be
found <link linkend="hdbk-op-search">here</link>.
</para>
</sect3>

<sect3 id="hdbk-op-parts-bookshelf-bookmarks">
<title>Working with bookmarks</title>
<para>
<tip><para>Drag &amp; Drop Works Here</para></tip>
Click with the <mousebutton>right</mousebutton> mouse button on the bookmark category of the bookshelf and select <guimenuitem>"Create new folder"</guimenuitem> to create a new bookmark subfolder. You can use normal drag &amp; drop
functions to drag verse references from read windows or search results to the bookmark folder, and to rearrange bookmarks between folders.</para>

<para>You can also import bookmarks from other people or export bookmarks to share them. To do this, open the <guimenu>context menu</guimenu> of the bookmark folder as described above, and select <guimenuitem>"Export bookmarks"</guimenuitem>. This will bring up a dialog box for you to save the bookmark collection. You can import bookmarks in a similar way.</para>

<para>You can also click with the <mousebutton>right</mousebutton> on folders and bookmarks to change their names and descriptions.</para>
</sect3>
</sect2>

<sect2 id="hdbk-op-parts-mag">
<title>The Mag(nifying glass)</title>
<para>This little window in the lower left corner of the &bibletime; window is purely passive. Whenever your mouse cursor is located over some text with additional information (e.g., Strong's numbers), then this additional information will be displayed in the Mag, and not in the text itself. Just try it out.</para>
</sect2>


<sect2 id="hdbk-op-parts-desk">
<title>The Desk</title>
<para>
The Desk is where the real work with &bibletime; takes place. Here you can open works from the Bookshelf, read them, <link linkend="hdbk-op-search">search</link> in them, and even save your annotations in the personal commentary module (see <link linkend="hdbk-op-parts-desk-write">below</link>).</para>

<sect3 id="hdbk-op-parts-desk-read">
<title>Reading works</title> 
<para>
As we have <link linkend="hdbk-op-parts-bookshelf-open">already seen</link>, you can open works for reading simply by clicking on their symbol in the Bookshelf. A read window will open in the Desk's area. Every read window has a toolbar. There you can find tools to navigate in the work that this read window is connected to, as well as history buttons like the ones that you know from your browser.</para>
</sect3>

<sect3 id="hdbk-op-parts-desk-placement">
<title>Read window placement</title> 
<para>
Of course, you can open multiple works at the same time. There are several possibilities for arranging the read windows on the desk. Please have a look at the entry <guimenu>Window</guimenu> in the main menu. There you can see that you can either control the placement of the read windows completely yourself, or have &bibletime; handle the placement automatically. To achieve this, you have to select one of the automatic placement modes available at <menuchoice><guimenu>Window</guimenu><guimenuitem>Arrangement mode</guimenuitem></menuchoice>. Just try it out, it's simple and works.
</para>
</sect3>

<sect3 id="hdbk-op-parts-desk-write">
<title>Editing your own commentary</title> 
<para>
To be able to store your own comments about parts of the Bible, you have install a certain work from the library of the <ulink url="http://www.crosswire.org">Crosswire Bible Society</ulink>. This work is called "Personal commentary".</para>
<para>
If you open the personal commentary by clicking on its symbol in the Bookshelf with a <mousebutton>left</mousebutton> mouse button, it opens
in read mode. You will not be able to edit it in this mode. Should you wish to write annotations into the personal commentary, you have to open it with the <mousebutton>right</mousebutton> mouse button and then select <guimenu>Edit this work</guimenu> and then either <guimenuitem>Plain text</guimenuitem>(source code editor) or <guimenuitem>HTML</guimenuitem>(basic gui wysiwyg editor).</para>

<tip><para>If <menuchoice><guimenu>Edit this work</guimenu></menuchoice>
is deactivated, please check if you have write permission for the files of 
the personal commentary.</para></tip>

<tip><para>Drag&amp;drop works here. Drop a verse reference and the text
of the verse will be inserted.</para></tip>
</sect3>

</sect2>

</sect1>


<sect1 id="hdbk-op-search">
<title>Searching in works</title>

<sect2 id="hdbk-op-search-intext">
<title>Searching text in an open read window</title>
<para>
You can look for a word or phrase in the open read window (e.g. the chapter of a bible that you're reading)
just like you are used to from other programs.
This function can be reached either by clicking with the <mousebutton>right</mousebutton> mouse button and 
selecting <guimenuitem>Find...</guimenuitem>, or by using the hotkey <keycombo action="simul">&Ctrl;<keycap>F</keycap> </keycombo>. Read on to learn how you can search in entire works.</para>
</sect2>

<sect2 id="hdbk-op-search-access">
<title>Accessing the search dialog</title>
<para>
You can search in a work by clicking with the <mousebutton>right</mousebutton> mouse button 
on its symbol in the <guimenu>Bookshelf</guimenu> and selecting <guimenuitem>Search in work(s)</guimenuitem>. By holding &Shift; or &Ctrl; and clicking on other work's names you can select more than one. Then follow the same procedure to open the search dialog.  You will be searching in all of these works at the same time.</para>
<para>You can also access the search dialog by clicking on <menuchoice><guimenu>Search</guimenu></menuchoice> from the main menu, and selecting the appropriate entry.</para>
<para>A third possibility to start searches is to click on the search symbol in an open read window.</para>
</sect2>

<sect2 id="hdbk-op-search-config">
<title>Search configuration</title>
<screenshot>
<screeninfo>Search Text Dialog Options Tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="ss_searchopts.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>

<sect3 id="hdbk-op-search-config-works">
<title>Selecting works</title>
<para>At the top of the options tab you will find <guibutton>Choose</guibutton> (works). If you would like to search in multiple works, click on this button and you will be offered a menu where you can select the works you want to search in.
</para>
</sect3>

<sect3 id="hd-op-search-config-scope">
<title>Using Search Scopes</title>
<para>You can narrow the scope of your search to certain parts of the Bible by selecting one of the predefined scopes from the list in <guimenu>Search scope</guimenu>. You can define your own search ranges by clicking the <guibutton>Setup ranges</guibutton> button.</para>
</sect3>

<sect3 id="hd-op-search-config-syntax">
<title>Basic Search Syntax Introduction</title>
<para>Enter search terms separated by spaces.  By default the search function will return results that match any of the search terms (OR). To search for all the terms separate the terms by AND.</para>
<para>You can use wildcards: '*' matches any sequence of characters, while '?' matches any single character. The use of brackets allows you to group your search terms, e.g. '(Jesus OR spirit) AND God'.</para>
<para>To search text other than the main text, enter the text type followed by ':', and then the search term.  For example, to search for the Strong's number H8077, use 'strong:H8077'.</para>
<para>Available text types:
<table><tgroup cols="2">
<thead><row><entry>Prefix</entry><entry>Meaning</entry></row></thead>
<tbody>
<row><entry>heading:</entry><entry>searches headings</entry></row>
<row><entry>footnote:</entry><entry>searches footnotes</entry></row>
<row><entry>strong:</entry><entry>searches Strong's Numbers</entry></row>
<row><entry>morph:</entry><entry>searches morphology codes</entry></row>
</tbody></tgroup></table></para>
<para>BibleTime uses the Lucene search engine to perform your searches. It has many advanced features, and you can read more about it here: <ulink url="http://lucene.apache.org/java/docs/queryparsersyntax.html">http://lucene.apache.org/java/docs/queryparsersyntax.html</ulink></para>
</sect3>


</sect2>

<sect2 id="hdbk-op-search-results">
<title>Search results</title>
<para>
Here you can see how many instances of the search string were found, sorted by works.
Clicking on a work with the <mousebutton>right</mousebutton> mouse button allows you to copy, save, or print all verses that were found in a certain work at once. This also works when you click on one or more of the references to copy, save or print them. Clicking on a particular reference opens that verse up in context in the preview window below.</para>

<tip><para>Drag a reference and drop it on a work symbol on the Bookshelf to open the
work at that verse in a new read window.</para></tip>
<tip><para>Drag a reference and drop it on an open read window, and it will jump to that verse.</para></tip>
<tip><para>Select references and drag them to the Bookshelf to create bookmarks.</para></tip>

<sect3 id="hdbk-op-search-analysis">
<title>Search result analysis</title>
<para>Click on <guibutton>Search analysis</guibutton> to open the search analysis display. 
This gives a simple graphic analysis of the number of instances the
search string was found in each book of the Bible, and you can also save the analysis.</para>

<screenshot>
<screeninfo>Search Analysis Dialog Box</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="ss_searchanal.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</sect3>
</sect2>
</sect1>



<sect1 id="hdbk-op-bookshelfmanager">
<title>The <guimenuitem>Bookshelf Manager</guimenuitem></title>

<para>The <guimenuitem>Bookshelf Manager</guimenuitem> is a tool to manage your Bookshelf. You can install new works to your Bookshelf, and update or remove existing works from your Bookshelf. Access it by clicking <menuchoice><guimenu>Settings</guimenu><guimenuitem>Bookshelf Manager</guimenuitem></menuchoice> in the main menu.</para>

<sect2 id="hdbk-op-bookshelfmanager-path">
<title>Bookshelf path(s) setup</title>

<para>Here you can specify where &bibletime; may store your Bookshelf on the harddrive. You can even store it in multiple directories. Default is "~/.sword/".</para>

<tip><para>If you have a sword CD, but do not want to install all the works on the harddisk, but use them directly from the CD, then you can add the path to the CD as one of your bookshelf paths. When you start &bibletime;, it will show all works on the CD if it is present.</para></tip>
</sect2>

<sect2 id="hdbk-op-bookshelfmanager-installupdate">
<title>Install/update work(s)</title>

<para>With this facility, you can connect to a repository of works (called "library"), and transfer one or more works to your local Bookshelf. These libraries may be local (e.g. a Sword CD), or remote (e.g. Crosswire's online repository of Sword modules, or another site offering Sword modules). You can manage your libraries with <guibutton>Add library</guibutton> and <guibutton>Delete library</guibutton>.</para>

<para>To begin the installation or update process, select a library you want to connect to and a local Bookshelf path to install the work(s) to. Then click on <guibutton>Connect to library</guibutton>. &bibletime; will scan the contents of the library and present you with a list of works that you can add to your Bookshelf, or that you already have installed but are available in a new version in the library, and thus can be updated. Then you can mark all works that you want to install or update, and click on <guibutton>Install works</guibutton>. They will then be transferred to your Bookshelf.
</para>
</sect2>

<sect2 id="hdbk-op-bookshelfmanager-remove">
<title>Remove work(s)</title>

<para>This facility allows you to delete one or more of the works from your Bookshelf too free up disk space. Simply mark the items and click on <guibutton>Remove works</guibutton>.
</para>

</sect2>

</sect1>

<sect1 id="hdbk-op-output">
<title>Exporting and Printing</title>

<para>
In many places, you can open a context menu by clicking with the
<mousebutton>right</mousebutton> mouse button. Depending on context, it will allow you
to <guimenuitem>Select</guimenuitem>, <guimenuitem>Copy</guimenuitem> (to clipboard), <guimenuitem>Save</guimenuitem> or <guimenuitem>Print</guimenuitem> text. This works for example in the read windows, when you click on the normal text or the verse reference, or in the search result page when you click on a work or one or more verse references. It is pretty straightforward, so just try it out.</para>

<para>Printing from &bibletime; is rather basic and is intended as
a utility. If you are composing a document or presentation containing text from
&bibletime; works, we suggest that you use one of the presentation or editing
tools on your system to format your document, rather than printing from &bibletime; directly.
</para>

</sect1>

</chapter>