/usr/share/doc/bibus/html/en/usingBibus.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>usingBibus</title>
</head>
<body>
<ol id="mozToc">
<!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6-->
  <li><a href="#mozTocId303624">Using Bibus</a>
    <ol>
      <li><a href="#mozTocId508510">First Start</a></li>
      <li><a href="#mozTocId863772">Main interface </a>
        <ol>
          <li><a href="#mozTocId242645">Keytree</a></li>
          <li><a href="#mozTocId932889">Reference
list</a></li>
        </ol>
      </li>
      <li><a href="#mozTocId99552">Importing references</a></li>
      <li><a href="#mozTocId194504">Searching</a>
        <ol>
          <li><a href="#mozTocId704764">Searching
in
the database</a></li>
          <li><a href="#mozTocId54422">Live
searches</a></li>
          <li><a href="#mozTocId679218">Searching
PubMed</a></li>
        </ol>
      </li>
      <li><a href="#mozTocId492878">Editing references</a></li>
      <li><a href="#mozTocId54305">Setting
preferences</a>
        <ol>
          <li><a href="#mozTocId409706">System-wide
preferences</a></li>
          <li><a href="#mozTocId202695">User preferences </a></li>
        </ol>
      </li>
    </ol>
  </li>
</ol>
<h1><a class="mozTocH1" name="mozTocId303624"></a>Using Bibus<br>
</h1>
<h2><a class="mozTocH2" name="mozTocId508510"></a>First Start</h2>
After installation, a menu item should be present in your "Start Menu"
under Windows or under the menu item "Office". Starting bibus the first
time will open the FirstTime Wizard:<br>
<br>
<div align="center"><img alt="FirstTime Wizard Window"
 src="../ScreenShots/FirstStart.png" height="508" width="779"><br>
<br>
<div align="left">Just answer the questions. For more detailled
instructions with screenshots have a look at the <a
 href="http://bibus-biblio.sourceforge.net/wiki/index.php/First_connection_wizard">wiki
page</a>.<br>
</div>
</div>
<h2><a class="mozTocH2" name="mozTocId863772"></a>Main interface<br>
</h2>
<p style="margin-bottom: 0cm;" align="center"><a name="fig_Main"></a><img
 src="../ScreenShots/main.png" name="Graphic1" alt="main interface"
 border="0" height="550" width="789"></p>
<p align="left"><br>
The main interface of Bibus should be intuitive for
anybody used to a mail reader. On the left is a tree with keys. Each
key is associated with a list of references. When the key is
selected, the references associated with this key are listed in the
listView located on the top panel of the right side of the window.
When a reference is selected in this list, this reference is shown at
the bottom right of the window. In the figure above, the key selected
is 'References/Antibodies/Therapy', the reference selected is
'Brodie2009' and
this reference is displayed.</p>
<p align="left">The bottom <b><font color="#ff0000">Reference view</font></b>
has 4 choices:</p>
<ul>
  <li><b>Style</b> As formatted using the current style.</li>
  <li><b>Details</b> Detailed view of the fields.</li>
  <li><b>Keys</b> All the keys associated with the currently selected
reference.</li>
  <li><b>Modif</b> Author and Date of the creation and last
modification of the reference.<br>
  </li>
</ul>
<p align="left">
In the status bar, the following information is
displayed from left to right: <br>
help messages | number of
references in the selected key : number of selected references |
style selected.</p>
<h3 align="left"><a class="mozTocH3" name="mozTocId242645"></a><font
 color="#ff0000"><b>Keytree</b></font></h3>
<p align="left">The keys are orderer in a non rooted tree. There are 8
main categories. You cannot modify or add any key at this level. Let
first describe these main categories:<br>
</p>
<ul>
  <ul>
    <li><b>All my references</b>. This keys contains all your
references.</li>
    <li><b>References.</b> It is
where you can classify your references. You can add subkeys, modify
their names, move them using drag&amp;drop, etc... To do that you can
either use the popup menu that appears when you right click on the keys
or the third menu 'Reference'. The preferred way is to right click on
the key since there are more choices than in the menu and only the
available choices will be displayed.</li>
    <li><b>Tagged.</b> This category allows quick organization of your
