# Primer do Projeto de Documentação do FreeBSD para novos colaboradores

### Projeto de documentação do FreeBSD

Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 DocEng

Obrigado por tornar-se parte do Projeto de Documentação do FreeBSD. A sua contribuição é extremamente valiosa.

Este Primer do Projeto de Documentação do FreeBSD cobre tudo o que você precisa saber para começar a contribuir com o Projeto de Documentação do FreeBSD, desde as ferramentas e softwares que você estará utilizando (tanto os obrigatórios quanto os recomendados) à filosofia por trás do projeto de documentação.

Este documento é um trabalho em andamento, e não está completo. As sessões que sabemos estarem incompletas estão indicadas com um `*` no seu nome.

Versão Traduzida para Português do Brasil

Esta é uma tradução não-oficial do Aviso Legal Padrão do Projeto de Documentação do FreeBSD para o Português do Brasil. Ela não foi publicada pelo Projeto de Documentação do FreeBSD, e legalmente não representa os termos de distribuição de documentação que utiliza o Aviso Legal Padrão do Projeto de Documentação do FreeBSD -- somente o texto original do Aviso Legal Padrão do Projeto de Documentação, em inglês, faz isso. Logo, a versão traduzida não deve ser utilizada como um aviso legal válido. Esperamos, contudo, que esta tradução ajude aos falantes de Português do Brasil a entender melhor o Aviso Legal Padrão do Projeto de Documentação do FreeBSD.

SEMPRE verifique a versão em Inglês mais recente do Aviso Legal Padrão do Projeto de Documentação do FreeBSD na versão em Inglês do Manual do FreeBSD.

Redistribuição e utilização do código fonte (SGML DocBook) ou formato "compilado" (SGML, HTML, PDF, PostScript, RTF e assim por diante) com ou sem modificação, são permitidas contanto que as seguintes condições sejam cumpridas:

1. As redistribuições do código fonte (SGML DocBook) devem reter o aviso de copyright acima, esta lista de condições e a seguinte nota de responsabilidade assim como as primeiras linhas deste arquivo não modificadas.

2. As redistribuições em forma compilada (transformada para outros DTDs, convertida para PDF, PostScript, RTF e outros formatos) devem reproduzir o aviso de copyright acima, esta lista de condições e a seguinte nota de responsabilidade na documentação e/ou outros materiais fornecidos com a distribuição.

> Importante: ESTA DOCUMENTAÇÃO É FORNECIDA PELO PROJETO DE DOCUMENTAÇÃO DO FREEBSD "NO ESTADO" E QUAISQUER GARANTIAS EXPLÍCITAS OU IMPLÍCITAS, INCLUINDO, MAS NÃO LIMITADAS AS GARANTIAS IMPLÍCITAS DE COMERCIALIZAÇÃO E A DE ADEQUAÇÃO PARA UMA FINALIDADE PARTICULAR SÃO DESMENTIDAS. EM NENHUM EVENTO O PROJETO DE DOCUMENTAÇÃO DO FREEBSD PODERÁ SER RESPONSABILIZADO POR QUAISQUER DANOS DIRETOS, INDIRETOS, INCIDENTAIS, ESPECIAIS, EXEMPLARES, OU CONSEQÜENTES (INCLUINDO, MAS NÃO LIMITADO A, OBTENÇÃO DE BENS OU SERVIÇOS SUBSTITUTOS; PERDA DE USO, DE DADOS, OU DE LUCROS; OU A INTERRUPÇÃO DE NEGÓCIOS) DE QUALQUER FORMA CAUSADO E EM QUALQUER TEORIA DE RESPONSABILIDADE, SE EM CONTRATO, EM RESPONSABILIDADE ESTRITA, OU PROCESSUAL (PASSÍVEL DE PROCESSO, INCLUINDO NEGLIGÊNCIA OU NÃO) LEVANTADA DE QUALQUER FORMA PELO USO DESTA DOCUMENTAÇÃO, MESMO QUE AVISADO DA POSSIBILIDADE DE TAIS DANOS.

English Version

This is an unofficial translation of the Standard FreeBSD Documentation Project Legal Notice into Brazilian Portuguese. It was not published by The FreeBSD Documentation Project, and does not legally state the distribution terms for documentation that uses the Standard FreeBSD Documentation Project Legal Notice -- only the original English text of the Standard FreeBSD Documentation Project Legal Notice does that. Therefore, the translated version should not be used as a valid legal notice. However, we hope that this translation will help Brazilian Portuguese speakers understand the Standard FreeBSD Documentation Project Legal Notice better.

Make sure to ALWAYS check the latest English version of the Standard FreeBSD Documentation Project Legal Notice in the English documentation version of the FreeBSD Handbook.

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.

> Importante: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 THE FREEBSD DOCUMENTATION PROJECT 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.

[ Split HTML / Single HTML ]

Lista de Exemplos
1. Uma amostra de exemplo
3-1. Utilizando um elemento (tags de inicio e fim)
3-2. Utilizando um elemento (Apenas tag de início)
3-3. Elementos contendo elementos; `<em>`
3-4. Utilizando um elemento com um atributo
3-5. Aspas simples envolta de atributos
3-6. `.profile`, para os usuários dos shells sh(1) e bash(1)
3-7. `.cshrc`, para os usuários dos shell csh(1) e tcsh(1)
3-8. Comentário SGML genérico
3-9. Comentários SGML errados
3-10. Definindo uma entidade geral
3-11. Definindo entidades de parâmetros
3-12. Utilizando entidades gerais para incluir arquivos
3-13. Utilizando entidades de parâmetro para incluir arquivos.
3-14. Estrutura de uma sessão marcada
3-15. Utilizando uma sessão marcada como CDATA
3-16. Utilizando `INCLUDE` e `IGNORE` nas sessões marcadas
3-17. Utilizando uma entidade de parâmetro para controlar uma sessão marcada
4-1. Estrutura Normal de um Documento HTML
4-2. `<h1>`, `<h2>`, e outras Tags de Header.
4-3. Má organização de elementos `<h`n`>`
4-4. `<p>`
4-5. `<blockquote>`
4-6. `<ul>` e `<ol>`
4-7. Listas de Definição com `<dl>`
4-8. `<pre>`
4-9. Uso Simples de `<table>`
4-10. Utiliizando `rowspan`
4-11. Usando `colspan`
4-12. Usando `rowspan` e `colspan` juntos
4-13. `<em>` e `<strong>`
4-14. `<b>` e `<i>`
4-15. `<tt>`
4-16. `<big>`, `<small>`, e `<font>`
4-17. Usando `<a href="...">`
4-18. Usando `<a name="...">`
4-19. Link para uma determinada parte de outro documento
4-20. Links para determinada parte do mesmo documento
4-21. Modelo padrão `<book>` com `<bookinfo>`
4-22. Modelo padrão `<article>` com `<articleinfo>`
4-23. Um capítulo simples
4-24. Capítulos Vazios
4-25. Seções em Capítulos
4-26. `<para>`
4-27. `<blockquote>`
4-28. `<warning>`
4-29. `<itemizedlist>`, `<orderedlist>`, e `<procedure>`
4-30. `<programlisting>`
4-31. `<co>` e `<calloutlist>`
4-32. `<informaltable>`
4-33. Tabelas com `frame="none"`
4-34. `<screen>`, `<prompt>`, e `<userinput>`
4-35. `<emphasis>`
4-36. Citações
4-37. Teclas, Mouse e Combinações
4-38. Aplicações, Comandos, Opções
4-39. `<filename>`
4-40. Tag `<filename>` com o atributo `package`
4-41. `<devicename>`
4-42. `<Hostid>` e `Roles`
4-43. `<Username>`
4-44. `<Maketarget>` e `<Makevar>`
4-45. `<Literal>`
4-46. `<replaceable>`
4-47. `<errorname>`
4-48. O atributo `id` em capítulos ou seções
4-49. `<anchor>`
4-50. Usando `<xref>`
4-51. Usando `<link>`
4-52. `<ulink>`
A-1. DocBook `<book>`
A-2. DocBook `<article>`
A-3. Convertendo de DocBook para HTML (em um único grande arquivo)
A-4. Convertendo de DocBook para HTML (vários arquivos pequenos)
A-5. Convertendo de DocBook para Postscript
A-6. Convertendo de DocBook para PDF

# Prefácio

## Prompt do interpretador de comandos (shell)

A tabela seguinte mostra o prompt padrão do sistema e o prompt do super usuário. Os exemplos irão utilizar estes prompts para indicar com qual usuário o exemplo foi executado.

Usuário | Prompt
--- | ---
Usuário normal | `%`
`root` | `#`

## Convenções Tipográficas

A tabela seguinte descreve as convenções tipográficas utilizadas neste livro.

Propósito | Exemplos
--- | ---
Nome de um comando. | Utilize `ls -a` para listar todos os arquivos.
Nome de um arquivo. | Edite o seu arquivo `.login` .

Saída (output) de um programa na tela do computador.

    Você tem email.

O que você digita, quando contrastado com a saída (output) do programa na tela do computador.

    % su
    Password:

Referência a uma página de manual. | Utilize o su(1) para assumir outro nome de usuário.
Nome de usuário e de grupos de usuários | Apenas o `root` pode fazer isso.
Ênfase | Você deve fazer isso.
Variáveis da linha de comando; Substitua com o nome real ou com a variável. | Para deletar um arquivo, digite `rm ``nome_do_arquivo```
Variáveis de ambiente | O `$HOME` é o seu diretório `home`.

## Notas, dicas, informações importantes, avisos e exemplos

Ao longo do texto aparecerão notas, avisos e exemplos.

> Nota: Notas são representadas desta forma, e contêm informações para as quais você deveria ficar atento, pois podem afetar o que você faz.

> Dica: Dicas são representadas desta forma, e contêm informações que você pode achar úteis, ou que mostram uma maneira mais fácil de fazer alguma coisa.

> Importante: Informações importantes são representadas desta forma. Normalmente elas destacam passos extras que você pode precisar realizar.

> Atenção: Avisos são representados deste modo, e contêm informações de alerta para você sobre possíveis danos se você não seguir as instruções. Estes danos podem ser físicos: para o seu equipamento ou para você; ou, podem ser não-físicos: tal como a deleção inadvertida de arquivos importantes.

Exemplo 1. Uma amostra de exemplo

Os exemplos são representados deste modo, e normalmente contêm exemplos que você deve analisar, ou então, mostram como deveriam ser os resultados de uma determinada ação.

## Agradecimentos

Meu muito obrigado a Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, e Christopher Maden, por terem gasto parte do seu tempo lendo os primeiros rascunhos deste documento e por terem oferecido muitos comentários e críticas construtivas para este trabalho.

# Capítulo 1 Visão Geral

Seja bem vindo ao Projeto de Documentação do FreeBSD. Documentação de boa qualidade é muito importante para o sucesso do FreeBSD, e o Projeto de Documentação do FreeBSD (FDP) é a origem de muitos destes documentos. Suas contribuições são muito importantes.

A finalidade principal deste documento é explicar claramente como o FDP é organizado, como escrever e como submeter documentos para o FDP , e como utilizar de forma efetiva as ferramentas que estão disponíveis para você enquanto estiver escrevendo.

Todos são bem vindos para se juntar ao FDP. Não existe nenhum requisito mínimo para a sua associação, nenhuma quota de documentos que você precise produzir por mês. Tudo o que você precisa fazer é se inscrever na lista de discussão do projeto de documentação do FreeBSD.

Depois que você tiver terminado de ler este documento, você deve:

- Saber quais documentos são mantidos pelo FDP.

- Ser capaz de ler e entender o código fonte SGML de um documento mantido pelo FDP.

- Ser capaz de efetuar alterações num documento.

- Ser capaz de enviar suas alterações de volta para revisão e eventual inclusão na documentação do FreeBSD.

## 1.1 Conjunto de Documentação do FreeBSD

O FDP é responsável por quatro categorias de documentos do FreeBSD.

Páginas de Manual

  As páginas de manual do sistema na língua inglesa não são escritas pelo FDP, porque elas são parte da base do sistema. Entretanto, o FDP pode (e tem) reescrever partes das páginas de manual existentes para torná-las mais claras, ou para corrigir imprecisões.

  Os times de tradução são responsáveis por traduzir as páginas de manual do sistema para diferentes idiomas. Estas traduções são mantidas pelo FDP.

FAQ

  O objetivo do FAQ é consolidar (no formato de perguntas e respostas curtas) as perguntas que foram feitas, ou que podem ser feitas, nas várias listas de discussão e newsgroups dedicados ao FreeBSD. O formato não permite respostas longas e detalhadas.

Handbook

  O Handbook almeja ser um compreensivo recurso de referência online para os usuários do FreeBSD.

Web Site

  Esta é a principal presença do FreeBSD na `World Wide Web`, visível em http://www.FreeBSD.org/ e em muitos sites espelhos ao redor do mundo. O web site é o primeiro contato de muitas pessoas com o FreeBSD.

A documentação do web site, do Handbook do FreeBSD e do FAQ estão disponíveis no repositório Subversion `doc/`, que está localizado em `svn://svn.FreeBSD.org/doc/`.

As páginas de manual estão disponíveis no repositório Subversion `src/`, que está disponível em `svn://svn.FreeBSD.org/base/`.

Isto significa que os logs das alterações realizadas nestes arquivos é visível para qualquer um, e qualquer pessoa pode utilizar o svn para ver as alterações.

Em adição, muitas pessoas escreveram tutoriais ou outros web sites relacionados ao FreeBSD. Alguns destes trabalhos também estão armazenados no repositório Subversion (com a permissão do autor). Em outros casos o autor decidiu manter o seu documento separado do repositório principal do FreeBSD. O FDP se esforça tanto quanto possível para fornecer os links para estes documentos.

## 1.2 Antes de você iniciar

Este documento assume que você já sabe:

- Como manter uma cópia local atualizada da documentação do FreeBSD, através da manutenção de uma cópia local do repositório Subversion do FreeBSD utilizando o svn.

- Como obter e instalar um novo software utilizando o sistema de ports ou o pkg_add(1) do FreeBSD.

## 1.3 Início Rápido

Se você deseja ir começando, e se sente seguro de que pode ir pegando as coisas à medida que avança, siga estas instruções.

1. Instale o meta-port `textproc/docproj`.

       # cd /usr/ports/textproc/docproj
       # make JADETEX=no install

2. Obtenha uma cópia local da árvore de documentação do FreeBSD (`doc`) utilizando o svn.

   Se a velocidade da sua conexão ou se o espaço de armazenamento do seu disco local forem motivo de preocupação, o mínimo que você vai precisar será uma cópia de trabalho dos diretórios `head/share`, e `head/`idioma`/share` . Por exemplo:

       % mkdir -p head/share
       % mkdir -p head/en_US.ISO8859-1/share
       % svn checkout svn://svn.FreeBSD.org/doc/head/share head/share
       % svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share

   Se você tiver abundância de espaço em disco, você pode retirar uma cópia de trabalho completa (de todos os subdiretórios da árvore doc).

       % svn checkout svn://svn.FreeBSD.org/doc/head head

3. Se você está preparando uma alteração de um artigo ou livro existente, retire uma versão de trabalho do arquivo do repositório. Se você está planejando contribuir com um novo livro ou artigo, então utilize um dos existentes como guia.

   Por exemplo, se você deseja contribuir com um novo artigo sobre como configurar uma VPN entre o FreeBSD e o Windows 2000, você pode fazer o seguinte:

   1. Retire uma cópia de trabalho do diretório `articles`.

          % svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles

   2. Copie um artigo existente para utilizar como template. Neste caso, você decidiu que o seu novo artigo iria para um diretório chamado `vpn-w2k`.

          % cd head/en_US.ISO8859-1/articles
          % svn export committers-guide vpn-w2k

   Se você deseja editar um documento existente, como por exemplo o FAQ, o qual está em `head/en_US.ISO8859-1/books/faq`, você deve retirar a cópia de trabalho do repositório da seguinte forma:

       % svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq

4. Edite os arquivos `.xml` utilizando o editor da sua preferência.

