alexandria-book-collection-manager 0.6.9.pre1

data/share/gnome/help/alexandria/C/introduction.xml

@@ -0,0 +1,142 @@
+<!-- 
+  This is part of the Alexandria Manual.
+  Copyright (C)  2005  Liam Davison
+  Copyright (C)  2007  Cathal Mc Ginley
+  See the file alexandria.xml for copying conditions.
+-->
+
+<!-- ============= Introduction ============================== -->
+<!-- Use the Introduction section to give a brief overview of what
+     the application is and what it does. -->
+<section id="introduction">
+  <title>Introduction</title>
+
+  <para>&app; is a simple GNOME application designed to allow
+  individuals to keep a catalogue of their book collection. In
+  addition, it enables users to keep track of books which are on
+  loan.</para>
+
+  <section id="features">
+    <title>Features</title>
+    
+    <para>&app; provides the following features:</para>
+
+
+    <itemizedlist>
+      <listitem>
+	<para>
+	  retrieves and displays book information (sometimes with cover
+	  pictures) from several online libraries and bookshops, such as
+	  <itemizedlist>
+	    <listitem>
+	      <para>
+		<ulink url="http://www.amazon.com">Amazon</ulink>
+		(searches .co.uk, .fr, .de, .jp and .ca websites, as
+		well as amazon.com)
+	      </para>
+	    </listitem>
+	    
+	    <listitem>
+	      <para><ulink url="http://www.proxis.be">Proxis</ulink></para>
+	    </listitem>
+	    
+	    <listitem>
+	      <para><ulink url="http://www.barnesandnoble.com">Barnes and Noble</ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="http://www.mcu.es">Spanish Ministry of Culture</ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="http://www.thalia.de">Thalia</ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="http://www.internetbookshop.it">Internet Bookshop Italia</ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="http://www.renaud-bray.com/">Renaud-Bray</ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="http://www.loc.gov">US Library of Congress</ulink></para>
+	    </listitem>
+	    <listitem>
+	      <para><ulink url="http://www.bl.uk">British Library</ulink></para>
+	    </listitem>
+	  </itemizedlist>
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>allows books to be added and updated by hand</para>
+      </listitem>
+      <listitem>
+	<para>enables searches either by <acronym>ISBN</acronym>, title, authors or keyword</para>
+      </listitem>
+      <listitem>
+	<para>supports the <ulink
+	url="http://www.z3950.org/">Z39.50</ulink> standard and
+	allow you to define your own online book information sources</para>
+      </listitem>
+
+      <listitem>
+	<para>saves data using the text-based <ulink
+	url="http://www.yaml.org"><acronym>YAML</acronym></ulink>
+	format, making it easy to work with your book data</para>
+      </listitem>
+      <listitem>
+	<para>can import and export data into <ulink
+	url="http://www.editeur.org/onix.html"><acronym>ONIX</acronym></ulink>,
+	<ulink url="http://www.periapsis.org/tellico/">Tellico</ulink>
+	and <acronym>ISBN</acronym>-list formats</para>
+      </listitem>
+
+      <listitem>
+	<para>can export library data in the form of
+	<acronym>XHTML</acronym> web pages themable with
+	<acronym>CSS</acronym></para>
+      </listitem>
+      <listitem>
+	<para>allows marking your books as loaned, each with the loan-date and
+	the name of the person who has borrowed them</para>
+      </listitem>
+
+      <!-- listitem>
+	<para>features a <ulink
+	url="http://developer.gnome.org/projects/gup/hig/"><acronym>HIG</acronym></ulink>-compliant
+	user interface</para>
+      </listitem -->
+      <listitem>
+	<para>shows books in different views (standard list or
+	icons list), that can be filtered and/or sorted</para>
+      </listitem>
+      <listitem>
+	<para>handles book rating and notes</para>
+      </listitem>
+
+      <listitem>
+	<para>supports <ulink
+	url="http://www.cuecat.com/">CueCat</ulink> barcode
+	readers for data entry</para>
+      </listitem>
+      <listitem>
+	<para>includes translations for several languages</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <para>
+	Alexandria is under active development (as of December 2007)
+	and new features are being planned and added regularly.  See
+	the <ulink url="http://alexandria.rubyforge.org/feedback.html"
+	type="http">&app; web page</ulink> for more information.
+      </para>
+    </note>
+
+  </section>
+
+</section>
+

data/share/gnome/help/alexandria/C/searching.xml

