basic API documentation, not yet finished.

1 files changed, 44 insertions, 0 deletions

diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
new file mode 100644
index 00000000000..583b7dfd282
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
@@ -0,0 +1,44 @@
+$OpenBSD: OpenBSD::PkgCfl.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PkgCfl - C<pkg_create(1)> C<@conflict> handling
+
+=head1 SYNOPSIS
+
+    use OpenBSD::PkgCfl;
+
+    $clist = OpenBSD::PkgCfl->make_conflicts_list($plist);
+    @cfls = $clist->conflicts_with(@pkgnames);
+
+    OpenBSD::PkgCfl::register($plist, $state);
+    OpenBSD::PkgCfl::unregister($plist, $state);
+    @cfls = OpenBSD::PkgCfl::find_all($plist, $state);
+
+=head1 DESCRIPTION
+
+C<OpenBSD::PkgCfl> is the canonical interface to packing-list conflict
+handling.
+
+Conflict information can be extracted from a packing-list 
+(see L<OpenBSD::PackingList>) through the
+C<OpenBSD::PkgCfl> class method. The result is an opaque object C<$clist> that
+can be queried to find out which package names conflict with the 
+packing-list.   A query of the form C<$clist-E<gt>conflicts_with(@pkgnames)>
+will extract from the list the package names that actually conflict with
+the packing-list.
+
+Most handling of conflict information happens through the higher level
+interface: C<OpenBSD::PkgCfl::register>, C<OpenBSD::PkgCfl::unregister> 
+and C<OpenBSD::PkgCfl::find_all>.  Package tools usually handle installed 
+packages, and this interface automatically takes the initial set of installed
+packages into account. The C<register> and C<unregister> functions must 
+be used to add and remove a packing-list from the set of installed packages, 
+where conflict information is concerned.
+
+The C<find_all> function can be used to find out about all possible conflicts
+a new packing-list will entail, before actually adding the package.
+
+The extra argument C<$state> is a hash used to record system-wide options. 
+In this case, it acts as a hidden object that records all conflict 
+information. The hash key C<conflict_list> is reserved for that purpose.