5. Teste a marcação SGML utilizando o alvo `lint` com o comando make. Isto irá listar rapidamente qualquer erro existente no documento sem realizar qualquer tipo de transformação no seu arquivo, o que consumiria tempo.

       % make lint

   Quando você estiver pronto para efetivamente compilar o documento, você pode especificar um único formato ou uma lista de formatos de destino, na variável `FORMATS`. Atualmente os formatos suportados são, `html`, `html-split`, `txt`, `ps`, `pdf`, e `rtf`. A lista mais atualizada dos formatos suportados está listada no início do arquivo `head/share/mk/doc.docbook.mk`. Certifique-se de utilizar aspas (`"`) em volta da lista de formatos quando você estiver compilando mais de um formato num único comando.

   Por exemplo, para converter o documento apenas para `html`, você deve utilizar:

       % make FORMATS=html

   Mas quando você deseja converter o documento tanto para o formato `html` quanto para o formato `txt`, você pode utilizar duas execuções separadas do make(1), como a seguir:

       % make FORMATS=html
       % make FORMATS=txt

   ou, você pode fazer isso em um único comando:

       % make FORMATS="html txt"

6. Envie suas alterações utilizando o send-pr(1).

# Capítulo 2 Ferramentas

O FDP utiliza diferentes ferramentas como auxílio no gerenciamento da documentação do FreeBSD, e na conversão para diferentes formatos, e assim por diante. Você irá precisar utilizar estas ferramentas se for trabalhar com a documentação do FreeBSD.

Todas estas ferramentas estão disponíveis como `Ports` e `Packages` do FreeBSD, simplificando enormemente o seu trabalho para instalá-las.

Você precisará instalar estas ferramentas antes de trabalhar com qualquer exemplo dos próximos capítulos. O uso real destas ferramentas será abordado nos próximos capítulos.

> Se possível use o `textproc/docproj`: Você pode economizar bastante tempo se instalar o `port` `textproc/docproj`. Este é um meta-port que por si só não contém nenhum programa. Ao invés disto, ele depende que já estejam instalados corretamente vários outros `ports`. O processo de instalação irá baixar e instalar automaticamente todos os pacotes listados como necessários neste capítulo.

> Um dos pacotes que você pode precisar é o conjunto de macros JadeTeX. No entanto, esse conjunto de macros requer que o TeX esteja instalado. O TeX é um pacote grande, e ele somente será necessário se você quiser gerar documentos nos formatos Postscript ou PDF.

> Para economizar seu tempo e espaço em disco você deve especificar se quer, ou não, a instalação do JadeTeX (e por consequência do TeX) quando o `port` for instalado. Conforme necessário, faça:

>     # make JADETEX=yes install

> ou

>     # make JADETEX=no install

> Alternativamente você pode instalar o `textproc/docproj-jadetex` ou o `textproc/docproj-nojadetex`. Estes `ports` secundários irão definir a variável `JADETEX` para você, consequentemente eles irão instalar o mesmo conjunto de aplicativos na sua máquina. Observe que você poderá produzir apenas documentos em HTML e ASCII se você não instalar o JadeTeX. Para produzir documentos em PostScript e PDF você irá precisar do TeX.

## 2.1 Ferramentas Obrigatórias

### 2.1.1 Software

Estes programas são necessários para você trabalhar com a documentação do FreeBSD, e permitirão a conversão da mesma para os formatos HTML, texto puro e RTF. Eles estão todos incluídos em `textproc/docproj`.

Jade (`textproc/jade`)

  Uma implementação DSSSL. Utilizado para a conversão de documentos escritos com linguagem de marcas para outros formatos, incluindo HTML e TeX.

Tidy (`www/tidy`)

  Um HTML “pretty printer” , utilizado para reformatar alguns dos HTMLs gerados automaticamente ficando mais fácil de entendê-los.

Links (`www/links`)

  Um navegador WWW em modo texto que também converte arquivos HTML para texto puro.

peps (`graphics/peps`)

  Parte da documentação inclui imagens, algumas delas estão armazenadas como arquivos EPS. Estas imagens precisam ser convertidas para o formato PNG antes de serem exibidas em um navegador `web`.

### 2.1.2 Entidades e DTDs

Estes são os conjuntos de DTDs e de entidades usados pelo FDP. Eles precisam estar instalados para que você possa trabalhar com qualquer parte da documentação.

HTML DTD (`textproc/html`)

  HTML é a linguagem de marcas escolhida para a `World Wide Web`, e é usada no `web site` do FreeBSD.

DocBook DTD (`textproc/docbook`)

  DocBook é uma linguagem de marcas projetada para documentação técnica. Toda a documentação do FreeBSD está escrita em DocBook.

ISO 8879 entities (`textproc/iso8879`)

  19 dos conjuntos de entidade de caracter ISO 8879:1986 utilizados por muitos DTDs. Inclui símbolos matemáticos nomeados, caracteres do conjunto de caracter Latin (acentos, diacríticos e assim por diante), e símbolos gregos.

### 2.1.3 Stylesheets

As `Stylesheets` são usadas na conversão e formatação de documentos para serem apresentados na tela, impressos, e assim por diante.

Modular DocBook Stylesheets (`textproc/dsssl-docbook-modular` )

  As `Modular DocBook Stylesheets` são usadas na conversão da documentação escrita em DocBook para outros formatos, tais como HTML ou RTF.

## 2.2 Ferramentas Opcionais

Você não precisa ter qualquer uma das ferramentas a seguir instaladas. Entretanto, você poderá achar mais fácil trabalhar com a documentação se elas estiverem disponíveis, elas também oferecem uma maior flexibilidade em relação aos formatos nos quais os documentos podem ser gerados.

### 2.2.1 Software

JadeTeX e teTeX (`print/jadetex` e `print/teTeX`)

  O Jade e o teTeX são usados para converter DocBook para os formatos DVI, Postscript, e PDF. As macros do JadeTeX são necessárias para estas conversões.

  Se você não pretende converter seus documentos para um destes formatos (i.e., HTML, texto puro, e RTF são o suficiente) então não será preciso instalar o JadeTeX e teTeX. Isto pode resultar em uma boa economia de tempo e espaço em disco, já que o teTeX possui tamanho de aproximadamente 30MB.

  > Importante: Se você decidir instalar o JadeTeX e teTeX então será preciso configurar o teTeX depois do JadeTeX ter sido instalado. O arquivo `print/jadetex/pkg-message` contém instruções detalhadas sobre o que é preciso ser feito.

Emacs ou XEmacs (`editors/emacs` ou `editors/xemacs`)

  Ambos editores incluem um modo especial para a edição de documentos com uma linguagem de marcas que siga um SGML DTD. Esse modo inclui comandos para reduzir o volume total de digitação a ser feita, o que ajuda a reduzir a possibilidade de erros.

  Você não precisa utilizá-los, qualquer editor pode ser usado para editar documentos escritos com linguagem de marcas. Entretanto, se optar por usá-los você poderá constatar que eles tornam seu trabalho mais eficiente.

Se alguém tiver sugestões sobre algum outro `software` que seja útil para a manipulação de documentos SGML, por favor informe a Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`, desta forma ele poderá ser adicionado a esta lista.

# Capítulo 3 SGML Primer

A maioria dos documentos do FDP é escrita utilizando SGML. Este capítulo irá explicar exatamente o que isso significa, como ler e compreender os fontes dos documentos e os truques de SGML que você irá se defrontar na documentação.

Partes desta seção foram inspiradas no documento Começando a utilizar o DocBook de autoria do Mark Galassi.

## 3.1 Visão Geral

Antigamente, era simples de se lidar com um texto eletrônico. Naquela época, você tinha que saber em qual conjunto de caracteres o seu documento havia sido escrito (ASCII, EBCDIC ou um dos inúmeros outros), e mais nada. O texto era texto, e o que você via era realmente o que você tinha. Nenhuma frescura, nenhuma formatação, nenhuma inteligência.

Inevitavelmente, isto não era o suficiente. Uma vez que você tem o texto em uma máquina num formato utilizável, você espera que o equipamento seja capaz de usá-lo e manipulá-lo de forma inteligente. Você pode desejar indicar que uma determinada frase deve ser enfatizada, ou adicionada a um glossário, ou ser interligada a outra parte do documento. Você pode querer que os nomes dos arquivos sejam exibidos com uma fonte de estilo “typewriter” quando forem exibidos na tela, mas como “itálico ” quando impresso, ou qualquer outra opção dentre a infinidade de opções disponíveis para apresentação.

Esperava-se que a inteligência artificial (AI) torna-se isso fácil. O seu computador leria o documento e identificaria automaticamente as frases chave, nomes de arquivos, os campos que o leitor teria que preencher, e muito mais. Infelizmente, a vida real não evoluiu como esperado, e os nossos computadores necessitam de algum auxílio antes que eles possam processar significativamente nosso texto.

Mais precisamente, eles precisam de ajuda para identificar o que é o que. Vejamos o texto abaixo:

> Para remover o `/tmp/foo` utilize rm(1).

>     % rm /tmp/foo

Nele podemos facilmente visualizar quais partes são nomes de arquivos, quais são comandos que devem ser digitados, quais partes são referências às páginas de manual, etc. Mas o computador processando o documento não pode. Para isto nós precisamos utilizar uma marcação (`markup`).

A “marcação” é comumente utilizada para descrever a “adição de valor” ou o “aumento de custo”. O termo (term) faz exame de ambos os meios quando aplicados ao texto. A marcação é um texto adicional incluído no documento, e de alguma forma destacado do seu conteúdo, de modo que os programas que forem processá-lo possam ler as marcações e utilizá-las ao tomar decisões sobre o documento. Os editores podem ocultar a marcação do usuário, de forma que o usuário não se distraia com ele.

As informações extras armazenadas na marcação adicionam valor ao documento. Tipicamente a adição da marcação ao documento precisa ser realizada por uma pessoa — apesar de tudo, se os computadores pudessem reconhecer suficientemente bem o texto para adicionar as marcações, então não haveria necessidade de adicioná-las em primeiro lugar. Isto aumenta o custo (isto é, o esforço requerido) para criar o documento.

O exemplo acima foi na verdade escrito neste documento como se segue:

    <para>Para remover <filename>/tmp/foo</filename> utilize &man.rm.1;.</para>

    <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>

Como você pode ver, a marcação está claramente separada do conteúdo.

Obviamente, se você estiver iniciando no uso de marcações, você precisa definir o que a sua marcação significa, e como ela será interpretada. Você vai precisar de uma linguagem de marcação a qual você possa seguir quando estiver marcando os seus documentos.

Naturalmente, uma linguagem de marcação pode não ser o bastante. Os requisitos de uma linguagem de marcação destinada formatação de documentos técnicos são diferentes dos requisitos de uma linguagem de marcação destinada a formatação de receitas culinárias. Esta, por sua vez, seria muito diferente de uma linguagem de marcação usada para formatar poemas. O que você realmente precisa é de uma linguagem primária, a qual você possa utilizar para escrever estas e outras linguagens de marcação. Uma meta linguagem de marcação.

É exatamente isso que a Standard Generalized Markup Language (SGML) é. Muitas linguagens de marcação foram escritas em SGML, incluindo as duas mais utilizadas pelo FDP, o HTML e o DocBook.

Cada definição de linguagem é mais corretamente chamada de Definição de Tipo de Documento (DTD). O DTD especifica o nome dos elementos que podem ser utilizados, em qual ordem eles aparecem (e se alguma marcação pode ser utilizada dentro de outra marcação) e as informações relacionadas. Um DTD é algumas vezes referenciado como uma aplicação do SGML.

Um DTD é uma especificação completa de todos os elementos que podem ser utilizados, da ordem em que podem aparecer, quais elementos são obrigatórios, quais são opcionais, e assim por diante. Isto torna possível escrever um interpretador (parser) SGML, que leia ambos os DTD e um documento que reividique se adequar ao DTD. O interpretador pode então confirmar se todos os elementos obrigatórios do DTD estão (ou não) presentes no documento na ordem correta, e se existem erros na marcação. Isto é normalmente referenciado como “validação do documento”.

> Nota: Este processamento simplesmente confirma se a escolha dos elementos, a sua ordenação, etc, estão de acordo com o especificado no DTD. Ele não verifica se você utilizou a marcação adequada para o conteúdo. Se você tentasse marcar todos os nomes de arquivo em seu documento como nomes de funções, o interpretador não iria apontar isto como um erro (assumindo, naturalmente, que a sua DTD define elementos para nomes de arquivos e para funções, e que eles podem ser utilizados nos mesmos lugares).

É provável que a maioria das suas contribuições ao projeto de documentação irão se constituir de conteúdos marcados tanto em HTML quanto em DocBook, em vez de alterações nos DTDs. Por esta razão este livro não irá abordar a criação de um DTD.

## 3.2 Elementos, tags, e atributos

Todos os DTDs escritos em SGML compartilham certas características. Isto é uma dura surpresa, como a filosofia por de trás do SGML nos mostrará ser completamente inevitável. Uma das manifestações mais óbvias desta filosofia está no conteúdo e nos elementos.

A sua documentação (independente se é uma única página web ou um livro longo) é composta de conteúdo. Este conteúdo é então dividido (e de novo subdividido) em elementos. O propósito da adição de marcações é atribuir nome e identidade para os limites destes elementos de forma a possibilitar o processamento adicional.

Por exemplo, considere um livro típico. No nível mais alto, o livro por si só é um elemento. Este elemento “livro” (book) obviamente contém capítulos, os quais também podem ser considerados elementos em sua própria forma. Cada capítulo irá conter mais elementos, tais como parágrafos, citações, notas de rodapé, etc. Cada parágrafo pode conter elementos adicionais, identificando o conteúdo que era de discurso direto, ou o nome de um personagem da história.

Você pode preferir pensar nisto como uma “quebra” do conteúdo. No nível mais alto você tem um pedaço, o Livro. Olhando um pouco mais abaixo, você tem mais pedaços, os capítulos individuais. Estes estão divididos em pedaços ainda menores, os parágrafos, notas de rodapé, nomes de personagens, etc.

Observe que você pode fazer esta diferenciação entre os diferentes elementos do conteúdo sem recorrer a nenhum termo SGML. Na realidade é surpreendentemente fácil de usar. Você pode fazer isso utilizando uma caneta de marcação e uma cópia impressa do livro, utilizando diferentes cores para indicar os diferentes pedaços do conteúdo.

Naturalmente, nós não possuímos uma caneta eletrônica de marcação, assim nós necessitamos de alguma outra maneira de indicar a que elemento cada peça de conteúdo pertence. Nas linguagens escritas em SGML (HTML, DocBook, etc) isto é feito através do uso de tags.

Uma tag é utilizada para identificar onde um elemento particular começa e onde ele termina. A tag não é uma parte própria do elemento . Porque cada DTD foi normalmente escrito para marcar um tipo específico de informação, cada um deles reconhecerá diferentes elementos, e terá nomes diferentes para cada tag.

Para um elemento chamado `element-name` a tag de início normalmente irá se parecer com `<`element-name`>`. E a tag correspondente de fechamento para este elemento seria `</`element-name`>`.

Exemplo 3-1. Utilizando um elemento (tags de inicio e fim)

O HTML possui um elemento para indicar que o conteúdo envolvido por este elemento é um parágrafo, chamado `<p>`. Este elemento possui ambas as tags de início e de fim.

    <p>Este é um parágrafo.  Ele inicia com a tag de inicio do
      elemento 'p', e irá terminar com a tag de fim para o
      elemento 'p'.</p>

    <p>Este é um outro parágrafo.  Mas este é muito menor.</p>

Nem todos os elementos requerem uma tag de finalização. Alguns elementos não possuem conteúdo. Por exemplo, em HTML você pode indicar que deseja que uma linha horizontal apareça no documento. Obviamente, esta linha não possui conteúdo, assim apenas a tag de inicio é requerida para este elemento.

Exemplo 3-2. Utilizando um elemento (Apenas tag de início)

O HTML possui um elemento para indicar uma linha horizontal, chamado `<hr>`. Este elemento não contém nenhum conteúdo, assim ele possui apenas uma tag de inicio.

    <p>Este é um parágrafo.</p>

    <hr>

    <p>Este é outro parágrafo.  Uma linha horizontal o separa do
      parágrafo anterior.</p>

Se isto não é óbvio agora, os elementos podem conter outros elementos. No exemplo anterior do livro, o elemento livro continha todos os elementos capítulos, os quais por sua vez continham todos os elementos parágrafos, etc.

Exemplo 3-3. Elementos contendo elementos; `<em>`

    <p>Este é um <em>parágrafo</em> simples no qual
      algumas das <em>palavras</em> foram <em>enfatizadas</em>.</p>

O DTD irá especificar as regras detalhando quais elementos podem conter outros elementos, e o que exatamente eles podem conter.

> Importante: As pessoas sempre confundem os termos tags e elementos, e utilizam os termos como se eles fossem intercambiáveis. Eles não são.

> Um elemento é uma parte conceitual do seu documento. Um elemento possui um inicio e fim determinados. As tags marcam onde os elementos começam e terminam.

> Quando este documento (ou qualquer pessoa que conheça SGML) se refere a “tag `<p>`” estamos nos referindo literalmente ao texto de três caracteres `<`, `p` e `>`. Mas a frase “o elemento `<p>`” se refere ao elemento inteiro.

> Esta distinção é muito sutil. Mas mantenha ela em mente

Os elementos podem ter atributos. Um atributo possui um nome e um valor, e é utilizado para adicionar informações extras ao elemento. Esta pode ser a informação a qual indica como o conteúdo deve ser renderizado, ou pode ser algo que identifique a ocorrência única do elemento, ou pode ser qualquer outra coisa.

O atributo de um elemento é sempre escrito dentro da tag de início para aquele elemento, e assume a forma ``nome-do-atributo`="`valor-do-atributo`"`.

Nas versões suficientemente recentes do HTML, o elemento `<p>` possui um atributo chamado `<align>`, o qual sugere o alinhamento (Justificação) de um parágrafo para o programa que estiver exibindo o HTML.

O atributo `align` pode assumir um de quatro valores possíveis, `left` (esquerda), `center` (centralizado), `right` (direita) e `justify` (justificado). Se o atributo não for especificado será assumido o valor padrão `left`.

Exemplo 3-4. Utilizando um elemento com um atributo

    <p align="left">A inclusão de um atributo de alinhamento neste
      parágrafo foi supérfluo, uma vez que o alinhamento
      padrão é left (esquerda).</p>

    <p align="center">Isto pode aparecer no centro.</p>

Alguns atributos irão assumir apenas valores específicos, como o `left` ou `justify`. Outros irão permitir que você entre com qualquer coisa que deseje. Se você precisar incluir aspas (`"`) no valor de um atributo, você deve envolver o valor do atributo com aspas simples (`'`).

