<chapter id="graphical-interface">
  <title>The graphical interface</title>
  
  <para>The graphical user interface is called &pyc;. It provides a
    simple  access  to the  most  common features  of the  underlying
    engine, &pyb; and lets you search, sort and modify bibliographic
    entries. Moreover, direct insertion of references into 
    <ulink type="http" url="http://www.lyx.org/"><application>Lyx
    </application></ulink> and <ulink type="http" 
    url="http://kile.sourceforge.net/"><application>Kile</application>
    </ulink>, direct queries on Medline, and
    saving selected references in different formats are also possible.
  </para>

  <sect1 id="gui-creating">
    <title>Creating a new database</title> 

    <para>When &pyc; is opened, you  can immediately begin to create a
    new database.  The type of  this database will be  determined when
    you will save it the first time.</para>

    <para>To  add   a  new  entry,   you  can  use   the  <menuchoice>
	<guimenu>Edit</guimenu>       <guimenuitem>Add</guimenuitem>
	</menuchoice> menu, directly the <guibutton>Add</guibutton> 
        toolbar button or click with the right button in the list window 
        and select <guibutton>Add</guibutton>.
    </para>
    
    <para>You will find more information on the main window's usage in
      <xref linkend="gui-navigate" />.</para>

  </sect1>

  <sect1 id="gui-opening">
    <title>Opening a database</title>
    
    <para>To    open    an    existing    database, click on the 
    <guibutton>Open</guibutton> toolbar button or go in the 
    <guimenu>File</guimenu> menu, and select <menuchoice>
      <guimenu>File</guimenu> <guimenuitem>Open</guimenuitem>
      </menuchoice>.</para>
    
    <figure id="figopen">
      <title>Opening a database</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/open.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; open file window.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>
    
    <para>A   file   selection  dialog   will   pop   up  (see   <xref
      linkend="figopen" />) and let you select a file. The type of the database
      can also be selected. Opening an existing database, the type can be guessed if
      you select <guibutton>- According to file suffix -</guibutton>.
    </para>
    <para>
      It is also possible to open a file at a remote location (as well as a local file)
      by typing the URI of the file (e.g. http://my.remote.site/pyblio.bib) using the 
      'Open Location' dialog, which can be invoked by the <menuchoice><guimenu>File</guimenu>
      <guimenuitem>Open Location</guimenuitem></menuchoice> menu item.
    </para>
  </sect1>
  
  <sect1 id="gui-navigate">
    <title>Navigating in the entries</title>
    
    <para>Once you have opened a  database, or started to create a new
      one, the  main window (see <xref  linkend="figmain" />) displays a
      list of all the entries on the top part of it. The fields 
      diplayed here can be configured under the <menuchoice><guimenu>
      Settings</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> 
      menu item.</para>

    <tip>
    <para>It is possible to display two types of combined fields: 
      <emphasis>-author/editor</emphasis> and <emphasis>-author/title-</emphasis>.
    </para>
    </tip>

    <para>Clicking on an entry displays its full content on the lower part of 
      the window. It is also possible to use the arrow keys to navigate in the 
      upper list.
    </para>

    <para>If an entry contains an <emphasis>URL</emphasis> field, 
      clicking on the small button next to the url, the appropriate 
      application is launched to view the target object 
      (e.g. PDF viewer for pdf files, web browser for http address).
      See <xref linkend="gui-edit" /> about how to add an URL field to 
      an entry. Alternatively, you can open the URL with the help of the 
      <menuchoice><guimenu>View</guimenu><guisubmenu>Resource</guisubmenu>
      </menuchoice> submenu item or the <menuchoice><guimenu>Resource</guimenu>
      </menuchoice> pop up menu provided for the item list. If an item contains one or 
      more viewable fields (like url) containing viewable resources, it is marked with 
      an icon at the left edge of the item in the upper part of the main window (see 
      <xref  linkend="figmain" />).
    </para>

    <tip>
    <para>You can set the viewable fields and the applications used to view the resources 
          in the 'Resource' tab under the <menuchoice><guimenu>Settings</guimenu>
          <guimenuitem>Preferences</guimenuitem></menuchoice> menu.
    </para>
    </tip>

    
    <para>Clicking     on    an     entry    while     pressing    the
      <keysym>Shift</keysym> key extends  the selection to the clicked
      entry. A  click while pressing  the <keysym>Control</keysym> key
      toggles the entry without altering  the state of the rest of the
      selection. With copy and paste, or by drag and drop you can copy 
      one or more selected entries into a new window/database.</para>

    <figure id="figmain">
      <title>The main window</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/main.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; main window.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>

     <para>Clicking the right button of the mouse in the list opens a
      contextual menu. With this menu you can:</para>
    
    <itemizedlist>
      <listitem>
	<para>add a new entry</para>
      </listitem>
      <listitem>
	<para>edit the currently selected items</para>
      </listitem>
      <listitem>
	<para>view the resource associated with the selected item</para>
      </listitem>
      <listitem>
	<para>delete the currently selected items</para>
      </listitem>
    </itemizedlist>
    
    <para>Note that some  of these menu options can  be disabled for a
      given database or entry,  provided that the corresponding action
      can't be  performed.</para>
    
    <para>By clicking  on the column  titles of the list,  you'll sort
      the entries according to the corresponding field.</para>
  </sect1>
  
  <sect1 id="gui-searching">
    <title>Searching</title>
    
    <para>&Pyc; offers  a quite powerful searching  mechanism. For searching 
      you can use the quick search entry of the toolbar or the search dialog. 
      To open the search dialog, click on <menuchoice> <guimenu>Edit</guimenu>
      <guimenuitem>Search</guimenuitem> </menuchoice> in the menu.

      The  dialog   that  appears  (see   <xref  linkend="figsearch" />)
      displays a search form at the top.</para>

    <figure id="figsearch">
      <title>The Search dialog</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/search.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; search dialog.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>
    
    <sect2 id="gui-searching-simple">
      <title>Simple searches</title>
      
      <para>With a simple  search, you can select the  field that will
	be searched  and you  can specify a  regular expression  to be
	matched.  <guibutton>- any  field -</guibutton> means that all
	the  existing fields will  be searched.  This is  usually more
	time-consuming.</para>

    </sect2>
    
    <sect2 id="gui-searching-expert">
      <title>Expert searches</title>
      
      <para>An expert search is an expression that looks like:</para>
      
      <programlisting>has('author','name') | -has('title','test')</programlisting>
      
      <para> Such  an expression means:  select the entries  where the
	field            <emphasis>author</emphasis>           matches
	<emphasis>name</emphasis>,   or   (symbol  <symbol>|</symbol>)
	where     the     field    <emphasis>title</emphasis>     does
	<emphasis>not</emphasis> match <emphasis>test</emphasis>.  The
	boolean          <symbol>and</symbol>         is         noted
	<symbol>&amp;</symbol>.</para>
      
      <para>There  are  other  commands  available for  this  type  of
	search:</para>
      
      <itemizedlist>
	<listitem>
	  <para><command>has_key(<varname>keyname</varname>)</command>
	    searches on a key name.</para>
	</listitem>
	<listitem>
	  <para><command>has_type(<varname>typename</varname>)</command>
	    searches for entries of a given type name.</para>
	</listitem>
	<listitem>
	  <para><command>any_has(<varname>value</varname>)</command>
	    searches  for the  given value  in  all the  fields of  an
	    entry.</para>
	</listitem>
	<listitem>
	  <para><command>before(<varname>field</varname>,
	      <varname>year</varname>,        <varname>month</varname>,
	      <varname>day</varname>)</command>  searches  for entries
	      where  the  specified  date  field  is  older  than  the
	      specified date.</para>
	</listitem>
	<listitem>
	  <para><command>after(<varname>field</varname>,
	      <varname>year</varname>,        <varname>month</varname>,
	      <varname>day</varname>)</command>searches   for  entries
	      where  the  specified date  field  is  younger than  the
	      specified date.</para>
	</listitem>
      </itemizedlist>
    </sect2>
    
    <sect2 id="gui-searching-hierarchical">
      <title>Hierarchical searches</title>
      
      <para>After a  search, only the selected items  are displayed in
	the main window.  It makes it convenient to  select a specific
	author, and then browse its publications for example.</para>
      
      <para> In addition, the results  of all the searches are kept in
	the  tree located  below  the search  form.  Therefore, a  new
	search can  be a refinement of  a previous one.  If you select
	the tree  item corresponding for  example to all  the articles
	written  by a certain  Nostradamus, you'll  be able  to select
	only those whose title contains the word eclipse.</para>
      
      <para>Right-clicking in this tree pops up a contextual menu that
	allows you to remove unuseful searches.</para>

      <para>To select the full list of database entries again, just
        click on the <emphasis>Full database</emphasis> item at the top
        of the search tree, or push the 'Esc' button on the keyboard when 
        you are in the main window.</para>
    </sect2>
    
  </sect1>

  <sect1 id="gui-sorting">
    <title>Sorting</title>

    <para>Clicking on the title of each column in the main index
    provides some rudimentary way of sorting a database. A much
    powerful method is to open the sort dialog (in <menuchoice>
    <guimenu>Edit</guimenu> <guimenuitem>Sort</guimenuitem>
    </menuchoice>). This menu, displayed in <xref linkend="figsort" />,
    gives a list of fields which can be used as sort criterions, plus
    a flag indicating how they are currently used. By clicking twice 
    on the item, it is possible to choose how the field will be used:
      <itemizedlist>
	<listitem>
	  <para>Nothing means the field is not in use.</para>
	</listitem>
	<listitem>
	  <para>A <symbol>triangle</symbol>-like symbol means sort in
	    <emphasis>ascending order</emphasis>.</para>
	</listitem>
	<listitem>
	  <para>An <symbol>upside down triangle</symbol>-like symbol
             means sort in <emphasis>descending order</emphasis>.</para>
	</listitem>
      </itemizedlist>
    </para>
    <para>The order in which the sorting is performed depends on the
    order in the list. To modify this order, simply drag and drop an
    item to change its position. To make this sort order default, it 
    can be saved by clicking on the <guibutton>Set as default</guibutton> 
    button.</para>

    <figure id="figsort">
      <title>The Sort dialog</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/sort.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; sort dialog.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>

  </sect1>

  <sect1 id="gui-edit">
    <title>Editing</title>

    <sect2 id="gui-edit-basic">
      <title>Basic editing</title>

    <figure id="figedit">
      <title>The Edition window</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/edit.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; edition window.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>
      
      <para>The    edition    window    is    represented    in    <xref
      linkend="figedit" />.  On  the  right  of  each  field,  a  symbol
      indicates if &pyb;  has been able to render  all the information
      given in that  field. For example, a BibTeX  field containing an
      unknown command  name cannot  be correctly represented.  In that
      case, &pyb; provides a  fake representation, and indicates it was
      not able to do  a good job on this field  by setting  a red symbol
      on its right, instead of a green one.</para>
    <warning>
      <para>If you edit such an  entry, you can loose  the additional
      information it  contained. To avoid this,  consider using native
      editing (see <xref linkend="gui-edit-native" />).</para>
    </warning>

    <para>To  edit the  entries, simply  type the  corresponding text,
      without  any   consideration  for  the   database  format  being
      used. For example, with <productname>BibTeX</productname>, don't
      add  any <symbol>{</symbol> or  special characters  to influence
      the result,  as they will be  quoted by the  system.  For fields
      requiring  names (like  author  and editor),  use the  following
      format:  type one  name per  line, in  the  <emphasis>last name,
      lineage, first name</emphasis> order. If an author or editor field
      has too many names, you can end the list of names with <emphasis>
      others</emphasis>; the standard bibtex styles convert this to 
      <emphasis>et al</emphasis>.</para>
    <para>In addition to the standard fields, you can create your 
     own fields using the <guibutton>Create Field</guibutton> button.
    </para>
    <tip>
      <para>You can customize the mandatory and optional fields for 
      the different type of entries. For example, associating the 
      <emphasis>URL</emphasis> field with a given type of entry, it is 
      possible to assign an url to an entry (e.g. the 
      location of the pdf version of an article or the address of a 
      website). See <xref linkend="figediturl" />. More information about 
      the association of fields can be found in 
      <xref linkend="gui-settings" />.</para>
    </tip>

    <figure id="figediturl">
      <title>The Edition window - Optional fields</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/edit2.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows the optional fields containing URL.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>

    <para>The  following  keyboard   shortcuts  are  available  during
      edition  (in   addition  to   the  standard  ones   provided  by
      Gtk):</para>
    <itemizedlist>
      <listitem>
	<para>
        <keycombo><keycap>Ctrl</keycap><keycap>TAB</keycap></keycombo>
        to jump to the next field</para>
      </listitem>
	<listitem>
	<para>
        <keycombo><keycap>Shift</keycap><keycap>TAB</keycap></keycombo>
        to jump to the previous field</para>
      </listitem>
      <listitem>
	<para>
        <keycombo><keycap>Ctrl</keycap><keycap>Enter</keycap></keycombo>
        to accept the modifications</para>
      </listitem>
      <listitem>
	<para><keycap>Esc</keycap> to cancel the edition</para>
      </listitem>
    </itemizedlist>

    <para>To specify a crossreference  to another entry, just drag the
      entry       from      the       main      list       to      the
      <guilabel>Crossreference</guilabel>   field.     To   remove   a
      crossreference,  drag  an  empty  selection on  the  field.   To
      unselect   all  the  entries,   you  might   need  to   use  the
      <keysym>Control</keysym>    key,   while    clicking    on   the
      entry.</para>
    </sect2>

    <sect2 id="gui-edit-native">
      <title>Native editing</title>

      <para>For databases  like BibTeX that provide  a specific syntax
	(called <emphasis>native</emphasis> syntax), it is possible to
	directly edit the entry in  this format. Just click the button
	called <guibutton>Native Editing</guibutton>  at the bottom of
	the window and  type the entry in its  native form.
      </para>
      
      <para>It is also possible to  type native commands in the normal
	editing window. For example, if  you want to use special LaTeX
	commands like  <command>\textbf</command> in a  title, you can
	type them  directly in the  Title field by preceding  the text
	with    a   <symbol>@</symbol>    symbol    (as   the    first
	character). After that symbol, you  have to use all the BibTeX
	conventions (braces, backslashes,...), as none of them will be
	escaped or modified by &pyb;.</para>

    </sect2>
    
  </sect1>

  <sect1 id="gui-lyx">
    <title>Using &pyc; with <application>LyX</application></title>
    
    <para>It  is possible  to directly  use &pyb;  in order  to insert
      bibliographic references  into LyX. It is done through the LyX
      <emphasis>server</emphasis>. The path of the LyX server pipe can
      be defined in the <menuchoice><guimenu>Tools</guimenu>
      <guimenuitem>Preferences</guimenuitem></menuchoice> dialog of LyX.
      The same path should be given in &pyb;'s settings 
      (the default value is ~/.lyx/lyxpipe).</para>
      
    <para>Then,  in &pyc;,  it is  possible to  select one  or several
      entries and insert their references into a running LyX simply by
      clicking  the <guibutton>Cite</guibutton>  toolbar button,  or 
      selecting the
      <menuchoice><guimenu>Cite</guimenu>
	<guimenuitem>Cite...</guimenuitem>
      </menuchoice>
      menu item.</para>

    <para>For the moment,  it is the user's job  to ensure that he/she
      inserts entries corresponding to the actual database being used.
      &pyc; does  not handle the full job  of bibliography generation;
      therefore  it is necessary  to use  <command>bibtex</command> as
      described in the LyX documentation.</para>
    <note>
    <para>&pyc; can interact with <application>Kile</application>
     (&gt;= 1.6) practically in the same way, since <application>Kile
     </application> can also read <emphasis>lyx pipe</emphasis>.</para>
    </note>
  </sect1>

  <sect1 id="gui-formats">
    <title>Saving selected entries in different formats</title>

    <para>Selected entries can be saved in different formats using  
    the <menuchoice><guimenu>Cite</guimenu> <guimenuitem>Format...
    </guimenuitem></menuchoice> menu item (<xref linkend="figformat" />).
    </para>

    <figure id="figformat">
      <title>Formatting entries</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/format.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; formatting entries dialog.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>


    <para>As a result, a formatted output file is generated according 
    to a bibliographic style, either in HTML, LaTeX, Raw or Text format. 
    The &pyb; package contains some bibliographic styles, but own styles
    can also be created easily. See also 
    <xref linkend="script-scripting-existing-pybformat" />.</para> 
  </sect1>

  <sect1 id="gui-pubmed">
    <title>Searching in PubMed</title>
    
    <para>With &pyc;, it is possible to perform a Medline search. To 
    use this option, click on the <menuchoice><guimenu>File</guimenu> 
    <guimenuitem>Medline query...</guimenuitem></menuchoice> menu item. The
    upcoming window is represented in <xref linkend="figmed" />.</para>

    <figure id="figmed">
      <title>Medline query</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/medline.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; medline search dialog.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>

     <para>The keyword, you are looking for, should be written into the 
     <emphasis>Search PubMed for</emphasis> field. As it can be seen 
     in <xref linkend="figmed" />, a number of options (limitations) can
     be set, which can help to obtain an optimal search result. The 
     matched references, resulted in by the query, appear in the main 
     window as a new database.</para>
  </sect1>

  <sect1 id="gui-settings">
    <title>Configuration</title>
    
    <para>Under the <menuchoice><guimenu>Settings</guimenu></menuchoice>
    menu, you can find some options to customize &pyb;.</para>

    <sect2 id="gui-settings-fields">
    <title>Entry types and field names configuration</title>

    <figure id="figfields">
      <title>Configuration of fields and entry types</title>
       <screenshot>
        <mediaobject>
         <imageobject>
          <imagedata fileref="figures/fields.png" format="PNG"/>
         </imageobject>
         <textobject> 
	      <phrase>Shows &app; fields and entry types configuration
              dialog.</phrase>
	 </textobject> 
        </mediaobject>
       </screenshot>
    </figure>

    <para>Selecting the <menuchoice><guimenu>Settings</guimenu> 
    <guimenuitem>Fields</guimenuitem></menuchoice> menu item, it 
    is possible to add or remove fields, to set their type, and 
    to define which fields should be associated with a given type of 
    entry. In addition, the mandatory and optional fields are also can
    be varied. In <xref linkend="figfields" />, as an example, the
    association of the Article entry type can be seen.</para>
    </sect2>
    <sect2 id="gui-settings-pref">
    <title>Preferences</title>

    <para>Clicking on the <menuchoice><guimenu>Settings</guimenu> 
    <guimenuitem>Preferences</guimenuitem></menuchoice> menu item, a 
    lot of configuration options can be controlled. Such options are, 
    for instance, settings of the different type of bibliographic 
    database formats, autosave, size of history, defult editing mode,
    the default type of a newly created entry, and resource configuration.
    </para>
    </sect2>
  </sect1>
</chapter>