references. When you go through your reference, you may sometimes need
to 'tag' a reference to remember it. In such a case, just select the
reference and hit "Ctrl + T" and the reference will be
copied under the key 'tagged'.</li>
    <li><b>Queries.</b> We will see
later how to define <a href="#queries">queries.</a>
You can see them as 'live search'. You can define a search and save it.
When you click on this query, Bibus looks in the database and show the
references that fulfill the search. If you change the database, the
search will be automatically updated. In fact a query is simply an SQL
query.</li>
    <li><b>PubMed Search</b>. When you do a <a href="#PubMed">PubMed</a>
search, the result is available here. </li>
    <li> <b>Import buffer</b>. When you import a file (Medline or
EndNote/Refer), the result is available here.</li>
    <li> <b>Cited.</b> If the connection with OOo is active, all the
citations
cited in the current OOo document are displayed under this key.</li>
    <li><b>Unclassified.</b> The reference available in the database
but that you did not drop under any key under the key References is
listed here.<br>
    </li>
  </ul>
</ul>
<h3 align="left"><a class="mozTocH3" name="mozTocId932889"></a><font
 color="#ff0000">Reference
list</font></h3>
<p align="left">Here are displayed all the references associated with
the currently selected key. Again, you can manipulate them by right
clicking on them or by using the menu 'Reference'.<br>
An important
way to manipulate the references is by using drag &amp; drop. For
instance in the figure above, I would like to associated the selected
reference(s) (Briodie2009) with the key 'References/Cancer'. I can drag
&amp; drop it on the key
References/Mes Papiers/Antibodies. If you now select this key, you
will see that the dropped reference is there. If you need to unfold a
key for dropping the reference, you can move the cursor (during the
drag &amp; drop) over the (+) before the key name.<br>
It is important
to understand what happens when you do that:</p>
<ul>
  <li>
    <p style="margin-bottom: 0cm;" align="left">You don't really move
the reference. In fact you just create a link between the reference and
the key. You can see that as a shortcut under windows or a symbolic
link under linux. </p>
  </li>
  <li>
    <p style="margin-bottom: 0cm;" align="left">You can drag from any
key but you can only drop to the key 'References' and its children
simply because it does not make sense to drag on the other keys since
their content is defined by Bibus. </p>
  </li>
  <li>
    <p style="margin-bottom: 0cm;" align="left">By default, drag &amp;
drop is equivalent to Cut/Paste, but in some cases (when the reference
cannot be deleted from the source) it is Copy/Paste. In fact when the
source is References and its children it is a Cut/Paste, and otherwise
Copy/Paste. As usual, you can force Copy/Paste by holding down the Ctrl
key when dragging. </p>
  </li>
  <li>
    <p style="margin-bottom: 0cm;" align="left">Because we are just
creating links it is very economic in term of disk usage. So, don't
hesitate to associate a reference with several keys. </p>
  </li>
  <li>
    <p align="left">Since it is a link, if you modify the reference
under any of the keys, you will also modify the reference in the other
places (in 'All' and in the other keys) not only for yourself but also
for the other users of the database.</p>
  </li>
</ul>
<p align="left">To edit (create) a reference, select Edit (New) in the
popup menu or in the menu 'Reference'. You can also double click on
the selected reference(s). You will get a <a
 href="../ScreenShots/refeditor.png">reference
editor</a> that allow you to modify and see all the fields.</p>
<p align="left">Finally
the last popup menu choice is 'openURL' (or Middle click with the
mouse under linux). If the URL field of the selected reference(s) is
not empty,
the&nbsp; default navigator will open with the URL selected. For
instance, the import filter for PubMed automatically put in the URL
field the URL of the reference in PubMed.<br>
<br>
<font color="#ff0000"><font color="#ff0000"><i></i></font><i></i></font>If
your navigator is
correctly configured, you can use the URL field to put a link to a
"locale" copy of the paper. If you have on your disk (or
somewhere else) a pdf version of the following paper:</p>
<pre style="margin-bottom: 0.5cm; text-align: left;">Marx.pdf located in /home/toto/pdf/</pre>
<p align="left">put, in the URL field</p>
<pre style="margin-bottom: 0.5cm; text-align: left;">file:///home/toto/pdf/Marx.pdf</pre>
<p align="left">When you select 'openURL', the webbrowser will be
called and will
open Acrobat (or xpdf, ...) to handle the document.</p>
<p></p>
<h2><a class="mozTocH2" name="mozTocId99552"></a>Importing references</h2>
If you have a database of references, Bibus can import them. Bibus
understand three formats, Medline, Refer and RIS. You must first change
your database to one of these before importing it.<br>
There are two ways to import references:<br>
<ul>
  <li>In the menu File, choosing Import/Refer (Import/RIS or
Import/Medline) will open a File chooser. Just select the file
containing your references, click OK, select the encoding in the next
dialog (the selected default should be OK in most cases), and the
references will be imported in Bibus.</li>
  <li>In the menu File, choosing 'Import/Text Window' will open a text
