debhelper.pt

title: debhelper.pt(7)

summary: a suite de ferramentas debhelper

text:
# debhelper.pt(7)

## NOME
debhelper - a suite de ferramentas debhelper

## RESUMO
dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]

## DESCRIÇÃO
Debhelper é usado para ajuda-lo a compilar um pacote Debian. A filosofia por detrás de debhelper é disponibilizar uma colecção de ferramentas pequenas, simples e de fácil compreensão que são usadas em debian/rules para automatizar vários aspectos comuns da compilação de um pacote. Isto significa menos trabalho para si, o empacotador. Também significa, até certo ponto, que estas ferramentas podem ser alteradas se a política de Debian alterar, e os pacotes que as usam irão precisar apenas de uma recompilação para ficarem em conformidade com a nova política.

Um ficheiro debian/rules típico que usa debhelper irá chamar vários comandos debhelper em sequência, ou usar dh(1) para automatizar este processo. Em /usr/share/doc/debhelper/examples/ estão exemplos de ficheiros de regras que usam debhelper.

Para criar um novo pacote Debian usando o debhelper, você pode copiar um dos ficheiros de regras exemplo e edita-lo à mão. Ou pode tentar o pacote dh-make, o qual contém um comando dh_make que automatiza parcialmente o processo Para uma introdução mais gentil, o pacote Debian maint-guide contém um tutorial acerca de como fazer o seu primeiro pacote usando o debhelper.

Except where the tool explicitly denotes otherwise, all of the debhelper tools assume that they run from the root directory of an unpacked source package. This is so they can locate files like debian/control when needed.

## COMANDOS DO DEBHELPER
Aqui está a lista dos comandos debhelper que você pode usar. Veja os seus manuais para documentação adicional.

\#LISTA#

### Comandos Descontinuados
Alguns comandos debhelper estão descontinuados e não devem ser usados.

\#LISTA_DE_DESCONTINUADOS#

### Outros comandos
Se o nome dum programa começa com dh_, e o programa não está nas listas em cima, então não faz parte do pacote debhelper, mas mesmo assim deverá funcionar como os outros programas descritos nesta página.

## FICHEIROS DE CONFIGURAÇÃO DO DEBHELPER
Muitos comandos do debhelper usam ficheiros em debian/ para controlar o que fazem. Para além dos comuns debian/changelog e debian/control, que estão em todos os pacotes, e não apenas aqueles que usam debhelper, alguns ficheiros adicionais podem ser usados para configurar o comportamento de comandos debhelper específicos. Estes ficheiros são chamados tipicamente debian/pacote.foo (onde pacote é claro, é substituído pelo nome do pacote no qual se está a actuar).

Por exemplo, dh_installdocs usa ficheiros chamados debian/package.docs para listar os ficheiros de documentação que ira instalar. Veja os manuais individuais dos comandos para detalhes acerca dos nomes e formatos dos ficheiros que usam. Geralmente, estes ficheiros irão listar ficheiros onde se vai actuar, um ficheiro por linha. Alguns programas no debhelper usam pares de ficheiros e destinos ou formatos ligeiramente mais complicados.

Nota se existir apenas um pacote binário listado em debian/control, então o debhelper irá usar debian/foo quando não existe nenhum ficheiro debian/package.foo. Nos níveis de compatibilidade antes de 15, este regressar também ocorre para o primeiro pacote binário listado em debian/control quando existem múltiplos pacotes binários. No entanto, é geralmente uma boa ideia manter o prefixo package. pois é mais explícito e também necessário quando se actualiza para compatibilidade 15.

Adicionalmente, existem alguns casos especiais onde o debhelper irá sempre cair para uma versão de menos-prefixo. Estes são casos como debian/copyright e debian/changelog, onde os ficheiros são geralmente usados e necessários para todos os pacotes binário.

Em alguns casos raros, você pode querer ter versões diferentes destes ficheiros para arquitecturas ou sistemas operativos diferentes. Se existirem ficheiros chamados debian/pacote.foo.ARCH ou debian/pacote.foo.OS, onde ARCH e OS são o mesmo que o resultado de "dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS", então eles irão ser usados em preferência de outros ficheiros mais gerais.

Maioritariamente, estes ficheiros de configuração são usados para especificar listas de vários tipos de ficheiros. Documentação ou ficheiros exemplo para instalar, ficheiros para mover, e etc. Quando apropriado, em casos como estes, você pode usar caracteres "wildcard" de shell standard (classes de caracteres ? e * e [..]) nos ficheiros. Também pode meter comentários neste ficheiros; as linhas começadas com # são ignoradas.

A sintaxe destes ficheiros é mantida intencionalmente muito simples para os tornar fáceis de ler, compreender e modificar.

### Substituições em ficheiros de configuração do debhelper
Em nível de compatibilidade 13 e posterior, é possível usar substituições simples em ficheiros de configuração do debhelper para as seguintes ferramentas:

- dh_clean

- dh_install

- dh_installcatalogs

- dh_installdeb

- dh_installdirs

- dh_installdocs

- dh_installexamples

- dh_installinfo

- dh_installman

- dh_installwm

- dh_link

- dh_missing

- dh_ucf

Todas as variáveis de substituição são do formato ${foo} e as chavetas são obrigatórias. Os nomes das variáveis são sensíveis a maiúscula/minúscula e consistem de alfanuméricos (a-zA-Z0-9), hífens (-), underscores (_), and dois pontos (:). O primeiro caractere tem de ser alfanumérico.

Se precisar de um sinal literal de dollar que não despolete uma substituição, você pode ou usar a substituição de ${Dollar} ou a sequência ${}.

As seguintes expansões estão disponíveis:

DEB_HOST_*, DEB_BUILD_*, DEB_TARGET_*

Expande para o valor dpkg-architecture(1) relevante (semelhante a dpkg-architecture -qVARIABLE_HERE). Em caso de dúvida, a variante DEB_HOST_* é aquela que irá trabalhar para ambas compilações nativas e cruzadas.

Por razões de performance, o debhelper irá tentar resolver esses nomes primeiro a partir do ambiente antes de consultar dpkg-architecture(1). Isto é muito mencionado para plenitude pois não irá ter importância na maioria dos casos.

Dollar

Expande para um símbolo literal único $-symbol. Este símbolo nunca irá ser considerado parte de uma variável de substituição. Isso é:

```
   # Triggers an error
   ${NO_SUCH_TOKEN}
   # Expands to the literal value "${NO_SUCH_TOKEN}"
   ${Dollar}{NO_SUCH_TOKEN}

```

Esta variável é equivalente à sequência ${} e as duas podem ser usadas alternadamente.

Newline, Space, Tab

Expande para uma nova linha ASCII única, espaço e tab respetivamente. Isto pode ser útil se precisar de incluir um caractere literal de "espaço em branco" (ex. espaço) onde caso contrário ele iria ser descartado ou usado como um separador.

env:NAME

Expande para a variável de ambiente NAME. A variável de ambiente tem de estar definida (mas pode estar definida para uma string vazia).

Note que todas as variáveis têm de expandir para um valor definido. Como exemplo, se o debhelper vir ${env:FOO}, então ele irá insistir que a variável de ambiente FOO está definida (pode estar definida para uma string vazia).

Limites de substituição

Para evitar ciclos infinitos e exaustão de recursos, o debhelper irá parar com um erro se o token conter muitas variáveis de substituição (50) ou se o valor total do valor expandido exceder um determinado tamanho (4096 caracteres ou 3x o comprimento da entrada original - qual deles for maior).

Note que o limite é por token. Cada ajudante decide a sua própria definição de um token. O caso comum de ficheiros como debian/package.install, cada token é um nome de ficheiro/caminho.

Limitações de substituição: filtragem

A substituição embutida não pode ser usada para "filtrar" conteúdos. Tentativas de criar "comentários" ou "linhas vazias" via substituição irá resultar em que essas variáveis seja consideradas um token no seu próprio direito com o conteúdo dado.

Se você deseja filtrar, considere usar um ficheiro de configuração de debhelper executável com o dh-exec como interpretador. A ferramenta dh-exec suporta várias funcionalidades directamente. No entanto tenha em mente que o dh-exec tem a sua própria lógica de substituição que consegue interagir funcionalmente com a do debhelper.

### Ficheiros de configuração do debhelper executáveis.
Se precisar de flexibilidade adicional, muitas das ferramentas debhelper (ex, dh_install(1)) suportam executar um ficheiro de configuração como um script.

Para usar esta funcionalidade, simplesmente marque o ficheiro de configuração como executável (ex. chmod +x debian/package.install) e a ferramenta irá tentar executa-lo e usar o resultado do script. Em muitos casos, você pode usar dh-exec(1) como interpretador do ficheiro de configuração para reter a maioria da sintaxe original enquanto obtém a flexibilidade adicional que precisa.

Quando usar ficheiros de configuração executáveis do debhelper, por favor tenha em atenção o seguinte:

- O ficheiro de configuração executável must termina com sucesso (isto é, o seu código de retorne deve indicar sucesso).

- Em nível de compatibilidade 13+, o resultado será sujeito a substituições (veja "Substituições em ficheiros de configuração do debhelper") onde a ferramenta suportar estes. Lembre-se disto se o seu gerador também disponibilizar substituições pois isto pode causar confusão desnecessária. Notavelmente, a ferramenta dh-exec geralmente usada tem o seu próprio suporte de substituição. Caso contrário, o resultado de saída irá ser usado exatamente como está. De notar que o debhelper não irá expandir wildcards, nem retirar comentários ou espaços em branco aos resultados que lê. A ferramenta dh-exec tem um filtro de saída ligado por predefinição que irá remover estas coisas.

Se precisar que o pacote compile num sistema de ficheiros onde não pode desactivar o bit de executável, então você pode usar dh-exec(1) o o seu script strip-output.

