Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Escrevendo seu documento
Firebird home Firebird home Anterior: FerramentasPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Outros aspectos da escrita

Escrevendo seu documento DocBook

Criando o documento
Digitando texto
Elementos que usamos freqüentemente

Alô - ainda conosco? Eu seu que gastei um bom tempo escrevendo sobre XML e DocBook, mas eu realmente sinto que era necessário - devido ao fato que esses conceitos são novos para muita gente. Apenas jogando alguns links e dizendo-os para se virarem por si mesmo certamente faria com que perdêssemos alguns escritores valiosos.

De qualquer modo, aqui estamos: finalmente prontos para escrever nossos documentos. Esta seção descreve como configurar seu documento DocBook, e aplicando as tags e atributos corretos nos lugares de direito.

Por favor leia a subseção sobre elementos hierárquicos mesmo que você seja um escritor DocBook experiente, pois contém algumas diretrizes específicas do nosso projeto. Depois disso, pode pular o resto da subseções sobre DocBook.

Criando o documento

Todo a nossa documentação é parte um grande elemento DocBook: o <set>. Este é o mais alto elemento na hierarquia DocBook. Nosso conjunto contém um número de livros (tag <book>), os quais contém capítulos (tag <chapter>), e por aí afora. A vantagem de pôr todos os livros em um único conjunto é que podem referenciar os outros, por exemplo, pode-se colocar links em sua documentação apontando para um determinado ponto em outro livro.

Felizmente, colocando todos os livros num único conjunto não implica em que eles tenham que estar em um único grande documento. DocBook permite que se possa configurar um documento principal como mostrado abaixo. (Não se preocupe se você não entende a seção iniciada com <!DOCTYPE - nós já temos um documento principal de modo que você não tem que escrever tal tipo de coisa horrível por você mesmo).

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
  "file:docbookx.dtd" [
    <!ENTITY firebird-intro SYSTEM "file:fbintro.xml">
    <!ENTITY firebird-sql-ref SYSTEM "file:fbsqlref.xml">
    <!ENTITY ...>
    <!ENTITY ...>
]>

<set id="firebird-books">
  &firebird-intro;
  &firebird-sql-ref;
  ...
  ...
</set>

Com o documento principal configurado, os vários outros livros podem estar em arquivos separados: fbintro.xml, fbsqlref.xml, etc., o quais podemos editar independentemente. Tal arquivo - o seu, por exemplo - é mais ou menos estruturado deste jeito:

<?xml version="1.0" encoding="UTF-8"?>

<book id="fbintro">
  <chapter id="fbintro-preface">
    ...
    ...
  </chapter>
  <chapter id="fbintro-installing-firebird">
    ...
    ...
  </chapter>
  ...
  ...
</book>    

É claro que você configurando um novo documento ele tem que ser colocado no conjunto principal, mas isso é algo que discutiremos quando você estiver preparado começar a escrever. (Não colocamos uma regra geral aqui por causa que isso depende do que você irá escrever - um livro, artigo, um ou alguns capítulos, ... - e como seu trabalho se encaixa no resto).

Todo documento DocBook tem que inicar com esta linha:

<?xml version="1.0" encoding="UTF-8"?>

Se você escreve sua documentação "na mão"; por exemplo, em um editor de texto, você deve digitar a linha acima. Se você usa um editor específico de XML, esta será inserida automaticamente no novo documento.

Você deve sempre colocar sua documentação na pasta src/docs/firebirddocs da árvore dos manuais - pelo menos se este estiver em inglês. Em documentos em outras línguas deve-se colocar o documento em pastas tipo src/docs/firebirddocs-fr, src/docs/firebirddocs-es, etc.

Digitando texto

Se você digitar seu texto DocBook XML em um editor tipo o Bloco de Notas, emacs ou ConText, você pode usar quebras de linha, endentação e múltiplos espaços do jeito que desejar. Cada ocorrência de whitespace (uma sequência de um ou mais caracteres space, tab, linefeed or formfeed) será convertida em um único espaço em branco na saída. Então isto:

<section><title>Arquiteturas do Firebird</title><para>Agora vamos dar
uma olhada nas diferentes arquiteturas do Firebird.</para><itemizedlist>
<listitem><para>Primeiro, existe a chamada arquitetura<firstterm>Classic
Server</firstterm>.</para></listitem><listitem><para>E também existe a
arquitetura <firstterm>Superserver</firstterm>.</para></listitem>
<listitem><para>E finalmente, com o lançamento do Firebird 1.5 nós
também temos o <firstterm>embedded server</firstterm>.</para></listitem>
</itemizedlist></section>

