3.3.1.1 Arquivos de catálogo

Se você utilizar a sintaxe acima e processar este documento utilizando um processador SGML, o processador irá precisar de uma forma de associar a FPI ao nome do arquivo no seu computador o qual contém o DTD.

Para isto devemos utilizar um arquivo de catálogo. Um arquivo de catálogo (tipicamente chamado de catalog) contém linhas as quais mapeiam FPIs para nomes de arquivos. Por exemplo, se o arquivo de catálogo contiver a linha:

PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"

O processador SGML saberia que deveria procurar pelo DTD strict.dtd no subdiretório 4.0 de qualquer diretório que possuísse um arquivo catalog contendo esta linha.

Veja o conteúdo do /usr/local/share/xml/html/catalog. Este é o arquivo de catálogo para o DTD HTML o qual será instalado como parte do port textproc/docproj.

3.3.1.2 SGML_CATALOG_FILES

A fim de encontrar um arquivo de catálogo, o seu processador SGML precisará saber onde procurar. Muitos deles possuem recursos de parâmetros de linha de comando para especificar o caminho para um ou mais catálogos.

Adicionalmente, você pode definir a variável de ambiente SGML_CATALOG_FILES para apontar para os arquivos. Esta variável deve consistir de uma lista, separada por dois pontos (":"), de arquivos de catálogo (incluindo seus caminhos completos).

Tipicamente, você precisará incluir os seguintes arquivos:

• /usr/local/share/xml/docbook/4.1/catalog

• /usr/local/share/xml/html/catalog

• /usr/local/share/xml/iso8879/catalog

• /usr/local/share/xml/jade/catalog

Você já deve ter feito isto.

3.7.3.1 Utilizando entidades gerais para incluir arquivos

3.7.3.2 Utilizando uma entidade de parâmetro para incluir arquivos.

3.8.1.1 CDATA, RCDATA

Estas palavras chave denotam o modelo do conteúdo das sessões marcadas, e permitem que você o altere a partir do padrão.

Quando um interpretador SGML esta processando um documento ele tenta seguir o que chamamos de “modelo de conteúdo”

Resumidamente, o modelo de conteúdo descreve que tipo de conteúdo o interpretador esta esperando encontrar, e o que fará com ele quando o encontrar.

Os dois modelos de conteúdo que você provavelmente irá achar mais úteis são o CDATA e o RCDATA.

O CDATA é para “Dados de Caracter”. Se o interpretador está neste modelo de conteúdo então ele está esperando encontrar caracteres, e apenas caracteres. Neste modelo os símbolos < e o & perdem o seu status especial, e serão tratados como caracteres ordinários.

O RCDATA é para “Referências de entidade e dados de caracter ”. Se o interpretador está neste modelo de conteúdo ele está esperando encontrar caracteres e entidades. O símbolo < perde o seu status especial, mas o & continuará sendo tratado como o inicio de uma entidade geral.

Isto é particularmente útil se você está incluindo algum texto literal o qual contém muitos caracteres < e &. Ao invés de atravessar o texto todo tendo que verificar se todos os < estão convertidos para um &lt; e todos os & estão convertidos para um &amp; pode ser mais simples marcar a sessão como contendo apenas CDATA. Quando o interpretador SGML encontrá-los ele irá ignorar os símbolos < e & embutidos no conteúdo.

<para>Aqui está um exemplo de como você incluiria algum texto que contenha muitos 
  símbolos <literal>&lt;</literal> e <literal>&amp;</literal>.  
  O texto de exemplo é um fragmento de HTML.  
  O texto circunvizinho (<para> e <programlisting>) é do
  DocBook.</para>
	  
<programlisting>
  <![ CDATA [  
    <p>Esta é uma amostra que apresenta alguns elementos de HTML.
       Uma vez que os símbolos de < e > são utilizados muitas vezes, é
       mais fácil dizer que o exemplo todo é uma sessão marcada do
       tipo CDATA, do que utilizar nomes de entidades para representar
       estes símbolos ao longo de todo o texto.</p>

    <ul>
      <li>Este é um item de lista</li>
      <li>Este é um segundo item de lista</li>
      <li>Este é um terceiro item de lista</li>
    </ul>

    <p>Este é o final do exemplo.</p>
  ]]>
