Help reviewing a new section of APT-Howto

[Gustavo Noronha Silva <kov@debian.org>]

Hello all,

I hope this list will help me with this =)... I wrote a new section
for apt-howto, my mother language is portuguese and apt-howto has
been primarily written and continues to be written in portuguese

I then translate what I write in portuguese to english... vorlon
has helped me a lot with this translation (it was mostly done by
him) because he's an native speaker of english...

I now send the new section for your review:

<sect id="pin">How to keep specific versions of packages installed
<p>
Sometimes you modified something in a program and don't have time or
don't want to port those changes to a new version of the program.
Then you "pin" the version you have installed so that it will not
be upgraded. Or you have just upgraded your Debian distribution
to 3.0 but wants to continue with a certain package from 2.2.
<p>
That's the purpose of "pinning". Using this resource is simple. 
You just need to edit the file <tt>/etc/apt/preferences</tt>.
<p>
The format is simple:
<example>
Package: &lt;package&gt;
Pin: &lt;pin definition&gt;
Pin-Priority: &lt;pin's priority&gt;
</example>
<p>
For example, to keep package <package>sylpheed</package> that I
have modified to use "reply-to-list" in version 0.4.99, I add:
<example>
Package: sylpheed
Pin: version 0.4.99*
</example>
Note that I used an <tt>*</tt> (asterisk). This is to say that
I want that this "pin" to be valid for all versions beginning
with 0.4.99. This is because Debian versions its packages with
a "Debian revision" and I don't want to avoid the instalation
of these revisions. So, versions 0.4.99-1 and 0.4.99-10 will
be installed as soon as they are made available.
<p>
Note also that I did not give a priority to the Pin. The priority
was auto-given as 989. Let's understand the priority better:
<p>
A priority that is lower than 0 marks the package defined by the
Pin to never be installed. Priorities 0 to 100 define packages
that are not installed and that have no available versions.
These won't come into the version-choosing process. Priority
100 is the priority given to an installed package - this means
that for a version that is different from the one installed to be
installed it needs to be priority greater than 100.
<p>
Priotities below 1000 are priorities that allows a package to be
installed. However, a package with a lower version than the one
wich is installed will not "downgrade". This means that: if I have
sylpheed 0.5.3 installed and define a Pin on sylpheed 0.4.99 with
priority 999, package 0.4.99 will <em>not</em> be installed to
satisfy the Pin. To make a package "downgradable", to satisfy the
Pin, it needs to be priority greater than 1000.
<p>
This takes us to an interesting idea. Suppose that you just upgraded
your <tt>stable</tt> version of Debian to the <tt>testing</tt> one
but you regreted. You may define a <tt>default Pin</tt> to come
back to stable. For example:
<example>
Package: *
Pin: release a=stable
Pin-Priority: 1001
</example>
<p>
After that, a <tt>apt-get -u dist-upgrade</tt> will "downgrade" your
system to the stable version.
<p>
Options to the pin are: <tt>version</tt>, <tt>release</tt>
or <tt>origin</tt>.
<p>
Option <tt>version</tt>, as we have seen, supports a normal version
and a mask (as an asterisk, for example) to define several versions
at one time.
<p>
Option <tt>release</tt> is the widest and depends on the Release
file from an APT repository or from a CD. This option can be
of no use at all because some repositories don't have this file.
You may see the contents of the Release files that you have on
<tt>/var/lib/apt/lists/</tt>. The sub-options are: a (archive),
c (components), v (version), o (origin) and l (label).
<p>
An example:
<example>
Package: *
Pin: release v=2.2*,a=stable,c=main,o=Debian,l=Debian
Priority: 1001
</example>
In this example, we chose version 2.2* of Debian, wich can be
2.2r2, 2.2r3, the <tt>stable</tt> repository, section <tt>main</tt>
(it could be contrib and non-free for example) and origin and
label Debian. Origin (o=) defines who produced that Release file,
the label (l=) defines the name of the distribution: Debian for
Debian itself and Progeny for Progeny, for example. A sample 
Release file:
<example>
$ cat /var/lib/apt/lists/ftp.debian.org.br_debian_dists_potato_main_binary-i386_Release 
Archive: stable
Version: 2.2r3
Component: main
Origin: Debian
Label: Debian
Architecture: i386
</example>
</sect>

here's the original in portuguese if it helps:

<sect id="pin">Como manter versões específicas de pacotes instaladas
<p>
Algumas vezes você fez uma modificação em um programa e não tem tempo
ou vontade de portar aquelas mudanças para um versão nova do programa.
Então você "prega" a versão que você tem instalada para que não seja
feita a atualização. Ou você acaba de atualizar sua distribuição Debian
para a 3.0 mas quer continuar com um certo pacote da 2.2.
<p>
É para esse propósito que serve o "pinning". A utilização desse recurso
é simples. Basta editar o arquivo <tt>/etc/apt/preferences</tt>.
<p>
O formato é simples:
<example>
Package: &lt;pacote&gt;
Pin: &lt;definição do pin&gt;
Pin-Priority: &lt;prioridade do pin&gt;
</example>
<p>
Por exemplo, para manter o pacote <package>sylpheed</package> que eu
modifiquei para aceitar "responder para a lista" na versão 0.4.99, eu adiciono:
<example>
Package: sylpheed
Pin: version 0.4.99*
</example>
Note que eu usei um <tt>*</tt> (asterisco). Isso serve para dizer
que quero que esse "pin" sirva para todas as versões que comecem
com 0.4.99. Isso porque o Debian versiona seus pacotes com uma
"revisão Debian" e eu não quero impedir essas revisões de entrar.
Ou seja, as versões 0.4.99-1 e 0.4.99-10 seriam instaladas a partir
do momento em que existissem.
<p>
Note também que eu não dei prioridade ao Pin. A prioridade foi
auto-definida como 989. Vamos entender melhor o que é a prioridade:
<p>
Uma prioridade menor que 0 faz com que o pacote definido para o
Pin nunca seja instalado. As prioridades 0 a 100 definem pacotes
não instalados e que não têm versões disponíveis então não entram
no processo de escolha de versão. A prioridade 100 é a prioridade
que o pacote atualmente instalado tem - isso significa que para
que uma versão diferente seja instalada ela precisa ter mais de
100 na prioridade.
<p>
Prioridades até 1000 são prioridades que permitem que o pacote seja
instalado. No entanto, um pacote com uma versão mais baixa não
será instalado com esta prioridade em cima de uma versão mais nova
que já está instalado. Ou seja: se eu tenho sylpheed 0.5.3 instalado
e defino um Pin para sylpheed 0.4.99 com prioridade 999, o pacote 0.4.99
<em>não</em> será instalado para conformar com o Pin. Para que um
pacote possa se "desatualizar" para cumprir a determinação de um Pin
ele precisa ter prioridade maior que 1000.
<p>
Isso leva a uma idéia interessante. Suponha que você acaba de atualizar
sua versão <tt>stable</tt> do Debian para a <tt>testing</tt> mas se 
arrependeu. Você pode definir um <tt>Pin padrão</tt> para voltar à
stable. Por exemplo:
<example>
Package: *
Pin: release a=stable
Pin-Priority: 1001
</example>
<p>
Depois disso, um <tt>apt-get -u dist-upgrade</tt> vai "desatualizar"
seu sistema para a versão estável.
<p>
As opções para o pin podem ser: <tt>version</tt>, <tt>release</tt>
ou <tt>origin</tt>.
<p>
A opção <tt>version</tt>, como já vimos, suporta uma versão normal
e uma máscara (como um asterisco, por exemplo) para definir várias
verões de uma vez.
<p>
A opção <tt>release</tt> é mais ampla e depende do arquivo Release
do repositório APT, ou do CD. Esta opção pode deixar a desejar pois
alguns repositórios não o contém. Você pode ver o conteúdo dos 
arquivos Release que você tem em <tt>/var/lib/apt/lists/</tt>. As
sub-opções são: a (archive), c (componente), v (versão), o (origin)
e l (label).
<p>
Um exemplo:
<example>
Package: *
Pin: release v=2.2*,a=stable,c=main,o=Debian,l=Debian
Priority: 1001
</example>
Neste exemplo escolhemos versão do Debian 2.2*, que pode ser
2.2r2, 2.2r3, repositório <tt>stable</tt>, seção <tt>main</tt>
(poderia ser contrib e non-free, por exemplo) e origem e nome
Debian. Origem (o=) define quem produziu aquele arquivo Release,
o nome (l=) define o nome da distribuição: Debian para o próprio
Debian e Progeny para a mesma, por exemplo. Um exemplo de
arquivo Release:
<example>
$ cat /var/lib/apt/lists/ftp.debian.org.br_debian_dists_potato_main_binary-i386_Release 
Archive: stable
Version: 2.2r3
Component: main
Origin: Debian
Label: Debian
Architecture: i386
</example>
</sect>

any suggestion will be appreciated =)

[]s!

-- 
    Gustavo Noronha Silva - kov <http://www.metainfo.org/kov>
*----------------------------------------------------------------*
|  .''`.  | Debian GNU/Linux: <http://www.debian.org>            |
| : :'  : | Debian BR.......: <http://debian-br.sourceforge.net> |
| `. `'`  |                  Be Happy! Be FREE!                  |
|   `-    |             "Think globally, act locally!"           |
*----------------------------------------------------------------*