@@ -0,0 +1,90 @@
+<!-- 
+  This is part of the Alexandria Manual.
+  Copyright (C)  2005  Liam Davison
+  Copyright (C)  2007  Cathal Mc Ginley
+  See the file alexandria.xml for copying conditions.
+-->
+
+<!-- ============= Searching and views subsection =============== -->
+
+<section id="searching">
+  <title>Searching, Filtering and Views</title>
+  <para>&app; includes powerful tools for searching and filtering and books display. You can use these tools to display only books by a certain author or publisher, only those you rate highly or those with additional notes. &app; also contains both Icon and List views, and can directly link to online information providers to display more detailed information.
+  <itemizedlist>
+    <listitem><para><xref linkend="searching-views"/></para></listitem>
+    <listitem><para><xref linkend="searching-filtering"/></para></listitem>
+    <listitem><para><xref linkend="searching-more-online"/></para></listitem>
+  </itemizedlist>
+  </para>
+
+
+  <!-- ========= Icon and List views =========== -->
+  <section id="searching-views">
+    <title>Icon and List Views</title>
+    <para>Like the <application>Nautilus</application> file manager, &app; has both Icon and List views. The Icon view shows the cover and title for every book in your library, while the List view shows more detailed information (as defined in the <xref linkend="alexandria-prefs-display"/> preferences), with one book per line.</para>
+    <tip>
+      <para>To switch between Icon and List views, either use the <guibutton>View as...</guibutton> button in the top right of the main window, or <menuchoice><guimenu>View</guimenu><guimenuitem>View As List / View as Icons</guimenuitem></menuchoice> in the main menu and right-click menu.</para>
+    </tip>
+    <para>The icons can be arranged in order of Title, Author, Publishing, Binding or Rating, and you can reverse this order. To change the order of the books in the Icon view, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Arrange Icons</guimenuitem></menuchoice> from the main menu or <guimenuitem>Arrange Icons</guimenuitem> from the right-click menu.</para>
+    <para>To change the order of the books in the List view, click on the appropriate column header.</para>
+    <figure id="listview-fig">
+      <title>The list view, showing books sorted in reverse by author name</title>
+      <screenshot>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figures/searching_filtering_views_list_view.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>The list view, showing books sorted by author name</phrase>
+	  </textobject>
+	</mediaobject>
+      </screenshot>
+    </figure>	
+  </section>
+
+  <!-- ========== Searching/filtering ======== -->
+  <section id="searching-filtering">
+    <title>Searching or filtering the view</title>
+    <para>It is very easy to search for a particular book, or to limit the number of books displayed. To search for a specific title, just enter its name in the entry field on the toolbar. Use the <guilabel>Title contains</guilabel> drop-down menu to choose between searching for Titles, Authors, ISBNs, Publishers or Notes.</para>
+    <figure id="listview-search-fig">
+      <title>The list view, showing books only those books whose author name contains 'banks'</title>
+      <screenshot>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figures/searching_filtering_views_list_view_search.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>The list view, searching for books by 'banks'</phrase>
+	  </textobject>
+	</mediaobject>
+      </screenshot>
+    </figure>
+    <tip>
+      <para>From the keyboard, you can move to the search field by pressing Ctrl-F. You can clear the search by pressing Ctrl-Alt-B.</para>
+    </tip>
+  </section>
+
+  <!-- ========= Finding out more online =========== -->
+  <section id="searching-more-online">
+    <title>Finding out more information about your books online</title>
+    <para>If you want to find out more information about your book, you can use &app; to open the web page of Amazon, Barnes and Noble, or one of the other online information providers and be taken directly to the relevant book. Simply select the book you wish to know more about, right-click on it, and from the menu <guimenuitem>Display Online Information</guimenuitem>, choose from either Amazon, Barnes and Nobel, Proxis, Spanish Culture Ministry, Amadeus Buch, Renaud-Bray or Internet Bookshop Italia.</para>
+    <tip>
+      <para>The <menuchoice><guimenu>Display Online Information</guimenu><guimenuitem>At Amazon</guimenuitem></menuchoice> choice will take you to the Amazon .com, .co.uk, .de, or jp site, as set up in the <xref linkend="alexandria-amazon-prefs"/>.</para>
+    </tip>
+    <caution>
+      <para>Not every online information source has a complete list of books and you may have to try several different providers to find the information you want.</para>
+    </caution>
+  </section>
+</section>

data/share/gnome/help/alexandria/C/settings.xml

