docs/PXML_schema_plaintext.txt

   1 NOTES:
   2 Note 1) libpnd is not (currently) as picky as the validator (since it only consumes some values, and will
   3         sometimes 'trust' bad values in hopes things will just work anyway), but many of the online download
   4         repositories _will_ use this validator, so it is probably a good idea to make your PXMLs conform! For
   5         example the <package> block is currently not used/required for libpnd to work.
   6 Note 2) These points aside -- anything passing the validator should pass into libpnd just fine; PXML.xmls that
   7         do not pass the validator may well work with libpnd, depending on the nature of the rejection --
   8         if the PXML.xml is just bad, fix it! But if the validator rejects the PXML.xml on grounds of
   9         bad categories or line ordering or whatever, then libpnd will 'accept' the application, but may
  10         massage things to work (eg add the application into the category 'Other' or do some more obscure things).
  11 Note 3) minimenu and xfce and other Freedesktop Standard adhering applications may actually be pickier about
  12         some things than the validator -- the validator will verify the categories and subcategories are
  13         known to the Freedesktop spec, but does not validate that a FD subcategory actually belongs to the
  14         listed parent category.
  15
  16 How to read this doc:
  17 * Every entry comes with a cardinality. Here is the meaning of those:
  18   =1: this block is required exactly once
  19   <=1: up to one of those blocks is allowed (0 or 1)
  20   >=1: at least one of those is allowed, more are possible but optional
  21   >=0: optional element that can be added in unlimited numbers
  22 * The actually used 'tag's are always displayed in this form: <tag>.
  23 * Arguments are always marked either as optional or required and mention what allowed values are. At the bottom
  24   of this doc is an explanation of most of those values. If you see [abc|xyz] it means that either 'abc' or
  25   'xyz' are valid values.
  26 * In general 'order' of elements does not matter unless stated otherwise.
  27 * If a block is used, the content is usually *NOT* allowed to be empty. So if you don't want to use something,
  28   don't specify that argument!
  29
  30
  31 Now, onto the actual specification:
  32
  33 1) at the root there is *exactly* one <PXML> block
  34 2) inside this PXML block is exactly =1 <package> block
  35         (required) id=DUMBFOLDERNAME
  36 3) inside this PXML block are >=1 <application> blocks
  37         (required) id=DUMBFOLDERNAME
  38         (optional) appdata=DUMBFOLDERNAME
  39
  40
  41 inside the <package> block:
  42 1) =1 <author>
  43         (required) name=TEXT
  44         (optional) website=anyURI
  45         (optional) email=EMAILADDRESS
  46 2) =1 <version>
  47         (required) major=VERSION_NR
  48         (required) minor=VERSION_NR
  49         (required) release=VERSION_NR
  50         (required) build=VERSION_NR
  51         (optional) type=[alpha|beta|release]
  52 3) =1 <titles> (order matters!)
  53         (required) =1 <description lang="en_US">TEXT</description> (enforcing that an en_US string is available, has to be listed first)
  54         (optional) >=1 <title>TEXT</title>
  55                         (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* )
  56 4) <=1 <descriptions> (order matters!)
  57         (required) =1 <description lang="en_US">TEXT</description> (enforcing that an en_US string is available, has to be listed first)
  58         (optional) >=0 <description>TEXT</description>
  59                         (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* )
  60 5) <=1 <icon>
  61         (required) src=DUMBPATH
  62
  63
  64 inside each <application> block:
  65 1) =1 <exec>
  66         (required) command=TOKEN
  67         (optional) arguments=TOKEN
  68         (optional) background=BOOLEAN
  69         (optional) startdir=DUMBPATH
  70         (optional) standalone=BOOLEAN
  71         (optional) x11=[req|stop|ignore]
  72 2) =1 <author>
  73         (required) name=TEXT
  74         (optional) website=anyURI
  75         (optional) email=EMAILADDRESS
  76 3) =1 <version>
  77         (required) major=VERSION_NR
  78         (required) minor=VERSION_NR
  79         (required) release=VERSION_NR
  80         (required) build=VERSION_NR
  81         (optional) type=[alpha|beta|release] (if not specified 'release' will be assumed)
  82 4) <=1 <osversion>
  83         (required) major=nonNegativeInteger
  84         (required) minor=nonNegativeInteger
  85         (required) release=nonNegativeInteger
  86         (required) build=nonNegativeInteger
  87 5) =1 <titles> (order matters!)
  88         (required) =1 <title lang="en_US">TEXT</title> (enforcing that an en_US string is available, has to be listed first)
  89         (optional) >=0 <title>TEXT</title>
  90                         (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* )
  91 6) <=1 <title lang="en_US">TEXT</title> (meant for compatibility with <=HF6, only en_US supported)
  92 7) <=1 <descriptions> (order matters!)
  93         (required) =1 <description lang="en_US">TEXT</description> (enforcing that an en_US string is available, has to be listed first)
  94         (optional) >=0 <description>TEXT</description>
  95                         (required) lang=LANGCODE ( [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})* )
  96 8) <=1 <description lang="en_US">TEXT</description> (meant for compatibility with <=HF6, only en_US supported)
  97 9) <=1 <icon>
  98         (required) src=DUMBPATH
  99 10)=1 <licenses>
 100         (required) >=1 <license>
 101                         (required) name=TEXT
 102                         (required) url=anyURI
 103                         (required) sourcecodeurl=anyURI
 104 11)<=1 <previewpics>
 105         (optional) >=0 <pic>
 106                         (required) src=DUMBPATH
 107 12)<=1 <info>
 108         (required) name=TEXT
 109         (required) type=[text/html|text/plain]
 110         (required) src=DUMBPATH
 111 13)=1 <categories>
 112         (required) >=1 <category>
 113                         (required) name=fdoCategory
 114                         (optional) <subcategory>
 115                                   (required) name=fdoSubCategory
 116 14)<=1 <associations>
 117         (required) >=1 <association>
 118                         (required) name=TEXT
 119                         (required) filetype=TOKEN
 120                         (required) arguments=TOKEN
 121 15)<=1 <clockspeed>
 122         (required) frequency=positiveInteger
 123
 124
 125
 126 Filetype/variable explanation:
 127 anyURI: should be some URL, no idea what exactly XML accepts there... (XML variable 'anyURI'!)
 128 BOOLEAN: 0 or 1 or true or false (XML variable 'boolean'!)
 129 DUMBFOLDERNAME: TEXT without ?>:/
 130 DUMBPATH: TEXT without ?>:
 131 EMAILADDRESS: [^@]+@[^\.]+\..+      in normal lang: something with an @ in the middle and some domain like thingie
 132 LANGCODE: [a-zA-Z]{2,3}(_[a-zA-Z0-9]{2,3})*   example: en, eng, en_US, fur_IT
 133 TEXT: The normalizedString data type also contains characters, but the XML processor will remove line feeds, carriage returns, and tab characters. (XML variable 'normalizedString'!)
 134 TOKEN: The token data type also contains characters, but the XML processor will remove line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces. (XML variable 'token'!)
 135 VERSION_NR: [a-zA-Z0-9+-]*   example: 1, a, +svn, -svn, 123456789123456789
 136 nonNegativeInteger: numberical characters only, no matter if 0 or 123456789
 137
 138 fdoCategory=AudioVideo|Audio|Video|Development|Education|Game|Graphics|Network|Office
 139 fdoSubCategory=Building|Debugger|IDE|GUIDesigner|Profiling|RevisionControl|Translation|Calendar|ContactManagement|Database|Dictionary|Chart|Email|Finance|FlowChart|PDA|ProjectManagement|Presentation|Spreadsheet|WordProcessor|2DGraphics|VectorGraphics|RasterGraphics|3DGraphics|Scanning|OCR|Photography|Publishing|Viewer|TextTools|DesktopSettings|HardwareSettings|Printing|PackageManager|Dialup|InstantMessaging|Chat|IRCClient|FileTransfer|HamRadio|News|P2P|RemoteAccess|Telephony|TelephonyTools|VideoConference|WebBrowser|WebDevelopment|Midi|Mixer|Sequencer|Tuner|TV|AudioVideoEditing|Player|Recorder|DiscBurning|ActionGame|AdventureGame|ArcadeGame|BoardGame|BlocksGame|CardGame|KidsGame|LogicGame|RolePlaying|Simulation|SportsGame|StrategyGame|Art|Construction|Music|Languages|Science|ArtificialIntelligence|Astronomy|Biology|Chemistry|ComputerScience|DataVisualization|Economy|Electricity|Geography|Geology|Geoscience|History|ImageProcessing|Literature|Math|NumericalAnalysis|MedicalSoftware|Physics|Robotics|Sports|ParallelComputing|Amusement|Archiving|Compression|Electronics|Emulator|Engineering|FileTools|FileManager|TerminalEmulator|Filesystem|Monitor|Security|Accessibility|Calculator|Clock|TextEditor|Documentation|Core|KDE|GNOME|GTK|Qt|Motif|Java|ConsoleOnly