XML, Marcação e Documentação

XML foi projetado como um mecanismo para identificar conteúdo estruturado em um conjunto de dados, agrupando diferentes partes hierárquicas desses dados entre tags de texto que identificam a função do texto que delimitam nessa hierarquia. Essas tags de texto, conhecidas como marcação, tags ou, mais adequadamente, elementos, estão em conformidade com uma estrutura predefinida. Essa estrutura é específica para diferentes tipos de dados e é conhecida como um esquema ou, historicamente, um DTD. Esquemas são gravados em XML, enquanto DTDs têm sua própria sintaxe.

A ideia das linguagens de marcação e, portanto, a própria XML, tem suas raízes em sistemas de produção de documento, em que arquivos de texto continham instruções de processamento ou identificadores estruturais para diferentes partes do documento. Esses arquivos de texto podiam, então, ser processados por software que sabia como interpretar essas instruções e produzir saída formatada para um dispositivo de saída específico. A evolução das linguagens de marcação para documentação incluiu quantidades crescentes de abstração sobre como marcação é usada.

As primeiras linguagens de marcação usavam instruções de formatação que especificavam detalhes de nível inferior, como mudanças de fonte e de tamanho de fonte. Rapidamente evoluíram para marcação mais genérica que identificava componentes lógicos e estruturais, como termos realçados, parágrafos, listas, títulos, etc.

As linguagens de marcação mais modernas, como Standard Generalized Markup Language (SGML) e XML, popularizaram a marcação estrutural mais abstrata, como manuais, capítulos, seções, etc. SGML também incluiu a noção de um DTD, que possibilitou que ferramentas SGML verificassem conformidade com conjunto específicos de elementos de marcação e os contextos os quais esses elementos podem aparecer na estrutura de um tipo de documento específico.

XML liberou explicitamente a marcação da região de documentação, expandindo seu uso para qualquer tipo de dados estruturados e incluindo um requisito para o conteúdo bem-formado, no qual as tags de abertura e de fechamento para cada elemento devem estar presentes. Apesar de as versões iniciais da especificação XML terem herdado DTDs de SGML, versões posteriores da especificação introduziram o uso de esquemas para definirem a estrutura de dados XML. Esquemas são equivalentes a DTDs, mas são gravados em XML e fornecem um modelo mais flexível para definir elementos válidos, seus tipos de dados e o contexto no qual podem aparecer em um documento XML.

A ideia de separar o conteúdo de um documento (as próprias palavras ou dados que contém) de sua apresentação (a maneira como é exibido em um formato de saída específico ou em um dispositivo de saída específico) é a ideia chave por trás de linguagens de marcação modernas e, especificamente, SGML e XML.

Apesar de XML facilitar a maneira de arquitetar DTDs e esquemas para aplicativos e segmentos de mercado específicos, uma de suas grandes vantagens no espaço de documentação é a existência de diversos DTDs e esquemas padrão para marcação de documentação. Os mais conhecidos deles são DocBook, Text Encoding Initiative (TEI), XHTML e os esquemas e DTDs usados pela Darwin Information Typing Architecture (DITA). Este artigo foca DocBook, que é o esquema mais conhecido e mais amplamente usado para marcação de documentação.

Visão Geral do Processo de Publicação para Documentos XML

Devido a seu foco em separar conteúdo da apresentação, XML é um mecanismo inerentemente para "gravar uma vez, ler muitas" que facilita a reutilização de informações em diversos documentos ou a customização de informações para um formato de saída ou público específico. Os outros artigos desta série explorarão esses tópicos em mais detalhes.

No contexto deste artigo, o termo publicação refere-se à conversão de um documento de um arquivo de texto que contém marcação de DocBook em um ou mais arquivos de saída em um formato de apresentação específico, como HTML, Portable Document Format (PDF) da Adobe®, PostScript, Rich Text Format (RTF) da Microsoft®, etc. Gerar saída HTML a partir de documentos XML é um processo de uma etapa que usa um único aplicativo para gerar saída HTML. O processo para produzir saída PDF, PostScript ou RTF requer somente uma etapa adicional:

1. Resolva quaisquer arquivos ou referências externas incluídos no documento DocBook e use uma folha de estilo XSL para gerar uma versão desse documento no formato Formatting Object (FO).
2. Para saída PDF, PostScript ou RTF, converta a versão FO do documento DocBook em um arquivo de saída no formato especificado.

Muitas ferramentas de software livre estão disponíveis para executar essas conversões, mas este artigo foca as três que acredito que forneçam as soluções mais úteis e mais flexíveis. A Tabela 1 descreve essas ferramentas.

