<chapter id="importing-exporting">
<title>Importing and Exporting Data</title>

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

<sect1 id="internet-search">
<title>Importing from the Internet</title>
<para>
&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 <link linkend="data-sources-options">Data Sources Options</link>.
</para>

<para>
Searches may use four different criteria: <guilabel>Title</guilabel>, <guilabel>Person</guilabel>, <guilabel>ISBN</guilabel>, or <guilabel>Keyword</guilabel>. Not all criteria are available for certain data sources. Once a search is initiated, the <guibutton>Search</guibutton> button becomes <guibutton>Stop</guibutton> 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 <guibutton>Add Entry</guibutton> button will add all the selected items to your collection. Clicking <guibutton>Clear</guibutton> will remove all the current results and reset the search.
</para>

<screenshot>
<screeninfo>The &appname; &fetch-dialog;</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="fetch-dialog.png"/></imageobject>
<textobject><phrase>The &appname; &fetch-dialog;</phrase></textobject>
<caption><para>The &appname; &fetch-dialog;</para></caption>
</mediaobject>
</screenshot>

<para>
Only entries that match the current collection type will be found. The <guilabel>Description</guilabel> column provides additional information about the entry, in order to differentiate between videos on different formats, or books in different bindings. Once an entry is successfully added to the collection, an icon is added to the first column in the list.
</para>

<para>
To facilitate the use of barcode scanners, searches can include multiple ISBN values. Selecting the <guilabel>Multiple ISBN search</guilabel> checkbox will disable the search box and enable the <guibutton>Edit ISBN list...</guibutton> 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 <acronym>UPC</acronym> codes, to the proper formatting. The ISBN list may also be read from a text file.
</para>

</sect1>

<sect1 id="importing">
<title>Importing Data</title>

<para>
&appname; offers three different actions when importing data. <guilabel>Replace collection</guilabel> indicates the current collection should be closed, and a new one created with the data from the imported file. <guilabel>Append collection</guilabel> 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 <guilabel>Merge collection</guilabel> 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 <link linkend="importing-audio-files">audio file importer</link> is able to correctly build track lists by merging entries.
</para>

<sect2 id="importing-tellico">
<title>Importing &appname; Data</title>

<para>
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.
</para>
</sect2>

<sect2 id="importing-csv">
<title>Importing CSV Data</title>

<para>
Comma-separated values (<acronym>CSV</acronym>) 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.
</para>

<screenshot>
<screeninfo>The CSV Import Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="csv-dialog.png"/></imageobject>
<textobject><phrase>The CSV Import Dialog</phrase></textobject>
<caption><para>The CSV Import Dialog</para></caption>
</mediaobject>
</screenshot>

<para>
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 checkbox 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.
</para>

<para>
In order for &appname; to properly import the file, it must know which field corresponds to each column. <emphasis>If the column only has a number in the header, the data in that column will not be imported.</emphasis> 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 dropdown list and clicking the <guibutton>Assign Field</guibutton> button. If you need to add a new field to the collection, the last item in the dropdown list opens the  <link linkend="fields-dialog">&fields-dialog;</link>.
</para>

<para>
Only the first five lines of the imported CSV file are shown in the dialog.
</para>

</sect2>

<sect2 id="importing-audio">
<title>Importing Audio CD Data</title>

<para>
&appname; is able to use the <ulink url="http://freedb.org">freedb.org</ulink> service to lookup
information about a <acronym>CD</acronym>, including the track list.
</para>
</sect2>

<sect2 id="importing-audio-files">
<title>Importing Audio File Metadata</title>

<para>
&appname; is able to scan a directory and read the tags for common audio file formats, such as <literal role="extension">mp3</literal> and <literal role="extension">ogg</literal>. 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.
</para>

<para>
In addition, if a directory contains a <filename>.directory</filename> file and the directory name matches an album title, the <literal>Icon</literal> entry in the desktop file is used as the cover image for the album.
</para>

<para>
The audio file metadata importer can recursively scan a directory to find all audio files in any subdirectory, though symbolic links are not followed.
</para>

</sect2>

<sect2 id="importing-alexandria">
<title>Importing Alexandria Libraries</title>

