4.2. DocBook

4.2.3.1. Starting a book

O conteúdo desse livro está contido dentro do elemento <livro>.Assim como podendo conter marcação estruturada, esse elemento pode conter elementos que incluam informações adicionais sobre livro. Isso é meta-informação, usado para referência, ou é conteúdo adicional usado para produzir uma página de título.

Essas informações adicionais devem estar contidas dentro do elemento <bookinfo>.

<book>
  <bookinfo>
    <title>Seu título aqui</title>
    
    <author>
      <firstname>Seu primeiro nome aqui</firstname>
      <surname>Seu sobrenome</surname>
      <affiliation>
        <address><email>Seu endereço de correio eletrônico aqui</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:seu endereço de e-mail">Seu nome</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Inclua um resumo do conteúdo do sua livro aqui.</para>
    </abstract>
  </bookinfo>

  ...

</book>

4.2.3.2. Começando um artigo

O conteúdo do artigo deve estar contido dentro do elemento <article>.Assim como contém marcação estruturada, esse elemento pode conter elementos que incluam informações adicionais sobre o artigo. Isso ou é meta-informação, usado para referência, ou é conteúdo adicional usado para produzir uma página de título

Essas informações adicionais devem estar contidas dentro de <articleinfo>.

<article>
  <articleinfo>
    <title>Seu título aqui</title>
    
    <author>
      <firstname>Seu primeiro nome</firstname>
      <surname>Seu sobrenome</surname>
      <affiliation>
        <address><email>Seu endereço de e-mail</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:seu endereço de e-mail">Seu nome</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Inclua um resumo do conteúdo do artigo aqui.</para>
    </abstract>
  </articleinfo>

  ...

</article>

4.2.3.3. Indicando capítulos

Use <chapter> para marcar seus capítulos. Cada capítulo tem obrigatóriamente um <title>. Artigos não contém capítulos, estes são reservados para os livros.

<chapter>
  <title>Título do capítulo</title>

  ...
</chapter>

Um capítulo não pode ser vazio; este precisa conter elementos além do <title>. Se você precisar incluir um cápitulo vazio então você precisa incluir um parágrafo vazio.

<chapter>
  <title>Isto &eacute; um cap&iacute;tulos vazio</title>

  <para></para>
</chapter>

4.2.3.4. Sessões abaixo dos capítulos

Em livros, capítulos podem (mas não é obrigatóriamente necessário) ser quebrados em sessões, sub-sessões, e assim por diante, sessã o é o principal elemento de estrutura, e cada artigo deve conter pelo menos uma sessão. Use o elemento <sectn>. O n indica o número da seção que identificam o nível da seção.

A primeira <sectn> é <sect1>. Você pode ter uma ou mais desta em um só capítulo. Elas podem conter um ou mais elementos <sect2>, e assim por diante, até <sect5>.

<chapter>
  <title>A sample chapter</title>

  <para>Algum texto dentro do capítulo</para>

  <sect1>
    <title>Primeira sessão (1.1)</title>

    ...
  </sect1>

  <sect1>
    <title>Seunda sessão (1.2)</title>

    <sect2>
      <title>First sub-section (1.2.1)</title>

      <sect3>
        <title>Primeira sub-sessão (1.2.1)</title>

        ...
      </sect3>
    </sect2>

    <sect2>
      <title>Primeira sub-sub-sessão (1.2.1.1)</title>

      ...
    </sect2>
  </sect1>
</chapter>

4.2.3.5. Subdividindo usando <part>s

Você pode introduzir outra camada de organização entre <book> and <chapter> com uma ou mais <part>s. Isso não pode ser feito em um <article>.

<part>
  <title>Introdução</title>

  <chapter>
    <title>Visão geral</title>

    ...
  </chapter>

  <chapter>
    <title>O que é FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>História</title>

    ...
  </chapter>
</part>

4.2.4.1. Parágrafos

DocBook suporta três tipos de parágrafos: <formalpara>, <para>, and <simpara>.

Na maioria das vezes você só vai precisar usar <para>. <formalpara> inclui um elemento <title>, e <simpara> desabilita alguns elementos dentro de <para>. Fique com o <para>.