resulta na mesma saída disto:

<section>
  <title>Arquiteturas do Firebird</title>
  <para>Vamos dar uma olhada nas diferentes arquiteturas
    do Firebird.</para>
  <itemizedlist>
    <listitem>
      <para>Primeiro, temos a chamada arquitetura
        <firstterm>Classic Server</firstterm>.</para>
    </listitem>
    <listitem>
      <para>Entar temos a arquitetura
        <firstterm>Superserver</firstterm>.</para>
    </listitem>
    <listitem>
      <para>E finalmente, com o lançamento do Firebird 1.5 nós também
        temos o <firstterm>embedded server</firstterm>.</para>
    </listitem>
  </itemizedlist>
</section>

Não é necessário dizer, a segunda foma é muito mais fácil de ler e entender para um humanos. Então, se você digita seu XML na mão, formate o texto em uma forma que a estrutura seja tão clara quanto possível. Como os profetas disseram: "Indente! Indente! Indente!"

Se, na outra vertente, você usa um editor XML dedicado, pressionando Enter pode automaticamente fechar o <para> corrente e abrir um novo. Tenha certeza de como o seu editor se comporta, e use a tecla Enter de acordo. Verifique também o que acontece com múltiplos caracteres espaço em branco, porque certos editores XML podem user certos truques para preservá-los.

Elementos que usamos freqüentemente

Esta seção discute os elementos DocBook que nós mais usamos em nossos documentos do Firebird. Isso inclui montes de exemplos em formato DocBook XML. Se você usa uma ferramenta de elaboração XML, o que você vê na sua tela pode ser completamente diferente da maneira que aparece em nossos exemplos, mas se você abrir o arquivo XML em um editor de texto - ou escolher a visão de texto da sua ferramenta XML - você verá o XML por baixo. Você devia dar uma olhada nos fontes em XML que já estão no módulo de manuais, para ver como os outros autores criaram seus documentos e aplicam as tags.

Dica

Esta é uma longa seção, mas não deixe isso desencorajá-lo. Meu conselho é que você cuidadosamente leia a subseção em elementos hierárquicos, e folheie as outras. Não se preocupe se há coisas que você ainda não entende de uma vez, não tente decorar o material. Apenas tenha-o à quando você escrever seu documento, e revisite as subseções de vez em quando (tipo "quando você precisar dele").

Elementos Hierárquicos

A hierarquia mais comum, partindo do topo: <set><book><chapter><section><para>. Elementos de seção são um pouco diferentes do resto, por haver dois sabores deles:

  • O elemento <section> como colocado acima. Ele pode ser usado recursivamente; por exemplo, você pode ter uma <section> dentro de uma outra <section> e daí por diante. Este sabor tem a vantagem de que você pode mover subárvores para cima ou abaixo sem ter que mudar as tags

  • E também existe a faixa de <sect1>, <sect2> ... <sect5>. Esses elementos devem ser devidamente aninhados, com o <sect1> no topo, <sect2> dentro <sect1> e assim por diante. Não se pode colocar <sect3> diretamente dentro de <sect1>. É menos flexível que <section>, mas raramente isso causa problemas na prática. Afinal, a mesma "rigidez" também se aplica a <set>, <book> e <chapter>, e nós conseguimos viver com isso sem problemas.

Nota

Em versões anteriores deste documento, a série <sectN>, nos recomendávamos por razões de apresentação. Devido à melhores nas folhas de estilo, tais razões não mais se aplicam. Siga o estilo que melhor lhe convier.

Livros, capítulos e seções de topo devem sempre possui um id e um title (um identificador e um título, respectivamente). O id permite que o elemento seja referenciado de uma outra parte do documento, e até mesmo de outros documentos no mesmo conjunto. Id é um atributo, o que significa que aparece dentro de uma tag; não é visível nos documentos renderizados (exceto no texto fonte do HTML; mais ainda, os identificadores da seção de alto nível são utilizados para nomear os arquivos HTML). Title é um elemento, geralmente o primeiro elemento-filho a ser achado no pai. O conteúdo of elemento título aparecerá nos documentos gerados.

Se você for rescrever um livro ou artigo, é também uma boa idéia incluir um elemento <bookinfo> ou <articleinfo>, onde você pode a informação de autor (e mais coisas).

