<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kscd;">
  <!ENTITY package "kdemultimedia">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kscd; Handbook</title>

<authorgroup>

<author>
<firstname>Jonathan</firstname>
<surname>Singer</surname>
<affiliation><address><email>jsinger@leeta.net</email></address></affiliation>
</author>

<author>
<firstname>David</firstname>
<surname>White</surname>
<affiliation><address><email>a9403784@unet.univie.ac.at</email></address>
</affiliation>
</author>

<othercredit role="developer">
<firstname>Bernd</firstname>
<othername>Johannes</othername>
<surname>Wuebben</surname>
<affiliation><address><email>wuebben@kde.org</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Dirk</firstname>
<surname>Forsterling</surname>
<affiliation><address><email>milliByte@gmx.net</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Dirk</firstname>
<surname>Foersterling</surname>
<affiliation><address><email>milliByte@gmx.net</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address><email>lauri@kde.org</email></address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2000</year><year>2002</year>
<holder>J Singer</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>


<date>2002-10-07</date>
<releaseinfo>1.03.03</releaseinfo>

<abstract>
<para>&kscd; is a small, fast, <abbrev>CDDB</abbrev> enabled audio
<abbrev>CD</abbrev> player for &UNIX; platforms.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
<keyword>kscd</keyword>
<keyword>music</keyword>
<keyword>CD</keyword>
<keyword>audio</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kscd; is a fast, <acronym>CDDB</acronym>cddb enabled &CD; player for the &UNIX;
platform. &kscd; stands for <quote>The KDE Project's small/simple &CD;
player</quote>.</para>

<para><emphasis>New</emphasis>: the <filename>workman2cddb.pl</filename> Perl
script provided in order to facilitate transition for users of workman.</para>

<para>I hope you will enjoy this &CD; player.</para>

<para>Bernd Johannes Wuebben</para>

<para><email>wuebben@kde.org</email></para>

<sect1 id="supported-platforms">
<title>Supported Platforms</title>

<para>&kscd; explicitly supports the following platforms:</para>

<itemizedlist>
<listitem><para>Linux</para></listitem>
<listitem><para>FreeBSD</para></listitem>
<listitem><para>NetBSD</para></listitem>
<listitem><para>BSD386</para></listitem>
<listitem><para>Sun</para></listitem>
<listitem><para>&Solaris; (including <acronym>cdda</acronym>
support)</para></listitem>
<listitem><para>&HP-UX;</para></listitem>
<listitem><para>&SGI; Irix (including <abbrev>cdda</abbrev>
support)</para></listitem>
<listitem><para>Sony NEWS</para></listitem>
<listitem><para>OSF/1</para></listitem>
<listitem><para>Ultrix</para></listitem>
</itemizedlist>

<para>and should compile on many others with few modifications.</para>

</sect1>

</chapter>

<chapter id="onscreen-fundamentals">
<title>Onscreen fundamentals</title>

<sect1 id="basic-operation">
<title>Basic Operation</title>

<screenshot>
<screeninfo>The &kscd; Interface</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kscd.png" format="PNG"/></imageobject>
<textobject><phrase>The &kscd; Interface</phrase></textobject>
</mediaobject>
</screenshot>

<para>This is the main window of &kscd;. You should see something like this when
you start &kscd;. The controls in this window are explained below, in no
particular order.</para>

<sect2 id="control-panel">
<title>The Control Panel</title>

<screenshot>
<screeninfo>The Control Panel</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd2.png" format="PNG"/></imageobject>
<textobject><phrase>The Control Panel</phrase></textobject>
</mediaobject>
</screenshot>

<para> This is the main control panel for &kscd;. The function of these buttons
should be familiar to anyone who has ever used a &CD; player.</para>

<para>The uppermost button in the above diagram toggles between playing and
pausing the &CD;. The left button in the second row stops playing the &CD;. The
right button in the second row toggles looping, so that the &CD; will start
playing again from the beginning when the end of the last audio track is
reached. The buttons in the third row advance the &CD; backward (left) or
forward (right) 30 seconds. The two buttons under the status display skip forward (right)
or backward (left) to the beginning of the next or previous track. </para>
</sect2>

