PO4A-BUILD.CONF(5)

NOME
po4a-build.conf - arquivo de configuração para compilação de conteúdo traduzido

Introdução
po4a-build.conf descreve como "po4a-build" deveria compilar a documentação traduzida e não traduzida de um conjunto de documentos fontes não traduzidos e arquivos PO correspondentes.

Todo suporte a formatos, em todo suporte a combinações, podem ser manipulados em um único arquivo de configuração po4a-build.conf e uma única chamada a "po4a-build". Porém, você também pode escolher separar os diretórios de po/ e ter um arquivo de configuração para cada execução. (Chamar "po4a-build -f ARQUIVO" para cada um.)

Note que apesar de po4a-build permitir adição de suporte gettext para tradução mensagens de saída de script, o próprio po4a-build.conf não comporta tais traduções. po4a-build.conf somente se relaciona a conteúdo estático de tradução, como páginas de manual.

Para suporte do po4a-build a mensagens de tradução em tempo de execução, veja po4a-runtime(7).

Formatos suportados
Atualmente, "po4a-build" tem suporte às seguintes combinações:

DocBook XML para seções 1 e 3
    Typically used for manpages for shell scripts or other interpreters that do not have their own documentation format like POD. Suitable XML can be generated directly from an existing manpage using "doclifter"(1) and "po4a-build" will then generate a POT file with no extra workload. The POT file can then be offered for translation and the PO files added to the relevant po/ directory. "po4a-build" will then prepare not only the untranslated manpage from the "doclifter" XML but also use "po4a" to prepare translated XML from the PO files and then build translated manpages from the XML.

    Páginas de manual são geradas usando suporte a docbook-xsl - a folha de estilo usada pode ser alterada usando a definição de "XSLFILE" no arquivo de configuração do "po4a-build".

DocBook XML para HTML
    A folha de estilo padrão para preparar o HTML final pode ser alterada usando a definição de "HTMLXSL" no arquivo de configuração "po4a-build".

POD para seções 1, 3, 5 e 7
    pod2man é usado para converter o conteúdo de POD para cada uma das seções que se tem suporte.

    Use "PODFILE" para seção 1, "PODMODULES" para seção 3, "POD5FILES" para seção 5 e "POD7FILES" para seção 7.

    Para conteúdo nas seções 5 ou 7 (as quais tendem a precisar de um nome de arquivo que também é usado para o conteúdo da seção 1), se o nome de arquivo incluir a 5 ou 7 como parte do nome do arquivo, isso (e qualquer extensão do nome do arquivo) será automaticamente retirado.

    ex.: para preparar /usr/share/man/man7/po4a.7.gz:

     # arquivos POD para seção 7
     POD7FILES="doc/po4a.7.pod"

Conteúdos de arquivo
Valores de configuração podem aparecer em qualquer ordem no arquivo de configuração.

Qualquer conteúdo depois de uma "#" é ignorado.

Qualquer valor que iria sempre ser vazio pode ser removido do arquivo.

Alguns campos de configuração são necessários - po4a-build poderia acabar com nada para fazer, se os campos necessários estivessem vazios.

CONFIG
    Necessário.

    Nome e localização do arquivo de configuração (temporário) do "po4a" que "po4a-build" vai gerar e manter. Esse arquivo não precisa ficar no seu sistema de controle de versão e pode ser com segurança removido durante a compilação do pacote.

     # nome e localização do arquivo de configuração
     CONFIG="_build/po4a.config"

PODIR
    Necessário.

    Diretório contendo os arquivos PO para TODAS as traduções manipuladas por este arquivo de configuração. Todas as strings serão mescladas em um arquivo POT neste diretório e todos os arquivos PO mesclados com este arquivo POT. Qualquer limite em KEEP (veja abaixo) será aplicado em todas as strings de arquivo de entrada especificados neste arquivo e todos arquivos PO neste diretório. O diretório não precisa ser chamado de "po". Por favor, repare, porém, que algumas ferramentas de estatísticas esperam que ele seja chamado de "po" e, portanto, é recomendado deixar este nome.

     # diretório po para páginas de manual/documentações
     PODIR="po/pod"