Eis um exemple de como estruturar seu documento:

<?xml version="1.0" encoding="UTF-8"?>

<book id="usersguide">

  <bookinfo>
    <title>Guia do Usuário do Firebird </title>
    <author>
      <firstname>William</firstname>
      <surname>Shakespeare</surname>
    </author>
  </bookinfo>

  <chapter id="usersguide-intro">
    <title>Introdução</title>
    <para>Alô! Este é texto introdutório do Guia do Usuário 
      do Firebird.</para>
  </chapter>

  <chapter id="usersguide-download-install">
    <title>Baixnado e instalando o Firebird</title>
    <para>Neste capítulo iremos demonstrar como baixar e instalar
      o Firebird.</para>
    <section id="usersguide-download">
      <title>Baixando o Firebird</title> 
      <para>Para baixar o Firebird, você deve ir primeiro na seguinte 
        URL:etc etc etc</para>
      <!-- ...mais parágrafos, possivelmente mais subseções... -->
    </section>
    <section id="usersguide-install">
      <title>Instalando o Firebird</title>
      <para>Instalação do Firebird no seu sistema será deste jeito: etc
        etc etc.</para>
      <!-- ...mais parágrafos, possivelmente mais subseções... -->
    </section>
  </chapter>

  <!-- ... mais capítulos... -->

</book>

Algumas regras e comentários:

  • Primeiro, note de novo que valores de atributos sempre devem estar entre aspas. (Mas se você os preencher em editor de atributos, não as coloque: o editor cuidará desse detalhe).

  • O title (título) de um livro ou artigo deve aparecer no próprio elemento book (livro) ou article (artigo). É até legal incluir em ambos, mas nesse caso os dois title's (títulos) devem possui o mesmo conteúdo. Em outras palavras: fique com one ou outro, não ambos, se quizer evitar encrenca.

  • Todos atributos id devem ser únicos dentro do mesmo conjunto de livros. Note que versões em diferentes linguagens estão contidas cada uma em seu próprio conjunto, é perfeitamente possível manter as id iguais aos originais.

  • Dentro de um livro ou artigo, todos os id's (identificadores) devem começar com a mesma paravra em minúsculas; por exemplo, usersguide, seguida de um traço, seguido por uma ou mais paravras em minúsculas. Exemplos são usersguide-intro e usersguide-download-install. Esta não é um requisito do DocBook, mas nossa própria convenção.

  • Como você pode ver no exemplo, chapter's e section's (capítulos e seções, respectivamente) podem iniciar diretamente com um ou mais elementos para. Mas uma vez que você inclua seções num capítulo, ou subseções numa seção, você não pode adicionar mais elementos para depois deles, somente dentro deles. Bom editores com suporte a DocBook simplesmente não permitir que você cometa tal erro, mas caso você digite seu XML do DocBook na mão isso é algo que você precisa ficar atento.

  • Se você utiliza um editor de XML,é bem provável que você raramente tenha que criar os elementos explicitamente. Por exemplo, se você inserir um chapter ou uma section (um capítulo ou uma seção, respectivamente) no XMLMind XML Editor, o primeiro para parágrafo vazio é automaticamente criado. E quando você digita texto em um parágrafo e pressiona ENTER, esse parágrafo é automaticamente fechado e um novo é criado.

Pule o resto das subseções sobre elementos DocBook se você já conhece tudo sobre elementos do DocBook.

Listas

DocBook oferece vários elementos de listas, dos quais são usados freqüentemente:

itemizedlist

Uma itemizedlist é usada para enumerar items cuja ordem não é muito importante:

<itemizedlist spacing="compact">
  <listitem><para>Laranjas são suculentas</para></listitem>
  <listitem><para>Maçãs supostamente são saudáveis</para></listitem>
  <listitem><para>A maioria das pessoas acham o limão muito
    ácido</para></listitem>
</itemizedlist>

Os items na lista são geralmente marcados com um marcador nos documentos de saída:

  • Laranjas são suculentas

  • Maçãs supostamente são saudáveis

  • A maioria das pessoas acham o limão muito ácido

orderedlist

Use uma lista ordenada (tag <orderedlist>) quando se deseja forçar a ordem entradas:

<orderedlist spacing="compact" numeration="loweralpha">
  <listitem><para>Sumérios 3300 AC - 1900 AC</para></listitem>
  <listitem><para>Império Assírio 1350 AC - 612 AC</para></listitem>
  <listitem><para>Império Pérsio 6º século AC - 330 AC</para>
  </listitem>
