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

1 files changed, 393 insertions, 0 deletions

diff --git a/doc/artsbuilder/index.docbook b/doc/artsbuilder/index.docbook
new file mode 100644
index 00000000..ba6649a1
--- /dev/null
+++ b/doc/artsbuilder/index.docbook
@@ -0,0 +1,393 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kappname "&arts;" >
+ <!ENTITY tools SYSTEM "tools.docbook">
+ <!ENTITY artsbuilder-doc SYSTEM "artsbuilder.docbook"> 
+ <!ENTITY detail SYSTEM "detail.docbook">
+ <!ENTITY arts-midi SYSTEM "midi.docbook">
+ <!ENTITY gui SYSTEM "gui.docbook">
+ <!ENTITY mcop-ref SYSTEM "mcop.docbook">
+ <!ENTITY arts-mcop SYSTEM "mcop.docbook">
+ <!ENTITY apis SYSTEM "apis.docbook">
+ <!ENTITY modules SYSTEM "modules.docbook">
+ <!ENTITY porting SYSTEM "porting.docbook">
+ <!ENTITY helping SYSTEM "helping.docbook">
+ <!ENTITY future SYSTEM "future.docbook">
+ <!ENTITY references SYSTEM "references.docbook">
+ <!ENTITY arts-faq SYSTEM "faq.docbook">
+ <!ENTITY arts-glossary SYSTEM "glossary.docbook">
+ <!ENTITY digitalaudio SYSTEM "digitalaudio.docbook">
+ <!ENTITY midiintro SYSTEM "midiintro.docbook">
+ <!ENTITY MCOP "<acronym>MCOP</acronym>">
+ <!ENTITY DCOP "<acronym>DCOP</acronym>">
+ <!ENTITY MIDI "<acronym>MIDI</acronym>">
+ <!ENTITY mcopidl "<application>mcopidl</application>">
+ <!ENTITY IDL "<acronym>IDL</acronym>">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+ <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &arts; Handbook</title>
+<authorgroup>
+
+<author>
+<firstname>Stefan</firstname>
+<surname>Westerfeld</surname>
+<affiliation>
+<address><email>stefan@space.twc.de</email></address>
+</affiliation>
+</author>
+
+<author>
+<firstname>Jeff</firstname>
+<surname>Tranter</surname>
+<affiliation>
+<address><email>tranter@kde.org</email></address>
+</affiliation>
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>1999-2001</year>
+<holder>Stefan Westerfeld &amp; Jeff Tranter</holder>
+</copyright>
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2001-06-10</date>
+<releaseinfo>1.00.09</releaseinfo>
+
+<abstract><para>This handbook describes &arts;, the Analog Real-time
+Synthesizer.</para>
+
+</abstract>
+
+<keywordset>
+<keyword>aRts</keyword>
+<keyword>artsbuilder</keyword>
+<keyword>synthesizer</keyword>
+<keyword>multimedia</keyword>
+<keyword>structure</keyword>
+<keyword>music</keyword>
+<keyword>sound</keyword>
+<keyword>KDE</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<sect1 id="what-is-arts">
+<title>What is &arts;?</title>
+
+<para>The Analog Real-Time Synthesizer, or &arts;, is a modular system
+for synthesizing sound and music on a digital computer. Using small
+building blocks called modules, the user can easily build complex audio
+processing tools. Modules typically provide functions such as sound
+waveform generators, filters, audio effects, mixing, and playback of
+digital audio in different file formats.</para>
+
+<para>The &artsd; sound server mixes audio from several sources in real
+time, allowing multiple sound applications to transparently share access
+to sound hardware.</para>
+
+<para>Using &MCOP;, the Multimedia Communication Protocol, multimedia
+applications can be network transparent, authenticated for security, and
+cross-platform using interfaces defined in a language-independent way
+using &IDL;. Support is also provided for non &arts;-aware legacy
+applications. As a core component of the &kde; 2 desktop environment,
+&arts; provides the basis for the &kde; multimedia architecture, and
+will in future support more media types including video. Like &kde;,
+&arts; runs on a number of operating systems, including &Linux; and BSD
+variants. It can also be used independently of &kde;.</para>
+
+</sect1>
+
+<sect1 id="using-this-manual">
+<title>Using This Manual</title>
+
+<para>This manual is intended to provide comprehensive documentation on
+&arts; for users at different skill levels. Depending on whether you are
+a casual user of multimedia applications that make use of &arts; or a
+multimedia application developer, you may want to take different paths
+through the manual.</para>
+
+<para>It is suggested that you first read the <link
+linkend="installation">Downloading and Building &arts;</link> chapter if
+you need to get &arts; initially installed and running. If you already
+have a working system, likely bundled with your operating system
+distribution, you may choose to skip this section.</para>
+
+<para>You should then read the sections in the <link
+linkend="arts-tools">&arts; Tools</link> chapter, especially &artsd;,
+artscontrol;, &artsshell;, and &artsdsp;. This will help you make the
+most effective use of &arts;.</para>
+
+<para>If you are interested in going further with &arts;, read the
+chapter on <link linkend="artsbuilder">&arts-builder;</link> and go
+through the tutorial. This should give you an appreciation of the
+powerful capabilities of &arts; and the provided modules that can be
+used without the need to be a programmer.</para>
+
+<para>If you want to know more about the internals of &arts;, either to
+develop multimedia applications or extend &arts; itself, read some or
+all of the chapter <link linkend="arts-in-detail">&arts; in
+Detail</link>. This should give you an understanding of all of the
+concepts that are prerequisites to &arts; software development.</para>
+
+<para>If you are interested specifically in the <acronym>MIDI</acronym>
+capabilities of &arts;, you should read the chapter on <link
+linkend="midi">&MIDI;</link>.</para>
+
+<!-- TODO
+<para>To learn more about the &arts; graphical elements, either as an advanced
+user of artsbuilder or to create new elements, read the section on <link
+linkend="gui-elements"><acronym>GUI</acronym> Elements</link>.</para>
+-->
+
+<para>If you want to develop &arts;-aware multimedia applications, the
+<link linkend="arts-apis">&arts; Application Programming
+Interfaces</link> chapter covers the different <acronym>API</acronym>s
+in detail.</para>
+
+<para>If you want to extend &arts; by creating new modules, read the
+<link linkend="arts-modules">&arts; Modules</link> chapter.</para>
+
+<para>If you are modifying an existing application to run under &arts;,
+read the chapter on <link linkend="porting">Porting Applications to
+&arts;</link>.</para>
+
+<para>You you can find out how to help contribute to the &arts; project
+in the <link linkend="contributing">Contributing to &arts;</link>
+chapter, read about upcoming &arts; development in the chapter on <link
+linkend="future-work">Future Work</link>, and find links to more
+information in the <link linkend="references">References</link>
+section.</para>
+
+<para>We have also rounded out the manual with some additional material,
+including <link linkend="faq">answers to frequently asked
+questions</link>, a <link linkend="contributors">list of
+contributors</link>, the details on &arts; <link
+linkend="copyright-and-licenses">copyright and licensing</link>, and
+some background material on <link linkend="intro-digital-audio">digital
+audio</link> and <link
+linkend="midi-introduction">&MIDI;</link>. A <link
+linkend="glossary">glossary</link> of terms is also included.</para>
+
+<note>
+<para>
+This manual is still very much a work in progress. You are welcome to
+contribute by writing portions of it, but if you wish to do so, contact
+Jeff Tranter <email>tranter@kde.org</email> or Stefan Westerfeld
+<email>stefan@space.twc.de</email> first to avoid duplication of effort.
+</para>
+</note>
+
+</sect1>
+
+<sect1 id="history">
+<title>History</title>
+
+<para>
+In late 1997 Stefan Westerfeld started working on a real-time, modular
+system for sound synthesis. The code initially ran on a PowerPC system
+running &AIX;. This first implementation was quite simple but supported
+a full-featured flow system that was able to do such things as play MP3
+files and pipe audio streams through effects modules.
+</para>
+
+
+<para>The next step was to implement a &GUI; so that modules could be
+manipulated graphically. Stefan had had some good experience using
+&kde;, so that was chosen as the &GUI; toolkit, (knowing that it might
+be necessary to do a GNOME/Gtk+ version as well) and this later led to
+using &Linux; as the main development platform. Originally named
+<application>ksynth</application>, the project was renamed &arts; and
+the pace of development accelerated. The project at this stage was quite
+complete, with a <acronym>CORBA</acronym>-based protocol, dozens of
+modules, a graphical module editing tool, C and C++
+<acronym>API</acronym>s, documentation, utilities, and a mailing list
+and web site with a small group of developers. The project had come a
+long way after only a little more than a year of development.</para>
+
+<para>As the &kde; team started planning for &kde; 2.0, it became clear
+that &kde; needed a more powerful infrastructure for sound and other
+streaming media. It was decided to adapt &arts;, as it was a good step
+in this direction with a proven architecture. Much new development
+effort went into this new version of &arts;, most notably the
+replacement of the <acronym>CORBA</acronym> code with an entirely new
+subsystem, &MCOP;, optimized for multimedia. Version 0.4 of &arts; was
+included in the &kde; 2.0 release.</para>
+
+<para>Work continues on &arts;, improving performance and adding new
+functionality. It should be noted that even though &arts; is now a core
+component of &kde;, it can be used without &kde;, and is also being used
+for applications that go beyond traditional multimedia. The project has
+attracted some interest from the GNOME team, opening up the possibility
+that it may someday become the standard multimedia architecture for
+&UNIX; desktop systems.</para>
+
+</sect1>
+
+</chapter>
+
+&tools;
+&artsbuilder-doc;
+&detail;
+&arts-midi;
+&gui;
+&mcop-ref;
+&apis;
+&modules;
+&porting;
+&helping;
+&future;
+&references;
+&arts-faq;
+
+<chapter id="copyright-and-licenses">
+
+<title>&arts; Copyright and Licensing</title>
+
+<para>&arts; software copyright 1998-2001 Stefan Westerfeld
+<email>stefan@space.twc.de</email></para>
+
+<para><anchor id="contributors" />
+Documentation copyright 1999-2001
+Stefan Westerfeld <email>stefan@space.twc.de</email> and
+Jeff Tranter <email>tranter@kde.org</email>.
+</para>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+
+<para>
+All libraries that are in &arts; are licensed under the terms of the
+<acronym>GNU</acronym> Lesser General Public license. The vast majority of the
+&arts; code is in the libraries, including the whole of <acronym>MCOP</acronym>
+and ArtsFlow. This allows the libraries to be used for non-free/non-open source
+applications if desired.
+</para>
+
+<para>There are a few programs (such as <application>artsd</application>), that
+are released under the terms of the <acronym>GNU</acronym> General Public
+License. As there have been different opinions on whether or not linking
+<acronym>GPL</acronym> programs with &Qt; is legal, I also added an explicit
+notice which allows that, in addition to the <acronym>GPL</acronym>: permission
+is also granted to link this program with the &Qt; library, treating &Qt; like a
+library that normally accompanies the operating system kernel, whether or not
+that is in fact the case.</para>
+
+</chapter>
+
+<appendix id="installation">
+<title>Installing &arts;</title>
+
+<para>
+In order to use &arts; you obviously need to have it installed and running on
+your system. There are two approaches for doing this, which are described in the
+next sections.
+</para>
+
+<sect1 id="binary-install">
+<title>Installing a Precompiled Binary Release</title>
+
+<para>
+The quickest and easiest way to get &arts; up and running is to install
+precompiled binary packages for your system. Most recent &Linux; distributions
+include &kde;, and if it is &kde; 2.0 or later it will include &arts;. If &kde;
+is not included on your installation media it may be available as a download
+from your operating system vendor.  Alternatively it may be available from third
+parties. Make sure that you use packages that are compatible with your operating
+system version.
+</para>
+
+<para>
+A basic install of &kde; will include the sound server, allowing most
+applications to play sound. If you want the full set of multimedia tools and
+applications you will likely need to install additional optional packages.
+</para>
+
+<para>
+The disadvantage of using precompiled binaries is that they may not be the most
+recent version of &arts;. This is particularly likely if they are provided on
+&CD-ROM;, as the pace of development of &arts; and &kde; is such that &CD-ROM;
+media cannot usually keep pace. You may also find that, if you have one of the
+less common architectures or operating system distributions, precompiled binary
+packages may not be available and you will need to use the second method.
+</para>
+
+</sect1>
+
+<sect1 id="source-install">
+<title>Building From Source</title>
+
+<para>
+While time consuming, the most flexible way to build &arts; is to compile it
+yourself from source code. This ensures you have a version compiled optimally
+for your system configuration and allows you to build the most recent version.
+</para>
+
+<para>
+You have two choices here -- you can either install the most recent stable
+version included with &kde; or you can get the most recent (but possibly
+unstable) version directly from the &kde; project <acronym>CVS</acronym>
+repository. Most users who aren't developing for &arts; should use the stable
+version. You can download it from <ulink
+url="ftp://ftp.kde.org">ftp://ftp.kde.org</ulink> or one of the many mirror
+sites. If you are actively developing for &arts; you probably want to use the
+<acronym>CVS</acronym> version. If you want to use aRts without KDE, you can
+download a standalone development snapshot from
+<ulink url="http://space.twc.de/~stefan/kde/arts-snapshot-doc.html">
+http://space.twc.de/~stefan/kde/arts-snapshot-doc.html</ulink>.
+</para>
+
+<para>
+Note that if you are building from <acronym>CVS</acronym>, some components
+of &arts; (&ie; the basic core components including the sound server) are found
+in the <acronym>CVS</acronym> module kdelibs, while additional components (&eg;
+<application>artsbuilder</application>) are included in the. This may change in
+the future. You may also find a version in the kmusic module; this is the old
+(pre-&kde; 2.0) version which is now obsolete.
+</para>
+
+<para>
+The requirements for building &arts; are essentially the same as for building
+&kde;. The configure scripts should detect your system configuration and
+indicate if any required components are missing. Make sure that you have a
+working sound driver on your system (either the <acronym>OSS</acronym>/Free
+driver in the kernel, <acronym>OSS</acronym> driver from 4Front
+Technologies, or 
+<acronym>ALSA</acronym> driver with <acronym>OSS</acronym> emulation).
+</para>
+
+<para>More information on downloading and installing &kde; (including &arts;)
+can be found in the <ulink
+url="http://www.kde.org/documentation/faq/index.html">&kde;
+&FAQ;</ulink>.</para>
+
+</sect1>
+
+</appendix>
+
+&digitalaudio;
+&midiintro;
+&arts-glossary;
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->