path: root/pt_BR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1.  Redistributions of source code (SGML DocBook) must retain the above
	 copyright notice, this list of conditions and the following
	 disclaimer as the first lines of this file unmodified.

      2.  Redistributions in compiled form (transformed to other DTDs,
	 converted to PDF, PostScript, RTF and other formats) must reproduce
	 the above copyright notice, this list of conditions and the
	 following disclaimer in the documentation and/or other materials
	 provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED.  IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     The FreeBSD Documentation Project
     The FreeBSD Brazilian Portuguese Documentation Project

     $FreeBSD$

     Original revision: r38851

-->

<chapter id="sgml-markup">
  <title>Marcação SGML</title>

  <para>Esse capítulo descreve as duas linguagens de
    marcação que você vai encontrar quando for
    contribuir para o projeto de documentação do 
    FreeBSD.  Cada seção descreve a linguagem de 
    marcação, e detalha a marcação que
    você provavelmente vai querer usar ou que já 
    está utilizando.</para>

  <para>Estas linguagens de marcação contém um 
    grande número de elementos, e as vezes pode ser 
    confuso escolher qual elemento usar em uma situação
    específica.  Esta seção apresenta os elementos 
    que provavelmente você vai precisar e fornece exemplos de 
    como utilizá-los.</para>

  <para>Esta <emphasis>não</emphasis> é uma lista
    detalhada de elementos, uma vez que ela apenas ratifica a
    documentação de cada linguagem.  O objetivo desta
    seção é listar os elementos mais 
    úteis para você.  Se você tiver alguma 
    dúvida sobre qual a melhor forma de marcar um pedaço 
    específico do seu documento, por favor, envie a sua
    dúvida para a &a.doc;.</para>

  <note>
    <title>Inline Versus Block</title>

    <para>No restante deste documento, quando descrevermos um elemento
    como <emphasis>inline</emphasis> significará que o elemento 
    pode ocorrer dentro de um bloco de elementos, que ele não 
    acarretará em uma quebra de linha.  Um elemento 
    <emphasis>block</emphasis>, por comparação, irá 
    causar uma quebra de linha (e outros processamentos) quando for 
    encontrado.</para>
  </note>

  <sect1 id="sgml-markup-html">
    <title>HTML</title>

    <para>O HTML, Linguagem de Marcação de Hypertexto,
    é a linguagem de marcação escolhida para a 
    <literal>World Wide Web</literal>.  Maiores informações 
    podem ser encontradas em 
    <ulink url="http://www.w3.org/"></ulink>.</para>

    <para>O HTML é utilizado para a marcação das 
    páginas do web site do FreeBSD.  Ele não deveria ser 
    utilizado (geralmente) para marcar outros tipos de documentos
    já que o <literal>DocBook</literal> oferece uma maior 
    variedade de elementos.  Consequentemente, você só 
    irá encontrar páginas em HTML se estiver escrevendo 
    para o web site.</para>

    <para>O HTML já passou por algumas versões, 1, 2, 3.0, 
      3.2 e a última, 4.0 (disponível nas duas variantes,
    <emphasis>strict</emphasis> e <emphasis>loose</emphasis>).</para>
	
    <para>Os HTML DTD's estão disponíveis na
      coleção de <literal>ports</literal> na pasta
      <filename role="package">textproc/html</filename>.  Eles 
      são automaticamente instalados como parte do
      <literal>port</literal>
      <filename role="package">textproc/docproj</filename></para>

    <sect2>
      <title>Identificador Público Formal (IPF)</title>

      <para>Existem vários IPF's para o HTML, os quais dependem
      da versão (também conhecida como nível) 
      do HTML que você quer declarar compatível com seu 
      documento.</para>

      <para>A maioria dos documentos HTML no web site do 
      FreeBSD estão de acordo com a versão
      <literal>loose</literal> do HTML 4.0.</para>

      <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
    </sect2>

    <sect2>
      <title>Elementos de Seção</title>

      <para>Um documento HTML é normalmente dividido em duas
      partes.  A primeira é chamada de
      <emphasis>head</emphasis>,  a qual contém
      meta-informações sobre o documento, tais como o
      seu título, o nome do autor, o documento pai e assim por 
      diante.  A segunda parte, o <emphasis>body</emphasis> é 
      contém o conteúdo que vai ser exibido para o 
      usuário.</para>

      <para>Estas seções são indicadas pelos 
      elementos <sgmltag>head</sgmltag> e <sgmltag>body</sgmltag>, 
      respectivamente.  Esses elementos estão contidos dentro 
      de um elemento <sgmltag>html</sgmltag> de alto-nível.</para>

      <example>
	<title>Estrutura Normal de um Documento HTML</title>

	<programlisting>&lt;html>
  &lt;head>
	  &lt;title><replaceable>Título do Documento</replaceable>&lt;/title>
  &lt;/head>

  &lt;body>

    &hellip;

  &lt;/body>
&lt;/html></programlisting>
      </example>
    </sect2>

    <sect2>
      <title>Bloco de Elementos</title>

      <sect3>
	<title>Cabeçalho</title>

	<para>O HTML permite a denotação de 
	  cabeçalho em seu documento, de até seis 
	  níveis diferentes.  </para>

	<para>O maior e mais proeminente cabeçalho é o
	  <sgmltag>h1</sgmltag>, depois vem o <sgmltag>h2</sgmltag>,
	  assim por diante até <sgmltag>h6</sgmltag>.
	</para>

	<para>O conteúdo dos elementos é o texto do
	  cabeçalho.</para>

	<example>
	  <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, e
	    outras Tags de Header.</title>

	  <para>Uso:</para>

	  <programlisting>&lt;h1&gt;Primeira seção&lt;/h1&gt;

&lt;!&hyphen;- a introdução do documento entra aqui -&hyphen;&gt;

&lt;h2&gt;Este é o cabeçalho da primeira seção&lt;/h2&gt;

&lt;!&hyphen;- O conteúdo da primeira seção entra aqui -&hyphen;&gt;

&lt;h3&gt;Este é o cabeçalho da primeira subseção&lt;/h3&gt;

&lt;!&hyphen;- O conteúdo da primeira subseção entra aqui -&hyphen;&gt;

&lt;h2&gt;Este é o heading para a segunda seção&lt;/h2&gt;

&lt;!&hyphen;- O conteúdo da segunda seção entra aqui -&hyphen;&gt;</programlisting>	    
	</example>
	
	<para>Geralmente, uma página HTML deveria ter um 
	  cabeçalho de primeiro nível 
	  (<sgmltag>h1</sgmltag>).  Este poderia conter muitos 
	  cabeçalhos de segundo nível
	  (<sgmltag>h2</sgmltag>), os quais por sua vez podem conter 
	  muitos cabeçalhos de terceiro nível.  Cada 
	  elemento <sgmltag>h<replaceable>n</replaceable></sgmltag> 
	  deve ter o mesmo elemento, sendo que os elementos mais acima 
	  na hierarquia estarão subtraídos de um.  Deve-se evitar 
	  buracos na numeração.</para>

	<example>
	  <title>Má organização de elementos
	    <sgmltag>h<replaceable>n</replaceable></sgmltag></title>

	  <para>Uso:</para>

	  <programlisting>&lt;h1&gt;Primeira seção&lt;/h1&gt;

&lt;!&hyphen;- Introdução do documento -&hyphen;&gt;

&lt;h3&gt;Subseção&lt;/h3&gt;

&lt;!&hyphen;- Isto é ruim, não foi usado &lt;h2&gt; -&hyphen;&gt;</programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Parágrafos</title>

	<para>O HTML suporta elementos formados de um único
	parágrafo <sgmltag>p</sgmltag>.</para>

	<example>
	  <title><sgmltag>p</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Isto é um parágrafo.  Pode conter qualquer outro elemento</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Bloco de Citação</title>

	<para>Um bloco de citação é uma
	  citação estendida de outro documento que
	  não deveria aparecer no parágrafo 
	  atual.</para>

	<example>
	  <title><sgmltag>blockquote</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Um pequeno trecho da constituição dos Estados Unidos:</p>

<blockquote>
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.
</blockquote>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Listas</title>

	<para>Você pode apresentar ao usuário três
	  tipos de listas, ordenadas, desordenadas e de 
	  definição.
	</para>

	<para>Tipicamente, cada entrada em uma lista ordenada, 
	  é numerada enquanto nas listas desordenadas 
	  serão processadas por um bullet point.  Listas de 
	  definição são compostas de duas 
	  partes para cada entrada a primeira é o termo a ser 
	  definido, e a segunda, é a definição 
	  em si.</para>

	<para>As Listas ordenadas, desordenadas e de 
	  definição, são indicadas pelos
	  elementos <sgmltag>ol</sgmltag>, <sgmltag>ul</sgmltag> e
	  <sgmltag>dl</sgmltag>, respectivamente.</para>

	<para>Listas ordenadas e desordenadas contém itens de 
	  lista, indicados pelo elemento <sgmltag>li</sgmltag>.  Um 
	  item de lista pode conter texto, podendo inclusive conter 
	  um ou mais elementos <sgmltag>p</sgmltag>.</para>

	<para>Listas de definição contém o termo
	  a ser definido (<sgmltag>dt</sgmltag>) e a 
	  descrição do termo (<sgmltag>dd</sgmltag>).  
	  A definição de um termo só pode conter 
	  elementos <literal>inline</literal>.  A 
	  descrição do termo pode conter elementos do 
	  tipo <literal>block</literal>.</para>

	<example>
	  <title><sgmltag>ul</sgmltag> e <sgmltag>ol</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Uma lista não ordenada.  Os itens serão provavelmente 