POTFILE
    Necessário.

    Caminho para o arquivo POT (relativo à localização deste arquivo de configuração) que vai ser gerado, mantido e atualizado por "po4a-build" para essas traduções.

     # caminho para o arquivo POT
     POTFILE="po/pod/po4a-pod.pot"

BASEDIR
    Necessário.

    Diretório base para escrever o conteúdo traduzido.

     # diretório base para arquivos gerados, ex.: doc
     BASEDIR="_build"

BINARIES
    Necessário.

    Mesmo se apenas um pacote for compilado, pelo menos um valor é necessário aqui.

    A própria string é arbitrária, mas normalmente consiste no nome do pacote. O conteúdo gerado vai, então, aparecer em subdiretórios de BASEDIR/BINARIES:

     _build/po4a/man/man1/foo.1

    Se o pacote compila mais do que um pacote binário (isto é, um pacote fonte e múltiplos arquivos .deb ou .rpm), este campo pode ajudar a isolar o conteúdo pretendido, tornando mais fácil automatizar o processo de compilação.

    Separe as strings com um espaço.

     # pacotes binários que vão conter as páginas de manual geradas
     BINARIES="po4a"

KEEP
    Valor a ser passado diretamente para "po4a -k" para especificar o limite para o conteúdo corretamente traduzido antes de uma tradução em particular é omitido da compilação. Deixe vazio ou remova para usar o padrão (80%) ou especifique zero para forçar a inclusão de todo o conteúdo, mesmo se completamente não traduzido.

    Para controle total sobre este comportamento, considere com cuidado quais arquivos estão atribuídos para qual arquivo de configuração po4a-build.conf.

    Note que ter muitos arquivos em um POT pode ser mais conveniente para tradutores, especificamente se os arquivos possuem strings em comum. Por outro lado, arquivos POT com milhares de strings longas são assustadores para tradutores, resultando em congelamentos de strings mais longos.

     # limite mínimo de porcentagem de tradução para se manter
     KEEP=

XMLMAN1
    Arquivos DocBook XML para gera páginas de manual na seção 1. Separe nomes de arquivos com espaços. Todos os arquivos precisam estar no diretório XMLDIR.

    É uma prática comum juntar vários arquivos XML em um livro, para fornecer uma tabela de conteúdos etc. Se o livro contém arquivos também especificados em XMLMAN3, apenas especifique os arquivos XML para seção 1 aqui, e não o livro propriamente dito. Se o livro contém apenas o conteúdo para esta seção, especifique apenas o arquivo do livro.

     # arquivos DocBook XML para seção 1
     XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"

XMLMAN3
    Arquivos DocBook XML para gerar páginas de manual na seção 3. Separe nomes de arquivos com espaços. Todos arquivos precisam estar no diretório XMLDIR.

    É uma prática comum juntar vários arquivos XML em um livro, para fornecer uma tabela de conteúdos etc. Se o livro contém arquivos também especificados em XMLMAN1, apenas especifique os arquivos XML para seção 3 aqui, e não o livro propriamente dito. Se o livro contém apenas o conteúdo para esta seção, especifique apenas o arquivo do livro.

     # Arquivos DocBook XML para seção 3
     XMLMAN3=""

XMLDIR
    Localização de todos os arquivos DocBook XML. Atualmente, "po4a-build" espera ser capaz de localizar todos os arquivos listados em XMLMAN1 e XMLMAN3 ao procurar por arquivos *.xml neste diretório.

    Deve ser especificado, se XMLMAN1 ou XMLMAN3 forem usados. Caminhos são relativos à localização do arquivo de configuração.

     # localização dos arquivos XML
     XMLDIR="share/doc/"