</orderedlist>

Por padrão, numerais arábicos (1, 2, 3, ...) serão colocados antes dos items, mas você pode mudar isso com o atributo numeration. Saída:

  1. Sumérios 3300 AC - 1900 AC

  2. Império Assírio 1350 AC - 612 AC

  3. Império Pérsio 6º século AC - 330 AC

procedure

Um procedimento (tag <procedure>) é freqüentemente renderizado como uma lista ordenada (tag <orderedlist>), mas com uma semântica diferente: um procedimento denota uma seqüência de passos a serem executados numa dada ordem:

<procedure>
  <step><para>Arrombe a fechadura</para></step>
  <step><para>Roube a casa</para></step>
  <step><para>Seja preso</para></step>
</procedure>

Aqui está a saída:

  1. Pick the lock

  2. Rob the house

  3. Get arrested

Dentro de um passo você pode incluir um elemento subpasso (tag <substep>), o qual pode conter mais passos.

variablelist

Uma lista variável (tag <variablelist>) é feita de entradas de lista variável (tag <varlistentry>), cada uma das quais possuem um termo (tag <term>) seguido de um item de lista (tag <listitem>):

<variablelist>
  <varlistentry>
    <term>Tag</term>
    <listitem>
      <para>Uma peça de texto entre um '<' e um '>'</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Element</term>
    <listitem>
      <para>Uma tag inicial, uma tag final correspondendo e tudo
        entre elas</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Coteúdo de um elemento</term>
    <listitem>
      <para>Tudo dentro das tags correspondentes</para>
    </listitem>
  </varlistentry>
</variablelist>

A lista que você está vendo agora, enumerando os diferentes tipos de listas, é uma lista variável com os nomes dos elementos (itemizedlist, orderedlist, etc.) como termos. A próxima seção, sobre links, também consiste de uma sentença introdutória seguida de uma lista variável.

Links

Você pode criar hiperlinks para alvos no seu próprio documento, em outro documento no mesmo conjunto ou na internet.

link

link é o elemento genérico que aponta para qualquer local no conjunto de documentos. O atributo linkend sempre deve estar presente; seu valor deve ser o id de um alvo de link (o elemento para o qual se irá saltar).

Clique <link linkend="docwritehowto-introduction-pt_br">aqui</link>
para saltar para a introdução.

No documento renderizado, a palavra "aqui" ficará quente, o que significa um link clicável apontando para a introdução.

Clique aqui para pular a introdução.

Cuidado

Embora você possa usar a tag link para apontar para qualquer elemento no conjunto inteiro, você só deve fazê-lo se o alvo do link estiver estiver no mesmo documento PDF que o próprio link. A versão em HTML é pode ser totalmente hiperlinkada, mas links na versão em PDF não podem ser feitos para fora do mesmo documento. Nossos PDFs tipicamente contém um livro (tag book) ou artigo (tag article); se o alvo está fora do documento corrente, use a tag ulink em de link. (veja abaixo)

Nota

Como você já deve ter percebido, a região clicável é por vezes recuada com respeito ao texto do link. Isso é um problema conhecido no Apache FOP, não havendo muito que possamos fazer a respeit.

ulink

Use um ulink para linkar para um recurso na Internet. O atributo url é obrigatório:

Clique <ulink url="http://docbook.org/tdg/en/">neste link</ulink> para
ler o O Guia Definitivo para DocBook.

As palavras “neste link” aparecerão como um hiperlink para http://docbook.org/tdg/en/, assim:

Clique neste link para ler O Guia Definitivo para DocBook.

email

Você pode fazer um link para email com um ulink, porém é mais fácil usando o elemento email. Este irá mostrar o endereço de email como texto clicável na saída. Esta linha de XML:

Envie mensagem para
<email>[email protected]</email> para 
assinar.

resulta na seguinte saída: "Envie mensagem para para se assinar."

Se você deseja que o texto clicável seja diferente do próprio endereço de email, use um ulink com uma URL mailto:.

Atenção

Se você incluir links para endereços de email - seja com email ou com ulink - ou mesmo se você apenas mencioná-los no seu texto, e seu documento é subseqüentemente publicado na Internet, esses endereços de email serão expostos a robôs de exploração usados por spammers. De modo que será previsível um aumento de spam nesses endereços. Tenha sempre certeza que os donos dos endereços concordam em tê-los publicados na internet!