precedidos por uma esfera sólida.</p>

<ul>
  <li>Primeiro item</li>

  <li>Segundo item</li>

  <li>Terceiro item</li>
</ul>

<p>Uma lista ordenada, com itens de lista com vários
parágrafos.  Cada item (nota: não cada parágrafo)
será numerado.</p>

<ol>
  <li><p>Este é o primeiro item.  Tem apenas um parágrafo.</p></li>

  <li><p>Este é o primeiro parágrafo do segundo item.</p>

    <p>Este é o segundo parágrafo do segundo item.</p></li>

  <li><p>Este é o primeiro e único parágrafo do terceiro item.</p></li>
</ol>]]></programlisting>
	</example>

	<example>
	  <title>Listas de Definição com 
	    <sgmltag>dl</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<dl>
  <dt>Termo 1</dt>

  <dd><p>Parágrafo 1 da definição 1.</p>

    <p>Parágrafo 2 da definição 1.</p></dd>

  <dt>Termo 2</dt>

  <dd><p>Parágrafo 1 da definição 2.</p></dd>

  <dt>Termo 3</dt>

  <dd><p>Parágrafo 1 da definição 3.</p></dd>
</dl>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Texto Pré-Formatado</title>

	<para>Você pode indicar que o texto deve ser 
	  apresentado exatamente como esta no arquivo.  Tipicamente, 
	  isto significa que o texto será mostrado em fonte fixa,
	  múltiplos espaços não serão fundidos em 
	  um e que as quebras de linha no texto serão 
	  significativas.</para>

	<para>Para fazer isto, envolva o conteúdo com o 
	  elemento <sgmltag>pre</sgmltag>:</para>

	<example>
	  <title><sgmltag>pre</sgmltag></title>

	  <para>Você pode usar <sgmltag>pre</sgmltag> para 
	    marcar uma mensagem de email;</para>

	  <programlisting><![CDATA[<pre>  
  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

  There is a new copy of my primer for contributors to the FreeBSD
  Documentation Project available at

	&lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Comments appreciated.

  N
</pre>]]></programlisting>

	  <para>Tenha em mente que o <literal>&lt;</literal> e o
	    <literal>&amp;</literal> continuam sendo reconhecidos como
	    caracteres especiais em um texto pré-formatado.  
	    É por isto que nos exemplos tivemos que utilizar
	    <literal>&amp;lt;</literal> ao invés de
	    <literal>&lt;</literal>.  Para manter a consistência,
	    o <literal>&amp;gt;</literal> também foi utilizado
	    no lugar do <literal>&gt;</literal>.  Fique atento para
	    caracteres especiais que podem aparecer em textos copiados
	    de origens não formatadas, como por exemplo, de uma
	    mensagem de email ou do código fonte de um 
	    programa.</para>

	</example>
      </sect3>

      <sect3>
	<title>Tabelas</title>

	<note>
	  <para>A maioria dos navegadores de modo texto (tal como o 
	    Lynx) não apresentam tabelas de maneira muito 
	    eficiente.  Se você quiser que o seu conteúdo
	    seja apresentado em forma de tabelas, você deve 
	    considerar outra marcação para evitar 
	    problemas.</para>
	</note>

	<para>Marque a informação tabular com o elemento
	  <sgmltag>table</sgmltag>.  Uma tabela consiste de uma ou 
	  mais linhas (<sgmltag>tr</sgmltag>), cada uma contendo uma 
	  ou mais células de dados (<sgmltag>td</sgmltag>).  
	  As células podem conter outros elementos de bloco, 
	  como parágrafos ou listas.  Também pode 
	  conter outra tabela (este aninhamento pode ser repetido
	  indefinidamente).  Se a célula contém apenas 
	  um parágrafo, então não é 
	  necessário incluir o elemento <sgmltag>p</sgmltag>.</para>
	
	<example>
	  <title>Uso Simples de <sgmltag>table</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Esta é uma simples tabela 2x2.</p>

<table>
  <tr>
    <td>Célula esquerda superior</td>

    <td>Célula direita superior</td>
  </tr>

  <tr>
    <td>Célula esquerda inferior</td>

    <td>Célula direita inferior</td>
  </tr>
</table>]]></programlisting></example>

	<para>Uma célula pode se estender por muitas linhas 
	  e colunas.  Para indicar isto, coloque o atributo 
	  <literal>rowspan</literal> e/ou <literal>colspan</literal>,
	  com valores que indiquem o número de linhas ou 
	  colunas a serem ocupados.</para>

	<example>
	  <title>Utiliizando <literal>rowspan</literal></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Uma célula comprida e estreita na esquerda e duas 
células pequenas à direita.</p>

<table>
  <tr>
    <td rowspan="2">Comprida e estreita</td>
  </tr>

  <tr>
    <td>Célula superior</td>

    <td>Célula inferior</td>
  </tr>
</table>]]></programlisting>
	</example>

	<example>
	  <title>Usando <literal>colspan</literal></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Uma célula longa em cima, duas células abaixo.</p>

<table>
  <tr>
    <td colspan="2">Célula superior</td>
  </tr>

  <tr>
    <td>Célula inferior esquerda</td>

    <td>Célula inferior direita</td>
  </tr>
</table>]]></programlisting>
	</example>

	<example>
	  <title>Usando <literal>rowspan</literal> e
	    <literal>colspan</literal> juntos</title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Numa tabela 3x3, o bloco superior esquerdo é um conjunto 
2x2 fundidos em um.  As outras células são normais.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Célula esquerda superior grande</td>

    <td>Célula direita superior</td>
  </tr>

  <tr>
    <td>Célula do meio a direita</td>
  </tr>

  <tr>
    <td>Célula inferior esquerda</td>

    <td>Célula inferior central</td>

    <td>Célula inferior direita</td>
  </tr>
</table>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Elementos In-line</title>

      <sect3>
	<title>Enfatizando a Informação</title>

	<para>Você tem dois níveis de ênfase
	  disponíveis em HTML, <sgmltag>em</sgmltag> e 
	  <sgmltag>strong</sgmltag>.  O <sgmltag>em</sgmltag> é 
	  para uma ênfase simples e o <sgmltag>strong</sgmltag> 
	  indica uma ênfase mais forte.</para>

	<para>Em geral, <sgmltag>em</sgmltag> é apresentada em
	  itálico e <sgmltag>strong</sgmltag> é 
	  apresentada em negrito.  Mas nem sempre é assim, e 
	  você não deve contar com isso.</para>

	<example>
	  <title><sgmltag>em</sgmltag> e <sgmltag>strong</sgmltag>
	    </title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p><em>Este</em> foi enfatizado
enquanto <strong>este</strong> foi fortemente enfatizado.</p>]]>
          </programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Negrito e Itálico</title>

	<para>Uma vez que o HTML inclui marcação de 
	  apresentação, você também pode
	  indicar que um conteúdo deve ser apresentado em 
	  negrito ou itálico.  Os elementos são 
	  <sgmltag>b</sgmltag> e <sgmltag>i</sgmltag> 
	  respectivamente.</para>

	<example>
	  <title><sgmltag>b</sgmltag> e <sgmltag>i</sgmltag></title>

	  <programlisting><![CDATA[<p><b>Este</b> esta em negrito, 
enquanto <i>este</i> está em itálico.</p>]]>
	  </programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Indicando Texto de Fonte Fixa</title>

	<para>Se você tiver conteúdo que deve ser 
	  apresentado em fonte fixa (typewriter), use 
	  <sgmltag>tt</sgmltag> (de <quote>teletipo</quote>).</para>

	<example>
	  <title><sgmltag>tt</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p> Este documento foi originalmente por