<para>Isso é um parágrafo.
          E pode conter quase qualquer outro elemento.</para> 

4.2.4.2. Bloco de citações

Um bloco de citação é uma longa citação de um outro documento que não deveria aparecer no parágrafo corrente. Não é usado com muita frequência.

Bloco de citação podem opcionalmente conter um título e uma atribuição ((ou eles podem ser deixados sem atributos)

<para>A small excerpt from the US Constitution;</para>
              
<blockquote>
  <title>Preâmbulo da constituição dos Estados Unidos.</title>

  <attribution>Copiado de um site qualquer</attribution>
            
  <para>Nós, povo dos Estados Unidos, com o objetivo de
  fazer uma união mais perfeita, estabelecer justiça,
  garantir tranquilidade doméstica, promover uma defesa comum, promover 
  bem estar geral, assegurar as benções da
  liberdade para nós mesmos e nossa posteridade, organizamos  e
  estabelecemos essa constituição para os estados Unidos
  da América.</para>
</blockquote>

4.2.4.3. Dicas, notas, cuidados, informações importantes e sidebars.

Você talvez precise incluir informações extras separadas do corpo principal do texto. Tipicamente isso é meta informação que o usuário deve tomar conhecimento.

Dependendo da natureza da informação, um elemento <tip>, <note>, <warning>, <caution>, and <important> deve ser usado. Alternativamente, se a informação é relacionada ao corpo principal do texto e não se encaixa em nunhum dos objetos acima, use <sidebar>.

As circunstâncias na qual se deve escolher um elemento ao invés do outro não é clara. A documentação do DocBokk sugere:

• O <note> é uma informação que deve ser lida por todos os leitores.

• Um <important> é uma variação do <note>.

• O <caution> é usado para as informações sobre perda de dados ou danos ao software.

• O <warning> é usado para informações sobre possíveis danos no hardware ou defeito sem conserto ou limb.

<warning>
             <para>Instalando FreeBSD talvez faça com que você queira 
               desinstalar o windows do seu Hard disk.</para>
           </warning>

4.2.4.4. Listas e procedimentos

Você frequentemente vai precisar listar pedaços de informações para o usuário, ou present eles com um número de passos que devem ser seguidos para alcançar um objetivo particular.

Para fazer isso, use <itemizedlist>, <orderedlist>, ou <procedure>[2]

<itemizedlist> e <orderedlist> são similares aos seus equivalentes em HTML, <ul> e <ol>. Cada um consiste de um ou mais elementos <listitem>, e cada <listitem> contém um ou mais elementos de bloco. O elemento <listitem> é analogo à <li>do HTML. Entretanto, ao contrário de HTML, elas são obrigatórias.

<procedure> é ligeiramente diferente. Consiste de <step>s, que por sua vez consiste de mais <step>s ou <substep>s. Cada <step> contém elementos de bloco.

<itemizedlist>
  <listitem>
    <para>Esse é o primeiro item itemized.</para>
  </listitem>

  <listitem>
    <para>Esse é o segundo item itemized.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>Esse é o primeiro item ordenado.</para>
  </listitem>

  <listitem>
    <para>Esse é o segundo item ordenado.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Faça isso.</para>
  </step>

  <step>
    <para>Depois faça isso.</para>
  </step>

  <step>
    <para>E agora faça isso.</para>
  </step>
</procedure>

4.2.4.5. Mostrando arquivos de exemplo

Se você quiser mostrar um trecho de um arquivo (ou talvez um arquivo inteiro) ao usuário, use o elemento <programlisting>

Espaços e quebras de linha são importantes dentro do <programlisting>. Em particular, isso significa que a tag de abertura deve aparecer na mesma linha que a primeira linha do programa, e a tag de fechamento deve estar na última linha do programa, do contrário linhas em branco espurias podem ser incluidas.

<para>Quando você tivert terminado, seu prograva deve
            estar assim;</para>

<programlisting>#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
}</programlisting>

#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
}

4.2.4.6. Chamadaa

