<chapter id="configuration">
<title>Configuration</title>

<para>
The <interface>Configuration Dialog</interface> contains all the options for
changing some of the default behaviour of &appname;.
</para>

<para>
Clicking the <guibutton>Apply</guibutton> button <action>causes the changes to
take effect immediately</action> without closing the dialog, while
<guibutton>OK</guibutton> <action>applies the changes and closes the dialog</action>. <guibutton>Cancel</guibutton> closes the dialog, but any changes already made
and applied will remain. The <guibutton>Defaults</guibutton> button <action>reverts
the options</action> on the current page of the dialog to their default values,
while <guibutton>Help</guibutton> <action>opens the &khelpcenter;</action> to
the relative section of the &appname; manual.
</para>

<para>
Some minor settings can only be changed by editing the configuration file itself. See <link linkend="hidden-options">Hidden Options</link>.
</para>

<sect1 id="general-options">
<title><guilabel>General Options</guilabel></title>

<screenshot>
<!-- <screeninfo>The General Options Dialog</screeninfo> -->
<mediaobject>
<imageobject><imagedata format="PNG" fileref="general-options.png"/></imageobject>
<textobject><phrase>The General Options Dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para>
The <guilabel>General Options</guilabel> control the general behavior. Images may be saved
in the data file itself, saved separately in the common &appname; application folder, or saved to
a directory with the same name as the data file, with <emphasis>_files</emphasis> appended to the
name. For collections with many images, saving them in the data file is much slower to use.
When &appname; is started, it can automatically reopen the last data file that was open.
The <interface>Quick Filter</interface> in the toolbar is useful
for easily filtering through your collection and can utilize regular expressions.
</para>

<para>
The <guilabel>Formatting Options</guilabel> control the level of automatic formatting
that &appname; does. For examples, see the <link linkend="field-formatting">Field
Formatting section</link>. Capitalization and formatting are distinct options, since
a field may be capitalized without having the order of the words changed, and
vice-versa. The auto-capitalization can be changed to ignore certain words.
The automatic formatting includes grammatical articles in titles,
along with prefixes and suffixes for personal names. The values are case-insensitive,
and should be separated by a semi-colon.
</para>

<para>
The formatting rules follow general English usage, which may not work for other languages.
Articles are appended to the end of the title, with a comma. Personal names are formatted
to have the last name first, followed by a comma, then the first name. Personal suffixes,
such as Jr., are kept with the last name. Prefixes, such as <emphasis>von</emphasis>,
are kept with the last name, but are ignored when the values are being sorted.</para>

<informalexample><para><emphasis>John Q. von Public, III</emphasis> would become
<emphasis>von Public, III, John Q.</emphasis> and <emphasis>Public</emphasis> would
be used as the sort key.</para></informalexample>

<para>
Only single word prefixes are supported. If a name includes <emphasis>van der</emphasis>,
for example, both <emphasis>van</emphasis> and <emphasis>der</emphasis> should be included
in the surname prefix list. Articles ending with an apostrophe are supported for sorting
order, as well.
</para>

<note><para>The actual values in the collection are <emphasis>not</emphasis> changed,
only the visible text used for the interface. So the formatting options can be
changed back and forth without affecting any of the data in the collection.</para></note>

</sect1>

<sect1 id="printing-options">
<title><guilabel>Printing Options</guilabel></title>

<para>
&appname; uses an &xslt; template for creating &HTML;
and then passes that to the &kde; printing service. Only the fields visible in the <link linkend="detailed-view"><interface>Column View</interface></link> are printed. Furthermore, if the collection
is being filtered, only the visible entries will be printed. Initially, a warning message
is shown if filtering is active.
</para>

<screenshot>
<screeninfo>The Print Options Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="print-options.png"/></imageobject>
<textobject><phrase>The Print Options Dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para>
The <guilabel>Printing Options</guilabel> allow you to change some formatting when
printing a collection. If <guilabel>Format titles and names</guilabel> is checked,
then the fields are <link linkend="field-formatting">auto-formatted</link> when they
are printed. Otherwise, they are printed exactly as they were entered.
</para>

