Difference between revisions of "PXML specification"

From Pandora Wiki
Jump to: navigation, search
(merged PXML archetype)
(Removing redundant outdated information)
 
Line 1: Line 1:
This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]].
+
This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]]. To see examples you can base your own on to get quickly up-to-speed, see [[#Example_files|below]]
  
'''Attention:''' at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.
+
{{Warning | At the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.}}This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in <code>.pnd</code>-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.
 
 
This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in <code>.pnd</code>-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.
 
  
 
A PXML file should be appended to your <code>.pnd</code>-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name <code>PXML.xml</code> (not case sensitive) and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.
 
A PXML file should be appended to your <code>.pnd</code>-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name <code>PXML.xml</code> (not case sensitive) and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.
Line 534: Line 532:
 
'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ''<!--pre HF6 compatibility-->'' and include those blocks in your pxml file.
 
'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ''<!--pre HF6 compatibility-->'' and include those blocks in your pxml file.
  
{{OutOfDate}}
+
== Examples ==
This PXML archetype section is outdated. Please have a look at the '''example files provided in git''':
+
 
 +
Please have a look at the '''example files provided in git''':
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/average-case_PXML.xml average-case_PXML.xml]: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/average-case_PXML.xml average-case_PXML.xml]: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
Line 542: Line 541:
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-libpnd_PXML.xml minimum-libpnd_PXML.xml]: This is a minimum example that will work on the pandora, but is '''not''' following the schema and lots of information that will be required for repositories based on the PXML specs is not available.
 
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-libpnd_PXML.xml minimum-libpnd_PXML.xml]: This is a minimum example that will work on the pandora, but is '''not''' following the schema and lots of information that will be required for repositories based on the PXML specs is not available.
  
 
 
'''WARNING!!!'''
 
 
'''Everything below this point is outdated!''' Please rely on the [[PXML_specification]] and the examples linked above!
 
 
 
 
 
 
 
 
 
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. It does no longer follow the schema specification and is not using "good style", but does provide some more in detail description. that can be adapted to "good" files, too. Please have a look at the list above to see some example files.
 
<source lang="xml">
 