Uma chamada é um mecanismo para fazr referência a um pedaço de texto ou uma posição específica de um exemplo anterior sem ligar a ele no texto.

Para fazer isso, marque as áreas de interesse no seu exemplo (<programlisting>, <literallayout>, ou o que for) com o elemento <co>. Cada elemento deve ter um único id atribuido a ele, Após o exemplo inclua um <calloutlist> que faça a referência e dê um comentário adicional.

<para><para>Quando você tivert terminado, seu prograva deve
            estar assim;</para>

<programlisting>#include <stdio.h> <co id="co-ex-include">

int <co id="co-ex-return">
main(void)
{
    printf("hello, world\n"); <co id="co-ex-printf">
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Inclui o arquivo padrão de IO.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Especifica que <function>main()</function> retorna um inteiro.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>A chamada <function>printf()</function> que escreve <literal>hello, 
      world</literal> na saída padrão.</para>
  </callout>
</calloutlist>

#include <stdio.h> 

int 
main(void)
{
    printf("hello, world\n"); 
}

4.2.4.7. Tabelas

Ao contrário de HTML, você não precisa usar tabelas para layout, as folhas de estilo cuidam disto para você. Use tabela apenas para marcação de dados tabulares.

De maneira geral (veja a documentação do DocBook para mais detalhes) uma tabela (que pode ser formal ou informal) consiste de um elemento <table>. Que contém ao menos um elemento <tgroup>, que especifica (como um atributo) o número de colunas neste grupo tabela. Dentro do grupo tabela você pode ter um elemento <thead>, que contém os elementos para o cabeçalho da tabela (cabeçalho da coluna), e um <tbody> que contém o corpo da tabela.

Tanto o <tgroup> quanto o <thead> contém elementos <row>, que por sua vez contém elementos <entry>. Cada elemento <entry> especifica uma célula da tabela.

<informaltable>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>Este é o cabeçalho da coluna 1</entry>
        <entry>Este é o cabeçalho da coluna 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Linha 1, coluna 1</entry>
        <entry>Linha 1, coluna 2</entry>
      </row>

      <row>
        <entry>Linha 2, coluna 1</entry>
        <entry>Linha 2, coluna 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

Se você não quiser borda na tabela adicione o atributo frame pode ser acrescentada ao elemento <informaltable> com o valor none (i.e., <informaltable frame="none">).

4.2.4.8. Exemplos para o usuário seguir

Geralmente você precisa mostrar exemplos para que o usuário siga. Tipicamente, isso irá consistir de diálogos com o computador; o usuário digita um comando, o usuário obtém uma resposta de volta, ele digita outro comando, e assim por diante.

Um certo número de elementos e entidades participam disso.

<screen><prompt>%</prompt> <userinput>ls -1</userinput>
foo1
foo2
foo3
<prompt>%</prompt> <userinput>ls -1 | grep foo2</userinput>
foo2
<prompt>%</prompt> <userinput>su</userinput>
<prompt>Password: </prompt>
<prompt>#</prompt> <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>

% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
This is the file called 'foo2'

4.2.5.1. Enfatizando a informação

Quando você quiser enfatizar uma palavra ou frase em particular, use <emphasis>. Ela pode ser apresentada em itálico, ou negrito, ou pode ser falada diferentemente com um sistema texto-para-fala.

Não há maneira de mudar a apresentação da ênfase no seu documento, não tem equivalente do HTML <b> e <i>. Se a informação que você está apresentando é importante então considere usar <important> ao invés de <emphasis>.

<para>FreeBSD é sem dúvida <emphasis>o</emphasis> melhor sistema operacional tipo Unix
 para a arquitetura Intel.</para>

4.2.5.2. Citações

Para citar um texto de outro documento ou fonte, ou para denotar uma frase que é usado figuradamente, use <quote>. Dentro da tag <quote>, você pode usar a maioira da marcação disponível para um texto normal.

<para>Entretanto, certifique-se que a busca não vá além do <quote>limite entre a administração 
local e pública</quote> como diz o RFC 1535.</para>

4.2.5.3. Teclas, mouse e combinações

Para se referir a uma tecla específica do teclado, use <keycap>. Para se referir a um botão do mouse, use <mousebutton>. E para se referir a combinação de digitar uma tecla e um clique do mouse, envolva-os com <keycombo>.

<keycombo> tem um atributo chamado action, que pode ser click, double-click,other, press, seq, ou simul. Os dois últimos dizem se teclas ou botões devem ser pressionados em sequência ou simultaneamente

As folhas de estilo automaticamente colocam o símbolo de ligação, tal como +, entre os nomes das teclas, quando envolvida com <keycombo>.

<para>Para mudar para o segundo terminal virtual, digite <keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>

<para>Sair do <command>vi</command> sem salvar o seu trabalho, digite <keycombo action="seq">
<keycap>Esc</keycap><keycap>:</keycap><keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>Meu gerenciador de janela é configurado de forma que <keycombo action="simul"><keycap>Alt</keycap>
<mousebutton>botão direito</mousebutton></keycombo> do mouse é usado para mover as janelas.</para>

4.2.5.4. Aplicações, comandos, opções e cites

Frequentemente você irá fazer referência tanto a aplicações quanto a comandos quando estiver escrendo para o Handbook. A distinção entre eles é simples: uma aplicação é o nome de um pacote de programas (ou possivelmente apenas um) que façam uma tarefa em particular. Um comando é o nome de um programa que o usuário pode rodar.

Além disso, você eventualmente precisará listar uma ou mais opções que um comando possa ter.

Finalmente, você irá querer listar um comando com o número da sua seção no manual, na forma comando(number) tão comum nos manuais de Unix.

marcando o nome da aplicação com <application>.

Quando você quiser listar um comando com o seu número da sua seção no manual (que deve acontecer a maioria das vezes) o elemento do DocBook é o <citerefentry>. Isto irá ter mais dois elementos, <refentrytitle> e <manvolnum>. O conteúdo de <refentrytitle> é o nome do comando, e o conteúdo de <manvolnum> é a seção da página do manual.

Isso pode ser trabalhoso de escrever, e assim uma série de entidades gerais foi criada para facilitar. Cada entidade é da forma &man.manual-page.manual-section;.

O arquivo que contém estas entidades está em doc/share/sgml/man-refs.ent, e pode ser usado usando este IPF:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

Portanto, a introdução à sua documentação provavelmente será assim:

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

...

]>