<sect2 id="eject">
<title>The <guibutton>Eject</guibutton> button</title>

<screenshot>
<screeninfo>The <guibutton>Eject</guibutton> button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd2a.png" format="PNG"/></imageobject>
<textobject><phrase>The Eject button</phrase></textobject>
</mediaobject>
</screenshot>

<para>This button ejects the &CD;. Note that the eject button on your &CD-ROM;
drive may not respond if an audio &CD; is in the drive and &kscd; is
started. Some very old &CD-ROM; drives may not support software eject. You may
also have to close the &CD-ROM; drive manually after inserting a new
disc.</para>
</sect2>

<sect2 id="status-display">
<title>The Status Display</title>

<screenshot>
<screeninfo>The Status Display</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd3.png" format="PNG"/></imageobject>
<textobject><phrase>The Status Display</phrase></textobject>
</mediaobject>
</screenshot>

<para>This is the status display. Starting at the top, from right to left, is
the main time display (see below for a discussion of the various possible time
display modes), the status of the &CD-ROM; drive, the total play time of the
audio &CD;, the current volume setting, and the current and maximum track
numbers (curr./max.). The bottommost two lines of text display the artist and
title of the &CD;, and then the title of the track, assuming that appropriate
entries exist in the local or network <acronym>CDDB</acronym> (&CD; Data
Base.)</para>

</sect2>

<sect2 id="time-display-modes">
<title>Time display modes</title>

<screenshot>
<screeninfo>The Time Display toggle</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd4.png" format="PNG"/></imageobject>
<textobject><phrase>The Time Display toggle</phrase></textobject>
</mediaobject>
</screenshot>

<para>This button toggles between the possible main time display modes. By
default, &kscd; displays the elapsed time of the current track, if the &CD; is
playing, or either &ndash;&ndash;:&ndash;&ndash; or 00:00 if the &CD; is not playing.
Pressing this button toggles in sequence between remaining track time, total
elapsed time, and total remaining time.</para>
</sect2>

<sect2 id="configuration-button">
<title>The <guibutton>Configuration</guibutton> button</title>

<screenshot>
<screeninfo>The Configuration button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd5.png" format="PNG"/></imageobject>
<textobject><phrase>The Configuration button</phrase></textobject>
</mediaobject>
</screenshot>

<para>This button opens the &kscd; configuration panel. This allows you to
configure &kscd; to work on your machine. See <link linkend="configuring-kscd">the configuring &kscd;</link> section, for details
about configuring &kscd;</para>
</sect2>

<sect2 id="cddb-button">
<title>The <guibutton>CDDB</guibutton> button</title>

<screenshot>
<screeninfo>The <acronym>CDDB</acronym> button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd6.png" format="PNG"/></imageobject>
<textobject><phrase>The <acronym>CDDB</acronym> button</phrase></textobject>
</mediaobject>
</screenshot>

<para> This button opens the <acronym>CDDB</acronym> (Compact Disc Data Base) entry
editor panel. </para>

<para>The <acronym>CDDB</acronym> can identify your &CD; and often download a
list of tracks for that &CD; or load it from the filesystem. See the <link
linkend="cddb-editor">&CD; Database Editor</link> section for more details about
using this tool.</para>
</sect2>

<sect2 id="information-button">
<title>The <guibutton>Information</guibutton> button</title>

<screenshot>
<screeninfo>The Information button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd7.png" format="PNG"/></imageobject>
<textobject><phrase>The Information button</phrase></textobject>
</mediaobject>
</screenshot>

<para> This button will help you search for information about the artist on the
Internet. You can find out about performance dates, purchase information, and
other information by pressing this button and choosing the appropriate option in
the pop-up menu that appears.</para>
</sect2>

<sect2>
<title>The Exit button</title>

<screenshot>
<screeninfo>The Exit button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd8.png" format="PNG"/></imageobject>
<textobject><phrase>The exit button</phrase></textobject>
</mediaobject>
</screenshot>