anchor

Um anchor (âncora) é um elemento vazio marcando um local exato dentro de um documento. Ele não é mostrado no texto que seus leitores lêem, mas podem ser usados como alvos para links. Isto é útil se você deseja linkar para um local qualquer no meio de um grande parágrafo.

<para id="lost-at-sea">
  Blah blah blah...
  e algo mais....
  e então algo...
  Agora aqui está um lugar interessante no parágrafo que eu quero ser
  capaz de linkar:
  <anchor id="captain-haddock"/>Aí está!
  Drones de parágrafo ligados...
  e ligados...
  e ligados...
</para>

Tendo colocado a âncora, você pode criar um link para ela:

<link linkend="captain-haddock">Vá para o lugar interessante</link> 
nesse longo, longo parágrafo.

Se você linkar para um elemento curto, ou para o início de um elemento, é mais fácil dar ao dito elemento uma id e usá-la como alvo do link.

Listagens de programas, telas, layout literal e exemplos

programlisting

Se você incluir fragmentos de código no seu documento, coloque-os num elemento programlisting (listagem de programa). Tudo que você digitar será renderizado como estiver escrto, incluindo quebras de linhas, espaços em branco, etc. E além disso, uma fonte de tamanho fixo será utilizada nos documentos renderizados. O termo "listagem de programa" pode interpretado de forma abrangente aqui: você pode usá-lo para fragmentos de SQL ou exemplos de DocBook XML. Este documento - especialmente na seção sobre elementos, a qual você está lendo agora - é cheia de programlisting's de modo que você já viu como elas se parecem:

Programlistings são renderizadas deste jeito.

Importante

Em listagens de programas (tag programlisting) você deve limitar o tamanho da linha por volta de 70 caracteres, caso contrário o texto sairá das margens quando renderizado em PDF. A mesma regra vale para outros elements que preservam layout como screen, literallayout, etc.

screen

Use um elemento screen (tela) para mostrar o que o usuário vê ou deverá ver numa tela de computador em modo texto, ou numa janela de terminal. Aqui também, seu layout será preservado e uma fonte de tamanho fixo será usada, mas a semântica é diferente. Ela pode ou não ter aparência diferente de uma listagem de programa na saída. Este é um exemplo curto, mostrando o que acontece se você tentar gerar um alvo não existente na árvore de manuais:

<screen>
D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.
</screen>

E aqui como isso é renderizado:

D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.
literallayout

literallayout, assim como screen e programlisting, mantém seu layout intacto, mas geralmente não muda a fonte - a não ser que você altere o atributo class para "monospaced". É também mais genérico que os outros dois anteriores no contexto de que não há nenhum significado atrelado a seu conteúdo - você pode colocar qualquer tipo de texto aqui o qual você deseje preserver o layout.

Exemplo de fonte:

<literallayout>
The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

  -- William Blake
</literallayout>

Saída:

The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

  -- William Blake

Nota

Nas versões anteriores deste documento, você era avisado para não usar a variante com fonte de tamanho não fixo de literallayout, porque ficava horrível a aparência na saída em PDF. Mas o problema já foi resolvido, como você pode ver nos PDFs.

example

Um example é um exemplo formal com um título. Geralmente se dá um id ao mesmo para possa ser referenciado de outros lugares no documento. Um índice de exemplos é gerado automaticamente quando o documento é renderizado. Você freqüentemente encontrará programlisting's em um exemplo, mas este pode conter screens, paras, listas, etc.

Eis um exemplo de um example:

<example id="docwritehowto-sql-example">
  <title>Um exemplo SQL</title>
  <para>Com este comando você pode listar todos os registros na tabela
    COUNTRY:</para>
  <programlisting>SELECT * FROM COUNTRY;</programlisting>
</example>

Na saída terá o seguinte aspecto:

Exemplo 1. Um exemplo de SQL

Com este comando você poderá listar todos os registros na tabela COUNTRY:

SELECT * FROM COUNTRY;

Se você deseja um exemplo sem um título obrigatório, use um informalexample (exemplo informal). Exemplos informais são também deixados de fora do índice de exemplos.

Tabelas

Se você já fez alguma vez uma tabela HTML para um website, você não terá muita dificuldade em criar tabelas no DocBook. Existem diferenças porém, e as tabelas do DocBook são bem ricas.