Exemplo 3-5. Aspas simples envolta de atributos

    <p align='right'>Eu estou a direita!</p>

Algumas vezes você não precisa utilizar aspas em volta de todos os valores dos atributos. Entretanto, a regra para fazer isso é muito sutil, e é muito mais simples sempre utilizar as aspas em volta dos valores dos seus atributos.

A informação nos atributos, elementos e tags são armazenados nos catálogos SGML. Várias ferramentas do projeto de documentação utilizam estes arquivos de catalogo para validarem o seu trabalho. As ferramentas no `textproc/docproj` incluem uma variedade de arquivos de catalogo SGML. O projeto de documentação do FreeBSD inclui seu próprio conjunto de arquivos de catálogos. Suas ferramentas precisam reconhecer ambos os tipos de arquivos de catalogo.

### 3.2.1 Para você fazer…

Para poder praticar com os exemplos deste documento você precisará instalar alguns aplicativos no seu sistema, além de assegurar que as variáveis de ambiente estejam corretamente configuradas.

1. Faça o download e instale o `textproc/docproj` a partir do sistema de ports do FreeBSD. Ele é um meta-port o qual deve efetuar o download e a instalação de todos os aplicativos e arquivos de suporte que são utilizados pelo projeto de documentação.

2. Adicione linhas ao seu arquivo de inicialização do shell para configurar a variável de ambiente `SGML_CATALOG_FILES`. (Se você não estiver trabalhando com a versão no idioma inglês da documentação, você pode precisar substituir o caminho com o diretório correto para o seu idioma.)

   Exemplo 3-6. `.profile`, para os usuários dos shells sh(1) e bash(1)

       SGML_ROOT=/usr/local/share/xml
       SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
       SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
       export SGML_CATALOG_FILES

   Exemplo 3-7. `.cshrc`, para os usuários dos shell csh(1) e tcsh(1)

       setenv SGML_ROOT /usr/local/share/xml
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES

   Para carregar estas variáveis, execute um logout do sistema, logando novamente em seguida, ou execute os comandos acima na sua linha de comando para configurar os valores das variáveis.

1. Crie o arquivo `example.xml`, e entre com o seguinte texto:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <body>
           <p>Este é um parágrafo contendo algum texto.</p>

           <p>Este parágrafo contém mais algum texto.</p>

           <p align="right">Este parágrafo pode estar alinhado a direita.</p>
         </body>
       </html>

2. Tente validar este arquivo utilizando um interpretador SGML.

   Um dos componentes do `textproc/docproj` é o `onsgmls`, um interpretador de validação. Normalmente, o `onsgmls` lê um documento marcado de acordo com um DTD SGML e retorna uma cópia do conjunto de informações sobre a estrutura dos elementos (ESIS, mas isso não é importante agora).

   Entretanto, quando o `onsgmls` é executado com o parâmetro `-s`, ele irá suprimir o output normal, e imprimir apenas as mensagens de erro. Isto o torna um meio útil de verificar se o seu documento é válido ou não.

   Utilize o `onsgmls` para verificar se o seu documento é válido:

       % onsgmls -s example.xml

   Como você irá ver, o `onsgmls` irá executar sem retornar nenhuma mensagem. Isto significa que o seu documento foi validado com sucesso.

3. Veja o que acontece quando um elemento obrigatório é omitido. Tente remover as tags `<title>` e `</title>` , e execute novamente a validação.

       % onsgmls -s example.xml
       onsgmls:example.xml:5:4:E: character data is not allowed here
       onsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished

   As mensagens de erro emitidas pelo `onsgmls` são organizadas em grupos separados por dois pontos, ou colunas.

   Coluna | Propósito
   --- | ---
   1 | O nome do programa que está gerando o erro. Ela será sempre `onsgmls`.
   2 | O nome do arquivo que contém o erro.
   3 | Número da linha na qual o erro aparece.
   4 | Número da coluna na qual o erro aparece.
   5 | Um código de uma letra indicando a natureza da mensagem. `I` indica uma mensagem informativa, `W` é para um aviso, e `E` é para um erro [a], e `X` é para uma referência cruzada. Como você pode ver, estas mensagens são erros.
   6 | O texto da mensagem.
   Notas: a. Ele não está sempre na quinta coluna. O `onsgmls -sv` exibe `onsgmls:I: "OpenSP" version "1.5.2"` (depende da versão instalada). Como você pode ver, esta é uma mensagem informativa.

   A simples omissão das tags `<title>` gerou 2 erros diferentes.

   O primeiro erro indica que o conteúdo (neste caso, caracteres, ou melhor, a tag de inicio de um elemento) ocorreu onde o interpretador SGML estava esperando outra coisa. Neste caso, o interpretador estava esperando encontrar uma das tags de início para os elementos que são válidos dentro do `<head>` (como a `<title>` ).

   O segundo erro é porque o elemento `<head>` deve conter o elemento `<title>`. Por causa disso o `onsgmls` considera que o elemento não foi corretamente finalizado. Entretanto, a tag de finalização indica que o elemento foi fechado antes que estivesse terminado.

4. Coloque de volta o elemento `<title>`.

## 3.3 A declaração DOCTYPE

O inicio de cada documento que você escrever deve especificar o nome do DTD o qual se aplica ao seu documento. Isto deve ser feito para que os interpretadores SGML possam determinar o DTD e assegurar que o documento esta em conformidade com o mesmo.

Esta informação é geralmente expressada em uma linha, na declaração DOCTYPE.

Uma declaração típica para um documento escrito para conformar-se com a versão 4.0 do DTD HTML se parece com esta:

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

Esta linha contém diferentes componentes.

`<!`

  É o indicador que indica que se trata de uma declaração SGML. Esta linha está declarando o tipo do documento.

`DOCTYPE`

  Mostra que esta é uma declaração SGML para o tipo de documento.

`html`

  O nome do primeiro elemento o qual irá aparecer no documento

`PUBLIC "-//W3C//DTD HTML 4.0//EN"`

  Lista o Identificador Público Formal (FPI) para o DTD ao qual este documento conforma-se. O seu interpretador SGML irá utiliza-lo para encontrar o DTD correto quando estiver processando o documento.

  O `PUBLIC` não faz parte do FPI, ele indica para o processador SGML como localizar o DTD referenciado na FPI. Outras formas de informar ao interpretador SGML como localizar o DTD serão abordadas mais tarde .

`>`

  Retorno ao documento.

### 3.3.1 Identificadores públicos formais (FPIs)

> Nota: Você não precisa conhecê-los, mas eles são um background útil, e podem ajudá-lo a depurar problemas quando o seu processador SGML não puder localizar o DTD que você esta utilizando.

Os FPIs devem seguir uma sintaxe específica. Esta sintaxe é a seguinte:

    "Proprietário//Palavra-Chave Descrição//Idioma"

`Proprietário`

  Isto indica o proprietário da FPI.

  Se este conjunto de caracteres começar com “ISO” significará que o FPI é de propriedade do ISO. Por exemplo, a FPI `"ISO 8879:1986//ENTITIES Greek Symbols//EN"` lista o `ISO 8879:1986` como sendo o proprietário do conjunto de entidades dos símbolos Gregos. O ISO 8879:1986 é o numero da ISO para o padrão SGML.

  De outra forma, este conjunto de caracteres irá se parecer com `-//`Proprietário`` ou `+//`Proprietário`` (Observe que a única diferença é a introdução do `+` ou do `-`).

  Se o conjunto de caracteres começar com `-` significa que o proprietário da informação não é registrado, se começar com um `+` significa que ele é registrado.

  O ISO 9070:1991 define como os nomes registrados são gerados; ele pode ser derivado do numero de uma publicação ISO, de um código ISBN, ou um código de organização atribuído de acordo com o ISO 6523. Além disso, uma autoridade de registro pode ser criada a fim de atribuir nomes registrados. O conselho ISO delegou isto ao `American National Standards Institute` (ANSI).

  Como o Projeto FreeBSD não foi registrado o conjunto de caracteres de proprietário é `-//FreeBSD`. E como você pode ver, o W3C também não é um proprietário registrado.

`Palavra-Chave`

  Existem diversas palavras-chave as quais indicam o tipo de informação no arquivo. Algumas das palavras chaves mais comuns são `DTD`, `ELEMENT`, `ENTITIES`, e `TEXT`. A palavra chave `DTD` é utilizada apenas para os arquivos DTD, a `ELEMENT` é normalmente utilizada para fragmentos DTD os quais contenham apenas entidades e declarações de elementos. A palavra `TEXT` é utilizada para o conteúdo SGML (texto e tags).

`Descricão`

  Qualquer descrição que você deseje fornecer para o conteúdo deste arquivo. O que pode incluir um número de versão ou qualquer texto curto o qual seja significativo para você e único para o sistema SGML.

`Idioma`

  Este é um código ISO de duas letras o qual identifica o idioma nativo do arquivo. O código `EN` é utilizado para o idioma inglês.

#### 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.3.2 Alternativas aos FPIs

Ao invés de utilizar um FPI para indicar o DTD ao qual o documento conforma-se (e consequentemente, quais arquivos no sistema contém o DTD), você pode especificar explicitamente o nome do arquivo.

A sintaxe para isto é ligeiramente diferente:

    <!DOCTYPE html SYSTEM "/path/to/file.dtd">

A palavra chave `SYSTEM` indica que o processador SGML deve encontrar o DTD em um local específico do sistema. Isto tipicamente (mas não sempre) significa que o DTD será fornecido como um nome de arquivo.

O uso de FPIs é preferido por razões de portabilidade. Você pode não desejar ter que enviar uma cópia do DTD junto com seu documento, e se você utilizasse um identificador `SYSTEM` todos necessitariam manter os seus DTDs no mesmo lugar que você.

## 3.4 Voltando para o SGML

Como mencionado anteriormente, o SGML é utilizado somente quando escrevemos um DTD. Isto não é estritamente verdade. Existem certas sintaxes SGML as quais você poderá desejar utilizar com os seus documentos. Por exemplo, você pode incluir comentários no seu documento, e eles serão ignorados pelo interpretador. Os comentários são adicionados utilizando sintaxe SGML. Outros usos para a sintaxe SGML no seu documento serão mostrados mais tarde.

Obviamente, você precisa indicar de alguma forma ao processador SGML que o conteúdo seguinte não se trata de elementos do documento, mas sim de SGML sobre o qual o interpretador deve atuar.

Estas sessões são marcadas no seu documento com `<! ... >`. Tudo entre estes delimitadores é sintaxe SGML tal como você pode encontrar dentro de um DTD.

Como você pode perceber, a declaração DOCTYPE é um exemplo de sintaxe SGML a qual você precisa incluir no seu documento.

## 3.5 Comentários

Comentários são uma construção SGML, e são normalmente válidos apenas dentro de um DTD. Entretanto, como mostrou a Seção 3.4, é possível utilizar sintaxe SGML com os seus documentos.

O delimitador para um comentário SGML é o conjunto de caracteres “`--`”. A primeira ocorrência deste conjunto de caracteres abre um comentário e a segunda fecha.

Exemplo 3-8. Comentário SGML genérico

    <!-- Teste de comentário -->

    <!-- Este é o interior do comentário -->

    <!-- Este é outro comentário    -->

    <!-- Esta é uma forma
         de fazer comentários de várias linhas -->

    <!-- Esta é outra forma  --
      -- de fazer comentários de várias linhas -->

Se você já utilizou HTML antes, você pode ter sido exposto a regras diferentes para comentários. Em particular, você pode pensar que o conjunto de caracteres `<!--` abre um comentário e que ele apenas é fechado por um `-->`.

Este não é o caso. Muitos dos navegadores web possuem interpretadores HTML quebrados, e irão aceitar isso como válido. Entretanto, os interpretadores SGML utilizados pelo projeto de documentação são muito mais rígidos, e irão rejeitar os documentos que contiverem este erro.

Exemplo 3-9. Comentários SGML errados

    <!-- Este é o comentário --

         Isto está fora do comentário!

      -- de volta para dentro do comentário -->

O interpretador SGML irá tratar isto como ele é realmente;

    <!Isto está fora do comentário>

Isto não é um SGML válido, e pode dar mensagens de erro confusas.

    <!--------------- Isto é uma idéia muito ruim --------------->

E como o exemplo sugere, não escreva comentários como esse.

    <!--===================================================-->

Esta é uma abordagem (ligeiramente) melhor, mas ele ainda é potencialmente confuso para as pessoas novas no uso do SGML.

### 3.5.1 Para você fazer…

1. Adicione alguns comentários ao arquivo `example.xml` e verifique se ele continua válido usando o `onsgmls`.

2. Adicione alguns comentários inválidos ao `example.xml` e veja as mensagens de erro que o `onsgmls` emite quando encontra um comentário inválido.

## 3.6 Entidades

Entidades são um mecanismo para atribuir nomes para pedaços de conteúdo. Quando o interpretador SGML processar o seu documento, qualquer entidade que ele encontrar será substituída pelo conteúdo da entidade.

Esta é uma boa forma de ter pedaços de conteúdo reutilizáveis e facilmente alteráveis em seus documentos SGML. Esta é também a única forma de incluir um arquivo marcado dentro de outro utilizando SGML.

Existem dois tipos de entidades que podem ser utilizadas em duas situações diferentes; Entidades gerais e Entidades de parâmetros.

### 3.6.1 Entidades gerais

Você não pode utilizar uma entidade geral em um contexto SGML (embora você as defina em um). Elas podem ser utilizadas apenas no seu documento. Compare isto com as entidades de parâmetros.

Cada entidade geral possui um nome. Quando você quer referenciar uma entidade geral (e consequentemente incluir o texto que ela representa no seu documento), você escreve `&`nome-da-entidade`;`. Por exemplo, suponha que você possui uma entidade chamada `current.version`, a qual expande para a versão atual do seu produto. Você pode escrever:

    <para>A versão atual do nosso produto é &current.version;.</para>

Quando o número de versão mudar, você pode simplesmente alterar a definição do valor da entidade geral e reprocessar o seu documento.

Você também pode utilizar entidades gerais para incorporar caracteres que você não poderia incorporar de outra forma em um documento SGML. Por exemplo, os caracteres `<` e `&` não podem aparecer normalmente em um documento SGML. Quando o interpretador SGML vê o símbolo `<` ele assume que aquilo é uma tag (uma tag de abertura ou de fechamento) que está a ponto de aparecer, e quando ele vê o símbolo `&` ele assume que o próximo texto será o nome de uma entidade.

