<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY app "<application>streamtuner</application>">
  <!ENTITY appversion "0.99.99">
  <!ENTITY manrevision "2.8">
  <!ENTITY date "Tuesday, December 21, 2004">

  <!ENTITY project "The streamtuner Project">

  <!ENTITY documentation-license SYSTEM "documentation-license.xml">

  <!ENTITY software-copyright-holder "Jean-Yves Lefort">
  <!ENTITY software-copyright-date "2002, 2003, 2004">
  <!ENTITY software-license SYSTEM "software-license.xml">

  <!ENTITY handler "<link linkend=&#34;directory-handler&#34;>directory handler</link>">
  <!ENTITY handlers "<link linkend=&#34;directory-handler&#34;>directory handlers</link>">
  <!ENTITY Handlers "<link linkend=&#34;directory-handler&#34;>Directory handlers</link>">
  <!ENTITY libcurl "<link linkend=&#34;libcurl&#34;>libcurl</link>">
  <!ENTITY session "<link linkend=&#34;session&#34;>session</link>">
  <!ENTITY uri "<link linkend=&#34;uri&#34;>URI</link>">
  <!ENTITY gtk "<ulink url=&#34;http://www.gtk.org&#34; type=&#34;http&#34;>GTK+</ulink>">
  <!ENTITY python "<ulink url=&#34;http://www.python.org&#34; type=&#34;http&#34;>Python</ulink>">
  <!ENTITY basic.ch "<ulink url=&#34;http://www.basic.ch&#34; type=&#34;http&#34;>basic.ch</ulink>">
  <!ENTITY shoutcast "<ulink url=&#34;http://www.shoutcast.com&#34; type=&#34;http&#34;>SHOUTcast</ulink>">
  <!ENTITY shoutcast-yp "<ulink url=&#34;http://www.shoutcast.com&#34; type=&#34;http&#34;>SHOUTcast Yellow Pages</ulink>">
  <!ENTITY live365 "<ulink url=&#34;http://www.live365.com&#34; type=&#34;http&#34;>Live365</ulink>">
  <!ENTITY xiph "<ulink url=&#34;http://dir.xiph.org&#34; type=&#34;http&#34;>Xiph.org</ulink> (<acronym>aka</acronym> icecast.org, <acronym>aka</acronym> Oddsock)">
]>

<!-- $Id: streamtuner.xml,v 1.44.2.43 2004/12/21 15:08:09 jylefort Exp $ -->
<!-- streamtuner Manual -->

<!-- Copyright (c) 2004 Jean-Yves Lefort -->
<!-- All rights reserved. -->

<!-- Redistribution and use in source (SGML DocBook) and 'compiled' -->
<!-- forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or -->
<!-- without modification, are permitted provided that the following -->
<!-- conditions are met: -->
<!-- 1. Redistributions of source code (SGML DocBook) must -->
<!--    retain the above copyright notice, this list of conditions and -->
<!--    the following disclaimer as the first lines of this file -->
<!--    unmodified. -->
<!-- 2. Redistributions in compiled form (transformed to other -->
<!--    DTDs, converted to PDF, PostScript, RTF and other formats) -->
<!--    must reproduce the above copyright notice, this list of -->
<!--    conditions and the following disclaimer in the documentation -->
<!--    and/or other materials provided with the distribution. -->

<!-- THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND -->
<!-- CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, -->
<!-- INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -->
<!-- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -->
<!-- DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS -->
<!-- BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -->
<!-- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED -->
<!-- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -->
<!-- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -->
<!-- ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -->
<!-- TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF -->
<!-- THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY -->
<!-- OF SUCH DAMAGE. -->