Uma <table> (tabela) consiste de um <title> (título) e um ou mais <tgroup>'s - mas geralmente apenas um. O elemento <tgroup> é obrigatório e tem um atributo obriagatório: cols. Você deve setar esse atributo com o número de colunas no <tgroup>. Dentro de um <tgroup> você pode colocar os elemento <thead>, <tfoot> e <tbody>. Cada um desses tem um ou mais <row>'s, os quais podem ter tantos <entry>s (células) quanto forem necessários para chegar ao número de colunas do atributo cols. (Você pode combinar células criando spans, mas eu não entrarei nesse mérito).

Tanta coisas para uma estrutura básica. Agora mostraremos um exemplo; primeiro em fonte DocBook XML, e depois a tabela resultante no documento de saída renderizado. Não se preocupe com os <colspec> por enquanto; estes são subelementos opcionais usados para ajustes finos:

<table id="docwritehowto-table-dboftheyear">
  <title>Pesquisa LinuxQuestions.org: Banco de dados do ano de
    2003</title>

  <tgroup cols="3">
    <colspec align="left" colname="col-dbname" colwidth="2*"/>
    <colspec align="right" colname="col-votes" colwidth="1*"/>
    <colspec align="right" colname="col-perc" colwidth="1*"/>

    <thead>
      <row>
        <entry align="center">Banco de Dados</entry>
        <entry align="center">Votos</entry>
        <entry align="center">Porcentagem</entry>
      </row>
    </thead>

    <tfoot>
      <row>
        <entry>Total</entry>
        <entry>1111</entry>
        <entry>99.99</entry>
      </row>
    </tfoot>

    <tbody>
      <row>
        <entry>MySQL</entry>
        <entry>405</entry>
        <entry>36.45</entry>
      </row>
      <row>
        <entry>Firebird</entry>
        <entry>403</entry>
        <entry>36.27</entry>
      </row>

      ... e mais 5 linhas não mostradas aqui....

    </tbody>
  </tgroup>
</table>

E aqui a tabela resultante:

Tabela 2. Pesquisa LinuxQuestions.org: Banco de Dados of ano de 2003

Banco de Dados Votos Porcentagem
Total 1111 99.99
MySQL 405 36.45
Firebird 403 36.27
Postgres 269 24.21
Oracle 25 2.25
Berkeley DB 4 0.36
Sybase 3 0.27
DB2 2 0.18

A propósito, esses são resultados atuais de uma pesquisa real no LinuxQuestions.org. Como você pode ver, faltaram 3 votos para o Firebird vencer a pesquisa. Se você conhece essas pessoas, por favor reporte-as ao seu Inquisitor Chefe. Ele gostaria de ter uma pequena, ahhh... humm... conversa com eles. ;-)

Tabelas são automaticamente indexadas. Uma <informaltable> (tabela informal) tem a mesma estrutura de uma <table> mas não requer um título e não será colocada no índice. (Tal como no caso do <example>/<informal example>). Se você deseja aninhar tabelas, use uma <table>/<informaltable> dentro de uma <entry>, ou uma <entrytbl> em vez de uma <entry>.

Tabelas possuem muitas outras funcionalidades além das mostradas aqui, mas essas nós deixaremos para você as explorar.

Avisos

DocBook tem muitas tags para marcar um bloco de texto como uma nota, aviso, dica, etc. Na saída tais blocos tipicamente aparecem indentados, e marcados com um ícone ou palavra para denotar seu propósito. Estas tags são, em ordem alfabética:

<caution>, <important>, <note>, <tip> e <warning>

Usarei uma <tip> em um exemplo; as outras funcionam exatamente do mesmo jeito:

<tip>
  <para>Se você inserir um elemento caution, important, note, tip ou
    warning no seu texto, não inicie o mesmo com as palavras advertência,
    importante, nota, dica ou aviso, porque essas palavras geralmente
    são geradas automaticamente pelo programa de renderização.</para>
</tip>

E este é o resultado:

Dica

Se você inserir um elemento caution, important, note, tip ou warning no seu texto, não inicie o mesmo com as palavras advertência, importante, nota, dica ou aviso, porque essas palavras geralmente são geradas automaticamente pelo programa de renderização.

Você deve ter notado que as palavras important, caution etc têm aparência diferente do resto do texto da dica. Como? Bem, para dizer a verdade, eu as coloquei entre tags especiais (as primeiras com <sgmltag>'s, nas segundas com <literal>'s) para fazê-las aparecerem diferente do resto do texto. Mas aí o fonte em XML ficaria muito poluído, então eu decidi tirá-las do código exemplo que apresentei a você.