<para> This button closes &kscd;.</para>
</sect2>

<sect2>
<title>The Volume slider</title>

<screenshot>
<screeninfo>The Volume slider</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd9.png" format="PNG"/></imageobject>
<textobject><phrase>The Volume slider</phrase></textobject>
</mediaobject>
</screenshot>

<para> This slider controls the volume of the audio output of the &CD;. Right is
louder, left is quieter. If you are playing your &CD; through your sound card,
the sound card mixer will affect the playback volume as well.</para>
</sect2>

<sect2 id="randomize-button">
<title>The Randomize button</title>

<screenshot>
<screeninfo>The Randomize button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd15.png" format="PNG"/></imageobject>
<textobject><phrase>The Randomize button</phrase></textobject>
</mediaobject>
</screenshot>

<para> This button causes the &CD; tracks to be played in random order. </para>
</sect2>

<sect2>
<title>The track selector</title>

<screenshot>
<screeninfo>The track selector</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd11.png" format="PNG"/></imageobject>
<textobject><phrase>The Track selector</phrase></textobject>
</mediaobject>
</screenshot>
	    
<para>This combo box shows you the current track and lets you directly select
a track to play. </para>
</sect2>

</sect1>
</chapter>

<chapter id="configuring-kscd">
<title>Configuring &kscd;</title>
<sect1 id="configuration-intro">
<title>The primary configuration window</title>

<para>The primary configuration window for &kscd; is a tabbed dialog with four
major sections. </para>

<itemizedlist>
<listitem><para><link linkend="kscd-options-tab"><guilabel>CD
Player</guilabel></link></para></listitem>
<listitem><para><link linkend="freedb-tab"><guilabel>freedb</guilabel></link></para></listitem>
<listitem><para><link linkend="smtp-options"><guilabel>SMTP</guilabel>
</link></para></listitem>
<listitem><para><link linkend="about"><guilabel>Credits</guilabel></link></para></listitem>
</itemizedlist>
</sect1>

<sect1 id="kscd-options-tab">
<title>The <guilabel>CD Player</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>CD Player</guilabel> tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd12.png" format="PNG"/></imageobject>
<textobject><phrase>The <guilabel>KSCD Configuration</guilabel> tab</phrase></textobject>
</mediaobject>
</screenshot>

<para>The <guilabel>LCD Color</guilabel> and <guilabel>Background
Color</guilabel> fields show the color selected for the foreground and
background of the status display. Press the color bars to change
these colors.</para>


<!--
<para>The <guilabel>Unix mail command</guilabel> field shows the
command used to send new <acronym>CDDB</acronym> entries to the
database. The default value is <userinput><command>mail</command>
<option>-s <replaceable>%s</replaceable></option></userinput>. You
will need to make sure this command will actually send mail to
non-local systems if you want to submit <acronym>CDDB</acronym>
entries, especially if you access the Internet through a dial-up
connection. Check the documentation for your &Linux; distribution for
details. Some Linux distributions that use sendmail to deliver e-mail
require only that you enter your mail host into the
<option>&quot;Smart&quot; relay host</option> field in
<filename>/etc/sendmail.cf</filename>. In addition, the
<acronym>CDDB</acronym> site will want to be able to mail you back; it
may therefore also be necessary to edit
<filename>/etc/sendmail.cf</filename> to ensure that the return
address on the submission is valid. Your mileage is likely to vary. If
all else fails, use <link linkend="smtp-options">SMTP</link>
instead.</para>

<para>The <guilabel>WWW-Browser</guilabel> section lets you choose which web
browser to use to access the web sites in the <link linkend="information-button">information button</link> menus.  You can choose
either &konqueror; or a custom browser with the radio buttons. By default, the
<guilabel>Use Custom Browser</guilabel> field contains
<userinput><command>kfmclient</command>
<option><replaceable>openURL %s</replaceable></option></userinput>.</para>
-->

<para>Set the <guilabel>Skip interval</guilabel> box to the desired number of 
seconds to move ahead or behind when the <guibutton>forward skip</guibutton> 
or <guibutton>reverse skip</guibutton> buttons in the Control Panel are pressed.</para>