window in which you can paste your reference. Select the correct format
and click 'Import'.</li>
</ul>
Once imported, the references will be found under the key 'Import'. If
you want to control them, you can double-click to see all the fields.<br>
<font color="#ff0000">The imported references are stored in a temporary
area</font>. If you quit
Bibus they will be lost. <font color="#ff0000">To save them
definitely, copy them and paste
them (or drag/drop) in the References key or in one of its children.</font><br>
<h2><a class="mozTocH2" name="mozTocId194504"></a>Searching</h2>
<p>Bibus uses a powerful yet simple search engine. You can either
search the <a href="#search">database,</a>
<a href="#PubMed">PubMed</a>
on the Web of you can use <a href="#queries">'Live
queries'</a> for
automatic reference classification. The first two types of search are
also directly available in the tool bar.</p>
<h3><a class="mozTocH3" name="mozTocId704764"></a><a name="search"></a>Searching
in
the database</h3>
<p style="margin-bottom: 0cm;">By choosing the menu Search/Search
(Ctrl S) you will get the following dialog:</p>
<p style="margin-bottom: 0cm;" align="center"><img
 src="../ScreenShots/search.png" name="Graphic2" alt="search"
 align="bottom" border="0" height="298" width="822"></p>
<p>First on the top left, you can choose the mode:</p>
<ul>
  <li>
    <p style="margin-bottom: 0cm;">Normal: The mode seen in the figure
above</p>
  </li>
  <li>
    <p>Expert: In this mode, you can enter any search string. You must
enter the where clause of the SQL query. Normally, you don't need to
use this mode. An easy way to use it is, first to use the Normal mode,
then click on expert: you will get the SQL translation of your actual
query. Just modify it. </p>
  </li>
</ul>
<p>On top right you have the choice between:</p>
<ul>
  <li>
    <p style="margin-bottom: 0cm;">Current key. The search will be
restricted to the currently selected key. If the selected key does not
allow search (Online, Import, Queries), this choice won't have any
effect. As the dialog is non modal, you can change the selected key
while the dialog is open. If 'Current key' is selected, the search will
be done on the key selected when you hit the Search button. </p>
  </li>
  <li>
    <p>All references. The search will be done on the whole database. </p>
  </li>
</ul>
<p>The rest of the dialog is self explanatory. For those unfamiliar
with SQL:</p>
<ul>
  <li>
    <p style="margin-bottom: 0cm;">LIKE is a substring search. LIKE
antibod will match antibodies, antibody, etc.. (For MySQL experts:
Bibus automatically adds % before and after the string).</p>
  </li>
  <li>
    <p>= is exact match. This means that the <i>whole field</i> must
be equal to your query. </p>
  </li>