## OPÇÕES DO DEBHELPER PARTILHADAS
As seguintes opções de linha de comandos são suportadas por todos os programas do debhelper.

-v, --verbose

Modo detalhado: mostra os comandos que modificam o directório de compilação de pacotes. Note que o modo detalhado pode também gerar resultados de outros comandos "internos" que não afectam diretamente o directório de compilação de pacotes.

--no-act

Não faz nada na realidade. Se usado com -v, o resultado é que o comando mostra o que iria fazer.

-a, --arch

Actua em pacotes dependentes da arquitectura que devem ser compilados para a arquitectura de compilação DEB_HOST_ARCH.

-i, --indep

Actua em todos os pacotes independentes da arquitectura.

-ppacote, --package=pacote

Actua no pacote chamado pacote. Esta opção pode ser especifica várias vezes para fazer o debhelper operar num determinado conjunto de pacotes.

-s, --same-arch

Alias descontinuado de -a. Esta opção foi removida no nível de compatibilidade 12.

-Npacote, --no-package=pacote

Não actua no pacote especificado mesmo se uma opção -a, -i, ou -p listarem o pacote como um em que se deverá actuar.

--remaining-packages

Não actua nos pacotes que já foram actuados antes por este comando do debhelper (isto é, se o comando estiver presente no debhelper log do pacote). Por exemplo, se você precisar de chamar o comando com opções especiais apenas para um par de pacotes binários, passe esta opção para a última chamada do comando para processar o resto dos pacotes com as definições predefinidas.

-Ptmpdir, --tmpdir=tmpdir

Usa tmpdir para directório de compilação de pacotes. A predefinição é debian/pacote

--mainpackage=pacote

Descontinuado: Esta opção não tem uso prático em compatibilidade 15 ou posterior pois o comportamento que afeta foi removido na compatibilidade 15. Esta opção pouco usada muda o pacote que o debhelper considera o "pacote principal", isto é, o primeiro listado em debian/control, e aquele para o qual os ficheiros debian/foo podem ser usados em vez dos ficheiros debian/package.foo usuais.

-O=opção|bundle

Isto é usado pelo dh(1) quando se passa opções específicas do utilizador a todos os comandos que corre. Se o comando suportar a opção ou opções especificadas, irá fazer efeito. Se o comando não suportar a opção (ou alguma parte do conjunto de opções), será ignorado.

## OPÇÕES COMUNS DO DEBHELPER
As seguintes opções de linha de comandos são suportadas por alguns programas do debhelper. Veja o manual de cada programa para uma explicação completa sobre o que cada opção faz.

-n

Não modifique os scripts postinst, postrm, etc.

-Xitem, --exclude=item

Exclui um item do processamento. Esta opção pode ser usada várias vezes, para excluir mais do que uma coisa. O item é tipicamente parte de um nome de ficheiro, e qualquer ficheiro que contenha o texto especificado será excluído.

-A, --all

Faz com que ficheiros ou outros itens que são especificados na linha de comandos tenham efeito em TODOS os pacotes em que se actua, e não apenas o primeiro.

## OPÇÕES DO SISTEMA DE COMPILAÇÃO
As seguintes opções de linha de comandos são suportadas por todos os comandos dh_auto_* do debhelper. Estes programas suportam uma variedade de sistemas de compilação, e normalmente determinam heuristicamente qual usar, e como os usar. Você pode usar estes opções de linha de comandos para sobrepor o comportamento predefinido. Tipicamente estas são passadas ao dh(1), o qual passa-as a todos os programas dh_auto_*.

-Sbuildsystem, --buildsystem=buildsystem

Força a utilização do |<buildsystem> especificado, em vez de tentar auto-seleccionar um que pode ser aplicável para o pacote. Passa none como buildsystem para desactivar a auto-selecção.

-Ddirectory, --sourcedir=directory, --sourcedirectory=directory

Assume que a árvore fonte do pacote original está no directório especificado em vez de estar no directório de nível de topo da árvore de pacotes fonte de Debian. Aviso: A variante --sourcedir corresponde a uma opção de nome semelhante em dh_install e dh_missing (etc.) por razões históricas. Apesar de terem nomes semelhantes, elas têm objectivos muito distintos e em alguns casos podem causar erros quando esta variante é passada ao dh (quando então passada para todas as ferramentas).

-B[directory], --builddir[=directory], --builddirectory[=directory]

Activa a compilação da fonte e usa o directório especificado como o directório de compilação. Se o parâmetro directório for omitido, é escolhido o directório de compilação predefinido. Se esta opção não for especificada, a compilação será feita por predefinição na fonte a menos que o sistema de compilação requeira ou prefira a compilação da árvore de fonte. Em tal caso, será usado o directório de compilação predefinido mesmo se --builddirectory não seja especificado.

Se o sistema de compilação preferir a compilação da árvore fonte mas ainda permitir a compilação da fonte, a última pode ser re-activada ao passar-lhe um caminho para um directório de compilação que é o mesmo que o caminho para o directório fonte.

--parallel, --no-parallel

Controla se devem ser usadas compilações paralelas se o sistema de compilação o suportar. O número de trabalhos paralelos é controlado pela variável de ambiente DEB_BUILD_OPTIONS ("Debian Policy, secção 4.9.1") durante a compilação. Também pode servir como um limite específico do sistema de compilação. Se nenhuma destas opções for especificada, presentemente o debhelper usa por predefinição --parallel em modo compatibilidade 10 (ou posterior) e --no-parallel em caso contrário.

Como uma optimização, o dh irá tentar evitar passar estas opções aos sub-processos, se estas forem desnecessárias e as únicas opções a passar. De notar que isto acontece quando DEB_BUILD_OPTIONS não tem um parâmetro parallel (ou o seu valor é 1).

--max-parallel=máximo

Esta opção implica --parallel e permite mais limitação ao número de trabalhos que podem ser usados numa compilação paralela. Se a compilação do pacote é conhecida por apenas funcionar em certos níveis de concorrência, você pode definir isto para o nível máximo que é sabido funcionar, ou que deseje suportar. De notar que, definir o máximo para 1 é efectivamente o mesmo que usar --no-parallel.

--reload-all-buildenv-variables

Por predefinição, o dh(1) irá computar várias variáveis de ambiente (ex. ao usar dpkg-buildflags(1)) e guarda-los em cache para evitar que todas as ferramentas dh_auto_* os recompute. Quando se passa esta opção, a ferramenta dh_auto_* concreta irá ignorar a cache de dh(1) e re-despoletar uma recompilação destas variáveis. Isto é útil nos casos muito raros onde o pacote precisa de fazer múltiplas compilações mas com diferentes opções ...FLAGS. Um exemplo concreto seria precisar de alterar o parâmetro -O em CFLAGS na segunda compilação:

```
    export DEB_CFLAGS_MAINT_APPEND=-O3
    %:
        dh $@
    override_dh_auto_configure:
        dh_auto_configure -Bbuild-deb ...
        DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
           --reload-all-buildenv-variables -Bbuild-udeb ...

```

Sem --reload-all-buildenv-variables na segunda chamada ao dh_auto_configure(1), a alteração em DEB_CFLAGS_MAINT_APPEND seria ignorada pois dh_auto_configure(1) iria usar o valor em cache de <CFLAGS> definido por dh(1).

Esta opção está apenas disponível com debhelper (>= 12.7~) quando o pacote usar nível de compatibilidade 9 ou posterior.

--list, -l

Lista todos os sistemas de compilação suportados pelo debhelper neste sistema. A lista inclui ambos sistemas de compilação predefinidos e de terceiros (marcados como tal). Também mostra qual o sistema de compilação será seleccionado automaticamente, ou qual está especificado manualmente com a opção --buildsystem.

## NÍVEIS DE COMPATIBILIDADE
De tempos a tempos, precisam de ser feitas grandes alterações no debhelper que não compatíveis com as versões anteriores, para o manter limpo e bem construído quando as necessidades alteram e o seu autor ganha mais experiência. Para prevenir que tais grandes alterações danifiquem os pacotes existentes, foi introduzido o conceito de níveis de compatibilidade no debhelper. Você deve dizer ao debhelper qual o nível de compatibilidade que ele deve usar, e ele modifica o seu comportamento de várias maneiras.

No debhelper actual, você pode especificar o nível de compatibilidade em debian/control ao adicionar um Build-Depends no pacote debhelper-compat. Por exemplo, para usar modo v13, assegure que debian/control tem:

```
  Build-Depends: debhelper-compat (= 13)
```

Isto também serve como uma dependência de compilação de versão apropriada numa versão suficiente do pacote debhelper, assim você não precisa de especificar uma dependência de compilação de versão separada no pacote debhelper a menos que precise de um lançamento pontual específico do debhelper (tal como para a introdução de uma nova funcionalidade ou correcção de bug dentro de um nível de compatibilidade).

Note que o debhelper não fornece debhelper-compat para os níveis de compatibilidade experimental ou beta; os pacotes que experimentem com esses níveis de compatibilidade devem meter o nível de compatibilidade no campo X-DH-Compat da estrofe Source no ficheiro debian/control (ou, se apenas para comandos selecionados, na variável de ambiente DH_COMPAT).

Historicamente, o debhelper requeria o nível de compatibilidade especificado no ficheiro debian/compat, e o debhelper até à versão 14 suporta isto para compatibilidade com as versões anteriores Para usar este método, o ficheiro debian/compat deve conter o nível de compatibilidade como um número singular, e nenhum outro conteúdo. Se você especificar o nível de compatibilidade neste método, o seu pacote vai também precisar duma dependência de compilação baseada em versão de uma versão do pacote debhelper igual (ou superior) ao nível de compatibilidade que o seu pacote usa. Assim, se você especificar o nível de compatibilidade 13 em debian/compat, assegure-se que debian/control contém:

```
  Build-Depends: debhelper (>= 13~)
```

