Difference between revisions of "PXML specification"

From Pandora Wiki
Jump to: navigation, search
(→‎Example file)
(Removing redundant outdated information)
 
(61 intermediate revisions by 13 users not shown)
Line 1: Line 1:
−
'''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. Please wait until this standard is finished before writing a PXML file.
+
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]]
  
−
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.
+
{{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.
  
−
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.
+
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.
 +
 
 +
The following specification is based on what the latest version of the <code>PXML_schema.xsd</code> 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.
  
 
== XML compatibility ==
 
== 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.
+
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 <code>.xsd</code>-file, which is used by XML tools to validate PXML files. A <code>.xsd</code>-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:
 
To write a PXML file, you also need to know the basics of writing a XML file. It boils down to the following:
Line 14: Line 16:
 
<source lang="xml">
 
<source lang="xml">
 
<exampleelement someattribute="something">something inside it</exampleelement> <!-- (1) -->
 
<exampleelement someattribute="something">something inside it</exampleelement> <!-- (1) -->
−
<exampleelement2 someattribute="something" /> <!-- (2) -->
+
<exampleelement2 someattribute="something"/> <!-- (2) -->
 
</source>
 
</source>
  
−
== Format ==
+
== 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-file is split up into multiple so-called elements, each of which specify one property of the <code>.pnd</code>-package. All of these elements are surrounded with a <code><PXML></code> 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 ===
+
=== The <PXML> tag ===
 
==== Description ====
 
==== Description ====
−
The PXML-tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file. An example "<PXML>"-tag would look like this:
+
The <code><PXML></code> 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 ====
 +
; <code><package></code> : ''(exactly one)'' See [[#The <package> area|The <package> area]]
 +
; <code><application></code> : ''(one or more)'' See [[#The <application> area|The <application> area]]
 +
 +
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<PXML xmlns="http://openpandora.org/namespaces/PXML" id="uniqueID">
+
<PXML xmlns="http://openpandora.org/namespaces/PXML">
 
   <!--All of the PXML elements should be put here-->
 
   <!--All of the PXML elements should be put here-->
 
</PXML>
 
</PXML>
 
</source>
 
</source>
  
−
As you can see, the PXML tag accepts a few attributes, namely the "id" and "xmlns" attributes.
+
== The <package> area ==
 +
Since PND files can contain various applications the new <code><package></code> 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 <code><application></code> element.
  
−
* 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.
+
==== Attributes ====
−
* '''DEPRECATED; SEE "application" tag.''' The "id" attribute specifies an identifier for your PND package, 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 an unique id for your PXML-file.
 
  
−
=== The Application-tag ===
+
; id
−
====Description====
+
: ''(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 <code>battlejewels.skeezix.001</code> or <code>quake-1.pickle.001</code>.
−
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.
+
: 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 ====
 +
; <code><author></code> : See [[#The <author> element|The <author> element]]
 +
; <code><version></code> : See [[#The <version> element|The <version> element]]
 +
; <code><titles></code> : See [[#The <titles> element|The <titles> element]]
  
 +
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<application id="uniqueID">
+
<package id="uniqueID">
−
   <!--All of the PXML elements should be put here-->
+
   <!--All other elements described in this section (author, version...) should be put here-->
−
</application>
+
</package>
 
</source>
 
</source>
  
−
* The "id" attribute specifies an identifier for your PND package, 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 an unique id for your PXML-file.
+
=== 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:
  
−
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.)
+
==== 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 ====
 +
<source lang="xml">
 +
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
 +
</source>
  
−
Consider:
+
=== The <version> element ===
−
battlejewels.skeezix.001
+
==== Description ====
−
quake-1.pickle.001
+
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:
  
−
unique-id formatting: '''Should not include directory or filename invalid characters, such as ?, >, /, etc. Any of those will cause the pnd-file to not function.'''
+
==== 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.
  
−
Note on Uniqueness: 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.
+
==== Example ====
 +
<source lang="xml">
 +
<version major="1" minor="1" release="1" build="2" type="release"/>
 +
</source>
  
−
=== The title element ===
+
=== The <titles> element ===
 
==== Description ====
 
==== Description ====
 +
The titles element is an element that contains multiple other elements.
  
−
The title element specifies the text that is shown to the users of your PND file as the application title. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.
+
The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <code><titles></code> block should be one entry for each language you want to support. The first language listed should always be <code>en_US</code>. The language is indicated by the lang attribute.
  
−
At least one "title"-element is required, in the "en_US" American English language.
+
==== Required Children ====
 +
; <code><title></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<title lang="en_US">Your application name</title>
+
<titles>
−
<title lang="de_DE">Dein Programmname</title>
+
  <title lang="en_US">Your application name</title>
 +
  <title lang="de_DE">Dein Programmname</title>
 +
</titles>
 
</source>
 
</source>
  
−
=== The description element ===
+
=== The <descriptions> element ===
 
==== Description ====
 
==== 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 <code>en_US</code>. 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.
  
−
The description element specifies the text that is shown to the users of your PND file as the application description. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.
+
==== Required Children ====
 +
; <code><description></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
−
At least one "description"-element is required, in the "en_US" American English language.
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
+
<descriptions>
−
<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
+
  <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>
 
</source>
 
</source>
  
−
=== The exec element ===
+
=== The <icon> element ===
 
==== Description ====
 
==== 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:
  
−
The exec element should specify all the information needed to execute your application.
+
'''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 <code>PXML.xml</code>.
−
An exec element must be included in every PXML file. It accepts the following attributes:
 
  
−
* 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 sh-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.
+
==== Attributes ====
−
* The arguments attribute may be not present, or present with 1 or more arguments to the executable.
+
; src : ''(required)'' The src attribute specifies the path to the image file used as the icon.
−
* 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.
 