</ul>
<p>Finally, 'Main Fields' allows a search in 'interesting fields'.
For instance, usually we are not interested in searching the URL
field. The fields included in 'Main Fields' are displayed at the top
of the dialog. 'Main Fields' definition can be changed in the
<a href="#preferences">preferences</a>.<br>
<br>
When you use the tool
bar box for searching, the entered string will be search against
'Main Fields' with a LIKE clause. You can also enter an expert search
in the tool bar for instance something like :</p>
<pre style="margin-left: 1.06cm; margin-bottom: 0.5cm;">authors LIKE '%Einstein%' and year = '1912'</pre>
<p>You can put any character in the search since the string will be
converted from unicode to 'UTF-8' encoding before searching the
database.</p>
<h3><a class="mozTocH3" name="mozTocId54422"></a><a name="queries"></a>Live
searches</h3>
<p>When you right click on the 'Queries' key, you can select 'New
query'.&nbsp; Bibus will first ask you for a name then will open the
same dialog than for <a href="#search">search</a>
except that the
search is restricted to the whole database and that you cannot select
'Current key'.<br>
When your search/query is defined, you can save it
and an item, corresponding to this search, will appear as a child of
'Queries'. Each time you click on this item, the database is searched
and the result displayed. If the database changes, the result of this
search will change. It is important to note that if you change the
definition of 'Main Fields' the query result won't change because the
definition of 'Main Fields' is stored when the query is defined.<br>
You
can edit the query by right clicking the key but only in expert mode.
So, except for simple modifications, it may be easier to delete the
query and define a new one.</p>
<h3><a class="mozTocH3" name="mozTocId679218"></a><a name="PubMed"></a>Searching
PubMed</h3>
<p>You can access PubMed on the Web. This is probably only of
interest to people working in the fields of biology and medicine.
Again you can either use a 'Normal' or an 'Expert' mode.</p>
<ul>
  <li>
    <p style="margin-bottom: 0cm;">The 'Normal' mode is simple to use. </p>
  </li>
  <li>
    <p>In the 'Expert' mode, the text is sent directly to PubMed. It is
up to you to correctly format it. See the <a
 href="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=PubMed">PubMed
site</a> if you need to use this mode. Again, as for search, you can
start with the 'Normal' mode, click on 'Expert' and then just modify
the text to suit your needs. This is a kind of assisted expert mode. </p>
  </li>
</ul>
<p>At the top left you can select the number of results that you want
to import. The default is to import the first 20 records. The choices
are self explanatory.<br>
The result of the search will be displayed
under the key 'Online'. Each search will replace the previous one. It
is important to note that it is a temporary storage. If you quit
Bibus and start it again, your search will be lost. If you want to
copy some of the results in the database, just drag and drop them to
the 'Reference' key or one of its children. You can use any of the
usual combinations of shift and ctrl to select more than one
reference at a time. <br>
You can use the tool bar to perform a PubMed
search. Your string will be used as when you use the Web interface to
PubMed. Because the search will download only the first 20 records
(PubMed default) it is a good idea to narrow your search. You can
change this default of 20 records in the PubMed search dialog, bibus
will remember your choice.<br>
</p>
<h2><a class="mozTocH2" name="mozTocId492878"></a>Editing references</h2>
You can edit a reference by double-clicking it in the list or by
choosing the menu item Reference/Edit or the context menu (Right-click
in the list) Edit. <br>
You can also open an empty editor to create a new reference by choosing
the menu item Reference/New (Ctrl+N), by right-click in the list and
choosing 'New' or by Right-clicking in a tree item and choosing New in
the context menu. The new reference will be created under the currently
selected key or under the key you Right-clicked.<br>
The Editor look like this:<br>
<a name="Reference_Editor"></a><img alt="Reference Editor"
 src="../ScreenShots/refeditor.png" style="width: 484px; height: 558px;"><br>
