<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>

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:

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>.

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:

É 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 < e ¨ 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:

Então esta linha de XML:

Kernigan & Ritchie escolheram '<' 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.

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.

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"/>

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.

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.

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

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.

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

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

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