PXML specification - Revision history

Levi: Removing redundant outdated information

2013-10-28T03:01:53Z

Removing redundant outdated information

Show changes

Kingu: merged PXML archetype

2013-10-09T06:04:31Z

merged PXML archetype

Show changes

Foxblock: /* Attributes */ Note about info.name (often occurring problem/mistake)

2013-04-10T13:47:13Z

‎Attributes: Note about info.name (often occurring problem/mistake)

Foxblock: Fixed wiki markup being horriby broken after info element for some reason

2013-04-10T12:57:26Z

Fixed wiki markup being horriby broken after info element for some reason

Foxblock at 12:55, 10 April 2013

2013-04-10T12:55:53Z

Ssokolow: /* Attributes */ Removed obsolete warning about dashes in appdata attribute

2013-03-13T12:00:08Z

‎Attributes: Removed obsolete warning about dashes in appdata attribute

Ssokolow: Use "Required Children" sections with cross-references to make the spec a bit easier for new users to get into

2013-03-12T19:26:12Z

Use "Required Children" sections with cross-references to make the spec a bit easier for new users to get into

Show changes

Ssokolow: Adjust "Note:"s for consistency and add hidden TODO notes for things I can't fix yet.

2013-03-12T18:55:11Z

Adjust "Note:"s for consistency and add hidden TODO notes for things I can't fix yet.

Ssokolow: Add a link to the freedesktop spec for the Exec line

2013-03-12T18:49:41Z

Add a link to the freedesktop spec for the Exec line

Ssokolow: Fix oversights in previous edits

2013-03-12T18:46:09Z

Fix oversights in previous edits

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

@@ Line 386: / Line 386: @@
 </source>
-=== The &lt;info&rt; element ===
+=== The &lt;info&gt; element ===
 ====Description====
 The "info" element allows the <code>PXML.xml</code> to suggest to the desktop environment or menu a file that may be shown to the user when they want to know more - be it an About, a Install Guide, a User Guide, or all of the above. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

@@ Line 386: / Line 386: @@
 </source>
-=== The <info> element ===
+=== The &lt;info&rt; element ===
 ====Description====
 The "info" element allows the <code>PXML.xml</code> to suggest to the desktop environment or menu a file that may be shown to the user when they want to know more - be it an About, a Install Guide, a User Guide, or all of the above. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

@@ Line 164: / Line 164: @@
 ; appdata
 : ''(optional)'' The "appdata" permits a directory name (NOT PATH) to be specified as preferred; if not present, the unique id provided in the ID attribute will be used. For example, we may want a unique id of <code>Battlejewels.skeezix.3216836217382163.v001</code>, but an appdata path of <code>battlejewels</code> to make it easier on the user, or to have multiple different battlejewels sharing one appdata.
 ===== Suggestions for Generating A Unique ID =====

@@ Line 129: / Line 129: @@
 ; 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 <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 <code>PXML.xml</code>.
 ==== Example ====
@@ Line 153: / Line 153: @@
 : ''(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.
 : '''Notice: appdata names with dashes in (e.g. quake-2 rather than quake2) will cause the PND file to function improperly.'''
 ===== Suggestions for Generating A Unique ID =====
@@ Line 249: / Line 251: @@
 '''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!
 At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.
@@ Line 268: / Line 271: @@
 '''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!
 ==== Example ====
@@ Line 285: / Line 289: @@
 ; src : ''(required)'' The src attribute specifies the path to the image file used as the icon.
-NOTE: Current implementation will use the PND file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So, for a PND file, all subapps will show the appended-icon regardless of the <code><icon></code> tag within the <code>PXML.xml</code>.
+'''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 ====
@@ Line 471: / Line 475: @@
 * [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-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.
 == Validation ==

@@ Line 433: / Line 433: @@
 *   <code>%u</code> → a single url
 *   <code>%U</code> → multiple urls
-* and so on (see the freedesktop specification in the Exec tag)
+* 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:

@@ Line 52: / Line 52: @@
 : ''(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 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.'''
 ==== Example ====
@@ Line 155: / Line 155: @@
 ===== Suggestions for Generating A Unique ID =====
-A unique ID '''must not include''' directory or filename invalid characters, such as <code>?</code>, <code>&gt;</code>, <code>/</code>, etc. Any of those will cause the PND file to not function.
+A unique ID '''must not''' include directory or filename invalid characters, such as <code>?</code>, <code>&gt;</code>, <code>/</code>, etc. Any of those will cause the PND file to not function.
 The unique-id should be unique against other PND files, but may be re-used by other 'application' tags within the PND; for example, you may have multiple subapps that want to share the same appdata path (which is formed based on unique-id!), so use the same unique-id. You might then have a utility application in that same PND, which needs its own appdata, and so gets its own unique-id.
@@ Line 358: / Line 358: @@
 ==== 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".
-; 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.
+; 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: ./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.
+; 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 ====
@@ Line 424: / Line 424: @@
 ==== Attributes ====
 ; 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
+; 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.