# &app; Manual V&manrevision;

&app; is a tool for managing bibliographic databases. It can be used for searching, editing, reformatting, etc.

2003-2010
Zoltán Kóta
1999-2010
Frédéric Gobry

&legal;

Zoltán
Kóta
Frédéric
Gobry
&app; Documentation
1999

Frédéric Gobry

&app; Manual V2.1
January 2004

Zoltán Kóta, Frédéric Gobry

&app; Manual V2.2
March 2004

Zoltán Kóta, Frédéric Gobry

&app; Manual V2.3
June 2004

Zoltán Kóta, Frédéric Gobry

&app; Manual V2.4
November 2004

Zoltán Kóta, Frédéric Gobry

&app; Manual V2.5
February 2005

Zoltán Kóta, Frédéric Gobry

&app; Manual V2.6
October 2008

Zoltán Kóta, Frédéric Gobry

&app; Manual V&manrevision;
&date;

Zoltán Kóta, Frédéric Gobry

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, follow the directions in the Pybliographer help page.

## Preface

### Typographical conventions

In this book, we'll mark some words with special typography:

- Applications

- `Commands` you type at the command line

- `Filenames`

- Replaceable text

- Labels for buttons and other portions of the graphical interface

- Menu selections look like this: Menu Submenu Menu Item

- Buttons you can click

- `Anything you type in`

We'll provide assorted bits of additional information in tips and notes as well.

#### Tip

Tips and bits of extra information will look like this.

#### Note

Notes will look like this.

We'll have warnings, in cases where you should be careful:

#### Example Warning

This is what a warning looks like. If there's a chance you'll run into trouble, we'll warn you beforehand.

### Additional Help Sources

For additional information, please, visit the &app; website at http://pybliographer.org. There is a mailing list also, where you can get answers for your questions, you can report bugs, etc.

### What's New in &app; &appversion;

You can find a list of bugs fixed and features added in the `News` and `ChangeLog` files supplied with the package. See the source tarball of pybliographer, or the default doc directory of your distribution (e.g. /usr/share/doc/pybliographer).

## Getting started with &app;

### What is Pybliographer?

Pybliographer is a tool for working with bibliographic databases. It provides a general framework that can be used to manipulate these databases with a simple graphical interface, but that can also be easily extended by the mean of a scripting language, to fit a wide range of needs.

### How to start Pybliographer?

You can start &app; in the following ways:

Graphical mode

  To start &app; in graphical mode from a command line, type the following command, then press Return:

  `pybliographic`

  For information on the graphical interface, see .

Command line mode

  You can start &app; also in command line mode by typing the following command followed by pressing Return:

  `pybliographer`

  For information on the command line interface, see .

From the gnome menu

  If the desktop file of the package is correctly installed in your sytem, you can find a launcher under the gnome menu to start the graphical interface of &app;.

It is possible to set the PYBLIOGRAPHER_DATABASE environment variable to an admissible bibliography file in order to open it always on startup, if no files are specified on the command line. Example:

        bash$ export PYBLIOGRAPHER_DATABASE=my/database.bib
        bash$ pybliographic

It is equivalent to

        bash$ pybliographic my/database.bib

## The graphical interface

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 Lyx and Kile , direct queries on Medline, and saving selected references in different formats are also possible.

### Creating a new database

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.

To add a new entry, you can use the Edit Add menu, directly the Add toolbar button or click with the right button in the list window and select Add.

You will find more information on the main window's usage in .

### Opening a database

To open an existing database, click on the Open toolbar button or go in the File menu, and select File Open .

#### Opening a database

Shows &app; open file window.

A file selection dialog will pop up (see ) 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 - According to file suffix -.

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 File Open Location menu item.

### Navigating in the entries

Once you have opened a database, or started to create a new one, the main window (see ) displays a list of all the entries on the top part of it. The fields diplayed here can be configured under the Settings Preferences menu item.

It is possible to display two types of combined fields: -author/editor and -author/title-.

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.

If an entry contains an URL 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 about how to add an URL field to an entry. Alternatively, you can open the URL with the help of the View Resource submenu item or the Resource 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 ).

