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

This HOWTO describes the procedures for creating a user-agent description
file to extend the ones that come pre-packaged with KDE.  The user-agent
description desktop files are used to create list of addresses for sites
which unfortunately require "faked" identities in order to be displayed
properly.

In order to create new user-agent description files, simply follow the normal
the specification set by the "DESKTOP ENTRY STANDARD" augmented with the
following entries and 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 show 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-KDE-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-KDE-UA-NAME).

X-KDE-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-KDE-UA-DYNAMIC-ENTRY field
and set its value to 1 (for true).

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

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

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

X-KDE-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-KDE-UA-DYNAMIC-ENTRY
FIELD:        OPTIONAL
TYPE:         BOOLEAN (0/1)
TRANSLATE:    NO
DESCRIPTION:
A boolean that indicates whether the keywords described under
X-KDE-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-KDE-UA-TAG=IE
X-KDE-UA-FULL=Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)
X-KDE-UA-NAME=Internet Explorer
X-KDE-UA-VERSION=5.5
X-KDE-UA-SYSNAME=Windows
X-KDE-UA-SYSRELEASE=98

[Desktop Entry]
Name=UADescription (NN 4.76 on current)
Type=Service
ServiceTypes=UserAgentStrings
X-KDE-UA-TAG=NN
X-KDE-UA-FULL=Mozilla/4.76 (appPlatform; U; appSysName appSysRelease appMachineType)
X-KDE-UA-NAME=Netscape Navigator
X-KDE-UA-VERSION=4.76
X-KDE-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 "keyword"
usage to describe fields that should be replaced dynamically based on
the current system settings.

Enjoy,
Dawit A.
