Difference between revisions of "PXML specification"

From Pandora Wiki
Jump to: navigation, search
(Added source tags, still needs headings and other formatting tweaks)
(Fixed formatting + weird content)
Line 1: Line 1:
 
'''This is taken from the HTML version included in the libpnd distribution; the HTML formatting therein may be perverted during import to this wiki.'''
 
'''This is taken from the HTML version included in the libpnd distribution; the HTML formatting therein may be perverted during import to this wiki.'''
  
The PXML file format specification
+
== Introduction ==
Introduction
 
  
Attention: at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. Please wait until this standard is finished before writing a PXML file.
+
'''Attention:''' at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. Please wait until this standard is finished before writing a PXML file.
  
 
This 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.
 
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.
Line 14: Line 13:
 
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:
  
  1. If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like this:
+
# If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like (1)
      <exampleelement someattribute="something">something inside it</exampleeelement>
+
# If an element does not contain other elements or text, but only attributes, it looks like (2)
  2. If an element does not contain other elements or text, but only attributes, it looks like this:
+
  <source lang="xml">
      <exampleelement2 someattribute="something" />
+
  <exampleelement someattribute="something">something inside it</exampleelement> <!-- (1) -->
 +
  <exampleelement2 someattribute="something" /> <!-- (2) -->
 +
  </source>
  
Format
+
== 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 ".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
+
=== 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. An example "<PXML>"-tag would look like this:
 
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:
  
Line 43: Line 44:
  
 
At least one "title"-element is required, in the "en_US" American English language.
 
At least one "title"-element is required, in the "en_US" American English language.
Example
+
 
 +
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<title lang="en_US">Your application name</title>
 
<title lang="en_US">Your application name</title>
Line 49: Line 51:
 
<title lang="de_DE">Deinen Programmnamen</title>
 
<title lang="de_DE">Deinen Programmnamen</title>
 
</source>
 
</source>
The description element
+
=== The description element ===
Description
+
==== Description ====
  
 
The description element specifies the text that is shown to the users of your PND file as the application description. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.
 
The description element specifies the text that is shown to the users of your PND file as the application description. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.
Line 61: Line 63:
 
<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und den wichtigsten Features beschreiben sollte.</description>
 
<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und den wichtigsten Features beschreiben sollte.</description>
 
</source>
 
</source>
The exec element
+
=== The exec element ===
Description
+
==== Description ====
  
 
The exec element should specify all the information needed to execute your application.
 
The exec element should specify all the information needed to execute your application.
Line 78: Line 80:
 
A value of "true" or "1" means that the application can run in the background.
 
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.
 
A value of "false" or "0" means that the application must be run as the only application.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="./myprogram"/>
 
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="./myprogram"/>
 
</source>
 
</source>
The icon element
+
=== The icon element ===
Description
+
==== Description ====
  
 
The icon element should specify a nice icon for your program.
 
The icon element should specify a nice icon for your program.
Line 89: Line 91:
  
 
The src attribute specifies the path to the image file used as the icon.
 
The src attribute specifies the path to the image file used as the icon.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<icon src="./images/icon.png"/>
 
<icon src="./images/icon.png"/>
 
</source>
 
</source>
The previewpics element
+
=== The previewpics element ===
Description
+
==== Description ====
  
 
The previewpics element is an element that contains multiple other elements.
 
The previewpics element is an element that contains multiple other elements.
Line 102: Line 104:
  
 
The src attribute on a pic element specifies the path to the image file used as the preview picture.
 
The src attribute on a pic element specifies the path to the image file used as the preview picture.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<previewpics>
 
<previewpics>
Line 109: Line 111:
 
</previewpics>
 
</previewpics>
 
</source>
 
</source>
The author element
+
=== The author element ===
Description
+
==== Description ====
  
 
The author element is an element that is used by the author to introduce him/herself.
 
The author element is an element that is used by the author to introduce him/herself.
Line 121: Line 123:
 
The email attribute specifies the e-mail of the author.
 
The email attribute specifies the e-mail of the author.
 
This attribute is not yet supported.
 
This attribute is not yet supported.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
 
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
 
</source>
 
</source>
The version element
+
=== The version element ===
Description
+
==== Description ====
  
 
The version element specifies the application version.
 
