# Importing and Exporting Data

&appname; is able to import and export a wide variety of data files, as well as search various Internet sites for information.

## Importing from the Internet

&appname; is able to search various Internet sites using the &fetch-dialog;. Entries may be directly imported and added to your current collection. The various providers are configured via the Data Sources Options.

Searches may use five different criteria: Title, Person, ISBN, UPC/EAN, or Keyword. Not all criteria are available for certain data sources.

Once a search is initiated, the Search button becomes Stop which will end a search. As results are found, they are added to the list directly under the search box, where selecting an item will show the result without adding it to the collection. Clicking the Add Entry button will add all the selected items to your collection. If the data source has more results than were initially requested, the Get More Results button becomes active. Clicking Clear will remove all the current results and reset the search.

The &appname; &fetch-dialog;
The &appname; &fetch-dialog;

Only entries that match the current collection type will be found. The Description column provides additional information about the entry, in order to differentiate between videos in different formats, or books in different bindings, for example. Once an entry is successfully added to the collection, a checkmark is added to the first column in the list.

Multiple entries can be added at once by using the standard &kde; method for multiple selection, which usually involves holding the &Shift; or &Ctrl; key when clicking on an item.

To facilitate the use of barcode scanners, searches can include multiple ISBN values. Selecting the Multiple ISBN search check box will disable the search box and enable the Edit ISBN list... button, which will open a multi-line text entry box. Each ISBN should be entered on a line by itself. After closing the box, each ISBN will be validated for correct formatting. The ISBN validation is able to convert 13-digit EAN values, as well as full UPC codes, to the proper formatting. The ISBN list may also be read from a text file.

## Importing Data

&appname; offers three different actions when importing data. Replace current collection will close the current collection, and create a new one with the data from the imported file. Append to current collection tells &appname; to add all the entries in the imported collection to the current one, and to add any fields which don't currently exist. The Merge collection action is the same as appending, except that each imported entry is compared to the current ones, and any identical entries are skipped. Future plans include an improved heuristic for identifying matching entries, but currently, except for music collections, they must be identical for every field. Music collections compare the artist and album only, and the tracks are merged for matching entries. The audio file importer is able to correctly build track lists by merging entries.

### Importing &appname; Data

Other &appname; data files may be imported. Replacing the current collection by importing a &appname; file is the same thing as just opening the file itself. The value of importing &appname; data is primarily for appending or merging two collections together.

### Importing CSV Data

Comma-separated values (CSV) are a common way of importing and exporting tabular data. Each field value is separated by a comma, with one entry per line. The field titles may be included in the first line. The CSV importer is not limited to using a comma as the separator. Any character or string may be used.

The CSV Import Dialog
The CSV Import Dialog

First, select the type of collection that you are importing. If you are appending or merging to your open collection, the type is limited to your current collection type. If the first line of the CSV file contains the field titles, click the check box and the importer will automatically compare the titles against the fields in the current collection. If a field title matches, the header for that column changes to show that the column has been assigned to that field. If the file uses a delimiter other than a comma, be sure to change that option accordingly.

In order for &appname; to properly import the file, it must know which field corresponds to each column. If the column only has a number in the header, the data in that column will not be imported. You should assign fields to each column by selecting a column, either by clicking in it or changing the column number itself, then selecting the field to assign from the drop down box and clicking the Assign Field button. If you need to add a new field to the collection, the last item in the dropdown list opens the &fields-dialog;.

Only the first five lines of the imported CSV file are shown in the dialog.

### Importing Audio CD Data

&appname; is able to use the freedb.org service to lookup information about a CD, including the track list. Depending on your distribution, settings for access to the service may be set in the &kde; Control Center. The CD artist, title, genre, year, and track listing are all added.

In addition, if the disc contains CD-Text, that information is read and added to the imported entry.

### Importing Audio File Metadata

&appname; is able to scan a folder and read the tags for common audio file formats, such as `mp3` and `ogg`. The songs are entered in a music collection, where each entry is an album. If the song files contain the track number, the song name is inserted in the correct spot in the track list. The artist and genre information is also added to the entry. If the song tags contain comments, they are appended to the comments field in the entry, preceded by the file name.