</programlisting>

3.8.1.2 INCLUDE and IGNORE

Se a palavra chave for INCLUDE então o conteúdo da sessão marcada será processado. Se a palavra chave for IGNORE então a sessão marcada será ignorada e não será processada. Ela não irá aparecer no output.

<![ INCLUDE [
  Este texto será processado e incluído.
]]>

<![ IGNORE [
  Este texto não será processado nem incluído.
]]>

Por si só, isto não é muito útil. Se você desejar remover o texto do seu documento você pode cortá-lo fora, ou comentá-lo.

Torna-se mais útil quando você utilizar entidades de parâmetro para controlá-lo. Lembre-se que entidades de parâmetro só podem ser utilizadas em um contexto SGML, e que a palavra chave de uma sessão marcada é um contexto SGML.

Por exemplo, suponha que você produza uma cópia impressa e uma versão eletrônica de alguma documentação. Você pode desejar incluir na versão eletrônica algum conteúdo extra, o qual não deve aparecer na versão impressa.

Crie uma entidade de parâmetro, e configure seu valor para INCLUDE. Escreva seu documento, usando uma sessão marcada para delimitar o conteúdo que deve aparecer apenas na versão eletrônica. Nesta sessão marcada utilize a entidade de parâmetro no lugar da palavra chave.

Quando você desejar produzir uma cópia impressa do documento, altere o valor da entidade de parâmetro para IGNORE e reprocesse o documento.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % electronic.copy "INCLUDE">	     
]]>

...

<![ %electronic.copy [
  Este conteúdo deve aparecer apenas na versão eletrônica do
  documento.
]]>

<!ENTITY % electronic.copy "IGNORE">

4.1.3.1 Cabeçalho

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

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

O conteúdo dos elementos é o texto do cabeçalho.

<h1>Primeira seção</h1>

<!-- a introdução do documento entra aqui -->

<h2>Este é o cabeçalho da primeira seção</h2>

<!-- O conteúdo da primeira seção entra aqui -->

<h3>Este é o cabeçalho da primeira subseção</h3>

<!-- O conteúdo da primeira subseção entra aqui -->

<h2>Este é o heading para a segunda seção</h2>

<!-- O conteúdo da segunda seção entra aqui -->

Geralmente, uma página HTML deveria ter um cabeçalho de primeiro nível (<h1>). Este poderia conter muitos cabeçalhos de segundo nível (<h2>), os quais por sua vez podem conter muitos cabeçalhos de terceiro nível. Cada elemento <hn> 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.

<h1>Primeira seção</h1>

<!-- Introdução do documento -->

<h3>Subseção</h3>

<!-- Isto é ruim, não foi usado <h2> -->

4.1.3.2 Parágrafos

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

<p>Isto é um parágrafo.  Pode conter qualquer outro elemento</p>

4.1.3.3 Bloco de Citação

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

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

4.1.3.4 Listas

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

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.

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

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

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

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

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

4.1.3.5 Texto Pré-Formatado

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 fazer isto, envolva o conteúdo com o elemento <pre>:

<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

	<URL:http://people.FreeBSD.org/~nik/primer/index.html>

  Comments appreciated.

  N
</pre>

4.1.3.6 Tabelas

Marque a informação tabular com o elemento <table>. Uma tabela consiste de uma ou mais linhas (<tr>), cada uma contendo uma ou mais células de dados (<td>). 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 <p>.

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

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

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

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

<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>
    <!-- Como a célula grande à esquerda funde-se com esta linha,
         o primeiro <td> ocorrerá à a sua direita. -->
    <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>

4.1.4.1 Enfatizando a Informação

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

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

<p><em>Este</em> foi enfatizado
enquanto <strong>este</strong> foi fortemente enfatizado.</p>
         

4.1.4.2 Negrito e Itálico

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 <b> e <i> respectivamente.

