docs update in progress

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

3 files changed, 192 insertions, 143 deletions

diff --git a/trunk/doc/README b/trunk/doc/README
index 50b0e9d..470b6ab 100644
--- a/trunk/doc/README
+++ b/trunk/doc/README
@@ -1,21 +1,19 @@
-Simplepkg: installation manager and metapackage system
-------------------------------------------------------
+Simplepkg: installation manager and packaging system
+----------------------------------------------------
 
 Author: Silvio Rhatto <rhatto at riseup.net>
 Licence: GPL
 
-Simplepkg is a non-intrusive package management system running on top of pkgtool.
-It uses templates -- lists of installed packages, scripts and configuration files
--- allowing the creation of installation profiles that can be used do install a
-complete and configured slackware system in another partition or to create chroot
-environments. The same templating scheme extends slackware packaging system, adding
-metapackages: a list of packages installed or removed with a single command.
+Simplepkg is a non-intrusive management system running on top of pkgtool made of a
+set of scripts which helps the sysadmin and developing cycles of an slackware system.
+It can be used to create packages and repositories as long as the operational system
+installation and config file change tracking.
 
 Documentation
 -------------
 
-  English documentation: README | http://slack.sarava.org/node/15
-  Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/node/12
+  English documentation: README | http://slack.sarava.org/simplepkg-en
+  Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/simplepkg
 
 Description
 -----------
@@ -37,6 +35,13 @@ management, allowing you to keep templates of each machine and install a custom
 system with just one or a few commands. Creating and upgrading chroot and vservers is easy
 with simplepkg.
 
+Package and installation management is not everything simplepkg can do. It can also be used
+to create vservers, create packages and store system configuration files in a subversion
+repository.
+
+Simplepkg works with any (official or not) slackware port that follows the minimum system
+guidelines.
+
 Architecture
 ------------
 
@@ -44,27 +49,15 @@ Simplepkg is a set of scripts wrote in the KISS philosophy. Its a pretty simple
 by the following commands:
 
    - mkjail: build a slackware jail/installation in a folder
-   - metapkg: install or remove a metapackage
    - templatepkg: create or update a package list of an installation template
    - lspkg: show installed packages and its contents
-   - jail-upgrade: upgrade all or some of the jails/installations 
-   - jail-update: update all configuration files of a template
+   - jail-commit: update all configuration files of a template
+   - jail-update: jail-commit counterpart
    - rebuildpkg: rebuild a package based on its /var/log/packages entry
    - simplaret: package retrieval tool
    - createpkg: donwload, compile and package creationg script based on http://slack.sarava.org/slackbuilds
-
-Simplepkg configs are placed at /etc/simplepkg. Templates are .template files containing an one-by-line
-package list. A template can be something like this:
-
-  aaa_base
-  aaa_elflibs
-  apache
-  bash
-  bin
-  coreutils
-  findutils
-
-Slackware's tagfile format can be used too as a template.
+   - repos: creates and manages binary repositories
+   - mkbuild: app to build slackware build scripts
 
 Installation
 ------------
@@ -74,134 +67,197 @@ Install it with the usual way:
 
   installpkg simplepkg-VERSION-noarch-BUILD.tgz
 
-If you have a working swaret on your system, add this line on you swaret.conf:
+Simplepkg usage
+---------------
 
-  REPOS_ROOT=SlackMidiataticaNoarch%http://slack.sarava.org/packages/noarch
+The three main simplepkg uses are:
 
-and then issue those commands:
+  - Package managemen
+  - Jail/installation creation and management
+  - Package creation
 
-  swaret --update
-  swaret --install simplepkg
+Package management is made with simplaret app, whose behaviour is detailed in its own document.
+The following sections will only show how simplepkg can be used to manage jails and template
+and create packages.
 
-Configuration
--------------
+Creating templates
+------------------
+
+Initially, simplepkg was built to help slackware install automation. To do that, it uses installation
+templates -- lists of installed packages, post-installation scripts and config files -- allowing the
+creation of installation profiles that can be used for system replication in other partition or even
+custom chroot building.
+
+Template creation is done with "templatepkg" script. To create a template called "my-slackware" containig
+the installed package list of your slackware installation, just type
+
+  templatepkg -c my-slackware
+
+The -c (or --create) flag tells templatepkg to create the /etc/simplepkg/templates/my-slackware folder
+with the following components:
 