Nik Clayton, que pode ser encontrado por email em
<tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Tamanho do Conteúdo</title>

	<para>Você pode indicar que o conteúdo deve ser
	  apresentado em uma fonte maior ou menor.  Existem 
	  três maneiras de fazer isto:</para>

	<orderedlist>
	  <listitem>
	    <para>Use <sgmltag>big</sgmltag> e 
	      <sgmltag>small</sgmltag>
	      em torno do texto que você deseja mudar o 
	      tamanho.  Estas tags podem ser aninhadas, assim
	      <literal>&lt;big&gt;&lt;big&gt;Este é muito 
	      maior&lt;/big&gt;&lt;/big&gt;</literal> é 
	      possível.</para>
	  </listitem>

	  <listitem>
	    <para>Use <sgmltag>font</sgmltag> com o atributo
	      <literal>size</literal> ajustado para 
	      <literal>+1</literal> ou <literal>-1</literal> 
	      respectivamente.  Isto tem o mesmo efeito que
	      <sgmltag>big</sgmltag> ou <sgmltag>small</sgmltag>.  
	      Entretanto esta forma está ultrapassada.</para>
	  </listitem>

	  <listitem>
	    <para>Use <sgmltag>font</sgmltag> com o atributo
	     <literal>size</literal> com um número entre
	     <literal>1</literal> e <literal>7</literal>.
	     O tamanho da fonte padrão é 
	     <literal>3</literal>.  Esta forma está 
	     ultrapassada.</para>
	  </listitem>
	</orderedlist>

	<example>
	  <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, e
	    <sgmltag>font</sgmltag></title>

	  <para>Todos os fragmentos fazem a mesma coisa.</para>

	  <programlisting><![CDATA[<p>Este texto é <small>ligeiramente menor</small>. 
Mas este texto é <big>ligeiramente maior</big>.</p>

<p>Este texto é <font size="-1">ligeiramente menor</font>. 
Mas este texto é <font size="+1">ligeiramente maior</font>.</p>

<p>Este texto é <font size="2">ligeiramente menor</font>.  
Mas este texto é <font size="4">ligeiramente maior</font>.</p>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Links</title>

      <note>
	<para>Os links também são elementos in-line.</para>
      </note>

      <sect3>
	<title>Ligando-se a Outros Documentos</title>

	<para>Para incluir um link para outro documento na WWW 
	  você deve saber o URL do documento ao qual deseja se 
	  ligar.</para>

	<para>O link é indicado com <sgmltag>a</sgmltag>, e o 
	  atributo <literal>href</literal> contém o URL do 
	  documento de destino.  O conteúdo do elemento se torna o 
	  link, e geralmente é indicado para o usuário 
	  de alguma maneira (sublinhado, mudança de cor, o
	  formato do cursor do mouse muda quando está sobre 
	  ele, etc.</para>

	<example>
	  <title>Usando <literal>&lt;a href="..."&gt;</literal>
	    </title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p>Maiores informações estão disponíveis no 
<a href="http://www.FreeBSD.org/">web site do FreeBSD</a>.</p>]]></programlisting>
	</example>

	<para>Este link irá levar o usuário ao topo do 
	  documento escolhido.</para>
      </sect3>

      <sect3>
	<title>Ligando-se a Outras Partes de um Documento</title>

	<para>Para fazer um link a um ponto dentro de outro 
	  documento (ou dentro do mesmo documento), é 
	  necessário que o autor do documento inclua 
	  âncoras ao qual você possa se ligar.</para>

	<para>Âncoras são indicadas com 
	  <sgmltag>a</sgmltag> e o atributo <literal>name</literal> 
	  ao invés de <literal>href</literal>.</para>

	<example>
	  <title>Usando <literal>&lt;a name="..."&gt;</literal>
	    </title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<p><a name="para1">Este</a> parágrafo pode ser referenciado
em outros links com o nome<tt>para1</tt>.</p>]]></programlisting>
	</example>

	<para>Para fazer um link a uma determinada parte de um 
	  documento, faça um link normal para aquele documento,
	  mas inclua o nome da âncora após o 
	  símbolo <literal>#</literal>.</para>

	<example>
	  <title>Link para uma determinada parte de outro 
	    documento</title>

	  <para>Suponha que o exemplo <literal>para1</literal> esteja
	    em um documento chamado <filename>foo.html</filename>.
	    </para>

	  <programlisting><![CDATA[<p>Mais informação no <a href="foo.html#para1">primeiro 
parágrafo</a> de <tt>foo.html</tt>.</p>]]>
          </programlisting>
	</example>

	<para>Se você for incluir um link para uma âncora
	  dentro do mesmo documento você pode omitir o URL do 
	  documento, e usar apenas o nome da âncora (precedido 
	  por <literal>#</literal>).</para>

	<example>
	  <title>Links para determinada parte do mesmo 
	    documento</title>

	  <para>Suponha que o exemplo <literal>para1</literal> esteja neste documento</para>

	  <programlisting><![CDATA[<p>Mais informação no <a href="#para1">primeiro 
parágrafo</a> deste documento.</p>]]></programlisting>
	</example>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="sgml-markup-docbook">
    <title>DocBook</title>

    <para>O DocBook foi originalmente desenvolvido por HaL Computer 
      Systems e O'Reilly &amp; Associates como um DTD para escrever 
      documentação técnica
      <footnote><para>Uma pequena história sobre este assunto 
      pode ser encontrada em
      <ulink url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
      http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.
      </para></footnote>.  E desde 1998 tem sido mantido pelo 
      <ulink
      url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
      DocBook Technical Committee</ulink>.  Desta forma, ao 
      contrário do LinuxDoc e do HTML, o DocBook é 
      fortemente orientado a marcação que descreve
      <emphasis>o que</emphasis> é alguma coisa, ao 
      invés de descrever <emphasis>como</emphasis> ela deve 
      ser apresentada.</para>

    <note>
      <title>Formal Versus Informal</title>

      <para>Alguns elementos podem existir em duas formas, 
	<emphasis>formal</emphasis> e <emphasis>informal</emphasis>.
	Tipicamente, a versão formal dos elementos 
	consistirá de um título seguido da 
	versão informal do elemento.  A versão informal 
	não terá um título.</para>
    </note>

    <para>O DocBook DTD está disponível na 
      coleção de ports como 
      <filename role="package">textproc/docbook</filename>.  
      Ele é automaticamente instalado como parte do port
      <filename role="package">textproc/docproj</filename>.</para>

    <sect2>
      <title>Extensões FreeBSD</title>

      <para>O Projeto de Documentação do FreeBSD 
	ampliou o DocBook DTD adicionando alguns elementos novos.  
	Estes elementos têm como objetivo tornar algumas 
	marcações mais precisas.</para>

      <para>Os elementos específicos introduzidos pelo FreeBSD 
	estarão claramente destacados quando forem listados 
	abaixo.</para>

      <para>No restante deste documento, o termo 
	<quote>DocBook</quote> deve ser interpretado como sendo a
	versão do DocBook DTD ampliado pelo projeto de 
	documentação do FreeBSD.</para>

      <note>
	<para>Não existe nada nestas extenssões
	  que seja específico ao FreeBSD, apenas percebemos
	  que elas seriam melhorias para este projeto em particular. 
	  Se alguém dos demais projetos *nix (NetBSD, OpenBSD, 
	  Linux, ...) tiver interesse em colaborar para a
	  criação de um conjunto de extensões 
	  DocBook padrão, por favor entre em 
	  contato com &a.doceng;.</para>
      </note>

      <para>As extensões &os; não estão 
	(atualmente) na coleção de ports.  Elas 
	estão armazenadas na árvore Subversion do &os;, 
	como <ulink
	url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">
	head/share/xml/freebsd.dtd</ulink>.</para>
    </sect2>

    <sect2>
      <title>Identificador Formal Público (IFP)</title>

      <para>De acordo com as diretrizes DocBook para a escrita de 
	IPF's para adaptação do DocBook, o IPF para 
	o DocBook estendido do FreeBSD é:</para>

	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
    </sect2>

    <sect2>
      <title>Estrutura dos Documentos</title>

      <para>DocBook permite que você estruture sua 
	documentação de várias maneiras.  No 
	projeto de documentação do FreeBSD nós 
	estamos utilizando dois tipos primários de documentos 
	DocBook: o livro e o artigo.</para>

      <para>Um livro é organizado em  
	<sgmltag>chapter</sgmltag>s (capítulos).  Isso é um 
	requerimento obrigatório.  Podem existir 
	<sgmltag>part</sgmltag>s (partes) entre o livro e os 
	capítulos para fornecer mais uma camada de 
	organização.  O Handbook, por exemplo, 
	é organizado desta maneira.</para>

      <para>Um capítulo pode (ou não) conter uma ou mais
	sessões.  Estas são indicadas pelo elemento
	<sgmltag>sect1</sgmltag>.  Se uma sessão 
	contém outra sessão, então use o 
	elemento <sgmltag>sect2</sgmltag>, e assim por diante 
	até <sgmltag>sect5</sgmltag>.</para>

      <para>Capítulos e sessões contém o 
	restante do conteúdo.</para>

      <para>Um artigo é mais simples do que um livro, e 
	não usa capítulos.  Ao invés disso, o
	conteúdo de um artigo é organizado em uma ou 
	mais sessões, usando os mesmos elementos 
	<sgmltag>sect1</sgmltag> (e <sgmltag>sect2</sgmltag> e assim por
	diante) que são usados nos livros.</para>

      <para>Obviamente, você deve considerar a natureza da
	documentação que você esta escrevendo 
	para poder decidir se é melhor uma 
	marcação formatada como um livro ou um artigo.
	Artigos suportam bem informações
	que não precisam ser divididas em capítulos, 
	isto é, relativamente pequena, com mais ou menos 20 
	a 25 páginas de conteúdo.  Livros suportam 
	melhor informações que se dividem em 
	capítulos com apêndices e conteúdos similares.
	</para>
	
      <para>Os <ulink url="&url.base;/docs.html">tutoriais sobre 
	FreeBSD</ulink> estão marcados na forma de artigos, 
	enquanto por exemplo este documento, 
	o <ulink url="&url.books.faq;/index.html">FAQ do FreeBSD</ulink>, 
	e o <ulink url="&url.books.handbook;/index.html">Handbook do 
	FreeBSD</ulink> estão marcados na forma como livros.</para>

      <sect3>
	<title>Iniciando um Livro</title>

	<para>O conteúdo de um livro deve estar contido 
	  dentro do elemento <sgmltag>book</sgmltag>.  Assim como 
	  outros elementos de marcação estrutural, esse 
	  elemento pode conter elementos que incluam 
	  informações adicionais sobre o livro.  Isto 
	  é tanto meta-informação, utilizada para 
	  fins de referência, ou conteúdo adicional 
	  usado para produzir uma página de 
	  título.</para>

	<para>Estas informações adicionais devem estar
	  contidas dentro do elemento <sgmltag>bookinfo</sgmltag>.</para>

	<example>
	  <title>Modelo padrão <sgmltag>book</sgmltag> com 
	    <sgmltag>bookinfo</sgmltag></title>

	  <!-- Can't put this in a marked section because of the
	       replaceable elements -->
	  <programlisting>&lt;book>
  &lt;bookinfo>
    &lt;title><replaceable>Seu título aqui</replaceable>&lt;/title>
    
    &lt;author>
      &lt;firstname><replaceable>Seu primeiro nome aqui</replaceable>&lt;/firstname>
      &lt;surname><replaceable>Seu sobrenome</replaceable>&lt;/surname>
      &lt;affiliation>
        &lt;address>&lt;email><replaceable>Seu endereço de correio eletrônico aqui</replaceable>&lt;/email>&lt;/address>
      &lt;/affiliation>
    &lt;/author>

    &lt;copyright>
      &lt;year><replaceable>1998</replaceable>&lt;/year>
      &lt;holder role="mailto:<replaceable>seu endereço de email</replaceable>"><replaceable>Seu nome</replaceable>&lt;/holder>
    &lt;/copyright>

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>

    &lt;abstract>
      &lt;para><replaceable>Inclua um resumo do conteúdo do seu livro aqui.</replaceable>&lt;/para>
    &lt;/abstract>
  &lt;/bookinfo>

  &hellip;

&lt;/book></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Começando um Artigo</title>

	<para>O conteúdo do artigo deve estar contido dentro 
	  do elemento <sgmltag>article</sgmltag>.   Assim como
          outros elementos de marcação estrutural,
	  esse elemento pode conter elementos que incluam 
	  informações adicionais sobre o artigo.  
	  Isto é tanto meta-informação,
          utilizada para fins de referência, ou conteúdo 
	  adicional usado para produzir uma página de 
	  título.</para>
	  
	<para>Estas informações adicionais devem estar 
	  contidas dentro do elemento 
	  <sgmltag>articleinfo</sgmltag>.</para>

	<example>
	  <title>Modelo padrão <sgmltag>article</sgmltag> com 
	    <sgmltag>articleinfo</sgmltag></title>

	  <!-- Can't put this in a marked section because of the
	       replaceable elements -->
	  <programlisting>&lt;article>
  &lt;articleinfo>
    &lt;title><replaceable>Seu título aqui</replaceable>&lt;/title>
    
    &lt;author>
      &lt;firstname><replaceable>Seu primeiro nome</replaceable>&lt;/firstname>
      &lt;surname><replaceable>Seu sobrenome</replaceable>&lt;/surname>
      &lt;affiliation>
        &lt;address>&lt;email><replaceable>Seu endereço de email</replaceable>&lt;/email>&lt;/address>
      &lt;/affiliation>
    &lt;/author>

    &lt;copyright>
      &lt;year><replaceable>1998</replaceable>&lt;/year>
      &lt;holder role="mailto:<replaceable>seu endereço de email</replaceable>"><replaceable>Seu nome</replaceable>&lt;/holder>
    &lt;/copyright>

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>

    &lt;abstract>
      &lt;para><replaceable>Inclua um resumo do conteúdo do artigo aqui.</replaceable>&lt;/para>
    &lt;/abstract>
  &lt;/articleinfo>

  &hellip;

&lt;/article></programlisting>
	</example>	
      </sect3>
      <sect3>
	<title>Indicando Capítulos</title>

	<para>Utilize <sgmltag>chapter</sgmltag> para marcar seus 
	  capítulos.  Cada capítulo tem 
	  obrigatoriamente um <sgmltag>title</sgmltag>.  
	  Artigos não contêm capítulos, estes 
	  são reservados para os livros.</para>

	<example>
	  <title>Um capítulo simples</title>

	  <programlisting><![CDATA[<chapter>
  <title>Título do capítulo</title>

  ...
</chapter>]]></programlisting>
	</example>

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

	<example>
	  <title>Capítulos Vazios</title>

	  <programlisting><![CDATA[<chapter>
  <title>Isto é um capítulo vazio</title>

  <para></para>
</chapter>]]></programlisting>	    
	</example>
      </sect3>

      <sect3>
	<title>Sessões Abaixo dos Capítulos</title>

	<para>Em um livro, os capítulos podem (mas não 
	é obrigatoriamente necessário) ser 
	quebrados em seções, subseções, 
	e assim por diante.  Em um artigo, as seções 
	são os principais elementos estruturais, e cada artigo 
	deve conter pelo menos uma seção.  Utilize o 
	elemento <sgmltag>sect<replaceable>n</replaceable></sgmltag>.  O 
	<replaceable>n</replaceable> indica o número da 
	seção o qual identifica o nível da 
	seção.</para>

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

	<example>
	  <title>Seções em Capítulos</title>

	  <programlisting><![CDATA[<chapter>
  <title>Um exemplo de capítulo</title>

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

  <sect1>
    <title>Primeira seção (1.1)</title>

    &hellip;
  </sect1>

  <sect1>
    <title>Segunda seção (1.2)</title>

    <sect2>
      <title>Primeira subseção (1.2.1)</title>

      <sect3>
        <title>Primeira sub-subseção (1.2.1.1)</title>

        &hellip;
      </sect3>
    </sect2>

    <sect2>
      <title>Segunda subseção (1.2.2)</title>

      &hellip;
    </sect2>
  </sect1>
</chapter>]]></programlisting>
	</example>
	
	<note>
	  <para>Este exemplo inclui os números das 
	    seções nos títulos de 
	    seções.  Você não deve fazer 
	    isso nos seus documentos.  A inserção dos 
	    números de seção é realizada 
	    pelas folhas de estilo (falaremos delas mais a frente), e 
	    você não precisa gerenciá-los 
	    manualmente.</para>
	</note>
      </sect3>

      <sect3>
	<title>Subdividindo Utilizando o Elemento 
	  <sgmltag>Part</sgmltag></title>

	<para>Você pode introduzir outra camada de 
	  organização entre <sgmltag>book</sgmltag> e
	  <sgmltag>chapter</sgmltag> utilizando uma ou mais 
	  <sgmltag>part</sgmltag>s.  Isto não pode ser 
	  feito em um <sgmltag>article</sgmltag>.</para>

	<programlisting><![CDATA[<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>]]></programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Elementos de Blocos</title>

      <sect3>
	<title>Parágrafos</title>
	
	<para>O DocBook suporta três tipos de parágrafos:
	  <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, e 
	  <sgmltag>simpara</sgmltag>.</para>
	
	<para>Na maioria das vezes você só vai precisar 
	  usar <sgmltag>para</sgmltag>.  O 
	  <sgmltag>formalpara</sgmltag> inclui um elemento 
	  <sgmltag>title</sgmltag>, e o <sgmltag>simpara</sgmltag>
	  desabilita alguns elementos dentro de 
	  <sgmltag>para</sgmltag>.  Fique com o 
	  <sgmltag>para</sgmltag>.</para>
	
	<example>
	  <title><sgmltag>para</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>Isso é um parágrafo.  E pode conter quase 
  qualquer outro elemento.</para> ]]></programlisting>

	  <para>Aparência:</para>
	
	  <para>Isso é um parágrafo.  E pode conter 
	    quase qualquer outro elemento.</para>
	</example>
      </sect3>

      <sect3>
	<title>Bloco de Citações</title>
	
	<para>Um bloco de citação é uma longa 
	  citação de outro documento que não 
	  deveria aparecer no parágrafo atual.  Você 
	  não irá usá-lo com muita 
	  frequência.</para>
	
	<para>Um bloco de citação pode conter 
	  opcionalmente um título e uma atribuição 
	  (ou eles podem ser deixados sem título e sem 
	  atributos)</para>

	<example>
	  <title><sgmltag>blockquote</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>Um pequeno pedaço da Constituição dos Estados Unidos:</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>]]></programlisting>

	  <para>Aparência:</para>

		<para>Um pequeno pedaço da
		Constituição dos Estados Unidos</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>	
	</example>
      </sect3>

      <sect3>
	<title>Dicas, notas, avisos, informações 
	  importantes e sidebars.</title>
	
	<para>Talvez você precise incluir 
	  informações extras separadas do corpo
	  principal do texto.  Tipicamente isto é 
	  <quote>meta</quote> informação que o 
	  usuário deve tomar conhecimento.</para>
	
	<para>Dependendo da natureza da informação, 
	  devemos utilizar o elemento <sgmltag>tip</sgmltag>, 
	  <sgmltag>note</sgmltag>, <sgmltag>warning</sgmltag>, 
	  <sgmltag>caution</sgmltag>, ou <sgmltag>important</sgmltag>.
	  Alternativamente, se a informação é 
	  relacionada ao corpo principal do texto e não se 
	  encaixa em nenhum dos objetos acima, utilize 
	  <sgmltag>sidebar</sgmltag>.</para>

	<para>As circunstâncias na qual se deve escolher um elemento ao invés
	do outro não é clara.  A documentação do DocBook sugere que:
</para>
	
	<itemizedlist>
	  <listitem>
	    <para>A <sgmltag>note</sgmltag> é uma 
	    informação que deve ser lida por todos 
	    os leitores.</para>
	  </listitem>
	
	  <listitem>
	    <para>A <sgmltag>important</sgmltag> é uma 
	      variação do <sgmltag>note</sgmltag>.
	      </para>
	  </listitem>
	
	  <listitem>
	    <para>A <sgmltag>caution</sgmltag> é usada para
	      informar sobre uma possível perda de dados ou 
	      possível dano causado pelo software.</para>
	  </listitem>
	
	  <listitem>
	    <para>O <sgmltag>warning</sgmltag> é usado para 
	      informações sobre possíveis danos 
	      ao hardware, sobre risco de vida ou de ferimento a um 
	      membro.</para>
	  </listitem>
	</itemizedlist>
	
	<example>
	  <title><sgmltag>warning</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<warning>
<para>Instalar o FreeBSD talvez faça com que você queira
desinstalar o Windows do seu Hard disk.</para>
</warning>]]></programlisting>
	  </example>
	
	<para>Aparência:</para>
	<!-- Need to do this outside of the example -->
	<warning>
	  <para>Instalar o FreeBSD talvez faça com que 
	    você queira desinstalar o Windows do seu Hard 
	    disk.</para>
	</warning>	
      </sect3>

      <sect3>
	<title>Listas e Procedimentos</title>
	
	<para>Você frequentemente vai precisar listar 
	  fragmentos de informação para o 
	  usuário, ou apresentar para eles um passo a passo 
	  o qual eles devem seguir para alcançar um objetivo 
	  específico.</para>
	
	<para>Para fazer isso, utilize 
	  <sgmltag>itemizedlist</sgmltag>, 
	  <sgmltag>orderedlist</sgmltag>, ou
	  <sgmltag>procedure</sgmltag> <footnote><para>Há 
	  outros tipos de elementos de lista no DocBook, mas 
	  não vamos nos preocupar com eles no momento.</para>
	  </footnote>.
	</para>
	
	<para>Os elementos <sgmltag>itemizedlist</sgmltag> e
	  <sgmltag>orderedlist</sgmltag> são similares aos 
	  seus equivalentes em HTML, <sgmltag>ul</sgmltag> e 
	  <sgmltag>ol</sgmltag>.  Cada um consiste de um ou mais
	  elementos <sgmltag>listitem</sgmltag>, e cada 
	  <sgmltag>listitem</sgmltag> contém um ou mais 
	  elementos de bloco.  O elemento <sgmltag>listitem</sgmltag>
	  é analogo à <sgmltag>li</sgmltag> do HTML.  
	  Entretanto, ao contrário do que ocorre no HTML, aqui
	  elas são obrigatórias.</para>
	
	<para>O elemento <sgmltag>procedure</sgmltag> é 
	  ligeiramente diferente.  Ele consiste de 
	  <sgmltag>step</sgmltag>s, que por sua vez consistem de 
	  mais <sgmltag>step</sgmltag>s ou 
	  <sgmltag>substep</sgmltag>s.  Cada <sgmltag>step</sgmltag> 
	  contém elementos de bloco.</para>

	<example>
	  <title><sgmltag>itemizedlist</sgmltag>,
	    <sgmltag>orderedlist</sgmltag>, e
	    <sgmltag>procedure</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<itemizedlist>
  <listitem>
    <para>Esse é o primeiro item enumerado.</para>
  </listitem>

  <listitem>
    <para>Esse é o segundo item enumerado.</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 isto.</para>
  </step>

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

  <step>
    <para>E agora faça isto.</para>
  </step>