Se você destacar um bloco de texto daquilo que o circunda sem marcá-lo como uma dica ou o que seja, use a tag <blockquote>.

Vários elemento em linha

Para concluir a subseção sobre elementos do DocBook, agora eu falarei sobre um certo número de elementos em linha. Eles são chamados “em linha” porque não interrompem o fluxo do texto. Se você usa (por exemplo) um elemento emphasis:

<emphasis>Em hipótese alguma</emphasis> me chame de gordo de novo!

o resultado será:

Em hipótese alguma me chame de gordo de novo!

A expressão "Em hipótese alguma" está enfatizada, mas mantém-se no seu lugar na sentença. Nós já encontramos alguns elementos em linha antes: os vários tipos de links. Outros elementos - como table, warning, blockquote e programlisting - são todos mostrados como um bloco, aparte do texto em volta (mesmo que você os coloque "em linha" no seu fonte em XML). Não é muito surpreendente que sejam chamados de elementos de bloco. Elementos de bloco freqüentemente possui elementos em linha; o inverso não é possível.

Ok, vamos começar a experimentar esses elementos em linha. Incluirei exemplos - tanto como fonte XML e saída renderizada - para a maior parte deles:

filename - command - application - envar

Use a tag filename para marcar nomes de arquivos no mais abrangente sentido. Atributos podem opcionalmente indicar que o mesmo é um arquivo de cabeçalho, um diretório, etc.

Coloque seu documento no subdiretório<filename
class="directory">src/docs/firebirddocs</filename>.

Na saída lê-se:

Coloque seu documento no subdiretório src/docs/firebirddocs.

command e application são ambos usados para programas executáveis. command é geralmente escolhido para programas menores e comandos internos; seu conteúdo deve ser o comando exato de disparado em uma linha de comando; application é usado para programas maiores e não precisa ser o nome do arquivo executável. Ambos podem se referir ao mesmo programa.

Digite <command>netscape&amp;</command> numa janela de terminal para
iniciar o <application>Netscape Navigator</application>.

Isto é renderizado como:

Digite netscape& numa janela de terminal para iniciar o Netscape Navigator.

envar denota uma variável de ambiente.

subscript - superscript

(subscrito - sobrescrito)

Fazem o que é esperado:

Após inventar a fórmula e = mc<superscript>2</superscript>, eu
realmente tive vontade de um copo de H<subscript>2</subscript>O
líquido!

Saída: Após inventar a fórmula e = mc2, eu realmente tive vontade de um copo de H2O líquido!

varname - constant - database

O uso de varname e constant (nome de varíavel e constante - respectivamente) deve ser óbvio. A tag <database> não é só para bancos de dados, mas também para objetos do banco de dados:

A tabela <database class="table">COUNTRY</database> tem dois campos:
<database class="field">COUNTRY</database> e
<database class="field">CURRENCY</database>.

Saída: A tabela COUNTRY tem dois campos: COUNTRY e CURRENCY.

function - parameter - returnvalue

(função, parâmetro e valor de retorno - respectivamente)

Esses três falam por si mesmos, eu confio.

A função <function>log</function> tem os parâmetros
<parameter>a</parameter> e <parameter>b</parameter>.

Saída: A função log tem os parâmetros a e b.

prompt - userinput - computeroutput

Nota

do Tradutor: prompt será usado no original, seu significado no caso poderia ser indicação de prontidão – tradução que realmente ajuda. userinput é entrada do usuário e computeroutput é saída do computador.

prompt é usado para uma string que indica que o usuário deve entrar algum texto; userinput refere-se ao texto entrado pelo usuário (não necessariamente num prompt); computeroutput é texto exibido pelo computador:

Digite <userinput>convidado</userinput> no prompt
<prompt>login:</prompt> e o servidor irá saudá-lo com um
<computeroutput>Bem-vindo, usuário convidado</computeroutput>.

Saída: Digite convidade no prompt login: e o servidor irá saudá-lo com um Bem-vindo, usuário convidade.

keycap

O texto de uma tecla do teclado, ou o seu nome comum:

Pressione a tecla <keycap>Del</keycap> para apagar a mensagem, ou 
<keycap>ESPAÇO</keycap> para movê-la.

Saída: Pressione a tecla Del para apagar a mensagem, ou SPACE para movê-la.

sgmltag

