1 This is the manual of B3, version 0.4. Copyright c Julien Dutheil, Christian Wiethol

Transcription

1 B3 Manual

2 1 This is the manual of B3, version 0.4. Copyright c Julien Dutheil, Christian Wiethol

3 i Table of Contents 1 The B3 Environment Databases Importing and file formats The BibView window Scanning a directory Fetching Pubmed Using external applications Extended functions The journal database The Journal Dictionary Checking journal names Switching between Full and Abbreviate modes The author database What is it for? How does-it work? Adding entries to the author database Searching a database (beta) Using style-sheets Interacting with word processors Exporting to OpenOffice using a flat file Export to a Text/CSV file The Database Configuration Dialog window Exporting a database Importing a Text/CSV file into OpenOffice Creating a new database Setting up the bibliography database You re done :-) Exporting to OpenOffice using MySQL Using L A TEX Processing OpenDocument texts Known issues and how to avoid them Index

4 Chapter 1: The B3 Environment 1 1 The B3 Environment When you launch B3, you have a void desktop with a menu bar. Some features are not available since no database is open. However you may configure a few things if you want. To open a existing database, click on the File menu, Read item. To create a new database, click on the File menu, New item. Figure 1.1: The B3 environment. No database is currently loaded. 1.1 Databases Databases are the main components in B3. A database is actually a set of entries, indexed by a unique key. Each entry has a type (e.g. article, book) and contains fields (e.g. title, authors, journal). The set of available fields depends on the entry type. Two graphic components are directly linked with databases: 1. The Database Editor: list all entries, show a few description (Key, Authors, Year, Title). Allow sorting, search, edition of existing entry, addition or deletion of new entries, importation from other databases or files. 2. The Entry Editor: appears when you double-click on an entry in the list. Here you can edit each field of an entry and modify its type.

5 Chapter 1: The B3 Environment 2 Figure 1.2: A database with several entry, with one being edited. The first internal frame from the left represents a database, with all entries in a table. It is possible to sort alphabetically (a-z,0-9) by clicking on the header. To sort anti-alphabetically (z-a,9-0), click on the header while maintaining SHIFT down. The bottom panel is used to display search results. The second internal frame is an Entry Editor, associated to the database. It is used to edit and display each entry. It can be opened by double-clicking on an entry in the database, or on a search result. Le last window is part of the Entry Editor. It allow the edition of author/editor names. B3 uses its own file format for storage, which can be seen as a XML version of the Bibtex format. B3 proposes two versions of this format: *.b3d files are text/xml files, and *.b3z and zipped xml files. The later format leads to smaller files, but writing and reading is slower. You can set the level of compression in the Configure panel. 1.2 Importing and file formats Importing data means that you can add data from other formats into a B3 database. B3 can import data in *.b3d and *.b3z format, but several additional formats are available. However, it is not possible to manage a database in one these formats, they are not fully implemented for now and they could lead to a loss of data. A list of available formats for import is given in the following table: Format: Description: Implementation level: *.b3d ; *.b3z B3 databases Full *.bib Bibtex file Full Pubmed text Text output of Pubmed (deprecated, use XML database instead) Pubmed xml XML output of Pubmed Full database RIS Reference Manager(c) format Articles only for now

6 Chapter 1: The B3 Environment 3 EndNotes(c) export EndNotes(c) export format 1 Articles only for now It is also possible to scan recursively a directory for bibliographic data, and to fetch the Pubmed database. whatever the importing procedure, the final step is the same: the entries are displayed in a BibView window The BibView window. Once imported, entries appear in a special read-only component called BibView. This allows you to select which data you want to add to the database by selecting them. An integrated Entry Editor is available in right part of the panel. Figure 1.3: The BibView component: a read-only database viewer and entry selector for import Scanning a directory This piece of utility try to import several files in a directory according to their extension. The dialog allows yo to specify the file types you want to look for. You also have to specify the directory to check, and tell if you want to perform a recursive search. It is also possible to automatically generate keys. Currently, the only available option is first author name + Year. the Default option keeps the original key. 1 This is a plain text, tagged format, not the binary.enl EndNotes file format! You have to export your file in this format using the appropriate EndNotes filter.