</procedure>]]></programlisting>
	
	  <para>Aparência:</para>
	
	  <itemizedlist>
	    <listitem>
	      <para>Esse é o primeiro item enumerado.</para>
	    </listitem>
	
	    <listitem>
	      <para>Esse é o segundo item enumerado.</para>
	    </listitem>
	  </itemizedlist>
	
	  <orderedlist>
	    <listitem>
	      <para>Esse é o primeiro item ordenado.</para>
	    </listitem>
	
	    <listitem>
	      <para>Esse é o segundo item ordenado.</para>
	    </listitem>
	  </orderedlist>
	</example>

	<!-- Can't have <procedure> inside <example>, so this is a cheat -->
	
	<procedure>
	  <step>
	    <para>Faça isto.</para>
	  </step>
	
	  <step>
	    <para>Depois faça isto.</para>
	  </step>
	
	  <step>
	    <para>E agora faça isto.</para>
	  </step>
	</procedure>	
      </sect3>

      <sect3>
	<title>Mostrando Amostras de Arquivos</title>
	
	<para>Se você quiser mostrar um trecho de um 
	  arquivo (ou talvez um arquivo inteiro) ao usuário, 
	  use o elemento <sgmltag>programlisting</sgmltag></para>
	
	<para>Espaços e quebras de linha 
	  <emphasis>são</emphasis> importantes dentro do 
	  <sgmltag>programlisting</sgmltag>.  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 espúrias podem ser 
	  incluídas.</para>
	
	<example>
	  <title><sgmltag>programlisting</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>Quando você tiver terminado, seu programa deve estar assim:</para>

<programlisting>#include &lt;stdio.h&gt;

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

	  <para>Note como os colchetes na linha 
	    <literal>#include</literal> precisaram ser referenciados
	    através de suas entidades ao invés de 
	    incluídas literalmente.</para>
	
	  <para>Aparência:</para>
	
	  <para>Quando você tiver terminado, seu programa 
	    deve estar assim;</para>
	
	  <programlisting>#include &lt;stdio.h&gt;

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

      <sect3>
	<title>Chamadas</title>

	<para>Uma chamada é um mecanismo para fazer 
	  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>

	<para>Para fazer isso, marque as áreas de interesse 
	  no seu exemplo (<sgmltag>programlisting</sgmltag>, 
	  <sgmltag>literallayout</sgmltag>, ou o que for) com o 
	  elemento <sgmltag>co</sgmltag>.  Cada elemento deve ter 
	  um <literal>id</literal> único atribuído a ele.
	  Insira um  <sgmltag>calloutlist</sgmltag> no final do
	  exemplo acima fazendo referência de volta a ele, 
	  exibindo comentários adicionais.</para>
	  	
	<example>
	  <title><sgmltag>co</sgmltag> e
	    <sgmltag>calloutlist</sgmltag></title>

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

<programlisting>#include &lt;stdio.h&gt; <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>]]></programlisting>

	  <para>Aparência:</para>

	  <para>Quando você tiver terminado, seu programa 
	    deve estar assim;</para>

	  <programlisting>#include &lt;stdio.h&gt; <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> escreve
		<literal>hello, world</literal> na saída padrão
	</para>
	    </callout>
	  </calloutlist>	
	</example>
      </sect3>

      <sect3>
	<title>Tabelas</title>

	<para>Ao contrário do HTML, você não 
	  precisa usar tabelas para acertar o layout, as folhas de 
	  estilo cuidam disto para você.  Utilize tabelas 
	  apenas para marcação de dados tabulares.</para>

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

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

	<example>
	  <title><sgmltag>informaltable</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<informaltable pgwide="1">
  <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>]]></programlisting>
	
	  <para>Aparência:</para>
	
	  <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>
	</example>

	<para>Sempre utilize o atributo <literal>pgwide</literal>
	  com o valor <literal>1</literal> junto ao elemento
	  <sgmltag>informaltable</sgmltag>.  Um bug no Internet 
	  Explorer pode fazer com que a tabela renderize de forma 
	  incorreta se ele for omitido.</para>
	
	<para>Se você não quiser borda na tabela 
	  adicione o atributo <literal>frame</literal> ao elemento
	  <sgmltag>informaltable</sgmltag> com o valor 
	  <literal>none</literal> (i.e., <literal>&lt;informaltable 
	  frame="none"&gt;</literal>).</para>


	<example>
	  <title>Tabelas com <literal>frame="none"</literal></title>
	
	  <para>Aparência:</para>
	
	  <informaltable frame="none" pgwide="1">
	    <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>
	</example>
      </sect3>

      <sect3>
	<title>Exemplos para o Usuário Seguir</title>
	
	<para>Muitas vezes você irá precisar mostrar 
	  exemplos para que o usuário siga.  Normalmente, 
	  isso irá consistir de diálogos com o 
	  computador, nos quais o usuário digita um comando, 
	  e obtém uma resposta de volta, ele digita outro 
	  comando e recebe outra reposta, e assim por diante.</para>

	<para>Vários elementos e entidades podem ser utilizados
	  nestes casos.</para>
	
	<variablelist>
	  <varlistentry>
	    <term><sgmltag>screen</sgmltag></term>
	
	    <listitem>
	      <para>Tudo que o usuário visualizar neste exemplo 
		estará na tela do computador, assim o 
		próximo elemento é 
		<sgmltag>screen</sgmltag>.</para>

	      <para>Dentro da marcação do 
		<sgmltag>screen</sgmltag>, espaços em branco
		são significativos.</para>
	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><sgmltag>prompt</sgmltag>,
	      <literal>&amp;prompt.root;</literal> e
	      <literal>&amp;prompt.user;</literal></term>
	
	    <listitem>

	      <para>Algumas das coisas que o usuário 
		irá visualizar na tela  
		são prompts do computador (seja do 
		sistema operacional, da linha de comando shell ou 
		de uma aplicação).  Estes prompts devem
		ser marcados usando <sgmltag>prompt</sgmltag>.</para>

	      <para>Por serem especiais, os prompts de shell do 
		usuário normal e do usuário root 
		estão disponíveis como uma entidade.  
		Sempre que quiser indicar que o usuário 
		está em um prompt do shell, use 
		<literal>&amp;prompt.root;</literal> para o
		usuário root e 
		<literal>&amp;prompt.user;</literal> para o 
		usuário normal, conforme for necessário.  
		Estas entidades não precisam estar dentro de
		um <sgmltag>prompt</sgmltag>.</para>

	      <note>
		<para><literal>&amp;prompt.root;</literal> e
		  <literal>&amp;prompt.user;</literal> são
		  extensões do FreeBSD ao DocBook, e 
		  não são parte do DTD original.</para>
	      </note>
	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><sgmltag>userinput</sgmltag></term>
	
	    <listitem>
	      <para>Quanto estiver mostrando um texto que o 
		usuário deva digitar, envolva-o com as tags 
		<sgmltag>userinput</sgmltag>.  Ele provavelmente 
		será mostrado diferente para o 
		usuário.</para>

	    </listitem>
	  </varlistentry>
	</variablelist>
	
	<example>
	  <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, e
	    <sgmltag>userinput</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>]]></programlisting>
	
	  <para>Aparência:</para>
	
	  <screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
	</example>
	
	<note>
	  <para>Ainda que estejamos mostrando o conteúdo do 
	    arquivo <filename>foo2</filename>, ele 
	    <emphasis>não</emphasis> está marcado como 
	    <sgmltag>programlisting</sgmltag>.  Deixe o 
	    <sgmltag>programlisting</sgmltag> para mostrar fragmentos
	    de arquivos fora do contexto de ação do 
	    usuário.</para>
	</note>
      </sect3>
    </sect2>

    <sect2>
      <title>Elementos In-line</title>

      <sect3>
	<title>Enfatizando a Informação</title>

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

	<para>Não há uma maneira de mudar a 
	  apresentação da ênfase no seu documento,
	  não existe um equivalente ao  <sgmltag>b</sgmltag> e
	  ao <sgmltag>i</sgmltag> do HTML.  Se a 
	  informação que você está 
	  apresentando é importante então considere 
	  usar <sgmltag>important</sgmltag> ao invés de
	  <sgmltag>emphasis</sgmltag>.</para>	
	
	<example>
	  <title><sgmltag>emphasis</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>O FreeBSD é sem dúvida <emphasis>o</emphasis> melhor sistema operacional tipo Unix