<para>
The default printing stylesheet prints the collection with the field values in columns.
<guilabel>Print field headers</guilabel> controls whether the field title is printed
at the top of the column.
</para>

<para>
In the printout, the entries will be sorted as they are in the <link linkend="detailed-view"><interface>Column View</interface></link>. Additionally, they may be grouped as they are in the <link linkend="group-view"><interface>Group View</interface></link>.
</para>

<para>
Finally, when image fields are included in the printout, the images may be resized,
while maintaining their aspect ratio. The maximum image width and height define the
largest possible size of the image, though it will never be increased.
</para>
</sect1>

<sect1 id="template-options">
<title><guilabel>Template Options</guilabel></title>

<para>
The <link linkend="entry-view"><interface>Entry View</interface></link> uses templates to show the field
values. You can specify a different template for each collection type. Some templates,
such as the <emphasis>Album</emphasis> or <emphasis>Video</emphasis> templates are
for a specific collection type, and a short error message will appear in the
<interface>Entry View</interface> if they are used for other types. The
<guilabel>Preview</guilabel> button pops up a window to show you a preview of what the template looks like.
Custom fonts and colors may be passed to the template, and all of the default templates
will honor those settings. However, custom template may choose to ignore them.</para>

<para>
Additional templates may be installed directly, or downloaded from
<ulink url="https://store.kde.org/">store.kde.org</ulink> by clicking
the <guilabel>Download</guilabel> button. Any templates installed by the user may also be deleted.
Entry templates are saved in <filename class="directory">~/.local/share/tellico/entry-templates/</filename>.
</para>

<para>If you create a new template, please consider submitting it at <ulink url="https://store.kde.org/">store.kde.org</ulink>!</para>

<screenshot>
<screeninfo>The Template Options Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="template-options.png"/></imageobject>
<textobject><phrase>The Template Options Dialog</phrase></textobject>
</mediaobject>
</screenshot>

</sect1>

<sect1 id="data-sources-options">
<title><guilabel>Data Sources Options</guilabel></title>

<para>
&appname; can use various sources for importing data, which can be configured
in the Data Sources Dialog. There are many available types and sources. A few of them are listed below,
while the full list is <ulink url="https://tellico-project.org/data-sources">available on the Tellico web site</ulink>.</para>