-As an example, we'll create a jail based on the packages installed in your slackware
-system. Edit the config file /etc/simplepkg/simplepkg.conf:
-
-  # /etc/simplepkg/simplepkg.conf
-  JAIL_ROOT="/vservers" # where jails are placed
-  SIMPLARET="simplaret" # package grabber program (can be swaret if you have it installed)
-  SIMPLARET_CLEAN="1" # clean package cache before installation
-  SIMPLARET_DELETE_DOWN="1" # clean package cache after the installation
-  SIMPLARET_UPDATE="0" # issue an simplaret --update before install the jail
-  SIMPLARET_PURGE_WEEKS="N" # delete packages older than N weeks from the cache
-  PATCHES_DIR="/storage/package/patches" # where patches are placed
-  DEFAULT_ARCH="i386"
-  DEFAULT=VERSION="10.2"
-  STORAGE="/storage/packages" # where simplepkg store packages
-  PASSIVE_FTP="1"
-
-You should also put in /etc/simplepkg/repos.conf all package repositories you use, like this:
-
-  ROOT-i386="http://slack.sarava.org/packages/slackware"
-  REPOS-i386="slack-sarava%http://slack.sarava.org/packages/slackware/slackware-10.2/"
-  ROOT-x86_64-10.2="http://darkstar.ist.utl.pt/pub/slamd64/"
-  REPOS-x86_64-10.2="slamd-sarava%http://slack.sarava.org/packages/slamd64/slamd64-10.2/"
-
-Instead of simplaret you can use swaret to fetch packages and them your swaret.conf must
-be configured to use the same place as STORAGE to the package cache. In this case you cant
-keep installations and jails with multiple arquitetures and for that reason the use of
-simplaret is recommended.
+  - /etc/simplepkg/templates/my-slackware/my-slackware.d: template config files
+  - /etc/simplepkg/templates/my-slackware/my-slackware.s: post-installation scripts
+  - /etc/simplepkg/templates/my-slackware/my-slackware.perms: metadata for config files
+  - /etc/simplepkg/templates/my-slackware/my-slackware.template: installaed package list
+
+This four components are enough to store all slackware installation characteristics: the package list
+controls with applications are installed, the config file folder can contain all desired configurations
+for any installed application and the post-installation scripts take care of all procedures that should
+be executed exactly after the system installation. The my-slackware.perms file contains metadata for the
+saved config files, i.e, permission and ownership.
+
+If you want to build a template from a installation placed in another folder or partition thats not your
+current root dir, just type something like
+
+  templatepkg -c my-slackware /mnt/slackware
+
+where /mnt/slackware is the place where this alternative system is installed. After created, the template
+will contain just the installed package list or that folder. As the folder /var/log/packages of your
+installation doesn't keep information about the package installation order, its recommended that you
+manually edit the template's package list. To do that, just type
+
+  templatepkg -e my-slackware
+
+To add configuration files inside the template, type something like
+
+  templatepkg -a my-slackware /etc/hosts
+
+This should add /etc/hosts file to "my-slackware" template. Beyond just automatically copy the file
+when you install a new system using this template, simplepkg can also take care of every change that
+/etc/hosts can suffer on your system, such as file content or permission and ownership change. If you're
+also storing your templates in a subversion repository, you'll be able to track all changes it ever had.
+
+WARNING: avoid the storage in a template of config files that contains important security information
+such as passwords or secret keys. The prefered place to put such stuff is a secured backup.
 
 Creating jails and replicating installations
 --------------------------------------------
 
-  templatepkg my-slackare
-  mkjail jail my-slackware
+As long as your template was created and populated with the package list, configuration files and
+post-installation scripts (what will be treated in another section), your can replicate your slackware
+installation as simpler than typing the following command:
 
-The previous commands creates a template called my-slackware from based on your installed
-softwares listed in /var/log/packages and then creates a completely new slackware
-tree with all those packages in the folder /vservers/jail (depending on the value of JAIL_ROOT from
-your simplepkg.conf).
+  mkjail jail my-slackware
 
-If you want that some config files get copied or some scripts executed after install this jail,
-place in the folder /etc/simplepkg/my-slackware.d all your config files (preserving the file
-system hierarchy, i.e, /etc/simplepkg/my-slackware/etc/apache/httpd.conf) and the scripts at
-/etc/simplepkg/my-slackware.s/. The template vserver, which comes in the simplepkg package, has
-an example script to use with mkjail.
+This creates a fresh slackware tree at /vservers/jail with all packages listed in the template "my-slackware"
+and all saved config files. The package installation is made by simplaret app, that should be properly configured.
+The standard simplaret configuration should work for most situations.
 