7 Chapter 1: The B3 Environment 4 Figure 1.4: Automatic scanning of directories for bibliographic data. The results appear in a single BibView window Fetching Pubmed It is possible to fetch Pubmed, by specifying a key, or by performing a search. The syntax used is the one specified by Pubmed (see tutorial/m1001.html for a complete tutorial). Figure 1.5: Fetching Pubmed... By default, only the 20 first entries are shown. It is possible to see the next 20 entries by clicking on the Next button, and/or to change the number of entries to display by setting the corresponding spinner. Finally, the Resume button reset the counters to their initial state. 1.3 Using external applications On several occasion, B3 may use external software installed on your system to display documents. In order to do so, you have to register them in the Options menu, Configre Mime-types submenu item. This will open a dialog box with possibility to add entries. There are two types that you will probably need: OpenDocument To be able to open OpenDocument (text) files. With open office or any OpenDocument editor (can be openoffice.org3, oowriter, kwrite, abiword, depending on your system and preference). HTML To be able to display web pages. This is used by the Bookmarks menu for instance. This will typically be something like firefox or opera, but any other browser or web editor can be used here. Finally, you can add any document of your choice to bibliographic entry, and visualize them directly by providing a type. You just have to register the corresponding type in this dialog box after all. For instance, you will probably want to do something like

8 Chapter 1: The B3 Environment 5 PDF With command acroread, evince, okular, xpdf or whatever. Please note that the command you provide should be accessible, since it will be used verbatim in a system call. A secure option consists in providing the absolute path of the corresponding program on your system.

9 Chapter 2: Extended functions 6 2 Extended functions 2.1 The journal database Articles entries contain a field named Journal. Journal may be displayed as fully named or abbreviated, for instance: Proceedings of the National Academy of Sciences of the USA or Proc.Nat. Acad. Sci. or PNAS The Journal Dictionary B3 includes a database with a set of journal names and corresponding abbreviations. You can access this database via the menu Journal -> Show Journal Dictionary Editor. You can edit this database providing you selected the corresponding check-box in the Options menu. Figure 2.1: Browsing the journal database Checking journal names When reading or importing a database, B3 can check if the journal fields are present in the database and warn you if not. In order to do so, select the corresponding check-box in the Options menu. When editing an entry, a pop-up window shows up to show you all possible completions. This window can also be displayed via the Journals menu Switching between Full and Abbreviate modes This is performed via the Options menu. Check the Use abbreviations check-box to switch to abbreviate mode. Check the Use dotted abbreviations check box to display dotted abbreviations (ie Proc. Nat. Acad. Sci. instead of Proc Nat Acad Sci). NB: This is only possible for entry whose journal is present in the dictionary. NB2: The selected mode will be used when processing the database with XSLT.

10 Chapter 2: Extended functions 7 Figure 2.2: Automatic insertion of a journal name. 2.2 The author database From version 2.50, I added the authors database functionality What is it for? Managing an authors database may be useful to edit entries, you just have to choose the author in a list instead of typing the whole name and stuff. An author database may also be useful to store additional information on authors, like and address How does-it work? A file named AuthorsDb.xml is created in the user personal directory ( ~/.B3/authorDb.xml ). This XML file will contain all data of the authors database. You can move this file providing you edit the configuration file accordingly. Since it s not in B3 s home directory, it will not be overwritten when installing a later version of B3 (different behavior from the Journal s database). This file will automatically be created if you upgrade from a previous version of B3, please check the console for messages. The authors database may be used in two ways: 1. By clicking on the Authors menu, and then the Show authors database item. This opens the database request dialog, where you can check, edit, add or remove entries.

11 Chapter 2: Extended functions 8 2. By editing an author field in any entry in your file. The author field as been updated, it is no longer a table. Double-clicking on an author brings a dialog box with several fields. From this dialog box, you can import authors from your database, or add any author both to your entry and the database. Please note that the additional fields ( address, and notes ) are only for the database, they will not be stored in your bibliography file. Figure 2.3: Importing authors and browsing the author database Adding entries to the author database It s possible to manually add entries by going to the Authors menu, and then clicking on the Show authors database item. The Add button in the toolbar will bring a dialog box similar to the one for setting authors in an entry. The other way is to automatically scan bibliography databases for authors. This is achieved by clicking on the corresponding item in the Authors menu. All authors in the current selected bibliography will be added to the database. Before adding an author to the base, B3 checks if any author with similar name are already present. If some are found, you ll be asked to either add the author to the database or to drop this one. An other possibility is to replace one of the existing entry by the new one. This is done by selecting the entry you want to replace in the list and then clicking on the Replace button. This functionality may be disabled by checking the corresponding item in the Authors menu. Be careful that this may lead to duplicated entries!