You can set the viewable fields and the applications used to view the resources in the 'Resource' tab under the Settings Preferences menu.

Clicking on an entry while pressing the Shift key extends the selection to the clicked entry. A click while pressing the Control 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.

#### The main window

Shows &app; main window.

Clicking the right button of the mouse in the list opens a contextual menu. With this menu you can:

- add a new entry

- edit the currently selected items

- view the resource associated with the selected item

- delete the currently selected items

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.

By clicking on the column titles of the list, you'll sort the entries according to the corresponding field.

### Searching

&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 Edit Search in the menu.

The dialog that appears (see ) displays a search form at the top.

#### The Search dialog

Shows &app; search dialog.

#### Simple searches

With a simple search, you can select the field that will be searched and you can specify a regular expression to be matched. - any field - means that all the existing fields will be searched. This is usually more time-consuming.

#### Expert searches

An expert search is an expression that looks like:

    has('author','name') | -has('title','test')

Such an expression means: select the entries where the field author matches name, or (symbol |) where the field title does not match test. The boolean and is noted &.

There are other commands available for this type of search:

- `has_key(`keyname`)` searches on a key name.

- `has_type(`typename`)` searches for entries of a given type name.

- `any_has(`value`)` searches for the given value in all the fields of an entry.

- `before(`field`, `year`, `month`, `day`)` searches for entries where the specified date field is older than the specified date.

- `after(`field`, `year`, `month`, `day`)`searches for entries where the specified date field is younger than the specified date.

#### Hierarchical searches

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.

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.

Right-clicking in this tree pops up a contextual menu that allows you to remove unuseful searches.

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

### Sorting

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 Edit Sort ). This menu, displayed in , 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:

- Nothing means the field is not in use.

- A triangle-like symbol means sort in ascending order.

- An upside down triangle-like symbol means sort in descending order.

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 Set as default button.

#### The Sort dialog

Shows &app; sort dialog.

### Editing

#### Basic editing

##### The Edition window

Shows &app; edition window.

The edition window is represented in . 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.

If you edit such an entry, you can loose the additional information it contained. To avoid this, consider using native editing (see ).

To edit the entries, simply type the corresponding text, without any consideration for the database format being used. For example, with BibTeX, don't add any { 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 last name, lineage, first name order. If an author or editor field has too many names, you can end the list of names with others; the standard bibtex styles convert this to et al.

In addition to the standard fields, you can create your own fields using the Create Field button.

You can customize the mandatory and optional fields for the different type of entries. For example, associating the URL 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 . More information about the association of fields can be found in .

##### The Edition window - Optional fields

Shows the optional fields containing URL.

The following keyboard shortcuts are available during edition (in addition to the standard ones provided by Gtk):

- Ctrl TAB to jump to the next field

- Shift TAB to jump to the previous field

- Ctrl Enter to accept the modifications

- Esc to cancel the edition

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

#### Native editing

For databases like BibTeX that provide a specific syntax (called native syntax), it is possible to directly edit the entry in this format. Just click the button called Native Editing at the bottom of the window and type the entry in its native form.

It is also possible to type native commands in the normal editing window. For example, if you want to use special LaTeX commands like `\textbf` in a title, you can type them directly in the Title field by preceding the text with a @ 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;.

### Using &pyc; with LyX

It is possible to directly use &pyb; in order to insert bibliographic references into LyX. It is done through the LyX server. The path of the LyX server pipe can be defined in the Tools Preferences dialog of LyX. The same path should be given in &pyb;'s settings (the default value is ~/.lyx/lyxpipe).

Then, in &pyc;, it is possible to select one or several entries and insert their references into a running LyX simply by clicking the Cite toolbar button, or selecting the Cite Cite... menu item.

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 `bibtex` as described in the LyX documentation.

&pyc; can interact with Kile (>= 1.6) practically in the same way, since Kile can also read lyx pipe.

### Saving selected entries in different formats

Selected entries can be saved in different formats using the Cite Format... menu item ().

#### Formatting entries