@@ -0,0 +1,140 @@
+<!-- 
+  This is part of the Alexandria Manual.
+  Copyright (C)  2005  Liam Davison
+  Copyright (C)  2007  Cathal Mc Ginley
+  See the file alexandria.xml for copying conditions.
+-->
+
+<!-- ============= Customization ============================= -->
+<!-- Use this section to describe how to customise the application. -->
+<section id="alexandria-preferences">
+  <title>Settings</title>
+  <para>To configure &app;, choose 
+  <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>. The 
+  <guilabel>Preferences</guilabel> dialogue contains the following tabbed
+  sections:</para>
+  <itemizedlist>
+    <listitem>
+      <para> 
+      <xref linkend="alexandria-prefs-display"/></para>
+    </listitem>
+    <listitem>
+      <para> 
+      <xref linkend="myapp-prefs-providers"/></para>
+    </listitem>
+  </itemizedlist>
+  <para>You can also add new online information providers to &app;:</para>
+  <itemizedlist>
+    <listitem><para><xref linkend="alexandria-z3950-prefs"/></para></listitem>
+  </itemizedlist>
+
+  <!-- ======== Visible columns ======= -->
+  <section id="alexandria-prefs-display">
+    <title>List View</title>
+    <para>You can choose which columns are displayed in the List view by selecting or deselecting the checkboxes. Possible columns are Authors, ISBN, Publisher, Binding and Rating.</para>
+  </section>
+
+  <!-- ======== Providers ======== -->
+  <section id="myapp-prefs-providers">
+    <title>Online information providers</title>
+    <para>&app; can download information from a variety of different online sources; some of these sources have additional options to control how the information is downloaded. &app; will search each of the sources in turn, in the order displayed in the list. You can change the order in which the sources are searched by moving each source up or down using the <guibutton>Up</guibutton> and <guibutton>Down</guibutton> buttons.
+    <itemizedlist>
+      <listitem><para><xref linkend="alexandria-amazon-prefs"/></para></listitem>
+      <listitem><para><xref linkend="alexandria-proxis-prefs"/></para></listitem>
+      <listitem><para>The Spanish Culture Ministry</para></listitem>
+      <listitem><para>Barnes and Noble</para></listitem>
+      <listitem><para>Amadeus Buch</para></listitem>
+      <listitem><para>Internet Bookshop Italia</para></listitem>
+      <listitem><para><xref linkend="alexandria-britlib-prefs"/></para></listitem>
+      <listitem><para><xref linkend="alexandria-uslibcon-prefs"/></para></listitem>
+      <listitem><para>Reynaud-Bray</para></listitem>
+    </itemizedlist>
+    </para>
+    <para>You can also use the Z39.50 protocol to add and remove new information providers. Two providers have been set up using this protocol for you.
+    <itemizedlist>
+      <listitem><para><xref linkend="alexandria-z3950-prefs"/></para></listitem>
+    </itemizedlist>
+    </para>
+
+
+    <sect3 id="alexandria-amazon-prefs">
+      <title>Amazon preferences</title>
+      <para>In order to use the Amazon provider, you must sign up for a free <ulink url="http://aws.amazon.com/">Amazon AWS</ulink> account, and enter your <guilabel>Access Key Id</guilabel> <guilabel>Secret Access Key</guilabel>. You can find these "Access Identifiers" under the link to "Your Account" on the AWS website.</para>
+      <note>
+	<para>Previous versions of &app; included an Amazon AWS Access
+	Key ID. From August 15 2009, Amazon have changed their
+	"Product Advertising API" so each request must be
+	authenticated, requiring a Secret Access Key. It is not
+	possible for us to distribute secret keys to users. So, in
+	order to continue using the Amazon provider you will need to
+	sign up for your own free AWS account.</para>
+        <para>You don't require an Amazon AWS account in order to use
+        &app;'s other providers. So, if you don't want to sign up for
+        an AWS account, you can leave these settings blank, and &app;
+        will simply not search Amazon when looking up books. </para>
+      </note>
+      <para>&app; can download book information from different amazon websites - currently, amazon.com, .co.uk, .fr, .de, .ca and .jp . To change which site to use, select Amazon from the Provider list, and click on <guibutton>Setup</guibutton>. Then choose either <guilabel>ca, de, fr, jp, uk</guilabel> or <guilabel>us</guilabel> from the drop-down menu.</para>
+    </sect3>
+
+
+    <sect3 id="alexandria-proxis-prefs">
+      <title>Proxis preferences</title>
+      <para>&app; can search the Proxis website for books in either English, French or Dutch. To change which language to use, select Proxis from the Provider list, and click on <guibutton>Setup</guibutton>. Then chose either <guilabel>en, fr</guilabel> or <guilabel>nl</guilabel> from the drop-down menu.</para>
+    </sect3>
+    
+    <sect3 id="alexandria-britlib-prefs">
+      <title>British Library preferences</title>
+      <para>If you have an account with the British Library, you can use this dialogue to specify your username and password for the z39.50 service. You can also choose which database to connect to.</para>
+    </sect3>
+    
+    <sect3 id="alexandria-uslibcon-prefs">
+      <title>US Library of Congress preferences</title>
+      <para>If you have an account with the US Library of Congress, you can use this dialogue to specify your username and password for the z39.50 service. You can also choose which database to connect to.</para>
+    </sect3>
+    
+    <sect3 id="alexandria-z3950-prefs">
+      <title>Adding Z39.50 providers</title>
+
+	  
+
+      <para>To add or remove a Z39.50 provider, you must first enable
+      the advanced preferences options by selecting
+      the <guilabel>Custom Z39.50 Providers</guilabel> checkbox. Two new
+      buttons will appear: <guibutton>Add</guibutton>
+      and <guibutton>Remove</guibutton>.</para>
+
+      <note>
+	<para>Z39.50 support is optional in &app;, and requires that
+	  you <ulink url="http://alexandria.rubyforge.org/faq.html#ruby-zoom-marc">install
+	  Ruby/ZOOM and marc</ulink>. If the <guilabel>Custom Z39.50
+	  Providers</guilabel> checkbox is greyed-out, it means that
+	  Ruby/ZOOM and marc are not correctly installed.</para>
+	</note>
+
+
+
+      <para>Clicking Add will open the New Z39.50 Provider dialogue:</para>
+      <figure id="add-z3950">
+	<title>Adding a new Z39.50 information provider</title>
+	<screenshot>
+	  <mediaobject>
+	    <imageobject>
+	      <imagedata fileref="figures/settings_providers_new_z3950.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>The Z39.50 information provider dialog.</phrase>
+	    </textobject>
+	  </mediaobject>
+	</screenshot>
+      </figure>
+      <para>Here you can specify the <guilabel>Name</guilabel> of the provider, the <guilabel>Hostname</guilabel>, the Internet <guilabel>Port</guilabel> to connect to, the name of the online <guilabel>Database</guilabel>, the <guilabel>Record Syntax</guilabel> used (&app; currently supports USMARC, UNIMARC and SUTRS formats), and, if relevant, a username and password to connect to the provider.</para>
+      <para>To remove a provider, select its name from the list and click on <guibutton>Remove</guibutton>. You cannot remove any of the default providers provided by &app;.</para>
+    </sect3>
+  </section>
+</section>

