-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hi everybody! As result of the discussions so far I have worked on creating a decent proposal embedding some of the new stuff. I attached several sample files (various "stages" of PXML.xml files as well as a plaintext description of the schema and the schema itself). And I will try to explain the changes compared to the existing format as well the reasoning behind these proposed changes. For some changes some slight alternations in libpnd might be required, but those should be doable in a non intrusive and backwards compatible way.
First some explanations of the concept: 1) libpnd libpnd is likely to be the most relaxed part in the whole setup. It will accept PXML files that are *significantly* more easy and simple than what the "specification" wants to see. libpnd does not use all possible tags and does simply ignore tags that are unknown, so adding new random stuff should not affect libpnd. 2) schema The schema is based on what is wanted in the specification. It is *not* mandatory to follow the scheme, since even when validation fails the pnd might still work with the PXML.xml file. This schema is basically meant to not only help with checking if the file is likely to work on the pandora, but also to establish some "good coding practices" as well as support possible package databases by making sure that pnds come with some basic information. 3) difference between package and application Inside a single pnd file several applications can be included. So basically a pnd file is (by definition) a 'package'. There is no "extra" information what makes the package a package (so far). At the moment all info available in the PXML is about the single applications that form the package. 4) mandatory / optional The usage of these terms has to be seen in context. Something mandatory for libpnd means that the pnd won't work unless those are met. Something mandatory for the schema means that the PXML file won't pass validation unless this is met, but the pnd might still be accepted by libpnd. Optional stuff should be self-explaining. Stuff that is optional for libpnd might be mandatory for the schema though (cf the stuff above).
New things and changes to the current system:
1) Add another flag to the <version> entry Adding a 'type=' entry here will allow to specify if this application is a "release" or an "alpha" or "beta" version. A possible usecase of this would allow some "closed beta test" via package repositories only allowing registered users (of a special group) to get the package/application/pnd. If no 'type' is specified, 'release' is to be assumed. This means that the <version> tag can look like this after the change: <version major="1" minor="17" release="3" build="4" type="release"/> This change requires no changes in libpnd itself since at the moment the version tag is not respected/used anyway.
2) Change how <title> and <description> are listed At the moment it is already possible to have several titles and descriptions allowing translations of those. Sadly the current system makes it difficult to validate the PXML using w3 conform validators. Either there can only be "up to one" block of each type in a schema, or the order of the blocks have to be strict (not too simple to explain, but trust me on this, it is a mess). Over here I will just explain things based on <title>, <description> behaves identically. It is possible to have more than one <title> block. For categories, previewpics and associations the specs already have a "subcategory" in which the real entries are stored. The idea is to do the same for all <title> blocks. So instead of having these lines: <title lang="en_US">Sample Application</title> <title lang="de_DE">Beispiel Anwendung</title> The resulting PXML that is valid would look like this: <titles> <title lang="en_US">Sample Application</title> <title lang="de_DE">Beispiel Anwendung</title> </titles> As you can see *exactly* the same entries would just be in one extra block. This makes it rather easy to transform the existing PXML into this changed format (for passing schema validation) and it should be easy to add this support to libpnd. After this change being added, the order inside the <application> blocks does *not* matter anymore for validation. This change requires some changes to libpnd, so that the title is also read from the additional level introduced by <titles>. Exactly the same as mentioned above applies for <description>.
3) Add a way to specify the license of an application At the moment there is no way for a packager/author of software to define the license of the stuff. The proposal is to add a way that allows several licenses to a given application (think of "dual licensing"). It would be mandatory (in the schema validation) to specify at least one license. The license itself only consists of a name, but you *can* also specify a url to the license text as well as a url to the sourcecode for those licenses that want you to publish the sourcecode. Here is a sample of how it can look with several licenses (remember, *one* <license> block is required for the PXML.xml to pass validation!): <licenses> <license name="other" url="http://openpandora.org/pandora_special.html"/> <license name="pandora commercial" url="http://url.openpandora.org/commercial_license.html"/> <license name="public domain"/> <license name="GPLv2+" url="http://www.gnu.org/licenses/gpl-2.0.html" sourcecodeurl="http://pandora.org/sources/package.tar.bz2"/> </licenses> The reason to call this 'license' is that every software comes with some form of license (a valid entry would also be 'do what you want with it'!), but not every license also makes you somehow bundle the sourcecode. There will also be nothing enforcing names for the license or forcing that there is a sourcecode url for some given license name, since the sources can be provided in *many* ways, eg by having it mentioned in the docs or *whatever*. This is basically an offer to packagers to say what license the package comes with. It will likely be rather important to have everything in package repositories in a "correct" form. No changes in libpnd required, since this tag would just be ignored on libpnd side (for the moment) and additional tags that are unknown are just ignored.
4) Add information about the 'package' in PXML At the moment the PXML is only about the included applications. This is all what is required to have the pnds working. Sadly this does not mean that all information that a user might expect is available in the PXML file. It does not provide any information about the "composition". The best known example for this is a game collection like eg kde-games. Beside the filename there is no way to see that this is a kde-games package. Currently PXML does offer the infrastructure of bundle applications from various authors and sources, but you can't add any extra info. This was already discussed over the last days (including a very early proposal I made up in some 5mins) on the list. Now lets come to the 'complete' version including some details: * My general idea is that it should be easy for a dev to create this section. Most things wanted/needed here can be done using a plain copy&paste of the blocks from the <application> area. This is mainly relevant for "single application" pnds. You can just copy the relevant parts into the <package> block and by this provide the information. Because of this I have *not* renamed terms like <author> to <packager> (which would make sense to do otherwise). * I want to have this block mandatory to pass schema validation. The main reason for this is to make it easier for package distribution systems. They can just scan for this block and are done and don't have to look at the <application> blocks for initial data collection (yes, it makes sense to also iterate through all application blocks, but the relevant stuff should be mentioned here). Since it is really easy to generate it, it should not be an extra burden on the author. * Of course there are mandatory as well as optional terms in the <package> block. * Here is an example of what a (rather) complete <package> block looks like: <package id="sample-package"> <version major="1" minor="0" release="0" build="0" type="release"/> <author name="packagers name" website="http://www.website.foo" email="user@name.who"/> <titles> <title lang="en_US">Sample Collection</title> <title lang="de_DE">Beispiel Sammlung</title> </titles> <descriptions> <description lang="en_US">This is a really verbose package with a whole lot of stuff from 2 different sources, mixing different things, having stuff in ways sometimes making use of stuff, often not.</description> <description lang="de_DE">Die gleiche Beschreibung wie oben, nur auf deutsch.</description> </descriptions> <icon src="my-icon.png"/> </package>
Now lets come to explaining the single blocks and the reasons behind them. The list below each section is about the parameters inside the tags themselves and only applied if the tag is actually used! 1) <package id="sample-package"> The ID behaves similar to the id used in the application block. For a single application pnd it might even make sense to use exactly the same. This is to allow "package managers" (no matter if repository or on the pandora) to check for existing packages and update if a more recent version of the package with this ID is available. (mandatory) id
2) <version major="1" minor="0" release="0" build="0" type="release"/> Identical to the <version> tag from <application> (in the way it works). This is meant to differ the version of the application collection from the versions of the single applications. Not really relevant for single application packages, but very relevant when talking about some package collections where single application versions might significantly differ and some version numbers increase, some decrease (downgrade!). Having this item is mandatory for schema validation. (mandatory) major (mandatory) minor (mandatory) release (mandatory) build (optional) type
3) <author name="packagers name" website="http://www.website.foo" email="user@name.who"/> This is the packager tag. Basically a way for the packager to state their name and website as well as the email address. This can be used to make contacting the packager easier. The website could eg also be the forum discussion thread for a given package. Having this item is mandatory for schema validation. (mandatory) name (optional) website (optional) email
4) <titles> <title lang="en_US">Sample Collection</title> <title lang="de_DE">Beispiel Sammlung</title> </titles> Of course packages need some kind of title (kde-games vs ksudoku/kpat/...), which can differ from the name of the applications. Having a title is mandatory, just as it is for the <application> block. Here translations are possible, too (eg the web interface could maybe also display in german or french and a package manager on the pandora could use the system locale which might not be en_US). Having at least one <title> inside a <titles> block is mandatory for schema validation (it is not easy to enforce having one en_US block included, but that is what should be there *at least*). (mandatory) lang (inside of <title> which is inside of <titles>)
5) <descriptions> <description lang="en_US">This is a really verbose package with a whole lot of stuff from 2 different sources, mixing different things, having stuff in ways sometimes making use of stuff, often not.</description> <description lang="de_DE">Die gleiche Beschreibung wie oben, nur auf deutsch.</description> </descriptions> The package itself might want to provide some explaining text. This tag is exactly meant for this. The description of eg the kde-games can say that this is the collection of games that kde does offer, while the single application descriptions would be about the respective application. For descriptions the same applies as for titles, they can be translated, too. Having a description is optional, though it is highly recommended to at least create one in en_US. (mandatory) lang (inside of <description> which is inside of <descriptions>)
6) <icon src="my-icon.png"/> Specify a package icon. For normal pandora usage this is 100% irrelevant. But it would/could be used by the repository and package manager. It could differ from the icon used for the single apps. Eg the single games within the kde-games bundle might want to have "game specific" icons, which would not fit nicely as "package" icon for the package database. Yes, I know that at the moment the icon does not make much sense, since the pnd has to be extracted to get to it, so the icon appended in the .pnd file itself can also be used. But once there is some infrastructure to more easily get to the previewpics and icons for the single apps this might be more interesting. Of course specifying an icon is completely optional when validating using the schema. (mandatory) src
Those are the basic changes that I propose. I attached the following files to the mail (all .xml files pass validation following the rules above unless explicitly mentioned):
1) average-case_PXML.xml A rather common single application pnd converted to follow the things mentioned above.
2) full-sample_PXML.xml A more complex PXML file that features many things allowed by the specs. Please look especially at things like the license blocks and the other new things mentioned in this mail.
3) minimum-libpnd_PXML.xml A rather minimum PXML file that will *not* pass validation but work nicely on the pandora.
4) minimum-schema_PXML.xml The minumum PXML file that still passes validation and will run on the Pandora.
5) old_PXML.xml An old file that still works on the pandora but won't pass validation (missing <package> block as well as wrong <title> and <description> blocks).
6) PXML_schema.xsd The schema definition file. It is basically the old file from [1] extended by the changes introduced and removing the dependency on "fixed order" for the entries inside the <application> block.
7) PXML_schema_plaintext.txt A more plaintext explanation in "coder terms" for those that don't like reading xml schema definitions. It is basically the old file from [1] extended by the changes introduced in this proposal and extended with some more info about the "numbers" used for cardinality throughout the file.
Now I am looking forward to your constructive criticism about this proposal. I hope I provided enough reasoning for the respective blocks (especially when reading this mail in context with the other mails that belong to this area) and the stuff I do propose is clearly understandable. Everything regarding PXML that is *not* mentioned in this mail is already part of the specs and mentioned at [2]. This is basically just an extension of the existing stuff, not a complete recreation.
If this is accepted as proposed here the following things would have to be done: * Implement "2) Change how <title> and <description> are listed" in libpnd. * Upload "PXML_schema.xsd" and "PXML_schema_plaintext.xml" (as well as possibly the example files) to [1] * Update the documentation in the wiki [2].
Cheers, Nils Kneuper aka Ivanovic
[1] http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=tree... [2] http://pandorawiki.org/PXML_specification