-You can specify an alternative destination for your jail with a command like
+If you want to install your jail in a place other than /vservers (this standard location can be changed through
+simpleokg config file), say /mnt/hda2, just use something like that:
 
   ROOT=/mnt mkjail hda2 my-slackware
 
-This does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages
+The above command does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages
 you have on your system, replacing the need of the slackware installer!
 
-In case no template specified, mkjail uses the one called /etc/simplepkg/default.template.
+In case no template specified, mkjail uses the one stored /etc/simplepkg/default, if exists. Simplepkg already
+came if some pre-built templates at /etc/simplepkg/defaults/templates.
 
-If you keep your jails in JAIL_ROOT with the same name as the template you used to create it, its
-possible to use the command jail-update to copy all modifications made in the files which their
-counterparts are placed at /etc/simplepkg/jail-name.d. Then you can copy all configuration files
-you edited to the template folder and leave a crontab entry to everyday seek for changes and update
-the template. When you issue the command
+Post-installation scripts
+-------------------------
 
-  jail-update
+Optionally, its possible to keep post-installation scripts inside a template. Such scripts are executed by mkjail
+exactly after a jail is installed and the template config files copied. To create or edit a post-installation
+script, just type
 
-all jails listed in /etc/simplepkg/jaillist are updated. This command also updates the package list
-of the template.
+  templatepkg -b my-slackware script-name.sh
 
-To add or remove packages from a template, you can just edit by hand the template file or use the
-command templatepkg with the -a (append) flag, which adds just the new installed packages in the
-template file. 
+This adds the script-name.sh at "my-slackware" template. Mkjail passes two command line arguments to a post-install
+script: the upward folder and the jail's name ("/mnt" and "hda2" from our previous example). Then, an example script
+is something like that:
 
-If you want to create a template from a jail, use
+  #!/bin/bash
+  chroot $1/$2/ sbin/ldconfig
 
-  templatepkg jail /vservers/jail
+Listing template contents
+-------------------------
 
-Metapackages
-------------
+To list available templates or the template content, use commands such as
 
-Another use for the templates is the creation of metapackegs: new users have lots of difficulties
-to track dependencies when installing a software. Using a template containing the name of all
-packages needed by some program allow users to easily install it through the command
+  templatepkg -l
+  templatepkg -l my-slackware
 
-  metapkg --install program-name
+Removing files from a template
+------------------------------
 
-This seems like swaret or slapt-get, with the only difference in the way metapkg deals with
-dependence resolution. Slapt-get support the slack-required file, wich comes or not with the
-package. Swaret has its own tool for dependence matching.
+As you did to add files, you can easily remove then from a template, using a comand such as
 
-Simplepkg doesn't wish to substitute those two dependence checking modes, but offer an alternate
-way to distribute packages where dependences are resolved without an specific tool or a change
-in the package itself.
+  templatepkg -d my-slackware /etc/hosts
 
-A metapackage, i.e, all installed packages from a template, can be removed with 
+This removes the file /etc/hosts from "my-slackware" template.
 
-  metapkg --remove program-name
+Removing a template
+-------------------
 
-Upgrading jails
----------------
+To remove a template, just type
+
+  templatepkg -r my-slackware
+
+Updating a template
+-------------------
+
+Now that we just talked about creating templates and jails, its time to cover another application, this time
+used to keep a template always updated. Jail-commit is a script that copies all config file changes (content,
+permissions and ownership) from a installation to a simplepkg template.
+
+For instance, if one wants to copy all changes from /mnt/hda2 jail into "my-slackware" template, he or she
+just needs to type the following command:
+
+  jail-commit /mnt/hda2 my-slackware
+
+Not just the package list from "my-slackware" template is updated according the installed packages from
+/mnt/hda2/var/log/packages: all config files from "my-slackware" template are compared it the ones from
+the jail and in case of any difference they're copied from the jail back to the template. Permissions
+and file ownership commit into the template works at the same way.
+
+Jail-commit allows that a template to being kept always updated and mirroring the actual configuration
+of an installed system. But if you want just to commit into the template just the installed package
+list, simply type
+
+  templatepkg -u my-template
 