<para>The <guilabel>Show tool tips</guilabel> checkbox turns tooltips (tiny
windows that pop up when the mouse is <quote>parked</quote> briefly over a
control) on or off.</para>

<para><guilabel>Show icon in system tray</guilabel> causes a &kscd; control to
appear in the &kicker; panel.</para>

<para><guilabel>Autoplay when CD inserted</guilabel> causes &CD; play to
start when the tray is closed, with no need to press the
<guibutton>Play</guibutton> button.</para>

<para><guilabel>Eject CD when finished playing</guilabel> causes the
&CD; to be ejected when playback ends.</para>

<para><guilabel>Stop playing on exit</guilabel> causes &CD; playback to stop
when &kscd; is closed.</para>

<!--<para><guilabel>Random is Shuffle</guilabel> means that when <link
linkend="randomize-button">random play</link> is used, each track is
played only once.</para> -->

<para>You can choose how random play operates, from two
self-explanatory options: <guilabel>Shuffle order and play each song
only once</guilabel> and <guilabel>Randomly select songs (may
repeat)</guilabel>.</para>

<para>The <guilabel>CD-ROM Device</guilabel> field contains the name
of the &CD-ROM; device to be used to play audio &CD;s. The default
value is <filename>/dev/cdrom</filename>. The permissions on this
device must be set to allow opening this device read-only. Changing
the permissions on this device file will in almost all cases require
superuser privileges and can be done from the command line, or in the
Super User Mode of &konqueror;.</para>

<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>
</sect1>

<sect1 id="freedb-tab">
<title>The <guilabel>freedb</guilabel> tab</title>
<screenshot>
<screeninfo>The <guilabel>freedb</guilabel> tab of the configuration dialog</screeninfo>
<mediaobject>
<imageobject> <imagedata fileref="kscd14.png" format="PNG"/> </imageobject>
<textobject><phrase>The <guilabel>freedb</guilabel> tab of the configuration
dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para> The <guilabel>freedb</guilabel> tab sets up the <acronym>CDDB</acronym> functions
of &kscd;.</para>

<para>The <guilabel>Enable Remote freedb</guilabel> checkbox turns on or off
<acronym>CDDB</acronym> lookups over the Internet.  The time allowed before the
lookup attempt times out can be set. To use an &HTTP; proxy, check the
<guilabel>Use HTTP proxy to access freedb</guilabel> and
enter the &URL; in the field below.</para>

<para>Checking <guilabel>Enable autosave to local database</guilabel> causes 
<acronym>CDDB</acronym> information to be stored locally, saving you from having 
to repeatedly perform lookups over the Internet. The <guilabel>freedb Base 
Folder:</guilabel> text field lets you choose the folder where you want 
<acronym>CDDB</acronym> entries to be stored locally.</para>

<para>The <guilabel>freedb server:</guilabel> list box shows a list of known
freedb servers. Select an entry from this list and it will
appear in the text field above the selection box. Press the
<guibutton>Update</guibutton> button to update the list of servers in the list
box.  Press the <guibutton>Defaults</guibutton> button to enter the default
value, <userinput>freedb.freedb.org cddbp 888 -</userinput>, which will permit you to
update the list with a fresh list of freedb servers listed with
the master freedb site at <systemitem
class="systemname">freedb.freedb.org</systemitem>. Servers can also be added 
manually by entering the address in the upper box and hitting the
<guiicon>+</guiicon> button. Hit the
<guiicon>-</guiicon> button to delete the selected entry from the
list.</para>

<para>The <guilabel>Send freedb submissions to:</guilabel> field contains the
e-mail address to which to submit <abbrev>CDDB</abbrev> entries. The default address
is <email>freedb-submit@freedb.org</email>. As of version 0.8,
<acronym>CDDB</acronym> entries from &kscd; are accepted for inclusion in the
database. Enter servers manually by entering the address in the upper box and hitting the
<guiicon>+</guiicon> button. Hit the <guiicon>-</guiicon> button to delete the selected entry
from the list. The <guibutton>Defaults</guibutton> button restores all settings
to the default values.The <guibutton>Help</guibutton> button opens the &kscd;
help home page (this document).</para>