<p><b>Este</b> esta em negrito, 
enquanto <i>este</i> está em itálico.</p>
	 

4.1.4.3 Indicando Texto de Fonte Fixa

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

<p> Este documento foi originalmente por
Nik Clayton, que pode ser encontrado por email em
<tt>nik@FreeBSD.org</tt>.</p>

4.1.4.4 Tamanho do Conteúdo

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

1. Use <big> e <small> em torno do texto que você deseja mudar o tamanho. Estas tags podem ser aninhadas, assim <big><big>Este é muito maior</big></big> é possível.

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

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

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

4.1.5.1 Ligando-se a Outros Documentos

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

O link é indicado com <a>, e o atributo href 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.

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

Este link irá levar o usuário ao topo do documento escolhido.

4.1.5.2 Ligando-se a Outras Partes de um Documento

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.

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

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

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

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

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

<p>Mais informação no <a href="#para1">primeiro 
parágrafo</a> deste documento.</p>

4.2.3.1 Iniciando um Livro

O conteúdo de um livro deve estar contido dentro do elemento <book>. 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.

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

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

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

    <releaseinfo>$FreeBSD$</releaseinfo>

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

  …

</book>

4.2.3.2 Começando um Artigo

O conteúdo do artigo deve estar contido dentro do elemento <article>. Assim como 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.

Estas informações adicionais devem estar contidas dentro do elemento <articleinfo>.

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

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

    <releaseinfo>$FreeBSD$</releaseinfo>

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

  …

</article>

4.2.3.3 Indicando Capítulos

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

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

  ...
</chapter>

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

<chapter>
  <title>Isto é um capítulo vazio</title>

  <para></para>
</chapter>

4.2.3.4 Sessões Abaixo dos Capítulos

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 <sectn>. O n indica o número da seção o qual identifica o nível da seção.

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

<chapter>
  <title>Um exemplo de capítulo</title>

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

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

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

        …
      </sect3>
    </sect2>

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

      …
    </sect2>
  </sect1>
</chapter>

4.2.3.5 Subdividindo Utilizando o Elemento <Part>

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

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

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

    ...
  </chapter>

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

    ...
  </chapter>

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

    ...
  </chapter>
</part>

4.2.4.1 Parágrafos

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

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

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

4.2.4.2 Bloco de Citações

Um bloco de citação é uma longa citação de outro documento que não deveria aparecer no parágrafo atual. Você não irá usá-lo com muita frequência.

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

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

Talvez você precise incluir informações extras separadas do corpo principal do texto. Tipicamente isto é “meta” informação que o usuário deve tomar conhecimento.

Dependendo da natureza da informação, devemos utilizar o elemento <tip>, <note>, <warning>, <caution>, ou <important>. Alternativamente, se a informação é relacionada ao corpo principal do texto e não se encaixa em nenhum dos objetos acima, utilize <sidebar>.

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:

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

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

• A <caution> é usada para informar sobre uma possível perda de dados ou possível dano causado pelo software.

• O <warning> é usado para informações sobre possíveis danos ao hardware, sobre risco de vida ou de ferimento a um membro.

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

Aparência:

4.2.4.4 Listas e Procedimentos

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 fazer isso, utilize <itemizedlist>, <orderedlist>, ou <procedure> [4].

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

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

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

4.2.4.5 Mostrando Amostras de Arquivos

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

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

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

<programlisting>#include <stdio.h>

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

#include <stdio.h>

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

4.2.4.6 Chamadas

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 fazer isso, marque as áreas de interesse no seu exemplo (<programlisting>, <literallayout>, ou o que for) com o elemento <co>. Cada elemento deve ter um id único atribuído a ele. Insira um <calloutlist> no final do exemplo acima fazendo referência de volta a ele, exibindo comentários adicionais.

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

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

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

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

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

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

#include <stdio.h> 

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

4.2.4.7 Tabelas

Ao contrário 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.

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

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

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

Sempre utilize o atributo pgwide com o valor 1 junto ao elemento <informaltable>. Um bug no Internet Explorer pode fazer com que a tabela renderize de forma incorreta se ele for omitido.

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