The version element specifies the application version.
Line 138: Line 140:
  
 
The build attribute specifies what build the application is at. This number should be 0 or more.
 
The build attribute specifies what build the application is at. This number should be 0 or more.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<version major="1" minor="1" release="1" build="2"/>
 
<version major="1" minor="1" release="1" build="2"/>
 
</source>
 
</source>
The osversion element
+
=== The osversion element ===
Description
+
==== Description ====
  
 
The osversion element specifies the application version.
 
The osversion element specifies the application version.
 
An osversion element is optional. It accepts the same attributes as the version element.
 
An osversion element is optional. It accepts the same attributes as the version element.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<osversion major="1" minor="1" release="1" build="2"/>
 
<osversion major="1" minor="1" release="1" build="2"/>
 
</source>
 
</source>
The categories element
+
=== The categories element ===
Description
+
==== Description ====
  
 
The categories element is an element that contains multiple other elements.
 
The categories element is an element that contains multiple other elements.
Line 159: Line 161:
 
It contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid categories are (among others):
 
It contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid categories are (among others):
  
  1. Development
+
# AudioVideo
  2. Education
+
# Audio
  3. Games
+
# Video
  4. Graphics
+
# Development
  5. Internet
+
# Education
  6. Multimedia
+
# Game
  7. Office
+
# Graphics
  8. Settings
+
# Network
  9. System
+
# Office
  10. Utilities
+
# Settings
 +
# System
 +
# Utility
 +
 
 +
Please see [http://standards.freedesktop.org/menu-spec/latest/apa.html|the FreeDesktop specification] for more information.
  
 
The category-element takes one attribute: The name-attribute. This attribute represents the category name, which preferrably should be one of the above.
 
The category-element takes one attribute: The name-attribute. This attribute represents the category name, which preferrably should be one of the above.
Line 175: Line 181:
  
 
The subcategory-element also takes a name-attribute; this attibute can contain any name for your subcategory.
 
The subcategory-element also takes a name-attribute; this attibute can contain any name for your subcategory.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<categories>
 
<categories>
   <category name="Games">
+
   <category name="Game">
     <subcategory name="Strategy"/>
+
     <subcategory name="StrategyGame"/>
    <subcategory name="Turn-based"/>
 
 
   </category>
 
   </category>
 
   <category name="Graphics">
 
   <category name="Graphics">
     <subcategory name="Image Editors"/>
+
     <subcategory name="ImageProcessing"/>
 
   </category>
 
   </category>
 
</categories>
 
</categories>
 
</source>
 
</source>
The associations element
+
=== The associations element ===
Description
+
==== Description ====
  
 
The associations element is an element that contains multiple other elements.
 
The associations element is an element that contains multiple other elements.
Line 201: Line 206:
 
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.
 
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"
 
For example, if the exec-line is "--file %s --type lol", and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into "--file "lol.bmp" --type lol"
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<associations>
 
<associations>
Line 208: Line 213:
 
</associations>
 
</associations>
 
</source>
 
</source>
The clockspeed element
+
=== The clockspeed element ===
Description
+
==== Description ====
  
 
The clockspeed element specifies what clockspeed this app should run at.
 
The clockspeed element specifies what clockspeed this app should run at.
Line 215: Line 220:
  
 
The frequency attribute specifies the wanted frequency, in megahertz mHz.
 
The frequency attribute specifies the wanted frequency, in megahertz mHz.
Example
+
==== Example ====
 
<source lang="xml">
 
<source lang="xml">
 
<clockspeed frequency="600"/>
 
<clockspeed frequency="600"/>
 
</source>
 
</source>
Example file
+
== Example file ==
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 261: Line 266:
 
</source>
 
</source>
  
Validation
+
== Validation ==
  
 
To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.
 
To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.

Revision as of 20:21, 24 November 2009

This is taken from the HTML version included in the libpnd distribution; the HTML formatting therein may be perverted during import to this wiki.

Introduction

Attention: at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. Please wait until this standard is finished before writing a PXML file.

This 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 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) -->

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. An example "<PXML>"-tag would look like this:

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

As you can see, the PXML tag accepts a few attributes, namely the "id" and "xmlns" attributes.

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.