data/share/gnome/help/alexandria/C/smart-libraries.xml

@@ -0,0 +1,160 @@
+<!-- 
+  This is part of the Alexandria Manual.
+  Copyright (C)  2005  Liam Davison
+  Copyright (C)  2007  Cathal Mc Ginley
+  See the file alexandria.xml for copying conditions.
+-->
+
+<!-- ============= Smart Libraries Subsection ============ -->
+
+<section id="smart-libraries">
+  <title>Smart Libraries</title>
+  <para>
+    The search feature makes it easy to narrow down the view of books
+    in a single library according to a single search term. In order to
+    support more complex filtering, in a persistent form, &app; uses
+    <quote>Smart Libraries</quote>.
+  </para>
+
+  <para>
+    Smart Libraries are listed beneath the actual libraries in the
+    application side pane. They do not actually contain books, but
+    rather a set of rules describing which books you wish to see. The
+    books from all libraries which satisfy the set of rules will be
+    displayed. You cannot directly add books to a Smart Library.
+  </para>
+
+  <para>
+    <itemizedlist>
+      <listitem><para><xref linkend="new-smart-library"/></para></listitem>
+      <listitem><para><xref linkend="edit-smart-library"/></para></listitem>
+      <listitem><para><xref linkend="renaming-smart-libraries"/></para></listitem>
+      <listitem><para><xref linkend="delete-smart-library"/></para></listitem>
+    </itemizedlist>
+  </para>
+
+  <!-- ======= Creating smart libraries ===== -->
+  <section id="new-smart-library">
+    <title>Creating a new Smart Library</title>
+
+    <para>
+      To create a new Smart library, choose
+      <menuchoice><guimenu>Library</guimenu><guimenuitem>New Smart
+      Library...</guimenuitem></menuchoice> from the main menu.  The
+      New Smart Library dialog allows you to define the rules which
+      select which books will be displayed. Each rule is displayed on
+      one line. The first drop-down list gives you the choice of what
+      attribute of a book you are concerned with (e.g. Title or
+      Publisher). The second drop-down gives a choice of conditions
+      for that attribute (e.g. contains). Depending on the attribute
+      you choose, there may be a text box to enter text or numbers to
+      further define the condition. You can add another rule by
+      clicking on the <guibutton>+</guibutton> button. You can remove
+      any rule (except the last remaining rule) by clicking on the
+      <guibutton>-</guibutton> button.
+    </para>
+    
+
+    <para>
+      An example will illustrate the use of Smart Libraries. Let us
+      suppose you have a large collections of books by Terry
+      Practchett and you add the tag <quote>discworld</quote> to all
+      the books in the Discworld series. Let us create a Smart Library
+      for all his non-Discworld books.
+    </para>
+    
+    <figure id="new-smart-library-fig">
+      <title>A New Smart Library dialog</title>
+      <screenshot>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figures/smart_libraries_new_smart_library.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>A New Smart Library dialog showing two rules; The
+	    first is <quote>Author</quote> <quote>contains</quote>
+	    <quote>Pratchett</quote>, the second is <quote>Tags</quote>
+	    <quote>does not contain</quote>
+	    <quote>discworld</quote>.</phrase>
+	  </textobject>
+	</mediaobject>
+      </screenshot>
+    </figure>
+    
+    <para>
+      This is quite simple. We make the first rule select all
+      Pratchett books by selecting <quote>Author</quote> and
+      <quote>contains</quote> and typing <quote>Pratchett</quote> into
+      the text box. Now we click <guibutton>+</guibutton> to add
+      another rule. With the second rule we narrow the selection by
+      selecting <quote>Tags</quote> and <quote>does not
+      contain</quote> and typing <quote>discworld</quote> into the
+      text box. Also be sure that <quote>Match <quote>all</quote> the
+      following rules</quote> is selected.  When you click
+      <guibutton>New</guibutton>, the new Smart Library will be
+      created, and you should see the books it contains. You will also
+      be able rename the Smart Library immediately, or you can accept
+      the default name.
+    </para>
+
+    <para>
+      Remember, some attributes are boolean - they can either be
+      <quote>set</quote> or <quote>not set</quote> (for example the
+      <quote>Own</quote> attribute). A text box is not required for
+      rules concerning these attributes.
+    </para>
+  </section>
+
+  <!-- ======= Editing smart libraries ===== -->
+  <section id="edit-smart-library">
+    <title>Editing a Smart Library</title> 
+
+    <para>
+      To edit a Smart Library, select it in the Smart Library list,
+      right-click the Smart Library name and select
+      <guimenuitem>Properties</guimenuitem> from the pop-up menu. The
+      Properties dialog is the same as the New Smart Library dialog;
+      you can modify, add and delete rules.
+    </para>
+  </section>
+
+  <!-- ======= Renaming smart libraries ===== -->
+  <section id="renaming-smart-libraries">
+    <title>Renaming a Smart Library</title>
+
+    <para>
+      To rename a Smart Library, simply click on its name twice in the
+      Smart Library pane, and type in the new name. You can also
+      right-click on the name, and select
+      <guimenuitem>Rename</guimenuitem> from the pop-up menu.
+    </para>
+  </section>
+
+  <!-- ======= Deleting smart libraries ===== -->
+  <section id="delete-smart-library">
+    <title>Deleting a Smart Library</title>
+
+    <para>
+      To delete a Smart Library, select it in the library pane, either
+      right-click and select <guimenuitem>Delete</guimenuitem>, choose
+      <menuchoice><guimenu>Edit</guimenu><guimenuitem>Delete</guimenuitem></menuchoice>
+      from the main menu, or press the <source>Delete</source> key on
+      your keyboard. &app; will ask for confirmation before deleting
+    the Smart Library.</para>
+
+    <note>
+      <para>
+	Deleting a Smart Library does not delete any books, just the
+	set of rules by which books are selected for display. However,
+	the deletion cannot be undone.
+      </para>
+    </note>
+  </section>
+
+</section>