docs update in progress

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

2 files changed, 109 insertions, 19 deletions

diff --git a/trunk/doc/CHANGELOG b/trunk/doc/CHANGELOG
index 67900d1..1a98742 100644
--- a/trunk/doc/CHANGELOG
+++ b/trunk/doc/CHANGELOG
@@ -1,6 +1,11 @@
 simplepkg changelog
 ===================
 
+0.5pre23
+========
+
+  - updated documentation
+
 0.5pre22
 ========
 
diff --git a/trunk/doc/README.simplaret b/trunk/doc/README.simplaret
index 9ddab93..c4399bd 100644
--- a/trunk/doc/README.simplaret
+++ b/trunk/doc/README.simplaret
@@ -183,33 +183,118 @@ command
   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 ...
+/etc/simplepkg/jailist. This file is used by simplepkg's mkjail script to store with jails you have
+on your system but is also used by simplaret to upgrade all jails with just one command.
 
-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):
+Considering that your box has the three previously mentioned slackware installation. Then, to add
+/mnt/slackware-1 and /mnt/slackware-2 in the automatic upgrade list, add the following lines in your
+/etc/simplepkg/jailist (without spaces):
 
   /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:
+The root system doesn't need to be added in this file. Then, you can get the patches for all your three
+systems with the command
 
   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:
+To get the patches and/or apply them in all jails (including the root system), use
 
   simplaret upgrade
 
-Desse modo, o gerenciamento de pacotes numa máquina que contenha mais de uma instalação do tipo Slackware
-fica unificada e consequentemente simplificada.
+This feature makes easier to keep all your installations always upgraded.
+
+The repos.conf file
+-------------------
+
+Now that we just talked about all simplaret features, its time to take a tour at its configuration
+files. The first one we'll say about is the repository definition file, /etc/simplepkg/repos.conf.
+
+If you don't mind to make an advanced simplaret usage, then probably you can just leave this section
+as the default config should work for almost all standard situations and you'll just need to edit
+repos.conf to change repository priorities.
+
+The repos.conf file contains one repository definition per line using the following syntax:
+
+  TYPE[-ARCH][-VERSION]="name%URL"
+
+The content in brackets are optional depending on the repository type as we'll see later in this
+section. The repository types supported by simplaret are:
+
+  - PATCHES: definição para repositórios que contenham patches (pacotes de atualização) e cuja lista
+    de arquivos é FILE_LIST e não FILELIST.TXT; exemplo:
+
+      PATCHES-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/patches/"
+
+    No caso da definição acima, temos um repositório de patches para a arquitetura i386 (distribuição
+    Slackware), versão 11.0 e o nome dado ao repositório é "sarava".
+
+    Possuir uma definição do tipo PATCHES é opcional para ter acesso às atualizações: a definição
+    de repositório ROOT, que veremos em seguida, já lida com patches: o tipo de repositório PATCHES
+    serve apenas se você quiser utilizar algum repositório não-oficial como fonte de patches
+    prioritária, já que repositório PATCHES são pesquisados pelo simplaret antes de qualquer outro.
+
+    Em resumo, se você não tiver um bom motivo para usar esse tipo de repositório, evite-o.
+
+  - ROOT: são tipos de repositórios cujo conteúdo está dividido por versão. O exemplo tradicional
+    deste caso é o próprio repositório oficial das distribuições:
+
+      ROOT-i386="tds%http://slackware.mirrors.tds.net/pub/slackware/"
+
+    Repositórios ROOT necessitam apenas de uma definição de arquitetura, um nome e uma URL. No caso
+    acima, temos a definição de repositório ROOT de nome "tds", ou seja, não há definição de versão,
+    já que o simplaret considerará que a versão desejada está numa subpasta dessa URL. Ou seja,
+    definições ROOT implicam que as pastas contendo pacotes de cada versão estejam bem separadas,
+    ou seja, pastas como http://slackware.mirrors.tds.net/pub/slackware/slackware-10.2/ e
+    http://slackware.mirrors.tds.net/pub/slackware/slackware-11.0/.
+
+  - REPOS: este tipo de repositório é orientado a arquitetura e versão, como por exemplo
+
+      REPOS-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/"
+
+    No caso acima, um repositório de nome "sarava" é definido para a arquitetura i386 e versão
+    11.0 com a URL http://slack.sarava.org/packages/slackware/slackware-11.0/. Esse tipo de definição
+    é recomendado para repositórios não-oficiais.
+
+  - NOARCH: o último tipo de definição é usado para repositórios cujos pacotes são independentes
+    de arquitetura e versão da distribuição. Como exemplo temos um repositório do Projeto Slack:
+
+      NOARCH="sarava%http://slack.sarava.org/packages/noarch"
+
+Em qualquer tipo de repositório, a URL pode ser do tipo http://, ftp:// ou file:// (para repositórios
+locais).
+
+Como podem haver mais de uma definição de repositório para cada tipo, versão e/ou arquitetura,
+as mesmas são diferenciadas de acordo com o nome. Definições de repositório podem ter nomes idênticos,
+desde que se refiram a tipo de repositório e/ou arquitetura e versão diferentes.
+
+Existe ainda uma prioridade dentre tipos de repositório e ordens de precedência. Numa pesquisa,
+repositórios são pesquisados de acordo com a seguinte ordem:
+
+  - PATCHES tem prioridade mais alta: caso um pacote de uma dada arquitetura e versão não seja
+    encontrado no primeiro repositório PATCHES do repos.conf, o próximo repositório definido na
+    ordem em que ele aparece no arquivo é pesquisado, e assim por diante.
+
+  - Em seguida, pacotes são procurados nas definições ROOT da arquitetura em questão, na ordem
+    em que aparecem no repos.conf.
+
+  - Depois, são os pacotes de repositórios REPOS daquela arquitetura e versão são pesquisados,
+    na ordem em que aparecem no repos.conf.
+
+  - Por fim, repositórios NOARCH são pesquisados, na ordem em que são definidos.
+
+Em resumo, o simplaret tem uma ordem de precedência e execução de repositórios e para busca e obtenção
+de pacotes: pacotes são exibidos de acordo com a ordem e precedência descritas acima. No caso da ontenção
+de pacotes, o primeiro repositório que possuí-lo será utilizado, isto é, caso o pacote não for solicitado
+explicitamente com seu nome de arquivo completo mas sim apenas com seu nome.
+
+No caso da obtenção de patches, por padrão apenas repositórios do tipo PATCHES e ROOT são pesquisados,
+a não ser que isso seja configurado como contrário.
+
+Em repositórios do tipo REPOS e ROOT ainda é possível, através de parâmetros de configuração, explicitar
+a ordem de pastas que são pesquisadas dentro dos repositórios, algo que veremos a seguir e facilita no
+caso do usuário estar interessado em dar prioridade para aplicativos em fase de testes (usualmente
+armazenados na pasta testing/) ou pacotes antigos (pasture).
 
 [...]
 
@@ -221,9 +306,9 @@ 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
+  - slamd64 11.0
+  - slackware 10.0
+  - slackware 11.0 with additional i686 packages
   - uSlack (i386 uClibc) 
 
 Keep all this stuff update manually is really a headache. Simplaret just tries to make it trivial.