The "id" attribute specifies an identifier for your PND package, and should be something globally unique so that no two PND packages have the same id. This can be achieved by appending some random number to your application name, and to use that as your id; or to simply generate a completely random, very long id. If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur. Please put effort into generating an unique id for your PXML-file. The title element Description

The title element specifies the text that is shown to the users of your PND file as the application title. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.

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

Example

<title lang="en_US">Your application name</title>

<title lang="de_DE">Deinen Programmnamen</title>

The description element

Description

The description element specifies the text that is shown to the users of your PND file as the application description. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.

At least one "description"-element is required, in the "en_US" American English language. Example

<description lang="en_US">Your long description of this application, describing it's purpose and highlighting it's features.</description>

<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und den wichtigsten Features beschreiben sollte.</description>

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. It accepts the following attributes:

The command attribute specifies the path to the executable file. This should be a relative path to a file within the PND package.

The startdir attribute specifies the starting directory Also known as the working directory that the application should start in. This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.

The standalone attribute specifies wether 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.

The background attribute specifies wether 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.

Example

<exec background="true" startdir="/usr/share/icons/" standalone="true" command="./myprogram"/>

The icon element

Description

The icon element should specify a nice icon for your program. An icon element is optional. It accepts the following attributes:

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

Example

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

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.

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

Example

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

The author element

Description

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

The name attribute specifies the name of the author.

The website attribute specifies the website of the author.

The email attribute specifies the e-mail of the author. This attribute is not yet supported.

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 accepts the following attributes:

The major attribute specifies the major version number. This number should be 0 or more.

The minor attribute specifies the minor version number. This number should be 0 or more.

The release attribute specifies the release number. This number should be 0 or more.

The build attribute specifies what build the application is at. This number should be 0 or more.

Example

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

The osversion element

Description

The osversion element specifies the application version. An osversion element is optional. It accepts the same attributes as the version element.

Example

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

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.

It contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid 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 FreeDesktop specification for more information.

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 any name for your subcategory.

Example

<categories>
  <category name="Game">
    <subcategory name="StrategyGame"/>
  </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.

It contains multiple association-elements. Every association-element represents one file action association.

The name attribute on an association element specifies the user-friendly action name for the association.

The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.

The exec attribute on an association element specifies the command-line arguments that should be given to the program, when this action is performed. The exec can contain a "%s", which indicates where the file name of the file, that the action is performed on, should be inserted. For example, if the exec-line is "--file %s --type lol", and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into "--file "lol.bmp" --type lol"

Example

<associations>
  <association name="Open Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/>
  <association name="Crash the computer with a stylesheet" filetype="text/css" exec="-f %s --crash-on-success"/>
</associations>

The clockspeed element

Description

The clockspeed element specifies what clockspeed this app should run at. A clockspeed element is optional. It accepts the following attributes:

The frequency attribute specifies the wanted frequency, in megahertz mHz.

Example

<clockspeed frequency="600"/>

Example file

<?xml version="1.0" encoding="UTF-8"?>
<PXML id="youruniqueID" xmlns="http://openpandora.org/namespaces/PXML">
  <title lang="en_US">Program Title</title>
  <title lang="de_DE">German Program Title</title>

  <exec background="true" startdir="/usr/share/icons/" standalone="true" command="./program"/>

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

  <description lang="en_US">This is the English Description of the file.</description>
  <description lang="de_DE">This would be the German description.</description>

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

  <author name="Some Dudeson" website="http://a.bc.de"/>

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

  <categories>
    <category name="Main category">
    <subcategory name="Subcategory 1"/>
    <subcategory name="Subcategory 2"/>
    </category>
    <category name="Alternative category">
      <subcategory name="Alternative Subcategory 1"/>
    </category>
  </categories>

  <associations>
    <association name="View Word File" filetype="application/msword" exec="-f %s -t doc"/>
  </associations>

  <clockspeed frequency="600"/><!--Frequency in Hz-->
</PXML>

Validation

To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.

You will also need to put the XML schema for the PXML format in the same folder as your PXML file.

When you have done that, and know how to use it, you need to change a few things in your PXML file. In your PXML tag, change the contents from this...

<PXML id="..." xmlns="http://openpandora.org/namespaces/PXML"> ...

...to this:

<PXML id="..." xmlns="http://openpandora.org/namespaces/PXML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PXML_schema.xsd"> ...

Now the PXML file can be validated.