There are three tabs.<br style="font-weight: bold;">
<span style="font-weight: bold;">Main Fields</span> should normally be
filled since they correspond to fields needed by most styles.<br>
<span style="font-weight: bold;">Supplementary Fields</span> may be
partially filled and correspond to less frequently used values for the
current reference type (for instance, the issue Number for an article.<br>
<span style="font-weight: bold;">Other Fields</span> are the other
possible fields.<br>
There is a Choice at the top for the reference type. By default it is
ARTICLE. If you change this type, you will notice that the fields
change. This is because the Required fields (Main) fields for a BOOK
are different than the fields required for an ARTICLE or an URL. If the
default values for Main/Supplementary/other fields don't suit your
needs, you can change them in the "Preferences" under the "Editor" tab.<br>
When you edit a reference by default you cannot change the Identifier
field. This is because changing this field may be dangerous if the
edited reference is used in one of your article. Bibus won't be able to
find the reference to format your article in OpenOffice.org. You can
however change the identifier by first checking the "Edit identifier"
check box.<br>
<span style="font-weight: bold;"><a name="Editor_Shortcuts"></a>Shortcuts</span>.
The window contains a menu bar. When you first start Bibus, this
menubar will be empty. To activate it you must set a list of categories
in the preference <a href="#Pref_Shortcuts">"Shortcuts" tab</a>. In
the <a href="#Reference_Editor">Screenshot above</a>, we have defined
three categories: Journal, Author and Divers. These category names are
just to help you classify your shortcuts and don't have to match the
fields names. If you click in one of these categories the menu will
look like this:<br>
<img alt="shortcuts menu" src="../ScreenShots/shortcuts.png"
 style="width: 486px; height: 557px;"><br>
To <span style="font-weight: bold;">insert</span> any of the menu item
in a field, just locate your cursor at the correct position in the
correct field then choose the menu item. For instance, you can insert
"FEBS Lett" with a single click in the corresponding menu item in the
Journal field. This can save you a lot of typing (and errors).<br>
To <span style="font-weight: bold;">save</span> a shortcut, you can
either:<br>
<ul>
  <li>Select some text in a fields and choose "Capture selection". The
current selection will then appear at the bottom of the menu.</li>
  <li>Select "Edit shortcuts ...". In the window that appear you can
edit any shortcut, sort them and capture them from the database. This
last option os explained below.</li>
</ul>
<span style="font-weight: bold;">Capturing</span> shortcuts from the
database. Instead of entering each shortcut by hand, you can decide
that you want to&nbsp; capture all the journal names present in the
database and put them in your shortcut list called journal. Here is how
to do that:<br>
<ul>
  <li>Create in the preference/Shortcuts a category called 'Journal'
(or anything else)</li>
  <li>Click the "Edit ..." button</li>
  <li>Click the "Capture ..." button</li>
  <li>Select "Journal" in the menuChoice</li>
  <li>Don't check "using separator"</li>
  <li>Click OK</li>
  <li>All the journals available in the database will now appear in the
Shortcut window</li>
  <li>Close the Preference editor by clicking OK</li>
</ul>
You can do the same in the reference editor by choosing "Edit shortcut"
in the menu but only if the shortcut category has been previously
defined in the preference/Shortcuts tab.<br>
Finally, the "using separator" option must be used with fields
containing multiple items. For instance, if you want to capture all the
authors from the database, check this option and choose ";" as the
separator. Bibus will split the author fields using this separator
before collecting the author names. This is normally what you want
since multiple authors in the author field are separated with ";" and
you want each author to appear as an independent shortcut.
<h2><a class="mozTocH2" name="mozTocId54305"></a><a name="preferences"></a>Setting
preferences</h2>
<h3><a class="mozTocH3" name="mozTocId409706"></a>System-wide
preferences</h3>
If you want to set preferences for all users, you can set many
variables in the file "bibus.config".<br>
This file is located either in the BIBUS directory or in the /etc/
directory (Debian and other UNIX in the future).<br>
This file is sourced as a Python file after the BIBbase.py file which
contains the system-wide constants. Usually you will set in this file
new values for the constants defined in BIBbase.py.<br>
For instance, you may have a central MySQL database for all the users
named 'biblioDB'. Put in the bibus.config file the following lines:<br>
<pre>import BIBbase<br>BIBbase.DB_STARTUP = 1                          # 0 = last used db used at startup. 1 = default db<br><br>BIBbase.DB_TYPE MySQL                           # type of database used 'MySQL','SQlite', etc... =&gt; modules dbBibMySQL,dbBibSQLite, etc...<br><br>DB_NAME = 'biblioDB'                            # Default MySQL database name<br><br><br>BIBbase.PORT = 3306                             #<br> server port used by the MySQL deamon<br>BIBbase.HOST = 'servername'                     # server running the MySQL deamon<br><br></pre>
Because this file is read as a&nbsp; python file, you can of course use
python scripts. <br>
<pre></pre>
<h3><a class="mozTocH3" name="mozTocId202695"></a>User preferences<br>
</h3>
<p>Select the menu Edit/Preferences to set some Bibus
preferences.<br>
There are three tabs:<br>
</p>
<ul>
  <li><b>Journals.</b> This is a list of Journal names and
abbreviations. You must use the first column "PubMed Journal name" to
enter the journal in your references. You will be then able to
automatically convert by chosing the correct option in your style
definition, either to the "ISO abbreviation" or the "Full journal name"
when you insert your citation in OOo/Word. See the <a
 href="usingOOo.html">next chapter</a> to see how to define/modify a
style.<br>
  </li>
  <li><span style="font-weight: bold;"><a name="Pref_Shortcuts"></a>Shortcuts</span>.
You can define here categories of shortcuts. These shortcuts will
appear has menu item in the reference editor. You can define the list
of shortcuts associated with any of the categories by double-clicking a
category of the "Edit ..." button. See the <a
 href="usingBibus.html#Editor_Shortcuts">reference
editor</a> help to know how to use them.</li>
  <li><span style="font-weight: bold;">Paths</span>. This setting
contains for the moment a single path. You can set this path if you
want to put all your cited paper&nbsp; in a single location (usually as
Acrobat pdf files). By default, when you click in the "URL/File" button
in the reference editor, the file dialog will open this directory. In
addition, the file location is saved as file:///$FILE/toto.pdf instead
of the absolute path. You can thus move the directory containing you
pdf files to a new location and have all your references still pointing
to the correct location by changing this setting.</li>
</ul>
There are extra preferences that you can access by clicking "Advanced
Preferences" at the bottom-left:<br>
<ul>
  <li>
    <p style="margin-bottom: 0cm;"><span style="font-weight: bold;">Display</span>
options. This first tab will
change the way the <a href="#fig_Main">Main
window</a> is displayed. You can change the fields displayed in the
list, their order and the sort order of the references. You can also at
the bottom change the colors of the displayed reference (panel at the
bottom right of the Main view) and to choose if the column width must
be fixed or automatically adjusted.</p>
  </li>
  <li><span style="font-weight: bold;">Printing</span> options. You can
choose which fields will be printed for
each reference type and the color and style of the fields.&nbsp;<span
 style="font-weight: bold;"></span></li>
  <li><span style="font-weight: bold;">Search</span>
options. It is where you
define what 'Main fields' means in the <a href="#search">search</a>
and <a href="#queries">query</a>
dialogs.</li>
  <li><span style="font-weight: bold;">Duplicates</span> options. If
you set this option, when you copy a reference in Bibus using
copy/paste or drag&amp;drop (after an import or a Search in PubMed),
Bibus will look in the current database for an identical record. You
set here what an identical record is, that is which fields must be
identical and if the comparison is case sensitive or not. If Bibus find
an identical record, Bibus will either not copy the new reference in
the database ("keep the old reference") or replace the old record with
the new one ("keep the new reference"). The first option is presumably
the better and it is the default, but the second option may be used to
update references in the database with new updated or more complete
records.<br>
    <span style="font-weight: bold;"></span></li>
  <li><span style="font-weight: bold;">Reference Editor.</span> You can
define in
this dialog for each reference type the
Main and Supplementary fields. This affect 2 aspects of Bibus:</li>
  <ul>
    <li>It will change the fields present in the tabs of the reference
editor when you double-click a reference</li>
    <li>It will change the fields displayed at the bottom-right of the <a
 href="#fig_Main">Main
window</a> (main fields of the current reference).<span
 style="font-weight: bold;"></span>&nbsp;<span
 style="font-weight: bold;"></span></li>
  </ul>
  <li><span style="font-weight: bold;">Database</span>
options.&nbsp;</li>
  <ul>
    <li>On top-left you can choose the
type of database engine used, MySQL or SQLite. </li>
    <li> Database used at startup. The
default is to use the last database used (the&nbsp; one used when you
exited Bibus for the last time). However you can also select 'default'
and define the database. This is useful if you want to always connect
to the same database, but from time to time want connect to another one
without changing your default settings. </li>
    <li> Finally, If you have chosen 'MySQL' you can decide to store
your password. This way you won't have to enter your MySQL password
when you start Bibus. This is not secure at all however since your
password is written in the .bibus configuration file (or in a registry
key). If you know a good way to store passwords securely, please let me
know.</li>
  </ul>
  <li> <b>Word Processor.</b> You can change your choice between Word
and OOo.<br>
  </li>
</ul>
</body>
</html>
bibus-doc-en 1.5.2-4 / usr / share / doc / bibus / html / en / usingBibus.html