Note que você deve usar exactamente um método para especificar o nível de compatibilidade predefinido do debhelper do pacote. Sempre que possível, é recomendado a build-dependency do debhelper-compat.

Se necessário, a variável de ambiente DH_COMPAT pode ser usada para sobrepor o nível de compatibilidade para um dado comando. Esta funcionalidade é maioritariamente útil seja para actualizar temporariamente alguns comandos para um novo nível de compatibilidade ou manter alguns comandos num nível de compatibilidade inferior. Esta funcionalidade é melhor ser usada com moderação pois introduz efectivamente casos-especiais no ficheiro debian/rules que podem ser surpreendentes para maintainers ou revisores (ou, a longo prazo, para si).

A menos que seja indicado o contrário, toda a documentação do debhelper assume que você está a usar o nível de compatibilidade mais recente, e na maioria dos casos não indica se o comportamento é diferente num nível de compatibilidade anterior, portanto se não está a usar o nível de compatibilidade mais recente, você é aconselhado a procurar em baixo por notas acerca do que é diferente nos níveis de compatibilidade anteriores.

### Níveis de compatibilidade suportados
A lista dos níveis de compatibilidade suportados e a lista de verificação de actualizações relacionadas foi movida para debhelper-compat-upgrade-checklist(7).

## NOTAS

### Suporte a pacotes de múltiplos binários
Se o seu pacote fonte gerar mais do que um pacote binário, os programas do debhelper, por predefinição, irão actuar em todos os pacotes binários quando correm. No caso do seu pacote fonte gerar um pacote dependente de arquitectura, e outro pacote independente da arquitectura, este não é o comportamento correcto, porque você precisa de gerar os pacotes dependentes de arquitectura no alvo debian/rules binary-arch, e os pacotes independentes de arquitectura no alvo debian/rules binary-indep.

Para facilitar isto, e também para lhe dar mais controle sobre em quais pacotes os programas debhelper actuam, todos os programas debhelper aceitam os parâmetros -a, -i, -p, e -s. Estes parâmetros são cumulativos. Se nenhum for usado, os programas debhelper por predefinição actuam em todos os pacotes listados no ficheiro de controle, com as excepções em baixo.

Primeiro, qualquer pacote cujo campo Architecture em debian/control não corresponda à arquitectura DEB_HOST_ARCH será excluído ("Debian Policy, secção 5.6.8").

Também, alguns pacotes adicionais podem ser excluídos com base no conteúdo da variável de ambiente DEB_BUILD_PROFILES e nos campos Build-Profiles nas estrofes de pacotes binários em debian/control, de acordo com a política proposta em <https://wiki.debian.org/BuildProfileSpec>.

Interacção entre selecções de pacotes e Build-Profiles

Build-Profiles afectam quais pacotes são incluídos nos mecanismos de selecção de pacotes do debhelper. Geralmente, as selecções de pacotes são descritas a partir do pressuposto que todos os pacotes estão activados. Esta secção descreve como as selecções reagem quando um pacote é desactivado devido a Build-Profiles activos (ou a falta de Build-Profiles activos).

-a/--arch, -i/--indep OU nenhuma opção de selecção (uma chamada "dh_X" crua)

O pacote desactivado por Build-Profiles é excluído em silêncio da selecção. Note que vai receber um aviso se todos os pacotes relacionados com estas selecções estiverem desactivados. Nesse caso, geralmente não faz nenhum sentido sequer fazer a compilação.

-N package / --no-package package

A opção é aceite e efectivamente não faz nada.

-p package / --package package

A opção é aceite, mas o debhelper não irá actuar no pacote.

Note que não importa se um pacote está activado ou desactivado por predefinição.

### Geração automática de scripts de instalação Debian
Alguns comandos do debhelper irão gerar automaticamente partes de scripts de maintainer Debian. Se desejar que estas coisas geradas automaticamente sejam incluídas nos sues scripts de maintainer Debian existentes, então você precisa adicionar #DEBHELPER# aos seus scripts, no local onde o código deverá ser adicionado. #DEBHELPER# será substituído por qualquer código auto-gerado quando você correr o dh_installdeb.

Se não existir nenhum script e o debhelper precisar de adicionar algo a ele, então o debhelper irá criar o script completo.

Ao inserir o token #DEBHELPER# num script, considere se qualquer do código escrito à mão tem uma razão convincente para aparecer antes do token #DEBHELPER#. O token #DEBHELPER# irá geralmente conter o código que arranca (postinst) ou pára (prerm/preinst) quaisquer serviços que o pacote fornece. Muitas vezes (mas nem sempre), é melhor deixar o código de #DEBHELPER# correr primeiro. Exceções comuns incluem coisas como set -e, inicializar debconf (quando necessário) e casos especiais como geração de gestão escrita à mão de ficheiros de configuração. Estas coisas devem geralmente ocorrer antes do token #DEBHELPER#.

Todos os comandos debhelper que geram código automaticamente deste modo permitem que o seja desactivado pelo parâmetro -n (ver em cima).

Note que o código inserido será código shell, portanto você não pode usa-lo directamente num script de Perl. Se desejar embebe-lo num script Perl, aqui está um modo de o fazer (note que Eu certifico-me que $1, $2, etc são definidos com o comando "set"):

```
  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("The debhelper script failed with error code: ${exit_code}");
     } else {
         die("The debhelper script was killed by signal: ${signal}");
     }
  }
```

### Geração automática de dependências variadas.
Alguns programas debhelper podem fazer com que o pacote gerado precise de depender de alguns outros pacotes. Por exemplo, se você usar o dh_installdebconf(1), o seu pacote irá geralmente depender do debconf. Ou se você usar dh_installxfonts(1), o seu pacote irá geralmente depender de uma versão particular do xutils. Acompanhar estas dependências variadas pode ser aborrecido pois elas dependem de como o debhelper faz as coisas, então o debhelper oferece um modo de automatizar isto.