<itemizedlist>
<!-- books -->
<listitem><simpara><link linkend="amazon-web-services">Amazon.com Web Services</link>,</simpara></listitem>
<listitem><simpara><link linkend="isbndb">ISBNdb.com</link>,</simpara></listitem>
<listitem><simpara><link linkend="openlibrary">OpenLibrary.org</link>,</simpara></listitem>
<listitem><simpara><link linkend="opds">OPDS catalogs</link>,</simpara></listitem>
<!-- movies -->
<listitem><simpara>the <link linkend="imdb">Internet Movie Database</link>,</simpara></listitem>
<listitem><simpara><link linkend="tmdb">TheMovieDB.org</link>,</simpara></listitem>
<listitem><simpara>the <link linkend="omdb">Open Movie Database</link>,</simpara></listitem>
<listitem><simpara><link linkend="filmaffinity">FilmAffinity</link>,</simpara></listitem>
<!-- comics -->
<listitem><simpara><link linkend="bedetheque">BDGest</link>,</simpara></listitem>
<listitem><simpara><link linkend="comicvine">Comic Vine</link>,</simpara></listitem>
<!-- music -->
<listitem><simpara><link linkend="discogs">Discogs.com</link>,</simpara></listitem>
<listitem><simpara><link linkend="musicbrainz">MusicBrainz.org</link>,</simpara></listitem>
<listitem><simpara><link linkend="itunes">iTunes</link>,</simpara></listitem>
<!-- video games -->
<listitem><simpara><link linkend="tgdb">TheGamesDB.net</link>,</simpara></listitem>
<listitem><simpara><link linkend="giantbomb">GiantBomb.com</link>,</simpara></listitem>
<listitem><simpara><link linkend="mobygames">MobyGames.com</link>,</simpara></listitem>
<listitem><simpara><link linkend="igdb">IGDB.com</link>,</simpara></listitem>
<listitem><simpara><link linkend="videogamegeek">VideoGameGeek</link>,</simpara></listitem>
<!-- board games -->
<listitem><simpara><link linkend="boardgamegeek">BoardGameGeek</link>,</simpara></listitem>
<!-- bibliographic -->
<listitem><simpara><link linkend="bib-sources">arxiv.org</link>,</simpara></listitem>
<listitem><simpara><link linkend="entrez">Entrez (PubMed) databases</link>,</simpara></listitem>
<listitem><simpara><link linkend="z3950">z39.50 servers</link>,</simpara></listitem>
<listitem><simpara><link linkend="sru">SRU servers</link>,</simpara></listitem>
<!-- coins -->
<listitem><simpara><link linkend="colnect">Colnect</link>,</simpara></listitem>
<listitem><simpara><link linkend="numista">Numista</link>,</simpara></listitem>
<!-- others -->
<listitem><simpara><link linkend="externalexec">other external scripts or applications</link>, and</simpara></listitem>
<listitem><simpara><link linkend="multiple-sources">combinations of any of the above sources</link>.</simpara></listitem>
</itemizedlist>

<screenshot>
<screeninfo>The Data Sources Options Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="source-options.png"/></imageobject>
<textobject><phrase>The Data Sources Options Dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para>
New sources may be added by clicking the <guibutton>New...</guibutton> button, while
existing ones may be modified or deleted, using the <guibutton>Modify...</guibutton> or
<guibutton>Delete</guibutton> buttons. The order of the sources, which shows up in the
entry updating menus, can also be changed.
</para>

<para>
Many of the data sources offer more information than the default fields in &appname;. Those other fields are
shown on the right of the configuration box. If any of those fields are checked, they will be added
to the collection when an entry is added from that source.
</para>

<!-- start book sources -->

<sect2 id="book-sources">
<title>Book and Bibliographic Data Sources</title>

<sect3 id="z3950">
<title>z39.50 Servers</title>

<para>
The <ulink url="http://www.cni.org/pub/NISO/docs/Z39.50-brochure/50.brochure.toc.html">z39.50 protocol</ulink> is used to access libraries and bibliographic information providers around the world. Lists of public z39.50 servers are <ulink url="http://www.indexdata.dk/targettest/">available from indexdata.dk</ulink>, among others. &appname; comes with
several preset configurations for major libraries, or you can specify the connection information manually.</para>

<para>&appname;
is able to read data in the <acronym>MODS</acronym>, <acronym>USMARC</acronym>/<acronym>MARC21</acronym>, or <acronym>UNIMARC</acronym> format, using the <ulink url="http://www.indexdata.dk/yaz/">yaz library</ulink>.
In addition, there is limited support for the <acronym>GRS-1</acronym> format.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="z3950-options.png"/></imageobject>
</mediaobject>
</screenshot>

<para>
To use one of the preset libraries, check the box and then select the library. The other configuration entries will be disabled. If you need to set the information manually, uncheck the preset box.
</para>

<para>
The default port for z39.50 access is 210, but some servers may use a different one. &appname; assumes the server uses the MARC-8 character encoding, unless configured otherwise. If an incorrect character encoding is used, an error message may appear on the program output, or possibly no entries are retrieved.
</para>

<para>
Some servers require a username and password for access. &appname; can use and save that password, but be aware that is written to the &appname; configuration file in plain text and is not secure. For most public servers, the username and password fields may be left empty.
</para>

</sect3>