In addition, if a folder contains a `.directory` file and the folder name matches an album title, the `Icon` entry in the desktop file is used as the cover image for the album.

The audio file metadata importer can recursively scan a folder to find all audio files in any subfolder, though symbolic links are not followed. &appname; uses the TagLib library for reading the audio file metadata, and so can import data from any file type that TagLib understands.

### Importing Alexandria Libraries

Alexandria is an alternate book collection manager for the GNOME desktop environment. The importer offers a choice of importing any of the libraries found in `$`HOME`/.alexandria/`.

### Importing Ant Movie Catalog Data

Ant Movie Catalog is an alternate movie collection manager.

### Importing Bibtex Data

Bibtex is a bibliography format used with the LaTeX document preparation system. Various type of bibliographic references may be included in the file. &appname; imports bibtex files as a Bibliographic collection.

If the bibtex importer encounters fields in the file which are not in the default bibliography collection, they are added as Simple Text fields, with two exceptions. If the field value contains more than 100 characters, it becomes a Paragraph field. If the field value appears to contain a &URL; or a file reference, then a URL field is created. &appname; uses an internal copy of the btparse library for parsing the bibtex files.

### Importing Bibtexml Data

Bibtexml is an &xml; representation of bibtex data, and the data from the imported bibtexml file is treated in the same way as bibtex data would be.

### Importing Delicious Library Data

Delicious Library is an alternate collection manager for the Mac OS X desktop. &appname; imports a subset of the data used by Delicious Library.

### Importing GCstar Data

GCstar is an alternate collection manager. Importing books, movies, music, coins, games, board games and wine collections is currently supported.

&appname; can also import GCfilms data files. GCfilms is the predecessor of GCstar and was an alternate movie collection manager. Normally, GCfilms data files are found in `$`HOME`/.local/share/gcfilms/`.

### Importing Griffith Data

Griffith is an alternate video collection manager. &appname; is able to import most data from a Griffith database.

### Importing MODS Data

MODS is a format for representing various types of media collections. Currently, only books are imported by &appname;, as a Bibliographic collection.

### Importing PDF Data

If &appname; was compiled with exempi or poppler support, metadata from PDF files can be imported. Metadata may include title, author, and date information, as well as bibliographic identifiers which are then used to update other information.

### Importing RIS Data

The RIS format is a bibliographic file format used by Reference Manager and others. &appname; imports RIS files as a Bibliographic collection.

### Importing Referencer Data

Referencer is a document organizer and bibliography manager for the GNOME desktop. &appname; will import most of the data found in a Referencer database.

### Importing File Listings

The best way to create a File Catalog is to import the contents of a folder. The folder may be searched recursively, to add all files found within. This importer is most useful for backup listings and media cataloging, such as CD or DVD listings. In addition, image previews of the file contents may be generated, although it can take some time to read a large number of files. The file previews are same as those shown in the &kde; file manager.

### Importing &xml; Data via XSLT

Any &xml; file may be imported into &appname; provided an XSL stylesheet is available to convert the file to &appname; format. &appname; automatically loads the stylesheet and performs the XSLT processing needed to load the file.

## Drag and Drop

Dragging data files to the main &appname; window and dropping them will import the files, just as if the import command was made from the menus. Drag and drop works for the following file formats: Tellico, Bibtex, RIS, and PDF. Importing multiple files at once is also supported.

So, for example, if you want to catalog several PDF files, select them in the file manager and drag them to the &appname; window. &appname; will import as much metadata from the files as it can, and then fetch additional information from various configured Internet sources.

## Exporting Data

When exporting the data in the collection, the entry values may be exported as entered, or with the automatic formatting provided by &appname;. Additionally, the export may be limited to the currently selected entries of the collection as well, where the statusbar shows the number of selected entries.

Exported text files, such as Bibtex or CSV, may use the Unicode (UTF-8) character encoding, or the current locale of the operating system.

General Export Options
General Export Options

### Exporting &xml;

The file format for &appname; data is a zipped &xml; file. Exporting to &xml; merely creates the &xml; file without zipping it. Images may be included in the &xml; file as base64-encoded data in an image element, but doing so can create very large text files.

