docs update in progress

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

1 files changed, 137 insertions, 15 deletions

diff --git a/trunk/doc/README b/trunk/doc/README
index 470b6ab..8a438bf 100644
--- a/trunk/doc/README
+++ b/trunk/doc/README
@@ -251,13 +251,42 @@ 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
+The opposite operation of jail-commit also is possible: suppose you edited some config files in your system but
+suddenly wants to go back and copy all config files from a template to your jail. To do that, just use the command
 
   jail-update /mnt/hda2 my-slackware
 
-[...]
+Storing templates inside a Subversion repository
+------------------------------------------------
+
+In order to increase once more the control and flexibility of template contents, simplepkg can also handle templates
+inside a subversion repository. To do that, edit first the config gile /etc/simplepkg/simplepkg.conf and set the
+parameter TEMPLATES_UNDER_SVN to "yes".
+
+Then, create a fresh subversion repository to keep your templates with a command like that:
+
+  svnadmin create /var/svn/simplepkg --fs-type fsfs
+
+Then, you just need to import your templates with
+
+  templatepkg -e file:///var/svn/simplepkg
+
+From now jail-commit will commit automatically any template changes to the svn repository. If, in the other hand,
+you wish to grab the changes from the svn repository to your local copy, use
+
+  templatepkg -s
+
+In case you want to import a template folder from an existing repository, use
+
+  templatepkg -i file:///var/svn/simplepkg
+
+where file:///var/svn/simplepkg is the repository path.
+
+Upgrading jails
+---------------
+
+Jail and installed system upgrading is done through simplaret and also supports /etc/simplepkg/jailist file.
+For more info on how it works, take a look at simplaret own documentation.
 
 Different archs and versions
 ----------------------------
@@ -280,27 +309,120 @@ 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.
 
-Auxiliar applications: rebuildpkg and createpkg
------------------------------------------------
+Creating a package from a template
+----------------------------------
+
+If, for any reason, you wish to build a package from an existing template, try the command
+
+  templatepkg -p template-name
+
+Although that should work smoothly, its not the recommended behaviour, as simplepkg was designed
+to deal easily with templates and repositories.
+
+Building packages
+-----------------
+
+Until now, we just showed simplepkg applications used to manage installations and packages.
+But simplepkg can also create packages using createpkg script: it downloads, builds and
+packages software that has an available script from a SlackBuild in a repository, working
+like a slackware ports system.
+
+Createpkg works with any SlackBuild repository but works better and is well integrated if
+they are compliant with the standards from
+
+  http://slack.sarava.org/wiki/Main/SlackBuilds
+
+Specifically, createpkg was built to use slackbuilds from http://slack.sarava.org/slackbuilds
+through a subversion repository.
+
+To fetch all scripts from slack.sarava.org, type
+
+  createpkg --sync
+
+Then, you can list all available script using
+
+  createpkg --list
 
-Simplepkg comes with an additional helper tool that recover installed packages which the original
-.tgz file was lost. The command rebuildpkg rebuilds a package from their entry in /var/log/packages.
-As an example,
+To search for a script, use something like
+
+  createpkg --search latex2html
+
+This searches for a SlackBuild for the program "latex2html". If you want to build that package,
+just type
+
+  createpkg latex2html
+
+The resulting package should be available at /tmp or at the folder specified by the environment
+variable $REPOS. To create and install the package, type
+
+  createpkg --install latex2html
+
+If the package has dependencies listed in a slack-required file that aren't installed in the
+system, then createpkg will try to process then before the desired package's SlackBuild: if
+the dependencies aren't available in the SlackBuild tree, then createpkg will call simplaret
+and try to install the package from a binary repository. If you want to avoid createpkg's
+dependency checking, just use it with the flag --no-deps.
+
+For more information about createpkg, type
+
+  createpkg --help
+
+or take a look at http://slack.sarava.org/wiki/Main/SlackBuilds.
+
+Auxiliar applications
+---------------------
+
+Simplepkg comes also with the following tools:
+
+   - lspkg: show installed packages and its contents
+   - rebuildpkg: rebuild a package based on its /var/log/packages entry
+   - repos: creates and manages binary repositories
+   - mkbuild: app to build slackware build scripts
+
+The command lspkg is used to show installed packages. Also, Simplepkg comes with an additional helper
+tool that recover installed packages which the original .tgz file was lost. The command rebuildpkg
+rebuilds a package from their entry in /var/log/packages. As an example,
 
   rebuildpkg coreutils
 
 rebuilds the coreutils package using the files, scripts and metainformations stored in
 /var/log/packages/ and /var/log/scripts/.
 
-If you want to build you own packages using the scripts available from http://slack.sarava.org/slackbuilds,
-use the createpkg script:
+For their time, scripts repos and mkbuild are used, respectivelly, to create and manage binary repositories
+and to create SlackBuild scripts.
+
+Parâmetros de configuração
+--------------------------
+
+Simplepkg's config file is /etc/simplepkg/simplepkg.conf and it keeps parameters used by all scripts.
+In this section, we won't cover any parameter that's just used by simplaret, whose settings are covered
+in its own documentation.
 
-  createpkg package-name
+  - JAIL_ROOT: Where jails are placed by mkjail. Default: "/vservers".
 
-Source
-------
+  - ADD_TO_JAIL_LIST: Wheter mkjial should add new jails to /etc/simplepkg/jailist. Default is "1" (enabled).
 
-Source code for simplepkg and its package builder can be fetched via subversion:
+  - TEMPLATES_UNDER_SVN: Set to yes if your templates will be placed in a subversion repository. Default
+    is "no" (disabled).
+
+  - TEMPLATE_FOLDER: Where your templates will be located. Default is "/etc/simplepkg/templates" and
+    dont change it except you know what you're doing.
+
+  - TEMPLATE_STORAGE_STYLE: This variable controls in which folder / subfolder your templates will
+    be stored. Default value is "own-folder" and you'll just need to change that if you're storing
+    your templates using an old simplepkg format and wants to keep compatibilty.
+
+Its important to note that all boolean parameters in the config file can be set either to "1" or "yes"
+to enable and "0" or "no" to disable.
+
+More information
+----------------
+
+Simplepkg was written by Silvio Rhatto (rhatto at riseup.net) and is released under GPL license. The code
+can be obtained from the subversion repository:
 
   svn checkout svn://slack.sarava.org/simplepkg
 
+Simplepkg's wiki is http://slack.sarava.org/wiki/Main/SimplePKG and its mailing list address is
+http://listas.sarava.org/wws/info/slack.
+