12 Chapter 2: Extended functions 9 Figure 2.4: Automatic scan for authors. 2.3 Searching a database (beta) Version 2.90 includes a new general search tool that comes as a replacement for the old limited "author search" tool. The search dialog is opened by going to the Search->Request menu item. A search request follows the general form: FIELD_TYPE matching operator REGEXP FIELD_TYPE corresponds to the field to search (for now: "Author", "Year", "Title" or "Keywords"). REGEXP is a regular expression following Java regex format /docs/api/java/util/regex/Pattern.html the java documentation for a detailed list of expressions allowed. matching operator is one of = (match) or!= (do not match) Several expression separated by a Boolean operator ( OR or & AND) are allowed, and priority may be specified by parenthesis. Here is an example: (AUTHOR=Kimura AUTHOR=Tamura) & YEAR=19\d\d Search for all entries with author "Kimura" or "Tamura" published in the XXth century. Finally, the request dialog provides some shortcuts for typing the request. 2.4 Using style-sheets B3 uses XSL style-sheet to process all entries in a database and write the result in several format for data exchange or pretty output. Each style-sheet may use only particular fields, however

13 Chapter 2: Extended functions 10 the user can switch off any field he doesn t want to be in the output using the Fields to export panel. For now, B3 can write a Bibtex file for use with LaTeX or several display style in HTML: Plain.b3s Full sorted author names, index with numbers; Abbreviate.b3s The same with initials for authors first names; Brieffing.b3s List all fields in each entry + keys; APA.b3s The American Psychological Association references format. Figure 2.5: Using XSL style-sheet to export a bibliography. On the left: selection the file and style-sheet. On the right: selecting the fields to export.

14 Chapter 3: Interacting with word processors 11 3 Interacting with word processors 3.1 Exporting to OpenOffice using a flat file This section describes how to export a database in a flat text file. Each entry will be on a separate line, with one field by column. Such file are often names CSV file (Coma Separated Value), because columns are separated by comas. Tabs or semi-columns are also frequently used. Such Text/CSV file can be imported in OpenOffice(OOo) as a bibliography database. It may be convenient to export to OOo without using a database manager (DBM). However, flat file are less powerful than DBMs. The next section will describe how to use a DBM to export bibliographic data to OOo Export to a Text/CSV file The Database Configuration Dialog window You first need to configure a few things. Go to the Options->Configure external database I/O to access the Database Configuration Dialog. From here, you can set up the way you want your bibliography to be exported. These settings are for database export, of which CSV export is a particular case. Figure 3.1: Configure the database I/O first. Fields Identifiers This table describes the correspondence between B3 entries fields (first column) and the column name in the resulting table (second column). The third column is for databases only, and specifies the type of the column. It will be ignored for text export. Allows the creation a an additional column. Such a column is required for OOo. It contains a unique description of the entry, which will appear in your OOo document. It is possible to use the key of the entry, but other more user-friendly options may be used: Authors + year the author list (last names), the year;

15 Chapter 3: Interacting with word processors 12 Short Authors + year the same, but if there are more than 3 authors, use first author, et al. notation; Number the index of the entry in the list. Not very convenient, consider using the numbering option in OpenOffice instead. Entry Types Describes the correspondence between B3 entry types and the type that will appear in the EntryType column of your table. Separators Allows you to configure the way Authors and Pages fields will look in your table. It is possible to save your settings to a XML file for latter re-use. As a consequence, it is also possible to use a pre-defined configuration file. Two files for OOo export are downloadable from the website: for exporting to OOo using keys as identifiers. for exporting to OOo using Authors description + Date as identifiers. For the rest of this section, we will consider that your are using this configuration file Exporting a database Got to the Export->Text/CSV menu, and choose the file where you want to export the data. The file must have the extension.txt or.csv to be recognized by OOo. An option dialog box appears, letting you set the characters to be used for delimiting columns and so on. Using tabulations to separate columns and double-quotes to delimit text is a reasonable choice Importing a Text/CSV file into OpenOffice. This tutorial was done with OpenOffice 1.5. OOo can import a database from a text file in CSV like format: a text file with columns Creating a new database First of all, you must create a new bibliography database in OpenOffice. Click on the Data Source menu item in the Tools menu. A dialog box then appears. Create a new source (Create new source button, in the upper left corner). Set the general option as in figure Figure 3.2: set the database type to text, set the database name and the directory where it can be found. Then switch to the text tab and set the format of you file:.csv extension for instance, and {tab} delimiter. The next panel allows you to select the table you want to use. One table should appear for each.csv file in the directory you selected in the general panel.