Use <command> quando quiser incluir um comando in-line mas como algo que deveria ser digitado.

Use <option> para marcar as opções de um comando.

Quando diversas referências a um mesmo comando estiverem próximas é melhor usar a notação &man.command.section; para marcar a primeira referência e usar <command> para marcar as referências subsequentes. Isso faz a saída gerada, especialmente HTML, parecer visualmente melhor.

Isso pode ser confuso, e às vezes a escolha nem sempre ´ clara. Este exemplo pode tornas as coisas mais claras.

<para><application>Sendmail</application> e a aplicacao de e-mail em Unix mais usada.</para>

<para><application>Sendmail</application> inclui os programas 
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.8;, e &man.newaliases.8;.</para>


<para>Um dos parametros de linha de comando para <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, ira mostrar o atual estado da
mensagem na file de e-mail. 
Verifique isto na linha de comando usando <command>sendmail -bp</command>.</para>

4.2.5.5. Arquivos, diretórios, extensões

Sempre que quiser se referir ao nome de um arquivo, diretório ou uma extensão de arquivo, use <filename>

<para>O fonte SGML do Handbook em Inglês pode ser encotrado em 
<filename>/usr/doc/en/handbook/</filename>.  O primeiro arquivo 
neste diretório é chamado <filename>handbook.sgml</filename>. 
Você também deve ver o <filename>Makefile</filename> 
e alguns arquivos com a extensão <filename>.ent</filename>.</para>

4.2.5.6. O nome dos ports

Você pode precisar incluir o nome de um programa da Coleção de Ports FreeBSD na documentação. Use a tag <filename> com o atributo role ajustado para package para identifica-lo. Uma vez que podem ser instalados em diversos lugares, inclua apenas a categoria e o nome do port, não inclua o /usr/ports.

