 Primer do Projeto de Documentac,ao do FreeBSD para novos colaboradores

  Projeto de documentac,ao do FreeBSD

   Copyright (c) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   2006, 2007, 2008, 2009 DocEng

   Obrigado por tornar-se parte do Projeto de Documentac,ao do
   FreeBSD. A sua contribuic,ao e extremamente valiosa.

   Este Primer do Projeto de Documentac,ao do FreeBSD cobre tudo o
   que voce precisa saber para comec,ar a contribuir com o Projeto de
   Documentac,ao do FreeBSD, desde as ferramentas e softwares que
   voce estara utilizando (tanto os obrigatorios quanto os
   recomendados) `a filosofia por tras do projeto de documentac,ao.

   Este documento e um trabalho em andamento, e nao esta completo. As
   sessoes que sabemos estarem incompletas estao indicadas com um *
   no seu nome.

   Versao Traduzida para Portugues do Brasil

   Esta e uma traduc,ao nao-oficial do Aviso Legal Padrao do Projeto
   de Documentac,ao do FreeBSD para o Portugues do Brasil. Ela nao
   foi publicada pelo Projeto de Documentac,ao do FreeBSD, e
   legalmente nao representa os termos de distribuic,ao de
   documentac,ao que utiliza o Aviso Legal Padrao do Projeto de
   Documentac,ao do FreeBSD -- somente o texto original do Aviso
   Legal Padrao do Projeto de Documentac,ao, em ingles, faz isso.
   Logo, a versao traduzida nao deve ser utilizada como um aviso
   legal valido. Esperamos, contudo, que esta traduc,ao ajude aos
   falantes de Portugues do Brasil a entender melhor o Aviso Legal
   Padrao do Projeto de Documentac,ao do FreeBSD.

   SEMPRE verifique a versao em Ingles mais recente do Aviso Legal
   Padrao do Projeto de Documentac,ao do FreeBSD na versao em Ingles
   do Manual do FreeBSD.

   Redistribuic,ao e utilizac,ao do codigo fonte (SGML DocBook) ou
   formato "compilado" (SGML, HTML, PDF, PostScript, RTF e assim por
   diante) com ou sem modificac,ao, sao permitidas contanto que as
   seguintes condic,oes sejam cumpridas:

    1. As redistribuic,oes do codigo fonte (SGML DocBook) devem reter
       o aviso de copyright acima, esta lista de condic,oes e a
       seguinte nota de responsabilidade assim como as primeiras
       linhas deste arquivo nao modificadas.

    2. As redistribuic,oes 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 condic,oes e a seguinte nota de responsabilidade na
       documentac,ao e/ou outros materiais fornecidos com a
       distribuic,ao.

     Importante: ESTA DOCUMENTAC,AO E FORNECIDA PELO PROJETO DE
     DOCUMENTAC,AO DO FREEBSD "NO ESTADO" E QUAISQUER GARANTIAS
     EXPLICITAS OU IMPLICITAS, INCLUINDO, MAS NAO LIMITADAS AS
     GARANTIAS IMPLICITAS DE COMERCIALIZAC,AO E A DE ADEQUAC,AO PARA
     UMA FINALIDADE PARTICULAR SAO DESMENTIDAS. EM NENHUM EVENTO O
     PROJETO DE DOCUMENTAC,AO DO FREEBSD PODERA SER RESPONSABILIZADO
     POR QUAISQUER DANOS DIRETOS, INDIRETOS, INCIDENTAIS, ESPECIAIS,
     EXEMPLARES, OU CONSEQU:ENTES (INCLUINDO, MAS NAO LIMITADO A,
     OBTENC,AO DE BENS OU SERVIC,OS SUBSTITUTOS; PERDA DE USO, DE
     DADOS, OU DE LUCROS; OU A INTERRUPC,AO DE NEGOCIOS) DE QUALQUER
     FORMA CAUSADO E EM QUALQUER TEORIA DE RESPONSABILIDADE, SE EM
     CONTRATO, EM RESPONSABILIDADE ESTRITA, OU PROCESSUAL (PASSIVEL
     DE PROCESSO, INCLUINDO NEGLIGENCIA OU NAO) LEVANTADA DE QUALQUER
     FORMA PELO USO DESTA DOCUMENTAC,AO, 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.

     --------------------------------------------------------------

   Indice

   Prefacio

                Prompt do interpretador de comandos (shell)

                Convenc,oes Tipograficas

                Notas, dicas, informac,oes importantes, avisos e
                exemplos

                Agradecimentos

   1 Visao Geral

                1.1 Conjunto de Documentac,ao do FreeBSD

                1.2 Antes de voce iniciar

                1.3 Inicio Rapido

   2 Ferramentas

                2.1 Ferramentas Obrigatorias

                             2.1.1 Software

                             2.1.2 Entidades e DTDs

                             2.1.3 Stylesheets

                2.2 Ferramentas Opcionais

                             2.2.1 Software

   3 SGML Primer

                3.1 Visao Geral

                3.2 Elementos, tags, e atributos

                             3.2.1 Para voce fazer...

                3.3 A declarac,ao DOCTYPE

                             3.3.1 Identificadores publicos formais
                             (FPIs)

                             3.3.2 Alternativas aos FPIs

                3.4 Voltando para o SGML

                3.5 Comentarios

                             3.5.1 Para voce fazer...

                3.6 Entidades

                             3.6.1 Entidades gerais

                             3.6.2 Entidades de parametro

                             3.6.3 Para voce fazer...

                3.7 Utilizando entidades para incluir arquivos

                             3.7.1 Utilizando entidades gerais para
                             incluir arquivos

                             3.7.2 Utilizando entidades de parametro
                             para incluir arquivos

                             3.7.3 Para voce fazer...

                3.8 Sessoes marcadas

                             3.8.1 Palavras-Chave de sessoes marcadas

                             3.8.2 Para voce fazer...

                3.9 Conclusao

   4 Marcac,ao SGML

                4.1 HTML

                             4.1.1 Identificador Publico Formal (IPF)

                             4.1.2 Elementos de Sec,ao

                             4.1.3 Bloco de Elementos

                             4.1.4 Elementos In-line

                             4.1.5 Links

                4.2 DocBook

                             4.2.1 Extensoes FreeBSD

                             4.2.2 Identificador Formal Publico (IFP)

                             4.2.3 Estrutura dos Documentos

                             4.2.4 Elementos de Blocos

                             4.2.5 Elementos In-line

                             4.2.6 Imagens

                             4.2.7 Links

   5 * Folhas de Estilo

                5.1 * DSSSL

                5.2 CSS

                             5.2.1 Documentos DocBook

   6 Estruturando Documentos Sob doc/

                6.1 O Nivel Superior, doc/

                6.2 Os Diretorios de idioma.codificac,ao

                6.3 Informac,ao Especifica do Documento

                             6.3.1 O Handbook

   7 O processo de construc,ao da documentac,ao

                7.1 Ferramentas para construc,ao da documentac,ao do
                FreeBSD

                7.2 Entendendo Makefiles na arvore da documentac,ao

                             7.2.1 Makefiles de Subdiretorios

                             7.2.2 Makefiles de Documentac,ao

                7.3 Includes do Make do projeto de documentac,ao do
                FreeBSD

                             7.3.1 doc.project.mk

                             7.3.2 doc.subdir.mk

   8 O Website

                8.1 Preparac,ao

                             8.1.1 Usando o svn

                8.2 Construa as paginas web do inicio

                8.3 Instalando as web pages em seu Web Server

                8.4 Variaveis de ambiente

   9 Traduc,oes

   10 Estilo de Escrita

                10.1 Guia de Estilo

                             10.1.1 Caixa de Letra
                             (Maiuscula/Minuscula)

                             10.1.2 Acronimos

                             10.1.3 Identac,ao

                             10.1.4 Estilo de Tags

                             10.1.5 Mudanc,as nos espac,os em branco.

                             10.1.6 Nonbreaking space

                10.2 Lista de Palavras

   11 Usando sgml-mode com o Emacs

   12 Veja tambem

                12.1 Projeto de documentac,ao do FreeBSD

                12.2 SGML

                12.3 HTML

                12.4 DocBook

                12.5 Projeto de documentac,ao do Linux

   A. Exemplos

                A.1 DockBook <book>

                A.2 DocBook <article>

                A.3 Produzindo saidas formatadas

                             A.3.1 Usando o Jade

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

   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 usuarios dos shells sh(1) e bash(1)

   3-7. .cshrc, para os usuarios dos shell csh(1) e tcsh(1)

   3-8. Comentario SGML generico

   3-9. Comentarios SGML errados

   3-10. Definindo uma entidade geral

   3-11. Definindo entidades de parametros

   3-12. Utilizando entidades gerais para incluir arquivos

   3-13. Utilizando entidades de parametro para incluir arquivos.

   3-14. Estrutura de uma sessao marcada

   3-15. Utilizando uma sessao marcada como CDATA

   3-16. Utilizando INCLUDE e IGNORE nas sessoes marcadas

   3-17. Utilizando uma entidade de parametro para controlar uma
   sessao marcada

   4-1. Estrutura Normal de um Documento HTML

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

   4-3. Ma organizac,ao de elementos <hn>

   4-4. <p>

   4-5. <blockquote>

   4-6. <ul> e <ol>

   4-7. Listas de Definic,ao 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 padrao <book> com <bookinfo>

   4-22. Modelo padrao <article> com <articleinfo>

   4-23. Um capitulo simples

   4-24. Capitulos Vazios

   4-25. Sec,oes em Capitulos

   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. Citac,oes

   4-37. Teclas, Mouse e Combinac,oes

   4-38. Aplicac,oes, Comandos, Opc,oes

   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 capitulos ou sec,oes

   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 unico grande arquivo)

   A-4. Convertendo de DocBook para HTML (varios arquivos pequenos)

   A-5. Convertendo de DocBook para Postscript

   A-6. Convertendo de DocBook para PDF

     --------------------------------------------------------------

                                Prefacio

Prompt do interpretador de comandos (shell)

   A tabela seguinte mostra o prompt padrao do sistema e o prompt do
   super usuario. Os exemplos irao utilizar estes prompts para
   indicar com qual usuario o exemplo foi executado.

                  Usuario                           Prompt            
   Usuario normal                        %                            
   root                                  #                            

     --------------------------------------------------------------

Convenc,oes Tipograficas

   A tabela seguinte descreve as convenc,oes tipograficas utilizadas
   neste livro.

                Proposito                         Exemplos            
   Nome de um comando.                 Utilize ls -a para listar      
                                       todos os arquivos.             
   Nome de um arquivo.                 Edite o seu arquivo .login .   
   Saida (output) de um programa na    Voce tem email.                
   tela do computador.                 
   O que voce digita, quando           % su                           
   contrastado com a saida (output) do Password:                      
   programa na tela do computador.     
   Referencia a uma pagina de manual.  Utilize o su(1) para assumir   
                                       outro nome de usuario.         
   Nome de usuario e de grupos de      Apenas o root pode fazer isso. 
   usuarios                            
   Enfase                              Voce deve fazer isso.          
   Variaveis da linha de comando;      Para deletar um arquivo,       
   Substitua com o nome real ou com a  digite rm nome_do_arquivo      
   variavel.                           
   Variaveis de ambiente               O $HOME e o seu diretorio      
                                       home.                          

     --------------------------------------------------------------

Notas, dicas, informac,oes importantes, avisos e exemplos

   Ao longo do texto aparecerao notas, avisos e exemplos.

     Nota: Notas sao representadas desta forma, e contem informac,oes
     para as quais voce deveria ficar atento, pois podem afetar o que
     voce faz.

     Dica: Dicas sao representadas desta forma, e contem informac,oes
     que voce pode achar uteis, ou que mostram uma maneira mais facil
     de fazer alguma coisa.

     Importante: Informac,oes importantes sao representadas desta
     forma. Normalmente elas destacam passos extras que voce pode
     precisar realizar.

     Atenc,ao: Avisos sao representados deste modo, e contem
     informac,oes de alerta para voce sobre possiveis danos se voce
     nao seguir as instruc,oes. Estes danos podem ser fisicos: para o
     seu equipamento ou para voce; ou, podem ser nao-fisicos: tal
     como a delec,ao inadvertida de arquivos importantes.

   Exemplo 1. Uma amostra de exemplo

   Os exemplos sao representados deste modo, e normalmente contem
   exemplos que voce deve analisar, ou entao, mostram como deveriam
   ser os resultados de uma determinada ac,ao.

     --------------------------------------------------------------

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 comentarios e criticas construtivas para este
   trabalho.

     --------------------------------------------------------------

                         Capitulo 1 Visao Geral

   Seja bem vindo ao Projeto de Documentac,ao do FreeBSD.
   Documentac,ao de boa qualidade e muito importante para o sucesso
   do FreeBSD, e o Projeto de Documentac,ao do FreeBSD (FDP) e a
   origem de muitos destes documentos. Suas contribuic,oes sao muito
   importantes.

   A finalidade principal deste documento e explicar claramente como
   o FDP e organizado, como escrever e como submeter documentos para
   o FDP , e como utilizar de forma efetiva as ferramentas que estao
   disponiveis para voce enquanto estiver escrevendo.

   Todos sao bem vindos para se juntar ao FDP. Nao existe nenhum
   requisito minimo para a sua associac,ao, nenhuma quota de
   documentos que voce precise produzir por mes. Tudo o que voce
   precisa fazer e se inscrever na lista de discussao do projeto de
   documentac,ao do FreeBSD.

   Depois que voce tiver terminado de ler este documento, voce deve:

     * Saber quais documentos sao mantidos pelo FDP.

     * Ser capaz de ler e entender o codigo fonte SGML de um
       documento mantido pelo FDP.

     * Ser capaz de efetuar alterac,oes num documento.

     * Ser capaz de enviar suas alterac,oes de volta para revisao e
       eventual inclusao na documentac,ao do FreeBSD.

     --------------------------------------------------------------

1.1 Conjunto de Documentac,ao do FreeBSD

   O FDP e responsavel por quatro categorias de documentos do
   FreeBSD.

   Paginas de Manual

           As paginas de manual do sistema na lingua inglesa nao sao
           escritas pelo FDP, porque elas sao parte da base do
           sistema. Entretanto, o FDP pode (e tem) reescrever partes
           das paginas de manual existentes para torna-las mais
           claras, ou para corrigir imprecisoes.

           Os times de traduc,ao sao responsaveis por traduzir as
           paginas de manual do sistema para diferentes idiomas.
           Estas traduc,oes sao mantidas pelo FDP.

   FAQ

           O objetivo do FAQ e consolidar (no formato de perguntas e
           respostas curtas) as perguntas que foram feitas, ou que
           podem ser feitas, nas varias listas de discussao e
           newsgroups dedicados ao FreeBSD. O formato nao permite
           respostas longas e detalhadas.

   Handbook

           O Handbook almeja ser um compreensivo recurso de
           referencia online para os usuarios do FreeBSD.

   Web Site

           Esta e a principal presenc,a do FreeBSD na World Wide Web,
           visivel em   http://www.FreeBSD.org/ e em muitos sites
           espelhos ao redor do mundo. O web site e o primeiro
           contato de muitas pessoas com o FreeBSD.

   A documentac,ao do web site, do Handbook do FreeBSD e do FAQ estao
   disponiveis no repositorio Subversion doc/, que esta localizado em
   svn://svn.FreeBSD.org/doc/.

   As paginas de manual estao disponiveis no repositorio Subversion
   src/, que esta disponivel em svn://svn.FreeBSD.org/base/.

   Isto significa que os logs das alterac,oes realizadas nestes
   arquivos e visivel para qualquer um, e qualquer pessoa pode
   utilizar o svn para ver as alterac,oes.

   Em adic,ao, muitas pessoas escreveram tutoriais ou outros web
   sites relacionados ao FreeBSD. Alguns destes trabalhos tambem
   estao armazenados no repositorio Subversion (com a permissao do
   autor). Em outros casos o autor decidiu manter o seu documento
   separado do repositorio principal do FreeBSD. O FDP se esforc,a
   tanto quanto possivel para fornecer os links para estes
   documentos.

     --------------------------------------------------------------

1.2 Antes de voce iniciar

   Este documento assume que voce ja sabe:

     * Como manter uma copia local atualizada da documentac,ao do
       FreeBSD, atraves da manutenc,ao de uma copia local do
       repositorio 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 Inicio Rapido

   Se voce deseja ir comec,ando, e se sente seguro de que pode ir
   pegando as coisas `a medida que avanc,a, siga estas instruc,oes.

    1. Instale o meta-port   textproc/docproj.

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

    2. Obtenha uma copia local da arvore de documentac,ao do FreeBSD
       (doc) utilizando o svn.

       Se a velocidade da sua conexao ou se o espac,o de
       armazenamento do seu disco local forem motivo de preocupac,ao,
       o minimo que voce vai precisar sera uma copia de trabalho dos
       diretorios 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 voce tiver abundancia de espac,o em disco, voce pode
       retirar uma copia de trabalho completa (de todos os
       subdiretorios da arvore doc).

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

    3. Se voce esta preparando uma alterac,ao de um artigo ou livro
       existente, retire uma versao de trabalho do arquivo do
       repositorio. Se voce esta planejando contribuir com um novo
       livro ou artigo, entao utilize um dos existentes como guia.

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

         1. Retire uma copia de trabalho do diretorio 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, voce decidiu que o seu novo artigo iria para
            um diretorio chamado vpn-w2k.

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

       Se voce deseja editar um documento existente, como por exemplo
       o FAQ, o qual esta em   head/en_US.ISO8859-1/books/faq, voce
       deve retirar a copia de trabalho do repositorio 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 preferencia.

    5. Teste a marcac,ao SGML utilizando o alvo lint com o comando
       make. Isto ira listar rapidamente qualquer erro existente no
       documento sem realizar qualquer tipo de transformac,ao no seu
       arquivo, o que consumiria tempo.

 % make lint

       Quando voce estiver pronto para efetivamente compilar o
       documento, voce pode especificar um unico formato ou uma lista
       de formatos de destino, na variavel FORMATS. Atualmente os
       formatos suportados sao, html, html-split, txt, ps, pdf, e
       rtf. A lista mais atualizada dos formatos suportados esta
       listada no inicio do arquivo head/share/mk/doc.docbook.mk.
       Certifique-se de utilizar aspas (") em volta da lista de
       formatos quando voce estiver compilando mais de um formato num
       unico comando.

       Por exemplo, para converter o documento apenas para html, voce
       deve utilizar:

 % make FORMATS=html

       Mas quando voce deseja converter o documento tanto para o
       formato html quanto para o formato txt, voce pode utilizar
       duas execuc,oes separadas do make(1), como a seguir:

 % make FORMATS=html
 % make FORMATS=txt

       ou, voce pode fazer isso em um unico comando:

 % make FORMATS="html txt"

    6. Envie suas alterac,oes utilizando o send-pr(1).

     --------------------------------------------------------------

                         Capitulo 2 Ferramentas

   O FDP utiliza diferentes ferramentas como auxilio no gerenciamento
   da documentac,ao do FreeBSD, e na conversao para diferentes
   formatos, e assim por diante. Voce ira precisar utilizar estas
   ferramentas se for trabalhar com a documentac,ao do FreeBSD.

   Todas estas ferramentas estao disponiveis como Ports e Packages do
   FreeBSD, simplificando enormemente o seu trabalho para
   instala-las.

   Voce precisara instalar estas ferramentas antes de trabalhar com
   qualquer exemplo dos proximos capitulos. O uso real destas
   ferramentas sera abordado nos proximos capitulos.

     Se possivel use o   textproc/docproj: Voce pode economizar
     bastante tempo se instalar o port textproc/docproj. Este e um
     meta-port que por si so nao contem nenhum programa. Ao inves
     disto, ele depende que ja estejam instalados corretamente varios
     outros ports. O processo de instalac,ao ira baixar e instalar
     automaticamente todos os pacotes listados como necessarios neste
     capitulo.

     Um dos pacotes que voce pode precisar e o conjunto de macros
     JadeTeX. No entanto, esse conjunto de macros requer que o TeX
     esteja instalado. O TeX e um pacote grande, e ele somente sera
     necessario se voce quiser gerar documentos nos formatos
     Postscript ou PDF.

     Para economizar seu tempo e espac,o em disco voce deve
     especificar se quer, ou nao, a instalac,ao do JadeTeX (e por
     consequencia do TeX) quando o port for instalado. Conforme
     necessario, fac,a:

 # make JADETEX=yes install

     ou

 # make JADETEX=no install

     Alternativamente voce pode instalar o textproc/docproj-jadetex
     ou o textproc/docproj-nojadetex. Estes ports secundarios irao
     definir a variavel JADETEX para voce, consequentemente eles irao
     instalar o mesmo conjunto de aplicativos na sua maquina. Observe
     que voce podera produzir apenas documentos em HTML e ASCII se
     voce nao instalar o JadeTeX. Para produzir documentos em
     PostScript e PDF voce ira precisar do TeX.

     --------------------------------------------------------------

2.1 Ferramentas Obrigatorias

  2.1.1 Software

   Estes programas sao necessarios para voce trabalhar com a
   documentac,ao do FreeBSD, e permitirao a conversao da mesma para
   os formatos HTML, texto puro e RTF. Eles estao todos incluidos em
   textproc/docproj.

   Jade (textproc/jade)

           Uma implementac,ao DSSSL. Utilizado para a conversao 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
           facil de entende-los.

   Links (www/links)

           Um navegador WWW em modo texto que tambem converte
           arquivos HTML para texto puro.

   peps (graphics/peps)

           Parte da documentac,ao inclui imagens, algumas delas estao
           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 sao os conjuntos de DTDs e de entidades usados pelo FDP.
   Eles precisam estar instalados para que voce possa trabalhar com
   qualquer parte da documentac,ao.

   HTML DTD (textproc/html)

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

   DocBook DTD (textproc/docbook)

           DocBook e uma linguagem de marcas projetada para
           documentac,ao tecnica. Toda a documentac,ao do FreeBSD
           esta escrita em DocBook.

   ISO 8879 entities (textproc/iso8879)

           19 dos conjuntos de entidade de caracter ISO 8879:1986
           utilizados por muitos DTDs. Inclui simbolos matematicos
           nomeados, caracteres do conjunto de caracter Latin
           (acentos, diacriticos e assim por diante), e simbolos
           gregos.

     --------------------------------------------------------------

  2.1.3 Stylesheets

   As Stylesheets sao usadas na conversao e formatac,ao de documentos
   para serem apresentados na tela, impressos, e assim por diante.

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

           As Modular DocBook Stylesheets sao usadas na conversao da
           documentac,ao escrita em DocBook para outros formatos,
           tais como HTML ou RTF.

     --------------------------------------------------------------

2.2 Ferramentas Opcionais

   Voce nao precisa ter qualquer uma das ferramentas a seguir
   instaladas. Entretanto, voce podera achar mais facil trabalhar com
   a documentac,ao se elas estiverem disponiveis, elas tambem
   oferecem uma maior flexibilidade em relac,ao 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 sao usados para converter DocBook para os
           formatos DVI, Postscript, e PDF. As macros do JadeTeX sao
           necessarias para estas conversoes.

           Se voce nao pretende converter seus documentos para um
           destes formatos (i.e., HTML, texto puro, e RTF sao o
           suficiente) entao nao sera preciso instalar o JadeTeX e
           teTeX. Isto pode resultar em uma boa economia de tempo e
           espac,o em disco, ja que o teTeX possui tamanho de
           aproximadamente 30MB.

             Importante: Se voce decidir instalar o JadeTeX e teTeX
             entao sera preciso configurar o teTeX depois do JadeTeX
             ter sido instalado. O arquivo print/jadetex/pkg-message
             contem instruc,oes detalhadas sobre o que e preciso ser
             feito.

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

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

           Voce nao precisa utiliza-los, qualquer editor pode ser
           usado para editar documentos escritos com linguagem de
           marcas. Entretanto, se optar por usa-los voce podera
           constatar que eles tornam seu trabalho mais eficiente.

   Se alguem tiver sugestoes sobre algum outro software que seja util
   para a manipulac,ao de documentos SGML, por favor informe a Equipe
   de Engenharia de Documentac,ao <doceng@FreeBSD.org>, desta forma
   ele podera ser adicionado a esta lista.

     --------------------------------------------------------------

                         Capitulo 3 SGML Primer

   A maioria dos documentos do FDP e escrita utilizando SGML. Este
   capitulo ira explicar exatamente o que isso significa, como ler e
   compreender os fontes dos documentos e os truques de SGML que voce
   ira se defrontar na documentac,ao.

   Partes desta sec,ao foram inspiradas no documento   Comec,ando a
   utilizar o DocBook de autoria do Mark Galassi.

     --------------------------------------------------------------

3.1 Visao Geral

   Antigamente, era simples de se lidar com um texto eletronico.
   Naquela epoca, voce tinha que saber em qual conjunto de caracteres
   o seu documento havia sido escrito (ASCII, EBCDIC ou um dos
   inumeros outros), e mais nada. O texto era texto, e o que voce via
   era realmente o que voce tinha. Nenhuma frescura, nenhuma
   formatac,ao, nenhuma inteligencia.

   Inevitavelmente, isto nao era o suficiente. Uma vez que voce tem o
   texto em uma maquina num formato utilizavel, voce espera que o
   equipamento seja capaz de usa-lo e manipula-lo de forma
   inteligente. Voce pode desejar indicar que uma determinada frase
   deve ser enfatizada, ou adicionada a um glossario, ou ser
   interligada a outra parte do documento. Voce pode querer que os
   nomes dos arquivos sejam exibidos com uma fonte de estilo
   "typewriter" quando forem exibidos na tela, mas como "italico "
   quando impresso, ou qualquer outra opc,ao dentre a infinidade de
   opc,oes disponiveis para apresentac,ao.

   Esperava-se que a inteligencia artificial (AI) torna-se isso
   facil. 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 nao evoluiu como esperado, e os nossos computadores
   necessitam de algum auxilio antes que eles possam processar
   significativamente nosso texto.

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

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

 % rm /tmp/foo

   Nele podemos facilmente visualizar quais partes sao nomes de
   arquivos, quais sao comandos que devem ser digitados, quais partes
   sao referencias `as paginas de manual, etc. Mas o computador
   processando o documento nao pode. Para isto nos precisamos
   utilizar uma marcac,ao (markup).

   A "marcac,ao" e comumente utilizada para descrever a "adic,ao de
   valor" ou o "aumento de custo". O termo (term) faz exame de ambos
   os meios quando aplicados ao texto. A marcac,ao e um texto
   adicional incluido no documento, e de alguma forma destacado do
   seu conteudo, de modo que os programas que forem processa-lo
   possam ler as marcac,oes e utiliza-las ao tomar decisoes sobre o
   documento. Os editores podem ocultar a marcac,ao do usuario, de
   forma que o usuario nao se distraia com ele.

   As informac,oes extras armazenadas na marcac,ao adicionam valor ao
   documento. Tipicamente a adic,ao da marcac,ao ao documento precisa
   ser realizada por uma pessoa - apesar de tudo, se os computadores
   pudessem reconhecer suficientemente bem o texto para adicionar as
   marcac,oes, entao nao haveria necessidade de adiciona-las em
   primeiro lugar. Isto aumenta o custo (isto e, o esforc,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 voce pode ver, a marcac,ao esta claramente separada do
   conteudo.

   Obviamente, se voce estiver iniciando no uso de marcac,oes, voce
   precisa definir o que a sua marcac,ao significa, e como ela sera
   interpretada. Voce vai precisar de uma linguagem de marcac,ao a
   qual voce possa seguir quando estiver marcando os seus documentos.

   Naturalmente, uma linguagem de marcac,ao pode nao ser o bastante.
   Os requisitos de uma linguagem de marcac,ao destinada formatac,ao
   de documentos tecnicos sao diferentes dos requisitos de uma
   linguagem de marcac,ao destinada a formatac,ao de receitas
   culinarias. Esta, por sua vez, seria muito diferente de uma
   linguagem de marcac,ao usada para formatar poemas. O que voce
   realmente precisa e de uma linguagem primaria, a qual voce possa
   utilizar para escrever estas e outras linguagens de marcac,ao. Uma
   meta linguagem de marcac,ao.

   E exatamente isso que a Standard Generalized Markup Language
   (SGML) e. Muitas linguagens de marcac,ao foram escritas em SGML,
   incluindo as duas mais utilizadas pelo FDP, o HTML e o DocBook.

   Cada definic,ao de linguagem e mais corretamente chamada de
   Definic,ao de Tipo de Documento (DTD). O DTD especifica o nome dos
   elementos que podem ser utilizados, em qual ordem eles aparecem (e
   se alguma marcac,ao pode ser utilizada dentro de outra marcac,ao)
   e as informac,oes relacionadas. Um DTD e algumas vezes
   referenciado como uma aplicac,ao do SGML.

   Um DTD e uma especificac,ao completa de todos os elementos que
   podem ser utilizados, da ordem em que podem aparecer, quais
   elementos sao obrigatorios, quais sao opcionais, e assim por
   diante. Isto torna possivel escrever um interpretador (parser)
   SGML, que leia ambos os DTD e um documento que reividique se
   adequar ao DTD. O interpretador pode entao confirmar se todos os
   elementos obrigatorios do DTD estao (ou nao) presentes no
   documento na ordem correta, e se existem erros na marcac,ao. Isto
   e normalmente referenciado como "validac,ao do documento".

     Nota: Este processamento simplesmente confirma se a escolha dos
     elementos, a sua ordenac,ao, etc, estao de acordo com o
     especificado no DTD. Ele   nao verifica se voce utilizou a
     marcac,ao adequada para o conteudo. Se voce tentasse marcar
     todos os nomes de arquivo em seu documento como nomes de
     func,oes, o interpretador nao iria apontar isto como um erro
     (assumindo, naturalmente, que a sua DTD define elementos para
     nomes de arquivos e para func,oes, e que eles podem ser
     utilizados nos mesmos lugares).

   E provavel que a maioria das suas contribuic,oes ao projeto de
   documentac,ao irao se constituir de conteudos marcados tanto em
   HTML quanto em DocBook, em vez de alterac,oes nos DTDs. Por esta
   razao este livro nao ira abordar a criac,ao de um DTD.

     --------------------------------------------------------------

3.2 Elementos, tags, e atributos

   Todos os DTDs escritos em SGML compartilham certas
   caracteristicas. Isto e uma dura surpresa, como a filosofia por de
   tras do SGML nos mostrara ser completamente inevitavel. Uma das
   manifestac,oes mais obvias desta filosofia esta no conteudo e nos
   elementos.

   A sua documentac,ao (independente se e uma unica pagina web ou um
   livro longo) e composta de conteudo. Este conteudo e entao
   dividido (e de novo subdividido) em elementos. O proposito da
   adic,ao de marcac,oes e atribuir nome e identidade para os limites
   destes elementos de forma a possibilitar o processamento
   adicional.

   Por exemplo, considere um livro tipico. No nivel mais alto, o
   livro por si so e um elemento. Este elemento "livro" (book)
   obviamente contem capitulos, os quais tambem podem ser
   considerados elementos em sua propria forma. Cada capitulo ira
   conter mais elementos, tais como paragrafos, citac,oes, notas de
   rodape, etc. Cada paragrafo pode conter elementos adicionais,
   identificando o conteudo que era de discurso direto, ou o nome de
   um personagem da historia.

   Voce pode preferir pensar nisto como uma "quebra" do conteudo. No
   nivel mais alto voce tem um pedac,o, o Livro. Olhando um pouco
   mais abaixo, voce tem mais pedac,os, os capitulos individuais.
   Estes estao divididos em pedac,os ainda menores, os paragrafos,
   notas de rodape, nomes de personagens, etc.

   Observe que voce pode fazer esta diferenciac,ao entre os
   diferentes elementos do conteudo sem recorrer a nenhum termo SGML.
   Na realidade e surpreendentemente facil de usar. Voce pode fazer
   isso utilizando uma caneta de marcac,ao e uma copia impressa do
   livro, utilizando diferentes cores para indicar os diferentes
   pedac,os do conteudo.

   Naturalmente, nos nao possuimos uma caneta eletronica de
   marcac,ao, assim nos necessitamos de alguma outra maneira de
   indicar a que elemento cada pec,a de conteudo pertence. Nas
   linguagens escritas em SGML (HTML, DocBook, etc) isto e feito
   atraves do uso de tags.

   Uma tag e utilizada para identificar onde um elemento particular
   comec,a e onde ele termina. A tag nao e uma parte propria do
   elemento . Porque cada DTD foi normalmente escrito para marcar um
   tipo especifico de informac,ao, cada um deles reconhecera
   diferentes elementos, e tera nomes diferentes para cada tag.

   Para um elemento chamado element-name a tag de inicio normalmente
   ira 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 conteudo envolvido
   por este elemento e um paragrafo, chamado <p>. Este elemento
   possui ambas as tags de inicio e de fim.

 <p>Este e um paragrafo.  Ele inicia com a tag de inicio do
   elemento 'p', e ira terminar com a tag de fim para o
   elemento 'p'.</p>

 <p>Este e um outro paragrafo.  Mas este e muito menor.</p>

   Nem todos os elementos requerem uma tag de finalizac,ao. Alguns
   elementos nao possuem conteudo. Por exemplo, em HTML voce pode
   indicar que deseja que uma linha horizontal aparec,a no documento.
   Obviamente, esta linha nao possui conteudo, assim apenas a tag de
   inicio e requerida para este elemento.

   Exemplo 3-2. Utilizando um elemento (Apenas tag de inicio)

   O HTML possui um elemento para indicar uma linha horizontal,
   chamado <hr>. Este elemento nao contem nenhum conteudo, assim ele
   possui apenas uma tag de inicio.

 <p>Este e um paragrafo.</p>

 <hr>

 <p>Este e outro paragrafo.  Uma linha horizontal o separa do
   paragrafo anterior.</p>

   Se isto nao e obvio agora, os elementos podem conter outros
   elementos. No exemplo anterior do livro, o elemento livro continha
   todos os elementos capitulos, os quais por sua vez continham todos
   os elementos paragrafos, etc.

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

 <p>Este e um <em>paragrafo</em> simples no qual
   algumas das <em>palavras</em> foram <em>enfatizadas</em>.</p>

   O DTD ira 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
     intercambiaveis. Eles nao sao.

     Um elemento e uma parte conceitual do seu documento. Um elemento
     possui um inicio e fim determinados. As tags marcam onde os
     elementos comec,am e terminam.

     Quando este documento (ou qualquer pessoa que conhec,a SGML) se
     refere a "tag <p>" estamos nos referindo literalmente ao texto
     de tres caracteres <, p e >. Mas a frase "o elemento <p>" se
     refere ao elemento inteiro.

     Esta distinc,ao e muito sutil. Mas mantenha ela em mente

   Os elementos podem ter atributos. Um atributo possui um nome e um
   valor, e e utilizado para adicionar informac,oes extras ao
   elemento. Esta pode ser a informac,ao a qual indica como o
   conteudo deve ser renderizado, ou pode ser algo que identifique a
   ocorrencia unica do elemento, ou pode ser qualquer outra coisa.

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

   Nas versoes suficientemente recentes do HTML, o elemento <p>
   possui um atributo chamado <align>, o qual sugere o alinhamento
   (Justificac,ao) de um paragrafo para o programa que estiver
   exibindo o HTML.

   O atributo align pode assumir um de quatro valores possiveis, left
   (esquerda), center (centralizado), right (direita) e justify
   (justificado). Se o atributo nao for especificado sera assumido o
   valor padrao left.

   Exemplo 3-4. Utilizando um elemento com um atributo

 <p align="left">A inclusao de um atributo de alinhamento neste
   paragrafo foi superfluo, uma vez que o alinhamento
   padrao e left (esquerda).</p>

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

   Alguns atributos irao assumir apenas valores especificos, como o
   left ou justify. Outros irao permitir que voce entre com qualquer
   coisa que deseje. Se voce precisar incluir aspas (") no valor de
   um atributo, voce 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 voce nao precisa utilizar aspas em volta de todos os
   valores dos atributos. Entretanto, a regra para fazer isso e muito
   sutil, e e muito mais simples sempre utilizar as aspas em volta
   dos valores dos seus atributos.

   A informac,ao nos atributos, elementos e tags sao armazenados nos
   catalogos SGML. Varias ferramentas do projeto de documentac,ao
   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 documentac,ao do FreeBSD
   inclui seu proprio conjunto de arquivos de catalogos. Suas
   ferramentas precisam reconhecer ambos os tipos de arquivos de
   catalogo.

     --------------------------------------------------------------

  3.2.1 Para voce fazer...

   Para poder praticar com os exemplos deste documento voce precisara
   instalar alguns aplicativos no seu sistema, alem de assegurar que
   as variaveis de ambiente estejam corretamente configuradas.

    1. Fac,a o download e instale o textproc/docproj a partir do
       sistema de ports do FreeBSD. Ele e um meta-port o qual deve
       efetuar o download e a instalac,ao de todos os aplicativos e
       arquivos de suporte que sao utilizados pelo projeto de
       documentac,ao.

    2. Adicione linhas ao seu arquivo de inicializac,ao do shell para
       configurar a variavel de ambiente SGML_CATALOG_FILES. (Se voce
       nao estiver trabalhando com a versao no idioma ingles da
       documentac,ao, voce pode precisar substituir o caminho com o
       diretorio correto para o seu idioma.)

       Exemplo 3-6. .profile, para os usuarios 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 usuarios 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 variaveis, execute um logout do sistema,
       logando novamente em seguida, ou execute os comandos acima na
       sua linha de comando para configurar os valores das variaveis.

    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 e um paragrafo contendo algum texto.</p>

     <p>Este paragrafo contem mais algum texto.</p>

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

    2. Tente validar este arquivo utilizando um interpretador SGML.

       Um dos componentes do textproc/docproj e o onsgmls, um
       interpretador de validac,ao. Normalmente, o onsgmls le um
       documento marcado de acordo com um DTD SGML e retorna uma
       copia do conjunto de informac,oes sobre a estrutura dos
       elementos (ESIS, mas isso nao e importante agora).

       Entretanto, quando o onsgmls e executado com o parametro -s,
       ele ira suprimir o output normal, e imprimir apenas as
       mensagens de erro. Isto o torna um meio util de verificar se o
       seu documento e valido ou nao.

       Utilize o onsgmls para verificar se o seu documento e valido:

 % onsgmls -s example.xml

       Como voce ira ver, o onsgmls ira executar sem retornar nenhuma
       mensagem. Isto significa que o seu documento foi validado com
       sucesso.

    3. Veja o que acontece quando um elemento obrigatorio e omitido.
       Tente remover as tags <title> e </title> , e execute novamente
       a validac,ao.

 % 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 sao organizadas em
       grupos separados por dois pontos, ou colunas.

       Coluna                        Proposito                        
       1      O nome do programa que esta gerando o erro. Ela sera    
              sempre onsgmls.                                         
       2      O nome do arquivo que contem o erro.                    
       3      Numero da linha na qual o erro aparece.                 
       4      Numero da coluna na qual o erro aparece.                
              Um codigo de uma letra indicando a natureza da          
              mensagem. I indica uma mensagem informativa, W e para   
       5      um aviso, e E e para um erro [a], e X e para uma        
              referencia cruzada. Como voce pode ver, estas mensagens 
              sao erros.                                              
       6      O texto da mensagem.                                    
       Notas: 
       a. Ele nao esta sempre na quinta coluna. O onsgmls -sv exibe
       onsgmls:I: "OpenSP" version "1.5.2" (depende da versao
       instalada). Como voce pode ver, esta e uma mensagem
       informativa.

       A simples omissao das tags <title> gerou 2 erros diferentes.

       O primeiro erro indica que o conteudo (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
       inicio para os elementos que sao validos dentro do <head>
       (como a <title> ).

       O segundo erro e porque o elemento <head> deve conter o
       elemento <title>. Por causa disso o onsgmls considera que o
       elemento nao foi corretamente finalizado. Entretanto, a tag de
       finalizac,ao indica que o elemento foi fechado antes que
       estivesse terminado.

    4. Coloque de volta o elemento <title>.

     --------------------------------------------------------------

3.3 A declarac,ao DOCTYPE

   O inicio de cada documento que voce 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 informac,ao e geralmente expressada em uma linha, na
   declarac,ao DOCTYPE.

   Uma declarac,ao tipica para um documento escrito para conformar-se
   com a versao 4.0 do DTD HTML se parece com esta:

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

   Esta linha contem diferentes componentes.

   <!

           E o indicador que indica que se trata de uma declarac,ao
           SGML. Esta linha esta declarando o tipo do documento.

   DOCTYPE

           Mostra que esta e uma declarac,ao SGML para o tipo de
           documento.

   html

           O nome do primeiro elemento o qual ira aparecer no
           documento

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

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

           O PUBLIC nao 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 serao abordadas mais tarde .

   >

           Retorno ao documento.

     --------------------------------------------------------------

  3.3.1 Identificadores publicos formais (FPIs)

     Nota: Voce nao precisa conhece-los, mas eles sao um background
     util, e podem ajuda-lo a depurar problemas quando o seu
     processador SGML nao puder localizar o DTD que voce esta
     utilizando.

   Os FPIs devem seguir uma sintaxe especifica. Esta sintaxe e a
   seguinte:

 "Proprietario//Palavra-Chave Descric,ao//Idioma"

   Proprietario

           Isto indica o proprietario da FPI.

           Se este conjunto de caracteres comec,ar com "ISO"
           significara que o FPI e de propriedade do ISO. Por
           exemplo, a FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN"
           lista o ISO 8879:1986 como sendo o proprietario do
           conjunto de entidades dos simbolos Gregos. O ISO 8879:1986
           e o numero da ISO para o padrao SGML.

           De outra forma, este conjunto de caracteres ira se parecer
           com -//  Proprietario ou +//Proprietario (Observe que a
           unica diferenc,a e a introduc,ao do + ou do -).

           Se o conjunto de caracteres comec,ar com - significa que o
           proprietario da informac,ao nao e registrado, se comec,ar
           com um + significa que ele e registrado.

           O ISO 9070:1991 define como os nomes registrados sao
           gerados; ele pode ser derivado do numero de uma
           publicac,ao ISO, de um codigo ISBN, ou um codigo de
           organizac,ao atribuido de acordo com o ISO 6523. Alem
           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 nao foi registrado o conjunto de
           caracteres de proprietario e -//FreeBSD. E como voce pode
           ver, o W3C tambem nao e um proprietario registrado.

   Palavra-Chave

           Existem diversas palavras-chave as quais indicam o tipo de
           informac,ao no arquivo. Algumas das palavras chaves mais
           comuns sao DTD, ELEMENT, ENTITIES, e TEXT. A palavra chave
           DTD e utilizada apenas para os arquivos DTD, a ELEMENT e
           normalmente utilizada para fragmentos DTD os quais
           contenham apenas entidades e declarac,oes de elementos. A
           palavra TEXT e utilizada para o conteudo SGML (texto e
           tags).

   Descricao

           Qualquer descric,ao que voce deseje fornecer para o
           conteudo deste arquivo. O que pode incluir um numero de
           versao ou qualquer texto curto o qual seja significativo
           para voce e unico para o sistema SGML.

   Idioma

           Este e um codigo ISO de duas letras o qual identifica o
           idioma nativo do arquivo. O codigo EN e utilizado para o
           idioma ingles.

     --------------------------------------------------------------

    3.3.1.1 Arquivos de catalogo

   Se voce utilizar a sintaxe acima e processar este documento
   utilizando um processador SGML, o processador ira precisar de uma
   forma de associar a FPI ao nome do arquivo no seu computador o
   qual contem o DTD.

   Para isto devemos utilizar um arquivo de catalogo. Um arquivo de
   catalogo (tipicamente chamado de catalog) contem linhas as quais
   mapeiam FPIs para nomes de arquivos. Por exemplo, se o arquivo de
   catalogo 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 subdiretorio 4.0 de qualquer diretorio que possuisse
   um arquivo catalog contendo esta linha.

   Veja o conteudo do /usr/local/share/xml/html/catalog. Este e o
   arquivo de catalogo para o DTD HTML o qual sera instalado como
   parte do port textproc/docproj.

     --------------------------------------------------------------

    3.3.1.2 SGML_CATALOG_FILES

   A fim de encontrar um arquivo de catalogo, o seu processador SGML
   precisara saber onde procurar. Muitos deles possuem recursos de
   parametros de linha de comando para especificar o caminho para um
   ou mais catalogos.

   Adicionalmente, voce pode definir a variavel de ambiente
   SGML_CATALOG_FILES para apontar para os arquivos. Esta variavel
   deve consistir de uma lista, separada por dois pontos (":"), de
   arquivos de catalogo (incluindo seus caminhos completos).

   Tipicamente, voce precisara 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

   Voce ja deve ter feito isto.

     --------------------------------------------------------------

  3.3.2 Alternativas aos FPIs

   Ao inves de utilizar um FPI para indicar o DTD ao qual o documento
   conforma-se (e consequentemente, quais arquivos no sistema contem
   o DTD), voce pode especificar explicitamente o nome do arquivo.

   A sintaxe para isto e 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 especifico do sistema. Isto
   tipicamente (mas nao sempre) significa que o DTD sera fornecido
   como um nome de arquivo.

   O uso de FPIs e preferido por razoes de portabilidade. Voce pode
   nao desejar ter que enviar uma copia do DTD junto com seu
   documento, e se voce utilizasse um identificador SYSTEM todos
   necessitariam manter os seus DTDs no mesmo lugar que voce.

     --------------------------------------------------------------

3.4 Voltando para o SGML

   Como mencionado anteriormente, o SGML e utilizado somente quando
   escrevemos um DTD. Isto nao e estritamente verdade. Existem certas
   sintaxes SGML as quais voce podera desejar utilizar com os seus
   documentos. Por exemplo, voce pode incluir comentarios no seu
   documento, e eles serao ignorados pelo interpretador. Os
   comentarios sao adicionados utilizando sintaxe SGML. Outros usos
   para a sintaxe SGML no seu documento serao mostrados mais tarde.

   Obviamente, voce precisa indicar de alguma forma ao processador
   SGML que o conteudo seguinte nao se trata de elementos do
   documento, mas sim de SGML sobre o qual o interpretador deve
   atuar.

   Estas sessoes sao marcadas no seu documento com <! ... >. Tudo
   entre estes delimitadores e sintaxe SGML tal como voce pode
   encontrar dentro de um DTD.

   Como voce pode perceber, a   declarac,ao DOCTYPE e um exemplo de
   sintaxe SGML a qual voce precisa incluir no seu documento.

     --------------------------------------------------------------

3.5 Comentarios

   Comentarios sao uma construc,ao SGML, e sao normalmente validos
   apenas dentro de um DTD. Entretanto, como mostrou a Sec,ao 3.4, e
   possivel utilizar sintaxe SGML com os seus documentos.

   O delimitador para um comentario SGML e o conjunto de caracteres
   "--". A primeira ocorrencia deste conjunto de caracteres abre um
   comentario e a segunda fecha.

   Exemplo 3-8. Comentario SGML generico

 <!-- Teste de comentario -->

 <!-- Este e o interior do comentario -->

 <!-- Este e outro comentario    -->

 <!-- Esta e uma forma
      de fazer comentarios de varias linhas -->

 <!-- Esta e outra forma  --
   -- de fazer comentarios de varias linhas -->

   Se voce ja utilizou HTML antes, voce pode ter sido exposto a
   regras diferentes para comentarios. Em particular, voce pode
   pensar que o conjunto de caracteres <!-- abre um comentario e que
   ele apenas e fechado por um -->.

   Este nao e o caso. Muitos dos navegadores web possuem
   interpretadores HTML quebrados, e irao aceitar isso como valido.
   Entretanto, os interpretadores SGML utilizados pelo projeto de
   documentac,ao sao muito mais rigidos, e irao rejeitar os
   documentos que contiverem este erro.

   Exemplo 3-9. Comentarios SGML errados

 <!-- Este e o comentario --

      Isto esta fora do comentario!

   -- de volta para dentro do comentario -->

   O interpretador SGML ira tratar isto como ele e realmente;

 <!Isto esta fora do comentario>

   Isto nao e um SGML valido, e pode dar mensagens de erro confusas.

 <!--------------- Isto e uma ideia muito ruim --------------->

   E como o exemplo sugere, nao escreva comentarios como esse.

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

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

     --------------------------------------------------------------

  3.5.1 Para voce fazer...

    1. Adicione alguns comentarios ao arquivo example.xml e verifique
       se ele continua valido usando o onsgmls.

    2. Adicione alguns comentarios invalidos ao example.xml e veja as
       mensagens de erro que o onsgmls emite quando encontra um
       comentario invalido.

     --------------------------------------------------------------

3.6 Entidades

   Entidades sao um mecanismo para atribuir nomes para pedac,os de
   conteudo. Quando o interpretador SGML processar o seu documento,
   qualquer entidade que ele encontrar sera substituida pelo conteudo
   da entidade.

   Esta e uma boa forma de ter pedac,os de conteudo reutilizaveis e
   facilmente alteraveis em seus documentos SGML. Esta e tambem a
   unica forma de incluir um arquivo marcado dentro de outro
   utilizando SGML.

   Existem dois tipos de entidades que podem ser utilizadas em duas
   situac,oes diferentes; Entidades gerais e Entidades de parametros.

     --------------------------------------------------------------

  3.6.1 Entidades gerais

   Voce nao pode utilizar uma entidade geral em um contexto SGML
   (embora voce as defina em um). Elas podem ser utilizadas apenas no
   seu documento. Compare isto com as   entidades de parametros.

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

 <para>A versao atual do nosso produto e &current.version;.</para>

   Quando o numero de versao mudar, voce pode simplesmente alterar a
   definic,ao do valor da entidade geral e reprocessar o seu
   documento.

   Voce tambem pode utilizar entidades gerais para incorporar
   caracteres que voce nao poderia incorporar de outra forma em um
   documento SGML. Por exemplo, os caracteres < e & nao podem
   aparecer normalmente em um documento SGML. Quando o interpretador
   SGML ve o simbolo < ele assume que aquilo e uma tag (uma tag de
   abertura ou de fechamento) que esta a ponto de aparecer, e quando
   ele ve o simbolo & ele assume que o proximo texto sera o nome de
   uma entidade.

   Felizmente, voce pode utilizar as duas entidades gerais &lt; e
   &amp; sempre que voce precisar inclui-los.

   Uma entidade geral so pode ser definida dentro de um contexto
   SGML. Tipicamente, isto e feito imediatamente depois da
   declarac,ao 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 declarac,ao DOCTYPE foi estendida adicionando-se um
   colchete no final da primeira linha. As duas entidades estao
   definidas nas proximas duas linhas, antes que o colchete seja
   fechado, e entao a declarac,ao DOTYPE e fechada.

   O colchete e necessario para indicar que nos estamos extendendo o
   DTD indicado pela declarac,ao DOCTYPE.

     --------------------------------------------------------------

  3.6.2 Entidades de parametro

   Assim como as entidades gerais , as entidades de parametro sao
   utilizadas para atribuir um nome a pedac,os reutilizaveis de
   texto. Entretanto, enquanto as entidades gerais so podem ser
   utilizadas com o seu documento, as entidades de parametro podem
   ser utilizadas apenas dentro de um contexto SGML.

   As entidades de parametro sao definidas de uma forma similar as
   entidades gerais. Entretanto, ao inves de utilizar
   &nome-da-entidade; como referencia, utiliza %nome-da-entidade;
   [1]. A definic,ao tambem inclui o % entre a palavra chave ENTITY e
   o nome da entidade.

   Exemplo 3-11. Definindo entidades de parametros

 <!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 contem "some more text" -->
 ]>

   Isto pode nao parecer particularmente util. Mas ele sera.

     --------------------------------------------------------------

  3.6.3 Para voce 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>

   <!-- Voce pode ter alguns comentarios aqui tambem -->
          
   <body>           
     <p>Este e um paragrafo contendo algum texto.</p>

     <p>Este paragrafo contem mais algum texto.</p>

     <p align="right">Este paragrafo pode estar alinhado a direita.</p>

     <p>A versao atual deste documento e: &version;</p>   
   </body>          
 </html>

    2. Valide o documento utilizando o onsgmls

    3. Carregue o arquivo example.xml no seu navegador web (Voce pode
       precisar copia-lo para example.html antes que o seu navegador
       possa reconhece-lo como um documento HTML).

       A menos que o seu navegador seja muito avanc,ado, voce nao ira
       ver a entidade referenciada por &version; substituida pelo
       numero de versao. A maioria dos navegadores web possuem
       interpretadores muito simplistas os quais nao manuseiam
       corretamente SGML [2].

    4. A soluc,ao e normalizar seu documento utilizando um
       normalizador SGML. Um normalizador le um SGML valido e retorna
       um SGML igualmente valido o qual foi transformado de alguma
       forma. Uma das formas em que o normalizador transforma o SGML
       e expandindo todas as entidades referenciadas no documento,
       substituindo as entidades pelo texto que elas representam.

       Voce pode utilizar o osgmlnorm para fazer isto:

 % osgmlnorm example.xml > example.html

       Voce deve encontrar uma copia normalizada (isto e, entidades
       referenciadas expandidas) do seu documento no arquivo
       example.html, pronta para ser carregada no seu navegador web.

    5. Se voce examinar o retorno do osgmlnorm voce ira ver que ele
       nao inclui a declarac,ao DOCTYPE no inicio. Para inclui-la
       voce precisa utilizar a opc,ao -d:

 % osgmlnorm -d example.xml > example.html

     --------------------------------------------------------------

3.7 Utilizando entidades para incluir arquivos

   As entidades (ambas gerais e de parametros) sao particularmente
   uteis quando utilizadas para incluir um arquivo dentro de outro.

     --------------------------------------------------------------

  3.7.1 Utilizando entidades gerais para incluir arquivos

   Suponha que voce possui algum conteudo para um livro SGML
   organizado em arquivos, um arquivo por capitulo, chamados
   chapter1.xml, chapter2.xml, e assim por diante, com um arquivo
   book.xml que ira conter estes capitulos.

   A fim de utilizar o conteudo destes arquivos como os valores para
   as suas entidades, voce as declara com a palavra chave SYSTEM.
   Isto direciona o interpretador SGML para utilizar o conteudo 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 capitulos -->

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

     Atenc,ao: Quando utilizar uma entidade geral para incluir outros
     arquivos em um documento, os arquivos que estiverem sendo
     inclusos (chapter1.xml, chapter2.xml, etc) nao devem iniciar com
     uma declarac,ao DOCTYPE. Isto e um erro de sintaxe.

     --------------------------------------------------------------

  3.7.2 Utilizando entidades de parametro para incluir arquivos

   Recorde-se que uma entidade de parametro so pode ser utilizada
   dentro de um contexto SGML. Por que entao voce desejaria incluir
   um arquivo dentro de um contexto do SGML?

   Voce pode utilizar isto para assegurar-se de que voce pode
   reutilizar as suas entidades gerais.

   Suponha que voce possui muitos capitulos em seu documento, e voce
   reutiliza estes capitulos em dois livros diferentes, cada livro
   organizando os capitulos de uma forma diferente.

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

   Em vez de disso, coloque as definic,oes das suas entidades gerais
   em um arquivo, e utilize uma entidade de parametro para incluir
   este arquivo dentro do seu documento.

   Exemplo 3-13. Utilizando entidades de parametro para incluir
   arquivos.

   Primeiro, coloque as suas definic,oes de entidades em um arquivo
   separado, chamado chapters.ent. Este arquivo contem 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 parametro para referenciar o conteudo
   do arquivo. E entao utilize a entidade de parametro para carregar
   o arquivo no seu documento, o que tornara todas as entidades
   gerais disponiveis para uso. Feito isso, utilize as entidades
   gerais como antes;

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

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

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

     --------------------------------------------------------------

  3.7.3 Para voce fazer...

    3.7.3.1 Utilizando entidades gerais para incluir arquivos

    1. Crie tres arquivos, para1.xml, para2.xml, e para3.xml.

       Coloque um conteudo similar ao seguinte em cada arquivo:

 <p>Este e o primeiro paragrafo.</p>

    2. Edite o arquivo example.xml para que ele se parec,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 versao atual deste documento e: &version;</p>

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

    3. Produza o arquivo example.html atraves da normalizac,ao 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 paran.xml foram incluidos no
       example.html.

     --------------------------------------------------------------

    3.7.3.2 Utilizando uma entidade de parametro para incluir arquivos.

     Nota: Voce deve ter executado os passos anteriores primeiro.

    1. Edite o arquivo example.xml para que ele se parec,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 versao atual deste documento e: &version;</p>

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

    2. Crie um novo arquivo chamado entities.xml, com este conteudo:

 <!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 atraves da normalizac,ao 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 paran.xml foram incluidos no arquivo
       example.html.

     --------------------------------------------------------------

3.8 Sessoes marcadas

   O SGML fornece um mecanismo para indicar que uma parte particular
   do documento deve ser processada de uma forma especial. Estas
   partes sao denominadas "sessoes marcadas".

   Exemplo 3-14. Estrutura de uma sessao marcada

 <![ Palavra-chave [
   Conteudo da sessao marcada
 ]]>

   Como voce esperaria, sendo uma construc,ao SGML, uma sessao
   marcada inicia com um <!.

   O primeiro colchete comec,a a limitar a sessao marcada.

   A Palavra-chave descreve como esta sessao marcada deve ser
   processada pelo interpretador.

   O segundo colchete indica que o conteudo da sessao marcada inicia
   aqui.

   A sessao marcada e finalizada pelo fechamento dos dois colchetes e
   entao retornando ao contexto do documento a partir do contexto
   SGML com o >.

     --------------------------------------------------------------

  3.8.1 Palavras-Chave de sessoes marcadas

    3.8.1.1 CDATA, RCDATA

   Estas palavras chave denotam o modelo do conteudo das sessoes
   marcadas, e permitem que voce o altere a partir do padrao.

   Quando um interpretador SGML esta processando um documento ele
   tenta seguir o que chamamos de "modelo de conteudo"

   Resumidamente, o modelo de conteudo descreve que tipo de conteudo
   o interpretador esta esperando encontrar, e o que fara com ele
   quando o encontrar.

   Os dois modelos de conteudo que voce provavelmente ira achar mais
   uteis sao o CDATA e o RCDATA.

   O CDATA e para "Dados de Caracter". Se o interpretador esta neste
   modelo de conteudo entao ele esta esperando encontrar caracteres,
   e apenas caracteres. Neste modelo os simbolos < e o & perdem o seu
   status especial, e serao tratados como caracteres ordinarios.

   O RCDATA e para "Referencias de entidade e dados de caracter ". Se
   o interpretador esta neste modelo de conteudo ele esta esperando
   encontrar caracteres e entidades. O simbolo < perde o seu status
   especial, mas o & continuara sendo tratado como o inicio de uma
   entidade geral.

   Isto e particularmente util se voce esta incluindo algum texto
   literal o qual contem muitos caracteres < e &. Ao inves de
   atravessar o texto todo tendo que verificar se todos os < estao
   convertidos para um &lt; e todos os & estao convertidos para um
   &amp; pode ser mais simples marcar a sessao como contendo apenas
   CDATA. Quando o interpretador SGML encontra-los ele ira ignorar os
   simbolos < e & embutidos no conteudo.

     Nota: Quando voce utiliza CDATA ou RCDATA nos exemplos de texto
     marcado em SGML, tenha em mente que o conteudo do CDATA nao e
     validado. Voce tem que verificar o SGML incluso no texto
     utilizando algum outro meio. Voce pode, por exemplo, escrever o
     exemplo em outro documento, validar o codigo de exemplo, e entao
     cola-lo para o seu conteudo CDATA.

   Exemplo 3-15. Utilizando uma sessao marcada como CDATA

 <para>Aqui esta um exemplo de como voce incluiria algum texto que contenha muitos
   simbolos <literal>&lt;</literal> e <literal>&amp;</literal>. 
   O texto de exemplo e um fragmento de HTML. 
   O texto circunvizinho (<para> e <programlisting>) e do
   DocBook.</para>
          
 <programlisting>
   <![ CDATA [ 
     <p>Esta e uma amostra que apresenta alguns elementos de HTML.
        Uma vez que os simbolos de < e > sao utilizados muitas vezes, e
        mais facil dizer que o exemplo todo e uma sessao marcada do
        tipo CDATA, do que utilizar nomes de entidades para representar
        estes simbolos ao longo de todo o texto.</p>

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

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

   Se voce examinar o fonte deste documento voce ira ver que esta
   tecnica foi utilizada por toda parte.

     --------------------------------------------------------------

    3.8.1.2 INCLUDE and IGNORE

   Se a palavra chave for INCLUDE entao o conteudo da sessao marcada
   sera processado. Se a palavra chave for IGNORE entao a sessao
   marcada sera ignorada e nao sera processada. Ela nao ira aparecer
   no output.

   Exemplo 3-16. Utilizando INCLUDE e IGNORE nas sessoes marcadas

 <![ INCLUDE [
   Este texto sera processado e incluido.
 ]]>

 <![ IGNORE [
   Este texto nao sera processado nem incluido.
 ]]>

   Por si so, isto nao e muito util. Se voce desejar remover o texto
   do seu documento voce pode corta-lo fora, ou comenta-lo.

   Torna-se mais util quando voce utilizar entidades de parametro
   para controla-lo. Lembre-se que entidades de parametro so podem
   ser utilizadas em um contexto SGML, e que a palavra chave de uma
   sessao marcada e um contexto SGML.

   Por exemplo, suponha que voce produza uma copia impressa e uma
   versao eletronica de alguma documentac,ao. Voce pode desejar
   incluir na versao eletronica algum conteudo extra, o qual nao deve
   aparecer na versao impressa.

   Crie uma entidade de parametro, e configure seu valor para
   INCLUDE. Escreva seu documento, usando uma sessao marcada para
   delimitar o conteudo que deve aparecer apenas na versao
   eletronica. Nesta sessao marcada utilize a entidade de parametro
   no lugar da palavra chave.

   Quando voce desejar produzir uma copia impressa do documento,
   altere o valor da entidade de parametro para IGNORE e reprocesse o
   documento.

   Exemplo 3-17. Utilizando uma entidade de parametro para controlar
   uma sessao marcada

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

 ...

 <![ %electronic.copy [
   Este conteudo deve aparecer apenas na versao eletronica do
   documento.
 ]]>

   Quando for produzir uma versao impressa do documento, altere a
   definic,ao da entidade para;

 <!ENTITY % electronic.copy "IGNORE">

   Ao reprocessar o documento, a sessao marcada que utilizar a
   entidade %electronic.copy como a sua palavra chave sera ignorada.

     --------------------------------------------------------------

  3.8.2 Para voce fazer...

    1. Crie um novo arquivo chamado section.xml, o qual deve conter o
       seguinte conteudo:

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

 <html>
   <head>
     <title>Um exemplo utilizando uma sessao marcada.</title>
   </head>

   <body>           
     <p>Este paragrafo <![ CDATA [contem muitos caracteres <
       (< < < < <) de forma que e mais simples utilizar
       uma sessao marcada do tipo CDATA.]]></p>

     <![ IGNORE [
     <p>Este paragrafo definitivamente nao sera incluido
       no output.</p>
     ]]>

     <![ %text.output [
     <p>Este paragrafo pode ou nao aparecer no output.</p>

     <p>A sua ocorrencia e controlada pela entidade de parametro %text.output
       .</p>        
     ]]>
   </body>
 </html>

    2. Normalize este arquivo utilizando o osgmlnorm e examine o
       resultado. Observe quais paragrafos apareceram, quais
       desapareceram e o que aconteceu com o conteudo da sessao
       marcada como CDATA.

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

     --------------------------------------------------------------

3.9 Conclusao

   Esta e a conclusao da introduc,ao ao SGML. Devido a restric,oes de
   espac,o e complexidade, diversos assuntos nao foram abordados em
   profundidade (ou sequer foram abordados). Entretanto, as sessoes
   previas cobriram o suficiente do SGML para que voce possa seguir a
   organizac,ao da documentac,ao do FDP.

     --------------------------------------------------------------

                       Capitulo 4 Marcac,ao SGML

   Esse capitulo descreve as duas linguagens de marcac,ao que voce
   vai encontrar quando for contribuir para o projeto de
   documentac,ao do FreeBSD. Cada sec,ao descreve a linguagem de
   marcac,ao, e detalha a marcac,ao que voce provavelmente vai querer
   usar ou que ja esta utilizando.

   Estas linguagens de marcac,ao contem um grande numero de
   elementos, e as vezes pode ser confuso escolher qual elemento usar
   em uma situac,ao especifica. Esta sec,ao apresenta os elementos
   que provavelmente voce vai precisar e fornece exemplos de como
   utiliza-los.

   Esta nao e uma lista detalhada de elementos, uma vez que ela
   apenas ratifica a documentac,ao de cada linguagem. O objetivo
   desta sec,ao e listar os elementos mais uteis para voce. Se voce
   tiver alguma duvida sobre qual a melhor forma de marcar um pedac,o
   especifico do seu documento, por favor, envie a sua duvida para a
   lista de discussao do projeto de documentac,ao do FreeBSD.

     Inline Versus Block: No restante deste documento, quando
     descrevermos um elemento como inline significara que o elemento
     pode ocorrer dentro de um bloco de elementos, que ele nao
     acarretara em uma quebra de linha. Um elemento block, por
     comparac,ao, ira causar uma quebra de linha (e outros
     processamentos) quando for encontrado.

     --------------------------------------------------------------

4.1 HTML

   O HTML, Linguagem de Marcac,ao de Hypertexto, e a linguagem de
   marcac,ao escolhida para a World Wide Web. Maiores informac,oes
   podem ser encontradas em http://www.w3.org/.

   O HTML e utilizado para a marcac,ao das paginas do web site do
   FreeBSD. Ele nao deveria ser utilizado (geralmente) para marcar
   outros tipos de documentos ja que o DocBook oferece uma maior
   variedade de elementos. Consequentemente, voce so ira encontrar
   paginas em HTML se estiver escrevendo para o web site.

   O HTML ja passou por algumas versoes, 1, 2, 3.0, 3.2 e a ultima,
   4.0 (disponivel nas duas variantes, strict e loose).

   Os HTML DTD's estao disponiveis na colec,ao de ports na pasta
   textproc/html. Eles sao automaticamente instalados como parte do
   port textproc/docproj

     --------------------------------------------------------------

  4.1.1 Identificador Publico Formal (IPF)

   Existem varios IPF's para o HTML, os quais dependem da versao
   (tambem conhecida como nivel) do HTML que voce quer declarar
   compativel com seu documento.

   A maioria dos documentos HTML no web site do FreeBSD estao de
   acordo com a versao loose do HTML 4.0.

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

     --------------------------------------------------------------

  4.1.2 Elementos de Sec,ao

   Um documento HTML e normalmente dividido em duas partes. A
   primeira e chamada de head, a qual contem meta-informac,oes sobre
   o documento, tais como o seu titulo, o nome do autor, o documento
   pai e assim por diante. A segunda parte, o body e contem o
   conteudo que vai ser exibido para o usuario.

   Estas sec,oes sao indicadas pelos elementos <head> e <body>,
   respectivamente. Esses elementos estao contidos dentro de um
   elemento <html> de alto-nivel.

   Exemplo 4-1. Estrutura Normal de um Documento HTML

 <html>
   <head>
           <title>Titulo do Documento</title>
   </head>

   <body>

     ...

   </body>
 </html>

     --------------------------------------------------------------

  4.1.3 Bloco de Elementos

    4.1.3.1 Cabec,alho

   O HTML permite a denotac,ao de cabec,alho em seu documento, de ate
   seis niveis diferentes.

   O maior e mais proeminente cabec,alho e o <h1>, depois vem o <h2>,
   assim por diante ate <h6>.

   O conteudo dos elementos e o texto do cabec,alho.

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

   Uso:

 <h1>Primeira sec,ao</h1>

 <!-- a introduc,ao do documento entra aqui -->

 <h2>Este e o cabec,alho da primeira sec,ao</h2>

 <!-- O conteudo da primeira sec,ao entra aqui -->

 <h3>Este e o cabec,alho da primeira subsec,ao</h3>

 <!-- O conteudo da primeira subsec,ao entra aqui -->

 <h2>Este e o heading para a segunda sec,ao</h2>

 <!-- O conteudo da segunda sec,ao entra aqui -->

   Geralmente, uma pagina HTML deveria ter um cabec,alho de primeiro
   nivel (<h1>). Este poderia conter muitos cabec,alhos de segundo
   nivel (<h2>), os quais por sua vez podem conter muitos cabec,alhos
   de terceiro nivel. Cada elemento <hn> deve ter o mesmo elemento,
   sendo que os elementos mais acima na hierarquia estarao subtraidos
   de um. Deve-se evitar buracos na numerac,ao.

   Exemplo 4-3. Ma organizac,ao de elementos <hn>

   Uso:

 <h1>Primeira sec,ao</h1>

 <!-- Introduc,ao do documento -->

 <h3>Subsec,ao</h3>

 <!-- Isto e ruim, nao foi usado <h2> -->

     --------------------------------------------------------------

    4.1.3.2 Paragrafos

   O HTML suporta elementos formados de um unico paragrafo <p>.

   Exemplo 4-4. <p>

   Uso:

 <p>Isto e um paragrafo.  Pode conter qualquer outro elemento</p>

     --------------------------------------------------------------

    4.1.3.3 Bloco de Citac,ao

   Um bloco de citac,ao e uma citac,ao estendida de outro documento
   que nao deveria aparecer no paragrafo atual.

   Exemplo 4-5. <blockquote>

   Uso:

 <p>Um pequeno trecho da constituic,ao dos Estados Unidos:</p>

 <blockquote>
 Nos, povo dos Estados Unidos, com o objetivo de fazer uma
 uniao mais perfeita, estabelecer justic,a, garantir
 tranquilidade domestica, promover uma defesa comum, promover
 bem estar geral, assegurar as benc,oes da liberdade para
 nos mesmos e nossa posteridade, organizamos e estabelecemos
 essa constituic,ao para os estados Unidos da America.
 </blockquote>

     --------------------------------------------------------------

    4.1.3.4 Listas

   Voce pode apresentar ao usuario tres tipos de listas, ordenadas,
   desordenadas e de definic,ao.

   Tipicamente, cada entrada em uma lista ordenada, e numerada
   enquanto nas listas desordenadas serao processadas por um bullet
   point. Listas de definic,ao sao compostas de duas partes para cada
   entrada a primeira e o termo a ser definido, e a segunda, e a
   definic,ao em si.

   As Listas ordenadas, desordenadas e de definic,ao, sao indicadas
   pelos elementos <ol>, <ul> e <dl>, respectivamente.

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

   Listas de definic,ao contem o termo a ser definido (<dt>) e a
   descric,ao do termo (<dd>). A definic,ao de um termo so pode
   conter elementos inline. A descric,ao do termo pode conter
   elementos do tipo block.

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

   Uso:

 <p>Uma lista nao ordenada.  Os itens serao provavelmente
 precedidos por uma esfera solida.</p>

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

   <li>Segundo item</li>

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

 <p>Uma lista ordenada, com itens de lista com varios
 paragrafos.  Cada item (nota: nao cada paragrafo)
 sera numerado.</p>

 <ol>
   <li><p>Este e o primeiro item.  Tem apenas um paragrafo.</p></li>

   <li><p>Este e o primeiro paragrafo do segundo item.</p>

     <p>Este e o segundo paragrafo do segundo item.</p></li>

   <li><p>Este e o primeiro e unico paragrafo do terceiro item.</p></li>
 </ol>

   Exemplo 4-7. Listas de Definic,ao com <dl>

   Uso:

 <dl>
   <dt>Termo 1</dt>

   <dd><p>Paragrafo 1 da definic,ao 1.</p>

     <p>Paragrafo 2 da definic,ao 1.</p></dd>

   <dt>Termo 2</dt>

   <dd><p>Paragrafo 1 da definic,ao 2.</p></dd>

   <dt>Termo 3</dt>

   <dd><p>Paragrafo 1 da definic,ao 3.</p></dd>
 </dl>

     --------------------------------------------------------------

    4.1.3.5 Texto Pre-Formatado

   Voce pode indicar que o texto deve ser apresentado exatamente como
   esta no arquivo. Tipicamente, isto significa que o texto sera
   mostrado em fonte fixa, multiplos espac,os nao serao fundidos em
   um e que as quebras de linha no texto serao significativas.

   Para fazer isto, envolva o conteudo com o elemento <pre>:

   Exemplo 4-8. <pre>

   Voce 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 pre-formatado. E por isto que nos
   exemplos tivemos que utilizar &lt; ao inves de <. Para manter a
   consistencia, o &gt; tambem foi utilizado no lugar do >. Fique
   atento para caracteres especiais que podem aparecer em textos
   copiados de origens nao formatadas, como por exemplo, de uma
   mensagem de email ou do codigo fonte de um programa.

     --------------------------------------------------------------

    4.1.3.6 Tabelas

     Nota: A maioria dos navegadores de modo texto (tal como o Lynx)
     nao apresentam tabelas de maneira muito eficiente. Se voce
     quiser que o seu conteudo seja apresentado em forma de tabelas,
     voce deve considerar outra marcac,ao para evitar problemas.

   Marque a informac,ao tabular com o elemento <table>. Uma tabela
   consiste de uma ou mais linhas (<tr>), cada uma contendo uma ou
   mais celulas de dados (<td>). As celulas podem conter outros
   elementos de bloco, como paragrafos ou listas. Tambem pode conter
   outra tabela (este aninhamento pode ser repetido indefinidamente).
   Se a celula contem apenas um paragrafo, entao nao e necessario
   incluir o elemento <p>.

   Exemplo 4-9. Uso Simples de <table>

   Uso:

 <p>Esta e uma simples tabela 2x2.</p>

 <table>
   <tr>
     <td>Celula esquerda superior</td>

     <td>Celula direita superior</td>
   </tr>

   <tr>
     <td>Celula esquerda inferior</td>

     <td>Celula direita inferior</td>
   </tr>
 </table>

   Uma celula pode se estender por muitas linhas e colunas. Para
   indicar isto, coloque o atributo rowspan e/ou colspan, com valores
   que indiquem o numero de linhas ou colunas a serem ocupados.

   Exemplo 4-10. Utiliizando rowspan

   Uso:

 <p>Uma celula comprida e estreita na esquerda e duas
 celulas pequenas `a direita.</p>

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

   <tr>
     <td>Celula superior</td>

     <td>Celula inferior</td>
   </tr>
 </table>

   Exemplo 4-11. Usando colspan

   Uso:

 <p>Uma celula longa em cima, duas celulas abaixo.</p>

 <table>
   <tr>
     <td colspan="2">Celula superior</td>
   </tr>

   <tr>
     <td>Celula inferior esquerda</td>

     <td>Celula inferior direita</td>
   </tr>
 </table>

   Exemplo 4-12. Usando rowspan e colspan juntos

   Uso:

 <p>Numa tabela 3x3, o bloco superior esquerdo e um conjunto
 2x2 fundidos em um.  As outras celulas sao normais.</p>

 <table>
   <tr>
     <td colspan="2" rowspan="2">Celula esquerda superior grande</td>

     <td>Celula direita superior</td>
   </tr>

   <tr>
     <!-- Como a celula grande `a esquerda funde-se com esta linha,
          o primeiro <td> ocorrera `a a sua direita. -->
     <td>Celula do meio a direita</td>
   </tr>

   <tr>
     <td>Celula inferior esquerda</td>

     <td>Celula inferior central</td>

     <td>Celula inferior direita</td>
   </tr>
 </table>

     --------------------------------------------------------------

  4.1.4 Elementos In-line

    4.1.4.1 Enfatizando a Informac,ao

   Voce tem dois niveis de enfase disponiveis em HTML, <em> e
   <strong>. O <em> e para uma enfase simples e o <strong> indica uma
   enfase mais forte.

   Em geral, <em> e apresentada em italico e <strong> e apresentada
   em negrito. Mas nem sempre e assim, e voce nao 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 Italico

   Uma vez que o HTML inclui marcac,ao de apresentac,ao, voce tambem
   pode indicar que um conteudo deve ser apresentado em negrito ou
   italico. Os elementos sao <b> e <i> respectivamente.

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

 <p><b>Este</b> esta em negrito,
 enquanto <i>este</i> esta em italico.</p>
          

     --------------------------------------------------------------

    4.1.4.3 Indicando Texto de Fonte Fixa

   Se voce tiver conteudo 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 Conteudo

   Voce pode indicar que o conteudo deve ser apresentado em uma fonte
   maior ou menor. Existem tres maneiras de fazer isto:

    1. Use <big> e <small> em torno do texto que voce deseja mudar o
       tamanho. Estas tags podem ser aninhadas, assim <big><big>Este
       e muito maior</big></big> e possivel.

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

    3. Use <font> com o atributo size com um numero entre 1 e 7. O
       tamanho da fonte padrao e 3. Esta forma esta ultrapassada.

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

   Todos os fragmentos fazem a mesma coisa.

 <p>Este texto e <small>ligeiramente menor</small>.
 Mas este texto e <big>ligeiramente maior</big>.</p>

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

 <p>Este texto e <font size="2">ligeiramente menor</font>. 
 Mas este texto e <font size="4">ligeiramente maior</font>.</p>

     --------------------------------------------------------------

  4.1.5 Links

     Nota: Os links tambem sao elementos in-line.

     --------------------------------------------------------------

    4.1.5.1 Ligando-se a Outros Documentos

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

   O link e indicado com <a>, e o atributo href contem o URL do
   documento de destino. O conteudo do elemento se torna o link, e
   geralmente e indicado para o usuario de alguma maneira
   (sublinhado, mudanc,a de cor, o formato do cursor do mouse muda
   quando esta sobre ele, etc.

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

   Uso:

 <p>Maiores informac,oes estao disponiveis no
 <a href="http://www.FreeBSD.org/">web site do FreeBSD</a>.</p>

   Este link ira levar o usuario 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), e necessario que o autor do documento inclua
   ancoras ao qual voce possa se ligar.

   Ancoras sao indicadas com <a> e o atributo name ao inves de href.

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

   Uso:

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

   Para fazer um link a uma determinada parte de um documento, fac,a
   um link normal para aquele documento, mas inclua o nome da ancora
   apos o simbolo #.

   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 informac,ao no <a href="foo.html#para1">primeiro
 paragrafo</a> de <tt>foo.html</tt>.</p>
          

   Se voce for incluir um link para uma ancora dentro do mesmo
   documento voce pode omitir o URL do documento, e usar apenas o
   nome da ancora (precedido por #).

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

   Suponha que o exemplo para1 esteja neste documento

 <p>Mais informac,ao no <a href="#para1">primeiro
 paragrafo</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 documentac,ao
   tecnica [3]. E desde 1998 tem sido mantido pelo   DocBook
   Technical Committee. Desta forma, ao contrario do LinuxDoc e do
   HTML, o DocBook e fortemente orientado a marcac,ao que descreve o
   que e alguma coisa, ao inves de descrever como ela deve ser
   apresentada.

     Formal Versus Informal: Alguns elementos podem existir em duas
     formas, formal e informal. Tipicamente, a versao formal dos
     elementos consistira de um titulo seguido da versao informal do
     elemento. A versao informal nao tera um titulo.

   O DocBook DTD esta disponivel na colec,ao de ports como
   textproc/docbook. Ele e automaticamente instalado como parte do
   port textproc/docproj.

     --------------------------------------------------------------

  4.2.1 Extensoes FreeBSD

   O Projeto de Documentac,ao do FreeBSD ampliou o DocBook DTD
   adicionando alguns elementos novos. Estes elementos tem como
   objetivo tornar algumas marcac,oes mais precisas.

   Os elementos especificos introduzidos pelo FreeBSD estarao
   claramente destacados quando forem listados abaixo.

   No restante deste documento, o termo "DocBook" deve ser
   interpretado como sendo a versao do DocBook DTD ampliado pelo
   projeto de documentac,ao do FreeBSD.

     Nota: Nao existe nada nestas extenssoes que seja especifico ao
     FreeBSD, apenas percebemos que elas seriam melhorias para este
     projeto em particular. Se alguem dos demais projetos *nix
     (NetBSD, OpenBSD, Linux, ...) tiver interesse em colaborar para
     a criac,ao de um conjunto de extensoes DocBook padrao, por favor
     entre em contato com Equipe de Engenharia de Documentac,ao
     <doceng@FreeBSD.org>.

   As extensoes FreeBSD nao estao (atualmente) na colec,ao de ports.
   Elas estao armazenadas na arvore Subversion do FreeBSD, como  
   head/share/xml/freebsd.dtd.

     --------------------------------------------------------------

  4.2.2 Identificador Formal Publico (IFP)

   De acordo com as diretrizes DocBook para a escrita de IPF's para
   adaptac,ao do DocBook, o IPF para o DocBook estendido do FreeBSD
   e:

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

     --------------------------------------------------------------

  4.2.3 Estrutura dos Documentos

   DocBook permite que voce estruture sua documentac,ao de varias
   maneiras. No projeto de documentac,ao do FreeBSD nos estamos
   utilizando dois tipos primarios de documentos DocBook: o livro e o
   artigo.

   Um livro e organizado em <chapter>s (capitulos). Isso e um
   requerimento obrigatorio. Podem existir <part>s (partes) entre o
   livro e os capitulos para fornecer mais uma camada de
   organizac,ao. O Handbook, por exemplo, e organizado desta maneira.

   Um capitulo pode (ou nao) conter uma ou mais sessoes. Estas sao
   indicadas pelo elemento <sect1>. Se uma sessao contem outra
   sessao, entao use o elemento <sect2>, e assim por diante ate
   <sect5>.

   Capitulos e sessoes contem o restante do conteudo.

   Um artigo e mais simples do que um livro, e nao usa capitulos. Ao
   inves disso, o conteudo de um artigo e organizado em uma ou mais
   sessoes, usando os mesmos elementos <sect1> (e <sect2> e assim por
   diante) que sao usados nos livros.

   Obviamente, voce deve considerar a natureza da documentac,ao que
   voce esta escrevendo para poder decidir se e melhor uma marcac,ao
   formatada como um livro ou um artigo. Artigos suportam bem
   informac,oes que nao precisam ser divididas em capitulos, isto e,
   relativamente pequena, com mais ou menos 20 a 25 paginas de
   conteudo. Livros suportam melhor informac,oes que se dividem em
   capitulos com apendices e conteudos similares.

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

     --------------------------------------------------------------

    4.2.3.1 Iniciando um Livro

   O conteudo de um livro deve estar contido dentro do elemento
   <book>. Assim como outros elementos de marcac,ao estrutural, esse
   elemento pode conter elementos que incluam informac,oes adicionais
   sobre o livro. Isto e tanto meta-informac,ao, utilizada para fins
   de referencia, ou conteudo adicional usado para produzir uma
   pagina de titulo.

   Estas informac,oes adicionais devem estar contidas dentro do
   elemento <bookinfo>.

   Exemplo 4-21. Modelo padrao <book> com <bookinfo>

 <book>
   <bookinfo>
     <title>Seu titulo aqui</title>
    
     <author>
       <firstname>Seu primeiro nome aqui</firstname>
       <surname>Seu sobrenome</surname>
       <affiliation>
         <address><email>Seu enderec,o de correio eletronico aqui</email></address>
       </affiliation>
     </author>

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

     <releaseinfo>$FreeBSD$</releaseinfo>

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

   ...

 </book>

     --------------------------------------------------------------

    4.2.3.2 Comec,ando um Artigo

   O conteudo do artigo deve estar contido dentro do elemento
   <article>. Assim como outros elementos de marcac,ao estrutural,
   esse elemento pode conter elementos que incluam informac,oes
   adicionais sobre o artigo. Isto e tanto meta-informac,ao,
   utilizada para fins de referencia, ou conteudo adicional usado
   para produzir uma pagina de titulo.

   Estas informac,oes adicionais devem estar contidas dentro do
   elemento <articleinfo>.

   Exemplo 4-22. Modelo padrao <article> com <articleinfo>

 <article>
   <articleinfo>
     <title>Seu titulo aqui</title>
    
     <author>
       <firstname>Seu primeiro nome</firstname>
       <surname>Seu sobrenome</surname>
       <affiliation>
         <address><email>Seu enderec,o de email</email></address>
       </affiliation>
     </author>

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

     <releaseinfo>$FreeBSD$</releaseinfo>

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

   ...

 </article>

     --------------------------------------------------------------

    4.2.3.3 Indicando Capitulos

   Utilize <chapter> para marcar seus capitulos. Cada capitulo tem
   obrigatoriamente um <title>. Artigos nao contem capitulos, estes
   sao reservados para os livros.

   Exemplo 4-23. Um capitulo simples

 <chapter>
   <title>Titulo do capitulo</title>

   ...
 </chapter>

   Um capitulo nao pode ser vazio; ele precisa conter elementos alem
   do <title>. Se voce precisar incluir um capitulo vazio entao voce
   precisara incluir um paragrafo vazio.

   Exemplo 4-24. Capitulos Vazios

 <chapter>
   <title>Isto e um capitulo vazio</title>

   <para></para>
 </chapter>

     --------------------------------------------------------------

    4.2.3.4 Sessoes Abaixo dos Capitulos

   Em um livro, os capitulos podem (mas nao e obrigatoriamente
   necessario) ser quebrados em sec,oes, subsec,oes, e assim por
   diante. Em um artigo, as sec,oes sao os principais elementos
   estruturais, e cada artigo deve conter pelo menos uma sec,ao.
   Utilize o elemento <sectn>. O n indica o numero da sec,ao o qual
   identifica o nivel da sec,ao.

   A primeira <sectn> e <sect1>. Voce pode ter uma ou mais desta em
   um so capitulo. Elas podem conter um ou mais elementos <sect2>, e
   assim por diante, ate <sect5>.

   Exemplo 4-25. Sec,oes em Capitulos

 <chapter>
   <title>Um exemplo de capitulo</title>

   <para>Algum texto dentro do capitulo</para>

   <sect1>
     <title>Primeira sec,ao (1.1)</title>

     ...
   </sect1>

   <sect1>
     <title>Segunda sec,ao (1.2)</title>

     <sect2>
       <title>Primeira subsec,ao (1.2.1)</title>

       <sect3>
         <title>Primeira sub-subsec,ao (1.2.1.1)</title>

         ...
       </sect3>
     </sect2>

     <sect2>
       <title>Segunda subsec,ao (1.2.2)</title>

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

     Nota: Este exemplo inclui os numeros das sec,oes nos titulos de
     sec,oes. Voce nao deve fazer isso nos seus documentos. A
     inserc,ao dos numeros de sec,ao e realizada pelas folhas de
     estilo (falaremos delas mais a frente), e voce nao precisa
     gerencia-los manualmente.

     --------------------------------------------------------------

    4.2.3.5 Subdividindo Utilizando o Elemento <Part>

   Voce pode introduzir outra camada de organizac,ao entre <book> e
   <chapter> utilizando uma ou mais <part>s. Isto nao pode ser feito
   em um <article>.

 <part>
   <title>Introduc,ao</title>

   <chapter>
     <title>Visao Geral</title>

     ...
   </chapter>

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

     ...
   </chapter>

   <chapter>
     <title>Historia</title>

     ...
   </chapter>
 </part>

     --------------------------------------------------------------

  4.2.4 Elementos de Blocos

    4.2.4.1 Paragrafos

   O DocBook suporta tres tipos de paragrafos: <formalpara>, <para>,
   e <simpara>.

   Na maioria das vezes voce so 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 e um paragrafo.  E pode conter quase
   qualquer outro elemento.</para>

   Aparencia:

   Isso e um paragrafo. E pode conter quase qualquer outro elemento.

     --------------------------------------------------------------

    4.2.4.2 Bloco de Citac,oes

   Um bloco de citac,ao e uma longa citac,ao de outro documento que
   nao deveria aparecer no paragrafo atual. Voce nao ira usa-lo com
   muita frequencia.

   Um bloco de citac,ao pode conter opcionalmente um titulo e uma
   atribuic,ao (ou eles podem ser deixados sem titulo e sem
   atributos)

   Exemplo 4-27. <blockquote>

   Uso:

 <para>Um pequeno pedac,o da Constituic,ao dos Estados Unidos:</para>
              
 <blockquote>
   <title>Preambulo da constituic,ao dos Estados Unidos.</title>

   <attribution>Copiado de um site qualquer</attribution>
            
   <para>Nos, povo dos Estados Unidos, com o objetivo de
   fazer uma uniao mais perfeita, estabelecer justic,a,
   garantir tranquilidade domestica, promover uma defesa comum, promover
   bem estar geral, assegurar as benc,oes da
   liberdade para nos mesmos e nossa posteridade, organizamos e
   estabelecemos essa constituic,ao para os estados Unidos
   da America.</para>
 </blockquote>

   Aparencia:

   Um pequeno pedac,o da Constituic,ao dos Estados Unidos

     Preambulo da constituic,ao dos Estados Unidos.                   
                                                                    
     Nos, povo dos Estados Unidos, com o objetivo de fazer uma      
     uniao mais perfeita, estabelecer justic,a, garantir            
     tranquilidade domestica, promover uma defesa comum, promover   
     bem estar geral, assegurar as benc,oes da liberdade para nos   
     mesmos e nossa posteridade, organizamos e estabelecemos essa   
     constituic,ao para os estados Unidos da America.               
                                      --Copiado de um site qualquer   

     --------------------------------------------------------------

    4.2.4.3 Dicas, notas, avisos, informac,oes importantes e sidebars.

   Talvez voce precise incluir informac,oes extras separadas do corpo
   principal do texto. Tipicamente isto e "meta" informac,ao que o
   usuario deve tomar conhecimento.

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

   As circunstancias na qual se deve escolher um elemento ao inves do
   outro nao e clara. A documentac,ao do DocBook sugere que:

     * A <note> e uma informac,ao que deve ser lida por todos os
       leitores.

     * A <important> e uma variac,ao do <note>.

     * A <caution> e usada para informar sobre uma possivel perda de
       dados ou possivel dano causado pelo software.

     * O <warning> e usado para informac,oes sobre possiveis danos ao
       hardware, sobre risco de vida ou de ferimento a um membro.

   Exemplo 4-28. <warning>

   Uso:

 <warning>
 <para>Instalar o FreeBSD talvez fac,a com que voce queira
 desinstalar o Windows do seu Hard disk.</para>
 </warning>

   Aparencia:

     Atenc,ao: Instalar o FreeBSD talvez fac,a com que voce queira
     desinstalar o Windows do seu Hard disk.

     --------------------------------------------------------------

    4.2.4.4 Listas e Procedimentos

   Voce frequentemente vai precisar listar fragmentos de informac,ao
   para o usuario, ou apresentar para eles um passo a passo o qual
   eles devem seguir para alcanc,ar um objetivo especifico.

   Para fazer isso, utilize <itemizedlist>, <orderedlist>, ou
   <procedure> [4].

   Os elementos <itemizedlist> e <orderedlist> sao similares aos seus
   equivalentes em HTML, <ul> e <ol>. Cada um consiste de um ou mais
   elementos <listitem>, e cada <listitem> contem um ou mais
   elementos de bloco. O elemento <listitem> e analogo `a <li> do
   HTML. Entretanto, ao contrario do que ocorre no HTML, aqui elas
   sao obrigatorias.

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

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

   Uso:

 <itemizedlist>
   <listitem>
     <para>Esse e o primeiro item enumerado.</para>
   </listitem>

   <listitem>
     <para>Esse e o segundo item enumerado.</para>
   </listitem>
 </itemizedlist>

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

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

 <procedure>
   <step>
     <para>Fac,a isto.</para>
   </step>

   <step>
     <para>Depois fac,a isto.</para>
   </step>

   <step>
     <para>E agora fac,a isto.</para>
   </step>
 </procedure>

   Aparencia:

     * Esse e o primeiro item enumerado.

     * Esse e o segundo item enumerado.

    1. Esse e o primeiro item ordenado.

    2. Esse e o segundo item ordenado.

    1. Fac,a isto.

    2. Depois fac,a isto.

    3. E agora fac,a isto.

     --------------------------------------------------------------

    4.2.4.5 Mostrando Amostras de Arquivos

   Se voce quiser mostrar um trecho de um arquivo (ou talvez um
   arquivo inteiro) ao usuario, use o elemento <programlisting>

   Espac,os e quebras de linha sao 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 ultima linha do
   programa, do contrario linhas em branco espurias podem ser
   incluidas.

   Exemplo 4-30. <programlisting>

   Uso:

 <para>Quando voce 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 atraves de suas entidades ao inves de incluidas
   literalmente.

   Aparencia:

   Quando voce tiver terminado, seu programa deve estar assim;

 #include <stdio.h>

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

     --------------------------------------------------------------

    4.2.4.6 Chamadas

   Uma chamada e um mecanismo para fazer referencia a um pedac,o de
   texto ou uma posic,ao especifica de um exemplo anterior sem ligar
   a ele no texto.

   Para fazer isso, marque as areas de interesse no seu exemplo
   (<programlisting>, <literallayout>, ou o que for) com o elemento
   <co>. Cada elemento deve ter um id unico atribuido a ele. Insira
   um <calloutlist> no final do exemplo acima fazendo referencia de
   volta a ele, exibindo comentarios adicionais.

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

 <para>Quando voce 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 padrao 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 saida padrao.</para>
   </callout>
 </calloutlist>

   Aparencia:

   Quando voce tiver terminado, seu programa deve estar assim;

 #include <stdio.h> (1)

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

   (1)
           Inclui o arquivo padrao de IO.
   (2)
           Especifica que main() retorna um inteiro.
   (3)
           A chamada printf() escreve hello, world na saida padrao

     --------------------------------------------------------------

    4.2.4.7 Tabelas

   Ao contrario do HTML, voce nao precisa usar tabelas para acertar o
   layout, as folhas de estilo cuidam disto para voce. Utilize
   tabelas apenas para marcac,ao de dados tabulares.

   De maneira geral (veja a documentac,ao do DocBook para mais
   detalhes) uma tabela (que pode ser formal ou informal) consiste de
   um elemento <table>. O qual contem ao menos um elemento <tgroup>,
   que especifica (como um atributo) o numero de colunas neste grupo
   da tabela. Dentro do grupo tabela voce pode ter um elemento
   <thead>, que contem os elementos para o cabec,alho da tabela
   (cabec,alho da coluna), e um <tbody> que contem o corpo da tabela.

   Tanto o <tgroup> quanto o <thead> contem elementos <row>, que por
   sua vez contem elementos <entry>. Cada elemento <entry> especifica
   uma celula da tabela.

   Exemplo 4-32. <informaltable>

   Uso:

 <informaltable pgwide="1">
   <tgroup cols="2">
     <thead>
       <row>
         <entry>Este e o cabec,alho da coluna 1</entry>
         <entry>Este e o cabec,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>

   Aparencia:

   +----------------------------------------------------------------+
   | Este e o cabec,alho da coluna  | Este e o cabec,alho da coluna |
   |               1                |               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 voce nao 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"

   Aparencia:

    Este e o cabec,alho da coluna 1  Este e o cabec,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 Usuario Seguir

   Muitas vezes voce ira precisar mostrar exemplos para que o usuario
   siga. Normalmente, isso ira consistir de dialogos com o
   computador, nos quais o usuario digita um comando, e obtem uma
   resposta de volta, ele digita outro comando e recebe outra
   reposta, e assim por diante.

   Varios elementos e entidades podem ser utilizados nestes casos.

   <screen>

           Tudo que o usuario visualizar neste exemplo estara na tela
           do computador, assim o proximo elemento e <screen>.

           Dentro da marcac,ao do <screen>, espac,os em branco sao
           significativos.

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

           Algumas das coisas que o usuario ira visualizar na tela
           sao prompts do computador (seja do sistema operacional, da
           linha de comando shell ou de uma aplicac,ao). Estes
           prompts devem ser marcados usando <prompt>.

           Por serem especiais, os prompts de shell do usuario normal
           e do usuario root estao disponiveis como uma entidade.
           Sempre que quiser indicar que o usuario esta em um prompt
           do shell, use &prompt.root; para o usuario root e
           &prompt.user; para o usuario normal, conforme for
           necessario. Estas entidades nao precisam estar dentro de
           um <prompt>.

             Nota: &prompt.root; e &prompt.user; sao extensoes do
             FreeBSD ao DocBook, e nao sao parte do DTD original.

   <userinput>

           Quanto estiver mostrando um texto que o usuario deva
           digitar, envolva-o com as tags <userinput>. Ele
           provavelmente sera mostrado diferente para o usuario.

   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>

   Aparencia:

 % 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 conteudo do arquivo foo2,
     ele nao esta marcado como <programlisting>. Deixe o
     <programlisting> para mostrar fragmentos de arquivos fora do
     contexto de ac,ao do usuario.

     --------------------------------------------------------------

  4.2.5 Elementos In-line

    4.2.5.1 Enfatizando a Informac,ao

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

   Nao ha uma maneira de mudar a apresentac,ao da enfase no seu
   documento, nao existe um equivalente ao <b> e ao <i> do HTML. Se a
   informac,ao que voce esta apresentando e importante entao
   considere usar <important> ao inves de <emphasis>.

   Exemplo 4-35. <emphasis>

   Uso:

 <para>O FreeBSD e sem duvida <emphasis>o</emphasis> melhor sistema operacional tipo Unix
 para a arquitetura Intel.</para>

   Aparencia:

   O FreeBSD e sem duvida o melhor sistema operacional tipo Unix para
   a arquitetura Intel.

     --------------------------------------------------------------

    4.2.5.2 Citac,oes

   Para citar um texto de outro documento ou fonte, ou para denotar
   uma frase que esta sendo usada figuradamente, use <quote>. Dentro
   da tag <quote>, voce pode usar a maioria das marcac,oes
   disponiveis para um texto normal.

   Exemplo 4-36. Citac,oes

   Uso:

 <para>Entretanto, certifique-se que a busca nao va alem do <quote>limite entre
   a administrac,ao local e publica</quote> como diz o RFC 1535.</para>

   Aparencia:

   Entretanto, certifique-se que a busca nao va alem do "limite entre
   a administrac,ao local e publica" como diz o RFC 1535.

     --------------------------------------------------------------

    4.2.5.3 Teclas, Mouse e Combinac,oes

   Para se referir a uma tecla especifica do teclado, use <keycap>.
   Para se referir a um botao do mouse, use <mousebutton>. E para se
   referir a combinac,ao 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 ultimos dizem
   se teclas ou botoes devem ser pressionados em sequencia ou
   simultaneamente.

   As folhas de estilo colocam automaticamente o simbolo de ligac,ao,
   tal como +, entre os nomes das teclas, quando elas estiverem
   envolvidas com <keycombo>.

   Exemplo 4-37. Teclas, Mouse e Combinac,oes

   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 e configurado de forma que
   <keycombo action="simul"><keycap>Alt</keycap>
     <mousebutton>botao direito</mousebutton>
   </keycombo> do mouse e usado para mover as janelas.</para>

   Aparencia:

   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 e configurado de forma que Alt+botao
   direito do mouse e usado para mover as janelas.

     --------------------------------------------------------------

    4.2.5.4 Aplicac,oes, Comandos, Opc,oes e Citac,oes

   Frequentemente voce ira fazer referencia tanto a aplicac,oes
   quanto a comandos quando estiver escrevendo a documentac,ao. A
   distinc,ao entre eles e simples: uma aplicac,ao e o nome de um
   pacote de programas (ou possivelmente apenas um) que executa uma
   tarefa em particular. Um comando e o nome de um programa que o
   usuario pode executar.

   Alem disso, voce eventualmente precisara listar uma ou mais
   opc,oes que um comando pode aceitar.

   Finalmente, voce ira querer listar um comando com o numero da sua
   sec,ao no manual, na forma "comando(numero)" que e tao comum nos
   manuais de Unix.

   Voce deve marcar o nome de uma aplicac,ao com <application>.

   Quando voce quiser listar um comando com o numero da sua sec,ao no
   manual (o que deve acontecer na maioria das vezes) o elemento do
   DocBook que deve ser utilizado e o <citerefentry>. Ele ira ter
   mais dois elementos, <refentrytitle> e <manvolnum>. O conteudo de
   <refentrytitle> e o nome do comando, e o conteudo de <manvolnum> e
   a sec,ao da pagina do manual.

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

   O arquivo que contem estas entidades e 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 introduc,ao `a sua documentac,ao provavelmente sera
   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 usuario.

   Use o elemento <option> para marcar as opc,oes que serao passadas
   para um comando.

   Quando diversas referencias a um mesmo comando estiverem proximas
   e melhor usar a notac,ao &man.command.section; para marcar a
   primeira referencia ao mesmo e depois utilizar <command> para
   marcar as referencias subsequentes. Isto fara a saida gerada,
   especialmente em HTML, ficar visualmente melhor.

   Isto pode ser confuso, e muitas vezes a escolha nem sempre e
   clara. Acredito que o exemplo abaixo ajudara a tornar as coisas
   mais claras.

   Exemplo 4-38. Aplicac,oes, Comandos, Opc,oes

   Uso:

 <para>O <application>Sendmail</application> e a aplicac,ao
   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 parametros 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>

   Aparencia:

   O Sendmail e a aplicac,ao de email mais utilizada em Unix.

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

   Um dos parametros de linha de comando para o sendmail(8), -bp, ira
   mostrar o atual estado da mensagem na fila de email. Verifique
   isto na linha de comando usando sendmail -bp.

     Nota: Veja como a notac,ao &man.command.section; e mais facil de
     acompanhar.

     --------------------------------------------------------------

    4.2.5.5 Arquivos, Diretorios, Extensoes

   Sempre que quiser se referir ao nome de um arquivo, diretorio ou
   uma extensao de arquivo, use o elemento <filename>.

   Exemplo 4-39. <filename>

   Uso:

 <para>O fonte SGML do Handbook em Ingles pode ser encotrado em
   <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. 
   O primeiro arquivo neste diretorio e chamado <filename>book.xml</filename>.
   Voce tambem deve ver o <filename>Makefile</filename>
   e alguns arquivos com a extensao <filename>.ent</filename>.</para>

   Aparencia:

   O fonte SGML do Handbook em Ingles pode ser encotrado em
   /usr/doc/en/handbook/. O primeiro arquivo neste diretorio e
   chamado handbook.xml. Voce tambem deve ver o Makefile e alguns
   arquivos com a extensao .ent.

     --------------------------------------------------------------

    4.2.5.6 O Nome dos Ports

     Extensoes FreeBSD: Estes elementos sao parte das extensoes do
     FreeBSD ao DocBook, e nao existem no DTD DocBook original.

   Voce pode precisar incluir o nome de um programa da Colec,ao de
   Ports do FreeBSD na documentac,ao. Use a tag <filename> com o
   atributo role ajustado para package para identifica-lo. Uma vez
   que a colec,ao de ports pode ser instalada em diversos lugares,
   inclua apenas a categoria e o nome do port, nao 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 trafego na rede.</para>

   Aparencia:

   Instale o port net/ethereal para ver o trafego na rede.

     --------------------------------------------------------------

    4.2.5.7 Dispositivos

     Extensoes FreeBSD: Estes elementos sao parte das extensoes do
     FreeBSD ao DocBook, e nao existem no DTD DocBook original.

   Voce tem 2 opc,oes para se referir a um dispositivo. Voce pode se
   referir ao dispositivo da forma como ele aparece no /dev, ou voce
   pode usar o nome do dispositivo como ele aparece no kernel. No
   segundo caso, use o elemento <devicename>.

   Em alguns casos voce nao tera escolha. Alguns dispositivos, como
   as placas de rede, nao tem entrada no /dev, ou as entradas sao
   muito diferentes das esperadas.

   Exemplo 4-41. <devicename>

   Uso:

 <para><devicename>sio</devicename> e usado para comunicac,ao
   serial no FreeBSD. <devicename>sio</devicename> se manifesta
   atraves 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>
   nao aparecem <filename>/dev</filename>.
   </para>

 <para>No MS-DOS, o primeiro disco flexivel e chamado de <devicename>a:</devicename>.
   No FreeBSD e <filename>/dev/fd0</filename>.
   </para>

   Aparencia:

   sio e usado para comunicac,ao serial no FreeBSD. sio se manifesta
   atraves de entradas em /dev, incluindo /dev/ttyd0 e /dev/cuaa0.

   Por outro lado, dispositivos de rede, tais como ed0 nao aparecem
   /dev.

   No MS-DOS, o primeiro disco flexivel e chamado de a:. No FreeBSD e
   /dev/fd0.

     --------------------------------------------------------------

    4.2.5.8 Hosts, Dominios, Enderec,os IP e etc.

     Extensoes FreeBSD: Estes elementos sao parte das extensoes do
     FreeBSD ao DocBook, e nao existem no DTD DocBook original.

   Voce pode marcar a informac,ao sobre a identificac,ao de
   computadores em rede (hosts) de diversas maneiras. Todas elas usam
   <hostid> como elemento, com o atributo role dizendo o tipo da
   informac,ao marcada.

   Sem o atributo role, ou role="hostname"

           Sem o atributo role (i.e., <hostid>...</hostid>) a
           informac,ao marcada e simplesmente o nome do computador,
           tal como freefall ou wcarchive. Voce pode especificar
           explicitamente com role="hostname".

   role="domainname"

           O texto e um nome de dominio, tal como FreeBSD.org ou
           ngo.org.uk. Nao ha o componente do nome do computador
           (hostname).

   role="fqdn"

           O texto e um nome completo, com o nome do computador e do
           dominio. O termo fqdn significa "Fully Qualified Domain
           Name" - Nome de Dominio Completamente Qualificado.

   role="ipaddr"

           O texto e um enderec,o IP, provavelmente expresso como
           dotted quad.

   role="ip6addr"

           O texto e um enderec,o IPv6.

   role="netmask"

           O texto e uma mascara de rede, que pode ser expressa como
           dotted quad, uma string hexadecimal ou como / seguido de
           um numero.

   role="mac"

           O texto e um enderec,o MAC Ethernet, expresso como numeros
           hexadecimais de 2 digitos separados por dois pontos (:).

   Exemplo 4-42. <Hostid> e Roles

   Use:

 <para>A maquina local sempre pode ser referida pelo nome
 <hostid>localhost</hostid>, que tera o enderec,o IP
 <hostid role="ipaddr">127.0.0.1</hostid>.</para>


 <para>O dominio <hostid role="domainname">FreeBSD.org</hostid>
 contem varios 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
 mascara de rede <hostid role="netmask">255.255.255.255</hostid> (que
 tambem pode ser expressa como <hostid role="netmask">0xffffffff</hostid>).
 </para>

 <para>O enderec,o MAC identifica unicamente cada placa de rede
 existente.  Um enderec,o MAC tipico se parece com  <hostid
 role="mac">08:00:20:87:ef:d0</hostid>).</para>

   Aparencia:

   A maquina local sempre pode ser referida pelo nome localhost, que
   tera o enderec,o IP 127.0.0.1.

   O dominio FreeBSD.org contem varios hosts diferentes, incluindo
   freefall.FreeBSD.org e bento.FreeBSD.org.

   Quando estiver adicionando um apelido para uma interface (usando
   ifconfig) sempre use a mascara de rede 255.255.255.255 (que tambem
   pode ser expressa como 0xffffffff).

   O enderec,o MAC identifica unicamente cada placa de rede
   existente. Um enderec,o MAC tipico se parece com
   08:00:20:87:ef:d0.

     --------------------------------------------------------------

    4.2.5.9 Usernames

     Extensoes FreeBSD: Estes elementos sao parte das extensoes do
     FreeBSD ao DocBook, e nao existem no DTD DocBook original.

   Quando precisar se referir a um nome de usuario especifico, tal
   como root ou bin, use o elemento <username>.

   Exemplo 4-43. <Username>

   Uso:

 <para>Para executar a maioria das func,oes administrativas voce precisara
   ser <username>root</username>.</para>

   Aparencia:

   Para executar a maioria das func,oes administrativas voce
   precisara ser root.

     --------------------------------------------------------------

    4.2.5.10 Descrevendo Makefiles

     Extensoes FreeBSD: Estes elementos sao parte das extensoes do
     FreeBSD ao DocBook, e nao existem no DTD DocBook original.

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

   O <maketarget> identifica uma alvo de construc,ao exportado por um
   Makefile que pode ser passado como um parametro ao make. O
   <makevar> identifica uma variavel 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> sao
 <maketarget>all</maketarget> e <maketarget>clean</maketarget>.</para>

 <para>Tipicamente, usar <maketarget>all</maketarget> ira refazer a
 aplicac,ao, usar <maketarget>clean</maketarget> ira remover os
 arquivos temporarios (<filename>.o</filename> por exemplo) criados
 pelo processo de construc,ao.</para>

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

   Aparencia:

   Dois alvos comuns em um Makefile sao all e clean.

   Tipicamente, usar all ira refazer a aplicac,ao, usar clean ira
   remover os arquivos temporarios (.o por exemplo) criados pelo
   processo de construc,ao.

   O clean pode ser controlado por muitas variaveis, incluindo
   CLOBBER e RECURSE.

     --------------------------------------------------------------

    4.2.5.11 Texto Literal

   Com frequencia voce ira precisar incluir texto "literal" na
   documentac,ao. Este texto que e originado de outro arquivo, ou que
   deve ser copiado de forma fiel da documentac,ao para outro
   arquivo.

   As vezes, o <programlisting> sera suficiente. Mas o
   <programlisting> nem sempre e apropriado, particularmente quando
   voce quer incluir uma parte de um arquivo "in-line" com todos os
   paragrafos.

   Nestas ocasioes, use <literal>.

   Exemplo 4-45. <Literal>

   Uso:

  <para>A linha <literal>maxusers 10</literal> no arquivo de
 configurac,ao do kernel determina o tamanho de muitas tabelas
 do sistema, e diz aproximadamente quantos logins simultaneos
 o sistema ira suportar.</para>

   Aparencia:

   A linha maxusers 10 no arquivo de configurac,ao do kernel
   determina o tamanho de muitas tabelas do sistema, e diz
   aproximadamente quantos logins simultaneos o sistema ira suportar.

     --------------------------------------------------------------

    4.2.5.12 Mostrando Itens que o Usuario Deve Preencher

   Muitas vezes voce ira querer mostrar ao usuario o que fazer, ou
   precisara se referir a um arquivo, a uma linha de comando ou coisa
   parecida, na qual ele nao podera simplesmente copiar o exemplo que
   voce forneceu, mas na qual ele tera deve dar alguma informac,ao
   por ele mesmo.

   O elemento <replaceable> foi criado para estas ocasioes. Use ele
   dentro de outros elementos para indicar partes do conteudo do
   elemento que o usuario deve substituir.

   Exemplo 4-46. <replaceable>

   Uso:

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

   Aparencia:

 % man comando

   O <replaceable> pode ser usado em muitos elementos diferentes,
   incluindo <literal>. Este exemplo tambem mostra que <replaceable>
   so deve envolver o conteudo que o usuario deve fornecer. O outro
   conteudo nao deve ser alterado.

   Uso:

 <para>A linha <literal>maxusers <replaceable>n</replaceable></literal>
 no arquivo de configurac,ao do kernel determina o tamanho de muitas
 tabelas do sistema, e diz aproximadamente quantos logins simultaneos
 o sistema ira suportar.
 </para>

 <para>Para uma estac,ao de trabalho, <literal>32</literal> e um
 bom valor para <replaceable>n</replaceable>.</para>

   Aparencia:

   A linha maxusers n no arquivo de configurac,ao do kernel determina
   o tamanho de muitas tabelas do sistema, e diz aproximadamente
   quantos logins simultaneos o sistema ira suportar.

   Para uma estac,ao de trabalho, 32 e um bom valor para n.

     --------------------------------------------------------------

    4.2.5.13 Citando erros do sistema

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

   Exemplo 4-47. <errorname>

   Uso:

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

   Aparencia:

 "Panic: cannot mount root"

     --------------------------------------------------------------

  4.2.6 Imagens

     Importante: O suporte a imagem na documentac,ao ainda e
     extremamente experimental. O mecanismo aqui descrito
     provavelmente nao ira mudar, mas isto nao e garantido.

     Voce precisara instalar o port graphics/ImageMagick que e usado
     para converter entre os diferentes formatos de imagens. Ele e
     grande e a sua maior parte nao e necessaria. Entretanto,
     enquanto nos ainda estamos trabalhando nos Makefiles e em outros
     itens da infraestrutura, ele torna as coisas mais faceis. Este
     port nao esta no meta port textproc/docproj, voce deve
     instala-lo manualmente.

     O melhor exemplo do que acontece na pratica e o documento
     doc/en_US.ISO8859-1/articles/vm-design/ . Se voce se sentir
     inseguro na descric,ao que segue, de uma olhada nos arquivos
     deste diretorio e veja como tudo se encaixa. Experimente criar
     versoes com diferentes formatos de saida do documento para ver
     como a marcac,ao de imagem aparece no documento final.

     --------------------------------------------------------------

    4.2.6.1 Formatos de Imagens

   Atualmente suportamos dois formatos de imagens. O formato que voce
   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 extensao .eps.

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

   Estes sao os unicos formatos de imagem que podem ser gravados no
   repositorio Subversion.

   Use o formato correto para a imagem correta. Espera-se que a sua
   documentac,ao tenha tanto imagens EPS quanto PNG. Os Makefiles
   asseguram que o formato correto seja escolhido dependendo do
   formato de saida da sua documentac,ao. Nao fac,a commit da mesma
   imagem nos dois formatos diferentes para o repositorio.

     Importante: E esperado que o projeto de documentac,ao passe a
     utilizar no futuro o formato Scalable Vector Graphic (SVG) para
     imagens vetoriais. Entretanto, o atual estado das ferramentas de
     edic,ao torna isto impraticavel.

     --------------------------------------------------------------

    4.2.6.2 Marcac,ao

   A marcac,ao para uma imagem e relativamente simples. Primeiro,
   marque um <mediaobject>. O <mediaobject> pode conter outros
   objetos mais especificos. Estamos interessandos em dois, o
   <imageobject> e o <textobject>.

   Voce deve incluir um <imageobject>, e dois elementos <textobject>.
   O <imageobject> ira apontar para o nome do arquivo da imagem que
   sera usada (sem a extensao). Os elementos <textobject> contem a
   informac,ao que sera apresentada ao usuario junto, ou nao, com a
   imagem.

   Ha duas circunstancias em que isso pode ocorrer.

     * Quando o leitor estiver vendo a documentac,ao em HTML. Neste
       caso, cada imagem precisara ter um texto alternativo associado
       para mostrar ao usuario, tipicamente enquanto a imagem estiver
       sendo carregada, ou se ele parar o ponteiro do mouse sobre a
       imagem.

     * Quando o leitor estiver vendo a documentac,ao em modo texto.
       Neste caso, cada imagem deve ter uma ASCII art equivalente
       para mostrar ao usuario.

   Um exemplo provavelmente ira tornar as coisas mais faceis de se
   entender. Suponha que voce tenha uma imagem, chamada fig1, que
   voce queira incluir no documento. Esta imagem e um retangulo com
   um A dentro dele. A marcac,ao para isso sera:

 <mediaobject>
   <imageobject>
     <imagedata fileref="fig1"> (1)
   </imageobject>

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

   <textobject>
     <phrase>Uma figura</phrase> (3)
   </textobject>
 </mediaobject>

   (1)
           Inclua um elemento <imagedata> dentro do elemento
           <imageobject>. O atributo fileref deve conter o nome da
           imagem a ser incluida, sem a extensao. As folhas de estilo
           irao decidir qual a extensao deve ser adicionada ao nome
           do arquivo automaticamente.
   (2)
           O primeiro <textobject> deve conter um elemento
           <literallayout>, onde o atributo class e ajustado para
           monospaced. Esta e a oportunidade para voce demonstrar
           suas habilidades com ASCII art. O conteudo sera usado se o
           documento for convertido para texto puro.

           Veja como as primeras e ultimas linhas do conteudo do
           elemento <literallayout > fica proximo a tag do elemento.
           Isso assegura que nao sejam incluidos espac,os extras.

   (3)
           O segundo <textobject> deve conter um unico elemento
           <phrase>. O conteudo deste elemento se tornara 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 variavel IMAGES do Makefile.
   Esta variavel deve conter o nome de todos fontes das suas imagens.
   Por exemplo, se voce criou tres figuras, fig1.eps, fig2.png,
   fig3.png, entao 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 ira fazer uma lista completa das imagens
   necessarias para criar o seu documento fonte, voce precisa listar
   apenas as imagens que voce fornece.

     --------------------------------------------------------------

    4.2.6.4 Imagens e Capitulos em Subdiretorios

   Voce precisa ser cuidadoso quando separar a sua documentac,ao em
   arquivos menores (veja Sec,ao 3.7.1) em diretorios diferentes.

   Suponha que voce tenha um livro com tres capitulos, e os capitulos
   estao armazenados cada um no seu proprio diretorio, chamados
   chapter1/chapter.xml, chapter2/chapter.xml, e
   chapter3/chapter.xml. Se cada capitulo tiver imagens associadas a
   eles, e sugerido que voce as coloque dentro do respectivo
   subdiretorio de cada capitulo (chapter1/, chapter2/, chapter3/).

   Entretanto, se voce fizer isso voce deve incluir o nome dos
   diretorios na variavel IMAGES no Makefile, e deve incluir o nome
   do diretorio no elemento <imagedata> do seu documento.

   Por exemplo, se voce tiver chapter1/fig1.png, entao
   chapter1/chapter.xml deve conter:

 <mediaobject>
   <imageobject>
     <imagedata fileref="chapter1/fig1"> (1)
   </imageobject>

   ...

 </mediaobject>

   (1)
           O nome do diretorio deve ser incluido no atributo fileref

   O Makefile deve conter:

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

   Desta forma tudo deve funcionar.

     --------------------------------------------------------------

  4.2.7 Links

     Nota: Links tambem sao elementos in-line.

     --------------------------------------------------------------

    4.2.7.1 Ligando-se a outras partes no mesmo documento

   Links dentro do mesmo documento exigem que voce especifique de
   onde voce esta se ligando (i.e., o texto no qual o usuario ira
   clicar, ou indicando de outra maneira a origem do link) e para
   onde voce esta se ligando (o destino do link).

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

   Este valor sera usado quando voce especificar a origem do link.

   Normalmente, voce ira se ligar apenas a capitulos ou sec,oes,
   assim voce ira colocar o atributo id nestes elementos.

   Exemplo 4-48. O atributo id em capitulos ou sec,oes

 <chapter id="chapter1">
   <title>Introduc,ao</title>

   <para>Esta e a introduc,ao.  Contem uma
     subsec,ao que tambem sera identificada.
   </para>
   <sect1 id="chapter1-sect1">
     <title>Subsec,ao 1</title>

     <para>Esta e a subsec,ao.</para>
   </sect1>
 </chapter>

   Obviamente, voce deve usar nomes mais descritivos. Estes nomes
   devem ser unicos dentro do documento (i.e., nao apenas no arquivo,
   mas sim no documento no qual o arquivo esta incluido). Repare como
   o id e construido adicionando-se texto ao id do capitulo. Isto
   ajuda a garantir que eles sejam unicos.

   Se voce quiser permitir ao usuario saltar para uma parte
   especifica do documento (possivelmente para o meio do paragrafo ou
   um exemplo), use o elemento <anchor>. Este elemento nao tem
   conteudo, mas aceita o atributo id.

   Exemplo 4-49. <anchor>

 <para>
 Este paragrafo tem um <anchor id="para1">alvo dentro dele.
 O qual nao ira aparecer no documento
 </para>

   Quando voce quiser dar ao usuario um link que possa ser ativado
   (provavelmente clicando-se) para ir para outra sec,ao do documento
   que tenha um atributo id, voce pode usar <xref> ou <link>.

   Ambos os elementos tem um atributo linkend. O valor deste atributo
   deve ser o mesmo usado no atributo id (nao importa se ele ainda
   nao ocorreu no documento; isto funciona tanto para um link `a
   frente quanto para tras).

   Se voce utilizar o <xref> entao voce nao tera controle sobre o
   texto do link. Ele sera gerado para voce.

   Exemplo 4-50. Usando <xref>

   Assuma que este fragmento aparec,a em algum lugar de um documento
   que inclua o id do exemplo.

 <para>Maiores informac,oes podem ser encontradas
   em <xref linkend="chapter1"/></para>

 <para>Informac,oes mais especificas podem ser
   encontradas na <xref linkend="chapter1-sect1"/>.</para>

   O texto do link sera gerado automaticamente, e ira se parecer com
   (As palavras em italico indicam o texto que sera o link):

     Maiores informac,oes podem ser encontradas no Capitulo Um.

     Informac,oes mais especificas podem ser encontradas na sec,ao
     chamada Subsec,ao 1.

   Observe como o texto do link e deduzido a partir do titulo da
   sec,ao ou do numero do capitulo.

     Nota: Isto significa que voce nao pode usar <xref> para se ligar
     a um atributo id em um elemento <anchor>. O <anchor> nao tem
     conteudo, desta forma o <xref> nao pode gerar o texto para o
     link.

   Se voce quiser controlar o texto do link voce devera utilizar
   <link>. Este elemento envolve o conteudo, e o conteudo sera 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 informac,oes podem ser encontradas
 <link linkend="chapter1">no primeiro capitulo</link>.
 </para>

 <para>Informac,oes mais especificas podem ser encontradas
 <link linkend="chapter1-sect1">nesta</link> sec,ao
 </para>

   Isto ira gerar o seguinte (Palavras em italico indicam o texto que
   sera o link):

     Maiores informac,oes podem ser encontradas no primeiro capitulo
     .

     Informac,oes mais especificas podem ser encontradas nesta sec,ao

     Nota: Este ultimo e um mau exemplo. Nunca use palavras como
     "esta" ou "aqui" como origem do link. O leitor tera que procurar
     no contexto proximo para ver para onde o link o esta levando.

     Nota: Voce pode usar o elemento <link> para incluir um link para
     um id em um elemento <anchor>, uma vez que o conteudo de <link>
     define o texto que sera usado para o link.

     --------------------------------------------------------------

    4.2.7.2 Ligando-se a documentos na WWW

   Ligar-se a um documento externo e muito mais simples, desde que
   voce saiba o URL do documento ao qual deseja se ligar. Basta
   utilizar o elemento <ulink>. O atributo url e o URL da pagina para
   o qual o link aponta, e o conteudo do elemento e o texto que sera
   mostrado para o usuario ativar.

   Exemplo 4-52. <ulink>

   Uso:

 <para>E claro que voce pode parar de ler este documento e ir para a
 <ulink url="http://www.FreeBSD.org/index.html">Pagina principal do FreeBSD</ulink>
 </para>

   Aparencia:

   E claro que voce pode parar de ler este documento e ir para a
   Pagina principal do FreeBSD

     --------------------------------------------------------------

                     Capitulo 5 * Folhas de Estilo

   O SGML nao diz nada sobre como um documento deve ser exibido ao
   usuario, ou formatado para impressao. Para fazer isto, varias
   linguagens foram desenvolvidas para descrever folhas de estilo,
   incluindo DynaText, Panorama, SPICE, JSSS, FOSI, CSS, e DSSSL.

   Para o DocBook, nos estamos usando folhas de estilo escritas em
   DSSSL. Para o HTML nos estamos usando o CSS.

     --------------------------------------------------------------

5.1 * DSSSL

   O projeto de documentac,ao usa uma versao 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 nao estao no sistema de ports.
   Elas sao parte do repositorio de fontes do projeto de
   documentac,ao, e podem ser encontradas em
   doc/share/xml/freebsd.dsl. Elas estao bem comentadas, e como a
   conclusao desta sec,ao esta pendente, recomendamos que voce
   examine este arquivo para ver como algumas das opc,oes disponiveis
   nas folhas de estilo padrao foram configuradas para customizar a
   saida para o projeto de documentac,ao do FreeBSD. Este arquivo
   tambem contem exemplos que mostram como estender os elementos que
   a folha de estilo compreende, que e como os elementos especificos
   para o FreeBSD foram formatados.

     --------------------------------------------------------------

5.2 CSS

   Folha de estilo em cascata (CSS) e um mecanismo para anexar a
   informac,ao de estilo (fontes, peso, tamanho, cor, e assim por
   diante) aos elementos de um documento HTML sem abusar do HTML para
   faze-lo.

     --------------------------------------------------------------

  5.2.1 Documentos DocBook

   As folhas de estilo DSSSL do FreeBSD incluem uma referencia para a
   folha de estilo, docbook.css, a qual espera-se aparecer no mesmo
   diretorio dos arquivos HTML. Este arquivo CSS geral do projeto e
   copiado de doc/share/misc/docbook.css quando os documentos sao
   convertidos para HTML, e e instalado automaticamente.

     --------------------------------------------------------------

              Capitulo 6 Estruturando Documentos Sob doc/

   A arvore doc/ e organizada de uma forma particular, e os
   documentos que compoe o Primer do Projeto de Documentac,ao do
   FreeBSD devem ser por isso organizados de forma particular. O
   objetivo e tornar simples a adic,ao de nova documentac,ao `a
   arvore, e:

    1. Facilitar a automatizac,ao da conversao de documentos para
       outros formatos.

    2. Promover consistencia entre diferentes formas de organizar a
       documentac,ao, facilitar a troca entre diferentes documentos.

    3. Facilitar a decisao de onde na arvore uma nova documentac,ao
       deveria ser colocada.

   Alem disso, a arvore de documentac,ao tem de acomodar
   documentac,ao que pode estar em muitas diferentes linguas e muitas
   diferentes codificac,oes. E importante que a estrutura da arvore
   de documentac,ao nao force nenhum padrao particular ou preferencia
   cultural.

     --------------------------------------------------------------

6.1 O Nivel Superior, doc/

   Existem dois tipos de diretorios sob doc/, cada um com nomes de
   diretorios e significados muito especificos.

   Diretorio: share/

   Significado: Contem arquivos que nao sao especificos as varias
   traduc,oes e codificac,oes da documentac,ao. Contem subdiretorios
   para promover uma melhor categorizac,ao da informac,ao. Por
   exemplo, os arquivos que compoem a infraestrutura de make(1)
   encontram-se em share/mk, enquanto os arquivos adicionais para
   suporte SGML (como as extensoes do FreeBSD ao DocBook DTD)
   encontram-se em share/xml.

   Diretorio: idioma.codificac,ao/

   Significado: Existe um diretorio para cada traduc,ao e
   codificac,ao da documentac,ao, por exemplo en_US.ISO8859-1/ e
   zh_TW.Big5/. Os nomes sao longos, mas ao especificar completamente
   a lingua e codificac,ao prevenimos qualquer futura dor de cabec,a
   caso um time de traduc,ao queira prover a documentac,ao na mesma
   lingua mas em mais de uma codificac,ao. Isto tambem nos isola
   completamente de quaisquer problemas que possam ser causados por
   uma mudanc,a para Unicode.

     --------------------------------------------------------------

6.2 Os Diretorios de idioma.codificac,ao

   Estes diretorios contem os documentos propriamente ditos. A
   documentac,ao e dividida em ate tres categorias adicionais neste
   nivel, indicadas pelos diferentes nomes de diretorios.

   Diretorio: articles

   Conteudo: Documentac,ao codificada como DocBook <article> (ou
   equivalente). Razoavelmente pequena, e separada em sec,oes.
   Normalmente disponivel apenas como um arquivo HTML.

   Diretorio: books

   Conteudo: Documentac,ao codificada como DocBook <book> (ou
   equivalente). Com o tamanho de um livro, e separada em capitulos.
   Normalmente disponivel tanto como um grande arquivo HTML (para
   pessoas com conexoes rapidas, ou que queiram imprimi-la facilmente
   a partir de um navegador Internet) quanto como uma colec,ao de
   pequenos arquivos interligados.

   Diretorio: man

   Conteudo: Para traduc,oes das paginas de manual do sistema. Este
   diretorio contera um ou mais diretorios mann, correspondendo as
   sec,oes que foram traduzidas.

   Nem todo diretorio idioma.codificac,ao contera todos estes
   diretorios. Isto depende de quantos documentos ja foram traduzidos
   pelo time de traduc,ao.

     --------------------------------------------------------------

6.3 Informac,ao Especifica do Documento

   Esta sessao contem observac,oes especificas sobre documentos
   particulares controlados pelo FDP.

     --------------------------------------------------------------

  6.3.1 O Handbook

   books/handbook/

   O Handbook e escrito de forma a obedecer a versao estendida do DTD
   DocBook utilizado pelo projeto FreeBSD.

   O Handbook e organizado como um <book> Docbook. Ele esta dividido
   em <part>es, e cada uma delas pode conter diversos <chapter>s
   (Capitulos). Os <chapter>s estao subdivididos em sec,oes (<sect1>)
   e subsec,oes (<sect2>, <sect3>) e assim por diante.

     --------------------------------------------------------------

    6.3.1.1 Organizac,ao Fisica

   Existem diversos arquivos e diretorios dentro do diretorio
   handbook.

     Nota: A organizac,ao do Handbook pode mudar ao longo do tempo, e
     este documento pode ficar defasado no detalhamento destas
     alterac,oes organizacionais. Se voce tiver alguma pergunta sobre
     como o Handbook e organizado, por favor entre em contato com a
     lista de discussao do projeto de documentac,ao do FreeBSD.

     --------------------------------------------------------------

      6.3.1.1.1 Makefile

   O Makefile define algumas variaveis as quais afetam a forma como o
   fonte SGML e convertido para outros formatos, e lista os varios
   arquivos fonte que compoem o Handbook. Ele tambem inclui um
   arquivo padrao chamado doc.project.mk, o qual contem o restante do
   codigo responsavel por realizar a conversao dos documentos de um
   formato para outro.

     --------------------------------------------------------------

      6.3.1.1.2 book.xml

   Este e o documento de mais alto nivel do Handbook. Ele contem as  
   declarac,oes DOCTYPE do Handbook, assim como os elementos que
   descrevem a estrutura do Handbook.

   O book.xml utiliza entidades de parametro para carregar os
   arquivos com extensao .ent. Estes arquivos (descritos abaixo)
   definem as   entidades gerais as quais sao utilizadas ao longo de
   todo o Handbook.

     --------------------------------------------------------------

      6.3.1.1.3 directory/chapter.xml

   Cada capitulo do Handbook e armazenado em um arquivo chamado
   chapter.xml localizado em um diretorio separado dos outros
   capitulos. Cada diretorio e nomeado depois do valor do atributo id
   no elemento <chapter>.

   Por exemplo, se um dos arquivos de capitulos contiver:

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

   Entao ele sera chamado de chapter.xml e sera armazenadao no
   diretorio kernelconfig . Em geral, todo o conteudo do capitulo
   sera mantido neste arquivo.

   Quando a versao HTML do Handbook for produzida, sera gerado um
   arquivo kernelconfig.html. Isto ocorre devido ao valor do atributo
   id e nao esta relacionado ao nome do diretorio.

   Nas versoes anteriores do Handbook os arquivos eram armazenados no
   mesmo diretorio que o book.xml, e depois nomeados a partir do
   valor do atributo id presente no elemento <chapter> do arquivo.
   Agora, e possivel incluir imagens em cada capitulo. As imagens de
   cada capitulo do Handbook sao armazenadas dentro de
   share/images/books/handbook. Observe que as versoes localizadas
   destas imagens devem ser colocadas no mesmo diretorio com o codigo
   fonte SGML de cada capitulo. Colisoes de namespace sao
   inevitaveis, e e muito mais simples trabalhar com varios
   diretorios que contenham poucos arquivos em cada um, do que
   trabalhar com um diretorio que contenha muitos arquivos.

   Um exame rapido vai mostrar que existem muitos diretorios com um
   unico arquivo chapter.xml, incluindo basics/chapter.xml,
   introduction/chapter.xml, e printing/chapter.xml.

     Importante: Os capitulos e/ou diretorios nao devem ser nomeados
     de forma que reflitam sua ordem no Handbook. Esta ordenac,ao
     pode mudar com uma reorganizac,ao do conteudo do Handbook; este
     tipo de reorganizac,ao nao deve (geralmente) incluir a
     necessidade de renomear os arquivos (a menos que um capitulo
     inteiro esteja sendo promovido ou rebaixado na hierarquia).

   Cada arquivo chapter.xml nao sera um documento SGML completo. Em
   particular, eles nao terao as suas proprias linhas DOCTYPE no
   inicio do arquivo.

   Isto e uma infelicidade pois torna impossivel trata-los como
   arquivos SGML genericos e simplesmente converte-los para HTML,
   RTF, PS, e outros formatos da mesma forma que o Handbook principal
   e gerado. Isto ira forc,a-lo a reconstruir o Handbook inteiro
   sempre que voce desejar ver o efeito de uma alterac,ao realizada
   em apenas um capitulo.

     --------------------------------------------------------------

         Capitulo 7 O processo de construc,ao da documentac,ao

   A principal finalidade desse capitulo e explicar claramente como o
   processo de criac,ao da documentac,ao e organizado, e como fazer
   modificac,oes a este processo.

   Depois de finalizar a leitura deste capitulo voce devera:

     * Saber o que voce precisa para compilar a documentac,ao mantida
       pelo FDP, em adic,ao ao que foi mencionado no capitulo
       Ferramentas SGML.

     * Ser capaz de ler e entender as instruc,oes do make que estao
       presentes em cada documento Makefile, assim como ter uma visao
       geral do doc.project.mk.

     * Ser capaz de customizar o processo de compilac,ao usando
       variaveis e alvos do make.

     --------------------------------------------------------------

7.1 Ferramentas para construc,ao da documentac,ao do FreeBSD

   Aqui estao suas ferramentas. Use-as de todas as formas que puder.

     * A primeira ferramenta que voce precisara e o make, mais
       especificamente o Berkeley Make.

     * A construc,ao de pacotes no FreeBSD e executada pelo
       pkg_create. Se voce nao esta utilizando o FreeBSD, voce tera
       que viver sem o uso de pacotes, ou entao tera que compilar o
       codigo fonte voce mesmo.

     * O gzip e necessario para criar versoes compactadas do
       documento. O compressor bzip2 e os arquivos zip tambem sao
       suportados. O tar e suportado, e a construc,ao de pacotes
       necessita dele.

     * O install e o metodo padrao para instalar a documentac,ao.
       Entretanto, existem alternativas.

     Nota: E improvavel que voce tenha qualquer problema em localizar
     esses dois ultimos, eles estao sendo mencionados apenas para que
     a listagem fique completa.

     --------------------------------------------------------------

7.2 Entendendo Makefiles na arvore da documentac,ao

   Ha tres tipos principais de Makefiles na arvore do projeto de
   documentc,ao do FreeBSD.

     * Os   Makefiles de subdiretorio simplesmente passam comandos
       para os diretorios abaixo dele.

     * Os   Makefiles de documentac,ao descrevem o(s) documento(s)
       que deve(m) ser produzido(s) a partir deste diretorio.

     * Os   Make includes sao os responsaveis pela produc,ao do
       documento, e geralmente possuem o nome no formato doc.xxx.mk.

     --------------------------------------------------------------

  7.2.1 Makefiles de Subdiretorios

   Estes Makefiles 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 nao vazias definem as
   variaveis do make, SUBDIR, COMPAT_SYMLINK, e DOC_PREFIX.

   A primeira declarac,ao da variavel SUBDIR, tanto quanto a
   declarac,ao da variavel COMPAT_SYMLINK, mostra como atribuir um
   valor a uma variavel, sobrescrevendo qualquer valor anterior que a
   mesma contenha.

   A segunda declarac,ao da variavel SUBDIR mostra como um valor e
   adicionado ao valor atual de uma variavel. A variavel SUBDIR agora
   e composta por articles books.

   A declarac,ao do DOC_PREFIX mostra como um valor e atribuido para
   uma variavel, mas somente se ela ainda nao estiver definida. Isto
   e util se o DOC_PREFIX nao for onde este Makefile pensa que e - o
   usuario pode cancelar e fornecer o valor correto.

   Agora o que tudo isso significa? O SUBDIR lista quais
   subdiretorios abaixo do atual devem ser incluidos no processo de
   compilac,ao durante a gerac,ao do documento.

   O COMPAT_SYMLINK e especifico para compatibilizar os links
   simbolicos que ligam os idiomas a sua codificac,ao oficial (por
   exemplo o doc/en deve apontar para en_US.ISO-8859-1).

   O DOC_PREFIX e o caminho para a raiz da arvore do projeto de
   documentac,ao do FreeBSD. O qual nem sempre e facil de encontrar,
   e que tambem pode ser facilmente sobrescrito, para permitir
   flexibilidade. O .CURDIR e uma variavel interna do make que contem
   o caminho para o diretorio atual.

   A linha final inclui o arquivo principal do projeto de
   documentac,ao do FreeBSD, o doc.project.mk, ele e o responsavel
   por converter estas variaveis em instruc,oes de compilac,ao para
   uso do make.

     --------------------------------------------------------------

  7.2.2 Makefiles de Documentac,ao

   Estes Makefiles ajustam varias variaveis do make as quais
   descrevem como construir a documentac,ao contida em um determinado
   diretorio.

   Aqui esta 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 variavel MAINTAINER e uma muito importante. Esta variavel
   fornece a habilidade de reivindicar a propriedade sobre um
   documento no projeto de documentac,ao do FreeBSD, e por meio dela
   que voce recebe a responsabilidade de mante-lo.

   DOC e o nome (sem a extensao .xml) do principal documento criado
   por este diretorio. A variavel SRCS lista todos os arquivos
   individuais que compoem o documento. Ela tambem deve incluir os
   arquivos importantes, nos quais qualquer mudanc,a deve resultar em
   uma reconstruc,ao.

   O FORMATS indica os formatos nos quais o documento deve ser gerado
   por padrao. O INSTALL_COMPRESSED contem a lista padrao das
   tecnicas de compressao que devem ser usadas no documento depois
   que ele e gerado. A variavel INSTALL_ONLY_COMPRESS, nula por
   padrao, deve ser definida para um valor nao nulo apenas se voce
   desejar gerar exclusivamente a versao compactada do documento.

     Nota: Nos abordamos a atribuic,ao das variaveis opcionais na
     sec,ao anterior.

   Voce tambem ja deve estar familiarizado com a atribuic,ao da
   variavel DOC_PREFIX e com as instruc,oes de include.

     --------------------------------------------------------------

7.3 Includes do Make do projeto de documentac,ao do FreeBSD

   Isto e melhor explicado pela inspec,ao no codigo. Aqui estao os
   arquivos include do sistema:

     * O doc.project.mk e o principal arquivo include do projeto, que
       inclui todos os arquivos includes necessarios.

     * O doc.subdir.mk controla a navegac,ao na arvore de
       documentac,ao durante o processo de construc,ao e instalac,ao.

     * O doc.install.mk fornece as variaveis que afetam a propriedade
       e a instalac,ao de documentos.

     * O doc.docbook.mk e incluido se o DOCFORMAT for docbook e se a
       variavel DOC estiver definida.

     --------------------------------------------------------------

  7.3.1 doc.project.mk

   Por inspec,ao:

 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 Variaveis

   As variaveis DOCFORMAT e MAINTAINER serao atribuidas com valores
   padrao, se o valor das mesmas nao tiver sido definido no arquivo
   Makefile do documento.

   O PREFIX define o caminho no qual os aplicativos de construc,ao da
   documentac,ao estao instalados. Para uma instalac,ao normal
   atraves de pacotes e/ou ports, este caminho sera sempre
   /usr/local.

   A variavel PRI_LANG deve ser configurada para refletir o idioma e
   a codificac,ao nativa dos usuarios aos quais os documentos se
   destinam. O Ingles Americano (US English) e o padrao.

     Nota: A variavel PRI_LANG de maneira alguma afeta quais
     documentos serao, ou que poderao, ser compilados. Sua func,ao
     principal e criar links para os documentos referenciados com
     maior frequencia no diretorio raiz de instalac,ao da
     documentac,ao do FreeBSD.

     --------------------------------------------------------------

    7.3.1.2 Condicionais

   A linha .if defined(DOC) e um exemplo da condicional do make ,
   como em outros programas, define o comportamento se alguma
   condic,ao e verdadeira ou se e falsa. defined e uma func,ao que
   retorna se uma dada variavel esta definida ou nao.

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

   Os dois .endifs fecham as duas condicionais anteriores, marcando o
   fim da sua aplicac,ao.

     --------------------------------------------------------------

  7.3.2 doc.subdir.mk

   Este arquivo e muito longo para ser explicado por inspec,ao, voce
   deve ser capaz de interpreta-lo com o conhecimento adquirido nos
   capitulos anteriores, e com a pequena ajuda dada aqui.

     --------------------------------------------------------------

    7.3.2.1 Variaveis

     * SUBDIR e a lista de subdiretorios nos quais o processo de
       construc,ao deve ser executado.

     * ROOT_SYMLINKS sao os nomes dos diretorios que devem ser
       linkados para a raiz de instalac,ao do documento a partir da
       sua localizac,ao atual, se o idioma atual for o idioma
       primario (especificado por PRI_LANG).

     * O COMPAT_SYMLINK ja foi descrito na sec,ao Makefiles de
       subdiretorio .

     --------------------------------------------------------------

    7.3.2.2 Targets e Macros

   As dependencias sao descritas por target: dependencia1
   dependencia2 ... , nas quais, para construir o target, voce
   necessita primeiramente construir as dependencias informadas.

   Depois desta descric,ao, instruc,oes de como construir o target
   podem ser passadas, no caso do processo de conversao entre o
   target e estas dependencias nao tiver sido previamente definido,
   ou se esta conversao em particular nao for a mesma que a definida
   pelo metodo padrao de conversao.

   A dependencia 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 codigo acima, _SUBDIRUSE e agora uma macro, a qual ira executar
   determinados comandos quando for listada como dependencia.

   O que define esta macro a parte de outros targets? Basicamente,
   ela e executada apos as instruc,oes passadas no processo de
   construc,ao por ser uma dependencia para o mesmo, e ela nao
   configura o .TARGET, que e a variavel que contem o nome do target
   atual que esta sendo construido.

 clean: _SUBDIRUSE
         rm -f ${CLEANFILES}

   No codigo acima, o clean ira usar a macro _SUBDIRUSE depois de ter
   executado a instruc,ao rm -f ${CLEANFILES}. De fato, isto causa
   uma limpeza (clean) na arvore de diretorios, deletando os arquivos
   construidos enquanto vai descendo pelos subdiretorios, e nao
   quando vai na direc,ao oposta.

     --------------------------------------------------------------

      7.3.2.2.1 Targets fornecidos

     * install e package, ambos descem pela arvore de diretorios
       executando a sua versao real dentro dos subdiretorios.
       (realinstall e realpackage respectivamente).

     * O clean remove os arquivos criados pelo processo de
       compilac,ao (e tambem desce na arvore de diretorios). O
       cleandir faz a mesma coisa, e tambem remove o diretorio de
       objetos se este existir.

     --------------------------------------------------------------

    7.3.2.3 Mais Condicionais

     * exists e outra func,ao condicional que retorna verdadeiro se o
       arquivo informado existir.

     * empty retorna verdadeiro se a variavel informada estiver
       vazia.

     * target retorna verdadeiro se o target informado ainda nao
       existir.

     --------------------------------------------------------------

    7.3.2.4 Construc,ao de Looping no make (.for)

   O .for fornece uma maneira de repetir instruc,oes definidas para
   cada elemento separado por espac,o em uma variavel. Ele faz isso
   atribuindo uma variavel para conter o elemento atual da lista que
   esta 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 codigo acima, se SUBDIR estiver vazia, nenhuma ac,ao sera
   executada; se ela possuir um ou mais elementos, as instruc,oes
   entre o .for e o .endfor serao repetidas para cada elemento, com o
   entry sendo substituido com o valor do elemento atual.

     --------------------------------------------------------------

                          Capitulo 8 O Website

8.1 Preparac,ao

   Utilize um disco que tenha espac,o livre suficiente. Voce ira
   precisar de 200 MB a 500 MB, dependendo do metodo que escolher.
   Este espac,o ira abrigar as ferramentas SGML, um subconjunto da
   arvore svn, os arquivos temporarios de trabalho e as paginas web
   instaladas.

     Nota: Certifique-se que seus ports de documentac,ao estao
     atualizados! Quando na duvida, remova os ports antigos usando o
     comando pkg_delete(1) antes de instalar o port. Por exemplo, nos
     atualmente dependemos do jade-1.2, e se voce tem instalado o
     jade-1.1, por favor execute:

 # pkg_delete jade-1.1

     --------------------------------------------------------------

  8.1.1 Usando o svn

   O svn e necessario para se obter ("check out") os arquivos do doc/
   a partir do repositorio Subversion. O svn pode ser instalado com o
   pkg_add(1) ou a partir da colec,ao de Ports do FreeBSD,
   executando:

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

   Para obter os arquivos com o codigo fonte completo do web site do
   FreeBSD, execute:

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

     Dica: Se o comando svn nao estiver sendo executado pelo usuario
     root, certifique-se de que o diretorio /usr/build possui as
     permissoes adequadas ao usuario utilizado. Se nao for possivel
     alterar as permissoes, utilize um diretorio diferente para
     armazenar os arquivos do web site.

   Quando o svn terminar, a versao atual do website do FreeBSD estara
   disponivel em /usr/build. Se voce utilizou um diretorio alvo
   diferente, substitua o /usr/build apropriadamente ao longo do
   restante deste documento.

   E isso! Agora voce pode proceder com a gerac,ao do web site.

     --------------------------------------------------------------

8.2 Construa as paginas web do inicio

   Depois de ter completado os passos necessarios para obter os
   arquivos com o codigo fonte do website, voce estara pronto para
   iniciar a compilac,ao do web site. No nosso exemplo, o diretorio
   de compilac,ao e /usr/build e todos os arquivos necessarios ja
   estao disponiveis no mesmo.

    1. Va para o diretorio de compilac,ao:

 # cd /usr/build

    2. A compilac,ao do web site deve ser iniciada de dentro do
       diretorio en_US.ISO8859-1/htdocs executando o comando make(1)
       all , para criar as paginas web:

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

     --------------------------------------------------------------

8.3 Instalando as web pages em seu Web Server

    1. Se voce tiver saido do diretorio 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 variavel
       DESTDIR para o nome do diretorio no qual deseja instalar os
       arquivos. Eles serao instalados no $DESTDIR/data o qual deve
       estar configurado para ser o diretorio raiz do seu servidor
       web.

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

    3. Se voce ja instalou previamente as paginas web dentro deste
       mesmo diretorio o processo de instalac,ao nao ira remover
       nenhuma pagina web antiga ou desatualizada. Por exemplo, se
       voce compilar e instalar uma nova copia do web site todos os
       dias, o comando abaixo ira procurar e remover todos os
       arquivos que nao tenham sido alterados nos ultimos tres dias.

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

     --------------------------------------------------------------

8.4 Variaveis de ambiente

   ENGLISH_ONLY

           Se esta variavel estiver definida e nao for vazia, apenas
           a documentac,ao em Ingles sera compilada e instalada.
           Todas as traduc,oes serao ignoradas. Por exemplo:

 # make ENGLISH_ONLY=YES all install

           Se voce quiser desabilitar a variavel ENGLISH_ONLY e
           compilar todas as paginas, incluindo traduc,oes, basta
           definir a variavel ENGLISH_ONLY para um valor vazio:

 # make ENGLISH_ONLY="" all install clean

   WEB_ONLY

           Se esta variavel estiver definida e nao for vazia, apenas
           as paginas HTML do diretorio en_US.ISO8859-1/htdocs serao
           compiladas e instaladas. Todos os demais documentos do
           diretorio en_US.ISO8859-1 (Handbook, FAQ, Tutorais, etc)
           serao ignorados. Por exemplo:

 # make WEB_ONLY=YES all install

   WEB_LANG

           Se esta variavel estiver definida, apenas as paginas web
           no idioma especificado por ela serao compiladas e
           instaladas dentro do diretorio   /usr/build. Todos os
           demais idiomas serao 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 variavel estiver definida, o processo de
           compilac,ao nao fara o check out dos arquivos do ports do
           repositorio cvs. Ao inves disso, ele ira copiar os
           arquivos a partir do /usr/ports (ou do local definido na
           variavel PORTSBASE).

   WEB_ONLY, WEB_LANG, ENGLISH_ONLY e NOPORTSCVS sao variaveis do
   make. Voce pode definir estas variaveis no /etc/make.conf, no
   Makefile.inc, ou ainda como variaveis de ambiente na linha de
   comando ou nos arquivos de inicializac,ao do seu shell.

     --------------------------------------------------------------

                         Capitulo 9 Traduc,oes

   Este e o FAQ para as pessoas que traduzem a documentac,ao do
   FreeBSD (FAQ, Manual do FreeBSD, tutoriais, paginas de manual e
   outros) para diferentes linguas.

   Ele e fortemente baseado na traduc,ao do FAQ do Projeto Alemao de
   Documentac,ao do FreeBSD, originalmente escrito por Frank Gru:nder
   <elwood@mc5sys.in-berlin.de> e traduzido novamente para o ingles
   por Bernd Warken <bwarken@mayn.de>.

   Este FAQ e mantido pela Equipe de Engenharia de Documentac,ao
   <doceng@FreeBSD.org>.

   9.1. Porque um FAQ?

   9.2. O que significa i18n e l10n

   9.3. Existe uma lista de discussao para tradutores?

   9.4. Sao necessarios mais tradutores?

   9.5. Quais idiomas eu preciso conhecer?

   9.6. Quais softwares eu preciso conhecer?

   9.7. Como eu fac,o para descobrir se ja existem outras pessoas
   traduzindo documentos para o meu idioma?

   9.8. Ninguem mais esta traduzindo para o meu idioma. O que eu
   fac,o?

   9.9. Eu ja tenho alguns documentos traduzidos, para onde eu devo
   envia-los?

   9.10. Eu sou a unica pessoa trabalhando na traduc,ao para este
   idioma, como fac,o para enviar meus documentos?

   9.11. Posso incluir uma lingua ou um texto especifico do pais em
   minha traduc,ao?

   9.12. Como os caracteres especificos do idioma podem ser
   incluidos?

   9.13. Dirigindo-se ao leitor

   9.14. Eu preciso colocar alguma informac,ao adicional nas minhas
   traduc,oes?

   9.1. Porque um FAQ?

   Mais e mais pessoas estao se juntando `a lista de discussao
   FreeBSD-doc e estao se oferecendo para traduzir a documentac,ao do
   FreeBSD para outras linguas. Este FAQ visa responder as suas
   perguntas, de forma que eles possam iniciar a traduc,ao da
   documentac,ao o quanto antes.

   9.2. O que significa i18n e l10n

   i18n significa internacionalizac,ao e l10n significa
   locallizac,ao. Sao apenas abreviac,oes.

   i18n pode ser lido como "i" seguido por 18 letras, seguidas por
   "n". Similarmente, l10n e "l" seguido por 10 letras, seguidas por
   "n".

   9.3. Existe uma lista de discussao para tradutores?

   Sim. Os diferentes grupos de traduc,ao possuem as suas proprias
   listas de discussao. A   lista dos projetos de traduc,ao possui
   maiores informac,oes sobre as listas de discussao e sobre os web
   sites mantidos por cada um dos projetos de traduc,ao.

   9.4. Sao necessarios mais tradutores?

   Sim. Quanto maior o numero de pessoas trabalhando na traduc,ao,
   mais rapidamente ela sera finalizada, e mais rapidamente as
   mudanc,as na documentac,ao em Ingles serao refletidas nos
   documentos traduzidos.

   Voce nao precisa ser um tradutor profissional para poder ajudar.

   9.5. Quais idiomas eu preciso conhecer?

   Idealmente, voce devera possuir bons conhecimentos de Ingles
   escrito, e obviamente necessitara ser fluente na lingua para a
   qual estiver traduzindo.

   O conhecimento do idioma Ingles nao e estritamente necessario. Por
   exemplo, voce poderia fazer uma traduc,ao do FAQ para o idioma
   Hungaro a partir da versao em Espanhol do documento.

   9.6. Quais softwares eu preciso conhecer?

   E fortemente recomendado que voce mantenha uma copia local do
   repositorio Subversion do FreeBSD (ao menos da parte referente a
   documentac,ao). Isto pode ser feito executando o comando:

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

     Nota: Voce ira precisar ter o devel/subversion instalado.

   Voce devera ter conhecimentos basicos de svn. Ele permitira que
   voce veja o que mudou entre as diferentes versoes dos arquivos que
   compoem a documentac,ao.

   Por exemplo, para ver as diferenc,as entre as revisoes 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 fac,o para descobrir se ja existem outras pessoas
   traduzindo documentos para o meu idioma?

   A pagina do Projeto de Traduc,ao da Documentac,ao lista os
   trabalhos de traduc,ao que sao conhecidos atualmente. Se outros ja
   estao trabalhando na traduc,ao da documentac,ao para o seu idioma,
   por favor, nao duplique os esforc,os. Ao inves disso, fac,a
   contato com o grupo para ver como pode ajuda-los.

   Se nao existir nenhum projeto de traduc,ao para o seu idioma
   listado nesta pagina, envie uma mensagem para lista de discussao
   do projeto de documentac,ao do FreeBSD para o caso de alguem estar
   pensando em fazer a traduc,ao, mas ainda nao tiver anunciado nada.

   9.8. Ninguem mais esta traduzindo para o meu idioma. O que eu
   fac,o?

   Parabes, voce acabou de comec,ar o "FreeBSD   sua-lingua-aqui
   Documentation Translation Project". Bem vindo a bordo.

   Primeiro, pense se voce tera o tempo necessario. Uma vez que voce
   e a unica pessoa trabalhando no seu idioma no momento, sera sua a
   responsabilidade de publicar o seu trabalho e coordenar qualquer
   voluntario que queira ajuda-lo.

   Escreva um email para a lista de discussao do Projeto de
   Documentac,ao, anunciando que voce ira traduzir a documentac,ao,
   assim a pagina do Projeto de Traduc,oes de Documentac,ao podera
   ser atualizada.

   Se ja existir alguem em seu pais provendo o espelhamento de
   servic,os do FreeBSD, voce deve contacta-lo e perguntar se voce
   pode ter algum espac,o web para seu projeto, e se possivel um
   enderec,o de email ou mesmo um servic,o de lista de discussao.

   Entao escolha um documento e comece a traduzir. E melhor comec,ar
   com algo razoavelmente pequeno como FAQ ou um dos tutoriais.

   9.9. Eu ja tenho alguns documentos traduzidos, para onde eu devo
   envia-los?

   Isso depende. Se voce ja esta trabalhando com uma equipe de
   traduc,ao (tal como a equipe japonesa, ou a equipe alema) entao
   ela tera seus proprios procedimentos para manipular a
   documentac,ao submetida, e estes serao descritos em seus web
   sites.

   Se voce for a unica pessoa trabalhando em um determinado idioma
   (ou se voce e o responsavel pelo projeto de traduc,ao e quer
   submeter suas mudanc,as de volta para o projeto FreeBSD) entao
   voce deve enviar sua traduc,ao ao Projeto FreBSD (veja pergunta
   seguinte).

   9.10. Eu sou a unica pessoa trabalhando na traduc,ao para este
   idioma, como fac,o para enviar meus documentos?

   ou

   Nos somos uma equipe de traduc,ao, e queremos submeter os
   documentos que nossos membros traduziram para nos.

   Primeiramente certifique-se que sua traduc,ao esta organizada
   corretamente. Isto significa que ela deve se encaixar na arvore de
   diretorios corrente e ser processada de maneira correta.

   Atualmente a documentac,ao do FreeBSD e armazenada em um diretorio
   de nivel superior chamado head/. Os diretorios abaixo deste sao
   nomeados de acordo com o codigo do idioma em que eles estao
   escritos, definidos na ISO639 (/usr/share/misc/iso639 em uma
   versao do FreeBSD mais nova que 20 de janeiro de 1999).

   Se seu idioma puder ser codificado de maneiras diferentes (por
   exemplo, Chines) entao deverao existir outros diretorios abaixo
   deste, um para cada formato que voce tenha forncecido.

   Finalmente voce deve ter diretorios para cada original.

   Por exemplo, em uma hipotetica traduc,ao para o Sueco ficaria
   assim:

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

   sv_SE.ISO8859-1 e o nome da traduc,ao, na forma lang.encoding.
   Repare nos dois Makefiles que serao usados para construir a
   documentac,ao.

   Use tar(1) e gzip(1) para compactar sua documentac,ao, 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 voce nao
   tiver acesso ao seu proprio espac,o web (talvez seu ISP nao
   disponibilize um), entao voce pode enviar um email para Equipe de
   Engenharia de Documentac,ao <doceng@FreeBSD.org>, e combinar de
   enviar os arquivos por email quando for conveniente.

   De qualquer forma, voce deve usar o send-pr(1) para enviar um
   relatorio indicando que voce submeteu a documentac,ao. Seria muito
   util se voce conseguisse outras pessoas para revisar a sua
   traduc,ao antes de submete-la, uma vez que e improvavel que a
   pessoa que ira disponibiliza-la no repositorio seja fluente no seu
   idoma.

   Alguem (provavelmente o gerente do projeto de documentac,ao,
   atualmente Equipe de Engenharia de Documentac,ao
   <doceng@FreeBSD.org>) ira examinar os seus arquivos e ira
   confirmar se eles compilam sem erros. Em especial, os seguintes
   items serao verificados:

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

    2. O make all no diretorio sv_SE.ISO8859-1 funciona corretamente?

    3. O make install funciona corretamente?

   Se houver algum problema, a pessoa que estiver examinando a sua
   submissao ira entrar em contato para que voce fac,a as correc,oes.

   Se nao exitir nenhum problema, os seus documentos traduzidos serao
   disponibilizados no repositorio o quanto antes.

   9.11. Posso incluir uma lingua ou um texto especifico do pais em
   minha traduc,ao?

   Nos preferimos que voce nao fac,a isso.

   Por exemplo, suponha que voce esteja traduzindo o Manual do
   FreeBSD para o Coreano e queira incluir uma sec,ao sobre
   varejistas na Coreia em seu Manual do FreeBSD.

   Nao ha razao pela qual esta informac,ao nao deva estar nas versoes
   em Ingles (ou Alemao, ou Espanhol, ou Japonas, ou ...). E possivel
   que uma pessoa que fale Ingles na Coreia possa tentar obter uma
   copia do FreeBSD enquanto esteja ali. Isso tambem ajuda a aumentar
   a presenc,a perceptivel do FreeBSD ao redor do mundo, o que nao e
   uma coisa ruim.

   Se voce tem uma informac,ao especifica do seu pais, por favor,
   submeta ela para alterac,ao no Manual do FreeBSD em Ingles (usando
   send-pr(1)) e depois traduza novamente para sua lingua no Manual
   do FreeBSD traduzido.

   Obrigado.

   9.12. Como os caracteres especificos do idioma podem ser
   incluidos?

   Caracteres nao-ASCII devem ser incluidos na documentac,ao usando
   entidades SGML.

   Resumidamente, eles sao um ``e'' comercial (&), o nome da entidade
   e um ponto-e-virgula (;).

   Os nomes de entidades estao definidos no ISO8879, que esta na
   arvore do ports como textproc/iso8879.

   Alguns exemplos Incluem

   Entidade: &eacute;

   Aparencia: e

   Descric,ao: "e" minusculo com acento agudo

   Entidade: &Eacute;

   Aparencia: E

   Descric,ao: "E" maiusculo com acento agudo

   Entidade: &uuml;

   Aparencia: u:

   Descric,ao: "u" minusculo com trema

   Depois que voce instalar o pacote iso8879, os arquivos em
   /usr/local/share/xml/iso8879 conterao a lista completa.

   9.13. Dirigindo-se ao leitor

   Nos documentos em Ingles, o leitor e tratado por "voce", nao ha
   distinc,ao entre formal/informal como existe em alguns idiomas.

   Se voce estiver traduzindo para um idioma que tenha esta
   distinc,ao, use qualquer forma que normalmente e usada em outras
   documentac,oes tecnicas. Na duvida, use a forma mais polida.

   9.14. Eu preciso colocar alguma informac,ao adicional nas minhas
   traduc,oes?

   Sim.

   O cabec,alho da versao em Ingles de cada documento sera 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 incluira a linha
   $FreeBSD$ e a frase The FreeBSD Documentation Project. Note que o
   $FreeBSD e inserido pelo svn, portanto ele deve estar vazio
   (apenas $FreeBSD$) para novos documentos.

   O seu documento traduzido deve incluir sua propria linha
   $FreeBSD$, e voce deve mudar a linha FreeBSD Documentation Project
   para The FreeBSD language Documentation Project.

   Voce deve ainda adicionar uma terceira linha que indicara qual
   revisao do texto em ingles o texto e baseado.

   Assim, a versao em Espanhol deste arquivo pode comec,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
      -->

     --------------------------------------------------------------

                     Capitulo 10 Estilo de Escrita

   A fim de promover a consistencia entre os inumeros autores da
   documentac,ao do FreeBSD, foram criadas algumas diretrizes para
   que os autores sigam.

   Use a Grafia Inglesa Americana

           Existem diversas variantes do ingles, com grafias
           diferentes para a mesma palavra. Onde as grafias diferem,
           use a variante inglesa americana. Por exemplo: "color",
           nao "colour", "rationalize", nao "rationalise", e assim
           por diante.

             Nota: O uso do Ingles Britanico pode ser aceito para a
             contribuic,ao de artigos, contudo a ortografia devera
             ser consistente ao longo de todo o documento. Os outros
             documentos, tais como livros, web sites, paginas de
             manual, etc. deverao utilizar o Ingles Americano.

   Nao use contrac,oes

           Nao use contrac,oes. Soletre sempre a frase por completo.
           A frase " Don't use contractions " seria errada.

           Evite fazer uso das contrac,oes para obter um tom mais
           formal, sera mais preciso, e ligeiramente mais facil para
           os tradutores.

   Use a virgula de serie

           Em uma lista de artigos dentro de um paragrafo, separe
           cada artigo do outro com uma virgula. Separe o ultimo
           artigo do outro com uma virgula e a palavra "e".

           Por o exemplo, observe o seguinte:

             Esta e uma lista de um, dois e tres artigos.

           Isto e uma lista de tres artigos, "um", "dois", e "tres",
           ou de uma lista de dois artigos, "um" e "dois e tres"?

           E melhor ser explicito e incluir uma virgula de serie:

             Esta e uma lista de um, dois, e tres artigos.

   Evite frases redundantes

           Tente nao usar frases redundantes. No detalhe, "o
           comando", "o arquivo", e "o comando man" sao provavelmente
           redundantes.

           Estes dois exemplos mostram isto para comandos. O segundo
           exemplo e 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 e preferido.

           ... no arquivo /etc/rc.local...

           ... no /etc/rc.local...

           Estes dois exemplos mostram isto para referencias aos
           manuais. O segundo exemplo e preferido (o segundo exemplo
           usa <citerefentry>).

           Veja o man csh para maiores informac,oes

           veja o csh(1)

   Dois espac,os no final das sentenc,as.

           Use sempre dois espac,os no fim das sentenc,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
           periodo, nem sempre denota uma sentenc,a nova,
           especialmente na grafia de nomes. "Jordan K. Hubbard" e um
           bom exemplo; tem um H em caixa alta depois de um periodo e
           um espac,o, e nao ha certamente uma sentenc,a nova la.

   Para maiores informac,oes sobre estilo de escrita, consulte  
   Elementos de Estilo, por William Strunk.

     --------------------------------------------------------------

10.1 Guia de Estilo

   Para manter o codigo fonte da documentac,ao consistente quando
   muitas pessoas diferentes o estao editando, por favor siga estas
   convenc,oes de estilo.

     --------------------------------------------------------------

  10.1.1 Caixa de Letra (Maiuscula/Minuscula)

   As tags devem ser utilizadas em caixa baixa, <para>, nao <PARA>.

   O texto que aparece em contextos do SGML e escrito geralmente em
   caixa alta, <!ENTITY...>, e <!DOCTYPE...>, nao <!entity...> e
   <!doctype...>.

     --------------------------------------------------------------

  10.1.2 Acronimos

   Um acronimo normalmente deve ser soletrado na primeira vez que ele
   aparecer em um livro, como por exemplo: "Network Time Protocol
   (NTP)". Depois que um acronimo for definido, voce deveria passar a
   utilizar apenas ele (e nao o termo completo, a nao ser que isso
   fac,a mais sentido contextualmente). Normalmente um acronimo e
   definido uma unica vez por livro. Mas se voce preferir, voce
   tambem pode defini-lo quando ele aparecer pela primeira vez em
   cada capitulo.

   Nas tres primeiras vezes que um acronimo for utilizado ele deve
   ser destacado com a tag <acronym> utilizando o atributo role
   setado com o termo completo como seu valor. Isto ira permitir que
   o link para o glossario seja criado, e habilitara um mouseover que
   quando renderizado ira exibir o termo completo.

     --------------------------------------------------------------

  10.1.3 Identac,ao

   Cada arquivo comec,a com a identac,ao ajustada na coluna 0,
   independentemente do nivel de identac,ao do arquivo que pode vir a
   inclui-lo.

   As tags de abertura aumentam o nivel de identac,ao em 2 espac,os,
   as tags de fechamento diminuem o nivel de identac,ao em 2
   espac,os. Blocos de 8 espac,os no comec,o de uma linha devem ser
   subistituidos por um Tab. Nao use espac,os na frente dos Tabs, e
   nao adicione espac,os em branco no final de uma linha. O conteudo
   dentro de um elemento deve ser identado por dois espac,os caso ele
   ocupe mais de uma linha.

   Por exemplo, o codigo para esta sec,ao 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 voce usar o Emacs ou XEmacs para editar os arquivos o sgml-mode
   sera carregado automaticamente, e as variaveis locais do Emacs ao
   final de cada arquivo devem reforc,ar estes estilos.

   Os usuarios 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 Espac,amento de Tags

   Tags que comec,am na mesma identac,ao que um Tag precedente devem
   ser separados por uma linha em branco, e aqueles que nao estao na
   mesma identac,ao que um Tag precedente nao, 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 terao sempre algum Tag adicional
   dentro dele, e que nao fazem exame dos dados eles mesmos, estarao
   sempre sozinhos em uma linha.

   Tags tais como <para> e <term> nao necessitam outros Tags para
   conter caracteres normais, e o seu conteudo comec,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 obvio ao misturar estes Tags.

   Quando um Tag de abertura que nao pode conter caracteres normais e
   utilizado logo apos 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 nao pode conter caracteres
   normais se fecha, eles podem coexistir na mesma linha.

     --------------------------------------------------------------

  10.1.5 Mudanc,as nos espac,os em branco.

   Ao enviar mudanc,as, nao envie mudanc,as de conteudo ao mesmo
   tempo que mudanc,as no formato.

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

   Por exemplo, se voce adicionar duas sentenc,as a um paragrafo, de
   forma que o comprimento das linhas no mesmo agora excedem 80
   colunas, envie sua mudanc,a sem corrigir o comprimento da linha.
   Ajuste entao a quebra de linha e envie uma segunda mudanc,a. Na
   mensagem de commit da segunda mudanc,a, deixe claro que se trata
   apenas de um ajuste de formatac,ao, e que a equipe da traduc,ao
   pode ignora-la.

     --------------------------------------------------------------

  10.1.6 Nonbreaking space

   Evite as quebras de linha nos locais onde elas ficarem feias ou
   onde dificultarem a compreensao de uma sentenc,a. As quebras de
   linha dependem da largura do meio de saida escolhido. Em
   particular, visualizar um documento em HTML com um navegador em
   modo texto pode conduzir a paragrafos 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 numeros e suas unidades:

 57600&nbsp;bps

     * Entre os nomes dos programas e os seus numeros de versao:

 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 e uma pequena lista das palavras com a grafia da
   maneira que deve ser usada no projeto da documentac,ao do FreeBSD.
   Se a palavra que voce esta procurando nao 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

     --------------------------------------------------------------

                Capitulo 11 Usando sgml-mode com o Emacs

   As versoes recentes do Emacs ou XEmacs (disponivel na colec,ao dos
   ports) contem um pacote muito util chamado PSGML (ele pode ser
   instalado pelo editors/psgml). Ele e automaticamente invocado
   quando um arquivo com a extensao .xml e carregado, ou executando
   M-x sgml-mode, ele e 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 facil.

   C-c C-e

           Executa o sgml-insert-element. Voce sera questionado sobre
           o nome do elemento que deseja inserir no ponto atual. Voce
           pode usar a tecla TAB para completar o elemento. Os
           elementos que sao invalidos no ponto atual nao serao
           permitidos.

           As tags de abertura e de fechamento para o elemento serao
           inseridas. Se o elemento contiver outro, obrigatorios, os
           elementos destes tambem serao inseridos.

   C-c =

           Executa o sgml-change-element-name. Coloque o cursor
           dentro de um elemento e execute este comando. Voce sera
           questionado sobre o nome do elemento para o qual voce
           deseja mudar. As tags de abertura e de fechamento do
           elemento atual serao alterados para o novo elemento.

   C-c C-r

           Executa o sgml-tag-region. Selecione algum texto
           (posicione o cursor no comec,o do texto, de C-espac,o,
           agora posicione o cursor no final do texto, de C-espac,o)
           e execute entao este comando. Voce sera questionado sobre
           o nome do elemento que deseja inserir. Este elemento sera
           inserido entao imediatamente antes e depois da regiao
           marcada.

   C-c -

           Executa o sgml-untag-element. Coloque o cursor dentro da
           tag de abertura ou de fechamento do elemento que voce quer
           remover, e execute este comando. As tags de abertura ou de
           fechamento do elemento serao removidas.

   C-c C-q

           Executa o sgml-fill-element. Ira reformatar recursivamente
           o elemento atual. A reformatac,ao afetara o conteudo em
           que os espac,os em branco sao 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
           contem uma lista de todos os atributos e valores atuais
           para o elemento mais proximo. Use a tecla TAB para navegar
           entre os atributos, utilize C-k para remover um valor
           existente e para substitui-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. Voce sera questionado se deseja
           salvar o documento atual (se necessario) e entao executa
           uma validac,ao do SGML. A saida da validac,ao e capturada
           em um novo buffer, e voce podera entao navegar de um foco
           de problema para outro, corrigindo os erros de marcac,ao
           durante este processo.

   C-c /

           Executa sgml-insert-end-tag. Insere a tag de fechamento
           para o elemento atual que esta aberto.

   Sem duvida ha outras func,oes uteis desta modalidade, mas estas
   sao as que voce ira utilizar com mais frequencia.

   Voce tambem pode usar as seguintes entradas no .emacs para ajustar
   o espac,amento apropriado, a identac,ao, e a largura de coluna
   para trabalhar com o projeto de documentac,ao.

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

     --------------------------------------------------------------

                        Capitulo 12 Veja tambem

   Este documento nao e deliberadamente uma discussao exaustiva sobre
   SGML, DTDs, ou do projeto de documentac,ao do FreeBSD. Para obter
   maiores informac,oes, sugerimos que voce visite os seguintes
   sitios web.

     --------------------------------------------------------------

12.1 Projeto de documentac,ao do FreeBSD

     * Paginas web do Projeto de documentac,ao do FreeBSD

     * Manual do FreeBSD

     --------------------------------------------------------------

12.2 SGML

     * Pagina web sobre SGML/XML, referencias detalhadas sobre SGML

     * Uma breve introduc,ao ao SGML

     --------------------------------------------------------------

12.3 HTML

     * Consorcio World Wide Web

     * As especificac,oes do HTML 4.0

     --------------------------------------------------------------

12.4 DocBook

     * O comite tecnico do DocBook, responsaveis pelo DTD DocBook.

     * DocBook: O guia definitivo, documentac,ao online para o DTD
       DocBook.

     * Repositorio aberto de DocBook contem folhas de estilo DSSSL e
       outros recursos para pessoas que utilizam DocBook.

     --------------------------------------------------------------

12.5 Projeto de documentac,ao do Linux

     * Paginas web do projeto de documentac,ao do Linux

     --------------------------------------------------------------

                          Apendice A. Exemplos

   Este apendice contem arquivos SGML de exemplo e linhas de comando
   que voce pode utilizar para converte-los de um formato para outro.
   Se voce instalou com sucesso as ferramentas do Projeto de
   Documentac,ao, entao voce sera capaz de utilizar estes exemplos
   imediatamente.

   Estes exemplos nao sao exaustivos - eles nao contem todos os
   elementos que voce pode utilizar, particularmente para a capa do
   seu documento. Para maiores exemplos de marcac,ao DocBook voce
   deve examinar o codigo SGML deste e de outros documentos,
   disponiveis no repositorio doc do svn, ou disponiveis online no
   enderec,o http://svnweb.FreeBSD.org/doc/.

   Para evitar confusao, estes exemplos utilizam a especificac,ao
   DocBook 4.1 DTD sem nenhuma extensao particular adicionada pelo
   FreeBSD. Eles tambem utilizam as folhas de estilo padroes
   distribuidas pelo Norm Walsh, sem nenhuma customizac,ao feita nas
   mesmas pelo Projeto de Documentac,ao do FreeBSD. Isto os torna
   mais uteis como exemplos genericos de marcac,ao 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 sumario ele deve ser colocado aqui.</para>
     </abstract>
   </bookinfo>

   <preface>
     <title>Prefacio</title>

     <para>Seu livro pode ter um prefacio, se este for o caso, ele deve
       ser colocado aqui.</para>
   </preface>
      
   <chapter>
     <title>Meu primeiro capitulo</title>

     <para>Este e o primeiro capitulo do meu livro.</para>

     <sect1>
       <title>Minha primeira sec,ao</title>

       <para>Esta e a primeira sec,ao 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 sumario ele deve ser colocado aqui.</para>
     </abstract>
   </articleinfo>

   <sect1>
     <title>Minha primeira sec,ao</title>

     <para>Esta e a primeira sec,ao do meu artigo.</para>

     <sect2>
       <title>Minha primeira subsec,ao</title>

       <para>Esta e a primeira subsec,ao do meu artigo.</para>
     </sect2>   
   </sect1>
 </article>

     --------------------------------------------------------------

A.3 Produzindo saidas formatadas

   Esta sec,ao assume que voce ja instalou os softwares listados no
   port textproc/docproj, seja via meta-port ou manualmente. Alem
   disso, ela tambem assume que os seus softwares estao instalados em
   subdiretorios sob o /usr/local/, e que os diretorios nos quais os
   binarios foram instalados, estao 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 unico grande
   arquivo)

 % jade -V nochunks \  (1)
     -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ (2)
     -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 \(3)
     -t sgml (4) file.xml > file.html (5)

   (1)
           Especifique o parametro nochunks para as folhas de estilo,
           forc,ando que todos os outputs sejam escritos para a saida
           padrao (STDOUT) (utilizando as folhas de estilo do Norm
           Walsh).
   (2)
           Especifique os catalogos que o Jade tera que processar.
           Tres catalogos sao requeridos. O primeiro e o catalogo que
           contem as informac,oes sobre as folhas de estilo DSSSL. O
           segundo contem informac,oes sobre o DTD DockBook. E o
           terceiro contem informac,oes especificas para o Jade.
   (3)
           Especifique o caminho completo das folhas de estilo DSSSL
           as quais o Jade ira utilizar quando estiver processando o
           documento.
   (4)
           Instrua o Jade para realizar uma transformac,ao de uma DTD
           para outra. Neste caso, a entrada sera transformada de um
           DTD DocBook para um DTD HTML.
   (5)
           Especifique o arquivo que o Jade deve processar, e
           redirecione a saida para o arquivo .html desejado.

   Exemplo A-4. Convertendo de DocBook para HTML (varios arquivos
   pequenos)

 % jade \
     -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ (1)
     -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 \(2)
     -t sgml (3) file.xml (4)

   (1)
           Especifique os catalogos os quais o Jade tera que
           processar. Tres catalogos sao requeridos. O primeiro e o
           catalogo o qual contem as informac,oes sobre as folhas de
           estilo DSSSL. O segundo contem informac,oes sobre o DTD
           DocBook. O terceiro contem informac,oes especificas para o
           Jade.
   (2)
           Especifique o caminho completo da folha de estilo DSSSL a
           qual o Jade ira utilizar quando estiver processando o
           documento.
   (3)
           Instrua o Jade para realizar a transformac,ao de uma DTD
           para outra. Neste caso, a entrada sera transformada de um
           DTD DocBook para um DTD HTML.
   (4)
           Especifique o arquivo que o Jade deve processar. A folha
           de estilo determina como os arquivos HTML individuais
           serao nomeados, inclusive o nome do arquivo "raiz" (e o
           arquivo que contem o inicio do documento).

   Este exemplo pode continuar gerando apenas um unico arquivo HTML,
   dependera da estrutura do documento que voce estiver processando e
   das regras da folha de estilo selecionada, para divisao 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 \ (1)
     -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ (2)
     -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 \(3)
     -t tex (4) file.xml

   (1)
           Customize as folhas de estilo para utilizar as varias
           opc,oes existentes, especificas para a produc,ao de saidas
           TeX.
   (2)
           Especifique os catalogos os quais o Jade tera que
           processar. Tres catalogos sao requeridos. O primeiro e o
           catalogo o qual contem as informac,oes sobre as folhas de
           estilo DSSSL. O segundo contem informac,oes sobre o DTD
           DocBook. O terceiro contem informac,oes especificas para o
           Jade.
   (3)
           Especifique o caminho completo da folha de estilo DSSSL a
           qual o Jade ira utilizar quando estiver processando o
           documento.
   (4)
           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

   Voce tem que executar o tex pelo menos tres vezes. A primeira
   execuc,ao ira processar o documento, e determinar as areas do
   documento que sao referenciadas a partir de outras partes do
   documento, para uso na indexac,ao, etc.

   Nao fique alarmado se voce visualizar mensagens de alertas tais
   como "LaTeX Warning: Reference `136' on page 5 undefined on input
   line 728." neste momento.

   A segunda execuc,ao reprocessa o documento agora que certas pec,as
   de informac,ao sao conhecidas (tais como o numero de paginas do
   documento). Isto permite indexar as entradas e estabelecer as
   outras referencias cruzadas.

   A terceira execuc,ao ira realizar a limpeza final necessaria no
   arquivo

   O output deste estagio sera 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 e identica 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 ja tiver sido gerado, voce deve executar o
   pdfTeX utilizando o pacote de macros &pdfjadetex.

 % pdftex "&pdfjadetex" file.tex

   De novo, execute este comando tres vezes.

   Ele ira gerar um arquivo .pdf, o qual nao necessita de nenhum
   processamento adicional.

  Notas

   [1] Entidades de Parametro utilizam o simbolo de Porcentagem.      
   [2] Isto e 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 historia sobre este assunto pode ser encontrada em 
       http://www.oasis-open.org/docbook/intro.shtml#d0e41.           
   [4] Ha outros tipos de elementos de lista no DocBook, mas nao      
       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 documentac,ao antes de contatar
                        <questions@FreeBSD.org>.
       Para perguntas sobre esta documentac,ao, envie e-mail para
                           <doc@FreeBSD.org>.
