Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Introdução DocBook XML
Firebird home Firebird home Anterior: Preparando-se para escreverPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Ferramentas

DocBook XML - uma introdução

Uma introdução bem genérica a XML
Uma introdução ao DocBook XML

O formato escolhido para a documentação do módulo de manuais do Firebird é o DocBook XML. Para quem não é familiar com XML e / ou Docbook, seguem-se algumas introduções curtas ao XML em geral e DocBook XML em particular. Esteja avisado que estas introduções dão uma imagem grosseiramente simplificada. Mas está tudo bem: não é necessário ser um especialista em DocBook para escrever documentos para o Firebird. O necessário é algum conhecimento básico - o qual você pode depreender em meia hora dos parágrafos abaixo - e uma pequena experiência em aplicar tags do DocBook XML em seus textos (o qual você irá obter assim que começar a escrever).

Para pular a introdução ao XML se você não precisa saber nada sobre XML, tags, elementos, atributos, renderização e publicação multicanal

Pule ambas as introduções se já for um autor já experiente com o DocBook.

Nota

Embora nós fortemente insistamos que você ao menos tente entregar seu trabalho no formato DocBook, também sabemos que algumas pessoas não tem o tempo necessário para aprendê-lo (ou converter seus documentos existentes para DocBook). Se isso se aplica a você, por favor fale sobre isso na lista de discussão firebird-docs. Nós certamente não desejamos recusar documentação útil apenas porque não está no formato certo.

Uma introdução bem genérica a XML

XML é sigla de Linguagem de Marcação Extensível (a sigla está em inglês), o que na verdade significa texto puro com algumas tags de marcação. Um fragmento de texto em XML seria algo como:

<paragrafo>
<alto>'Nao!'</alto> ela gritou. <assustador>Mas a mao sangrenta
<italico>continuou rastejando</italico> em direcao a ela.</assustador>
<figura arquivo="bloody_hand.png"/>
</paragrafo>

Atributos e tags

No exemplo dado acima, as palavras e frases entre os sinais de “<” e “>” são tags de marcação. <italics> é uma tag inicial, </italico> é uma tag final, e <figura arquivo="bloody_hand.png"/> é uma tag isolada, cuja nomenclatura oficial é tag de elemento vazio. Tags em XML são sempre formatadas deste jeito:

Tabela 1. Formato das tags em XML

Tipo de Tag Inicia com Termina com
Tag inicial < >
Tag final </ >
Tag de elemento vazio < />

Ainda nos referindo ao exemplo, as palavras paragrafo, alto, assustador, italico e figura são nomes de tag. Na tag <figura.../>, archivo="bloody_hand.png" é chamado de atributo, com archivo sendo o nome do atributo, e bloody_hand.png sendo o valor do atributo. Os valores dos atributos devem sempre estar entre aspas, tanto faz aspas duplas ou simples.

XML permite que você defina do jeito que você desejar, desde que você as construa corretamente. Deste modo <estatag>, <aquelatag>, e <isto_nao_e_uma_tag/> são todas tags XML corretamente formadas. Por que eu disse “corretamente formadas” em vez de “válidas”? Por causa de que o termo “validar” só usado para algumas implementações especificamente definidas - como por exemplo o DocBook.

Obviamente as tags propriamente ditas não são para aparecer no documento final (isto é, aquele que é apresentado aos leitores). Em vez disso, ele contém instruções que afetam sua aparência. XML, quando usado para escrever documentação, é um típico formato fonte, criado para ser processado por software para produzir documentos de saída bem formatados. Este processo é chamado renderização.

Algumas tags são, sem sombra de dúvida, instruções de maquiagem:

<italico>continuou rastejando</italico>

significando que as palavras continuou rastejando sejam mostradas em itálico. Porém

<alto>Nao</alto>

é menos óbvio. Deve a palavra Não aparecer em negrito? Ou sublinhada? Ou mesmo em itálico? Ou talvez este texto é para ser lido em voz alta por sintetizador de discurso, e a tag <alto> o instrua a levantar a voz? Todas essas coisas são possíveis, e tem mais: freqüentemente um documento fonte em XML é convertido para diferente formatos de saída - exemplos: um arquivo PDF, uma página HTML ou mesmo um arquivo de som. Isto é chamado de publicação multicanal. Neste contexto, <alto> pode ser traduzido por negrito no formato PDF; para uma fonte com cor vermelha em negrito numa página web, e no sintetizador signifique um aumento de volume de 50%.

Olhando as outras tags, <figura.../> é obviamente uma instrução para inserir a imagem bloody_hand.png no documento, e <scary>, bem... essa aí é bem menos clara que <loud>. Talvez a frase entre as tags <scary> tenham que pingar sangue. Ou talvez alguma música assustadora tenha que ser tocada aqui. Isso tudo depende da pessoa que definiu as tags, e do software que eles usam para renderização.

