docs update in progress

git-svn-id: svn+slack://slack.fluxo.info/var/svn/simplepkg@381 04377dda-e619-0410-9926-eae83683ac58

1 files changed, 154 insertions, 67 deletions

diff --git a/trunk/doc/README.simplaret b/trunk/doc/README.simplaret
index ce7efbd..9ddab93 100644
--- a/trunk/doc/README.simplaret
+++ b/trunk/doc/README.simplaret
@@ -9,122 +9,209 @@ 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.
+by archictecture and version. It can also search for packages. It runs on top of pkgtool
+and is totally non-instrusive and can search, add, remove and upgrade packages.
 
 Documentation
 -------------
 
-The always updated english documentation is hosted at http://slack.sarava.org/node/17
+The always updated english documentation is hosted at http://slack.sarava.org/simplaret-en
 
 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.
+Simplaret comes with simplepkg, wich installation and configuration is detailed at
+http://slack.sarava.org/simplepkg. Simplaret uses /etc/simplepkg/simplepkg.conf for its definitions
+and /etc/simplepkg/repos.conf for repository information. The default configuration should work
+for almost everyone.
 
-Repository organization
------------------------
+Using simplaret
+---------------
 
-Simplaret local storage folder is defined through STORAGE parameter and is organized
-in this manner:
+Simplaret stores its data in system wide folders. Then, some funcionality will just be available
+if its run with root user capabilities. The first thing you need to do with simplaret is to fetch
+repository metadata, using
 
-  $STORAGE/arch/version/
+  simplaret --update
 
-Packages from contributed repositories (i.e, not from an official distro mirror) are
-stored at
+or simply 
 
-  $STORAGE/arch/version/repository-name/
+  simplaret update
 
-This means, for example, that slack 10.2 packages are located in
+as simplepkg supports both command line behaviour (--update or just update). After that, you can
+search for packages using commands like
 
-  $STORAGE/i386/10.2/
+  simplaret search ekiga
 
-And the slack.sarava.org's slamd64 packages can be stored in a place such as
+The result should be something like
 
-  $STORAGE/x86_64/10.2/slack.sarava.org/
+  REPOS repository sarava, arch: i386, version: 11.0: ekiga-2.0.5-i586-1rd.tgz
 
-In the repository definition file (/etc/simplepkg/repos.conf), the entries must match
-the following schema, something that remembers a swaret.conf:
+As we'll see afterwards, "REPOS" means the repository type, "sarava" is the repository name,
+"arch" is the package architecture (i386 in this case) and "version" is the repository version
+(11.0 in this case).
 
-  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/"
+To install this package, just type
 
-Repositories defined as ROOT are those wich
+  simplaret install ekiga
 
-  - Have packages from the official distro or
-  - Are organized by version according to the mirror guidelines
+By default, if simplaret finds in the repository a slack-required file for this package (i.e, the
+file ekiga.slack-required in the same folder of the binary package) then it will try to install
+all unmet dependencies. This default behaviour can be disabled through config file parameters.
 
-Repositories defined as REPOS are those containing packages from a specific version or
-non-oficial packages.
+If you just want to download the package, type
 
-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 %.
+  simplaret get ekiga
 
-Fetching the package list
--------------------------
+In the case of simplaret finds more than one package with the same name, it will get in the order
+that the "search" option shows them. The search precedence can also be defined by config file
+parameters. For instance, the command
 
-After configured, simplaret can fetch the package list with
+  simplaret search kernel-generic
 
-  simplaret --update
+can return something like
 
-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
+  ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.17.13-i486-1.tgz
+  ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.18-i486-1.tgz
 
-  ARCH=x86_64 VERSION=10.2 simplaret --update
+So the command
 
-Searching
----------
+  simplaret install kernel-generic
 
-To search for a package, use the following commands as examples:
+will attempt to install the package "kernel-generic-2.6.17.13-i486-1.tgz" and not the file
+"kernel-generic-2.6.18-i486-1.tgz". If you want to force simplaret to get and specific package,
+use its complete file name:
 
-  simplaret --search coreutils
+  simplaret install kernel-generic-2.6.18-i486-1.tgz
 
-for a Slack/390 package,
+If a package is already installed in the system, the --install option will try to upgrade it
+if the version or build number between the installed package and the one in the repository
+are different. So the command
 
-  ARCH=s390 simplaret --search x11
+  simplaret install simplepkg
 
-for slack 10.1 with contributed i686 packages,
+updates simplepkg in the case there's a new version. To remove a package, type
 
-  ARCH=i686 VERSION=10.1 simplaret --search icecast
+  simplaret remove nome-do-pacote
 
-Downloading
------------
+That's just an alias for the standard removepkg command.
 
-To download a package,
+Simplaret stores downloaded packages in a system folder that defaults to /var/simplaret.
+As you get more and more packages, simplaret will consume more space ir your disk. To
+erase your local repository folder, use the command
 
-  simplaret --get icecast
+  simplaret purge
 
-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.
+This will erase just the packages from the current arch and version. Details about how to
+erase the repository for different arch and version are in another session.
 
