Nível: Intermediário William von Hagen, Systems Administrator, Writer, WordSmiths
07/Jul/2009 XML é um formato opcional para gravar documentação que pode ser usado com muitos pacotes de software de documentação e ambientes de produção diferentes. Neste terceiro artigo na série, descubra como criar documentos de fonte isolada que podem produzir saída em variados e diferentes formatos de saída.
O que É Documentação de Fonte Isolada?
Como a Parte 1
desta série mostrou, usar XML (e seu predecessor conceitual, Standard
Generalized Markup Language, ou SGML) para documentação possibilita separar o
conteúdo de um documento—as palavras e dados reais que contém
—de sua apresentação—a maneira na qual o conteúdo é exibido em um formato de saída específico ou em um dispositivo de saída específico.
Essa separação possibilita focar o conteúdo desse documento em vez de em como as informações serão eventualmente usadas ou apresentadas.
A Parte 2
discutiu diversos mecanismos que possibilitam organizar a documentação XML em unidades menores de informações (popularmente conhecidas como
divisão em partes), para criar documentos maiores ou documentos para diferentes públicos, criando threads de diferentes partes de informações ou das mesmas partes de informações em diferentes sequências.
 |
Acrônimos Usados Frequentemente
- DITA: Darwin Information Typing Architecture
- DTD: Document type definition
- HTML: Linguagem de Marcação de Hipertexto
- PDF: Portable Document Format
- URL: Localizador Uniforme de Recursos
- XML: Linguagem de Marcação Extensível
- XSL: Extensible Stylesheet Language
|
|
Um desenvolvimento natural de XML como um ambiente de documentação independente de software que facilita a reutilização de informações é a necessidade de customizar essas informações de forma que seu conteúdo seja diferente com base no público específico ou no formato de saída.
Essa reutilização é comumente conhecida como
documentação de fonte isolada, pois um único conjunto de arquivos de entrada pode atender os requisitos de diversos públicos ou formatos de saída.
Alguns requisitos de fonte isolada são tratados automaticamente pelas ferramentas que produzem saída em diferentes formatos.
Por exemplo, gerar a saída PDF para um documento XML DocBook que contenha um link para recursos externos (usando o elemento
<ulink> ) integra um hyperlink nessas informações e sua URL real nessa saída, enquanto que gerar saída HTML a partir do mesmo documento XML integra um link nessa saída HTML.
Transformar um único elemento em diferentes maneiras para diferentes formatos de saída é um passo na direção certa para a documentação de fonte isolada, mas não possibilita a customização de conteúdo do documento além de seus requisitos de apresentação.
Poder customizar o conteúdo real de um documento com base em seu formato de saída de destino é um requisito bastante comum para a documentação moderna.
Felizmente, isso é tratado facilmente por uma combinação de pré-processamento e do proveito tirado dos aspectos flexíveis do design de formatos de documentação, como XML DocBook.
Elementos e Atributos de DocBook
Os elementos XML usam pares nome-valor chamados de atributos para fornecer informações adicionais sobre uma instância de um elemento.
Geralmente, os atributos identificam de forma exclusiva instâncias do mesmo elemento em um documento XML ou identificam comportamento especializado para instâncias de um elemento.
Os atributos estão contidos no escopo de um elemento e têm o formato:
Como um exemplo, o atributo mais comum para elementos XML
é o atributo id, que identifica de forma exclusiva uma determinada instância de um elemento XML, como no exemplo a seguir:
<section id="introduction">
|
Na documentação XML, os atributos id suportam referência cruzada através de elementos como os elementos
<xref> e
<link>. Seguem exemplos de referências ao elemento
<section> usado no exemplo anterior:
<xref linkend="introduction"/>
<link linkend="introduction">introduction to this document</link>
|
Um exemplo de um atributo que identifica o comportamento especializado para um elemento é o atributo
role do elemento <emphasis>:
<emphasis role="bold">example</emphasis>
|
Conteúdo englobado em um elemento <emphasis> é geralmente renderizado em itálico em formatos de apresentação como PDF ou HTML.
Especificar o atributo role="bold" altera a renderização desse elemento de itálico para negrito.
Abordagens Alternativas para Customização do Documento
Historicamente, as linguagens de marcação que eram orientadas para a produção de documentos suportava algum grau de customização do conjunto de elementos que suportavam.
Criar elementos customizados que podem ser usados de maneiras especializadas em uma determinada ferramenta era um recurso da Generalized Markup Language, ou GML, original, a predecessora da SGML (consulte
Recursos para obter informações adicionais).
Como o acrônimo sugere, uma diferença principal entre GML e SGML era a padronização do conjunto de elementos que estavam presentes em uma determinada definição de tipo de documento.
Apesar de SGML e, posteriormente, os tipos de documentos XML serem projetados para usar um conjunto de elementos padrão predefinido, ainda é possível incluir definições de elementos customizados, fazendo referência a recursos externos que definem esses elementos.
No entanto, incluir definições de elementos customizados em um esquema ou DTD existente é geralmente uma má ideia por diversas razões, principalmente:
- Documentos que usam elementos não padrão não estão mais em conformidade com os tipos de documentos padrão, como DocBook ou DITA.
- Estender um esquema ou DTD limita suas oportunidades para troca de documentos com outras instituições ou empresas que usam os esquemas ou DTDs padrão.
Mesmo se também for possível trocar as definições para seus elementos não padrão, trabalho de customização adicional será necessário para troca de documentos bem-sucedida.
- Ferramentas projetadas para trabalharem com tipos de documentos padrão precisarão ser estendidas para suportar os novos elementos.
Apesar de ser relativamente fácil fazer isso com ferramentas de software livre, essa extensão pode ser impossível com ferramentas proprietárias de código fechado.
Este artigo discute o uso de uma etapa de pré-processamento para eliminar texto com condições que
não se aplicam a um público ou formato de saída específico.
Algumas ferramentas gráficas de documentação XML fornecem uma solução equivalente, possibilitando a configuração de variáveis usadas durante o processo de geração de saída.
Este artigo foca a abordagem mais genérica de pré-processamento que pode ser usada por uma ampla gama de ferramentas de documentação XML de software livre em vez de os mecanismos suportados pelas ferramentas de documentação específicas.
Atributos Comuns para Elementos DocBook
Como pode-se esperar, diferentes elementos XML têm diferentes atributos com base no tipo e uso de um elemento específico.
No entanto, os esquemas e DTDs de documentação XML, como o tipo de documento DocBook que é o foco desta série de artigos, também definem um conjunto comum de atributos (consulte
Recursos
para obter informações adicionais) que podem ser usados em qualquer elemento XML e que são tipicamente usados para identificar informações especificas de apresentação ou de destino para um determinado elemento.
Exemplos comuns desses atributos incluem:
arch: Projetado para identificar o sistema de computador ou a arquitetura do processador ao qual o conteúdo de uma determinada instância de um elemento se aplica
audience: Projetado para identificar o público ao qual o conteúdo de uma determinada instância de um elemento se aplica
condition: Projetado para customização de conteúdo local específico do aplicativo
os: Projetado para identificar o sistema operacional do computador ao qual o conteúdo de uma determinada instância de um elemento se aplica
revision: Projetado para identificar uma revisão de software ou documento específica à qual o conteúdo de uma determinada instância de um elemento se aplica
vendor: Projetado para identificar o fornecedor de hardware ou software ao qual o conteúdo de uma determinada instância de um elemento se aplica
Definir um conjunto de valores válidos para qualquer um desses atributos e depois implementar um pré-processador que descarte elementos que têm outros valores para esse atributo fornece uma maneira fácil de
determinar condições para seus documentos. Os atributos que você decide usar para customização são decididos inteiramente por você, mas a opção geralmente depende de qual desses atributos melhor se aplica ao tipo de conteúdo para o qual deseja determinar a condição e a razão para essa customização.
Este artigo usa o atributo
condition genérico como um exemplo de determinação de condição geral específica de um determinado formato de saída/apresentação.
As duas seções a seguir explicam como usar os atributos como esses para identificar de forma condicional elementos específicos ou fragmentos de conteúdo em um elemento.
Incluindo Condicionalmente Elementos Inteiros
Os atributos comuns discutidos na seção anterior fornecem uma maneira fácil de identificar as partes de seus documentos que deseja associar a públicos específicos ou formatos de saída.
Esta seção usa o atributo condition
como um exemplo, mas é possível usar qualquer elemento comum discutido nas seções anteriores, desde que ainda não sejam usados em seu site.
Um tipo comum de conteúdo com condição determinada é o texto que aparece em um documento quando é formatado para ser usado em diferentes formatos de apresentação.
Por exemplo, documentos projetados para serem usados on-line incluem links para a próxima seção no final de cada seção para simplificar a navegação para o leitor.
Esses links podem ter a seguinte aparência:
<para>
To proceed to the next section of this tutorial, click
<link linkend="link-to-next-section">here</link>.
</para>
|
Apesar de útil em documentos on-line, essas informações são redundantes e confusas quando o mesmo documento é formatado como um documento
Adobe® PostScript® ou PDF. Para identificar essa parte do documento como pretendida para uso somente quando o documento for formatado para apresentação on-line, é possível incluir o atributo
condition="online"
no elemento <para>, como no exemplo a seguir:
<para condition="online">
To proceed to the next section of this tutorial, click
<link linkend="link-to-next-section">here</link>.
</para>
|
Incluindo Pré-processamento no Processo de Formatação de Documento
Seria interessante se a simples inclusão dos atributos discutidos na seção anterior em um determinado elemento fizesse a coisa certa para suas ferramentas de documentação, mas isso é raramente o caso.
Para tirar proveito desse tipo de determinação de condição, é necessário gravar um pequeno script XSL que descarte essa parte de seu documento quando estiver formatando o mesmo para outros formatos de apresentação.
A Lista 1
mostra um exemplo de um script XSL que descarta elementos do conteúdo que têm um atributo
condition com um valor diferente de
print.
Lista 1. Script de Pré-processamento para Saída de Impressão
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xi="http://www.w3.org/2003/XInclude">
<xsl:output method="xml" omit-xml-declaration="yes" indent="yes"/>
<xsl:preserve-space elements="*"/>
<xsl:template match="*|@*">
<xsl:variable name="_element">
<xsl:value-of select="name()" />
</xsl:variable>
<xsl:variable name="_condition">
<xsl:value-of select="@condition" />
</xsl:variable>
<xsl:choose>
<xsl:when test="$_condition = ''">
<xsl:copy>
<xsl:apply-templates select="@* | * | text() | comment()" />
</xsl:copy>
</xsl:when>
<xsl:when test="$_condition = 'print'">
<xsl:copy>
<xsl:apply-templates select="@*|node()" />
</xsl:copy>
</xsl:when>
<xsl:otherwise>
<xsl:message> Skipping <xsl:value-of select="$_element"/></xsl:message>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
|
Nota: Esse script foi gravado para capacidade de leitura, não elegância. Ele pode ser simplificado, com certeza.
Dando continuidade ao exemplo anterior, o script da Lista 1
descarta elementos cujo atributo
condition os identifica como previstos para outros formatos de saída.
Essa previsão remove o conteúdo mostrado no exemplo
"online-only" anterior, pois seu atributo condition
tinha o valor online. A primeira parte do script processa cada elemento e designa o nome do elemento e qualquer valor para um atributo
condition a variáveis associadas.
O restante do script emite a saída do conteúdo de forma condicional com base no valor do atributo
condition. Se nenhum atributo condition
estiver presente ou se o atributo tiver um valor igual a print, o elemento de contenção será copiado para a saída do script. Se o atributo
condition tiver qualquer outro valor, o elemento associado é suprimido da saída e o processamento continua.
Para integrar facilmente um script como este a seu processo de produção de documentos, inclua-o na parte de um Makefile que produz documentação PDF ou PostScript.
Para fazer isso, esse script é usado para processar seu documento de entrada, redirecionando sua saída em um arquivo, que é então formatada de forma apropriada.
A Lista 2 mostra o mesmo script XSL, customizado para descartar elementos de conteúdo que têm um atributo
condition com um valor diferente de online. Incluir esse script em um Makefile destino para documentação on-line possibilita incluir elementos, como aquele em
exemplos de código anteriores como sendo somente on-line.
Lista 2. Script de Pré-processamento para Saída On-line
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xi="http://www.w3.org/2003/XInclude">
<xsl:output method="xml" omit-xml-declaration="yes" indent="yes"/>
<xsl:preserve-space elements="*"/>
<xsl:template match="*|@*">
<xsl:variable name="_element">
<xsl:value-of select="name()" />
</xsl:variable>
<xsl:variable name="_condition">
<xsl:value-of select="@condition" />
</xsl:variable>
<xsl:choose>
<xsl:when test="$_condition = ''">
<xsl:copy>
<xsl:apply-templates select="@* | * | text() | comment()" />
</xsl:copy>
</xsl:when>
<xsl:when test="$_condition = 'online'">
<xsl:copy>
<xsl:apply-templates select="@*|node()" />
</xsl:copy>
</xsl:when>
<xsl:otherwise>
<xsl:message> Skipping <xsl:value-of select="$_element"/></xsl:message>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
|
Uma comparação do código XSL na Lista 1 e Lista 2 mostra que são diferentes somente em uma única palavra, o que os torna bons candidatos para simplificação através do suporte para parâmetros (stringparam) fornecidos em XSL e, portanto, em
xsltproc. Deixo isso como um exercício, pois o objetivo desses exemplos era clareza, não um curso rápido sobre gravação de XSL elegante.
Incluindo Condicionalmente Fragmentos de Conteúdo
Os exemplos da seção anterior são bem adequados para incluir ou excluir elementos inteiros com base em um valor de atributo.
No entanto, a maioria da documentação XML com condição determinada também requer partes de determinação de condição do texto em outro elemento.
Mais comumente, pode ser necessário customizar conteúdo específico em um parágrafo.
Isso é geralmente feito de duas maneiras:
- Determinar a condição de elementos que podem aparecer em um parágrafo
- Usar o elemento
<phrase> para determinar condição de partes do texto em um parágrafo
Para determinar a condição de elementos que podem aparecer em um parágrafo, inclua o atributo que está sendo usado para determinação de condição e um valor apropriado para o elemento apropriado em um parágrafo.
Por exemplo, o fragmento de documento mostrado na
Lista 3 fornece um elemento com condição determinada
<mediaobject> em um parágrafo
(formatado para capacidade de leitura).
Lista 3. Um Elemento mediaobject com Condição Determinada
<para>
To create a new file, click the <emphasis
role="bold">Add</emphasis> icon
(<mediaobject>
<imageobject audience="online">
<imagedata fileref="add.gif"/>
</imageobject>
<imageobject audience="print">
<imagedata fileref="../../images/add.gif" />
</imageobject>
</mediaobject>)
beside the <emphasis role="bold">New File</emphasis> menu entry.
</para>
|
Apesar de usado principalmente como um exemplo aqui, determinar a condição de um elemento
<mediaobject> possibilita especificar diferentes caminhos para localizar o gráfico em diferentes formatos de apresentação.
Nesse caso, os documentos on-line localizam o gráfico no local centralizado para gráficos em um determinado servidor da Web ou servidor da Web virtual, enquanto documentos de impressão localizam o gráfico em um diretório específico para formatar propósitos.
Usar o elemento <phrase> para identificar seções de texto com condição determinada é um tanto quanto mais interessante.
Com o elemento
<phrase> , é possível identificar um intervalo ou amplitude específico de texto menor que um parágrafo e é perfeitamente adequado para determinação de condição do documento.
A Lista 4
(formatada para capacidade de leitura) mostra um exemplo de determinação de condição de uma única palavra para tornar a documentação mais específica para um determinado formato de apresentação.
Lista 4. Determinando a Condição de uma Única Palavra
<p>
See the
<link linkend="target-id">
introduction to this
<phrase audience="online">portion</phrase>
<phrase audience="print">chapter</phrase>
of the documentation
</link>
for more information.
</p>
|
Conclusão
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 fornecem um ambiente poderoso para criar e manter documentação. Os atributos e técnicas discutidos neste artigo facilitam a criação de documentação com condição determinada que pode conter conteúdo diferente previsto para públicos, sistemas de computador ou formatos de apresentação específicos.
Caso você inclua um estágio de pré-processamento simples ou configure variáveis para uso em seu processo de produção de documentação, é possível criar e manter documentação de fonte isolada que produz saída especializada.
Essa funcionalidade fornece uma solução eminentemente útil e flexível para o problema de documentação tradicional de simplificar desenvolvimento e manutenção de documentação enquanto ainda atende melhor os requisitos de conjuntos de usuários específicos dessa documentação.
Downloads | Descrição | Nome | Tamanho | Método de download |
|---|
| Sample XSL script for print output | conditional-print.zip | 1KB | HTTP |
|---|
| Sample XSL script for online output | conditional-online.zip | 1KB | HTTP |
|---|
Recursos Aprender
- Produzindo Documentação e Reutilizando Informações em XML, Parte 1: Publicação de Documento Usando XML (William von Hagen,
developerWorks, março de 2009): Monte facilmente um sistema de publicação XML em qualquer sistema
UNIX® ou Linux™. Combine pacotes de software livre gratuitos com XML para reutilização eficiente de informações e produza documentos em diversos formatos a partir de um conjunto de documentos de origem.
- 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.
- 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 faça 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 considere comprar uma cópia caso faça trabalho sério de publicação com DocBook.
- Atributos comuns: Consulte uma lista do conjunto comum de elementos XML DocBook.
- GML: Leia a entrada da Wikipedia sobre a Generalized Markup Language.
- Certificação em XML da IBM: 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.
- Livraria de tecnologia: Procure livros sobre XML, DocBook e outros tópicos técnicos.
- Podcasts do developerWorks: Ouça entrevistas e discussões interessantes para desenvolvedores de software.
Obter produtos e tecnologias
Discutir
Sobre o autor | | | William von Hagen é escritor e administrador de sistemas UNIX há mais de 20 anos e um defensor de Linux desde 1993. Bill é o autor ou coautor de livros sobre assuntos como Ubuntu Linux, Xen Virtualization, GNU Compiler Collection (GCC), SUSE Linux, Mac OS X, sistemas de arquivos Linux e SGML. Também escreveu diversos artigos para publicações e Web sites de Linux e Mac OS X. |
Avalie esta página
| 