4.2.4.8 Exemplos para o Usuário Seguir

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.

Vários elementos e entidades podem ser utilizados nestes casos.

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

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

4.2.5.1 Enfatizando a Informação

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

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

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

4.2.5.2 Citações

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

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

4.2.5.3 Teclas, Mouse e Combinações

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

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

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

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

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

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

4.2.5.4 Aplicações, Comandos, Opções e Citações

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.

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

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

Você deve marcar o nome de uma aplicação com <application>.

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 <citerefentry>. Ele irá ter mais dois elementos, <refentrytitle> e <manvolnum>. O conteúdo de <refentrytitle> é o nome do comando, e o conteúdo de <manvolnum> é a seção da página do manual.

Pode ser trabalhoso escrever desta forma, para facilitar este processo foram criadas uma série de entidades gerais. Cada entidade está na forma &man.manual-page.manual-section;.

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

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

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

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

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

…

]>

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

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

Quando diversas referências a um mesmo comando estiverem próximas é melhor usar a notação &man.command.section; para marcar a primeira referência ao mesmo e depois utilizar <command> para marcar as referências subsequentes. Isto fará a saída gerada, especialmente em HTML, ficar visualmente melhor.

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

4.2.5.5 Arquivos, Diretórios, Extensões

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

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

4.2.5.6 O Nome dos Ports

Você pode precisar incluir o nome de um programa da Coleção de Ports do FreeBSD na documentação. Use a tag <filename> com o atributo role ajustado para package 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 /usr/ports.

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

4.2.5.7 Dispositivos

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

Em alguns casos você não terá escolha. Alguns dispositivos, como as placas de rede, não tem entrada no /dev, ou as entradas são muito diferentes das esperadas.

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

4.2.5.8 Hosts, Domínios, Endereços IP e etc.

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

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


<para>O domí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>

4.2.5.9 Usernames

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

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

4.2.5.10 Descrevendo Makefiles

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

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

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

<para>Tipicamente, usar <maketarget>all</maketarget> irá refazer a
aplicação, usar <maketarget>clean</maketarget> irá remover os
arquivos temporários (<filename>.o</filename> por exemplo) 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>

4.2.5.11 Texto Literal

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

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

Nestas ocasiões, use <literal>.

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

4.2.5.12 Mostrando Itens que o Usuário Deve Preencher

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.

O elemento <replaceable> 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.

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

% man comando

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

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

4.2.5.13 Citando erros do sistema

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

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

“Panic: cannot mount root”

4.2.6.1 Formatos de Imagens

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

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

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

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

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

4.2.6.2 Marcação

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

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

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

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

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

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

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

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

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

4.2.6.3 Entradas no Makefile

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

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

ou

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

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

4.2.6.4 Imagens e Capítulos em Subdiretórios

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

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

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

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

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

  …

</mediaobject>

O Makefile deve conter:

…
IMAGES=  chapter1/fig1.png
…

Desta forma tudo deve funcionar.

4.2.7.1 Ligando-se a outras partes no mesmo documento

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

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

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

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

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

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

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

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

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

<para>
Este parágrafo tem um <anchor id="para1">alvo dentro dele. 
O qual não irá aparecer no documento
</para>

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

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

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

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

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

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

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

4.2.7.2 Ligando-se a documentos na WWW

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

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

6.3.1.1 Organização Fisíca

Existem diversos arquivos e diretórios dentro do diretório handbook.

<chapter id="kernelconfig">
...
</chapter>

7.3.1.1 Variáveis

As variáveis DOCFORMAT e MAINTAINER serão atribuídas com valores padrão, se o valor das mesmas não tiver sido definido no arquivo Makefile do documento.

O PREFIX define o caminho no qual os aplicativos de construção da documentação estão instalados. Para uma instalação normal através de pacotes e/ou ports, este caminho será sempre /usr/local.

A variável PRI_LANG deve ser configurada para refletir o idioma e a codificação nativa dos usuários aos quais os documentos se destinam. O Inglês Americano (US English) é o padrão.