A partir de compatibilidade 14, o debhelper irá injectar automaticamente as dependências relevantes para si, como a dependência é feita via um "relacionamento substvar" (veja <https://lists.debian.org/debian-devel/2024/02/msg00230.html> e <https://lists.debian.org/debian-devel/2024/03/msg00030.html> para detalhes).

Em níveis de compatibilidade anteriores, você tem de especificar manualmente os substvars relevantes nos campos relevantes. Tipicamente, ${misc:Depends} para o campo Depends e ${misc:Pre-Depends} para o campo Pre-Depends.

As variáveis listadas aqui são inteiramente independentes do standard ${shlibs:Depends} gerado pelo dh_makeshlibs(1), e do ${perl:Depends} gerado pelo dh_perl(1). Para compatibilidade 13 e anterior você terá também de adicionar estes aos campos respectivos quando relevante.

### Directórios de compilação de pacotes
Por predefinição, todos os programas do debhelper assumem que o directório temporário usado para montar a árvore de ficheiros num pacote é debian/pacote.

Por vezes, você pode querer usar outro directório temporário. Isto é suportado pela bandeira -P, por exemplo, "dh_installdocs -Pdebian/tmp", irá usar debian/tmp como directório temporário. Note que se você usar -P, os programas debhelper só podem actuar num pacote de cada vez. Por isso se tem um pacote que compila muitos pacotes binários, irá também precisar de usar a bandeira -p para especificar em qual pacote binário o programa debhelper irá actuar.

### udebs
Debhelper inclui suporte para udebs. Para criar um udeb com o debhelper, adicione "Package-Type: udeb" à estrofe do pacote em debian/control. O Debhelper irá tentar criar udebs em conformidade com a política do instalador debian, ao finalizar os ficheiros de pacotes gerados com .udeb, não instalando nenhuma documentação num udeb, saltando os scripts preinst, postrm, prerm, e config, etc.

## AMBIENTE
Esta secção descreve algumas das variáveis de ambiente que influenciam o comportamento do debhelper ou de quem o debhelper interage.

É importante notar que estas que estas têm de ser mesmo variáveis de ambiente de modo a afectarem o comportamento do debhelper (e não simplesmente variáveis do Makefile). Para as especificar correctamente em debian/rules, assegure-se de lhes fazer "export". Por exemplo, "export DH_VERBOSE"

DH_VERBOSE

Definir para um valor não-vazio para activar o modo detalhado. Por favor veja a opção -v / --verbose para detalhes.

DH_QUIET

Definir para um valor não-vazio para activar o modo silencioso. O Debhelper não irá escrever os comandos a chamar o sistema de compilação do autor nem o dh irá escrever quais sub-comandos são chamados e dependendo do sistema de compilação do autor, poderá também tornar isso mais silencioso. Isto facilita a identificação de mensagens importantes mas torna os resultados inúteis como relatório do buildd. É ignorado se DH_VERBOSE estiver também definido ou se for passado -v / --verbose.

DH_COMPAT

Especifica temporariamente em que nível de compatibilidade o debhelper deve correr, sobrepondo o nível de compatibilidade predefinido do pacote fonte.

DH_NO_ACT

Defina para 1 para activar o modo no-act.

DH_OPTIONS

Todas as ferramentas debhelper irão processar os argumentos de linha de comandos listados nesta variável antes de qualquer opção de comando (como se eles fossem anexados aos argumentos de linha de comandos). Infelizmente, algumas ferramentas disponibilizadas por terceiros podem não suportar esta variável e irão ignorar estes argumentos de linha de comandos. Quando se usa dh(1), podem-se passar opções que irão ser passadas a cada comando do debhelper, o que é geralmente melhor do que usar DH_OPTIONS.

DH_ALWAYS_EXCLUDE

Se definido, isto adiciona o valor que está definido na variável às opções -X de todos os comandos que suportam a opção -X. Ainda mais, o dh_builddeb irá fazer rm -rf a tudo o que corresponda a esse valor na sua árvore de compilação do pacote. Isto pode ser útil se você está a fazer uma compilação a partir de uma árvore fonte CVS, que no caso definindo DH_ALWAYS_EXCLUDE=CVS irá prevenir que quaisquer directórios CVS se esgueirem para o pacote que está a compilar. Ou, se um pacote tem um tarball de fonte que (não inteligentemente) inclui directórios CVS, você pode querer exportar DH_ALWAYS_EXCLUDE=CVS em debian/rules, para o fazer ter efeito onde o seu é compilado.

Várias coisas a excluir podem ser separadas com "dois pontos", como em DH_ALWAYS_EXCLUDE=CVS:.svn

DH_EXTRA_ADDONS

Se definido, isto adiciona os addons especificados do dh para serem corridos nos lugares apropriados na sequência de comandos. Isto é equivalente a especificar o addon a correr coma bandeira --with no ficheiro debian/rules file. Qualquer chamada --without que especifique um addon nesta variável de ambiente não será executada. Isto destina-se a ser usado por downstreams ou configurações locais especificas que requeiram a execução dum addon do debhelper durante múltiplas compilações sem terem que aplica patch a um grande número de ficheiros de regras. Se de todo possível, isto deve ser evitado em favor de uma bandeira --with no ficheiro rules.

DH_COLORS, DPKG_COLORS

Estas variáveis podem ser usadas para controlar se os comandos do debhelper devem usar cores nos resultados textuais. Podem ser definidas para "always", "auto" (a predefinição), ou "never". Note que DPKG_COLOR também afecta um número de ferramentas relacionadas ao dpkg e o debhelper usa-o na suposição que você quer a mesma definição de cor para o dpkg e debhelper. Na hipótese de você querer definição de cor diferente para o debhelper, pode usar DH_COLORS em vez disso ou em adição a DPKG_COLORS.

NO_COLOR

Se não for fornecido um pedido específico para cor (ex. DH_COLORS e DPKG_COLORS estão ambos não-definidos), a presença desta variável de ambiente faz com que a definição de cor predefinida seja "never". A variável é definida de acordo com <https://no-color.org/>. Neste projecto, as variáveis de ambiente (tais como DH_COLORS) são consideradas um requisito explícito para cor.

CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS, LDFLAGS

Por predefinição (em qualquer nível de compatibilidade não-abandonado). o debhelper irá automaticamente definir estas flags ao usar dpkg-buildflags(1), quando não estiverem definidas. Se você precisar de modificar as flags predefinidas, por favor use as funcionalidades de dpkg-buildflags(1) para o fazer (ex. DEB_BUILD_MAINT_OPTIONS=hardening=all ou DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) em vez de definir a variável concreta directamente.

HOME, XDG_*

Em compatibilidade 13 e posterior, estas variáveis de ambiente são reiniciadas antes de invocar o sistema de compilação do autor via ajudantes do dh_auto_*. As variáveis HOME (todos os ajudantes dh_auto_*) e XDG_RUNTIME_DIR (apenas dh_auto_test) irão ser definidas para um directório gravável. Todas as restantes variáveis e XDG_RUNTIME_DIR (excepto para durante dh_auto_test) irão ser limpas. O directório HOME será criado como um directório vazio mas ele será reutilizado entre chamadas a dh_auto_*. Qualquer conteúdo irá persistir até ser explicitamente apagado ou dh_clean.

DEB_BUILD_OPTIONS

Por favor veja "Bandeiras suportadas em DEB_BUILD_OPTIONS" para esta variável de ambiente. Por favor note que esta variável não deve ser alterada por maintainers de pacote dentro de debian/rules para mudar o comportamento do debhelper. Em vez disso, onde o maintainer do pacote precisar destas funcionalidades, eles devem procurar desactivar a funcionalidade relevante directamente (ex. ao sobrepor as ferramentas concretas).

DEB_BUILD_MAINT_OPTIONS

Esta é uma variável de ambiente especifica do dpkg (veja por ex. dpkg-buildflags(1)). A suite de ferramentas do debhelper ignora-a em silêncio. Está documentada aqui porque tem um nome semelhante a DEB_BUILD_OPTIONS, o que faz com que algumas pessoas assumam em erro que o debhelper também vai reagir a esta variável.

### Bandeiras suportadas em DEB_BUILD_OPTIONS
A suite de ferramentas debhelper reage às seguintes bandeiras em DEB_BUILD_OPTIONS.

dherroron=obsolete-compat-levels

Este é um valor específico do debhelper. Quando dherroron está presente e definida para obsolete-compat-levels, então as ferramentas debhelper irão promover para erros os avisos de descontinuidade de níveis de compatibilidade antigos e prestes a serem removidos.

Isto é útil para verificação automática de confiança de código em níveis de compatibilidade descontinuados que estão agendados para remoção.

Esta opção destina-se a objectivos de teste; não compilações produtivas.

nostrip

Este valor irá mudar o conteúdo dos debs a serem compilados. Os pacotes .deb compilados quando isto está definido são por isto não reproduzíveis bit-a-bit com uma compilação regular nas generalidade dos casos. Este valor irá fazer com que as ferramentas oficiais debhelper saltem acções e ajudantes que ou removem, desanexam ou duplicam símbolos em binários ELF.

Este valor afecta dh_dwz(1) e dh_strip(1).

nocheck

Este valor irá fazer com que os sistemas de compilação oficiais debhelper saltem execuções de suites de testes do autor original. Os maintainers de pacotes que procurem evitar correr os testes do autor não devem confiar nisto. Em vez disto, eles podem adicionar um alvo de sobreposição vazio para saltar o dh_auto_test.

Este valor afecta dh_auto_test(1).

nodoc

Este valor irá mudar o conteúdo dos debs a serem compilados. Os pacotes .deb compilados quando isto está definido são por isto não reproduzíveis bit-a-bit com uma compilação regular nas generalidade dos casos. Este valor irá fazer com que várias ferramentas debhelper saltem a instalação de documentação tal como os manuais ou documentação fornecida pelo autor original. Adicionalmente, as ferramentas irão também ignorar se a documentação declarada está "em falta" assumindo que a documentação não foi compilada.

Este valor afecta ferramentas do tipo dh_installdocs(1), que sabem que estão a trabalhar com documentação.

notrimdch

Este valor irá mudar o conteúdo dos debs a serem compilados. Os pacotes .deb compilados quando isto está definido são por isto não reproduzíveis bit-a-bit com uma compilação regular nas generalidade dos casos. Este valor irá fazer o dh_installchangelogs(1) actuar como se tivesse passado a opção --no-trim, forçando-o a renunciar a remoção de entradas antigas dos registos de alterações.

noautodbgsym, noddebs

O nome oficial é noautodbgsym. A variante noddebs é aceite por razões históricas. Este valor faz com que o debhelper salte a geração de pacotes de símbolos de depuração gerados automaticamente.

Este valor afecta dh_strip(1).

parallel=N

Este valor habilita o debhelper a usar até N linhas de processos (sujeitos a parâmetros como --no-parallel e --max-parallel=M). Nem todas as ferramentas debhelper trabalham com tarefas paralelas e podem ignorar o pedido em silêncio. Este valor afecta muitas ferramentas debhelper. Mais notoriamente dh_auto_*, a qual irá tentar correr o sistema de compilação subjacente do autor com esse número de linhas de execução.

terse

Este valor irá fazer com que os sistemas de compilação oficiais debhelper configurem as compilações do autor para serem concisas (isto é, reduzir os detalhes dos seus resultados). Isto está sujeito a que os sistemas de compilação do autor e do debhelper suportem tais funcionalidades. Este valor afecta a maioria das ferramentas dh_auto_* diretamente. Para comandos fornecidos pelo pacote debhelper, também faz com que as ferramentas actuem como se a variável de ambiente DH_QUIET estiver não-vazia.

Bandeiras desconhecidas são ignoradas em silêncio.

Note que ferramentas de terceiros estilo-debhelper ou sistemas de compilação fornecidos por terceiros podem não reagir às bandeiras em cima. Isto tende a depender dos detalhes de implementação da ferramenta.

## VEJA TAMBÉM
debhelper-compat-upgrade-checklist(7)

Lista de níveis de compatibilidade suportados e uma lista de verificação de actualização para cada um deles.

/usr/share/doc/debhelper/examples/

Um conjunto de ficheiros debian/rules exemplo que usam debhelper.

<http://joeyh.name/code/debhelper/>

Sítio web do debhelper.

## AUTOR
Joey Hess <joeyh@debian.org>

## TRADUÇÃO
Américo Monteiro

Se encontrar algum erro na tradução deste documento, por favor comunique para Américo Monteiro a_monteiro@gmx.com ou Equipa Debian de Tradução Portuguesa traduz@debianpt.org.


markdown

package: discount

title: markdown(7)

summary: The Markdown text formatting syntax

text:
# markdown(7)

## NAME
Markdown — The Markdown text formatting syntax

## DESCRIPTION

### Philosophy
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters -- including Setext, atx, Textile, reStructuredText, Grutatext, and EtText -- the single biggest source of inspiration for Markdown's syntax is the format of plain text email.

To this end, Markdown's syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you've ever used email.

### Inline HTML
Markdown's syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown's formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown's syntax, you simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements -- e.g. <div>, <table>, <pre>, <p>, etc. -- must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

```
    This is a regular paragraph.

    <table>
        <tr>
            <td>Foo</td>
        </tr>
    </table>

    This is another regular paragraph.
```

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style *emphasis* inside an HTML block.

Span-level HTML tags -- e.g. <span>, <cite>, or <del> -- can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you'd prefer to use HTML <a> or <img> tags instead of Markdown's link or image syntax, go right ahead.

Unlike block-level HTML tags, Markdown syntax *is* processed within span-level tags.

### Automatic Escaping for Special Characters
In HTML, there are two characters that demand special treatment: `<` and `&`. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. `<`, and `&`.

Ampersands in particular are bedeviling for web writers. If you want to write about 'AT&T', you need to write '`AT&T`'. You even need to escape ampersands within URLs. Thus, if you want to link to:

```
    http://images.google.com/images?num=30&q=larry+bird
```

you need to encode the URL as:

```
    http://images.google.com/images?num=30&q=larry+bird
```

in your anchor tag `href` attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into `&`.

So, if you want to include a copyright symbol in your article, you can write:

```
    ©
```

and Markdown will leave it alone. But if you write:

```
    AT&T
```

Markdown will translate it to:

```
    AT&T
```

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

```
    4 < 5
```

Markdown will translate it to:

```
    4 < 5
```

However, inside Markdown code spans and blocks, angle brackets and ampersands are *always* encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single `<` and `&` in your example code needs to be escaped.)

