From 49aecf458ffc55c0171fb097f624bbf68c72f198 Mon Sep 17 00:00:00 2001 From: Nils Kneuper Date: Sat, 5 Mar 2011 20:35:09 +0100 Subject: [PATCH] New schema as discussed on the firmware-dev ml, cf this thread: http://openpandora.org/pipermail/firmware-dev/2011-March/000056.html Added updated examples --- docs/PXML_schema.xsd | 288 +++++++++++++++++++------- docs/PXML_schema_plaintext.txt | 102 ++++++--- docs/examples/PXML-example.txt | 5 + docs/examples/PXML.xml | 99 ++++++--- docs/examples/average-case_PXML.xml | 46 ++++ docs/examples/full-sample_PXML.xml | 109 ++++++++++ docs/examples/minimum-libpnd_PXML.xml | 8 + docs/examples/minimum-schema_PXML.xml | 28 +++ 8 files changed, 551 insertions(+), 134 deletions(-) create mode 100644 docs/examples/average-case_PXML.xml create mode 100644 docs/examples/full-sample_PXML.xml create mode 100644 docs/examples/minimum-libpnd_PXML.xml create mode 100644 docs/examples/minimum-schema_PXML.xml diff --git a/docs/PXML_schema.xsd b/docs/PXML_schema.xsd index e756003..335efe5 100644 --- a/docs/PXML_schema.xsd +++ b/docs/PXML_schema.xsd @@ -1,6 +1,10 @@ + + + + @@ -9,6 +13,7 @@ + @@ -16,6 +21,7 @@ + @@ -23,147 +29,281 @@ + + + + + + + + + + + - + + + + + + - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + - - - + + + + + + + - - - - - - + + + + - - - - - - - - - - - - - - + + - - - + + + + + + + + + + + + + + + + + + + - + + + + + + - - - - + + + + - - + + + + + + - - - - + + + + - - - - - - - - - - - + + - + + + - + + + - - - - - + - - - - - - - + - + - + @@ -179,13 +319,7 @@ - - - - - - - + @@ -195,7 +329,7 @@ - + diff --git a/docs/PXML_schema_plaintext.txt b/docs/PXML_schema_plaintext.txt index 98e8f69..443ab98 100644 --- a/docs/PXML_schema_plaintext.txt +++ b/docs/PXML_schema_plaintext.txt @@ -1,29 +1,67 @@ - NOTES: - -Note 1) PXML_schema.xsd is overly picky about line-ordering; the line order is not required in practice, - but requiring the ordering makes the validator happy; this the validator may reject a valid PXML.xml -Note 2) libpnd is not (currently) as picky as the validator (since it only consumes some values, and will +Note 1) libpnd is not (currently) as picky as the validator (since it only consumes some values, and will sometimes 'trust' bad values in hopes things will just work anyway), but many of the online download - repositories _will_ use this validator, so it is probably a good idea to make your PXMLs conform! -Note 3) These points aside -- anything passing the validator should pass into libpnd just fint; PXML.xmls that + repositories _will_ use this validator, so it is probably a good idea to make your PXMLs conform! For + example the block is currently not used/required for libpnd to work. +Note 2) These points aside -- anything passing the validator should pass into libpnd just fine; PXML.xmls that do not pass the validator may well work with libpnd, depending on the nature of the rejection -- if the PXML.xml is just bad, fix it! But if the validator rejects the PXML.xml on grounds of bad categories or line ordering or whatever, then libpnd will 'accept' the application, but may - massage things to work. -Note 4) minimenu and xfce and other Freedesktop Statandard adhering applications may actually be pickier about + massage things to work (eg add the application into the category 'Other' or do some more obscure things). +Note 3) minimenu and xfce and other Freedesktop Standard adhering applications may actually be pickier about some things than the validator -- the validator will verify the categories and subcategories are known to the Freedesktop spec, but does not validate that a FD subcategory actually belongs to the listed parent category. +How to read this doc: +* Every entry comes with a cardinality. Here is the meaning of those: + =1: this block is required exactly once + <=1: up to one of those blocks is allowed (0 or 1) + >=1: at least one of those is allowed, more are possible but optional + >=0: optional element that can be added in unlimited numbers +* The actually used 'tag's are always displayed in this form: . +* Arguments are always marked either as optional or required and mention what allowed values are. At the bottom + of this doc is an explanation of most of those values. If you see [abc|xyz] it means that either 'abc' or + 'xyz' are valid values. +* In general 'order' of elements does not matter unless stated otherwise. +* If a block is used, the content is usually *NOT* allowed to be empty. So if you don't want to use something, + don't specify that argument! + + Now, onto the actual specification: -1) at the root there is *exactly* one PXML block -2) inside this PXML block are >=1 blocks +1) at the root there is *exactly* one block +2) inside this PXML block is exactly =1 block + (required) id=DUMBFOLDERNAME +3) inside this PXML block are >=1 blocks (required) id=DUMBFOLDERNAME (optional) appdata=DUMBFOLDERNAME -inside each application block: + +inside the block: +1) =1 + (required) name=TEXT + (optional) website=anyURI + (optional) email=EMAILADDRESS +2) =1 + (required) major=VERSION_NR + (required) minor=VERSION_NR + (required) release=VERSION_NR + (required) build=VERSION_NR + (optional) type=[alpha|beta|release] +3) =1 (order matters!) + (required) =1 TEXT (enforcing that an en_US string is available, has to be listed first) + (optional) >=1 TEXT + (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) +4) <=1 (order matters!) + (required) =1 TEXT (enforcing that an en_US string is available, has to be listed first) + (optional) >=0 TEXT + (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) +5) <=1 + (required) src=DUMBPATH + + +inside each block: 1) =1 (required) command=TOKEN (optional) arguments=TOKEN @@ -31,49 +69,61 @@ inside each application block: (optional) startdir=DUMBPATH (optional) standalone=BOOLEAN (optional) x11=[req|stop|ignore] -2) >=1 TEXT - (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) -3) =1 +2) =1 (required) name=TEXT (optional) website=anyURI (optional) email=EMAILADDRESS -4) =1 +3) =1 (required) major=VERSION_NR (required) minor=VERSION_NR (required) release=VERSION_NR (required) build=VERSION_NR -5) <=1 + (optional) type=[alpha|beta|release] (if not specified 'release' will be assumed) +4) <=1 (required) major=VERSION_NR (required) minor=VERSION_NR (required) release=VERSION_NR (required) build=VERSION_NR -6) >=0 TEXT - (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) -7) <=1 +5) =1 (order matters!) + (required) =1 TEXT (enforcing that an en_US string is available, has to be listed first) + (optional) >=0 TEXT + (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) +6) <=1 TEXT (meant for compatibility with <=HF6, only en_US supported) +7) <=1 (order matters!) + (required) =1 TEXT (enforcing that an en_US string is available, has to be listed first) + (optional) >=0 TEXT + (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* ) +8) <=1 TEXT (meant for compatibility with <=HF6, only en_US supported) +9) <=1 (required) src=DUMBPATH -8) <=1 +10)=1 + (required) >=1 + (required) name=TEXT + (required) url=anyURI + (required) sourcecodeurl=anyURI +11)<=1 (optional) >=0 (required) src=DUMBPATH -9) <=1 +12)<=1 (required) name=TEXT (required) type=[text/html|text/plain] (required) src=DUMBPATH -10)=1 +13)=1 (required) >=1 (required) name=fdoCategory (optional) (required) name=fdoSubCategory -11)<=1 +14)<=1 (required) >=1 (required) name=TEXT (required) filetype=TOKEN (required) arguments=TOKEN -12)<=1 +15)<=1 (required) frequency=positiveInteger -Filetype/variable explaination: +Filetype/variable explanation: anyURI: should be some URL, no idea what exactly XML accepts there... (XML variable 'anyURI'!) BOOLEAN: 0 or 1 or true or false (XML variable 'boolean'!) DUMBFOLDERNAME: TEXT without ?>:/ diff --git a/docs/examples/PXML-example.txt b/docs/examples/PXML-example.txt index 13075bb..7b0bee5 100644 --- a/docs/examples/PXML-example.txt +++ b/docs/examples/PXML-example.txt @@ -1,3 +1,8 @@ The best and most-current PXML example (if overly comprehensive) is here: http://pandorawiki.org/PXML_archetype + +Various stages of PXML.xml files are shown here. They show the minimum that +still validates with the schema, the minimum that is usable on the pandora, as +well as some examples of average and "full" case. At the top of each file you +will find a short summary what this PXML.xml file tries to show. diff --git a/docs/examples/PXML.xml b/docs/examples/PXML.xml index 76f1e11..c42003a 100644 --- a/docs/examples/PXML.xml +++ b/docs/examples/PXML.xml @@ -1,43 +1,80 @@ - - Program Title - German Program Title + + - + - + - This is the English Description of the file. - This would be the German description. + - - - - + + Program Title + German Program Title + - + + This is the English Description of the file. + This would be the German description. + - - + - - - - - - - - - + - - - - - + + + + + + + + + + + Program Title + German Program Title + + Program Title + + + This is the English Description of the file. + This would be the German description. + + This is the English Description of the file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - ......kfujl........ - ......qwe......fwer..... diff --git a/docs/examples/average-case_PXML.xml b/docs/examples/average-case_PXML.xml new file mode 100644 index 0000000..bb2e1d1 --- /dev/null +++ b/docs/examples/average-case_PXML.xml @@ -0,0 +1,46 @@ + + + + + + + + Sample Application + Beispiel Anwendung + + + A really lenghty description for the application. + Die Beschreibung einer Beispielanwendung. + + + + + + + + + + Sample Application + Beispiel Anwendung + + Sample Application + + A really lenghty description for the application. + Die Beschreibung einer Beispielanwendung. + + A really lenghty description for the application. + + + + + + + + + + + + + + + diff --git a/docs/examples/full-sample_PXML.xml b/docs/examples/full-sample_PXML.xml new file mode 100644 index 0000000..01b3bea --- /dev/null +++ b/docs/examples/full-sample_PXML.xml @@ -0,0 +1,109 @@ + + + + + + + + Sample Collection + Beispiel Sammlung + + + 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. + Die gleiche Beschreibung wie oben, nur auf deutsch. + + + + + + + + + + Sample Application 1 + Beispiel Anwendung 1 + + Sample Application 1 + + A really lenghty description for the application. + Die Beschreibung einer Beispielanwendung. + + A really lenghty description for the application. + + + + + + + + + + + + + + + + + + + + + + + + + Sample Application + Beispiel Anwendung + + Sample Application + + A really lenghty description for the application. Just different + Die Beschreibung einer *anderen* Beispielanwendung. + This is in french! + + A really lenghty description for the application. Just different + + + + + + + + + + + + + + + + + + + + + Sample Application + + Sample Application + + Additional tool description. + + Additional tool description. + + + + + + + + + + + + + + + + + diff --git a/docs/examples/minimum-libpnd_PXML.xml b/docs/examples/minimum-libpnd_PXML.xml new file mode 100644 index 0000000..1532c40 --- /dev/null +++ b/docs/examples/minimum-libpnd_PXML.xml @@ -0,0 +1,8 @@ + + + + + + Sample Application + + diff --git a/docs/examples/minimum-schema_PXML.xml b/docs/examples/minimum-schema_PXML.xml new file mode 100644 index 0000000..9c6bd1b --- /dev/null +++ b/docs/examples/minimum-schema_PXML.xml @@ -0,0 +1,28 @@ + + + + + + + + Sample Application + + + + + + + Sample Application + + + + + + + + + + + + -- 2.39.5