−
* 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).
 
−
* 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.
 
−
* 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.)
 
  
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option"/>
+
<icon src="images/icon.png"/>
 +
</source>
 +
 
 +
== The <application> area ==
 +
The Application-tag permits the <code>PXML.xml</code> container to have multiple applications within it; you should have at least one application tag-pair (for one app), though you may have many.
 +
 
 +
<source lang="xml">
 +
<application id="uniqueID" appdata="dirname">
 +
  <!--All other elements described in this section (exec, author...) should be put here-->
 +
</application>
 
</source>
 
</source>
  
−
=== The icon element ===
+
The sections which follow describe the allowed elements inside <code><application></code> 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 <code>Battlejewels.skeezix.3216836217382163.v001</code>, but an appdata path of <code>battlejewels</code> 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 <code>?</code>, <code>&gt;</code>, <code>/</code>, 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:
 +
* <code>battlejewels.skeezix.001</code>
 +
* <code>quake-1.pickle.001</code>
 +
 
 +
==== Required Children ====
 +
; <code><exec></code> : See [[#The <exec> element|The <exec> element]]
 +
; <code><author></code> : See "The <author> element" (below)
 +
; <code><version></code> : See "The <version> element" (below)
 +
; <code><titles></code> : See "The <titles> element" (below)
 +
; <code><licenses></code> : See [[#The <licenses> element|The <licenses> element]]
 +
; <code><categories></code> : See [[#The <categories> element|The <categories> element]]
 +
 
 +
<!-- TODO: Figure out how to disambiguate between two identically-named sections when linking or rename some of the sections. -->
 +
 
 +
=== The <exec> element ===
 
==== Description ====
 
==== 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 <code>LD_LIBRARY_PATH</code>, 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 <code>Exec=</code> <code>.desktop</code> line after everything else, and after adding a <code>--</code>
 +
: <code>pnd_run.sh</code>, 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 <code>pnd_run.sh</code> so not handled/expanded by the shell or desktop environment. Example: For file associations, <code>%f</code> (or others) may be a desirable argument.. however, placing <code>%f</code> into the <code>arguments</code> element above will result in a literal <code>%f</code> being passed into the PND application; adding <code>%f</code> into <code>extraarguments</code> will result in a file associated invocation with <code>%f</code> expanded to the desired string, instead.
 +
: Specifically, <code>arguments</code> above will insert <code>-a "foo"</code> into the <code>Exec=</code> line, while <code>extraarguments</code> will append <code>-- foo</code>.
 +
 +
==== Example ====
 +
 +
A minimal (and typical) exec:
 +
 +
<source lang="xml">
 +
<exec command="myprogram.sh"/>
 +
</source>
  
−
The icon element should specify a nice icon for your program.
 
−
An icon element is optional. It accepts the following attributes:
 
  
−
* The src attribute specifies the path to the image file used as the icon.
+
A fully loaded one:
 +
 
 +
<source lang="xml">
 +
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option" extraarguments="%f"/>
 +
</source>
 +
 
 +
=== 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:
  
−
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 ====
 +
; 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 ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<icon src="images/icon.png"/>
+
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
 
</source>
 
</source>
  
−
=== The info element ===
+
=== The <version> element ===
−
====Description====
+
==== 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:
  
−
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.
+
==== 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.
  
−
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.
+
==== Example ====
 +
<source lang="xml">
 +
<version major="1" minor="1" release="1" build="2" type="release"/>
 +
</source>
  
−
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!
+
=== 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.
  
−
* name -> 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".
+
==== Attributes ====
−
* type -> 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.
+
; major : ''(required)'' The major attribute specifies the major version number. Valid entries: non negative integers.
−
* 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.
+
; 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 ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<info name="AwesomeGame Setup" type="txt/html" src="index.html">
+
<osversion major="1" minor="1" release="1" build="2"/>
 
</source>
 
</source>
  
−
=== The previewpics element ===
+
=== The <titles> element ===
 
==== Description ====
 
==== Description ====
 +
The titles element is an element that contains multiple other elements.
  
−
The previewpics 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 <code><titles></code> block should be one entry for each language you want to support. The first language listed should always be <code>en_US</code>. The language is indicated by the lang attribute.
−
A previewpics element is optional.
+
 
 +
'''Note:''' This is new in HF6. For backwards compatibilty please include the <code><title lang="en_US"></code> once outside the <code><titles></code> block, too!
 +
<!-- TODO: These backwards compatibility messages are repeated enough that they should probably be rewritten as Mediawiki template badges to simplify things and ensure consistent phrasing. -->
 +
 
 +
==== Required Children ====
 +
; <code><title></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
−
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.
+
At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
  
−
* The src attribute on a pic element specifies the path to the image file used as the preview picture.
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<previewpics>
+
<titles>
−
   <pic src="preview/pic1.jpg"/>
+
   <title lang="en_US">Your application name</title>
−
   <pic src="preview/pic2.jpg"/>
+
   <title lang="de_DE">Dein Programmname</title>
−
</previewpics>
+
</titles>
 +
<title lang="en_US">Your application name</title><!--pre HF6 compatibility-->
 
</source>
 
</source>
  
−
=== The author element ===
+
=== The <descriptions> element ===
 
==== Description ====
 
==== 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 <code>en_US</code>. The language is indicated by the lang attribute. Additional tags are optional.
  
−
The author element is an element that is used by the author to introduce him/herself.
+
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.
−
An author element is optional. It accepts the following attributes:
+
 
 +
'''Note:''' This is new in HF6. For backwards compatibilty please include the <code><description lang="en_US"></code> once outside the <code><titles></code> block, too!
 +
<!-- TODO: These backwards compatibility messages are repeated enough that they should probably be rewritten as Mediawiki template badges to simplify things and ensure consistent phrasing. -->
 +
 
 +
==== Required Children ====
 +
; <code><description></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
−
* The name attribute specifies the name of the author.
 
−
* The website attribute specifies the website of the author.
 
−
* The email attribute specifies the e-mail of the author. This attribute is not yet supported by libpnd, but please specify it anyways.
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
+
<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-->
 
</source>
 
</source>
−
=== The version element ===
+
 
 +
=== The <icon> element ===
 
==== Description ====
 
==== 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:
  
−
The version element specifies the application version.
+
==== Attributes ====
−
A version element is required. It accepts the following 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 <code><icon></code> tag within the <code>PXML.xml</code>.
  
−
* The major attribute specifies the major version number. This number should be 0 or more.
 
−
* The minor attribute specifies the minor version number. This number should be 0 or more.
 
−
* The release attribute specifies the release number. This number should be 0 or more.
 
−
* The build attribute specifies what build the application is at. This number should be 0 or more.
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<version major="1" minor="1" release="1" build="2"/>
+
<icon src="images/icon.png"/>
 
</source>
 
</source>
−
=== The osversion element ===
+
 
 +
=== The <licenses> element ===
 
==== Description ====
 
==== 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 ====
 +
; <code><license></code> : ''(At least one)''
 +
 +
==== Attributes for <code><license></code> ====
 +
; 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.
  
−
The osversion element specifies the application version.
 
−
An osversion element is optional. It accepts the same attributes as the version element.
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
−
<osversion major="1" minor="1" release="1" build="2"/>
+
<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>
 
</source>
 
</source>
−
=== The categories element ===
+
 
 +
=== The <previewpics> element ===
 
==== Description ====
 
==== 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 ====
 +
; <code><pic></code> : ''(At least one)''
 +
 +
==== Attributes for <code><pic></code> ====
 +
; 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>!<br>
 +
''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,
 +
* [http://repo.openpandora.org/includes/rss.php Repo RSS feed] shows only the first picture,
 +
* [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager]'s app info shows 1 picture at first sight, more on demand.
 +
 +
Currently there is no technical definition of the ''"primary"'' <code><previewpic></code>, therefore ensure that your intended primary <code><previewpic></code>
 +
* 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?''<br>
 +
It should quickly give an impression of the look & feel of an application.<br>
 +
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.
 +
 +
 +
[http://boards.openpandora.org/index.php?/topic/8137-pnd-packagers-1-please-provide-previewpics-2-define-primary-pic-if-you-give-multiple/ Discussion in the developer forum]
 +
 +
==== Example ====
 +
<source lang="xml">
 +
<previewpics>
 +
  <pic src="preview/pic1.jpg"/>
 +
  <pic src="preview/pic2.jpg"/>
 +
</previewpics>
 +
</source>
 +
 +
=== The &lt;info&gt; element ===
 +
====Description====
 +
The "info" element allows the <code>PXML.xml</code> 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 <code>.pnd</code>-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 <code>text/html</code> (for an html file) or <code>text/plain</code> (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: <code>./index.html</code> 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 ====
 +
<source lang="xml">
 +
<info name="AwesomeGame Setup" type="text/html" src="index.html"/>
 +
</source>
  
 +
=== The <categories> element ===
 +
==== Description ====
 
The categories element is an element that contains multiple other elements.
 
The categories element is an element that contains multiple other elements.
 
A categories element is required, and must contain at least one category.
 
A categories element is required, and must contain at least one category.
Line 216: Line 431:
  
 
The subcategory-element also takes a name-attribute; this attibute can contain a name for your subcategory.
 
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 ====
 +
; <code><category></code> : ''(At least one)''
  
 
==== Example ====
 
==== Example ====
Line 230: Line 450:
 
</categories>
 
</categories>
 
</source>
 
</source>
−
=== The associations element ===
+
 
 +
=== The <associations> element ===
 
==== Description ====
 
==== Description ====
  
 
The associations element is an element that contains multiple other elements.
 
The associations element is an element that contains multiple other elements.
−
An associations element is optional, except if exec.standalone is false.
+
An associations element is optional, except if <code>exec.standalone</code> is false (this is not checked via the schema!).
  
−
It contains multiple association-elements. Every association-element represents one file action association.
+
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 ====
 +
; <code><association></code> : ''(At least one)''
 +
 
 +
==== Attributes for <code><association></code> ====
 +
; 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: <code>image/png</code>
 +
; 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 <code>extraarguments</code> element into the <code><exec></code> line, to contain <code>%f</code> or other hint; in this way the desktop environment will know to insert the filename(s), url(s), etc:
 +
*  <code>%f</code> → a single file
 +
*  <code>%F</code> → multiple files
 +
*  <code>%u</code> → a single url
 +
*  <code>%U</code> → multiple urls
 +
* and so on (see the [http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables freedesktop specification for the Exec tag])
 +
 
 +
The result in the <code>.desktop</code> file is a <code>Exec=</code> line looking approximately like:
 +
<source lang="ini">
 +
Exec=/usr/pandora/scripts/pnd_run.sh -p "/media/mysdcard/pandora/menu//ristrun.pnd" -e "run.sh" -b "ristrun" -- %f
 +
</source>
  
−
* The name attribute on an association element specifies the user-friendly action name for the association.
 
−
* The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.
 
−
* The exec attribute on an association element specifies the command-line arguments that should be given to the program, when this action is performed. The exec can contain a "%s", which indicates where the file name of the file, that the action is performed on, should be inserted. For example, if the exec-line is "--file %s --type lol", and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into "--file "lol.bmp" --type lol"
 
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 +
...
 +
<exec command="myprogram.sh" extraarguments="%f"/>
 +
...
 
<associations>
 
<associations>
−
   <association name="Open Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/>
+
   <association name="Open a BMP Image" filetype="image/bmp" />
−
   <association name="Crash the computer with a stylesheet" filetype="text/css" exec="-f %s --crash-on-success"/>
+
   <association name="Open a stylesheet" filetype="text/css" />
 
</associations>
 
</associations>
 +
...
 
</source>
 
</source>
−
=== The clockspeed element ===
+
 
 +
=== The <clockspeed> element ===
 
==== Description ====
 
==== 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.
 
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:
 
A clockspeed element is optional. It accepts the following attributes:
  
−
* The frequency attribute specifies the wanted frequency, in megahertz (MHz).
+
==== Attributes ====
 +
; frequency : ''(required)'' The frequency attribute specifies the wanted frequency, in megahertz (MHz).
  
 
==== Example ====
 
==== Example ====
Line 261: Line 507:
 
</source>
 
</source>
  
 +
== Example files ==
 +
There are several example files available in the [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=tree;f=docs/examples 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:
  
−
=== The mkdir element ===
+
* [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 <code>PXML.xml</code> 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/full-sample_PXML.xml full-sample_PXML.xml]: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
 +
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-schema_PXML.xml 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!
 +
* [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.
  
−
==== Description ====
+
<!-- TODO: These "Note:" backwards compatibility messages are repeated enough that they should probably be rewritten as Mediawiki template badges to simplify things and ensure consistent phrasing. -->
  
−
The PXML may request creation of directories on the SD card.
+
== 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: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/PXML_schema_plaintext.txt plaintext description of the schema]
−
'''This should be used sparingly.'''
 
−
 
 
−
There are a number of scenarios in which this may be useful; should an application wish to attempt to establish a canonicle location for a file, it can request a path be created. This can avoid user confusion -- user merely plugs in SD, waits a few moments, pulls out SD, and inspects it to see what directories he may populate. Consider 'id' files for Quake -- the user might have many ports of the game, such as Quake, or ioquake, or others. They could all share the same id pak files, but the user may not know where to put them. (Especially since the pnd-file itself does not have user documentation available perhaps.) Consider ROM-paths for emulators .. perhaps the emulator expects ROMs in a specific location? If so, the author may wish to have that location created, to make it obvious.
 
−
 
 
−
'''NOTES'''
 
−
The paths are created on the SD that contains the pnd.
 
−
The paths may not include ".." or wildcards.
 
−
 
 
−
It accepts the following attributes:
 
  
−
* dir -> the name of the path to be created; it may not be multiple levels deep - to effect that, include multiple <dir path="..."/> entries
+
The current-most XSD is in 'libpnd' (in the git repository). Here is the file history: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=history;f=docs/PXML_schema.xsd PXML_schema.xsd file history]
 +
Once on the history page, just click on the filename (right click -> save as) to download the latest version.
  
−
==== Example ====
+
The easiest way to run validation is using this command:
−
<source lang="xml">
+
<source lang="bash">
−
<mkdir>
+
xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml
−
  <dir path="/foo/bar"/>
 
−
</mkdir>
 
 
</source>
 
</source>
 +
To run it you have to have xmllint installed and the (latest) <code>PXML_schema.xsd</code> definition downloaded. Using this command you can now simply evaluate if the <code>PXML.xml</code> file is valid.  xmllint can be installed via the angstrom repository (it is part of <code>libxml2-utils</code>).
  
−
If this is in /pandora/desktop on SD1 (/media/mmcblk0p1 say), then /media/mmcblk0p1/foo/bar will be created.
+
'''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.
−
 
 
−
== Example file ==
 
−
<source lang="xml">
 
−
<?xml version="1.0" encoding="UTF-8"?>
 
−
<PXML xmlns="http://openpandora.org/namespaces/PXML">
 
−
 
 
−
  <application id="youruniqueID">
 
  
−
    <title lang="en_US">Program Title</title>
+
== Examples ==
−
    <title lang="de_DE">German Program Title</title>
 
  
−
    <exec background="true" command="program"/>
+
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.
−
    <info name="AwesomeGame Setup" type="txt/html" src="index.html"/>
+
* [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/full-sample_PXML.xml full-sample_PXML.xml]: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
−
    <icon src="program.png"/>
+
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-schema_PXML.xml 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!
−
 
+
* [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.
−
    <description lang="en_US">This is the English Description of the file.</description>
 
−
    <description lang="de_DE">This would be the German description.</description>
 
−
 
 
−
    <previewpics>
 
−
      <pic src="preview/pic1.jpg"/>
 
−
      <pic src="preview/pic2.jpg"/>
 
−
    </previewpics>
 
−
 
 
−
    <author name="Some Dudeson" website="http://a.bc.de"/>
 
−
 
 
−
    <version major="1" minor="1" release="1" build="2"/>
 
−
    <osversion major="1" minor="0" release="0" build="0"/>
 
−
 
 
−
    <categories>
 
−
      <category name="Game">
 
−
        <subcategory name="StrategyGame"/>
 
−
      </category>
 
−
      <category name="Graphics">
 
−
        <subcategory name="ImageProcessing"/>
 
−
      </category>
 
−
    </categories>
 
−
 
 
−
  <clockspeed frequency="600"/>
 
−
 
 
−
  </application>
 
−
 
 
−
</PXML>
 
−
</source>
 
−
 
 
−
== Validation ==
 
−
 
 
−
To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.
 
−
 
 
−
You will also need to put the XML schema for the PXML format in the same folder as your PXML file. Note that the current PXML schema is horribly out of date.
 
−
 
 
−
When you have done that, and know how to use it, you need to change a few things in your PXML file. In your PXML tag, change the contents from this...
 
−
<source lang="xml">
 
−
<PXML id="..." xmlns="http://openpandora.org/namespaces/PXML"> ...
 
−
</source>
 
−
 
 
−
...to this:
 
−
<source lang="xml">
 
−
<PXML id="..." xmlns="http://openpandora.org/namespaces/PXML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PXML_schema.xsd"> ...
 
−
</source>
 
  
−
Now the PXML file can be validated.
 
  
 +
[[Category:Documentation]]
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Official OpenPandora Development]]
 +
[[Category:PND]]

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

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 .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.
Retrieved from "https://pandorawiki.org/index.php?title=PXML_specification&oldid=28418"