Este elemento foi usado extensivamente durane este docuemento: ele marca tags, elementos, atributos, entidades, etc de SGML e XML :

Se é um diretório, ajuste o atributo
<sgmltag class="attribute">class</sgmltag> do elemento 
<sgmltag class="element">filename</sgmltag> para to
<sgmltag class="attvalue">directory</sgmltag>.

Saída: Se é um diretório, ajuste o atributo class do elemento filename para directory.

Outros possíveis valores de para sgmltag.class são: starttag, endtag, emptytag e genentity (para uma entidade).

emphasis - citetitle - firstterm

(ênfase - título de citação - primeiro termo)

Use emphasis para enfatizar palavras em geral, citetitle para títulos de livro etc, e firstterm se você introduzir um novo conceito ou palavras para os seus leitores:

Nós usamos <firstterm>DocBook XML</firstterm> para nossa documentação 
do Firebird. Uma introdução curta segue;
<emphasis>por favor</emphasis> leia-a cuidadosamente! Se você deseja
saber mais sobre o assunto, compre <citetitle>DocBook – The Definitive 
Guide</citetitle>.

Saída: Nós usamos DocBook XML para nossa documentação do Firebird. Uma introdução curta segue; por favor leia-a cuidadosamente! Se deseja saber mais sobre o assunto, compre DocBook – The Definitive Guide.

quote - literal

(citação - literal)

Use quote para uma citação em linha (ao oposto de um blockquote). Caracteres aspas serão inseridas automaticamente. Usando quote ao invés de digitando as aspas por você mesmo (o que é perfeitamente legal) tem a vantagem de que nós podemos alterar o tipo de aspas através das folhas de estilo se nós quisermos.

Um literal é um fragmento de texto ou palavra para ser lido literalmente. É um elemento bem genérico, freqüentemente usado para fazer certas palavras se destacarem tipograficamente:

A qualquer custo evite usar a palavra <literal>monstruoso</literal> 
em sua documentação.

Saída: A qualquer custo evite usar a palavra monstruoso em sua documentação.

Você deve usar esses elementos em linha onde você puder? Bem, se o fizer, certamente fará o seu documento ficar mais rico; fará com que seja fácil procurar por nomes de arquivos por exemplo, ou gerar um índice de todas aplicações mencionadas em seu documento. Por outro lado, existem tantos desse elementos semânticos (de fato nós discutimos apenas uns poucos deles) que se você aplicar todos em todo lugar que você possa, provavelmente ficará maluco antes de terminar o documento. Não é isso que desejamos: se você realmente tiver que ficar doido, por favor faça-o depois de terminar seu documento. ;-)

Então, como um conselho geral: vá devagar com esses elementos; use-os toda vez que você achar que fazem sentido, mas não exagere.

Para empacotar os elementos

Você deve ter notado que os documentos renderizados (você está lendo um agora, a não ser que você tenha aberto a versão XML) muitos diferentes elementos têm a mesma aparência: um filename, um literal e uma application têm exatamente a mesma tipografia; o mesmo valendo para emphasis, firstterm e citetitle.

Então, qual é o sentido de todas essas tags diferentes? Por que não usar umas poucas, tipo emphasis e literal, se todos aparacer da mesma maneira? Bem, há duas boas razôes para não fazer isso:

  • Primeiro, se nós deixarmos de usar a maior parte de nossos elementos em linha em favor de, por exemplo, emphasis e literal, a semântica seria perdida. E lembramos que o DocBook XML é todo sobre estrutura e semântica. firstterm e citetitle podem parecer a mesma coisa uma vez renderizado, mas eles não são a mesma coisa. O fonte em XML sabe disso, apesar não mostrar sempre. Esta informação é útil, e não queremos perdê-la.

  • Além disso, nós podemos adaptar nossas folhas de estilos para cada de elemento individualmente. Assim que decidirmos que um firstterm deva ter aparência diferente de um citetitle, nós arranjamos isso - mas somente se eles forem marcados com tags diferentes, não se eles forem ambos emphasis no fonte em XML.

Isso conclui as seções no DocBook. Com o conhecimento apresentado acima, você deve saber o suficiente para elaborar documentos em DocBook XML para o projeto Firebird. Claro que se você usar um editor de XML dedicado - o que é altamente recomendado - você deve consultar a documentação do mesmo para aprender como usá-lo; o que é uma que este documento não cobre.

Anterior: FerramentasPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Outros aspectos da escrita
Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Escrevendo seu documento