1 files changed, 143 insertions, 0 deletions
diff --git a/doc/README.simplaret b/doc/README.simplaret
new file mode 100644
index 0000000..ce7efbd
--- /dev/null
+++ b/doc/README.simplaret
@@ -0,0 +1,143 @@
+simplaret: simplepkg retrieval tool
+-----------------------------------
+
+Simplaret is a simplepkg tool used to download packages from local and remote repositories.
+With simplaret, one can grab packages for all archictectures and versions of slackware-like
+distributions that follows the mirror guidelines, allowing an easy management all
+jails and slackware installations in a machine, no matter wich arquiteture or version
+each one has.
+
+It was inspired in swaret behavior but don't tries to get its complexity level, but
+execute package download in a different way, where the local repository is organized
+by archictecture and version. It can also search for packages.
+
+Documentation
+-------------
+
+The always updated english documentation is hosted at http://slack.sarava.org/node/17
+
+Downloading and installing
+--------------------------
+
+Simplaret comes with simplepkg, wich installation and configuration is detailed
+at http://slack.sarava.org/node/15. Simplaret uses /etc/simplepkg/simplepkg.conf for
+its definitions and /etc/simplepkg/repos.conf for repository information.
+
+Repository organization
+-----------------------
+
+Simplaret local storage folder is defined through STORAGE parameter and is organized
+in this manner:
+
+  $STORAGE/arch/version/
+
+Packages from contributed repositories (i.e, not from an official distro mirror) are
+stored at
+
+  $STORAGE/arch/version/repository-name/
+
+This means, for example, that slack 10.2 packages are located in
+
+  $STORAGE/i386/10.2/
+
+And the slack.sarava.org's slamd64 packages can be stored in a place such as
+
+  $STORAGE/x86_64/10.2/slack.sarava.org/
+
+In the repository definition file (/etc/simplepkg/repos.conf), the entries must match
+the following schema, something that remembers a swaret.conf:
+
+  ROOT-i386="http://slack.sarava.org/slackware/"
+  ROOT-x86_64="http://ftp.heanet.ie/pub/slamd64/"
+  REPOS-i386-10.2="slack.sarava.org%http://slack.sarava.org/packages/slackware/slackware-10.2/"
+  REPOS-x86_64-10.2="slack.sarava.org%http://slack.sarava.org/packages/slamd64/slamd64-10.2/"
+
+Repositories defined as ROOT are those wich
+
+  - Have packages from the official distro or
+  - Are organized by version according to the mirror guidelines
+
+Repositories defined as REPOS are those containing packages from a specific version or
+non-oficial packages.
+
+When simplaret searches for a package, precedence is given first for ROOT definitions and then
+for REPOS ones. REPOS definitions should also include a identification name, delimited from
+the repository URL by the special sign %.
+
+Fetching the package list
+-------------------------
+
+After configured, simplaret can fetch the package list with
+
+  simplaret --update
+
+This updates the package list from arch defined in DEFAULT_ARCH and version from DEFAULT_VERSION.
+To fetch package listings for x86_64 (slamd64) and version 10.2, use
+
+  ARCH=x86_64 VERSION=10.2 simplaret --update
+
+Searching
+---------
+
+To search for a package, use the following commands as examples:
+
+  simplaret --search coreutils
+
+for a Slack/390 package,
+
+  ARCH=s390 simplaret --search x11
+
+for slack 10.1 with contributed i686 packages,
+
+  ARCH=i686 VERSION=10.1 simplaret --search icecast
+
+Downloading
+-----------
+
+To download a package,
+
+  simplaret --get icecast
+
+Simplaret downloads the first package found with the precedence explaned above.
+Future versions should contain an option to explicit get a package from a
+specific repository.
+
+Downloading patches
+-------------------
+
+From the PATCHES_DIR parameter is possible to specify a folder where patches are
+placed, sorted by arch and version.
+
+Patches for slack 10.2 are always located at
+
+  $PATCHES_DIR/i386/10.2/
+
+In reality, patches are downloaded with a "simplaret --get" and stored in the $STORAGE
+subfolder for its arch and version and a symlink is created in $PATCHES_DIR/$ARCH/$VERSION.
+
+To grab all patches from an arch and version, use
+
+  ARCH=architecture VERSION=version simplaret --get-patches
+
+Purging the cache
+-----------------
+
+Simplaret cache from an arch and version can be purged with a
+
+  simplaret --purge
+
+But why use that?
+-----------------
+
+You may ask why someone wishes to use such tool.
+
+Simplaret was written with a *x86 environment in mind, where lots of jails with different archs
+and versions are installed. Suppose a x86_64 with the following chroots installed:
+
+  - slamd64 10.2
+  - slackware 10.2
+  - slackware 10.1 with additional i686 packages
+  - uSlack (i386 uClibc) 
+
+Keep all this stuff update manually is really a headache. Simplaret just tries to make it trivial.
+