<sect3 id="sru">
<title>SRU Servers</title>

<para>
<acronym>SRU</acronym> stands for <ulink url="http://www.loc.gov/standards/sru/">Search/Retrieve via &URL;</ulink> and is a standard search protocol for
Internet searches. Some libraries use it for providing access to their data catalogs. Among them, the <ulink url="http://www.loc.gov/z3950/lcserver.html#oppr">US Library of Congress</ulink> is probably the best known.
</para>

<para>
Custom fields can be added to tweak Tellico's interaction with the SRU server. To override particular query protocols, use the x-tellico prefix and the desired field name. For
example, to query ISBN using the bib schema instead of the bath schema, set <userinput>x-tellico-isbn</userinput>=<userinput>bib.isbn</userinput>. &tellico; can also make the
SRU request by the POST method, if <userinput>x-tellico-method</userinput>=<userinput>POST</userinput>. In order to override the record schema, add a custom field setting
<userinput>recordSchema</userinput>=<userinput>unimarcXchange</userinput>.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="sru-options.png"/></imageobject>
</mediaobject>
</screenshot>

</sect3>

<sect3 id="entrez">
<title>Entrez Databases</title>
<para>
<ulink url="http://www.ncbi.nlm.nih.gov/Entrez/">Entrez</ulink> is the integrated, text-based search and retrieval system used at the National Center for Biotechnology Information (NCBI). The most well-known Entrez database is <ulink url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=PubMed">PubMed</ulink>, the database for life science articles from many biological journals. At the moment, the only Entrez database supported by &appname; is PubMed.</para>
</sect3>

<sect3 id="bib-sources">
<title>Bibliographic Databases</title>
<para>
<ulink url="http://arxiv.org">arXiv.org</ulink>, <ulink url="http://bibsonomy.org">Bibsonomy</ulink>, and <ulink url="http://crossref.org">CrossRef</ulink> are online databases for academic articles and bibliographic information. For access to the CrossRef source, you must <ulink url="http://www.crossref.org/requestaccount/">request an account</ulink> and add your account information to the data source configuration.</para>
</sect3>

<sect3 id="isbndb">
<title>ISBNdb.com</title>
<para>
<ulink url="http://isbndb.com">ISBNdb.com</ulink> is an online book database, from libraries around the world.
</para>
</sect3>

<sect3 id="openlibrary">
<title>OpenLibrary.org</title>
<para>
<ulink url="http://openlibrary.org">OpenLibrary.org</ulink> is an online book database that aims to have one page for every book.
</para>
</sect3>

<sect3 id="opds">
<title>OPDS Catalogs</title>
<para>
<ulink url="https://en.wikipedia.org/wiki/Open_Publication_Distribution_System">OPDS catalogs</ulink> provide a means for searching (and distributing) digital books.
&tellico; can use many OPDS catalogs as a data source, such as <ulink url="https://wiki.mobileread.com/wiki/OPDS">Project Gutenberg</ulink>. Enter the link to the catalog
and verify the access and format to confirm &tellico; can read the link.
</para>
</sect3>

</sect2>
<!-- end of books -->

<!-- start of movie sources -->
<sect2 id="comicbook-sources">
<title>Comic Book Data Sources</title>

<sect3 id="bedetheque">
<title>Bedetheque</title>
<para>
<ulink url="http://www.bedetheque.com">Bedetheque</ulink> is a French comic book database, managed by BDGest.
</para>
</sect3>

<sect3 id="comicvine">
<title>Comic Vine</title>
<para>
<ulink url="https://comicvine.gamespot.com/">Comic Vine</ulink> is billed as the largest comic book wiki in the universe.
</para>
</sect3>

</sect2>

<!-- start of movie sources -->
<sect2 id="movie-sources">
<title>Movie Data Sources</title>

<sect3 id="imdb">
<title>Internet Movie Database</title>

