docs/PXML_proposed_spec.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3   <head>
   4     <title>The PXML file format</title>
   5     <h1>
   6       The official current-most specification is: http://pandorawiki.org/PXML_specification
   7     </h1>
   8     <style type="text/css">
   9       body { background-color: white; }
  10       h1 {
  11         color: rgb(0, 0, 32);
  12         font: normal 2em sans-serif;
  13         counter-reset: section;
  14         border-bottom: thin solid blue;
  15       }
  16       h2:before {
  17         counter-increment: section;
  18         content: counter(section) ". ";
  19         font: normal 0.5em sans-serif;
  20         color: gray;
  21       }
  22       h2 {
  23         margin-top: 2.1em;
  24         color: rgb(0, 0, 64);
  25         font: normal 1.4em sans-serif;
  26         counter-reset: subsection;
  27       }
  28       h3:before {
  29         counter-increment: subsection;
  30         content: counter(section) ". " counter(subsection) ". ";
  31         font: normal 0.5em sans-serif;
  32         color: gray;
  33       }
  34       h3 {
  35         margin-top: 2em;
  36         color: rgb(0, 0, 96);
  37         font: normal 1.2em sans-serif;
  38         counter-reset: element;
  39       }
  40       h4:before {
  41         counter-increment: element;
  42         content: counter(section) ". " counter(subsection) ". " counter(element) ". ";
  43         font: normal 0.5em sans-serif;
  44         color: gray;
  45       }
  46       h4 {
  47         margin-top: 0.5em;
  48         color: rgb(0, 0, 128);
  49         font: normal 1.1em sans-serif;
  50       }
  51       p {
  52         color: rgb(64, 64, 64);
  53         font: normal 1em sans-serif;
  54       }
  55       ol {
  56         color: rgb(32, 32, 32);
  57         font: normal 1em sans-serif;
  58       }
  59       div.code {
  60         font: normal 1em monospace;
  61         color: black;
  62         background-color: rgb(196, 196, 196);
  63         border: thin solid #888;
  64         min-width: 10em;
  65         margin: 1em;
  66         padding: 0.5em;
  67         overflow: auto;
  68         outline: #444 solid thin;
  69       }
  70       brack:before { content: "("; } /* just for fun XD */
  71       brack:after { content: ")"; }
  72       imp { font-weight: bold; }
  73     </style>
  74   </head>
  75   <body>
  76     <h1>The PXML file format specification</h1>
  77
  78
  79     <h2>Introduction</h2>
  80     <p><imp>
  81       Attention: at the present time, the PXML file format isn't set in stone, and is therefore subject to change.
  82       There is no guarantee that the format or the schema are bug-free or will be changed at any time.
  83       Please wait until this standard is finished before writing a PXML file.
  84     </imp></p>
  85     <p>
  86       This is the human-readable specification for the PXML file format.
  87       The PXML file format is used in <imp>your</imp> applications for the <a href="http://openpandora.org">OpenPandora®</a> <brack>that you package in <q>.pnd</q>-files or distribute otherwise</brack>, to make it possible for menus and launchers to use your applications and their properties.
  88     </p>
  89     <p>
  90       A PXML file should be appended to your <q>.pnd</q>-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.
  91       It should have the name <q>PXML.xml</q> <brack>not case sensitive</brack>, and there should only be one such file.
  92       The contents of the PXML file should also comply to this specification <imp>without exception</imp>, to guarantee that everyone will be able to read it.
  93     </p>
  94     <p>
  95       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.
  96       Included with this specification should also be a <q>.xsd</q>-file, which is used by XML tools to validate PXML files.
  97       A <q>.xsd</q>-file is also known as a XML schema, and can be called the <q>computer-readable</q> version of this document. It is very good practice to validate your PXML-files with that schema before publishing them.
  98     </p>
  99     <p>
 100       To write a PXML file, you also need to know the basics of writing a XML file.
 101       It boils down to the following:
 102       <ol>
 103         <li>If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like this:
 104           <div class="code">
 105             &lt;exampleelement someattribute="something"&gt;something inside it&lt;/exampleeelement&gt;
 106           </div>
 107         </li>
 108         <li>If an element does <imp>not</imp> contain other elements or text, but only attributes, it looks like this:
 109           <div class="code">
 110             &lt;exampleelement2 someattribute="something" /&gt;
 111           </div>
 112         </li>
 113       </ol>
 114     </p>
 115
 116
 117     <h2>Format</h2>
 118     <p>
 119       The PXML-file is split up into multiple so-called <imp>elements</imp>, each of which specify one property of the
 120       <q>.pnd</q>-package.
 121       All of these elements are surrounded with a <imp><q>&lt;PXML&gt;</q>-tag</imp>, 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:
 122     </p>
 123
 124     <h3>The PXML-tag</h3>
 125     <p>
 126       The PXML-tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file.
 127       An example <q>&lt;PXML&gt;</q>-tag would look like this:
 128     </p>
 129     <div class="code">
 130       &lt;PXML xmlns="http://openpandora.org/namespaces/PXML" id="uniqueID"&gt;<br/>
 131       &nbsp;&nbsp;&lt;!--All of the PXML elements should be put here--&gt;<br/>
 132       &lt;/PXML&gt;
 133     </div>
 134     <p>
 135       As you can see, the PXML tag accepts a few <imp>attributes</imp>, namely the <q>id</q> and <q>xmlns</q> attributes.
 136     </p>
 137     <p>
 138       The <imp><q>xmlns</q></imp> attribute is required by the XML standard, and guarantees that this file will be identified as a PXML file.
 139       You <imp>must</imp> include the xmlns attribute, exactly as shown, in your PXML file, with the URL as specified.
 140       Only then can it be guaranteed that the file will be read at all by launchers and menu apps.
 141     </p>
 142     <p>
 143       The <imp><q>id</q></imp> attribute specifies an identifier for your PND package, and should be something globally unique so that no two PND packages have the same id.
 144       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.
 145       If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur.
 146       Please put effort into generating an unique id for your PXML-file.
 147     </p>
 148
 149     <h3>The title element</h3>
 150     <h4>Description</h4>
 151     <p>
 152       The <imp>title</imp> element specifies the text that is shown to the users of your PND file as the application title.
 153       This element can be specified multiple times in multiple languages <brack>the language is indicated by the lang attribute</brack>.
 154     </p>
 155     <p>
 156       At least one <q>title</q>-element is required, in the <q>en_US</q> <brack>American English</brack> language.
 157     </p>
 158     <h4>Example</h4>
 159     <div class="code">
 160       &lt;title lang="en_US"&gt;Your application name&lt;/title&gt;<br/><br/>
 161       &lt;title lang="de_DE"&gt;Deinen Programmnamen&lt;/title&gt;
 162     </div>
 163
 164     <h3>The description element</h3>
 165     <h4>Description</h4>
 166     <p>
 167       The <imp>description</imp> element specifies the text that is shown to the users of your PND file as the application description.
 168       This element can be specified multiple times in multiple languages <brack>the language is indicated by the lang attribute</brack>.
 169     </p>
 170     <p>
 171       At least one <q>description</q>-element is required, in the <q>en_US</q> <brack>American English</brack> language.
 172     </p>
 173     <h4>Example</h4>
 174     <div class="code">
 175       &lt;description lang="en_US"&gt;Your long description of this application, describing it's purpose and highlighting it's features.&lt;/description&gt;<br/><br/>
 176       &lt;description lang="de_DE"&gt;Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und den wichtigsten Features beschreiben sollte.&lt;/description&gt;
 177     </div>
 178
 179     <h3>The exec element</h3>
 180     <h4>Description</h4>
 181     <p>
 182       The <imp>exec</imp> element should specify all the information needed to execute your application.<br/>
 183       An exec element <imp>must</imp> be included in every PXML file.
 184       It accepts the following attributes:
 185     </p>
 186     <p>
 187       The <imp>command</imp> attribute specifies the path to the executable file.
 188       This should be a relative path to a file within the PND package.
 189     </p>
 190     <p>
 191       The <imp>startdir</imp> attribute specifies the starting directory <brack>Also known as the working directory</brack> that the application should start in.
 192       This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.
 193     </p>
 194     <p>
 195       The <imp>standalone</imp> attribute specifies wether or not this application can run on its own, or if it needs parameters to run.<br/>
 196       A value of <q>true</q> or <q>1</q> means that the application can be run without parameters.<br/>
 197       A value of <q>false</q> or <q>0</q> means that the application must be run with parameters.
 198     </p>
 199     <p>
 200       The <imp>background</imp> 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.<br/>
 201       A value of <q>true</q> or <q>1</q> means that the application can run in the background.<br/>
 202       A value of <q>false</q> or <q>0</q> means that the application must be run as the only application.
 203     </p>
 204     <h4>Example</h4>
 205     <div class="code">
 206       &lt;exec background="true" startdir="/usr/share/icons/" standalone="true" command="./myprogram"/&gt;
 207     </div>
 208
 209     <h3>The icon element</h3>
 210     <h4>Description</h4>
 211     <p>
 212       The <imp>icon</imp> element should specify a nice icon for your program.<br/>
 213       An icon element <imp>is optional</imp>.
 214       It accepts the following attributes:
 215     </p>
 216     <p>
 217       The <imp>src</imp> attribute specifies the path to the image file used as the icon.
 218     </p>
 219     <h4>Example</h4>
 220     <div class="code">
 221       &lt;icon src="./images/icon.png"/&gt;
 222     </div>
 223
 224     <h3>The previewpics element</h3>
 225     <h4>Description</h4>
 226     <p>
 227       The <imp>previewpics</imp> element is an element that contains multiple other elements.<br/>
 228       A previewpics element <imp>is optional</imp>.
 229     </p>
 230     <p>
 231       It contains multiple <imp>pic</imp>-elements. Every pic-element represents one preview picture.
 232       If the previewpics element is specified, it must contain at least one pic element.
 233     </p>
 234     <p>
 235       The <imp>src</imp> attribute on a pic element specifies the path to the image file used as the preview picture.
 236     </p>
 237     <h4>Example</h4>
 238     <div class="code">
 239       &lt;previewpics&gt;<br/>
 240       &nbsp;&nbsp;&lt;pic src="./preview/pic1.jpg"/&gt;<br/>
 241       &nbsp;&nbsp;&lt;pic src="./preview/pic2.jpg"/&gt;<br/>
 242       &lt;/previewpics&gt;
 243     </div>
 244
 245     <h3>The author element</h3>
 246     <h4>Description</h4>
 247     <p>
 248       The <imp>author</imp> element is an element that is used by the author to introduce him/herself.<br/>
 249       An author element <imp>is optional</imp>. It accepts the following attributes:
 250     </p>
 251     <p>
 252       The <imp>name</imp> attribute specifies the name of the author.
 253     </p>
 254     <p>
 255       The <imp>website</imp> attribute specifies the website of the author.
 256     </p>
 257     <p>
 258       The <imp>email</imp> attribute specifies the e-mail of the author.<br/>
 259       <imp>This attribute is not yet supported.</imp>
 260     </p>
 261     <h4>Example</h4>
 262     <div class="code">
 263       &lt;author name="Bjornhild Andersson" website="http://some.website.with.author.info"/&gt;
 264     </div>
 265
 266     <h3>The version element</h3>
 267     <h4>Description</h4>
 268     <p>
 269       The <imp>version</imp> element specifies the application version.<br/>
 270       A version element <imp>is required</imp>. It accepts the following attributes:
 271     </p>
 272     <p>
 273       The <imp>major</imp> attribute specifies the major version number. This number should be 0 or more.
 274     </p>
 275     <p>
 276       The <imp>minor</imp> attribute specifies the minor version number. This number should be 0 or more.
 277     </p>
 278     <p>
 279       The <imp>release</imp> attribute specifies the release number. This number should be 0 or more.
 280     </p>
 281     <p>
 282       The <imp>build</imp> attribute specifies what build the application is at. This number should be 0 or more.
 283     </p>
 284     <h4>Example</h4>
 285     <div class="code">
 286       &lt;version major="1" minor="1" release="1" build="2"/&gt;
 287     </div>
 288
 289     <h3>The osversion element</h3>
 290     <h4>Description</h4>
 291     <p>
 292       The <imp>osversion</imp> element specifies the application version.<br/>
 293       An osversion element <imp>is optional</imp>. It accepts the same attributes as the version element.
 294     <h4>Example</h4>
 295     <div class="code">
 296       &lt;osversion major="1" minor="1" release="1" build="2"/&gt;
 297     </div>
 298
 299     <h3>The categories element</h3>
 300     <h4>Description</h4>
 301     <p>
 302       The <imp>categories</imp> element is an element that contains multiple other elements.<br/>
 303       A categories element <imp>is required, and must contain at least one category</imp>.
 304     </p>
 305     <p>
 306       It contains multiple <imp>category</imp>-elements. Every category-element represents one category that this app can be sorted into.
 307       Valid categories are (among others):
 308       <ol>
 309         <li>Development</li>
 310         <li>Education</li>
 311         <li>Games</li>
 312         <li>Graphics</li>
 313         <li>Internet</li>
 314         <li>Multimedia</li>
 315         <li>Office</li>
 316         <li>Settings</li>
 317         <li>System</li>
 318         <li>Utilities</li>
 319       </ol>
 320     </p>
 321     <p>
 322       The category-element takes one attribute: The <imp>name</imp>-attribute.
 323       This attribute represents the category name, which preferrably should be one of the above.
 324     </p>
 325     <p>
 326       A category-element can contain further child-elements: <imp>subcategory</imp>-elements.
 327       These represent the subcategories of a category that the app will be sorted into.
 328     </p>
 329     <p>
 330       The subcategory-element also takes a <imp>name</imp>-attribute; this attibute can contain any name for your subcategory.
 331     </p>
 332     <h4>Example</h4>
 333     <div class="code">
 334       &lt;categories&gt;<br/>
 335       &nbsp;&nbsp;&lt;category name="Games"&gt;<br/>
 336       &nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory name="Strategy"/&gt;<br/>
 337       &nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory name="Turn-based"/&gt;<br/>
 338       &nbsp;&nbsp;&lt;/category&gt;<br/>
 339       &nbsp;&nbsp;&lt;category name="Graphics"&gt;<br/>
 340       &nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory name="Image Editors"/&gt;<br/>
 341       &nbsp;&nbsp;&lt;/category&gt;<br/>
 342       &lt;/categories&gt;<br/>
 343     </div>
 344
 345     <h3>The associations element</h3>
 346     <h4>Description</h4>
 347     <p>
 348       The <imp>associations</imp> element is an element that contains multiple other elements.<br/>
 349       An associations element <imp>is optional, except if exec.standalone is false</imp>.
 350     </p>
 351     <p>
 352       It contains multiple <imp>association</imp>-elements. Every association-element represents one file action association.
 353     </p>
 354     <p>
 355       The <imp>name</imp> attribute on an association element specifies the user-friendly action name for the association.
 356     </p>
 357     <p>
 358       The <imp>filetype</imp> attribute on an association element specifies what file types (in MIME format) that this association should apply to.
 359     </p>
 360     <p>
 361       The <imp>exec</imp> attribute on an association element specifies the command-line arguments that should be given to the program, when this action is performed.
 362       The exec can contain a <q>%s</q>, which indicates where the file name of the file, that the action is performed on, should be inserted.<br/>
 363       For example, if the exec-line is <q>--file %s --type lol</q>, and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into <q>--file "lol.bmp" --type lol</q>
 364     </p>
 365     <h4>Example</h4>
 366     <div class="code">
 367       &lt;associations&gt;<br/>
 368       &nbsp;&nbsp;&lt;association name="Open Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/&gt;<br/>
 369       &nbsp;&nbsp;&lt;association name="Crash the computer with a stylesheet" filetype="text/css" exec="-f %s --crash-on-success"/&gt;<br/>
 370       &lt;/associations&gt;
 371     </div>
 372
 373     <h3>The clockspeed element</h3>
 374     <h4>Description</h4>
 375     <p>
 376       The <imp>clockspeed</imp> element specifies what clockspeed this app should run at.<br/>
 377       A clockspeed element <imp>is optional</imp>. It accepts the following attributes:
 378     </p>
 379     <p>
 380       The <imp>frequency</imp> attribute specifies the wanted frequency, in megahertz <brack>mHz</brack>.
 381     </p>
 382     <h4>Example</h4>
 383     <div class="code">
 384       &lt;clockspeed frequency="600"/&gt;
 385     </div>
 386
 387
 388     <h2>Example file</h2>
 389     <div class="code">
 390       &lt;?xml&nbsp;version="1.0"&nbsp;encoding="UTF-8"?&gt;<br/>
 391       &lt;PXML&nbsp;id="youruniqueID"&nbsp;xmlns="http://openpandora.org/namespaces/PXML"&gt;<br/>
 392       &nbsp;&nbsp;&lt;title&nbsp;lang="en_US"&gt;Program&nbsp;Title&lt;/title&gt;<br/>
 393       &nbsp;&nbsp;&lt;title&nbsp;lang="de_DE"&gt;German&nbsp;Program&nbsp;Title&lt;/title&gt;<br/>
 394       <br/>
 395       &nbsp;&nbsp;&lt;exec&nbsp;background="true"&nbsp;startdir="/usr/share/icons/"&nbsp;standalone="true"&nbsp;command="./program"/&gt;<br/>
 396       <br/>
 397       &nbsp;&nbsp;&lt;icon&nbsp;src="./program.png"/&gt;<br/>
 398       <br/>
 399       &nbsp;&nbsp;&lt;description&nbsp;lang="en_US"&gt;This&nbsp;is&nbsp;the&nbsp;English&nbsp;Description&nbsp;of&nbsp;the&nbsp;file.&lt;/description&gt;<br/>
 400       &nbsp;&nbsp;&lt;description&nbsp;lang="de_DE"&gt;This&nbsp;would&nbsp;be&nbsp;the&nbsp;German&nbsp;description.&lt;/description&gt;<br/>
 401       <br/>
 402       &nbsp;&nbsp;&lt;previewpics&gt;<br/>
 403       &nbsp;&nbsp;&nbsp;&nbsp;&lt;pic&nbsp;src="./preview/pic1.jpg"/&gt;<br/>
 404       &nbsp;&nbsp;&nbsp;&nbsp;&lt;pic&nbsp;src="./preview/pic2.jpg"/&gt;<br/>
 405       &nbsp;&nbsp;&lt;/previewpics&gt;<br/>
 406       <br/>
 407       &nbsp;&nbsp;&lt;author&nbsp;name="Some Dudeson"&nbsp;website="http://a.bc.de"/&gt;<br/>
 408       <br/>
 409       &nbsp;&nbsp;&lt;version&nbsp;major="1"&nbsp;minor="1"&nbsp;release="1"&nbsp;build="2"/&gt;<br/>
 410       &nbsp;&nbsp;&lt;osversion&nbsp;major="1"&nbsp;minor="0"&nbsp;release="0"&nbsp;build="0"/&gt;<br/>
 411       <br/>
 412       &nbsp;&nbsp;&lt;categories&gt;<br/>
 413       &nbsp;&nbsp;&nbsp;&nbsp;&lt;category&nbsp;name="Main&nbsp;category"&gt;<br/>
 414       &nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory&nbsp;name="Subcategory&nbsp;1"/&gt;<br/>
 415       &nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory&nbsp;name="Subcategory&nbsp;2"/&gt;<br/>
 416       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/category&gt;<br/>
 417       &nbsp;&nbsp;&nbsp;&nbsp;&lt;category&nbsp;name="Alternative&nbsp;category"&gt;<br/>
 418       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;subcategory&nbsp;name="Alternative&nbsp;Subcategory&nbsp;1"/&gt;<br/>
 419       &nbsp;&nbsp;&nbsp;&nbsp;&lt;/category&gt;<br/>
 420       &nbsp;&nbsp;&lt;/categories&gt;<br/>
 421       <br/>
 422       &nbsp;&nbsp;&lt;associations&gt;<br/>
 423       &nbsp;&nbsp;&nbsp;&nbsp;&lt;association&nbsp;name="View&nbsp;Word&nbsp;File"&nbsp;filetype="application/msword"&nbsp;exec="-f&nbsp;%s&nbsp;-t&nbsp;doc"/&gt;<br/>
 424       &nbsp;&nbsp;&lt;/associations&gt;<br/>
 425       <br/>
 426       &nbsp;&nbsp;&lt;clockspeed&nbsp;frequency="600"/&gt;&lt;!--Frequency&nbsp;in&nbsp;Hz--&gt;<br/>
 427       &lt;/PXML&gt;<br/>
 428     </div>
 429
 430
 431     <h2>Validation</h2>
 432     <p>To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.</p>
 433     <p>You will also need to put the XML schema for the PXML format in the same folder as your PXML file.</p>
 434     <p>
 435       When you have done that, and know how to use it, you need to change a few things in your PXML file.
 436       In your PXML tag, change the contents from this:
 437     </p>
 438     <div class="code">
 439       &lt;PXML id="..." xmlns="http://openpandora.org/namespaces/PXML"&gt;...
 440     </div>
 441     <p>...to this:</p>
 442     <div class="code">
 443       &lt;PXML id="..." xmlns="http://openpandora.org/namespaces/PXML" <imp>xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PXML_schema.xsd"</imp>&gt;...
 444     </div>
 445     <p>
 446       Now the PXML file can be validated.
 447     </p>
 448   </body>
 449 </html>