Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

2 files changed, 490 insertions, 0 deletions

diff --git a/doc/noatun/Makefile.am b/doc/noatun/Makefile.am
new file mode 100644
index 00000000..171f575c
--- /dev/null
+++ b/doc/noatun/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
diff --git a/doc/noatun/index.docbook b/doc/noatun/index.docbook
new file mode 100644
index 00000000..7a6bd2b7
--- /dev/null
+++ b/doc/noatun/index.docbook
@@ -0,0 +1,488 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&noatun;">
+  <!ENTITY package "kdemultimedia">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+  <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &noatun; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Charles</firstname>
+<surname>Samuels</surname>
+<affiliation>
+<address><email>charles@kde.org</email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2001</year><year>2002</year>
+<holder>Charles Samuels</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2002-03-01</date>
+<releaseinfo>2.00.00</releaseinfo> <!-- Use App version here -->
+
+<abstract>
+<para>&noatun; is a fully-featured plugin-based media player for &kde;.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Noatun</keyword>
+<keyword>kdemultimedia</keyword>
+<keyword>mp3</keyword>
+<keyword>music</keyword>
+<keyword>media</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&noatun; is a fully-featured plugin-based media player for &kde;.</para>
+
+<sect1 id="features">
+<title>Features</title>
+
+<para>&noatun; is an elaborate front-end to &arts; &mdash; the Analog
+Real-Time Synthesizer.  To add additional playobjects, go to <ulink
+url="http://noatun.kde.org/plugins/">
+http://noatun.kde.org/plugins.phtml</ulink>, or <ulink
+url="http://mpeglib.sf.net">http://mpeglib.sf.net</ulink>.  By
+default &arts; supports MP3 and MPEG-1.  Vorbis is also supported if the Vorbis
+libraries were available during the compilation of &kde;.  </para>
+
+</sect1>
+</chapter>
+
+<chapter id="using-noatun">
+<title>Using &noatun;</title>
+
+<para>&noatun;, by  default, starts with the Excellent user interface
+plugin.  This plugin was chosen  as it bears the most similarity to
+other &kde; applications.</para>
+
+<para>&noatun; is unique in that no two installations are the same,
+and there is no standard interface, although there is a default
+one. You're free to mix-and-match your selection of plugins, and
+customize &noatun; until it is your ideal media player!
+</para>
+
+<sect1 id="title-format">
+<title>Title Format</title>
+<para>
+The &noatun; Preferences Window has an odd <guilabel>Title Format</guilabel> text box.  You can enter a format string to customize how titles appear.
+</para>
+
+<itemizedlist>
+<listitem><para>Any text appears normally, unless it is within a <literal>$( )</literal>.</para></listitem>
+<listitem><para>The text within <literal>$( )</literal> will read the &noatun; property
+for the given item, and replace the text with it.</para></listitem>
+<listitem><para>If, within the <literal>$( )</literal> are quotes, the text within the quotes
+will be displayed normally, but only if the property of the name exists.</para></listitem>
+<listitem><para>The quotes may be either at the beginning of the <literal>$( )</literal>, at the end of 
+it, or at both the end or the beginning</para></listitem>
+</itemizedlist>
+
+<para>
+	For example, <literal>$(bitrate)</literal> is replaced by the		bitrate of the file, as loaded
+	by the Metatag plugin.  However, if you insert quotes into that field,
+	the text within the quotes will be displayed:
+<literal>$(bitrate"kbps")</literal> for
+	example will display the bitrate of the file, followed by the characters 	<literal>&quot;kbps&quot;</literal>.  Neither will be displayed if the property <quote>bitrate</quote> does not exist.
+</para>	
+</sect1>
+
+</chapter>
+
+<chapter id="using-noatun-plugins">
+<title>Using &noatun; Plugins</title>
+
+<para>You can select different plugins by going to the
+<guimenuitem>Settings</guimenuitem> menu, and selecting
+<guimenuitem>Configure &noatun;...</guimenuitem>.  Move to the
+<guilabel>Plugins</guilabel> page by selecting the appropriate list item.
+Then you can enable enable plugins by selecting the checkbox near their name.
+&noatun; requires at least one User-Interface plugin, and requires exactly
+one Playlist plugin.
+</para>
+
+<sect1 id="milk-chocolate">
+<title>Milk Chocolate</title>
+
+<para>Milk Chocolate is a small, simple User Interface. The buttons
+behave mostly like a CD-player, and the <guiicon>eject</guiicon>
+button opens the playlist.  The <guiicon>sheet with a cross</guiicon>
+button removes the current playlist item, but does not delete the file
+from disk, and the <guiicon>arrow</guiicon> button sets the looping
+mode.  A menu is available by &RMB; clicking anywhere in the
+window.</para>
+
+</sect1>
+
+<sect1 id="young-hickory">
+
+<title>Young Hickory</title>
+
+<para>Young hickory is a plugin for the &kde; System Tray, the area near the
+clock, by default.</para>
+
+<para>&RMB; clicking on the icon will show a small menu, and &LMB; clicking
+will toggle the visibility of your &noatun; user-interface windows.  Note that
+playlists, for example, are not considered user-interfaces.</para>
+
+</sect1>
+
+<sect1 id="html-exporter">
+<title><acronym>HTML</acronym> Playlist Export</title>
+
+<para>This plugin will place your playlist in a nice
+<acronym>HTML</acronym> table.  Its preferences page will allow you to
+set colors, background image, and enable the Hover mode, for changing
+colors when the cursor is over a link.</para>
+
+<para>After setting options, the <guimenu>Actions</guimenu> menu's
+<guimenuitem>Export Playlist...</guimenuitem> will open a file dialog
+for you to select where to save the output. </para>
+
+</sect1>
+
+<sect1 id="kjofol-skin">
+<title><application>K-Jöfol</application> Skins</title>
+
+<para>The &noatun; <application>K-Jöfol</application> skin loader is a
+reimplementation of a &Windows; program under the same name.</para>
+
+<para>&noatun;'s implementation has a few limitations,
+unfortunately. For instance the skins must be uncompressed on disk in
+order to load them.</para>
+
+<para>To install a skin (in the &Windows; ZIP format) you can use
+the skin-installer that can be found in the preferences-dialog of
+&noatun;.</para>
+
+<para>Because some skins are not packaged correctly and the skin-installer
+can not guess everything you can still follow these commands if installation
+of a certain skin failed:</para>
+
+<screen><prompt>%</prompt> <userinput><command>cd</command> <filename class="directory">$KDEHOME/share/apps/noatun</filename></userinput>
+<prompt>%</prompt> <userinput><command>mkdir</command> <option>kjskins</option></userinput> (if needed)
+<prompt>%</prompt> <userinput><command>cd</command> <option>kjskins</option></userinput>
+<prompt>%</prompt> <userinput><command>mkdir</command> <option>new_skin</option> ; <command>cd</command> <replaceable>new_skin</replaceable></userinput>
+<prompt>%</prompt> <userinput><command>unzip</command> <replaceable>/path/to/new_skin.zip</replaceable></userinput></screen>
+
+<para>You can also make your own skins with the tutorial at <ulink
+url="http://www.angelfire.com/mo/nequiem/tutorial.html">http://www.angelfire.com/mo/nequiem/tutorial.html</ulink>.
+</para>
+
+</sect1>
+
+<sect1 id="splitplaylist">
+<title>The Split Playlist</title>
+
+<para> The Split Playlist had a simple, classic-style design.  Double
+clicking on an entry will play it (as will selecting it and pressing
+<keycap>Enter</keycap>).  You can drag files and
+&URL;s in as well.  </para>
+
+<para>
+As of &kde; 3.0, the Split Playlist (<acronym>SPL</acronym>) stores its
+data in an &XML; format, but will automatically
+import the <acronym>m3u</acronym> list if the &XML; file
+does not exist.  This means that you can write to the m3u file, and delete
+the &XML; file, to automatically generate playlists.
+</para>
+
+<para>
+The name Split Playlist is a bit of a misnomer, as the list is not actually split.
+It results from the original design (back in the early &noatun; days) actually
+having it split.
+</para>
+</sect1>
+
+<sect1 id="winampskin">
+<title>Winamp Skins</title>
+<para>
+If you're actually using the <trademark>Winamp</trademark> skin,
+it should seem familiar to you.  Clicking on the timer will
+toggle it between count-down and count-up mode.  Selecting
+the Scope region under it will enable and disable the scope.  You
+can also double click on the titlebar to toggle Windowshade mode.
+<mousebutton>Right</mousebutton> clicking (or clicking on the top-left icon will show the
+standard &noatun; toolbar.
+</para>
+<para>
+You can install new skins by, in 
+<filename class="directory">$KDEHOME/share/apps/noatun/skins/winamp</filename>,
+creating a folder for them, and then unzipping the skin in there.  <trademark>Winamp</trademark>
+skin files with the extension <literal role="extension">.wsz</literal> can be treated
+as normal zip files.  You may have to rename them first, however, to be
+able to unzip them.
+</para>
+</sect1>
+
+<sect1 id="metatag">
+<title>Metatag</title>
+<para>
+Metatag is a plugin that loads information about a file through the use
+of KFile, the same mechanism that provides &konqueror; with those tooltips
+when you hover a mouse over files.  Aside from loading the information,
+it supports editing it via the <guimenu>Actions'</guimenu> menu subitem 
+<guimenu>Tag Editing</guimenu>.  It supports editing of <acronym>ID3</acronym>
+tags, as well as OggVorbis tags.  It also reads the bitrate from files.
+</para>
+</sect1>
+
+<sect1 id="keyz">
+<title>Keyz</title>
+<para>
+Carsten Pfeiffer decided to break with the long lived &noatun; tradition
+of naming a plugin in the most inaccurate way possible, as proven by both
+Milk-Chocolate, Young Hickory, and countless others.  What's the value
+in just converting an S to a Z?  Sounds like something American-English speakers would do!
+</para>
+<para>
+However, just because the name is unoriginal doesn't mean this is any
+less of a plugin.  Indeed, this one lets you assign keystrokes to some
+&noatun; actions.  The real beauty is that these keystrokes work from
+anywhere, not just from &noatun;.  So this may finally make those
+<quote>Multimedia Keyboards</quote> worthwhile.
+</para>
+</sect1>
+
+<sect1 id="ir-control">
+<title>Infrared Control</title>
+<para>
+If you have a remote control for your computer (such as those found
+on television cards with <trademark class="registered">Brooktree</trademark>
+tuners), and your infrared remote control is supported by
+<ulink url="http://www.lirc.org">LIRC</ulink>, this should work.  Like Keyz,
+the name is unexciting, but the plugin allows you to assign actions to
+button presses.
+</para>
+<para>
+To assign an action to a keypress, load the plugin, go to the Infrared Control
+page in the &noatun; configuration window.  Select the keypress in the 
+list, and then choose the action to perform with the combo box below.  If, in
+an action like Volume control, you want the action to be performed repeatedly,
+check the box and select the interval between actions.
+</para>
+<para>
+If you have a <acronym>TV</acronym> card, a convenient trick is to 
+assign the <guibutton>Mute</guibutton> button to Pause, thereby allowing you to mute your
+<acronym>TV</acronym> display application while unpausing &noatun;,
+and vice-versa, particularly useful in the case of commercials.
+</para>
+</sect1>
+</chapter>
+
+<chapter id="questions-answers-and-tips">
+
+<title>Questions, Answers, and Tips</title>
+
+<qandaset id="faq">
+<title>Frequently-asked questions</title>
+<qandaentry>
+<question>
+<para>The music skips a lot when moving windows.</para>
+</question>
+<answer>
+<para> 
+You can have &arts; buffer more as follows: 
+</para> 
+
+<itemizedlist> 
+<listitem><para>Start &kcontrol;</para></listitem>
+<listitem><para>Move to the <guilabel>Sound</guilabel>
+group</para></listitem> 
+<listitem><para>Move to the <guilabel>Sound
+Server</guilabel> section</para></listitem> 
+<listitem><para>Increase the response time&mdash;384ms is
+usually sufficient 
+for most computers.</para></listitem> 
+</itemizedlist> 
+
+<para> 
+You may also consider running the soundserver with real-time priority 
+if setting the response time doesn't help. Be aware that this can 
+cause your system to lock-up. 
+</para> 
+
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I can't remove a playlist or user-interface from the plugins list.</para>
+</question>
+<answer>
+<para>
+Since &noatun; requires at least one user-interface loaded, and exactly
+one playlist, you have to add a new user-interface plugin before
+removing the old one.  Adding a new playlist will automatically
+remove the old one.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>Where can I get more plugins?</para>
+</question>
+<answer>
+<para>
+Third-party developers can submit their own plugins to the
+<ulink url="http://noatun.kde.org/plugins/">&noatun; web-site</ulink>, where they
+can be downloaded by you, the users.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>How do I write a &noatun; plugin?</para>
+</question>
+<answer>
+<para>
+Documentation, an <acronym>API</acronym> reference, and example source code is
+available at the <ulink url="http://noatun.kde.org">&noatun; web-site</ulink>.
+Also, in the spirit of Open Source software the source code to
+&noatun; and all default plugins is available.
+</para>
+</answer>
+</qandaentry>
+</qandaset>
+</chapter>
+
+<chapter id="credits-and-licenses">
+<title>Credits and Licenses</title>
+
+<para>Program copyright 2000-2002 Charles Samuels
+<email>charles@kde.org</email></para>
+
+<para>Documentation copyright 2002 Charles Samuels
+<email>charles@kde.org</email></para>
+
+<para>&noatun; has been brought to you by the following people:</para>
+
+<itemizedlist>
+<listitem>
+<para>Charles Samuels <email>charles@kde.org</email></para>
+</listitem>
+<listitem>
+<para>Neil Stevens <email>multivac@fcmail.com</email></para>
+</listitem>
+<listitem>
+<para>Stefan Westerfeld <email>stefan@space.twc.de</email></para>
+</listitem>
+<listitem>
+<para>Martin Vogt <email>mvogt@rhrk.uni-kl.de</email></para>
+</listitem>
+<listitem>
+<para>Malte Starostik <email>malte.starostik@t-online.de</email></para>
+</listitem>
+<listitem>
+<para>Nikolas Zimmermann <email>wildfox@kde.org</email></para>
+</listitem>
+<listitem>
+<para>Stefan Schimanski <email>1Stein@gmx.de</email></para>
+</listitem>
+</itemizedlist>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underBSDLicense;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="how-to-obtain-Noatun">
+<title>How to obtain &noatun;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>&noatun; requires at least a Pentium 200 with &Linux;, a PowerPC with
+&Linux; 2.4.1 or later, or several other platforms.  Support for more platforms
+will be available in later versions.</para>
+
+<para>For a platform to be supported easily, it must have pthread support, and
+the <acronym>OSS</acronym> sound output system, however <acronym>ALSA</acronym>
+is supported under &Linux;.</para>
+
+</sect1>
+
+<sect1 id="compilation-and-installation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+<para>Should you run into any problems, please report them to
+the author at <email>charles@kde.org</email>.</para>
+
+<para>If you have this documentation, you've probably already compiled
+&noatun;</para>
+
+</sect1>
+
+</appendix>
+
+<glossary id="glossary">
+<title>Glossary</title>
+
+<glossentry id="gloss-mc">
+<glossterm>Milk Chocolate</glossterm><glossdef>
+<para>
+	Milk Chocolate is a simple, minimalist user interface plugin
+</para></glossdef></glossentry>
+
+<glossentry id="gloss-arts">
+<glossterm>&arts;</glossterm><glossdef>
+<para>
+	&arts; is the Analog Real-time Synthesizer.  A powerful
+	media framework used by &noatun;
+</para></glossdef></glossentry>
+<glossentry id="gloss-kj">
+<glossterm>K-Jöfol</glossterm><glossdef>
+<para>
+	This plugin loads skins originally used under a &Windows;
+	media player under the same name.
+</para></glossdef></glossentry>
+
+<glossentry id="gloss-keyz">
+<glossterm>Keyz</glossterm><glossdef>
+<para>
+	Keyz allows you to assign keystrokes to actions in &noatun;
+</para></glossdef></glossentry>
+<glossentry id="gloss-young-hickory">
+<glossterm>Young Hickory</glossterm><glossdef>
+<para>
+	Young Hickory is a system tray plugin.
+</para></glossdef></glossentry>
+<glossentry id="gloss-kaiman">
+<glossterm>Noatun</glossterm><glossdef>
+<para>
+	Kaiman is a plugin that loads skins from the media player
+	GQMPEG.  Kaiman is also &noatun;'s predecessor, and was
+	distributed with &kde; for &kde; 2.0. When
+	&noatun; was introduced in &kde; 2.1, Kaiman's skin loader
+	became a &noatun; plugin.
+</para></glossdef></glossentry>
+
+</glossary>
+
+&documentation.index;
+</book>
+