<?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 (&lt; &gt; &amp; 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.
 
 
      NOTE: If you type 'name=""', this won't mean that you left out the
 
      name! It only means that the name of the author is 0 characters
 
      long! Implementations will e.g. display an empty 'Author: ' field
 
      if you do this!
 
 
      To leave out the name of the author, remove the attribute completely,
 
      and to leave out author information completely, remove the whole tag.
 
      -->
 
    <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>
 
</source>
 
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 03:01, 28 October 2013

This article covers the specification for PXML files. To see the specification for PND repository files, please see the PND repository specification. To see examples you can base your own on to get quickly up-to-speed, see below


This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in .pnd-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.

A PXML file should be appended to your .pnd-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name PXML.xml (not case sensitive) and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.

The following specification is based on what the latest version of the PXML_schema.xsd definition accepts as valid data. Files that do not pass the validation might still work as expected, but if the validation is passed you can be (almost) 100% sure that it is supposed to be correct.

Contents

XML compatibility

The PXML format is XML-based and fully XML-compliant, which means that it can be read and written by any XML reader or writer. Included with this specification should also be a .xsd-file, which is used by XML tools to validate PXML files. A .xsd-file is also known as a XML schema, and can be called the "computer-readable" version of this document. It is very good practice to validate your PXML-files with that schema before publishing them.

To write a PXML file, you also need to know the basics of writing a XML file. It boils down to the following:

  1. If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like (1)
  2. If an element does not contain other elements or text, but only attributes, it looks like (2)
<exampleelement someattribute="something">something inside it</exampleelement> <!-- (1) -->
<exampleelement2 someattribute="something"/> <!-- (2) -->

General format

The PXML-file is split up into multiple so-called elements, each of which specify one property of the .pnd-package. All of these elements are surrounded with a <PXML> tag, which tells the readers of the file that the data within that tag belongs to a PXML file. The tag and elements should be defined as follows:

The <PXML> tag

Description

The <PXML> tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file.

Attributes

xmlns 
The "xmlns" attribute is required by the XML standard, and guarantees that this file will be identified as a PXML file. You must include the xmlns attribute, exactly as shown, in your PXML file, with the URL as specified. Only then can it be guaranteed that the file will be read at all by launchers and menu apps.

Required Children

<package> 
(exactly one) See The <package> area
<application> 
(one or more) See The <application> area

Example

<PXML xmlns="http://openpandora.org/namespaces/PXML">
  <!--All of the PXML elements should be put here-->
</PXML>

The <package> area

Since PND files can contain various applications the new <package> element was introduced. It is meant to allow you to describe what the package is about. This will, at least at the moment (firmware 1 pre hotfix6), not be used by the pandora itself for detection, but is meant as tool for package repositories as well as package managers that might eventually be created.

Each PND should have one of those at the top (and only one). For single application packages this can basically be a copy of the respective areas from the <application> element.

Attributes

id
(required) The "id" attribute specifies an identifier common to all versions of a particular PND package. This can be achieved by appending some random number to your package name or by simply generating a completely random, very long identifier. A good ID may consist of the application name, developer name and some key, for example battlejewels.skeezix.001 or quake-1.pickle.001.
The package ID allows repositories to identify different versions of the same package and therefore determine whether that package should be updated. The package ID should therefore not be changed if a package is merely updated.
The package ID must not include characters which would be invalid in directory or file names, such as ?, >, /, etc. Use of such characters will prevent the PND from functioning.

Required Children

<author> 
See The <author> element
<version> 
See The <version> element
<titles> 
See The <titles> element

Example

<package id="uniqueID">
  <!--All other elements described in this section (author, version...) should be put here-->
</package>

The <author> element

Description

The author element is an element that is used by the author to introduce him/herself. An author element is mandatory. It accepts the following attributes:

Attributes

name 
(required) The name attribute specifies the name of the author.
website 
(optional) The website attribute specifies the website of the author.
email 
(optional) The email attribute specifies the e-mail of the author.

Example

<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>

The <version> element

Description

The version element specifies the application version. A version element is required. It is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

Attributes

major 
(required) The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
minor 
(required) The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
release 
(required) The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
build 
(required) The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
type 
(optional You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

Example

<version major="1" minor="1" release="1" build="2" type="release"/>

The <titles> element

Description

The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute.

Required Children

<title> 
(At least one with lang="en_US" for American English)

Example

<titles>
  <title lang="en_US">Your application name</title>
  <title lang="de_DE">Dein Programmname</title>
</titles>

The <descriptions> element

Description

The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. Additional tags are optional.

The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

Required Children

<description> 
(At least one with lang="en_US" for American English)

Example

<descriptions>
  <description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
  <description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</descriptions>

The <icon> element

Description

The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

Note: Current implementation will use the PND file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So, for a PND file, all subapps will show the appended-icon regardless of the <icon> tag within the PXML.xml.

Attributes

src 
(required) The src attribute specifies the path to the image file used as the icon.

Example

<icon src="images/icon.png"/>

The <application> area

The Application-tag permits the PXML.xml container to have multiple applications within it; you should have at least one application tag-pair (for one app), though you may have many.

<application id="uniqueID" appdata="dirname">
  <!--All other elements described in this section (exec, author...) should be put here-->
</application>

The sections which follow describe the allowed elements inside <application> blocks. You can have as many applications listed in a single PXML file as you want to (though there is/was a limit in libpnd that was set to about 50 once upon the time, which might eventually be completely be removed).

Attributes

id
(required) The "id" attribute specifies an identifier for your current application, and should be something globally unique so that no two PND packages have the same id. This can be achieved by appending some random number to your application name, and to use that as your id; or to simply generate a completely random, very long id. If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur. Please put effort into generating a unique id for your PXML-file.
appdata
(optional) The "appdata" permits a directory name (NOT PATH) to be specified as preferred; if not present, the unique id provided in the ID attribute will be used. For example, we may want a unique id of Battlejewels.skeezix.3216836217382163.v001, but an appdata path of battlejewels to make it easier on the user, or to have multiple different battlejewels sharing one appdata.


Suggestions for Generating A Unique ID

A unique ID must not include directory or filename invalid characters, such as ?, >, /, etc. Any of those will cause the PND file to not function.

The unique-id should be unique against other PND files, but may be re-used by other 'application' tags within the PND; for example, you may have multiple subapps that want to share the same appdata path (which is formed based on unique-id!), so use the same unique-id. You might then have a utility application in that same PND, which needs its own appdata, and so gets its own unique-id.

A good unique id is the application name, developer name, and some key you may wish to update on occasion (should state-data become incompatible between updates, say.) Consider:

  • battlejewels.skeezix.001
  • quake-1.pickle.001

Required Children

<exec> 
See The <exec> element
<author> 
See "The <author> element" (below)
<version> 
See "The <version> element" (below)
<titles> 
See "The <titles> element" (below)
<licenses> 
See The <licenses> element
<categories> 
See The <categories> element


The <exec> element

Description

The exec element should specify all the information needed to execute your application. An exec element must be included in every PXML file. Only exactly one exec element is allowed. It accepts the following attributes:

Attributes

command 
(required) The command attribute specifies the path to the executable file. This should be a relative path to a file within the PND package. Must contain no arguments! One strategy you may need is to point to a shell script in your PND file, which in turn sets up LD_LIBRARY_PATH, determines arguments to pass, uses zenity to pop up a pre-run menu, or other trickery.
arguments 
(optional) The arguments attribute may be not present, or present with 1 or more arguments to the executable.
startdir 
(optional) The startdir attribute specifies the starting directory (Also known as the working directory) that the application should start in. This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.
standalone 
(optional) The standalone attribute specifies whether or not this application can run on its own, or if it needs parameters to run. A value of "true" or "1" means that the application can be run without parameters. A value of "false" or "0" means that the application must be run with parameters (Meaning that no icon will appear for it in a launcher; it will only be run via file associations or via the terminal).
background 
(optional) The background attribute specifies whether or not this application should run in the background, and it should be possible to switch to other apps while it is running, or if it is the only application that should be running. A value of "true" or "1" means that the application can run in the background. A value of "false" or "0" means that the application must be run as the only application.
x11 
(optional) The x11 attribute may be missing; values are one of "req", "stop", and "ignore". If "req" is set, it means the application requires X11 (and possibly could be filtered out of users display in a menu if X is not running, or perhaps such a menu would have to start X.) If "stop" is set, it means X must be not running, or temporarily shut down, for the app. If "ignore" is set, the app doesn't care if X is running or not (such as an SDL app, or a sh-script, etc.)
extraarguments
(optional) The extraarguments attribute may be missing; values here are appended to the Exec= .desktop line after everything else, and after adding a --
pnd_run.sh, when executing this, will let the dashdash arguments be handled first by the shell then fed into the PND application. Regular arguments above are quoted and shielded by pnd_run.sh so not handled/expanded by the shell or desktop environment. Example: For file associations, %f (or others) may be a desirable argument.. however, placing %f into the arguments element above will result in a literal %f being passed into the PND application; adding %f into extraarguments will result in a file associated invocation with %f expanded to the desired string, instead.
Specifically, arguments above will insert -a "foo" into the Exec= line, while extraarguments will append -- foo.

Example

A minimal (and typical) exec:

<exec command="myprogram.sh"/>


A fully loaded one:

<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option" extraarguments="%f"/>

The <author> element

Description

The author element is an element that is used by the author to introduce him/herself. An author element is mandatory. It accepts the following attributes:

Attributes

name 
(required) The name attribute specifies the name of the author.
website 
(optional) The website attribute specifies the website of the author.
email 
(optional) The email attribute specifies the e-mail of the author.

Example

<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>

The <version> element

Description

The version element specifies the application version. A version element is required. It is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

Attributes

major 
(required) The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
minor 
(required) The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
release 
(required) The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
build 
(required) The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
type 
(optional) You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

Example

<version major="1" minor="1" release="1" build="2" type="release"/>

The <osversion> element

Description

The osversion element specifies the minimal OS version that supports the PND file. The PND file will not be loaded by an OS that has an older version than the one specified here. If unsure, just use a '0' in the respective field.

Attributes

major 
(required) The major attribute specifies the major version number. Valid entries: non negative integers.
minor 
(required) The minor attribute specifies the minor version number. Valid entries: non negative integers.
release 
(required) The release attribute specifies the release number. Valid entries: non negative integers.
build 
(required) The build attribute specifies what build the application is at. Valid entries: non negative integers.

Example

<osversion major="1" minor="1" release="1" build="2"/>

The <titles> element

Description

The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute.

Note: This is new in HF6. For backwards compatibilty please include the <title lang="en_US"> once outside the <titles> block, too!

Required Children

<title> 
(At least one with lang="en_US" for American English)

At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

Example

<titles>
  <title lang="en_US">Your application name</title>
  <title lang="de_DE">Dein Programmname</title>
</titles>
<title lang="en_US">Your application name</title><!--pre HF6 compatibility-->

The <descriptions> element

Description

The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. Additional tags are optional.

The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

Note: This is new in HF6. For backwards compatibilty please include the <description lang="en_US"> once outside the <titles> block, too!

Required Children

<description> 
(At least one with lang="en_US" for American English)

Example

<descriptions>
  <description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
  <description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</descriptions>
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description><!--pre HF6 compatibility-->

The <icon> element

Description

The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

Attributes

src 
(required) The src attribute specifies the path to the image file used as the icon.

Note: Current implementation will use the PND file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So, for a PND file, all subapps will show the appended-icon regardless of the <icon> tag within the PXML.xml.

Example

<icon src="images/icon.png"/>

The <licenses> element

Description

The licenses element is an element that contains multiple other elements.

It contains multiple license elements. Every element represents one license (so you *can* also multilicense something). You have to provide at least one license for your application. You can basically enter anything you want, though if you are using an existing license, it is best to just enter the name and provide a link to the full version. This tag also allows you to provide links to websites with the sourcecode.

Required Children

<license> 
(At least one)

Attributes for <license>

name 
(required) The name attribute specifies what the license is called. If you don't have a real license you can also enter some short text here (please keep it short!) or just enter "other" and doN't care no more.
url 
(optional) The url attribute can be used to specify a url to the full license text.
sourcecodeurl 
(optional) The sourcecodeurl attribute can be used to specify a url to the sources.

Example

<licenses>
  <license name="GPLv2+" url="http://www.gnu.org/licenses/gpl-2.0.html" sourcecodeurl="http://pandora.org/sources/package.tar.bz2"/>
  <license name="other"/>
</licenses>

The <previewpics> element

Description

The previewpics element is an element that contains multiple other elements. A previewpics element is optional.

It contains multiple pic-elements. Every pic-element represents one preview picture. If the previewpics element is specified, it must contain at least one pic element. Use the native 800x480 LCD screen resolution, minimenu and others will scale it down as needed.

Required Children

<pic> 
(At least one)

Attributes for <pic>

src 
(required) The src attribute on a pic element specifies the path to the image file used as the preview picture.

Recommendation

If you define multiple <previewpic> elements, then set the most illustrative picture as the primary <previewpic>!
Why? Because many context use only that picture at all or at that picture at first sight and more only on demand. Examples:

  • Minimenu's preview function (toggled via "A") shows only the first picture,
  • Repo RSS feed shows only the first picture,
  • PNDManager's app info shows 1 picture at first sight, more on demand.

Currently there is no technical definition of the "primary" <previewpic>, therefore ensure that your intended primary <previewpic>

  • occurs first in the source code order,
  • has a filename that lists it first in a typical lexicographical sorting order.

What is an illustrative picture?
It should quickly give an impression of the look & feel of an application.
I.e. for video games this would mean and in-game screenshot rather than a main menu screenshot, except if the menu is just a small overlay, and the important parts of the game can still be seen.


Discussion in the developer forum

Example

<previewpics>
  <pic src="preview/pic1.jpg"/>
  <pic src="preview/pic2.jpg"/>
</previewpics>

The <info> element

Description

The "info" element allows the PXML.xml to suggest to the desktop environment or menu a file that may be shown to the user when they want to know more - be it an About, a Install Guide, a User Guide, or all of the above. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

The file can be a txt-file or an html-file, and as the PXML-app-dir or .pnd-application will be mounted, the file may in turn branch to other files should it wish to.

Developers do not need to have this element, if their app is nice and simple and just runs. If the application requires additional set up (such as Quake requiring separate pak files that cannot be included in the PND), or if you wish to include sample config files or config guidelines for something complex like DosBox, or include Pandora-specific notes.. those are all good things. But the developer is encouraged to be tasteful and not go hog-wild!

Attributes

name 
(required) the name to be shown in the menu; should be obvious that it belongs to the PND .. Quake's game PND could have "Quake 1 Setup". Don’t call it „Readme“ or similar as it will show up just like that in the big list which is the Documentations menu of XFCE, unclear to which application it belongs!
type 
(required) the mime type for the file; in the event the consuming application can map mimetypes to an appropriate executable, this would be a good way of letting the user's preferred reader come up. Should be one of text/html (for an html file) or text/plain (for a .txt file). Those two are the only types allowed if the validation against the scheme is meant to be successful.
src 
(required) A file (including path relative to the PND; ie: ./index.html would be the root of the PND) in the PND to open up; by default, the web browser will likely be used to open it.

Example

<info name="AwesomeGame Setup" type="text/html" src="index.html"/>

The <categories> element

Description

The categories element is an element that contains multiple other elements. A categories element is required, and must contain at least one category.

Menus that use your PXML in any shape or form will use the category information to sort your application entry into the tree or sub menus. Depending on the menu system, this will be done differently every time. It is therefore advisable to specify as many categories and subcategories as possible (and as suitable; don't specify that your application belongs in a category if it doesn't).

The "categories" element contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid top-level categories are (among others):

  1. AudioVideo
  2. Audio
  3. Video
  4. Development
  5. Education
  6. Game
  7. Graphics
  8. Network
  9. Office
  10. Settings
  11. System
  12. Utility

Please see the FreeDesktop specification for more information. In it, you will also find valid subcategories for your top-level categories.

The category-element takes one attribute: The name-attribute. This attribute represents the category name, which preferrably should be one of the above.

A category-element can contain further child-elements: subcategory-elements. These represent the subcategories of a category that the app will be sorted into.

The subcategory-element also takes a name-attribute; this attibute can contain a name for your subcategory.

For passing validation any category/subcategory entries have to confirm to the FDO specs linked above.

Required Children

<category> 
(At least one)

Example

<categories>
  <!-- This app belongs in the "Game/StrategyGame" category -->
  <category name="Game">
    <subcategory name="StrategyGame"/>
  </category>
  <!-- This app also belongs in the "Graphics/ImageProcessing" category -->
  <category name="Graphics">
    <subcategory name="ImageProcessing"/>
  </category>
</categories>

The <associations> element

Description

The associations element is an element that contains multiple other elements. An associations element is optional, except if exec.standalone is false (this is not checked via the schema!).

It contains one or multiple association-elements. Every association-element represents one file action association (though it is possible to put multiple mimetypes into a single association it muddies the waters so is best avoided.) The association is a request that this application may open a specified mimetype(s). Many applications may associate the same mimetype, and the desktop may offer a menu to allow one to be selected.

Note: This element is a 'recent' addition to the firmware (Super Zaxxon) - users will have to ensure they are in a late edition firmware

Required Children

<association> 
(At least one)

Attributes for <association>

name 
(required) The name attribute on an association element specifies the user-friendly action name for the association. ex: "Open PNG". It will be shown in menus, so include your app name ideally.
filetype 
(required) The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to. ex: image/png
command 
(no longer used) The command attribute is not used; most linux distributions do not allow for alternative execution methods for file associations versus standalone execution, so we have dropped this idea
arguments 
(no longer used) The arguments attribution is no longer used; see 'command' for why.

You will likely want to add an extraarguments element into the <exec> line, to contain %f or other hint; in this way the desktop environment will know to insert the filename(s), url(s), etc:

The result in the .desktop file is a Exec= line looking approximately like:

Exec=/usr/pandora/scripts/pnd_run.sh -p "/media/mysdcard/pandora/menu//ristrun.pnd" -e "run.sh" -b "ristrun" -- %f

Example

...
<exec command="myprogram.sh" extraarguments="%f"/>
...
<associations>
  <association name="Open a BMP Image" filetype="image/bmp" />
  <association name="Open a stylesheet" filetype="text/css" />
</associations>
...

The <clockspeed> element

Description

The clockspeed element specifies what clockspeed this app should run at. Please do only specify this element if your application *needs* to run at the specified clock speed. A clockspeed element is optional. It accepts the following attributes:

Attributes

frequency 
(required) The frequency attribute specifies the wanted frequency, in megahertz (MHz).

Example

<clockspeed frequency="600"/>

Example files

There are several example files available in the git repository. They do match the current specification and (unless mentioned differently) validate. Below the direct links and a short description what they are meant to show:

  • PXML.xml: This is a sample PXML.xml file making use of many different things.
  • average-case_PXML.xml: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
  • full-sample_PXML.xml: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
  • minimum-schema_PXML.xml: This is a minimum example that will validate with the schema but basically offer nothing beside what really is required. This application should work nicely with any pnd repositories based upon the PXML specs. Note: This application will not work with pre HF6, for support for OS versions up to HF6 an additional <title> block outside of <titles> is required!
  • minimum-libpnd_PXML.xml: This is a minimum example that will work on the pandora, but is not following the schema and lots of information that will be required for repositories based on the PXML specs is not available.


Validation

To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it. The schema is also available in a plaintext file described in words that are by far more compact than this page but still understandable for coders: plaintext description of the schema

The current-most XSD is in 'libpnd' (in the git repository). Here is the file history: PXML_schema.xsd file history Once on the history page, just click on the filename (right click -> save as) to download the latest version.

The easiest way to run validation is using this command:

 xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml

To run it you have to have xmllint installed and the (latest) PXML_schema.xsd definition downloaded. Using this command you can now simply evaluate if the PXML.xml file is valid. xmllint can be installed via the angstrom repository (it is part of libxml2-utils).

Attention: It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ' and include those blocks in your pxml file.

Examples

Please have a look at the example files provided in git:

  • PXML.xml: This is a sample PXML.xml file making use of many different things.
  • average-case_PXML.xml: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
  • full-sample_PXML.xml: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
  • minimum-schema_PXML.xml: This is a minimum example that will validate with the schema but basically offer nothing beside what really is required. This application should work nicely with any pnd repositories based upon the PXML specs. NOTE: This application will not work with pre HF6, for support for OS versions up to HF6 an additional <title> block outside of <titles> is required!
  • minimum-libpnd_PXML.xml: This is a minimum example that will work on the pandora, but is not following the schema and lots of information that will be required for repositories based on the PXML specs is not available.