As próximas seções explicam como fazer download e instalar esses aplicativos. Uma seção subsequente fornece um shell script que amarra todos juntos e fornece algumas opções convenientes para especificar formatos de saída, folhas de estilo customizadas, etc.

Obtendo e Instalando Software Necessário

Consulte Recursos para obter informações sobre onde obter os pacotes que fornecem o software e as folhas de estilo discutidas na seção anterior.

Nota: Caso use um sistema Linux, há uma boa chance de que os utilitários xmlto e xsltproc já estejam instalados em seu sistema ou estejam pelo menos disponíveis a partir de repositórios ou mídia de instalação para sua distribuição. Uma JVM real também deve ser instalada para executar fop—o GNU Compiler para Java não fornece todos os recursos necessários para fop.

Muitos desses pacotes instalam software em locais específicos de forma que o software de gerenciamento de pacote de seu sistema possa monitorar e atualizar o software conforme necessário. Isso não é verdadeiro para as folhas de estilo XSL do DocBook e para o Apache Formatting Objects Processor (FOP), que são transferidos por download como arquivos archive que contêm um único diretório de nível superior e diversos subdiretórios.

Para unificar um ambiente de análise e formatação de documentação, é uma boa ideia instalar quaisquer pacotes que não tenham nomes de caminho integrados em um único diretório que ainda não exista, como /home/doc. Isso fornece um único local onde é possível procurar arquivos relacionados, atualizar software conforme necessário e coletar ferramentas e folhas de estilo adicionais que podem ser desenvolvidas ou acumuladas.

Para que os pacotes discutidos na seção anterior funcionem com o script de unificação fornecido na próxima seção, execute os comandos da Lista 1 como usuário root em seu sistema UNIX ou Linux.

      mkdir /home/doc
      mkdir /home/doc/bin
      mkdir /home/doc/external
      mkdir /home/doc/external/SAVE
      mkdir /home/doc/XSL

Após fazer download dos arquivos (.zip) compactados para FOP e as folhas de estilo XSL do DocBook, coloque-os no diretório /home/doc/external, vá para esse diretório e extraia o conteúdo deles no mesmo, usando os comandos da Lista 2.

      cd /home/doc/external
      unzip fop-0.95-bin.zip
      unzip docbook-xsl-1.74.3.zip
      chmod 755 fop-0.95/fop

Para verificar se todos os pacotes necessários estão instalados em seu sistema, execute os comandos da Lista 3.

      xmlto --version
      xsltproc --version
      java --version

Se os aplicativos xmlto e xsltproc e uma JVM estiverem instalados corretamente em seu sistema e estiverem em seu caminho de execução, cada um desses comandos retorna informações de versão sobre esse aplicativo.

Gravando um Script de Wrapper para Publicação de Documentos

Agora que todo o software necessário para publicação do DocBook está instalado em seu sistema, tudo que precisa ser feito é lembrar-se de todas as opções necessárias e executar coisas na ordem correta. Como alternativa, é possível gravar um script de wrapper simples que amarre as coisas juntas corretamente e forneça algum controle sobre o processo de publicação, como o mostrado na Lista 4, Lista 5 e Lista 6.

Esse script gera saída HTML, PDF ou RTF com base nos argumentos fornecidos. Ao gerar saída PDF ou RTF, usa um processo em duas etapas para produzir a saída PDF; primeiro, executando xsltproc para gerar o arquivo FO a partir de sua entrada do DocBook, usando a folha de estilo XSL identificada na variável driverfile para identificar as regras de conversão. O script de wrapper usa, então, o aplicativo fop para gerar o formato de saída de destino a partir desse arquivo. Cada uma dessas etapas captura mensagens dos aplicativos usados (xsltproc e fop) em arquivos chamados xsltproc.out e fop.out. O script usa esses arquivos intermediários para monitorar o processo de conversão e capturar informações sobre depuração em potencial se surgirem problemas.

A Lista 4 mostra o início do script de wrapper de amostra, que define uma mensagem de uso que é exibida, caso o script seja executado sem nenhum argumento ou com o número errado de argumentos. Também configura alguns valores padrão para o script e analisa então os argumentos da linha de comando usando a função padrão getopt. (A Lista 7 mostra a saída dessa mensagem de uso.)

#! /bin/bash
#
# Simple script to generate HTML output from a DocBook file using
# xmlto, or to generate PDF/RTF output by generating a fo file,
# and then using Apache's FOP to format that.
#
# wvh@vonhagen.org
#

