dh_installdocs - instala documentação em directórios de
compilação de pacotes
dh_installdocs [
debhelper opções] [
-A]
[
-Xitem] [
ficheiro ...]
dh_installdocs é um programa debhelper que é
responsável por instalar documentação em
usr/share/doc/package nos directórios de
compilação de pacotes.
Em compatibilidade 10 e anterior,
dh_install(1) pode ser a melhor
ferramenta para lidar com a documentação do autor, quando o
sistema de compilação próprio do autor instala toda a
documentação desejada correctamente Neste caso, o
dh_installdocs ainda é útil para instalar
documentação relacionada com o empacotamento (ex. o ficheiro
debian/copyright).
Desde nível de compatibilidade 11 do debhelper em diante, o
dh_install irá procurar os ficheiros em
debian/tmp, se
não os encontrar no directório actual (ou onde você o
mandou procurar usando
--sourcedir).
Em compatibilidade 11 e posterior,
dh_installdocs oferece muitas das
características que o
dh_install(1) também tem. Mais
ainda, o
dh_installdocs também suporta o perfil de
compilação
nodoc para excluir documentação
(independentemente do nível de compatibilidade).
- debian/pacote.docs
- Lista os ficheiros de documentação a serem
instalados em pacote.
Suporta variáveis de substituição em compatibilidade 13
e posterior como documentado em debhelper(7).
- debian/copyright
- O ficheiro de copyright é instalado em todos os
pacotes, a menos que esteja disponível um ficheiro de copyright
mais específico.
- debian/pacote.copyright
- debian/pacote.README.Debian
- debian/pacote.TODO
- Cada um destes ficheiros são instalados
automaticamente se presentes para um pacote.
- debian/README.Debian
- debian/TODO
- Estes ficheiros são instalados no primeiro pacote
binário listado em debian/control.
Note que os ficheiros README.debian são também
instalados como README.Debian, e os ficheiro TODO
serão instalados como TODO.Debian em pacotes não
nativos.
- debian/pacote.doc-base
- instalado como ficheiros de controle doc-base. Note que o
doc-id será determinado a partir da entrada Document: no
ficheiro de controle de doc-base em questão. Na eventualidade de
múltiplos ficheiros doc-base num pacote fonte partilharem o mesmo
doc-id, eles serão instalados em usr/share/doc-base/package em vez
de usr/share/doc-base/doc-id.
- debian/pacote.doc-base.*
- Se o seu pacote precisa de registar mais do que um
documento, você precisa de vários ficheiros baseados em doc,
e pode-os nomear desta maneira. Na eventualidade de vários
ficheiros baseados em doc deste estilo num único pacote fonte
partilharem o mesmo doc-id, serão instalados em
usr/share/doc-base/package-* em vez de usr/share/doc-base/doc-id.
Por favor tenha atenção que esta de-duplicação
é actualmente feita apenas em memória, assim por agora
requer o dh_installdocs seja chamado não mais do que uma vez
durante a compilação do pacote. Chamar dh_installdocs
-p package em combinação com o uso de ficheiros
debian/package.doc-base.* pode levar a pacotes
não instaláveis. Veja <https://bugs.debian.org/980903>
para detalhes.
-
-A, --all
- Instala todos os ficheiros especificados pelos
parâmetros de linha de comandos em TODOS os pacotes em que
actua.
-
-Xitem, --exclude=item
- Exclui da instalação ficheiros que contenham
item em qualquer ponto do seu nome de ficheiro. Note que isto
inclui ficheiros baseados em doc.
-
--sourcedir=directório
- Procura no directório especificado por ficheiros
para serem instalados. Esta opção requer compatibilidade 11
ou posterior (é ignorada em silêncio na compatibilidade 10
ou anterior).
Note que isto não é o mesmo que a opção
--sourcedirectory usada pelos comandos dh_auto_*.
Você raramente vai precisar de usar esta opção, pois
o dh_installman procura automaticamente por ficheiros em
debian/tmp no nível de compatibilidade 11 e superiores do
debhelper.
-
--doc-main-package=main-package
- Define o pacote principal para pacote de
documentação. Isto é usado para a
documentação do pacote de documentação em
/usr/share/doc/ main-package como recomendado pelo
manual de políticas Debian 3.9.7 em §12.3.
Em compatibilidade 11 (ou posterior), esta opção apenas
é útil se a auto-detecção do debhelper do
pacote principal está errada. A opção também
pode ser usada para silenciar um aviso do debhelper quando a
auto-detecção falha mas acontece a
predefinição estar correcta.
Esta opção não pode ser usada quando o
dh_installdocs é instruído a actuar em
múltiplos pacotes. Se precisar desta opção,
você irá geralmente precisar de combiná-la com
-p para assegurar exactamente que um pacote é actuado.
Por favor tenha em mente que alguma documentação (o ficheiro
de copyright, README.Debian, etc.) não serão afectados por
esta opção.
-
--link-doc=pacote
- Faz com que o directório de
documentação de todos os pacotes onde actua seja um link
simbólico para o directório de documentação do
pacote. Isto não tem nenhum efeito quando se actual no
próprio pacote, ou se o directório de
documentação a ser criado já existir quando o
dh_installdocs é executado. Para estar em conformidade com a
política, o pacote tem de ser um pacote binário que
vem do mesmo pacote fonte.
O debhelper irá tentar evitar instalar ficheiros em
directórios de documentação vinculados que
poderão causar conflitos com o pacote vinculado. A
opção -A não terá nenhum efeito em
pacotes com directórios de documentação vinculados, e
os ficheiros copyright, changelog, README.Debian, e
TODO não serão instalados.
(Um outro método de consegui o mesmo, o qual ainda é
suportado, é tornar o directório de
documentação de um pacote num link simbólico
pendente, antes de chamar o dh_installdocs.)
Por favor note que esta opção apenas é aplicada ao
directório de documentação para o próprio
pacote. Quando o pacote embarca documentação para outro
pacote (ex. veja --doc-main-package), não irá usar um
link simbólico para a documentação do outro pacote.
CAVEAT 1: Se uma versão anterior do pacote foi compilada sem
esta opção e for agora compilada com ela (ou vice-versa),
precisa de uma migração de dir para symlink" (ou de
"symlink para dir"). Como o debhelper não tem
conhecimento das versões anteriores, você terá que
ser o próprio a activar esta migração.
Isto pode ser feito ao fornecer um ficheiro "debian/
pacote.maintscript" e usar o dh_installdeb(1) para
fornecer os fragmentos relevantes do script do maintainer.
CAVEAT 2: O uso de --link-doc apenas deve ser feito quando os
pacotes têm o mesmo tipo de "arquitectura". Um link de um
pacote independente de uma arquitectura para um pacote depende de uma
arquitectura (ou vice-versa) não irá funcionar. Desde
compatibilidade 10, o debhelper irá rejeitar activamente
combinações não suportadas.
-
ficheiro ...
- Instala estes ficheiros como documentação no
primeiro pacote em que se actua. (Ou em todos os pacotes se for
especificado -A).
Este é um exemplo de um ficheiro
debian/package.docs:
README
TODO
debian/notes-for-maintainers.txt
docs/manual.txt
docs/manual.pdf
docs/manual-html/
Note que
dh_installdocs irá alegremente copiar as hierarquias
completas dos directórios se você lhe pedir (semelhante a
cp
-a). Se lhe for pedido para instalar um directório, irá
instalar o conteúdo completo desse directório.
debhelper(7)
Este programa é parte do debhelper.
Joey Hess <
[email protected]>
Américo Monteiro
Se encontrar algum erro na tradução deste documento, por favor
comunique para Américo Monteiro
[email protected] ou Equipa
Debian de Tradução Portuguesa
[email protected].