<para>
The <ulink url="http://www.imdb.com">Internet Movie Database</ulink> provides information about movies and videos. When a search is conducted for a <emphasis>Person</emphasis>, if more than one possible result is returned, a dialog box is opened to allow you to select the correct person. The configuration options include selecting which IMDb nationality to use and whether images are fetched or not. Since IMDb can return a large number of cast members, you can limit that to a certain number.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="imdb-options.png"/></imageobject>
</mediaobject>
</screenshot>

</sect3>

<sect3 id="tmdb">
<title>TheMovieDB.org</title>
<para>
<ulink url="http://themoviedb.org">TheMovieDB.org</ulink> is a free and open online movie database. Registration for a free account is required.
</para>
</sect3>

<sect3 id="omdb">
<title>The Open Movie Database</title>
<para>
<ulink url="http://omdbapi.com">The Open Movie Database (OMDBAPI.com)</ulink> is a free web service to obtain movie information.
</para>
</sect3>

<sect3 id="filmaffinity">
<title>FilmAffinity</title>
<para>
<ulink url="https://filmaffinity.com">FilmAffinity</ulink> is an independent film site.
</para>
</sect3>

</sect2>

<!-- start of music sources -->
<sect2 id="music-sources">
<title>Music Data Sources</title>

<sect3 id="discogs">
<title>Discogs.com</title>
<para>
<ulink url="http://discogs.com">Discogs.com</ulink> is a user-built music database containing information on artists, labels, and their recordings. Registration for a free account is required.
</para>
</sect3>

<sect3 id="musicbrainz">
<title>MusicBrainz.org</title>
<para>
<ulink url="http://musicbrainz.org">MusicBrainz.org</ulink> is a community music metadatabase that attempts to create a comprehensive music information site.
</para>
</sect3>

<sect3 id="itunes">
  <title>iTunes Search</title>
  <para>
    The <ulink url="https://performance-partners.apple.com/search-api">iTunes Search</ulink> provides information on content within the iTunes Store and Apple Books Store. You can search for a variety of content; including books, movies, podcasts, music, music videos, audiobooks, and TV shows.
  </para>
</sect3>

</sect2>

<!-- start of wine sources -->
<!--<sect2 id="wine-sources">
<title>Wine Data Sources</title>

</sect2>-->

<!-- start of video game sources -->
<sect2 id="videogame-sources">
<title>Video Game Data Sources</title>

<sect3 id="giantbomb">
<title>GiantBomb.com</title>
<para>
<ulink url="http://giantbomb.com">GiantBomb.com</ulink> is a large community-driven video game database. Registration for a free account is required.
</para>
</sect3>

<sect3 id="tgdb">
<title>TheGamesDB.net</title>
<para>
<ulink url="http://thegamesdb.net">TheGamesDB.net</ulink> is an open, online database for video game fans.
</para>
</sect3>

<sect3 id="mobygames">
<title>MobyGames</title>
<para>
<ulink url="https://www.mobygames.com">MobyGames.com</ulink> is self-described as the oldest, largest and most accurate video game database.
</para>
</sect3>

<sect3 id="igdb">
<title>IGDB.com</title>
<para>
<ulink url="https://www.igdb.com">IGDB.com</ulink> calls itself a gaming website for everyone that loves game.
</para>
</sect3>

<sect3 id="videogamegeek">
<title>VideoGameGeek</title>
<para>
<ulink url="https://videogamegeek.com">VideoGameGeek</ulink> is an online video gaming resource and community.
</para>
</sect3>

</sect2>

<!-- start of board game sources -->
<sect2 id="boardgame-sources">
<title>Board Game Data Sources</title>

<sect3 id="boardgamegeek">
<title>BoardGameGeek</title>
<para>
<ulink url="https://boardgamegeek.com">BoardGameGeek</ulink> is an online board gaming resource and community.
</para>
</sect3>

</sect2>