function usage {
        echo "Usage: $0 [OPTIONS] document-name"
        echo "  -D : produce draft mode document"
        echo "  -d : use specified xsl driver (requires name of XSL file) "
        echo "  -h : generate HTML output (requires output directory name)"
        echo "  -k : attempt PDF generation even if xsltproc errors were encountered"
        echo "  -n : suppress TOC"
        echo "  -r : produce RTF output rather than PDF"
        exit 1
}

dir=`dirname $0`

XSLTPROC="xsltproc"
PATH=$dir/../external/fop-0.95:${PATH}

if [ $# == 0 ] ; then
        usage
        exit
fi

driverfile="$dir/../external/docbook-xsl-1.74.3/fo/docbook.xsl"
# driverfile="$dir/../XSL/generic-print-driver.xsl"
draft="no"
keepgoing="no"
RTFoutput="no"
HTMLoutput="no"

while getopts ":d:h:Dknr" opt
do
  case $opt in
      d  )
           driverfile=$OPTARG
           echo "Using driver file: $driverfile"
           if [ ! -f $driverfile ] ; then
               echo "  Driver file not found"
               exit 1
           fi
           ;;
      D  )
           draft="yes"
           echo "Producing Draft Mode Document"
           ;;
      h  )
           HTMLdir=$OPTARG
           HTMLoutput="yes"
           echo "Producing HTML output to $HTMLdir instead of PDF"
           if [ -d $HTMLdir ] ; then
               echo "  Output directory $HTMLdir already exists"
               exit 1
           fi
           ;;
      k  )
           keepgoing="yes"
           echo "Will not stop if errors are encountered"
            ;;
      n  )
           notoc="--stringparam generate.toc ''"
           echo "Suppressing TOC..."
            ;;
      r  )
           RTFoutput="yes"
           echo "Producing RTF output rather than PDF"
            ;;
      \? ) 
           usage
           exit 1;;
  esac
done
shift $(($OPTIND - 1))

if [ ! -f $1 ] ; then
        echo "  Input file $1 not found - exiting."
        exit
fi

A Lista 5 mostra a parte do script que usa o aplicativo xmlto para gerar HTML ao produzir saída HTML ou o aplicativo xsltproc para criar saída FO a partir do arquivo XML de entrada caso esteja produzindo saída PDF ou RTF. A saída da etapa de conversão de XML para FO é gravada em um arquivo temporário denominado xsltproc.out, que simplifica a depuração se o aplicativo xsltproc encontrar erros em seu arquivo de entrada. Se qualquer variação da palavra error for detectada nesse arquivo, o script sai após gerar o arquivo FO. É possível então examinar o arquivo xsltproc.out, que deve ajudar a identificar e resolver o problema. Como na Lista 4, também é possível especificar a opção da linha de comando -k para forçar o script a continuar, mesmo se alguns erros forem detectados durante o processamento de xsltproc.

doc_base=`basename $1 .xml`

echo "Processing base name: $doc_base"

if [ x$HTMLoutput != "xno" ] ; then
     xmlto -o $HTMLdir html $1
     exit
fi

echo "  Generating FO file:  $doc_base.fo"

$XSLTPROC --output $doc_base".fo" \
          --stringparam draft.mode $draft \
          --stringparam fop1.extensions 1 \
          --xinclude \
          $notoc \
          $driverfile \
          $1 1> xsltproc.out 2> xsltproc.out

probs=`grep -i error xsltproc.out | wc -l | sed -e 's; ;;g'`

if [ x$probs != "x0" ] ; then
          echo ""
          echo "PROBLEMS:"
          echo ""
          cat xsltproc.out
          echo ""
          if [ x$keepgoing = "xno" ] ; then
                  exit
          fi
fi

echo "    Fixing FO file references to system images..."
cat $doc_base".fo" | sed -e "s;\"url(\.\./external/;\"url($dir/\.\./external/;g" > $$
mv $$ $doc_base".fo"

A Lista 6 mostra o último estágio do script, que usa o aplicativo fop para gerar saída PDF ou RTF a partir de um arquivo FO. Como no processo de conversão de XML para FO, a saída da etapa de conversão de FO para PDF/RTF é gravada em um arquivo temporário denominado fop.out, que simplifica a depuração se o aplicativo fop encontrar erros no arquivo FO. Se a geração de PDF/RTF falhar, é possível, então, examinar o arquivo fop.out, que deve ajudá-lo a identificar e resolver o problema. Como na Lista 4, também é possível especificar a opção da linha de comando -k para forçar o script a continuar mesmo se alguns erros tiverem sido detectados durante o processamento de xsltproc.

if [ x$RTFoutput = "xno" ] ; then
    echo "  Generating PDF file: $doc_base"".pdf"
        fop -fo $doc_base".fo" -pdf $doc_base".pdf" 1> fop.out 2> fop.out