XMLPACKAGES
    Quais pacotes, fora da lista de BINARIES, usam o conteúdo fonte do XML.

    Se quaisquer valores forem passados em XMLMAN1 ou XMLMAN3, um valor deve ser passado aqui também.

     # pacotes binários usando DocBook XML & xsltproc
     XMLPACKAGES="po4a"

DOCBOOKDIR
    Similar a XMLDIR, mas usado apenas para preparar os arquivos DocBook traduzidos. Se seu pacote quer usar arquivos .sgml, por favor discuta como eles deveriam ser compilados na lista de discussão po4a-devel.

     # padrão para localizar os arquivos .docbook
     DOCBOOKDIR=""

XSLFILE
    Folha de estilo XSL usado para preparar o conteúdo traduzido e não traduzido dos arquivos DocBook XML.

     # arquivo XSL a ser usado para DocBook XML
     XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

PODFILE
    Arquivos POD para gerar conteúdo de página de manual files na seção 1. Separe arquivos POD com espaços. Caminhos, se usados, precisam ser relativos à localização do arquivo de configuração especificado.

     # arquivos POD para seção 1
     PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"

PODMODULES
    Suporte especializado para módulos Perl contendo conteúdo POD - o nome do módulo vai ser reconstruído a partir do caminho (então, ele deveria ser um layout Perl comum) e páginas de manual são colocadas automaticamente na seção 3.

     # arquivos POD para seção 3 - nomes de módulo gerados novamente a partir do caminho
     PODMODULES="lib/Locale/Po4a/*.pm"

POD5FILES
    Conteúdo POD arbitrário para usar ao gerar páginas de manual para seção 5. Caminhos, se usados, precisam ser relativos à localização do arquivo de configuração especificado.

    Para conteúdo nas seções 5 ou 7 (as quais tendem a precisar de um nome de arquivo que também é usado para o conteúdo da seção 1), se o nome de arquivo incluir a 5 ou 7 como parte do nome do arquivo, isso (e qualquer extensão do nome do arquivo) será automaticamente retirado.

     # arquivos POD para seção 5
     POD5FILES="doc/po4a-build.conf.5.pod"

POD7FILES
    Conteúdo POD arbitrário para usar ao gerar páginas de manual para seção 7. Caminhos, se usados, precisam ser relativos à localização do arquivo de configuração especificado.

    Para conteúdo nas seções 5 ou 7 (as quais tendem a precisar de um nome de arquivo que também é usado para o conteúdo da seção 1), se o nome de arquivo incluir a 5 ou 7 como parte do nome do arquivo, isso (e qualquer extensão do nome do arquivo) será automaticamente retirado.

     # arquivos POD para seção 7
     POD7FILES="doc/po4a.7.pod"

PODPACKAGES
    Similar a XMLPACKAGES - qualquer pacote esperando conteúdo ser compilado de arquivos POD precisa incluir um valor em PODPACKAGES. Necessário se quaisquer valores forem especificados para PODFILE, PODMODULES, POD5FILES ou POD7FILES.

     # pacotes binários usando POD
     PODPACKAGES="po4a"

HTMLDIR
    Subdiretório de BASEDIR a ser usado para enviar a saída em HTML traduzido ou não traduzido.

     # saída HTML (subdiretório de BASEDIR)
     HTMLDIR=""

HTMLFILE
    Arquivo DocBook a ser convertido em HTML (pode ser o mesmo que um dos arquivos em XMLMAN1 ou XMLMAN3). Seções não são relevantes para saída HTML. Então, sinta-se à vontade para usar o arquivo único de livro de forma que o HTML tenha tabela de conteúdos etc.

     # arquivo DocBook HTML
     HTMLFILE=""

HTMLXSL
    O padrão é usar uma folha de estilo XSL fragmentada. Atualmente não há suporte a usar mais de uma folha de estilo por HTML.

     # arquivo XSL para usar para HTML
     HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

AUTORES
 Neil Williams <linux@codehelp.co.uk>