Felizmente, você pode utilizar as duas entidades gerais `&lt;` e `&amp;` sempre que você precisar incluí-los.

Uma entidade geral só pode ser definida dentro de um contexto SGML. Tipicamente, isto é feito imediatamente depois da declaração DOCTYPE.

Exemplo 3-10. Definindo uma entidade geral

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY current.version    "3.0-RELEASE">
    <!ENTITY last.version       "2.2.7-RELEASE">
    ]>

Observe como a declaração DOCTYPE foi estendida adicionando-se um colchete no final da primeira linha. As duas entidades estão definidas nas próximas duas linhas, antes que o colchete seja fechado, e então a declaração DOTYPE é fechada.

O colchete é necessário para indicar que nós estamos extendendo o DTD indicado pela declaração DOCTYPE.

### 3.6.2 Entidades de parâmetro

Assim como as entidades gerais , as entidades de parâmetro são utilizadas para atribuir um nome a pedaços reutilizáveis de texto. Entretanto, enquanto as entidades gerais só podem ser utilizadas com o seu documento, as entidades de parâmetro podem ser utilizadas apenas dentro de um contexto SGML.

As entidades de parâmetro são definidas de uma forma similar as entidades gerais. Entretanto, ao invés de utilizar `&`nome-da-entidade`;` como referência, utiliza `%`nome-da-entidade`;` [1]. A definição também inclui o `%` entre a palavra chave `ENTITY` e o nome da entidade.

Exemplo 3-11. Definindo entidades de parâmetros

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY % param.some "some">
    <!ENTITY % param.text "text">
    <!ENTITY % param.new  "%param.some more %param.text">

    <!-- %param.new agora contém "some more text" -->
    ]>

Isto pode não parecer particularmente útil. Mas ele será.

### 3.6.3 Para você fazer…

1. Adicione uma entidade geral ao `example.xml`.

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
       <!ENTITY version "1.1">
       ]>

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <!-- Você pode ter alguns comentários aqui também -->

         <body>
           <p>Este é um parágrafo contendo algum texto.</p>

           <p>Este parágrafo contém mais algum texto.</p>

           <p align="right">Este parágrafo pode estar alinhado a direita.</p>

           <p>A versão atual deste documento é: &version;</p>
         </body>
       </html>

2. Valide o documento utilizando o `onsgmls`

3. Carregue o arquivo `example.xml` no seu navegador web (Você pode precisar copiá-lo para `example.html` antes que o seu navegador possa reconhecê-lo como um documento HTML).

   A menos que o seu navegador seja muito avançado, você não irá ver a entidade referenciada por `&version;` substituída pelo número de versão. A maioria dos navegadores web possuem interpretadores muito simplistas os quais não manuseiam corretamente SGML [2].

4. A solução é normalizar seu documento utilizando um normalizador SGML. Um normalizador lê um SGML válido e retorna um SGML igualmente válido o qual foi transformado de alguma forma. Uma das formas em que o normalizador transforma o SGML é expandindo todas as entidades referenciadas no documento, substituindo as entidades pelo texto que elas representam.

   Você pode utilizar o `osgmlnorm` para fazer isto:

       % osgmlnorm example.xml > example.html

   Você deve encontrar uma cópia normalizada (isto é, entidades referenciadas expandidas) do seu documento no arquivo `example.html`, pronta para ser carregada no seu navegador web.

5. Se você examinar o retorno do `osgmlnorm` você ira ver que ele não inclui a declaração DOCTYPE no inicio. Para incluí-la você precisa utilizar a opção `-d`:

       % osgmlnorm -d example.xml > example.html

## 3.7 Utilizando entidades para incluir arquivos

As entidades (ambas gerais e de parâmetros) são particularmente úteis quando utilizadas para incluir um arquivo dentro de outro.

### 3.7.1 Utilizando entidades gerais para incluir arquivos

Suponha que você possui algum conteúdo para um livro SGML organizado em arquivos, um arquivo por capítulo, chamados `chapter1.xml`, `chapter2.xml`, e assim por diante, com um arquivo `book.xml` que irá conter estes capítulos.

A fim de utilizar o conteúdo destes arquivos como os valores para as suas entidades, você as declara com a palavra chave `SYSTEM`. Isto direciona o interpretador SGML para utilizar o conteúdo dos arquivos nomeados como o valor da entidade.

Exemplo 3-12. Utilizando entidades gerais para incluir arquivos

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY chapter.1 SYSTEM "chapter1.xml">
    <!ENTITY chapter.2 SYSTEM "chapter2.xml">
    <!ENTITY chapter.3 SYSTEM "chapter3.xml">
    <!-- e assim por diante -->
    ]>

    <html>
      <!-- Utilize as entidades para carregar os capítulos -->

      &chapter.1;
      &chapter.2;
      &chapter.3;
    </html>

> Atenção: Quando utilizar uma entidade geral para incluir outros arquivos em um documento, os arquivos que estiverem sendo inclusos (`chapter1.xml`, `chapter2.xml`, etc) não devem iniciar com uma declaração DOCTYPE. Isto é um erro de sintaxe.

### 3.7.2 Utilizando entidades de parâmetro para incluir arquivos

Recorde-se que uma entidade de parâmetro só pode ser utilizada dentro de um contexto SGML. Por que então você desejaria incluir um arquivo dentro de um contexto do SGML?

Você pode utilizar isto para assegurar-se de que você pode reutilizar as suas entidades gerais.

Suponha que você possui muitos capítulos em seu documento, e você reutiliza estes capítulos em dois livros diferentes, cada livro organizando os capítulos de uma forma diferente.

Você pode listar as entidades no topo de cada livro, mas isto rapidamente torna-se incomodo de gerenciar.

Em vez de disso, coloque as definições das suas entidades gerais em um arquivo, e utilize uma entidade de parâmetro para incluir este arquivo dentro do seu documento.

Exemplo 3-13. Utilizando entidades de parâmetro para incluir arquivos.

Primeiro, coloque as suas definições de entidades em um arquivo separado, chamado `chapters.ent`. Este arquivo contém o seguinte:

    <!ENTITY chapter.1 SYSTEM "chapter1.xml">
    <!ENTITY chapter.2 SYSTEM "chapter2.xml">
    <!ENTITY chapter.3 SYSTEM "chapter3.xml">

Agora crie uma entidade de parâmetro para referenciar o conteúdo do arquivo. E então utilize a entidade de parâmetro para carregar o arquivo no seu documento, o que tornará todas as entidades gerais disponíveis para uso. Feito isso, utilize as entidades gerais como antes;

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!-- Define uma entidade de parâmetro para carregar as entidades gerais de capitulo -->
    <!ENTITY % chapters SYSTEM "chapters.ent">

    <!-- Agora utilize a entidade de parâmetro para carregar neste arquivo -->
    %chapters;
    ]>

    <html>
      &chapter.1;
      &chapter.2;
      &chapter.3;
    </html>

### 3.7.3 Para você fazer…

#### 3.7.3.1 Utilizando entidades gerais para incluir arquivos

1. Crie três arquivos, `para1.xml`, `para2.xml`, e `para3.xml`.

   Coloque um conteúdo similar ao seguinte em cada arquivo:

       <p>Este é o primeiro parágrafo.</p>

2. Edite o arquivo `example.xml` para que ele se pareça com este:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY version "1.1">
       <!ENTITY para1 SYSTEM "para1.xml">
       <!ENTITY para2 SYSTEM "para2.xml">
       <!ENTITY para3 SYSTEM "para3.xml">
       ]>

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <body>
           <p>A versão atual deste documento é: &version;</p>

           &para1;
           &para2;
           &para3;
         </body>
       </html>

3. Produza o arquivo `example.html` através da normalização do arquivo `example.xml`.

       % osgmlnorm -d example.xml > example.html

4. Carregue o arquivo `example.html` no seu navegador web, e confirme que os arquivos `para`n`.xml` foram incluídos no `example.html`.

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

> Nota: Você deve ter executado os passos anteriores primeiro.

1. Edite o arquivo `example.xml` para que ele se pareça com este:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY % entities SYSTEM "entities.xml"> %entities;
       ]>

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <body>
           <p>A versão atual deste documento é: &version;</p>

           &para1;
           &para2;
           &para3;
         </body>
       </html>

2. Crie um novo arquivo chamado `entities.xml`, com este conteúdo:

       <!ENTITY version "1.1">
       <!ENTITY para1 SYSTEM "para1.xml">
       <!ENTITY para2 SYSTEM "para2.xml">
       <!ENTITY para3 SYSTEM "para3.xml">

3. Produza o arquivo `example.html` através da normalização do arquivo `example.xml`.

       % osgmlnorm -d example.xml > example.html

4. Carregue o arquivo `example.html` no seu navegador web e confirme que os arquivos `para`n`.xml` foram incluídos no arquivo `example.html`.

## 3.8 Sessões marcadas

O SGML fornece um mecanismo para indicar que uma parte particular do documento deve ser processada de uma forma especial. Estas partes são denominadas “sessões marcadas”.

Exemplo 3-14. Estrutura de uma sessão marcada

    <![ Palavra-chave [
      Conteúdo da sessão marcada
    ]]>

Como você esperaria, sendo uma construção SGML, uma sessão marcada inicia com um `<!`.

O primeiro colchete começa a limitar a sessão marcada.

A `Palavra-chave` descreve como esta sessão marcada deve ser processada pelo interpretador.

O segundo colchete indica que o conteúdo da sessão marcada inicia aqui.

A sessão marcada é finalizada pelo fechamento dos dois colchetes e então retornando ao contexto do documento a partir do contexto SGML com o `>`.

### 3.8.1 Palavras-Chave de sessões marcadas

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

> Nota: Quando você utiliza `CDATA` ou `RCDATA` nos exemplos de texto marcado em SGML, tenha em mente que o conteúdo do `CDATA` não é validado. Você tem que verificar o SGML incluso no texto utilizando algum outro meio. Você pode, por exemplo, escrever o exemplo em outro documento, validar o código de exemplo, e então colá-lo para o seu conteúdo `CDATA`.

Exemplo 3-15. Utilizando uma sessão marcada como CDATA

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

Se você examinar o fonte deste documento você irá ver que esta técnica foi utilizada por toda parte.

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

Exemplo 3-16. Utilizando `INCLUDE` e `IGNORE` nas sessões marcadas

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

Exemplo 3-17. Utilizando uma entidade de parâmetro para controlar uma sessão marcada

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

Quando for produzir uma versão impressa do documento, altere a definição da entidade para;

    <!ENTITY % electronic.copy "IGNORE">

Ao reprocessar o documento, a sessão marcada que utilizar a entidade `%electronic.copy` como a sua palavra chave será ignorada.

### 3.8.2 Para você fazer…

1. Crie um novo arquivo chamado `section.xml`, o qual deve conter o seguinte conteúdo:

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

       <html>
         <head>
           <title>Um exemplo utilizando uma sessão marcada.</title>
         </head>

         <body>
           <p>Este parágrafo <![ CDATA [contêm muitos caracteres <
             (< < < < <) de forma que é mais simples utilizar
             uma sessão marcada do tipo CDATA.]]></p>

           <![ IGNORE [
           <p>Este parágrafo definitivamente não será incluído
             no output.</p>
           ]]>

           <![ %text.output [
           <p>Este parágrafo pode ou não aparecer no output.</p>

           <p>A sua ocorrência é controlada pela entidade de parâmetro %text.output
             .</p>
           ]]>
         </body>
       </html>

2. Normalize este arquivo utilizando o `osgmlnorm` e examine o resultado. Observe quais parágrafos apareceram, quais desapareceram e o que aconteceu com o conteúdo da sessão marcada como CDATA.

3. Altere a definição da entidade `text.output` de `INCLUDE` para `IGNORE`. Re-normalize o arquivo, e observe o resultado para ver o que foi alterado.

## 3.9 Conclusão

Esta é a conclusão da introdução ao SGML. Devido a restrições de espaço e complexidade, diversos assuntos não foram abordados em profundidade (ou sequer foram abordados). Entretanto, as sessões prévias cobriram o suficiente do SGML para que você possa seguir a organização da documentação do FDP.

# Capítulo 4 Marcação SGML

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.

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.

Esta não é 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 lista de discussão do projeto de documentação do FreeBSD.

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

## 4.1 HTML

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

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 `DocBook` oferece uma maior variedade de elementos. Consequentemente, você só irá encontrar páginas em HTML se estiver escrevendo para o web site.

O HTML já passou por algumas versões, 1, 2, 3.0, 3.2 e a última, 4.0 (disponível nas duas variantes, strict e loose).

Os HTML DTD's estão disponíveis na coleção de `ports` na pasta `textproc/html`. Eles são automaticamente instalados como parte do `port` `textproc/docproj`

### 4.1.1 Identificador Público Formal (IPF)

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.

A maioria dos documentos HTML no web site do FreeBSD estão de acordo com a versão `loose` do HTML 4.0.

    PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

### 4.1.2 Elementos de Seção

Um documento HTML é normalmente dividido em duas partes. A primeira é chamada de head, 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 body é contém o conteúdo que vai ser exibido para o usuário.

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

Exemplo 4-1. Estrutura Normal de um Documento HTML

    <html>
      <head>
    	  <title>Título do Documento</title>
      </head>

      <body>

        …

      </body>
    </html>

### 4.1.3 Bloco de Elementos

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

Exemplo 4-2. `<h1>`, `<h2>`, e outras Tags de Header.

Uso:

    <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 `<h`n`>` 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.

Exemplo 4-3. Má organização de elementos `<h`n`>`

Uso:

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

Exemplo 4-4. `<p>`

Uso:

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

Exemplo 4-5. `<blockquote>`

Uso:

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

Exemplo 4-6. `<ul>` e `<ol>`

Uso:

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

Exemplo 4-7. Listas de Definição com `<dl>`

Uso:

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

Exemplo 4-8. `<pre>`

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

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

Tenha em mente que o `<` e o `&` continuam sendo reconhecidos como caracteres especiais em um texto pré-formatado. É por isto que nos exemplos tivemos que utilizar `&lt;` ao invés de `<`. Para manter a consistência, o `&gt;` também foi utilizado no lugar do `>`. 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.

#### 4.1.3.6 Tabelas

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

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

Exemplo 4-9. Uso Simples de `<table>`

Uso:

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

Exemplo 4-10. Utiliizando `rowspan`

Uso:

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

Exemplo 4-11. Usando `colspan`

Uso:

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

Exemplo 4-12. Usando `rowspan` e `colspan` juntos

Uso:

    <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 Elementos In-line

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

Exemplo 4-13. `<em>` e `<strong>`

Uso:

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

Exemplo 4-14. `<b>` e `<i>`

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

Exemplo 4-15. `<tt>`

Uso:

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

Exemplo 4-16. `<big>`, `<small>`, e `<font>`

Todos os fragmentos fazem a mesma coisa.

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

> Nota: Os links também são elementos in-line.

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

Exemplo 4-17. Usando `<a href="...">`

Uso:

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

Exemplo 4-18. Usando `<a name="...">`

Uso:

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

Exemplo 4-19. Link para uma determinada parte de outro documento

Suponha que o exemplo `para1` esteja em um documento chamado `foo.html`.

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

Exemplo 4-20. Links para determinada parte do mesmo documento

Suponha que o exemplo `para1` esteja neste documento

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

## 4.2 DocBook

O DocBook foi originalmente desenvolvido por HaL Computer Systems e O'Reilly & Associates como um DTD para escrever documentação técnica [3]. E desde 1998 tem sido mantido pelo DocBook Technical Committee. Desta forma, ao contrário do LinuxDoc e do HTML, o DocBook é fortemente orientado a marcação que descreve o que é alguma coisa, ao invés de descrever como ela deve ser apresentada.

> Formal Versus Informal: Alguns elementos podem existir em duas formas, formal e informal. 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.

O DocBook DTD está disponível na coleção de ports como `textproc/docbook`. Ele é automaticamente instalado como parte do port `textproc/docproj`.

### 4.2.1 Extensões FreeBSD

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.

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

No restante deste documento, o termo “DocBook” deve ser interpretado como sendo a versão do DocBook DTD ampliado pelo projeto de documentação do FreeBSD.

