     Primer do Projeto de Documentac,ao do FreeBSD para Novos Colaboradores

  Projeto de Documentac,ao do FreeBSD

   Revisao: 1b46489d06

   Copyright (c) 1998-2020 DocEng

   Copyright

   Redistribution and use in source (XML DocBook) and 'compiled' forms (XML,
   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 (XML DocBook) must retain the above
       copyright notice, this list of conditions and the following disclaimer
       as the first lines of this file unmodified.

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

  Importante:

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

   2020-08-05 22:09:20 +0000 por Danilo G. Baio.
   Resumo

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

   Este primer cobre tudo o que voce precisa saber para comec,ar a contribuir
   com o Projeto de Documentac,ao do FreeBSD, ou FDP, incluindo ferramentas,
   softwares, e a filosofia por tras do Projeto de Documentac,ao.

   Este documento e um trabalho em andamento. Correc,oes e adic,oes sao
   sempre bem vindas.

   [ Documento HTML em partes / Documento HTML completo ]

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

   Indice

   Prefacio

                1. Prompts do Shell

                2. Convenc,oes Tipograficas

                3. Notas, Dicas, Informac,oes Importantes, Avisos e Exemplos

                4. Agradecimentos

   1. Visao Geral

                1.1. Quick Start

                1.2. Conjunto de Documentac,ao do FreeBSD

   2. Ferramentas

                2.1. Ferramentas Obrigatorias

                2.2. Ferramentas Opcionais

   3. A Area de Trabalho

                3.1. Documentac,ao e Paginas de Manual

                3.2. Escolhendo um Diretorio

                3.3. Baixando uma Copia

                3.4. Atualizando

                3.5. Revertendo Alterac,oes

                3.6. Criando um Diff

                3.7. Referencias Subversion

   4. Estrutura de Diretorios da Documentac,ao

                4.1. O Nivel Superior, doc/

                4.2. Os Diretorios lang.encoding/

                4.3. Informac,ao Especifica de Documentac,ao

   5. O Processo de Compilac,ao da Documentac,ao

                5.1. Renderizando DocBook

                5.2. O Conjunto de Ferramentas de Compilac,ao da
                Documentac,ao do FreeBSD

                5.3. Noc,oes Basicas de Makefiles no Repositorio de
                Documentac,ao

                5.4. Includes do Make do Projeto de Documentac,ao do FreeBSD

   6. O Website

                6.1. Variaveis &#8203;&#8203;de Ambiente

                6.2. Compilando e Instalando as Paginas Web

   7. Primer XML

                7.1. Visao Geral

                7.2. Elementos, Tags e Atributos

                7.3. A Declarac,ao DOCTYPE

                7.4. De Volta para o XML

                7.5. Comentarios

                7.6. Entidades

                7.7. Usando Entidades para Incluir Arquivos

                7.8. Sec,oes Marcadas

                7.9. Conclusao

   8. XHTML Markup

                8.1. Introduc,ao

                8.2. Identificador Publico Formal (FPI)

                8.3. Sec,oes de Elementos

                8.4. Elementos Block

                8.5. Elementos In-line

   9. DocBook Markup

                9.1. Introduc,ao

                9.2. Extensoes do FreeBSD

                9.3. Identificador Publico Formal (FPI)

                9.4. Estrutura do Documento

                9.5. Elementos Block

                9.6. Elementos In-line

                9.7. Imagens

                9.8. Links

   10. Folhas de Estilo

                10.1. CSS

   11. Traduc,oes

   12. Traduc,oes PO

                12.1. Introduc,ao

                12.2. Quick Start

                12.3. Criando Novas Traduc,oes

                12.4. Traduzindo

                12.5. Dicas para Tradutores

                12.6. Compilando um Documento Traduzido

                12.7. Submetendo a Nova Traduc,ao

   13. Paginas de Manual

                13.1. Introduc,ao

                13.2. Sec,oes

                13.3. Marcac,ao

                13.4. Exemplo de Estruturas de Pagina de Manual

                13.5. Exemplos de paginas de manuais para usar como modelos

                13.6. Recursos

   14. Estilo de escrita

                14.1. Dicas

                14.2. Diretrizes

                14.3. Guia de estilo

                14.4. Lista de palavras

   15. Configurac,ao do Editor

                15.1. Vim

                15.2. Emacs

                15.3. nano

   16. Veja tambem

                16.1. O projeto de documentac,ao do FreeBSD

                16.2. XML

                16.3. HTML

                16.4. DocBook

   A. Exemplos

                A.1. Livro DocBook

                A.2. Artigo DocBook

   Indice Remissivo

   Lista de Tabelas

   5.1. Formatos de Saida Comuns

   12.1. Nomes de Idioma

   Lista de Exemplos

   1. Uma Amostra de Exemplo

   5.1. Compilar um Arquivo Unico HTML

   5.2. Compilar HTML-Split e PDF

   6.1. Compile o Web Site Completo e Todos Documentos

   6.2. Compile Apenas o Web Site em Ingles

   6.3. Compile e Instale o Web Site

   7.1. Utilizando um Elemento (Tag Inicial e Final)

   7.2. Usando um Elemento Sem Conteudo

   7.3. Elementos Dentro de Elementos; em

   7.4. Usando um Elemento com um Atributo

   7.5. Aspas Simples nos Atributos

   7.6. XML Comentarios Genericos

   7.7. Comentario XML Incorreto

   7.8. Definindo Entidades Gerais

   7.9. Definindo Entidades de Parametro

   7.10. Usando Entidades Gerais para Incluir Arquivos

   7.11. Usando Entidades de Parametro para Incluir Arquivos

   7.12. Estrutura de uma Sec,ao Marcada

   7.13. Usando uma Sec,ao Marcada CDATA

   7.14. Usando INCLUDE e IGNORE em Sec,oes Marcadas

   7.15. Usando uma Entidade de Parametro para Controlar uma Sec,ao Marcada

   8.1. Estrutura de um Documento XHTML

   8.2. h1, h2 e Outras Tags de Cabec,alho

   8.3. Exemplo p

   8.4. Exemplo blockquote

   8.5. Exemplo ul and ol

   8.6. Listas de Definic,ao com dl

   8.7. Exemplo pre

   8.8. Uso Simples de table

   8.9. Usando rowspan

   8.10. Usando colspan

   8.11. Usando rowspan e colspan Juntos

   8.12. Exemplo em e strong

   8.13. Exemplo tt

   8.14. Usando <a href="...">

   8.15. Criando uma Ancora

   8.16. Criando Link para uma Parte Nomeada de um Outro Documento

   8.17. Criando Link para uma Parte Nomeada no Mesmo Documento

   9.1. Exemplo de book com info

   9.2. Exemplo de article com info

   9.3. Um Capitulo Simples

   9.4. Capitulos Vazios

   9.5. Sec,oes em Capitulos

   9.6. Exemplo de um para

   9.7. Exemplo blockquote

   9.8. Example de tip e important

   9.9. example

   9.10. example Renderizado

   9.11. Exemplo de itemizedlist e orderedlist

   9.12. Exemplovariablelist

   9.13. Exemplo procedure

   9.14. Exemplo programlisting

   9.15. Exemplo co e calloutlist

   9.16. Exemplo informaltable

   9.17. Exemplo de Tabela com frame="none"

   9.18. Exemplos screen, prompt, e userinput

   9.19. Exemplo de emphasis

   9.20. Exemplo acronym

   9.21. Exemplo quote

   9.22. Exemplos de Teclas, Botoes do Mouse e Combinac,oes

   9.23. Exemplo de Aplicac,oes, Comandos e Opc,oes

   9.24. Exemplo filename

   9.25. Exemplo de package

   9.26. Exemplos systemitem

   9.27. Exemplo uri

   9.28. Exemplo de Hiperlink com email

   9.29. Exemplo de email Sem Hiperlink

   9.30. Exemplo de buildtarget e varname

   9.31. Exemplo literal

   9.32. Exemplo de replaceable

   9.33. Exemplo guibutton

   9.34. Exemplo errorname

   9.35. xml:id em Ccapitulos e sSec,oes de eExemplo

   9.36. Exemplo xref

   9.37. link para um Exemplo de Pagina Web de Documentac,ao do FreeBSD

   9.38. link para um Exemplo de Pagina Web do FreeBSD

   9.39. link para um Exemplo de Pagina Web Externa

   12.1. Criando uma Traduc,ao em Espanhol do Porter's Handbook

   12.2. Criando uma traduc,ao em Frances do Artigo Chaves Open PGP

   12.3. Traduzindo o Porter's Handbook para o Espanhol

   12.4. Preservando Tags XML

   12.5. Construindo o Porter's Handbook Espanhol

   12.6. Traduc,ao Espanhola do Artigo NanoBSD

   12.7. Traduc,ao Coreana UTF-8 do Artigo Explicando o BSD

   A.1. Livro DocBook

   A.2. Artigo DocBook

                                    Prefacio

   Indice

   1. Prompts do Shell

   2. Convenc,oes Tipograficas

   3. Notas, Dicas, Informac,oes Importantes, Avisos e Exemplos

   4. Agradecimentos

1. Prompts do Shell

   Esta tabela mostra o prompt padrao do sistema e o prompt do super usuario.
   Os exemplos usam estes prompts para indicar com qual usuario o exemplo foi
   executado.

                    Usuario                               Prompt              
   Usuario normal                            %                                
   root                                      #                                

2. Convenc,oes Tipograficas

   Esta tabela descreve as convenc,oes tipograficas utilizadas neste livro.

               Proposito                             Exemplos                 
   Nome dos comandos.                Utilize ls -l para listar todos os       
                                     arquivos.                                
   Nome dos arquivos.                Edite .login.                            
   Saida de um programa na tela do   You have mail.                           
   computador.                       
   O que o usuario digita, quando    % date +"The time is %H:%M"              
   contrastado com a saida do        The time is 09:18                        
   programa na tela do computador.   
   Referencia a uma pagina de        Utilize su(1) para assumir outro nome de 
   manual.                           usuario.                                 
   Nome de usuario e de grupos de    Apenas o root pode fazer isso.           
   usuarios.                         
   Enfase.                           O usuario deve fazer isso.               
   Texto que o usuario deve          Para buscar por uma palavra chave nas    
   substituir com o texto real.      paginas de manual, digite man -k keyword 
   Variaveis de ambiente.            $HOME aponta para o diretorio inicial do 
                                     usuario.                                 

3. Notas, Dicas, Informac,oes Importantes, Avisos e Exemplos

   Notas, avisos e exemplos aparecem ao longo do texto.

  Nota:

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

  Dica:

   Dicas sao representadas desta forma, e contem informac,oes uteis para o
   usuario, como as que mostram uma maneira mais facil de fazer alguma coisa.

  Importante:

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

  Atenc,ao:

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

   Exemplo 1. Uma Amostra de Exemplo

   Os exemplos sao representados deste modo, e normalmente contem exemplos
   passo a passo, ou mostram 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.

                            Capitulo 1. Visao Geral

   Indice

   1.1. Quick Start

   1.2. Conjunto de Documentac,ao do FreeBSD

   Seja bem vindo ao Projeto de Documentac,ao do FreeBSD.(FDP). Documentac,ao
   de boa qualidade e muito importante para o sucesso do FreeBSD, e nos
   valorizamos muito suas contribuic,oes.

   Este documento descreve como o FDP e organizado, como escrever e como
   submeter documentos, e como utilizar de forma efetiva as ferramentas que
   estao disponiveis.

   Todos sao bem vindos para se juntar ao FDP. A vontade de contribuir e o
   unico requisito de adesao.

   Este primer mostra como:

     * Identificar quais partes do FreeBSD sao mantidas pelo FDP.

     * Instalar as ferramentas e arquivos de documentac,ao necessarios.

     * Realizar alterac,oes na documentac,ao.

     * Enviar de volta alterac,oes para revisao e inclusao na documentac,ao
       do FreeBSD.

1.1. Quick Start

   Algumas etapas preparatorias devem ser seguidas antes de editar a
   documentac,ao do FreeBSD. Primeiro, se registre na lista de email do
   projeto de documentac,ao do FreeBSD. Alguns membros do time tambem
   interagem no IRC, canal #bsddocs na rede EFnet. Estas pessoas podem ajudar
   com questoes e problemas envolvendo documentac,ao.

    1. Instale o meta-port textproc/docproj e o Subversion. Este meta-port
       instala todo software necessario para editar e compilar a
       documentac,ao do FreeBSD. O pacote Subversion e necessario para obter
       uma copia de trabalho da documentac,ao e para gerar patches.

 # pkg install docproj subversion

    2. Opcional: para gerar a documentac,ao em PDF, instale o pacote
       textproc/fop pois ele nao e instalado por padrao com o
       textproc/docproj.

 # pkg install fop

    3. Obtenha uma copia local da arvore de documentac,ao do FreeBSD em ~/doc
       (see Capitulo 3, A Area de Trabalho).

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

    4. Configure o editor de texto:

          * Defina a quebra de linha para 70 caracteres.

          * Defina a parada de tabulac,ao para 2.

          * Substitua cada grupo de 8 espac,os por um tab.

       Configurac,oes especificas por editor sao informados em Capitulo 15,
       Configurac,ao do Editor.

    5. Atualize a arvore de trabalho local:

 % svn up ~/doc

    6. Edite os arquivos de documentac,ao que precisam de alterac,oes. Se um
       arquivo precisar de grandes mudanc,as, consulte a lista de discussao
       para obter informac,oes.

       Referencias pra uso de tag e entidade podem ser encontradas em
       Capitulo 8, XHTML Markup and Capitulo 9, DocBook Markup.

    7. Apos alterac,ao, cheque por eventuais problemas rodando:

 % igor -R filename.xml | less -RS

       Revise a saida e edite o arquivo para corrigir os problemas informados
       e, em seguida, execute novamente o comando para verificar os problemas
       restantes. Repita ate que todos os erros sejam resolvidos.

    8. Sempre realize testes de compilac,ao antes de submeter algo. Execute
       make no diretorio de nivel superior da documentac,ao alterada e assim
       sera gerado a documentac,ao no formato HTML com divisoes. Por exemplo,
       pra compilar a versao Ingles do Handbook em HTML, execute make no
       diretorio en_US.ISO8859-1/books/handbook/.

    9. Quando as alterac,oes estiverem completas e testadas, gere um "arquivo
       diff":

 % cd ~/doc
 % svn diff > bsdinstall.diff.txt

       De ao arquivo diff um nome. No exemplo acima, foram feitas alterac,oes
       na parte bsdinstall do Handbook.

   10. Submeta o arquivo diff file pela web para o sistema de Relatorios de
       Problema. Se estiver usando o formulario web, insira um Sumario com
       [patch] descric,ao curta do problema. Selecione o Componente
       Documentation. No campo de Descric,ao, insira uma breve descric,ao das
       alterac,oes e quaisquer detalhes importantes sobre elas. Use o botao
       [ Add an attachment ] para anexar o arquivo diff. Finalmente,
       pressione o botao [ Submit Bug ] para enviar seu diff para o sistema
       de relatorio de problemas.

1.2. Conjunto de Documentac,ao do FreeBSD

   O FDP e responsavel por quatro categorias de documentac,ao do FreeBSD.

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

     * FAQ: O FAQ utiliza um formato curto de pergunta e resposta para
       abordar duvidas que sao frequentemente realizadas nas listas de
       discussao e foruns dedicados ao FreeBSD. Este formato nao permite
       respostas longas e detalhadas.

     * Paginas de Manual: As paginas de manual do sistema de lingua inglesa
       geralmente nao sao escritas pelo FDP, pois fazem parte do sistema
       base. Contudo, o FDP pode reformular partes das paginas de manual
       existentes para torna-las mais claras ou para corrigir imprecisoes.

     * Web site: Esta e a presenc,a principal do FreeBSD na web, visite
       https://www.FreeBSD.org/ e muitos mirrors ao redor do mundo. O site e
       tipicamente o primeiro contato de um usuario novo com o FreeBSD.

   As equipes de traduc,ao sao responsaveis por traduzir o manual e o site
   para diferentes idiomas. As paginas do manual nao sao traduzidas no
   momento.

   Codigo fonte do site do FreeBSD, Handbook, e FAQ estao disponiveis no
   repositorio de documentac,ao em https://svn.FreeBSD.org/doc/.

   Codigo fonte das paginas de manual estao disponiveis em um repositorio
   diferente localizado em https://svn.FreeBSD.org/base/.

   As mensagens de commit de documentac,ao podem ser visualizadas com svn
   log. As mensagens de commit tambem sao arquivadas em
   http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all.

   Enderec,o web para ambos os repositorios disponiveis em
   https://svnweb.FreeBSD.org/doc/ e https://svnweb.FreeBSD.org/base/.

   Muitas pessoas tem escrito tutoriais e artigos how-to sobre FreeBSD.
   Alguns sao armazenados como parte dos arquivos FDP. Em outros casos, o
   autor decidiu manter a documentac,ao separada. O FDP esforc,a-se para
   fornecer links para o maximo possivel dessas documentac,oes externas.

                            Capitulo 2. Ferramentas

   Indice

   2.1. Ferramentas Obrigatorias

   2.2. Ferramentas Opcionais

   Varias ferramentas sao utilizadas para gerenciar a documentac,ao do
   FreeBSD e renderiza-la para diferentes formatos. Algumas dessas
   ferramentas sao necessarias e devem ser instaladas antes de trabalhar com
   os exemplos nos capitulos a seguir. Algumas sao opcionais, adicionando
   recursos ou tornando a tarefa de criar documentac,ao mais simples.

2.1. Ferramentas Obrigatorias

   Instale o textproc/docproj pela Colec,ao de Ports. Este meta-port instala
   todos os aplicativos necessarios para trabalhar com a documentac,ao do
   FreeBSD. Informac,oes adicionais especificas de alguns componentes serao
   informadas abaixo.

  2.1.1. DTDs e Entidades

   A documentac,ao do FreeBSD utiliza diversas Definic,oes de Tipos de
   Documento (DTDs) e conjuntos de entidades XML. Estes sao todos instalados
   pelo port textproc/docproj.

   XHTML DTD (textproc/xhtml)

           XHTML e a linguagem markup escolhida pela Web, e e utilizada em
           todo o site do FreeBSD.

   DocBook DTD (textproc/docbook-xml)

           O DocBook e projetado para escrever documentac,ao tecnica. A maior
           parte da documentac,ao do FreeBSD e escrita no DocBook.

   Entidades ISO 8879 (textproc/iso8879)

           Entidades do padrao ISO 8879:1986 utilizado por muitos DTDs.
           Inclui simbolos matematicos nomeados, caracteres adicionais no
           conjunto de caracteres latinos (acentos, diacriticos e assim por
           diante) e simbolos Gregos.

2.2. Ferramentas Opcionais

   Essas ferramentas nao sao necessarias, mas podem facilitar o trabalho na
   documentac,ao ou adicionar recursos.

  2.2.1. Software

   Vim (editors/vim)

           Um editor de texto popular que trabalha com XML and documentos
           derivados, como DocBook XML.

   Emacs (editors/emacs)

           Ambos editores incluem um modo especial para editar documentos
           marcados como XML DTD. Esse modo inclui comandos para reduzir a
           quantidade de digitac,ao necessaria e ajudar a reduzir a
           possibilidade de erros.

                         Capitulo 3. A Area de Trabalho

   Indice

   3.1. Documentac,ao e Paginas de Manual

   3.2. Escolhendo um Diretorio

   3.3. Baixando uma Copia

   3.4. Atualizando

   3.5. Revertendo Alterac,oes

   3.6. Criando um Diff

   3.7. Referencias Subversion

   A area de trabalho e uma copia da arvore de documentac,ao do repositorio
   do FreeBSD baixada no computador local. As alterac,oes sao feitas na copia
   de trabalho local, testadas e enviadas como patches para serem submetidas
   no repositorio principal.

   Uma copia completa da arvore de documentac,ao pode ocupar 700 megabytes de
   espac,o em disco. Tenha um gigabyte de espac,o total para ter sobra para
   arquivos temporarios e versoes de teste dos diversos formatos de saida.

   O Subversion e utilizado para gerenciar os arquivos de documentac,ao do
   FreeBSD. Ele e obtido pela instalac,ao do pacote Subversion:

 # pkg install subversion

3.1. Documentac,ao e Paginas de Manual

   A documentac,ao do FreeBSD nao e formada apenas por livros e artigos.
   Paginas de manual para todos os comandos e arquivos de configurac,ao
   tambem fazem parte da documentac,ao e fazem parte do territorio do FDP.
   Dois repositorios estao envolvidos: doc para os livros e artigos, e base
   para o sistema operacional e paginas de manual. Para editar paginas de
   manual, o repositorio base deve ser registrado separadamente.

   Repositorios podem conter varias versoes de documentac,ao e codigo-fonte.
   Novas modificac,oes quase sempre sao feitas apenas para a versao mais
   recente, chamada head.

3.2. Escolhendo um Diretorio

   A documentac,ao do FreeBSD e tradicionalmente armazenada em /usr/doc/, e o
   codigo fonte do sistema com paginas de manual em /usr/src/. Essas arvores
   sao realocaveis &#8203;&#8203;e os usuarios podem armazenar as copias de
   trabalho em outros locais para evitar interferir nas informac,oes
   existentes nos diretorios principais. Os exemplos a seguir utilizam ~/doc
   e ~/src, ambos subdiretorios do diretorio pessoal do usuario.

3.3. Baixando uma Copia

   O processo de download de um repositorio e chamado de checkout e e feito
   com um svn checkout. Este exemplo faz checkout de uma copia da versao mais
   recente (head) do repositorio de documentac,ao principal:

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

   O checkout do codigo-fonte para trabalhar nas paginas de manual e muito
   semelhante:

 % svn checkout https://svn.FreeBSD.org/base/head ~/src

3.4. Atualizando

   Os documentos e arquivos no repositorio do FreeBSD mudam diariamente. As
   pessoas modificam arquivos e submetem alterac,oes com frequencia. Mesmo
   apos um checkout inicial, ja havera alterac,oes entre a copia de trabalho
   local e o repositorio principal do FreeBSD. Para atualizar a versao local
   com as mudanc,as que foram feitas no repositorio principal, execute svn
   update no diretorio que contem a copia de trabalho local:

 % svn update ~/doc

   Adquira o habito de protec,ao de executar svn update antes de editar os
   arquivos de documentac,ao. Alguem pode ter editado esse arquivo muito
   recentemente e a copia de trabalho local nao incluira essas alterac,oes
   mais recentes ate que ela seja atualizada. Editar a versao mais recente de
   um arquivo e muito mais facil do que tentar combinar um arquivo local
   editado mais antigo com a versao mais recente do repositorio.

3.5. Revertendo Alterac,oes

   De vez em quando acontece que algumas mudanc,as nao eram necessarias, ou o
   escritor so quer comec,ar novamente. Arquivos podem ser "resetados" para
   sua forma anterior com svn revert. Por exemplo, para apagar as alterac,oes
   feitas no chapter.xml e redefini-las para o formato sem modificac,ao:

 % svn revert chapter.xml

3.6. Criando um Diff

   Apos finalizar as alterac,oes em um arquivo ou grupo de arquivos, as
   diferenc,as entre a copia de trabalho local e a versao no repositorio do
   FreeBSD devem ser coletadas em um unico arquivo para ser submetido. Estes
   arquivos diff sao produzidos redirecionando a saida de svn diff para um
   arquivo:

 % cd ~/doc
 % svn diff > doc-fix-spelling.diff

   De ao arquivo um nome significativo que identifique o conteudo. O exemplo
   acima e para correc,ao ortografica em toda a arvore de documentac,ao.

   Se o arquivo diff for enviado com a interface web "Submit a FreeBSD
   problem report", adicione uma extensao .txt para que o formulario web
   identifique que o conteudo do arquivo e texto plano.

   Tenha cuidado: svn diff inclui todas as alterac,oes feitas no diretorio
   atual e em quaisquer subdiretorios. Se houver arquivos na copia de
   trabalho com edic,oes que ainda nao estao prontas para serem enviadas,
   fornec,a uma lista apenas dos arquivos a serem incluidos:

 % cd ~/doc
 % svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff

3.7. Referencias Subversion

   Estes exemplos demonstram um uso muito basico do Subversion. Mais detalhes
   estao disponiveis no Subversion Book e na Documentac,ao do Subversion.

              Capitulo 4. Estrutura de Diretorios da Documentac,ao

   Indice

   4.1. O Nivel Superior, doc/

   4.2. Os Diretorios lang.encoding/

   4.3. Informac,ao Especifica de Documentac,ao

   Arquivos e diretorios no repositorio doc/ seguem uma estrutura destinada
   a:

    1. Facilitar a conversao do documento para outros formatos.

    2. Promover a consistencia entre as diferentes organizac,oes de
       documentac,ao, e assim facilitar a alternancia entre diferentes
       documentos.

    3. Facilitar a decisao de onde a nova documentac,ao deve ser colocada.

   Alem disso, o repositorio de documentac,ao deve acomodar documentos em
   varios idiomas e codificac,oes diferentes. E importante que a estrutura do
   repositorio de documentac,ao nao imponha quaisquer padroes particulares ou
   preferencias culturais.

4.1. O Nivel Superior, doc/

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

     Diretorio                               Uso                              
   share         Contem arquivos que nao sao especificos das varias           
                 traduc,oes e codificac,oes da documentac,ao. Contem          
                 subdiretorios para categorizar ainda mais as informac,oes.   
                 Por exemplo, os arquivos que fazem parte da infra-estrutura  
                 make(1) estao em share/mk, enquanto o suporte adicional a    
                 arquivos XML (como o DTBook estendido do FreeBSD DTD) estao  
                 em share/xml.                                                
   lang.encoding Existe um diretorio para cada traduc,ao e codificac,ao       
                 disponivel da documentac,ao, por exemplo, en_US.ISO8859-1/ e 
                 zh_TW.UTF-8/. Os nomes sao longos, mas ao especificar        
                 totalmente o idioma e a codificac,ao, evitamos dores de      
                 cabec,a futuras quando uma equipe de traduc,ao desejar       
                 fornecer documentac,ao no mesmo idioma, mas em mais de uma   
                 codificac,ao. Isso tambem evita problemas que podem ser      
                 causados &#8203;&#8203;por uma futura mudanc,a para Unicode. 

4.2. Os Diretorios lang.encoding/

   Esses diretorios contem os proprios documentos. A documentac,ao e dividida
   em ate tres outras categorias, indicadas pelos diferentes nomes de
   diretorio.

   Diretorio                               Uso                                
   articles  Documentac,ao marcada como DocBook article (ou equivalente).     
             Conteudo curto e dividido em sec,oes. Normalmente disponivel     
             apenas como um arquivo XHTML.                                    
   books     Documentac,ao marcada como DocBook book (ou equivalente).        
             Conteudo longo e dividido em capitulos. Normalmente disponivel   
             como um grande arquivo XHTML (para pessoas com conexoes rapidas, 
             ou que desejam imprimi-lo facilmente de um navegador) e como uma 
             colec,ao de arquivos menores e com links.                        
   man       Para traduc,oes das paginas de manual do sistema. Esse diretorio 
             contera um ou mais diretorios manN, correspondendo `as sec,oes   
             que foram traduzidas.                                            

   Nem todo diretorio lang.encoding tera todos esses subdiretorios. Depende
   de quanto a traduc,ao foi realizada por essa equipe de traduc,ao.

4.3. Informac,ao Especifica de Documentac,ao

   Esta sec,ao contem informac,oes especificas sobre documentos gerenciados
   pelo FDP.

  4.3.1. O Handbook

    books/handbook/

   O Handbook esta escrito em DocBook XML usando DTD extendido do DocBook
   FreeBSD.

   O Handbook esta organizado como um DocBook book. O livro e dividido em
   parts, cada uma contendo varios chapters. Os chapters sao subdivididos em
   sec,oes (sect1) e subsec,oes (sect2, sect3) e assim por diante.

    4.3.1.1. Organizac,ao Fisica

   Existem varios arquivos e diretorios dentro do diretorio handbook.

  Nota:

   A organizac,ao do Handbook pode ser alterada ao longo do tempo, e este
   documento pode estar defasado quanto ao detalhamento das mudanc,as
   organizacionais do mesmo. Envie perguntas sobre a organizac,ao do Handbook
   na lista de discussao do projeto FreeBSD.

      4.3.1.1.1. Makefile

   O Makefile define algumas variaveis &#8203;&#8203;que afetam como o fonte
   XML e convertido em diversos formatos e lista os varios arquivos fontes
   que compoem o Handbook. Em seguida, ele inclui o doc.project.mk padrao,
   para inserir o restante do codigo que manipula a conversao de documentos
   de um formato para outro.

      4.3.1.1.2. book.xml

   Este e o principal arquivo do Handbook. Ele contem a declarac,ao DOCTYPE,
   bem como os elementos que descrevem a estrutura do Handbook.

   book.xml utiliza entidades de parametro para carregar os arquivos com a
   extensao .ent. Esses arquivos (descritos posteriormente) e entao definem
   as entidades gerais que sao utilizadas &#8203;&#8203;no restante do
   Handbook.

      4.3.1.1.3. directory/chapter.xml

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

   Por exemplo, se um dos arquivos de capitulo contiver:

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

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

   Quando a versao XHTML do Handbook for gerada, produzira o
   kernelconfig.html. Isso e por causa do valor id e nao esta relacionado ao
   nome do diretorio.

   Nas versoes anteriores do Handbook, os arquivos eram armazenados no mesmo
   diretorio que book.xml e nomeados apos o valor do atributo id no elemento
   chapter. Agora, e possivel incluir imagens em cada capitulo. Imagens para
   cada capitulo do Handbook sao armazenadas em share/images/books/handbook.
   As imagens devem ser colocadas no mesmo diretorio que os fontes XML para
   cada capitulo. As colisoes de Namespace sao inevitaveis &#8203;&#8203;e e
   mais facil trabalhar com varios diretorios que contenham alguns arquivos,
   do que trabalhar com um unico diretorio que contenham muitos arquivos.

   Com uma breve analise pode-se constatar que existem diversos diretorios
   com arquivos individuais chapter.xml, incluindo basics/chapter.xml,
   introduction/chapter.xml, e printing/chapter.xml.

  Importante:

   Nao nomeie capitulos ou diretorios com a ordenac,ao do Handbook. Essa
   ordenac,ao pode mudar conforme o conteudo do Handbook e reorganizado. A
   reorganizac,ao deve ser realizada sem renomear arquivos, a menos que
   capitulos inteiros sejam promovidos ou rebaixados dentro da hierarquia.

   Os arquivos chapter.xml nao sao arquivos completos de documentos XML que
   podem ser compilados individualmente. Eles so podem ser compilados como
   partes de todo o Handbook.

             Capitulo 5. O Processo de Compilac,ao da Documentac,ao

   Indice

   5.1. Renderizando DocBook

   5.2. O Conjunto de Ferramentas de Compilac,ao da Documentac,ao do FreeBSD

   5.3. Noc,oes Basicas de Makefiles no Repositorio de Documentac,ao

   5.4. Includes do Make do Projeto de Documentac,ao do FreeBSD

   Este capitulo aborda a organizac,ao do processo de compilac,ao da
   documentac,ao e como o make(1) e utilizado para isso.

5.1. Renderizando DocBook

   Diferentes tipos de saida podem ser produzidos a partir de um unico
   arquivo fonte DocBook. O tipo de saida desejado e definido com a variavel
   FORMATS. Uma lista de formatos de saida conhecidos e armazenada em
   KNOWN_FORMATS:

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make -V KNOWN_FORMATS

   Tabela 5.1. Formatos de Saida Comuns

   Valor FORMATS    Tipo de Arquivo                  Descric,ao               
   html          HTML, arquivo unico   Um unico book.html ou article.html.    
                                       Varios arquivos HTML, um para cada     
   html-split    HTML, varios arquivos capitulo ou sec,ao, para uso em um     
                                       site comum.                            
   pdf           PDF                   Portable Document Format               

   O formato de saida padrao pode variar de acordo com o documento, mas
   geralmente e html-split. Outros formatos sao escolhidos definindo FORMATS
   para um valor especifico. Multiplos formatos de saida podem ser criados de
   uma so vez definindo FORMATS para uma lista de formatos.

   Exemplo 5.1. Compilar um Arquivo Unico HTML

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS=html

   Exemplo 5.2. Compilar HTML-Split e PDF

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS="html-split pdf"

5.2. O Conjunto de Ferramentas de Compilac,ao da Documentac,ao do FreeBSD

   Estas sao as ferramentas utilizadas para compilar e instalar a
   documentac,ao do FDP.

     * A principal ferramenta de compilac,ao e o make(1), especificamente o
       Berkeley Make.

     * A construc,ao de pacotes e gerenciada pelo pkg-create(8) do FreeBSD.

     * gzip(1) e usado para criar versoes compactadas de um documento.
       bzip2(1) tambem sao suportados. tar(1) e usado na criac,ao de pacotes.

     * install(1) e usado para instalar a documentac,ao.

5.3. Noc,oes Basicas de Makefiles no Repositorio de Documentac,ao

   Existem tres tipos principais de Makefiles no repositorio de Documentac,ao
   do Projeto FreeBSD.

     * Makefiles de Subdiretorio simplesmente passam os comandos para os
       diretorios abaixo deles.

     * Makefiles de Documentac,ao descrevem os documentos que devem ser
       produzidos a partir deste diretorio.

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

  5.3.1. Makefiles de Subdiretorio

   Estes Makefiles geralmente tem a forma de:

 SUBDIR =articles
 SUBDIR+=books

 COMPAT_SYMLINK = en

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

   As quatro primeiras linhas nao vazias definem as variaveis
   &#8203;&#8203;do make(1), SUBDIR, COMPAT_SYMLINK, e DOC_PREFIX.

   A declarac,ao SUBDIR e COMPAT_SYMLINK mostram como atribuir um valor a uma
   variavel, sobrescrevendo qualquer valor anterior que a mesma contenha.

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

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

   Agora o que tudo isso significa? 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 (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(1) que contem o caminho para o diretorio atual.

   A linha final inclui o arquivo principal do make(1) doc.project.mk do
   Projeto de Documentac,ao do FreeBSD, ele e o responsavel por converter
   estas variaveis em instruc,oes de compilac,ao.

  5.3.2. Makefiles de Documentac,ao

   Estes conjuntos de &#8203;&#8203;make(1) Makefiles descrevem como
   construir a documentac,ao contida nesse 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 permite que os committers reivindiquem a propriedade
   de um documento no Projeto de Documentac,ao do FreeBSD, e sejam
   responsaveis &#8203;&#8203;por mante-lo.

   DOC e o nome (sem a extensao .xml) do principal documento criado por este
   diretorio. O 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.

   FORMATS indica os formatos nos quais o documento deve ser gerado por
   padrao. 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.

   Voce ja deve estar familiarizado com a atribuic,ao da variavel DOC_PREFIX
   e com as instruc,oes de include.

5.4. Includes do Make do Projeto de Documentac,ao do FreeBSD

   make(1) includes sao melhor explicados por uma inspec,ao de codigo. Aqui
   estao os arquivos include do sistema:

     * doc.project.mk e o principal arquivo include do projeto, que inclui
       todos os arquivos includes necessarios.

     * doc.subdir.mk controla a navegac,ao na arvore de documentac,ao durante
       o processo de construc,ao e instalac,ao.

     * doc.install.mk fornece as variaveis que afetam a propriedade e a
       instalac,ao de documentos.

     * doc.docbook.mk e incluido se o DOCFORMAT for docbook e se a variavel
       DOC estiver definida.

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

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

   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 e o padrao.

  Nota:

   A variavel PRI_LANG de maneira alguma afeta quais documentos serao, ou que
   poderao, ser compilados. Sua func,ao principal e criar links para os
   documentos referenciados com maior frequencia no diretorio raiz de
   instalac,ao da documentac,ao do FreeBSD.

    5.4.1.2. Condicionais

   A linha .if defined(DOC) e um exemplo da condicional do make ( 1 ) 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.

  5.4.2. doc.subdir.mk

   Este arquivo e muito longo para ser explicado em detalhes. Estas notas
   descrevem as principais funcionalidades.

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

     * COMPAT_SYMLINK ja foi descrito na sec,ao Makefiles de Subdiretorio.

    5.4.2.2. Targets e Macros

   As dependencias sao descritas por target: dependencia1 dependencia2 ...,
   nas quais, para construir o target, e necessario 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 diferencia essa macro 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 usara a macro _SUBDIRUSE depois de ter executado
   a instruc,ao rm -f $ {CLEANFILES}. De fato, isso faz com que clean va mais
   a fundo na arvore de diretorios, excluindo os arquivos construidos `a
   medida que vai descendo pelos subdiretorios, e nao quando vai na direc,ao
   oposta.

      5.4.2.2.1. Targets Fornecidos

     * install e package ambos percorrem a arvore de diretorios executando as
       suas versoes reais dentro dos subdiretorios (realinstall e realpackage
       respectivamente).

     * clean remove arquivos criados pelo processo de compilac,ao (e tambem
       desce na arvore de diretorios). cleandir faz a mesma coisa, e tambem
       remove o diretorio de objetos se este existir.

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

    5.4.2.4. Construc,oes de Looping no make (.for)

   .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 .for e .endfor
   serao repetidas para cada elemento, com o entry sendo substituido com o
   valor do elemento atual.

                             Capitulo 6. O Website

   Indice

   6.1. Variaveis &#8203;&#8203;de Ambiente

   6.2. Compilando e Instalando as Paginas Web

   O web site do FreeBSD e parte da documentac,ao do FreeBSD. Os arquivos
   para o web site sao armazenados no subdiretorio en_US.ISO8859-1/htdocs do
   repositorio ~/doc neste exemplo.

6.1. Variaveis &#8203;&#8203;de Ambiente

   Diversas variaveis &#8203;&#8203;de ambiente controlam quais partes do web
   site sao compiladas ou instaladas e para quais diretorios.

  Dica:

   O sistema de compilac,ao do web site utiliza o make(1), e valida variaveis
   configuradas mesmo se estiverem vazias. Os exemplos aqui mostram as formas
   recomendadas de configurar e utilizar essas variaveis. Definir ou
   configurar essas variaveis &#8203;&#8203;com outros valores ou metodos
   pode levar a surpresas inesperadas.

   DOCDIR

           DOCDIR especifica o caminho onde os arquivos do web site devem ser
           instalados.

           Esta variavel e melhor configurada com env(1) ou o metodo do shell
           do usuario para configurar variaveis &#8203;&#8203;de ambiente,
           setenv para csh(1) ou export para sh(1).

   ENGLISH_ONLY

           Padrao: indefinido. Compile e inclua todas as traduc,oes.

           ENGLISH_ONLY=yes: compile apenas os documentos em Ingles e ignore
           todas as traduc,oes.

   WEB_ONLY

           Padrao: indefinido. Compile o web site e todos os livros e
           artigos.

           WEB_ONLY=yes: Compile ou instale apenas paginas HTML do diretorio
           en_US.ISO8859-1/htdocs. Outros diretorios e documentos, incluindo
           livros e artigos, serao ignorados.

   WEB_LANG

           Padrao: indefinido. Compile e inclua todos os idiomas disponiveis
           no web site.

           Defina com uma lista separada por espac,os, todos os idiomas a
           serem incluidos na compilac,ao ou instalac,ao. Os formatos sao os
           mesmos que os nomes de diretorio no diretorio raiz do documento.
           Por exemplo, para incluir os documentos alemao e frances:

 WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"

   WEB_ONLY, WEB_LANG, e ENGLISH_ONLY sao variaveis make(1) que&#8203;e podem
   ser definidas em /etc/make.conf, Makefile.inc, como variaveis
   &#8203;&#8203;de ambiente na linha de comando, ou em arquivos dot.

6.2. Compilando e Instalando as Paginas Web

   Apos obter os arquivos fontes da documentac,ao e web site, o site pode ser
   compilado.

   Uma instalac,ao real do web site precisa ser executada pelo usuario root
   porque as permissoes no diretorio do servidor web nao permitirao a
   instalac,ao de arquivos por um usuario nao privilegiado. Para testar, pode
   ser util instalar os arquivos com um usuario normal em um diretorio
   temporario.

   Nestes exemplos, os arquivos do web site sao criados pelo usuario jru em
   seu diretorio home, ~/doc, com um caminho completo de /usr/home/jru/doc.

  Dica:

   A compilac,ao do web site utiliza o arquivo INDEX da Colec,ao de Ports e
   pode falhar se este arquivo ou /usr/ports nao estiver presente no sistema.
   A abordagem mais simples e instalar a Colec,ao de Ports.

   Exemplo 6.1. Compile o Web Site Completo e Todos Documentos

   Compile o web site e todos os documentos. Os arquivos finais sao deixados
   na arvore de documento:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % make all

   Exemplo 6.2. Compile Apenas o Web Site em Ingles

   Compile o web site apenas em Ingles, como usuario jru, e instale os
   arquivos finais em /tmp/www para teste:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % env DOCDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install

   Alterac,oes em arquivos estaticos geralmente podem ser testadas
   visualizando os arquivos modificados diretamente com um navegador web. Se
   o web site foi construido como apresentado acima, a pagina principal
   modificada pode ser visualizada com:

 % firefox /tmp/www/data/index.html

   Modificac,oes em arquivos dinamicos podem ser testadas com um servidor web
   rodando no sistema local. Depois de construir o site como apresentado
   acima, o /usr/local/etc/apache24/httpd.conf pode ser usado com
   www/apache24:

 # httpd.conf for testing the FreeBSD website
 Define TestRoot "/tmp/www/data"

 # directory for configuration files
 ServerRoot "/usr/local"

 Listen 80

 # minimum required modules
 LoadModule authz_core_module libexec/apache24/mod_authz_core.so
 LoadModule mime_module libexec/apache24/mod_mime.so
 LoadModule unixd_module libexec/apache24/mod_unixd.so
 LoadModule cgi_module libexec/apache24/mod_cgi.so
 LoadModule dir_module libexec/apache24/mod_dir.so

 # run the webserver as user and group
 User www
 Group www

 ServerAdmin you@example.com
 ServerName fbsdtest

 # deny access to all files
 <Directory />
     AllowOverride none
     Require all denied
 </Directory>

 # allow access to the website directory
 DocumentRoot "${TestRoot}"
 <Directory "${TestRoot}">
     Options Indexes FollowSymLinks
     AllowOverride None
     Require all granted
 </Directory>

 # prevent access to .htaccess and .htpasswd files
 <Files ".ht*">
     Require all denied
 </Files>

 ErrorLog "/var/log/httpd-error.log"
 LogLevel warn

 # set up the CGI script directory
 <Directory "${TestRoot}/cgi">
     AllowOverride None
     Options None
     Require all granted
     Options +ExecCGI
     AddHandler cgi-script .cgi
 </Directory>

 Include etc/apache24/Includes/*.conf

   Inicie o servidor web com

 # service apache24 onestart

   O web site pode ser visualizado em http://localhost. Esteja ciente de que
   muitos links se referem ao site real do FreeBSD por nome, e esses links
   ainda levar para o site externo em vez da versao de teste local. O teste
   completo do web site local exigira a configurac,ao temporaria do DNS para
   que o enderec,o www.FreeBSD.org seja resolvido como localhost ou o
   enderec,o IP local.

   Exemplo 6.3. Compile e Instale o Web Site

   Compile o web site e todos os documentos como usuario jru. Instale os
   arquivos finais como root no diretorio padrao, /root/public_html:

 % cd ~/doc/en_US.ISO8859-1/htdocs
 % make all
 % su -
 Password:
 # cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs
 # make install

   O processo de instalac,ao nao exclui nenhum arquivo antigo ou
   desatualizado que existia anteriormente no mesmo diretorio. Se uma nova
   copia do web site for criada e instalada todos os dias, esse comando
   localizara e excluira todos os arquivos que nao foram atualizados em tres
   dias:

 # find /usr/local/www -ctime 3 -delete

                             Capitulo 7. Primer XML

   Indice

   7.1. Visao Geral

   7.2. Elementos, Tags e Atributos

   7.3. A Declarac,ao DOCTYPE

   7.4. De Volta para o XML

   7.5. Comentarios

   7.6. Entidades

   7.7. Usando Entidades para Incluir Arquivos

   7.8. Sec,oes Marcadas

   7.9. Conclusao

   A maioria das documentac,oes do FDP e escrita com linguagens markup
   baseadas em XML. Este capitulo explica o que isso significa, como ler e
   entender os arquivos fontes da documentac,ao e as tecnicas de XML
   utilizadas.

   Partes desta sec,ao foram inspiradas por Mark Galassi's Get Going With
   DocBook.

7.1. Visao Geral

   Nos primordios da era computacional, o texto eletronico era simples. Havia
   poucos conjuntos de caracteres como ASCII ou EBCDIC, e apenas isso. Texto
   era texto, e o que voce lia era realmente o texto que voce tinha. Sem
   frescuras, sem formatac,ao, sem inteligencia.

   Inevitavelmente, isso nao era suficiente. Quando o texto esta em um
   formato utilizavel por computadores, espera-se que eles possam usa-lo e
   manipula-lo de maneira inteligente. Os autores querem indicar que certas
   frases devem ser enfatizadas, adicionadas a um glossario ou transformadas
   em hiperlinks. Os nomes dos arquivos podem ser apresentados em uma fonte
   de estilo "typewriter" para exibic,ao na tela do computador, ou como
   "italico" quando impressos, ou qualquer outra opc,ao dentre uma infinidade
   de opc,oes para apresentac,ao.

   Esperava-se que a Inteligencia Artificial (IA) facilitasse isso. O
   computador leria o documento e identificaria automaticamente frases-chave,
   nomes de arquivos, textos que o leitor deveria digitar, exemplos e outros
   tipos. Infelizmente, na vida real nao foi dessa forma, e os computadores
   ainda precisam de assistencia antes que possam processar o texto de
   maneira significativa.

   Mais precisamente, eles precisam de ajuda para identificar o que e o que.
   Considere este texto:

     Para remover /tmp/foo, use rm(1).

 % rm /tmp/foo

   E facil identificar quais partes sao nomes de arquivos, quais sao comandos
   a serem digitados, quais partes sao referencias a paginas de manual e
   assim por diante. Mas o computador que processa o documento nao consegue.
   Para isso, precisamos utilizar markup.

   "Markup" e geralmate utilizado assim "adicionando valor" ou "aumentando o
   custo". O termo tem seus significados realc,ados quando aplicado ao texto.
   Markup e um texto adicional incluido no documento, diferenciado de alguma
   forma do conteudo do documento, para que os programas que processam o
   documento possam ler a marcac,ao e utiliza-la ao tomar decisoes sobre o
   documento. Os editores podem ocultar o markup do usuario, para que este
   nao se distraia com ela.

   A informac,ao extras armazenada no markup adiciona valor ao documento.
   Adicionar markup ao documento normalmente deve ser feito por uma pessoa -
   afinal, se os computadores pudessem reconhecer o texto suficientemente bem
   para adicionar a markup, nao haveria necessidade de utilizar markup. Isto
   aumenta o custo (o esforc,o necessario) para criar algum documento.

   O exemplo anterior e representado neste documento da seguinte forma:

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

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

   O markup e claramente separado do conteudo.

   As linguagens markup definem o que as marcac,oes significam e como elas
   devem ser interpretadas.

   Claro, uma linguagem markup pode nao ser suficiente. Uma linguagem markup
   para documentac,ao tecnica tem requisitos muito diferentes de uma
   linguagem markup destinada a receitas de culinaria. Isso, por sua vez,
   seria muito diferente de uma linguagem markup utilizada para descrever uma
   poesia. O que e realmente necessario e uma primeira linguagem utilizada
   para escrever essas outras linguagens markup. Uma meta linguagem markup.

   E exatamente isso que a eXtensible Markup Language (XML) e. Muitas
   linguagens markup foram escritas em XML, incluindo as duas mais utilizadas
   pelo FDP, XHTML e DocBook.

   Cada definic,ao de idioma e mais apropriadamente chamada de gramatica,
   vocabulario, esquema ou Definic,ao de Tipo de Documento (DTD). Existem
   varios idiomas para especificar uma gramatica XML ou um schema.

   Um schema e uma especificac,ao completa de todos os elementos que podem
   ser utilizados, a ordem em que devem aparecer, quais elementos sao
   obrigatorios, quais sao opcionais e assim por diante. Isso torna possivel
   escrever um XML parser que le tanto o schema quanto um documento que
   afirma estar em conformidade com o schema. O parser pode confirmar se
   todos os elementos exigidos pelo vocabulario estao ou nao na ordem correta
   do documento ou se ha algum erro no markup. Isto e normalmente conhecido
   como a "valiidac,ao do documento".

  Nota:

   A validac,ao confirma se a escolha dos elementos, sua ordenac,ao e assim
   por diante estao em conformidade com os listados na gramatica. Ela nao
   valida se o markup correto foi utilizado no conteudo. Se todos os nomes de
   arquivo em um documento fossem marcados como sendo nomes de func,ao, o
   analisador nao sinalizaria isso como um erro (supondo, e claro, que o
   schema define elementos para nomes de arquivos e func,oes e que eles
   possam aparecer no mesmo local).

   A maioria das contribuic,oes no Projeto de Documentac,ao utilizara markup
   XHTML ou DocBook, em vez de alterac,oes nos schemas. Por esse motivo, este
   livro nao abordara como escrever um vocabulario.

7.2. Elementos, Tags e Atributos

   Todos os vocabularios escritos em XML compartilham certas caracteristicas.
   Isso nao surpreende, pois a filosofia por tras do XML inevitavelmente ira
   transparecer. Uma das manifestac,oes mais obvias desta filosofia e a do
   conteudo e dos elementos.

   A documentac,ao, seja uma unica pagina web ou um livro extenso, e
   considerada como conteudo. Este conteudo e entao dividido e subdividido em
   elementos. A finalidade de adicionar markup e nomear e identificar os
   limites desses elementos para processamento futuro.

   Por exemplo, considere um livro tipico. No maior nivel, o livro e um
   elemento. Este elemento "livro" contem obviamente capitulos, que podem ser
   considerados elementos tambem. Cada capitulo contera mais elementos, como
   paragrafos, citac,oes e notas de rodape. Cada paragrafo pode conter outros
   elementos, identificando o conteudo que foi um discurso direto ou o nome
   de um personagem na historia.

   Pode ser util pensar nisso como um conteudo por "pedac,os". No nivel mais
   alto e um pedac,o, o livro. Olhando um pouco mais, encontra-se mais
   pedac,os, os capitulos individuais. Estes sao segmentados em paragrafos,
   notas de rodape, nomes de caracteres e assim por diante.

   Observe como essa diferenciac,ao entre diferentes elementos do conteudo
   pode ser feita sem recorrer a quaisquer termos XML. E realmente
   surpreendentemente simples. Isso pode ser feito com uma caneta marca-texto
   e um livro impresso, usando cores diferentes para indicar diferentes
   partes do conteudo.

   E claro que nao temos um marca-texto eletronico, entao precisamos de outra
   maneira de indicar a qual elemento cada parte do conteudo pertence. Em
   idiomas escritos em XML (XHTML, DocBook, e outros) isto e feito por meio
   de tags.

   Uma tag e usada para identificar onde um determinado elemento comec,a e
   onde o elemento termina. A tag nao faz parte do proprio elemento. Como
   cada gramatica foi normalmente escrita para marcar tipos especificos de
   informac,ao, cada um reconhecera elementos diferentes e, portanto, tera
   nomes diferentes para as tags.

   Para um elemento chamado nome-do-elemento, a tag inicial normalmente se
   parecera com <nome-do-elemento>. A tag de fechamento correspondente para
   este elemento e </nome-do-elemento>.

   Exemplo 7.1. Utilizando um Elemento (Tag Inicial e Final)

   XHTML possui um elemento para indicar que o conteudo incluido pelo
   elemento e um paragrafo, chamado p.

 <p>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
   element.</p>

 <p>This is another paragraph.  But this one is much shorter.</p>

   Alguns elementos nao possuem conteudo. Por exemplo, em XHTML, uma linha
   horizontal pode ser incluida no documento. Para estes elementos "vazios",
   XML trouxe um formato abreviado que e completamente equivalente `a versao
   de duas tags:

   Exemplo 7.2. Usando um Elemento Sem Conteudo

   XHTML tem um elemento para indicar uma linha horizontal, chamada hr. Esse
   elemento nao possui conteudo, e se parece com isso:

 <p>One paragraph.</p>
 <hr></hr>

 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>

   A versao abreviada consiste em uma unica tag:

 <p>One paragraph.</p>
 <hr/>

 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>

   Como mostrado acima, os elementos podem conter outros elementos. No
   exemplo do livro anterior, o elemento livro continha elementos de
   capitulo, que por sua vez continham elementos de paragrafo, e assim por
   diante.

   Exemplo 7.3. Elementos Dentro de Elementos; em

 <p>This is a simple <em>paragraph</em> where some
   of the <em>words</em> have been <em>emphasized</em>.</p>

   A gramatica consiste em regras que descrevem quais elementos podem conter
   outros elementos e exatamente o que eles podem conter.

  Importante:

   As pessoas geralmente confundem os termos tags e elementos e usam os
   termos como se fossem intercambiaveis. Eles nao sao.

   Um elemento e uma parte conceitual do seu documento. Um elemento tem
   inicio e fim definidos. As tags marcam onde o elemento comec,a e termina.

   Quando este documento (ou qualquer pessoa com conhecimento sobre XML)
   refere-se a "a <p> tag" significa o texto literal que consiste nos tres
   caracteres <, p, e >. Mas a frase "o elemento p" refere-se ao elemento
   inteiro.

   Essa distinc,ao e muito sutil. Mas tenha isso em mente.

   Elementos podem ter atributos. Um atributo tem um nome e um valor e e
   usado para adicionar informac,oes extras ao elemento. Isso pode ser uma
   informac,ao que indica como o conteudo deve ser renderizado ou pode ser
   algo que identifica exclusivamente essa ocorrencia do elemento ou isso
   pode ser outra coisa tambem.

   Os atributos de um elemento sao escritos dentro da tag de inicio para
   aquele elemento, e toma o formato nome-do-atributo="valor-do-atributo".

   Em XHTML, o elemento p tem um atributo chamado align, que sugere um
   alinhamento (justificac,ao) do paragrafo para o programa exibindo o XHTML.

   O atributo align pode ter um dos quatro valores definidos, left, center,
   right e justify. Se o atributo nao for especificado, o padrao sera left.

   Exemplo 7.4. Usando um Elemento com um Atributo

 <p align="left">The inclusion of the align attribute
   on this paragraph was superfluous, since the default is left.</p>

 <p align="center">This may appear in the center.</p>

   Alguns atributos so aceitam valores especificos, como left ou justify.
   Outros permitem qualquer valor.

   Exemplo 7.5. Aspas Simples nos Atributos

 <p align='right'>I am on the right!</p>

   Os valores de atributos em XML devem ser colocados entre aspas simples ou
   duplas. Aspas duplas sao tradicionais. Aspas simples sao uteis quando o
   valor do atributo contem aspas duplas.

   Informac,oes sobre atributos, elementos e tags sao armazenadas em arquivos
   de catalogo. O Projeto de Documentac,ao usa catalogos padrao do DocBook e
   inclui catalogos adicionais para recursos especificos do FreeBSD. Os
   caminhos para os arquivos de catalogo sao definidos em uma variavel de
   ambiente para que possam ser encontradas pelas ferramentas de compilac,ao
   de documentos.

  7.2.1. Para Fazer...

   Antes de rodar os exemplos deste documento, instale o textproc/docproj
   pela Colec,ao de Ports do FreeBSD. Este e um meta-port que baixa e instala
   os programas padrao e arquivos de suporte necessarios para o Projeto de
   Documentac,ao. Os usuarios de csh(1) devem executar o rehash para que o
   shell reconhec,a os novos binarios depois de instalados ou efetue logout
   e, em seguida, fac,a login novamente.

    1. Crie example.xml e insira este texto:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>This is a paragraph containing some text.</p>

     <p>This paragraph contains some more text.</p>

     <p align="right">This paragraph might be right-justified.</p>
   </body>
 </html>

    2. Tente validar esse arquivo usando um parser XML.

       O textproc/docproj inclui o parser xmllint.

       Execute xmllint para validar o documento:

 % xmllint --valid --noout example.xml

       xmllint nao retorna nada se o documento for validado com sucesso.

    3. Veja o que acontece quando os elementos obrigatorios sao omitidos.
       Exclua a linha com as tags <title> e </title>, entao execute novamente
       a validac,ao.

 % xmllint --valid --noout example.xml
 example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()

       Isso mostra que o erro de validac,ao vem da linha cinco do arquivo
       example.xml e que o conteudo de <head> e a parte que nao segue as
       regras da gramatica XHTML.

       Em seguida, o xmllint mostra a linha onde o erro foi encontrado e
       marca a posic,ao exata com um sinal ^.

    4. Substitua o elemento title.

7.3. A Declarac,ao DOCTYPE

   No inicio de cada documento pode-se especificar o nome do DTD ao qual o
   documento esta em conformidade. Esta declarac,ao DOCTYPE e usada por XML
   parsers para identificar o DTD e garantir que o documento esteja de acordo
   com ele.

   Uma declarac,ao tipica para um documento escrito em conformidade com a
   versao 1.0 do XHTML DTD se parece com isto:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

   Essa linha contem varios componentes diferentes.

   <!

           O indicador mostra que esta e uma declarac,ao XML.

   DOCTYPE

           Mostra que esta e uma declarac,ao XML do tipo de documento.

   html

           Nomeia o primeiro elemento que aparecera no documento.

   PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

           Lista o Identificador Publico Formal (FPI) para o DTD com o qual
           este documento esta em conformidade. O XML parser usa isso para
           encontrar o DTD correto ao processar este documento.

           PUBLIC nao faz parte do FPI, mas indica ao XML parser como
           encontrar o DTD mencionado no FPI. Outras formas de informar ao
           XML parser como encontrar o DTD serao informadas depois.

   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"

           Um nome de arquivo local ou uma URL para encontrar o DTD.

   >

           Termina a declarac,ao e retorna ao documento.

  7.3.1. Identificadores Publicos Formais (FPIs)

  Nota:

   Nao e necessario conhecer isso, mas pode ser util e ajudar a depurar
   problemas quando o XML parser nao conseguir localizar o DTD.

   FPIs devem seguir uma sintaxe especifica:

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

   Proprietario

           O proprietario do FPI.

           O inicio da string identifica o proprietario do FPI. Por exemplo,
           o FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lista ISO
           8879:1986 como sendo o proprietario para o conjunto de entidades
           de Simbolos Gregos. ISO 8879:1986 e o numero na International
           Organization for Standardization (ISO) para o padrao SGML, o
           predecessor (e um superset) do XML.

           Caso contrario, essa sequencia seria parecida com -//Proprietario
           ou +//Proprietario (observe que a unica diferenc,a e o + ou -).

           Se a string comec,ar com -, a informac,ao do proprietario nao e
           registrada, com o + identifica como registrada.

           A ISO 9070:1991 define como os nomes registrados sao gerados. Pode
           ser derivado do numero de uma publicac,ao ISO, um codigo ISBN ou
           um codigo de organizac,ao atribuido de acordo com a ISO 6523. Alem
           disso, uma autoridade de registro poderia ser criada para atribuir
           nomes registrados. O conselho da ISO delegou isso ao American
           National Standards Institute (ANSI).

           Como o Projeto FreeBSD nao foi registrado, a string de propriedade
           e -//FreeBSD. Como visto no exemplo, a W3C tambem nao e
           registrada.

   Palavra-chave

           Existem varias palavras-chave que indicam o tipo de informac,ao no
           arquivo. Algumas das palavras-chave mais comuns sao DTD, ELEMENT,
           ENTITIES e TEXT. DTD e usada apenas para arquivos DTD, ELEMENT e
           normalmente usada para fragmentos DTD que contem apenas
           declarac,oes de elementos ou entidades. TEXT e usada para conteudo
           XML (texto e tags).

   Descric,ao

           Qualquer descric,ao pode ser informada no conteudo deste campo.
           Isso pode incluir numeros de versao ou qualquer texto curto que
           tenha significado e seja exclusivo para o sistema XML.

   Idioma

           Um codigo de dois caracteres ISO que identifica o idioma nativo do
           arquivo. EN e usado para o Ingles.

    7.3.1.1. Arquivos catalog

   Com a sintaxe acima, um XML parser precisa ter alguma forma de transformar
   o FPI no nome do arquivo que contem o DTD. Um arquivo de catalogo
   (normalmente chamado de catalog) contem linhas que mapeiam FPIs para nomes
   de arquivos. Por exemplo, se o arquivo de catalogo continha a linha:

 PUBLIC  "-//W3C//DTD XHTML 1.0 Transitional//EN"             "1.0/transitional.dtd"

   O XML parser sabe que o DTD e chamado de transitional.dtd no subdiretorio
   1.0 do diretorio que continha catalog.

   Examine o conteudo de /usr/local/share/xml/dtd/xhtml/catalog.xml. Este e o
   arquivo de catalogo dos XHTML DTD s que foram instalados como parte do
   port textproc/docproj .

  7.3.2. Alternativas para FPI s

   Em vez de usar uma FPI para indicar o DTD ao qual o documento esta em
   conformidade (e, portanto, qual arquivo no sistema contem o DTD), o
   arquivo pode ser explicitamente especificado.

   A sintaxe e um pouco diferente:

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

   A palavra-chave SYSTEM indica que o XML parser deve localizar o DTD de uma
   maneira especifica no sistema. Isso normalmente (mas nem sempre) significa
   que o DTD sera fornecido como um nome de arquivo.

   Usando FPIs e preferivel por razoes de portabilidade. Se o identificador
   SYSTEM for usado, entao o DTD deve ser fornecido e mantido no mesmo local
   para todos.

7.4. De Volta para o XML

   Algumas das sintaxes subjacentes do XML podem ser uteis em documentos. Por
   exemplo, os comentarios podem ser incluidos no documento e serao ignorados
   pelo parser. Os comentarios sao inseridos usando a sintaxe XML. Outros
   usos para a sintaxe XML serao mostrados mais tarde.

   Sec,oes XML comec,am com uma tag <! e terminam com >. Essas sec,oes contem
   instruc,oes para o parser em vez de elementos do documento. Tudo entre
   essas tags sao sintaxe XML. A declarac,ao DOCTYPE mostrada anteriormente e
   um exemplo da sintaxe XML incluida no documento.

7.5. Comentarios

   Um documento XML pode conter comentarios. Eles podem aparecer em qualquer
   lugar, desde que nao estejam dentro de tags. Eles ate sao permitidos em
   alguns locais dentro do DTD (por exemplo, entre declarac,oes de entidade).

   Os comentarios XML comec,am com a string "<!--" e terminam com a string
   "-->".

   Aqui estao alguns exemplos de comentarios validos de XML:

   Exemplo 7.6. XML Comentarios Genericos

 <!-- This is inside the comment -->

 <!--This is another comment-->

 <!-- This is how you
      write multiline comments -->

 <p>A simple <!-- Comment inside an element's content --> paragraph.</p>

   Os comentarios XML podem conter quaisquer strings, exceto "--":

   Exemplo 7.7. Comentario XML Incorreto

 <!-- This comment--is wrong -->

  7.5.1. Para Fazer...

    1. Adicione alguns comentarios ao arquivo example.xml e depois o valide
       utilizando o xmllint.

    2. Adicione alguns comentarios invalidos ao arquivo example.xml e veja as
       mensagens de erros que o xmllint ira retornar quando encontrar algum
       comentario invalido.

7.6. Entidades

   Entidades sao um mecanismo para atribuir nomes a partes do conteudo. A
   medida que um XML parser processa um documento, qualquer entidade
   encontrada e substituida pelo conteudo da entidade.

   Esta e uma boa maneira de ter pedac,os de conteudo reutilizaveis
   &#8203;&#8203;e facilmente alteraveis &#8203;&#8203;em documentos XML.
   Tambem e a unica maneira de incluir um arquivo markup dentro de outro
   usando XML.

   Existem dois tipos de entidades para duas situac,oes diferentes: entidades
   gerais e entidades de parametros.

  7.6.1. Entidades Gerais

   Entidades gerais sao usadas para atribuir nomes a partes reutilizaveis
   &#8203;&#8203;de texto. Essas entidades so podem ser usadas no documento.
   Elas nao podem ser usadas &#8203;&#8203;em um contexto XML.

   Para incluir o texto de uma entidade geral no documento, inclua
   &nome-da-entidade; no texto. Por exemplo, considere uma entidade geral
   chamada current.version, que se expande para o numero da versao atual de
   um produto. Para usa-la no documento, escreva:

 <para>The current version of our product is
   &current.version;.</para>

   Quando o numero da versao for alterado, edite a definic,ao da entidade
   geral, substituindo o valor. Em seguida, reprocesse o documento.

   Entidades gerais tambem podem ser usadas para inserir caracteres que nao
   poderiam ser incluidos em um documento XML. Por exemplo, < e & normalmente
   nao podem aparecer em um documento XML. O XML parser ve o simbolo < como o
   inicio de uma tag. Da mesma forma, quando o simbolo & e visto, espera-se
   que o proximo texto seja um nome de entidade.

   Esses simbolos podem ser incluidos usando duas entidades gerais
   predefinidas: &lt; e &amp;.

   Entidades gerais so podem ser definidas dentro de um contexto XML. Tais
   definic,oes geralmente sao feitas imediatamente apos a declarac,ao
   DOCTYPE.

   Exemplo 7.8. Definindo Entidades Gerais

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>

   A declarac,ao DOCTYPE foi estendida adicionando um colchete no final da
   primeira linha. As duas entidades sao entao definidas nas proximas duas
   linhas, o colchete e fechado e, em seguida, a declarac,ao DOCTYPE e
   fechada.

   Os colchetes sao necessarios para indicar que o DTD indicado pela
   declarac,ao DOCTYPE esta sendo estendido.

  7.6.2. Entidades de Parametro

   Entidades de parametro, como as entidades gerais, sao usadas para atribuir
   nomes a blocos reutilizaveis &#8203;&#8203;de texto. Mas as entidades de
   parametro so podem ser usadas dentro de um contexto XML.

   As definic,oes de entidade de parametro sao semelhantes `aquelas para
   entidades gerais. No entanto, entradas de parametros sao incluidas com
   %nome-da-entidade;. A definic,ao tambem inclui o % entre a palavra-chave
   ENTITY e o nome da entidade.

   Para memorizar, lembre que entidade de"Parametro utiliza o simbolo de
   Porcentagem".

   Exemplo 7.9. Definindo Entidades de Parametro

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY % entity "<!ENTITY version '1.0'>">
 <!-- use the parameter entity -->
 %entity;
 ]>

   A primeira vista, as entidades de parametros nao parecem muito uteis, mas
   elas tornam possivel incluir outros arquivos em um documento XML.

  7.6.3. Para Fazer...

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

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY version "1.1">
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <!-- There may be some comments in here as well -->

   <body>
     <p>This is a paragraph containing some text.</p>

     <p>This paragraph contains some more text.</p>

     <p align="right">This paragraph might be right-justified.</p>

     <p>The current version of this document is: &version;</p>
   </body>
 </html>

    2. Valide o documento usando o xmllint.

    3. Carregue example.xml em um navegador web. Ele pode ter que ser copiado
       para o example.html antes que o navegador o reconhec,a como um
       documento XHTML.

       Navegadores mais antigos com parsers simples podem nao renderizar esse
       arquivo conforme o esperado. A referencia de entidade &version; pode
       nao ser substituida pelo numero da versao, ou o fechamento de contexto
       XML ]> pode nao ser reconhecido e em vez disso, apresentado
       literalmente.

    4. A soluc,ao e normalizar o documento com um normalizador XML. O
       normalizador le um XML valido e grava outro XML igualmente valido. Uma
       maneira pela qual o normalizador transforma a entrada e expandindo
       todas as referencias de entidade no documento, substituindo as
       entidades pelo texto que elas representam.

       O xmllint pode ser usado para isso. Ele tambem tem a opc,ao de remover
       a sec,ao inicial DTD para que ]> nao confunda os navegadores:

 % xmllint --noent --dropdtd example.xml > example.html

       Uma copia normalizada do documento com entidades expandidas e
       produzida em example.html, pronta para ser carregada em um navegador
       web.

7.7. Usando Entidades para Incluir Arquivos

   Ambas as entidades geral e parametro sao particularmente uteis para
   incluir um arquivo dentro de outro .

  7.7.1. Usando Entidades Gerais para Incluir Arquivos

   Considere algum conteudo para um livro XML organizado em arquivos, um
   arquivo por capitulo, chamado chapter1.xml, chapter2.xml e assim por
   diante, com um book.xml que contera esses capitulos.

   Para usar o conteudo desses arquivos como valores para entidades, eles sao
   declarados com a palavra-chave SYSTEM. Isso direciona o XML parser a
   incluir o conteudo do arquivo nomeado como o valor da entidade.

   Exemplo 7.10. Usando Entidades Gerais para Incluir Arquivos

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY chapter.1 SYSTEM "chapter1.xml">
 <!ENTITY chapter.2 SYSTEM "chapter2.xml">
 <!ENTITY chapter.3 SYSTEM "chapter3.xml">
 <!-- And so forth -->
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <!-- Use the entities to load in the chapters -->

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

  Atenc,ao:

   Ao usar entidades gerais para incluir outros arquivos em um documento, os
   arquivos que estao sendo incluidos ( chapter1.xml, chapter2.xml e assim
   por diante) nao devem comec,ar com uma declarac,ao DOCTYPE. Este e um erro
   de sintaxe porque as entidades sao constructors de baixo nivel e sao
   transformadas antes que qualquer analise ocorra.

  7.7.2. Usando Entidades de Parametro para Incluir Arquivos

   As entidades de parametro so podem ser usadas dentro de um contexto XML. A
   inclusao de um arquivo em um contexto XML pode ser usada para garantir que
   as entidades gerais sejam reutilizaveis.

   Suponha que haja muitos capitulos no documento, e esses capitulos foram
   reutilizados em dois livros diferentes, cada livro organizando os
   capitulos de maneira diferente.

   As entidades podem ser listadas no topo de cada livro, mas isso
   rapidamente se torna dificil de gerenciar.

   Em vez disso, coloque as definic,oes gerais da entidade em um arquivo e
   use uma entidade de parametro para incluir esse arquivo no documento.

   Exemplo 7.11. Usando Entidades de Parametro para Incluir Arquivos

   Coloque as definic,oes de entidade em um arquivo separado chamado
   chapters.ent contendo este texto:

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

   Crie uma entidade de parametro para se referir ao conteudo do arquivo. Em
   seguida, use a entidade de parametro para carregar o arquivo no documento,
   o que tornara todas as entidades gerais disponiveis para uso. Em seguida,
   use as entidades gerais como antes:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!-- Define a parameter entity to load in the chapter general entities -->
 <!ENTITY % chapters SYSTEM "chapters.ent">

 <!-- Now use the parameter entity to load in this file -->
 %chapters;
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>

  7.7.3. Para Fazer...

    7.7.3.1. Use Entidades Gerais para Incluir Arquivos

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

       Coloque conteudo como este em cada arquivo:

 <p>This is the first paragraph.</p>

    2. Edite example.xml para que fique assim:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.xml">
 <!ENTITY para2 SYSTEM "para2.xml">
 <!ENTITY para3 SYSTEM "para3.xml">
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>The current version of this document is: &version;</p>

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

    3. Gere example.html ao normalizar example.xml.

 % xmllint --dropdtd --noent example.xml > example.html

    4. Carregue example.html no navegador web e confirme se os arquivos
       paran.xml foram incluidos em example.html.

    7.7.3.2. Use Entidades de Parametro para Incluir Arquivos

  Nota:

   As etapas anteriores devem ser concluidas antes dessa etapa.

    1. Edite example.xml para que fique assim:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY % entities SYSTEM "entities.ent"> %entities;
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>The current version of this document is: &version;</p>

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

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

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

    3. Gere example.html ao normalizar example.xml.

 % xmllint --dropdtd --noent example.xml > example.html

    4. Carregue example.html no navegador web e confirme se os arquivos
       paran.xml foram incluidos em example.html.

7.8. Sec,oes Marcadas

   XML fornece um mecanismo para indicar que partes especificas do documento
   devem ser processadas de uma maneira especial. Estes sao chamados de
   "sec,oes marcadas".

   Exemplo 7.12. Estrutura de uma Sec,ao Marcada

 <![KEYWORD[
   Contents of marked section
 ]]>

   Como esperado de um construct XML, uma sec,ao marcada comec,a com <!.

   O primeiro colchete inicia a sec,ao marcada.

   KEYWORD descreve como esta sec,ao marcada deve ser processada pelo parser.

   O segundo colchete indica o inicio do conteudo da sec,ao marcada.

   A sec,ao marcada e concluida, fechando os dois colchetes e, em seguida,
   retornando ao contexto do documento do contexto XML com >.

  7.8.1. Palavras-chave da Sec,ao Marcada

    7.8.1.1. CDATA

   Essas palavras-chave indicam as sec,oes marcadas pelo modelo de conteudo e
   permitem que voce a altere do padrao.

   Quando um XML parser esta processando um documento, ele acompanha o
   "modelo de conteudo".

   O modelo de conteudo descreve o conteudo que o parser espera ver e o que
   ele fara com esse conteudo.

   O modelo de conteudo CDATA e um dos mais uteis.

   CDATA e para "Dados de Caractere". Quando o parser esta neste modelo de
   conteudo, ele espera ver apenas caracteres. Nesse modelo, os simbolos < e
   & perdem seu status especial e serao tratados como caracteres comuns.

  Nota:

   Ao usar CDATA em exemplos de texto marcados em XML, lembre-se de que o
   conteudo de CDATA nao e validado. O texto incluido deve ser verificado por
   outros meios. Por exemplo, o conteudo poderia ser escrito em outro
   documento, validado e depois colado na sec,ao CDATA.

   Exemplo 7.13. Usando uma Sec,ao Marcada CDATA

 <para>Here is an example of how to include some text that contains
   many <literal>&lt;</literal> and <literal>&amp;</literal>
   symbols.  The sample text is a fragment of
   <acronym>XHTML</acronym>.  The surrounding text (<para> and
   <programlisting>) are from DocBook.</para>

 <programlisting><![CDATA[<p>This is a sample that shows some of the
   elements within <acronym>XHTML</acronym>.  Since the angle
   brackets are used so many times, it is simpler to say the whole
   example is a CDATA marked section than to use the entity names for
   the left and right angle brackets throughout.</p>

     <ul>
       <li>This is a listitem</li>
       <li>This is a second listitem</li>
       <li>This is a third listitem</li>
     </ul>

     <p>This is the end of the example.</p>]]></programlisting>

    7.8.1.2. INCLUDE e IGNORE

   Quando a palavra-chave e INCLUDE, o conteudo da sec,ao marcada sera
   processado. Quando a palavra-chave e IGNORE, a sec,ao marcada e ignorada e
   nao sera processada. Nao aparecera na saida.

   Exemplo 7.14. Usando INCLUDE e IGNORE em Sec,oes Marcadas

 <![INCLUDE[
   This text will be processed and included.
 ]]>

 <![IGNORE[
   This text will not be processed or included.
 ]]>

   Por si so, isso nao e muito util. O texto a ser removido do documento pode
   ser recortado ou estar em forma de comentarios.

   Ele se torna mais util quando controlado por entidades de parametro, mas
   esse uso e limitado a arquivos de entidades.

   Por exemplo, suponha que a documentac,ao tenha sido produzida em uma
   versao impressa e em uma versao eletronica. Algum texto extra e desejado
   no conteudo da versao eletronica que nao deveria aparecer na copia
   impressa.

   Crie um arquivo de entidade que defina entidades gerais para incluir cada
   capitulo e proteja essas definic,oes com uma entidade de parametro que
   pode ser definida como INCLUDE ou IGNORE para controlar se a entidade esta
   definida . Apos essas definic,oes de entidades gerais condicionais,
   coloque mais uma definic,ao para cada entidade geral para defini-las como
   um valor vazio. Essa tecnica faz uso do fato de que as definic,oes de
   entidade nao podem ser substituidas, mas a primeira definic,ao sempre
   entra em vigor. Assim, a inclusao do capitulo e controlada com a entidade
   de parametro correspondente. Definido como INCLUDE, a primeira definic,ao
   de entidade geral sera lida e a segunda sera ignorada. Definido como
   IGNORE, a primeira definic,ao sera ignorada e a segunda sera utilizada.

   Exemplo 7.15. Usando uma Entidade de Parametro para Controlar uma Sec,ao
   Marcada

 <!ENTITY % electronic.copy "INCLUDE">

 <![%electronic.copy;[
 <!ENTITY chap.preface   SYSTEM "preface.xml">
 ]]>

 <!ENTITY chap.preface "">

   Ao produzir a versao impressa, altere a definic,ao do parametro de
   entidade para:

 <!ENTITY % electronic.copy "IGNORE">

  7.8.2. Para Fazer...

    1. Modifique entidades.ent para conter o seguinte texto:

 <!ENTITY version "1.1">
 <!ENTITY % conditional.text "IGNORE">

 <![%conditional.text;[
 <!ENTITY para1 SYSTEM "para1.xml">
 ]]>

 <!ENTITY para1 "">

 <!ENTITY para2 SYSTEM "para2.xml">
 <!ENTITY para3 SYSTEM "para3.xml">

    2. Normalize example.xml e observe que o texto condicional nao esta
       presente no documento de saida. Altere o parametro de entidade para
       INCLUDE e gere novamente o documento normalizado, dessa forma e o
       texto aparecera novamente. Esse metodo faz sentido se houver mais
       partes condicionais dependendo da mesma condic,ao. Por exemplo, para
       controlar a gerac,ao de texto impresso ou on-line.

7.9. Conclusao

   Essa e a conclusao deste primer XML. Por razoes de espac,o e complexidade,
   varios assuntos nao foram cobertos bem afundo. No entanto, as sec,oes
   anteriores abrangem o suficiente de XML para apresentar a organizac,ao da
   documentac,ao do FDP.

                            Capitulo 8. XHTML Markup

   Indice

   8.1. Introduc,ao

   8.2. Identificador Publico Formal (FPI)

   8.3. Sec,oes de Elementos

   8.4. Elementos Block

   8.5. Elementos In-line

8.1. Introduc,ao

   Este capitulo descreve o uso da linguagem XHTML markup usada no site do
   FreeBSD.

   XHTML e a versao XML da HyperText Markup Language, a linguagem markup
   escolhida na World Wide Web. Mais informac,oes podem ser encontradas em
   http://www.w3.org/.

   XHTML e usado para escrever paginas no site do FreeBSD. Geralmente nao e
   usado para escrever outra documentac,ao, uma vez que o DocBook oferece um
   conjunto muito mais rico de elementos para se escolher. Consequentemente,
   as paginas XHTML normalmente so serao encontradas ao escrever para o web
   site.

   O HTML passou por varias versoes. A versao compativel com XML descrita
   aqui e chamada XHTML. A versao mais recente generalizada e o XHTML 1.0,
   disponivel nas variantes strict e transitional.

   Os XHTML DTDs estao disponiveis na Colec,ao de Ports em textproc/xhtml.
   Eles sao automaticamente instalados pelo port textproc/docproj.

  Nota:

   Isto nao e uma lista completa de elementos, uma vez que isso apenas
   repetiria a documentac,ao de XHTML. O objetivo e listar os elementos mais
   utilizados. Por favor, poste perguntas sobre elementos ou usos nao
   abordados aqui na lista de discussao do projeto de documentac,ao do
   FreeBSD.

  Inline Versus Block:

   No restante deste documento, ao descrever elementos, inline significa que
   o elemento pode estar dentro de um elemento de bloco e nao causa uma
   quebra de linha. Um elemento block, por outro lado, causara uma quebra de
   linha (e outro processamento) quando for encontrado.

8.2. Identificador Publico Formal (FPI)

   Existem varios XHTML FPIs, dependendo da versao, ou da versao do XHTML ao
   qual um documento esta em conformidade. A maioria dos documentos XHTML no
   site do FreeBSD esta de acordo com a versao de transic,ao do XHTML 1.0.

 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

8.3. Sec,oes de Elementos

   Um documento XHTML e normalmente dividido em duas sec,oes. A primeira
   sec,ao, chamada de head, contem meta-informac,oes sobre o documento, como
   seu titulo, o nome do autor, o documento pai e assim por diante. A segunda
   sec,ao, obody, contem o conteudo que sera exibido ao usuario.

   Essas sec,oes sao indicadas com os elementos head e body, respectivamente.
   Esses elementos estao dentro do elemento html de nivel superior.

   Exemplo 8.1. Estrutura de um Documento XHTML

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
           <title>The Document's Title</title>
   </head>

   <body>

     ...

   </body>
 </html>

8.4. Elementos Block

  8.4.1. Cabec,alhos

   XHTML tem tags para indicar titulos no documento em ate seis niveis
   diferentes.

   O maior e mais importante titulo e h1, depois h2, seguindo ate h6.

   O conteudo do elemento e o texto do cabec,alho.

   Exemplo 8.2. h1, h2 e Outras Tags de Cabec,alho

   Uso:

 <h1>First section</h1>

 <!-- Document introduction goes here -->

 <h2>This is the heading for the first section</h2>

 <!-- Content for the first section goes here -->

 <h3>This is the heading for the first sub-section</h3>

 <!-- Content for the first sub-section goes here -->

 <h2>This is the heading for the second section</h2>

 <!-- Content for the second section goes here -->

   Geralmente, uma pagina XHTML deve ter um titulo de primeiro nivel (h1).
   Nela pode conter muitos titulos de segundo nivel (h2), que por sua vez
   podem conter muitos cabec,alhos de terceiro nivel. Nao deixe lacunas na
   numerac,ao.

  8.4.2. Paragrafos

   O XHTML suporta um unico elemento de paragrafo, p.

   Exemplo 8.3. Exemplo p

   Uso:

 <p>This is a paragraph.  It can contain just about any
   other element.</p>

  8.4.3. Bloco de Citac,oes

   Um bloco de citac,ao e uma citac,ao estendida de outro documento que
   aparecera em um paragrafo separado.

   Exemplo 8.4. Exemplo blockquote

   Uso:

 <p>A small excerpt from the US Constitution:</p>

 <blockquote>We the People of the United States, in Order to form
   a more perfect Union, establish Justice, insure domestic
   Tranquility, provide for the common defence, promote the general
   Welfare, and secure the Blessings of Liberty to ourselves and our
   Posterity, do ordain and establish this Constitution for the
   United States of America.</blockquote>

  8.4.4. Listas

   O XHTML pode apresentar ao usuario tres tipos de listas: ordenadas,
   desordenadas e de definic,ao.

   Entradas em uma lista ordenada serao numeradas, enquanto as entradas em
   uma lista nao ordenada serao precedidas por marcadores. Listas de
   definic,oes tem duas sec,oes para cada entrada. A primeira sec,ao e o
   termo que esta sendo definido e a segunda sec,ao e a definic,ao.

   As listas ordenadas sao indicadas pelo elemento ol, listas nao ordenadas
   pelo elemento ul e listas de definic,ao pelo elemento dl.

   As listas ordenadas e nao ordenadas contem listitens, indicadas pelo
   elemento li. Um listitem pode conter conteudo textual ou pode ser envoltos
   em um ou mais elementos p.

   As listas de definic,oes contem termos de definic,ao (dt) e descric,oes de
   definic,ao (dd). Um termo de definic,ao pode conter apenas elementos
   in-line. Uma descric,ao de definic,ao pode conter outros elementos de
   bloco.

   Exemplo 8.5. Exemplo ul and ol

   Uso:

 <p>An unordered list.  Listitems will probably be
   preceded by bullets.</p>

 <ul>
   <li>First item</li>

   <li>Second item</li>

   <li>Third item</li>
 </ul>

 <p>An ordered list, with list items consisting of multiple
   paragraphs.  Each item (note: not each paragraph) will be
   numbered.</p>

 <ol>
   <li><p>This is the first item.  It only has one paragraph.</p></li>

   <li><p>This is the first paragraph of the second item.</p>

     <p>This is the second paragraph of the second item.</p></li>

   <li><p>This is the first and only paragraph of the third
     item.</p></li>
 </ol>

   Exemplo 8.6. Listas de Definic,ao com dl

   Uso:

 <dl>
   <dt>Term 1</dt>

   <dd><p>Paragraph 1 of definition 1.</p>

     <p>Paragraph 2 of definition 1.</p></dd>

   <dt>Term 2</dt>

   <dd><p>Paragraph 1 of definition 2.</p></dd>

   <dt>Term 3</dt>

   <dd><p>Paragraph 1 of definition 3.</p></dd>
 </dl>

  8.4.5. Texto Pre-formatado

   Texto pre-formatado e apresentado para o usuario exatamente como esta no
   arquivo. O texto e mostrado em uma fonte fixa. Varios espac,os e quebras
   de linha sao mostrados exatamente como estao no arquivo.

   Deixe o texto pre-formatado no elemento pre.

   Exemplo 8.7. Exemplo pre

   Por exemplo, as tags pre podem ser usadas 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:https://people.FreeBSD.org/~nik/primer/index.html&gt;

   Comments appreciated.

   N</pre>

   Tenha em mente que < e & ainda sao reconhecidos como caracteres especiais
   no texto pre-formatado. E por isso que o exemplo mostrado teve que usar
   &lt; em vez de <. Para consistencia, o &gt; tambem foi usado no lugar de
   >. Fique atento com os caracteres especiais que podem aparecer no texto
   copiado de uma fonte de texto simples, como uma mensagem de e-mail ou
   codigo de programa.

  8.4.6. Tabelas

   Marque as informac,oes tabulares usando o elemento table. Uma tabela
   consiste em uma ou mais linhas da tabela (tr), cada uma contendo uma ou
   mais celulas de dados da tabela (td). Cada celula pode conter outros
   elementos de bloco, como paragrafos ou listas. Tambem pode conter outra
   tabela (esse aninhamento pode repetir indefinidamente). Se a celula
   contiver apenas um paragrafo, o elemento p nao sera necessario.

   Exemplo 8.8. Uso Simples de table

   Uso:

 <p>This is a simple 2x2 table.</p>

 <table>
   <tr>
     <td>Top left cell</td>

     <td>Top right cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

   Uma celula pode abranger varias linhas e colunas adicionando os atributos
   rowspan ou colspan com valores para o numero de linhas ou colunas a serem
   abrangido.

   Exemplo 8.9. Usando rowspan

   Uso:

 <p>One tall thin cell on the left, two short cells next to
   it on the right.</p>

 <table>
   <tr>
     <td rowspan="2">Long and thin</td>
   </tr>

   <tr>
     <td>Top cell</td>

     <td>Bottom cell</td>
   </tr>
 </table>

   Exemplo 8.10. Usando colspan

   Uso:

 <p>One long cell on top, two short cells below it.</p>

 <table>
   <tr>
     <td colspan="2">Top cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

   Exemplo 8.11. Usando rowspan e colspan Juntos

   Uso:

 <p>On a 3x3 grid, the top left block is a 2x2 set of
   cells merged into one.  The other cells are normal.</p>

 <table>
   <tr>
     <td colspan="2" rowspan="2">Top left large cell</td>

     <td>Top right cell</td>
   </tr>

   <tr>
     <!-- Because the large cell on the left merges into
          this row, the first <td> will occur on its
          right -->

     <td>Middle right cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom middle cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

8.5. Elementos In-line

  8.5.1. Realc,ando Informac,ao

   Dois niveis de enfase estao disponiveis em XHTML, em e strong. em e para
   um nivel normal de enfase e strong indica enfase mais forte.

   em e normalmente renderizado em italico e o strong e renderizado em
   negrito. Isso nem sempre assim e nao deve ser considerado ao pe da letra.
   De acordo com as praticas recomendadas, as paginas web armazenam apenas
   informac,oes estruturais e semanticas, e as folhas de estilo sao aplicadas
   posteriormente a elas. Pense na semantica, nao na formatac,ao, ao usar
   essas tags.

   Exemplo 8.12. Exemplo em e strong

   Uso:

 <p><em>This</em> has been emphasized, while
   <strong>this</strong> has been strongly emphasized.</p>

  8.5.2. Indicando Texto Fixo

   O conteudo que deve ser renderizado em um tipo fixo de texto (typewriter)
   e marcado com tt (para "teletype").

   Exemplo 8.13. Exemplo tt

   Uso:

 <p>Many system settings are stored in
   <tt>/etc</tt>.</p>

  8.5.3. Links

  Nota:

   Links tambem sao elementos in-line.

    8.5.3.1. Criando Links para Outros Documentos na Web

   Um link aponta para uma URL de um documento na web. O link e indicado com
   a a, e o atributo href contem a URL do documento de destino. O conteudo do
   elemento se torna o link, indicado ao usuario, mostrando-o em uma cor
   diferente ou com um sublinhado.

   Exemplo 8.14. Usando <a href="...">

   Uso:

 <p>More information is available at the
   <a href="http://www.&os;.org/">&os; web site</a>.</p>

   Esse link sempre leva o usuario ao topo do documento que foi linkado.

    8.5.3.2. Criando Links para Partes Especificas de Documentos

   Para linkar a um ponto especifico dentro de um documento, esse documento
   deve incluir uma ancora no ponto desejado. As ancoras sao incluidas
   configurando o atributo id de um elemento para um nome. Este exemplo cria
   uma ancora definindo o atributo id de um elemento p.

   Exemplo 8.15. Criando uma Ancora

   Uso:

 <p id="samplepara">This paragraph can be referenced
   in other links with the name <tt>samplepara</tt>.</p>

   Links para ancoras sao semelhantes aos links simples, mas incluem um
   simbolo # e o ID da ancora no final da URL.

   Exemplo 8.16. Criando Link para uma Parte Nomeada de um Outro Documento

   O exemplo samplepara e parte de um documento chamado foo.html. Um link
   para esse paragrafo especifico no documento e construido neste exemplo.

 <p>More information can be found in the
   <a href="foo.html#samplepara">sample paragraph</a> of
   <tt>foo.html</tt>.</p>

   Para vincular-se a uma ancora nomeada no mesmo documento, omita a URLdo
   documento, e use apenas o simbolo # seguido do nome da ancora.

   Exemplo 8.17. Criando Link para uma Parte Nomeada no Mesmo Documento

   O exemplo samplepara reside neste documento. Para vincular a ele:

 <p>More information can be found in the
   <a href="#samplepara">sample paragraph</a> of this
   document.</p>

                           Capitulo 9. DocBook Markup

   Indice

   9.1. Introduc,ao

   9.2. Extensoes do FreeBSD

   9.3. Identificador Publico Formal (FPI)

   9.4. Estrutura do Documento

   9.5. Elementos Block

   9.6. Elementos In-line

   9.7. Imagens

   9.8. Links

9.1. Introduc,ao

   Este capitulo e uma introduc,ao ao DocBook e como ele e usado na
   documentac,ao do FreeBSD. O DocBook e um sistema de marcac,ao extenso e
   complexo, mas o subconjunto descrito aqui abrange as partes mais usadas
   para a documentac,ao do FreeBSD. Enquanto um subconjunto moderado e
   coberto, e impossivel antecipar todas as situac,oes. Por favor, poste
   questoes que este documento nao responde `a lista de discussao do projeto
   de documentac,ao do FreeBSD.

   DocBook foi originalmente desenvolvido por HaL Computer Systems and
   O'Reilly & Associates para ser uma Definic,ao de Tipo de Documento (DTD)
   para escrever documentac,ao tecnica [1]. Desde 1998, ele e mantido pelo
   Comite Tecnico do DocBook. Como tal, e ao contrario do LinuxDoc e do
   XHTML, o DocBook e fortemente orientado para um markup que descreve o que
   alguma coisa e, em vez de descrever como deve ser apresentado.

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

  Formal Versus Informal:

   Alguns elementos podem existir em duas formas, formal e informal.
   Normalmente, a versao formal do elemento consistira em um titulo seguido
   pela versao informal do elemento. A versao informal nao tera um titulo.

  Inline Versus Block:

   No restante deste documento, ao descrever elementos, inline significa que
   o elemento pode estar dentro de um elemento de bloco e nao causa uma
   quebra de linha. Um elemento block, por outro lado, causara uma quebra de
   linha (e outro processamento) quando for encontrado.

9.2. Extensoes do FreeBSD

   O Projeto de Documentac,ao do FreeBSD estendeu o DocBook DTD com elementos
   e entidades adicionais. Essas adic,oes servem para tornar algumas das
   marcac,oes mais faceis ou mais precisas.

   Ao longo deste documento, o termo "DocBook" e usado para indicar o DocBook
   DTD estendido do FreeBSD.

  Nota:

   A maioria dessas extensoes nao e exclusiva do FreeBSD, foi apenas
   identificado que elas eram melhorias uteis para este projeto. Se alguem de
   qualquer um dos outros *nix (NetBSD, OpenBSD, Linux,...) estiverem
   interessados em colaborar em um conjunto de extensao DocBook padrao, entre
   em contato com a Equipe de Engenharia de Documentac,ao
   <doceng@FreeBSD.org>.

  9.2.1. Elementos do FreeBSD

   Os elementos adicionais do FreeBSD nao estao (atualmente) na Colec,ao de
   Ports. Eles sao armazenados na repositorio Subversion do FreeBSD, como
   head/share/xml/freebsd.dtd.

   Os elementos especificos do FreeBSD usados &#8203;&#8203;nos exemplos
   abaixo estao claramente marcados.

  9.2.2. Entidades do FreeBSD

   Esta tabela mostra algumas das entidades mais uteis disponiveis no FDP.
   Para obter uma lista completa, consulte os arquivos *.ent em
   doc/share/xml.

                                                                                                                                                          
Entidades de Nome do FreeBSD    
&os;                            FreeBSD                                                                                                                   
&os.stable;                     FreeBSD-STABLE                                                                                                            
&os.current;                    FreeBSD-CURRENT                                                                                                           
                                                                                                                                                          
Entidades de Pagina de Manual   
&man.ls.1;                      ls(1)                                                     Uso: &man.ls.1; e a pagina de manual para o                     
                                                                                          <command>ls</command>.                                          
&man.cp.1;                      cp(1)                                                     Uso: A pagina de manual para <command>cp</command> e            
                                                                                          &man.cp.1;.                                                     
&man.command.sectionnumber;     link para a pagina de manual command na sec,ao            As entidades sao definidas para todas as paginas de manual do   
                                sectionnumber                                             FreeBSD.                                                        
                                                                                                                                                          
Entidades das Listas de Email do FreeBSD
&a.doc;                         Lista de discussao do projeto de documentac,ao do FreeBSD Uso: Um link para a &a.doc;.                                    
&a.questions;                   Lista de discussao de assuntos gerais do FreeBSD          Uso: Um link para a &a.questions;.                              
&a.listname;                    link para listname                                        Foram criadas entidades para todas as listas de email do        
                                                                                          FreeBSD.                                                        
                                                                                                                                                          
Entidades de Link de Documento do FreeBSD
&url.books.handbook;a           ../../../../doc/en_US.ISO8859-1/books/handbook            Uso: Um link para o capitulo <link                              
                                                                                          xlink:href="&url.books.handbook;/advanced-networking.html">Rede 
                                                                                          Avanc,ado</link> do Handbook.                                   
&url.books.bookname;            caminho relativo parabookname                             As entidades sao definidas para todos os livros FreeBSD.        
&url.articles.committers-guide; ../../../../doc/en_US.ISO8859-1/articles/committers-guide Uso: Um link para o artigo <link                                
                                                                                          xlink:href="&url.articles.committers-guide;">Guia dos           
                                                                                          Committer's</link>.                                             
&url.articles.articlename;      caminho relativo para articlename                         As entidades sao definidas para todos os artigos do FreeBSD.    
                                                                                                                                                          
Outras Entidades de Sistema Operacional
&linux;                         Linux(R)                                                  O sistema operacional Linux(R).                                 
&unix;                          UNIX(R)                                                   O sistema operacional UNIX(R).                                  
&windows;                       Windows(R)                                                O sistema operacional Windows(R).                               
                                                                                                                                                          
Entidades Diversas              
&prompt.root;                   #                                                         O prompt de usuario root .                                      
&prompt.user;                   %                                                         Um prompt para um usuario sem privilegios.                      
&postscript;                    PostScript(R)                                             A linguagem de programac,ao PostScript(R).                      
&tex;                           TeX                                                       A linguagem de composic,ao tipografica TeX.                     
&xorg;                          Xorg                                                      Xorg, Sistema X Window de codigo aberto.                        

9.3. Identificador Publico Formal (FPI)

   Em conformidade com as diretrizes do DocBook, para escrever FPIs
   customizadas do DocBook, o FPI para o DocBook DTD estendido do FreeBSD e:

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

9.4. Estrutura do Documento

   O DocBook permite a documentac,ao de estruturac,ao de varias maneiras. O
   Projeto de Documentac,ao do FreeBSD usa dois tipos principais de
   documentos do DocBook: o book e o article.

   Os livros (books) sao organizados em chapter s. Este e um requisito
   obrigatorio. Pode haver partes entre o livro e o capitulo para fornecer
   outra camada de organizac,ao. Por exemplo, o Handbook e organizado dessa
   maneira.

   Um capitulo(chapter) pode (ou nao) conter uma ou mais sec,oes. Estes sao
   indicados com o elemento sect1. Se uma sec,ao contiver outra sec,ao, use o
   elemento sect2 e assim por diante, ate sect5.

   Capitulos e sec,oes contem o restante do conteudo.

   Um artigo e mais simples que um livro e nao utiliza capitulos. Em vez
   disso, o conteudo de um artigo e organizado em uma ou mais sec,oes, usando
   os mesmos elementos sect1 (e sect2 e assim por diante) que sao usados
   &#8203;&#8203;em livros.

   A natureza do documento que esta sendo escrito deve ser usada para
   determinar se ele e melhor marcado como um livro ou um artigo. Os artigos
   sao adequados `a informac,ao que nao precisa ser dividida em varios
   capitulos, ou seja, relativamente curta, em ate 20-25 paginas de conteudo.
   Os livros sao mais adequados para informac,oes que podem ser divididas em
   varios capitulos, possivelmente com apendices e conteudo similar tambem.

   Os Tutoriais do FreeBSD estao todos marcados como artigos, enquanto este
   documento, o FAQ e o Handbook estao todos marcados como livros, por
   exemplo.

  9.4.1. Iniciando um Livro

   O conteudo de um livro esta dentro do elemento book. Alem de conter
   marcac,ao estrutural, esse elemento pode conter elementos que incluem
   informac,oes adicionais sobre o livro. Isso e uma meta-informac,ao, usada
   para fins de referencia ou conteudo adicional usado para produzir um
   titulo de pagina.

   Esta informac,ao adicional esta em um elemento info.

   Exemplo 9.1. Exemplo de book com info

 <book>
   <info>
     <title>Your Title Here</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>Your email address</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:your email address">Your name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Include an abstract of the book's contents here.</para>
     </abstract>
   </info>

   ...

 </book>

  9.4.2. Iniciando um Artigo

   O conteudo do artigo esta dentro do elemento article. Alem de conter
   marcac,ao estrutural, esse elemento pode conter elementos que incluem
   informac,oes adicionais sobre o artigo. Isso e uma meta-informac,ao, usada
   para fins de referencia ou conteudo adicional usado para produzir um
   titulo de pagina.

   Esta informac,ao adicional esta em um elemento info.

   Exemplo 9.2. Exemplo de article com info

 <article>
   <info>
     <title>Your title here</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>Your email address</email></address>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:your email address">Your name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Include an abstract of the article's contents here.</para>
     </abstract>
   </info>

   ...

 </article>

  9.4.3. Criando Capitulos

   Use chapter para marcar seus capitulos. Cada capitulo tem um title
   obrigatorio. Os artigos nao contem capitulos, eles sao reservados para
   livros.

   Exemplo 9.3. Um Capitulo Simples

 <chapter>
   <title>The Chapter's Title</title>

   ...
 </chapter>

   Um capitulo nao pode estar vazio; ele deve conter elementos alem do title.
   Se voce precisar incluir um capitulo vazio, basta usar um paragrafo vazio.

   Exemplo 9.4. Capitulos Vazios

 <chapter>
   <title>This is An Empty Chapter</title>

   <para></para>
 </chapter>

  9.4.4. Sec,oes Abaixo dos Capitulos

   Nos livros, os capitulos podem (mas nao precisam) ser divididos em
   sec,oes, subsec,oes e assim por diante. Nos artigos, as sec,oes sao o
   principal elemento estrutural e cada artigo deve conter pelo menos uma
   sec,ao. Use o elemento sectn. O n indica o numero da sec,ao, que
   identifica o nivel da sec,ao.

   A primeira sectn e sect1. Voce pode ter um ou mais destes em um capitulo.
   Eles podem conter um ou mais elementos sect2 e assim por diante, ate
   sect5.

   Exemplo 9.5. Sec,oes em Capitulos

 <chapter>
   <title>A Sample Chapter</title>

   <para>Some text in the chapter.</para>

   <sect1>
     <title>First Section</title>

     ...
   </sect1>

   <sect1>
     <title>Second Section</title>

     <sect2>
       <title>First Sub-Section</title>

       <sect3>
         <title>First Sub-Sub-Section</title>

         ...
       </sect3>
     </sect2>

     <sect2>
       <title>Second Sub-Section (1.2.2)</title>

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

  Nota:

   Os numeros de sec,ao sao gerados automaticamente e anexados aos titulos
   quando o documento e renderizado em um formato de saida. Os numeros de
   sec,ao e titulos gerados a partir do exemplo acima serao:

     * 1.1. First Section

     * 1.2. Second Section

     * 1.2.1. First Sub-Section

     * 1.2.1.1. First Sub-Sub-Section

     * 1.2.2. Second Sub-Section

  9.4.5. Subdividindo Utilizando Elementos part

   partes adiciona outro nivel de organizac,ao entre book e chapter com uma
   ou mais partes. Isso nao pode ser utilizado em um article.

 <part>
   <title>Introduction</title>

   <chapter>
     <title>Overview</title>

     ...
   </chapter>

   <chapter>
     <title>What is FreeBSD?</title>

     ...
   </chapter>

   <chapter>
     <title>History</title>

     ...
   </chapter>
 </part>

9.5. Elementos Block

  9.5.1. Paragrafos

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

   Quase todos os paragrafos da documentac,ao do FreeBSD usam para.
   formalpara inclui um elemento title, e simpara desabilita alguns elementos
   de um para. Utilize mais o para .

   Exemplo 9.6. Exemplo de um para

   Uso:

 <para>This is a paragraph.  It can contain just about any
   other element.</para>

   Aparencia:

   This is a paragraph. It can contain just about any other element.

  9.5.2. Bloco de Citac,oes

   Uma cotac,ao em bloco e uma cotac,ao estendida de outro documento que nao
   deve aparecer no paragrafo atual. Estes raramente sao necessarios.

   Os blockquotes podem, opcionalmente, conter um titulo e uma atribuic,ao
   (ou podem ser deixados sem titulo e sem atribuic,ao).

   Exemplo 9.7. Exemplo blockquote

   Uso:

 <para>A small excerpt from the US Constitution:</para>

 <blockquote>
   <title>Preamble to the Constitution of the United States</title>

   <attribution>Copied from a web site somewhere</attribution>

   <para>We the People of the United States, in Order to form a more
     perfect Union, establish Justice, insure domestic Tranquility,
     provide for the common defence, promote the general Welfare, and
     secure the Blessings of Liberty to ourselves and our Posterity, do
     ordain and establish this Constitution for the United States of
     America.</para>
 </blockquote>

   Aparencia:

   A small excerpt from the US Constitution:

     Preamble to the Constitution of the United States                        
                                                                            
     We the People of the United States, in Order to form a more perfect    
     Union, establish Justice, insure domestic Tranquility, provide for the 
     common defence, promote the general Welfare, and secure the Blessings  
     of Liberty to ourselves and our Posterity, do ordain and establish     
     this Constitution for the United States of America.                    
                                                --Copiado de um site qualquer

  9.5.3. Dicas, Notas, Avisos, Cuidados e Informac,oes Importantes

   Informac,oes adicionais podem precisar ser separadas do texto principal.
   Normalmente, essa e a informac,ao "meta" da qual o usuario deve estar
   ciente.

   Varios tipos de informac,oes estao disponiveis: tip, note, warning,
   caution, e important.

   O tipo a ser escolhido depende da situac,ao. A documentac,ao do DocBook
   sugere:

     * A nota e para informac,oes onde todos os leitores devem prestar
       atenc,ao.

     * Importante e uma variac,ao de Nota.

     * Cuidado e para informac,oes sobre possiveis perdas de dados ou danos
       ao software.

     * Aviso e para informac,oes sobre possiveis danos ao hardware, sobre
       risco de vida ou de ferimento a um membro.

   Exemplo 9.8. Example de tip e important

   Uso:

 <tip>
   <para>&os; may reduce stress.</para>
 </tip>

 <important>
   <para>Please use admonitions sparingly.  Too many admonitions
     are visually jarring and can have the opposite of the
     intended effect.</para>
 </important>

   Aparencia:

  Dica:

   FreeBSD may reduce stress.

  Importante:

   Please use admonitions sparingly. Too many admonitions are visually
   jarring and can have the opposite of the intended effect.

  9.5.4. Exemplos

   Exemplos podem ser apresentados com example.

   Exemplo 9.9. example

   Uso:

 <example>
   <para>Empty files can be created easily:</para>

   <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
 </example>

   Aparencia:

   Exemplo 9.10. example Renderizado

   Empty files can be created easily:

 % touch file1 file2 file3

  9.5.5. Listas e Procedimentos

   Muitas vezes, as informac,oes precisam ser apresentadas como listas ou
   como uma serie de etapas que devem ser realizadas para atingir um objetivo
   especifico.

   Para fazer isso, utilize itemizedlist, orderedlist, variablelist ou
   procedure. Existem outros tipos de elementos de lista no DocBook, mas nao
   os cobriremos aqui.

   itemizedlist e orderedlist sao semelhantes `as suas contrapartes em HTML,
   ul e ol. Cada um consiste em um ou mais elementos listitem, e cada
   listitem contem um ou mais elementos de bloco. Os elementos listitem sao
   analogos `as tags li do HTML. No entanto, ao contrario do HTML, eles sao
   obrigatorios.

   Exemplo 9.11. Exemplo de itemizedlist e orderedlist

   Uso:

 <itemizedlist>
   <listitem>
     <para>This is the first itemized item.</para>
   </listitem>

   <listitem>
     <para>This is the second itemized item.</para>
   </listitem>
 </itemizedlist>

 <orderedlist>
   <listitem>
     <para>This is the first ordered item.</para>
   </listitem>

   <listitem>
     <para>This is the second ordered item.</para>
   </listitem>
 </orderedlist>

   Aparencia:

     * This is the first itemized item.

     * This is the second itemized item.

    1. This is the first ordered item.

    2. This is the second ordered item.

   Uma maneira alternativa e frequentemente util de apresentar informac,oes e
   a variablelist. Estas sao listas onde cada entrada tem um termo e uma
   descric,ao. Eles sao adequados para muitos tipos de descric,oes e
   apresentam informac,oes de uma forma que geralmente e mais facil para o
   leitor do que sec,oes e subsec,oes.

   Uma variablelist tem um title e, em seguida, pares de entradas term e
   listitem.

   Exemplo 9.12. Exemplovariablelist

   Uso:

 <variablelist>
   <varlistentry>
     <term>Parallel</term>

     <listitem>
       <para>In parallel communications, groups of bits arrive
         at the same time over multiple communications
         channels.</para>
     </listitem>
   </varlistentry>

   <varlistentry>
     <term>Serial</term>

     <listitem>
       <para>In serial communications, bits arrive one at a
         time over a single communications
         channel.</para>
     </listitem>
   </varlistentry>
 </variablelist>

   Aparencia:

   Parallel

           In parallel communications, groups of bits arrive at the same time
           over multiple communications channels.

   Serial

           In serial communications, bits arrive one at a time over a single
           communications channel.

   Um procedure mostra uma serie de steps, que por sua vez consistem em mais
   steps ou substeps. Cada step contem elementos de bloco e pode incluir um
   titulo opcional.

   As vezes, os passos nao sao sequenciais, mas apresentam uma escolha: fazer
   isso ou fazer aquilo, mas nao ambos. Para essas escolhas alternativas, use
   stepalternatives.

   Exemplo 9.13. Exemplo procedure

   Uso:

 <procedure>
   <step>
     <para>Do this.</para>
   </step>

   <step>
     <para>Then do this.</para>
   </step>

   <step>
     <substeps>
       <step>
         <para>And now do this smaller thing.</para>
       </step>

       <step>
         <para>And now do this other smaller thing.</para>
       </step>
     </substeps>
   </step>

   <step>
     <para>Finally, do one of these:</para>

     <stepalternatives>
       <step>
         <para>Go left.</para>
       </step>

       <step>
         <para>Go right.</para>
       </step>
     </stepalternatives>
   </step>
 </procedure>

   Aparencia:

    1. Do this.

    2. Then do this.

    3.   a. And now do this small thing.

         b. And this other small thing.

    4. Finally, do one of these:

          * Go left.

          * Go right.

  9.5.6. Mostrando Exemplos de Arquivos

   Fragmentos de um arquivo (ou talvez um arquivo completo) sao mostrados
   agrupando-os no elemento programlisting.

   Espac,o em branco e quebra de linha dentro de programlisting sao
   importantes. Em particular, isso significa que a tag de abertura deve
   aparecer na mesma linha que a primeira linha da saida, e a tag de
   fechamento deve aparecer na mesma linha da ultima linha da saida, caso
   contrario linhas vazias podem ser incluidas.

   Exemplo 9.14. Exemplo programlisting

   Uso:

 <para>When finished, the program will look like
   this:</para>

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

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

   Observe como os colchetes angulares na linha #include precisam ser
   referenciados por suas entidades, em vez de serem incluidos literalmente.

   Aparencia:

   When finished, the program will look like this:

 #include <stdio.h>

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

  9.5.7. Chamadas

   Uma chamada e um marcador visual para se referenciar a um texto ou a uma
   posic,ao especifica em um exemplo.

   As chamadas sao marcadas com o elemento co. Cada elemento deve ter um id
   unico atribuido a ele. Apos o exemplo, inclua uma calloutlist que descreve
   cada frase de destaque.

   Exemplo 9.15. Exemplo co e calloutlist

 <para>When finished, the program will look like
   this:</para>

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

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

 <calloutlist>
   <callout arearefs="co-ex-include">
     <para>Includes the standard IO header file.</para>
   </callout>

   <callout arearefs="co-ex-return">
     <para>Specifies that <function>main()</function> returns an
       int.</para>
   </callout>

   <callout arearefs="co-ex-printf">
     <para>The <function>printf()</function> call that writes
       <literal>hello, world</literal> to standard output.</para>
   </callout>
 </calloutlist>

   Aparencia:

   When finished, the program will look like this:

 #include <stdio.h> 1

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

   1   Includes the standard IO header file.                           
   2   Specifies that main() returns an int.                           
   3   The printf() call that writes hello, world to standard output.  

  9.5.8. Tabelas

   Ao contrario de HTML, o DocBook nao precisa de tabelas para fins de
   layout, ja que a folha de estilo lida com esses problemas. Em vez disso,
   basta usar tabelas para marcar dados tabulares.

   Em termos gerais (e veja a documentac,ao do DocBook para mais detalhes),
   uma tabela (que pode ser formal ou informal) consiste em um elemento
   table. Este contem pelo menos um elemento tgroup, que especifica (como um
   atributo) o numero de colunas neste grupo de tabelas. Dentro do tgroup ha
   um elemento thead, que contem elementos para os titulos da tabela
   (cabec,alhos da coluna), e um tbody que contem o corpo da tabela.

   Ambos tgroup e thead contem elementos row, que por sua vez contem
   elementos entry. Cada elemento entry especifica uma celula na tabela.

   Exemplo 9.16. Exemplo informaltable

   Uso:

 <informaltable pgwide="1">
   <tgroup cols="2">
     <thead>
       <row>
         <entry>This is Column Head 1</entry>
         <entry>This is Column Head 2</entry>
       </row>
     </thead>

     <tbody>
       <row>
         <entry>Row 1, column 1</entry>
         <entry>Row 1, column 2</entry>
       </row>

       <row>
         <entry>Row 2, column 1</entry>
         <entry>Row 2, column 2</entry>
       </row>
     </tbody>
   </tgroup>
 </informaltable>

   Aparencia:

   +------------------------------------------------------------------------+
   |       This is Column Head 1        |       This is Column Head 2       |
   |------------------------------------+-----------------------------------|
   | Row 1, column 1                    | Row 1, column 2                   |
   |------------------------------------+-----------------------------------|
   | Row 2, column 1                    | Row 2, column 2                   |
   +------------------------------------------------------------------------+

   Sempre use o atributo pgwide com um valor 1 com o elemento informaltable.
   Um erro no Internet Explorer pode fazer com que a tabela seja renderizada
   incorretamente se isso for omitido.

   As bordas da tabela podem ser escondidas configurando o atributo frame
   para none no elemento informaltable. Por exemplo, informaltable
   frame="none".

   Exemplo 9.17. Exemplo de Tabela com frame="none"

   Aparencia:

           This is Column Head 1                This is Column Head 2         
   Row 1, column 1                       Row 1, column 2                      
   Row 2, column 1                       Row 2, column 2                      

  9.5.9. Exemplos para o Usuario Seguir

   Exemplos para o usuario seguir sao frequ:entemente necessarios.
   Normalmente, eles consistem em dialogos com o computador; o usuario digita
   um comando, o usuario recebe uma resposta de volta, o usuario digita outro
   comando e assim por diante.

   Varios elementos e entidades podem ser utilizados nestes casos.

   screen

           Tudo o que o usuario ve neste exemplo estara na tela do
           computador, entao o proximo elemento e screen .

           Dentro da screen, o espac,o em branco e significativo.

   prompt, &prompt.root; and &prompt.user;

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

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

  Nota:

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

   userinput

           Ao exibir o texto que o usuario deve digitar, coloque-o nas tags
           userinput. Ele provavelmente sera mostrado diferente para o
           usuario.

   Exemplo 9.18. Exemplos 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'

  Nota:

   Ainda que estejamos mostrando o conteudo do arquivo foo2, ele nao esta
   marcado como programlisting. Deixe o programlisting para mostrar
   fragmentos de arquivos fora do contexto de ac,oes do usuario.

9.6. Elementos In-line

  9.6.1. Realc,ando Informac,ao

   Para enfatizar uma palavra ou frase em particular, use emphasis. Isso pode
   ser apresentado em italico ou negrito, ou pode ser falado diferentemente
   com um sistema de conversao de texto em fala.

   Nao ha uma maneira de mudar a apresentac,ao da enfase no documento, nao
   existe um equivalente a b e i do HTML . Se as informac,oes apresentadas
   forem importantes, considere apresenta-las em important em vez de
   emphasis.

   Exemplo 9.19. Exemplo de emphasis

   Uso:

 <para>&os; is without doubt <emphasis>the</emphasis>
   premiere &unix;-like operating system for the Intel
   architecture.</para>

   Aparencia:

   FreeBSD is without doubt the premiere UNIX(R)-like operating system for
   the Intel architecture.

  9.6.2. Siglas

   Muitos termos de computador sao siglas, palavras formadas a partir da
   primeira letra de cada palavra em uma frase. Os acronimos sao marcados com
   elementos acronym. E util para o leitor quando um acronimo e definido no
   primeiro uso, como mostrado no exemplo abaixo.

   Exemplo 9.20. Exemplo acronym

   Uso:

 <para>Request For Comments (<acronym>RFC</acronym>) 1149
   defined the use of avian carriers for transmission of
   Internet Protocol (<acronym>IP</acronym>) data.  The
   quantity of <acronym>IP</acronym> data currently
   transmitted in that manner is unknown.</para>

   Aparencia:

   Request For Comments (RFC) 1149 defined the use of avian carriers for
   transmission of Internet Protocol (IP) data. The quantity of IP data
   currently transmitted in that manner is unknown.

  9.6.3. Citac,oes

   Para citar texto de outro documento ou fonte, ou para denotar uma frase
   que e usada de forma figurada, use quote. A maioria das tags de marcac,ao
   disponiveis para texto normal tambem esta disponivel em quote.

   Exemplo 9.21. Exemplo quote

   Uso:

 <para>However, make sure that the search does not go beyond the
   <quote>boundary between local and public administration</quote>,
   as <acronym>RFC</acronym> 1535 calls it.</para>

   Aparencia:

   However, make sure that the search does not go beyond the "boundary
   between local and public administration", as RFC 1535 calls it.

  9.6.4. Teclas, Botoes do Mouse e Combinac,oes

   Para se referir a uma tecla especifica no teclado, use keycap. Para se
   referir a um botao do mouse, use mousebutton. E para se referir a
   combinac,oes de pressionamentos de teclas ou cliques do mouse, coloque
   todos eles em keycombo.

   keycombo tem um atributo chamado action, que pode ser um dos click,
   double-click, other, press, seq, ou simul. Os dois ultimos valores indicam
   se as teclas ou botoes devem ser pressionados em sequencia ou
   simultaneamente.

   As folhas de estilo adicionam automaticamente quaisquer simbolos de
   conexao, como +, entre os nomes das chaves, quando agrupados em keycombo.

   Exemplo 9.22. Exemplos de Teclas, Botoes do Mouse e Combinac,oes

   Uso:

 <para>To switch to the second virtual terminal, press
   <keycombo action="simul"><keycap>Alt</keycap>
     <keycap>F1</keycap></keycombo>.</para>

 <para>To exit <command>vi</command> without saving changes, type
   <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
     <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

 <para>My window manager is configured so that
   <keycombo action="simul"><keycap>Alt</keycap>
     <mousebutton>right</mousebutton>
   </keycombo> mouse button is used to move windows.</para>

   Aparencia:

   To switch to the second virtual terminal, press Alt+F1.

   To exit vi without saving changes, type Esc : q !.

   My window manager is configured so that Alt+right mouse button is used to
   move windows.

  9.6.5. Aplicativos, Comandos, Opc,oes e Citac,oes

   Ambos os aplicativos e comandos sao frequentemente utiilzados ao escrever
   uma documentac,ao. A distinc,ao entre eles e que um aplicativo e o nome de
   um programa ou conjunto de programas que preenche uma tarefa especifica.
   Um comando e o nome do arquivo de um programa que o usuario pode digitar e
   executar em uma linha de comando.

   Muitas vezes e necessario mostrar algumas das opc,oes que um comando pode
   ter.

   Finalmente, muitas vezes e util listar um comando com seu numero de sec,ao
   do manual, no formato "command(number)" que e comum em manuais Unix.

   Marque nomes de aplicac,oes com application.

   Para listar um comando com seu numero de sec,ao do manual (que deve ser
   utilizado com maior frequencia), o elemento DocBook e citerefentry. Isto
   ira conter mais dois elementos, refentrytitle e manvolnum. O conteudo de
   refentrytitle e o nome do comando, e o conteudo do manvolnum e a sec,ao da
   pagina de manual.

   Isso pode ser trabalhoso para escrever e assim uma serie de entidades
   gerais foram criadas para tornar esse processo mais facil. Cada entidade
   assume o formato &man.manual-page.manual-section;.

   O arquivo que contem essas entidades esta em doc/share/xml/man-refs.ent e
   pode ser referenciado usando este FPI:

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

   Portanto, a introduc,ao `a documentac,ao do FreeBSD geralmente incluira
   isto:

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

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

 ...

 ]>

   Use command para incluir um nome de comando "in-line", mas mostre como
   algo que o usuario deve digitar.

   Use option para marcar as opc,oes que serao passadas para um comando.

   Ao se referir ao mesmo comando varias vezes nas proximidades, e preferivel
   usar a notac,ao &man.command.section; para marcac,ao a primeira referencia
   e use command para marcar as referencias subsequentes. Isso faz com que a
   saida gerada, especialmente HTML, aparec,a visualmente melhor.

   Exemplo 9.23. Exemplo de Aplicac,oes, Comandos e Opc,oes

   Uso:

 <para><application>Sendmail</application> is the most
   widely used Unix mail application.<para>

 <para><application>Sendmail</application> includes the
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
   programs.</para>

 <para>One of the command line parameters to <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, <option>-bp</option>, will display the current
   status of messages in the mail queue.  Check this on the command
   line by running <command>sendmail -bp</command>.</para>

   Aparencia:

   Sendmail e o aplicativo de email Unix mais utilizado.

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

   Um dos parametros da linha de comando para o sendmail(8), -bp, exibira o
   status atual das mensagens no fila de email. Verifique isso na linha de
   comando executando sendmail -bp.

  Nota:

   Observe como a notac,ao &man..section; e mais facil de ser seguida.

  9.6.6. Arquivos, Diretorios, Extensoes, Nomes de Dispositivo

   Para se referir ao nome de um arquivo, um diretorio, uma extensao de
   arquivo ou um nome de dispositivo, use filename.

   Exemplo 9.24. Exemplo filename

   Uso:

 <para> O codigo fonte do Handbook em ingles e encontrada em
   <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
   O arquivo principal e chamado <filename>book.xml</filename>.
   Ha tambem um <filename>Makefile</filename> e varios arquivos com a extensao <filename>.ent</filename>.</para>

 <para><filename>kbd0</filename> e o primeiro teclado detectado
   pelo sistema e aparece em
   <filename>/dev</filename>. </para>

   Aparencia:

   O codigo fonte do Handbook em ingles e encontrada em
   /usr/doc/en_US.ISO8859-1/books/handbook/. O arquivo principal e chamado
   book.xml. Ha tambem um Makefile e varios arquivos com a extensao .ent.

   kbd0 e o primeiro teclado detectado pelo sistema e aparece em /dev.

  9.6.7. Nome dos Ports

  Extensao FreeBSD:

   Estes elementos fazem parte da extensao do FreeBSD ao DocBook, e nao
   existem no DocBook DTD original.

   Para incluir o nome de um programa da Colec,ao de Ports do FreeBSD no
   documento, use a tag package. Como a Colec,ao de Ports pode ser instalada
   em qualquer local, inclua apenas a categoria e o nome do port; nao inclua
   /usr/ports.

   Por padrao, package refere-se a um pacote binario. Para se referir a um
   port que sera compilado a partir do codigo fonte, configure o atributo
   role para port.

   Exemplo 9.25. Exemplo de package

   Uso:

 <para>Instale o pacote binario <package>net/wireshark</package> para
   visualizar o trafego de rede.</para>

 <para><package role="port">net/wireshark</package> tambem pode ser
   compilado e instalado pela Colec,ao de Ports.</para>

   Aparencia:

   Instale o pacote binario net/wireshark para visualizar o trafego de rede.

   O net/wireshark tambem pode ser compilado e instalado pela Colec,ao de
   Ports.

  9.6.8. Hosts, Dominios, Enderec,os IP, Usuario, Grupo e Outros Itens do
  Sistema

  Extensao FreeBSD:

   Estes elementos fazem parte da extensao do FreeBSD ao DocBook, e nao
   existem no DocBook DTD original.

   Informac,oes para "itens do sistema" estao marcadas com systemitem. O
   atributo class e usado para identificar o tipo especifico de informac,ao
   mostrada.

   class="domainname"

           O texto e um nome de dominio, como FreeBSD.org ou ngo.org.uk. Nao
           ha nenhum componente de nome de host.

   class="etheraddress"

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

   class="fqdomainname"

           O texto e um nome de dominio FQDM, com ambos nome de dominio e
           hostname.

   class="ipaddress"

           O texto e um enderec,o de IP.

   class="netmask"

           O texto e uma mascara de rede, que pode ser expressa igual a um
           IP, uma sequencia hexadecimal ou como um / seguido por um numero
           (notac,ao CIDR).

   class="systemname"

           Com class="systemname", as informac,oes marcadas sao o nome do
           host simples, como freefall ou wcarchive.

   class="username"

           O texto e um nome de usuario, como root.

   class="groupname"

           O texto e um grupo, como wheel.

   Exemplo 9.26. Exemplos systemitem

   Uso:

 <para>The local machine can always be referred to by the
   name <systemitem class="systemname">localhost</systemitem>, which will have the IP
   address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

 <para>The <systemitem class="domainname">FreeBSD.org</systemitem>
   domain contains a number of different hosts, including
   <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
   <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>

 <para>When adding an <acronym>IP</acronym> alias to an
   interface (using <command>ifconfig</command>)
   <emphasis>always</emphasis> use a netmask of
   <systemitem class="netmask">255.255.255.255</systemitem> (which can
   also be expressed as
   <systemitem class="netmask">0xffffffff</systemitem>).</para>

 <para>The <acronym>MAC</acronym> address uniquely identifies
   every network card in existence.  A typical
   <acronym>MAC</acronym> address looks like
   <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>

 <para>To carry out most system administration functions
   requires logging in as <systemitem class="username">root</systemitem>.</para>

   Aparencia:

   A maquina local sempre pode ser referenciada 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.

   Ao adicionar um alias de IP a uma interface (usando ifconfig) sempre use
   uma mascara de rede de 255.255.255.255 (que tambem pode ser expressa como
   0xffffffff).

   O enderec,o MAC identifica exclusivamente todas as placas de rede
   existentes. Um enderec,o MAC tipico se parece com 08:00:20:87:ef:d0.

   Para executar a maioria das func,oes de administrac,ao do sistema, e
   necessario efetuar login como root.

  9.6.9. Identificadores Uniformes de Recursos (URIs)

   Ocasionalmente, e util mostrar um Identificador de Recurso Uniforme (URI)
   sem torna-lo um hiperlink ativo. O elemento uri torna isso possivel:

   Exemplo 9.27. Exemplo uri

   Uso:

 <para>Esta URL e mostrada apenas como texto:
   <uri>https://www.FreeBSD.org</uri>. Nao e criado um link.</para>

   Aparencia:

   Esta URL e mostrada apenas como texto: https://www.FreeBSD.org. Nao e
   criado um link.

   Para criar links, consulte Sec,ao 9.8, "Links".

  9.6.10. Enderec,os de Email

   Os enderec,os de email sao marcados como elementos email. No formato de
   saida HTML, o texto marcado se torna um hiperlink para o enderec,o de
   email. Outros formatos de saida que suportam hiperlinks tambem podem
   tornar o enderec,o de email em um link.

   Exemplo 9.28. Exemplo de Hiperlink com email

   Uso:

 <para> Um enderec,o de email que nao existe, como
   <email>notreal@example.com</email>, pode ser usado como um
   exemplo </para>

   Aparencia:

   Um enderec,o de email que nao existe, como <notreal@example.com>, pode ser
   usado como exemplo.

   Uma extensao especifica do FreeBSD permite configurar o atributo role para
   nolink para evitar a criac,ao do hiperlink para o enderec,o de email.

   Exemplo 9.29. Exemplo de email Sem Hiperlink

   Uso:

 <para> As vezes, o link para um enderec,o de email como
   <email role="nolink">notreal@example.com</email> nao e
   desejado.</para>

   Aparencia:

   As vezes, o link para um enderec,o de email como <notreal@example.com> nao
   e desejado.

  9.6.11. Descrevendo Makefiles

  Extensao FreeBSD:

   Estes elementos fazem parte da extensao do FreeBSD ao DocBook, e nao
   existem no DocBook DTD original.

   Existem dois elementos para descrever partes de Makefiles, buildtarget e
   varname.

   buildtarget identifica um destino de compilac,ao exportado por um Makefile
   que pode ser fornecido como um parametro para o make. varname identifica
   uma variavel que pode ser definida (no ambiente, na linha de comando com o
   make, ou dentro do Makefile) para influenciar o processo.

   Exemplo 9.30. Exemplo de buildtarget e varname

   Uso:

 <para>Two common targets in a <filename>Makefile</filename>
   are <buildtarget>all</buildtarget> and
   <buildtarget>clean</buildtarget>.</para>

 <para>Typically, invoking <buildtarget>all</buildtarget> will
   rebuild the application, and invoking
   <buildtarget>clean</buildtarget> will remove the temporary
   files (<filename>.o</filename> for example) created by the
   build process.</para>

 <para><buildtarget>clean</buildtarget> may be controlled by a
   number of variables, including <varname>CLOBBER</varname>
   and <varname>RECURSE</varname>.</para>

   Aparencia:

   Dois targets comuns em um Makefile sao all e clean.

   Normalmente, invocar all ira reconstruir o aplicativo, e invocar clean
   removera os arquivos temporarios (.o por exemplo) criados pelo processo de
   compilac,ao.

   clean pode ser controlado por varias de variaveis, incluindo CLOBBER e
   RECURSE.

  9.6.12. Texto Literal

   O texto literal, ou texto que deve ser inserido na integra, e
   frequentemente necessario na documentac,ao. Este e um texto extraido de
   outro arquivo ou que deve ser copiado exatamente como mostrado na
   documentac,ao em um outro arquivo.

   Na maioria das vezes, programlisting sera suficiente para denotar este
   texto. Mas programlisting nem sempre e apropriado, particularmente quando
   voce quer incluir uma parte de um arquivo "in-line" com o resto do
   paragrafo.

   Nestes casos, use literal.

   Exemplo 9.31. Exemplo literal

   Uso:

 <para>The <literal>maxusers 10</literal> line in the kernel
   configuration file determines the size of many system tables, and is
   a rough guide to how many simultaneous logins the system will
   support.</para>

   Aparencia:

   A linha maxusers 10 no arquivo de configurac,ao do kernel determina o
   tamanho de muitas tabelas do sistema e e um guia aproximado de quantos
   logins simultaneos o sistema suportara.

  9.6.13. Mostrando Itens que o Usuario Deve Preencher

   Havera diversos momentos em que o usuario ira ver o que fazer, ou sera
   referenciado a um arquivo ou linha de comando, mas nao podera simplesmente
   copiar o exemplo fornecido. Em vez disso, eles precisam fornecer algumas
   informac,oes.

   replaceable e projetado para essa eventualidade. Use isso dentro de outros
   elementos para indicar partes do conteudo desse elemento que o usuario
   deve substituir.

   Exemplo 9.32. Exemplo de replaceable

   Uso:

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

   Aparencia:

 % man command

   replaceable pode ser usado em diversos elementos, incluindo literal. Este
   exemplo tambem mostra que o replaceable deve estar apenas em torno do
   conteudo que o usuario esta destinado a fornecer. O outro conteudo deve
   ser deixado de lado.

   Uso:

 <para>The <literal>maxusers <replaceable>n</replaceable></literal>
   line in the kernel configuration file determines the size of many system
   tables, and is a rough guide to how many simultaneous logins the system will
   support.</para>

 <para>For a desktop workstation, <literal>32</literal> is a good value
   for <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 e um guia aproximado de quantos
   logins simultaneos o sistema suportara.

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

  9.6.14. Mostrando Botoes GUI

   Os botoes apresentados por uma interface grafica do usuario sao marcados
   com guibutton. Para tornar o texto mais parecido com um botao grafico,
   colchetes e espac,os nao separaveis &#8203;&#8203;sao adicionados em volta
   do texto.

   Exemplo 9.33. Exemplo guibutton

   Uso:

 <para>Edit the file, then click
   <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
   changes.</para>

   Aparencia:

   Edite o arquivo e clique em [ Salvar ] para salvar as alterac,oes.

  9.6.15. Citac,oes de Erros do Sistema

   Erros de sistema gerados pelo FreeBSD sao marcados com errorname. Isso
   indica o erro exato que aparece.

   Exemplo 9.34. Exemplo errorname

   Uso:

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

   Aparencia:

 Panic: cannot mount root

9.7. Imagens

  Importante:

   O suporte de imagem na documentac,ao e um pouco experimental. Os
   mecanismos descritos aqui provavelmente nao mudarao, mas isso nao e
   garantido.

   Para fornecer conversao entre diferentes formatos de imagem, o port
   graphics/ImageMagick deve estar instalado. Esse port nao esta incluido no
   meta port textproc/docproj e deve ser instalado separadamente.

   Um bom exemplo do uso de imagens e o documento graphics/ImageMagick.
   Examine os arquivos nesse diretorio para ver como esses elementos sao
   usados &#8203;&#8203;juntos. Crie formatos de saida diferentes para ver
   como o formato determina quais imagens sao mostradas no documento
   renderizado.

  9.7.1. Formatos de Imagem

   Os seguintes formatos de imagem sao suportados atualmente. Um arquivo de
   imagem sera automaticamente convertido em bitmap ou imagem vetorial,
   dependendo do formato do documento de saida.

   Estes sao os formatos somente nos quais as imagens devem ser enviadas para
   o repositorio de documentac,ao.

   EPS (Encapsulated Postscript)

           Imagens com base principalmente em vetores, como diagramas de
           rede, linhas de tempo e similares, devem estar nesse formato.
           Estas imagens tem uma extensao .eps.

   PNG (Portable Network Graphic)

           Para bitmaps, como capturas de tela, use este formato. Essas
           imagens tem a extensao .png.

   PIC (PIC graphics language)

           PIC e uma linguagem para desenhar figuras baseadas em vetor
           simples usadas no utilitario pic(1). Essas imagens tem a extensao
           .pic.

   SCR (SCReen capture)

           Este formato e especifico para capturas de tela da saida do
           console. O seguinte comando gera um arquivo SCR shot.scr do buffer
           de video /dev/ttyv0:

 # vidcontrol -p < /dev/ttyv0 > shot.scr

           E preferivel o formato PNG para capturas de tela porque o arquivo
           SCR contem texto sem formatac,ao das linhas de comando para que
           possa ser convertido em uma imagem PNG ou um texto simples,
           dependendo do formato do documento de saida.

   Use o formato apropriado para cada imagem. A documentac,ao geralmente tem
   uma mistura de imagens EPS e PNG. O Makefile assegura que a imagem de
   formato correta seja escolhida dependendo do formato de saida usado. Nao
   envie a mesma imagem ao repositorio em dois formatos diferentes.

  Importante:

   O Projeto de Documentac,ao pode eventualmente mudar para o formato SVG
   (Scalable Vector Graphic) para imagens vetoriais. No entanto, o estado
   atual das ferramentas de edic,ao compativeis com SVG torna isso inviavel.

  9.7.2. Localizac,oes das Imagens

   As imagens podem ser armazenados em um dos diversos locais abaixo,
   dependendo do documento e da imagem:

     * No mesmo diretorio do documento em si, geralmente feito para artigos e
       pequenos livros que mantem todos os arquivos em um unico diretorio.

     * Em um subdiretorio do documento principal. Geralmente feito quando um
       livro grande usa subdiretorios separados para organizar capitulos
       individuais.

       Quando as imagens sao armazenadas em um subdiretorio do diretorio do
       documento principal, o nome do subdiretorio deve ser incluido em seus
       caminhos no Makefile e no elemento imagedata.

     * Em um subdiretorio de doc/share/images nomeado apos o documento. Por
       exemplo, as imagens do Handbook estao armazenadas em
       doc/share/images/books/handbook. Imagens que funcionam para varias
       traduc,oes sao armazenadas neste nivel superior da arvore de arquivos
       da documentac,ao. Geralmente, estas sao imagens que podem ser usadas
       inalteradas em traduc,oes nao inglesas do documento.

  9.7.3. Marcac,ao em Imagem

   As imagens sao incluidas como parte de um mediaobject. O mediaobject pode
   conter outros objetos mais especificos. Estamos preocupados com dois, o
   imageobject e o textobject.

   Inclua um imageobject e dois elementos textobject. O imageobject apontara
   para o nome do arquivo de imagem sem a extensao. Os elementos textobject
   contem informac,oes que serao apresentadas ao usuario, bem como, ou em vez
   da propria imagem.

   Elementos de texto sao mostrados ao leitor em varias situac,oes. Quando o
   documento e exibido em HTML, elementos de texto sao mostrados enquanto a
   imagem esta sendo carregada ou se o ponteiro do mouse estiver sobre a
   imagem ou se um navegador somente texto estiver sendo usado. Em formatos
   como texto simples, onde os graficos nao sao possiveis, os elementos de
   texto sao mostrados em vez dos graficos.

   Este exemplo mostra como incluir uma imagem chamada fig1.png em um
   documento. A imagem e um retangulo com um A dentro dela:

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

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

   <textobject>
     <phrase>A picture</phrase> 3
   </textobject>
 </mediaobject>

   1 Inclua um elemento imagedata dentro do elemento imageobject. O atributo  
     fileref deve conter o nome do arquivo da imagem a ser incluida, sem a    
     extensao. As folhas de estilo irao descobrir qual extensao deve ser      
     adicionada ao nome do arquivo automaticamente.                           
   2 O primeiro textobject contem um elemento literallayout, onde o atributo  
     class e definido como monospaced. Esta e uma oportunidade para           
     demonstrar habilidades artisticas em ASCII. Este conteudo sera usado se  
     o documento for convertido em texto simples.                             
                                                                              
     Observe como a primeira e a ultima linha do conteudo do elemento         
     literallayout aparecem ao lado das tags do elemento. Isso garante que    
     nenhum espac,o em branco seja incluido.                                  
   3 O segundo textobject contem um unico elemento phrase. O conteudo desta   
     frase se tornara o atributo alt para a imagem quando este documento for  
     convertido para HTML.                                                    

  9.7.4. Entradas de Imagem no Makefile

   As imagens devem estar listadas no Makefile na variavel IMAGES. Esta
   variavel deve conter os nomes de todas as imagens source. Por exemplo, se
   houver tres figuras, fig1.eps, fig2.png, fig3.png, entao o Makefile deve
   ter linhas como esta.

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

   ou

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

   Novamente, o Makefile ira elaborar a lista completa de imagens necessarias
   para compilar o documento, voce so precisa listar os arquivos de imagem
   que voce forneceu.

  9.7.5. Imagens e Capitulos em Subdiretorios

   Tenha cuidado ao separar a documentac,ao em arquivos menores em diretorios
   diferentes (consulte Sec,ao 7.7.1, "Usando Entidades Gerais para Incluir
   Arquivos").

   Imagine que haja um livro com tres capitulos e os capitulos sejam
   armazenados em seus proprios diretorios, chamados chapter1/chapter.xml,
   chapter2/chapter.xml e chapter3/chapter.xml. Se cada capitulo tiver
   imagens associadas, coloque essas imagens no subdiretorio de cada capitulo
   (chapter1/, chapter2/, e chapter3/).

   No entanto, fazer isso requer a inclusao dos nomes de diretorio na
   variavel IMAGES no Makefile, e a inclusao do nome do diretorio no elemento
   imagedata no documento.

   Por exemplo, se o livro 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
 ...

9.8. Links

  Nota:

   Links tambem sao elementos in-line. Para mostrar uma URI sem criar um
   link, consulte Sec,ao 9.6.9, "Identificadores Uniformes de Recursos
   (URIs)".

  9.8.1. Atributos xml:id

   A maioria dos elementos DocBook aceita um atributo xml:id para dar a essa
   parte do documento um nome exclusivo. O xml:id pode ser usado como um
   destino para uma referencia cruzada ou link.

   Qualquer parte do documento que sera um destino de link deve ter um
   atributo xml:id. Atribuir um xml:id a todos os capitulos e sec,oes, mesmo
   que nao haja planos atuais para criar link para eles, e uma boa ideia.
   Esses xml:id s podem ser usados &#8203;&#8203;como pontos de referencia
   exclusivos por qualquer pessoa que se refira `a versao do documento HTML.

   Exemplo 9.35. xml:id em Ccapitulos e sSec,oes de eExemplo

 <chapter xml:id="introduction">
   <title>Introduction</title>

   <para>This is the introduction.  It contains a subsection,
     which is identified as well.</para>

   <sect1 xml:id="introduction-moredetails">
     <title>More Details</title>

     <para>This is a subsection.</para>
   </sect1>
 </chapter>

   Use valores descritivos para nomes de xml:id. Os valores devem ser
   exclusivos em todo o documento, nao apenas em um unico arquivo. No
   exemplo, a subsec,ao xml:id e construida anexando o texto ao capitulo
   xml:id. Isso garante que os xml:id s sejam exclusivos. Ele tambem ajuda o
   leitor e qualquer um que editar o documento a ver onde o link esta
   localizado no documento, semelhante a um caminho de diretorio para um
   arquivo.

  9.8.2. Referencias Cruzadas com xref

   xref fornece ao leitor um link para ir para outra sec,ao do documento. O
   destino xml:id e especificado no atributo linkend e xref gera o texto do
   link automaticamente.

   Exemplo 9.36. Exemplo xref

   Imagine que esse fragmento aparec,a em algum lugar em um documento que
   inclua o exemplo xml:id mostrado acima:

 <para>More information can be found
   in <xref linkend="introduction"/>.</para>

 <para>More specific information can be found
   in <xref linkend="introduction-moredetails"/>.</para>

   O texto do link sera gerado automaticamente, parecendo como (O enfatizado
   indica o texto do link):

     Mais informac,oes podem ser encontradas no Capitulo 1, Introduc,ao.

     Informac,oes mais especificas podem ser encontradas em Sec,ao 1.1, "Mais
     Detalhes".

   O texto do link e gerado automaticamente a partir do capitulo e numero da
   sec,ao e elementos title.

  9.8.3. Criando Links para Outros Documentos na Web

   O elemento link descrito aqui permite que o escritor defina o texto do
   link. Quando o texto do link e usado, e muito importante ser descritivo
   para dar ao leitor uma ideia de onde o link vai. Lembre-se que o DocBook
   pode ser renderizado para varios tipos de midia. O leitor pode estar
   olhando para um livro impresso ou outra forma de midia onde nao ha links.
   Se o texto do link nao for descritivo o suficiente, talvez o leitor nao
   consiga localizar a sec,ao vinculada.

   O atributo xlink:href e a URL da pagina, e o conteudo do elemento e o
   texto que sera exibido para o usuario ativar.

   Em muitas situac,oes, e preferivel mostrar a URL real em vez do texto.
   Isso pode ser feito deixando de fora o texto do elemento.

   Exemplo 9.37. link para um Exemplo de Pagina Web de Documentac,ao do
   FreeBSD

   Link para uma URL de uma entidade. de livro ou artigo Para criar um link
   para um capitulo especifico de um livro, adicione uma barra e o nome do
   arquivo do capitulo, seguido por uma ancora opcional dentro do capitulo.
   Para artigos, crie um link para a entidade URL do artigo, seguida por uma
   ancora opcional no artigo. As entidades URL podem ser encontradas em
   doc/share/xml/urls.ent.

   Uso para links de livros do FreeBSD:

 <para>Read the <link
     xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
     introduction</link>, then pick the nearest mirror from
   the list of <link
     xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
     mirror sites</link>.</para>

   Aparencia:

   Leia a Introduc,ao ao SVN, em seguida, escolha o espelho mais proximo do
   lista de sites espelho do Subversion.

   Uso para links de artigos do FreeBSD:

 <para>Read this
   <link xlink:href="&url.articles.bsdl-gpl;">article
     about the BSD license</link>, or just the
   <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>

   Aparencia:

   Leia este artigo sobre a licenc,a BSD, ou apenas a sua introduc,ao.

   Exemplo 9.38. link para um Exemplo de Pagina Web do FreeBSD

   Uso:

 <para>Of course, you could stop reading this document and go to the
   <link xlink:href="&url.base;/index.html">FreeBSD home page</link> instead.</para>

   Aparencia:

   Claro, voce pode parar de ler este documento e ir para a pagina inicial do
   FreeBSD.

   Exemplo 9.39. link para um Exemplo de Pagina Web Externa

   Uso:

 <para>Wikipedia has an excellent reference on
   <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
     Partition Tables</link>.</para>

   Aparencia:

   A Wikipedia tem uma excelente referencia em Tabelas de Partic,ao GUID.

   O texto do link pode ser omitido para mostrar a URL real:

 <para>Wikipedia has an excellent reference on
   GUID Partition Tables: <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"></link>.</para>

   O mesmo link pode ser inserido usando notac,ao mais curta em vez de uma
   tag de finalizac,ao separada:

 <para>Wikipedia has an excellent reference on
   GUID Partition Tables: <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"/>.</para>

   Os dois metodos sao equivalentes. Aparencia:

   A Wikipedia tem uma excelente referencia em Tabelas de Partic,ao GUID:
   http://en.wikipedia.org/wiki/GUID_Partition_Table .

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

   [1] Um breve historico pode ser encontrado em
   http://www.oasis-open.org/docbook/intro.shtml#d0e41.

                         Capitulo 10. Folhas de Estilo

   Indice

   10.1. CSS

   O XML se preocupa com o conteudo e nao diz nada sobre como esse conteudo
   deve ser apresentado ao leitor ou renderizado no papel. Multiplas
   linguagens de folha de estilo foram desenvolvidas para descrever o layout
   visual, incluindo a Transformac,ao de Linguagem de Folha de Estilo
   Extensivel (XSLT), Semantica de Estilo de Documento e Linguagem de
   Especificac,ao (DSSSL ) e Folhas de Estilo em Cascata (CSS).

   Os documentos do FDP usam folhas de estilo XSLT para transformar o DocBook
   em XHTML, e entao a formatac,ao CSS e aplicada nas paginas XHTML. A saida
   imprimivel e atualmente renderizada com folhas de estilo legadas do DSSSL,
   mas isso provavelmente mudara no futuro.

10.1. CSS

   Folhas de estilos em cascata (CSS) sao um mecanismo para anexar
   informac,oes de estilo (font, weight, size, color e assim por diante) a
   elementos em um documento XHTML sem abusar de XHTML para o fazer.

  10.1.1. Os Documentos DocBook

   As folhas de estilo XSLT e DSSSL do FreeBSD se referem a docbook.css, que
   deve estar presente no mesmo diretorio que os arquivos XHTML. O arquivo
   CSS de todo o projeto e copiado de doc/share/misc/docbook.css quando os
   documentos sao convertidos para XHTML e sao instalados automaticamente .

                            Capitulo 11. Traduc,oes

   Este e o FAQ para pessoas que estao traduzindo a documentac,ao do FreeBSD
   (FAQ, Handbook, tutoriais, paginas de manual e outros) para diferentes
   idiomas.

   Ele e fortemente baseado na traduc,ao do FAQ do Projeto de Documentac,ao
   Alemao do FreeBSD, originalmente escrito por Frank Gru:nder
   <elwood@mc5sys.in-berlin.de> e traduzido de volta para o ingles por Bernd
   Warken <bwarken@mayn.de>.

   O FAQ e mantido pela Equipe de Engenharia de Documentac,ao
   <doceng@FreeBSD.org>.

   11.1. O que significa i18n e l10n?

   11.2. Existe uma lista de discussao para tradutores?

   11.3. Sao necessarios mais tradutores?

   11.4. Quais idiomas eu preciso saber?

   11.5. Quais softwares eu preciso conhecer?

   11.6. Como eu fac,o para descobrir se ja existem outras pessoas traduzindo
   documentos para o meu idioma?

   11.7. Ninguem mais esta traduzindo para o meu idioma. O que eu fac,o?

   11.8. Eu ja tenho alguns documentos traduzidos, para onde eu devo
   envia-los?

   11.9. Eu sou a unica pessoa trabalhando na traduc,ao para este idioma,
   como fac,o para enviar minha traduc,ao?

   11.10. Posso incluir um texto especifico do idioma ou do pais em minha
   traduc,ao?

   11.11. Como os caracteres especificos do idioma podem ser incluidos?

   11.12. Dirigindo-se ao leitor

   11.13. Preciso incluir informac,oes adicionais nas minhas traduc,oes?

   11.1.  O que significa i18n e l10n?                                        
          i18n significa internacionalizac,ao e l10n significa localizac,ao.  
          Sao apenas uma abreviac,ao.                                         
                                                                              
          i18n pode ser lido como "i" seguido por 18 letras, seguido por "n". 
          Da mesma forma, l10n e "l" seguido por 10 letras, seguido por "n".  
   11.2.  Existe uma lista de discussao para tradutores?                      
          Sim. Diferentes grupos de traduc,ao tem suas proprias listas de     
          discussao. A lista dos projetos de traduc,ao possui mais            
          informac,oes sobre as listas de discussao e sites web mantidos por  
          cada projeto de traduc,ao. Alem disso, existe a                     
          <freebsd-translators@freebsd.org> para discussao geral de           
          traduc,ao.                                                          
   11.3.  Sao necessarios mais tradutores?                                    
          Sim. Quanto mais pessoas trabalham na traduc,ao, mais rapido 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.    
   11.4.  Quais idiomas eu preciso saber?                                     
          Idealmente, voce devera possuir um bom conhecimento de Ingles       
          escrito, e obviamente, precisara ser fluente no idioma para o qual  
          esta traduzindo.                                                    
                                                                              
          Ingles nao e estritamente necessario. Por exemplo, voce poderia     
          fazer uma traduc,ao Hungara do FAQ da traduc,ao em Espanhol.        
   11.5.  Quais softwares eu preciso conhecer?                                
          E fortemente recomendado que voce mantenha uma copia local do       
          repositorio Subversion do FreeBSD (pelo menos a parte da            
          documentac,ao). Isso pode ser feito executando:                     
                                                                              
          % svn checkout https://svn.FreeBSD.org/doc/head/ head               
                                                                              
          svn.FreeBSD.org e um servidor publico SVN. Verifique o certificado  
          do servidor na lista de Mirrors de Subversion.                      
                                                                              
            Nota:                                                             
                                                                              
          Sera necessario que o pacote devel/subversion esteja 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  
                                                                              
          Por favor, veja a explicac,ao completa de como usar o Subversion no 
          FreeBSD no FreeBSD Handbook.                                        
   11.6.  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. Se outras pessoas ja     
          estiverem trabalhando na traduc,ao de documentac,ao para o seu      
          idioma, por favor, nao duplique os esforc,os. Em vez disso, entre   
          em contato para saber como voce pode ajudar.                        
                                                                              
          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.  
   11.7.  Ninguem mais esta traduzindo para o meu idioma. O que eu fac,o?     
          Parabens, voce acabou de iniciar o " Projeto de Traduc,ao da        
          Documentac,ao do FreeBSD em seu idioma aqui ". 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 o FAQ ou um dos tutoriais.      
   11.8.  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).    
   11.9.  Eu sou a unica pessoa trabalhando na traduc,ao para este idioma,    
          como fac,o para enviar minha traduc,ao?                             
                                                                              
          ou                                                                  
                                                                              
          Somos uma equipe de traduc,ao e queremos enviar a documentac,ao que 
          nossos membros traduziram para nos.                                 
          Primeiro, verifique se sua traduc,ao esta organizada corretamente.  
          Isso significa que ele deve cair na arvore de documentac,ao         
          existente e ser compilada de maneira correta.                       
                                                                              
          Atualmente a documentac,ao do FreeBSD e armazenada em um diretorio  
          de nivel superior chamado head/. Os diretorios abaixo desse sao     
          nomeados de acordo com o codigo do idioma em que estao escritos,    
          conforme definido na ISO639 (/usr/share/misc/iso639 em uma versao   
          do FreeBSD mais recente que 20 de janeiro de 1999).                 
                                                                              
          Se o seu idioma puder ser codificado de maneiras diferentes (por    
          exemplo, Chines), deve haver diretorios abaixo desse, um para cada  
          formato de codificac,ao fornecido.                                  
                                                                              
          Finalmente, voce deve ter diretorios para cada documento.           
                                                                              
          Por exemplo, em uma hipotetica traduc,ao Sueca 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, no formato lang.encoding .   
          Repare nos dois Makefiles, que serao usados &#8203;&#8203;para      
          compilar a documentac,ao.                                           
                                                                              
          Usetar(1) e gzip(1) para compactar sua documentac,ao e envia-lo     
          para o projeto.                                                     
                                                                              
          % cd doc                                                            
          % tar cf swedish-docs.tar sv_SE.ISO8859-1                           
          % gzip -9 swedish-docs.tar                                          
                                                                              
          Coloque swedish-docs.tar.gz em algum lugar. Se voce nao tiver       
          acesso ao seu proprio espac,o web (talvez seu ISP nao disponibilize 
          um), envie um email para a Equipe de Engenharia da Documentac,ao    
          <doceng@FreeBSD.org> e combine o envio dos arquivos por email       
          conveniente quando for conveniente.                                 
                                                                              
          De qualquer maneira, voce deve usar o Bugzilla para enviar um       
          relatorio indicando que voce enviou a documentac,ao. Seria muito    
          util se voce conseguir outras pessoas para checar sua traduc,ao     
          primeiro, ja que e improvavel que a pessoa que ira fazer o commit   
          seja fluente no idioma.                                             
                                                                              
          Alguem (provavelmente o Gerente do Projeto de Documentac,ao,        
          atualmente Equipe de Engenharia de Documentac,ao                    
          <doceng@FreeBSD.org>) ira entao pegar sua traduc,ao e checar se ela 
          compila. Em particular, as seguintes coisas serao analisadas:       
                                                                              
           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, quem estiver validando a submissao ira    
          entrar em contato para que seja feito as correc,oes.                
                                                                              
          Se nao houver problemas, sua traduc,ao sera disponibilizada o mais  
          rapido possivel.                                                    
   11.10. Posso incluir um texto especifico do idioma ou do pais em minha     
          traduc,ao?                                                          
          Nos preferimos que voce nao fac,a isso.                             
                                                                              
          Por exemplo, suponha que voce esteja traduzindo o Handbook para o   
          Coreano e queira incluir uma sec,ao sobre varejistas na Coreia em   
          seu Handbook.                                                       
                                                                              
          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 tiver informac,oes especificas do pais, submeta-as como uma 
          alterac,ao do Handbook em Ingles (usando o Bugzilla) e em seguida,  
          traduza a alterac,ao de volta para o seu idioma no Handbook         
          traduzido.                                                          
                                                                              
          Obrigado.                                                           
   11.11. Como os caracteres especificos do idioma podem ser incluidos?       
          Caracteres nao-ASCII na documentac,ao devem ser incluidos usando    
          entidades SGML.                                                     
                                                                              
          Resumidamente, eles se parecem com um "e" comercial (&), o nome da  
          entidade e um ponto e virgula (;).                                  
                                                                              
          Os nomes das entidades sao definidos em ISO8879, que esta na arvore 
          de ports em 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 de instalar o port iso8879, os arquivos em                   
          /usr/local/share/xml/iso8879 conterao a lista completa.             
   11.12. 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 educada.       
   11.13. Preciso incluir informac,oes adicionais nas minhas traduc,oes?      
          Sim.                                                                
                                                                              
          O cabec,alho da versao em Ingles de cada documento sera algo        
          parecido com isto:                                                  
                                                                              
          <!--                                                                
               The FreeBSD Documentation Project                              
                                                                              
               $FreeBSD$                                                      
          -->                                                                 
                                                                              
          O forma exata pode mudar, mas sempre incluira uma linha $FreeBSD$ e 
          a frase The FreeBSD Documentation Project. Note que a parte do      
          $FreeBSD e expandida automaticamente pelo Subversion, portanto ela  
          deve estar vazia (apenas $FreeBSD$) para novos arquivos.            
                                                                              
          Seus documentos traduzidos devem incluir sua propria linha          
          $FreeBSD$, e 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 desse arquivo pode comec,ar com:        
                                                                              
          <!--                                                                
               The FreeBSD Spanish Documentation Project                      
                                                                              
               $FreeBSD$                                                      
               Original revision: r38674                                      
          -->                                                                 

                           Capitulo 12. Traduc,oes PO

   Indice

   12.1. Introduc,ao

   12.2. Quick Start

   12.3. Criando Novas Traduc,oes

   12.4. Traduzindo

   12.5. Dicas para Tradutores

   12.6. Compilando um Documento Traduzido

   12.7. Submetendo a Nova Traduc,ao

12.1. Introduc,ao

   O GNU gettext oferece aos tradutores uma maneira facil de criar e manter
   traduc,oes de documentos. Sequencias traduziveis sao extraidas do
   documento original em um arquivo PO (Portable Object). Versoes traduzidas
   das strings sao inseridas com um editor separado. As strings podem ser
   usadas diretamente ou incorporadas em uma versao traduzida completa do
   documento original.

12.2. Quick Start

   Supoe-se que o procedimento mostrado em Sec,ao 1.1, "Quick Start" ja tenha
   sido executado. A opc,ao TRANSLATOR e necessaria e ja esta ativada por
   padrao no port textproc/docproj.

   Este exemplo mostra a criac,ao de uma traduc,ao em Espanhol do pequeno
   artigo Leap Seconds.

   Procedimento 12.1. Instale um Editor PO
     * E necessario um editor PO para editar os arquivos de traduc,ao. Este
       exemplo utiliza o editors/poedit.

 # cd /usr/ports/editors/poedit
 # make install clean

   Procedimento 12.2. Configurac,ao Inicial

   Quando uma nova traduc,ao e criada pela primeira vez, a estrutura do
   diretorio e o Makefile devem ser criados ou copiados do original em
   Ingles:

    1. Crie um diretorio para a nova traduc,ao. O codigo fonte do artigo em
       Ingles esta em ~/doc/en_US.ISO8859-1/articles/leap-seconds/. A
       traduc,ao em Espanhol estara em
       ~/doc/es_ES.ISO8859-1/articles/leap-seconds/. O caminho e o mesmo,
       exceto pelo nome do diretorio de idiomas.

 % svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

    2. Copie o Makefile do documento original para o diretorio de traduc,ao:

 % svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
     ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

   Procedimento 12.3. Traduc,ao

   A traduc,ao de um documento consiste em duas etapas: extrair strings
   traduziveis do documento original e inserir as traduc,oes dessas strings.
   Essas etapas sao repetidas ate que o tradutor sinta que o documento foi
   traduzido o suficiente para produzir um documento traduzido que seja
   utilizavel.

    1. Extraia as strings traduziveis da versao original em Ingles para um
       arquivo PO:

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make po

    2. Use um editor PO para inserir as traduc,oes no arquivo PO. Existem
       varios editores diferentes disponiveis. O poedit do editors/poedit e
       mostrado aqui.

       O nome do arquivo PO e o codigo de idioma de dois caracteres seguido
       por um codigo de regiao de tambem dois caracteres, seprados por um
       underline. Para espanhol, o nome do arquivo e es_ES.po.

 % poedit es_ES.po

   Procedimento 12.4. Gerando um Documento Traduzido
    1. Gere o documento traduzido:

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make tran

       O nome do documento gerado corresponde ao nome do original em Ingles,
       geralmente article.xml para artigos ou book.xml para livros.

    2. Verifique o arquivo gerado renderizando-o para HTML e exibindo-o com
       um navegador web:

 % make FORMATS=html
 % firefox article.html

12.3. Criando Novas Traduc,oes

   O primeiro passo para criar um novo documento traduzido e localizar ou
   criar um diretorio para mante-lo. O FreeBSD coloca documentos traduzidos
   em um subdiretorio nomeado para seu idioma e regiao no formato lang_REGION
   . lang e um codigo minusculo de dois caracteres. Ele e seguido por um
   caractere underline, em seguida, pelo codigo de duas letras maiusculas
   REGION.

   Tabela 12.1. Nomes de Idioma

     Lingua        Regiao        Nome do Diretorio      Nome do   Conjunto de 
                                     Traduzido         Arquivo PO Caracteres  
   Ingles      Estados Unidos en_US.ISO8859-1          en_US.po   ISO 8859-1  
   Bengali     Bangladesh     bn_BD.UTF-8              bn_BD.po   UTF-8       
   Dinamarques Dinamarca      da_DK.ISO8859-1          da_DK.po   ISO 8859-1  
   Alemao      Alemanha       de_DE.ISO8859-1          de_DE.po   ISO 8859-1  
   Grego       Grecia         el_GR.ISO8859-7          el_GR.po   ISO 8859-7  
   Espanhol    Espanha        es_ES.ISO8859-1          es_ES.po   ISO 8859-1  
   Frances     Franc,a        fr_FR.ISO8859-1          fr_FR.po   ISO 8859-1  
   Hungaro     Hungria        hu_HU.ISO8859-2          hu_HU.po   ISO 8859-2  
   Italiano    Italia         it_IT.ISO8859-15         it_IT.po   ISO 8859-15 
   Japones     Japao          ja_JP.eucJP              ja_JP.po   EUC JP      
   Coreano     Coreia         ko_KR.UTF-8              ko_KR.po   UTF-8       
   Mongol      Mongolia       mn_MN.UTF-8              mn_MN.po   UTF-8       
   Holandes    Holanda        nl_NL.ISO8859-1          nl_NL.po   ISO 8859-1  
   Polones     Polonia        pl_PL.ISO8859-2          pl_PL.po   ISO 8859-2  
   Portugues   Brasil         pt_BR.ISO8859-1          pt_BR.po   ISO 8859-1  
   Russo       Russia         ru_RU.KOI8-R             ru_RU.po   KOI8-R      
   Turco       Turquia        tr_TR.ISO8859-9          tr_TR.po   ISO 8859-9  
   Chines      China          zh_CN.UTF-8              zh_CN.po   UTF-8       
   Chines      Taiwan         zh_TW.UTF-8              zh_TW.po   UTF-8       

   As traduc,oes estao em subdiretorios do diretorio principal da
   documentac,ao, aqui assumido como ~/doc/ como mostrado em Sec,ao 1.1,
   "Quick Start". Por exemplo, as traduc,oes em alemao estao localizadas em
   ~/doc/de_DE.ISO8859-1/ e as traduc,oes em frances estao em
   ~/doc/fr_FR.ISO8859-1/.

   Cada diretorio de idiomas contem subdiretorios separados para os tipos de
   documentos, geralmente articles/ e books/.

   A combinac,ao desses nomes de diretorios fornece o caminho completo para
   um artigo ou livro. Por exemplo, a traduc,ao Francesa do artigo NanoBSD
   esta em ~/doc/fr_FR.ISO8859-1/articles/nanobsd/, e a traduc,ao em Mongol
   do manual esta em ~/doc/mn_MN.UTF-8/books/handbook/.

   Um novo diretorio de idioma deve ser criado ao traduzir um documento para
   um novo idioma. Se o diretorio de idiomas ja existir, somente um
   subdiretorio no diretorio articles/ ou books/ sera necessario.

   As compilac,oes da documentac,ao do FreeBSD sao controladas por um
   Makefile no mesmo diretorio. Com artigos simples, o Makefile muitas vezes
   pode ser copiado literalmente do diretorio original em ingles. O processo
   de traduc,ao combina varios arquivos book.xml e chapter.xml de livros em
   um unico arquivo, portanto, o Makefile para as traduc,oes de livros deve
   ser copiado e modificado.

   Exemplo 12.1. Criando uma Traduc,ao em Espanhol do Porter's Handbook

   Crie uma nova traduc,ao em Espanhol do Porter's Handbook. O original e um
   livro em ~/doc/en_US.ISO8859-1/books/porters-handbook/.

    1. O diretorio de livros em Espanhol ~/doc/es_ES.ISO8859-1/books/ ja
       existe, portanto, apenas um novo subdiretorio para o Porter's Handbook
       e necessario:

 % cd ~/doc/es_ES.ISO8859-1/books/
 % svn mkdir porters-handbook
 A         porters-handbook

    2. Copie o Makefile do livro original:

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
 A         Makefile

       Modifique o conteudo do Makefile para esperar apenas um unico
       book.xml:

 #
 # $FreeBSD$
 #
 # Build the FreeBSD Porter's Handbook.
 #

 MAINTAINER=doc@FreeBSD.org

 DOC?= book

 FORMATS?= html-split

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # XML content
 SRCS=  book.xml

 # Images from the cross-document image library
 IMAGES_LIB+=    callouts/1.png
 IMAGES_LIB+=    callouts/2.png
 IMAGES_LIB+=    callouts/3.png
 IMAGES_LIB+=    callouts/4.png
 IMAGES_LIB+=    callouts/5.png
 IMAGES_LIB+=    callouts/6.png
 IMAGES_LIB+=    callouts/7.png
 IMAGES_LIB+=    callouts/8.png
 IMAGES_LIB+=    callouts/9.png
 IMAGES_LIB+=    callouts/10.png
 IMAGES_LIB+=    callouts/11.png
 IMAGES_LIB+=    callouts/12.png
 IMAGES_LIB+=    callouts/13.png
 IMAGES_LIB+=    callouts/14.png
 IMAGES_LIB+=    callouts/15.png
 IMAGES_LIB+=    callouts/16.png
 IMAGES_LIB+=    callouts/17.png
 IMAGES_LIB+=    callouts/18.png
 IMAGES_LIB+=    callouts/19.png
 IMAGES_LIB+=    callouts/20.png
 IMAGES_LIB+=    callouts/21.png

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

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

       Agora a estrutura do documento esta pronta para o tradutor comec,ar a
       traduc,ao com make po.

   Exemplo 12.2. Criando uma traduc,ao em Frances do Artigo Chaves Open PGP

   Crie uma nova traduc,ao em Frances do artigo Chaves Open PGP. O original e
   um artigo em ~/doc/en_US.ISO8859-1/articles/pgpkeys/.

    1. O diretorio de artigos em Frances ~/doc/fr_FR.ISO8859-1/articles/ ja
       existe, portanto, apenas um novo subdiretorio para o artigo Chaves
       Open PGP e necessario:

 % cd ~/doc/fr_FR.ISO8859-1/articles/
 % svn mkdir pgpkeys
 A         pgpkeys

    2. Copie o Makefile do artigo original:

 % cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
 % svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
 A         Makefile

       Verifique o conteudo do Makefile. Este e um artigo simples e neste
       caso, o Makefile pode ser usado sem altarac,ao. A string $FreeBSD...$
       na segunda linha sera substituida pelo sistema de controle de versao
       quando este arquivo sofrer um commit.

 #
 # $FreeBSD$
 #
 # Article: PGP Keys

 DOC?= article

 FORMATS?= html
 WITH_ARTICLE_TOC?= YES

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 SRCS=   article.xml

 # To build with just key fingerprints, set FINGERPRINTS_ONLY.

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

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

       Com a estrutura do documento completa, o arquivo PO pode ser criado
       com make po.

12.4. Traduzindo

   O sistema gettext reduz bastante o numero de itens que devem ser
   rastreados por um tradutor. As strings a serem traduzidas sao extraidas do
   documento original em um arquivo PO. Em seguida, um editor PO e usado para
   inserir as traduc,oes de cada string.

   O sistema de traduc,ao PO do FreeBSD nao sobrescreve os arquivos PO,
   portanto a etapa de extrac,ao pode ser executada a qualquer momento para
   atualizar o arquivo PO.

   Um editor PO e usado para editar o arquivo. editores/poedit e usado nestes
   exemplos porque e simples e tem requisitos minimos. Outros editores PO
   oferecem recursos para facilitar o trabalho de traduc,ao. A Colec,ao de
   Ports oferece varios desses editores, incluindo o devel/gtranslator.

   E importante preservar o arquivo PO. Ele contem todo o trabalho que os
   tradutores fizeram.

   Exemplo 12.3. Traduzindo o Porter's Handbook para o Espanhol

   Digite as traduc,oes para o Espanhol do conteudo do Porter's Handbook.

    1. Mude para o diretorio Espanhol do Porter's Handbook e atualize o
       arquivo PO. O arquivo PO gerado e chamado es_ES.po como mostrado em
       Tabela 12.1, "Nomes de Idioma".

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make po

    2. Realize as traduc,oes usando um editor de PO:

 % poedit es_ES.po

12.5. Dicas para Tradutores

  12.5.1. Preservando Tags XML

   Preserve as tags XML mostradas no original em Ingles.

   Exemplo 12.4. Preservando Tags XML

   Ingles original:

 If <acronym>NTP</acronym> is not being used

   Traduc,ao para o Espanhol:

 Si <acronym>NTP</acronym> no se utiliza

  12.5.2. Preservando Espac,os

   Preserve os espac,os existentes no inicio e no final das strings a serem
   traduzidas. A versao traduzida tambem deve ter esses espac,os.

  12.5.3. Tags

   O conteudo de algumas tags devem ser copiadas igualmente, sem realizar
   traduc,ao:

     * <citerefentry>

     * <command>

     * <filename>

     * <literal>

     * <manvolnum>

     * <orgname>

     * <package>

     * <programlisting>

     * <prompt>

     * <refentrytitle>

     * <screen>

     * <userinput>

     * <varname>

  12.5.4. Strings $FreeBSD$

   As strings da versao $FreeBSD$ usadas nos arquivos requerem tratamento
   especial. Nos exemplos como Exemplo 12.1, "Criando uma Traduc,ao em
   Espanhol do Porter's Handbook", essas strings nao devem ser expandidas. Os
   documentos em ingles usam entidades &dollar; para evitar a inclusao de
   sinais reais de dolar no arquivo:

 &dollar;FreeBSD&dollar;

   As entidades &dollar; nao sao vistas como cifroes pelo sistema de controle
   de versao e, portanto, a string nao e expandida em uma string de versao.

   Quando um arquivo PO e criado, as entidades &dollar; usadas nos exemplos
   sao substituidas por cifroes reais. A sequencia literal $FreeBSD$ sera
   expandida incorretamente pelo sistema de controle de versao quando o
   arquivo sofrer algum commit.

   A mesma tecnica usada nos documentos em Ingles pode ser usada na
   traduc,ao. O &dollar; e usado para substituir o sinal de dolar na
   traduc,ao inserida no editor PO:

 &dollar;FreeBSD&dollar;

12.6. Compilando um Documento Traduzido

   Uma versao traduzida do documento original pode ser criada a qualquer
   momento. Quaisquer porc,oes nao traduzidas do original serao incluidas em
   Ingles no documento resultante. A maioria dos editores PO tem um indicador
   que mostra quanto da traduc,ao foi realizada. Isso torna mais facil para o
   tradutor ver quantas strings foram traduzidas para tornar a compilac,ao do
   documento final utiilizavel.

   Exemplo 12.5. Construindo o Porter's Handbook Espanhol

   Compile e visualize a versao em Espanhol do Porter's Handbook criado em um
   exemplo anterior.

    1. Compile o documento traduzido. Como o original e um livro, o documento
       gerado e book.xml.

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make tran

    2. Renderize o book.xml traduzido para HTML e visualize-o com o Firefox.
       Este e o mesmo procedimento usado com a versao em Ingles dos
       documentos, e outros FORMATS podem ser usados &#8203;&#8203;aqui da
       mesma maneira. Veja Tabela 5.1, "Formatos de Saida Comuns".

 % make FORMATS=html
 % firefox book.html

12.7. Submetendo a Nova Traduc,ao

   Prepare os novos arquivos de traduc,ao para envio. Isso inclui adicionar
   os arquivos ao sistema de controle de versao, definir propriedades
   adicionais e criar um diff para a submissao.

   Os arquivos diff criados por esses exemplos podem ser anexados a um
   relatorio de bug de documentac,ao ou revisao de codigo.

   Exemplo 12.6. Traduc,ao Espanhola do Artigo NanoBSD
    1. Adicione a string FreeBSD na primeira linha do arquivo PO:

 #$FreeBSD$

    2. Adicione o Makefile, o arquivo PO e o arquivo traduzido XML que foi
       gerado para o controle de versao:

 % cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/
 % ls
 Makefile        article.xml     es_ES.po
 % svn add Makefile article.xml es_ES.po
 A         Makefile
 A         article.xml
 A         es_ES.po

    3. Configure as propriedades Subversion svn:keywords nesses arquivos para
       FreeBSD=%H para que as strings $FreeBSD$ sejam expandidas com o
       caminho, revisao, data e autor quando o arquivo sofrer o commit:

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'es_ES.po'

    4. Defina os tipos MIME dos arquivos. Estes sao text/xml para livros e
       artigos, e text/x-gettext-translation para o arquivo PO.

 % svn propset svn:mime-type text/x-gettext-translation es_ES.po
 property 'svn:mime-type' set on 'es_ES.po'
 % svn propset svn:mime-type text/xml article.xml
 property 'svn:mime-type' set on 'article.xml'

    5. Crie um diff dos novos arquivos a partir do diretorio base ~/doc/ para
       que o caminho completo seja mostrado com os nomes dos arquivos. Isso
       ajuda os committers a identificar o diretorio do idioma de destino.

 % cd ~/doc
 svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff

   Exemplo 12.7. Traduc,ao Coreana UTF-8 do Artigo Explicando o BSD
    1. Adicione a string FreeBSD na primeira linha do arquivo PO:

 #$FreeBSD$

    2. Adicione o Makefile, o arquivo PO e o arquivo traduzido XML que foi
       gerado para o controle de versao:

 % cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/
 % ls
 Makefile        article.xml     ko_KR.po
 % svn add Makefile article.xml ko_KR.po
 A         Makefile
 A         article.xml
 A         ko_KR.po

    3. Configure as propriedades Subversion svn:keywords nesses arquivos para
       FreeBSD=%H para que as strings $FreeBSD$ sejam expandidas com o
       caminho, revisao, data e autor quando o arquivo sofrer o commit:

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'ko_KR.po'

    4. Defina os tipos MIME dos arquivos. Como esses arquivos usam o conjunto
       de caracteres UTF-8, isso tambem e especificado. Para evitar que o
       sistema de controle de versao confunda esses arquivos com arquivos
       binarios, a propriedade fbsd:notbinary tambem e configurada:

 % svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po
 property 'svn:mime-type' set on 'ko_KR.po'
 % svn propset fbsd:notbinary yes ko_KR.po
 property 'fbsd:notbinary' set on 'ko_KR.po'
 % svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml
 property 'svn:mime-type' set on 'article.xml'
 % svn propset fbsd:notbinary yes article.xml
 property 'fbsd:notbinary' set on 'article.xml'

    5. Crie um diff desses novos arquivos no diretorio base ~/doc/:

 % cd ~/doc
 svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff

                         Capitulo 13. Paginas de Manual

   Indice

   13.1. Introduc,ao

   13.2. Sec,oes

   13.3. Marcac,ao

   13.4. Exemplo de Estruturas de Pagina de Manual

   13.5. Exemplos de paginas de manuais para usar como modelos

   13.6. Recursos

13.1. Introduc,ao

   Paginas de manual, geralmente abreviadas como man pages, foram concebidas
   como lembretes prontamente disponiveis para sintaxe de comandos, detalhes
   de drivers de dispositivos ou formatos de arquivos de configurac,ao. Elas
   se tornaram uma referencia rapida extremamente valiosa de linha de comando
   para usuarios, administradores de sistema e programadores.

   Embora tenham sido planejados como material de referencia em vez de
   tutoriais, as sec,oes EXEMPLOS das paginas de manual geralmente fornecem
   casos de uso detalhados.

   Paginas de manual sao geralmente mostradas interativamente pelo comando
   man(1). Quando o usuario digita man ls, uma pesquisa e executada para uma
   pagina de manual que corresponde a ls. O primeiro resultado correspondente
   e exibido.

13.2. Sec,oes

   As paginas de manual sao agrupadas em sec,oes. Cada sec,ao contem paginas
   de manual para uma categoria especifica de documentac,ao:

   +-----------------------------------------+
   | Numero da Sec,ao |      Categoria       |
   |------------------+----------------------|
   | 1                | Comandos Gerais      |
   |------------------+----------------------|
   | 2                | System Calls         |
   |------------------+----------------------|
   | 3                | Library Functions    |
   |------------------+----------------------|
   | 4                | Interfaces de Kernel |
   |------------------+----------------------|
   | 5                | Formatos de Arquivo  |
   |------------------+----------------------|
   | 6                | Jogos                |
   |------------------+----------------------|
   | 7                | Diversos             |
   |------------------+----------------------|
   | 8                | System Manager       |
   |------------------+----------------------|
   | 9                | Desenvolvedor Kernel |
   +-----------------------------------------+

13.3. Marcac,ao

   Varios formularios de marcac,ao e programas de renderizac,ao foram usados
   &#8203;&#8203;para paginas de manual. O FreeBSD usou groff(7) e o mais
   recente mandoc(1). A maioria das paginas de manual do FreeBSD, e todas as
   novas, usam o formulario mdoc(7) de marcac,ao. Esta e uma marcac,ao
   simples baseada em linhas que e razoavelmente expressiva. E principalmente
   semantico: partes do texto sao marcadas para o que sao, em vez de como
   devem aparecer quando renderizadas. Existe alguma marcac,ao baseada em
   aparencia que geralmente e melhor evitar.

   O codigo fonte de pagina de manual geralmente e interpretada e exibido na
   tela interativamente. Os arquivos fontes podem ser arquivos de texto
   comuns ou compactados com gzip(1) para economizar espac,o.

   As paginas de manual tambem podem ser renderizadas para outros formatos,
   incluindo PostScript para impressao ou gerac,ao de PDF. Veja man(1).

  Dica:

   O teste de uma nova pagina de manual pode ser um desafio quando o arquivo
   nao esta localizado no caminho de pesquisa normal da paginas de manual.
   man(1) tambem nao procura no diretorio atual. Se a nova pagina de manual
   estiver no diretorio atual, prefixe o nome do arquivo com um ./:

 % man ./mynewmanpage.8

   Um caminho absoluto tambem pode ser usado:

 % man /home/xsmith/mynewmanpage.8

  13.3.1. Sec,oes de Pagina de Manual

   Paginas de manual sao compostas por varias sec,oes padrao. Cada sec,ao tem
   um titulo em letras maiusculas e as sec,oes de um determinado tipo de
   pagina de manual aparecem em uma ordem especifica. Para uma pagina de
   manual do Comando Geral da categoria 1, as sec,oes sao:

   +------------------------------------------------------------------------+
   | Nome da Sec,ao |                      Descric,ao                       |
   |----------------+-------------------------------------------------------|
   | NAME           | Nome do Comando                                       |
   |----------------+-------------------------------------------------------|
   | SYNOPSIS       | Formato das opc,oes e argumentos                      |
   |----------------+-------------------------------------------------------|
   | DESCRIPTION    | Descric,ao da finalidade e uso                        |
   |----------------+-------------------------------------------------------|
   | ENVIRONMENT    | Configurac,oes de ambiente que afetam a operac,ao     |
   |----------------+-------------------------------------------------------|
   | EXIT STATUS    | Codigos de erro retornados na saida                   |
   |----------------+-------------------------------------------------------|
   | EXAMPLES       | Exemplos de uso                                       |
   |----------------+-------------------------------------------------------|
   | COMPATIBILITY  | Compatibilidade com outras implementac,oes            |
   |----------------+-------------------------------------------------------|
   | SEE ALSO       | Referencia cruzada para paginas de manual             |
   |                | relacionadas                                          |
   |----------------+-------------------------------------------------------|
   | STANDARDS      | Compatibilidade com padroes como o POSIX              |
   |----------------+-------------------------------------------------------|
   | HISTORY        | Historia de implementac,ao                            |
   |----------------+-------------------------------------------------------|
   | BUGS           | Bugs conhecidos                                       |
   |----------------+-------------------------------------------------------|
   | AUTHORS        | Pessoas que criaram o comando ou escreveram a pagina  |
   |                | de manual.                                            |
   +------------------------------------------------------------------------+

   Algumas sec,oes sao opcionais e a combinac,ao de sec,oes para um tipo
   especifico de pagina manual pode variar. Exemplos dos tipos mais comuns
   sao mostrados mais adiante neste capitulo.

  13.3.2. Macros

   A marcac,ao mdoc(7) e baseada em macros. As linhas que comec,am com um
   ponto contem comandos de macro, com duas ou tres letras. Por exemplo, veja
   esta parte da pagina de manual do ls(1):

 .Dd December 1, 2015  1
 .Dt LS 1
 .Sh NAME  2
 .Nm ls
 .Nd list directory contents
 .Sh SYNOPSIS  3
 .Nm  4
 .Op Fl -libxo  5
 .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,  6
 .Op Fl D Ar format  7
 .Op Ar  8
 .Sh DESCRIPTION  9
 For each operand that names a
 .Ar file
 of a type other than
 directory,
 .Nm
 displays its name as well as any requested,
 associated information.
 For each operand that names a
 .Ar file
 of type directory,
 .Nm
 displays the names of files contained
 within that directory, as well as any requested, associated
 information.

   1 O Document date e Document title sao definidos.                          
   2 O Cabec,alho da Sec,ao para a sec,ao NAME e definido. Em seguida, sao    
     definidos o Nome do comando e uma Descric,ao do Nome de uma linha.       
   3 A sec,ao SYNOPSIS comec,a. Esta sec,ao descreve as opc,oes e argumentos  
     de linha de comando que sao aceitos.                                     
   4 Nome (.Nm) ja foi definido, e repeti-lo aqui apenas exibe o valor        
     definido no texto.                                                       
   5 Uma Optional Flag chamada -libxo e mostrada. A macro Fl adiciona um      
     trac,o ao inicio das flags, portanto, isso aparece na pagina de manual   
     como --libxo.                                                            
   6 Uma longa lista de sinalizadores opcionais de caracteres unicos e        
     apresentada.                                                             
   7 Uma flag opcional -D e definida. Se a flag -D for informada, ela deve    
     ser seguida por um Argumento. O argumento e um format, uma string que    
     diz ls(1) o que exibir e como exibi-lo. Detalhes sobre a string de       
     formato sao fornecidos posteriormente na pagina de manual.               
   8 Um argumento opcional final e definido. Como nenhum nome e especificado  
     para o argumento, o padrao file ... e usado.                             
   9 O Cabec,alho da Sec,ao para a sec,ao DESCRIPTION e definido.             

   Quando renderizado com o comando man ls, o resultado exibido na tela e
   semelhante ao seguinte:

 LS(1)                   FreeBSD General Commands Manual                  LS(1)

 NAME
      ls - list directory contents

 SYNOPSIS
      ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
         [file ...]

 DESCRIPTION
      For each operand that names a file of a type other than directory, ls
      displays its name as well as any requested, associated information.  For
      each operand that names a file of type directory, ls displays the names
      of files contained within that directory, as well as any requested,
      associated information.

   Valores opcionais sao mostrados entre colchetes.

  13.3.3. Diretrizes de Marcac,ao

   A linguagem de marcac,ao mdoc(7) nao e muito rigorosa. Para maior clareza
   e consistencia, o projeto Documentac,ao do FreeBSD adiciona algumas
   diretrizes de estilo adicionais:

   Apenas a primeira letra das macros e maiuscula

           Sempre use maiusculas para a primeira letra de uma macro e
           minuscula para as letras restantes.

   Comece novas frases em novas linhas

           Inicie uma nova frase em uma nova linha, nao a inicie na mesma
           linha de uma frase existente.

   Atualizar .Dd ao fazer alterac,oes nao triviais em uma pagina de manual

           A Data do documento informa o leitor sobre a ultima vez que a
           pagina de manual foi atualizada. E importante atualizar sempre que
           alterac,oes nao triviais forem feitas nas paginas de manual.
           Alterac,oes triviais, como correc,oes ortograficas ou de
           pontuac,ao que nao afetam o uso, podem ser feitas sem atualizar
           .Dd.

   Apresentando exemplos

           Apresente exemplos ao leitor sempre que possivel. Mesmo exemplos
           triviais sao valiosos, porque o que e trivial para o escritor nao
           e necessariamente trivial para o leitor. Tres exemplos sao um bom
           objetivo. Um exemplo trivial mostra os requisitos minimos, um
           exemplo afundo mostra o uso real e um exemplo detalhado demonstra
           uma funcionalidade incomum ou nao obvia.

   Inclua a licenc,a BSD

           Inclua a licenc,a BSD em novas paginas de manual. A licenc,a
           preferencial esta disponivel no Guia dos Committer's.

  13.3.4. Truques de Marcac,ao

   Adicione um espac,o antes da pontuac,ao em uma linha com macros. Exemplo:

 .Sh SEE ALSO
 .Xr geom 4 ,
 .Xr boot0cfg 8 ,
 .Xr geom 8 ,
 .Xr gptboot 8

   Observe como as virgulas no final das linhas .Xr foram colocadas apos um
   espac,o. A macro .Xr espera dois parametros, o nome de uma pagina de
   manual externa e um numero de sec,ao. O espac,o separa a pontuac,ao do
   numero da sec,ao. Sem o espac,o, os links externos apontariam
   incorretamente para a sec,ao 4, ou 8,.

  13.3.5. Macros Importantes

   Algumas macros muito comuns serao mostradas aqui. Para obter mais exemplos
   de uso, consulte mdoc(7), groff_mdoc(7), ou procure por uso real no
   diretorio /usr/share/man/man*. Por exemplo, para procurar exemplos da
   macro .Bd Begin display:

 % find /usr/share/man/man* | xargs zgrep '.Bd'

    13.3.5.1. Macros Organizacionais

   Algumas macros sao usadas para definir blocos logicos de uma pagina de
   manual.

   +------------------------------------------------------------------------+
   | Macro Organizacional |                       Uso                       |
   |----------------------+-------------------------------------------------|
   |                      | Section header (Cabec,alho da sec,ao). Seguido  |
   | .Sh                  | pelo nome da sec,ao, tradicionalmente com os    |
   |                      | caracteres todos em maiusculas. Pense neles     |
   |                      | como titulos de capitulos.                      |
   |----------------------+-------------------------------------------------|
   |                      | Subsection header (Cabec,alho da subsec,ao).    |
   | .Ss                  | Seguido pelo nome da subsec,ao. Usado para      |
   |                      | dividir uma sec,ao .Sh em subsec,oes.           |
   |----------------------+-------------------------------------------------|
   | .Bl                  | Begin list. Comece uma lista de itens.          |
   |----------------------+-------------------------------------------------|
   | .El                  | End a list (Finalize uma lista).                |
   |----------------------+-------------------------------------------------|
   |                      | Begin display (Comece a exibic,ao). Comece em   |
   | .Bd                  | uma area especial de texto, como uma area       |
   |                      | recuada.                                        |
   |----------------------+-------------------------------------------------|
   | .Ed                  | End display (Termine a exibic,ao).              |
   +------------------------------------------------------------------------+

    13.3.5.2. Macros Inline

   Muitas macros sao usadas para marcar texto embutido.

   +------------------------------------------------------------------------+
   | Macro Inline |                           Uso                           |
   |--------------+---------------------------------------------------------|
   |              | Name. Chamado com um nome como parametro no primeiro    |
   | .Nm          | uso, usado depois sem o parametro para exibir o nome    |
   |              | que ja foi definido.                                    |
   |--------------+---------------------------------------------------------|
   | .Pa          | Path to a file (Caminho para um arquivo). Usado para    |
   |              | marcar nomes de arquivos e caminhos de diretorio.       |
   +------------------------------------------------------------------------+

13.4. Exemplo de Estruturas de Pagina de Manual

   Esta sec,ao mostra o conteudo minimo desejavel para um pagina de manual
   para varias categorias comuns de paginas de manual.

  13.4.1. Sec,ao 1 ou 8 sobre um comando

   A estrutura basica preferida para uma sec,ao 1 ou 8 sobre um comando:

 .Dd August 25, 2017
 .Dt EXAMPLECMD 8
 .Os
 .Sh NAME
 .Nm examplecmd
 .Nd "command to demonstrate section 1 and 8 man pages"
 .Sh SYNOPSIS
 .Nm
 .Op Fl v
 .Sh DESCRIPTION
 The
 .Nm
 utility does nothing except demonstrate a trivial but complete
 manual page for a section 1 or 8 command.
 .Sh SEE ALSO
 .Xr exampleconf 5
 .Sh AUTHORS
 .An Firstname Lastname Aq Mt flastname@example.com

  13.4.2. Sec,ao 4 sobre um Driver de Dispositivo

   A estrutura basica preferida para a sec,ao 4 sobre um driver de
   dispositivo:

 .Dd August 25, 2017
 .Dt EXAMPLEDRIVER 4
 .Os
 .Sh NAME
 .Nm exampledriver
 .Nd "driver to demonstrate section 4 man pages"
 .Sh SYNOPSIS
 To compile this driver into the kernel, add this line to the
 kernel configuration file:
 .Bd -ragged -offset indent
 .Cd "device exampledriver"
 .Ed
 .Pp
 To load the driver as a module at boot, add this line to
 .Xr loader.conf 5 :
 .Bd -literal -offset indent
 exampledriver_load="YES"
 .Ed
 .Sh DESCRIPTION
 The
 .Nm
 driver provides an opportunity to show a skeleton or template
 file for section 4 manual pages.
 .Sh HARDWARE
 The
 .Nm
 driver supports these cards from the aptly-named Nonexistent
 Technologies:
 .Pp
 .Bl -bullet -compact
 .It
 NT X149.2 (single and dual port)
 .It
 NT X149.8 (single port)
 .El
 .Sh DIAGNOSTICS
 .Bl -diag
 .It "flashing green light"
 Something bad happened.
 .It "flashing red light"
 Something really bad happened.
 .It "solid black light"
 Power cord is unplugged.
 .El
 .Sh SEE ALSO
 .Xr example 8
 .Sh HISTORY
 The
 .Nm
 device driver first appeared in
 .Fx 49.2 .
 .Sh AUTHORS
 .An Firstname Lastname Aq Mt flastname@example.com

  13.4.3. Sec,ao 5 sobre um Arquivo de Configurac,ao

   A estrutura basica preferida para a sec,ao 5 sobre um arquivo de
   configurac,ao:

 .Dd August 25, 2017
 .Dt EXAMPLECONF 5
 .Os
 .Sh NAME
 .Nm example.conf
 .Nd "config file to demonstrate section 5 man pages"
 .Sh DESCRIPTION
 .Nm
 is an example configuration file.
 .Sh SEE ALSO
 .Xr example 8
 .Sh AUTHORS
 .An Firstname Lastname Aq Mt flastname@example.com

13.5. Exemplos de paginas de manuais para usar como modelos

   Algumas destas paginas de manual sao adequadas para serem usadas como
   exemplos detalhados.

   +----------------------------------------------------------+
   | Pagina Manual |      Caminho para o local de origem      |
   |---------------+------------------------------------------|
   | cp(1)         | /usr/src/bin/cp/cp.1                     |
   |---------------+------------------------------------------|
   | vt(4)         | /usr/src/share/man/man4/vt.4             |
   |---------------+------------------------------------------|
   | crontab(5)    | /usr/src/usr.sbin/cron/crontab/crontab.5 |
   |---------------+------------------------------------------|
   | gpart(8)      | /usr/src/sbin/geom/class/part/gpart.8    |
   +----------------------------------------------------------+

13.6. Recursos

   Recursos para escritores de paginas manuais:

     * man(1)

     * mandoc(1)

     * groff_mdoc(7)

     * Manuais Praticos do UNIX: mdoc

     * Historia das Man pages do UNIX

                         Capitulo 14. Estilo de escrita

   Indice

   14.1. Dicas

   14.2. Diretrizes

   14.3. Guia de estilo

   14.4. Lista de palavras

14.1. Dicas

   A documentac,ao tecnica pode ser melhorada pelo uso consistente de varios
   principios. A maioria destes pode ser classificada em tres objetivos: ser
   claro, ser completo e ser conciso. Essas metas podem entrar em conflito
   umas com as outras. Uma boa escrita consiste em um equilibrio entre eles.

  14.1.1. Seja claro

   A clareza e extremamente importante. O leitor pode ser um novato ou ler o
   documento em um segundo idioma. Esforce-se por um texto simples e
   descomplicado que explique claramente os conceitos.

   Evite discurso florido ou embelezado, piadas ou expressoes coloquiais.
   Escreva da maneira mais simples e clara possivel. Um texto simples e mais
   facil de se entender e de se traduzir.

   Mantenha as explicac,oes o mais curtas, simples e claras possivel. Evite
   frases vazias como "a fim de" as quais normalmente significam apenas um
   "para". Evite palavras potencialmente paternalistas tais como
   "basicamente". Evite termos latinos como "i.e." ou "cf.", os quais podem
   ser desconhecidos fora de grupos academicos ou cientificos.

   Escreva em um estilo formal. Evite dirigir-se ao leitor como "voce". Por
   exemplo, digamos "copie o arquivo para /tmp" em vez de "voce pode copiar o
   arquivo para /tmp".

   De exemplos claros, corretos, e testados. Um exemplo trivial e melhor do
   que nenhum exemplo. Um bom exemplo e ainda melhor. Nao de exemplos ruins,
   identificaveis &#8203;&#8203;por desculpas ou frases como "mas realmente
   isso nunca deve ser feito dessa forma". Exemplos ruins sao piores que
   nenhum exemplo. De bons exemplos, porque mesmo quando avisado para nao
   usar o exemplo como mostrado , o leitor normalmente so usa o exemplo como
   mostrado.

   Evite palavras vazias como "deveria", "poderia", "tentaria", ou "podia".
   Estas palavras implicam que o autor nao tem certeza dos fatos e cria
   duvidas no leitor.

   Da mesma forma, de instruc,oes como comandos imperativos: nao utilize
   "voce deve fazer isso", mas apenas "fac,a isso".

  14.1.2. Seja completo

   Nao fac,a suposic,oes sobre as habilidades do leitor. Diga-lhes o que
   precisam saber. De links para outros documentos para fornecer informac,oes
   basicas sem precisar recria-las. Coloque-se no lugar do leitor, antecipe
   as perguntas que eles farao e responda-os.

  14.1.3. Seja conciso

   Embora as funcionalidades devam ser documentadas completamente, `as vezes
   existe tanta informac,ao que o leitor nao consegue encontrar facilmente os
   detalhes especificos de que necessita. O equilibrio entre ser completo e
   ser conciso e um desafio. Uma abordagem e ter uma introduc,ao e, em
   seguida, uma sec,ao de "inicio rapido" que descreve a situac,ao mais
   comum, seguida por uma sec,ao de referencia aprofundada.

14.2. Diretrizes

   Para promover a consistencia entre os inumeros autores da documentac,ao do
   FreeBSD, algumas diretrizes foram elaboradas para os autores seguirem.

   Use a Ortografia do Ingles Americano

           Existem varias variantes do ingles, com grafias diferentes para a
           mesma palavra. Onde as grafias diferem, use a variante do ingles
           americano. "color", nao "colour", "rationalize", nao
           "rationalise", e assim por diante.

  Nota:

           O uso do ingles britanico pode ser aceito no caso de um artigo
           contribuido, no entanto, a ortografia deve ser consistente em todo
           o documento. Os outros documentos, como livros, site, paginas de
           manual, etc., terao que usar o ingles americano.

   Nao use contrac,oes

           Nao use contrac,oes. Sempre soletre a frase na integra. "Do not" e
           a forma correta, "Don't" e a errada.

           Evitar contrac,oes contribui para um tom mais formal, e mais
           preciso e e um pouco mais facil para os tradutores.

   Use a virgula serial

           Em uma lista de itens dentro de um paragrafo, separe cada item dos
           outros com uma virgula. Separe o ultimo item dos outros com uma
           virgula e a letra "e".

           Por exemplo:

             Esta e uma lista de um, dois e tres itens.

           E uma lista de tres itens, "um", "dois" e "tres", ou uma lista de
           dois itens, "um" e "dois e tres"?

           E melhor ser explicito e incluir uma virgula serial:

             Esta e uma lista de um, dois, e tres itens.

   Evite frases redundantes

           Nao use frases redundantes. Em particular, "o comando", "o
           arquivo" e o "comando man" sao frequentemente redundantes.

           Por exemplo, comandos:

           Errado: Use o comando svn para atualizar o codigo fonte.

           Correto: Use o svn para atualizar o codigo fonte.

           Nomes de arquivo:

           Errado:... no nome do arquivo /etc/rc.local...

           Correto:... no /etc/rc.local...

           Referencias de paginas de manual (o segundo exemplo usa
           citerefentry com a entidade &man.csh.1;):.

           Errado: Veja man csh para mais informac,oes.

           Correto: Veja csh(1).

   Dois espac,os entre frases

           Sempre use dois espac,os entre as sentenc,as, pois isso melhora a
           legibilidade e facilita o uso de ferramentas como o Emacs.

           Um periodo e espac,os seguidos por uma letra maiuscula nem sempre
           marcam uma nova sentenc,a, especialmente em nomes. "Jordan K.
           Hubbard" e um bom exemplo. Ele tem um capital H apos um periodo e
           um espac,o, e certamente nao e uma nova sentenc,a.

   Para mais informac,oes sobre o estilo de escrita, consulte Elementos de
   Estilo, de William Strunk.

14.3. Guia de estilo

   Para manter o codigo fonte da documentac,ao consistente quando muitas
   pessoas diferentes a estiverem editando, siga estas convenc,oes de estilo.

  14.3.1. Letter Case

   As tags sao digitadas em minusculas, para, nao PARA.

   O texto que aparece em contextos SGML e geralmente escrito em letras
   maiusculas, <! ENTITY ... >, e <! DOCTYPE... >, nao <! entity... > e <!
   doctype... >.

  14.3.2. Siglas

   Os acronimos devem ser definidos na primeira vez que aparecerem em um
   documento, como em: "Network Time Protocol (NTP)". Depois que o acronimo
   tiver sido definido, use apenas o acronimo, a menos que fac,a mais sentido
   contextualmente usar todo o termo. Acronimos geralmente sao definidos
   apenas uma vez por capitulo ou por documento.

   Todos os acronimos devem ser colocados em tags acronym.

  14.3.3. Indentac,ao

   A primeira linha em cada arquivo comec,a sem recuo, independentemente do
   nivel de recuo do arquivo que pode conter o arquivo atual.

   Tags de abertura aumentam o nivel de recuo por dois espac,os. Tags de
   fechamento diminuem o nivel de recuo por dois espac,os. Blocos de oito
   espac,os no inicio de uma linha devem ser substituidos por um tab. Nao use
   espac,os na frente das tabs e nao adicione espac,o em branco extra no
   final de uma linha. O conteudo nos elementos deve ser indentado por dois
   espac,os se o conteudo for executado em mais de uma linha.

   Por exemplo, a fonte desta sec,ao e assim:

 <chapter>
   <title>...</title>

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

     <sect2>
       <title>Indentation</title>

       <para>The first line in each file starts with no indentation,
         <emphasis>regardless</emphasis> of the indentation level of
         the file which might contain the current file.</para>

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

   Tags contendo atributos longos seguem as mesmas regras. Seguir as regras
   de recuo neste caso ajuda editores e escritores a ver qual conteudo esta
   dentro das tags:

 <para>See the <link
     linkend="gmirror-troubleshooting">Troubleshooting</link>
   section if there are problems booting.  Powering down and
   disconnecting the original <filename>ada0</filename> disk
   will allow it to be kept as an offline backup.</para>

 <para>It is also possible to journal the boot disk of a &os;
   system.  Refer to the article <link
     xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
     Journaling on a Desktop PC</link> for detailed
   instructions.</para>

   Quando um elemento e muito longo para caber no restante de uma linha sem
   quebra-la, mover a tag inicial para a proxima linha pode facilitar a
   leitura do codigo. Neste exemplo, o elemento systemitem foi movido para a
   proxima linha para evitar a quebra e o recuo:

 <para>With file flags, even
   <systemitem class="username">root</systemitem> can be
   prevented from removing or altering files.</para>

   Configurac,oes para ajudar varios editores de texto a operar em
   conformidade com estas diretrizes podem ser encontradas em Capitulo 15,
   Configurac,ao do Editor.

  14.3.4. Estilo de Tag

    14.3.4.1. Espac,amento de tag

   Tags que comec,am no mesmo recuo como uma tag anterior devem ser separadas
   por uma linha em branco, e aquelas que nao estao no mesmo recuo como uma
   tag anterior nao devem:

 <article lang='en'>
   <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>

    14.3.4.2. Separando Tags

   Tags como itemizedlist, que sempre terao outras tags dentro delas, e de
   fato nao pegam dados de caractere, estao sempre sozinhas em uma linha.

   Tags como para e term nao precisam de outras tags para conter dados de
   caracteres normais, e seus conteudos comec,am imediatamente apos a tag, na
   mesma linha .

   O mesmo se aplica quando esses dois tipos de tags fecham.

   Isso leva a um problema obvio ao misturar essas tags.

   Quando uma tag inicial que nao pode conter dados de caractere segue
   diretamente uma tag do tipo que requer outras tags dentro dela para usar
   dados de caractere, elas estao em linhas separadas. A segunda tag deve
   estar corretamente recuada.

   Quando uma tag que pode conter dados de caractere e fechada diretamente
   apos uma tag que nao pode conter dados de caractere fechados, eles
   coexistem na mesma linha.

  14.3.5. Mudanc,as no espac,o em branco

   Nao fac,a commit de mudanc,as no conteudo ao mesmo tempo em que faz
   mudanc,as na formatac,ao.

   Quando as alterac,oes de conteudo e espac,o em branco sao mantidas
   separadas, as equipes de traduc,ao podem ver facilmente se uma alterac,ao
   foi de um conteudo que deve ser traduzido ou apenas espac,o em branco.

   Por exemplo, se duas sentenc,as foram adicionadas a um paragrafo para que
   os comprimentos de linha passem de 80 colunas, primeiro fac,a commit da
   alterac,ao com as linhas longas demais. Em seguida, corrija a quebra de
   linha e confirme essa segunda alterac,ao. Na mensagem de confirmac,ao da
   segunda alterac,ao, indique que esta e uma alterac,ao somente de espac,o
   em branco a qual pode ser ignorada pelos tradutores.

  14.3.6. Espac,os Nao Separaveis (Non-Breaking Space)

   Evite quebras de linha em locais onde elas parec,am feias ou dificultem o
   entendimento de uma frase. Quebras de linha dependem da largura do meio de
   saida escolhido. Em particular, a visualizac,ao da documentac,ao em HTML
   com um navegador de texto pode levar a paragrafos mal formatados como o
   seguinte:

 A capacidade de dados varia de 40 MB a 15
 GB Compressao de hardware...

   A entidade geral &nbsp; proibe as quebras de linha entre as partes que
   estao juntas. Use espac,os nao separaveis &#8203;&#8203;nos seguintes
   locais:

     * entre numeros e unidades:

 57600&nbsp;bps

     * entre nomes de programas e numeros de versao:

 &os;&nbsp;9.2

     * entre nomes com varias palavras (use com cautela ao aplicar isso em
       nomes de mais de 3-4 palavras como "The FreeBSD Portuguese Portuguese
       Documentation Project"):

 Sun &Microsystems

14.4. Lista de palavras

   Esta lista de palavras mostra a ortografia e letras maiusculas corretas
   quando usadas na documentac,ao do FreeBSD. Se uma palavra nao estiver
   nesta lista, pergunte sobre isso na lista de discussao do projeto de
   documentac,ao do FreeBSD.

     Palavra                Codigo XML                        Notas           
   CD-ROM      <acronym>CD-ROM</acronym>                                      
   DoS                                                                        
   (negac,ao   <acronym>DoS</acronym>                 
   de          
   servic,o)   
   email                                                                      
   sistema de                                                                 
   arquivo     
   IPsec                                                                      
   Internet                                                                   
   pagina de                                                                  
   manual      
   servidor de                                                                
   email       
   nome do                                                                    
   servidor    
   Colec,ao de                                                                
   Ports       
   somente                                                                    
   leitura     
   Soft                                                                       
   Updates     
   stdin       <varname>stdin</varname>                                       
   stdout      <varname>stdout</varname>                                      
   stderr      <varname>stderr</varname>                                      
                                                     Nao se refira ao         
                                                     aplicativo Subversion    
   Subversion  <application>Subversion</application> como SVN em letras       
                                                     maiusculas. Para se      
                                                     referir ao comando, use  
                                                     <command>svn</command>.  
   UNIX(R)     &unix;                                                         
                                                     coisas que se aplicam ao 
   userland                                          espac,o do usuario, nao  
                                                     ao kernel                
   servidor                                                                   
   web         

                      Capitulo 15. Configurac,ao do Editor

   Indice

   15.1. Vim

   15.2. Emacs

   15.3. nano

   Ajustar a configurac,ao do editor de texto pode tornar o trabalho nos
   arquivos da documentac,ao mais rapido e facil, alem de ajudar os
   documentos a ficarem em conformidade com as diretrizes do FDP.

15.1. Vim

   Instale-o a partir de editors/vim, editors/vim-console, ou
   editors/vim-tiny e siga as instruc,oes de configurac,ao em Sec,ao 15.1.2,
   "Configurac,ao".

  15.1.1. Uso

   Pressione P para reformatar paragrafos ou texto selecionado no modo
   Visual. Pressione T para substituir grupos de oito espac,os por um tab.

  15.1.2. Configurac,ao

   Edite o ~/.vimrc, adicionando estas linhas ao final do arquivo:

 if has("autocmd")
     au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
     au BufNewFile,BufRead *.[1-9] call ShowSpecial()
 endif " has(autocmd)

 function Set_Highlights()
     "match ExtraWhitespace /^\s* \s*\|\s\+$/
     highlight default link OverLength ErrorMsg
     match OverLength /\%71v.\+/
     return 0
 endfunction " Set_Highlights()

 function ShowSpecial()
     setlocal list listchars=tab:>>,trail:*,eol:$
     hi def link nontext ErrorMsg
     return 0
 endfunction " ShowSpecial()

 function Set_SGML()
     setlocal number
     syn match sgmlSpecial "&[^;]*;"
     setlocal syntax=sgml
     setlocal filetype=xml
     setlocal shiftwidth=2
     setlocal textwidth=70
     setlocal tabstop=8
     setlocal softtabstop=2
     setlocal formatprg="fmt -p"
     setlocal autoindent
     setlocal smartindent
     " Rewrap paragraphs
     noremap P gqj
     " Replace spaces with tabs
     noremap T :s/        /\t/<CR>
     call ShowSpecial()
     call Set_Highlights()
     return 0
 endfunction " Set_SGML()

15.2. Emacs

   Instale-o a partir de editors/emacs ou editors/emacs-devel.

  15.2.1. Validac,ao

   O modo nxml do Emacs usa esquemas NG relax compacto para validar o XML. Um
   esquema NG relax compacto para a extensao do FreeBSD para DocBook 5.0 esta
   incluido no repositorio de documentac,ao. Para configurar o modo nxml para
   validar usando este esquema, crie ~/.emacs.d/schema/schemas.xml e adicione
   estas linhas ao arquivo:

 <locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
   <documentElement localName="section" typeId="DocBook">
   <documentElement localName="chapter" typeId="DocBook">
   <documentElement localName="article" typeId="DocBook">
   <documentElement localName="book" typeId="DocBook">
   <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc">
 </locatingRules>

  15.2.2. Revisao Automatizada com Flycheck e Igor

   O pacote Flycheck esta disponivel no Emacs Lisp Package Archive da
   Milkypostman (MELPA). Se a MELPA ainda nao estiver nos repositorios de
   pacotes do Emacs, ele pode ser adicionado executando

 (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)

   Adicione a linha ao arquivo de inicializac,ao do Emacs (qualquer um deles,
   ~/.emacs, ~/.emacs.el, ou ~.emacs.d/init.el) para tornar esta alterac,ao
   permanente.

   Para instalar o Flycheck, execute

 (package-install 'flycheck)

   Crie um verificador Flycheck para textproc/igor executando

 (flycheck-define-checker igor
   "FreeBSD Documentation Project sanity checker.

 See URLs https://www.freebsd.org/docproj/ and
 http://www.freshports.org/textproc/igor/."
   :command ("igor" "-X" source-inplace)
   :error-parser flycheck-parse-checkstyle
   :modes (nxml-mode)
   :standard-input t)

   (add-to-list 'flycheck-checkers 'igor 'append)

   Novamente, adicione essas linhas ao arquivo de inicializac,ao do Emacs
   para tornar as mudanc,as permanentes.

  15.2.3. Configurac,oes Especificas da Documentac,ao do FreeBSD

   Para aplicar configurac,oes especificas para o projeto de documentac,ao do
   FreeBSD, crie o arquivo .dir-locals.el no diretorio raiz do repositorio de
   documentac,ao e adicione estas linhas ao arquivo:

 ;;; Directory Local Variables
 ;;; For more information see (info "(emacs) Directory Variables")

 ((nxml-mode
   (eval . (turn-on-auto-fill))
   (fill-column . 70)
   (eval . (require 'flycheck))
   (eval . (flycheck-mode 1))
   (flycheck-checker . igor)
   (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))

15.3. nano

   Instale o aplicativo partir de editors/nano ou editors/nano-devel.

  15.3.1. Configurac,ao

   Copie o arquivo com a amostra da regra para realce da sintaxe XML para o
   diretorio inicial do usuario:

 % cp /usr/local/share/nano/xml.nanorc ~/.nanorc

   Use um editor para substituir as linhas do ~/.nanorc referentes ao bloco
   syntax "xml" por estas regras:

 syntax "xml" "\.([jrs]html?|xml|xslt?)$"
 # trailing whitespace
 color ,blue "[[:space:]]+$"
 # multiples of eight spaces at the start a line
 # (after zero or more tabs) should be a tab
 color ,blue "^([TAB]*[ ]{8})+"
 # tabs after spaces
 color ,yellow "( )+TAB"
 # highlight indents that have an odd number of spaces
 color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
 # lines longer than 70 characters
 color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"

   Processe o arquivo para criar guias incorporadas:

 % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

  15.3.2. Uso

   Especifique opc,oes uteis adicionais ao executar o editor:

 % nano -AKipwz -r 70 -T8 chapter.xml

   Usuarios do csh(1) podem definir um alias em ~/.cshrc para automatizar
   estas opc,oes:

 alias nano "nano -AKipwz -r 70 -T8"

   Depois que o alias e definido, as opc,oes serao adicionadas
   automaticamente:

 % nano chapter.xml

                            Capitulo 16. Veja tambem

   Indice

   16.1. O projeto de documentac,ao do FreeBSD

   16.2. XML

   16.3. HTML

   16.4. DocBook

   Este documento nao e deliberadamente uma discussao exaustiva de XML, das
   DTDs listadas e o Projeto de Documentac,ao do FreeBSD. Para mais
   informac,oes sobre estes, voce e encorajado a consultar os seguintes
   sites.

16.1. O projeto de documentac,ao do FreeBSD

     * As Paginas Web do Projeto de Documentac,ao do FreeBSD

     * O Handbook do FreeBSD

16.2. XML

     * Pagina W3C's XML Pagina Web SGML/XML

16.3. HTML

     * O Consorcio World Wide Web

     * A especificac,ao HTML 4.0

16.4. DocBook

     * O Comite Tecnico do DocBook , mantenedores do DocBook DTD

     * DocBook: O Guia Definitivo , a documentac,ao online do DocBook DTD

     * O DocBook Open Repository contem folhas de estilo DSSSL e outros
       recursos para pessoas que usam DocBook

                              Apendice A. Exemplos

   Indice

   A.1. Livro DocBook

   A.2. Artigo DocBook

   Estes exemplos nao sao exaustivos - eles nao contem todos os elementos que
   podem ser desejaveis &#8203;&#8203;de usar, particularmente em relac,ao ao
   inicio dos documentos (Front Matter). Para mais exemplos de marcac,ao
   DocBook, examine o codigo XML para este e outros documentos disponiveis no
   repositorio Subversion doc ou disponivel on-line a partir de
   http://svnweb.FreeBSD.org/doc/.

A.1. Livro DocBook

   Exemplo A.1. Livro DocBook

 <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
         "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

 <book xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:lang="en">

   <info>
     <title>An Example Book</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>foo@example.com</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>

     <abstract>
       <para>If your book has an abstract then it should go here.</para>
     </abstract>
   </info>

   <preface>
     <title>Preface</title>

     <para>Your book may have a preface, in which case it should be placed
       here.</para>
   </preface>

   <chapter>
     <title>My First Chapter</title>

     <para>This is the first chapter in my book.</para>

     <sect1>
       <title>My First Section</title>

       <para>This is the first section in my book.</para>
     </sect1>
   </chapter>
 </book>

A.2. Artigo DocBook

   Exemplo A.2. Artigo DocBook

 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
         "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

 <article xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:lang="en">

   <info>
     <title>An Example Article</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>foo@example.com</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>

     <abstract>
       <para>If your article has an abstract then it should go here.</para>
     </abstract>
   </info>

   <sect1>
     <title>My First Section</title>

     <para>This is the first section in my article.</para>

     <sect2>
       <title>My First Sub-Section</title>

       <para>This is the first sub-section in my article.</para>
     </sect2>
   </sect1>
 </article>

                                Indice Remissivo

  F

   Formal Public Identifier, A Declarac,ao DOCTYPE

  I

   Identificador Publico Formal, Identificadores Publicos Formais (FPIs)