A tag <paragrafo>, finalmente, é uma tag estrutural. Ela nos diz algo sobre o lugar que as linhas tem dentro da hieraquia interna do documento. No documento final, parágrafos podem ou não ser separados por linhas vazias. Novamente, tudo depende no software de renderização e possivelmente em alguma opção de configuração. Algumas outras tags estruturais que se pode pensar são, por exemplo, <capitulo>, <seção>, and <subdocumento>.

Caracteres especiais e Entidades

Por causa o caractere '<' tem um significado especiais como o início de uma tag, você não pode incluí-lo diretamente, como um valor literal. Em vez disso, se você deseja que os seus leitores possam vê-lo, você digita isso:

&lt;

É um '&', seguido pelas letras l e t (para menos que, em inglês), seguido de um ponto-e-vírgula. Você pode usar também &gt; (maior que) para o símbolo '>' embora não seja necessário.

XML tem montes de códigos como estes, eles são chamados entidades. Alguns representam caracteres, como &lt; e &uml; e alguns servem para outros propósitos completamente diferentes. Mas todos começam com um '&' e terminam com um ponto-e-vírgula.

Mas espere um minuto... Se um '&' marca o início de uma entidade, como você o inclui como um literal no seu texto? Claro que existe uma entidade para isso também:

&amp;

Então esta linha de XML:

Kernigan &amp; Ritchie escolheram '&lt;' como o operador menos-que
para o C.

virá no documento final como

Kernigan & Ritchie escolheram '<' como o operador menos-que para o C.

E aqui vão algumas boas notícias: se você usar algum editor especializado em XML para criar o seu documento, você provavelmente apenas precisará digitar '<' e '&' normalmente onde você gostaria que eles estivessem. O editor cuida para que saia exatamente como literal e não como um início de tag ou entidade no XML que será salvo no disco. Neste documento, você encontrará (mais adiante) algumas sugestões de editores de XML/DocBook.

Elementos

Tem mais um conceito importante de XML que você precisa conhecer: o elemento. O elemento é a combinação de uma tag inicial, uma tag final respectiva, e tudo que estier no meio. Esse “tudo que está no meio” é chamado de conteúdo do elemento, e pode incluir outros elementos. Elementos são nomeados de acordo com suas tags, de modo que podemos falar em elementos do parágrafo, elementos do itálico, etc.

Nota

Verdadeiramente, elementos são um conceito mais básico que as tags: as tags na verdade são coisas que identificam os elementos. Então é melhor dizer que as tags são nomeadas de acordo com seus elementos. Mas como as tags são mais fáceis de reconhecer que os elementos, eu acabei mostrando-as primeiro a você.

Isto é um elemento:

<alto>'Nao!'</alto>

Isto também é um elemento:

<paragrafo>Este e um elemento contendo <negrito>outro</negrito> 
  elemento!</paragrafo>

Tags de elemento vazio constituem um elemento por si mesmas. Esses elementos não possuem nenhum conteúdo, porque não possuem um par de tags:

<figura arquivo="bloody_hand.png"/>

Importante

Não confunda conteúdo com atributos. Conteúdo ficam entre tags e os atributos dentro das tags. O tag de elemento vazio do último exemplo possui um atributo, mas não possui conteúdo.

Estou insistindo no conceito de elementos por causa que grande parte da documentação tende a falar em “elementos do capítulo”, “elementos do título”, etc em vez de “tags de capitulo” ou “tags de título”. Embora estes termos possam ser intercambiáveis na maior parte do tempo, existem situalções onde é importante saber a diferença.

Conclusão do XML

Bom - isso é tudo que você necessita saber sobre XML. Agora você deve ter uma idéia geral de como um texto em XML se aparenta, o que são tags e elementos, e para quê eles existem. E como eu disse antes, a idéia é supersimplificada mas é suficiente para os nossos propósitos.

Deve-se entender também que escrever puramente em um XML auto-inventado é algo sem muito sentido a não ser que você tenha software que entenda e processe suas tags. Senão, como você vai tornar o seu XML em um documento bem formatado e apresentável?

Felizmente, não temos que nos preocupar em desenvolver nossas definições de elementos e software de conversão. Existem alguns tipos de XML formalizados, cada um definindo um número de tags e, igualmente importante, algumas regras sobre como usá-las. DocBook XML é um desses tipos.

Uma introdução ao DocBook XML

DocBook foi projetado tendo em mente a escrita de documentos estruturados usando SGML ou XML (mas não se preocupe com SGML - nós utilizamos a variante XML). É particularmente interessante para escrever livros técnicos e artigos, especialmente em assuntos relacionados a computadores. DocBook XML é definido em uma DTD (Document Type Definition ou Definição de Tipo de Documento): um conjunto de definições e regras descrevendo exatamente como um documento DocBook válido é estruturado. Este formato está se tornando um padrão de fato para documentos técnicos para computação, e é suportado por um crescente número de aplicações e ferramentas.

Características do DocBook XML