> Nota: 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 Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`.

As extensões FreeBSD não estão (atualmente) na coleção de ports. Elas estão armazenadas na árvore Subversion do FreeBSD, como head/share/xml/freebsd.dtd.

### 4.2.2 Identificador Formal Público (IFP)

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

    PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"

### 4.2.3 Estrutura dos Documentos

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.

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

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

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

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 `<sect1>` (e `<sect2>` e assim por diante) que são usados nos livros.

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.

Os tutoriais sobre FreeBSD estão marcados na forma de artigos, enquanto por exemplo este documento, o FAQ do FreeBSD, e o Handbook do FreeBSD estão marcados na forma como livros.

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

Exemplo 4-21. Modelo padrão `<book>` com `<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>`.

Exemplo 4-22. Modelo padrão `<article>` com `<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.

Exemplo 4-23. Um capítulo simples

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

Exemplo 4-24. Capítulos Vazios

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

A primeira `<sect`n`>` é `<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>`.

Exemplo 4-25. Seções em Capítulos

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

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

#### 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 Elementos de Blocos

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

Exemplo 4-26. `<para>`

Uso:

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

Aparência:

Isso é um parágrafo. E pode conter quase qualquer outro elemento.

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

Exemplo 4-27. `<blockquote>`

Uso:

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

Aparência:

Um pequeno pedaço da Constituição dos Estados Unidos

| Preâmbulo da constituição dos Estados Unidos. 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. |
--Copiado de um site qualquer |

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

Exemplo 4-28. `<warning>`

Uso:

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

Aparência:

> Atenção: Instalar o FreeBSD talvez faça com que você queira desinstalar o Windows do seu Hard disk.

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

Exemplo 4-29. `<itemizedlist>`, `<orderedlist>`, e `<procedure>`

Uso:

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

Aparência:

- Esse é o primeiro item enumerado.

- Esse é o segundo item enumerado.

1. Esse é o primeiro item ordenado.

2. Esse é o segundo item ordenado.

1. Faça isto.

2. Depois faça isto.

3. E agora faça isto.

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

Exemplo 4-30. `<programlisting>`

Uso:

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

    <programlisting>#include <stdio.h>

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

Note como os colchetes na linha `#include` precisaram ser referenciados através de suas entidades ao invés de incluídas literalmente.

Aparência:

Quando você tiver terminado, seu programa deve estar assim;

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

Exemplo 4-31. `<co>` e `<calloutlist>`

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

Aparência:

Quando você tiver terminado, seu programa deve estar assim;

    #include <stdio.h>

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

  Inclui o arquivo padrão de IO.
  Especifica que `main()` retorna um inteiro.
  A chamada `printf()` escreve `hello, world` na saída padrão

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

Exemplo 4-32. `<informaltable>`

Uso:

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

Aparência:

Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2
--- | ---
Linha 1, coluna 1 | Linha 1, coluna 2
Linha 2, coluna 1 | Linha 2, coluna 2

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">`).

Exemplo 4-33. Tabelas com `frame="none"`

Aparência:

Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2
--- | ---
Linha 1, coluna 1 | Linha 1, coluna 2
Linha 2, coluna 1 | Linha 2, coluna 2

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

  Tudo que o usuário visualizar neste exemplo estará na tela do computador, assim o próximo elemento é `<screen>`.

  Dentro da marcação do `<screen>`, espaços em branco são significativos.

`<prompt>`, `&prompt.root;` e `&prompt.user;`

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

  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 `&prompt.root;` para o usuário root e `&prompt.user;` para o usuário normal, conforme for necessário. Estas entidades não precisam estar dentro de um `<prompt>`.

  > Nota: `&prompt.root;` e `&prompt.user;` são extensões do FreeBSD ao DocBook, e não são parte do DTD original.

`<userinput>`

  Quanto estiver mostrando um texto que o usuário deva digitar, envolva-o com as tags `<userinput>`. Ele provavelmente será mostrado diferente para o usuário.

Exemplo 4-34. `<screen>`, `<prompt>`, e `<userinput>`

Uso:

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

Aparência:

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

> Nota: Ainda que estejamos mostrando o conteúdo do arquivo `foo2`, ele não está marcado como `<programlisting>`. Deixe o `<programlisting>` para mostrar fragmentos de arquivos fora do contexto de ação do usuário.

### 4.2.5 Elementos In-line

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

Exemplo 4-35. `<emphasis>`

Uso:

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

Aparência:

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

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

Exemplo 4-36. Citações

Uso:

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

Aparência:

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

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

Exemplo 4-37. Teclas, Mouse e Combinações

Uso:

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

Aparência:

Para mudar para o segundo terminal virtual, digite Alt+F1.

Sair do `vi` sem salvar o seu trabalho, digite Esc : q !.

Meu gerenciador de janela é configurado de forma que Alt+botão direito do mouse é usado para mover as janelas.

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

Exemplo 4-38. Aplicações, Comandos, Opções

Uso:

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

Aparência:

O Sendmail é a aplicação de email mais utilizada em Unix.

O Sendmail inclui os programas sendmail(8), mailq(1), and newaliases(1).

Um dos parâmetros de linha de comando para o sendmail(8), `-bp`, irá mostrar o atual estado da mensagem na fila de email. Verifique isto na linha de comando usando `sendmail -bp`.

> Nota: Veja como a notação `&man.`command`.`section`;` é mais fácil de acompanhar.

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

Exemplo 4-39. `<filename>`

Uso:

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

Aparência:

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

#### 4.2.5.6 O Nome dos Ports

> Extensões FreeBSD: Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

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

Exemplo 4-40. Tag `<filename>` com o atributo `package`

Use:

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

Aparência:

Instale o port `net/ethereal` para ver o tráfego na rede.

#### 4.2.5.7 Dispositivos

> Extensões FreeBSD: Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

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.

Exemplo 4-41. `<devicename>`

Uso:

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

Aparência:

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

Por outro lado, dispositivos de rede, tais como `ed0` não aparecem `/dev`.

No MS-DOS, o primeiro disco flexível é chamado de `a:`. No FreeBSD é `/dev/fd0`.

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

> Extensões FreeBSD: Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

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.

Sem o atributo `role`, ou `role="hostname"`

  Sem o atributo `role` (i.e., `<hostid>`...`</hostid>`) a informação marcada é simplesmente o nome do computador, tal como `freefall` ou `wcarchive`. Você pode especificar explicitamente com `role="hostname"`.

`role="domainname"`

  O texto é um nome de domínio, tal como `FreeBSD.org` ou `ngo.org.uk`. Não há o componente do nome do computador (hostname).

`role="fqdn"`

  O texto é um nome completo, com o nome do computador e do domínio. O termo `fqdn` significa “Fully Qualified Domain Name” - Nome de Domínio Completamente Qualificado.

`role="ipaddr"`

  O texto é um endereço IP, provavelmente expresso como `dotted quad`.

`role="ip6addr"`

  O texto é um endereço IPv6.

`role="netmask"`

  O texto é uma máscara de rede, que pode ser expressa como `dotted quad`, uma string hexadecimal ou como `/` seguido de um número.

`role="mac"`

  O texto é um endereço MAC Ethernet, expresso como números hexadecimais de 2 digitos separados por dois pontos (:).

Exemplo 4-42. `<Hostid>` e `Roles`

Use:

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

Aparência:

A máquina local sempre pode ser referida pelo nome `localhost`, que terá o endereço IP `127.0.0.1`.

O domínio `FreeBSD.org` contém vários hosts diferentes, incluindo `freefall.FreeBSD.org` e `bento.FreeBSD.org`.

Quando estiver adicionando um apelido para uma interface (usando `ifconfig`) sempre use a máscara de rede `255.255.255.255` (que também pode ser expressa como `0xffffffff`).

O endereço MAC identifica unicamente cada placa de rede existente. Um endereço MAC típico se parece com `08:00:20:87:ef:d0`.

#### 4.2.5.9 Usernames

> Extensões FreeBSD: Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

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

Exemplo 4-43. `<Username>`

Uso:

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

Aparência:

Para executar a maioria das funções administrativas você precisará ser `root`.

#### 4.2.5.10 Descrevendo `Makefile`s