16 Chapter 3: Interacting with word processors 13 Figure 3.2: Choosing the database format Setting up the bibliography database For now, you have imported your B3 data as a database in OpenOffice. The next step is to tell OpenOffice that this database is the one where you can find references. To change the bibliography database, jump to the tools menu and select the bibliography database menu item (the one just above data source ). A new Window appears:

17 Chapter 3: Interacting with word processors 14 Figure 3.3: Open Office bibliography database manager. The database you see is the default database with references to OpenOffice books, or the last one you used (in this case, you need not reading more of this tutorial ;-). You must change to the new one you just created by clicking on the data source button (the last button in the toolbar). Your database must appear in the list: just select it. OpenOffice will now prompt you for the field assignation: answer yes to the question in the dialog box. Another window appears: Figure 3.4: This dialog box allows you to set up the correspondence between B3 fields and the table column names. You can also display it with the column assignation button. You may set something different, according to the fields you chose to export or else. If some fields are set to nothing, OpenOffice will prompt you again for column assignation. You

18 Chapter 3: Interacting with word processors 15 can answer no to the question, and it will work. Of course, you won t be able to use the corresponding field in the bibliography You re done :-) Here it ends! No you can insert reference as usual via theinsertion -> Index -> Bibliography entry menu. Bibliography management in OpenOffice is beyond the scope of this tutorial, so give a look at the OpenOffice help files for additional information. 3.2 Exporting to OpenOffice using MySQL [This tutorial is contributed by Christian Wietholt.] This tutorial is an attempt in helping people to export the reference database from B3 into OpenOffice.org with the help of a MySQL database. As there are many distributions and Operating systems available, on which you can run B3 and MySQL, I am not able to cover all the details. I assume that you installed MySQL successfully and you were able to log into the SQL manager with the commandline tool "mysql". Personally, I am using B3 and MySQL on Debian unstable, and I installed phpmyadmin including a required web-server to administer the MySQL database. As this requires additional setup, I shall use the command line tool "mysql" that is distributed with the MySQL database. First step in exporting your reference database to MySQL is to create a MySQL database. Log into your mysql database manager using : me@mydesktop:~\$ mysql --user me -p Enter password: ********** Here I assume that you enabled password protection in your database manager, and already created a user with the required privileges to create, and alter a databases. Next you need to create a database with the following command : mysql> create database myrefdb; Query OK, 1 row affected (0.00 sec) If you get the query OK response, everything should be fine, and you can exit your database manager by typing exit Now your database is created and waiting for you to fill it with data from B3. You can start B3 and load up bibliography database that you wish to export. First step you need to do is load the correct configuration file for you database I/O see Figure 3.5. This is essential for the bibliography database to work with OpenOffice.org. As the expected reference database format changes with different OpenOffice.org version, you need to keep this configuration updated. I am currently using OpenOffice

19 Chapter 3: Interacting with word processors 16 Figure 3.5: Configure the database I/O first. A recent I/O configuration file can be found at Load the downloaded XML file and close the dialog box: Figure 3.6: Load the database I/O configuration file. Now you can safely export your bibliography database to MySQL using the menu entry Export -> Export to SQL database. A dialog will pop up to specify the MySQL database access information such as Driver, Domain, Port, Database, Username and Password. As a driver you need to choose MySQL, and set the other parameters appropriately. An example for accessing a database installed on you local machine is given in Figure 3.7. Then push the "Connect" button.

20 Chapter 3: Interacting with word processors 17 Figure 3.7: Export reference database to mysql. B3 will ask you for a table name in which the database will be stored in. I typically choose "biblio". This is the standard table name in OpenOffice. I experienced some problems during my initial tests with a different table name, so I suggest to stick with "biblio". If you are adventurous enough, you can try using different names. If this table does not exist, B3 will create it for you. Just click "OK" and if you need to create the table, click "Yes", and your data is exported. Now it is time to start OpenOffice. First you need to open the database application. OOo will ask you what you want to do. You choose the option "Connect to existing database" as shown in Figure 3.8 and select of course "MySQL". Figure 3.8: Connect to the mysql database. In the next wizard screen select the database driver you wish to use to connect to your MySQL database. Here you should select the JDBC driver. In the following wizard screen you need to input the connection details. In our case the appropriate configuration parameters are shown in the next figure:

21 Chapter 3: Interacting with word processors 18 Figure 3.9: Connect to the mysql database parameter input. In the next screen you need to input your user name and don t forget to tick the password check-box if you have password protected access to your database manager. In the following screen, you need to make sure that the radio button "Yes, register the database for me" is selected. You can also choose to "Open the database for editing" to make sure that everything works as planned. See figure Ffigure 3.1 for details. Click on "Finish" and save your OpenOffice database to a location of your choice. You can click on "tables" in OpenOffice Base to make sure that everything is working properly. OpenOffice should ask you for your password. In my case, accessing the table itself seems a little sluggish from OpenOffice Base, but the "Bibliography Database" dialog should work fine. Ffigure 3.1: Connect to the mysql database finished. Now it is time to close OpenOffice Base and to open OpenOffice Writer. We choose the menu entry by going to Tools -> Bibliography Database. Click on the tool bar entry "Data Source" and select the just registered database. The name of the saved OpenOffice database will be available in the list menu. OpenOffice will ask you for your password, and your bibliography should appear in the spreadsheet field of the "Bibliography Database" dialog. As a next step I d suggest to make sure that the column arrangement is appropriately set. Just click on "Column Arrangement" in the tool bar of the "Bibliography Database" tool, and arrange the columns as shown in:

22 Chapter 3: Interacting with word processors 19 Figure 3.10: Make sure that the column Arrangement is set appropriately. Now you can close the "Bibliography Database" dialog, and use the menu entry Insert -> Indexes and Tables -> Bibliography Entry to insert your citations at the cursor position. In the pop-up dialog you should be able to choose the reference entry in the bibliography database from a pull down menu. OpenOffice will place it at the cursor position after you pushed"insert". If you want to create a bibliography table, select the menu entryinsert -> Indexes and Tables -> Indexes and Tables. Here choose the "Type" "Bibliography" and format the table to your desires, or journal requirements. Have fun with the great Open Source product. 3.3 Using L A TEX The insertion of citation in LaTeX document is facilitated by the LaTeX menu. This task may be achieved in 3 steps: 1. Select one or several entries in a database, by clicking on the corresponding lines. Maintaining SHIFT key down allows to make a continuous selection, while maintaining CTRL key down allows to make a multi-intervals selections. 2. Use the LaTeX menu (or the corresponding shortcut) to choose a L A TEX command. For now, the standard \cite command and commands from the Natbib package are supported: \cite \citet \citep \citealt \citealp \citeauthor \citeyear CTRL+i CTRL+t CTRL+p CTRL+ALT+t CTRL+ALT+p CTRL+a CTRL+y The corresponding command is copied to clipboard. 3. Paste the content of the clipboard to your favorite LATEX editor (usually using CTRL+c). 3.4 Processing OpenDocument texts [Please note that this functionality is still under testing and should be considered as experimental.] From version 3.00, B3 can parse files in OpenDocument format. This principle is similar to EndNotes(C) RTF files parsing.

23 Chapter 3: Interacting with word processors 20 Basically, B3 looks for citations and check the references in a database. Then, it inserts the corresponding formatted citation at the right place in the text, and compile the list of reference according to a given style-sheet. In order to do so, citations must follow a particular format, so that it be unambiguously recognized by B3 during the parsing process. The syntax used is rather similar to the Natbib LaTeX package: #B3citet #B3citep #B3citealt #B3citealp SHIFT+t SHIFT+p SHIFT+ALT+t SHIFT+ALT+p It is possible to directly write these commands into your OpenDocument editor, or use the shortcuts or OpenDocument processor menu to automatically insert citations commands. This will copy the command to the clipboard (See Section 3.3 [Using LaTeX], page 19) Known issues and how to avoid them... For the display document and display bibliography options to work, you need to register the corresponding mime-types in the options menu (See Section 1.3 [External Applications], page 4). When working with document revisions, avoid to break the B3 reference tags, as it will not be recognize. For the same reason, do not use formatting there (bold, italic, text decorations and so one). To be on the safe side, always use the keyboard shortcuts to insert your references.

24 Index 21 Index A Author database B B3 environment Bib View BibTex C CSV D Database Configuration Dialog Databases Directory scan E EndNotes Entries Entry Editor Exporting External F Fetching Pubmed Fields File type... 1 H HTML , 9 I Importing J Journal abbreviation Journal database K Key L LaTeX M Mime-type MySQL O OpenDocument OpenOffice... 11, 15 OpenOffice.org P PDF Pubmed R Reference Manager Regular expressions RIS S Searching a database Stylesheets X XSLT