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, 246 insertions, 0 deletions

diff --git a/doc/artsbuilder/helping.docbook b/doc/artsbuilder/helping.docbook
new file mode 100644
index 00000000..72b2ff2b
--- /dev/null
+++ b/doc/artsbuilder/helping.docbook
@@ -0,0 +1,246 @@
+<!-- <?xml version="1.0" ?>
+<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
+To validate or process this file as a standalone document, uncomment
+this prolog. Be sure to comment it out again when you are done -->
+
+<chapter id="contributing">
+<title>Contributing to &arts;</title>
+
+<sect1 id="how-to-help">
+<title>How You Can Help</title>
+
+<para>
+The &arts; project can use help from developers to make existing
+multimedia applications &arts;-aware, write new multimedia applications,
+and enhance the capabilities of &arts;. However, you don't have to be a
+developer to contribute. We can also use help from testers to submit bug
+reports, translators to translate the application text and documentation
+into other languages, artists to design bitmaps (especially for
+<application>artsbuilder</application> modules), musicians to create
+sample &arts; modules, and writers to write or proofread documentation.
+</para>
+</sect1>
+
+<sect1 id="mailing-lists">
+<title>Mailing Lists</title>
+
+<para>
+Most development discussions on &arts; take place on two mailing
+lists. This is the place to discuss new feature and implementation ideas
+or ask for help with problems.
+</para>
+
+<para>
+The &kde; Multimedia mailing list is for general &kde; multimedia issues
+including &arts; as well as the multimedia applications like &noatun;
+and &aktion;.  You can subscribe from the web page at
+<ulink url="http://www.kde.org/mailinglists.html">
+http://www.kde.org/mailinglists.html</ulink> or send an email with the
+subject set to <userinput>subscribe
+<replaceable>your-email-address</replaceable></userinput> to
+<email>kde-multimedia-request@kde.org</email>. The list is also archived
+at <ulink url="http://lists.kde.org"> http://lists.kde.org</ulink>.
+</para>
+
+<para>
+The &arts; mailing list is for issues specific to &arts;, including
+non-&kde; use of &arts;. To subscribe, send an email containing the
+message body <userinput>subscribe
+<replaceable>your-email-address</replaceable></userinput> to
+<email>arts-request@space.twc.de</email>.  The list is archived at
+<ulink url="http://space.twc.de/~stefan/arts-archive">
+http://space.twc.de/~stefan/arts-archive</ulink>.
+</para>
+
+</sect1>
+
+<sect1 id="coding-standards">
+<title>Coding Standards</title>
+
+<para>
+For getting a consistent reading through all the sources, it is
+important to keep the coding style the same, all over the &arts;
+source. Please, even if you just write a module, try to write/format
+your source accordingly, as it will make it easier for different people
+to maintain the source tree, and easier to copy pieces of from one
+source to another.
+</para>
+
+<variablelist>
+<varlistentry>
+<term>Naming of member functions</term>
+<listitem>
+<para>
+&Qt;/&Java; style.  That means capitalization on word breaks, and first
+letter always without capitalization; no underscores.
+</para>
+<para>This means for instance:</para>
+
+<programlisting>   createStructureDesc()
+   updateWidget();
+   start(); </programlisting>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Class members</term>
+<listitem>
+<para>
+Class members are not capitalized, such as menubar or button.
+</para>
+
+<para>
+When there are accessing functions, the standard should be the &MCOP;
+way, that is, when having an long member <function>foo</function>, which
+shouldn't be visible directly, you create:
+</para>
+
+<programlisting>   foo(long new_value);
+   long foo(); </programlisting>
+
+<para>
+functions to get and set the value. In that case, the real value of
+<function>foo</function> should be stored in
+<returnvalue>&lowbar;foo</returnvalue>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Class names</term>
+<listitem>
+<para>
+All classes should be wordwise capitalized, that means
+<classname>ModuleView</classname>,
+<classname>SynthModule</classname>. All classes that belong to the
+libraries should use the &arts; namespace, like
+<classname>Arts::Soundserver</classname>.
+</para>
+<para>
+The implementations of &MCOP; classes should get called
+<classname>Class&lowbar;impl</classname>, such as
+<classname>SoundServer&lowbar;impl</classname>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Parameters</term>
+<listitem>
+<para>
+Parameters are always uncapitalized.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Local variables</term>
+<listitem>
+<para>
+Local variables are always uncapitalized, and may have names like
+<varname>i</varname>, <varname>p</varname>, <varname>x</varname>, &etc;
+where appropriate.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Tab width (Shift width)</term>
+<listitem>
+<para>
+One tab is as long as 4 spaces.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Spaces in expressions</term>
+<listitem>
+<para>
+You normally don't need to use spaces in expressions. You can however use
+them between operator and their operands. However, if you put a space before
+an operator (i.e. +), you also need to put a space after the operator. The only
+exception to this are list-like expressions (with ,), where you should only put
+a space after the ",", but not before. It's okay to omit the space here, too.
+</para>
+<para>
+The following examples demonstrate good use of spaces:
+</para>
+<programlisting>
+{
+    int a,b;
+    int c, d, e;
+    int f = 4;
+
+    a=b=c=d+e+f;
+    a = b = c = d + e + f;
+
+    if(a == 4) {
+        a = b = c = (d+e)/2;
+    }
+
+    while(b&lt;3)
+        c--;
+
+    arts_debug("%d\n", c);
+}
+</programlisting>
+<para>
+The following examples demonstrate how <emphasis>not</emphasis> to use spaces.
+For function calls, after if, while, for, switch and so on, no space is being
+written.
+</para>
+<programlisting>
+{
+    // BAD: if you write a list, write spaces only after the ","
+    int a , b , c , d , e , f;
+
+    // BAD: non-symmetric use of spaces for = operator
+    a= 5;
+
+    // BAD: if is considered a function, and isn't followed by a space
+    if (a == 5) {   
+    }
+
+    // BAD: don't write a space after while
+    while (a--)
+        b++; 
+
+    // BAD: functions names are not followed by a space
+    arts_debug ("%d\n", c);
+
+    // BAD: neither are member names
+    Arts::Object o = Arts::Object::null ();
+}
+</programlisting>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>Naming of source files</term>
+<listitem>
+<para>
+Source files should have no capitalization in the name. They should have
+the name of the class when they implement a single class. Their
+extension is <literal role="extension">.cc</literal> if they refer to
+&Qt;/&GUI; independent code, and <literal
+role="extension">.cpp</literal> if they refer to &Qt;/&GUI; dependant
+code. Implementation files for interfaces should be called
+<filename><replaceable>foo</replaceable>_impl</filename>, if Foo was the
+name of the interface.
+</para>
+
+<para>
+&IDL; files should be called in a descriptive way for the collection of
+interfaces they contain, also all lower case. Especially it is not good
+to call an &IDL; file like the class itself, as the .mcopclass trader
+and type info entries will collide, then.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+</chapter>