<!-- start of coin sources -->
<sect2 id="coin-sources">
<title>Coin &amp; Stamp Data Sources</title>

<sect3 id="colnect">
<title>Colnect</title>
<para>
<ulink url="https://colnect.com">Colnect</ulink> is an online community for collectibles providing personal collection management.
&tellico; can search Colnect for coin and stamp information, as well as comic books, sports card, and video games.
</para>
</sect3>

<sect3 id="numista">
<title>Numista</title>
<para>
<ulink url="https://numista.com">Numista</ulink> is a world coin catalog which grows thanks to member contributions, offering
online collection management, tools to easily exchange with other collectors, and a forum.
</para>
</sect3>

</sect2>

<sect2 id="variety-type-sources">
<title>Data Sources for Multiple Collection Types</title>

<sect3 id="amazon-web-services">
<title>Amazon.com</title>

<para>
Using the Amazon Web Services, &appname; can search any of 14 different international sites operated by <ulink url="http://amazon.com">Amazon.com</ulink> for information: United States, United Kingdom, Germany, Japan,
France, Canada, China, Spain, Italy, Brazil, Australia, India, Mexico, and Turkey.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="amazon-options.png"/></imageobject>
</mediaobject>
</screenshot>

<para>
Configuring each Amazon.com source involves three settings: the server location, image size, and associate's ID. Some information
from <ulink url="http://amazon.com">Amazon.com</ulink> may include an image, such as a book or video cover. That image may be downloaded in three different sizes, depending on the item. The associate's ID must be used to access the Amazon.com Web Services, and is included in the links back to the item, as dictated by the license agreement for the use of the Amazon.com Web Services.
</para>

<para>Access to the <ulink url="https://docs.aws.amazon.com/AWSECommerceService/latest/DG/Welcome.html">Amazon Product Advertising API</ulink> may have restrictions related to sales referrals or advertising. Refer to the Amazon documentation for further information when signing up for API access.
</para>

</sect3>

<sect3 id="externalexec">
<title>External Scripts or Applications</title>
<para>
As an easier way for &appname; to integrate with third-party plugins, external scripts or applications may be used as an interface for searching other information sources. &appname; will execute a command, and pass the search terms as command-line options.
</para>

<para>Some scripts are distributed with &appname; itself. <ulink url="http://python.org">Python</ulink> is required to search <ulink url="http://darkhorse.com">Dark Horse Comics</ulink>, a comic book publisher, for example.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="externalexec-options.png"/></imageobject>
</mediaobject>
</screenshot>

<para>
The collection type returned by the script must be set, along with the data format. Not only can &appname; import data from scripts that
use the <link linkend="file-format">default &appname; &XML; format</link>, but it can also import other formats as well, such as bibtex.
</para>

<para>The full path to the application should be entered in the source options. Check the boxes next to the search keys supported by the application, and enter the required command line options in the edit box. The search value will be inserted where <userinput>%1</userinput> appears.
</para>

<warning>
<para>
Never install and run a script from an untrusted source. They are executed with the same permissions as the user,
and as a result, could modify or delete files or otherwise mess up your system.
</para>
</warning>

<para>
For updating entries already in the collection, the final check box and edit box are used to determine the command-line options. The entry fields used to find an update must be entered, in the same format as used for <link linkend="derived">derived value</link> fields.
</para>
</sect3>

</sect2>

<sect2 id="multiple-sources">
<title>Multiple Combined Data Sources</title>
<para>
Combinations of up to eight existing data sources can be used as a single source, where each search result from the first source is updated from the subsequent sources. The collection type to be used must be set before adding sources.
</para>

<screenshot>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="multiple-sources-options.png"/></imageobject>
</mediaobject>
</screenshot>

<para>
Only existing data sources can be used in combination. Only the search type for the first source can be used in this source since the results come from the first data source. For example, a UPCitemDb search may first be done, with each result then updated from the TheMovieDB.
</para>
</sect2>

</sect1>

</chapter>