diff -r 333964c621f1 -r cb59d6afeb61 openpkg/release.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/release.pod	Tue Jan 06 23:40:39 2009 +0100
@@ -0,0 +1,128 @@
+##
+##  release -- OpenPKG Release Utility
+##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
+##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
+##
+##  Permission to use, copy, modify, and distribute this software for
+##  any purpose with or without fee is hereby granted, provided that
+##  the above copyright notice and this permission notice appear in all
+##  copies.
+##
+##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+##  SUCH DAMAGE.
+##
+
+=pod
+
+=head1 NAME
+
+B<openpkg release> - OpenPKG Release Utility
+
+=head1 SYNOPSIS
+
+B<openpkg release> [B<-F>|B<--fmt> I<format>]
+
+=head1 DESCRIPTION
+
+The B<openpkg release> command displays the OpenPKG release tag and
+distribution URL. The release tag uniquely identifies an OpenPKG
+distribution and the distribution URL is the location where the
+distribution packages and indices are stored.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-F>, B<--fmt> I<format>
+
+The output format specification. The argument I<format> is an arbitrary
+string which can contain the special expansion constructs "C<%t>" for
+expanding the release tag, "C<%u>" for expanding the distribution URL
+and "C<\n>" for expanding an embedded newline character. 
+The instance UUID information is also availble by expanding
+C<%r> to UUID_REGISTRY, C<%i> to UUID_INSTANCE, C<%p> to UUID_PLATFORM.
+The default I<format> is "C<OpenPKG-%t %u>".
+
+=item B<-r>, B<--release> I<release>
+
+The package "C<Release>" header value to use for deriving the release
+tag. The values in the F<@l_prefix@/etc/openpkg/release> file and the
+"C<Release>" header of the bootstrap package B<openpkg> are ignored if
+this option is used.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<@l_prefix@/etc/openpkg/release>
+
+This optional configuration file can be used to explicitly set values
+for the OpenPKG release tag and distribution URLs. It consists of lines
+with variable name/value pairs. The following configuration variables
+are recognized:
+
+=over 4
+
+=item B<TAG=>I<tag>
+
+The default I<tag> is automatically derived from the "C<Version>" header
+of the OpenPKG bootstrap package B<openpkg>. One usually only sets this
+explicitly to a value if a bootstrap package is used from a foreign
+distribution version.
+
+=item B<URL=>I<url>
+
+The fully-qualified distribution URL based on either the "C<ftp>",
+"C<http>" or "C<file>" URL schemes. If I<url> contains a trailing
+"C</*>", this is expanded according to the I<tag> value of the B<TAG>
+variable and the corresponding filesystem layout on C<ftp.openpkg.org>.
+The default I<url> is "C<ftp://ftp.openpkg.org/*>".
+
+=over
+
+=back
+
+=head1 EXAMPLE
+
+ $ openpkg release
+ OpenPKG-CURRENT ftp://ftp.openpkg.org/current/SRC/
+
+ $ openpkg release --fmt=%t
+ CURRENT
+
+ $ openpkg release --fmt=%u
+ ftp://ftp.openpkg.org/current/SRC/
+
+ $ openpkg release --fmt="OpenPKG %t is located at:\\n%u"
+ OpenPKG CURRENT is located at:
+ ftp://ftp.openpkg.org/current/SRC/
+
+ $ openpkg release --release=2.5.4 --fmt=%t
+ 2.5-RELEASE
+
+ $ cat /openpkg/etc/openpkg/release
+ TAG=2-STABLE-20060622
+ URL=ftp://ftp.example.com/mirror/openpkg.org/*
+
+=head1 SEE ALSO
+
+uuid(8)
+
+=head1 HISTORY
+
+The B<openpkg release> command first appeared in B<OpenPKG 2-STABLE-20060622>.
+
+=cut
+