Shows &app; formatting entries dialog.

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 .

### Searching in PubMed

With &pyc;, it is possible to perform a Medline search. To use this option, click on the File Medline query... menu item. The upcoming window is represented in .

#### Medline query

Shows &app; medline search dialog.

The keyword, you are looking for, should be written into the Search PubMed for field. As it can be seen in , 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.

### Configuration

Under the Settings menu, you can find some options to customize &pyb;.

#### Entry types and field names configuration

##### Configuration of fields and entry types

Shows &app; fields and entry types configuration dialog.

Selecting the Settings Fields 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 , as an example, the association of the Article entry type can be seen.

#### Preferences

Clicking on the Settings Preferences 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.

## The command line interface

To start &app; in command line mode, type the following command:

      bash$ pybliographer
      This is pybliographer, version 1.2.12
      Copyright (C) 1998-2004 Frederic GOBRY
      This is free software with ABSOLUTELY NO WARRANTY.
      For details, type `warranty'.
      Useful commands:
             help     to get some help
             quit     to quit

      >>

To get some help about how to use &app; in this mode, type `help` at the &pyb; prompt.

The next example shows how to open a database and make a simple search in it. See the following commands and the output:

      >> db = bibopen ("database.bib")
      >> iterator = search (db, 'author = Mantsch')
      >> ls (iterator)
      The Use and Misuse of FTIR Spectro  Jackson, Michael; Mantsc  [JM95            ]
      Phospholipid phase transitions in   Mantsch, H. H.; McElhane  [MM01            ]
      >>

To see the complete entries listed by the command `ls (iterator)`:

      >> more (iterator)
      Article [JM95]
      ----------------------------------------------------------------------
        Author         Jackson, Michael; Mantsch, Henry H.
        Title          The Use and Misuse of FTIR Spectroscopy in the
                       Determination of Protein Structure
        Journal        Critical Reviews in Biochemistry and Molecular Biology
        Date           1995
        Volume         30
        Number         2
        Pages          95-120
        keywords       infrared spectroscopy; proteins; secondary structure;
                       quantitation
        comments       Review

      Article [MM01]
      ----------------------------------------------------------------------
        Author         Mantsch, H. H.; McElhaney, R. N.
        Title          Phospholipid phase transitions in model and biological
                       membranes as studied by infrared spectroscopy
        Journal        Chemistry and Physics of Lipids
        Date           1991
        Volume         57
      --More--

## The scripting language

&pyb; is in fact a simple set of classes and functions written in python, and that provides with a simple and homogenous access to bibliographic databases. Therefore, it is possible to write python scripts that make use of these specialized functions. The graphical interface, &pyc;, is itself a simple script on top of &pyb;.

To execute a script written for &pyb;, simply run

        bash$ pybliographer [--quiet] myscript.py

You can alternatively start your script by

          #!/path/to/pybliographer

          ...rest of your script...

and make it executable.

### Existing scripts

Some scripts are provided with pybliographer, both as example and as useful tools. They are quite short and should be readable with basical knowledge of python.

#### pybcheck

This tool takes a list of files or directory, and check if they are valid (syntax, no entries with the same key,...)

It is possible to use its output directly in an emacs compile buffer, in order to jump directly to the encountered errors. To do so, type M-x compile, then the command `pybcheck `yourfiles``, and use the middle button of the mouse to jump into the faulty file.

#### pybcompact

This tool extracts the citations made in a LaTeX document and generates a BibTeX file containing them.

Usually, one stores its bibliographies in one or several large BibTeX files, and lets `bibtex` extract the entries used in a LaTeX document. But it is sometime convenient to create a self-contained package (for example to share it in native form with somebody else, or to store it), with a minimalistic BibTeX file holding exactly the entries used in LaTeX. This tool does exactly that: it reads a LaTeX `.aux` file, and extract from the specified BibTeX databases the corresponding entries.

#### pybconvert

This tool converts from one bibliographic format to another.

The general syntax is pretty simple. To convert from Refer to BibTeX for example, just run:

    	bash$ pybconvert refer..bibtex toto.refer toto.bib

#### pybformat

This script generates a bibliography according to a bibliographic style, and outputs it in a specific format (like HTML, LaTeX,...) as it should appear in a document.

The general form of the command is

    	bash$ pybformat [options] database...

This command without options will use the style called alpha to create a bibliography in Text format. Several options are available to create these documents:

- `--style=... or -s ...`: specify a bibliography style. This can be a full path to an existing XML file, or a name which will be searched in the standard places. Default is Alpha.

- `--format=... or -f ...`: specify an output format (HTML, LaTeX, Raw, Text, Textau, Textnum). Default is Text. (Textau and Textnum are just slightly modified versions of Text. See for more details.)

- `--output=... or -o ...`: specify an output filename. STDOUT is the default.

- `--header=... or -H ...`: defines a file that will be prepended to the output file.

- `--footer=... or -F ...`: defines a file that will be appended to the output file.

- `--list=output or -l output`: lists the available output formats

#### pybtex

This tool searches for the citations in a LaTeX document and generates a LaTeX bibliography file.

This tool reads a LaTeX `.aux` file, and extracting the corresponding entries from the specified BibTeX databases creates a LaTeX bbl file.

The form of the command is

    	bash$ pybtex latexfile [bibtexfiles...]

#### pybtext

This tool processes a text file containing citations and appends a bibliography according to a given style.

The script searches for citations like [key] or [key1,key2...] in a text file (for example: ...This is a text fragment with citations [AKM95,MPJ+03] inserted from pybliographer...). First, according to the keys found in the text file, it generates a reference list. Using an appropriate style (see below), it replaces the database keys in the text body with the new keys generated by the style module, and finally it appends the reference list to the text resulting a new file.

The keys of selected entries can be copied easily from pybliographer into a text editor or terminal by copy and paste or drag and drop.

The general form of the command is

    	bash$ pybtext [-o outputfile] [-s style] textfile bibfiles...

This command without the options will use the style called Abbrev and `textfile.pyb` as outputfile for processing. `textfile` is the name of the file to be processed and `bibfiles` is one or more bibliographic database file.

There are three different styles which are designed for pybtext. Using abbrvbib results in keys as they are defined in the database. With the style abbrvau, author-year type keys (e.g. Jackson et al., 2004) can be generated. Using abbrvnum, the script produces a simple numbered list. For abbrvau and abbrvnum, the formats Textau and Textnum are used, respectively. They are just simple modifications of the Text format, optimized for these styles. Using other styles (Alpha, Abbrev or apa4e), the text body is not processed, but the reference list is appended in the form that corresponds to the used style.

### Writing your own scripts

To start writing your own script, you can read what follows, and then have a look at the existing scripts. Trying to adapt them to fit your personal needs can be a good way of testing what you read.

#### Some concepts

This section describes some basic classes and ideas that are useful to understand how &pyb; works.

In the following, all the modules that will be refered to belong to the Pyblio domain. So, to access the members of the Open module, you'll have to write at the beginning of your script something like

    from Pyblio import Open

The Base module contains some of the most basical classes used in the application:

- Base.Entry represents a specific bibliographic entry, with all its fields. It behaves like a hash table which returns the content of a field given its name

- Base.DataBase is the class from which every database type inherits. It behaves like a hash table that returns a Base.Entry given a Base.Key

Key.Key is the object that uniquely identifies an entry. This object must be unique over the whole application, and is composed of a database part and an entry part.

An Iterator is an object that provides a way to access a sequence of items in order. These iterators are used extensively in &pyb;, because they hide the underlying access mechanism, and provide the same access on any database. They are also perfectly suited for implementing transparent filtering and sorting of entries: the Selection.Selection class for example takes an iterator (on a database for example) and return a new one which will only iterate on a subset of the entries, according to a search criterion.

## Customization

The configuration system is heavily based on python's module system. The configuration files are standard &pyb; scripts (that is, python code making use of &pyb; extra classes and functions), whose single special feature is to be automatically parsed at startup or when needed.

### Files involved

The first file to be parsed is `${prefix}/share/pybliographer/pybrc.py`. It serves as a bootstrap for the general configuration mechanism, and defines:

- the available input and output formats

- where to find the configuration directories.

A configuration directory holds a list of files which are parsed when needed. For example, if a method requires some configuration data for the bibtex module, it will import the corresponding file in this directory.

This mechanism allows more flexibility to add new formats: the new format can be installed with a default configuration without messing with the global configuration file. In addition, the program imports only what is needed, decreasing its startup time.

Finally, if the user provides a file called `.pybrc.py` in its home directory, this file is then parsed. Of course it can also define a private configuration directory, and override what has been defined before.

### The `Config` module

All the data that can be configured should be handled by the so-called `Config` module. It provides a standard interface to set/get and document configuration items.

## Creating new Styles

It is possible to describe your own bibliography style, by writing a simple XML file. The XML file should have the following header:

          <?xml version="1.0"?>

The whole description should fit in a <bibstyle> pair of tags, whose content is shortly described in this section. It is suggested that the interested users look at the corresponding DTD, which describes the allowed syntax in details. This DTD can be found in the same directory as the default style files.

### Global formatting

The XML style file describes how the different data fields are organized in order to create a bibliographic style. For example, it can specify that an article starts with the article title in bold, followed by the authors names, etc.

In its current incarnation, the XML format can however not describe lower-level informations, like how an author's name should be output. This is done by pointing to a set of python functions, grouped in a module. Let's consider the following example:

      <module name="generic">
        <define field="author">full_authors</define>
        <define field="editor">first_last_full_authors</define>
        <define field="date">european_date</define>
        <define method="keys">string_keys</define>
      </module>

In this example, we require that the author fields should be formatted by the `full_authors()` function, located in the `generic` module.

Such a module has to be declared in the `pybrc.py` file, by a line like:

    Autoload.preregister ('style','Generic','Pyblio.Style.Generic')

The precise definition of the formatting functions is better explained by looking at the code of `Generic.py` for example.

### Bibliography definition

Once the basic formatting definitions have been specified, it is possible to describe the aspect of the actual bibliographies with following tags:

- <style name="`stylename`">

  This tag specifies the current display style, among bold, italic, slanted, emph.

- <inentry name="`entryname`">

  This tag encloses a block that is only to appear in entries of type `entryname`.

- <notinentry name="`entryname`">

  This tag encloses a block that is only to appear in entries that are not of type `entryname`.

- <infield name="`fieldname`">

  This tag encloses a block that only appears when the specified `fieldname` field exists in the current entry.

- <notinfield name="`fieldname`">

  This tag encloses a block that only appears when the specified `fieldname` field does not exist in the current entry.

- <content name="`fieldname`"/>

  This empty tag is replaced by the content of the current field (when placed in a <infield> block) or the content of the field specified as attribute.

- <separator>

  This tag's content evaluates to nothing when no text has been issued so far. It is a convenient way to add a delimiter after a series of fields without being worried of the special case when the fields are not defined.

The existing style files are a good source of examples.

### Future of the format

In the future, this rudimentary format will most likely be replaced with an XSL-based mechanism, which should encompass both the XML definition and the python modules, thus providing standalone style files, parsable by any XSL parser.

## Authors

&app; was originally written by Frédéric Gobry. Many thanks to all contributors for their fruitful work.

Contributions:

Yuri Bongiorno

  documentation, translations

Hervé Dréau

  internationalization, UI goodies

Frédéric Gobry

  project maintainer, core application, Gnome interface, documentation

Zoltán Kóta

  documentation, packaging, ui code

Travis Oliphant

  original Ovid parser

Darrell Rudmann

  APA 4th edition style

Peter Schulte-Stracke

  application design, requirement docs, import and ui code

John Vu

  Medline database parser

Thanks to everyone who helped out with the bug tracking process.

Many thanks also to the Documentation Translators and the Gnome Translation Teams.

This manual was written with the help of the GNOME Documentation Project.

If you contributed to this project but do not see your name here, please contact the project maintainer and he'll list you.

For more information please visit the &app; website.