<para>
<application><ulink url="http://alexandria.rubyforge.org">Alexandria</ulink></application> is a book collection manager for the <ulink url="http://www.gnome.org">Gnome</ulink> desktop environment. The importer offers a choice of importing any of the libraries found in <filename class="directory">$<envar>HOME</envar>/.alexandria/</filename>.
</para>

</sect2>

<sect2 id="importing-bibtex">
<title>Importing Bibtex Data</title>

<para>
<ulink url="http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html">Bibtex</ulink> 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.
</para>

<para>
If the bibtex importer encounters fields in the file which are not in the default bibliography collection, they are added as <link linkend="line">Simple Text</link> fields, with two exceptions. If the field value contains more than 100 characters, it becomes a <link linkend="para">Paragraph</link> field. If the field value appears to contain a &URL; or a file reference, then a <link linkend="url">URL</link> field is created. &appname; uses an internal copy of the <ulink url="http://www.gerg.ca/software/btOOL/">btparse library</ulink> for parsing the bibtex files.
</para>
</sect2>

<sect2 id="importing-bibtexml">
<title>Importing Bibtexml Data</title>

<para>
<ulink url="http://bibtexml.sf.net">Bibtexml</ulink> 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.
</para>

</sect2>

<sect2 id="importing-mods">
<title>Importing MODS Data</title>

<para>
<acronym><ulink url="http://www.loc.gov/standards/mods/">MODS</ulink></acronym> is a format for representing various types of media collections. Currently, only books may be imported to &appname;.
</para>

</sect2>

<sect2 id="importing-ris">
<title>Importing RIS Data</title>
<para>
The <ulink url="http://www.adeptscience.co.uk/kb/article/A626"><acronym>RIS</acronym> format</ulink> is a bibliographic file format used by <application>Reference Manager</application> and others.
</para>
</sect2>

<sect2 id="importing-xslt">
<title>Importing &xml; Data via XSLT</title>

<para>
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.
</para>
</sect2>

</sect1>

<sect1 id="exporting">
<title>Exporting Data</title>

<para>
When exporting the data in the collection, the entry values may be exported as entered, or with the <link linkend="field-formatting">automatic formatting</link> provided by &appname;. Additionally, the export may be limited to the currently selected entries of the collection as well, where the <link linkend="status-bar">statusbar</link> shows the number of selected entries.
</para>

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

<screenshot>
<screeninfo>General Export Options</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="export-options.png"/></imageobject>
<textobject><phrase>General Export Options</phrase></textobject>
<caption><para>General Export Options</para></caption>
</mediaobject>
</screenshot>

<sect2 id="exporting-xml">
<title>Exporting &xml;</title>

<para>
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.
</para>
</sect2>

<sect2 id="exporting-html">
<title>Exporting HTML</title>

<para>
The HTML export uses the <filename>tellico2html.xsl</filename> stylesheet. Images are exported to a folder with the same name as the exported HTML file with <emphasis><filename>-images</filename></emphasis> appended.
</para>

<para>
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.
</para>

<para>
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 a folder with the same name as the exported HTML file, with <emphasis><filename>-entries</filename></emphasis> appended. The entry HTML files will use the current stylesheet template, as shown in the &entry-view;.
</para>

<screenshot>
<screeninfo>HTML Export Options</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="export-html.png"/></imageobject>
<textobject><phrase>HTML Export Options</phrase></textobject>
<caption><para>HTML Export Options</para></caption>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="exporting-csv">
<title>Exporting CSV</title>

<para>
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.
</para>

<screenshot>
<screeninfo>CSV Export Options</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="export-csv.png"/></imageobject>
<textobject><phrase>CSV Export Options</phrase></textobject>
<caption><para>CSV Export Options</para></caption>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="exporting-pilotdb">
<title>Exporting Pilot-DB</title>

<para>
TBD
</para>
</sect2>

<sect2 id="exporting-bibtex">
<title>Exporting Bibtex</title>

<para>
When exporting to Bibtex, the field values may be escaped with braces or quotation marks.
</para>
</sect2>

<sect2 id="exporting-bibtexml">
<title>Exporting Bibtexml</title>

<para>
TBD
</para>

</sect2>

<sect2 id="exporting-xslt">
<title>Exporting &xml; via &xslt;</title>

<para>
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.
</para>
</sect2>

</sect1>

</chapter>