## Block Elements

### Paragraphs and Line Breaks
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line -- a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard-wrapped" Dtext paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type's "Convert Line Breaks" option) which translate every line break character in a paragraph into a `<br />` tag.

When you *do* want to insert a `<br />` break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a `<br />`, but a simplistic "every line break is a `<br />`" rule wouldn't work for Markdown. Markdown's email-style blockquoting

and multi-paragraph list items work best -- and look better -- when you format them with hard breaks.

### Headers
Markdown supports two styles of headers, Setext and atx.

Setext-style headers are ‘underlined’ using equal signs (for first-level headers) and dashes (for second-level headers). For example:

```
    This is an H1
    =============

    This is an H2
    -------------
```

Any number of underlining `=`'s or `-`'s will work.

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

```
    # This is an H1

    ## This is an H2

    ###### This is an H6
```

Optionally, you may "close" atx-style headers. This is purely cosmetic -- you can use this if you think it looks better. The closing hashes don't even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :

```
    # This is an H1 #

    ## This is an H2 ##

    ### This is an H3 ######
```

### Blockquotes
Markdown uses email-style `>` characters for blockquoting. If you're familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a `>` before every line:

```
    > This is a blockquote with two paragraphs. Lorem ipsum
    > dolor sit amet, consectetuer adipiscing elit. Aliquam
    > hendrerit mi posuere lectus. Vestibulum enim wisi,
    > viverra nec, fringilla in, laoreet vitae, risus.
    >
    > Donec sit amet nisl. Aliquam semper ipsum sit amet
    > velit. Suspendisse id sem consectetuer libero luctus
    > adipiscing.
```

Markdown allows you to be lazy and only put the `>` before the first line of a hard-wrapped paragraph:

```
    > This is a blockquote with two paragraphs. Lorem ipsum
    dolor sit amet, consectetuer adipiscing elit. Aliquam
    hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.

    > Donec sit amet nisl. Aliquam semper ipsum sit amet
     velit. Suspendisse id sem consectetuer libero luctus
      adipiscing.
```

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of `>`:

```
    > This is the first level of quoting.
    >
    > > This is nested blockquote.
    >
    > Back to the first level.
```

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

```
	> ## This is a header.
	>
	> 1.   This is the first list item.
	> 2.   This is the second list item.
	>
	> Here's some example code:
	>
	>     return shell_exec("echo $input | $markdown_script");
```

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

### Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens -- interchangably -- as list markers:

```
    *   Red
    *   Green
    *   Blue
```

is equivalent to:

```
    +   Red
    +   Green
    +   Blue
```

and:

```
    -   Red
    -   Green
    -   Blue
```

Ordered lists use numbers followed by periods:

```
    1.  Bird
    2.  McHale
    3.  Parish
```

It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

```
    <ol>
    <li>Bird</li>
    <li>McHale</li>
    <li>Parish</li>
    </ol>
```

If you instead wrote the list in Markdown like this:

```
    1.  Bird
    1.  McHale
    1.  Parish
```

or even:

```
    3. Bird
    1. McHale
    8. Parish
```

you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

```
    *   Lorem ipsum dolor sit amet, consectetuer adipiscing
	elit. Aliquam hendrerit mi posuere lectus. Vestibulum
	enim wisi, viverra nec, fringilla in, laoreet vitae,
	risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet
	velit. Suspendisse id sem consectetuer libero luctus
	adipiscing.
```

But if you want to be lazy, you don't have to:

```
    *   Lorem ipsum dolor sit amet, consectetuer adipiscing
    elit. Aliquam hendrerit mi posuere lectus. Vestibulum
    enim wisi, viverra nec, fringilla in, laoreet vitae,
    risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet
    velit. Suspendisse id sem consectetuer libero luctus
    adipiscing.
```

If list items are separated by blank lines, Markdown will wrap the items in `<p>` tags in the HTML output. For example, this input:

```
    *   Bird
    *   Magic
```

will turn into:

```
    <ul>
    <li>Bird</li>
    <li>Magic</li>
    </ul>
```

But this:

```
    *   Bird

    *   Magic
```

will turn into:

```
    <ul>
    <li><p>Bird</p></li>
    <li><p>Magic</p></li>
    </ul>
```

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be intended by either 4 spaces or one tab:

```
    1.  This is a list item with two paragraphs. Lorem ipsum
	dolor sit amet, consectetuer adipiscing elit. Aliquam
	hendrerit mi posuere lectus.

        Vestibulum enim wisi, viverra nec, fringilla in,
	laoreet vitae, risus. Donec sit amet nisl. Aliquam
	semper ipsum sit amet velit.

    2.  Suspendisse id sem consectetuer libero luctus
	adipiscing.
```

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

```
    *   This is a list item with two paragraphs.

        This is the second paragraph in the list item.
	You're only required to indent the first line. Lorem
	ipsum dolor sit amet, consectetuer adipiscing elit.

    *   Another item in the same list.
```

To put a blockquote within a list item, the blockquote's `>` delimiters need to be indented:

```
    *   A list item with a blockquote:

        > This is a blockquote
        > inside a list item.
```

To put a code block within a list item, the code block needs to be indented *twice* -- 8 spaces or two tabs:

```
    *   A list item with a code block:

            <code goes here>
```

It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:

```
    1986. What a great season.
```

In other words, a *number-period-space* sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

```
    1986\. What a great season.
```

### Code Blocks
Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both `<pre>` and `<code>` tags.

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

```
    This is a normal paragraph:

        This is a code block.
```

Markdown will generate:

```
    <p>This is a normal paragraph:</p>

    <pre><code>This is a code block.
    </code></pre>
```

One level of indentation -- 4 spaces or 1 tab -- is removed from each line of the code block. For example, this:

```
    Here is an example of AppleScript:

        tell application "Foo"
            beep
        end tell
```

will turn into:

```
    <p>Here is an example of AppleScript:</p>

    <pre><code>tell application "Foo"
        beep
    end tell
    </code></pre>
```

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown -- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:

```
        <div class="footer">
            © 2004 Foo Corporation
        </div>
```

will turn into:

```
    <pre><code><div class="footer">
        &copy; 2004 Foo Corporation
    </div>
    </code></pre>
```

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it's also easy to use Markdown to write about Markdown's own syntax.

### Horizontal Rules
You can produce a horizontal rule tag (`<hr />`) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

```
    * * *

    ***

    *****

    - - -

    ---------------------------------------
```

## Span Elements

### Links
Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an *optional* title for the link, surrounded in quotes. For example:

```
    This is [an example](http://example.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.
```

Will produce:

```
    <p>This is <a href="http://example.com/" title="Title">
    an example</a> inline link.</p>

    <p><a href="http://example.net/">This link</a> has no
    title attribute.</p>
```

If you're referring to a local resource on the same server, you can use relative paths:

```
    See my [About](/about/) page for details.
```

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

```
    This is [an example][id] reference-style link.
```

You can optionally use a space to separate the sets of brackets:

```
    This is [an example] [id] reference-style link.
```

Then, anywhere in the document, you define your link label like this, on a line by itself:

```
    [id]: http://example.com/  "Optional Title Here"
```

That is:

- Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);

- followed by a colon;

- followed by one or more spaces (or tabs);

- followed by the URL for the link;

- optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

```
	[foo]: http://example.com/  "Optional Title Here"
	[foo]: http://example.com/  'Optional Title Here'
	[foo]: http://example.com/  (Optional Title Here)
```

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

```
    [id]: <http://example.com/>  "Optional Title Here"
```

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

```
    [id]: http://example.com/longish/path/to/resource/here
        "Optional Title Here"
```

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are not case sensitive. E.g. these two links:

```
	[link text][a]
	[link text][A]
```

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets -- e.g., to link the word "Google" to the google.com web site, you could simply write:

```
	[Google][]
```

And then define the link:

```
	[Google]: http://google.com/
```

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

```
	Visit [Daring Fireball][] for more information.
```

And then define the link:

```
	[Daring Fireball]: http://daringfireball.net/
```

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they're used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here's an example of reference links in action:

```
    I get 10 times more traffic from [Google] [1] than from
    [Yahoo] [2] or [MSN] [3].

      [1]: http://google.com/        "Google"
      [2]: http://search.yahoo.com/  "Yahoo Search"
      [3]: http://search.msn.com/    "MSN Search"
```

Using the implicit link name shortcut, you could instead write:

```
    I get 10 times more traffic from [Google][] than from
    [Yahoo][] or [MSN][].

      [google]: http://google.com/        "Google"
      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
      [msn]:    http://search.msn.com/    "MSN Search"
```

Both of the above examples will produce the following HTML output:

```
    <p>I get 10 times more traffic from <a href="http://google.com/"
    title="Google">Google</a> than from
    <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    or
    <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
```

For comparison, here is the same paragraph written using Markdown's inline link style:

```
    I get 10 times more traffic from
    [Google](http://google.com/ "Google") than from
    [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
    [MSN](http://search.msn.com/ "MSN Search").
```

