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/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 386 insertions, 0 deletions

diff --git a/doc/kpilot/faq.docbook b/doc/kpilot/faq.docbook
new file mode 100644
index 000000000..cbc9196e2
--- /dev/null
+++ b/doc/kpilot/faq.docbook
@@ -0,0 +1,386 @@
+<chapter id="faq">
+<title>&FAQ;</title>
+
+<sect1 id="faq-crash">
+<title>&kpilot; Startup Problems</title>
+
+<qandaset>
+
+<qandaentry>
+<question>
+<para>
+What do I put after <option>--debug</option>?
+</para>
+</question>
+<answer>
+<para>
+Nothing. Most versions of &kpilot; don't even have
+a <option>--debug</option> option, and will complain if you use it.
+For those versions that <emphasis>do</emphasis> have it,
+use a value between 1 and 4, which will control the
+amount of debugging printed (a little).
+Using a value of 1 will print a fairly complete call trace
+without the really-boring functions, while 4 will include every trivial
+function in all of &kpilot;.
+</para>
+
+</answer>
+</qandaentry>
+
+<qandaentry id="faq-connection">
+<question>
+<para>
+&kpilot; says <errorname>Can't connect to pilot</errorname>
+</para>
+</question>
+<answer>
+<para>
+This can have various causes. Check that:
+<itemizedlist>
+<listitem>
+<para>
+	The pilot device (usually <filename
+	class="devicefile">/dev/pilot</filename>) exists and points to the
+	serial port the &PalmPilot; is actually connected to.
+</para>
+<para>
+	To link the &PalmPilot; device to the correct serial port, you can
+	either fill in
+	<filename
+	class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename>
+	in the <guilabel>Pilot Device</guilabel> field in the <link
+	linkend="page-general">setup dialog</link> or (preferably) link
+	<filename class="devicefile">/dev/pilot</filename> to
+	<filename
+	class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename>
+	with the following command (as <systemitem
+	class="username">root</systemitem>):
+	<userinput>
+	<command>ln</command>
+	<option>-s</option>
+	<parameter>/dev/ttyS<replaceable>n</replaceable></parameter>
+	<parameter>/dev/pilot</parameter></userinput>
+	Here <filename
+	class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename>
+	is the name
+	of the serial port; replace <replaceable>n</replaceable>
+	with the correct number (usually 0 or 1).
+</para>
+</listitem>
+<listitem>
+<para>
+	Check that you have permission to read and write to the serial port.
+	The permissions for the serial port should be such that you can write to
+	it. This is most easily done by running the following (as root):
+	<userinput>
+	<command>chmod</command>
+	<option>666</option>
+	<parameter>/dev/ttyS<replaceable>n</replaceable></parameter>
+	</userinput>
+</para>
+</listitem>
+<listitem>
+<para>
+	Try starting the daemon by hand before starting &kpilot;.
+</para>
+</listitem>
+<listitem>
+<para>
+	(For &Linux-Mandrake; 7 systems) Check the system security level:
+	settings higher than 3 prevent some forms of inter-process
+	communication which are necessary for &kpilot; to
+	operate correctly.
+</para>
+
+<para>
+	(<emphasis>&Linux-Mandrake; security information
+	courtesy of Jay Summett</emphasis>)
+	To set your
+<!-- TM? --><acronym>MSEC</acronym>
+<!-- TM? -->(Mandrake SECurity)
+	settings to not block the
+	&kpilot; socket (for connections to localhost) you can
+	login as root and
+	type
+	<userinput>
+	<command>/etc/security/msec/init.sh</command>
+	<option>3</option>
+	</userinput>
+	Which will set your
+<!-- TM? --><acronym>MSEC</acronym>
+	level to 3 (regular security).
+	For more information about the various security levels, &etc;, see:
+	<ulink url="http://www.linux-mandrake.com/userguide/en/reference/017.html#157">
+	the
+<!-- TM? -->Mandrake
+reference guide</ulink>.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+</sect1>
+
+<sect1 id="faq-database">
+<title>Database Questions</title>
+
+<para>
+This section answers questions commonly asked about
+particular databases and how they
+interact with &kpilot;.
+</para>
+
+<qandaset>
+
+<qandaentry>
+<question>
+<para>
+Databases become corrupted after a sync,
+what should I do?
+</para>
+</question>
+<answer>
+<para>
+Certain databases (from third-party software manufacturers)
+appear not to follow the standard database layout.
+If you can find out what the creator id of the database is,
+you can add it to either the
+<guilabel>Backup Only:</guilabel> list or the
+<guilabel>Skip</guilabel> list in the
+<link linkend="page-backup">settings dialog</link>.
+</para>
+
+<para>
+The following table shows which databases should be skipped
+or backed-up only:
+<table id="dbskip">
+<title>Databases needing Special Treatment</title>
+<tgroup cols="3">
+<thead>
+<row><entry>Database</entry><entry>Creator ID</entry><entry>Action</entry></row>
+</thead>
+<tbody>
+<row>
+	<entry>Launcher (the &PalmPilot;'s main menu)</entry>
+	<entry>lnch</entry>
+	<entry>Backup Only:</entry>
+</row>
+<row>
+	<entry>Arranger</entry>
+	<entry>Arng</entry>
+	<entry>Backup Only:</entry>
+</row>
+<row>
+	<entry>(unknown)</entry>
+	<entry>PmDB</entry>
+	<entry>Backup Only:</entry>
+</row>
+<row>
+	<entry>AvantGo</entry>
+	<entry>avgo</entry>
+	<entry>Skip (Mostly because there's no point in backing up the
+	news articles that AvantGo gives you)</entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Is there a conduit for &Netscape; <application>Calendar</application>?
+</para>
+</question>
+<answer>
+<para>
+No, there isn't.
+Neither are there plans to include support or write a
+conduit for &Netscape; <application>Calendar</application>.
+</para>
+</answer>
+</qandaentry>
+
+
+</qandaset>
+
+</sect1>
+
+<sect1 id="faq-hotsync">
+<title>
+Special HotSync Questions
+</title>
+
+<para>
+This section lists questions about HotSync methods that differ
+from the <quote>usual</quote> direct serial link method.
+</para>
+
+<qandaset>
+
+<qandaentry>
+<question>
+<para>
+How do I do an infrared (<acronym>IR</acronym>) HotSync?
+</para>
+</question>
+<answer>
+<para>
+First of all your &PalmPilot; has to actually support
+<acronym>IR</acronym> HotSyncs.  This can be achieved through various
+means: &PalmOS; 3.3 and higher include support for it; there is an
+<acronym>IR</acronym> enhancements package for older &PalmOS; versions;
+<application>IrLink</application> from IsComplete apparently has the
+same capabilities.  Check out the <ulink
+url="http://www.palmone.com/us/">PalmOne</ulink> web pages for more information.
+</para>
+
+<para>
+Assuming your &PalmPilot; now has <acronym>PC</acronym> HotSync support
+and it is setup to do <acronym>IR</acronym> HotSyncs (in the HotSync
+preferences on the &PalmPilot;), we can turn our attention to the
+<acronym>PC</acronym> you will be synchronization with.  It needs an
+<acronym>IR</acronym> port.  For laptops, this is trivial, desktop
+<acronym>PCs</acronym> may require some extra hardware.
+</para>
+
+<para>
+Your &Linux; kernel will need to support <acronym>IR</acronym> and the <acronym>IRCOMM</acronym> protocol.
+For stock
+&RedHat;
+systems, the following command should
+setup <acronym>IR</acronym> support (as <systemitem class="username">root</systemitem>):
+<screen width="40">
+<prompt># </prompt><userinput><command>modprobe</command> <option>ircomm</option></userinput>
+</screen>
+
+Other distributions should follow the <filename>IR-HOWTO</filename>.
+Once <acronym>IR</acronym> support in the kernel has been activated,
+you need to make devices for the <acronym>IR</acronym> ports.
+The <filename>IR-HOWTO</filename> suggests (as <systemitem class="username">root</systemitem>):
+<screen width="40">
+<prompt># </prompt><userinput><command>mknod</command>
+<option>/dev/ircomm0</option> <parameter>60</parameter> <parameter>64</parameter> </userinput>
+<prompt># </prompt><userinput><command>chmod</command>
+<option>666</option> <parameter>/dev/ircomm0</parameter></userinput>
+</screen>
+Next we need to start some daemons for <acronym>IR</acronym> services:
+<screen width="40">
+<prompt># </prompt><userinput><command>irattach</command>
+<option>/dev/ttyS<replaceable>n</replaceable></option></userinput>
+<prompt># </prompt><userinput><command>irmanager</command>
+<option>-d</option> <parameter>0</parameter></userinput>
+</screen>
+Here <filename class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename>
+is the serial port
+the <acronym>IR</acronym> port is using. <replaceable>n</replaceable> could be 0, 1, or some other
+number depending on your hardware setup.
+Follow the instructions in the <filename>IR-HOWTO</filename> for assistance
+(for desktop machines, it's usually a setting in the <acronym>BIOS</acronym>).
+</para>
+
+<para>
+Once you've gotten this far, just make <filename class="devicefile">/dev/pilot</filename>
+point to <filename class="devicefile">/dev/ircomm0</filename>
+and you're ready!
+</para>
+
+<para>
+The IR-HOWTO and other useful information on using IR may
+be found at
+<ulink url="http://mobilix.org/howtos.html">http://mobilix.org/howtos.html</ulink>
+and
+<ulink url="http://mobilix.org/software/irda/">http://mobilix.org/software/irda/</ulink>.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>Can I do a &HotSync; with my (<acronym>USB</acronym>)
+<!-- TM? -->&Handspring; &Visor;?
+</para>
+</question>
+<answer>
+<para>
+Yes, you can.
+I don't have definitive information, but postings on the
+&kpilot; mailing-list have stated that you can point <filename class="devicefile">/dev/pilot</filename>
+to the <acronym>USB</acronym> device and everything will work fine.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Is there any support for remote HotSyncs?</para>
+</question>
+<answer>
+<para>
+No, not yet.
+Maybe later.
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+</sect1>
+
+
+<sect1>
+<title>&kpilot;'s &DCOP; interface</title>
+
+<qandaset>
+
+<qandaentry>
+<question>
+<para>What does &kpilot; use &DCOP; for?</para>
+</question>
+<answer><para>
+The daemon and &kpilot; communicate using &DCOP;
+for several purposes: logging messages, changing the &HotSync;
+type, and exchanging configuration information.
+</para></answer>
+</qandaentry>
+
+<qandaentry><question>
+<para>Which &DCOP; interfaces are there?</para></question>
+
+<answer><para>
+The daemon has two important interfaces:
+<interface>LogIface</interface>
+and
+<interface>KPilotDaemonIface
+</interface>.
+The <interface>LogIface</interface>
+interface is used to record messages in the sync log
+on the &handheld;, and is rarely used.
+The <interface>KPilotDaemonIface</interface>
+is the more important &DCOP; interface,
+and is used to control the kind of &HotSync; that
+&kpilot; will do.
+</para></answer>
+</qandaentry>
+
+<qandaentry><question><para>
+How can I tell the daemon to perform a specific kind of &HotSync;?</para></question>
+<answer><para>
+There are three &DCOP; functions that control what kind
+of &HotSync;
+the daemon will do next:
+<function></function>
+<function></function>
+</para></answer>
+</qandaentry>
+</qandaset>
+
+</sect1>
+
+</chapter>