else
    echo "  Generating RTF file: $doc_base"".rtf"
        fop -fo $doc_base".fo" -rtf $doc_base".rtf" 1> fop.out 2> fop.out
fi

probs=`grep -i Exception fop.out | wc -l | sed -e 's; ;;g'`

if [ x$probs != "x0" ] ; then
        echo ""
        echo "EXCEPTION OCCURRED DURING PROCESSING:"
        echo ""
        cat fop.out
        echo ""
fi

É possível fazer download de uma cópia desse script de amostra, chamado xml-format.sh (consulte xml-format.zip em Downloads). Para instalar esse script em seu sistema, faça download do arquivo zip e extraia xml-format.sh para o diretório /home/doc/bin. Use o comando a seguir para assegurar que o script seja executável:

      chmod 755 /home/doc/bin/xml-format.sh

Por fim, certifique-se de que o diretório /home/doc/bin esteja em seu caminho de execução, editando seu arquivo ~/.bashrc e incluindo a linha a seguir no final desse arquivo ou executando essa mesma linha como um comando em uma linha de comando do shell em seu sistema:

      export PATH=/home/doc/bin:${PATH}

Caso inclua esse comando em seu arquivo ~/.bashrc, determine a origem desse arquivo na sessão de login atual para que suas mudanças tenham efeito no shell atual. Para fazer isso, execute o seguinte comando:

      source ~/.bashrc

Publicando um Documento DocBook

Executar o script xml-format.sh sem nenhum argumento exibe informações de resumo sobre como o script deve ser usado, como na Lista 7.

      Usage: xml-format.sh [OPTIONS] document-name
        -D : produce draft mode document
        -d : use specified xsl driver (requires name of XSL file)
        -h : generate HTML output (requires output directory name)
        -k : attempt PDF generation even if xsltproc errors were encountered
        -n : suppress TOC
        -r : produce RTF output rather than PDF

Para gerar a versão PDF de um documento DocBook, simplesmente execute o script com o nome desse documento, como no exemplo a seguir:

      xml-format.sh sample-document.xml

Para gerar a versão HTML de um documento DocBook usando esse script, é necessário usar a opção -h e especificar o nome do diretório de destino para os arquivos de saída HTML. Por exemplo, para criar uma versão HTML de um documento DocBook no diretório HTML-output (relativo a seu diretório de trabalho atual), execute o seguinte comando:

      xml-format.sh -h HTML-output sample-document.xml

Incluindo uma Camada de Customização XSL para Saída PDF

Por padrão, o script xml-format.sh fornecido com este artigo usa as folhas de estilo de saída padrão fornecidas no pacote XSL do DocBook. Para incluir suas próprias customizações, é possível criar sua própria folha de estilo que primeiro carrega a folha de estilo XSL padrão do DocBook e fornece então valores customizados para quaisquer parâmetros que você deseje substituir. Um exemplo de uma camada de customização é fornecido na folha de estilo generic-print-driver.xsl (consulte generic-print-driver.zip em Downloads).

Para usar uma folha de estilo diferente com o script xml-format.sh, é possível usar a opção -d para especificar o nome do caminho completo ou relativo da folha de estilo que deseje usar ou é possível modificar o valor da variável driverfile no script xml-format.sh. O script de amostra inclui uma linha que possibilita o uso do script generic-print-driver.xsl de exemplo. Simplesmente comente a linha do valor anterior para a variável driverfile e remova o comentário da linha a seguir, que contém a nova definição.

Resumo

O poder e flexibilidade de XML, os conjuntos de padrões existentes e um rico conjunto de ferramentas para trabalhar com e converter documentos XML facilitam a instalação e configuração de seu próprio conjunto de ferramentas para gerar saída em diversos formatos de documentos XML. Apesar de muitas ferramentas comerciais estarem disponíveis para editar e formatar documentos XML, criar seu próprio conjunto de ferramentas para fazer isso ajuda a entender melhor o processo, e o preço é imbatível.

Voltar para parte superior

Downloads

Informações sobre métodos de download

Recursos

Aprender