<para>Instale o port <filename role="package">net/ethereal</filename>
para ver o tráfego na rede.</para>

4.2.5.7. Dispositivos

Quando estiver falando de dispositivos, você tem duas escolhas. Você pode se referir ao dispositivo como aparece no /dev, ou usar o nome do dispositivo como ele aparece no kernel. No segundo caso, use <devicename>.

À vezes você não tem escolha. Alguns dispositivos, como placas de rede, não tem entrada no /dev, ou as entradas são muito diferentes daquelas entradas.

<para><devicename>sio</devicename> e usado para comunicação
serial no FreeBSD. <devicename>sio</devicename> se manifesta 
através de entradas em <filename>/dev</filename>, incluindo 
<filename>/dev/ttyd0</filename> e <filename>/dev/cuaa0</filename>.
</para>

<para>Por outro lado, dispositivos de rede, tais como <devicename>ed0</devicename> 
não aparecem <filename>/dev</filename>.
</para>

<para>No MS-DOS, o primeiro disco flexível é chamado de <devicename>a:</devicename>. 
No FreeBSD é <filename>/dev/fd0</filename>.
</para>

4.2.5.8. Hosts, domínios, endereço IP e etc.

Você pode marcar a informação sobre a identificação de computadores em rede (hosts) de diversas maneiras. Todas elas usam <hostid> como elemento, com o atributo role dizendo o tipo da informação marcada.

<para>A máquina local sempre pode ser referida pelo nome 
<hostid>localhost</hostid>, que terá o endereço IP
<hostid role="ipaddr">127.0.0.1</hostid>.</para>