para a arquitetura Intel.</para>]]></programlisting>
	
	  <para>Aparência:</para>
	<para>O FreeBSD é sem dúvida 
	  <emphasis>o</emphasis> melhor sistema operacional tipo 
	  Unix para a arquitetura Intel.</para>
	</example>
      </sect3>

      <sect3>
	<title>Citações</title>

	<para>Para citar um texto de outro documento ou fonte, ou para
	  denotar uma frase que está sendo usada figuradamente, use
	  <sgmltag>quote</sgmltag>.  Dentro da tag 
	  <sgmltag>quote</sgmltag>, você pode usar a maioria 
	  das marcações disponíveis para um texto 
	  normal.</para>

	<example>
	  <title>Citações</title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[<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>]]></programlisting>

	  <para>Aparência:</para>

	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Teclas, Mouse e Combinações</title>

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

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

	<para>As folhas de estilo colocam automaticamente o 
	  símbolo de ligação, tal como 
	  <literal>+</literal>, entre os nomes das teclas, quando 
	  elas estiverem envolvidas com 
	  <sgmltag>keycombo</sgmltag>.</para>
	
	<example>
	  <title>Teclas, Mouse e Combinações</title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<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>
]]></programlisting>

	  <para>Aparência:</para>
	
	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Aplicações, Comandos, 
	  Opções e Citações</title>

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

	<para>Além disso, você eventualmente 
	  precisará listar uma ou mais opções 
	  que um comando pode aceitar.</para>

	<para>Finalmente, você irá querer listar um 
	  comando com o número da sua seção no 
	  manual, na forma <quote>comando(número)</quote> que 
	  é tão comum nos manuais de Unix.</para>
	
	<para>Você deve marcar o nome de uma 
	  aplicação com <sgmltag>application</sgmltag>.
	  </para>

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

	<para>Pode ser trabalhoso escrever desta forma, para
	  facilitar este processo foram criadas uma série de  
	  <link linkend="sgml-primer-general-entities">entidades 
	  gerais</link>.  Cada entidade está na 
	  forma <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>

	<para>O arquivo que contém estas entidades 
	  é o <filename>doc/share/xml/man-refs.ent</filename>,
	  o qual pode ser referenciado utilizando o seguinte FPI:</para>

	<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>

	<para>Portanto, a introdução à sua
	  documentação provavelmente será assim:
	</para>

	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
%man;

&hellip;

]&gt;</programlisting>


	<para>Use o elemento <sgmltag>command</sgmltag> quando quiser 
	  incluir um comando <quote>in-line</quote> para ser 
	  apresentado como algo que deveria ser digitado pelo
	  usuário.</para>

	<para>Use o elemento <sgmltag>option</sgmltag> para marcar as 
	opções que serão passadas para um 
	comando.</para>

	<para>Quando diversas referências a um mesmo comando 
	  estiverem próximas é melhor usar a 
	  notação <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
	  para marcar a primeira referência ao mesmo e depois 
	  utilizar <sgmltag>command</sgmltag> para marcar as 
	  referências subsequentes.  Isto fará a 
	  saída gerada, especialmente em HTML, ficar 
	  visualmente melhor.</para>
	
	<para>Isto pode ser confuso, e muitas vezes a escolha nem 
	  sempre é clara.  Acredito que o exemplo abaixo
	  ajudará a tornar as coisas mais claras.</para>

	<example>
	  <title>Aplicações, Comandos,
	    Opções</title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>O <application>Sendmail</application> é a aplicação 
  de email mais utilizada em Unix.</para>

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