> Extensões FreeBSD: Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Existem dois elementos para descrever partes de `Makefile`s, `<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.

Exemplo 4-44. `<Maketarget>` e `<Makevar>`

Uso:

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

Aparência:

Dois alvos comuns em um `Makefile` são `all` e `clean`.

Tipicamente, usar `all` irá refazer a aplicação, usar `clean` irá remover os arquivos temporários (`.o` por exemplo) criados pelo processo de construção.

O `clean` pode ser controlado por muitas variáveis, incluindo `CLOBBER` e `RECURSE`.

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

Exemplo 4-45. `<Literal>`

Uso:

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

Aparência:

A linha `maxusers 10` 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.

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

Exemplo 4-46. `<replaceable>`

Uso:

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

Aparência:

    % man comando

O `<replaceable>` pode ser usado em muitos elementos diferentes, incluindo `<literal>`. Este exemplo também mostra que `<replaceable>` só deve envolver o conteúdo que o usuário deve fornecer. O outro conteúdo não deve ser alterado.

Uso:

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

Aparência:

A linha `maxusers `n`` 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 uma estação de trabalho, `32` é um bom valor para `n`.

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

Exemplo 4-47. `<errorname>`

Uso:

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

Aparência:

    “Panic: cannot mount root”

### 4.2.6 Imagens

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

> Você precisará instalar o port `graphics/ImageMagick` 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 `Makefile`s e em outros itens da infraestrutura, ele torna as coisas mais fáceis. Este port não está no meta port `textproc/docproj`, você deve instalá-lo manualmente.

> O melhor exemplo do que acontece na prática é o documento `doc/en_US.ISO8859-1/articles/vm-design/` . 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.

#### 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 `Makefile`s 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.

> Importante: É 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.

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

  Inclua um elemento `<imagedata>` dentro do elemento `<imageobject>`. O atributo `fileref` 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.
  O primeiro `<textobject>` deve conter um elemento `<literallayout>`, onde o atributo `class` é ajustado para `monospaced`. Esta é a oportunidade para você demonstrar suas habilidades com ASCII art. O conteúdo será usado se o documento for convertido para texto puro.

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

  O segundo `<textobject>` deve conter um único elemento `<phrase>`. O conteúdo deste elemento se tornará o atributo `alt` para as imagens quando o documento for convertido para HTML.

#### 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 nome do diretório deve ser incluído no atributo `fileref`

O `Makefile` deve conter:

    …
    IMAGES=  chapter1/fig1.png
    …

Desta forma tudo deve funcionar.

### 4.2.7 Links

> Nota: Links também são elementos in-line.

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

Exemplo 4-48. O atributo `id` em capítulos ou seções

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

Exemplo 4-49. `<anchor>`

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

Exemplo 4-50. Usando `<xref>`

Assuma que este fragmento apareça em algum lugar de um documento que inclua o `id` do exemplo.

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

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

> Maiores informações podem ser encontradas no Capítulo Um.

> Informações mais específicas podem ser encontradas na seção chamada Subseção 1.

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

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

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.

Exemplo 4-51. Usando `<link>`

Assuma que este fragmento aparece em algum lugar em um documento que inclui o `id` do exemplo.

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

Isto irá gerar o seguinte (Palavras em itálico indicam o texto que será o link):

> Maiores informações podem ser encontradas no primeiro capítulo .

> Informações mais específicas podem ser encontradas nesta seção

> Nota: Este último é um mau exemplo. Nunca use palavras como “esta” ou “aqui” como origem do link. O leitor terá que procurar no contexto próximo para ver para onde o link o está levando.

> Nota: Você pode usar o elemento `<link>` para incluir um link para um `id` em um elemento `<anchor>`, uma vez que o conteúdo de `<link>` define o texto que será usado para o link.

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

Exemplo 4-52. `<ulink>`

Uso:

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

Aparência:

É claro que você pode parar de ler este documento e ir para a Página principal do FreeBSD

# Capítulo 5 * Folhas de Estilo

O SGML não diz nada sobre como um documento deve ser exibido ao usuário, ou formatado para impressão. Para fazer isto, várias linguagens foram desenvolvidas para descrever folhas de estilo, incluindo DynaText, Panorama, SPICE, JSSS, FOSI, CSS, e DSSSL.

Para o `DocBook`, nós estamos usando folhas de estilo escritas em DSSSL. Para o HTML nós estamos usando o CSS.

## 5.1 * DSSSL

O projeto de documentação usa uma versão ligeiramente customizada das folhas de estilo modulares do `DocBook` de Norm Walsh.

Elas podem ser encontradas no `textproc/dsssl-docbook-modular`.

As folhas de estilo modificadas não estão no sistema de `ports`. Elas são parte do repositório de fontes do projeto de documentação, e podem ser encontradas em `doc/share/xml/freebsd.dsl`. Elas estão bem comentadas, e como a conclusão desta seção está pendente, recomendamos que você examine este arquivo para ver como algumas das opções disponíveis nas folhas de estilo padrão foram configuradas para customizar a saída para o projeto de documentação do FreeBSD. Este arquivo também contém exemplos que mostram como estender os elementos que a folha de estilo compreende, que é como os elementos específicos para o FreeBSD foram formatados.

## 5.2 CSS

Folha de estilo em cascata (CSS) é um mecanismo para anexar a informação de estilo (fontes, peso, tamanho, cor, e assim por diante) aos elementos de um documento HTML sem abusar do HTML para fazê-lo.

### 5.2.1 Documentos DocBook

As folhas de estilo DSSSL do FreeBSD incluem uma referência para a folha de estilo, `docbook.css`, a qual espera-se aparecer no mesmo diretório dos arquivos HTML. Este arquivo CSS geral do projeto é copiado de `doc/share/misc/docbook.css` quando os documentos são convertidos para HTML, e é instalado automaticamente.

# Capítulo 6 Estruturando Documentos Sob `doc/`

A árvore `doc/` é organizada de uma forma particular, e os documentos que compõe o Primer do Projeto de Documentação do FreeBSD devem ser por isso organizados de forma particular. O objetivo é tornar simples a adição de nova documentação à árvore, e:

1. Facilitar a automatização da conversão de documentos para outros formatos.

2. Promover consistência entre diferentes formas de organizar a documentação, facilitar a troca entre diferentes documentos.

3. Facilitar a decisão de onde na árvore uma nova documentação deveria ser colocada.

Além disso, a árvore de documentação tem de acomodar documentação que pode estar em muitas diferentes línguas e muitas diferentes codificações. É importante que a estrutura da árvore de documentação não force nenhum padrão particular ou preferência cultural.

## 6.1 O Nível Superior, `doc/`

Existem dois tipos de diretórios sob `doc/`, cada um com nomes de diretórios e significados muito específicos.

Diretório: `share/`

Significado: Contém arquivos que não são específicos as várias traduções e codificações da documentação. Contém subdiretórios para promover uma melhor categorização da informação. Por exemplo, os arquivos que compõem a infraestrutura de make(1) encontram-se em `share/mk`, enquanto os arquivos adicionais para suporte SGML (como as extensões do FreeBSD ao DocBook DTD) encontram-se em `share/xml`.

Diretório: ``idioma`.`codificação`/`

Significado: Existe um diretório para cada tradução e codificação da documentação, por exemplo `en_US.ISO8859-1/` e `zh_TW.Big5/`. Os nomes são longos, mas ao especificar completamente a língua e codificação prevenimos qualquer futura dor de cabeça caso um time de tradução queira prover a documentação na mesma língua mas em mais de uma codificação. Isto também nos isola completamente de quaisquer problemas que possam ser causados por uma mudança para Unicode.

## 6.2 Os Diretórios de ``idioma`.`codificação``

Estes diretórios contêm os documentos propriamente ditos. A documentação é dividida em até três categorias adicionais neste nível, indicadas pelos diferentes nomes de diretórios.

Diretório: `articles`

Conteúdo: Documentação codificada como DocBook `<article>` (ou equivalente). Razoavelmente pequena, e separada em seções. Normalmente disponível apenas como um arquivo HTML.

Diretório: `books`

Conteúdo: Documentação codificada como DocBook `<book>` (ou equivalente). Com o tamanho de um livro, e separada em capítulos. Normalmente disponível tanto como um grande arquivo HTML (para pessoas com conexões rápidas, ou que queiram imprimí-la facilmente a partir de um navegador Internet) quanto como uma coleção de pequenos arquivos interligados.

Diretório: `man`

Conteúdo: Para traduções das páginas de manual do sistema. Este diretório conterá um ou mais diretórios `man`n``, correspondendo as seções que foram traduzidas.

Nem todo diretório ``idioma`.`codificação`` conterá todos estes diretórios. Isto depende de quantos documentos já foram traduzidos pelo time de tradução.

## 6.3 Informação Específica do Documento

Esta sessão contém observações específicas sobre documentos particulares controlados pelo FDP.

### 6.3.1 O Handbook

`books/handbook/`

O Handbook é escrito de forma a obedecer a versão estendida do DTD DocBook utilizado pelo projeto FreeBSD.

O Handbook é organizado como um `<book>` Docbook. Ele está dividido em `<part>`es, e cada uma delas pode conter diversos `<chapter>`s (Capítulos). Os `<chapter>`s estão subdivididos em seções (`<sect1>`) e subseções (`<sect2>`, `<sect3>`) e assim por diante.

#### 6.3.1.1 Organização Fisíca

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

> Nota: A organização do Handbook pode mudar ao longo do tempo, e este documento pode ficar defasado no detalhamento destas alterações organizacionais. Se você tiver alguma pergunta sobre como o Handbook é organizado, por favor entre em contato com a lista de discussão do projeto de documentação do FreeBSD.

##### 6.3.1.1.1 `Makefile`

O `Makefile` define algumas variáveis as quais afetam a forma como o fonte SGML é convertido para outros formatos, e lista os vários arquivos fonte que compõem o Handbook. Ele também inclui um arquivo padrão chamado `doc.project.mk`, o qual contém o restante do código responsável por realizar a conversão dos documentos de um formato para outro.

##### 6.3.1.1.2 `book.xml`

Este é o documento de mais alto nível do Handbook. Ele contém as declarações DOCTYPE do Handbook, assim como os elementos que descrevem a estrutura do Handbook.

O `book.xml` utiliza entidades de parâmetro para carregar os arquivos com extensão `.ent`. Estes arquivos (descritos abaixo) definem as entidades gerais as quais são utilizadas ao longo de todo o Handbook.

##### 6.3.1.1.3 ``directory`/chapter.xml`

Cada capítulo do Handbook é armazenado em um arquivo chamado `chapter.xml` localizado em um diretório separado dos outros capítulos. Cada diretório é nomeado depois do valor do atributo `id` no elemento `<chapter>`.

Por exemplo, se um dos arquivos de capítulos contiver:

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

Então ele será chamado de `chapter.xml` e será armazenadao no diretório `kernelconfig` . Em geral, todo o conteúdo do capítulo será mantido neste arquivo.

Quando a versão HTML do Handbook for produzida, será gerado um arquivo `kernelconfig.html`. Isto ocorre devido ao valor do atributo `id` e não está relacionado ao nome do diretório.

Nas versões anteriores do Handbook os arquivos eram armazenados no mesmo diretório que o `book.xml`, e depois nomeados a partir do valor do atributo `id` presente no elemento `<chapter>` do arquivo. Agora, é possível incluir imagens em cada capítulo. As imagens de cada capítulo do Handbook são armazenadas dentro de `share/images/books/handbook`. Observe que as versões localizadas destas imagens devem ser colocadas no mesmo diretório com o código fonte SGML de cada capítulo. Colisões de namespace são inevitáveis, e é muito mais simples trabalhar com vários diretórios que contenham poucos arquivos em cada um, do que trabalhar com um diretório que contenha muitos arquivos.

Um exame rápido vai mostrar que existem muitos diretórios com um único arquivo `chapter.xml`, incluindo `basics/chapter.xml`, `introduction/chapter.xml`, e `printing/chapter.xml`.

> Importante: Os capítulos e/ou diretórios não devem ser nomeados de forma que reflitam sua ordem no Handbook. Esta ordenação pode mudar com uma reorganização do conteúdo do Handbook; este tipo de reorganização não deve (geralmente) incluir a necessidade de renomear os arquivos (a menos que um capítulo inteiro esteja sendo promovido ou rebaixado na hierarquia).

Cada arquivo `chapter.xml` não será um documento SGML completo. Em particular, eles não terão as suas próprias linhas DOCTYPE no início do arquivo.

Isto é uma infelicidade pois torna impossível tratá-los como arquivos SGML genéricos e simplesmente convertê-los para HTML, RTF, PS, e outros formatos da mesma forma que o Handbook principal é gerado. Isto irá forçá-lo a reconstruir o Handbook inteiro sempre que você desejar ver o efeito de uma alteração realizada em apenas um capítulo.

# Capítulo 7 O processo de construção da documentação

A principal finalidade desse capítulo é explicar claramente como o processo de criação da documentação é organizado, e como fazer modificações a este processo.

Depois de finalizar a leitura deste capítulo você deverá:

- Saber o que você precisa para compilar a documentação mantida pelo FDP, em adição ao que foi mencionado no capítulo Ferramentas SGML.

- Ser capaz de ler e entender as instruções do make que estão presentes em cada documento `Makefile`, assim como ter uma visão geral do `doc.project.mk`.

- Ser capaz de customizar o processo de compilação usando variáveis e alvos do make.

## 7.1 Ferramentas para construção da documentação do FreeBSD

Aqui estão suas ferramentas. Use-as de todas as formas que puder.

- A primeira ferramenta que você precisará é o make, mais especificamente o Berkeley Make.

- A construção de pacotes no FreeBSD é executada pelo pkg_create. Se você não está utilizando o FreeBSD, você terá que viver sem o uso de pacotes, ou então terá que compilar o código fonte você mesmo.

- O gzip é necessário para criar versões compactadas do documento. O compressor bzip2 e os arquivos zip também são suportados. O tar é suportado, e a construção de pacotes necessita dele.

- O install é o método padrão para instalar a documentação. Entretanto, existem alternativas.

> Nota: É improvável que você tenha qualquer problema em localizar esses dois últimos, eles estão sendo mencionados apenas para que a listagem fique completa.

## 7.2 Entendendo `Makefile`s na árvore da documentação

Há três tipos principais de `Makefile`s na árvore do projeto de documentção do FreeBSD.

- Os `Makefile`s de subdiretório simplesmente passam comandos para os diretórios abaixo dele.

- Os `Makefile`s de documentação descrevem o(s) documento(s) que deve(m) ser produzido(s) a partir deste diretório.

- Os Make includes são os responsáveis pela produção do documento, e geralmente possuem o nome no formato `doc.`xxx`.mk`.

### 7.2.1 `Makefile`s de Subdiretórios

Estes `Makefile`s geralmente tem a forma:

    SUBDIR =articles
    SUBDIR+=books

    COMPAT_SYMLINK = en

    DOC_PREFIX?= ${.CURDIR}/..
    .include "${DOC_PREFIX}/share/mk/doc.project.mk"

Resumidamente, as primeiras quatro linhas não vazias definem as variáveis do make, `SUBDIR`, `COMPAT_SYMLINK`, e `DOC_PREFIX`.

A primeira declaração da variável `SUBDIR`, tanto quanto a declaração da variável `COMPAT_SYMLINK`, mostra como atribuir um valor a uma variável, sobrescrevendo qualquer valor anterior que a mesma contenha.

A segunda declaração da variável `SUBDIR` mostra como um valor é adicionado ao valor atual de uma variável. A variável `SUBDIR` agora é composta por `articles books`.

A declaração do `DOC_PREFIX` mostra como um valor é atribuído para uma variável, mas somente se ela ainda não estiver definida. Isto é útil se o `DOC_PREFIX` não for onde este `Makefile` pensa que é - o usuário pode cancelar e fornecer o valor correto.

Agora o que tudo isso significa? O `SUBDIR` lista quais subdiretórios abaixo do atual devem ser incluídos no processo de compilação durante a geração do documento.

O `COMPAT_SYMLINK` é específico para compatibilizar os links simbólicos que ligam os idiomas a sua codificação oficial (por exemplo o `doc/en` deve apontar para `en_US.ISO-8859-1`).

O `DOC_PREFIX` é o caminho para a raíz da árvore do projeto de documentação do FreeBSD. O qual nem sempre é facil de encontrar, e que também pode ser facilmente sobrescrito, para permitir flexibilidade. O `.CURDIR` é uma variável interna do make que contém o caminho para o diretório atual.

A linha final inclui o arquivo principal do projeto de documentação do FreeBSD, o `doc.project.mk`, ele é o responsável por converter estas variáveis em instruções de compilação para uso do make.

### 7.2.2 `Makefile`s de Documentação

Estes `Makefile`s ajustam várias variáveis do make as quais descrevem como construir a documentação contida em um determinado diretório.

Aqui está um exemplo:

    MAINTAINER=nik@FreeBSD.org

    DOC?= book

    FORMATS?= html-split html

    INSTALL_COMPRESSED?= gz
    INSTALL_ONLY_COMPRESSED?=

    # SGML content
    SRCS=  book.xml

    DOC_PREFIX?= ${.CURDIR}/../../..

    .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

A variável `MAINTAINER` é uma muito importante. Esta variável fornece a habilidade de reivindicar a propriedade sobre um documento no projeto de documentação do FreeBSD, é por meio dela que você recebe a responsabilidade de mantê-lo.

`DOC` é o nome (sem a extensão `.xml`) do principal documento criado por este diretório. A variável `SRCS` lista todos os arquivos individuais que compõem o documento. Ela também deve incluir os arquivos importantes, nos quais qualquer mudança deve resultar em uma reconstrução.

O `FORMATS` indica os formatos nos quais o documento deve ser gerado por padrão. O `INSTALL_COMPRESSED` contém a lista padrão das técnicas de compressão que devem ser usadas no documento depois que ele é gerado. A variável `INSTALL_ONLY_COMPRESS`, nula por padrão, deve ser definida para um valor não nulo apenas se você desejar gerar exclusivamente a versão compactada do documento.

> Nota: Nós abordamos a atribuição das variáveis opcionais na seção anterior.

Você também já deve estar familiarizado com a atribuição da variável `DOC_PREFIX` e com as instruções de include.

## 7.3 Includes do Make do projeto de documentação do FreeBSD

Isto é melhor explicado pela inspeção no código. Aqui estão os arquivos include do sistema:

- O `doc.project.mk` é o principal arquivo include do projeto, que inclui todos os arquivos includes necessários.

- O `doc.subdir.mk` controla a navegação na árvore de documentação durante o processo de construção e instalação.

- O `doc.install.mk` fornece as variáveis que afetam a propriedade e a instalação de documentos.

- O `doc.docbook.mk` é incluído se o `DOCFORMAT` for `docbook` e se a variável `DOC` estiver definida.

### 7.3.1 `doc.project.mk`

Por inspeção:

    DOCFORMAT?=	docbook
    MAINTAINER?=	doc@FreeBSD.org

    PREFIX?=	/usr/local
    PRI_LANG?=	en_US.ISO8859-1

    .if defined(DOC)
    .if ${DOCFORMAT} == "docbook"
    .include "doc.docbook.mk"
    .endif
    .endif

    .include "doc.subdir.mk"
    .include "doc.install.mk"

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

> Nota: A variável `PRI_LANG` de maneira alguma afeta quais documentos serão, ou que poderão, ser compilados. Sua função principal é criar links para os documentos referenciados com maior frequência no diretório raiz de instalação da documentação do FreeBSD.

#### 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 `.endif`s fecham as duas condicionais anteriores, marcando o fim da sua aplicação.

### 7.3.2 doc.subdir.mk

Este arquivo é muito longo para ser explicado por inspeção, você deve ser capaz de interpretá-lo com o conhecimento adquirido nos capítulos anteriores, e com a pequena ajuda dada aqui.

#### 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.2.1 Targets fornecidos

- `install` e `package`, ambos descem pela árvore de diretórios executando a sua versão real dentro dos subdiretórios. (`realinstall` e `realpackage` respectivamente).

- O `clean` remove os arquivos criados pelo processo de compilação (e também desce na árvore de diretórios). O `cleandir` faz a mesma coisa, e também remove o diretório de objetos se este existir.

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

# Capítulo 8 O Website

## 8.1 Preparação

Utilize um disco que tenha espaço livre suficiente. Você irá precisar de 200 MB a 500 MB, dependendo do método que escolher. Este espaço irá abrigar as ferramentas SGML, um subconjunto da árvore svn, os arquivos temporários de trabalho e as páginas web instaladas.

> Nota: Certifique-se que seus ports de documentação estão atualizados! Quando na dúvida, remova os ports antigos usando o comando pkg_delete(1) antes de instalar o port. Por exemplo, nós atualmente dependemos do jade-1.2, e se você tem instalado o jade-1.1, por favor execute:

>     # pkg_delete jade-1.1

### 8.1.1 Usando o `svn`

O `svn` é necessário para se obter (“`check out`”) os arquivos do `doc/` a partir do repositório Subversion. O `svn` pode ser instalado com o pkg_add(1) ou a partir da coleção de Ports do FreeBSD, executando:

    # cd /usr/ports/devel/subversion
    # make install clean

Para obter os arquivos com o código fonte completo do web site do FreeBSD, execute:

    # svn checkout svn://svn.FreeBSD.org/doc/head/ /usr/build

> Dica: Se o comando `svn` não estiver sendo executado pelo usuário `root`, certifique-se de que o diretório `/usr/build` possui as permissões adequadas ao usuário utilizado. Se não for possível alterar as permissões, utilize um diretório diferente para armazenar os arquivos do web site.

Quando o `svn` terminar, a versão atual do website do FreeBSD estará disponível em `/usr/build`. Se vocé utilizou um diretório alvo diferente, substitua o `/usr/build` apropriadamente ao longo do restante deste documento.

É isso! Agora você pode proceder com a geração do web site.

## 8.2 Construa as páginas web do início

Depois de ter completado os passos necessários para obter os arquivos com o código fonte do website, você estará pronto para iniciar a compilação do web site. No nosso exemplo, o diretório de compilação é ``/usr/build`` e todos os arquivos necessários já estão disponíveis no mesmo.

1. Vá para o diretório de compilação:

       # cd /usr/build

2. A compilação do web site deve ser iniciada de dentro do diretório `en_US.ISO8859-1/htdocs` executando o comando make(1) `all` , para criar as páginas web:

       # cd en_US.ISO8859-1/htdocs
       # make all

## 8.3 Instalando as web pages em seu Web Server

1. Se você tiver saído do diretório `en_US.ISO8859-1/htdocs`, volte para dele.

       # cd /usr/build/en_US.ISO8859-1/htdocs

2. Execute o comando make(1) `install` , definindo a variável `DESTDIR` para o nome do diretório no qual deseja instalar os arquivos. Eles serão instalados no `$DESTDIR/data` o qual deve estar configurado para ser o diretório raiz do seu servidor web.

       # env DESTDIR=/usr/local/www make install

3. Se você já instalou previamente as páginas web dentro deste mesmo diretório o processo de instalação não irá remover nenhuma página web antiga ou desatualizada. Por exemplo, se você compilar e instalar uma nova cópia do web site todos os dias, o comando abaixo irá procurar e remover todos os arquivos que não tenham sido alterados nos últimos três dias.

       # find /usr/local/www -ctime 3 -print0 | xargs -0 rm

## 8.4 Variáveis de ambiente

`ENGLISH_ONLY`

  Se esta variável estiver definida e não for vazia, apenas a documentação em Inglês será compilada e instalada. Todas as traduções serão ignoradas. Por exemplo:

      # make ENGLISH_ONLY=YES all install

  Se você quiser desabilitar a variável `ENGLISH_ONLY` e compilar todas as páginas, incluindo traduções, basta definir a variável `ENGLISH_ONLY` para um valor vazio:

      # make ENGLISH_ONLY="" all install clean

`WEB_ONLY`

  Se esta variável estiver definida e não for vazia, apenas as páginas HTML do diretório `en_US.ISO8859-1/htdocs` serão compiladas e instaladas. Todos os demais documentos do diretório `en_US.ISO8859-1` (Handbook, FAQ, Tutorais, etc) serão ignorados. Por exemplo:

      # make WEB_ONLY=YES all install

`WEB_LANG`

  Se esta variável estiver definida, apenas as páginas web no idioma especificado por ela serão compiladas e instaladas dentro do diretório ``/usr/build``. Todos os demais idiomas serão ignorados. Por exemplo:

      # make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install

`NOPORTSCVS`

  Se esta variável estiver definida, o processo de compilação não fará o check out dos arquivos do ports do repositório cvs. Ao invés disso, ele irá copiar os arquivos a partir do `/usr/ports` (ou do local definido na variável `PORTSBASE`).

`WEB_ONLY`, `WEB_LANG`, `ENGLISH_ONLY` e `NOPORTSCVS` são variáveis do `make`. Você pode definir estas variáveis no `/etc/make.conf`, no `Makefile.inc`, ou ainda como variáveis de ambiente na linha de comando ou nos arquivos de inicialização do seu shell.

# Capítulo 9 Traduções

Este é o `FAQ` para as pessoas que traduzem a documentação do FreeBSD (`FAQ`, Manual do FreeBSD, tutoriais, páginas de manual e outros) para diferentes línguas.

Ele é fortemente baseado na tradução do `FAQ` do Projeto Alemão de Documentação do FreeBSD, originalmente escrito por Frank Gründer `<elwood@mc5sys.in-berlin.de>` e traduzido novamente para o inglês por Bernd Warken `<bwarken@mayn.de>`.

Este `FAQ` é mantido pela Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`.