7.3.1.2 Condicionais

A linha .if defined(DOC) é um exemplo da condicional do make , como em outros programas, define o comportamento se alguma condição é verdadeira ou se é falsa. defined é uma função que retorna se uma dada variável está definida ou não.

A seguir, .if ${DOCFORMAT} == "docbook" , testa se a variável DOCFORMAT é "docbook", e neste caso, inclue o doc.docbook.mk.

Os dois .endifs fecham as duas condicionais anteriores, marcando o fim da sua aplicação.

7.3.2.1 Variáveis

• SUBDIR é a lista de subdiretórios nos quais o processo de construção deve ser executado.

• ROOT_SYMLINKS são os nomes dos diretórios que devem ser linkados para a raíz de instalação do documento a partir da sua localização atual, se o idioma atual for o idioma primário (especificado por PRI_LANG).

• O COMPAT_SYMLINK já foi descrito na seção Makefiles de subdiretório .

7.3.2.2 Targets e Macros

As dependências são descritas por target: dependência1 dependência2 ... , nas quais, para construir o target, você necessita primeiramente construir as dependências informadas.

Depois desta descrição, instruções de como construir o target podem ser passadas, no caso do processo de conversão entre o target e estas dependências não tiver sido previamente definido, ou se esta conversão em particular não for a mesma que a definida pelo método padrão de conversão.

A dependência especial .USE define o equivalente a uma macro.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

No código acima, _SUBDIRUSE é agora uma macro, a qual irá executar determinados comandos quando for listada como dependência.

O que define esta macro a parte de outros targets? Basicamente, ela é executada após as instruções passadas no processo de construção por ser uma dependência para o mesmo, e ela não configura o .TARGET, que é a variável que contém o nome do target atual que está sendo construído.

clean: _SUBDIRUSE
	rm -f ${CLEANFILES}

No código acima, o clean irá usar a macro _SUBDIRUSE depois de ter executado a instrução rm -f ${CLEANFILES}. De fato, isto causa uma limpeza (clean) na árvore de diretórios, deletando os arquivos construídos enquanto vai descendo pelos subdiretórios, e não quando vai na direção oposta.

7.3.2.3 Mais Condicionais

• exists é outra função condicional que retorna verdadeiro se o arquivo informado existir.

• empty retorna verdadeiro se a variável informada estiver vazia.

• target retorna verdadeiro se o target informado ainda não existir.

7.3.2.4 Construção de Looping no make (.for)

O .for fornece uma maneira de repetir instruções definidas para cada elemento separado por espaço em uma variável. Ele faz isso atribuíndo uma variável para conter o elemento atual da lista que está sendo examinada.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

No código acima, se SUBDIR estiver vazia, nenhuma ação será executada; se ela possuir um ou mais elementos, as instruções entre o .for e o .endfor serão repetidas para cada elemento, com o entry sendo substituído com o valor do elemento atual.

10.1.4.1 Espaçamento de Tags

Tags que começam na mesma identação que um Tag precedente devem ser separados por uma linha em branco, e aqueles que não estão na mesma identação que um Tag precedente não, observe:

<article>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
  ...
  ...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

10.1.4.2 Separando Tags

Tags tais como <itemizedlist> que terão sempre algum Tag adicional dentro dele, e que não fazem exame dos dados eles mesmos, estarão sempre sozinhos em uma linha.

Tags tais como <para> e <term> não necessitam outros Tags para conter caracteres normais, e o seu conteúdo começa imediatamente depois do Tag, na mesma linha.

O mesmo se aplica quando estes dois tipos de Tag se fecham.

Isto conduz a um problema óbvio ao misturar estes Tags.

Quando um Tag de abertura que não pode conter caracteres normais é utilizado logo após um Tag do tipo que requer outros Tags dentro dele para conter caracteres normais, eles devem estar em linhas separadas e o segundo Tag deve ser corretamente identado.

Quando um Tag que possa conter caracteres normais se fecha imediatamente depois que um Tag que não pode conter caracteres normais se fecha, eles podem coexistir na mesma linha.