-Both the main installation (your root system) and your jails are upgraded with the command
-jail-upgrade: just adjust simplepkg.conf's PATCHES_DIR to where you store slackware patches
-(that can be rsync'ed everyday) and do a
+To make life even easier, there's also a feature of keeping a list of all installed slackware system in
+the box in the file /etc/simplepkg/jailist. This file, despite its use by simplaret (what is described
+in its own text), allow jail-commit to run with no arguments.
 
-  jail-upgrade
+Suppose you have three slackware installations: the root system and two more:
 
-This will upgrade your main system and all jails living in JAIL_ROOT. To specify another
-folder, use
+  - /mnt/slackware-1 using "slackware-1" template
+  - /mnt/slackware-2 using "slackware-2" template 
 
-  ROOT=/otherroot jail-upgrade
+If your /etc/simplepkg/jailist has the following lines:
 
-If you want to upgrade just one specific jail,
+  /mnt/slackware-1
+  /mnt/slackware-2
 
-  jail-upgrade jail-name
+then the command
 
-To use a patches folder other than PATCHES_DIR, e.g when you have jails with different
-slackware versions, use
- 
-  PATCHES=/alternative/patches/folder jail-upgrade jail-name
+  jail-commit
+
+will update both "slackware-1" and "slackware-2" templates according, respectivelly, the contents of
+/mnt/slackware-1 and /mnt/slackware-2. If you also have a template called "main", then jail-commit
+will sync the contents of your root system with that template.
+
+You can even add the following line at root's crontab
+
+  20 4 * * * jail-commit
+
+so all your templates get updated everyday. If your system is configured to send emails, then crontab's
+jail-commit output you give a summary of yesterday changes your system suffered, both config file changes
+and package additions and removals.
+
+Restoring changes in a jail
+---------------------------
+
+A operação contrária ao que o jail-commit faz também é possível: suponha que você mexeu na configuração do sistema
+mas se arrependeu das alterações e deseja voltar a configuração para o modo como ela se encontra no seu template,
+basta usar o comando
+
+  jail-update /mnt/hda2 my-slackware
+
+[...]
 
 Different archs and versions
 ----------------------------
@@ -224,14 +280,6 @@ Note that the templates are arch and version independent, as they just contain p
 configuration files and scripts. For this reason, the commands templatepkg, metapkg, lspkg and
 jail-update can be used normaly.
 
-To upgrade jails with othes archs and versions, jail-upgrade checks this information through
-/etc/slackware-version for each jail and applies the correspondent patches grabed from
-simplaret (see the proper documentation).
-
-By this way, doesn't matter which versions and archs each of your jails has, jail-upgrade remains
-the same since your patches are sorted by arch an version, as explained in simplaret documentation
-found at http://slack.sarava.org/node/17.
-
 Auxiliar applications: rebuildpkg and createpkg
 -----------------------------------------------
 
diff --git a/trunk/doc/README.pt_BR b/trunk/doc/README.pt_BR
index 4f3b928..138125e 100644
--- a/trunk/doc/README.pt_BR
+++ b/trunk/doc/README.pt_BR
@@ -147,7 +147,7 @@ utilizando o comando
 
   mkjail jaula meu-slackware
 
-Isso cria uma nova árvore do slackware em /vserver/jaula contendo todos os pacotes e arquivos de configuração
+Isso cria uma nova árvore do slackware em /vservers/jaula contendo todos os pacotes e arquivos de configuração
 do template "meu-slackware". A instalação dos pacotes será feita pelo aplicativo simplaret, que deve estar
 configurado corretamente e cuja configuração padrão deve funcionar para a maioria dos casos.
 
@@ -160,7 +160,7 @@ O comando acima faz exatamente o que você está pensando: replica sua instalação
 dispensando totalmente o programa de instalação do slackware!
 
 Caso nenhum template for especificado, o mkjail utiliza o template /etc/simplepkg/default. O simplepkg já vem
-com alguns templates padrões, presentes em /etc/simplepkg/defaults/template.
+com alguns templates padrões, presentes em /etc/simplepkg/defaults/templates.
 
 Scripts de pós-instalação
 -------------------------
@@ -285,6 +285,12 @@ para sua cópia local, use o comando
 
   templatepkg -s
 
+Caso você queira importar uma pasta de templates de um repositório já existente, use
+
+  templatepkg -i file:///var/svn/simplepkg
+
+onde file:///var/svn/simplepkg é o camninho do repositório.
+
 Atualização de jaulas
 ---------------------
 
@@ -310,16 +316,7 @@ slack 10.2 numa partição, experimente
   ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 meu-slackware
 
 Note que os templates independem de arquitetura e versão, já que eles só contém nomes de pacotes,
-arquivos de configuração e scripts. Por isso, o templatepkg, o metapkg, o lspkg e o jail-update
-funcionam normalmente.
-
-Para atualizar suas jaulas, o jail-upgrade checa antes qual a versão e arquitetura de cada uma
-de suas jaulas através do /etc/slackware-version correspondente e a partir disso aplica os patches
-da arquitetura e versão da mesma, usando para isso o simplaret (veja a documentação própria).
-
-Desse modo, mesmo que você tenha jaulas de versões e arquiteturas diversas, usar o comando "jail-upgrade"
-faz a atualização sem problemas, desde que seus patches estejam organizados por arquitetura e versão,
-conforme é detalhado na documentação do simplaret, em http://slack.sarava.org/node/16.
+arquivos de configuração e scripts.
 
 Criando um pacote de um template
 --------------------------------
diff --git a/trunk/doc/simplepkg.tex b/trunk/doc/simplepkg.tex
index 67e8086..216d0d6 100644
--- a/trunk/doc/simplepkg.tex
+++ b/trunk/doc/simplepkg.tex
@@ -119,7 +119,7 @@ Uma vez que um template foi criado com uma lista de pacotes e opcionalmente com
 mkjail jaula meu-slackware
 \end{verbatim}
 
-Isso cria uma nova árvore do slackware em /vserver/jaula contendo todos os pacotes e arquivos de configuração do template "meu-slackware". A instalação dos pacotes será feita pelo aplicativo simplaret, que deve estar configurado corretamente e cuja configuração padrão deve funcionar para a maioria dos casos.
+Isso cria uma nova árvore do slackware em /vservers/jaula contendo todos os pacotes e arquivos de configuração do template "meu-slackware". A instalação dos pacotes será feita pelo aplicativo simplaret, que deve estar configurado corretamente e cuja configuração padrão deve funcionar para a maioria dos casos.
 
 Se você quiser instalar essa jaula em outro local que não seja a pasta /vservers (esse local padrão pode ser mudado pelo arquivo de configuração do \emph{simplepkg}), basta usar um comando do tipo
 
@@ -129,7 +129,7 @@ ROOT=/mnt mkjail hda2 meu-slackware
 
 O comando acima faz exatamente o que você está pensando: replica sua instalação slackware em /mnt/hda2, dispensando totalmente o programa de instalação do slackware!
 
-Caso nenhum template for especificado, o mkjail utiliza o template /etc/simplepkg/default. O \emph{simplepkg} já vem com alguns templates padrões, presentes em /etc/simplepkg/defaults/template.
+Caso nenhum template for especificado, o mkjail utiliza o template /etc/simplepkg/default. O \emph{simplepkg} já vem com alguns templates padrões, presentes em /etc/simplepkg/defaults/templates.
 
 \section{Scripts de pós-instalação}
 
@@ -255,6 +255,14 @@ A partir daí, o comando jail-commit enviará automaticamente todas as alterações
 templatepkg -s
 \end{verbatim}
 
+Caso você queira importar uma pasta de templates de um repositório já existente, use
+
+\begin{verbatim}
+templatepkg -i file:///var/svn/simplepkg
+\end{verbatim}
+
+onde file:///var/svn/simplepkg é o camninho do repositório.
+
 \section{Atualização de jaulas}
 
 A atualização de jaulas e sistemas instalados é feita através do simplaret e também utiliza o arquivo /etc/simplepkg/jailist. Para mais informações a respeito, consulte a documentação do simplaret para mais detalhes.
@@ -275,11 +283,7 @@ Arquiteturas diferentes também podem ser usadas. Se você está num sistema x86\_6
 ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 meu-slackware
 \end{verbatim}
 
-Note que os templates independem de arquitetura e versão, já que eles só contém nomes de pacotes, arquivos de configuração e scripts. Por isso, o templatepkg, o metapkg, o lspkg e o jail-update funcionam normalmente.
-
-Para atualizar suas jaulas, o jail-upgrade checa antes qual a versão e arquitetura de cada uma de suas jaulas através do /etc/slackware-version correspondente e a partir disso aplica os patches da arquitetura e versão da mesma, usando para isso o simplaret (veja a documentação própria).
-
-Desse modo, mesmo que você tenha jaulas de versões e arquiteturas diversas, usar o comando "jail-upgrade" faz a atualização sem problemas, desde que seus patches estejam organizados por arquitetura e versão, conforme é detalhado na documentação do simplaret, em http://slack.sarava.org/node/16.
+Note que os templates independem de arquitetura e versão, já que eles só contém nomes de pacotes, arquivos de configuração e scripts.
 
 \section{Criando um pacote de um template}