Contrariamente ao que se poderia pensar lendo o título, este capítulo descreve a instalação dos instrumentos necessários para a produção formatada do presente Guia ao NetBSD. Ainda que a SGML/DocBook e a DSSSL não sejam descritas aqui, ao fim do capítulo estão presentes alguns links em que pode ser encontrado o material informativo para aqueles que desejam saber mais.
O ambiente SGML/DocBook pode ser instalado com a utilização do "meta-pacote" netbsd-docs. Este é o método mais simples e é o que aconselho usar. O presente capítulo, entretanto, descreve a instalação e a configuração de cada um dos componentes necessários, a fim de que os examinemos com maior detalhamento e, eventualmente, de também verificar sua correta instalação.
Nota: O "meta-pacote" netbsd-docs instala alguns pacotes não estritamente necessários para a produção do guia. Tais pacotes, que não são descritos neste documento, são:
iso12083-1993
unproven-pthreads-0.17nb2
opensp-1.4
html-4.0b
Os pacotes necessários para o guia serão instalados com a utilização de pacotes pré-compilados. Para quem preferir, é possível compilá-los a partir do código-fonte. Para mais detalhes veja-se o Capítulo 8.
Nota: Os números das versões dos pacotes instalados são, naturalmente, sujeitos a mudança com a saída de novas versões.
SGML (Standard Generalized Markup Language) é uma linguagem utilizada para definir a estrutura de outras linguagens baseadas em "markup". Isso significa que com a SGML pode-se definir a gramática das linguagens de markup. HTML, por exemplo, pode ser definida usando-se SGML. Os programadores podem pensar em SGML como o equivalente da BNF (Backus-Naur Form) para as linguagens de programação: uma notação para definir gramáticas.
DocBook é um esquema de markup definido para o uso da SGML. O DocBook especifica quais tags podem ser utilizados em um documento e de que modo podem ser combinados entre si. Os programadores podem pensar em DocBook como em uma linguagem de programação, com as suas palavras-chave válidas e as suas regras. Por exemplo, para o DocBook os tags
<para> ... </para>
definem o início e o fim de um parágrafo. Além disso o DocBook especifica que o tag <para> pode estar no interior de uma seção <sect1> mas que o tag <sect1> não pode estar no interior de um <para>.
À luz do que acaba de ser dito pode-se compreender que os documentos produzidos com estes instrumentos são documentos DocBook e não SGML. Desse ponto de vista, DocBook é a contraparte da HTML (ainda que os tags sejam mais numerosos e os conceitos à base das duas linguagens, diversos).
A especificação DocBook (isto é, a lista dos tags válidos e as regras para combiná-los é chamada DTD (Document Type Definition).
Uma DTD definirá qual será o aspecto de um documento-fonte válido mas não dá nenhuma indicação sobre o formato do documento final gerado a partir das fontes. A título de exemplo, o tag <title> marca o início de um título mas não especifica que aparência terá o título no documento final (tamanho e corpo dos caracteres, alinhamento, espaçamento, etc.) Para chegar à "apresentação" do documento é necessário um passo a mais, efetuado com a utilização do programa Jade, que aplica ao documento-fonte as transformações DSSSL. DSSSL (Document Style Semantics and Specification Language) é o formato utilizado para definir as stylesheets (folhas de estilo) necessárias para converter o documento DocBook em outros formatos.
A "vida" de um documento DocBook é portanto a seguinte:
redação do documento fonte;
a DTD do DocBook é utilizado pelo nsgmls para "validar" o documento;
Jade aplica as folhas de estilo DSSSL ao documento fonte e gera um novo documento.
ainda não é possível imprimir o documento gerado porque ele contém as diretrizes de formatação indicadas nas folhas de estilo (pode tratar-se de um documento HTML, RTF, TeX, etc.);
um programa de formatação (um navegador para HTML, um processador de textos para RTF, TeX, ...) cria a versão final, visualizável ou imprimível do documento.
Em definitivo, o que precisa para iniciar o trabalho é:
uma DTD para DocBook
as folhas de estilo DSSSL usadas pelo Jade para gerar HTML/RTF, etc.
o programa Jade e o parser (analisador gramatical) nsgmls
Jade é um parser SGML/XML que implementa o mecanismo da DSSSL. O pacote Jade inclui também o parser nsgmls, que valida os documentos.
Nota: OpenJade é uma evolução do Jade que, no momento, não se compila sob NetBSD (mas que não é necessário para o guia).
Para instalar o pacote pré-compilado do Jade:
# pkg_add jade-1.2.1.tgz
Ao fim da instalação, a documentação do Jade encontra-se em /usr/pkg/share/doc/jade/index.htm. O diretório principal da instalação é /usr/pkg/share/sgml/jade/: é aí que se encontra o arquivo catalog do Jade.
Depois de ter instalado o Jade pode-se proceder à instalação da DocBook DTD.
Este pacote exige a instalação das "entities" para o conjunto de caracteres ISO 8879:1986. Adicionemos pois o pacote correspondente:
# pkg_add iso8879-1986.tgz
As entities são instaladas no diretório /usr/pkg/share/sgml/iso8879/ e o catálogo correspondente é: /usr/pkg/share/sgml/iso8879/catalog.
Finalmente pode-se instlar a DTD.
# pkg_add docbook-4.1.tgz
Apesar do nome este pacote instala várias versões de DTD (2.4.1, 3.0, 3.1, 4.0, 4.1). Isto é, permite a elaboração de documentos que usam diferentes versões de DocBook.
Nota: o guia do NetBSD usa no momento a versão 4.1 do DTD do DocBook e, portanto, as outras versões não são estritamente necessárias. Todavia, em consideração ao fato de que cada DTD ocupa menos de 250 kb, pode ser conveniente mantê-las no disco rígido, já que permitem a elaboração de outros documentos.
A raiz da instalação do sistema é /usr/pkg/share/sgml/docbook/4.1/. Cada versão de DTD encontra-se em um diretório separado e possui um arquivo catálogo próprio. Por exemplo: /usr/pkg/share/sgml/docbook/4.1/catalog.
O último passo consiste na instalação das folhas de estilo DSSSL.
# pkg_add dsssl-docbook-modular-1.57.tgz
Também as folhas de estilo instalam um catálogo próprio que se encontra em /usr/pkg/share/sgml/docbook/dsssl/modular/catalog. Ademais são munidas de detalhada documentação acessada em /usr/pkg/share/sgml/docbook/dsssl/modular/doc/index.html.
Agora que foi instalado todo o necessário, pode-se começar a utilizar as ferramentas para produzir a versão HTML do guia (por exemplo, a versão italiana).
Com um cd entra-se no diretório raiz do guia e se executa o comando make:
$ cd it
$ make netbsd.html
Uma longa relação de erros escorrerá sobre a tela. Isso é devido ao fato de que o parser (analisador gramatical) SGML nsgmls não consegue encontrar os arquivos catalog. Portanto, é necessário digitar os seguintes comandos (que convém inserir no próprio ~/.profile):
SGML_ROOT=/usr/pkg/share/sgml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/3.0/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/3.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.0/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/dsssl/modular/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES Nota: modificar oportunamente os comandos se for utilizada uma shell C (csh) ou uma shell derivada desta.
Agora que a variável do ambiente SGML_CATALOG_FILES está ativa, pode-se tentar de novo o comando precedente:
$ make netbsd.html nsgmls -sv netbsd.sgml nsgmls:I: SP version "1.3.3" jade -d ../dsl/myhtml.dsl -t sgml -o netbsd.html netbsd.sgml
Desta vez a operação chega a bom termo e será gerada a versão HTML do guia. A criação do formato RTF não apresenta maiores dificuldades:
$ make netbsd.rtf nsgmls -sv netbsd.sgml nsgmls:I: SP version "1.3.3" jade -d ../dsl/myrtf.dsl -t rtf -o netbsd.rtf netbsd.sgml
Com a instalação descrita acima podem ser gerados apenas os formatos HTML e RTF. Para se criar os formatos PS e PDF é necessário instalar e configurar o TeX e o Jadetex (um pacote de macros para o TeX).
Nas minhas instalações geralmente crio um arquivo de catálogo master, que contém uma referência a todos os outros. Para usar esse método pode-se criar o arquivo /usr/pkg/share/sgml/catalog com o seguinte conteúdo:
CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog" CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog" CATALOG "/usr/pkg/share/sgml/docbook/4.0/catalog" CATALOG "/usr/pkg/share/sgml/docbook/4.1/catalog" CATALOG "/usr/pkg/share/sgml/docbook/dsssl/modular/catalog" CATALOG "/usr/pkg/share/sgml/iso8879/catalog" CATALOG "/usr/pkg/share/sgml/jade/catalog"
Feito isso, as inicializações no ~/.profile podem ser simplificadas assim:
SGML_CATALOG_FILES=/usr/pkg/share/sgml/catalog export SGML_CATALOG_FILES
Para criar a versão Postscript do guia são necessárias algumas operações preliminares:
instalação do TeX
habilitar a silabação italiana do TeX
criação do formato hugelatex exigido pelo Jadetex
instalação do Jadetex
As seções seguintes descrevem em detalhe os pontos precedentes.
A instalação do TeX foi bastante simplificada, como de costume, pelo sistema de gerenciamento pacotes. Utilizando-se os pacotes pré-compilados é suficiente executar os seguintes comandos (os números das versões dos pacotes poderiam ser diferentes):
# pkg_add teTeX-share-1.0.2.tgz
# pkg_add teTeX-bin-1.0.7nb1.tgz
O guia do NetBSD é correntemente disponível em quatro línguas diferentes: francês, inglês, italiano e português brasileiro. Destas, apenas inglês e francês têm silabação automática feita pelo TeX. Para habilitar a silabação para a língua italiana (e também para o português. Nota do tradutor.), são necessárias algumas operações simples:
Editar a arquivo /usr/pkg/share/texmf/tex/generic/config/language.dat removendo o caracter indicador de comentário (%) ao início da linha relativa à língua italiana. Isto é:
%italian ithyph.tex
torna-se
italian ithyph.tex
Nota: quando estiverem disponíveis ulteriores traduções do guia, será provavelmente necessário ativar a silabação também para as novas línguas.
Agora é necessário recriar os formatos latex e pdflatex:
# cd /usr/pkg/share/texmf/web2c
# fmtutil --byfmt latex
# fmtutil --byfmt pdflatex
Para se fazer uma verificação pode-se conferir, por exemplo, o arquivo latex.log que deveria conter, entre outras informações, uma linha do seguinte tipo:
Babel <v3.6Z> and hyphenation patterns for american, french, german, ngerman, italian, nohyphenation, loaded.
Nota: há vários modos de se executar estas operações, de acordo com o próprio nível de conhecimento do TeX (o meu é razoavelmente baixo). Por exemplo, é possível usar o programa interativo texconfig, ou recriar os formatos usando diretamente tex (fmtutil, de fato, é simplesmente um script que invoca o tex).
Se você conhece um método melhor para efetuar as operações descritas neste capítulo, peço-lhe mo aponte.
Para poder utilizar o jadetex é necessário criar o formato hugelatex, que não é senão um formato latex com os limites de capacidade aumentados para poder gerir os grandes arquivos criados pelo jadetex. Antes de efetuar as modificações convém fazer uma cópia de segurança (back up) do arquivo /usr/pkg/share/texmf/web2c/texmf.cnf. Depois, acrescentar ao fim do arquivo as linhas seguintes (precisaremos das definições para o jadetex e para o pdfjadetex quando instalarmos o Jadetex mais tarde):
% hugelatex settings main_memory.hugelatex = 1100000 param_size.hugelatex = 1500 stack_size.hugelatex = 1500 hash_extra.hugelatex = 15000 string_vacancies.hugelatex = 45000 pool_free.hugelatex = 47500 nest_size.hugelatex = 500 save_size.hugelatex 5000 pool_size.hugelatex = 500000 max_strings.hugelatex 55000 font_mem_size.hugelatex = 400000 % jadetex & pdfjadetex main_memory.jadetex = 1500000 param_size.jadetex = 1500 stack_size.jadetex = 1500 hash_extra.jadetex = 15000 string_vacancies.jadetex = 45000 pool_free.jadetex = 47500 nest_size.jadetex = 500 save_size.jadetex 5000 pool_size.jadetex = 500000 max_strings.jadetex 55000 main_memory.pdfjadetex = 2500000 param_size.pdfjadetex = 1500 stack_size.pdfjadetex = 1500 hash_extra.pdfjadetex = 50000 string_vacancies.pdfjadetex = 45000 pool_free.pdfjadetex = 47500 nest_size.pdfjadetex = 500 save_size.pdfjadetex 5000 pool_size.pdfjadetex = 500000 max_strings.pdfjadetex 55000
Acrescentar as seguintes linhas, que descrevem o formato hugelatex, ao arquivo fmtutil.cnf (no diretório /usr/pkg/share/texmf/web2c)
# hugelatex format created for jadetex hugelatex tex language.dat latex.ini
salvar o arquivo e executar o comando
fmtutil --byfmt hugelatex.
Agora o formato hugelatex está pronto para o uso.
Nota: como já se assinalou, com o TeX há muitos modos de se atingir o mesmo resultado (neste caso, a criação do formato hugelatex).
O guia para a instalação do Jadetex nos dá as seguintes instruções:
# cp -R /usr/pkg/share/texmf/tex/latex/config /tmp # cd /tmp/config # tex -ini -progname=hugelatex latex.ini # mv latex.fmt hugelatex.fmt # mv hugelatex.fmt /usr/pkg/share/texmf/web2c # ln -s /usr/pkg/bin/tex /usr/pkg/bin/hugelatex
Nota: a versão mais recente do Jadetex pode ser obtida em http://www.tug.org/applications/jadetex/
Fazer o download do pacote Jadetex (a versão corrente é jadetex-3.6.zip), descompactá-lo e depois executar os seguintes comandos:
# cd jadetex
# make install
# mktexlsr
A instalação copia os arquivos de formatação do jadetex e do pdfjadetex (assim como alguns arquivos de apoio) na árvore dos diretórios do TeX.
A distribuição do Jadetex contém também duas páginas de manual que não são instaladas automaticamente. Se as quisermos é suficiente copiá-las manualmente no diretório adequado. Por exemplo:
# cp jadetex.1 pdfjadetex.1 /usr/local/man/man1
Agora está tudo pronto para se criar a versão Postscript do guia do NetBSD (e naturalmente de qualquer outro documento). Por exemplo, deslocar-se para o diretório base do guia e dar os seguintes comandos:
$ cd it
# make netbsd.ps
Uma simples e bem escrita introdução à SGML/DocBook, assim como uma descrição das ferramentas necessárias encontram-se em SGML comme format de fichier universel.
The official DocBook home page é a fonte oficial de informações sobre o DocBook. Entre outras informações pode-se fazer consultas on line ou o download do livro DocBook: The Definitive Guide de Norman Walsh e Leonard Muellner, um guia fundamental para quem quer aprofundar-se no tema.
Para informações sobre as DSSSL convém começar com nwalsh.com.
As fontes do Jade/OpenJade e documentação correspondente podem-se encontrar em OpenJade Home Page.
Para quem deseja produzir documentos em formato Postscript ou PDF a partir das fontes DocBook é bom dar uma olhada na home page do JadeTex.
A home page de Markus Hoenicka explica tudo o que é necessário saber para trabalhar com SGML/DocBook no Windows NT.