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

1 files changed, 129 insertions, 0 deletions

diff --git a/kdelirc/README.remote-creation b/kdelirc/README.remote-creation
new file mode 100644
index 0000000..3582351
--- /dev/null
+++ b/kdelirc/README.remote-creation
@@ -0,0 +1,129 @@
+How to give your LIRC remote control KDELIRC functionality
+==========================================================
+
+by Gav Wood, 2003.
+
+Introduction
+------------
+
+All LIRC-understandable remote controls automatically function in KDELirc.
+However, to get the advanced (really cool) KDELirc stuff you'll need to create a
+remote.xml file for your remote control. The files are simple and easy to create
+so don't be put off.
+
+The function of the remote.xml file is to describe what the remote controls'
+buttons do in a general manner and to provide free-form text names for them,
+since LIRC only allows non-spaces, non-symbolic charecters in the remote control
+definition files.
+
+When you're finished your remote.xml, you might want to send it to me
+(gav at kde dot org) for inclusion in the distribution of KDELirc. It may soon
+be possible to distribute the remote.xml files along with the lircd.conf files.
+
+Method
+------
+
+a) Start with the basic template and define the LIRC ID of the remote control.
+The LIRC ID is most important, and must be the identifier (look for the line
+"name <...>" after the "begin remote" line). put the text after "name" into "id"
+attribute of the "remote" tag in the "lircd.conf" file ("/etc/lircd.conf").
+   In addition to this, fill in the author and name tags with your name and the
+"nice" name of the remote control. Any extra information you may wish to give it
+(such as alternate names, multimedia bundles/system is comes with etc) may be
+enclosed between optional information tags:
+
+	<?xml version="1.0" ?>
+	<!DOCTYPE remote SYSTEM "remote.dtd">
+
+	<remote id="myremote">
+		<name>My Remote Control</name>
+		<author>Me</author>
+		<information>As bundled with ACME LinTV</information>
+	</remote>
+
+This would compliment a "lircd.conf" file:
+
+	begin remote
+	  name myremote
+	  ...
+	end remote
+
+b) With the hard work out of the way, just start going though each button on the
+remote control. For each button, make sure the "id" attribute is the same as in
+the lircd.conf file.
+   For each (common) button, you might also want to specify the class, which will
+help KDELirc match it to any application's action. For a list of all button
+classes, look in the remote.dtd file which comes with KDELirc. If the class type
+is one which encompasses many buttons, for example "number", then you should also
+specify which number it is in the parameter attribute. Currently, this only
+actually applies to "number" - all other classes are simple and do not require a
+parameter attribute.
+   Note: If no "class" is given, it will default to the "id". In the unlikely
+case that this is not what you want, simply define it to be null (class="").
+
+	<?xml version="1.0" ?>
+	<!DOCTYPE remote SYSTEM "remote.dtd">
+
+	<remote id="myremote">
+		<name>My Remote Control</name>
+		<author>Me</author>
+		<button id="num0" class="number" parameter="0">
+		</button>
+		<button id="rec" class="record">
+		</button>
+	</remote>
+
+This would compliment a "lircd.conf" file:
+
+	begin remote
+	  name myremote
+	  ...
+	  begin raw_codes
+	    name num0
+	    ...
+	    name rec
+	    ...
+	  end raw_codes
+	end remote
+
+c) The last thing to define in each of your buttons is the "nice" name. This may
+be descriptive and use spaces, symbols and mixed case text, in a similar fashion
+to the remote control's name. There is no need to copy the remote control's label
+verbatim. If necessary expand the description to provide a readable, aethetically
+pleasing label e.g. you should name the "CC" button "Closed Captions" or the "Rec"
+button "Record".
+
+	<?xml version="1.0" ?>
+	<!DOCTYPE remote SYSTEM "remote.dtd">
+
+	<remote id="myremote">
+		<name>My Remote Control</name>
+		<author>Me</author>
+		<button id="num0" class="number" parameter="0">
+			<name>0</name>
+		</button>
+		<button id="rec" class="record">
+			<name>Record</name>
+		</button>
+	</remote>
+
+   Note: The name of a button will automatically default to its "id", so you can
+save yourself some time and effort with buttons which share the same name and id
+by changing
+
+		<button id="num0" class="number" parameter="0">
+			<name>0</name>
+		</button>
+
+to the far less cluttered and simpler:
+
+		<button id="num0" class="number" parameter="0"/>
+
+That's it - just save it as <id>.remote.xml, where <id> is the ID of the remote
+control (*not* its name but the LIRC id!) and copy it to your KDE remotes data
+directory (~/.kde/share/apps/remotes).
+
+   You'll probably need to restart control center before the remote definition
+is recognised.
+
+Gav Wood <gav at kde dot org>
\ No newline at end of file