<!-- 
Copyright (C) 2004 James Lowe, Jr.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or any
later version published by the Free Software Foundation; with no Invariant
Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
<!DOCTYPE form
[
<!ENTITY swconventions SYSTEM "swpackage_conventions.sgml">
]>
-->
<TITLE>
SWBIS PSF CONVENTIONS
</TITLE>
<PARA>
This section describes attribute usage and conventions imposed by the swbis implementation.
Not all attributes are listed here.  Those that are have important effects or
particular interest.
</PARA>
<REFSECT3>
<TITLE>
o Distribution Attributes
</TITLE>
<PARA>
The standard defines a limited set of attributes for the distribution object.
An expanded set is suggested by the informative annex however a conforming
implementation is not required act on them.  The reason for this is a
distribution may be acted upon by a conforming utility in such a way that attributes
of the <FUNCTION>distribution</FUNCTION> become invalid.
For this reason, some attributes that refer to an entire "package" [in other package managers]
are referred from the product object and attain their broadened scope by the distributor's
convention that their distribution contains just one
<FUNCTION>product</FUNCTION>.
</PARA>
<PARA>
For example, the package NAME and VERSION are referred from the product tag and revision,
not the distribution's.  This convention supports multiple products in a distribution and
is consistent with the standard.
</PARA>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the distribution.
Providing a distribution tag is optional.  The swbis implementation will use this as the
[single] path name prefix if there is no distribution.control_directory attribute.
A distribution tag attribute and swpackage's response to it is an implementation extension.
The leading package path can also be controlled with the ''-W dir'' option. 
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>control_directory</REPLACEABLE>, in a distribution object, is the constant leading package path.
Providing this attribute is optional.
A distribution control_directory attribute and swpackage's response to it is an implementation extension.
The leading package path can also be controlled with the ''-W dir'' option.  This attribute will be
generated by swpackage if not set in a PSF.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>

<REFSECT3>
<TITLE>
o Bundle Attributes
</TITLE>
<PARA>
A <FUNCTION>bundle</FUNCTION> defines a collection of products whether or not
the distribution has all the products present.
</PARA>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the bundle.
This value is used by the swbis implementation as a path name component in the
installed software catalog.  If it is not present the product tag is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>

<REFSECT3>
<TITLE>
o Product Attributes
</TITLE>
<PARA>
A <FUNCTION>product</FUNCTION> defines the software product.
</PARA>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the product.
This value is used by the swbis implementation as a path name component in the
installed software catalog.  It is required.  The swbis implementation uses it in a way 
that is analogous to the RPMTAG_NAME attribute.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
Is the directory name in the distribution under which the product contents are located.
This value has no affect on the installed software catalog.  If it is not given in a PSF
then the
<REPLACEABLE>tag</REPLACEABLE> is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
<PARA>
<OPTION>revision</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
Is the product revision.  It should not contain a "RELEASE" attribute part or other
version suffix modifiers.
This value is used by the swbis implementation as a path name component in the
installed software catalog.  It is required by swinstall.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>vendor_tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
This is a short identifying name of the distributor that supplied the product and
associates the <FUNCTION>vendor</FUNCTION> object from the INDEX file.
This attribute is optional.
This attribute value should strive to be unique among all distributors.
It is one of the version distinguishing attributes of a product specified by the standard. 
It is transfered into the installed_software catalog (not as a path name component) by swinstall.
If this attribute exists there should also be a
<OPTION>vendor</OPTION> object in the PSF in the distribution object that has this tag.
This attribute is assigned the value of RPMTAG_RELEASE by
swpackage when translating an RPM.
In this capacity it serves to distinguish products with the same revision and tag from the same or
different distributor.  It most closely maps to the RPMTAG_RELEASE or "debian_revision" attributes.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>
<REFSECT3>
<TITLE>
o Fileset Attributes
</TITLE>
<PARA>
A <FUNCTION>fileset</FUNCTION> defines the fileset.
</PARA>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the fileset.
It is required.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
Is the directory name in the product under which the fileset contents are located.
This value has no affect on the installed software catalog.  If it is not given in a PSF
then the
<REPLACEABLE>tag</REPLACEABLE> is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>
<REFSECT3>
<TITLE>
o Example Source Package PSF
</TITLE>
<PARA>
This PSF packages every file is current directory. It uses nil control directories
so the package structure does not change relative to a vanilla tarball.
</PARA>
<PROGRAMLISTING><SBR>
 distribution
   description "fooit - a program from fooware
that does everything."
   title "fooit - a really cool program"
   LICENSE < /usr/local/fooware/legalstuff/LICENSE
 vendor
   the_term_vendor_is_misleading true
   tag fooware
   title fooware Consultancy Services, Inc.
 product
   tag fooit
   control_directory "" 
 fileset
    tag fooit-SOURCE
    control_directory ""
    directory .
    file *
    exclude catalog
</PROGRAMLISTING>
</REFSECT3>

<REFSECT3>
<TITLE>
o Example Runtime (Binary) Package PSF
</TITLE>
<PARA>
This is a sample PSF for a runtime package.  It implies multiple products (e.g. sub-packages)
using the bundle.contents attribute.  Since the bundle and product tags exist in a un-regulated
namespace and are seen by end users they should be carefully chosen.   Note that the bundle
and product have the same tag which may force downstream users to disambiguate using software
selection syntax such as fooit,bv=* or fooit,pv=* .
</PARA>
<PROGRAMLISTING><SBR>
 distribution
   description "fooit - a program from fooware
that does everything."
   title "fooit - a really cool program"
   LICENSE < /usr/local/fooware/legalstuff/LICENSE

     vendor
        the_term_vendor_is_misleading false
        tag fooware
        title fooware Consultancy Services, Inc.
        description "Provider of the programs
 that do everything"

     vendor
        the_term_vendor_is_misleading false
         tag fw0
         title fooware Packaging Services, Inc.
         description "fooware Re-packaging service"

#  Bundle definition:
     bundle
         tag fooit
         vendor_tag fooware
         contents fooit,v=fw0 fooit-devel fooit-doc

#  Product definition:
     product
         tag fooit
         revision 1.34.56
         vendor_tag fw0
         postinstall scripts/postinstall
     fileset
          tag fooit-RUN
          file doc/man/man1/fooit.1 /usr/man/man1/fooit.1 
          file src/fooit /usr/bin/fooit
</PROGRAMLISTING>
</REFSECT3>