The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it's 176 characters; and as raw HTML, it's 234 characters. In the raw HTML, there's more markup than there is text.

With Markdown's reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

### Emphasis
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>` tag. E.g., this input:

```
    *single asterisks*

    _single underscores_

    **double asterisks**

    __double underscores__
```

will produce:

```
    <em>single asterisks</em>

    <em>single underscores</em>

    <strong>double asterisks</strong>

    <strong>double underscores</strong>
```

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

```
    un*fucking*believable
```

But if you surround an `*` or `_` with spaces, it'll be treated as a literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

```
    \*this text is surrounded by literal asterisks\*
```

### Code
To indicate a span of code, wrap it with backtick quotes (`` ` ``). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

```
    Use the `printf()` function.
```

will produce:

```
    <p>Use the <code>printf()</code> function.</p>
```

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

```
    ``There is a literal backtick (`) here.``
```

which will produce this:

```
    <p><code>There is a literal backtick (`) here.</code></p>
```

The backtick delimiters surrounding a code span may include spaces -- one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

```
	A single backtick in a code span: `` ` ``

	A backtick-delimited string in a code span: `` `foo` ``
```

will produce:

```
	<p>A single backtick in a code span: <code>`</code></p>

	<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
```

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

```
    Please don't use any `<blink>` tags.
```

into:

```
    <p>Please don't use any <code><blink></code> tags.</p>
```

You can write this:

```
    `—` is the decimal-encoded equivalent of `—`.
```

to produce:

```
    <p><code>&#8212;</code> is the decimal-encoded
    equivalent of <code>&mdash;</code>.</p>
```

### Images
Admittedly, it's fairly difficult to devise a "natural" syntax for placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

```
    Alt text

    Alt text
```

That is:

- An exclamation mark: `!`;

- followed by a set of square brackets, containing the `alt` attribute text for the image;

- followed by a set of parentheses, containing the URL or path to the image, an optional `size` attribute (in width c height format) prefixed with a `=`, and an optional `title` attribute enclosed in double or single quotes.

Reference-style image syntax looks like this:

```
    ![Alt text][id]
```

Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references:

```
    [id]: url/to/image  =Optional size "Optional title attribute"
```

## Miscellaneous

### Automatic Links
Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to

show the actual text of a URL or email address, and also have it be

a clickable link, you can do this:

```
    <http://example.com/>
```

Markdown will turn this into:

```
    <a href="http://example.com/">http://example.com/</a>
```

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

```
    <address@example.com>
```

into something like this:

```
    <a href="mailto:addre
    ss@example.co
    m">address@exa
    mple.com</a>
```

which will render in a browser as a clickable link to "address@example.com".

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won't fool all of them. It's better than nothing, but an address published in this way will probably eventually start receiving spam.)

### Backslash Escapes
Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML `<em>` tag), you add backslashes before the asterisks, like this:

```
    \*literal asterisks\*
```

Markdown provides backslash escapes for the following characters:

backslash

`

backtick

*

asterisk

_

underscore

curly braces

[]

square brackets

()

parentheses

\#

hash mark

+

plus sign

-

minus sign (hyphen)

.

dot

exclamation mark

## BUGS
Markdown assumes that tabs are set to 4 spaces.

## AUTHOR
John Gruber http://daringfireball.net/

## SEE ALSO
markdown(1), markdown(3), mkd-callbacks(3), mkd-functions(3), mkd-extensions(7).

http://daringfireball.net/projects/markdown

http://docutils.sourceforge.net/mirror/setext.html

http://www.aaronsw.com/2002/atx/

http://textism.com/tools/textile/

http://docutils.sourceforge.net/rst.html

http://www.triptico.com/software/grutatxt.html

http://ettext.taint.org/doc/

branch: sisyphus


mkd-extensions

title: mkd-extensions(7)

text:
# mkd-extensions(7)

## NAME
mkd-extensions — Extensions to the Markdown text formatting syntax

## DESCRIPTION
This version of markdown has been extended in a few ways by extending existing markup, creating new markup from scratch, and borrowing markup from other markup languages.

### Image dimensions
Markdown embedded images have been extended to allow specifying the dimensions of the image by adding a new argument =/height/x/width/ to the link description.

The new image syntax is

```
	alt text
```

### pseudo-protocols
Five pseudo-protocols have been added to links

id:

The alt text is marked up and written to the output, wrapped with  and .

class:

The alt text is marked up and written to the output, wrapped with  and .

raw:

The title is written -- with no further processing -- to the output. The alt text is discarded.

abbr:

The alt text is marked up and written to the output, wrapped with  and .

lang:

The alt text s marked up and written to the output, wrapped with  and .

### Pandoc headers
The markdown source document can have a 3-line Pandoc header in the format of

```
    % title
    % author(s)
    % date
```

which will be made available to the mkd_doc_title(), mkd_doc_author(), and mkd_doc_date() functions.

### Definition lists
A definition list item is defined as

```
=tag=
    description
```

(that is a =, followed by text, another =, a newline, 4 spaces of intent, and then more text.)

Alternatively, definition list items are defined as

```
tag
: description
```

(This is the format that PHP Markdown Extra uses.)

### embedded stylesheets
Stylesheets may be defined and modified in a  at the end of the line or a </style> at the beginning of a subsequent line.

Be warned that style blocks work like footnote links -- no matter where you define them they are valid for the entire document.

### alpha lists
Alphabetic lists (like regular numeric lists, but with alphabetic items) are supported. So:

```
    a. this
    b. is
    c. an alphabetic
    d. list
```

will produce:

```
    <ol type=a>
    <li>this</li>
    <li>is</li>
    <li>an alphabetic</li>
    <li>list</li>
    </ol>
```

### tables
PHP Markdown Extra tables are supported; input of the form

```
    header|header
    ------|------
     text | text
```

will produce:

```
    <table>
    <thead>
    <tr>
    <th>header</th>
    <th>header</th>
    </tr>
    </thead>
    <tbody>
    <tr>
    <td>text</td>
    <td>text</td>
    </tr>
    </tbody>
    </table>
```

The dashed line can also contain : characters for formatting; if a : is at the start of a column, it tells discount to align the cell contents to the left; if it's at the end, it aligns right, and if there's one at the start and at the end, it centers.

### strikethrough
A strikethrough syntax is supported in much the same way that ` is used to define a section of code. If you enclose text with two or more tildes, such as ~~erased text~~ it will be written as erased text. Like code sections, you may use as many ~ as you want, but there must be as many starting tildes as closing tildes.

### markdown extra-style footnotes
PHP Markdown Extra footnotes are supported. If a footnote link begins with a ^, the first use of that footnote will generate a link down to the bottom of the rendered document, which will contain a numbered footnote with a link back to where the footnote was called.

## AUTHOR
David Parsons http://www.pell.portland.or.us/~orc/

## SEE ALSO
markdown(1), markdown(3), mkd-callbacks(3), mkd-functions(3), mkd-line(3).

http://daringfireball.net/projects/markdown

http://michelf.com/projects/php-markdown


dnf.modularity

package: dnf

title: dnf.modularity(7)

summary: Modularity in DNF

text:
# dnf.modularity(7)

## NAME
dnf.modularity - Modularity in DNF

Modularity is new way of building, organizing and delivering packages. For more details see: <https://docs.pagure.org/modularity/>

## DEFINITIONS
modulemd

Every repository can contain modules metadata with modulemd documents. These documents hold metadata about modules such as Name, Stream or list of packages.

(non-modular) package

Package that doesn't belong to a module.

modular package

Package that belongs to a module. It is listed in modulemd under the artifacts section. Modular packages can be also identified by having %{modularitylabel} RPM header set.

(module) stream

Stream is a collection of packages, a virtual repository. It is identified with Name and Stream from modulemd separated with colon, for example "postgresql:9.6". Module streams can be active or inactive. active means the RPM packages from this stream are included in the set of available packages. Packages from inactive streams are filtered out. Streams are active either if marked as default or if they are explicitly enabled by a user action. Streams that satisfy dependencies of default or enabled streams are also considered active. Only one stream of a particular module can be active at a given point in time.

## PACKAGE FILTERING
Without modules, packages with the highest version are used by default.

Module streams can distribute packages with lower versions than available in the repositories available to the operating system. To make such packages available for installs and upgrades, the non-modular packages are filtered out when their name or provide matches against a modular package name from any enabled, default, or dependent stream. Modular source packages will not cause non-modular binary packages to be filtered out.

### Demodularized rpms
Contains names of RPMs excluded from package filtering for particular module stream. When defined in the latest active module, non-modular RPMs with the same name or provide which were previously filtered out will reappear.

## HOTFIX REPOSITORIES
In special cases, a user wants to cherry-pick individual packages provided outside module streams and make them available on along with packages from the active streams. Under normal circumstances, such packages are filtered out or rejected from getting on the system by Fail-safe mechanisms. To make the system use packages from a repository regardless of their modularity, specify module_hotfixes=true in the .repo file. This protects the repository from package filtering.

Please note the hotfix packages do not override module packages, they only become part of available package set. It's the package Epoch, Version and Release what determines if the package is the latest.

## FAIL-SAFE MECHANISMS

### Repositories with module metadata are unavailable
When a repository with module metadata is unavailable, package filtering must keep working. Non-modular RPMs must remain unavailable and must never get on the system.

This happens when:

- user disables a repository via --disablerepo or uses --repoid

- user removes a .repo file from disk

- repository is not available and has skip_if_unavailable=true

DNF keeps copies of the latest modulemd for every active stream and uses them if there's no modulemd available for the stream. This keeps package filtering working correctly.

The copies are made any time a transaction is resolved and started. That includes RPM transactions as well as any dnf module <enable|disable|reset> operations.

When the fail-safe data is used, dnf show such modules as part of @modulefailsafe repository.