Características importantes do DocBook - ao invés de um XML genericamente - são:

  • A DTD do DocBook define um número limitado de tags, e dá regras exatas em como usá-las: quais atributos são válidos para a tag A, que elemento B pode ser aninhado dentro do elemento C, e por aí vai. Usando tags indefinidas, ou não seguindo as regras, seu documento não é DocBook mais (e as ferramentas que suportam o DocBook provavelmente não serão capazes de processá-lo sem erros)

  • As tags do DocBook trabalham com estrutura e semântica (significado), nunca cosmética. No DocBook, você achará tags estruturais como <book>, <part>, <chapter>, <section>, <para>, <table>; e tags semânticas como <filename>, <warning>, <emphasis>, <postcode>; mas nada como <font>, <bold>, <center>, <indent>, <backgroundcolor> – ou seja, nada que tenha a ver com layout ou cosmética.

  • Por causa disso, uma decisão deve ser tomada em como as tags do DocBook serão transfomadas em maquiagem apresentável. Esta decisão (ou melhor: as regras de renderização) poderiam ser codificadas direto nas ferramentas mas isso tornaria tudo muito inflexível. Este é o motivo pelo qual estas regras são definidas em folhas de estilo (stylesheets, no original). Uma folha de estilos é um documento, usualmente em texto puro, que diz às ferramentas coisas como:

    "Imprima os títulos dos capítulos numa fonte preta de 24 pontos; inicie cada capítulo numa nova página; use itálico para ênfase; renderize avisos com uma fonte vermelha 12 pontos, em negrito; use caixa baixa para acrônimos; etc,etc"

    Esta abordagem permite que o usuário altere as folhas de estilo se ele (ou ela) não gosta do resultado final na aparência do documento. Isto seria muito mais difícil - ou mesmo impossível - sem ter que alterar as próprias ferramentas

Benefícios do DocBook XML

DocBook tem uma monte vantagens para qualquer quem escreve documentação técnica. Embora nenhum desses benefícios seja único do DocBook, ele possui todos e é largamente suportado. Isto o faz a escolha perfeita para a nossa documentação do Firebird.

Cuidado

Esta lista de benefícios está ligeiramente diferente da versão original do autor.

Para nós, estas são as mais importantes:

  • A primeira vantagem do DocBook é inexistência de informação de apresentação. Com isso temos apenas estrutura e conteúdo, tornando o documento-fonte independente dos formatos a serem acessados pelos leitores finais.

  • Além disso, o fato de DocBook estar focado na estrutura do documento, torna a tarefa de transferir um rascunho de assuntos para a estrutura do documento final muito mais fácil.

  • DocBook é um padrão aberto. Com isso, um documento fonte pode gerar documentos finais em qualquer sistema operacional que tenha ferramentas disponíveis para isso. E também permite que um documento fonte seja gerado, por exemplo, em Mac OS X e tenha seus documentos finais renderizados em Windows. Ao baixar o módulo de manuais do Firebird, são incluídas ferramentas de renderização em PDF e HTML (tanto para Linux e Windows) - e no futuro poderemos abranger mais plataformas conforme seja necessário.

  • Integração simplificada com o CVS, uma vez que o DocBook é baseado em texto puro, com isso habilitando-nos a utilizar diversas funcionalidades do CVS que só são utilizáveis com texto puro.

  • Simplifica enormemente o gerenciamento da documentação, devido ao fato que as regras de renderização são centralizadas e com isso todos ganham. Ninguém necessita ficar seguindo regras chatas de formatação e as decisões sobre a identidade visual dos documentos ficam todas armazenadas nas stylesheets (folhas de estilos). Com isso todos ganham: os escritores se preocupam com o conteúdo e os gerentes da documentação com as regras de formatação e renderização.

Documentação sobre DocBook na Internet

Aqui estão alguns links em caso você deseje mais informações sobre o DocBook (todos em inglês):

  • http://opensource.bureau-cornavin.com/crash-course/

    Writing Documentation Using DocBook - a Crash Course por David Rugge, Mark Galassi e Eric Bischoff. Um ótimo tutorial, mesmo que a maior das ferramentas usadas não são as que nós usamos.

  • http://docbook.org/tdg/en/

    DocBook - The Definitive Guide, por Normam Walsh e Leonard Muellner. Não espere seja um tutorial para o iniciante - de fato, a primeira parte é meio assustador se você é um novato em DocBook. A razão do mesmo estar listado aqui é o fato de este site ser uma excelente referência online para os elementos.

  • http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/

    O DocBook Demystification Howto é interessante que caso você deseje conhecer um pouco mais sobre XML e DocBook do que é mostrado aqui. Possui também um monte de material sobre SGML, e - de novo - ferramentas que não são utilizadas no subprojeto de documentação do Firebird.

  • http://sourceforge.net/projects/docbook

    O projeto open source DocBook no SourceForge.

Se você conhece algum outra fonte de informação onlie, deixe-nos saber postando uma mensagem na lista de discussão firebird-docs

Anterior: Preparando-se para escreverPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Ferramentas
Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Introdução DocBook XML