PXML archetype
From Pandora Wiki
This is a template for PXML files. It covers most of the spec and is considered to be clean, meaning that it can be used as a sane starting point for PXML write-ups.
<?xml version="1.0" encoding="UTF-8"?>
<!--This is an example PXML file for an application named "Exaile", to
demonstrate how a PXML file is supposed to be structured. Feel free to
replace all of the field contents with your own data, and to remove these
comments afterwards, in order to get a working and valid PXML file.
Note that this file is MINIMAL aka. this is the information you SHOULD
specify if you're well-behaved (all of it isn't NEEDED per-se, though) -->
<!--
PXML tag
Indicates the root node of a PXML file.
Attributes:
xmlns:
Identifies the namespace of this PXML file. Potential future PXML
specifications will use a different name space.
-->
<PXML xmlns="http://openpandora.org/namespaces/PXML">
<!--
application tag
Declares a new application that this PND package provides. Most PND
packages will only have one application entry, and it is discouraged to
have too many application entries in one PND file, since a PND file is
inseparable, i.e. an user cannot upgrade one app and leave another be if
they share the same PND file.
Attributes:
id:
Identifies the application in application enumerations.
This has to be a string that is unique to the package series; there
must not be two packages with entirely different purposes and
origins that share the same ID.
tl;dr: Choose an id like you would choose a package name on the
Linux Desktop.
Some things you have to consider when choosing an id:
- If you release new versions of your application, they should have
the same id as previous versions. Packages with different id's
are not considered to be related at all, while packages with
identical id's are considered to be of the same kind.
- Your id should not be too complex. You should choose something
that is unique to your application, and not something globally
unique.
- The application id will be used by package managers and the like.
So, choose something that you expect to be typed in as:
"installtool install %id%"
If you are publishing an application that you created yourself,
and that you don't expect anyone else to also publish, these
would be GOOD id's:
- "exaile"
- "myapp"
- "kdemod-extras-quassel"
- "awesome-music-player"
These would be BAD id's:
- "Exaile" - This is an user-adapted name and not a machine-
adapted name
- "Exaile - A music player that rocks" - This contains spaces and
might therefore be mistreated by shell scripts and the like.
- "exaile-1.0" - This contains version information; you should
put this information in the version tag below instead.
- "exaile-written-by-foobar-in-the-year-of-the-lord-two-thousand-and-ten-and-given-to-yall-for-free"
This is too long.
- "ae4c8bc112cafedd" - This doesn't identify *the application*, but
is just a random unique identifier.
These would be GOOD id's if you PORTED or MODDED an existing
application:
- "exaile-dflemstr" - (port) The app was ported by dflemstr
- "exaile-nox" - (mod) The app runs without X
- "exaile-player" - (port) Only a part of the application was
ported
- "exaile-pure" - (mod) Substantial mods were carried through, and
a rebranding was needed.
appdata:
Specifies a name for a data store for your application
This is where all your writes to CWD will end up when you run
your application. You should choose an user friendly name, but
*not* an user-adapted name (think about localization and
management).
Good alternatives:
- "exaile"
- "exaile-1" - If you intend to release newer versions that use
a different storage format.
- "exaile-dev" - If you want an user to be able to use a dev
version of your app, and a stable version of your app
simultaneously.
-->
<application id="exaile" appdata="exaile">
<!--
title tag(s)
Defines a human-readable title for the application in a specified locale.
You MUST specify a title with the language "en_US"; other localizations
are optional, but it is recommended to add one for generic,
not-only-american english ("en"). Titles and descriptions should also be
in pairs (you should not translate a title and omit a translation for a
description).
Attributes:
lang:
Specifies the language of the title.
This is made up of two parts:
- The language part. This code is the lower-case, two-letter
code as defined by ISO-639.
- OPTIONAL: The country part. This code is the upper-case,
two-letter code as defined by ISO-3166, with an underscore
as the prefix.
-->
<title lang="en_US">Exaile music player</title>
<title lang="sv">Exaile musikspelare</title>
<title lang="de">Exaile musikspieler</title>
<!--
description tag(s)
Defines a human-readable description for your application in a specified
locale. The same rules apply to this element, as to title elements. Note
that we by description don't mean page-long texts; the recommended length
for a description is 128 characters, but certain implementations support
up to 1024 or 4096 characters. More than that is absolutely not
recommended. Also, please remember that newlines are ignored in
descriptions according to the XML standard, but that spaces are
significant. XML escaping applies for the characters less-than,
greater-than and ampersand (< > & respectively).
Attributes:
lang:
See above.
-->
<description lang="en_US">A versatile music player written in Python.</description>
<description lang="sv">En kraftfull musikspelare skriven i Python.</description>
<description lang="de">Ein fähiger Musikspieler, in Python geschrieben.</description>
<!--
version tag
This specifies the version quadron for this application.
ALL FIELDS MUST BE POSITIVE INTEGERS OR 0. You are free to choose your
own versioning scheme (ie. "build" doesn't have to be the number of times
you built the application), but you must specify all four version fields
below.
-->
<version major="1" minor="0" release="0" build="2"/>
<!--
exec tag
Declares how the application should be started.
Attributes:
command:
The executable to start when the program is launched. This is
a path relative to the root of your PND file.
arguments:
Does the app need to be started with certain arguments every
time it is run? This is useful for PNDs that contain
multiple applications that use the same executable file.
(specify the actual arguments, not true/false unless your app
accepts true or false as arguments!)
background:
Can this application "be minimised" or should it run
singleton?
"true", "false", "1" or "0" accepted.
startdir:
Sets the CWD for the application before it is run.
Default is the PND mount point.
standalone:
Can this application run directly, or should it only be
started via associations? If this is "false" or "0", it
won't show up in launchers.
x11:
Can be one of:
"req" - X11 is required for the application to run.
"stop" - X11 must be stopped for the application to run.
"ignore" (default) - Don't care about X11.
-->
<exec command="./bin/exaile" background="true" standalone="true"/>
<!--
author tag
Contains information about the application author. All three fields
are optional.
-->
<author name="Bjornhild Andersson" website="http://some.website.with.author.info" email="a.b@c.de"/>
<!--
icon tag
Declares the icon for the application. This should be the same icon that
is appended to the PND file, or something different if *this* application
should have a different icon from the rest.
Attributes:
src:
Relative URI to the icon (can be a relative file, or a
fully-qualified URL; the latter is only supported in some
implementations)
-->
<icon src="icon.png"/>
<!--
categories tag
Specifies which categories this application belongs to. See
http://standards.freedesktop.org/menu-spec/latest/apa.html for more
information. The optional sub-element "subcategory" is currently ignored
by all implementations.
-->
<categories>
<category name="Audio"/>
<category name="Music"/>
<category name="GTK"/>
</categories>
</application>
</PXML>