9.1. Porque um `FAQ`?
9.2. O que significa i18n e l10n
9.3. Existe uma lista de discussão para tradutores?
9.4. São necessários mais tradutores?
9.5. Quais idiomas eu preciso conhecer?
9.6. Quais softwares eu preciso conhecer?
9.7. Como eu faço para descobrir se já existem outras pessoas traduzindo documentos para o meu idioma?
9.8. Ninguém mais está traduzindo para o meu idioma. O que eu faço?
9.9. Eu já tenho alguns documentos traduzidos, para onde eu devo enviá-los?
9.10. Eu sou a única pessoa trabalhando na tradução para este idioma, como faço para enviar meus documentos?
9.11. Posso incluir uma língua ou um texto específico do país em minha tradução?
9.12. Como os caracteres específicos do idioma podem ser incluídos?
9.13. Dirigindo-se ao leitor
9.14. Eu preciso colocar alguma informação adicional nas minhas traduções?

9.1. Porque um `FAQ`?

Mais e mais pessoas estão se juntando à lista de discussão FreeBSD-doc e estão se oferecendo para traduzir a documentação do FreeBSD para outras línguas. Este `FAQ` visa responder as suas perguntas, de forma que eles possam iniciar a tradução da documentação o quanto antes.

9.2. O que significa i18n e l10n

i18n significa internacionalização e l10n significa locallização. São apenas abreviações.

i18n pode ser lido como “i” seguido por 18 letras, seguidas por “n”. Similarmente, l10n é “l” seguido por 10 letras, seguidas por “n”.

9.3. Existe uma lista de discussão para tradutores?

Sim. Os diferentes grupos de tradução possuem as suas próprias listas de discussão. A lista dos projetos de tradução possui maiores informações sobre as listas de discussão e sobre os web sites mantidos por cada um dos projetos de tradução.

9.4. São necessários mais tradutores?

Sim. Quanto maior o número de pessoas trabalhando na tradução, mais rapidamente ela será finalizada, e mais rapidamente as mudanças na documentação em Inglês serão refletidas nos documentos traduzidos.

Você não precisa ser um tradutor profissional para poder ajudar.

9.5. Quais idiomas eu preciso conhecer?

Idealmente, você deverá possuir bons conhecimentos de Inglês escrito, e obviamente necessitará ser fluente na língua para a qual estiver traduzindo.

O conhecimento do idioma Inglês não é estritamente necessário. Por exemplo, você poderia fazer uma tradução do FAQ para o idioma Húngaro a partir da versão em Espanhol do documento.

9.6. Quais softwares eu preciso conhecer?

É fortemente recomendado que você mantenha uma cópia local do repositório Subversion do FreeBSD (ao menos da parte referente a documentação). Isto pode ser feito executando o comando:

    % svn checkout svn://svn.FreeBSD.org/doc/head/ head

> Nota: Você irá precisar ter o `devel/subversion` instalado.

Você deverá ter conhecimentos básicos de svn. Ele permitirá que você veja o que mudou entre as diferentes versões dos arquivos que compõem a documentação.

Por exemplo, para ver as diferenças entre as revisões `r33733` e `r33734` do `en_US.ISO8859-1/books/fdp-primer/book.xml` , execute:

    % svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml

9.7. Como eu faço para descobrir se já existem outras pessoas traduzindo documentos para o meu idioma?

A página do Projeto de Tradução da Documentação lista os trabalhos de tradução que são conhecidos atualmente. Se outros já estão trabalhando na tradução da documentação para o seu idioma, por favor, não duplique os esforços. Ao invés disso, faça contato com o grupo para ver como pode ajudá-los.

Se não existir nenhum projeto de tradução para o seu idioma listado nesta página, envie uma mensagem para lista de discussão do projeto de documentação do FreeBSD para o caso de alguém estar pensando em fazer a tradução, mas ainda não tiver anunciado nada.

9.8. Ninguém mais está traduzindo para o meu idioma. O que eu faço?

Parabés, você acabou de começar o “FreeBSD `sua-língua-aqui` Documentation Translation Project”. Bem vindo a bordo.

Primeiro, pense se você terá o tempo necessário. Uma vez que você é a única pessoa trabalhando no seu idioma no momento, será sua a responsabilidade de publicar o seu trabalho e coordenar qualquer voluntário que queira ajudá-lo.

Escreva um email para a lista de discussão do Projeto de Documentação, anunciando que você irá traduzir a documentação, assim a página do Projeto de Traduções de Documentação poderá ser atualizada.

Se já existir alguém em seu país provendo o espelhamento de serviços do FreeBSD, você deve contacta-lo e perguntar se você pode ter algum espaço web para seu projeto, e se possível um endereço de email ou mesmo um serviço de lista de discussão.

Então escolha um documento e comece a traduzir. É melhor começar com algo razoavelmente pequeno como `FAQ` ou um dos tutoriais.

9.9. Eu já tenho alguns documentos traduzidos, para onde eu devo enviá-los?

Isso depende. Se você já está trabalhando com uma equipe de tradução (tal como a equipe japonesa, ou a equipe alemã) então ela terá seus próprios procedimentos para manipular a documentação submetida, e estes serão descritos em seus web sites.

Se você for a única pessoa trabalhando em um determinado idioma (ou se você é o responsável pelo projeto de tradução e quer submeter suas mudanças de volta para o projeto FreeBSD) então você deve enviar sua tradução ao Projeto FreBSD (veja pergunta seguinte).

9.10. Eu sou a única pessoa trabalhando na tradução para este idioma, como faço para enviar meus documentos?

ou

Nós somos uma equipe de tradução, e queremos submeter os documentos que nossos membros traduziram para nós.

Primeiramente certifique-se que sua tradução está organizada corretamente. Isto significa que ela deve se encaixar na árvore de diretórios corrente e ser processada de maneira correta.

Atualmente a documentação do FreeBSD é armazenada em um diretório de nível superior chamado `head/`. Os diretórios abaixo deste são nomeados de acordo com o código do idioma em que eles estão escritos, definidos na ISO639 (`/usr/share/misc/iso639` em uma versão do FreeBSD mais nova que 20 de janeiro de 1999).

Se seu idioma puder ser codificado de maneiras diferentes (por exemplo, Chinês) então deverão existir outros diretórios abaixo deste, um para cada formato que você tenha forncecido.

Finalmente você deve ter diretórios para cada original.

Por exemplo, em uma hipotética tradução para o Sueco ficaria assim:

    head/
        sv_SE.ISO8859-1/
                         Makefile
    		     htdocs/
    			    docproj
                         books/
                               faq/
                                   Makefile
                                   book.xml

`sv_SE.ISO8859-1` é o nome da tradução, na forma ``lang`.`encoding``. Repare nos dois Makefiles que serão usados para construir a documentação.

Use tar(1) e gzip(1) para compactar sua documentação, e envie para o projeto.

    % cd doc
    % tar cf swedish-docs.tar sv_SE.ISO8859-1
    % gzip -9 swedish-docs.tar

Coloque o arquivo `swedish-docs.tar.gz` em algum lugar. Se você não tiver acesso ao seu próprio espaço web (talvez seu ISP não disponibilize um), então você pode enviar um email para Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`, e combinar de enviar os arquivos por email quando for conveniente.

De qualquer forma, você deve usar o send-pr(1) para enviar um relatório indicando que você submeteu a documentação. Seria muito útil se você conseguisse outras pessoas para revisar a sua tradução antes de submetê-la, uma vez que é improvável que a pessoa que irá disponibilizá-la no repositório seja fluente no seu idoma.

Alguém (provavelmente o gerente do projeto de documentação, atualmente Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`) irá examinar os seus arquivos e irá confirmar se eles compilam sem erros. Em especial, os seguintes items serão verificados:

1. Todos os seus arquivos usam strings RCS (tais como "ID")?

2. O `make all` no diretório `sv_SE.ISO8859-1` funciona corretamente?

3. O `make install` funciona corretamente?

Se houver algum problema, a pessoa que estiver examinando a sua submissão irá entrar em contato para que você faça as correções.

Se não exitir nenhum problema, os seus documentos traduzidos serão disponibilizados no repositório o quanto antes.

9.11. Posso incluir uma língua ou um texto específico do país em minha tradução?

Nós preferimos que você não faça isso.

Por exemplo, suponha que você esteja traduzindo o Manual do FreeBSD para o Coreano e queira incluir uma seção sobre varejistas na Coréia em seu Manual do FreeBSD.

Não há razão pela qual esta informação não deva estar nas versões em Inglês (ou Alemão, ou Espanhol, ou Japonâs, ou …). É possível que uma pessoa que fale Inglês na Coréia possa tentar obter uma cópia do FreeBSD enquanto esteja ali. Isso também ajuda a aumentar a presença perceptível do FreeBSD ao redor do mundo, o que não é uma coisa ruim.

Se você tem uma informação específica do seu país, por favor, submeta ela para alteração no Manual do FreeBSD em Inglês (usando send-pr(1)) e depois traduza novamente para sua língua no Manual do FreeBSD traduzido.

Obrigado.

9.12. Como os caracteres específicos do idioma podem ser incluídos?

Caracteres não-ASCII devem ser incluídos na documentação usando entidades SGML.

Resumidamente, eles são um ``e'' comercial (&), o nome da entidade e um ponto-e-vírgula (;).

Os nomes de entidades estão definidos no ISO8879, que está na árvore do ports como `textproc/iso8879`.

Alguns exemplos Incluem

Entidade: &eacute;

Aparência: é

Descrição: “e” minúsculo com acento agudo

Entidade: &Eacute;

Aparência: É

Descrição: “E” maiúsculo com acento agudo

Entidade: &uuml;

Aparência: ü

Descrição: “u” minúsculo com trema

Depois que você instalar o pacote iso8879, os arquivos em `/usr/local/share/xml/iso8879` conterão a lista completa.

9.13. Dirigindo-se ao leitor

Nos documentos em Inglês, o leitor é tratado por “você”, não há distinção entre formal/informal como existe em alguns idiomas.

Se você estiver traduzindo para um idioma que tenha esta distinção, use qualquer forma que normalmente é usada em outras documentações técnicas. Na dúvida, use a forma mais polida.

9.14. Eu preciso colocar alguma informação adicional nas minhas traduções?

Sim.

O cabeçalho da versão em Inglês de cada documento será parecido com o texto exibido abaixo:

    <!--
         The FreeBSD Documentation Project

         $FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $
    -->

A forma exata pode mudar, mas ela sempre incluirá a linha $FreeBSD$ e a frase `The FreeBSD Documentation Project`. Note que o $FreeBSD é inserido pelo svn, portanto ele deve estar vazio (apenas `$FreeBSD$`) para novos documentos.

O seu documento traduzido deve incluir sua própria linha $FreeBSD$, e você deve mudar a linha `FreeBSD Documentation Project` para `The FreeBSD `language` Documentation Project`.

Você deve ainda adicionar uma terceira linha que indicará qual revisão do texto em inglês o texto é baseado.

Assim, a versão em Espanhol deste arquivo pode começar com:

    <!--
         The FreeBSD Spanish Documentation Project
         $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $
         Original revision: r38674
         -->

# Capítulo 10 Estilo de Escrita

A fim de promover a consistência entre os inúmeros autores da documentação do FreeBSD, foram criadas algumas diretrizes para que os autores sigam.

Use a Grafia Inglesa Americana

  Existem diversas variantes do inglês, com grafias diferentes para a mesma palavra. Onde as grafias diferem, use a variante inglesa americana. Por exemplo: “color”, não “colour”, “rationalize”, não “rationalise”, e assim por diante.

  > Nota: O uso do Inglês Britânico pode ser aceito para a contribuição de artigos, contudo a ortografia deverá ser consistente ao longo de todo o documento. Os outros documentos, tais como livros, web sites, páginas de manual, etc. deverão utilizar o Inglês Americano.

Não use contrações

  Não use contrações. Soletre sempre a frase por completo. A frase “ Don't use contractions ” seria errada.

  Evite fazer uso das contrações para obter um tom mais formal, será mais preciso, e ligeiramente mais fácil para os tradutores.

Use a vírgula de série

  Em uma lista de artigos dentro de um parágrafo, separe cada artigo do outro com uma vírgula. Separe o último artigo do outro com uma vírgula e a palavra “e”.

  Por o exemplo, observe o seguinte:

  > Esta é uma lista de um, dois e três artigos.

  Isto é uma lista de três artigos, “um”, “dois”, e “três”, ou de uma lista de dois artigos, “um” e “dois e três”?

  É melhor ser explícito e incluir uma vírgula de série:

  > Esta é uma lista de um, dois, e três artigos.

Evite frases redundantes

  Tente não usar frases redundantes. No detalhe, “o comando”, “o arquivo”, e “o comando man” são provavelmente redundantes.

  Estes dois exemplos mostram isto para comandos. O segundo exemplo é preferido.

  Use o comando `cvsup` para atualizar seus fontes.

  Use o `cvsup` para atualizar seus fontes.

  Estes dois exemplos mostram isto para nomes de arquivo. O segundo exemplo é preferido.

  … no arquivo `/etc/rc.local`…

  … no `/etc/rc.local`…

  Estes dois exemplos mostram isto para referências aos manuais. O segundo exemplo é preferido (o segundo exemplo usa `<citerefentry>`).

  Veja o `man csh` para maiores informações

  veja o csh(1)

Dois espaços no final das sentenças.

  Use sempre dois espaços no fim das sentenças, isto melhora a legibilidade, e facilita o uso de ferramentas tais como o Emacs.

  Lembre-se que uma letra em caixa alta depois de um período, nem sempre denota uma sentença nova, especialmente na grafia de nomes. “Jordan K. Hubbard” é um bom exemplo; tem um `H` em caixa alta depois de um período e um espaço, e não há certamente uma sentença nova lá.

Para maiores informações sobre estilo de escrita, consulte Elementos de Estilo, por William Strunk.

## 10.1 Guia de Estilo

Para manter o código fonte da documentação consistente quando muitas pessoas diferentes o estão editando, por favor siga estas convenções de estilo.

### 10.1.1 Caixa de Letra (Maiúscula/Minúscula)

As `tags` devem ser utilizadas em caixa baixa, `<para>`, não `<PARA>`.

O texto que aparece em contextos do SGML é escrito geralmente em caixa alta, `<!ENTITY…>`, e `<!DOCTYPE…>`, não `<!entity…>` e `<!doctype…>`.

### 10.1.2 Acrônimos

Um acrônimo normalmente deve ser soletrado na primeira vez que ele aparecer em um livro, como por exemplo: "Network Time Protocol (NTP)". Depois que um acrônimo for definido, você deveria passar a utilizar apenas ele (e não o termo completo, a não ser que isso faça mais sentido contextualmente). Normalmente um acrônimo é definido uma única vez por livro. Mas se você preferir, você também pode definí-lo quando ele aparecer pela primeira vez em cada capítulo.

Nas três primeiras vezes que um acrônimo for utilizado ele deve ser destacado com a tag <acronym> utilizando o atributo `role` setado com o termo completo como seu valor. Isto irá permitir que o link para o glossário seja criado, e habilitará um mouseover que quando renderizado irá exibir o termo completo.

### 10.1.3 Identação

Cada arquivo começa com a identação ajustada na coluna 0, independentemente do nível de identação do arquivo que pode vir a incluí-lo.

As tags de abertura aumentam o nível de identação em 2 espaços, as tags de fechamento diminuem o nível de identação em 2 espaços. Blocos de 8 espaços no começo de uma linha devem ser subistituidos por um Tab. Não use espaços na frente dos Tabs, e não adicione espaços em branco no final de uma linha. O conteúdo dentro de um elemento deve ser identado por dois espaços caso ele ocupe mais de uma linha.