### Orphaned modular packages
All packages that are built as a part of a module have %{modularitylabel} RPM header set. If such package becomes part of RPM transaction and cannot be associated with any available modulemd, DNF prevents from getting it on the system (package is available, but cannot be installed, upgraded, etc.). Packages from Hotfix repositories or Commandline repository are not affected by Fail-safe mechanisms.

## Author
See AUTHORS in DNF source distribution.

## Copyright
2012-2020, Red Hat, Licensed under GPLv2+


jw-backend-spec

package: docbook-utils

title: jw-backend-spec(7)

summary: interface between jw and its backends

text:
# jw-backend-spec(7)

## NAME
backend-spec - interface between jw and its backends

## DESCRIPTION
jw(1) calls backends like backends/html to do the "real" conversion work. The backend gets all necessary data delivered via environment variables ready to use.

This documentation describes those environment variables.

The backend is run in the directory where the output files are to be created. It should return 0 if there weren't any problem, and return a positive value otherwise.

## VARIABLES
SGML_FILE_NAME

The bare name of the source file

SGML_FILE

The full name and path of the source file

SGML_JADE

The name of the parser (usually Jade or OpenJade)

SGML_ARGUMENTS

The full argument-string for Jade or OpenJade

SGML_CATALOG_FILES

The list of catalog files needed by Jade or OpenJade

SGML_STYLESHEET

The style sheet to use

SGML_BASE_DIR

The base directory of the SGML system (default is /usr/share/sgml)

## SEE ALSO
frontend-spec(7)

## AUTHORS
Jochem Huhmann <joh@revier.com>


jw-frontend-spec

title: jw-frontend-spec(7)

summary: interface between jw and its frontends

text:
# jw-frontend-spec(7)

## NAME
frontend-spec - interface between jw and its frontends

## DESCRIPTION
jw(1) calls frontends like frontends/docbook to get the informations specific to a given input format. The frontend knows which information to return from the first command line parameter. It gets all necessary data via environment variables ready to use.

This document describes that command line parameter and those environment variables.

The frontend should return 0 if there weren't any problem, and return a positive value otherwise.

## VARIABLES
$1

The command line parameter, specifying which information to return. It can take the following values:

centralized-catalog

The frontend must return the DTD-specific centralized catalog name. Centralized catalogs normally reside in /etc/sgml and provide the location of all the catalog files useful for handling this input type (the catalog for the DTD, the catalog for the stylesheets, the catalog for the entities, ...)

style-sheet

The frontend must return the filename of the style sheet to be used for this document type and with the chosen backend.

SGML_CATALOGS_DIR

The directory where the centralized catalogs reside. It is normally /etc/sgml.

(This variable is valid only while determining the centralized catalog to use.)

SGML_BASE_DIR

The base directory of the SGML system. It is normally /usr/share/sgml.

(This variable is valid only while determining the style sheet to use.)

SGML_FILE

The name of the file to convert.

(This variable is valid only while determining the centralized catalog to use.)

SGML_TYPE

The type of the backend to use, whether it produces output files to be displayed online or to be printed out. It can take the value html or print.

(This variable is valid only while determining the style sheet to use).

SGML_STYLESHEETS

The desired custom stylesheet type, either none or default. If none, the frontend must return the file name of the style sheet provided by the system beneath the docbook-utils. If default, the frontend must return the custom stylesheet provided by the docbook-utils.

(This variable is valid only while determining the style sheet to use). SGML_XML

The metalanguage of the file to convert, either sgml or xml.

(This variable is valid only while determining the centralized catalog to use).

## SEE ALSO
backend-spec(7)

## AUTHORS
Jochem Huhmann <joh@revier.com>


doveadm-search-query

package: dovecot

title: doveadm-search-query(7)

text:
# doveadm-search-query(7)

## NAME
doveadm-search-query - Overview of search queries for doveadm mailbox commands

## DESCRIPTION
Several doveadm(1) commands use a search_query in order to act only on matching messages. This manual page describes all SEARCH KEYS, which can be used in a search_query. The query is mostly compatible with the IMAP SEARCH command parameters, although there are some differences.

Each search_query consists at least of one SEARCH KEY. Most of the SEARCH KEYS require an argument. All SEARCH KEYS are case-insensitive. The shortest valid search_query is ALL. For example:

```
doveadm search ALL
```

Multiple search query expressions will be combined with the AND operator by default. To find all messages that are new and greater than 50 kilobyte, one can use:

```
doveadm search NEW LARGER 50k
```

OR-ed SEARCH KEYS have to be written in parenthesis, when mixing ANDs and ORs. Shells commonly require escaping for parentheses. To find messages that were saved on the "13th of April 2007" AND have the \Seen and/or \Flagged flag set, one can use for example:

```
doveadm search SAVEDON 2007-04-13 \( SEEN OR FLAGGED \)
```

It's also possible to specify the mailbox, in which should be searched. Use either the keyword mailbox and the name of the mailbox or the keyword mailbox-guid and the mailbox's globally unique identifier in the search_query. To find all messages in the mailbox with the GUID "44f68b13ce97044b837f000035ca9452" use:

```
doveadm search mailbox-guid 44f68b13ce97044b837f000035ca9452 ALL
```

To list all deleted messages in the "Trash" folder use:

```
doveadm search mailbox Trash DELETED
```

## SEARCH KEYS
The following search keys from the specification of IMAP version 4 revision 1 (see: RFC 3501) are supported:

sequence-set

Matches messages with the given sequence numbers. The sequence-set may be a single sequence number. Can be a sequence range, written as from:to, e.g. 100:125. As comma separated list of sequences, e.g. 11,50,4. It's also possible to combine multiple sequences, e.g. 1,3,5,7,10:20. Using * selects the last mail in the mailbox.

For example 1:100 matches the first 100 mails and 101:200 the next second hundred mails. 1,5,* matches the first, the fifth and the last email.

Use UID (see below) to search by unique ID.

ALL

Matches all messages.

ANSWERED

Matches messages with the IMAP flag \Answered set.

BCC string

Matches messages, which contain string in the BCC field of the message's IMAP envelope structure.

BEFORE date specification

Matches messages with an internal date before date specification.

BODY string

Matches messages, which contain string in the body part.

CC string

Matches messages, which contain string in the CC field of the message's IMAP envelope structure.

DELETED

Matches messages with the IMAP flag \Deleted set.

DRAFT

Matches messages with the IMAP flag \Draft set.

FLAGGED

Matches messages with the IMAP flag \Flagged set.

FROM string

Matches messages, which contain string in the FROM field of the message's IMAP envelope structure.

HEADER field string

Matches messages, which either have the named header field, when empty string was given. Or messages, where the given header field's value contains the specified string.

KEYWORD keyword

Matches messages with the given IMAP keyword (e.g. $Forwarded) flag set.

LARGER size

Matches messages that are larger than the specified size.

MAILBOX name

Matches messages in the mailbox with the specified name.

MAILBOX-GUID guid

Matches messages in the mailbox with the specified guid.

NEW

Matches messages, which have the IMAP flag \Recent set but not the IMAP flag \Seen.

NOT search key

Inverse matching - matches massages, where the search doesn't match the specified search key or its value.

OLD

Matches messages, which do not have the IMAP flag \Recent set.

ON date specification

Matches messages whose internal date matches the given date specification.

search key OR search key

Matches messages where one of the OR-ed search keys matches.

Note: IMAP4rev1 uses the syntax: OR search key search key

RECENT

Matches messages with the IMAP flag \Recent set.

SEEN

Matches messages with the IMAP flag \Seen set.

SENTBEFORE date specification

Matches messages with a Date: header before date specification.

SENTON date specification

Matches messages with a Date: header matching the given date specification.

SENTSINCE date specification

Matches messages with a Date: header matching or after the given date specification.

SINCE date specification

Matches messages whose internal date is within or after the given date specification.

SMALLER size

Matches messages with a size smaller than the given size.

SUBJECT string

Matches messages, which contain string in the SUBJECT field of the message's IMAP envelope structure.

TEXT string

Matches messages, which contain string in the message headers or body.

TO string

Matches messages, which contain string in the TO field of the message's IMAP envelope structure.

UID sequence-set

Matches messages with the given IMAP UID(s). See the sequence-set description for details on it. For example 1:10,100:200,* matches the UIDs from 1 to 10, 100 to 200 and also the last mail.

UNANSWERED

Matches messages, which do not have the IMAP flag \Answered set.

UNDELETED

Matches messages, which do not have the IMAP flag \Deleted set.

UNDRAFT

Matches messages, which do not have the IMAP flag \Draft set.

UNFLAGGED

Matches messages, which do not have the IMAP flag \Flagged set.

UNKEYWORD keyword

Matches messages, which do not have the given IMAP keyword flag set

UNSEEN

Matches messages, which do not have the IMAP flag \Seen set.

## DOVEADM SEARCH KEYS
Additional search keys, provided by doveadm(1).

SAVEDBEFORE date specification

Matches messages, which were saved before date specification.

SAVEDON date specification

Matches messages whose save date matches the given date specification.

SAVEDSINCE date specification

Matches messages with a save date matching or after the given date specification.

## DATE SPECIFICATION
doveadm(1) supports a few additional date specification formats. They can be used anywhere, where a date specification value is obligatory.

dd-mon-yyyy

Default IMAP4rev1 date format.

Date components:

day : the day of month: 1-31.

month : the abbreviated month name: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec.

year : four digits of year, e.g. 2007.

For example the "13th of April 2007" will be represented as 13-Apr-2007.

dd-mon-yyyy hh:mm:ss [+-]zzzz

Default IMAP4rev1 date-time format. See dd-mon-yyyy above for the date format.

Time format components:

hh : the hour

mm : the minute

ss : the second

[+-]zzzz : the timezone as hhmm, e.g. +0530, -0700

interval

Combination of a positive integer number and a time unit.

Available time units are:

weeks : abbreviated: w

days : abbreviated: d

hours : abbreviated: h

mins : abbreviated: m

secs : abbreviated: s

To match messages from last week, you may specify for example: since 1w, since 1weeks or since 7days.

Unix timestamp

A 10 digit Unix timestamp, seconds since the 1st of January 1970, 00:00:00 UTC. For example the "13th of April 2007" will be represented as 1176418800.

YYYY-MM-DD

Extended ISO-8601 calendar date format. For example the "13th of April 2007" will be represented as 2007-04-13.

## SIZE
doveadm(1) provides also an additional size representation format. The following formats can be used anywhere, where a size value is obligatory.

octets

The message size in octets, as specified in the IMAP4rev1 specification.

size

The message size in B (byte), k (kilobyte), M (megabyte), G (gigabyte) or T (terabyte). To match messages, bigger than 1 megabyte, you may specify for example: larger 1M or larger 1024k.

## REPORTING BUGS
Report bugs, including doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. Information about reporting bugs is available at: ⟨https://dovecot.org/bugreport.html⟩

## SEE ALSO
doveadm(1)


pigeonhole

package: dovecot-pigeonhole

title: pigeonhole(7)

text:
# pigeonhole(7)

## NAME
pigeonhole - Overview of the Pigeonhole Sieve support for Dovecot

## DESCRIPTION
Pigeonhole adds support for the Sieve language (RFC 5228) and the ManageSieve protocol (RFC 5804) to Dovecot (dovecot(1)).

In the literal sense, a pigeonhole is a a hole or recess inside a dovecot for pigeons to nest in. It is, however, also the name for one of a series of small, open compartments in a cabinet used for filing or sorting mail. As a verb, it describes the act of putting an item into one of those pigeonholes. The name "Pigeonhole" therefore well describes an important part of the functionality that it adds to Dovecot: sorting and filing e-mail messages.

The Sieve language is used to specify how e-mail needs to be processed. By writing Sieve scripts, users can customize how messages are delivered, e.g. whether they are forwarded or stored in special folders. Unwanted messages can be discarded or rejected, and, when the user is not available, the Sieve interpreter can send an automated reply. Above all, the Sieve language is meant to be simple, extensible and system independent. And, unlike most other mail filtering script languages, it does not allow users to execute arbitrary programs. This is particularly useful to prevent virtual users from having full access to the mail store. The intention of the language is to make it impossible for users to do anything more complex (and dangerous) than write simple mail filters.

Using the ManageSieve protocol, users can upload their Sieve scripts remotely, without needing direct filesystem access through FTP or SCP. Additionally, a ManageSieve server always makes sure that uploaded scripts are valid, preventing compile failures at mail delivery.

Pigeonhole provides the following items:

- The LDA Sieve plugin for Dovecot's Local Delivery Agent (LDA) (dovecot-lda(1)) that facilitates the actual Sieve filtering upon delivery.

- The ManageSieve service that implements the ManageSieve protocol through which users can remotely manage Sieve scripts on the server.

- A plugin for Dovecot's doveadm(1) command line tool that adds new doveadm-sieve(1) commands for management of Sieve filtering.

- The imap-sieve plugin documentation plugin, which provides the ability to attach Sieve scripts that are run for IMAP events in their mailboxes.

- The imap-filter-sieve plugin documentation that allows refiltering mails in a mailbox using Sieve scripts.

The functionality and configuration of the LDA Sieve plugin and the ManageSieve service is described in detail in the README and INSTALL files contained in the Pigeonhole package and in sieve.

The following command line tools are available outside of doveadm:

sievec(1)

Compiles Sieve scripts into a binary representation for later execution.

sieve-test(1)

The universal Sieve test tool for testing the effect of a Sieve script on a particular message.

sieve-filter(1)

Filters all messages in a particular source mailbox through a Sieve script.

sieve-dump(1)

Dumps the content of a Sieve binary file for (development) debugging purposes.

## REPORTING BUGS
Report bugs, including doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. Information about reporting bugs is available at: ⟨https://dovecot.org/bugreport.html⟩

## SEE ALSO
dovecot(1), dovecot-lda(1), doveadm(1), doveadm-sieve(1), sieve-dump(1), sieve-test(1), sieve-filter(1), sievec(1)

Additional resources:

•

sieve


deb-version

package: dpkg

title: deb-version(7)

summary: Debian package version number format

text:
# deb-version(7)

## NAME
deb-version - Debian package version number format

## SYNOPSIS
[epoch:]upstream-version[-debian-revision]

## DESCRIPTION
Version numbers as used for Debian binary and source packages consist of three components. These are:

epoch

This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. If it is omitted then the upstream-version may not contain any colons. It is provided to allow mistakes in the version numbers of older versions of a package, and also a package's previous version numbering schemes, to be left behind.

upstream-version

This is the main part of the version number. It is usually the version number of the original (“upstream”) package from which the .deb file has been made, if this is applicable. Usually this will be in the same format as that specified by the upstream author(s); however, it may need to be reformatted to fit into the package management system's format and comparison scheme. The comparison behavior of the package management system with respect to the upstream-version is described below. The upstream-version portion of the version number is mandatory.

The upstream-version may contain only alphanumerics (“A-Za-z0-9”) and the characters . + - : ~ (full stop, plus, hyphen, colon, tilde) and should start with a digit. If there is no debian-revision then hyphens are not allowed; if there is no epoch then colons are not allowed.

debian-revision

This part of the version number specifies the version of the Debian package based on the upstream version. It may contain only alphanumerics and the characters + . ~ (plus, full stop, tilde) and is compared in the same way as the upstream-version is. It is optional; if it isn't present then the upstream-version may not contain a hyphen. This format represents the case where a piece of software was written specifically to be turned into a Debian package, and so there is only one “debianization” of it and therefore no revision indication is required.

It is conventional to restart the debian-revision at ‘1’ each time the upstream-version is increased.

Dpkg will break the version number apart at the last hyphen in the string (if there is one) to determine the upstream-version and debian-revision. The absence of a debian-revision compares earlier than the presence of one (but note that the debian-revision is the least significant part of the version number).

### Sorting algorithm
The upstream-version and debian-revision parts are compared by the package management system using the same algorithm:

The strings are compared from left to right.

First the initial part of each string consisting entirely of non-digit characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters and so that a tilde sorts before anything, even the end of a part. For example, the following parts are in sorted order: ‘~~’, ‘~~a’, ‘~’, the empty part, ‘a’.

Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero.

These two steps (comparing and removing initial non-digit strings and initial digit strings) are repeated until a difference is found or both strings are exhausted.

Note that the purpose of epochs is to allow us to leave behind mistakes in version numbering, and to cope with situations where the version numbering scheme changes. It is not intended to cope with version numbers containing strings of letters which the package management system cannot interpret (such as ‘ALPHA’ or ‘pre-’), or with silly orderings.

## NOTES
The tilde character and its special sorting properties were introduced in dpkg 1.10 and some parts of the dpkg build scripts only gained support for it later in the 1.10.x series.

## SEE ALSO
deb-control(5), deb(5), dpkg(1)


dpkg-build-api

title: dpkg-build-api(7)

summary: source package dpkg build API level

text:
# dpkg-build-api(7)

## NAME
dpkg-build-api - source package dpkg build API level

## SYNOPSIS

```
 Build-Depends:
  dpkg-build-api (= 1),
```

## DESCRIPTION
The source package dpkg build API level, defines a versioned interface for source packages, where each API level provides specific behaviors and guarantees.

These interfaces can then be adopted by packages in a gradual way, and phased out more easily than with global behavior changes.

The declaration of this API level is done through build-dependencies, in one of Build-Depends, Build-Depends-Indep or Build-Depends-Arch, or via the environment variable DPKG_BUILD_API, which will override these if both are present, and might emit a warning in case they are different.

## API LEVELS
v2

This level is still under development, and cannot be declared via build-dependencies.

v1

This is the recommended level. Since dpkg 1.22.0. Changes from v0 are:

- dpkg-shlibdeps no longer uses the LD_LIBRARY_PATH environment variable. The -l option should be used instead.

- dpkg-buildpackage defaults to Rules-Requires-Root value no. To restore the v0 behavior (from before dpkg 1.22.13) Rules-Requires-Root should be set to binary-targets.

- dpkg-buildpackage expects all required debian/rules targets to be supported and no longer has backwards compatibility fallback code. The required targets are clean, build, build-indep, build-arch, binary-indep and binary-arch.

- vendor.mk defaults to using dpkg_vendor_derives_from_v1 for the dpkg_vendor_derives_from macro. To restore the v0 behavior set dpkg_vendor_derives_from to dpkg_vendor_derives_from_v0.

- default.mk defaults to including buildtools.mk.

v0

This is the current global level, equivalent to not specifying one. The interfaces and behaviors provided are subject to the normal global interface updates, which tend to require longer deprecation cycles and/or coordinated transitions.

## SEE ALSO
deb-src-control(5).


libdpkg

title: libdpkg(7)

summary: Debian package manager C library

text:
# libdpkg(7)

## NAME
libdpkg - Debian package manager C library

## DESCRIPTION
The libdpkg C library provides functions and infrastructure for the dpkg tool set, and external projects that need to integrate tightly with it.

The library provides a pkgconf(1) entry named libdpkg.

Warning: The API provided by this library is highly volatile, still in the process of being cleaned up. It is only supposed to be used internally by dpkg for now. Header files, functions, variables and types might get renamed, removed or change semantics. If you still have a need to use it, which you would be doing anyway, say by locally building dpkg to get the library, then define the C preprocessor macro LIBDPKG_VOLATILE_API in your build to acknowledge that fact.

Due to the currently API volatility, only a static library is provided.

## SEE ALSO
/usr/share/doc/dpkg/README.api, <https://www.dpkg.org/doc/libdpkg/>.