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

1 files changed, 750 insertions, 0 deletions

diff --git a/doc/krdc/index.docbook b/doc/krdc/index.docbook
new file mode 100644
index 00000000..574bb326
--- /dev/null
+++ b/doc/krdc/index.docbook
@@ -0,0 +1,750 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&krdc;">
+  <!ENTITY package "kdenetwork">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English 
+                                     original documentation, change 
+                                     the language here -->
+    
+  <!-- Do not define any other entities; instead, use the entities
+       from entities/general.entities and $LANG/user.entities. -->
+]>
+<!-- Based on kdoctemplate v0.9 January 10 2003 -->
+
+<book lang="&language;">
+
+<!-- This header contains all of the meta-information for the document such
+as Authors, publish date, the abstract, and Keywords -->
+
+<bookinfo>
+<title>The &krdc; Handbook</title>
+
+<authorgroup>
+<author>
+&Brad.Hards;
+&Brad.Hards.mail;
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2003</year>
+<holder>&Brad.Hards;</holder>
+</copyright>
+<!-- Translators: put here the copyright notice of the translation -->
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2003-09-27</date>
+<releaseinfo>1.0.0</releaseinfo>
+
+<abstract>
+<para>
+&krdc; is a client application that allows you to view or even control
+the desktop session on another machine that is running a compatible
+(VNC) server.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdenetwork</keyword>
+<keyword>krfb</keyword>
+<keyword>VNC</keyword>
+<keyword>RFB</keyword>
+<keyword>krdc</keyword>
+<keyword>Desktop Sharing</keyword>
+<keyword>Remote Control</keyword>
+<keyword>Remote Assistance</keyword>
+<keyword>Remote Desktop</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&krdc; is a client application that allows you to view or even control
+the desktop session on another machine that is running a compatible
+(VNC) server.
+</para>
+
+<para>
+You would typically use &krdc; with the &kde; VNC server, which is
+&krfb;, since it closely matches the special features of &krdc;.
+</para>
+
+<para>
+Please report any problems or feature requests to the &kde; mailing
+lists or file a bug at <ulink
+url="http://bugs.kde.org">http://www.bugs.kde.org</ulink>. 
+</para>
+</chapter>
+
+<chapter id="what-is-RFB">
+<title>The Remote Frame Buffer protocol</title>
+
+<para>
+This chapter provides a brief description of the Remote Frame Buffer
+protocol used by &krdc; and by other compatible systems. If you are
+already familiar with Remote Frame Buffer, you can safely skip this
+chapter.
+</para>
+
+<para>
+The high level implementation of a system using the Remote Frame
+Buffer protocol is known as Virtual Network Computer, or more often
+just as <acronym>VNC</acronym>. 
+</para>
+
+<para>
+Remote Frame Buffer (or <acronym>RFB</acronym> for short) is a simple
+protocol for remote access to graphical user interfaces. It works at
+the frame-buffer level, which roughly corresponds to the rendered
+screen image, which means that it can be applied to all windowing
+systems (including X11, &MacOS; and &Microsoft; &Windows;). Remote
+Frame Buffer applications exist for many platforms, and can often be
+free re-distributed.
+</para>
+
+<para>
+In the Remote Frame Buffer protocol, the application that runs on the
+machine where the user sits (containing the display, keyboard and
+pointer) is called the client. The application that runs on the
+machine where the framebuffer is located (which is running the
+windowing system and applications that the user is remotely
+controlling) is called the server. &krdc; is the &kde; client for the
+Remote Frame Buffer protocol. &krfb; is the &kde; server for the
+Remote Frame Buffer protocol. 
+</para>
+
+<para>
+It takes a reasonable amount of network traffic to send an image of
+the framebuffer, so Remote Frame Buffer works best over high
+bandwidth links, such as a local area network. It is still possible to
+use &krdc; over other links, but performance is unlikely to be as good.
+</para>
+
+</chapter>
+
+<chapter id="using-krdc">
+<title>Using &krdc;</title>
+
+<para>
+It is very easy to use &krdc; - it has a simple interface, as shown in
+the screenshot below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Here's a screenshot of &krdc;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; main window</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+If you click on the <guibutton>Browse &lt;&lt;</guibutton> button, you
+will get an even simpler interface, as shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; main window, without browse functionality</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_nobrowse.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_nobrowse.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; main window, without browse functionality</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+If you click on the <guibutton>Browse &gt;&gt;</guibutton> button, you
+will get the normal interface back.
+</para>
+
+<sect1 id="compatible-versions"><title>Connecting &krdc; to compatible servers</title>
+
+<para>
+&krdc; is a client, and it needs to be used with compatible
+servers. There are three ways to connect to those servers:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>Directly typing the server name (or IP address) into the
+<guilabel>Remote desktop:</guilabel> combo box.</para> 
+</listitem>
+<listitem>
+<para>By using an invitation that you received. &krfb; uses
+invitations, and can send them by email.</para>
+</listitem>
+<listitem>
+<para>By using Service Location Protocol browsing.</para>
+</listitem>
+</itemizedlist>
+
+<para>
+Let's look at each of these in turn.
+</para>
+
+<sect2><title>Server name entry</title>
+<para>
+If you know the host name (or IP address) of the server you want to
+connect to, you can enter it directly into the <guilabel>Remote
+desktop:</guilabel> combo box.
+</para>
+
+<para>
+If you want to connect to a machine named megan, which is
+running a <acronym>VNC</acronym> server on screen 1, you can enter
+<userinput>megan:1</userinput> or alternatively as
+<userinput>vnc:/megan:1</userinput> into the <guilabel>Remote
+desktop:</guilabel> combo box.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Entering a hostname into &krdc;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_vncentry.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_vncentry.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Entering a hostname into &krdc;</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+Similary, if you are using a <acronym>RFB</acronym> server on that
+machine, you can enter <userinput>rfb:/megan</userinput>. RFB does not
+need the screen number to be specified.
+</para>
+
+</sect2>
+
+<sect2><title>Using an invitation</title>
+<para>
+Within the &krfb; server application, it is possible to send
+invitations over email (and in other ways, although email is the most
+useful). If you receive this type of email invitation, you can just
+click on the link provided in the mail. 
+This will start &krdc; if it is not already running, and connect to
+the server specified in the invitation.
+</para>
+
+</sect2>
+
+<sect2><title>Using Service Location Protocol</title>
+<para>
+The third way to use &krdc; is to browse using Service Location
+Protocol. A list of compatible servers that are registered with the
+Service Location Protocol system is shown in a list in the center of
+the main window:
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; showing service browsing</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; showing service browsing</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<note>
+<para>
+If your main window doesn't contain the table, remember that you can
+use the <guibutton>Browse &gt;&gt;</guibutton> to get back to the full
+&krdc; window. Also, not all compatible servers support automatic
+registration - one that does is the &krfb; server which is part of
+&kde;.
+</para>
+</note>
+
+<para>
+If you click once on an entry in the table, it will be selected, and
+you can use the <guibutton>Connect</guibutton> to establish a
+connection to the server. As a short-cut, you can just double-click on
+an entry, which will also establish a connection.
+</para>
+
+<para>
+While Service Location Protocol will usually detect new servers
+becoming available, you can also force the &krdc; to scan for new
+servers. This is done using the <guibutton>Rescan</guibutton>. When
+you ask for a scan, the button is disabled (greyed out) while the scan
+is being performed - this typically takes a few seconds.
+</para>
+
+<para>
+When using Service Location Protocol, the concept of Scopes is
+important. If there are a lot of services being advertised, it can
+become unwieldy to scan through a list. A re-scan can also produce
+a lot of network traffic. To avoid this problem, administrator's can
+configure Service Location Protocol with a set of Scopes, and only
+register services in certain scopes. For example, a host may be
+registered in the "third_floor" scope and the "logistics" scope, but
+not in the "engineering" scope or "maintenance" scope. In smaller
+setups, everything is only registered in the "DEFAULT" scope. &krdc;
+supports selection of a scope other than "DEFAULT", using the
+<guilabel>Scope:</guilabel> drop-down box in the top right hand corner
+of the main window.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="connection"><title>What happens when you connect</title>
+
+<para>
+No matter how you select the server to connect to, the next thing that
+happens is that &krdc; asks you about the network connection to the
+server, as shown below:
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; connection speed selection</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_connectionspeed.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="snapshot_connectionspeed.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; connection speed selection</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+There are three speed settings:
+</para>
+
+<itemizedlist>
+<listitem><para>High Quality (LAN, direct connection), which is the
+default, and you should evaluate how well this setting performs before
+selecting a lower performance option that uses less bandwidth.
+</para></listitem>
+<listitem><para>Medium Quality (DSL, Cable, fast
+Internet).</para></listitem>
+<listitem><para>Low Quality (Modem, ISDN, slow
+Internet).</para></listitem>
+</itemizedlist>
+
+<para>
+If you always operate over the same link type, you can deselect the
+checkbox labelled <guilabel>Show this dialog again for this
+host</guilabel>, which means that you won't be asked about the
+connection type again for this host, providing you identify it in the
+same way. For example, if a host has two names, and deselect the
+checkbox when connecting using one name, you won't get asked if you
+connect using that name, although you will be asked if you use the
+other name, or the IP address.
+</para>
+
+<para>
+You select the appropriate speed setting, and select the
+<guibutton>Connect</guibutton> to proceed.
+</para>
+
+<para>
+You will then see a small window containing a progress bar, which
+fills in as &krdc; negotiates the connection.
+</para>
+
+<para>
+Depending on the configuration of the server, you may (and almost
+certainly will) need to provide a password to authenticate to the
+server. &krdc; will provide a password dialog similar to that shown
+below. 
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; password entry</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="authentication.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="authentication.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; password entry</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+After authentication, you will be connected to the remote server, and
+can begin using &krdc; to observe or control the remote desktop.
+</para>
+
+</sect1>
+
+<sect1 id="controlling-remote"><title>Controlling the remote desktop connection</title>
+
+<para>
+Having connected to the remote server, you would normally use the
+keyboard and mouse to control the windowing system and applications on
+that remote machine. 
+</para>
+
+<para>
+You can view the remote desktop either as a full screen, or as a
+window on the local desktop. You can change between these modes using
+icons shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; full screen mode selection</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="window_fullscreen.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; full screen mode selection</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; window mode selection</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="window_nofullscreen.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; window mode selection</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+Full screen mode is normally better when you are helping a remote
+user, because you can see all of what they can see. Window mode is
+most useful when you are working both remotely and locally - perhaps
+referring to some local documentation and then using those
+instructions on the remote machine.
+</para>
+
+<sect2><title>Using window mode</title>
+
+<para>
+&krdc; in window mode looks something like the screenshot below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; window</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="krdc_window.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="krdc_window.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; window</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+In window mode, you can terminate the connection by closing the window.
+</para>
+
+</sect2>
+
+<sect2><title>Using full screen mode</title>
+
+<para>
+In full screen mode, you can terminate the connection by selecting the
+red "close" icon, which is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; close icon</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="close.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; close icon</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="managing-configuration"><title>Managing &krdc; configuration</title>
+<para>
+Using the <guibutton>Preferences...</guibutton> button in the bottom
+left hand corner of the the &krdc; main window, you can open a dialog
+to modify the behaviour of &krdc;. Selecting that button brings up a
+window as shown below:
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; preferences - Host Profiles tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_profilestab.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_profilestab.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; preferences - <guilabel>Host Profiles</guilabel> tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; preferences - <guilabel>VNC Defaults</guilabel> tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_vncdefaultstab.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_vncdefaultstab.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; preferences - <guilabel>VNC
+Defaults</guilabel> profiles tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+<screenshot>
+<screeninfo>&krdc; preferences - <guilabel>RDP Defaults</guilabel> tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_rdpdefaultstab.png" format="PNG"/>
+	  </imageobject>
+	  <imageobject>
+	    <imagedata fileref="preferences_rdpdefaultstab.eps" format="EPS"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&krdc; preferences - <guilabel>RDP
+Defaults</guilabel> profiles tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+
+</sect1>
+
+</chapter>
+
+<chapter id="dcop">
+<title>Developer's Guide to &krdc;</title>
+
+<para>
+&krdc; supports a small number of &DCOP; commands, which are described
+in this chapter. If you aren't familiar with &DCOP;, then you don't
+need to worry about this. However if you'd like to automate some of
+your &krdc; (or other &kde; application) actions, &DCOP; is a useful
+tool. You can find out more about &DCOP; in its on-line documentation,
+and in tutorials on <ulink
+url="http://developer.kde.org">http://developer.kde.org</ulink>.
+</para>
+
+<para>
+You can shut down the &krdc; application using the quit command, as
+shown in this example:
+</para>
+
+<informalexample>
+<screen>
+<prompt>&percnt;</prompt>dcop krdc-25550 MainApplication-Interface quit
+</screen>
+</informalexample>
+
+<note>
+<para>
+You will need to change the <userinput>krdc-25550</userinput> in the
+example to match the instance of &krdc; that you actually want to
+shutdown. If you run <command>dcop</command> with no options, you will
+get a list of all applications that are running and &DCOP; can
+control.
+</para>
+</note>
+
+</chapter>
+
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+<!-- (OPTIONAL but recommended) This chapter should include all of the silly
+(and not-so-silly) newbie questions that fill up your mailbox. This chapter
+should be reserved for BRIEF questions and answers! If one question uses more
+than a page or so then it should probably be part of the
+"Using this Application" chapter instead. You should use links to
+cross-reference questions to the parts of your documentation that answer them.
+This is also a great place to provide pointers to other FAQ's if your users
+must do some complicated configuration on other programs in order for your
+application work. -->
+
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para>When I start &krdc;, I get a message box that reads
+<computeroutput> Browsing the network is not possible. You probably
+did not install SLP support correctly.</computeroutput>
+What is wrong?</para> 
+</question>
+<answer>
+<para>SLP is Service Location Protocol, and is typically provided by
+<application>OpenSLP</application>, or by <application>The
+Knot</application>. </para>
+<para>
+If you compiled &krdc; yourself, this probably
+means that &krdc; has been compiled against the SLP libraries, but
+the server (probably called <command>slpd</command> or
+<command>knotd</command>) isn't running. You normally need to start
+these servers as the superuser, which may mean requesting that your
+system administrator does this, if you can't do this yourself.
+</para>
+<para>
+If you are running a packaged version of &krdc;, then you may have some missing
+dependencies. There are so many ways this can happen that you'd need
+to seek support from whoever did the packaging.</para>
+</answer>
+</qandaentry>
+</qandaset>
+
+</chapter>
+
+<chapter id="credits">
+
+<!-- Include credits for the programmers, documentation writers, and
+contributors here. The license for your software should then be included below
+the credits with a reference to the appropriate license file included in the KDE
+distribution. -->
+
+<title>Credits and License</title>
+
+<para>
+&krdc;
+</para>
+<para>
+Program copyright 2002 Tim Jansen <email>tim@tjansen.de</email>
+</para>
+<para>
+Contributors:
+<itemizedlist>
+<listitem><para>Ian Reinhart Geiser <email>geiseri@kde.org</email></para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+Documentation Copyright &copy; 2003 &Brad.Hards; &Brad.Hards.mail;
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+
+&underGPL;        	 <!-- GPL License -->
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-krdc">
+<title>How to obtain &krdc;</title>
+
+<!-- This first entity contains boiler plate for applications that are
+part of KDE CVS.  You should remove it if you are releasing your
+application --> 
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+<!-- This entity contains the boilerplate text for standard -->
+<!-- compilation instructions.  If your application requires any -->
+<!-- special handling, remove it, and replace with your own text. -->
+
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->