Difference between revisions of "PXML specification"

From Pandora Wiki
Jump to: navigation, search
(fix more copy-pasta)
(Removing redundant outdated information)
 
(30 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]].
+
This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]]. To see examples you can base your own on to get quickly up-to-speed, see [[#Example_files|below]]
  
'''Attention:''' at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.
+
{{Warning | At the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.}}This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in <code>.pnd</code>-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.
  
This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in ".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 <code>.pnd</code>-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name <code>PXML.xml</code> (not case sensitive) and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.
  
A PXML file should be appended to your ".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 <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.
 
 
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.
 
  
 
== 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 23: Line 21:
 
== General 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">
 
<PXML xmlns="http://openpandora.org/namespaces/PXML">
Line 34: Line 40:
 
</source>
 
</source>
  
As you can see, the PXML tag only requires the "xmlns" attribute.
+
== 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.
  
* 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.
+
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 <package> element ===
+
==== Attributes ====
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). The information required in the <package> block will be explained below in the respective section below.
 
  
=== The <application> element ===
+
; id
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 information required in the <application> blocks will be explained below in the respective section below.
+
: ''(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 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.'''
  
== The <package> area ==
+
==== Required Children ====
As described above, each pnd should start with a package description. For single application packages this can basically be a copy of the respective areas from the <application> element.
+
; <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">
 
<package id="uniqueID">
 
<package id="uniqueID">
Line 52: Line 63:
 
</package>
 
</package>
 
</source>
 
</source>
 
* ''(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 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.''' 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 <author> element ===
 
=== The <author> element ===
Line 60: Line 69:
 
An author element is mandatory. It accepts the following attributes:
 
An author element is mandatory. It accepts the following attributes:
  
* ''(required)'' The name attribute specifies the name of the author.
+
==== Attributes ====
* ''(optional)'' The website attribute specifies the website of the author.
+
; name : ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The email attribute specifies the e-mail 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 ====
Line 74: Line 84:
 
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:
 
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:
  
* ''(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 '-'.
+
==== Attributes ====
* ''(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 '-'.
+
; 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 '-'.
* ''(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 '-'.
+
; 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 '-'.
* ''(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 '-'.
+
; 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 '-'.
* ''(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.
+
; 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 ====
 
==== Example ====
Line 89: Line 100:
 
The titles element is an element that contains multiple other elements.
 
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. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
+
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. Additional tags are optional.
+
==== Required Children ====
 +
; <code><title></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
 
==== Example ====
 
==== Example ====
Line 105: Line 117:
 
The descriptions element is an element that contains multiple other elements.
 
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.
+
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.
 +
 
 +
==== Required Children ====
 +
; <code><description></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
 
==== Example ====
 
==== Example ====
Line 119: Line 136:
 
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 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:
  
* ''(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 <code>PXML.xml</code>.
  
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 ====
 
==== Example ====
Line 129: Line 147:
  
 
== The <application> area ==
 
== 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.
+
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">
 
<source lang="xml">
Line 137: Line 155:
 
</source>
 
</source>
  
* ''(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 an unique id for your PXML-file.
+
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).
  
* ''(optional)'' The "appdata" permits a directory name (NOT PATH) to be specified as preferred; if not present, the unique-id will be used. For example, we may want a unique-id of "Battlejewels.skeezix.3216836217382163.v001", but a appdata path of "battlejewels" to make it easier on the user, or to have multiple different battlejewels sharing one appdata.
+
==== Attributes ====
'''Notice: appdata names with dashes in (e.g. quake-2 rather than quake2) will cause the pnd file to function improperly.'''   
+
; 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.
  
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:
+
===== Suggestions for Generating A Unique ID =====
battlejewels.skeezix.001
+
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.
quake-1.pickle.001
 
  
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.'''
+
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.
  
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.
+
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>
  
Below are the allowed elements inside the <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).
+
==== 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 ===
 
=== The <exec> element ===
Line 158: Line 188:
 
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:
 
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:
  
* ''(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 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 ====
* ''(optional)'' The arguments attribute may be not present, or present with 1 or more arguments to the executable.
+
; 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.
* ''(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.
+
; arguments : ''(optional)'' The arguments attribute may be not present, or present with 1 or more arguments to the executable.
* ''(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).
+
; 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.
* ''(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.
+
; 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).
* ''(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.)
+
; 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 ====
 
==== Example ====
 +
 +
A minimal (and typical) exec:
 +
 
<source lang="xml">
 
<source lang="xml">
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option"/>
+
<exec command="myprogram.sh"/>
 +
</source>
 +
 
 +
 
 +
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>
 
</source>
  
Line 175: Line 220:
 
An author element is mandatory. It accepts the following attributes:
 
An author element is mandatory. It accepts the following attributes:
  
* ''(required)'' The name attribute specifies the name of the author.
+
==== Attributes ====
* ''(optional)'' The website attribute specifies the website of the author.
+
; name : ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The email attribute specifies the e-mail 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 ====
Line 189: Line 235:
 
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:
 
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:
  
* ''(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 '-'.
+
==== Attributes ====
* ''(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 '-'.
+
; 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 '-'.
* ''(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 '-'.
+
; 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 '-'.
* ''(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 '-'.
+
; 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 '-'.
* ''(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.
+
; 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 ====
 
==== Example ====
Line 203: Line 250:
 
==== Description ====
 
==== 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.
 
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 ====
 
==== Example ====
Line 208: Line 261:
 
<osversion major="1" minor="1" release="1" build="2"/>
 
<osversion major="1" minor="1" release="1" build="2"/>
 
</source>
 
</source>
 
* ''(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 '-'.
 
* ''(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 '-'.
 
* ''(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 '-'.
 
* ''(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 '-'.
 
  
 
=== The <titles> element ===
 
=== The <titles> element ===
Line 218: Line 266:
 
The titles element is an element that contains multiple other elements.
 
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 application 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. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
+
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.
  
'''Note:''' This is new in HF6. For backwards compatibilty please include the <title lang="en_US"> once outside the <titles> block, too!
+
'''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)''
  
 
At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
 
At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
Line 237: Line 289:
 
The descriptions element is an element that contains multiple other elements.
 
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. 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 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.
 +
 
 +
'''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. -->
  
'''Note:''' This is new in HF6. For backwards compatibilty please include the <description lang="en_US"> once outside the <titles> block, too!
+
==== Required Children ====
 +
; <code><description></code> : ''(At least one with <code>lang="en_US"</code> for American English)''
  
 
==== Example ====
 
==== Example ====
Line 254: Line 312:
 
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 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:
  
* ''(required)'' The src attribute specifies the path to the image file used as the icon.
+
==== 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
+
'''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>.
  
 
==== Example ====
 
==== Example ====
Line 269: Line 328:
 
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.  
 
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)'' 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.
+
==== Required Children ====
* ''(optional)'' The url attribute can be used to specify a url to the full license text.
+
; <code><license></code> : ''(At least one)''
* ''(optional)'' The sourcecodeurl attribute can be used to specify a url to the sources.
+
 
 +
==== 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.
  
 
==== Example ====
 
==== Example ====
Line 288: Line 351:
 
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.
 
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)'' The src attribute on a pic element specifies the path to the image file used as the preview picture.
+
==== 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 ====
 
==== Example ====
Line 298: Line 384:
 
</source>
 
</source>
  
=== The <info> element ===
+
=== The &lt;info&gt; element ===
 
====Description====
 
====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 "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 .pnd-application will be mounted, the file may in turn branch to other files should it wish to.
+
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!
+
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!
  
* ''(required)'' 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 ====
* ''(required)'' 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. 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.
+
; 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!'''
* ''(required)'' src → 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.
+
; 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 ====
 
==== Example ====
Line 346: Line 433:
  
 
For passing validation any category/subcategory entries have to confirm to the FDO specs linked above.
 
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 363: Line 453:
 
=== 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 (this is not checked via the schema!).
+
An associations element is optional, except if <code>exec.standalone</code> 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 ====
 +
; <code><association></code> : ''(At least one)''
  
It contains multiple association-elements. Every association-element represents one file action association.
+
==== 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.  
  
* ''(required)'' The name attribute on an association element specifies the user-friendly action name for the association.
+
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:
* ''(required)'' The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.
+
*  <code>%f</code> → a single file
* ''(required)'' 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"
+
*  <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>
  
 
==== Example ====
 
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 +
...
 +
<exec command="myprogram.sh" extraarguments="%f"/>
 +
...
 
<associations>
 
<associations>
   <association name="Deinterlaced Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/>
+
   <association name="Open a BMP Image" filetype="image/bmp" />
   <association name="Style sheet system crasher" filetype="text/css" exec="-f %s --crash-on-success"/>
+
   <association name="Open a stylesheet" filetype="text/css" />
 
</associations>
 
</associations>
 +
...
 
</source>
 
</source>
  
Line 385: Line 499:
 
A clockspeed element is optional. It accepts the following attributes:
 
A clockspeed element is optional. It accepts the following attributes:
  
* ''(required)'' 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 395: Line 510:
 
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:
 
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:
  
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
+
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample <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/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/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-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.
 
* [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.
 +
 +
<!-- 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. -->
  
 
== Validation ==
 
== Validation ==
Line 408: Line 525:
  
 
The easiest way to run validation is using this command:
 
The easiest way to run validation is using this command:
 +
<source lang="bash">
 
  xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml
 
  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).  
+
</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>).  
  
 
'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ''<!--pre HF6 compatibility-->'' and include those blocks in your pxml file.
 
'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ''<!--pre HF6 compatibility-->'' and include those blocks in your pxml file.
  
 +
== Examples ==
 +
 +
Please have a look at the '''example files provided in git''':
 +
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
 +
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/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.
 +
 +
 +
[[Category:Documentation]]
 
[[Category:Development]]
 
[[Category:Development]]
 
[[Category:Official OpenPandora Development]]
 
[[Category:Official OpenPandora Development]]
 
[[Category:PND]]
 
[[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


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.