|
|
| (One intermediate revision by one other user not shown) |
| Line 1: |
Line 1: |
| − | {{OutOfDate}}
| + | #REDIRECT [[PXML specification]] |
| − | This page is outdated. Please have a look at the '''example files provided in git''':
| |
| − | * [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
| |
| − | * [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-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.
| |
| − | | |
| − | | |
| − | | |
| − | This is a template for PXML files. It covers most of the spec and is considered to be ''clean'', meaning that it can be used as a sane starting point for PXML write-ups. It does no longer follow the schema specification and is not using "good style", but does provide some more in detail description. that can be adapted to "good" files, too. Please have a look at the list above to see some example files.
| |
| − | <source lang="xml">
| |
| − | <?xml version="1.0" encoding="UTF-8"?>
| |
| − | <!--This is an example PXML file for an application named "Exaile", to
| |
| − | demonstrate how a PXML file is supposed to be structured. Feel free to
| |
| − | replace all of the field contents with your own data, and to remove these
| |
| − | comments afterwards, in order to get a working and valid PXML file.
| |
| − | | |
| − | Note that this file is MINIMAL aka. this is the information you SHOULD
| |
| − | specify if you're well-behaved (all of it isn't NEEDED per-se, though) -->
| |
| − | | |
| − | <!--
| |
| − | PXML tag
| |
| − | Indicates the root node of a PXML file.
| |
| − | | |
| − | Attributes:
| |
| − | xmlns:
| |
| − | Identifies the namespace of this PXML file. Potential future PXML
| |
| − | specifications will use a different name space.
| |
| − | -->
| |
| − | <PXML xmlns="http://openpandora.org/namespaces/PXML">
| |
| − | <!--
| |
| − | application tag
| |
| − | Declares a new application that this PND package provides. Most PND
| |
| − | packages will only have one application entry, and it is discouraged to
| |
| − | have too many application entries in one PND file, since a PND file is
| |
| − | inseparable, i.e. an user cannot upgrade one app and leave another be if
| |
| − | they share the same PND file.
| |
| − | | |
| − | Attributes:
| |
| − | id:
| |
| − | Identifies the application in application enumerations.
| |
| − | This has to be a string that is unique to the package series; there
| |
| − | must not be two packages with entirely different purposes and
| |
| − | origins that share the same ID.
| |
| − | | |
| − | tl;dr: Choose an id like you would choose a package name on the
| |
| − | Linux Desktop.
| |
| − | | |
| − | Some things you have to consider when choosing an id:
| |
| − | - If you release new versions of your application, they should have
| |
| − | the same id as previous versions. Packages with different id's
| |
| − | are not considered to be related at all, while packages with
| |
| − | identical id's are considered to be of the same kind.
| |
| − | - Your id should not be too complex. You should choose something
| |
| − | that is unique to your application, and not something globally
| |
| − | unique.
| |
| − | - The application id will be used by package managers and the like.
| |
| − | So, choose something that you expect to be typed in as:
| |
| − | "installtool install %id%"
| |
| − | | |
| − | If you are publishing an application that you created yourself,
| |
| − | and that you don't expect anyone else to also publish, these
| |
| − | would be GOOD id's:
| |
| − | - "exaile"
| |
| − | - "myapp"
| |
| − | - "kdemod-extras-quassel"
| |
| − | - "awesome-music-player"
| |
| − | | |
| − | These would be BAD id's:
| |
| − | - "Exaile" - This is an user-adapted name and not a machine-
| |
| − | adapted name
| |
| − | - "Exaile - A music player that rocks" - This contains spaces and
| |
| − | might therefore be mistreated by shell scripts and the like.
| |
| − | - "exaile-1.0" - This contains version information; you should
| |
| − | put this information in the version tag below instead.
| |
| − | - "exaile-written-by-foobar-in-the-year-of-the-lord-two-thousand-and-ten-and-given-to-yall-for-free"
| |
| − | This is too long.
| |
| − | - "ae4c8bc112cafedd" - This doesn't identify *the application*, but
| |
| − | is just a random unique identifier.
| |
| − | These would be GOOD id's if you PORTED or MODDED an existing
| |
| − | application:
| |
| − | - "exaile-dflemstr" - (port) The app was ported by dflemstr
| |
| − | - "exaile-nox" - (mod) The app runs without X
| |
| − | - "exaile-player" - (port) Only a part of the application was
| |
| − | ported
| |
| − | - "exaile-pure" - (mod) Substantial mods were carried through, and
| |
| − | a rebranding was needed.
| |
| − | appdata:
| |
| − | Specifies a name for a data store for your application
| |
| − | This is where all your writes to CWD will end up when you run
| |
| − | your application. You should choose an user friendly name, but
| |
| − | *not* an user-adapted name (think about localization and
| |
| − | management).
| |
| − | Good alternatives:
| |
| − | - "exaile"
| |
| − | - "exaile-1" - If you intend to release newer versions that use
| |
| − | a different storage format.
| |
| − | - "exaile-dev" - If you want an user to be able to use a dev
| |
| − | version of your app, and a stable version of your app
| |
| − | simultaneously.
| |
| − | -->
| |
| − | <application id="exaile" appdata="exaile">
| |
| − | <!--
| |
| − | title tag(s)
| |
| − | Defines a human-readable title for the application in a specified locale.
| |
| − | You MUST specify a title with the language "en_US"; other localizations
| |
| − | are optional, but it is recommended to add one for generic,
| |
| − | not-only-american english ("en"). Titles and descriptions should also be
| |
| − | in pairs (you should not translate a title and omit a translation for a
| |
| − | description).
| |
| − | | |
| − | Attributes:
| |
| − | lang:
| |
| − | Specifies the language of the title.
| |
| − | | |
| − | This is made up of two parts:
| |
| − | - The language part. This code is the lower-case, two-letter
| |
| − | code as defined by ISO-639.
| |
| − | - OPTIONAL: The country part. This code is the upper-case,
| |
| − | two-letter code as defined by ISO-3166, with an underscore
| |
| − | as the prefix.
| |
| − | -->
| |
| − | <title lang="en_US">Exaile music player</title>
| |
| − | <title lang="sv">Exaile musikspelare</title>
| |
| − | <title lang="de">Exaile musikspieler</title>
| |
| − | | |
| − | <!--
| |
| − | description tag(s)
| |
| − | Defines a human-readable description for your application in a specified
| |
| − | locale. The same rules apply to this element, as to title elements. Note
| |
| − | that we by description don't mean page-long texts; the recommended length
| |
| − | for a description is 128 characters, but certain implementations support
| |
| − | up to 1024 or 4096 characters. More than that is absolutely not
| |
| − | recommended. Also, please remember that newlines are ignored in
| |
| − | descriptions according to the XML standard, but that spaces are
| |
| − | significant. XML escaping applies for the characters less-than,
| |
| − | greater-than and ampersand (< > & respectively).
| |
| − | | |
| − | Attributes:
| |
| − | lang:
| |
| − | See above.
| |
| − | -->
| |
| − | <description lang="en_US">A versatile music player written in Python.</description>
| |
| − | <description lang="sv">En kraftfull musikspelare skriven i Python.</description>
| |
| − | <description lang="de">Ein fähiger Musikspieler, in Python geschrieben.</description>
| |
| − | | |
| − | <!--
| |
| − | version tag
| |
| − | This specifies the version quadron for this application.
| |
| − | ALL FIELDS MUST BE POSITIVE INTEGERS OR 0. You are free to choose your
| |
| − | own versioning scheme (ie. "build" doesn't have to be the number of times
| |
| − | you built the application), but you must specify all four version fields
| |
| − | below.
| |
| − | -->
| |
| − | <version major="1" minor="0" release="0" build="2"/>
| |
| − | | |
| − | <!--
| |
| − | exec tag
| |
| − | Declares how the application should be started.
| |
| − | | |
| − | Attributes:
| |
| − | command:
| |
| − | The executable to start when the program is launched. This is
| |
| − | a path relative to the root of your PND file.
| |
| − | arguments:
| |
| − | Does the app need to be started with certain arguments every
| |
| − | time it is run? This is useful for PNDs that contain
| |
| − | multiple applications that use the same executable file.
| |
| − | (specify the actual arguments, not true/false unless your app
| |
| − | accepts true or false as arguments!)
| |
| − | background:
| |
| − | Can this application "be minimised" or should it run
| |
| − | singleton?
| |
| − | "true", "false", "1" or "0" accepted.
| |
| − | startdir:
| |
| − | Sets the CWD for the application before it is run.
| |
| − | Default is the PND mount point.
| |
| − | standalone:
| |
| − | Can this application run directly, or should it only be
| |
| − | started via associations? If this is "false" or "0", it
| |
| − | won't show up in launchers.
| |
| − | x11:
| |
| − | Can be one of:
| |
| − | "req" - X11 is required for the application to run.
| |
| − | "stop" - X11 must be stopped for the application to run.
| |
| − | "ignore" (default) - Don't care about X11.
| |
| − | -->
| |
| − | <exec command="./bin/exaile" background="true" standalone="true"/>
| |
| − | | |
| − | <!--
| |
| − | author tag
| |
| − | Contains information about the application author. All three fields
| |
| − | are optional.
| |
| − | | |
| − | NOTE: If you type 'name=""', this won't mean that you left out the
| |
| − | name! It only means that the name of the author is 0 characters
| |
| − | long! Implementations will e.g. display an empty 'Author: ' field
| |
| − | if you do this!
| |
| − | | |
| − | To leave out the name of the author, remove the attribute completely,
| |
| − | and to leave out author information completely, remove the whole tag.
| |
| − | -->
| |
| − | <author name="Bjornhild Andersson" website="http://some.website.with.author.info" email="a.b@c.de"/>
| |
| − | | |
| − | <!--
| |
| − | icon tag
| |
| − | Declares the icon for the application. This should be the same icon that
| |
| − | is appended to the PND file, or something different if *this* application
| |
| − | should have a different icon from the rest.
| |
| − | | |
| − | Attributes:
| |
| − | src:
| |
| − | Relative URI to the icon (can be a relative file, or a
| |
| − | fully-qualified URL; the latter is only supported in some
| |
| − | implementations)
| |
| − | -->
| |
| − | <icon src="icon.png"/>
| |
| − | | |
| − | <!--
| |
| − | categories tag
| |
| − | Specifies which categories this application belongs to. See
| |
| − | http://standards.freedesktop.org/menu-spec/latest/apa.html for more
| |
| − | information. The optional sub-element "subcategory" is currently ignored
| |
| − | by all implementations.
| |
| − | -->
| |
| − | <categories>
| |
| − | <category name="Audio"/>
| |
| − | <category name="Music"/>
| |
| − | <category name="GTK"/>
| |
| − | </categories>
| |
| − | </application>
| |
| − | </PXML>
| |
| − | </source>
| |
| − | [[Category:PND]]
| |
| − | [[Category:Documentation]]
| |
