The following is a list of MetaData fields defined in TIP #55 for use in the DESCRIPTION.txt file inside a Tcl package. If you would like to suggest a new field name, or discuss these, please do so at the end of this page. Let's try to keep this list definitive in some sense.
An important standard in MetaData is the Dublin Core element set and many of the field names below come from there. If you're proposing a new field name please browse the DC element set to see if there is an existing name that could be used. SC
Identifier
- This element is a string containing the name of the distributed package. The name may consist only of alphanumeric characters, colons, dashes and underscores. This name should correspond to the name of the package defined by this distribution (that is, the code should contain package provide xyzzy where xyzzy is the value of this element.
- Care must be taken to make this name unique among the package names in the archive. To overcome this, namespace style names separated by double colons should be used.
- Examples: xyzzy, tcllib, xml::soap, cassidy::wonderful-package_2
Version
- This element is a string containing the version of the package. It consists of 4 components separated by full stops. The components are major version, minor version, maturity and level; and are written in this order.
- The major and minor version components are integer numbers greater than or equal to zero.
- The component maturity is restricted to the values a, b. The represent the maturity states alpha, beta respectively. For a production release, this component can be omitted.
- The level component allows a more fine-grained differentiation of maturity levels. When a package has maturity production the level component is often called the patchlevel of the package. If the level component is zero, it may be ommitted.
- The period each side of the maturity component may be ommited.
- Valid version numbers can be decoded via the following regular expression:
regexp {([0-9]+)\.([0-9]+)\.?([ab])?\.?([0-9]*)} $ver => major minor maturity level- Examples: 8.4.0 8.4a1 2.5.b.5
Title
- This element is a free form string containing a one sentence description of the package contained in the distribution.
- Example: Installer Tools for Tcl Packages
Creator
- This element is a string containing the name of the person, organisation or service responsible for the creation of the package optionally followed by the email address of the author in angle brackets [L1 ]. More detail about an author can be provided in a seperate object in the description and if this is provided the email address should be used as the value of the Name field in that object.
- If there is more than one author this field may appear multiple times.
- Email addresses may be obfuscated to avoid spam harvesters.
- Example: Steve Cassidy <Steve.Cassidy at mq dot edu dot au>
Maintainer
- This element is a string analogous to the Creator element which contains the name of the current maintainer of the package.
Contributor
- This element is a string analogous to the Creator element which contains the name of a contributor to the package.
Rights
- Typically, a Rights element will contain a rights management statement for the resource, or reference a service providing such information. This will usually be a reference to the license under which the package is distributed. This can be a free form string naming the license or a URL refering to a document containing the text of the license.
- If the Rights element is absent, no assumptions can be made about the status of these and other rights with respect to the resource. * Examples: BSD, Artistic license
URL
- This element is a string containing an url refering to a document or site at which the information about the package can be found. This url is not the location of the distribution, as this might be part of a larger repository separate from the package site.
- Example: http://www.ics.mq.edu.au/~cassidy/tcl/
Available
- This element is the release data of the package in the form YYYY-MM-DD.
- YYYY is a four-digit integer number greater than zero denoting the year the distribution was released.
- MM is a two-digit integer number greater than zero and less than 13. It is padded with zero at the front if it less than 10. It denotes the month the distribution was released. The number 1 represents January, 2 represents February; and 12 represents December.
- DD is a two-digit integer number greater than zero and less than 32. It is and padded with zero at the front if less than 10. It denotes the day in the month the distribution was released.
- A valid data string can be obtained with the tcl command
[clock format [clock seconds] -format "%Y-%m-%d"]
- Example: 2002-01-23
- (The DC element is Date but it can be refined to Created, Available, Applies)
Description
- This element is a free form string briefly describing the package.
Architecture
- This element is a string describing one of the architectures included in the distribution. As a distribution is allowed to contain the files for several architectures, this element may appear multiple times and should correspond to a directory in the distribution.
Require
- Names a package that must be installed for this package to operate properly. This should have the same format as the package require command, eg. ?-exact? package ?version?.
- Example: http 2.0
Recommend
- Declares a strong, but not absolute dependancy on another package. In most cases this package should be installed unless the user has specific reasons not to install them.
Suggest
- Declares a package which would enhance the functionality of this package but which is not a requirement for the basic functionality of the package.
Conflict
- Names a package with which can't be installed alongside this package. The syntax is the same as for Require. If a conflicting package is present on the system, an installer might offer an option of removing it or not installing this package.
Subject
- The topic or content of the package expressed as a set of Keywords. At some future time, a set of canonical keywords may be established by a repository manager.
The first suggested extension to this set comes from Steve Landers to describe the person responsible for packaging an extension which might be different from the Creator. We borrow the field name used in the RPM world:
Packager
- This element is a string containing the name of the person, organisation or service responsible for the packaging of the software optionally followed by an email address in angle brackets [L2 ].
- If there is more than one author this field may appear multiple times.
- Email addresses may be obfuscated to avoid spam harvesters.
- Example: Steve Cassidy <Steve.Cassidy at mq dot edu dot au>
Another proposal comes from the need to store source code as well as installable packages in a repository such as CANTCL.
Type
- This element is a string describing the type of resource
- The value is limited to the set source, installable, documentation
- source is the source of an application or package
- installable is a package bundled in such a way that it can be installed automatically. The recommended format is that described in TIP55 but a more operational definition might be developed.
- documentation is a documentation file or bundle of these.
- Additional types may be added in future as the need arises
escargo 27 Nov 2002 - Is there a TIP to change the intepretation of version as understood by the package command to track what the Version field here specifies? They currently appear to be incompatible. Certainly there should also be some logic in the package require that allows one to specify only the latest stable (non-Alpha and non-Beta code).
--- LV Regarding uniqueness of distribution value - have you looked into NICS - which permits one to create public registries of such information? Perhaps the distribution field should be required to be on file in the registry?
Also, should not something be said regarding whether the above metadata is required to be unique or not? For instance, what would it mean if there were multiple identifiers in the file?
See also