• Produzindo Documentação e Reutilizando Informações em XML, Parte 2: Reutilizar Informações na Documentação XML (William von Hagen, developerWorks, março de 2009): Estruture documentos e fragmentos de XML para reutilização. Com XInclude, inclua seções de documento externo e, com XPointer, inclua pequenos fragmentos do documento em um documento maior, na Parte 2 desta série em três partes.
  
  
• Produzindo Documentação e Reutilizando Informações em XML, Parte 3: Criando Documentos XML com Diversos Destinos (William von Hagen, developerWorks, julho de 2009): Customize a documentação para públicos específicos e formatos de saída usando atributos XML e uma etapa de pré-processamento, na Parte 3 desta série em três partes. Usando DocBook como um exemplo, simplifique e automatize a produção da documentação concluída com shell scripts e Makefiles.
  
  
• DocBook: The Definitive Guide: Localize informações completas sobre a marcação DocBook em SGML e XML. O texto completo desse manual está disponível on-line, mas vale a pena comprar uma cópia caso vá fazer trabalho sério de publicação com DocBook.
  
  
• DocBook XSL: The Complete Guide: Leia informações definitivas sobre folhas de estilo e publicação do DocBook. O texto completo desse manual está disponível on-line, mas vale a pena comprar uma cópia caso vá fazer trabalho sério de publicação com DocBook.
  
  
• What is XSL-FO? (G. Ken Holman, O'Reilly xml.com, março de 2002): Leia com atenção uma excelente introdução à especificação XSL Formatting Object.
  
  
• OASIS DocBook Technical Committee: Obtenha informações sobre versões existentes e futuras do padrão DocBook. O Web site do OASIS fornece uma grande quantidade de informações sobre XML e outros padrões abertos.
  
  
• Listas de correspondência relacionadas a DocBook no OASIS: Junte-se a discussões gerais sobre marcação e aplicativos DocBook que processam e formatam documentos DocBook.
  
  
• XML Schema 1.1, Parte 1: Uma Introdução ao XML Schema 1.1 (Neil Delima, Sandy Gao. Michael Glavassevich, Khaled Noaman; developerWorks; dezembro de 2008): Obtenha informações detalhadas sobre como definir e organizar o XML Schema.
  
  
• DTD, XML Schema e DSD: Encontre uma boa comparação de DTDs e esquemas e um ponteiro para An Introduction to XML and Web Technologies, um bom livro que atinge as expectativas de seu título.
  
  
• Certificação IBM XML: Saiba como você pode se tornar um Desenvolvedor Certificado pela IBM em XML e tecnologias relacionadas.
  
  
• Biblioteca Técnica de XML: Consulte a Zona de XML do developerWorks para obter uma ampla gama de artigos técnicos e dicas, tutoriais, padrões e IBM Redbooks.
  
  
• Eventos Técnicos e Webcasts do developerWorks: Fique atualizado com a tecnologia nessas sessões.
  
  
• Podcasts do developerWorks: Ouça entrevistas e discussões interessantes para desenvolvedores de software.
  
  

Obter produtos e tecnologias

• Apache FOP: Faça download da versão mais recente para sua plataforma. Clique em Download do lado esquerdo.
  
  
• xsltproc: Faça download da versão mais recente para sistemas UNIX e Linux.
  
  
• DocBook DTD: Faça download da versão mais recente e inicie.
  
  
• DocBook XSL Stylesheets: Faça download da versão mais recente. (Vá para Site do Projeto DocBook > releases de arquivos e selecione docbook-xsl.)
  
  
• xmlto: Faça download da versão mais recente se ainda não estiver disponível em seu sistema. Dependendo da versão do UNIX ou Linux que você está executando, também pode ser necessário fazer download e instalar Bash, the Bourne-Again shell, GNU find and friends e mktemp.
  
  
• IBM Java SDK: Faça download desse developers kit para sua plataforma. Pode ser necessário fazer download e instalar o IBM Java SDK para instalar e usar o formatador Apache FOP em determinadas distribuições UNIX e Linux.
  
  
• Versões de avaliação de produtos IBM: Faça download ou explore as avaliações on-line no IBM SOA Sandbox e entre em contato com ferramentas de desenvolvimento de aplicativos e produtos de middleware do DB2®, Lotus®, Rational®, Tivoli® e WebSphere®.
  
  

Discutir

• Participar do fórum de discussão.
  
  
• Fóruns de Discussão da Zona XML: Participe de qualquer uma das diversas discussões relacionadas a XML.
  
  
• Blogs do developerWorks: Verifique esse blogs e envolva-se na comunidade do developerWorks.
  
  

Sobre o autor

Classificar este artigo

Comentários

Voltar para parte superior

Índice

• XML, Marcação e Documentação
• Visão Geral do Processo de Publicação para Documentos XML
• Obtendo e Instalando Software Necessário
• Gravando um Script de Wrapper para Publicação de Documentos
• Publicando um Documento DocBook
• Incluindo uma Camada de Customização XSL para Saída PDF
• Resumo
• Downloads
• Recursos
• Sobre o autor
• Comentários

Conheça a IBM da sua cidade

A IBM está mais perto do que você imagina!

---

Saiba mais