1 files changed, 236 insertions, 0 deletions
diff --git a/man/7/pkg.pod b/man/7/pkg.pod
new file mode 100644
index 0000000..c9163d7
--- /dev/null
+++ b/man/7/pkg.pod
@@ -0,0 +1,236 @@
+=head1 NAME
+
+pkg - distributed dotfile and script manager, package format
+
+=head1 INTRO
+
+(if you prefer technical infos over historical blah-blah, skip this section)
+
+Actually, pkg is just a pimped dotfile manager, which just happens to support
+a sort of packages, version control, automatic sym- and hardlinking, and which
+can also handle scripts and binaries. Oh, and it can cause serious brain damage.
+
+It evolved from two hg repos for ~/bin and ~/etc and some management scripts,
+and now it can handle as many git repos as you want, which may contain
+basically anything you can think of - you can even store movies in them.
+(Of course that would be completely braindead, but hey -
+you could, if you wanted to)
+
+=head1 THE BASICS
+
+pkg requires two directories in you home directory. B<~/bin> contains
+symlinks to the executables shipped with your packages, and $PKG_DIR
+(B<~/packages> by default) contains the
+packages themselves. B<~/bin> may also contain normal executables; pkg will
+not overwrite existing files.
+
+=head1 THE PACKAGE DIRECTORY
+
+$PKG_DIR is the core of all this stuff. Its main use is storing the packages.
+There is one directory for each installed package, as created by B<git clone>.
+$PKG_DIR holds two special files: B<.list> and B<.list-remote>. For
+an explanation about these files, see L</"THE PACKAGE LIST"> below.
+It also contains a special directory, F<.collected> - see L</"COLLECTED PACKAGE FILES">.
+
+=head2 NOTE
+
+All directories in $PKG_DIR must be valid git repositories which are not in the
+state of 'initial commit'. Dotfiles (directories starting with a .) are exempt
+from this, they will be ignored by pkg.
+
+=head1 THE PACKAGE ROOT
+
+The packages_root, in pkg referred to as $PKG_ROOT, is structured just like
+the packages directory $PKG_DIR, except that it neither contains .list nor
+.list-remote. The packages root is the central point where pkg fetches
+packages from and pushes packages to.
+
+The package root should contain the pkglist script shipped in include/.
+If it doesn't, PKGLIST_PATH in .pkg.conf must be set to the appropiate
+location on the package root host.
+
+=head1 THE PACKAGE LIST
+
+Thi package list lives in the files B<.list> and B<.list-remote> mentioned
+above. It's used to decide whether a package needs to be pulled / pushed.
+Also, the 'pkg add' completion relies on .list-remote, and back in the days when
+pkg supported more than one DVCS, it was used to determine which DVCS to use
+for which package.
+
+It consists of one line per package, each line containing three items separated
+by a single whitespace. The first item is the package name, the second one the
+repository type (DVCS), the third the current revision. Example:
+
+  pkg git 82d716d01dee0329af7df5e67b55558fe3ff1466
+
+=head1 WHAT IS A PACKAGE?
+
+Anything tracked with git can be used as package. However, as the purpose of pkg
+is not to do your version control, you probably want to have at least one of the
+files and directories described below in it.
+
+=head1 PACKAGE STRUCTURE
+
+Special (as in, mostly handled by pkg) directories and files in a package.
+
+Unless marked with [*], all files and directories are optional
+
+=over
+
+=item bin/
+
+The place for executables to be in the user's PATH.
+pkg will automatically create symlinks in F<~/bin> pointing to the files
+in the package's F<bin/>. Also, if a file in F<bin/> contains valid POD,
+a manual will be generated out of it (see L</"COLLECTED PACKAGE FILES">)
+
+=item etc/
+
+Configuration files, not threated specially though
+
+=item hooks/
+
+Package hooks, see L</"HOOKS">
+
+=item include/
+
+Scripts used by the package that don't belong into B<bin/>. Not threated specially
+
+=item man/
+
+Manual files in POD format, separated by section (like man/7/pkg.pod).
+To be prepared for possible future support of other manual formats, it is
+recommended to postfix each file with .pod
+
+=item provides/
+
+Files for inclusion into other packages
+
+=item description
+
+Package description for B<pkg info>
+
+=item links
+
+Sym- and hardlink descriptions. See checklinks(1)
+
+=item Makefile
+
+If a Makefile is available, C<make> will be executed
+
+=item prereqs
+
+The package's prerequisites, mainly dependencies. See L</"PREREQUISITES">
+
+=item priority
+
+Package priority as an integer between 1 and 6.
+Packages with a priority above 3 require user confirmation to be removed
+
+=back
+
+=head1 PREREQUISITES
+
+The prerequisites are stored in a package in the file F<prereqs>.
+It as an ordinary shell script which is sourced by pkg's global post-update
+hook; so it will be sourced after pulling, pushing or refreshing a package.
+
+Note that the file will be sourced in function scope. It is recommended to
+introduce parameters and options local to the prereqs script with
+C<< typeset >> and C<< setopt localoptions >>, respectively.
+
+It's main use is to check for dependencies. To help with this, the following
+functions are available:
+
+=over
+
+=item B<is_installed> I<package>
+
+Returns true if I<package> is installed, otherwise false
+
+=item B<perlmodule> I<perlmodule>
+
+Returns true if I<perlmodule> can be used by perl, otherwise false
+
+=item B<executable> I<commendname>
+
+Returns true if I<commandname> was found in the users PATH, otherwise false
+
+=item B<offer_install> I<package>
+
+Mark I<package> for installation
+
+=item B<depend> I<expression> | B<depend package> I<package>
+
+Execute expression and automatically warn if it fails.
+In case of B<depend package>, automatically mark B<package> for installation
+if it isn't installed.
+If a B<depend> fails, pkg will inform the user about it and wait for confirmation
+
+=item B<recommend> I<...>, B<suggest> I<...>
+
+Take the same arguments as B<depend>, but are of lower priority.
+recommend only causes "info" messages, and suggest does not interrupt pkg
+to make sure it's read by the user
+
+=back
+
+Additionally, the string parameters B<warn> and B<info> can be used to store
+messages.
+
+After executing the prereqs script, pkg will print the content of
+these parameters; in case of B<warn>, it will also wait for confirmation.
+It will also offer to install packages marked by B<depend package> or
+B<recommend package>.
+
+=head1 HOOKS
+
+Hooks are little zsh-snippets residing in $PKG_DIR/hooks
+which are sourced from within pkg whenever needed.
+
+Currently, the following hooks exist:
+
+=over
+
+=item post-add
+
+Sourced after a package was installed (e.g. with pkg add/pkg install)
+
+=item post-update
+
+Sourced after a package was updated (pkg upgrade/pkg pull).
+It is also sourced when adding a package (after post-add) and
+when calling pkg refresh.
+
+=item pre-remove
+
+Sourced before a package is removed (pkg remove/pkg delete)
+
+=back
+
+=head1 COLLECTED PACKAGE FILES
+
+These files reside in F<$PKG_DIR/.collected> (subject to change).
+
+The directory is somewhat similar to F<~/bin> - it is automatically populated
+by pkg. However, this one does not contain symlinks.
+
+Currently, it only contains the directory F<man/>, which holds the "compiled"
+manual pages from the packages (extracted from F<bin/> and F<man/>).
+This way, yuo can put F<.../.collected/man> into you MANPATH to access manuals
+provided by packages.
+
+=head1 GIT
+
+B<pkg> uses git(1) as backend for storing and syncing package information.
+It is not recommended to use branches other than "master".
+While they should work if GIT_USE_ORIGIN is set to 1 (the default), they will
+most likely confuse pkg update.
+
+=head1 AUTHOR
+
+Daniel Friesel E<lt>derf@derf.homelinux.orgE<gt>
+
+=head1 SEE ALSO
+
+checklinks(1), pkg(1)