### Exporting Zip

The standard file format for &appname; is a zipped file, contained the &xml; collection file, and optionally, all the images referenced in the collection. If the images are being stored in the application folder instead, exporting to a Zip file will create a self-contained data file, which includes all the images in the collection.

### Exporting HTML

The HTML export uses the `tellico2html.xsl` stylesheet. Images are exported to a folder with the same name as the exported HTML file with `_files` appended.

The default format is similar to the printed output, and allows various options for modifying the HTML. Field headers may be printed at the top of each column, but unfortunately, &kde; does not yet allow the table headers to be be repeated on each page. The entries may be grouped as in the &group-view;, as well.

Additionally, individual files may be created for each entry in the collection, with links created in the top-level HTML file. The entry files will be created in the same folder as the images. The entry HTML files will use the current stylesheet template, as shown in the &entry-view;.

HTML Export Options
HTML Export Options

### Exporting CSV

Comma-separated values (CSV) are a common way of importing and exporting tabular data. Each field value is separated by a comma, with one entry per line. The field titles may be included as headers in the first line. Any character or string other than a comma may also be used to delimit the fields.

CSV Export Options
CSV Export Options

### Exporting Pilot-DB

Pilot-DB is a database format for Palm OS. Various desktop applications can read and write Pilot-DB files. Exported `.pdb` files can be transferred to a PDA, and used directly. At the moment, &appname; is not able to import Pilot-DB files.

Pilot-DB Export Options
Pilot-DB Export Options

### Exporting Alexandria

Alexandria is a book collection manager for the GNOME desktop environment. &appname; is able to export a limited subset of book collection fields to the default Alexandria data location.

### Exporting ONIX

ONIX is an XML format for representing and communicating book industry product information, primarily for book vendors. &appname; can export book collections using a small subset of ONIX.

### Exporting Bibtex

When exporting to Bibtex, the field values may be escaped with braces or quotation marks. If any string macros are used in the collection, they may optionally be exported as macros or expanded. For &URL; fields, &appname; may enclose the field values with the `\url{...}` tag. Finally, entries with no citation key may be skipped rather than have &appname; auto-generate the key.

Bibtex Export Options
Bibtex Export Options

### Exporting Bibtexml

Bibtexml is a format for expressing bibtex data via XML.

### Exporting GCfilms

GCfilms is another movie collection manager. &appname; is able to export a limited subset of video collection fields to a GCfilms data file.

### Exporting &xml; via &xslt;

Finally, &appname; is able to process its internal &xml; representation of the collection data through an external XSL stylesheet before exporting. This type of export may be useful for generating text reports or other file types.

## Working With Citations

When working with a bibliography, citations for the currently selected entries may be generated and used in various other applications. A citation in bibtex format can be copied to the clipboard, and then pasted in a latex file. Bibtex citations can also be pushed to an external application such as LyX or Kile using the so-called lyxpipe. Finally, limited support is available for interacting with OpenOffice.org Writer.

### Working with OpenOffice.org

&appname; has some limited support for sending citations to OpenOffice.org Writer and updating the bibliography of a document. A special plugin is used, and if it is available, the menu command for citing an entry in Writer is enabled. If it is not enabled, then &appname; is either unable to find the plugin or is unable to load it. More information about building &appname; with OpenOffice.org support is in a later section.

OpenOffice.org must be configured to allow interaction from other applications. There are two methods: named pipes and TCP/IP. Named pipes are the easier and faster. To run Writer and connect with a named pipe, the following command may be used:

    % oowriter "-accept=pipe,name=OOo_pipe;urp;StarOffice.ServiceManager"

The pipe or TCP/IP port can be configured to be open every time OpenOffice.org is used. Check the OpenOffice.org documentation for more details.

To insert a citation, select the entry, then use the Cite Entry in OpenOffice.org. Writer must be running already. &appname; will attempt to connect, and if it fails, it will ask for more information about the connection.

OpenOffice.org Connection Dialog
OpenOffice.org Connection Dialog

Select the type of connection, either a pipe or a TCP/IP port. Enter the pipe name, or the hostname and port. &appname; will remember your connection settings for later use.