-Downloading patches
--------------------
+You can also force simplaret to erase just old packages. The following command erases just
+packages older than six weeks or more:
 
-From the PATCHES_DIR parameter is possible to specify a folder where patches are
-placed, sorted by arch and version.
+  simplaret purge -w 3
 
-Patches for slack 10.2 are always located at
+Downloading patches and upgrading the system
+--------------------------------------------
 
-  $PATCHES_DIR/i386/10.2/
+Simplaret hasn't just about package installing and removal, it has two more important
+features: patches retrieval and application. Assuming that the patches repository of
+your slackware flavour is correctly configured (what should work with almost everyone
+with the default configuration), you can fetch the available patches using the command
 
-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.
+  simplaret get-patches
 
-To grab all patches from an arch and version, use
+If you don't just donwload but also apply those patches, use
 
-  ARCH=architecture VERSION=version simplaret --get-patches
+  simplaret upgrade
 
-Purging the cache
------------------
+Working with more than one architecture and version
+---------------------------------------------------
+
+Until now we just looked what is the requirement for all package management system: package
+retrieval, installation, search, upgrade and dependency resolution. What makes simplaret
+different from another tools is the ability to deal with different architectures and versions
+and slackware installations.
+
+The features descibed in this section will just make sense after you read the next section, when
+we'll talk about multiple slackware installations and jails in the same computer.
+
+Suppose you're running Slackware (arch i386) bit wants to update the package list from Slamd64
+version 11.0 (arch x86_64). To do that, just type
+
+  ARCH=x86_64 VERSION=11.0 simplaret update
+
+This command grabs the Slamd64 package list without confliting in any way with the standard and
+already downloaded i386 Slackware package list. This doesn't happens because simplaret stores
+metadata from different archs and versions at different folders.
+
+Its optional to pass ARCH and VERSION environment variables to simplaret. If one or none of them
+was specified, simplaret uses the standar system value, obtained from the file /etc/slackware-version,
+or uses config parameters to do that.
+
+As an example, to search for a package in the arch powerpc (Slackintosh) version 11.0, just type
+
+  ARCH=powerpc VERSION=11.0 simplaret search package-name
+
+All command previously mentioned can work that way, except those that install or remove packages as
+its dangerous to mix packages from different archs and versions in the same system.
+
+Working with multiple installations
+-----------------------------------
+
+The previously section mentions a feature that just makes sense in systems where there's more than
+one slackware-like installation using different archs and versions.
+
+Say you have a x86_64 machine with three installed systems:
+
+  - Slamd64 11.0 at the root folder
+  - Slackware 11.0 at /mnt/slackware-1
+  - Slackware 10.2 at /mnt/slackware-2
+
+In the case of package install or patch retrieval and application, simplaret supports the environment
+variable ROOT to specify which folder simplaret should look for a system.
+
+Then, to install a package at /mnt/slackware-1, just type
+
+  ARCH=i386 VERSION=11.0 simplaret update
+  ROOT=/mnt/slackware-1 simplaret install package-name
+
+The first command just updates the package list and the second makes simplepkg install the package with
+using /mnt/slackware-1 arch and version. If you want to do the same at /mnt/slackware-2, use the analogous
+command
+
+  ARCH=i386 VERSION=10.2 simplaret update
+  ROOT=/mnt/slackware-2 simplaret install package-name
+
+There's also a feature to make patch retrieval and application with just one command, using the file
+/etc/simplepkg/jailist. This file is used by simplepkg's mkjail script to store ...
+
+Existe ainda uma facilidade para que a obtenção e aplicação de atualizações seja feita de forma única,
+através do arquivo /etc/simplepkg/jailist. Esse arquivo serve, além de outros propósitos descritos na
+documentação do simplepkg, para que o simplaret saiba de antemão quais são as instalações de sistema
+do tipo Slackware presentes numa máquina, além da instalação principal na raíz do sistema.
+
+Considerando que a máquina possua as três instalações citadas no início deste tópico, a atualização
+automática das mesmas pode ser feita quando o arquivo /etc/simplepkg/jailist contiver as seguintes
+linhas (sem espaços no início de cada uma):
+
+  /mnt/slackware-1
+  /mnt/slackware-2
+
+O sistema principal, contido na raíz do sistema, não precisa estar listado nesse arquivo. Se todas
+as suas instalações de sistema do tipo Slackware estiverem constando corretamente no /etc/simplepkg/jailist,
+o seguinte comando baixará as atualizações disponíveis para todas elas, incluindo o sistema contido na raíz:
+
+  simplaret get-patches
+
+Analogamente, o seguinte comando baixará e/ou aplicará todas as atualizações disponíveis em todas as
+instalações, incluindo o sistema contido na raíz:
+
+  simplaret upgrade
 
-Simplaret cache from an arch and version can be purged with a
+Desse modo, o gerenciamento de pacotes numa máquina que contenha mais de uma instalação do tipo Slackware
+fica unificada e consequentemente simplificada.
 
-  simplaret --purge
+[...]
 
 But why use that?
 -----------------