Por exemplo, o código para esta seção seria algo como:

    +--- This is column 0
    V
    <chapter>
      <title>...</title>

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

        <sect2>
          <title>Indentation</title>

          <para>Each file starts with indentation set at column 0,
    	<emphasis>regardless</emphasis> of the indentation level of the file
    	which might contain this one.</para>
          ...
        </sect2>
      </sect1>
    </chapter>

Se você usar o Emacs ou XEmacs para editar os arquivos o `sgml-mode` será carregado automaticamente, e as variáveis locais do Emacs ao final de cada arquivo devem reforçar estes estilos.

Os usuários do Vim podem querer configurar o seu editor da seguinte forma:

    augroup sgmledit
      autocmd FileType sgml set formatoptions=cq2l " Special formatting options
      autocmd FileType sgml set textwidth=70       " Wrap lines at 70 spaces
      autocmd FileType sgml set shiftwidth=2       " Automatically indent
      autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
      autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
      autocmd FileType sgml set autoindent         " Automatic indentation
    augroup END

### 10.1.4 Estilo de Tags

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

### 10.1.5 Mudanças nos espaços em branco.

Ao enviar mudanças, não envie mudanças de conteúdo ao mesmo tempo que mudanças no formato.

Desta forma as equipes que convertem o manual para outras línguas podem ver rapidamente o que de fato mudou no conteúdo com o seu envio, sem ter que se decidir se uma linha mudou por causa do conteúdo, ou apenas porque foi reformatada.

Por exemplo, se você adicionar duas sentenças a um parágrafo, de forma que o comprimento das linhas no mesmo agora excedem 80 colunas, envie sua mudança sem corrigir o comprimento da linha. Ajuste então a quebra de linha e envie uma segunda mudança. Na mensagem de `commit` da segunda mudança, deixe claro que se trata apenas de um ajuste de formatação, e que a equipe da tradução pode ignorá-la.

### 10.1.6 Nonbreaking space

Evite as quebras de linha nos locais onde elas ficarem feias ou onde dificultarem a compreensão de uma sentença. As quebras de linha dependem da largura do meio de saída escolhido. Em particular, visualizar um documento em HTML com um navegador em modo texto pode conduzir a parágrafos mal formatados como o exemplo a seguir:

       Data capacity ranges from 40 MB to 15
       GB.  Hardware compression …

A entidade geral `&nbsp;` proibe a quebra de linha entre partes que devem permanecer juntas. Utilize nonbreaking spaces nos seguintes lugares:

- Entre números e suas unidades:

      57600&nbsp;bps

- Entre os nomes dos programas e os seus números de versão:

      FreeBSD&nbsp;4.7

- Entre nomes compostos (utilize com cuidado quando estiver lidando com nomes com mais de 3 ou 4 palavras, como por exemplo, “The FreeBSD Brazilian Portuguese Documentation Project”):

      Sun&nbsp;Microsystems

## 10.2 Lista de Palavras

O que se segue é uma pequena lista das palavras com a grafia da maneira que deve ser usada no projeto da documentação do FreeBSD. Se a palavra que você está procurando não estiver nesta lista, por favor consulte a lista de palavras da O'Reilly.

- 2.2.X

- 4.X-STABLE

- CD-ROM

- DoS (Denial of Service)

- Ports Collection

- IPsec

- Internet

- MHz

- Soft Updates

- Unix

- disk label

- email

- file system

- manual page

- mail server

- name server

- null-modem

- web server

# Capítulo 11 Usando `sgml-mode` com o Emacs

As versões recentes do Emacs ou XEmacs (disponível na coleção dos `ports`) contêm um pacote muito útil chamado PSGML (ele pode ser instalado pelo `editors/psgml`). Ele é automaticamente invocado quando um arquivo com a extensão `.xml` é carregado, ou executando `M-x sgml-mode`, ele é a modalidade principal para tratar dos elementos e dos atributos de um arquivo SGML.

Compreender alguns dos comandos fornecidos por esta modalidade pode tornar o trabalho com os documentos em SGML, tais como o Handbook, muito mais fácil.

`C-c C-e`

  Executa o `sgml-insert-element`. Você será questionado sobre o nome do elemento que deseja inserir no ponto atual. Você pode usar a tecla TAB para completar o elemento. Os elementos que são inválidos no ponto atual não serão permitidos.

  As tags de abertura e de fechamento para o elemento serão inseridas. Se o elemento contiver outro, obrigatórios, os elementos destes também serão inseridos.

`C-c =`

  Executa o `sgml-change-element-name`. Coloque o cursor dentro de um elemento e execute este comando. Você será questionado sobre o nome do elemento para o qual você deseja mudar. As tags de abertura e de fechamento do elemento atual serão alterados para o novo elemento.

`C-c C-r`

  Executa o `sgml-tag-region`. Selecione algum texto (posicione o cursor no começo do texto, de `C-espaço`, agora posicione o cursor no final do texto, de `C-espaço`) e execute então este comando. Você será questionado sobre o nome do elemento que deseja inserir. Este elemento será inserido então imediatamente antes e depois da região marcada.

`C-c -`

  Executa o `sgml-untag-element`. Coloque o cursor dentro da tag de abertura ou de fechamento do elemento que você quer remover, e execute este comando. As tags de abertura ou de fechamento do elemento serão removidas.

`C-c C-q`

  Executa o `sgml-fill-element`. Irá reformatar recursivamente o elemento atual. A reformatação afetará o conteúdo em que os espaços em branco são significativos, como dentro de elementos `<programlisting>`, assim utilize este comando com cuidado.

`C-c C-a`

  Executa o `sgml-edit-attributes`. Abre um segundo `buffer` que contém uma lista de todos os atributos e valores atuais para o elemento mais próximo. Use a tecla TAB para navegar entre os atributos, utilize `C-k` para remover um valor existente e para substituí-lo com um novo, utilize `C-c C-c` para fechar este `buffer` e para retornar ao documento principal.

`C-c C-v`

  Executa o `sgml-validate`. Você será questionado se deseja salvar o documento atual (se necessário) e então executa uma validação do SGML. A saída da validação é capturada em um novo `buffer`, e você poderá então navegar de um foco de problema para outro, corrigindo os erros de marcação durante este processo.

`C-c /`

  Executa `sgml-insert-end-tag`. Insere a tag de fechamento para o elemento atual que está aberto.

Sem dúvida há outras funções úteis desta modalidade, mas estas são as que você irá utilizar com mais frequência.

Você também pode usar as seguintes entradas no `.emacs` para ajustar o espaçamento apropriado, a identação, e a largura de coluna para trabalhar com o projeto de documentação.

        (defun local-sgml-mode-hook
          (setq fill-column 70
                indent-tabs-mode nil
                next-line-add-newlines nil
                standard-indent 4
                sgml-indent-data t)
          (auto-fill-mode t)
          (setq sgml-catalog-files '("/usr/local/share/xml/catalog")))
        (add-hook 'psgml-mode-hook
          '(lambda () (local-psgml-mode-hook)))

# Capítulo 12 Veja também

Este documento não é deliberadamente uma discussão exaustiva sobre SGML, DTDs, ou do projeto de documentação do FreeBSD. Para obter maiores informações, sugerimos que você visite os seguintes sítios web.

## 12.1 Projeto de documentação do FreeBSD

- Páginas web do Projeto de documentação do FreeBSD

- Manual do FreeBSD

## 12.2 SGML

- Página web sobre SGML/XML, referências detalhadas sobre SGML

- Uma breve introdução ao SGML

## 12.3 HTML

- Consórcio `World Wide Web`

- As especificações do HTML 4.0

## 12.4 DocBook

- O comitê técnico do DocBook, responsáveis pelo DTD DocBook.

- DocBook: O guia definitivo, documentação online para o DTD DocBook.

- Repositório aberto de DocBook contém folhas de estilo DSSSL e outros recursos para pessoas que utilizam DocBook.

## 12.5 Projeto de documentação do Linux

- Pagínas web do projeto de documentação do Linux

# Apêndice A. Exemplos

Este apêndice contém arquivos SGML de exemplo e linhas de comando que você pode utilizar para convertê-los de um formato para outro. Se você instalou com sucesso as ferramentas do Projeto de Documentação, então você será capaz de utilizar estes exemplos imediatamente.

Estes exemplos não são exaustivos — eles não contêm todos os elementos que você pode utilizar, particularmente para a capa do seu documento. Para maiores exemplos de marcação DocBook você deve examinar o código SGML deste e de outros documentos, disponíveis no repositório `doc` do svn, ou disponíveis online no endereço http://svnweb.FreeBSD.org/doc/.

Para evitar confusão, estes exemplos utilizam a especificação DocBook 4.1 DTD sem nenhuma extensão particular adicionada pelo FreeBSD. Eles também utilizam as folhas de estilo padrões distribuídas pelo Norm Walsh, sem nenhuma customização feita nas mesmas pelo Projeto de Documentação do FreeBSD. Isto os torna mais úteis como exemplos genéricos de marcação DocBook.

## A.1 DockBook `<book>`

Exemplo A-1. DocBook `<book>`

    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

    <book>
      <bookinfo>
        <title>Um exemplo de Livro</title>

        <author>
          <firstname>Seu nome</firstname>
          <surname>Seu sobrenome</surname>
          <affiliation>
            <address><email>seuemail@example.com</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>2000</year>
          <holder>Texto de Copyright</holder>
        </copyright>

        <abstract>
          <para>Se seu livro possui um sumário ele deve ser colocado aqui.</para>
        </abstract>
      </bookinfo>

      <preface>
        <title>Prefácio</title>

        <para>Seu livro pode ter um prefácio, se este for o caso, ele deve
          ser colocado aqui.</para>
      </preface>

      <chapter>
        <title>Meu primeiro capítulo</title>

        <para>Este é o primeiro capítulo do meu livro.</para>

        <sect1>
          <title>Minha primeira seção</title>

          <para>Esta é a primeira seção do meu livro.</para>
        </sect1>
      </chapter>
    </book>

## A.2 DocBook `<article>`

Exemplo A-2. DocBook `<article>`

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

    <article>
      <articleinfo>
        <title>Um exemplo de Artigo</title>

        <author>
          <firstname>Seu nome</firstname>
          <surname>Seu sobrenome</surname>
          <affiliation>
            <address><email>seuemail@example.com</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>2000</year>
          <holder>Texto de Copyright</holder>
        </copyright>

        <abstract>
          <para>Se o seu artigo possuir um sumário ele deve ser colocado aqui.</para>
        </abstract>
      </articleinfo>

      <sect1>
        <title>Minha primeira seção</title>

        <para>Esta é a primeira seção do meu artigo.</para>

        <sect2>
          <title>Minha primeira subseção</title>

          <para>Esta é a primeira subseção do meu artigo.</para>
        </sect2>
      </sect1>
    </article>

## A.3 Produzindo saídas formatadas

Esta seção assume que você já instalou os softwares listados no port `textproc/docproj`, seja via meta-port ou manualmente. Além disso, ela também assume que os seus softwares estão instalados em subdiretórios sob o `/usr/local/`, e que os diretórios nos quais os binários foram instalados, estão mapeados no seu `PATH`. Ajuste os paths conforme a necessidade do seu sistema.

### A.3.1 Usando o Jade

Exemplo A-3. Convertendo de DocBook para HTML (em um único grande arquivo)

    % jade -V nochunks \
        -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
        -c /usr/local/share/xml/docbook/catalog \
        -c /usr/local/share/xml/jade/catalog \
        -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
        -t sgml  file.xml > file.html

  Especifique o parâmetro `nochunks` para as folhas de estilo, forçando que todos os outputs sejam escritos para a saída padrão (STDOUT) (utilizando as folhas de estilo do Norm Walsh).
  Especifique os catálogos que o Jade terá que processar. Três catálogos são requeridos. O primeiro é o catálogo que contém as informações sobre as folhas de estilo DSSSL. O segundo contém informações sobre o DTD DockBook. E o terceiro contém informações específicas para o Jade.
  Especifique o caminho completo das folhas de estilo DSSSL as quais o Jade irá utilizar quando estiver processando o documento.
  Instrua o Jade para realizar uma transformação de uma DTD para outra. Neste caso, a entrada será transformada de um DTD DocBook para um DTD HTML.
  Especifique o arquivo que o Jade deve processar, e redirecione a saída para o arquivo `.html` desejado.

Exemplo A-4. Convertendo de DocBook para HTML (vários arquivos pequenos)

    % jade \
        -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
        -c /usr/local/share/xml/docbook/catalog \
        -c /usr/local/share/xml/jade/catalog \
        -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
        -t sgml  file.xml

  Especifique os catálogos os quais o Jade terá que processar. Três catálogos são requeridos. O primeiro é o catálogo o qual contém as informações sobre as folhas de estilo DSSSL. O segundo contém informações sobre o DTD DocBook. O terceiro contém informações específicas para o Jade.
  Especifique o caminho completo da folha de estilo DSSSL a qual o Jade irá utilizar quando estiver processando o documento.
  Instrua o Jade para realizar a transformação de uma DTD para outra. Neste caso, a entrada será transformada de um DTD DocBook para um DTD HTML.
  Especifique o arquivo que o Jade deve processar. A folha de estilo determina como os arquivos HTML individuais serão nomeados, inclusive o nome do arquivo “raiz” (é o arquivo que contém o inicio do documento).

Este exemplo pode continuar gerando apenas um único arquivo HTML, dependerá da estrutura do documento que você estiver processando e das regras da folha de estilo selecionada, para divisão do output.

Exemplo A-5. Convertendo de DocBook para Postscript

O arquivo fonte SGML precisa ser convertido para um arquivo TeX.

    % jade -V tex-backend \
        -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
        -c /usr/local/share/xml/docbook/catalog \
        -c /usr/local/share/xml/jade/catalog \
        -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \
        -t tex  file.xml

  Customize as folhas de estilo para utilizar as várias opções existentes, específicas para a produção de saídas TeX.
  Especifique os catálogos os quais o Jade terá que processar. Três catálogos são requeridos. O primeiro é o catálogo o qual contém as informações sobre as folhas de estilo DSSSL. O segundo contém informações sobre o DTD DocBook. O terceiro contém informações específicas para o Jade.
  Especifique o caminho completo da folha de estilo DSSSL a qual o Jade irá utilizar quando estiver processando o documento.
  Instrua o Jade para converter o output para TeX.

O arquivo `.tex` gerado, deve ser agora processado pelo `tex`, especificando o pacote de macros `&jadetex`.

    % tex "&jadetex" file.tex

Você tem que executar o `tex` pelo menos três vezes. A primeira execução irá processar o documento, e determinar as áreas do documento que são referenciadas a partir de outras partes do documento, para uso na indexação, etc.

Não fique alarmado se você visualizar mensagens de alertas tais como “`LaTeX Warning: Reference `136' on page 5 undefined on input line 728.`” neste momento.

A segunda execução reprocessa o documento agora que certas peças de informação são conhecidas (tais como o número de páginas do documento). Isto permite indexar as entradas e estabelecer as outras referências cruzadas.

A terceira execução irá realizar a limpeza final necessária no arquivo

O output deste estágio será um ``arquivo`.dvi`.

Finalmente, execute o `dvips` para converter o arquivo `.dvi` para o formato Postscript.

    % dvips -o file.ps file.dvi

Exemplo A-6. Convertendo de DocBook para PDF

A primeira parte deste processo é idêntica ao realizado quando se converte de DocBook para Postscript, utilizando a mesma linha de comando para o `jade` (Exemplo A-5).

Quando o arquivo `.tex` já tiver sido gerado, você deve executar o pdfTeX utilizando o pacote de macros `&pdfjadetex`.

    % pdftex "&pdfjadetex" file.tex

De novo, execute este comando três vezes.

Ele irá gerar um ``arquivo` .pdf`, o qual não necessita de nenhum processamento adicional.

### Notas

[1] | Entidades de Parâmetro utilizam o símbolo de Porcentagem.
[2] | Isto é uma vergonha. Imagine todos os problemas e `hacks` (tais como os Server Side Includes) que poderiam ser evitados se eles o fizessem.
[3] | Uma pequena história sobre este assunto pode ser encontrada em http://www.oasis-open.org/docbook/intro.shtml#d0e41.
[4] | Há outros tipos de elementos de lista no DocBook, mas não vamos nos preocupar com eles no momento.

Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.