<!-- This document does its best to adhere to the -->
<!-- GNOME Documentation Style Guide V1.3 -->
<!-- (http://developer.gnome.org/documents/style-guide) -->

<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo>
    <title>&app; Manual V&manrevision;</title>

    <copyright>
      <year>2004</year>
      <holder>Jean-Yves Lefort</holder>
    </copyright>
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
    <publisher>
      <publishername>&project;</publishername>
    </publisher>

    &documentation-license;

    <authorgroup>
      <author>
	<firstname>Jean-Yves</firstname>
	<surname>Lefort</surname>
	<affiliation>
	  <orgname>&project;</orgname>
	  <address><email>jylefort@brutele.be</email></address>
	</affiliation>
      </author>
      
<!-- This is appropriate place for other contributors: translators,
     maintainers,  etc. Commented out by default.
     
      <othercredit role="translator">
		<firstname>Latin</firstname> 
		<surname>Translator 1</surname> 
		<affiliation> 
	  		<orgname>Latin Translation Team</orgname> 
	  		<address> <email>translator@gnome.org</email> </address> 
		</affiliation>
		<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>

<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->  
    <revhistory>
      <revision>
	<revnumber>streamtuner Manual V&manrevision;</revnumber>
	<date>&date;</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.7</revnumber>
	<date>Saturday, October 23, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.6</revnumber>
	<date>Monday, August 9, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.5</revnumber>
	<date>Monday, July 26, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.4</revnumber>
	<date>Tuesday, May 11, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.3</revnumber>
	<date>Tuesday, May 11, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.2</revnumber>
	<date>Wednesday, March 31, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.1</revnumber>
	<date>Tuesday, March 30, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>streamtuner Manual V2.0</revnumber>
	<date>Tuesday, March 30, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
    </revhistory>

    <releaseinfo>
      This manual describes version &appversion; of streamtuner.
    </releaseinfo>
    <legalnotice>
      <title>Feedback</title>
      <para>To report a bug or make a suggestion regarding the &app;
	application or this manual, follow the directions in
	<xref linkend="problem-reports" />.
      </para>
      <!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo>

  <indexterm zone="index">
    <primary>streamtuner</primary>
  </indexterm>

  <sect1 id="introduction">
    <title>Introduction</title>
    <para>
      &app; is a stream directory browser. Through the use of a plugin
      system, it offers an intuitive &gtk; interface to Internet radio
      directories such as &shoutcast; and &live365;.
    </para>
    <para>
      With &app;, you can:
    </para>
    <itemizedlist>
      <listitem><para>
	  Browse the &shoutcast-yp;
	</para></listitem>
      <listitem><para>
	  Browse the &live365; directory
	</para></listitem>
      <listitem><para>
	  Browse the &xiph; directory
	</para></listitem>
      <listitem><para>
	  Browse the &basic.ch; DJ mixes
	</para></listitem>
      <listitem><para>
	  Manage your local music collection, with full support for
	  ID3 and Vorbis metadata editing
	</para></listitem>
      <listitem><para>
	  Listen to streams, browse their web page, or record them
	  using programs such as <ulink url="http://streamripper.sourceforge.net" type="http">Streamripper</ulink>
	</para></listitem>
      <listitem><para>
	  Implement new &handlers; as tiny &python; scripts or as
	  dynamically loadable modules written in C
	</para></listitem>
      <listitem><para>
	  Retain your favourite streams by bookmarking them
	</para></listitem>
      <listitem><para>
	  Manually add streams to your collection
	</para></listitem>
    </itemizedlist>
    <para>
      &app; offers hundreds of thousands of music resources in a fast
      and clean common interface.
    </para>

    <sect2 id="terminology">
      <title>Terminology Side Note</title>
      <para>
	Throughout &app; and this manual, media resources are referred
	to as <guilabel>streams</guilabel>.
      </para>
      <para>
	However, because of the extensible nature of &app;, they
	really can be anything: an Internet audio stream, a MP3 or Ogg
	song, a web page, or even a television channel!
      </para>
    </sect2>
  </sect1>

  <sect1 id="getting-started">
    <title>Getting Started</title>

    <sect2 id="to-start">
    <title>To Start &app;</title>
      <para>
	You can start <application>&app;</application> in the
	following ways:
      </para>
      <variablelist>
    	<varlistentry>
	  <term><guimenu>Applications</guimenu> menu</term>
	  <listitem>
	    <para>Choose
	      <menuchoice>
    		<guisubmenu>Multimedia</guisubmenu>
    		<guimenuitem>&app;</guimenuitem>
	      </menuchoice>.</para>
	  </listitem>
    	</varlistentry>

    	<varlistentry>
	  <term>Command line</term>
	  <listitem>
	    <para>
	      To start <application>&app;</application> from a command
	      line, type the following command, then press
	      <keycap>Return</keycap>:
	    </para>
	    <para>
	      <command>streamtuner</command>
	      <replaceable>options</replaceable>
	    </para>
	    <para>
	      where <replaceable>options</replaceable> is one or more options
	      from the following list:
	    </para>
	    <variablelist>
	      <varlistentry>
		<term>--help</term>
		<listitem><para>Show help and exit</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>--version</term>
		<listitem><para>Show version information and exit</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>--directory <replaceable>directory</replaceable></term>
		<listitem><para>
		    Use configuration directory <replaceable>directory</replaceable>
		    instead of the default <filename class="directory">~/.streamtuner</filename>
		  </para></listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
    	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="when-start">
      <title>When You Start &app;</title>
      <para>
	When you start <application>&app;</application>, a window
	similar to the following one is displayed.
      </para>

      <figure id="main-window-fig">
	<title>&app; Main Window</title>
	<screenshot>
	  <mediaobject> 
	    <imageobject>
	      <imagedata fileref="figures/main-window.png" format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>
		Shows &app; main window. Contains titlebar, menubar,
		toolbar, tabbed notebook and statusbar. Menubar
		contains
		<guimenu>Stream</guimenu>,
		<guimenu>Edit</guimenu>,
		<guimenu>View</guimenu>,
		<guimenu>Directories</guimenu>,
		and <guimenu>Help</guimenu> menus.
	      </phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </figure>

      <para>A few remarks:</para>
      <itemizedlist>
	<listitem><para>
	    &Handlers; can be reordered by dragging their tab label.
	  </para></listitem>
	<listitem><para>
	    Right-clicking on the tab label of a &handler; will popup
	    a menu presenting a couple of actions specific to that
	    &handler;.
	  </para></listitem>
	<listitem><para>
	    Right-clicking on a stream column header will popup a menu
	    allowing to hide the column or to show all columns.
	  </para></listitem>
	<listitem><para>
	    Right-clicking on a stream will popup a menu mostly
	    similar to the <guimenu>Stream</guimenu> menu.
	  </para></listitem>
      </itemizedlist>

      <tip>
	<title>&gtk; Tips</title>
	<para>
	  Double-click on a column separator to autosize the column.
	</para>
	<para>
	  Drag a column header to move the column.
	</para>
	<para>
	  Press
	  <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
	  in a list to trigger the interactive search feature.
	</para>
      </tip>
    </sect2>
  </sect1>

  <sect1 id="usage"> 
    <title>Usage</title> 
    <para>You can use &app; to perform the following tasks: 
      <itemizedlist> 
	<listitem> 
	  <para><link linkend="browse">Browse a Stream Directory</link></para>
	</listitem> 
	<listitem> 
	  <para><link linkend="search">Search for Streams</link></para>
	</listitem> 
	<listitem> 
	  <para><link linkend="stream-tune-in">Tune Into Streams</link></para>
	</listitem> 
	<listitem> 
	  <para><link linkend="stream-record">Record a Stream</link></para> 
	</listitem> 
	<listitem> 
	  <para><link linkend="stream-browse">Browse the Web Page of a Stream</link></para> 
	</listitem>
	<listitem> 
	  <para><link linkend="stream-edit">Edit a Stream</link></para> 
	</listitem>
	<listitem> 
	  <para><link linkend="stream-delete">Delete Streams</link></para> 
	</listitem>
	<listitem> 
	  <para><link linkend="add-bookmarks">Add Bookmarks</link></para> 
	</listitem>
	<listitem> 
	  <para><link linkend="new-preselection">Create a Preselection</link></para> 
	</listitem>
      </itemizedlist>
    </para>

    <sect2 id="browse">
      <title>To Browse a Stream Directory</title>
      <para>
	To browse a stream directory, click on its tab and start
	navigating categories by selecting them.
      </para>
      <para>
	Categories will be kept in the internal &app; cache and loaded
	from the network only if necessary, unless
	<link linkend="always-reload">Always reload categories</link>
	is enabled.
      </para>
      <para>
	The number of available &handlers; depends on the loaded
	<link linkend="plugins">plugins</link>.
      </para>
    </sect2>

    <sect2 id="search">
      <title>To Search for Streams</title>
      <para>
	To search for streams in the current category, choose
	<menuchoice>
	  <guimenu>Edit</guimenu>
	  <guimenuitem>Find</guimenuitem>
	</menuchoice>.
	<tip>
	  <para>
	    Alternatively, you may use the &gtk; interactive search feature
	    by pressing <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
	    in a list.
	  </para>
	</tip>
      </para>
      <para>
	To search for streams in all categories, choose
	<menuchoice>
	  <guimenu>Edit</guimenu>
	  <guimenuitem>Search in All Categories</guimenuitem>
	</menuchoice>.
	<note>
	  <para>
	    Not all &handlers; support this feature.
	  </para>
	</note>
      </para>
    </sect2>
	
    <sect2 id="stream-tune-in"> 
      <title>To Tune Into Streams</title> 
      <para>To tune into streams, select them<footnoteref linkend="tune-in-multiple"/>
	and choose
	<menuchoice> 
	  <guimenu>Stream</guimenu> 
	  <guimenuitem>Tune in</guimenuitem> 
	</menuchoice> (or press <keycap>Return</keycap>).
	You may also use the <guibutton>Tune in</guibutton> toolbar
	button, or the stream context menu (which can be accessed by
	right-clicking on a stream).
	<footnote id="tune-in-multiple">
	  <para>
	    Some &handlers; can only tune into one stream at a time.
	  </para>
	</footnote>
      </para>
      <important>
	<title>Properly Configuring Applications</title>
	<para>
	  <!-- FIXME -->
	  You need to properly configure the applications needed to
	  tune into streams. It can be done from the
	  <link linkend="preferences-applications">Applications</link>
	  tabbed section of the <guilabel>Preferences</guilabel>
	  dialog.
	</para>
      </important>
    </sect2> 

    <sect2 id="stream-record"> 
      <title>To Record a Stream</title> 
      <para>To record a stream, select it and choose
	<menuchoice> 
	  <guimenu>Stream</guimenu> 
	  <guimenuitem>Record</guimenuitem> 
	</menuchoice>.
	You may also use the <guibutton>Record</guibutton> toolbar
	button, or the stream context menu (which can be accessed by
	right-clicking on a stream).
      </para>
      <important>
	<title>Properly Configuring Applications</title>
	<para>
	  <!-- FIXME -->
	  You need to properly configure the applications needed to
	  record streams. It can be done from the
	  <link linkend="preferences-applications">Applications</link>
	  tabbed section of the <guilabel>Preferences</guilabel>
	  dialog.
	</para>
      </important>
    </sect2> 

    <sect2 id="stream-browse"> 
      <title>To Browse the Web Page of a Stream</title> 
      <para>To browse the web page of a stream, select it and choose
	<menuchoice> 
	  <guimenu>Stream</guimenu> 
	  <guimenuitem>Browse</guimenuitem> 
	</menuchoice> (or, if the &handler; has no tune in feature,
	press <keycap>Return</keycap>).
	You may also use the <guibutton>Browse</guibutton> toolbar
	button, or the stream context menu (which can be accessed by
	right-clicking on a stream).
      </para>
      <important>
	<title>Properly Configuring Applications</title>
	<para>
	  <!-- FIXME -->
	  You need to properly configure the applications needed to
	  browse streams. It can be done from the
	  <link linkend="preferences-applications">Applications</link>
	  tabbed section of the <guilabel>Preferences</guilabel>
	  dialog.
	</para>
      </important>
    </sect2> 

    <sect2 id="stream-edit"> 
      <title>To Edit a Stream</title>
      <para>To edit a stream, select it and choose
	<menuchoice>
	  <guimenu>Stream</guimenu>
	  <guimenuitem>Properties</guimenuitem>
	</menuchoice>.
	You may also use the stream context menu (which can be
	accessed by right-clicking on a stream).
      </para>
      <para>
	You will be presented with the <guilabel>Stream Properties</guilabel> dialog
	displaying the fields of the stream.
      </para>
      <note>
	<para>
	  A field is editable only when it makes sense to do so. For
	  example, you cannot edit SHOUTcast streams, since they are
	  dynamic data loaded from the network.
	</para>
      </note>
    </sect2>

    <sect2 id="stream-delete">
      <title>To Delete Streams</title>
      <para>To delete streams, select them and choose
	<menuchoice>
	  <guimenu>Stream</guimenu>
	  <guimenuitem>Delete</guimenuitem>
	</menuchoice>.
	You may also use the stream context menu (which can be
	accessed by right-clicking on a stream).
      </para>
      <note>
	<para>
	  If the &handler; requests it, you will be presented with a
	  confirmation dialog.
	</para>
	<para>
	  Benign actions such as deleting bookmarks or preselections
	  will not require confirmation.
	</para>
      </note>
    </sect2>

    <sect2 id="add-bookmarks">
      <title>To Add Bookmarks</title>
      <para>To add bookmarks, select one or more streams and choose
	<menuchoice>
	  <guimenu>Stream</guimenu>
	  <guimenuitem>Add Bookmark</guimenuitem>
	</menuchoice>.
	You may also use the stream context menu (which can be
	accessed by right-clicking on a stream).
      </para>
      <para>
	The added bookmarks will show up in the
	<guilabel>Bookmarks</guilabel> tabbed section, and you will be
	able to edit their name, genre and description.
      </para>
    </sect2>

    <sect2 id="new-preselection">
      <title>To Create a Preselection</title>
      <para>To create a preselection, choose
	<menuchoice>
	  <guimenu>Stream</guimenu>
	  <guimenuitem>New Preselection</guimenuitem>
	</menuchoice>.
      </para>
      <para>
	You will be presented with the <guilabel>Stream Properties</guilabel>
	dialog, allowing you to edit the fields of the new preselection.
      </para>
      <para>
	The <guilabel>Homepage</guilabel> field will be used to browse
	the preselection, and the <guilabel>URL</guilabel> field will
	be used to tune into the preselection.
      </para>
    </sect2>
  </sect1>

  <sect1 id="plugins">
    <title>Plugins</title>
    <para>
      &app; uses a plugin system to handle different stream
      directories, and ships with several plugins.
    </para>

    <sect2>
      <title>SHOUTcast</title>
      <para>
	This plugin provides an interface to the &shoutcast-yp;.
      </para>
      <!-- FIXME: you can configure blah blah -->
    </sect2>

    <sect2>
      <title>Live365</title>
      <para>
	This plugin adds &live365; support to &app;.
      </para>
      <!-- FIXME: you can configure blah blah -->
    </sect2>

    <sect2>
      <title>Xiph</title>
      <para>
	This plugin adds &xiph; support to &app;.
      </para>
    </sect2>

    <sect2 id="plugin-local">
      <title>Local</title>
      <para>
	This plugin provides an interface to your local music
	collection. It can edit ID3 and Vorbis metadata.
      </para>
      <para>
	Use the <link linkend="music-folder">Music folder</link> option to
	set the path to your music collection.
      </para>
    </sect2>

    <sect2>
      <title>Python</title>
      <para>
	This plugin provides an embedded &python; interpreter,
	allowing to write &handlers; with the &python; programming
	language.
      </para>
      <para>
	Three example scripts are shipped with the plugin:
      </para>
      <itemizedlist>
	<listitem><para>basic.ch.py, providing a &basic.ch; &handler;</para></listitem>
	<listitem><para>google-stations.py, providing a <ulink url="http://directory.google.com/Top/Arts/Music/Sound_Files/MP3/Streaming/Stations" type="http">Google Stations</ulink> &handler;</para></listitem>
	<listitem><para>punkcast.com.py, providing a <ulink url="http://punkcast.com" type="http">punkcast.com</ulink> &handler;</para></listitem> <!-- FIXME: you can configure blah blah -->
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="preferences"> 
    <title>Preferences</title> 
    <para>To configure &app;, choose
      <menuchoice> 
	<guimenu>Edit</guimenu> 
	<guimenuitem>Preferences</guimenuitem> 
      </menuchoice>. The
      <guilabel>Preferences</guilabel> dialog contains the following
      pages:
    </para>
    <itemizedlist>
      <listitem>
	<para><link linkend="preferences-applications">Applications</link></para>
      </listitem>
      <listitem>
	<para><link linkend="preferences-general">General</link></para>
      </listitem>
      <listitem>
	<para><link linkend="preferences-network">Network</link></para>
      </listitem>
      <listitem>
	<para><link linkend="preferences-plugins">Plugins</link></para>
	<itemizedlist>
	  <listitem>
	    <para><link linkend="preferences-live365">Live365</link></para>
	  </listitem>
	  <listitem>
	    <para><link linkend="preferences-shoutcast">SHOUTcast</link></para>
	  </listitem>
	  <listitem>
	    <para><link linkend="preferences-punkcast">punkcast.com</link></para>
	  </listitem>
	</itemizedlist>
      </listitem>
    </itemizedlist>

    <sect2 id="preferences-applications"> 
      <title>Applications</title> 
      <para>
	These commands will be used to perform various actions.
      </para>
      <para>
	The following percent substitutions will be applied:
	<variablelist>
	  <varlistentry>
	    <term>%u</term>
	    <listitem><para>Replaced by the &uri; to be acted upon</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>%q</term>
	    <listitem><para>Replaced by the quoted &uri; to be acted upon</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>%%</term>
	    <listitem><para>Replaced by a single percent character</para></listitem>
	  </varlistentry>
	</variablelist>
      </para>
      <note>
	<para>
	  Commands will not be run in a shell, so meta-characters and
	  other shell specific features such as redirections will not
	  be available.
	</para>
      </note>
    </sect2> 

    <sect2 id="preferences-general"> 
      <title>General</title> 
      <variablelist>
	<varlistentry>
	  <term><guilabel>Show splash screen at startup</guilabel></term>
	  <listitem>
	    <para>
	      If this option is enabled, a splash screen will be shown when
	      starting &app;.
	      <tip>
		<para>
		  On a fast system, keeping this option enabled is
		  probably useless.
		</para>
	      </tip>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="always-reload">
	  <term><guilabel>Always reload categories</guilabel></term>
	  <listitem>
	    <para>
	      If this option is enabled, categories will be
	      unconditionally reloaded when you select them.
	      Otherwise, they will be looked up in the internal cache,
	      reloading them only if needed.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="music-folder">
	  <term><guilabel>Music folder:</guilabel></term>
	  <listitem>
	    <para>
	      Use this option to set the path to your music collection
	      (used by the <link linkend="plugin-local">Local</link>
	      plugin).
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="preferences-network">
      <title>Network</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>Use a proxy</guilabel></term>
	  <listitem>
	    <para>
	      If this option is enabled and the
	      <guilabel>Server</guilabel> field is filled, &app; will
	      use a proxy server for data transfers.
	    </para>
	    <para>
	      Otherwise, &libcurl; will use a proxy server if
	      environment variables such as <envar>http_proxy</envar>,
	      <envar>ftp_proxy</envar> or <envar>all_proxy</envar> are
	      set.
	    </para>

	    <variablelist>
	      <varlistentry>
		<term><guilabel>Type</guilabel></term>
		<listitem>
		  <para>
		    This option specifies the type of the proxy server
		    to use.
		  </para>
		  <note>
		    <title>Socks 5 Support</title>
		    <para>
		      Some versions of &libcurl; are known to have
		      problems with Socks 5 proxies.
		    </para>
		  </note>
		</listitem>
	      </varlistentry>
		
	      <varlistentry>
		<term><guilabel>Server</guilabel></term>
		<listitem>
		  <para>
		    This field must contain the hostname or IP address
		    of the proxy server to use.
		  </para>
		</listitem>
	      </varlistentry>
		
	      <varlistentry>
		<term><guilabel>Port</guilabel></term>
		<listitem>
		  <para>
		    This field must contain the port number of the
		    proxy server to use.
		  </para>
		  <tip>
		    <title>Standard Port Numbers</title>
		    <para>
		      HTTP proxies commonly listen on port 8080 or 3120.
		    </para>
		    <para>
		      Socks 5 proxies commonly listen on port 1080.
		    </para>
		  </tip>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><guilabel>Use proxy authentication</guilabel></term>
		<listitem>
		  <para>
		    You should enable this option if your proxy server requires
		    user authentication.
		  </para>

		  <variablelist>
		    <varlistentry>
		      <term><guilabel>Name</guilabel></term>
		      <listitem>
			<para>
			  This field must contain your proxy login name.
			</para>
			<para>
			  If it is left blank, you will be prompted
			  for your login name when needed.
			</para>
		      </listitem>
		    </varlistentry>
		    <varlistentry>
		      <term><guilabel>Password</guilabel></term>
		      <listitem>
			<para>
			  This field must contain your proxy password.
			</para>
			<para>
			  If it is left blank, you will be prompted
			  for your password when needed.
			</para>
			<warning>
			  <para>
			    If the field is filled, the password will be
			    stored in clear text in the <filename>~/.streamtuner/config</filename>
			    file.
			  </para>
			</warning>
		      </listitem>
		    </varlistentry>
		  </variablelist>

		</listitem>
	      </varlistentry>

	    </variablelist>

	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="preferences-plugins">
      <title>Plugins</title>
      <para>
	This page displays the list of plugins found at startup, and
	allows you to disable the plugins you do not need.
      </para>

      <sect3 id="preferences-live365">
	<title>Live365</title>
	<variablelist>
	  <varlistentry>
	    <term><guilabel>Streams Limit</guilabel></term>
	    <listitem>
	      <para>
		You can choose to limit the number of streams to
		download per category by enabling the
		<guilabel>Load at most</guilabel> option.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guilabel>Membership</guilabel></term>
	    <listitem>
	      <para>
		If you are registered to &live365;, you might want to
		use your membership to tune into streams (some
		stations will only be available to paying members).
	      </para>
	      <para>
		You can use your membership by enabling the
		<guilabel>Use membership</guilabel> option and filling
		the <guilabel>Name</guilabel> and <guilabel>Password</guilabel> fields
		(if a field is left blank, you will be prompted for it
		when needed).
	      </para>
	      <warning>
		<para>
		  If the password field is filled, the password will
		  be stored in clear text in the
		  <filename>~/.streamtuner/config</filename> file.
		</para>
	      </warning>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>

      <sect3 id="preferences-shoutcast">
	<title>SHOUTcast</title>
	<variablelist>
	  <varlistentry>
	    <term><guilabel>Streams Limit</guilabel></term>
	    <listitem>
	      <para>
		You can choose to limit the number of streams to
		download per category by enabling the
		<guilabel>Load at most</guilabel> option.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>

      <sect3 id="preferences-punkcast">
	<title>punkcast.com</title>
	<variablelist>
	  <varlistentry>
	    <term><guilabel>Images</guilabel></term>
	    <listitem>
	      <para>
		You can choose to not download the show banners by disabling
		the <guilabel>Download images</guilabel> option.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="technical-information">
    <title>Technical Information</title>

    <sect2 id="configuration-files">
      <title>Configuration Files</title>
      <variablelist>
	<varlistentry>
	  <term><filename>~/.streamtuner/accels</filename></term>
	  <listitem><para>The &gtk; accelerators file</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><filename class="directory">~/.streamtuner/cache</filename></term>
	  <listitem><para>The cache directory</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><filename>~/.streamtuner/config</filename></term>
	  <listitem><para>The configuration file</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><filename>~/.streamtuner/disabled-plugins</filename></term>
	  <listitem><para>The list of disabled plugins</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><filename>~/.streamtuner/splash-disabled</filename></term>
	  <listitem><para>If this file exists, the splash screen will not be displayed.</para></listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2>
      <title>Search Paths</title>
      <para>
	Plugins will be looked up in
	<filename class="directory"><replaceable>LIBDIR</replaceable>/streamtuner/plugins</filename>,
	<filename class="directory">~/.streamtuner/plugins</filename>, and in
	the directories specified in the colon-separated environment variable
	<envar>STREAMTUNER_PLUGINS_PATH</envar> (in that order).
	Filenames not having the system-specific shared object
	extension (usually .so) will be ignored.
      </para>
      <para>
	&python; scripts will be looked up in
	<filename class="directory"><replaceable>LIBDIR</replaceable>/streamtuner/python/scripts</filename> and
	<filename class="directory">~/.streamtuner/python/scripts</filename> (in that order).
	Filenames not having the .py extension will be ignored.
      </para>
    </sect2>
	
    <sect2 id="source-quality">
      <title>Quality of Source Code</title>
      <para>
	&app; is extremely stable. The source code is
	production-quality, and special care has been taken to ensure
	that the plugins will never trust their input.
      </para>
    </sect2>
  </sect1>

  <sect1 id="about">
    <title>About &app;</title>
    <para> &app; was written by Jean-Yves Lefort
      (<email>jylefort@brutele.be</email>). To find more information about
      &app;, visit the
      <ulink url="http://www.nongnu.org/streamtuner" type="http">streamtuner web page</ulink>.
    </para>
    
    <sect2 id="problem-reports">
      <title>Reporting Bugs and Other Feedback</title>
      <itemizedlist>
	<listitem><para>
	    Bug reports should be sent to <email>streamtuner-bugs@nongnu.org</email>.
	  </para></listitem>
	<listitem><para>
	    Questions, patches and various feedback should be sent to <email>streamtuner-misc@nongnu.org</email>.
	  </para></listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="acknowledgements">
      <title>Acknowledgements</title>
      <para>
	The following people have contributed code, packages,
	translations, money or have helped to fix bugs:
      </para>
      <itemizedlist>
	<!-- We don't use <firstname> and <surname> because we can't -->
	<!-- unambiguously split some names. -->
	<listitem><para>Dan Allen</para></listitem>
	<listitem><para>Novák Áron</para></listitem>
	<listitem><para>Alban Bedel</para></listitem>
	<listitem><para>Wolfgang Meyer zu Bergsten</para></listitem>
	<listitem><para>Gonéri Le Bouder</para></listitem>
	<listitem><para>Elmar Hoffmann</para></listitem>
	<listitem><para>Ulrich Ivens</para></listitem>
	<listitem><para>Jose Jorge</para></listitem>
	<listitem><para>Rudolf Kastl</para></listitem>
	<listitem><para>Marc Lavallée</para></listitem>
	<listitem><para>Satoshi Machino</para></listitem>
	<listitem><para>Jeff Moe</para></listitem>
	<listitem><para>Adam Nevins</para></listitem>
	<listitem><para>Matthew Newton</para></listitem>
	<listitem><para>Andy Piper</para></listitem>
	<listitem><para>Marcus Rückert</para></listitem>
	<listitem><para>Kim Schulz</para></listitem>
	<listitem><para>Stephen Stackwick</para></listitem>
	<listitem><para>Martin Stromberger</para></listitem>
	<listitem><para>Philipp Thomas</para></listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="licensing-terms">
      <title>Licensing Terms</title>
      &software-license;
    </sect2>
  </sect1>

  <glossary id="glossary">
    <title>Glossary</title>
    <glossdiv><title>D</title>
      <glossentry id="directory-handler">
	<glossterm>directory handler</glossterm>
	<glossdef>
	  <para>
	    In &app; terminology, both the logic used to handle a
	    music resource provider (such as an online stream
	    directory or your local music collection), and the user
	    interface element representing it (a tabbed section in the
	    main notebook).
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>L</title>
      <glossentry id="libcurl">
	<glossterm>libcurl</glossterm>
	<glossdef>
	  <para>
	    A <quote>multiprotocol file transfer library</quote>
	    used by &app; for its data transfers.
	    More information can be found on the
	    <ulink url="http://curl.haxx.se/libcurl" type="http">libcurl web page</ulink>.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>S</title>
      <glossentry id="session">
	<glossterm>session</glossterm>
	<glossdef>
	  <para>
	    In &app; terminology, the application state (position,
	    visibility and dimensions of user interface elements,
	    preferences, contents of the cache, ...).
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>U</title>
      <glossentry>
	<glossterm>URI</glossterm>
	<glosssee otherterm="uri"/>
      </glossentry>

      <glossentry id="uri">
	<glossterm>Uniform Resource Identifier</glossterm>
	<acronym>URI</acronym>
	<glossdef>
	  <para>
	    A <quote>compact string of characters for identifying an
	      abtract or physical resource</quote>, as defined
	    by <ulink url="http://www.ietf.org/rfc/rfc2396.txt" type="http">RFC 2396</ulink>.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>
  </glossary>
</article>