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

  Projeto de documentac,ao do FreeBSD

   Revision: 43184

   Copyright (c) 1998-2009 DocEng

   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.

  Important:

   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.

  Important:

   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.

   Last modified on 2013-11-13 07:52:45 by hrs.
   Abstract

   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.

   [ Documento HTML em partes / Documento HTML completo ]

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

   Table of Contents

   Prefacio

                1. Prompt do interpretador de comandos (shell)

                2. Convenc,oes Tipograficas

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

                4. 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.2. Ferramentas Opcionais

   3. SGML Primer

                3.1. Visao Geral

                3.2. Elementos, tags, e atributos

                3.3. A declarac,ao DOCTYPE

                3.4. Voltando para o SGML

                3.5. Comentarios

                3.6. Entidades

                3.7. Utilizando entidades para incluir arquivos

                3.8. Sessoes marcadas

                3.9. Conclusao

   4. Marcac,ao SGML

                4.1. HTML

                4.2. DocBook

   5. * Folhas de Estilo

                5.1. * DSSSL

                5.2. CSS

   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

   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.3. Includes do Make do projeto de documentac,ao do FreeBSD

   8. O Website

                8.1. Preparac,ao

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

   Index

   List of Examples

   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

   Table of Contents

   1. Prompt do interpretador de comandos (shell)

   2. Convenc,oes Tipograficas

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

   4. Agradecimentos

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

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

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

   Ao longo do texto aparecerao notas, avisos e exemplos.

  Note:

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

  Tip:

   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.

  Important:

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

  Warning:

   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.

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

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

                             Chapter 1. Visao Geral

   Table of Contents

   1.1. Conjunto de Documentac,ao do FreeBSD

   1.2. Antes de voce iniciar

   1.3. Inicio Rapido

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

                             Chapter 2. Ferramentas

   Table of Contents

   2.1. Ferramentas Obrigatorias

   2.2. Ferramentas Opcionais

   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.

  Important:

           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.

                             Chapter 3. SGML Primer

   Table of Contents

   3.1. Visao Geral

   3.2. Elementos, tags, e atributos

   3.3. A declarac,ao DOCTYPE

   3.4. Voltando para o SGML

   3.5. Comentarios

   3.6. Entidades

   3.7. Utilizando entidades para incluir arquivos

   3.8. Sessoes marcadas

   3.9. Conclusao

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

  Note:

   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.

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

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

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

  Important:

   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.

   Example 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 (').

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

       Example 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

       Example 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      
       5      indica uma mensagem informativa, W e para 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.                                            
       [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)

  Note:

   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 Section 3.4, "Voltando para o
   SGML", 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.

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

   Example 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 &amp;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.

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

   Example 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">
 ]>

   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>

   <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: &amp;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.

   Example 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">
 ]>

 <html>

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

  Warning:

   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.

   Example 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" [
 <!ENTITY % chapters SYSTEM "chapters.ent">
 %chapters;
 ]>

 <html>
   &amp;chapter.1;
   &amp;chapter.2;
   &amp;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: &amp;version;</p>

     &amp;para1;
     &amp;para2;
     &amp;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.

  Note:

   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: &amp;version;</p>

     &amp;para1;
     &amp;para2;
     &amp;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".

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

  Note:

   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.

   Example 3.15. Utilizando uma sessao marcada como CDATA

 <para>Aqui esta um exemplo de como voce incluiria algum texto que contenha muitos
   simbolos <literal><</literal> e <literal>></literal>.
   O texto de exemplo e um fragmento de HTML. 
   O texto circunvizinho (<para> e <programlisting>) e do
   DocBook.</para>
          
 <programlisting>
   <![CDATA[>![RCDATA[
     <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.

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

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

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

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

                           Chapter 4. Marcac,ao SGML

   Table of Contents

   4.1. HTML

   4.2. DocBook

   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.

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

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

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

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

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

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

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

   Example 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

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

   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

  Note:

   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.

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

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

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

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

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

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

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

   Example 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

  Note:

   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.

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

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

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

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

  Note:

   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 chapters (capitulos). Isso e um requerimento
   obrigatorio. Podem existir parts (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.

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

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

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

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

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

     &hellip;
   </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>

         &hellip;
       </sect3>
     </sect2>

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

       &hellip;
     </sect2>
   </sect1>
 </chapter>

  Note:

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

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

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

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

  Warning:

   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 steps, que
   por sua vez consistem de mais steps ou substeps. Cada step contem
   elementos de bloco.

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

   Example 4.30. programlisting

   Uso:

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

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

 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.

   Example 4.31. co e calloutlist

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

 <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>

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

 <calloutlist>
   <callout arearefs="co-ex-include">
     <para>Inclui o arquivo 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.

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

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

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

  Note:

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

   Example 4.34. screen, prompt, e userinput

   Uso:

 <screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>

   Aparencia:

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

  Note:

   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.

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

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

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

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

  Note:

   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.

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

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

   Example 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 (:).

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

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

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

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

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

   Example 4.47. errorname

   Uso:

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

   Aparencia:

 Panic: cannot mount root

  4.2.6. Imagens

  Important:

   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.

  Important:

   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.png, 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 Section 3.7.1, "Utilizando entidades gerais para incluir
   arquivos") 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

  Note:

   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.

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

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

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

  Note:

   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.

   Example 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

  Note:

   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.

  Note:

   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.

   Example 4.52. ulink

   Uso:

 <para>E claro que voce pode parar de ler este documento e ir para a
 <ulink url="&url.base;/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

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

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

                         Chapter 5. * Folhas de Estilo

   Table of Contents

   5.1. * DSSSL

   5.2. CSS

   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.

                  Chapter 6. Estruturando Documentos Sob doc/

   Table of Contents

   6.1. O Nivel Superior, doc/

   6.2. Os Diretorios de idioma.codificac,ao

   6.3. Informac,ao Especifica do Documento

   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 partes,
   e cada uma delas pode conter diversos chapters (Capitulos). Os chapters
   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.

  Note:

   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.

  Important:

   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.

             Chapter 7. O processo de construc,ao da documentac,ao

   Table of Contents

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

   7.2. Entendendo Makefiles na arvore da documentac,ao

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

   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.

  Note:

   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.

  Note:

   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.

  Note:

   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.

                              Chapter 8. O Website

   Table of Contents

   8.1. Preparac,ao

   8.2. Construa as paginas web do inicio

   8.3. Instalando as web pages em seu Web Server

   8.4. Variaveis de ambiente

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.

  Note:

   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

  Tip:

   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.

                             Chapter 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                                      
                                                                                               
        Note:                                                                                  
                                                                                               
      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                                                           
           -->                                                                                 

                         Chapter 10. Estilo de Escrita

   Table of Contents

   10.1. Guia de Estilo

   10.2. Lista de Palavras

   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.

  Note:

           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

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

                            Chapter 12. Veja tambem

   Table of Contents

   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

   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

                              Appendix A. Exemplos

   Table of Contents

   A.1. DockBook book

   A.2. DocBook article

   A.3. Produzindo saidas formatadas

   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

   Example 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

   Example 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

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

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

   Example 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

   Example 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 (Example A.5, "Convertendo de DocBook para Postscript").

   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.

                                     Index

  I

   Identificadores Publicos Formais, Identificadores publicos formais (FPIs)

   Identificar Publico Formal, A declarac,ao DOCTYPE

  S

   Sociedade, Visao Geral
