Mini HOWTO create a "User-Agent" description file for KDE
=========================================================

This mini HOWTO describes the procedure for creating a new user-agent 
description file to extend the ones that come pre-packaged with KDE. 
The purpose of a user agent description file is to fake or spoof sites 
that refuse to render pages with the default KDE user-agent identification.

In order to create new user-agent description files, simply follow the
normal desktop file specifications set by the "DESKTOP ENTRY STANDARD"
augmented with the following requirements:

REQUIREMENTS:
=============
The following properties as defined by the DESKTOP ENTRY STANDARD
must be set as shown below:

Name=UADescription (XXXX)
Type=Service
ServiceTypes=UserAgentStrings

Though the (XXXX) value shown above can be any text, it is a good idea 
to make it a short identification of the browser being emulated.  However,
there is NO requirement on what the text should be.  It can even be left 
out. It is only meant to give people a quick idea which browser is being
emulated by your desktop file.

NEW PROPERTIES:
===============
X-TDE-UA-TAG
FIELD:        REQUIRED
TYPE:         QString
TRANSLATE:    NO
DESCRIPTION:
An abbreviation of the actual browser-brand and is used
to group the entries whenever necessary. Currently there are 5
approximations: IE, NN, MOZ, OP, MISC. These represent Internet
Explorer, Netscape Navigator, Mozilla, Opera and Miscellaneous
respectively. NOTE: you can enter any value here as it is just
a place holder that would be automatically replaced with the
actual user-agent name (X-TDE-UA-NAME).

X-TDE-UA-FULL
FIELD:        REQUIRED
TYPE:         QString
TRANSLATE:    NO
DESCRIPTION:
The full user-agent description that will be sent to the remote
site. It can contain the following keywords that would be replaced
with the appropriate value as defined by "uname":

appSysName          the name of the operating system (ex: Linux).
appPlatform         the name of the platform.  Currently hardcoded to "X11".
appLanguage         the language values as set in the control panel (ex: en, en-US).
appSysRelease       the version of the operating system (ex: 2.2.18).
appKDERelease       the current release number as set by KDE (ex: 2.1.9 >=20010310).
appMachineType      the processor or machine type (ex: i686).

NOTE: if you use any of these values and want them to be replaced
automatically, make sure you include the X-TDE-UA-DYNAMIC-ENTRY field
and set its value to 1 (for true).

X-TDE-UA-NAME
FIELD:        REQUIRED
TYPE:         QString
TRANSLATE:    YES
DESCRIPTION:
The actual name of the browser or user-agent.

X-TDE-UA-VERSION
FIELD:        REQUIRED
TYPE:         QString
TRANSLATE:    YES
DESCRIPTION:
The actual version of the browser or user-agent.

X-TDE-UA-SYSNAME
FIELD:        OPTIONAL
TYPE:         QString
TRANSLATE:    YES
DESCRIPTION:
The system name (for example Linux) where the browser
identification was obtained from.

X-TDE-UA-SYSRELEASE
FIELD:        OPTIONAL
TYPE:         QString
TRANSLATE:    YES
DESCRIPTION:
The system version (for example 2.4.1) where the browser
identification was obtained from.

X-TDE-UA-DYNAMIC-ENTRY
FIELD:        OPTIONAL
TYPE:         BOOLEAN (0/1)
TRANSLATE:    NO
DESCRIPTION:
A boolean that indicates whether the keywords described under
X-TDE-UA-FULL should be translated.  Make sure this field is
there with its value set to "1" if you want the keywords to
be replaced appropriately.


EXAMPLES:
=========
[Desktop Entry]
Name=UADescription (IE 5.5 on Win 98)
Type=Service
ServiceTypes=UserAgentStrings
X-TDE-UA-TAG=IE
X-TDE-UA-FULL=Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)
X-TDE-UA-NAME=Internet Explorer
X-TDE-UA-VERSION=5.5
X-TDE-UA-SYSNAME=Windows
X-TDE-UA-SYSRELEASE=98

[Desktop Entry]
Name=UADescription (NN 4.76 on current)
Type=Service
ServiceTypes=UserAgentStrings
X-TDE-UA-TAG=NN
X-TDE-UA-FULL=Mozilla/4.76 (appPlatform; U; appSysName appSysRelease appMachineType)
X-TDE-UA-NAME=Netscape Navigator
X-TDE-UA-VERSION=4.76
X-TDE-UA-DYNAMIC-ENTRY=1

The first entry is a description file for Internet Explorer running on
a Windows 98 machine while the second one is an example of a description
file for Netscape browser using the "keyword" based approach to describe 
the fields that should be replaced dynamically based on the current system 
settings. Note that all "keyword" based desktop files should always set
X-TDE-UA-DYNAMIC-ENTRY to 1.

Enjoy,
Dawit A.