<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>
</sect1>

<sect1 id="smtp-options">
<title>The <guilabel>SMTP</guilabel> tab</title>

<screenshot>
<screeninfo>The SMTP tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd16.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>The <acronym>SMTP</acronym> tab sets up connection to a mail
server to submit new <acronym>CDDB</acronym> entries. This is useful
if you do not have your own system configured as a server. Check
<guilabel>Enable submission via SMTP</guilabel> to use this
feature. Select your preferred email profile in the <guilabel>Current
Email Profile</guilabel> box. Enter the address of the
<acronym>SMTP</acronym> server server in the field labelled
<guilabel>Host:</guilabel> and the port number (typically
<userinput>25</userinput>) in the field labelled
<guilabel>Port:</guilabel>.</para>

<para>You may choose to <guilabel>Use email addresses from Control
 Center</guilabel> if you wish.  If you would like to open the
 &kcontrol; module to configure this email address, click on the text
 labelled <guilabel>Open the email address control panel</guilabel>.
 Changing the address there will change the default address for all
 &kde; applications that use this setting, not just for &kscd;, so do
 this with caution.</para>

<para>If you don't wish to use the globally configured email address,
choose the option labelled <guilabel>Use the following email
address</guilabel> and enter a different email or reply-to address in
the lower text fields.</para>

<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>
</sect1>


<sect1 id="about">
<title>The <guilabel>Credits</guilabel> tab </title>

<para> The <guilabel>Credits</guilabel> tab displays information about
the version of &kscd; you are using and some copyright
information. </para>

</sect1>
</chapter>

<chapter id="cddb-editor">
<title>The <guilabel>CD Database Editor</guilabel></title>

<screenshot>
<screeninfo>The CD Database Editor</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd13.png" format="PNG"/></imageobject>
<textobject><phrase>The CD Database Editor</phrase></textobject>
</mediaobject>
</screenshot>

<para>The &CD; Database Editor allows you to modify, download, save, annotate,
and upload <link linkend="cddb-support"><acronym>CDDB</acronym> (Compact Disc
Data Base)</link> entries.</para>

<para>If there is an entry in your local <acronym>CDDB</acronym> tree
(see the <link linkend="freedb-tab">CDDB subsection</link> in the
Configuration chapter) for the &CD; in your &CD-ROM; drive, or if the
disc could be found in the freedb, you will see the name of the artist
and the title of the &CD; in the <guilabel>Artist:</guilabel> and
<guilabel>Title</guilabel> fields and a list of tracks with song
titles in the <interface>Tracks</interface> selection box. Otherwise,
you will see a list of tracks and play times without titles.</para>

<para>You can make an annotation for the entire disc with the
<guibutton>Comment</guibutton> button under the
<guilabel>Title</guilabel> field, or for a selected track in the
<guilabel>Tracks</guilabel> selection box with the adjacent
<guibutton>Comment</guibutton> button. If you select a track in the
<guilabel>Tracks</guilabel> selection box, the title, if present, will
appear in the <guilabel>Title</guilabel> field below. You can type a
title for the track in the box, or edit the entry to suit your
needs. Press the <keycap>Return</keycap> key on your keyboard, and the
text will appear in the proper line in the selection box.</para>

<para>Once all tracks have been given titles and the
<guilabel>Artist:</guilabel> and <guilabel>Title</guilabel> fields have
been filled out, you can press the <guibutton>Upload</guibutton>
button to send your submission by e-mail to freedb.</para>

<para>You will be prompted to select a category for the
submission. The <guilabel>Disc ID</guilabel> section displays the 32
bit <acronym>ID</acronym> code used by freedb to identify a compact
disc. Above the <acronym>ID</acronym> code is the category of the
<guilabel>freedb</guilabel> entry. These categories correspond to the
subfolders tree of the folder chosen in the <guilabel>freedb
Base Folder:</guilabel> in the <link
linkend="freedb-tab"><guilabel>freedb</guilabel> tab</link> of the &kscd;
Configuration window.</para>