<para>Um dos parâmetros de linha de comando para o <citerefentry>
    <refentrytitle>Sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, ira mostrar o atual estado da
  mensagem na fila de email. 
  Verifique isto na linha de comando usando <command>sendmail -bp</command>.</para>]]></programlisting>

	  <para>Aparência:</para>
	
	  <para>O <application>Sendmail</application> é a
	    aplicação de email mais utilizada em 
	    Unix.</para>
	
	  <para>O <application>Sendmail</application> inclui os programas
	    <citerefentry>
	      <refentrytitle>sendmail</refentrytitle>
	      <manvolnum>8</manvolnum>
	 		</citerefentry>, &man.mailq.1;, and &man.newaliases.1;.</para>

  	  <para>Um dos parâmetros de linha de comando para o 
	    <citerefentry><refentrytitle>sendmail</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
	    <option>-bp</option>, irá  mostrar o atual estado 
	    da mensagem na fila de email.  Verifique isto na linha de
	    comando usando <command>sendmail -bp</command>.</para>
	</example>

	<note>
	  <para>Veja como a notação
	    <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> 
	    é mais fácil de acompanhar.</para>
	</note>
      </sect3>

      <sect3>
	<title>Arquivos, Diretórios, Extensões</title>
	
	<para>Sempre que quiser se referir ao nome de um arquivo,
	  diretório ou uma extensão de arquivo, use
	  o elemento <sgmltag>filename</sgmltag>.</para>
	
	<example>
	  <title><sgmltag>filename</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>O fonte SGML do Handbook em Inglês pode ser encotrado em 
  <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.  
  O primeiro arquivo neste diretório é chamado <filename>book.xml</filename>. 
  Você também deve ver o <filename>Makefile</filename> 
  e alguns arquivos com a extensão <filename>.ent</filename>.</para>]]></programlisting>

	  <para>Aparência:</para>
	
	  <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.xml</filename>.  Você 
	    também deve ver o <filename>Makefile</filename> 
	    e alguns arquivos com a extensão 
	    <filename>.ent</filename>.</para>

	</example>
      </sect3>

      <sect3>
	<title>O Nome dos Ports</title>
	
	<note>
	  <title>Extensões FreeBSD</title>
	
	  <para>Estes elementos são parte das extensões
	    do FreeBSD ao DocBook, e não existem no DTD 
	    DocBook original.</para>
	</note>

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

	<example>
	  <title>Tag <sgmltag>filename</sgmltag>  com o atributo
	    <literal>package</literal></title>

	  <para>Use:</para>

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

	  <para>Aparência:</para>
	
	  <para>Instale o port 
	    <filename role="package">net/ethereal</filename>
	    para ver o tráfego na rede.</para>
	</example>
      </sect3>

      <sect3>
	<title>Dispositivos</title>
	
	<note>
	  <title>Extensões FreeBSD</title>
	
	  <para>Estes elementos são parte das extensões
	    do FreeBSD ao DocBook, e não existem no DTD 
	    DocBook original.</para>
	</note>

	<para>Você tem 2 opções para se referir a 
	  um dispositivo.  Você pode se referir ao dispositivo 
	  da forma como ele aparece no <filename>/dev</filename>, 
	  ou você pode usar o nome do dispositivo como ele aparece 
	  no kernel.  No segundo caso, use o elemento
	  <sgmltag>devicename</sgmltag>.</para>	

	<para>Em alguns casos você não terá escolha.  
	  Alguns dispositivos, como as placas de rede, não 
	  tem entrada no <filename>/dev</filename>, ou as entradas 
	  são muito diferentes das esperadas.</para>	
	
	<example>
	  <title><sgmltag>devicename</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[
<para><devicename>sio</devicename> é 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>]]></programlisting>

	<para>Aparência:</para>
	<para><devicename>sio</devicename> é 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>	

	</example>
      </sect3>
	
      <sect3>
	<title>Hosts, Domínios, Endereços IP e etc.</title>
	
	<note>
	  <title>Extensões FreeBSD</title>
	
	  <para>Estes elementos são parte das extensões
	    do FreeBSD ao DocBook, e não existem no DTD 
	    DocBook original.</para>
	</note>

	<para>Você pode marcar a informação sobre
	  a identificação de computadores em rede 
	  (hosts) de diversas maneiras.  Todas elas usam 
	  <sgmltag>hostid</sgmltag> como elemento, com o atributo 
	  <literal>role</literal> dizendo o tipo da 
	  informação marcada.</para>	
	
	<variablelist>
	  <varlistentry>
	    <term>Sem o atributo <literal>role</literal>, ou 
	      <literal>role="hostname"</literal></term>
	
	    <listitem>
	      <para>Sem o atributo <literal>role</literal> (i.e.,
		<sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>)
		a informação marcada é 
		simplesmente o nome do computador, tal como 
		<literal>freefall</literal> ou 
		<literal>wcarchive</literal>.  Você pode 
		especificar explicitamente com 
		<literal>role="hostname"</literal>.</para>
	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><literal>role="domainname"</literal></term>
	
	    <listitem>
	      <para>O texto é um nome de domínio, tal 
		como <literal>FreeBSD.org</literal> ou
		<literal>ngo.org.uk</literal>.  Não há o
		componente do nome do computador (hostname).</para>

	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><literal>role="fqdn"</literal></term>
	
	    <listitem>
	      <para>O texto é um nome completo, com o nome do
		computador e do domínio.  O termo
		<literal>fqdn</literal> significa <quote>Fully 
		Qualified Domain Name</quote> - Nome de 
		Domínio Completamente Qualificado.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="ipaddr"</literal></term>
	
	    <listitem>
	      <para>O texto é um endereço IP, 
		provavelmente expresso como <literal>dotted 
		quad</literal>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="ip6addr"</literal></term>

	    <listitem>
	      <para>O texto é um endereço IPv6.</para>
	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><literal>role="netmask"</literal></term>
	
	    <listitem>
	      <para>O texto é uma máscara de rede, que 
		pode ser expressa como <literal>dotted quad</literal>,
		uma string hexadecimal ou como <literal>/</literal> 
		seguido de um número.</para>
	    </listitem>
	  </varlistentry>
	
	  <varlistentry>
	    <term><literal>role="mac"</literal></term>
	
	    <listitem>
	      <para>O texto é um endereço MAC Ethernet,
		expresso como números hexadecimais de 2 digitos
		separados por dois pontos (:).</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
	<example>
	  <title><sgmltag>Hostid</sgmltag> e <literal>Roles</literal></title>
	
	  <para>Use:</para>
	
	  <programlisting><![CDATA[
<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ínio <hostid role="domainname">FreeBSD.org</hostid>
contém vários hosts diferentes, incluindo 
<hostid role="fqdn">freefall.FreeBSD.org</hostid> e 
<hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>

<para>Quando estiver adicionando um apelido para uma interface (usando 
<command>ifconfig</command>) <emphasis>sempre</emphasis> use a
máscara de rede <hostid role="netmask">255.255.255.255</hostid> (que
também pode ser 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 se parece com  <hostid
role="mac">08:00:20:87:ef:d0</hostid>).</para>
]]></programlisting>

	  <para>Aparência:</para>
	
	  <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ínio
	    <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 estiver adicionando um apelido para uma 
	    interface (usando <command>ifconfig</command>) 
	    <emphasis>sempre</emphasis> use a máscara de 
	    rede <hostid role="netmask">255.255.255.255</hostid> (que 
	    também pode ser 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 se parece com
	    <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>
	</example>
      </sect3>

      <sect3>
	<title>Usernames</title>
	
	<note>
	  <title>Extensões FreeBSD</title>
	
	  <para>Estes elementos são parte das extensões
	    do FreeBSD ao DocBook, e não existem no DTD 
	    DocBook original.</para>
	</note>

	<para>Quando precisar se referir a um nome de usuário
	  específico, tal como <literal>root</literal> ou
	  <literal>bin</literal>, use o elemento 
	  <sgmltag>username</sgmltag>.</para>	
	
	<example>
	  <title><sgmltag>Username</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[<para>Para executar a maioria das funções administrativas você precisará 
  ser <username>root</username>.</para>]]></programlisting>

	  <para>Aparência:</para>
	
	  <para>Para executar a maioria das funções 
	    administrativas você precisará ser 
	    <username>root</username>.</para>
	</example>
      </sect3>

      <sect3>
	<title>Descrevendo <filename>Makefile</filename>s</title>
	
	<note>
	  <title>Extensões FreeBSD</title>
	
	  <para>Estes elementos são parte das extensões
	    do FreeBSD ao DocBook, e não existem no DTD 
	    DocBook original.</para>
	</note>

	<para>Existem dois elementos para descrever partes de
	  <filename>Makefile</filename>s, 
	  <sgmltag>maketarget</sgmltag> e <sgmltag>makevar</sgmltag>.
	  </para>	

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

	<example>
	  <title><sgmltag>Maketarget</sgmltag> e
	    <sgmltag>Makevar</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[
<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) criados
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>
]]></programlisting>

	  <para>Aparência:</para>
	
	  <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) criados pelo processo de 
	    construção.</para>

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

      <sect3>
	<title>Texto Literal</title>

	<para>Com frequência você irá precisar 
	  incluir texto <quote>literal</quote> na 
	  documentação.  Este texto que é 
	  originado de outro arquivo, ou que deve ser copiado de
	  forma fiel da documentação para outro 
	  arquivo.</para>	

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

	<para>Nestas ocasiões, use <sgmltag>literal</sgmltag>.
	  </para>
	
	<example>
	  <title><sgmltag>Literal</sgmltag></title>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[ <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 simultâneos
o sistema irá suportar.</para>
]]></programlisting>

	  <para>Aparência:</para>
	  <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 simultâneos o sistema irá 
	    suportar.</para>
	
	</example>
      </sect3>
	
      <sect3>
	<title>Mostrando Itens que o Usuário 
	  <emphasis>Deve</emphasis> Preencher</title>

	<para>Muitas vezes você irá querer mostrar ao 
	  usuário o que fazer, ou precisará se referir a
	  um arquivo, a uma linha de comando ou coisa parecida, na 
	  qual ele não poderá simplesmente copiar o 
	  exemplo que você forneceu, mas na qual ele 
	  terá deve dar alguma informação por 
	  ele mesmo.</para>	

	<para>O elemento <sgmltag>replaceable</sgmltag> foi criado para 
	  estas ocasiões.  Use ele dentro de outros elementos para 
	  indicar partes do conteúdo do elemento que o 
	  usuário deve substituir.</para>

	<example>
	  <title><sgmltag>replaceable</sgmltag></title>
	
	  <para>Uso:</para>
	
		<programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>

	  <para>Aparência:</para>
	
	  <informalexample>
	    <screen>&prompt.user; <userinput>man <replaceable>comando</replaceable></userinput></screen>
	  </informalexample>
	
	  <para>O <sgmltag>replaceable</sgmltag> pode ser usado em 
	    muitos elementos diferentes, incluindo 
	    <sgmltag>literal</sgmltag>.  Este exemplo também 
	    mostra que <sgmltag>replaceable</sgmltag> só deve 
	    envolver o conteúdo que o usuário 
	    <emphasis>deve</emphasis> fornecer.  O outro 
	    conteúdo não deve ser alterado.</para>
	
	  <para>Uso:</para>
	
	  <programlisting><![CDATA[
<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>
]]></programlisting>

	  <para>Aparência:</para>
	  <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>	
	</example>
      </sect3>

      <sect3>
	<title>Citando erros do sistema</title>

	<para>Você pode querer mostrar erros gerados pelo
	  FreeBSD.  Marque-os com <sgmltag>errorname</sgmltag>.
	  Isto indicará o erro exato que aparece.</para>
	<example>
	  <title><sgmltag>errorname</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[ 
<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
</programlisting>


	  <para>Aparência:</para>

	  <informalexample>
            <screen><errorname>Panic: cannot mount root</errorname></screen>
	  </informalexample>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Imagens</title>

      <important>
	<para>O suporte a imagem na documentação ainda
	  é extremamente experimental.  O mecanismo aqui 
	  descrito provavelmente não irá mudar, mas 
	  isto não é garantido.</para>

	<para>Você precisará instalar o port
	  <filename role="package">graphics/ImageMagick</filename>
	  que é usado para converter entre os diferentes 
	  formatos de imagens.  Ele é grande e a sua maior 
	  parte não é necessária.  Entretanto, 
	  enquanto nós ainda estamos trabalhando nos 
	  <filename>Makefile</filename>s e em outros itens da  
	  infraestrutura, ele torna as coisas mais 
	  fáceis.  Este port <emphasis>não</emphasis> 
	  está no meta port 
	  <filename role="package">textproc/docproj</filename>, 
	  você deve instalá-lo manualmente.</para>

	<para>O melhor exemplo do que acontece na prática 
	  é o documento
	  <filename>doc/en_US.ISO8859-1/articles/vm-design/
	  </filename>.  Se você se sentir inseguro na 
	  descrição que segue, dê uma olhada nos 
	  arquivos deste diretório e veja como tudo se 
	  encaixa.  Experimente criar versões com diferentes 
	  formatos de saída do documento para ver como a 
	  marcação de imagem aparece no documento final. 
	  </para>
      </important>

      <sect3>
	<title>Formatos de Imagens</title>

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

	<para>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
	  <filename>.eps</filename>.</para>

	<para>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 
	  <filename>.png</filename>.</para>

	<para>Estes são os <emphasis>únicos</emphasis>
	  formatos de imagem que podem ser gravados no 
	  repositório Subversion.</para>

	<para>Use o formato correto para a imagem correta.  Espera-se
	  que a sua documentação tenha tanto imagens
	  EPS quanto PNG.  Os <filename>Makefile</filename>s
	  asseguram que o formato correto seja escolhido dependendo
	  do formato de saída da sua 
	  documentação.  <emphasis>Não faça 
	  commit da mesma imagem nos dois formatos diferentes para o 
	  repositório</emphasis>.</para>

	<important>
	  <para>É esperado que o projeto de 
	    documentação passe a utilizar no futuro o 
	    formato Scalable Vector Graphic (SVG) para imagens 
	    vetoriais.  Entretanto, o atual estado das ferramentas
	    de edição torna isto impraticável.
	</para>
	</important>
      </sect3>

      <sect3>
	<title>Marcação</title>

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

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

	<para>Há duas circunstâncias em que isso pode 
	  ocorrer.</para>

	<itemizedlist>
	  <listitem>
	    <para>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.</para>
	  </listitem>

	  <listitem>
	    <para>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.</para>
	  </listitem>
	</itemizedlist>

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

	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="fig1"> <co id="co-image-ext"/>
  &lt;/imageobject>

  &lt;textobject>
    &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal"/>
|       A       |
+---------------+&lt;/literallayout>
  &lt;/textobject>

  &lt;textobject>
    &lt;phrase>Uma figura&lt;/phrase> <co id="co-image-phrase"/>
  &lt;/textobject>
&lt;/mediaobject></programlisting>

	<calloutlist>
	  <callout arearefs="co-image-ext">
	    <para>Inclua um elemento <sgmltag>imagedata</sgmltag> 
	      dentro do elemento <sgmltag>imageobject</sgmltag>.  
	      O atributo <literal>fileref</literal> deve conter o 
	      nome da imagem a ser incluída, sem a extensão.  
	      As folhas de estilo irão decidir qual a 
	      extensão deve ser adicionada ao nome do arquivo 
	      automaticamente.</para>
	  </callout>

	  <callout arearefs="co-image-literal">
	    <para>O primeiro <sgmltag>textobject</sgmltag> deve conter
	      um elemento <sgmltag>literallayout</sgmltag>, onde o 
	      atributo <literal>class</literal> é ajustado para
	      <literal>monospaced</literal>.  Esta é a 
	      oportunidade para você demonstrar suas habilidades
	      com ASCII art.  O conteúdo será usado se o 
	      documento for convertido para texto puro.</para>

	    <para>Veja como as primeras e últimas linhas do
	      conteúdo do elemento <sgmltag>literallayout
	      </sgmltag> fica próximo a tag do elemento.  
	      Isso assegura que não sejam incluídos 
	      espaços extras.</para>
	  </callout>

	  <callout arearefs="co-image-phrase">
	    <para>O segundo <sgmltag>textobject</sgmltag> deve conter
	      um único elemento <sgmltag>phrase</sgmltag>.  O
	      conteúdo deste elemento se tornará o atributo
	      <literal>alt</literal> para as imagens quando o 
	      documento for convertido para HTML.</para>
	  </callout>
	</calloutlist>
      </sect3>

      <sect3>
	<title>Entradas no <filename>Makefile</filename></title>

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

	<programlisting>&hellip;
IMAGES= fig1.eps fig2.png fig3.png
&hellip;</programlisting>

	<para>ou</para>

	<programlisting>&hellip;
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
&hellip;</programlisting>

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

      <sect3>
	<title>Imagens e Capítulos em Subdiretórios</title>

	<para>Você precisa ser cuidadoso quando separar a sua
	  documentação em arquivos menores (veja
	  <xref linkend="sgml-primer-include-using-gen-entities"/>) em
	  diretórios diferentes.</para>

	<para>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 <filename>chapter1/chapter.xml</filename>,
	  <filename>chapter2/chapter.xml</filename>, e
	  <filename>chapter3/chapter.xml</filename>.  Se cada 
	  capítulo tiver imagens associadas a eles, é 
	  sugerido que você as coloque dentro do respectivo 
	  subdiretório de cada capítulo 
	  (<filename>chapter1/</filename>, 
	  <filename>chapter2/</filename>, 
	  <filename>chapter3/</filename>).</para>	

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

	<para>Por exemplo, se você tiver
	  <filename>chapter1/fig1.png</filename>, então
	  <filename>chapter1/chapter.xml</filename> deve 
	  conter:</para>  	

	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/>
  &lt;/imageobject>

  &hellip;

&lt;/mediaobject></programlisting>
	
	<calloutlist>
	  <callout arearefs="co-image-dir">
	    <para>O nome do diretório deve ser incluído no 
	    atributo <literal>fileref</literal></para>
	  </callout>
	</calloutlist>

	<para>O <filename>Makefile</filename> deve conter:</para>

	<programlisting>&hellip;
IMAGES=  chapter1/fig1.png
&hellip;</programlisting>

	<para>Desta forma tudo deve funcionar.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Links</title>

      <note>
	<para>Links também são elementos in-line.</para>
      </note>

      <sect3>
	<title>Ligando-se a outras partes no mesmo documento</title>

	<para>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 a origem do link) e para onde
	  você está se ligando (o destino do 
	  link).</para>

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

	<para>Este valor será usado quando você 
	  especificar a origem do link.</para>

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

	<example>
	  <title>O atributo <literal>id</literal> em capítulos
	    ou seções</title>

	  <programlisting><![CDATA[<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>Subseção 1</title>

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

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

	<para>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 o elemento <sgmltag>anchor</sgmltag>.  Este 
	  elemento não tem conteúdo, mas aceita o atributo 
	  <literal>id</literal>.</para>

	<example>
	  <title><sgmltag>anchor</sgmltag></title>

	  <programlisting><![CDATA[<para>
Este parágrafo tem um <anchor id="para1">alvo dentro dele. 
O qual não irá aparecer no documento
</para>]]></programlisting>
	</example>
	
	<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 <literal>id</literal>, você pode usar 
	  <sgmltag>xref</sgmltag> ou <sgmltag>link</sgmltag>.</para>

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

	<para>Se você utilizar o <sgmltag>xref</sgmltag> 
	  então você não terá controle 
	  sobre o texto do link.  Ele será gerado para 
	  você.</para>	
	
	<example>
	  <title>Usando <sgmltag>xref</sgmltag></title>

	  <para>Assuma que este fragmento apareça em algum 
	    lugar de um documento que inclua o <literal>id</literal> 
	    do exemplo.</para>
	
	  <programlisting><![CDATA[
<para>Maiores informações podem ser encontradas
  em <xref linkend="chapter1"/></para>

<para>Informações mais específicas podem ser 
  encontradas na <xref linkend="chapter1-sect1"/>.</para>
]]></programlisting>

	  <para>O texto do link será gerado automaticamente, e
	    irá se parecer com (As palavras em  
	    <emphasis>itálico</emphasis> indicam o texto que 
	    será o link):</para>

	  <blockquote>
	    <para>Maiores informações podem ser encontradas
	      no <emphasis>Capítulo Um</emphasis>.</para>
	
	    <para>Informações mais específicas
	      podem ser encontradas na <emphasis>seção 
	      chamada Subseção 1</emphasis>.</para>
	  </blockquote>
	</example>

	<para>Observe como o texto do link é deduzido a 
	  partir do título da seção ou do 
	  número do capítulo.</para>	

	<note>
	  <para>Isto significa que você <emphasis>não
	    pode</emphasis> usar <sgmltag>xref</sgmltag> para se
	    ligar a um atributo <literal>id</literal> em um elemento
	    <sgmltag>anchor</sgmltag>.  O <sgmltag>anchor</sgmltag> 
	    não tem conteúdo, desta forma o 
	    <sgmltag>xref</sgmltag> não pode gerar o texto 
	    para o link.</para>
	</note>

	<para>Se você quiser controlar o texto do link 
	  você deverá utilizar  <sgmltag>link</sgmltag>.  
	  Este elemento envolve o conteúdo, e o conteúdo 
	  será usado para o link.</para>	

	<example>
	  <title>Usando <sgmltag>link</sgmltag></title>

	  <para>Assuma que este fragmento aparece em algum lugar em 
	    um documento que inclui o <literal>id</literal> do 
	    exemplo.</para>
	  
	  <programlisting><![CDATA[
<para>Maiores informações podem ser encontradas
<link linkend="chapter1">no primeiro capítulo</link>.
</para>

<para>Informações mais específicas podem ser encontradas
<link linkend="chapter1-sect1">nesta</link> seção
</para>
]]></programlisting>
	
	  <para>Isto irá gerar o seguinte (Palavras em 
	    <emphasis>itálico</emphasis> indicam o texto que 
	    será o link):</para>
	
	  <blockquote>
	    <para>Maiores informações podem ser
	      encontradas <emphasis>no primeiro capítulo
	      </emphasis>.</para>

	    <para>Informações mais específicas
	      podem ser encontradas <emphasis>nesta
	      </emphasis> seção</para>
	  </blockquote>
	</example>
	
	<note>
	  <para>Este último é um mau exemplo.  
	    Nunca use palavras como <quote>esta</quote> ou 
	    <quote>aqui</quote> como origem do link.  O leitor 
	    terá que procurar no contexto próximo para 
	    ver para onde o link o está levando.</para>
	</note>

	<note>
	  <para>Você <emphasis>pode</emphasis> usar o elemento
	    <sgmltag>link</sgmltag> para incluir um link para um
	    <literal>id</literal> em um elemento 
	    <sgmltag>anchor</sgmltag>, uma vez que o conteúdo 
	    de <sgmltag>link</sgmltag> define o texto que será 
	    usado para o link.</para>
	</note>
      </sect3>

      <sect3>
	<title>Ligando-se a documentos na WWW</title>

	<para>Ligar-se a um documento externo é muito mais 
	  simples, desde que você saiba o URL do documento ao 
	  qual deseja se ligar.  Basta utilizar o elemento 
	  <sgmltag>ulink</sgmltag>.  O atributo <literal>url
	  </literal> é 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>

	<example>
	  <title><sgmltag>ulink</sgmltag></title>

	  <para>Uso:</para>

	  <programlisting><![CDATA[
<para>É claro que você pode parar de ler este documento e ir para a
<ulink url="&url.base;/index.html">Página principal do FreeBSD</ulink>
</para>
]]></programlisting>

	  <para>Aparência:</para>

	  <para>É claro que você pode parar de ler este 
	    documento e ir para a
	    <ulink url="&url.base;/index.html">Página principal
	    do FreeBSD</ulink></para>
	</example>
      </sect3>
    </sect2>
  </sect1>
</chapter>