<para>O domíminio <hostid role="domainname">FreeBSD.org</hostid>
contém vários hosts diferentes, incluindo 
<hostid role="fqdn">freefall.FreeBSD.org</hostid> e 
<hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>Quando tiver adicionando um apelido para uma interface (usando 
<command>ifconfig</command>) <emphasis>sempre</emphasis> use uma
máscara de <hostid role="netmask">255.255.255.255</hostid> (que
também pode expressa como <hostid role="netmask">0xffffffff</hostid>.
</para>

<para>O endereço MAC identifica unicamente cada placa de rede 
existente. Um endereço MAC típico parece com  <hostid
role="mac">08:00:20:87:ef:d0</hostid>.</para>

4.2.5.9. Usernames

Quando precisar se referir a um nome de usuário específico, tal como root ou bin, use <username>.

<para>
Para fazer a maioria das funções administrativas você precisará 
ser <username>root</username>.</para>

4.2.5.10. Descrevendo Makefiles

Existe dois elementos para descrever partes de Makefiles, <maketarget> e <makevar>.

<maketarget> identifica uma alvo de construção exportado por um Makefile que pode ser dado como um parâmetro ao make. <makevar> identifica uma variável que pode ser ajustada (no ambiente, na linha de comando make, ou dentro do Makefile) para influenciar no processo.

<para>Dois alvos comuns em um <filename>Makefile</filename> são
<maketarget>all</maketarget> e <maketarget>clean</maketarget>.</para>

<para>Tipicamente, usar <maketarget>all</maketarget> irá refazer a
aplicação, usar <maketarget>clean</maketarget> irá remover os
arquivos temporários (<filename>.o</filename> por exemplo) criado
pelo processo de construção.</para>

<para><maketarget>clean</maketarget> pode ser controlado por
muitas variáveis, incluindo <makevar>CLOBBER</makevar> e
<makevar>RECURSE</makevar>.</para>

4.2.5.11. Texto literal

Com frequência você irá precisar incluir texto literal no Handbook. Este texto é retirado de outro arquivo, or que deve ser copiado do Handbook para outro arquivo palavra-por-palavra.

Às vezes, <programlisting> será suficiente. <programlisting> nem sempre é apropriado, particularmente quando você quer incluir uma parte de um arquivo in-line com todos os parágrafos.

Nestas ocasiões, use <literal>.

<para>A linha <literal>maxusers 10</literal> no arquivo de 
configuração do kernel determina o tamanho de muitas tabelas 
do sistema, e diz aproximadamente quantos logins simultaneos
o sistema irá suportar.
</para>

4.2.5.12. Mostrando itens que o usuário deve preencher

Irá acontecer muitas vezes que você quer mostrar ao usuário o que fazer, ou se referir ao um arquivo, uma linha de comando ou coisa parecida, onde ele não pode simplesmente copiar o exemplo que você forneceu, mas deve dar alguma informação por ele mesmo.

<replaceable> é feita para estas eventualidades. Use inside dentro de outros elementos para indicar partes do conteúdo do elemento que o usuário deve substituir.

<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>comando</replaceable></userinput></screen>
</informalexample>

% man comando

<para>A linha <literal>maxusers <replaceable>n</replaceable></literal> 
no arquivo de configuração do kernel determina o tamanho de muitas 
tabelas  do sistema, e diz aproximadamente quantos logins simultâneos
o sistema irá suportar.
</para>

<para>Para uma estação de trabalho, <literal>32</literal> é um
bom valor para <replaceable>n</replaceable>.</para>

4.2.5.13. Citando erros do sistema

Você pode querer mostrar erros gerados pelo FreeBSD. Marque-os com <errorname>. Isto indica o exato erro que aparece.

 
<screen><errorname>Panic: cannot mount root</errorname></screen> 

Panic: cannot mount root

4.2.6.1. Formatos de imagens

Atualmente suportamos dois formatos de imagens. O formato que você deve usar depende da natureza da sua imagem.

Para imagens vetoriais, tais como diagramas de rede, linhas temporais e similares, use Encapsulated Postscript, e certifique-se que suas imagens tenham a extensão .eps.

Para bitmaps, tais como a captura de uma tela, use o formato Portable Network Graphic, e certifique-se que suas imagens tenham a extensão .png.

Estes são os únicos que podem ser gravados no repositório CVS

Use o formato correto para a imagem correta. Espera-se que a sua documentação tenha tanto imagens EPS quanto PNG. Os Makefiles asseguram que o formato correto seja escolhido dependendo do formato de saída da sua documentação. Não grave a mesma imagem nos dois formatos diferentes no repositório.

4.2.6.2. Marcação

A marcação para uma imagem é relativamente simples. Primeiro, marque <mediaobject>. O <mediaobject> pode conter outros objetos mais específicos. Estamos interessandos em dois, o <imageobject> e o <textobject>.

Você deve incluir um <imageobject>, e dois elementos <textobject>. O <imageobject> irá apontar para o nome do arquivo da imagem que será usada (sem a extensão). Os elementos <textobject> contém informação que será apresentada ao usuário junto, ou não, com a imagem.

Há duas circunstâncias em que isso pode ocorrer.

• Quando o leitor estiver vendo a documentação em HTML. Neste caso, cada imagem precisará ter um texto alternativo associado para mostrar ao usuário, tipicamente enquanto a imagem estiver sendo carregada, ou se ele parar o ponteiro do mouse sobre a imagem.

• Quando o leitor estiver vendo a documentação em modo texto. Neste caso, cada imagem deve ter uma ASCII art equivalente para mostrar ao usuário.

Um exemplo provavelmente irá tornas as coisas mais fáceis de se entender. Suponha que você tenha uma imagem, chamada fig1, que você queira incluir no documento. Esta imagem é um retângulo com um A dentro dele. A marcação para isso será

<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"> 
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>Uma figura</phrase> 
  </textobject>
</mediaobject>

4.2.6.3. Entradas no Makefile

Suas imagens devem estar listadas na variável IMAGES do Makefile. Esta variável deve conter o nome de todos fontes das suas imagens. Por exemplo, se você criou três figuras, fig1.eps, fig2.png, fig3.png,, então o seu Makefile deve ter linhas como estas.

...
IMAGES= fig1.eps fig2.png fig3.png
...

or

...
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
...

De novo, o Makefile irá fazer uma lista completa das imagens necessárias para criar o seu documento fonte, você apenas precisa listar as imagens que você fornece.

4.2.6.4. Imagens e capítulos em subdiretórios

Você precisa ser cuidadoso quando separar a sua documentação em arquivos menores (veja Seção 3.7.1) em diretórios diferentes.

Suponha que você tenha um livro com três capítulos, e os capítulos estão armazenados cada um no seu próprio diretório, chamados chapter1/chapter.sgml, chapter2/chapter.sgml, e chapter3/chapter.sgml. Se cada capítulo tiver imagens associados a eles, sugiro que as coloque em um subdiretório do capítulo (chapter1/, chapter2/, chapter3/).

Entretanto, se você fizer isso você deve incluir o nome dos diretórios na variável IMAGES no Makefile, e deve incluir o nome do diretório no elemento <imagedata> do seu documento.

Por exemplo, se você tiver chapter1/fig1.png, então chapter1/chapter.sgml deve conter

<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"> 
  </imageobject>

  ...

</mediaobject>

O Makefile deve conter

...
IMAGES=  chapter1/fig1.png
...

Assim as coisas devem funcionar.

4.2.7.1. Ligando-se a outras partes no mesmo documento

Links dentro do mesmo documento exigem que você especifique de onde você esta se ligando (i.e., o texto no qual o usuário irá clicar, ou indicando de outra maneira como origem do link) e para onde você você está se ligando (o destino do link).

Cada elemento dentro do DocBook tem um atributo chamado id. Você pode por um texto neste atributo para identificar unicamente o elemento associado a ele.

Este valor será usado quando você especificar a origem do link.

Normalmente, você irá se ligar apenas a capítulos ou seções, assim você vai colocar o atributo id nestes elementos.

<chapter id="chapter1">
  <title>Introdução</title>

  <para>Esta é a introdução. Contém uma 
    subseção que também será identificada.
  </para>
  <sect1 id="chapter1-sect1">
    <title>Sub-sec 1</title>

    <para>Esta é a subseção.</para>
  </sect1>
</chapter>

Obviamente, você deve usar nomes mais descritivos. Estes nomes devem ser únicos dentro do documento (i.e., não apenas no arquivo, mas bem como no documento no qual o arquivo está incluido). Repare como o id é feito adicionando-se texto ao id do capítulo. Isto ajuda a garantir eles sejam únicos.

Se você quiser permitir ao usuário saltar para uma parte específica do documento (possivelmente para o meio do parágrafo ou um exemplo), use <anchor>. Este elemento não tem conteúdo, exceto um atributo id.

<para>
Este parágrafo tem um <anchor id="para1">alvo dentro dele. Nao
 ira aparecer no documento
</para>

Quando você quiser dar ao usuário um link que possa ser ativado (provavelmente clicando-se) para ir para outra seção do documento que tenha um atributo id, você pode usar <xref> ou <link>.

Ambos elementos têm um atributo linkend. O valor deste atributo deve ser o mesmo usado no atributo id (não importa se ele ainda não ocorreu no documento; isto funciona tanto para link a frente quanto para trás).

Se você usar <xref> então não terá controle sobre o texto do link. Ele será gerado para você.

<para>Mais informação pode ser encontrada
em <xref linkend="chapter1">
</para>

<para>Informação mais específica pode ser encontrada
em <xref linkend="chapter1-sect1">.
</para>

Note como o texto do link é deduzido a partir do título da seção ou do número do capítulo.

Se você quiser controlar o texto do link então use <link>. Este elemento envolve o conteúdo, e o conteúdo será usado para o link.

<para>Mais informação pode ser encontrada
<link linkend="chapter1">no primeiro capítulo</link>.
</para>

<para>Informação mais específica pode ser encontrada
<link linkend="chapter1-sect1">nesta</link> seção
</para>

4.2.7.2. Ligando-se a documentos na WWW

Ligar-se a um documento externo é muito mais simples, desde que você saiba o URL do documento ao deseja se ligar. Use <ulink>. O atributo url é o URL da página para o qual o link aponta, e o conteúdo do elemento é o texto que será mostrado para o usuário ativar.

<para>Claro que você parar de ler este documento e ir para a
<ulink url="../../../../index.html">Página principal do FreeBSD</ulink>
</para>