<para>The <guilabel>Total Time:</guilabel> display shows the total play time of
the &CD;.</para>

<para>Press the <guibutton>Fetch Info</guibutton> button to download 
<acronym>CDDB</acronym> data.
Press the <guibutton>OK</guibutton> button to save your changes locally.
The <guibutton>Cancel</guibutton> button closes the &CD;
Database Editor without saving.</para>

</chapter>

<chapter id="using-kscd-in-the-panel">
<title>Using &kscd; in the &kde; Panel</title>

<screenshot>
<screeninfo>Using &kscd; in the &kde; Panel</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd18.png" format="PNG"/></imageobject>
<textobject><phrase>Using &kscd; in the &kde; Panel</phrase></textobject>
</mediaobject>
</screenshot>

<para>When the <guilabel>Enable KPanel Docking</guilabel> box is checked, a
small &kscd; applet is also displayed in the <application>KDE
panel</application>. Unlike the main &kscd; window, this applet is available on
any desktop. <mousebutton>Right</mousebutton> click on the applet to pop up a
menu to control &CD; playback. A <mousebutton>left</mousebutton> click on the
applet hides the main &kscd; window. If the main window is hidden, a second
<mousebutton>left</mousebutton> click on the applet restores it. </para>

<note><para>To be precise, the applet is displayed in the <application>system
tray</application> in the panel. If no applet appears when &kscd; is minimized,
you may have removed the tray. To add it, <mousebutton>right</mousebutton> click
on an empty spot on the panel and select <menuchoice><guisubmenu>Add</guisubmenu>
<guisubmenu>Applet</guisubmenu> <guimenuitem>System Tray</guimenuitem>
</menuchoice></para></note>

</chapter>

<chapter id="cddb-support">
<title><acronym>CDDB</acronym> Support</title>

<para>freedb is a distributed network database accessible
over the Internet that contains information about most audio &CD;s in
circulation. If you have Internet access, you will likely never have to manually
enter track information for your &CD;s if you have this set up properly. See
<link linkend="freedb-tab">The freedb Tab</link> subsection in the configuring
&kscd; chapter for detailed instructions on how to configure this service, and
the <link linkend="cddb-editor">The CD Database Editor</link> section for
instructions on how to edit <acronym>CDDB</acronym> entries.</para>

<para>Use of the <acronym>CDDB</acronym> is free. Submissions from users are
encouraged.</para>

<para>When preparing entries for the <acronym>CDDB</acronym>, please keep the
following points in mind:</para>

<itemizedlist>
<listitem><para>Use <quote>standard</quote> latin characters in the entries. Some
special characters are supported, but Cyrillic or Greek alphabet submissions,
for example, cannot be accepted.</para></listitem>
<listitem><para>Use only one <keysym>/</keysym> character in the
<guilabel>Disc Artist / Title</guilabel> field in the &CD; Database
Editor.</para>

<para>For classical &CD;s, it is standard practice to put the composer's name in
the Artist section (before the slash) and the performer's name in the Title
section (after the slash).</para></listitem> 
<listitem><para>If you send an entry that already exists in the database, any
additional information you provide may be added to the existing entry.</para>
</listitem>
</itemizedlist>

<para>By default, &kscd; installs the standard <acronym>CDDB</acronym>
categories in <filename class="directory">$KDEDIR/share/apps/kscd/cddb</filename>. You can create as
many category subfolders as you like. However, when uploading, only the
official <acronym>CDDB</acronym> categories are displayed. The default upload
address is <email>freedb-submit@freedb.org</email>. For more information about
<abbrev>freedb</abbrev> visit the <abbrev>freedb</abbrev> homepage.</para>

<para>The local <acronym>CDDB</acronym> entry for a particular &CD; is stored in
the file <filename><replaceable>category name</replaceable>/<replaceable>disc
ID</replaceable></filename> under the <acronym>CDDB</acronym> Base
Folder. These files can be edited with any text editor if you have nothing
better to do with your spare time.</para>

