[tellico] doc: Update help documents, cleaning up import/export section primarily
Robby Stephenson
null at kde.org
Mon May 13 01:49:29 BST 2019
Git commit edacf481d43eaaa27b695aad663b97c02090fd38 by Robby Stephenson.
Committed on 13/05/2019 at 00:46.
Pushed by rstephenson into branch 'master'.
Update help documents, cleaning up import/export section primarily
M +39 -35 doc/configuration.docbook
M +50 -92 doc/importing-exporting.docbook
M +6 -16 doc/index.docbook
https://commits.kde.org/tellico/edacf481d43eaaa27b695aad663b97c02090fd38
diff --git a/doc/configuration.docbook b/doc/configuration.docbook
index 5c11486b..a368616d 100644
--- a/doc/configuration.docbook
+++ b/doc/configuration.docbook
@@ -154,29 +154,29 @@ Entry templates are saved in <filename class="directory">$<envar>KDEHOME</envar>
<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.</para>
+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="http://tellico-project.org/data-sources">available on the Tellico web site</ulink>.</para>
<itemizedlist>
-<listitem><para><link linkend="amazon-web-services">Amazon.com Web Services</link>,</para></listitem>
-<listitem><para>the <link linkend="imdb">Internet Movie Database</link>,</para></listitem>
-<listitem><para><link linkend="z3950">z39.50 servers</link>,</para></listitem>
-<listitem><para><link linkend="sru">SRU servers</link>,</para></listitem>
-<listitem><para><link linkend="entrez">Entrez (PubMed) databases</link>,</para></listitem>
-<listitem><para><link linkend="animenfo">AnimeNfo.com</link>,</para></listitem>
-<listitem><para><link linkend="ibs">Internet Bookshop Italia</link>,</para></listitem>
-<listitem><para><link linkend="isbndb">ISBNdb.com</link>,</para></listitem>
-<listitem><para><link linkend="bib-sources">arxiv.org</link>,</para></listitem>
-<listitem><para><link linkend="bib-sources">bibsonomy.org</link>,</para></listitem>
-<listitem><para><link linkend="bib-sources">crossref.org</link>,</para></listitem>
-<listitem><para><link linkend="discogs">Discogs.com</link>,</para></listitem>
-<listitem><para><link linkend="tmdb">TheMovieDB.org</link>,</para></listitem>
-<listitem><para><link linkend="tgdb">TheGamesDB.net</link>,</para></listitem>
-<listitem><para><link linkend="omdb">OMDBAPI.com</link>,</para></listitem>
-<listitem><para><link linkend="musicbrainz">MusicBrainz.org</link>,</para></listitem>
-<listitem><para><link linkend="giantbomb">GiantBomb.com</link>,</para></listitem>
-<listitem><para><link linkend="openlibrary">OpenLibrary.org</link>,</para></listitem>
-<listitem><para><link linkend="externalexec">other external scripts or applications</link>, and</para></listitem>
-<listitem><para><link linkend="multiple-sources">combinations of any of the above sources</link>.</para></listitem>
+<listitem><simpara><link linkend="amazon-web-services">Amazon.com Web Services</link>,</simpara></listitem>
+<listitem><simpara>the <link linkend="imdb">Internet Movie Database</link>,</simpara></listitem>
+<listitem><simpara><link linkend="allocine">AlloCiné</link>,</simpara></listitem>
+<listitem><simpara><link linkend="z3950">z39.50 servers</link>,</simpara></listitem>
+<listitem><simpara><link linkend="sru">SRU servers</link>,</simpara></listitem>
+<listitem><simpara><link linkend="entrez">Entrez (PubMed) databases</link>,</simpara></listitem>
+<listitem><simpara><link linkend="animenfo">AnimeNfo.com</link>,</simpara></listitem>
+<listitem><simpara><link linkend="bedetheque">BDGest</link>,</simpara></listitem>
+<listitem><simpara><link linkend="isbndb">ISBNdb.com</link>,</simpara></listitem>
+<listitem><simpara><link linkend="bib-sources">arxiv.org</link>,</simpara></listitem>
+<listitem><simpara><link linkend="discogs">Discogs.com</link>,</simpara></listitem>
+<listitem><simpara><link linkend="tmdb">TheMovieDB.org</link>,</simpara></listitem>
+<listitem><simpara><link linkend="tgdb">TheGamesDB.net</link>,</simpara></listitem>
+<listitem><simpara><link linkend="omdb">OMDBAPI.com</link>,</simpara></listitem>
+<listitem><simpara><link linkend="musicbrainz">MusicBrainz.org</link>,</simpara></listitem>
+<listitem><simpara><link linkend="giantbomb">GiantBomb.com</link>,</simpara></listitem>
+<listitem><simpara><link linkend="openlibrary">OpenLibrary.org</link>,</simpara></listitem>
+<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>
@@ -194,12 +194,6 @@ existing ones may be modified or deleted, using the <guibutton>Modify...</guibut
entry updating menus, can also be changed.
</para>
-<para>
-Additional templates may be downloaded from the author's online repository by clicking
-the <guilabel>Download</guilabel> button. Those scripts are gpg-signed by the author to
-guard against dangerous scripts from unknown sources, which could cause damage to your system.
-</para>
-
<warning>
<para>
Never install and run a script from an untrusted source. They are executed with the same permissions as the user,
@@ -279,17 +273,10 @@ the best known.
<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="ibs">
-<title>Internet Bookstore Italia</title>
-<para>
-<ulink url="http://ibs.it">IBS, or Internet Bookstore Italia</ulink>, is an online Italian bookstore.
-</para>
-</sect3>
-
<sect3 id="isbndb">
<title>ISBNdb.com</title>
<para>
-<ulink url="http://isbndb.com">ISBNdb.com</ulink> is an online book database, with data collection libraries around the world.
+<ulink url="http://isbndb.com">ISBNdb.com</ulink> is an online book database, from libraries around the world.
</para>
</sect3>
@@ -314,6 +301,13 @@ the best known.
</para>
</sect3>
+<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>
+
</sect2>
<!-- start of movie sources -->
@@ -349,6 +343,13 @@ The <ulink url="http://www.imdb.com">Internet Movie Database</ulink> provides in
</para>
</sect3>
+<sect3 id="allocine">
+<title>AlloCiné</title>
+<para>
+<ulink url="http://allocine.fr">AlloCiné</ulink> is an online movie information service, based in France.
+</para>
+</sect3>
+
</sect2>
<!-- start of music sources -->
@@ -419,6 +420,9 @@ Configuring each Amazon.com source involves three settings: the server location,
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">
diff --git a/doc/importing-exporting.docbook b/doc/importing-exporting.docbook
index 4ecc851a..a7ca2b68 100644
--- a/doc/importing-exporting.docbook
+++ b/doc/importing-exporting.docbook
@@ -43,18 +43,29 @@ To facilitate the use of barcode scanners, searches can include multiple ISBN/UP
<title>Importing Data</title>
<para>
-&appname; offers three different actions when importing data. <guilabel>Replace current collection</guilabel> will close the current collection, and create a new one with the data from the imported file. <guilabel>Append to current 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.
+&appname; offers three different actions when importing data. <guilabel>Replace current collection</guilabel> will close the current collection, and create a new one with the data from the imported file. <guilabel>Append to current 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. &appname; attempts to identify matching entries which are not completely identical by comparing significant fields and will then merge the entries. For example, music collections compare the artist and album, and the tracks would be 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">
+<sect2 id="alternate-software">
+<title>Importing Data From Other Software</title>
+
+<para>&appname; can import data directly from a variety of other collection management programs, including <application><ulink url="http://www.gcstar.org">GCstar</ulink></application>, <application><ulink url="https://github.com/mvz/alexandria-book-collection-manager">Alexandria</ulink></application>, <application><ulink url="https://www.delicious-monster.com">Delicious Library</ulink></application>, <application><ulink url="http://www.antp.be/software/moviecatalog/">Ant Movie Catalog</ulink></application>, <application><ulink url="https://en.wikipedia.org/wiki/Referencer">Referencer</ulink></application>, and <application><ulink url="https://launchpad.net/griffith">Griffith</ulink></application>.</para>
+
+</sect2>
+
+<sect2 id="import-data-files">
+<title>Importing Other Data Formats</title>
+<para>&appname; can import data from a variety of other file formats, including <acronym>CSV</acronym>, bibtex, audio discs and files, <acronym>MODS</acronym>, &PDF;, and <acronym>RIS</acronym>.</para>
+
+<sect3 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.
+Other &appname; data files may be imported directly. 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>
+</sect3>
-<sect2 id="importing-csv">
+<sect3 id="importing-csv">
<title>Importing CSV Data</title>
<para>
@@ -78,12 +89,12 @@ In order for &appname; to properly import the file, it must know which field cor
</para>
<para>
-Only the first five lines of the imported CSV file are shown in the dialog.
+For compactness, only the first five lines of the imported CSV file are shown in the dialog. However, all the lines in the file will be imported.
</para>
-</sect2>
+</sect3>
-<sect2 id="importing-audio">
+<sect3 id="importing-audio">
<title>Importing Audio &CD; Data</title>
<para>
@@ -96,9 +107,9 @@ year, and track listing are all added.
<para>
In addition, if the disc contains &CD;-Text, that information is read and added to the imported entry.
</para>
-</sect2>
+</sect3>
-<sect2 id="importing-audio-files">
+<sect3 id="importing-audio-files">
<title>Importing Audio File Metadata</title>
<para>
@@ -110,113 +121,69 @@ In addition, if a folder contains a <filename>.directory</filename> file and the
</para>
<para>
-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 <ulink url="http://developer.kde.org/~wheeler/taglib.html">TagLib library</ulink> for reading the audio file metadata, and so can import data from any file type that TagLib understands.
+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 <ulink url="https://taglib.org">TagLib library</ulink> for reading the audio file metadata, and so can import data from any file type that TagLib understands.
</para>
-</sect2>
-
-<sect2 id="importing-alexandria">
-<title>Importing Alexandria Libraries</title>
+</sect3>
-<para>
-<application><ulink url="http://alexandria.rubyforge.org">Alexandria</ulink></application> is an alternate 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-amc">
-<title>Importing Ant Movie Catalog Data</title>
-
-<para>
-<application><ulink url="http://www.antp.be/software/moviecatalog/">Ant Movie Catalog</ulink></application> is an alternate movie collection manager.
-</para>
-
-</sect2>
-
-<sect2 id="importing-bibtex">
+<sect3 id="importing-bibtex">
<title>Importing Bibtex Data</title>
<para>
-<ulink url="http://en.wikipedia.org/wiki/Bibtex">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.
+<ulink url="http://en.wikipedia.org/wiki/Bibtex">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 <link linkend="bibliography">Bibliographic collection</link>.
</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-delicious-library">
-<title>Importing Delicious Library Data</title>
-
-<para>
-<application><ulink url="http://www.delicious-monster.com/">Delicious Library</ulink></application> is an alternate collection manager for the &Mac; OS X desktop. &appname; imports a subset of the data used by Delicious Library.
-</para>
-</sect2>
+</sect3>
-<sect2 id="importing-gcstar">
-<title>Importing GCstar Data</title>
-
-<para>
-<application><ulink url="http://www.gcstar.org">GCstar</ulink></application> is an alternate collection manager. Importing books, movies, music, coins, games, board games and wine collections is currently supported.
-</para>
+<sect3 id="importing-mods">
+<title>Importing MODS Data</title>
<para>
-&appname; can also import <application>GCfilms</application> data files. <application><ulink url="http://home.gna.org/gcfilms/">GCfilms</ulink></application> is the predecessor of <application>GCstar</application> and was an alternate movie collection manager. Normally, <application>GCfilms</application> data files are found in <filename class="directory">$<envar>HOME</envar>/.local/share/gcfilms/</filename>.
+<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 are imported by &appname;, as a <link linkend="bibliography">Bibliographic collection</link>.
</para>
-</sect2>
-
-<sect2 id="importing-griffith">
-<title>Importing Griffith Data</title>
+</sect3>
+<sect3 id="importing-pdf">
+<title>Importing &PDF; Data</title>
<para>
-<application><ulink url="http://griffith.berlios.de/">Griffith</ulink></application> is an alternate video collection manager. &appname; is able to import most data from a Griffith database.
+If &appname; was compiled with <emphasis>exempi</emphasis> or <emphasis>poppler</emphasis> 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.
</para>
-</sect2>
-
-<sect2 id="importing-mods">
-<title>Importing MODS Data</title>
+</sect3>
+<sect3 id="importing-ris">
+<title>Importing RIS 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 are imported by &appname;, as a Bibliographic collection.
+The <ulink url="https://en.wikipedia.org/wiki/RIS_(file_format)"><acronym>RIS</acronym> format</ulink> is a bibliographic file format used by <application>EndNote</application>, <application>Reference Manager</application>, and others. &appname; imports RIS files as a <link linkend="bibliography">Bibliographic collection</link>.
</para>
+</sect3>
</sect2>
-<sect2 id="importing-pdf">
-<title>Importing PDF Data</title>
-<para>
-If &appname; was compiled with <emphasis>exempi</emphasis> or <emphasis>poppler</emphasis> 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.
-</para>
-</sect2>
+<sect2 id="import-online-collection">
+<title>Importing Online Collections</title>
+<para>&appname; can connect to and import from websites that manage personal collections.</para>
-<sect2 id="importing-referencer">
-<title>Importing Referencer Data</title>
+<sect3 id="importing-boardgamegeek">
+<title>Importing BoardGameGeek Collection</title>
<para>
-<application><ulink url="http://icculus.org/referencer/">Referencer</ulink></application> is a document organizer and bibliography manager for the GNOME desktop. &appname; will import most of the data found in a Referencer database.
+<ulink url="https://boardgamegeek.com">BoardGameGeek</ulink> is an online board gaming resource and community. &appname; can import the board games in a user's collection, as long as the collection is set to be publicly accessible. The imported collection may be limited to those items marked as being owned.
</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. &appname; imports RIS files as a Bibliographic collection.
-</para>
-</sect2>
+</sect3>
-<sect2 id="importing-goodreads">
+<sect3 id="importing-goodreads">
<title>Importing Goodreads Collection</title>
<para>
-<ulink url="http://www.goodreads.com">Goodreads</ulink> is an online social network for readers to track book collections. &appname; can import the list of books in a user's collection, given either the user name or user ID, as long as the collection is set to be publicly accessible.
+<ulink url="https://www.goodreads.com">Goodreads</ulink> is an online social network for readers to track book collections. &appname; can import the list of books in a user's collection, given either the user name or user ID, as long as the collection is set to be publicly accessible.
</para>
+</sect3>
</sect2>
<sect2 id="importing-file-listing">
@@ -240,9 +207,9 @@ Any &XML; file may be imported into &appname; provided an &XSL; stylesheet is av
<sect1 id="drag-n-drop">
<title>Drag and Drop</title>
-<para>Dragging data files to the main &appname; window and dropping them will import the files, just as if the <link linkend="importing">import command</link> 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.</para>
+<para>Dragging data files to the main &appname; window and dropping them will import the files, just as if the <link linkend="importing">import command</link> 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.</para>
-<para>So, for example, if you want to catalog several <link linkend="importing-pdf">PDF files</link>, 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.</para>
+<para>So, for example, if you want to catalog several <link linkend="importing-pdf">&PDF; files</link>, 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.</para>
</sect1>
@@ -357,15 +324,6 @@ may enclose the field values with the <literal>\url{...}</literal> tag. Finally,
</screenshot>
</sect2>
-<sect2 id="exporting-bibtexml">
-<title>Exporting Bibtexml</title>
-
-<para>
-<ulink url="http://bibtexml.sourceforge.net">Bibtexml</ulink> is a format for expressing bibtex data via &XML;.
-</para>
-
-</sect2>
-
<sect2 id="exporting-gcstar">
<title>Exporting GCstar</title>
diff --git a/doc/index.docbook b/doc/index.docbook
index fdd1119f..73446352 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -39,8 +39,8 @@ need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->
-<date>28/08/2009</date>
-<releaseinfo>2.0</releaseinfo>
+<date>12/05/2019</date>
+<releaseinfo>3.2</releaseinfo>
<title>The &tellico; Handbook</title>
@@ -56,17 +56,7 @@ Do NOT change these in the translation. -->
</authorgroup>
<copyright>
-<year>2001</year>
-<year>2002</year>
-<year>2003</year>
-<year>2004</year>
-<year>2005</year>
-<year>2006</year>
-<year>2007</year>
-<year>2008</year>
-<year>2009</year>
-<year>2010</year>
-<year>2011</year>
+<year>2001-2019</year>
<holder>&robby;</holder>
</copyright>
@@ -147,7 +137,7 @@ little information as you like.
</para>
<para>
-Loans may be tracked, with optional integration with &korganizer;. Collections may be
+Loans of items in your collection may be tracked, including a due date. Collections may be
imported or exported using a variety of formats, to allow for easy exchange
or publication of data.
</para>
@@ -254,10 +244,10 @@ file included in the KDE distribution. -->
&tellico;
</para>
<para>
-Program copyright 2001-2011 &robby; <email>&email;</email>
+Program copyright 2001-2019 &robby; <email>&email;</email>
</para>
<para>
-Documentation copyright 2001-2011 &robby; <email>&email;</email>
+Documentation copyright 2001-2019 &robby; <email>&email;</email>
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
More information about the kde-doc-english
mailing list