diff -r 71503088f51b -r f880f219c566 openpkg/mirror.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/mirror.pod	Tue Jul 31 12:23:42 2012 +0200
@@ -0,0 +1,137 @@
+##
+##  mirror.pod -- OpenPKG Package Mirroring
+##  Copyright (c) 2011-2012 OpenPKG GmbH <http://openpkg.com/>
+##
+##  This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
+##  All rights reserved. Licenses which grant limited permission to use,
+##  copy, modify and distribute this software are available from the
+##  OpenPKG GmbH.
+##
+##  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 mirror> - B<OpenPKG> Package Mirroring
+
+=head1 SYNOPSIS
+
+B<openpkg>
+B<mirror>
+[B<-h>]
+[B<-f>]
+[B<-q>]
+[B<-C> I<local-cache-file>]
+[B<-r> I<remote-url>]
+[B<-p> I<remote-url-prefix>]
+I<local-dir-prefix> ...
+
+=head1 DESCRIPTION
+
+The B<openpkg mirror> tool is a frontend for mirroring OpenPKG
+repositories, based on the OpenPKG XML/RDF index files B<openpkg
+index -S -T -D> creates. The resulting mirror can then be used with
+B<openpkg build>.
+
+=head1 COMMAND LINE ARGUMENTS
+
+The following command line options and arguments exist:
+
+=over 4
+
+=item B<-h>
+
+Print usage help.
+
+=item B<-f>
+
+Force deletion of local files, even if more than 30% of the existing
+local files have to be removed.
+
+=item B<-q>
+
+More quiet operation, i.e., do not print interactive download progress
+bars.
+
+=item B<-C> I<local-cache-file>
+
+Use the text-file I<local-cache-file> for caching size/mtime/MD5
+information of local files in order to especially avoid the expensive
+re-calculation of MD5 message digests of local files on every mirror
+operation. It is strongly advised to use such a cache. Do NOT place
+I<local-cache-file> under I<local-dir-prefix>.
+
+=item B<-r> I<remote-url>
+
+The OpenPKG repository URL. By default the same URL as for B<openpkg
+build> is used: C<http://download.openpkg.org/stacks/current/source/>
+
+=item B<-p> I<remote-url-prefix>
+
+In case the I<remote-url> (option B<-r> above) points NOT to a
+root/base directory of the remote repository, it is required to
+provide the corresponding base directory I<remote-url-prefix> in
+order to allow all remote paths to be correctly mapped to sub-paths
+under I<local-dir-prefix>. By default I<remote-url-prefix> is
+just I<remote-url>. For the public OpenPKG default repository URL
+C<http://download.openpkg.org/stacks/current/source/> the corresponding
+I<remote-url-prefix> is C<http://download.openpkg.org/>.
+
+=item I<local-dir-prefix>
+
+The local base directory under which the mirror is established.
+Content-wise it directly corresponds to I<remote-url-prefix> (option
+B<-p> above).
+
+=back
+
+=head1 EXAMPLE
+
+The following command mirrors the public OpenPKG-CURRENT repository
+files from download.openpkg.org to the local directory F<download/>. The
+prefix specification is important as the OpenPKG-CURRENT stack index
+points upwards.
+
+ $ openpkg mirror \
+   -C download.cache \
+   -r http://download.openpkg.org/stacks/current/source/ \
+   -p http://download.openpkg.org/ \
+   download/ 
+
+The mirror now can be used with B<openpkg build>:
+
+ $ openpkg build \
+   -r file://`pwd`/download/stacks/current/source/ \
+   -Uaq | sh
+
+=head1 SEE ALSO
+
+index(8).
+
+=head1 HISTORY
+
+The B<openpkg mirror> command was invented in May 2012 by I<Ralf
+S.  Engelschall> E<lt>rse@engelschall.comE<gt> for use inside the
+B<OpenPKG> project E<lt>http://www.openpkg.org/E<gt>.
+
+=head1 AUTHORS
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+=cut
+