</chapter>

<chapter id="questions-and-answers">
<title>Questions and answers</title>

<qandaset>
<qandaentry>
<question><para>I see this dialog when I start &kscd;.  What's wrong?</para>
<screenshot>
<screeninfo>Error dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd19.png" format ="PNG"/></imageobject>
<textobject><phrase>Error dialog</phrase></textobject>
</mediaobject>
</screenshot>
</question>
<answer><para>This means that &kscd; couldn't open your &CD-ROM; drive. The name of
the device in the <guilabel>&CD-ROM; Device</guilabel>cdrom field of the
<guilabel>Kscd Configuration</guilabel> must actually refer to the block device
associated with your &CD-ROM; drive. This will often be a hardlink to the
appropriate <acronym>IDE</acronym> (<filename>/dev/hdx</filename>) or
<acronym>SCSI</acronym> (<filename>/dev/sdx</filename>) device.</para>

<para> The device file normally belongs to user root in group root, and does not
allow normal users to open it for reading, writing, or execution directly. This
has <emphasis>nothing</emphasis> to do with the <application>SUID</application>
(Set User <acronym>ID</acronym> programs use the <function>setuid()</function>
function in the standard Un*x library to assume the identity of another user)
<command>mount</command> command, which has no problems with permissions; &kscd;
must be able to get a read-only file descriptor referring to the &CD; device to
control the &CD-ROM; drive and read raw data off the disk.</para>

<para> If you have the root password, you can fix this quickly and easily.
Become root and type <userinput><command>chmod</command> <option>a+r</option>
<filename><replaceable>/dev/cdrom</replaceable></filename></userinput> to allow
any user on your system to read from <filename>/dev/cdrom</filename>.  If your
&CD-ROM; device is called something else, change the permissions on that device
with the same procedure. If you don't have the root password, ask your system
administrator nicely to give you read permission for the &CD-ROM; device.</para>

<para>See also the chapter on <link linkend="configuring-kscd">configuring KSCD
</link></para></answer>
</qandaentry>

<qandaentry> 
<question><para>I can't get the <acronym>CDDB</acronym> to work. Can I get any
detailed information about what may be going wrong?</para></question> 
<answer><para>If you experience trouble with the <acronym>CDDB</acronym>
functionality try to starting &kscd; from the command line with the
<option>-d</option> switch and observe the debug output.</para></answer> 
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits-and-license">
<title>Credits and licenses</title>

<para>&kscd; Copyright 1997,1998 Bernd Johannes Wuebben
<email>wuebben@kde.org</email>wuebben></para>

<para>&kscd; contains code from: </para>
<itemizedlist>
<listitem><para><application>workman</application> 1.4 beta 3 Copyright (c)
Steven Grimm <email>koreth@hyperion.com</email></para></listitem>
</itemizedlist>

<para>Special thanks to Ti Kan and Steve Scherf, the inventors of the
<acronym>CDDB</acronym> database concept. Visit <ulink
url="http://www.cddb.com/">http://ww.cddb.com</ulink> for more information on
<acronym>CDDB</acronym>.</para>

<para>A very special thank you also to David White who wrote the original &kscd;
help documention. Great Job David!</para>

<para>Documentation updated for KDE 2.0, and copyright by Jonathan Singer
<email>jsinger@leeta.net.</email></para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="how-to-obtain-kscd">
<title>How to obtain &kscd;</title>

&install.intro.documentation;

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile &kscd;, you need the latest versions of
the KDE libraries as well as the &Qt; C++ library.  All required libraries as
well as &kscd; itself can be found at the &kde; &FTP; site, <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>.</para>

</sect1> 

<sect1 id="compilation-and-installation"> 
<title>Compilation and Installation</title> 

&install.compile.documentation;
	
<para>Please inform the current maintainer, Dirk Foersterling, at
<email>milliByte@gmlx.net</email> of any modification you had to undertake in
order to get &kscd; to compile on your platform.</para>

</sect1>

</appendix>

&documentation.index; 
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
