diff options
Diffstat (limited to 'pt_BR.ISO8859-1')
40 files changed, 15754 insertions, 116 deletions
diff --git a/pt_BR.ISO8859-1/articles/Makefile b/pt_BR.ISO8859-1/articles/Makefile index 179cf673ab..c66b28ff60 100644 --- a/pt_BR.ISO8859-1/articles/Makefile +++ b/pt_BR.ISO8859-1/articles/Makefile @@ -1,15 +1,21 @@ -# $FreeBSD$ # # Build the FreeBSD FAQ # # The FreeBSD Documentation Project # The FreeBSD Brazilian Portuguese Documentation Project # -# Original revision: 1.36 +# Original revision: r38826 # +# $FreeBSD$ SUBDIR = SUBDIR+= contributing +SUBDIR+= contributing-ports +SUBDIR+= explaining-bsd +SUBDIR+= freebsd-questions +SUBDIR+= linux-users +SUBDIR+= new-users +SUBDIR+= problem-reports DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/Makefile.inc b/pt_BR.ISO8859-1/articles/Makefile.inc index 6f0272c892..cb9d4cd6d3 100644 --- a/pt_BR.ISO8859-1/articles/Makefile.inc +++ b/pt_BR.ISO8859-1/articles/Makefile.inc @@ -2,7 +2,7 @@ # The FreeBSD Documentation Project # The FreeBSD Brazilian Portuguese Documentation Project # -# Original revision: 1.4 +# Original revision: r38826 # # $FreeBSD$ # diff --git a/pt_BR.ISO8859-1/articles/contributing-ports/Makefile b/pt_BR.ISO8859-1/articles/contributing-ports/Makefile new file mode 100644 index 0000000000..2e619ed49c --- /dev/null +++ b/pt_BR.ISO8859-1/articles/contributing-ports/Makefile @@ -0,0 +1,24 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: Contributing to the FreeBSD Ports Collection + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?=gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/contributing-ports/article.sgml b/pt_BR.ISO8859-1/articles/contributing-ports/article.sgml new file mode 100644 index 0000000000..28983924eb --- /dev/null +++ b/pt_BR.ISO8859-1/articles/contributing-ports/article.sgml @@ -0,0 +1,1078 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r38826 + + $FreeBSD$ +--> + +<article> + <articleinfo> + <title>Contribuindo para a Coleção de Ports do + FreeBSD</title> + + <pubdate>$FreeBSD$</pubdate> + + <abstract> + <title>Sumário</title> + + <para>Este artigo descreve as formas pelas quais uma pessoa pode + contribuir com a Coleção de + <literal>Ports</literal> do FreeBSD.</para> + </abstract> + + <authorgroup> + <author> + <firstname>Sam</firstname> + <surname>Lawrance</surname> + </author> + <author> + <firstname>Mark</firstname> + <surname>Linimon</surname> + </author> + </authorgroup> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.general; + </legalnotice> + </articleinfo> + + <indexterm><primary>Contribuindo com o ports</primary></indexterm> + + <sect1> + <title>Introdução</title> + + <para>A Coleção de <literal>Ports</literal> + é um trabalho permanente, em constante + evolução. Nós queremos oferecer + aos nossos usuários um repositório de + softwares de terceiros que seja fácil de utilizar, + atualizado e de alta qualidade.</para> + + <para>Qualquer um pode se envolver, e existem muitas formas + diferentes de fazer isso. Contribuir para a + coleção de <literal>ports</literal> é + uma excelente forma de ajudar e de <quote>devolver</quote> + algo para o projeto. Não importa se você + está à procura de participação + contínua, ou apenas um desafio divertido para um dia + chuvoso, nós vamos adorar receber a sua ajuda!</para> + + <para> + Como voluntário, o que você faz é limitado + apenas pelo que você quer fazer. No entanto, pedimos que + você tome conhecimento do que os outros membros da + comunidade &os; irão esperar de você. Você + pode querer levar isso em conta antes de decidir se + voluntariar.</para> + </sect1> + + <sect1 id="what-contribute"> + <title>O que você pode fazer para ajudar</title> + + <para>Existem várias maneiras pelas quais você pode + contribuir para manter a árvore de + <literal>Ports</literal> atualizada e em boas + condições de funcionamento:</para> + + <itemizedlist> + <listitem> + <para>Encontre algum software legal e útil e + <link linkend="create-port">crie um + <literal>port</literal></link> para ele.</para> + </listitem> + + <listitem> + <para>Existe um grande número de + <literal>ports</literal> que não têm nenhum + mantenedor (<quote>maintainer</quote>). Torne-se um + mantenedor e <link linkend="adopt-port">adote um + <literal>port</literal></link>.</para> + </listitem> + + <listitem> + <para>Se você tiver criado ou adotado um + <literal>port</literal>, tome conhecimento <link + linkend="maintain-port">do que precisa fazer agora que + é um mantenedor</link>.</para> + </listitem> + + <listitem> + <para>Quando você estiver procurando por um desafio + rápido você pode <link + linkend="fix-broken">corrigir um bug ou um + <literal>port</literal> quebrado</link>.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="create-port"> + <title>Criando um novo <literal>port</literal></title> + + <para>Existe um documento separado, disponível para ajudar + e guiá-lo no processo de criação (ou de + atualização) de um <literal>port</literal>, + chamado <ulink + url="&url.books.porters-handbook;"><literal>Porter's + Handbook</literal></ulink>. O <literal>Porter's + Handbook</literal> é a melhor fonte de referência + para se trabalhar no sistema de <literal>ports</literal>. Ele + fornece detalhes de como o sistema de <literal>ports</literal> + funciona e discute as boas práticas recomendadas.</para> + </sect1> + + <sect1 id="adopt-port"> + <title>Adotando um <literal>port</literal> sem + manutenção</title> + + <sect2> + <title>Escolhendo um <literal>port</literal> sem + manutenção</title> + + <para>Assumir a responsabilidade pela manutenção + de um <literal>port</literal> que está abandonado + é uma excelente forma de se envolver. + <literal>Ports</literal> sem manutenção + só são atualizados ou consertados quando + alguém se voluntaria à trabalhar neles. + Existe um grande número de <literal>ports</literal> + sem manutenção. É uma boa idéia + iniciar com a adoção de um + <literal>port</literal> que você usa + regularmente.</para> + + <para>Os <literal>ports</literal> sem manutenção + tem a variável <makevar>MAINTAINER</makevar> setada + como <literal>ports@FreeBSD.org</literal> em seu + <filename>Makefile</filename>. A lista dos + <literal>ports</literal> sem manutenção, seus + erros atuais, e seus respectivos relatórios de problema + , pode ser vista no <ulink + url="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">Sistema + de Monitoração de Ports do + FreeBSD</ulink>.</para> + + <para>Alguns <literal>ports</literal> afetam um grande + número de outros devido as suas dependências e + aos <literal>ports</literal> escravos. Você deve + esperar até que tenha alguma experiência antes + de se voluntariar para manter um <literal>port</literal> + destes.</para> + + <para>Você pode descobrir se um <literal>port</literal> + tem ou não dependências ou + <literal>ports</literal> + escravos, observando o índice principal de ports + chamado <filename>INDEX</filename>. (O nome do arquivo varia + de acordo com a release do &os;; por exemplo, + <filename>INDEX-8</filename>.) Alguns + <literal>ports</literal> têm dependências + condicionais que não são incluídas na + compilação padrão do + <filename>INDEX</filename>. Esperamos que você seja + capaz de identificar estes <literal>ports</literal> + observando os <filename>Makefile</filename>s dos outros + <literal>ports</literal>.</para> + </sect2> + + <sect2> + <title>Como adotar um <literal>port</literal></title> + + <para>Primeiro certifique-se de que você compreende as + suas <link linkend="maintain-port">responsabilidades como um + mantenedor</link>. Também leia o <ulink + url="&url.books.porters-handbook;">Porter's Handbook</ulink>. + <emphasis>Por favor, não se comprometa com mais do + que o que você se sente capaz de + fazer.</emphasis></para> + + <para>Você pode pedir para se tornar o responsável + por um <literal>port</literal> sem manutenção no + momento em que desejar. Basta definir o + <makevar>MAINTAINER</makevar> para o seu próprio email + e enviar um PR (relatório de problema) com a + mudança. Se o <literal>port</literal> tiver erros de + compilação ou se estiver precisando de + atualização, você pode querer enviar + quaisquer outras alterações no mesmo PR. Isto + irá ajudar porque muitos <literal>comitters</literal> + estão pouco dispostos a designar alguém sem um + histórico conhecido junto ao &os; como + responsável pela manutenção de um + <literal>port</literal>. Enviar PRs os quais corrigem erros + de compilação ou que atualizam + <literal>ports</literal> é a melhor forma de + estabelecer um.</para> + + <para>Envie o seu PR com a categoria <literal>ports</literal> + e a classe <literal>change-request</literal>. Um + <literal>comitter</literal> irá examinar o seu PR, dar + <literal>commit</literal> das alterações e + finalmente fechar o seu PR. Algumas vezes este processo pode + demorar um pouco (afinal os <literal>comitters</literal> + também são voluntários).</para> + </sect2> + </sect1> + + <sect1 id="maintain-port"> + <title>Os desafios dos mantenedores de + <literal>ports</literal></title> + + <para>Esta seção lhe dará uma idéia de + porque os <literal>ports</literal> precisam ser mantidos e + irá apresentar as responsabilidades de um mantenedor de + <literal>ports</literal>.</para> + + <sect2 id="why-maintenance"> + <title>Porque os <literal>ports</literal> precisam de + manutenção</title> + + <para>Criar um <literal>port</literal> é uma tarefa que + demanda esforço uma única vez. Garantir que um + <literal>port</literal> está atualizado e que continua + a compilar e a executar é um esforço de + manutenção permanente. Os mantenedores + (<quote>maintainers</quote>), são pessoas as quais + dedicam uma parte do seu tempo para a realização + destes objetivos.</para> + + <para>A principal razão pela qual o sistema de + <literal>ports</literal> precisa de manutenção + é trazer os melhores e mais recentes softwares de + terceiros para a comunidade &os;. Um desafio adicional + é manter os <literal>ports</literal> individuais + trabalhando com o <literal>framework</literal> da + Coleção de <literal>Ports</literal> a medida que + ele evolui.</para> + + <para>Como mantenedor, você vai precisar gerenciar os + seguintes desafios:</para> + + <itemizedlist> + <listitem> + <formalpara> + <title>Novas versões de software e + atualizações.</title> + + <para>Novas versões e atualizações de + softwares que já pertencem ao + <literal>ports</literal> tornam-se disponíveis o + tempo todo, e estes têm de ser incorporados a + Coleção de <literal>Ports</literal> a fim + de atualizar os softwares disponibilizados por + ela.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Alterações em + dependências.</title> + + <para>Se forem feitas mudanças significativas nas + dependências de seu <literal>port</literal>, ele + pode precisar ser atualizado para que continue a + funcionar corretamente.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Alterações que afetam + <literal>ports</literal> que dependem do seu.</title> + + <para>Se outros <literal>ports</literal> dependem de um + <literal>port</literal> que você mantém, + alterações em seu <literal>port</literal> + podem demandar coordenação com outros + mantenedores.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Interação com outros usuários, + mantenedores e desenvolvedores.</title> + + <para>Parte do trabalho de um mantenedor é atuar no + suporte. Não esperamos que você + ofereça suporte generalizado (mas será bem + vindo se você optar por isto). O que você + deve oferecer é um ponto de + coordenação para questões sobre + os seus <literal>ports</literal> que sejam especificos + ao &os;.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Caça aos bugs.</title> + + <para>Um <literal>port</literal> pode ser afetado por + erros que são específicos ao &os;. + Você vai precisar investigar, encontrar e + corrigir estes erros quando eles forem reportados. + Testar exaustivamente um <literal>port</literal> para + identificar problemas antes que eles cheguem na + Coleção de <literal>Ports</literal> + é ainda melhor.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Alterações na política e na + infra-estrutura de <literal>ports</literal>.</title> + + <para>Ocasionalmente, os sistemas que são + utilizados para compilar os <literal>ports</literal> + e os pacotes são atualizados ou uma nova + recomendação que afeta esta + infra-estrutura é feita. Você deve estar + ciente destas alterações para o caso dos + seus <literal>ports</literal> serem afetados e + precisarem de atualização.</para> + </formalpara> + </listitem> + + <listitem> + <formalpara> + <title>Alterações no sistema base.</title> + + <para>O &os; está em constante desenvolvimento. + Alterações ao software, as bibliotecas, ao + kernel ou mesmo alterações na + política podem alterar os requisitos de um + <literal>port</literal>.</para> + </formalpara> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Responsabilidades de um Mantenedor</title> + + <sect3> + <title>Mantenha seus <literal>ports</literal> + atualizados</title> + + <para>Esta seção descreve o processo que + você deve seguir para manter seus + <literal>ports</literal> atualizados.</para> + + <para>Esta é uma visão geral. Maiores + informações sobre o processo de + atualização de um <literal>port</literal> + estão disponíveis no + <ulink url="&url.books.porters-handbook;"> + Porter's Handbook</ulink>.</para> + + <procedure> + <step> + <title>Fique atentendo para as + atualizações</title> + + <para>Monitore o desenvolvedor para tomar conhecimento + sobre a liberação de novas versões, + atualizações, e correções de + segurança para o software do seu + <literal>port</literal>. Listas de discussão + destinadas a avisos de lançamentos ou + páginas web de notícias são + úteis para fazer isso. + Algumas vezes os usuários + irão entrar em contato com você e perguntar + quando o seu <literal>port</literal> será + atualizado. Se você está ocupado com + outras coisas ou se por qualquer outra razão + não pode fazer a atualização + naquele momento, pergunte se eles irão + ajudá-lo enviando um PR com a + atualização.</para> + + <para>Você também pode receber um email + automático do <literal>sistema de + verificação de ports do &os;</literal> + informando que uma nova versão do seu + <literal>port's distfile</literal> está + disponível. Maiores informações + sobre este sistema (incluindo a de como parar emails + futuros) serão fornecidas na mensagem.</para> + </step> + + <step> + <title>Incorpore as alterações</title> + + <para>Quando elas se tornarem disponíveis, + incorpore as mudanças ao seu + <literal>port</literal>. Você precisa ser capaz + de gerar um <literal>patch</literal> entre o seu + <literal>port</literal> original e o seu + <literal>port</literal> atualizado.</para> + </step> + + <step> + <title>Revisão e teste</title> + + <para>Examine cuidadosamente e teste as suas + alterações:</para> + + <itemizedlist> + <listitem> + <para>Compile, instale e teste o seu + <literal>port</literal> no maior número + possível de plataformas e arquiteturas. + É comum que um <literal>port</literal> + funcione em um <literal>branch</literal> ou + plataforma e falhe em outra.</para> + </listitem> + + <listitem> + <para>Certifique-se de que as dependências do + seu <literal>port</literal> estão completas. + A melhor forma de fazer isto é instalar a sua + própria <literal>ports</literal> + <application>tinderbox</application>. Consulte a + seção sobre <link + linkend="resources">recursos</link> para maiores + informações.</para> + </listitem> + + <listitem> + <para>Verifique se a lista de empacotamento + está atualizada. Isto envolve a + adição de novos arquivos e + diretórios e a remoção de + entradas não utilizadas.</para> + </listitem> + + <listitem> + <para>Verifique o seu <literal>port</literal> + utilizando o &man.portlint.1; como um guia. + Consulte a seção sobre <link + linkend="resources">recursos</link> para + informações importantes sobre o uso do + <application>portlint</application>.</para> + </listitem> + + <listitem> + <para>Avalie se as alterações no seu + <literal>port</literal> podem levar a quebra de + outros <literal>ports</literal>. Se este for o + caso, coordene as alterações com os + mantenedores destes <literal>ports</literal>. Isto + é especialmente importante se a sua + atualização alterar a versão de + uma biblioteca compartilhada; neste caso, no + mínimo, os <literal>ports</literal> que forem + dependentes do seu vão precisar atualizar seu + <makevar>PORTREVISION</makevar> de modo que eles + sejam automaticamente atualizados pelas ferramentas + de automação tais como o + <application>portmaster</application> ou o + &man.portupgrade.1;.</para> + </listitem> + </itemizedlist> + </step> + + <step> + <title>Envie as alterações</title> + + <para>Envie sua atualização através + da submissão de um PR contendo uma + explicação sobre as mudanças e um + patch com as diferenças entre o port original e a + versão atualizada. Por favor, consulte o artigo + <ulink url="&url.articles.problem-reports;">Escrevendo + Relatórios de Problema para o FreeBSD</ulink> + para maiores informações sobre como + escrever um bom PR.</para> + + <note> + <para>Por favor, não envie um arquivo + &man.shar.1; com o <literal>port</literal> inteiro. + Em vez disso, utilize &man.diff.1; + <literal>-ruN</literal>. Desta forma, os + <literal>committers</literal> podem ver com muito mais + facilidade e precisão quais são as + mudanças que estão sendo feitas. A + seção <ulink + url="&url.books.porters-handbook;/port-upgrading.html">Atualizações</ulink> + do <literal>Porter's Handbook</literal> tem maiores + informações.</para> + </note> + </step> + + <step> + <title>Aguarde</title> + + <para>Em algum momento um <literal>committer</literal> vai + cuidar do seu PR. Isto pode demorar alguns minutos, ou + pode levar semanas — desta forma, por favor, seja + paciente.</para> + </step> + + <step> + <title>Dê feedbacks</title> + + <para>Se um <literal>committer</literal> encontrar um + problema nas suas alterações, ele + provavelmente irá encaminhá-lo de volta + para você. Uma resposta rápida irá + ajudá-lo a ter o seu PR resolvido mais + rapidamente, e será melhor para manter o fluxo + de conversação quando se está + tentando resolver qualquer problema.</para> + </step> + + <step> + <title>E finalmente...</title> + + <para>As suas alterações serão + aceitas e o seu <literal>port</literal> estará + atualizado. O PR será fechado pelo + <literal>committer</literal>. E é isso!</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Assegure que os seus <literal>ports</literal> continuem + compilando corretamente.</title> + + <para>Esta seção é sobre descobrir e + corrigir problemas que impeçam os seus + <literal>ports</literal> de compilar corretamente.</para> + + <para>O funcionamendo da <literal>Coleção de + Ports</literal> é garantido pelo &os; apenas no ramo + <literal>-STABLE</literal> do sistema. Você deve + estar executando o <literal>8-STABLE</literal> ou o + <literal>9-STABLE</literal>, preferencialmente o + último. Em teoria, você deve ser capaz de + usá-lo com a última <literal>release</literal> + de cada ramo estável (uma vez que as + <literal>ABIs</literal> não deveriam mudar) mas se + você puder executar o ramo <literal>-STABLE</literal>, + isto será ainda melhor.</para> + + <para>Uma vez que a maioria das instalações do + FreeBSD rodam em maquinas PC compatíveis (como + é denominada a arquitetura <literal>i386</literal>), + nós esperamos que você mantenha os seus + <literal>ports</literal> funcionando nesta arquitetura. + Nós preferimos que os <literal>ports</literal> + também funcionem de forma nativa na arquitetura + <literal>amd64</literal>. É totalmente justo que + você peça ajuda se você não + possuir uma destas máquinas.</para> + + <note> + <para>As falhas mais usuais na compilação para + máquinas não-<literal>i386</literal> ocorrem + porque o programador original assumiu, por exemplo, que os + ponteiros são do tipo <literal>int</literal>, ou + então que uma versão antiga e relativamente + mais frouxa do compilador <application>gcc</application> + está sendo utilizada. Cada vez mais, os autores de + aplicações estão retrabalhando seu + código para remover estes pressupostos — mas + se o autor não estiver mantendo o código + de forma ativa, você pode precisar fazer isto + você mesmo.</para> + </note> + + <para>Estas são as tarefas que precisam ser executadas + para garantir o seu <literal>port</literal> pode ser + compilado:</para> + + <procedure> + <step> + <title>Esteja atento para falhas de + compilação</title> + + <para>Verifique regularmente o cluster de + compilação automatizada de + <literal>ports</literal>, o <ulink + url="http://pointyhat.FreeBSD.org">pointyhat</ulink>, e + o <ulink url="http://www.portscout.org">scanner de + arquivos de distribuição</ulink> para ver + se algum dos <literal>ports</literal> que você + mantém está falhando na + compilação ou no download do + código fonte (veja a seção sobre + <link linkend="resources">recursos</link> para maiores + informações sobre estes sistemas). + Relatórios de falha também podem chegar + até você por email, vindos de outros + usuários ou dos sistemas automatizados.</para> + </step> + + <step> + <title>Colete informações</title> + + <para>Uma vez que você tome conhecimento de um + problema, colete informações para + ajudá-lo a corrigi-lo. Os erros de + compilação reportados pelo pointyhay + são acompanhados por + logs os quais irão lhe mostrar onde a + compilação falhou. Se a falha tiver sido + reportada à você por um usuário, + peça a ele para lhe enviar + informações as quais possam lhe ajudar no + diagnóstico do problema, tais como:</para> + + <itemizedlist> + <listitem> + <para>Logs de compilação</para> + </listitem> + + <listitem> + <para>Os comandos e as opções que foram + utilizadas para compilar o <literal>port</literal> + (incluindo as opções definidas no + <filename>/etc/make.conf</filename>)</para> + </listitem> + + <listitem> + <para>A lista de aplicativos instalados em seus + sistemas, como mostrada pelo &man.pkg.info.1;</para> + </listitem> + + <listitem> + <para>A versão do &os; que eles estão + utilizando, como mostrada pelo + &man.uname.1;<command> -a</command></para> + </listitem> + + <listitem> + <para>Quando a sua Coleção de + <literal>Ports</literal> foi atualizada pela + última vez</para> + </listitem> + + <listitem> + <para>Quando o seu arquivo <filename>INDEX</filename> + foi atualizado pela última vez</para> + </listitem> + </itemizedlist> + </step> + + <step> + <title>Investigue e encontre uma + solução</title> + + <para>Infelizmente não existe um processo simples + a ser seguido para fazer isto. Porém + lembre-se: Se você estiver sem saber o que + fazer, peça ajuda! A &a.ports; é um bom + lugar para começar, e os desenvolvedores do + software também estão frequentemente + dispostos a ajudar.</para> + </step> + + <step> + <title>Envie as alterações</title> + + <para>Assim como na atualização de um + <literal>port</literal>, você agora deve + incorporar as alterações, + revisá-las, testá-las, e depois submeter + um PR com elas, fornecendo feedback, se + necessário.</para> + </step> + + <step> + <title>Envie <literal>patches</literal> para os + desenvolvedores do software</title> + + <para>Em alguns casos você irá precisar + modificar o software do seu <literal>port</literal> para + que ele execute no &os;. Alguns (mas não todos) + desenvolvedores irão aceitar incorporar tais + <literal>patches</literal> em seu código para a + próxima release. Se eles aceitarem, isto pode + até ajudar os seus usuários nos outros + sistemas derivados do BSD e talvez evite esforços + duplicados. Por favor, considere o envio de qualquer + <literal>patch</literal> aplicável aos + desenvolvedores do software como uma cortesia.</para> + </step> + </procedure> + </sect3> + + <sect3> + + <title>Investigue os relatórios de bugs e os PRs + relacionados ao seu <literal>port</literal></title> + + <para>Esta seção é sobre a descoberta + e correção de bugs.</para> + + <para>Os bugs específicos ao &os; são geralmente + causados por suposições feitas pelo + desenvolvedor sobre o ambiente de compilação e + de execução que não se aplicam ao &os;. + É pouco provável que você encontre um + problema deste tipo, eles são mais sutis e + difíceis de diagnosticar.</para> + + <para>Estas são as tarefas que precisam ser executadas + para garantir que o seu <literal>port</literal> continua + funcionando como esperado:</para> + + <procedure> + <step> + <title>Responda os relatórios de bugs</title> + + <para>Bugs podem ser reportados para você por + meio de email através do <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">Banco + de Dados de Relatórios de Problema GNATS</ulink>. + Bugs também podem ser reportados diretamente + à você pelos usuários.</para> + + <para>Você deve responder os PRs e demais + relatórios no prazo de até 14 dias, mas + por favor tente não levar tanto tempo. Tente + responder o mais rápido possível, mesmo + que seja só para dizer que você precisa de + mais algum tempo antes que você possa trabalhar no + PR.</para> + + <para>Se você não responder neste prazo de 14 + dias, qualquer <literal>committer</literal> + poderá realizar o <literal>commit</literal> do PR + ao qual você não respondeu baseado na regra + de <literal>maintainer-timeout</literal>.</para> + </step> + + <step> + <title>Colete informações</title> + + <para>Se a pessoa que reportou o bug não tiver + fornecido também uma correção, + você vai precisar coletar as + informações que irão lhe + permitir gerar uma.</para> + + <para>Se o bug pode ser reproduzido, você pode + coletar a maioria das informações + necessárias você mesmo. Se não + conseguir reproduzi-lo, peça para a pessoa que + reportou o bug para coletar as informações + para você, tais como:</para> + + <itemizedlist> + <listitem> + <para>Uma descrição detalhada das suas + ações, comportamento esperado para o + programa e o seu comportamento atual</para> + </listitem> + + <listitem> + <para>Cópia dos dados que desencadearam o + bug</para> + </listitem> + + <listitem> + <para>Informação sobre o seu ambiente de + compilação e execução + — como, por exemplo, a lista dos aplicativos + instalados e a saída do &man.env.1;</para> + </listitem> + + <listitem> + <para>Dumps de memória</para> + </listitem> + + <listitem> + <para>Rastreamento de pilhas</para> + </listitem> + </itemizedlist> + </step> + + <step> + <title>Elimine os relatórios incorretos</title> + + <para>Alguns dos relatórios de bugs podem estar + incorretos. Por exemplo, o usuário pode ter + simplesmente utilizado o programa de forma errada; ou os + aplicativos instalados podem estar desatualizados e + precisando de atualização. À + vezes, o bug reportado não é + específico ao &os;. Neste caso, relate o bug + para o desenvolvedor do software. Se a + correção do bug estiver dentro da sua + capacidade técnica, você também pode + aplicar um <literal>patch</literal> ao seu + <literal>port</literal>, para que a + correção seja disponibilizada antes do + release da nova versão oficial por parte do + desenvolvedor.</para> + </step> + + <step> + <title>Encontre uma solução</title> + + <para>Assim como ocorre com os erros de + compilação, você vai precisar + encontrar uma correção para o problema. + Mais uma vez, lembre-se de pedir ajuda se você + estiver sem saber por onde começar!</para> + </step> + + <step> + <title>Envie ou aprove as alterações</title> + + <para>Assim como ocorre na atualização de um + <literal>port</literal>, agora você deve + incorporar as alterações, + revisá-las, testá-las, e enviar as suas + mudanças em um PR (ou enviar um followup se + já existir um PR para o problema). Se outro + usuário tiver submetido alterações + em um PR, você também pode enviar um + followup dizendo se aprova ou não estas + mudanças.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Forneça suporte</title> + + <para>Faz parte da função de mantenedor prover + suporte — não para o software em geral — + mas para o <literal>port</literal> e para qualquer problema + ou peculiaridade que seja específica do &os;. + Usuários podem contatá-lo com perguntas, + sugestões, problemas e <literal>patches</literal>. + Na maior parte do tempo serão mensagens especificas + ao &os;.</para> + + <para>Ocasionalmente você pode precisar usar as suas + habilidades diplomáticas para gentilmente direcionar + os usuários que buscam suporte geral aos recursos + apropriados. Menos frequentemente você irá + encontrar pessoas perguntando por que o + <literal>RPM</literal> não está atualizado ou + como eles podem fazer o software executar no Linux XYZ. + Aproveite a oportunidade para informar que o seu + <literal>port</literal> está atualizado (se ele + estiver, é claro) e sugira que eles testem o + &os;.</para> + + <para>À vezes os usuários e desenvolvedores + irão decidir que você é um pessoa + ocupada, cujo tempo é valioso e irão fazer + parte do trabalho para você. Por exemplo, eles + podem:</para> + <itemizedlist> + <listitem> + <para>Submeter um PR ou enviar um <literal>patch</literal> + para atualizar o seu <literal>port</literal>,</para> + </listitem> + + <listitem> + <para>investigar e talvez disponibilizar uma + correção para um PT, ou</para> + </listitem> + + <listitem> + <para>de outra forma, submeter mudanças para o seu + <literal>port</literal>.</para> + </listitem> + </itemizedlist> + + <para>Nestes casos a sua principal obrigação + é responder rapidamente. Mais uma vez, o tempo + limite de espera pela resposta de um mantenedor é de + 14 dias. Após este período as + alterações podem ser processadas sem a sua + aprovação. Eles se deram ao trabalho de fazer + isto por você, portanto, tente pelo menos responder + prontamente. Em seguida analise, aprove, modifique ou + discuta as alterações com eles o mais + rapidamente possível.</para> + + <para>Se você puder fazê-los sentir que a + contribuição deles é apreciada (e ela + deveria ser), você terá melhores chances de + persuadi-los a fazer mais coisas para você no futuro + <!-- smiley -->:-).</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="fix-broken"> + <title>Localizando e corrigindo um <literal>port</literal> + quebrado.</title> + + <para>Existem dois lugares muito bons nos quais você pode + encontrar <literal>ports</literal> que precisam de alguma + atenção.</para> + + <para>Você pode utilizar a <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">interface + web</ulink> do banco de dados dos Relatórios de Problema + para pesquisar e visualizar os PRs não resolvidos. A + maioria dos PRs da categoria <literal>ports</literal> são + referentes a atualizações, mas com um pouco de + pesquisa e leitura das sinopses você deverá ser + capaz de encontrar algo interessante para trabalhar (a classe + <literal>sw-bug</literal> é um bom ponto de + partida).</para> + + <para>O outro lugar é o <ulink + url="http://portsmon.FreeBSD.org/">Sistema de + Monitoração de <literal>Ports</literal> do + &os;</ulink>. Em especial, procure por <literal>ports</literal> + sem manutenção e com erros de + compilação e por <literal>ports</literal> que + estejam marcados como <makevar>BROKEN</makevar> (quebrados). + É OK enviar alterações para um + <literal>port</literal> que está sendo mantido, mas + lembre-se de consultar primeiro o mantenedor para o caso dele + já estar trabalhando na solução do + problema.</para> + + <para>Depois que você tiver encontrado um bug ou problema, + colete informações, investigue e conserte! Se + existir já um PR, envie um followup. Caso + contrário, crie um novo PR. Suas + alterações serão revisadas e se tudo + estiver OK, serão processadas e incorporadas.</para> + </sect1> + + <sect1 id="mortal-coil"> + <title>Saber quando parar</title> + + <para>A medida que seus interesses e compromissos mudarem, + você poderá se ver sem tempo para continuar com + algumas (ou com todas) das suas contribuições + para os seus <literal>ports</literal>. Tudo bem! Por favor, + nos avise se você não estiver mais utilizando um + <literal>port</literal>, ou se de outra forma você + não tem mais tempo ou mesmo interesse para ser um + mantenedor. Desta forma, poderemos seguir em frente e permitir + que outras pessoas trabalhem com os problemas existentes nestes + <literal>ports</literal> sem ter que aguardar pela sua resposta. + Lembre-se, o &os; é um projeto voluntário, se + manter um <literal>port</literal> não é mais + divertido, provavelmente está na hora de deixar alguma + outra pessoa fazê-lo.</para> + + <para>De qualquer forma, a Equipe de Gerenciamento do + <literal>Ports</literal> (<literal>portmgr</literal>) se reserva + o direito de revogar a sua condição de mantenedor + de um <literal>port</literal> se você não estiver + dando manutenção de forma ativa ao mesmo já + há algum tempo (Atualmente, o período limite + é de 3 meses). Com isto queremos dizer que existem + problemas não resolvidos ou atualizações + pendentes as quais não foram trabalhadas durante esse + tempo.</para> + </sect1> + + <sect1 id="resources"> + <title>Recursos para mantenedores de <literal>ports</literal> e + colaboradores</title> + + <para>O <ulink url="&url.books.porters-handbook;">Porter's + Handbook</ulink> é o seu guia de mochila para o sistema + de <literal>ports</literal>. Mantenha ele sempre a + mão!</para> + + <para>O artigo <ulink url="&url.articles.problem-reports;">Escrevendo + Relatórios de Problemas para o FreeBSD</ulink> descreve + as melhores práticas na elaboração e na + submissão de um PR. Em 2005 foram submetidos mais de 11 + mil relatórios de problema na categoria + <literal>ports</literal>. Ao seguir as + recomendações deste artigo você irá + nos ajudar a reduzir o tempo necessário para processar o + seu PR.</para> + + <para>O <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + Banco de Dados de Relatórios de Problemas</ulink>.</para> + + <para>O <ulink url="http://pointyhat.FreeBSD.org/">Pointyhat</ulink> + é o cluster de compilação do sistema de + <literal>ports</literal>. Você pode utilizar o Pointyhat + para verificar os logs de compilação de um + <literal>port</literal> em todas as arquiteturas e releases + principais.</para> + + <para>O <ulink url="http://portsmon.FreeBSD.org/">Sistema de + Monitoração de Ports do &os;</ulink> pode lhe + mostrar informações de referência cruzada + sobre um <literal>port</literal> tais como erros de + compilação e relatórios de problema. Se + você é um mantenedor você pode + utilizá-lo para verificar o status de + compilação dos seus ports. Se você é + um colaborador você pode utilizá-lo para encontrar + <literal>ports</literal> quebrados e sem + manutenção os quais precisam ser + corrigidos.</para> + + <para>O <ulink url="http://www.portscout.org">Scanner de Arquivos + de Distribuição</ulink> da Coleção + de Ports do FreeBSD pode lhe mostrar <literal>ports</literal> + para os quais não é possível fazer o + download do código fonte. Você pode + utilizá-lo nos seus próprios + <literal>ports</literal> ou usá-lo + para encontrar <literal>ports</literal> que precisam ter o seu + <makevar>MASTER_SITES</makevar> atualizado.</para> + + <para>O <literal>ports</literal> + <application>tinderbox</application> + é a forma mais completa de testar um + <literal>port</literal> através de todo o ciclo de + instalação, empacotamento, e + desinstalação. Ele possui uma interface de linha + de comando, mas também pode ser controlado através + de uma interface web. Ele está disponível em + <filename>ports/ports-mgmt/tinderbox</filename>. Você + irá encontrar maiores informações na <ulink + url="http://tinderbox.marcuscom.com/">Home page do marcuscom + sobre o tinderbox</ulink>.</para> + + <para>O &man.portlint.1; é um aplicativo o qual pode ser + utilizado para verificar se o seu <literal>port</literal> esta + em conformidade com as muitas e importantes diretrizes + funcionais e de estilo que se aplicam a um + <literal>port</literal>. O <application>portlint</application> + é um aplicação heurística simples, + de forma que você deve usá-lo <emphasis>apenas como + um guia</emphasis>. Se o <application>portlint</application> + sugerir uma alteração que lhe parece ser + irracional, consulte o <ulink + url="&url.books.porters-handbook;">Porter's Handbook</ulink> ou + peça orientação usando os canais + apropriados.</para> + + <para>A &a.ports; destina-se a discussão de assuntos gerais + relacionados ao sistema de <literal>ports</literal>. Ela + é um bom lugar para se pedir ajuda. Você pode se + <ulink + url="http://lists.freebsd.org/mailman/listinfo">inscrever, ou + ler e consultar o histórico de mensagens da + lista</ulink>. A leitura do histórico da &a.ports-bugs; + e da &a.cvs-ports; também pode ser interessante.</para> + </sect1> +</article> diff --git a/pt_BR.ISO8859-1/articles/contributing/Makefile b/pt_BR.ISO8859-1/articles/contributing/Makefile index 4e8402dbe3..711016a9bd 100644 --- a/pt_BR.ISO8859-1/articles/contributing/Makefile +++ b/pt_BR.ISO8859-1/articles/contributing/Makefile @@ -1,16 +1,14 @@ # $FreeBSD$ # -# Build the FreeBSD FAQ -# # The FreeBSD Documentation Project # The FreeBSD Brazilian Portuguese Documentation Project # -# Original revision: 1.4 +# Original revision: r38826 # DOC?= article -FORMATS?= html +FORMATS?= html html-split INSTALL_COMPRESSED?=gz INSTALL_ONLY_COMPRESSED?= diff --git a/pt_BR.ISO8859-1/articles/contributing/article.sgml b/pt_BR.ISO8859-1/articles/contributing/article.sgml index 17577588f8..204c10c4a9 100644 --- a/pt_BR.ISO8859-1/articles/contributing/article.sgml +++ b/pt_BR.ISO8859-1/articles/contributing/article.sgml @@ -9,12 +9,12 @@ The FreeBSD Documentation Project The FreeBSD Brazilian Portuguese Documentation Project - Original revision: 1.496 + Original revision: r38826 $FreeBSD$ --> -<article lang='pt_br'> +<article> <articleinfo> <title>Contribuindo para o FreeBSD</title> @@ -123,9 +123,9 @@ idioma, você pode ajudar a traduzir novos documentos ou verificar se as traduções existentes estão atualizadas. Primeiro, verifique o <ulink - url="../../books/fdp-primer/translations.html">FAQ sobre - traduções</ulink> no &a.ptbr.p.fdpp;. - Você não estará se comprometendo a + url="&url.books.fdp-primer;/translations.html">FAQ sobre + traduções</ulink> no &a.ptbr.p.fdpp;. + Você não estará se comprometendo a traduzir todos os documentos do FreeBSD fazendo isto — como um voluntário, você pode traduzir muitos ou poucos documentos, quantos desejar. @@ -159,7 +159,7 @@ profundo do kernel do FreeBSD; ou, ambos. Entretanto, também existem muitas tarefas úteis que são apropriadas para os <quote>hackers de final de - semana</quote>.</para> + semana</quote>.</para> <orderedlist> <listitem> @@ -194,14 +194,14 @@ <listitem> <para>Mova as contribuições de <foreignphrase>software</foreignphrase> para - <filename>src/contrib</filename> na árvore do - código fonte.</para> + <filename class="directory">src/contrib</filename> + na árvore do código fonte.</para> </listitem> <listitem> - <para>Tenha certeza que o código disponível em - <filename>src/contrib</filename> está - atualizado.</para> + <para>Tenha certeza que o código disponível em + <filename class="directory">src/contrib</filename> + está atualizado.</para> </listitem> <listitem> @@ -220,7 +220,8 @@ <listitem> <para>Se você contribuiu com algum dos - <literal>ports</literal>, envie suas + <literal>ports</literal>, e teve que fazer alguma + mudança específica para o &os;, envie suas correções de volta aos autores originais (isto tornará sua vida mais fácil quando eles lançarem a próxima @@ -231,9 +232,9 @@ <para>Consiga cópias de padrões formais tais como &posix;. Você pode obter alguns <foreignphrase>links</foreignphrase> sobre estes - padrões no sítio www <ulink - url="http://www.FreeBSD.org/projects/c99/index.html">FreeBSD - C99 e Projeto de Conformidade com Padrões + padrões no sítio www <ulink + url="&url.base;/projects/c99/index.html">FreeBSD + C99 e Projeto de Conformidade com Padrões Posix</ulink>. Compare o comportamento do FreeBSD àquele requerido pelo padrão. Se o comportamento diferir, particularmente em pontos sutis ou @@ -256,12 +257,14 @@ <title>Trabalhe no banco de dados de <literal>PR</literal> (relatório de problemas)</title> - <indexterm><primary>base de dados de relatórios de - problemas</primary></indexterm> + <indexterm> + <primary>base de dados de relatórios de + problemas</primary> + </indexterm> <para>A <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">Lista - de <literal>PRs</literal> do FreeBSD</ulink> mostra todos os + url="&url.base;/cgi/query-pr-summary.cgi">Lista + de <literal>PRs</literal> do FreeBSD</ulink> mostra todos os relatórios de problemas ativos no momento e os pedidos de melhoria que foram submetidos pelos usuários do FreeBSD. O banco de dados inclui tarefas para programadores e @@ -282,6 +285,18 @@ um <literal>patch</literal> pronto para ser testado, ou você pode discutir novas idéias com ele.</para> </sect2> + + <sect2> + <title>Escolha um dos itens da <quote>página de + idéias</quote></title> + + <para>A <ulink url="&url.base;/projects/ideas/">lista de projetos + do &os; e de idéias para voluntários</ulink> + também está disponível para as pessoas + dispostas a contribuir com o projeto &os;. A lista é + atualizada regularmente e contém itens sobre cada projeto + para programadores e para não programadores.</para> + </sect2> </sect1> <sect1 id="contrib-how"> @@ -299,37 +314,37 @@ &a.hackers;. Da mesma forma, pessoas com interesse neste tipo de assunto (e uma tolerância para um <emphasis>alto</emphasis> volume de mensagens!), devem se - inscrever na &a.hackers; através do envio de um e-mail - para &a.majordomo;. Consulte o <ulink - url="../../books/handbook/eresources.html#ERESOURCES-MAIL">&a.ptbr.p.handbook;</ulink> - para maiores informações sobre esta e outras - listas de discussão.</para> + inscrever na &a.hackers;. Consulte o <ulink + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">&a.ptbr.p.handbook;</ulink> + para maiores informações sobre esta e outras + listas de discussão.</para> <para>Se você encontrar um erro ou estiver enviando uma alteração específica; por favor, faça o relatório utilizando o programa &man.send-pr.1; ou a sua <ulink - url="../../../../send-pr.html">interface WWW + url="&url.base;/send-pr.html">interface WWW equivalente</ulink>. A não ser que ele exceda 65KB, inclua qualquer <literal>patch</literal> diretamente no - relatório. Se o <literal>patch</literal> é - destinado a ser aplicado na árvore de código, - coloque a palavra <literal>[PATCH]</literal> na sinópse - do relatório. Quando incluir um - <literal>patch</literal>, <emphasis>não</emphasis> o - faça utilizando copiar-e-colar porque ao copiar-e-colar - os <literal>tabs</literal> serão convertidos para - espaços, e tornará o <literal>patch</literal> - inutilizável. Se o <literal>patch</literal> - ultrapassar 20KB considere a possibilidade de comprimi-lo e - utilizar o &man.uuencode.1; antes de enviá-lo.</para> + relatório. Se o <literal>patch</literal> é + destinado a ser aplicado na árvore de código, + coloque a palavra <literal>[PATCH]</literal> na sinópse + do relatório. Quando incluir um + <literal>patch</literal>, <emphasis>não</emphasis> o + faça utilizando copiar-e-colar porque ao copiar-e-colar + os <literal>tabs</literal> serão convertidos para + espaços, e tornará o <literal>patch</literal> + inutilizável. Quando os <literal>patches</literal> + forem muito maiores que 20KB, considere a possibilidade de + comprimi-los (por ex. usando &man.gzip.1; or &man.bzip2.1;) e + utilize o &man.uuencode.1; para incluir a versão + compactada no seu relatório de problema.</para> <para>Depois de enviar o relatório, voce deve receber uma confirmação junto com um número de registro. Guarde este número de registro, de forma que você possa nos manter atualizados sobre o seu problema - enviando um e-mail para - <email>bug-followup@FreeBSD.org</email>. Coloque o + enviando um e-mail para &a.bugfollowup;. Coloque o número no assunto da mensagem, por ex. <literal>"Re: kern/3377"</literal>. Informações adicionais sobre qualquer relatório de problema @@ -344,9 +359,9 @@ pode pedir que alguém o envie para você enviando e-mail para &a.bugs;.</para> - <para>Consulte também <ulink - url="../../articles/problem-reports/article.html">este - artigo</ulink> sobre como escrever um bom relatório + <para>Consulte também <ulink + url="&url.articles.problem-reports;/article.html">este + artigo</ulink> sobre como escrever um bom relatório de problema.</para> </sect2> @@ -354,16 +369,17 @@ <title>Alterações na Documentação</title> - <indexterm><primary>Envio de - documentação</primary></indexterm> + <indexterm> + <primary>Envio de documentação</primary> + </indexterm> <para>Alterações na documentação são administradas pela &a.doc;. Por favor, verifique o <ulink - url="../../books/fdp-primer/index.html">&a.ptbr.p.fdpp;</ulink> - para obter instruções detalhadas. Envie suas - colaborações e alterações - (inclusive as pequenas são bem vindas!) usando o + url="&url.books.fdp-primer;/index.html">&a.ptbr.p.fdpp;</ulink> + para obter instruções detalhadas. Envie suas + colaborações e alterações + (inclusive as pequenas são bem vindas!) usando o &man.send-pr.1; como descrito no <link linkend="contrib-general"> Relatórios de Erro e Comentários em Geral</link>.</para> @@ -386,8 +402,8 @@ em uma grande variedade de formas para a comodidade dos desenvolvedores que trabalham ativamente no sistema. Consulte o <ulink url=" - ../../books/handbook/current-stable.html">&a.ptbr.p.handbook;</ulink> - para maiores informações sobre como obter e + &url.books.handbook;/current-stable.html">&a.ptbr.p.handbook;</ulink> + para maiores informações sobre como obter e utilizar o FreeBSD-CURRENT.</para> <para>Trabalhar com versões antigas do código, @@ -422,19 +438,25 @@ <para>Por exemplo:</para> - <para> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - ou - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - geraria o tal conjunto de <literal>diffs</literal> de contexto - para um dado arquivo de código ou para uma hierarquia - de diretórios.</para> - - <para>Da mesma forma, - <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen> - ou - <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen> - faria o mesmo, exceto que utilizando o formato de + <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> + + <para>ou</para> + + <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> + + <para>geraria o tal conjunto de <literal>diffs</literal> de + contexto para um dado arquivo de código ou para uma + hierarquia de diretórios.</para> + + <para>Da mesma forma,</para> + + <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen> + + <para>ou</para> + + <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen> + + <para>faria o mesmo, exceto que utilizando o formato de <literal>diff</literal> unificado.</para> <para>Consulte o manual do &man.diff.1; para maiores @@ -519,7 +541,9 @@ <orderedlist> <listitem> - <indexterm><primary>Licensa BSD</primary></indexterm> + <indexterm> + <primary>Licensa BSD</primary> + </indexterm> <para>Os direitos autorais BSD. Este tipo de licensa é a mais preferível devido a sua natureza @@ -532,12 +556,14 @@ </listitem> <listitem> - <indexterm><primary>GPL</primary><see>GNU General Public - License</see></indexterm> - - <indexterm><primary>Licença Pública Geral GNU + <indexterm> + <primary>GPL</primary><see>GNU General Public License</see> + </indexterm> + <indexterm> + <primary>Licença Pública Geral GNU (<foreignphrase>GNU General Public - License</foreignphrase>)</primary></indexterm> + License</foreignphrase>)</primary> + </indexterm> <para>A licensa pública geral GNU, ou <quote>GPL</quote>. Esta licensa não é @@ -550,10 +576,11 @@ contribuições adicionais sob esta licensa. O código sob a GPL também vai para uma parte diferente da árvore, mais especificamente para - <filename>/sys/gnu</filename> ou - <filename>/usr/src/gnu</filename>, de forma que é - muito fácil identificá-lo para qualquer um - que a GPL representa um problema.</para> + <filename class="directory">/sys/gnu</filename> ou + <filename class="directory">/usr/src/gnu</filename>, de + forma que é muito fácil + identificá-lo para qualquer um que a GPL + representa um problema.</para> </listitem> </orderedlist> @@ -630,13 +657,15 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. entidade isenta de impostos são freqüentemente dedutíveis dos impostos federais.</para> - <para>As doações podem ser enviadas - através de cheques para: <address> The FreeBSD - Foundation <street>7321 Brockway Dr.</street> - <city>Boulder</city>, <state>CO</state> - <postcode>80303</postcode> <country>USA</country> - </address> - </para> + <para>As doações podem ser enviadas + através de cheques para: + <address> + The FreeBSD Foundation + <street>7321 Brockway Dr.</street> + <city>Boulder</city>, + <state>CO</state>, <postcode>80303</postcode> + <country>USA</country> + </address></para> <para>A Fundação FreeBSD é agora capaz de receber doações através da web com o @@ -657,17 +686,19 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <sect3> <title>Doando <foreignphrase>Hardware</foreignphrase></title> - <indexterm><primary>doacões</primary></indexterm> + <indexterm> + <primary>doacões</primary> + </indexterm> <para>O projeto de FreeBSD aceita alegremente doações de <foreignphrase>hardware</foreignphrase> para as quais pode encontrar bom uso. Se voce estiver interessado em doar componentes de <foreignphrase>hardware</foreignphrase>; por - favor, contate o <ulink - url="http://www.FreeBSD.org/donations/">Escritório - de Relacionamento com Doadores</ulink>.</para> - </sect3> + favor, contate o + <ulink url="&url.base;/donations/">Escritório de + Relacionamento com Doadores</ulink>.</para> + </sect3> <sect3> <title>Doando Acesso Internet</title> @@ -676,8 +707,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. espelho para os serviços de FTP, WWW ou <command>cvsup</command>. Se você desejar se tornar um sítio espelho; por favor, consulte o artigo <ulink - url="../../articles/hubs/index.html">Espelhando o FreeBSD - </ulink> para maiores informações.</para> + url="&url.articles.hubs;/index.html">Espelhando o + FreeBSD</ulink> para maiores informações.</para> </sect3> </sect2> </sect1> diff --git a/pt_BR.ISO8859-1/articles/explaining-bsd/Makefile b/pt_BR.ISO8859-1/articles/explaining-bsd/Makefile new file mode 100644 index 0000000000..cee66a9543 --- /dev/null +++ b/pt_BR.ISO8859-1/articles/explaining-bsd/Makefile @@ -0,0 +1,26 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: Explaining BSD + +MAINTAINER=doc@FreeBSD.org + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/explaining-bsd/article.sgml b/pt_BR.ISO8859-1/articles/explaining-bsd/article.sgml new file mode 100644 index 0000000000..a7ef6010a1 --- /dev/null +++ b/pt_BR.ISO8859-1/articles/explaining-bsd/article.sgml @@ -0,0 +1,750 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r38826 + + $FreeBSD$ + +--> + +<article> + <articleinfo> + <title>Explicando o BSD</title> + + <author> + <firstname>Greg</firstname> + + <surname>Lehey</surname> + + <affiliation> + <address><email>grog@FreeBSD.org</email></address> + </affiliation> + </author> + + <abstract> + <para>No mundo do open source, a palavra <quote>Linux</quote> + é quase um sinônimo de <quote>Sistema + Operacional</quote>, mas esse não é o + único sistema operacional &unix; + de código aberto. De acordo com o <ulink + url="http://www.leb.net/hzo/ioscount/data/r.9904.txt"> + Contador de Sistemas Operacionais da Internet</ulink>, em + Abril de 1999 31.3% das máquinas conectadas na rede + rodam Linux. 14.6% rodam BSD &unix;. Alguns dos + responsáveis pelas maiores operações da + rede no mundo, como o <ulink + url="http://www.yahoo.com">Yahoo!</ulink>, rodam BSD. O + servidor FTP mais requisitado do mundo em 1999 (atualmente + extinto), <ulink + url="ftp://ftp.cdrom.com/">ftp.cdrom.com</ulink>, usava BSD + para transferir 1.4 TB de dados por dia. É claro, que + não se trata de um nicho de mercado: O BSD é um + segredo muito bem guardado.</para> + + <para>Então, qual é o segredo? Por que o BSD + não é melhor difundido, mais conhecido? Esse + documento abordará essas e outras + questões.</para> + + <para>Ao longo desse documento, as diferenças entre o BSD + e o Linux serão denotadas <emphasis>dessa + forma</emphasis>.</para> + </abstract> + </articleinfo> + + <sect1 id="what-is-bsd"> + <title>O que é BSD?</title> + + <para>BSD significa <quote>Distribuição do Sistema + de Berkeley</quote>. É o nome da + distribuição de códigos fonte proveniente + da Universidade da Califórnia, Berkeley, as quais foram + originalmente extensões para o sistema operacional &unix; + do departamento de Pesquisas da AT&T. Vários + projetos de sistemas operacionais de código aberto + são baseados em uma distribuição desse + código fonte, conhecido como 4.4BSD-Lite. Em + adição, tais sistemas constituem-se de + várias porções de outros projetos de + Código Aberto, incluindo o notável projeto GNU. A + constituição total do sistema operacional + inclui:</para> + + <itemizedlist> + <listitem> + <para>O kernel BSD, que cuida do agendamento de processos, + gerenciamento de memória, multi-processamento + simétrico (SMP), dispositivos de controle, + etc.</para> + + <para><emphasis>Ao contrário do kernel do Linux, + existem vários kernels distintos de sistemas BSD + com diferentes características e + recursos.</emphasis></para> + </listitem> + + <listitem> + <para>A biblioteca C, a API base do sistema.</para> + + <para><emphasis>A biblioteca C do BSD é baseada em + código proveniente de Berkeley, e não do + projeto GNU.</emphasis></para> + </listitem> + + <listitem> + <para>Programas utilitários como shells, + utilitários de manuseio de arquivos, compiladores, + linkadores.</para> + + <para><emphasis>Alguns desses programas são derivados + do projeto GNU, outros não.</emphasis></para> + </listitem> + + <listitem> + <para>O sistema X Window, que provê uma interface + gráfica.</para> + + <para>O sistema X Window usado na maioria das versões + do BSD é mantido pelo <ulink url="http://www.X.org/"> + projeto X.Org</ulink>. O &os; permite ao usuário + escolher entre uma variedade de ambientes de desktop, tais + como <application>Gnome</application>, + <application>KDE</application>, ou + <application>Xfce</application>; e gerenciadores de janela + leves como o <application>Openbox</application>, + <application>Fluxbox</application>, ou + <application>Awesome</application>.</para> + </listitem> + + <listitem> + <para>Muitos outros programas e utilitários.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="what-a-real-unix"> + <title>O que é um UNIX de verdade?</title> + + <para>Os sistemas operacionais BSD não são clones, + mas sim, código livre derivado diretamente do sistema + operacional &unix; da AT&T, que também é o + ancestral dos modernos &unix; System V. Talvez isso lhe + surpreenda. Como pode ser isso, se a AT&T nunca + disponibilizou seus fontes como código aberto?</para> + + <para>É verdade que o &unix; da AT&T não é + Open Source, e do ponto de vista da licença de direitos + legais, o BSD definitivamente <emphasis>não + é</emphasis> &unix;, mas por outro lado, a AT&T + importou muito código de outros projetos, especialmente + do Grupo de Pesquisas de Ciências Computacionais (CSRG) da + Universidade da Califórnia, em Berkeley, CA. Desde 1976 + o CSRG lançava fitas magnéticas com cópias + de seu software, o qual era chamado de + <emphasis>Distribuição do Software de + Berkeley</emphasis> ou <emphasis>BSD</emphasis>.</para> + + <para>As versões iniciais do BSD consistiam-se + fundamentalmente de programas à nível de + usuário, mas essa realidade mudou dramaticamente assim + que o CSRG fechou um contrato com a Agência de Pesquisas e + Projetos de Avançados de Defesa (a DARPA) para atualizar + os protocolos de comunicação que eram usados em + sua rede, a ARPANET. Os novos protocolos passaram a ser + conhecidos como <emphasis>Protocolos de Internet</emphasis>, e + mais tarde como <emphasis>TCP/IP</emphasis> se tornando os mais + importantes protocolos de todos os tempos. A primeira + implementação amplamente distribuída desses + protocolos eram parte do 4.2BSD, em 1982.</para> + + <para>Ao longo da década de 80, várias empresas que + produziam estações de trabalho começaram a + se espalhar. Muitas delas preferiam licenciar o &unix; ao + invés de desenvolverem sistemas operacionais por si + mesmas. A Sun Microsystems em particular, licenciou o &unix; e + implementou uma versão do 4.2BSD, a qual eles chamaram de + &sunos;. Quando a AT&T se deu permissão para vender + o &unix; comercialmente, começaram a desenvolver uma + implementação “na unha” chamada de + System III, que seria rapidamente sucedida pelo System V. A + base do código do System V não incluía o suporte a + networking, então todas as implementações + passaram a incluir software adicional do BSD, incluindo o + TCP/IP, e também programas utilitários como o + interpretador de linha de comandos <emphasis>csh</emphasis> e o + editor <emphasis>vi</emphasis>. Em sua coletividade, estes + aprimoramentos foram conhecidos como + <emphasis>Extensões de Berkeley</emphasis>.</para> + + <para>As fitas magnéticas do BSD continham código + fonte da AT&T e por isso precisavam de uma licença de + fontes do &unix;. Por volta de 1990, os fundos do CSRG estavam + acabando. Alguns membros do grupo decidiram lançar o + código BSD, que era Open Source, sem o código + proprietário da AT&T. Finalmente isso aconteceu com + o <emphasis>Networking Tape 2</emphasis>, normalmente conhecido + como <emphasis>Net/2</emphasis>. O Net/2 não era um + sistema operacional completo: aproximadamente 20% do + código do kernel estava faltando. Um dos membros do + CSRG, William F. Jolitz, escreveu o código que faltava e + o lançou em 1992, como o <emphasis>386BSD</emphasis>. Ao + mesmo tempo, um outro grupo de membros do extinto CSRG formou + uma empresa comercial chamada de <ulink + url="http://www.bsdi.com/">Berkeley Software Design + Inc.</ulink> e lançou uma versão beta de seu + sistema operacional, chamada de <ulink + url="http://www.bsdi.com/">BSD/386</ulink>, baseado nos mesmos + fontes. Depois o nome do sistema operacional mudou para + BSD/OS.</para> + + <para>O 386BSD nunca se tornou um sistema operacional + estável. Ao invés disso, outros dois projetos + nasceram à partir dele, em 1993: O <ulink + url="http://www.NetBSD.org/">NetBSD</ulink> e o <ulink + url="&url.base;/index.html">FreeBSD</ulink>. Originalmente + os dois projetos divergiram devido às diferenças + quanto à paciência na espera de novas melhorias no + 386BSD: o pessoal do NetBSD começou o projeto no + início do ano, e a primeira versão do FreeBSD + não ficou pronta até o final do ano. No meio + tempo, a base do código se modificou o suficiente para + tornar difícil uma união. Em + adição, os projetos tinham objetivos diferentes, + como veremos a seguir. Em 1996, um projeto posterior, o <ulink + url="http://www.OpenBSD.org/">OpenBSD</ulink>, originou-se + à partir do NetBSD e em 2003, o <ulink + url="http://www.dragonflybsd.org/">DragonFlyBSD</ulink> + originou-se a partir do FreeBSD.</para> + </sect1> + + <sect1 id="why-is-bsd-not-better-known"> + <title>Por quê o BSD não é mais + conhecido?</title> + + <para>Por algumas razões, o BSD é relativamente + desconhecido:</para> + + <orderedlist> + <listitem> + <para>Os desenvolvedores do BSD estão frequentemente + mais interessados em aprimorar seu código do que + fazer propaganda dele.</para> + </listitem> + + <listitem> + <para>A maior parte da popularidade do Linux se deve a fatores + externos ao projeto Linux, como a imprensa, e companhias + criadas para oferecer serviços em Linux. Até + recentemente, os BSDs open source não contavam com + tais proponentes.</para> + </listitem> + + <listitem> + <para>Os desenvolvedores BSD tendem a ser mais experientes do + que desenvolvedores Linux, e tem menos interesse em tornar o + sistema fácil de utilizar. Novatos tendem a se + sentir mais confortáveis com Linux.</para> + </listitem> + + <listitem> + <para>Em 1992, a AT&T processou a <ulink + url="http://www.bsdi.com/">BSDI</ulink>, vendedora do + BSD/386, alegando que o produto continha código + proprietário da AT&T. O caso foi resolvido na + corte, em 1994, mas os aspectos da litigação + continuam perseguindo as pessoas. Em Março de 2000 + um artigo publicado na rede afirmou que o caso havia sido + <quote>resolvido recentemente</quote>. + </para> + + <para>Um detalhe que o processo judicial clarificou foi sobre a + denominação: nos anos 80, os BSD eram + conhecidos como <quote>BSD &unix;</quote>. Com a + eliminação do último vestígio de + código da AT&T no BSD, ele também perdeu o + direito de ser chamado de &unix; Contudo ainda podem ser + vistas referências em títulos de livros como + <quote>the 4.3BSD &unix; operating system</quote> e + <quote>the 4.4BSD operating system</quote>.</para> + </listitem> + + <listitem> + <para>Existe uma idéia que os projetos BSD sejam + fragmentados e beligerantes. O <ulink + url="http://interactive.wsj.com/bin/login?Tag=/&URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&">Wall + Street Journal</ulink> falou de + <quote>balkanização</quote> nos projetos BSD. + Assim como o processo judicial, essas idéias se + baseiam fundamentalmente em história antiga.</para> + </listitem> + </orderedlist> + </sect1> + + <sect1 id="comparing-bsd-and-linux"> + <title>Comparando BSD e Linux</title> + + <para>Então qual é realmente a diferença + entre, digamos, o Debian Linux e o FreeBSD? Pra maioria dos + usuários, as diferenças são + surpreendentemente pequenas: Ambos são sistemas + operacionais &unix; like. Ambos são desenvolvidos por + projetos não comerciais (é claro que isso + não se aplica a muitas outras distribuições + Linux). Na próxima seção, vamos dar uma + olhada no BSD e compará-lo com o Linux. As + descrições se aplicam mais ao FreeBSD, que + somatiza uma média estimada de 80% das + instalações de sistemas BSD, mas as + diferenças pro NetBSD, pro OpenBSD e pro DragonFlyBSD + são pequenas.</para> + + <sect2> + <title>Quem é dono do BSD?</title> + + <para>Nenhuma pessoa ou corporação é dona + do BSD. Ele é criado e distribuído por uma + comunidade de contribuidores altamente técnicos em todo + o mundo. Alguns dos componentes do BSD são projetos + Open Source independentes e gerenciados por mantenedores de + projetos distintos.</para> + </sect2> + + <sect2> + <title>Como o BSD é desenvolvido e atualizado?</title> + + <para>Os kernels do BSD são desenvolvidos e mantidos + seguindo o modelo de desenvolvimento do Open Source. Cada + projeto mantém uma <quote>árvore de + código fonte</quote> publicamente acessível + sob o <ulink url="http://www.cvshome.org/">Sistema de + Versões Concorrentes</ulink> (CVS), que contém + todos os arquivos fontes do projeto, incluindo + documentação e outros arquivos acidentais. O + CVS permite que usuários façam <quote>check + out</quote> (em outras palavras, extrair uma cópia) + de qualquer versão desejada do sistema.</para> + + <para>Um grande número de desenvolvedores ao redor do + mundo contribui para as melhorias do BSD. Eles são + divididos em 3 tipos:</para> + + <itemizedlist> + <listitem> + <para><firstterm>Contribuidores</firstterm> escrevem + código e documentação. Eles + não têm permissão de commit (adicionar + código) diretamente na árvore de + código fonte. Para que seu código seja + incluso no sistema, é necessário que seja + revisado e aprovado por um desenvolvedor registrado, os + quais são conhecidos como + <emphasis>committer</emphasis>.</para> + </listitem> + + <listitem> + <para><firstterm>Committers</firstterm> são + desenvolvedores com acesso de escrita na árvore do + código fonte. Para se tornar um commiter, o + indivíduo deve mostrar habilidade na área em + que ele é ativo.</para> + + <para>Faz parte da responsabilidade individual de cada + desenvolvedor considerar quando devem obter + autorização antes de fazer um commit na + árvore. No geral, desenvolvedores experientes + podem fazer modificações que são + obviamente corretas sem precisar de consenso. Por + exemplo, um commiter do projeto de + documentação pode corrigir erros + tipográficos ou gramaticais sem a + necessidade de uma revisão. Por outro lado, + espera-se que desenvolvedores que fazem + alterações muito abrangentes ou complicadas + enviem suas mudanças para revisão antes de + adicioná-las. Em casos extremos, um membro do + Grupo Central (Core Team) cuja função seja, + o Arquiteto Principal pode ordenar que as + modificações sejam retiradas da + árvore do código fonte, em um processo + conhecido como <firstterm>backing out</firstterm>. Todos + os desenvolvedores recebem mensagens de correio + eletrônico sobre cada alteração + individual, portanto é impossível fazer + alguma modificação secretamente.</para> + </listitem> + + <listitem> + <para>O <firstterm>Grupo Central</firstterm>. O FreeBSD e o + NetBSD cada qual, tem um grupo central que gerencia o + projeto. Tais grupos centrais foram criados no decorrer + dos projetos e seu papel não é sempre bem + definido. Não é preciso ser um + desenvolvedor para se tornar membro do grupo central, + apesar de que, normalmente esse é o caso. As + regras para o grupo central variam de um projeto para o + outro, mas no geral eles têm mais voz na hora de dizer as + direções que o projeto deve seguir, do que + outros membros fora do grupo.</para> + </listitem> + </itemizedlist> + + <para>Esse modelo se diferencia do Linux em inúmeras + maneiras:</para> + + <orderedlist> + <listitem> + <para>Não existe uma pessoa em especial que controla + o conteúdo do sistema. Na prática, essa + diferença é sobretaxada, considerando que o + Arquiteto Principal pode solicitar que códigos + sejam retirados do sistema, e que até mesmo o + projeto Linux tem várias pessoas autorizadas a + fazer modificações.</para> + </listitem> + + <listitem> + <para>Por outro lado, <emphasis>existe</emphasis> um + repositório central, um lugar único onde os + fontes inteiros do sistema operacional podem ser + encontrados, incluindo todas as versões + anteriores.</para> + </listitem> + + <listitem> + <para>Os projetos BSD mantém um <quote>Sistema + Operacional</quote> completo, não apenas o + kernel. Essa distinção é + marginalmente proveitosa: nem o BSD nem o Linux são + úteis sem aplicações. As + aplicações usadas sob BSD são + frequentemente as mesmas aplicações usadas + sob Linux.</para> + </listitem> + + <listitem> + <para>Como resultado da manutenção formalizada + de uma única árvore CVS do código + fonte, o desenvolvimento do BSD é limpo, e é + possível acessar qualquer versão do sistema + por seu número de lançamento (release) ou + por data. O CVS ainda oferece manutenção + incremental ao sistema: por exemplo, o repositório + do FreeBSD é atualizado em média 100 vezes + por dia. A maioria dessas alterações + é de pequena ordem.</para> + </listitem> + </orderedlist> + </sect2> + + <sect2> + <title>Releases BSD</title> + + <para>O FreeBSD, o NetBSD e o OpenBSD oferecem o sistema em + três <quote>versões (releases)</quote> + diferentes. Como no Linux, os releases são + identificados por um número, como 1.4.1 ou 3.5. Em + adição, o número da versão tem + um sufixo, indicando seu propósito:</para> + + <orderedlist> + <listitem> + <para>A versão de desenvolvimento do sistema é + chamada de <firstterm>CURRENT</firstterm>. O FreeBSD + relaciona um número ao CURRENT, por exemplo, FreeBSD + 5.0-CURRENT. O NetBSD usa um esquema de + denominação um pouco diferente, adicionando + um sufixo com uma letra única que indica + modificações nas interfaces internas, por + exemplo NetBSD 1.4.3G. O OpenBSD não adiciona + números (<quote>OpenBSD-current</quote>). Todo + novo desenvolvimento no sistema vai nesse branch.</para> + </listitem> + + <listitem> + <para>Em intervalos regulares, entre duas a quatro vezes por + ano, os projetos lançam uma nova versão de + <firstterm>RELEASE</firstterm> do sistema, que é + disponibilizado em CD-ROM e por download gratuíto + em sítios de FTP, por exemplo OpenBSD 2.6-RELEASE + ou NetBSD 1.4-RELEASE. A versão do RELEASE + é destinada a usuários finais e é a + versão normal do sistema. O NetBSD oferece ainda + <emphasis>patch releases</emphasis> (releases de + correções) com um terceiro dígito, + por exemplo, NetBSD 1.4.2.</para> + </listitem> + + <listitem> + <para>Conforme os problemas são encontrados em uma + versão RELEASE, eles são corrigidos, e as + correções são adicionadas à + árvore CVS. No FreeBSD a versão resultante + é chamada de <firstterm>STABLE</firstterm>, + enquanto que no NetBSD e no OpenBSD elas continuam sendo + chamadas de versão RELEASE. Novas + características menores também podem ser + adicionadas nesse branch depois do período de + testes no CURRENT.</para> + </listitem> + </orderedlist> + + <para><emphasis>Em contraste, o Linux mantém duas + árvores de código separadas: a versão + estável e a versão de desenvolvimento. A + versão estável tem ainda um número + menor de versão, como 2.0, 2.2 ou 2.4. Versões + em desenvolvimento tem o número menor ímpar, + como 2.1, 2.4 e 2.5. Em cada caso, a versão é + ainda seguida de um número posterior designando o + release exato. Em adição, cada vendedor de + Linux coloca suas próprias aplicações e + utilitários à nível de usuário, + portanto o nome de sua distribuição + também é importante. Cada + distribuição do vendedor ainda é + acrescida de seu próprio número, então + a descrição completa seria algo parecido com + <quote>TurboLinux 6.0 com kernel + 2.2.14</quote></emphasis></para> + </sect2> + + <sect2> + <title>Quais são as versões disponíveis do + BSD?</title> + + <para>Em contraste com as numerosas distribuições + Linux, existem apenas quatro BSDs de código livre. + Cada projeto BSD mantém sua própria + árvore de código fonte e seu próprio + kernel. Na prática, as divergências entre o + código à nível de usuário parece + ser ainda menor entre os projetos BSD do que entre os + vários Linux.</para> + + <para>É difícil categorizar os objetivos de cada + projeto: as diferenças são bastante subjetivas. + Basicamente,</para> + + <itemizedlist> + <listitem> + <para>O FreeBSD clama por alta performance e facilidade de + uso para usuários finais, e é o favorito de + provedores de conteúdo da rede mundial de + computadores. Ele pode ser usado em um grande + número de plataformas, incluindo sistemas baseados + em &i386; (<quote>PCs</quote>), sistemas baseados em + processadores AMD 64-bit, sistemas baseados em + &ultrasparc;, sistemas baseados em processadores Compaq + Alpha e sistemas baseados em torno da + especificação NEC PC-98. O projeto &os; + possui significativamente mais usuários do que + os outros projetos.</para> + </listitem> + <listitem> + <para>O NetBSD clama pelo máximo de portabilidade: + <quote>é lógico que roda NetBSD</quote>. Ele + roda de máquinas palmtop à grandes + servidores, e vem sendo usado até em missões + espaciais da NASA. É particularmente uma boa + escolha para rodar em equipamentos antigos que não + sejam &intel;.</para> + </listitem> + + <listitem> + <para>O OpenBSD clama por segurança e pureza de + código: ele usa uma combinação dos + conceitos de código livre com rigorosas + revisões de seu código para criar um sistema + demonstravelmente correto, tornando-o a escolha de + organizações conscientes com a + segurança como bancos e departamentos do governo. + Como o NetBSD, ele roda em várias + plataformas.</para> + </listitem> + + <listitem> + <para>O DragonFlyBSD clama por alta performance e + escalabilidade acima de tudo, não importa se estamos + falando de um sistema composto por um único nó + ou um sistema massivamente clusterizado. O DragonFlyBSD tem + muitos objetivos técnicos de longo prazo, mas o seu + foco concentra-se em prover uma infra estrutura de SMP + (multiprocessamento simétrico) que seja fácil + de entender, manter e desenvolver.</para> + </listitem> + </itemizedlist> + + <para>Existem ainda dois sistemas operacionais BSD &unix; + adicionais que não são de código livre, + o BSD/OS e o &macos; X da Apple:</para> + + <itemizedlist> + <listitem> + <para>O BSD/OS era o mais velho dos derivados do 4.4BSD. + Ele não era de código livre, embora as + licenças de seu código fonte estivessem + disponíveis por um preço relativamente + baixo. Ele assemelhava-se ao FreeBSD de diversas formas. + Dois anos depois da aquisição da BSDI pela + Wind River Systems, o BSD/OS falhou em sobreviver como um + produto independente. O suporte e o código fonte + podem ainda estar disponíveis pela Wind River, mas + os novos desenvolvimentos estão todos focados no + sistema operacional embarcado VxWorks.</para> + </listitem> + + <listitem> + <para>O <ulink url="http://www.apple.com/macosx/server/"> + &macos; X</ulink> é a mais recente versão do + sistema operacional da linha &macintosh; da <ulink + url="http://www.apple.com/">Apple Computers Inc.</ulink> + O core BSD deste sistema operacional, o <ulink + url="http://developer.apple.com/darwin/">Darwin</ulink>, + está disponível como um sistema operacional + completamente funcional para computadores x86 e PPC. + Contudo, o sistema gráfico Aqua/Quartz e muitos + outros aspectos proprietários do &macos; X + continuam como código fechado. Vários + desenvolvedores do Darwin também são + desenvolvedores do &os; e vice versa.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Como a licença BSD se diferencia da licença + Pública GNU?</title> + + <para>O Linux está disponível sob a <ulink + url="http://www.fsf.org/copyleft/gpl.html">Licença + Pública Geral GPL (GPL)</ulink>, que foi planejada + para eliminar o software proprietário (de fonte + fechada). Em particular, qualquer trabalho derivado de um + produto lançado sob a GPL também deve oferecer + seu código fonte, caso seja requerido. Em contraste, a + <ulink + url="http://www.opensource.org/licenses/bsd-license.html">licença + BSD</ulink> é menos restritiva: + distribuições apenas binárias são + permitidas. Isso é particularmente atrativo para + aplicações acopladas (embedded).</para> + </sect2> + + <sect2> + <title>O que mais eu deveria saber?</title> + + <para>Considerando que um número menor de + aplicações está disponível para + o BSD do que para o Linux, os desenvolvedores do BSD criaram + um pacote de compatibilidade Linux, que permite que programas + Linux sejam executados sob BSD. O pacote inclui + modificações no kernel, de forma a possibilitar + as corretas chamadas de sistemas Linux, e arquivos de + compatibilidade Linux, como a biblioteca C. Não existe + diferença notável na velocidade de + execução entre aplicações Linux + rodando em uma máquina Linux e aplicações + Linux rodando em uma máquina BSD de mesma + velocidade.</para> + + <para>A natureza <quote>tudo do mesmo fornecedor</quote> dos + sistemas BSD implica na maior facilidade de + atualização do que frequentemente acontece no + caso do Linux. Os BSD oferecem atualizações de + versões de bibliotecas oferecendo módulos de + compatibilidade com versões mais antigas de + bibliotecas, dessa forma é possível rodar + binários que existem há vários anos sem o + menor problema.</para> + </sect2> + + <sect2> + <title>Qual eu devo usar, BSD ou Linux?</title> + + <para>O que isso tudo significa na prática? Quem deve + usar BSD? Quem deve usar Linux?</para> + + <para>Essa é uma pergunta muito difícil para se + responder. Aqui estão algumas + considerações:</para> + + <itemizedlist> + <listitem> + <para><quote>Se não está quebrado, não + conserte</quote>: Se você já usa algum + sistema operacional de código livre, e está + feliz com ele, provavelmente não existe uma boa + razão para mudar.</para> + </listitem> + + <listitem> + <para>Sistemas BSD, em particular o FreeBSD, podem ter + performance notavelmente superior ao Linux. Mas + isso não é uma regra. Em muitos casos a + diferença pode ser pouca ou até mesmo nem + existir. Em alguns casos o Linux pode funcionar melhor + que o FreeBSD.</para> + </listitem> + + <listitem> + <para>No geral, sistemas BSD tem melhor + reputação por sua confiabilidade, + principalmente por ser resultado de uma base de + códigos mais madura.</para> + </listitem> + + <listitem> + <para>Os projetos BSD têm uma melhor + reputação em relação a + qualidade e abrangência da sua + documentação. Os vários projetos de + documentação têm por objetivo prover + ativamente documentos atualizados, em muitos idiomas e + cobrindo todos os aspectos do sistema.</para> + </listitem> + + + <listitem> + <para>A licença BSD pode ser mais atrativa do que a + GPL.</para> + </listitem> + + <listitem> + <para>O BSD pode executar a maioria dos binários do + Linux, enquanto o Linux não pode executar + binários do BSD. Muitas das + implementações; BSD podem inclusive executar + binários de outros sistemas derivados do &unix;. + Como resultado, o BSD pode ser uma opção de + migração a partir de outros sistemas mais + fácil do que o Linux seria.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Quem oferece suporte, serviços e treinamento para + o BSD?</title> + + <para>A BSDI / <ulink url="http://www.freebsdmall.com">FreeBSD + Mall, Inc.</ulink> têm fornecido contratos de suporte + FreeBSD no mercado a quase uma década.</para> + + <para>Em adição, cada um dos projetos tem uma + lista de consultores que podem ser contratados: <ulink + url="&url.base;/commercial/consulting_bycat.html">FreeBSD</ulink>, + <ulink + url="http://www.netbsd.org/gallery/consultants.html">NetBSD</ulink>, + e <ulink + url="http://www.openbsd.org/support.html">OpenBSD</ulink>.</para> + </sect2> + </sect1> +</article> diff --git a/pt_BR.ISO8859-1/articles/freebsd-questions/Makefile b/pt_BR.ISO8859-1/articles/freebsd-questions/Makefile new file mode 100644 index 0000000000..c30215815e --- /dev/null +++ b/pt_BR.ISO8859-1/articles/freebsd-questions/Makefile @@ -0,0 +1,26 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: How to get best results from the FreeBSD-questions mailing list + +MAINTAINER=doc@FreeBSD.org + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/freebsd-questions/article.sgml b/pt_BR.ISO8859-1/articles/freebsd-questions/article.sgml new file mode 100644 index 0000000000..c4b8a05b1c --- /dev/null +++ b/pt_BR.ISO8859-1/articles/freebsd-questions/article.sgml @@ -0,0 +1,797 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r38826 +--> + +<article> + <articleinfo> + <title>Como obter o melhor resultado para as suas perguntas na + lista de discussão FreeBSD-Question</title> + + <author> + <firstname>Greg</firstname> + <surname>Lehey</surname> + + <affiliation> + <address><email>grog@FreeBSD.org</email></address> + </affiliation> + </author> + + <pubdate> $FreeBSD$ </pubdate> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.microsoft; + &tm-attrib.netscape; + &tm-attrib.opengroup; + &tm-attrib.qualcomm; + &tm-attrib.general; + </legalnotice> + + <abstract> + <para>Este documento prove informações + úteis para as pessoas que planejam enviar + um email para a lista de discussão + FreeBSD-questions. Os avisos e conselhos foram elaborados com + o com objetivo de maximizar as chances de que o leitor receba + respostas úteis para as suas mensagens.</para> + + <para>Este documento é enviado regularmente para a lista + de discussão FreeBSD-questions.</para> + </abstract> + </articleinfo> + + <sect1> + <title id="Introduction">Introdução</title> + + <para>A lista de discussão + <literal>FreeBSD-questions</literal> é + mantida pelo projeto FreeBSD para ajudar as pessoas que possuem + perguntas referentes ao uso cotidiano do FreeBSD. + Diferentemente da lista <literal>FreeBSD-hackers</literal>, na + qual são discutidas questões mais + avançadas, tais como os rumos + a serem seguidos no desenvolvimento futuro do FreeBSD.</para> + + <note> + <para>O termo <quote>hacker</quote> não está + relacionado com pessoas que invadem os computadores de outras + pessoas. O termo correto para este tipo de atividade é + <quote>cracker</quote>, porém a imprensa popular + insiste em confundi-los. Os hackers do FreeBSD desaprovam + fortemente as atividades de <literal>cracking</literal> + (quebra de segurança), e não se envolvem com + as mesmas. Para uma descrição mais abrangente + sobre hackers, consulte o artigo + <ulink url="http://www.catb.org/~esr/faqs/hacker-howto.html"> + Como se tornar um hacker</ulink>, de autoria de Eric + Raymond.</para> + </note> + + <para>A FreeBSD-questions se destina a ajudar tanto as pessoas + que buscam auxilio na lista (os + <quote>recém-chegados</quote>), quanto as que respondem + as perguntas enviadas (os <quote>hackers</quote>).</para> + + <para>Inevitavelmente é normal ocorrerem alguns atritos + na lista, os quais são decorrentes dos diferentes + pontos de vista dos dois grupos predominantes. Os + recém-chegados acusam os hackers de serem arrogantes, de + se considerarem melhores que os outros, e de serem + inúteis, enquanto os hackers acusam os + recém-chegados de serem estúpidos, de serem + incapazes de lerem a documentação, e de esperarem + que tudo lhe seja dado em uma bandeja de prata. É claro, + existem elementos verdadeiros nas afirmações de + ambas as partes, porém estes pontos de vista, na maior + parte das vezes, levam ambas as partes a uma + sensação de frustração.</para> + + <para>Neste documento, eu gostaria de fazer algo para aliviar + esta frustração e auxiliá-los para que + obtenham melhores resultados para as suas perguntas na + FreeBSD-questions. Na sessão seguinte, eu mostrarei + como enviar uma pergunta, e depois disso, iremos ver como + responder a uma.</para> + </sect1> + + <sect1> + <title id="subscribe">Como se cadastrar na + FreeBSD-questions</title> + + <para>A FreeBSD-questions é uma lista de discussão + por email, logo você precisa ter acesso a uma conta de + email. Para se inscrever vá até a <ulink + url="&a.questions.url;">página web de + informações da lista de discussão + FreeBSD-questions</ulink>. Na seção denominada + <quote>Subscribing to freebsd-questions</quote> (Inscrevendo-se + na freebsd-question) preencha o campo <quote>Your email + address</quote> com o seu endereço de email; os outros + campos são opcionais.</para> + + <note> + <para>O campo de password no formulário de + inscrição provê apenas uma segurança + leve, mas que deve evitar que outras pessoas brinquem com a sua + inscrição. <emphasis>Não utilize nenhum + password que você já faça uso em outros + serviços e/ou sites</emphasis>, pois eventualmente ele + será enviado de volta para você em texto + simples.</para> + </note> + + <para>Você irá receber uma mensagem de + confirmação do <application>mailman</application>; + siga as instruções contidas no email para + completar a sua inscrição.</para> + + <para>Por último, quando você receber a mensagem de + boas vindas (<quote>Welcome</quote>) do + <application>mailman</application> contendo os detalhes da + lista e o seu password para a área de assinantes, + <emphasis>por favor, salve uma cópia</emphasis>. Se + no futuro você desejar sair da lista, você + irá precisar destas informações. + Veja a próxima seção para maiores + detalhes.</para> + </sect1> + + <sect1> + <title id="unsubscribe">Como se descadastrar da + FreeBSD-questions?</title> + + <para>Quando você se cadastrou na FreeBSD-questions, + você recebeu uma mensagem de boas vindas do + <application>mailman</application>. Nesta mensagem, no meio de + outras coisas, estão as instruções de + como se descadastrar. Aqui está uma mensagem + típica:</para> + + <literallayout class="monospaced"> +Welcome to the freebsd-questions@freebsd.org mailing list! + +To post to this list, send your email to: + + freebsd-questions@freebsd.org + +General information about the mailing list is at: + + http://lists.freebsd.org/mailman/listinfo/freebsd-questions + +If you ever want to unsubscribe or change your options (e.g., switch +to or from digest mode, change your password, etc.), visit your +subscription page at: + +http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de + +You can also make such adjustments via email by sending a message to: + + freebsd-questions-request@freebsd.org + +with the word `help' in the subject or body (don't include the +quotes), and you will get back a message with instructions. + +You must know your password to change your options (including changing +the password, itself) or to unsubscribe. It is: + + 12345 + +Normally, Mailman will remind you of your freebsd.org mailing list +passwords once every month, although you can disable this if you +prefer. This reminder will also include instructions on how to +unsubscribe or change your account options. There is also a button on +your options page that will email your current password to you. +</literallayout> + + <para>A partir da url especificada na sua mensagem de boas vindas + (<quote>Welcome</quote>) você deve visitar a página + de gerenciamento de conta (<quote>Account management + page</quote>) e entrar com a sua requisição de + cancelamento da sua inscrição + (<quote>Unsubscribe</quote>) na lista + de discussão FreeBSD-questions.</para> + + <para>Uma mensagem de confirmação será + enviada para você pelo <application>mailman</application>; + siga as instruções contidas nesta mensagem para + finalizar o processo de cancelamento.</para> + + <para>Se você já fez isso, e ainda continua + recebendo mensagens da lista, envie uma mensagem para + <email>freebsd-questions-request@FreeBSD.org</email> pedindo + ajuda e eles irão resolver as coisas para você. + <emphasis>Não</emphasis> envie a sua mensagem para a + FreeBSD-questions: eles não podem + ajudá-lo.</para> + </sect1> + + <sect1> + <title id="askwho">Devo perguntar na <literal>-questions</literal> + ou na <literal>-hackers</literal>?</title> + + <para>Duas listas de discussão lidam com questões + gerais sobre o FreeBSD, <literal>FreeBSD-questions</literal> e + <literal>FreeBSD-hackers</literal>. Em alguns casos, não + é realmente muito simples saber para qual dos grupos + você deve perguntar. O critério seguinte deve + ajuda-lo nessa decisão para 99% de todas as + dúvidas, entretanto:</para> + + <orderedlist> + <listitem> + <para>Se a pergunta é de natureza geral, pergunte na + <literal>FreeBSD-questions</literal>. Exemplos de perguntas + desta natureza são as perguntas sobre a + instalação do FreeBSD ou sobre o uso + especifico de algum utilitário &unix;.</para> + </listitem> + + <listitem> + <para>Se você acredita que a pergunta está + relacionada a uma falha, mas você não tem + certeza disso ou não sabe como procurá-lo, + envie a mensagem para a <literal>FreeBSD-questions + </literal>.</para> + </listitem> + + <listitem> + <para>Se a pergunta se relaciona a uma falha, e você tem + <emphasis>certeza</emphasis> de que é uma falha (por + exemplo, você pode destacar o lugar no código + fonte onde ele ocorre, e você talvez tenha uma + correção), então envie a mensagem para + a <literal>FreeBSD-hackers</literal>.</para> + </listitem> + + <listitem> + <para>Se a pergunta se relaciona a melhorias para o FreeBSD, e + você pode fazer sugestões sobre como + implementá-las, então envie a mensagem para a + <literal>FreeBSD-hackers</literal>.</para> + </listitem> + </orderedlist> + + <para>Existe um grande número de outras listas de + discussão especializadas, por exemplo, + <literal>FreeBSD-isp</literal>, a qual trata dos interesses dos + ISPs (Provedores de Serviço Internet) que rodam o + FreeBSD. No caso de você ser um ISP, isso não + significa que deve enviar automaticamente suas perguntas para a + <literal> FreeBSD-isp</literal>. O critério acima + continua válido, e você deve continuar seguindo-o, + uma vez que você irá obter melhores resultados + desta forma.</para> + </sect1> + + <sect1> + <title id="before">Antes de enviar uma pergunta</title> + + <para>Você pode (e deve) fazer algumas coisas você + mesmo antes de fazer uma pergunta em uma lista de + discussão:</para> + + <itemizedlist> + <listitem> + <para>Tente resolver o problema sozinho. Se você + enviar uma pergunta a qual mostre que você já + tentou resolver o problema, geralmente irá atrair + mais a atenção das pessoas que lerem a sua + pergunta. Além disso, ao tentar resolver o problema, + você irá reforçar o seu domínio + do FreeBSD, o que irá eventualmente possibilitar que + você o utilize para ajudar outras pessoas, respondendo + as perguntas que elas enviarem para as listas de + discussão.</para> + </listitem> + + <listitem> + <para>Leia as páginas de manual, e a + documentação do FreeBSD (elas estão + instaladas em <filename>/usr/doc</filename> ou + acessíveis via WWW em <ulink + url="http://www.FreeBSD.org"> http://www.FreeBSD.org</ulink>), + especialmente o <ulink + url="&url.books.handbook;/index.html">handbook</ulink> e o + <ulink url="&url.books.faq;/index.html">FAQ</ulink>.</para> + </listitem> + + <listitem> + <para>Navegue ou faça uma busca no histórico da + lista para ver se a sua pergunta ou uma semelhante a ela + já não foi feita (e possivelmente respondida) + antes. Você pode navegar e/ou realizar buscas no + histórico das listas de discussão nos URLs + <ulink + url="http://www.FreeBSD.org/mail">http://www.FreeBSD.org/mail + </ulink> e <ulink + url="http://www.FreeBSD.org/search/search.html#mailinglists"> + http://www.FreeBSD.org/search/search.html#mailinglists</ulink> + respectivamente. Isto também pode ser feito em + outros locais, como por exemplo em <ulink + url="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com + </ulink>.</para> + </listitem> + + <listitem> + <para>Utilize um mecanismo de busca como o <ulink + url="http://www.google.com">Google</ulink> ou o <ulink + url="http://www.yahoo.com">Yahoo</ulink> para procurar + respostas para a sua dúvida. O Google possui uma + <ulink url="http://www.google.com/bsd">interface especifica + para buscas relacionadas aos *BSDs</ulink>.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title id="submit">Como enviar uma pergunta</title> + + <para>Quando enviar uma pergunta para a FreeBSD-questions, + considere os seguintes pontos:</para> + + <itemizedlist> + <listitem> + <para>Lembre-se que ninguém é pago para + responder as suas perguntas sobre FreeBSD. Eles o fazem de + boa vontade. Você pode influenciar positivamente esta + boa vontade através do envio de uma pergunta bem + formulada fornecendo a maior quantidade possível de + informações relevantes. Você pode + influenciar de forma negativa esta boa vontade ao enviar uma + pergunta incompleta, ilegível ou rude. É + perfeitamente possível enviar uma mensagem para a + FreeBSD-questions e não obter nenhuma resposta mesmo + que você siga estas regras. Mas é muito mais + provável que você não obtenha a resposta + se você não as seguir. No restante deste + documento, veremos como obter o máximo de resultado + para as suas perguntas na FreeBSD-questions.</para> + </listitem> + + <listitem> + <para>Nem todos que respondem as perguntas sobre FreeBSD + lêem todas as mensagens: Eles olham para o assunto da + mensagem e decidem se os interessa. Claramente, é de + seu interesse especificar o campo assunto de forma adequada. + <quote>Problema com o FreeBSD</quote> ou + <quote>Ajudem-me</quote> não são adequados. + Se você não especificar um assunto, muitas + pessoas não se incomodarão em ler a sua + mensagem. Se o assunto da sua mensagem não for + específico o suficiente, as pessoas que podem + responder a sua duvida podem não se interessar em ler + a sua mensagem.</para> + </listitem> + + <listitem> + <para>Formate sua mensagem de forma que ela seja + legível, e POR FAVOR, NÃO GRITE!!!!!. + Nós sabemos que muitas pessoas não tem a + língua inglesa como seu idioma nativo, e tentamos + fazer concessões para estas pessoas, mas é + realmente doloroso tentar ler uma mensagem cheia de erros + tipográficos ou sem nenhuma quebra de linha.</para> + + <para>Não subestime o efeito de uma mensagem de email + mal formatada, e não apenas na lista de + discussão FreeBSD-questions. A sua mensagem de email + é tudo que as outras pessoas vêem de + você, e se ela for mal formatada, possui apenas uma + linha por parágrafo, é mal escrita, ou + está cheia de erros, ela dará as outras + pessoas uma impressão negativa de você.</para> + + <para>Muitas das mensagens mal formatadas vêm de <ulink + url="http://www.lemis.com/email.html">clientes de email + ruins ou mal configurados</ulink>. Os clientes de email a + seguir são conhecidos por enviar mensagens mal + formatadas:</para> + + <itemizedlist> + <listitem> + <para>cc:Mail</para> + </listitem> + + <listitem> + <para>&eudora;</para> + </listitem> + + <listitem> + <para>exmh</para> + </listitem> + + <listitem> + <para>µsoft; Exchange</para> + </listitem> + + <listitem> + <para>µsoft; Internet Mail</para> + </listitem> + + <listitem> + <para>µsoft; &outlook;</para> + </listitem> + + <listitem> + <para>&netscape;</para> + </listitem> + </itemizedlist> + + <para>Como você pode ver, os clientes de email do mundo + Microsoft são ofensores freqüentes. Sempre que + for possível utilize um cliente de email &unix;. Se + você precisar utilizar um cliente de email no ambiente + Microsoft, tenha certeza de que o configurou corretamente. + Tente não utilizar o <acronym>MIME</acronym>: muitas + pessoas usam clientes de email que não se entendem + bem com mensagens em formato MIME.</para> + </listitem> + + <listitem> + <para>Certifique-se de que sua data e hora, assim como o seu + fuso horário estão corretamente configurados. + Isso pode parecer besteira, uma vez que sua mensagem ainda + estará lá, mas muitas pessoas que você + esta tentando alcançar começam o dia com + centenas de mensagens para ler. Eles freqüentemente + ordenam as mensagens que chegaram por assunto e por data e + se a sua mensagem não vier antes da primeira + resposta, eles podem assumir que a mensagem está + faltando e não se incomodarão em + procura-la.</para> + </listitem> + + <listitem> + <para>Não inclua perguntas que não se relacionam + em uma mesma mensagem. Primeiro, uma mensagem longa tende a + espantar as pessoas, e segundo, é mais difícil + de conseguir que as pessoas que podem responder a todas as + suas perguntas leiam a mensagem.</para> + </listitem> + + <listitem> + <para>Forneça o maior número de + informações relevantes quanto possível. + Esta é uma área difícil, e nós + precisamos detalhar quais informações + você deve enviar, mas aqui está um + começo:</para> + + <itemizedlist> + <listitem> + <para>Em praticamente todos os casos é importante + saber qual a versão do FreeBSD que você + está utilizando. Um caso particular é o + FreeBSD-Current, para o qual você deve fornecer + também a data do código, embora as + perguntas sobre o ramo -Current não devam ser + encaminhadas para a lista FreeBSD-questions.</para> + </listitem> + + <listitem> + <para>No caso de qualquer problema que <emphasis>possa + estar </emphasis> relacionado a hardware, envie + informações sobre o seu hardware. No caso + de dúvida, assuma que seu problema pode ser + causado por um problema de hardware e nos envie suas + especificações. Que tipo de CPU + você está utilizando? Qual o clock do + processador? Qual a placa mãe? Qual a + quantidade de memória física instalada? + Quais outros periféricos você possui? Ao + responder perguntas como essa você terá uma + lista com as informações básicas a + enviar.</para> + + <para>Há uma chamada de julgamento aqui, + naturalmente, a saída do comando &man.dmesg.8; + freqüentemente é muito útil, uma vez + que ele nos diz não apenas que componentes de + hardware que você esta utilizando, como + também qual a versão do FreeBSD.</para> + </listitem> + + <listitem> + <para>Se você obtiver uma mensagem de erro, + não diga <quote>Eu recebi uma mensagem de + erro</quote>, diga (por exemplo) <quote>Eu recebi a + mensagem de erro 'No route to host'</quote>.</para> + </listitem> + + <listitem> + <para>Se o seu sistema deu um panic, não diga + <quote>Meu sistema sofre um panic</quote>, diga (por + exemplo) <quote>Meu sistema sofreu um panic e a mensagem + de erro foi 'free vnode isn't'</quote>.</para> + </listitem> + + <listitem> + <para>Se você esta com dificuldades na + instalação do FreeBSD, por favor nos diga + que hardware você possui. Em particular, é + importante conhecer os IRQs e os endereços de I/O + das placas que você tem instalado na sua + máquina.</para> + </listitem> + + <listitem> + <para>Se você está com dificuldades para + colocar o PPP para rodar, descreva a sua + configuração. Qual versão do PPP + você está utilizando? Qual tipo de + autenticação você esta usando? + Você possui um IP dinâmico ou + estático? Quais tipos de mensagens você + tem no seu arquivo de log?</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>A maioria das informações que + você precisa fornecer são as saídas de + programas, tais como &man.dmesg.8;, ou mensagens de + console, as quais usualmente aparecem no + <filename>/var/log/messages</filename>. Não tente + copiar estas informações digitando-as + novamente; isto é realmente desnecessário, e + você estará cometendo um erro. Ao enviar o + conteúdo de um arquivo de log, faça uma + cópia do arquivo e utilize um editor de textos para + cortar as partes desnecessárias, deixando apenas as + que forem relevantes para a interpretação do + problema, ou simplesmente copie e cole o trecho relevante + para a sua mensagem. Para enviar a saída de + comandos, como o &man.dmesg.8;, redirecione a saída + do comando para um arquivo e inclua-o em sua mensagem. + Por exemplo,</para> + + <screen>&prompt.user; <userinput>dmesg > /tmp/dmesg.out</userinput></screen> + + <para>Este comando redireciona as informações + para o arquivo <filename>/tmp/dmesg.out</filename>.</para> + </listitem> + + <listitem> + <para>Se você fez tudo isso, e continua sem receber uma + resposta, podem existir outras razões. Por exemplo, + o problema pode ser muito complicado e ninguém + conhece a resposta, ou então a pessoa que conhece a + resposta está offline. Se você não + obtiver uma resposta depois de, digamos, uma semana, pode + ser útil reenviar a mensagem. Se você + não obtiver resposta para a sua segunda mensagem, + significa que você provavelmente não irá + obter uma nesta lista. Reenviar a mesma pergunta diversas + vezes para a mesma lista apenas irá torná-lo + impopular.</para> + </listitem> + </itemizedlist> + + <para>Para resumir, vamos assumir que você conhece a + resposta para as seguintes questões (sim, ambas + são sobre o mesmo assunto). Escolha qual destas duas + perguntas você estaria mais preparado para + responder:</para> + + <example> + <title>Mensagem 1</title> + + <literallayout class="monospaced">Subject: HELP!!?!?? +Eu simplesmente não consigo colocar o raio do FreeBSD para funcionar, +e eu sou geralmente bom nisso, mas eu nunca vi nada tão difícil de +instalar, ele simplesmente não funciona, não importa o que eu faça. +Por que vocês rapazes não me dizem o que eu estou fazendo errado? +</literallayout> + </example> + + <example> + <title>Mensagem 2</title> + + <literallayout class="monospaced">Subject: Problemas para instalar o FreeBSD + +Eu comprei um CD do FreeBSD 2.1.5 na Walnut Creek, e eu estou tendo +muita dificuldade para instala-lo. Eu possuo um 486 66Mhz com 16 Mb de +memória, uma controladora SCSI Adaptec 1540A, um HD de 1.2GB Quantum +Fireball e um drive cd cdrom Toshiba 3501XA. A instalação funciona +perfeitamente, mas quando eu dou boot no sistema, eu recebo a +mensagem <quote>Missing Operating System</quote>.</literallayout> + </example> + </sect1> + + <sect1> + <title id="followup">Como fazer um follow up em uma + pergunta</title> + + + <para>Frequentemente você pode desejar enviar alguma + informação adicional para uma pergunta que + você já enviou. A melhor forma de fazer isto + é dando um replay na sua mensagem original. Isto tem 3 + vantagens></para> + + <orderedlist> + <listitem> + <para>Você inclui o texto original da mensagem, assim as + pessoas irão saber sobre oque você esta + falando. Não se esqueça de remover as partes + desnecessárias da mensagem original.</para> + </listitem> + + <listitem> + <para>O texto na linha de assunto permanecerá o mesmo + (você se lembrou de colocar um, não lembrou?). + Muitos clientes de email irão ordenar as mensagens + pelo assunto. Isto ajuda a manter as mensagens de um mesmo + grupo juntas.</para> + </listitem> + + <listitem> + <para>Os números de referência da mensagem no + cabeçalho irão apontar para a mensagem + anterior. Alguns clientes de email, como, por exemplo, o + <ulink url="http://www.mutt.org/">mutt</ulink>, podem + agrupar as mensagens por <emphasis>thread</emphasis>, + mostrando o relacionamento exato entre as mensagens.</para> + </listitem> + </orderedlist> + </sect1> + + <sect1> + <title id="answer">Como responder uma pergunta</title> + + + <para>Antes que você responda uma pergunta para + FreeBSD-questions, considere:</para> + + <orderedlist> + <listitem> + <para>Muitos dos pontos relacionados ao envio de uma pergunta, + também se aplicam quando respondemos à uma. + Leia os tópicos anteriores.</para> + </listitem> + + <listitem> + <para>Alguém já respondeu a pergunta? A melhor + forma de verificar isso é ordenando as mensagens pelo + campo assunto: Então (esperamos) você + irá ver a pergunta seguida por qualquer resposta, + todas juntas.</para> + + <para>Se alguém já tiver respondido a pergunta, + isso não significa automaticamente que você + não deve enviar outra. Mas tenha o bom senso de ler + todas as respostas já enviadas antes de enviar as + suas.</para> + </listitem> + + <listitem> + <para>Você tem algo para contribuir alem daquilo que + já foi dito ? Em geral, respostas como <quote>Sim, + eu também</quote> não ajudam muito, mas + é claro existem exceções, como por + exemplo quando alguém está descrevendo um + problema que esta tendo, e que ele não sabe se foi + ocasionado por uma falha dele ou se alho está errado + com o hardware ou com o software que ele está usando. + Se você enviar uma resposta do tipo <quote>eu + também</quote>, você também deve incluir + qualquer outra informação relevante que + você tenha.</para> + </listitem> + + <listitem> + <para>Você tem certeza de que entendeu a pergunta? + Muito freqüentemente, a pessoa que faz uma pergunta + esta confusa ou não se expressou muito bem. Mesmo + com a melhor compreensão do sistema, é + fácil enviar uma mensagem que não responda a + pergunta. Isto não ajuda: você irá + deixar a pessoa que enviou a pergunta mais frustrada ou + confusa do que antes. Se ninguém mais tiver + respondido, e você também não tiver + certeza, você sempre pode solicitar maiores + informações.</para> + </listitem> + + <listitem> + <para>Você tem certeza de que a resposta está + correta? Se não, espere um dia ou mais. Se + ninguém mais aparecer com uma resposta melhor, + você pode enviar a sua resposta e dizer, por exemplo, + <quote>Eu não tenho certeza se estou correto, mas + como ninguém mais respondeu... Porque você + não tenta substituir o seu CDROM ATAPI por + outro?</quote>.</para> + </listitem> + + <listitem> + <para>A menos que tenha uma boa razão para fazer + diferente, responda para a pessoa que enviou a pergunta e + para a FreeBSD-questions. Muitas pessoas inscritas na lista + são <quote>observadoras</quote>: Elas aprendem + através da leitura das mensagens enviadas e + respondidas pelas outras pessoas. Se você deixar uma + mensagem que é de interesse geral fora da lista, + você estará privando estas pessoas dessa + informação. Seja cuidadoso como as respostas + em grupo; muitas pessoas enviam mensagens com centenas de + endereços em CCs. Se este é o caso, tenha + certeza de ajustar as linhas Cc: de forma apropriada.</para> + </listitem> + + <listitem> + <para>Inclua o texto relevante da mensagem original. Mantenha + o mínimo necessário do texto original, mas + não corte demais. Ele precisa ser conciso o + suficiente para que uma pessoa que não tenha lido a + mensagem original entender sobre o que você + está falando.</para> + </listitem> + + <listitem> + <para>Utilize alguma técnica para identificar qual + parte da mensagem veio da mensagem original e qual parte foi + adicionada por você. Eu pessoalmente acho que + adicionar <quote><literal>> </literal></quote> no inicio + de cada linha da mensagem original é o que funciona + melhor. Procure deixar um espaço em branco depois do + <quote><literal>> </literal></quote> e sempre use uma + linha vazia entre a sua resposta e o texto original, isso + deixará sua mensagem mais legível.</para> + </listitem> + + <listitem> + <para>Coloque sua resposta no local correto (Depois do texto + ao qual ela se aplica). É muito difícil ler + uma sequência de mensagens, onde as respostas vem + antes do texto ao qual elas se aplicam.</para> + </listitem> + + <listitem> + <para>A maioria dos clientes de email altera a linha de + assunto em uma resposta adicionando um texto como <quote>Re: + </quote> ao inicio da linha. Se o seu cliente não + fizer isso de forma automática você deve + fazê-lo manualmente.</para> + </listitem> + + <listitem> + <para>Se a pessoa que enviou a pergunta não respeitou + as convenções de formatação + (linhas muito longas, Linha de assunto inapropriada, etc), + <emphasis>por favor</emphasis>, corrija-a. No caso do uso + de uma linha de assunto inapropriada (como, por exemplo, + <quote>Ajudem-me!!??</quote>), altere a linha de assunto + para algo relacionado ao assunto da mensagem, mas mantenha + uma indicação de qual era o assunto original, + por exemplo,<quote>Re: Dificuldades com o PPP em modo + síncrono (era: Ajudem-me!!??)</quote>. Desta forma + as outras pessoas que estão tentando acompanhar a + discussão irão ter menos dificuldades para + acompanhá-la.</para> + + <para>Nesses casos, é apropriado dizer o que você + fez e porque você o fez, mas tente a não ser + rude. Se você acreditar que não pode responder + sem ser rude, simplesmente não responda.</para> + + <para>Se você quiser responder uma mensagem por causa + de sua má formatação, responda-a + apenas para quem a enviou, e não para a lista. + Se você preferir, na resposta você pode apenas + recomendar que ele leia este artigo.</para> + </listitem> + </orderedlist> + </sect1> +</article> diff --git a/pt_BR.ISO8859-1/articles/linux-users/Makefile b/pt_BR.ISO8859-1/articles/linux-users/Makefile new file mode 100644 index 0000000000..e7b9b23ca7 --- /dev/null +++ b/pt_BR.ISO8859-1/articles/linux-users/Makefile @@ -0,0 +1,19 @@ +# +# $FreeBSD$ +# +# Article: FreeBSD Quickstart for Linux Users + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/linux-users/article.sgml b/pt_BR.ISO8859-1/articles/linux-users/article.sgml new file mode 100644 index 0000000000..da3c2621a7 --- /dev/null +++ b/pt_BR.ISO8859-1/articles/linux-users/article.sgml @@ -0,0 +1,745 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r39170 +--> + +<article> + <articleinfo> + <title>Guia Rápido do FreeBSD para Usuários + &linux;</title> + + <authorgroup> + <author> + <firstname>John</firstname> + <surname>Ferrell</surname> + </author> + </authorgroup> + + <copyright> + <year>2008</year> + <holder>The FreeBSD Documentation Project</holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.linux; + &tm-attrib.intel; + &tm-attrib.redhat; + &tm-attrib.unix; + &tm-attrib.general; + </legalnotice> + + <abstract> + <para>O objetivo deste documento é familiarizar + rapidamente os usuários intermediários e + avançados de &linux; com o FreeBSD.</para> + </abstract> + </articleinfo> + + <sect1 id="intro"> + <title>Introdução</title> + + <para>Este documento irá destacar as diferenças + entre &os; e &linux; para que os usuários + intermediários e avançados possam rapidamente + se familiarizar com os conceitos básicos do FreeBSD. + Esta é apenas uma rápida introdução + técnica, ela não tenta discutir as + diferenças <quote>filosóficas</quote> entre os + dois sistemas operacionais.</para> + + <para>Este documento assume que você já tem o &os; + instalado. Se você não tem o &os; instalado ou + precisa de ajuda com o processo de instalação, + por favor, consulte o capítulo <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/install.html"> + Instalando o FreeBSD</ulink> no Handbook.</para> + </sect1> + + <sect1 id="shells"> + <title><literal>Shells</literal>: Sem Bash?</title> + + <para>Usuários vindos do &linux; são frequentemente + surpreendidos por não encontrarem o + <application>Bash</application> como o + <literal>shell</literal> padrão no &os;. De fato, o + <application>Bash</application> nem mesmo está + presente na instalação padrão. Em vez + disso, o &os; usa o &man.tcsh.1; como <literal>shell</literal> + padrão. Embora o <application>Bash</application> e + seus outros <literal>shells</literal> favoritos estejam + disponíveis na <ulink url="article.html#SOFTWARE"> + Coleção de <literal>Ports</literal> + </ulink> do &os;.</para> + + <para>Se você instalar outros <literal>shells</literal>, o + &man.chsh.1; poderá ser usado para definir o + <literal>shell</literal> padrão dos usuários. + Contudo, é recomendável que o + <literal>shell</literal> padrão do + <username>root</username> permaneça inalterado. A + razão para isso é que + <literal>shells</literal> não incluídos na + base do sistema são normalmente instalados em + <filename>/usr/local/bin</filename> ou + <filename>/usr/bin</filename>. Caso ocorra um + problema no sistema de arquivos no qual estão localizados + o <filename>/usr/local/bin</filename> e o + <filename>/usr/bin</filename>, eles não poderão + ser montados. Neste caso, o usuário + <username>root</username> não teria acesso ao seu + <literal>shell</literal> padrão, o que o impediria de + efetuar login. Por este motivo uma segunda conta + <username>root</username>, a conta <username>toor</username>, + foi criada para uso com <literal>shells</literal> que + não fazem parte da base do sistema. Leia o + <literal>FAQ</literal> de segurança para obter + informações sobre a <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/faq/security.html#TOOR-ACCOUNT">conta toor</ulink>.</para> + </sect1> + + <sect1 id="software"> + <title>Pacotes e <literal>Ports</literal>: Adicionando programas + no &os;</title> + + <para>Além do tradicional método &unix; de + instalação de programas (baixar o código + fonte, extrair, editar o código fonte, e compilar), + o &os; oferece dois outros métodos para instalar + aplicações: pacotes e <literal>ports</literal>. + Uma lista completa de todos os <literal>ports</literal> e + pacotes disponíveis pode ser encontrada <ulink + url="http://www.freebsd.org/ports/master-index.html">aqui</ulink>.</para> + + <sect2 id="packages"> + <title>Pacotes</title> + + <para>Pacotes são aplicações + pré-compiladas, o equivalente no &os; ao + <filename>.deb</filename> nos sistemas baseados no + Debian/Ubuntu e ao <filename>.rpm</filename> nos + sistemas baseados no Red Hat/Fedora. Pacotes + são instalados usando &man.pkg.add.1;. Por exemplo, + o seguinte comando instala o + <application>Apache 2.2</application>:</para> + + <screen>&prompt.root; <userinput>pkg_add <replaceable>/tmp/apache-2.2.6_2.tbz</replaceable></userinput></screen> + + <para>Usar a opção <option>-r</option> + dirá ao &man.pkg.add.1; para baixar automaticamente + o pacote e instalá-lo, juntamente com quaisquer + dependências que ele possua:</para> + + <screen>&prompt.root; <userinput>pkg_add -r <replaceable>apache22</replaceable></userinput> +Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/Latest/apache22.tbz... Done. +Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/expat-2.0.0_1.tbz... Done. +Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/perl-5.8.8_1.tbz... Done. +[snip] + +To run apache www server from startup, add apache22_enable="YES" +in your /etc/rc.conf. Extra options can be found in startup script.</screen> + + <note> + <para>Se você está rodando uma versão de + <literal>release</literal> do &os; (6.2, 6.3, 7.0, etc., + geralmente instalada a partir de um CD-ROM) o + <command>pkg_add -r</command> vai baixar o pacote compilado + especificamente para esta versão. Este pacote + <emphasis>pode não</emphasis> ser a versão + mais atual da aplicação. Você pode + usar a variável <envar>PACKAGESITE</envar> para + sobrescrever este comportamento padrão. Por + exemplo, ajuste <envar>PACKAGESITE</envar> para <ulink + url="ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/"></ulink> + para baixar os pacotes mais recentes compilados para a + série 6.X.</para> + + <para>Você pode ler mais sobre as versões do + &os; no artigo <ulink + url="&url.base;/doc/en_US.ISO8859-1/articles/version-guide/"> + Escolhendo a Versão do &os; Certa para Você</ulink>.</para> + </note> + + <para>Para mais informações sobre pacotes, por + favor, consulte a seção 4.4 do Handbook do + &os;: <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/packages-using.html"> + Usando o Sistema de Pacotes</ulink>.</para> + </sect2> + + <sect2 id="ports"> + <title><literal>Ports</literal></title> + + <para>O segundo método para instalação + de aplicações no &os; é a + Coleção de <literal>Ports</literal>. + A Coleção de <literal>Ports</literal> + é um <foreignphrase>framework</foreignphrase> de + <filename>Makefiles</filename> e + <foreignphrase>patches</foreignphrase> especialmente + customizados para a instalação de vários + programas a partir do código fonte no &os;. Ao + instalar um <literal>port</literal> o sistema irá + baixar o código fonte, aplicar qualquer + <foreignphrase>patch</foreignphrase> necessário, + compilar o código, e instalar a + aplicação. O mesmo processo será + aplicado para todas as suas dependências.</para> + + <para>A Coleção de <literal>Ports</literal>, por + vezes designada como a árvore de + <literal>ports</literal>, pode ser encontrada em + <filename>/usr/ports</filename>. Isto assumindo que a + Coleção de <literal>Ports</literal> foi + instalada durante o processo de instalação do + &os;. Se a Coleção de <literal>Ports</literal> + não foi instalada, ela pode ser adicionada a partir + dos discos de instalação usando + &man.sysinstall.8;, ou baixada dos servidores do &os; usando + &man.csup.1; ou &man.portsnap.8;. Instruções + detalhadas para a instalação da + Coleção de <literal>Ports</literal> podem ser + encontradas na <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html"> + seção 4.5.1</ulink> do Handbook.</para> + + <para>A instalação de um <literal>port</literal> + é tão simples (geralmente) quanto entrar no + diretório do <literal>port</literal> desejado e + iniciar o processo de compilação. O exemplo + seguinte instala o <application>Apache 2.2</application> a + partir da Coleção de + <literal>Ports</literal>:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/apache22</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Um grande benefício do uso do + <literal>ports</literal> para instalar programas é a + possibilidade de personalizar as opções de + instalação. Por exemplo, ao instalar o + <application>Apache 2.2</application> a partir do + <literal>ports</literal>, você poderá habilitar + o <application>mod_ldap</application> definindo a + variável <makevar>WITH_LDAP</makevar> ao executar + &man.make.1;:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/apache22</userinput> +&prompt.root; <userinput>make WITH_LDAP="YES" install clean</userinput></screen> + + <para>Por favor, leia a seção 4.5 do Handbook do + &os;, <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html"> + Usando a Coleção de + <literal>Ports</literal></ulink>, para maiores + informações sobre a Coleção de + <literal>Ports</literal>.</para> + </sect2> + + <sect2 id="which"> + <title><literal>Ports</literal> ou pacotes, qual eu devo usar?</title> + + <para>Pacotes são apenas <literal>ports</literal> + pré-compilados, então na prática é + uma questão de instalarmos a partir do código + fonte (<literal>ports</literal>) contra instalarmos de um + pacote binário. Cada método tem seus + próprios benefícios:</para> + + <itemizedlist> + <title>Pacotes (binário)</title> + + <listitem><simpara>Instalação rápida + (a compilação de grandes + aplicações pode ser um tanto + demorada).</simpara></listitem> + + <listitem><simpara>Você não precisar saber como + compilar o programa.</simpara></listitem> + + <listitem><simpara>Não é necessário + instalar compiladores no seu sistema.</simpara></listitem> + </itemizedlist> + + <itemizedlist> + <title><literal>Ports</literal> (código fonte)</title> + + <listitem><simpara>Possibilidade de personalizar as + opções de instalação. (Pacotes + normalmente são compilados com as + opções padrões. Com o + <literal>ports</literal> você pode personalizar + várias opções, como a + compilação de módulos adicionais ou + a mudança do <foreignphrase>path</foreignphrase> de + instalação + padrão.)</simpara></listitem> + + <listitem><simpara>Você pode aplicar seus + próprios <foreignphrase>patches</foreignphrase> se + assim desejar.</simpara></listitem> + </itemizedlist> + + <para>Se você não tem qualquer requisito especial, + o sistema de pacotes provavelmente vai se adequar + muito bem à sua situação. Se + você for precisar personalizar a + instalação, o <literal>ports</literal> é + a melhor opção. (E lembre-se, se você + precisa personalizar a instalação, mas prefere + pacotes, você pode compilar um pacote personalizado a + partir do <literal>ports</literal> usando + <command>make</command> <maketarget>package</maketarget> e, + em seguida, copiar o pacote para outros servidores.)</para> + </sect2> + </sect1> + + <sect1 id="startup"> + <title>Inicialização do Sistema: Onde estão + os <foreignphrase>run-levels</foreignphrase>?</title> + + <para>O &linux; usa o sistema <literal>SysV init</literal>, + enquanto o &os; usa o tradicional <literal>BSD-style</literal> + &man.init.8;. Sob o <literal>BSD-style</literal> &man.init.8; + não existem <foreignphrase>run-levels</foreignphrase> e + nem <filename>/etc/inittab</filename>, em vez disso a + inicialização é controlada pelo + utilitário &man.rc.8;. O <literal>script</literal> + <filename>/etc/rc</filename> lê + <filename>/etc/defaults/rc.conf</filename> e + <filename>/etc/rc.conf</filename> para determinar quais + serviços serão iniciados. Os serviços + especificados são, então, inicializados rodando + os <literal>scripts</literal> de inicialização + correspondentes em <filename>/etc/rc.d/</filename> + e <filename>/usr/local/etc/rc.d/</filename>. Esses + <literal>scripts</literal> são similares aos + <literal>scripts</literal> localizados em + <filename>/etc/init.d/</filename> nos sistemas &linux;.</para> + + <sidebar> + <para><emphasis>Por que existem dois locais para + <literal>scripts</literal> de inicialização de + serviços?</emphasis> Os <literal>scripts</literal> + encontrados em <filename>/etc/rc.d/</filename> são + para aplicações que são parte da + <quote>base</quote> do sistema. (&man.cron.8;, &man.sshd.8;, + &man.syslog.3;, e outros.) Os <literal>scripts</literal> em + <filename>/usr/local/etc/rc.d/</filename> são para + aplicações instaladas pelo usuário, como + <application>Apache</application>, + <application>Squid</application>, etc.</para> + + <para><emphasis>Qual é a diferença entre a + <quote>base</quote> do sistema e as aplicações + instaladas pelo usuário?</emphasis> O &os; é + desenvolvido como um sistema operacional completo. + Em outras palavras, o <literal>kernel</literal>, bibliotecas + do sistema, e utilitários de nível de + usuário (como &man.ls.1;, &man.cat.1;, &man.cp.1;, + etc.) são desenvolvidos juntos e lançados como + um só. Isso é designado como + <quote>base</quote> do sistema. As aplicações + instaladas pelo usuário são + aplicações que não fazem parte da + <quote>base</quote> do sistema, como + <application>Apache</application>, + <application>X11</application>, + <application>Mozilla Firefox</application>, etc. Estas + aplicações instaladas pelo usuário + são geralmente instaladas usando os <ulink + url="article.html#SOFTWARE">Pacotes e a Coleção + de <literal>Ports</literal></ulink>. A fim de mantê-las + separadas da <quote>base</quote> do sistema, as + aplicações dos usuário são + normalmente instaladas sob <filename>/usr/local/</filename>. + Portanto, os binários instalados pelo usuário + residem em <filename>/usr/local/bin/</filename>, arquivos de + configuração em + <filename>/usr/local/etc/</filename>, e assim por + diante.</para> + </sidebar> + + <para>Os Serviços são ativados espeficificando + <literal><replaceable>NomeDoServiço</replaceable>_enable="YES"</literal> + em <filename>/etc/rc.conf</filename> (&man.rc.conf.5;). + Dê uma olhada em + <filename>/etc/defaults/rc.conf</filename> para visualizar os + padrões do sistema, essas configurações + padrões podem ser sobrescritas por + configurações em + <filename>/etc/rc.conf</filename>. Quando instalar + aplicações adicionais não deixe de + analisar a documentação para determinar + como ativar qualquer serviço associado.</para> + + <para>O seguinte trecho do <filename>/etc/rc.conf</filename> ativa + o &man.sshd.8; e o <application>Apache 2.2</application>. Ele + também determina que o <application>Apache</application> + deve ser iniciado com SSL.</para> + + <programlisting># enable SSHD +sshd_enable="YES" +# enable Apache with SSL +apache22_enable="YES" +apache22_flags="-DSSL"</programlisting> + + <para>Uma vez que o serviço foi ativado em + <filename>/etc/rc.conf</filename>, ele pode ser inicializado + pela linha de comando (sem precisar reinicializar o + sistema):</para> + + <screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> start</userinput></screen> + + <para>Se o serviço não foi ativado, ele pode ser + inicializado pela linha de comando usando + <option>forcestart</option>:</para> + + <screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> forcestart</userinput></screen> + </sect1> + + <sect1 id="network"> + <title>Configuração da rede</title> + + <sect2 id="interfaces"> + <title>Interfaces de Rede</title> + + <para>Em vez do identificador genérico + <emphasis>ethX</emphasis>, que o &linux; usa para identificar + uma interface de rede, o &os; usa o nome do driver do + dispositivo de rede seguido por um número como + identificador. A seguinte saída do &man.ifconfig.8; + mostra duas interfaces de rede &intel Pro 1000 + (<devicename>em0</devicename> e <devicename>em1</devicename>): + </para> + + <screen>&prompt.user; <userinput>ifconfig</userinput> +em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + options=b<RXCSUM,TXCSUM,VLAN_MTU> + inet 10.10.10.100 netmask 0xffffff00 broadcast 10.10.10.255 + ether 00:50:56:a7:70:b2 + media: Ethernet autoselect (1000baseTX <full-duplex>) + status: active +em1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + options=b<RXCSUM,TXCSUM,VLAN_MTU> + inet 192.168.10.222 netmask 0xffffff00 broadcast 192.168.10.255 + ether 00:50:56:a7:03:2b + media: Ethernet autoselect (1000baseTX <full-duplex>) + status: active</screen> + </sect2> + + <sect2 id="ipaddress"> + <title>Configuração IP</title> + + <para>Um endereço IP pode ser atribuído a uma + interface de rede usando &man.ifconfig.8;. No entanto, para + mantê-lo persistente entre as + reinicializações, a configuração + deve ser incluída em <filename>/etc/rc.conf</filename>. + O seguinte exemplo configura o <literal>hostname</literal>, o + endereço IP, e o <literal>gateway</literal> + padrão:</para> + + <programlisting>hostname="server1.example.com" +ifconfig_em0="inet 10.10.10.100 netmask 255.255.255.0" +defaultrouter="10.10.10.1"</programlisting> + + <para>Use a seguinte sintaxe para configurar a interface para + DHCP:</para> + + <programlisting>hostname="server1.example.com" +ifconfig_em0="DHCP"</programlisting> + + </sect2> + </sect1> + + <sect1 id="firewall"> + <title><literal>Firewall</literal></title> + + <para>Como o <application>IPTABLES</application> no &linux;, o + &os; também oferece um <literal>firewall</literal> ao + nível de <literal>kernel</literal>; atualmente o &os; + oferece três opções de + <literal>firewalls</literal>:</para> + + <itemizedlist> + <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html">IPFIREWALL</ulink></simpara></listitem> + <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipf.html">IPFILTER</ulink></simpara></listitem> + <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html">PF</ulink></simpara></listitem> + </itemizedlist> + + <para>O <application>IPFIREWALL</application>, ou + <application>IPFW</application> (o comando para gerenciar um + conjunto de regras <application>IPFW</application> é + &man.ipfw.8;), é o <literal>firewall</literal> + desenvolvido e mantido pelos desenvolvedores do &os;. O + <application>IPFW</application> pode ser integrado com + &man.dummynet.4; para prover a capacidade de controle de + tráfego e simular diferentes tipos de conexões de + rede.</para> + + <para>Amostra de uma regra do <application>IPFW</application> para + permitir uma conexão de entrada do + <application>SSH</application>:</para> + + <programlisting>ipfw add allow tcp from any to me 22 in via $ext_if</programlisting> + + <para><application>IPFILTER</application> é um aplicativo + de <literal>firewall</literal> desenvolvido por + Darren Reed. Ele não é específico + para o &os; e foi portado para vários sistemas + operacionais, incluindo NetBSD, OpenBSD, SunOS, HP/UX, e + Solaris.</para> + + <para>Amostra do comando <application>IPFILTER</application> para + permitir uma conexão de entrada do + <application>SSH</application>:</para> + + <programlisting>pass in on $ext_if proto tcp from any to any port = 22</programlisting> + + <para>O último aplicativo de <literal>firewall</literal>, + <application>PF</application>, é desenvolvido pelo + projeto OpenBSD. O <application>PF</application> foi criado + como um substituto para o <application>IPFILTER</application>. + Como tal, a sintaxe do <application>PF</application> é + muito similar à do <application>IPFILTER</application>. + O <application>PF</application> pode ser integrado com + &man.altq.4; para prover recursos de QoS.</para> + + <para>Amostra do comando <application>PF</application> para + permitir uma conexão de entrada do + <application>SSH</application>:</para> + + <programlisting>pass in on $ext_if inet proto tcp from any to ($ext_if) port 22</programlisting> + </sect1> + + <sect1 id="updates"> + <title>Atualizando o &os;</title> + + <para>Existem três métodos para atualizar um + sistema &os;: a partir do código fonte, + atualização binária, e a partir dos + discos de instalação.</para> + + <para>A atualização a partir do código + fonte é a mais demorada, mas por outro lado é + a que oferece a maior flexibilidade. O processo envolve a + sincronização de uma cópia local do + código fonte do sistema a partir dos servidores + <application>CVS</application> (Concurrent Versioning System) + do &os;. Uma vez que o código fonte local esta + atualizado, você pode compilar a nova versão do + <literal>kernel</literal> e dos aplicativos de nível + de usuário. Para maiores informações + sobre atualizações a partir do código + fonte veja <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/updating-upgrading.html"> + o capítulo sobre atualização</ulink> no + Handbook do &os;.</para> + + <para>As atualizações binárias são + similares ao uso do <command>yum</command> ou + <command>apt-get</command> para atualizar sistemas &linux;. O + comando &man.freebsd-update.8; vai baixar e instalar as novas + atualizações. As atualizações + podem ser agendadas usando &man.cron.8;.</para> + + <note> + <para>Se você utilizar o &man.cron.8; para agendar as + atualizações, por favor, certifique-se de + usar <command>freebsd-update cron</command> em seu + &man.crontab.1; para reduzir a possibilidade de que um + grande número de máquinas busquem as + atualizações todas ao mesmo tempo.</para> + + <programlisting>0 3 * * * root /usr/sbin/freebsd-update cron</programlisting> + </note> + + <para>O último método de atualização, + a partir dos discos de instalação, é um + processo bastante simples. Efetue o <literal>boot</literal> + a partir dos discos de instalação e selecione a + opção para atualizar.</para> + </sect1> + + <sect1 id="procfs"> + <title>procfs: Morto, mas vivo na memória</title> + + <para>No &linux;, para determinar se o encaminhamento IP + está ativado, você pode olhar em + <filename>/proc/sys/net/ipv4/ip_forward</filename>. No &os; + você precisa usar o &man.sysctl.8; para ver esta e + outras opções do sistema, pois o &man.procfs.5; + tornou-se obsoleto nas versões mais recentes do &os;. + (Embora <command>sysctl</command> também esteja + disponível no &linux;.)</para> + + <para>No exemplo do encaminhamento IP, você poderia usar o + seguinte comando para determinar se ele está ativado no + seu sistema FreeBSD:</para> + + <screen>&prompt.user; <userinput>sysctl net.inet.ip.forwarding</userinput> +net.inet.ip.forwarding: 0</screen> + + <para>A opção <option>-a</option> é + utilizada para listar todas as configurações + do sistema:</para> + + <screen>&prompt.user; <userinput>sysctl -a</userinput> +kern.ostype: FreeBSD +kern.osrelease: 6.2-RELEASE-p9 +kern.osrevision: 199506 +kern.version: FreeBSD 6.2-RELEASE-p9 #0: Thu Nov 29 04:07:33 UTC 2007 + root@i386-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC + +kern.maxvnodes: 17517 +kern.maxproc: 1988 +kern.maxfiles: 3976 +kern.argmax: 262144 +kern.securelevel: -1 +kern.hostname: server1 +kern.hostid: 0 +kern.clockrate: { hz = 1000, tick = 1000, profhz = 666, stathz = 133 } +kern.posix1version: 200112 +...</screen> + + <note> + <para>Alguns dos valores do <command>sysctl</command> + estão disponíveis somente para + leitura.</para></note> + + <para>Existem ocasiões nas quais o <literal>procfs</literal> + é necessário, como na execução de + programas antigos, no uso do &man.truss.1; para rastrear + chamadas de sistema, e para possibilitar a <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/linuxemu.html"> + Compatibilidade Binária com Linux</ulink>. + (Embora a Compatibilidade Binária com Linux use seu + próprio <literal>procfs</literal>, &man.linprocfs.5;.) + Se você precisar montar o <literal>procfs</literal>, + você pode adicionar a seguinte entrada no + <filename>/etc/fstab</filename>:</para> + + <screen>proc /proc procfs rw,noauto 0 0</screen> + + <note> + <para><option>noauto</option> vai prevenir + <filename>/proc</filename> de ser montado automaticamente + durante o <literal>boot</literal>.</para></note> + + <para>E então monte o <literal>procfs</literal> com:</para> + + <screen>&prompt.root; <userinput>mount /proc</userinput></screen> + </sect1> + + <sect1 id="commands"> + <title>Comandos Comuns</title> + + <sect2 id="packageCommands"> + <title>Gerenciamento de Pacotes</title> + + <para> + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Comando no &linux; (Red Hat/Debian)</entry> + <entry>Equivalente no &os;</entry> + <entry>propósito</entry> + </row> + </thead> + + <tbody> + <row> + <entry><command>yum install <replaceable>pacote</replaceable></command> / <command>apt-get install <replaceable>pacote</replaceable></command></entry> + <entry><command>pkg_add -r <replaceable>pacote</replaceable></command></entry> + <entry>Instala o <replaceable>pacote</replaceable> a partir do repositório remoto</entry> + </row> + + <row> + <entry><command>rpm -ivh <replaceable>pacote</replaceable></command> / <command>dpkg -i <replaceable>pacote</replaceable></command></entry> + <entry><command>pkg_add -v <replaceable>pacote</replaceable></command></entry> + <entry>Instala um pacote</entry> + </row> + + <row> + <entry><command>rpm -qa</command> / <command>dpkg -l</command></entry> + <entry><command>pkg_info</command></entry> + <entry>Lista de pacotes instalados</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </sect2> + + <sect2 id="systemCommands"> + <title>Gerenciamento do Sistema</title> + + <para> + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Comando no &linux;</entry> + <entry>Equivalente no &os;</entry> + <entry>Propósito</entry> + </row> + </thead> + + <tbody> + <row> + <entry><command>lspci</command></entry> + <entry><command>pciconf</command></entry> + <entry>Lista de dispositivos PCI</entry> + </row> + + <row> + <entry><command>lsmod</command></entry> + <entry><command>kldstat</command></entry> + <entry>Lista de módulos do <literal>kernel</literal> + carregados</entry> + </row> + + <row> + <entry><command>modprobe</command></entry> + <entry><command>kldload</command> / <command>kldunload</command></entry> + <entry>Carrega/descarrega módulos do + <literal>kernel</literal></entry> + </row> + + <row> + <entry><command>strace</command></entry> + <entry><command>truss</command></entry> + <entry>Rastrear chamadas de sistema</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </sect2> + </sect1> + + <sect1 id="conclusion"> + <title>Conclusão</title> + + <para>Esperamos que este documento tenha fornecido para + você o suficiente para começar a utilizar o + &os;. Certifique-se de dar uma olhada no <ulink + url="&url.base;/doc/en_US.ISO8859-1/books/handbook/index.html"> + Handbook do &os;</ulink> para se aprofundar nos + tópicos abordados, assim como nos muitos + tópicos não mencionados neste documento.</para> + </sect1> +</article> diff --git a/pt_BR.ISO8859-1/articles/new-users/Makefile b/pt_BR.ISO8859-1/articles/new-users/Makefile new file mode 100644 index 0000000000..ac8c11d6d4 --- /dev/null +++ b/pt_BR.ISO8859-1/articles/new-users/Makefile @@ -0,0 +1,24 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: For People New to Both FreeBSD and Unix + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?=gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/new-users/article.sgml b/pt_BR.ISO8859-1/articles/new-users/article.sgml new file mode 100644 index 0000000000..61b33f002b --- /dev/null +++ b/pt_BR.ISO8859-1/articles/new-users/article.sgml @@ -0,0 +1,1225 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<article> + <articleinfo> + <title>Para os novatos em FreeBSD e &unix;</title> + + <authorgroup> + <author> + <firstname>Annelise</firstname> + + <surname>Anderson</surname> + + <affiliation> + <address><email>andrsn@andrsn.stanford.edu</email></address> + </affiliation> + </author> + </authorgroup> + + <pubdate>15 de agosto de 1997</pubdate> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.ibm; + &tm-attrib.microsoft; + &tm-attrib.netscape; + &tm-attrib.opengroup; + &tm-attrib.general; + </legalnotice> + + <abstract> + <para>Parabéns pela instalação do FreeBSD! + Esta introdução é para os novatos no + FreeBSD <emphasis>e</emphasis> no &unix;—, então + ela começa com o básico. Este artigo assume que + você está usando a versão 2.0.5, ou mais + atual, do &os; distribuído pela &os;.org, seu sistema, + por agora, tem um único usuário (você) e + você provavelmente está muito bem com o + DOS/&windows; ou &os2;.</para> + </abstract> + </articleinfo> + + <sect1 id="in-and-out"> + <title>Entrando e saindo do sistema</title> + + <para>Entre no sistema (quando você vê + <prompt>login:</prompt>) como o usuário que você + criou durante a instalação ou como + <username>root</username>. (Sua instalação do + FreeBSD já terá uma conta + <username>root</username>; que pode ir para qualquer lugar e + fazer qualquer coisa, incluindo remover arquivos essenciais, + então seja muito cuidadoso!) Os símbolos + &prompt.user; e &prompt.root; nos exemplos a seguir representam + o <literal>prompt</literal> (o seu pode ser diferente), com o + &prompt.user; indicando o <literal>prompt</literal> de um + usuário comum e o &prompt.root; indicando o + <literal>prompt</literal> do <username>root</username>.</para> + + <para>Para sair do sistema (e obter uma novo + <literal>prompt</literal> de <prompt>login:</prompt>) + escreva:</para> + + <informalexample> + <screen>&prompt.root; <userinput>exit</userinput></screen> + </informalexample> + + <para>quantas vezes forem necessárias. Você precisa + pressionar <keysym>enter</keysym> após os comandos, e + lembre-se que &unix; é sensível a letras + maiúsculas e minúsculas — + <command>exit</command> não é o mesmo que + <command>EXIT</command>.</para> + + <para>Para desligar a máquina escreva:</para> + + <informalexample> + <screen>&prompt.root; <userinput>/sbin/shutdown -h now</userinput></screen> + </informalexample> + + <para>Ou para reinicializar, escreva:</para> + + <informalexample> + <screen>&prompt.root; <userinput>/sbin/shutdown -r now</userinput></screen> + </informalexample> + + <para>ou</para> + + <informalexample> + <screen>&prompt.root; <userinput>/sbin/reboot</userinput></screen> + </informalexample> + + <para>Você também pode reiniciar com + <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. + Dê-lhe um pouco de tempo para trabalhar. Isso é o + equivalente ao <command>/sbin/reboot</command> nas + versões recentes do FreeBSD e é muito, muito + melhor do que pressionar o botão de + <literal>reset</literal>. Você não quer ter que + instalar tudo de novo, não é?</para> + </sect1> + + <sect1 id="adding-a-user"> + <title>Adicionando um Usuário com Privilégios de + Root</title> + + <para>Se você não criou nenhum usuário + durante a instalação do sistema e, portanto, + está logado como <username>root</username>, você + provavelmente precisa criar um usuário agora com:</para> + + <informalexample> + <screen>&prompt.root; <userinput>adduser</userinput></screen> + </informalexample> + + <para>Na primeira vez que você usar o + <command>adduser</command>, ele pode pedir por valores + padrões para salvar. Você pode querer definir o + <literal>shell</literal> padrão como &man.csh.1; ao + invés do &man.sh.1;, se ele sugerir o + <command>sh</command> como padrão. Do contrário, + apenas pressione <keysym>enter</keysym> para aceitar os valores + padrões. Os valores padrões serão + salvos em <filename>/etc/adduser.conf</filename>, o qual + pode ser editado.</para> + + <para>Suponha que você criou um usuário + <username>jack</username>, cujo nome completo seja + <emphasis>Jack Benimble</emphasis>. Dê a + <username>jack</username> uma senha se segurança (mesmo + crianças ao redor que possam por as mãos no + teclado) é um problema. Quando for questionado se + você deseja incluir <username>jack</username> em outros + grupos, escreva <groupname>wheel</groupname>:</para> + + <informalexample> + <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen> + </informalexample> + + <para>Isso tornará possível entrar no sistema como + <username>jack</username> e usar o comando &man.su.1; para + tornar-se <username>root</username>. Então você + não será mais repreendido por logar como + <username>root</username>.</para> + + <para>Você pode interromper o <command>adduser</command> + à qualquer momento apenas pressionando + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, e + no fim você poderá aprovar o novo usuário + ou simplesmente escrever <keycap>n</keycap> para não. + Você pode querer criar um segundo usuário para o + caso de algo sair errado na edição dos arquivos de + <literal>login</literal> do usuário + <username>jack</username>.</para> + + <para>Uma vez que você tenha concluído, use + <command>exit</command> para voltar ao <literal>prompt</literal> + de <literal>login</literal> e entrar como o usuário + <username>jack</username>. Em geral, é uma boa + idéia fazer tudo quanto for possível como um + usuário comum, que não tem o poder — e o + risco — do <username>root</username>.</para> + + <para>Se você já criou o usuário e quer que + ele tenha permissão de utilizar o <command>su</command> + para tornar-se <username>root</username>, você pode entrar + como <username>root</username> e editar o arquivo + <filename>/etc/group</filename>, adicionando + <username>jack</username> ao grupo presente na primeira + linha (o grupo <groupname>wheel</groupname>). Mas primeiro + você precisa praticar com &man.vi.1;, o editor de texto + instalado nas versões mais recentes do FreeBSD — ou + usar um editor de texto mais simples, como o &man.ee.1;.</para> + + <para>Para remover um usuário, use o comando + <command>rmuser</command>.</para> + </sect1> + + <sect1 id="looking-around"> + <title>Explorando</title> + + <para>Ao entrar como um usuário comum, explore e tente + alguns comandos que irão acessar as fontes de ajuda e + informação do FreeBSD.</para> + + <para>Aqui estão alguns comandos e o que eles fazem:</para> + + <variablelist> + <varlistentry> + <term><command>id</command></term> + + <listitem> + <para>Diz quem você é!</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>pwd</command></term> + + <listitem> + <para>Mostra onde você está — o + diretório corrente de trabalho</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ls</command></term> + + <listitem> + <para>Lista os arquivos no diretório corrente.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ls <option>-F</option></command></term> + + <listitem> + <para>Lista os arquivos no diretório corrente com um + <literal>*</literal> depois de arquivos + executáveis, um <literal>/</literal> depois de + diretórios, e um <literal>@</literal> depois de + <literal>links</literal> simbólicos.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ls <option>-l</option></command></term> + + <listitem> + <para>Lista os arquivos com detalhes — tamanho, data, + e permissões.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ls <option>-a</option></command></term> + + <listitem> + <para>Lista os arquivos ocultos, que iniciam com + <quote>ponto</quote>, com os outros. Se você + está como <username>root</username>, os arquivos + ocultos, que iniciam com <quote>ponto</quote>, são + mostrados sem a necessidade da opção + <option>-a</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>cd</command></term> + + <listitem> + <para>Muda o diretório corrente. <command>cd + <parameter>..</parameter></command> sobe um nível + com relação ao diretório atual; note + o espaço depois do <command>cd</command>. + <command>cd <parameter>/usr/local</parameter></command> + entra no diretório especificado. <command>cd + <parameter>~</parameter></command> entra no + diretório <literal>home</literal> do usuário + logado — e.g., <filename>/usr/home/jack</filename>. + Tente <command>cd <parameter>/cdrom</parameter></command>, + e execute <command>ls</command>, para descobrir se seu + CDROM está montado e funcionando.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>view + <replaceable>filename</replaceable></command></term> + + <listitem> + <para>Permite que você visualize um arquivo (chamado + <replaceable>filename</replaceable>) sem modificar + seu conteúdo. Tente <command>view + <parameter>/etc/fstab</parameter></command>. Escreva + <command>:q</command> para sair.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>cat + <replaceable>filename</replaceable></command></term> + + <listitem> + <para>Mostra o conteúdo de + <replaceable>filename</replaceable> na tela. Se ele + é muito longo e você só consegue ver o + final do arquivo, pressione <keycap>ScrollLock</keycap> e + use <keycap>up-arrow</keycap> para navegar até o + topo do arquivo; você pode usar + <keycap>ScrollLock</keycap> também com + páginas de manual. Pressione + <keycap>ScrollLock</keycap> novamente para interromper o + rolamento de conteúdo. Você pode querer + experimentar o <command>cat</command> em alguns arquivos + ocultos no seu diretório <literal>home</literal> + — <command>cat + <parameter>.cshrc</parameter></command>, <command>cat + <parameter>.login</parameter></command>, <command>cat + <parameter>.profile</parameter></command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Você vai encontrar <literal>aliases</literal> em seu + <filename>.cshrc</filename> para alguns comandos + <command>ls</command> (estes são muito convenientes). + Você pode criar outros <literal>aliases</literal> + editando <filename>.cshrc</filename>. Você pode criar + <literal>aliases</literal> disponíveis para todos os + usuários colocando-os no arquivo de + configuração principal do <command>csh</command> + o qual afeta todo o sistema, o + <filename>/etc/csh.cshrc</filename>.</para> + </sect1> + + <sect1 id="getting-help"> + <title>Obtendo Ajuda e Informação</title> + + <para>Aqui estão algumas fontes de ajuda úteis. + <replaceable>Text</replaceable> representa um termo de sua + escolha, para o qual você precisa de + informação ou ajuda — usualmente um comando + ou arquivo.</para> + + <variablelist> + <varlistentry> + <term><command>apropos + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Tudo que contiver o texto + <replaceable>text</replaceable> na <database>whatis + database</database>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>man + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Exibe a página de manual do + <replaceable>text</replaceable>. A maior fonte de + documentação para sistemas &unix;. + <command>man <parameter>ls</parameter></command> vai lhe + mostrar todos os detalhes de como usar o comando + <command>ls</command>. Pressione <keycap>Enter</keycap> + para navegar através do texto, + <keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo> + para voltar uma página, + <keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo> + para avançar uma página, + <keycap>q</keycap> ou + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> + para sair.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>which + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Informa onde, no <literal>path</literal> do + usuário, o comando <replaceable>text</replaceable> + é encontrado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>locate + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Informa todos os caminhos onde o termo + <replaceable>text</replaceable> é + encontrado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>whatis + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Informa o que o comando + <replaceable>text</replaceable> faz e qual sua + página de manual. Executar <command>whatis + *</command> vai lhe informar sobre todos os + binários no diretório corrente.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>whereis + <replaceable>text</replaceable></command></term> + + <listitem> + <para>Encontra o arquivo <replaceable>text</replaceable>, + informando seu caminho completo.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Você pode querer experimentar usar + <command>whatis</command> em alguns comandos comuns, como + <command>cat</command>, <command>more</command>, + <command>grep</command>, <command>mv</command>, + <command>find</command>, <command>tar</command>, + <command>chmod</command>, <command>chown</command>, + <command>date</command>, e <command>script</command>. + <command>more</command> permite que você leia uma + página de cada vez, do mesmo modo como no DOS, e.g., + <command>ls -l | more</command> ou <command>more + <replaceable>filename</replaceable></command>. O + <literal>*</literal> funciona como curinga — e.g., + <command>ls w*</command> vai mostrar os arquivos que + começam com <literal>w</literal>.</para> + + <para>Algum desses programas não está trabalhando + muito bem? Ambos, &man.locate.1; e &man.whatis.1;, dependem de + uma base de dados recompilada semanalmente. Se sua + máquina não vai permanecer ligada (e rodando o + &os;) durante o final de semana, convém executar + manualmente os comandos de manutenção + diários, semanais, e mensais de vez em quando. + Execute-os como <username>root</username> e, + por agora, dê a cada um deles um tempo para finalizar + antes de você iniciar o próximo.</para> + + <informalexample> + <screen>&prompt.root; <userinput>periodic daily</userinput> +<lineannotation>output omitted</lineannotation> +&prompt.root; <userinput>periodic weekly</userinput> +<lineannotation>output omitted</lineannotation> +&prompt.root; <userinput>periodic monthly</userinput> +<lineannotation>output omitted</lineannotation></screen> + </informalexample> + + <para>Se você cansar de esperar, pressione + <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> + para acessar outro <firstterm>virtual console</firstterm>, e + entre no sistema novamente. Afinal, ele é um sistema + multiusuário e multitarefa. No entanto, é + provável que esses comandos exibam mensagens na sua tela + enquanto eles estão rodando; você pode executar + <command>clear</command> em seu <literal>prompt</literal> para + limpar a tela. Uma vez que eles tenham executado, você + pode querer olhar em <filename>/var/mail/root</filename> e + <filename>/var/log/messages</filename>.</para> + + <para>Executar tais comandos é parte da + administração do sistema — e como o + único usuário do sistema &unix;, você + é seu próprio administrador de sistemas. + Praticamente tudo que você precisa fazer como + <username>root</username> será para + administração de sistemas. Tais responsabilidades + não são muito bem exploradas, mesmo nos grossos + livros sobre &unix;, que parecem dedicar um grande espaço + para opções de menus em gerenciadores de janelas. + Você pode querer obter um dos dois livros principais sobre + administração de sistemas, ou Evi Nemeth et.al.'s + <citetitle>UNIX System Administration Handbook</citetitle> + (Prentice-Hall, 1995, ISBN 0-13-15051-7) — a segunda + edição da capa vermelha; ou Æleen Frisch's + <citetitle>Essential System Administration</citetitle> (O'Reilly + & Associates, 2002, ISBN 0-596-00343-9). Eu uso + Nemeth.</para> + </sect1> + + <sect1 id="editing-text"> + <title>Editando Texto</title> + + <para>Para configurar seu sistema, você precisará + editar arquivos de texto. Muitos deles estarão no + diretório <filename>/etc</filename>; e você + precisará do <command>su</command> para tornar-se + <username>root</username> e poder modificá-los. + Você pode utilizar o <command>ee</command>, por ser + fácil de usar, mas à longo prazo vale a pena + aprender o editor de texto <command>vi</command>. Um excelente + tutorial sobre o <command>vi</command> pode ser encontrado em + <filename>/usr/src/contrib/nvi/docs/tutorial</filename>, se + você tiver os fontes do sistema instalado.</para> + + <para>Antes de editar um arquivo, você provavelmente + deveria fazer um backup dele. Suponha que você queira + editar o <filename>/etc/rc.conf</filename>. Você pode + simplesmente usar <command>cd /etc</command> para ir até + o diretório <filename>/etc</filename> e fazer:</para> + + <informalexample> + <screen>&prompt.root; <userinput>cp rc.conf rc.conf.orig</userinput></screen> + </informalexample> + + <para>Isso vai copiar o <filename>rc.conf</filename> para + <filename>rc.conf.orig</filename>, e depois você + poderá copiar o <filename>rc.conf.orig</filename> para + <filename>rc.conf</filename> para recuperar o original. Mas o + melhor mesmo seria mover (renomear) e copiar novamente:</para> + + <informalexample> + <screen>&prompt.root; <userinput>mv rc.conf rc.conf.orig</userinput> +&prompt.root; <userinput>cp rc.conf.orig rc.conf</userinput></screen> + </informalexample> + + <para>pelo fato do comando <command>mv</command> preservar a data + e o dono originais do arquivo. Você pode agora editar o + <filename>rc.conf</filename>. Se você quiser o original + de volta, você faria <userinput>mv rc.conf + rc.conf.myedit</userinput> (assumindo que você queira + preservar a versão modificada) e então:</para> + + <informalexample> + <screen>&prompt.root; <userinput>mv rc.conf.orig rc.conf</userinput></screen> + </informalexample> + + <para>para voltar as coisas do jeito que estavam.</para> + + <para>Para editar um arquivo, faça:</para> + + <informalexample> + <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput></screen> + </informalexample> + + <para>Mova-se através do texto com as setas do teclado. + <keycap>Esc</keycap> (a tecla de escape) coloca o + <command>vi</command> em modo de comando. Aqui estão + alguns comandos:</para> + + <variablelist> + <varlistentry> + <term><command>x</command></term> + + <listitem> + <para>Remove o caractere onde está o cursor</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dd</command></term> + + <listitem> + <para>remove a linha inteira (mesmo que ela quebre na + tela)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>i</command></term> + + <listitem> + <para>para inserir texto a partir do cursor</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>a</command></term> + + <listitem> + <para>para inserir texto após o cursor</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Uma vez que você digite <command>i</command> ou + <command>a</command>, você pode inserir o texto. + <command>Esc</command> coloca você de volta no modo de + comando</para> + + <variablelist> + <varlistentry> + <term><command>:w</command></term> + + <listitem> + <para>para salvar suas modificações no disco + e continuar editando</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>:wq</command></term> + + <listitem> + <para>para salvar as modificações e + sair</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>:q!</command></term> + + <listitem> + <para>para sair sem salvar as + modificações</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>/<replaceable>text</replaceable></command></term> + + <listitem> + <para>para mover o curso para + <replaceable>text</replaceable>; + <command>/<keycap>Enter</keycap></command> (a tecla enter) + para encontrar a próxima ocorrência de + <replaceable>text</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>G</command></term> + + <listitem> + <para>vai para o final do arquivo</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command><replaceable>n</replaceable>G</command></term> + + <listitem> + <para> vai para a linha <replaceable>n</replaceable> no + arquivo, onde <replaceable>n</replaceable> é o + número.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo></term> + + <listitem> + <para>para redesenhar a tela</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> e + <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo></term> + + <listitem> + <para>volta e avança na tela, respectivamente, assim + como fazem no <command>more</command> e + <command>view</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Pratique com o <command>vi</command> em seu diretório + <literal>home</literal>, criando um novo arquivo com <command>vi + <replaceable>filename</replaceable></command>, adicionando e + removendo texto, salvando o arquivo, e chamando-o de novo. + <command>vi</command> oferece muitas surpresas, pois ele + é realmente bastante complexo, e algumas vezes você + vai inadvertidamente executar um comando que vai fazer alguma + coisa que você não espera. (Algumas pessoas + realmente gostam do <command>vi</command> — ele é + mais poderoso que o DOS EDIT — procure sobre o comando + <command>:r</command>.) Use <keycap>Esc</keycap> uma ou mais + vezes para estar seguro de que você está no modo de + comando e continuar a partir daí se você tiver + problemas, salve frequentemente com <command>:w</command>, e use + <command>:q!</command> para sair e começar novamente (a + partir do seu último <command>:w</command>) quando + você precisar.</para> + + <para>Agora você pode entrar no diretório + <filename>/etc</filename> com o <command>cd</command>, usar o + <command>su</command> para tornar-se <username>root</username>, + usar o <command>vi</command> para editar o arquivo + <filename>/etc/group</filename>, e adicionar um usuário + no grupo <groupname>wheel</groupname> para que ele tenha + privilégios de <username>root</username>. Só + adicione uma vírgula e o <literal>login</literal> do + usuário no fim da primeira linha do arquivo, pressione + <keycap>Esc</keycap>, e use <command>:wq</command> para escrever + suas alterações no disco e sair. Efeito + instantâneo. (Você não colocou um + espaço depois da vírgula, colocou?)</para> + </sect1> + + <sect1 id="printing-files-from-dos"> + <title>Imprimindo Arquivos no DOS</title> + + <para>Neste ponto você provavelmente não tem uma + impressora funcionando, então aqui vai uma maneira de + criar um arquivo a partir de uma página de manual, + movê-lo para um disquete, e então imprimi-lo do + DOS. Suponhamos que você queira ler cuidadosamente sobre + mudança de permissões em arquivos (muito + importante). Você pode usar <command>man chmod</command> + para ler a respeito. O comando</para> + + <informalexample> + <screen>&prompt.user; <userinput>man chmod | col -b > chmod.txt</userinput></screen> + </informalexample> + + <para>irá remover códigos de + formatação e enviar a página de manual para + o arquivo <filename>chmod.txt</filename> em vez de + mostrá-lo na tela. Agora coloque um disquete formatado + no DOS em seu drive de disquete <devicename>a</devicename>, use + o <command>su</command> para tornar-se + <username>root</username>, e escreva</para> + + <informalexample> + <screen>&prompt.root; <userinput>/sbin/mount -t msdosfs /dev/fd0 /mnt</userinput></screen> + </informalexample> + + <para>para montar o drive de disquete em + <filename>/mnt</filename>.</para> + + <para>Agora (você não precisa mais estar como + <username>root</username>, e você pode executar + <command>exit</command> para voltar para o usuário + inicial <username>jack</username>) você pode ir até + o diretório onde você criou o + <filename>chmod.txt</filename> e copiar o arquivo para o + disquete com:</para> + + <informalexample> + <screen>&prompt.user; <userinput>cp chmod.txt /mnt</userinput></screen> + </informalexample> + + <para>e usar <command>ls /mnt</command> para obter a listagem do + diretório <filename>/mnt</filename>, que deveria mostrar + o arquivo <filename>chmod.txt</filename>.</para> + + <para>Você pode querer criar um arquivo a partir do + <filename>/sbin/dmesg</filename> executando:</para> + + <informalexample> + <screen>&prompt.user; <userinput>/sbin/dmesg > dmesg.txt</userinput></screen> + </informalexample> + + <para>e copiar o <filename>dmesg.txt</filename> para o disquete. + <command>/sbin/dmesg</command> é o registro das + mensagens de <literal>boot</literal>, e ele é útil + para entender o que o FreeBSD encontra durante a + inicialização. Se você enviar perguntas + para a &a.questions; ou para o grupo da USENET — como + <quote>O FreeBSD não encontra a minha unidade de fita, o + que eu faço?</quote> — as pessoas vão querer + saber o que o <command>dmesg</command> diz.</para> + + <para>Você pode desmontar o drive de disquete agora (como + <username>root</username>) para retirá-lo com:</para> + + <informalexample> + <screen>&prompt.root; <userinput>/sbin/umount /mnt</userinput></screen> + </informalexample> + + <para>e reiniciar para ir para o DOS. Copie os arquivos para um + diretório do DOS, chame-os com o DOS EDIT, &windows; + Notepad ou Wordpad, ou algum outro processador de texto, + faça uma pequena alteração para o arquivo + ser salvo, e imprima como você normalmente faz a partir do + DOS ou Windows. Espero que funcione! Páginas de manual + saem melhor se impressas com o comando <command>print</command> + do DOS. (Copiar arquivos do FreeBSD para uma + partição DOS montada ainda é, em alguns + casos, um pouco arriscado.)</para> + + <para>Obter uma impressora imprimindo do FreeBSD envolve criar uma + entrada apropriada em <filename>/etc/printcap</filename> e criar + um diretório de <literal>spool</literal> correspondente + em <filename>/var/spool/output</filename>. Se sua impressora + está na <hardware>lpt0</hardware> (nos DOS é + chamada de <hardware>LPT1</hardware>), você só + precisa ir para <filename>/var/spool/output</filename> e (como + <username>root</username>) criar o diretório + <filename>lpd</filename> executando: <command>mkdir + lpd</command>, se ele ainda não existe. Em seguida, a + impressora deve responder se ela estiver ligada durante a + inicialização, e <command>lp</command> ou + <command>lpr</command> deve enviar um arquivo para a impressora. + Se o arquivo vai ser impresso ou não, depende da + configuração, esta é coberta no <ulink + url="&url.books.handbook;/index.html">FreeBSD + handbook.</ulink></para> + </sect1> + + <sect1 id="other-useful-commands"> + <title>Outros comando úteis</title> + + <variablelist> + <varlistentry> + <term><command>df</command></term> + + <listitem> + <para>mostra os dispositivos montados e o espaço em + disco.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ps aux</command></term> + + <listitem> + <para>mostra os processos rodando. <command>ps ax</command> + exibe uma lista compacta.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>rm <replaceable>filename</replaceable></command></term> + + <listitem> + <para>exclui o arquivo + <replaceable>filename</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>rm -R <replaceable>dir</replaceable></command></term> + + <listitem> + <para>remove o diretório + <replaceable>dir</replaceable> e todos os seus + subdiretórios — seja cuidadoso!</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ls -R</command></term> + + <listitem> + <para>lista os arquivos no diretório corrente e + todos os subdiretórios; eu usei uma variante, + <command>ls -AFR > where.txt</command>, para obter uma + lista de todos os arquivos de <filename>/</filename> e + (separadamente) <filename>/usr</filename>, antes de + descobrir um jeito melhor de encontrar arquivos.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>passwd</command></term> + + <listitem> + <para>para mudar a senha do usuário (ou a senha do + <username>root</username>)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>man hier</command></term> + + <listitem> + <para>exibe a página de manual sobre o sistema de + arquivos do &unix;</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Use <command>find</command> para localizar + <filename>filename</filename> em <filename>/usr</filename>, ou + qualquer de seus subdiretórios, com</para> + + <informalexample> + <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</replaceable>"</userinput></screen> + </informalexample> + + <para>Você pode usar <literal>*</literal> como curinga em + <parameter>"<replaceable>filename</replaceable>"</parameter> + (que deve estar entre aspas). Se você diz para + <command>find</command> procurar em <filename>/</filename>, em + vez de <filename>/usr</filename>, ele vai procurar o arquivo em + todos os dispositivos montados, incluindo CDROM e as + partições DOS.</para> + + <para>Um excelente livro que explica os comandos e + utilitários &unix; é Abrahams & Larson, + <citetitle>Unix for the Impatient</citetitle> (2nd ed., + Addison-Wesley, 1996). Existe também uma grande + quantidade de informações sobre &unix; na + Internet.</para> + </sect1> + + <sect1 id="next-steps"> + <title>Próximos Passos</title> + + <para>Agora você deve ter as ferramentas que você + precisa para explorar e editar arquivos, então você + pode ter tudo ligado e funcionando. Existe uma grande + quantidade de informações no FreeBSD handbook (que + provavelmente está em seu disco rígido) e no + <ulink url="&url.base;/index.html">web site do FreeBSD</ulink>. + Uma grande variedade de pacotes e <literal>ports</literal> + estáo disponível no CDROM, bem como no site web. + O handbook diz mais sobre como usá-los (obter um pacote, + se ele existir, com <command>pkg_add + /cdrom/packages/All/<replaceable>nomepacote</replaceable></command>, + onde <replaceable>nomepacote</replaceable> é o nome do + pacote). O CDROM tem uma lista dos pacotes e + <literal>ports</literal> com uma breve descrição + em <filename>cdrom/packages/index</filename>, + <filename>cdrom/packages/index.txt</filename>, e + <filename>cdrom/ports/index</filename>, com as + descrições completas em + <filename>/cdrom/ports/*/*/pkg/DESCR</filename>, onde os + <literal>*</literal> representam subdiretórios das + categorias e dos nomes dos programas, respectivamente.</para> + + <para>Se você achar o handbook muito sofisticado (com + <command>lndir</command> e tudo) sobre a + instalação de <literal>ports</literal> a partir do + CDROM, aqui está o que normalmente funciona:</para> + + <para>Encontre o <literal>port</literal> que você quer, + digamos que seja o <command>kermit</command>. Haverá um + diretório para ele no CDROM. Copie o subdiretório + para <filename>/usr/local</filename> (um bom lugar para + adicionar programas que estarão disponíveis para + todos os usuários) com:</para> + + <informalexample> + <screen>&prompt.root; <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</userinput></screen> + </informalexample> + + <para>Isso deve resultar em um subdiretório + <filename>/usr/local/kermit</filename> onde estarão + todos os arquivos do subdiretório + <command>kermit</command> do CDROM.</para> + + <para>Em seguida, crie o diretório + <filename>/usr/ports/distfiles</filename>, se ele ainda + não existe, usando <command>mkdir</command>. Agora + verifique em <filename>/cdrom/ports/distfiles</filename> por um + arquivo com o nome que indique o <literal>port</literal> que + você quer. Copie o arquivo para + <filename>/usr/ports/distfiles</filename>; nas versões + recentes você pode pular este passo, o FreeBSD vai fazer + isso por você. No caso do <command>kermit</command> + não existe <literal>distfile</literal>.</para> + + <para>Vá até o subdiretório + <filename>/usr/local/kermit</filename>, onde estará o + arquivo <filename>Makefile</filename>. E execute</para> + + <informalexample> + <screen>&prompt.root; <userinput>make all install</userinput></screen> + </informalexample> + + <para>Durante este processo o <literal>port</literal> vai obter + a partir do FTP quaisquer arquivos compactados que sejam + necessários e não estejam presentes no CDROM ou em + <filename>/usr/ports/distfiles</filename>. Se sua rede ainda + não está funcionando e não existe arquivo + para o <literal>port</literal> em + <filename>/cdrom/ports/distfiles</filename>, você vai + precisar obter este arquivo de outra máquina e + copiá-lo para <filename>/usr/ports/distfiles</filename> + de um disquete ou de sua partição DOS. Leia o + <filename>Makefile</filename> (com o <command>cat</command>, ou + <command>more</command>, ou <command>view</command>) para + descobrir aonde ir (o site de distribuição + principal) para obter o arquivo e qual o seu nome. O nome do + arquivo será truncado se ele for obtido a partir do DOS, + e depois de colocá-lo em + <filename>/usr/ports/distfiles</filename> você precisa + renomear o arquivo (com o comando <command>mv</command>) para + seu nome original para que ele possa ser encontrado. (Use o + modo de transferência binária!) Então volte + para <filename>/usr/local/kermit</filename>, encontre o + diretório com o <filename>Makefile</filename>, e execute + <command>make all install</command>.</para> + + <para>Outra coisa que pode acontecer quando da + instalação de um <literal>port</literal> ou pacote + é que algum outro programa seja necessário. Se a + instalação parar com uma mensagem <errorname>can't + find unzip</errorname> ou algo parecido, você pode + precisar instalar o pacote ou <literal>port</literal> do unzip + antes de continuar.</para> + + <para>Uma vez instalado, execute <command>rehash</command> para + fazer o FreeBSD reler os arquivos no <literal>path</literal>, + então ele saberá o que existe lá. (Se + você obter uma série de mensagens <errorname>path + not found</errorname> quando usar <command>whereis</command> ou + <command>which</command>, você pode querer adicionar + entradas para a lista de diretórios na + declaração do <literal>path</literal> no + <filename>.cshrc</filename> em seu diretório + <literal>home</literal>. A declaração do + <literal>path</literal> no &unix; funciona do mesmo modo que no + DOS, exceto pelo diretório corrente que não + é (por padrão) incluído no + <literal>path</literal> por razões de segurança; + você precisa digitar <filename>./</filename> antes do + comando para executa-lo; sem espaços depois da + barra.</para> + + <para>Você pode querer obter a versão mais recente + do &netscape; a partir de seu <ulink + url="ftp://ftp.netscape.com/">site FTP</ulink>. (O &netscape; + requer o <literal>X Window System</literal>.) Agora existe uma + versão para o &os;, então explore com + cuidado. Basta usar o <command>gunzip + <replaceable>filename</replaceable></command> e <command>tar xvf + <replaceable>filename</replaceable></command> no arquivo, mover + o binário para <filename>/usr/local/bin</filename> ou + algum outro lugar onde os binários são mantidos, + execute <command>rehash</command>, e então coloque as + seguintes linhas no <filename>.cshrc</filename> de cada + diretório <literal>home</literal> dos usuários ou + (mais fácil) em <filename>/etc/csh.cshrc</filename>, o + arquivo de configuração principal de + inicialização do <command>csh</command>:</para> + + <informalexample> + <programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB +setenv XNLSPATH /usr/X11R6/lib/X11/nls</programlisting> + </informalexample> + + <para>Isso assume que o arquivo <filename>XKeysymDB</filename> e o + diretório <filename>nls</filename> estão em + <filename>/usr/X11R6/lib/X11</filename>; se eles não + estiverem, encontre-os e coloque-os lá.</para> + + <para>Se você instalou o &netscape; originalmente a partir + de um <literal>port</literal> usando o CDROM (ou o site FTP), + não substitua o + <filename>/usr/local/bin/netscape</filename> com o novo + binário do &netscape;; isso é só um + <literal>shell script</literal> que define as variáveis + de ambiente para você. Em vez disso, renomeie o novo + binário para <filename>netscape.bin</filename> + e mova o binário antigo + para <filename>/usr/local/netscape/netscape</filename>.</para> + </sect1> + + <sect1 id="your-working-environment"> + <title>Seu Ambiente de Trabalho</title> + + <para>Seu <literal>shell</literal> é uma parte muito + importante do seu ambiente de trabalho. No DOS, o + <literal>shell</literal> usual é o + <literal>command.com</literal>. O <literal>shell</literal> + é quem interpreta os comandos que você executa na + linha de comando, e, portanto, se comunica com o resto do + sistema operacional. Você também pode escrever + <literal>shell scripts</literal>, que são como arquivos + de lotes do DOS: uma série de comando para serem + executados sem sua intervenção.</para> + + <para>O FreeBSD vem com dois <literal>shells</literal> instalados: + <command>csh</command> e <command>sh</command>. + <command>csh</command> é bom para trabalhar com a linha + de comando, mas <literal>scripts</literal> devem ser escritos + com <command>sh</command> (ou <command>bash</command>). + Você pode descobrir qual <literal>shell</literal> + você está utilizando executando <command>echo + $SHELL</command>.</para> + + <para>O <literal>shell</literal> <command>csh</command> é + bom, mas <command>tcsh</command> faz tudo que o + <command>csh</command> faz e mais. Ele aceita que você + chame novamente os comandos, com as setas do teclado, e + edite-os. Ele completa nomes de arquivos através da + tecla TAB (<command>csh</command> usa a tecla + <keycap>Esc</keycap>), e ele permite que você mude para + seu último diretório com <command>cd -</command>. + É muito fácil alternar seu + <literal>prompt</literal> com <command>tcsh</command>. Ele + torna sua vida muito fácil.</para> + + <para>Aqui estão os passos para a instalação + de um novo <literal>shell</literal>:</para> + + <procedure> + <step> + <para>Instale o <literal>shell</literal> a partir de um + <literal>port</literal> ou pacote, como você faria + para qualquer outro <literal>port</literal> ou pacote. Use + <command>rehash</command> e <command>which tcsh</command> + (assumindo que você instalou o + <command>tcsh</command>) para ter certeza que ele foi + instalado.</para> + </step> + + <step> + <para>Como <username>root</username>, edite o + <filename>/etc/shells</filename>, adicionando uma linha no + arquivo para o novo <literal>shell</literal>, nesse caso + <filename>/usr/local/bin/tcsh</filename>, e salve o arquivo. + (Alguns <literal>ports</literal> vão fazer isso por + você.)</para> + </step> + + <step> + <para>Use o comando <command>chsh</command> para mudar seu + <literal>shell</literal> para o <command>tcsh</command> + permanentemente, ou execute <command>tcsh</command> no + <literal>prompt</literal> para mudar seu + <literal>shell</literal> sem precisar realizar o + <literal>login</literal> novamente.</para> + </step> + </procedure> + + <note> + <para>Pode ser perigoso mudar o <literal>shell</literal> do + <username>root</username> para qualquer coisa diferente de + <command>sh</command> ou <command>csh</command> nas + versões anteriores do FreeBSD e em muitas outras + versões do &unix;; você pode não ter um + <literal>shell</literal> funcional quando o sistema colocar + você em modo monousuário. A + solução é usar + <command>su -m</command> para tornar-se + <username>root</username>, o que lhe dará o + <command>tcsh</command> como <username>root</username>, pois + o <literal>shell</literal> é parte do seu ambiente. + Você pode tornar isso permanente adicionando para seu + arquivo <filename>.tcshrc</filename> um + <literal>alias</literal> com:</para> + <programlisting>alias su su -m</programlisting> + </note> + + <para>Quando <command>tcsh</command> inicia, ele lê os + arquivos <filename>/etc/csh.cshrc</filename> e + <filename>/etc/csh.login</filename>, assim como o + <command>csh</command>. Ele também irá ler o + arquivo <filename>.login</filename> em seu diretório + <literal>home</literal> e o arquivo <filename>.cshrc</filename>, + a menos que você providencie um arquivo + <filename>.tcshrc</filename>. Para isso você pode + simplesmente copiar o <filename>.cshrc</filename> para + <filename>.tcshrc</filename>.</para> + + <para>Agora que você já instalou o + <command>tcsh</command>, você pode ajustar o seu + <literal>prompt</literal>. Você encontra os detalhes na + página de manual do <command>tcsh</command>, mas aqui + está uma linha para você incluir em seu + <filename>.tcshrc</filename> que vai lhe dizer quantos comandos + você digitou, que horas são, e em que + diretório você se encontra. Ele também + mostra um <literal>></literal> se você está como um + usuário comum e um <literal>#</literal> se você + está como <username>root</username>, mas + <command>tcsh</command> vai fazer isso em qualquer caso:</para> + + <para>set prompt = "%h %t %~ %# "</para> + + <para>Isso deve ser incluído no mesmo lugar do <literal>set + prompt</literal> existente, ou sob <literal>"if($?prompt) + then"</literal> se este não existir. Comente a linha + antiga; você poderá voltar para o + <literal>prompt</literal> antigo se preferir. Não + esqueça o espaço e as aspas. Você pode + recarregar o <filename>.tcshrc</filename> executando + <command>source .tcshrc</command>.</para> + + <para>Você pode obter uma lista de outras variáveis + de ambiente que foram definidas executando + <command>env</command> no <literal>prompt</literal>. O + resultado vai lhe mostrar seu editor padrão, paginador, e + o tipo de terminal, e possivelmente muitos outros. Um comando + útil se você está logado remotamente e + não pode executar um programa, pois o terminal não + é compatível, é <command>setenv TERM + vt100</command>.</para> + </sect1> + + <sect1 id="other"> + <title>Outros</title> + + <para>Como <username>root</username> você pode desmontar + o CDROM com <command>/sbin/umount /cdrom</command>, + retirá-lo do <literal>drive</literal>, inserir outro, + e montá-lo com<command>/sbin/mount_cd9660 /dev/cd0a + /cdrom</command>,assumindo que <hardware>cd0a</hardware> + é o nome do seu dispositivo de CDROM. As versões + mais recentes do FreeBSD deixam você montar o CDROM apenas + com <command>/sbin/mount /cdrom</command>.</para> + + <para>Usar o sistema de arquivos <literal>live</literal> — + o segundo dos discos de CDROM do FreeBSD — é + útil se você tem um espaço limitado. O + conteúdo do sistema de arquivos <literal>live</literal> + varia de versão para versão. Você pode + tentar jogar a partir do CDROM. Isso envolve o uso do + <command>lndir</command>, que é instalado com o + <literal>X Window System</literal>, para informar aos programas + onde encontrar os arquivos necessários, pois eles + estão no sistema de arquivos de + <filename>/cdrom</filename>, em vez de <filename>/usr</filename> + e seus subdiretórios, que é o local onde eles + esperam estar. Consulte <command>man lndir</command>.</para> + </sect1> + + <sect1 id="comments-welcome"> + <title>Comentários São Bem-vindos</title> + + <para>Se você usou este guia, eu estou interessado em + saber onde ele não está claro, o que foi deixado + de fora que você acha que deve ser incluído, e se + ele foi útil. Meus agradecimentos para Eugene W. Stark, + professor de ciência da computação em + SUNY-Stony Brook, e John Fieber pelos comentários + úteis.</para> + + <para>Annelise Anderson, + <email>andrsn@andrsn.stanford.edu</email></para> + </sect1> +</article> diff --git a/pt_BR.ISO8859-1/articles/problem-reports/Makefile b/pt_BR.ISO8859-1/articles/problem-reports/Makefile new file mode 100644 index 0000000000..a63b4aca1a --- /dev/null +++ b/pt_BR.ISO8859-1/articles/problem-reports/Makefile @@ -0,0 +1,24 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: Writing FreeBSD Problem Reports + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?=gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/articles/problem-reports/article.sgml b/pt_BR.ISO8859-1/articles/problem-reports/article.sgml new file mode 100644 index 0000000000..23895124cb --- /dev/null +++ b/pt_BR.ISO8859-1/articles/problem-reports/article.sgml @@ -0,0 +1,1650 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +]> + +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r39487 +--> + +<article> + <articleinfo> + <title>Escrevendo Relatórios de Problema no &os;</title> + + <pubdate>$FreeBSD$</pubdate> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.cvsup; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.sun; + &tm-attrib.general; + </legalnotice> + + <abstract> + <para>Este artigo descreve qual a melhor forma de formular e + de submeter um relatório de problema para Projeto + &os;.</para> + </abstract> + + <authorgroup> + <author> + <firstname>Dag-Erling</firstname> + <surname>Smørgrav</surname> + <contrib>Contribuido por</contrib> + </author> + + <author> + <firstname>Mark</firstname> + <surname>Linimon</surname> + </author> + </authorgroup> + </articleinfo> + + <indexterm><primary>relatório de problema</primary> + </indexterm> + + <section id="pr-intro"> + <title>Introdução</title> + + <para>Uma das experiências mais frustrantes que + alguém pode ter como um usuário de um software + é submeter um relatório sobre um problema + que está enfrentando apenas para vê-lo ser + sumariamente fechado com uma informação curta + e pouco útil do tipo <quote>isto não é + um bug</quote> ou ainda <quote>este relatório de + problema não procede</quote>. Da mesma forma, uma das + experiências mais frustrantes para um desenvolvedor de + software é ser inundado com relatórios de + problemas que na verdade não são realmente + relatórios de problemas, mas sim + solicitações de suporte, ou então que + contenham pouca ou nenhuma informação sobre como + o problema ocorre e sobre como proceder para + reproduzi-lo.</para> + + <para>Este documento tem por objetivo descrever como escrever + bons relatórios de problema. Mas o que vem a ser um + bom relatório de problema? Bem, indo direto ao ponto, + um bom relatório de problema é aquele que se + pode analisar e tratar rapidamente, para a + satisfação mútua do usuário e do + desenvolvedor.</para> + + <para>Embora o foco primário deste artigo seja a + elaboração de relatórios de problemas no + &os;, a maior parte das recomendações deve + aplicar-se muito bem a outros projetos de software.</para> + + <para>Observe que este artigo esta organizado de forma + temática, e não de forma cronológica, + desta forma você deve ler o documento inteiro antes + de enviar um relatório de problema, ao invés + de tratá-lo como um tutorial passo-a-passo.</para> + </section> + + <section id="pr-when"> + <title>Quando enviar um relatório de problema</title> + + <para>Existem muitos tipos de problemas, e nem todos eles devem + gerar um relatório de problema. É claro, + ninguém é perfeito e em algumas ocasiões + você terá certeza de que encontrou um bug em um + determinado software quando na verdade você compreendeu + errado a sintaxe de um comando ou mesmo cometeu um erro de + digitação em um arquivo de + configuração (o que por sua vez pode indicar + uma documentação pouco detalhada ou + então um tratamento inadequado do erro por parte + da aplicação). Existem ainda muitas outras + situações nas quais enviar um relatório de + problema claramente <emphasis>não</emphasis> é + a melhor ação a ser tomada, e só vai + servir para frustrar a você e aos desenvolvedores. Em + contrapartida, existem situações nas quais + é recomendado que você nos envie um + relatório de problema sobre outras coisas que + não um bug, como por exemplo para nos enviar uma + sugestão de melhoria ou um pedido de uma nova + funcionalidade.</para> + + <para>Então como você irá diferenciar o que + é e o que não é um bug? Existe uma regra + de ouro que diz que o seu problema <emphasis>não + é</emphasis> um bug se ele pode ser expresso como uma + pergunta (normalmente na forma <quote>Como eu faço + X</quote> ou <quote>Onde eu posso encontrar Y</quote>). Na + maior parte das vezes não será sempre + tão claro desta forma, mas a regra acima cobre a grande + maioria dos casos. Se você estiver procurando por uma + resposta, considere enviar a sua pergunta para + &a.questions;.</para> + + <para>Veja alguns casos nos quais pode ser apropriado enviar um + relatório de problema sobre algo que não é + um bug:</para> + + <itemizedlist> + <listitem> + <para>Pedidos de melhorias nas funcionalidades. Geralmente + é uma boa idéia debater estas propostas nas + listas de discussão antes de enviá-las em um + relatório de problemas.</para> + </listitem> + + <listitem> + <para>Notificações sobre + atualizações de softwares mantidos + externamente (principalmente do ports, mas também + de componentes do sistema base como, por exemplo, o BIND e + vários outros utilitários GNU).</para> + + <para>Para os ports sem manutenção + (aqueles nos quais a variável + <makevar>MAINTAINER</makevar> contém + <literal>ports@FreeBSD.org</literal>), essas + notificações de atualização + podem ser capturadas por um <literal>committer</literal> + interessado, ou você pode ser solicitado a fornecer + um <literal>patch</literal> para atualizar o port; + disponibilizar este <literal>patch</literal> antecipadamente + irá melhorar de forma significativa as suas chances + de ter o port atualizado rapidamente.</para> + + <para>Se o port possui um mantenedor, o envio de um + relatório de problema comunicando sobre o + lançamento de uma nova versão geralmente + não é muito útil uma vez que eles geram + trabalho adicional para os <literal>committers</literal>, + e o mantenedor provavelmente já tem conhecimento de + que existe uma nova versão, ele provavelmente + já trabalhou com os desenvolvedores para + atualizá-lo e está provavelmente executando + testes para verificar se não existem problemas, + etc.</para> + + <para>Em ambos os casos, você irá obter melhores + resultados se seguir o processo descrito no <ulink + url="&url.books.porters-handbook;/port-upgrading.html">Porter's Handbook</ulink>. + (Talvez você também queira ler o artigo <ulink + url="&url.articles.contributing-ports;/article.html"> + Contribuindo para a Coleção de Ports + do &os;</ulink>.)</para> + </listitem> + </itemizedlist> + + <para>Um bug que não pode ser reproduzido, raramente + será corrigido. Se o bug ocorreu uma única + vez e você não consegue reproduzi-lo, e + se aparentemente ele não ocorre com mais ninguém, + as chances são de que nenhum dos desenvolvedores + será capaz de reproduzir ou de saber o que está + errado. Isso não significa que não seja + possível, mas significa que a probabilidade do seu + relatório de problema resultar na correção + do bug é muito pequena. Para piorar a + situação, muitas vezes este tipo de erro + é, na realidade, causado por falhas nos discos + rígidos ou por superaquecimento do processador — + sempre que possível você deve tentar excluir estas + causas antes de enviar um relatório de problema.</para> + + <para>Em seguida, para decidir a quem você deve apresentar + o seu relatório de problema, você precisa + entender que o &os; é composto de vários + elementos de software diferentes:</para> + + <itemizedlist> + <listitem> + <para>Código na base do sistema que é escrito + e mantido por colaboradores do &os;, tais como o Kernel, a + biblioteca C, os drivers de dispositivos (categorizados + como <literal>kern</literal>); os utilitários + binários (<literal>bin</literal>); as páginas + de manual e a documentação + (<literal>docs</literal>); e as páginas web + (<literal>www</literal>). Todos os bugs nestas + áreas devem ser reportados para os desenvolvedores + do &os;</para> + </listitem> + + <listitem> + <para>Código na base do sistema que é escrito + e mantido por outros, e que foram adaptados e importados + no &os;. Exemplos incluen <application>bind</application>, + &man.gcc.1;, e &man.sendmail.8;. A maioria dos bugs nestas + áreas devem ser reportados para os desenvolvedores do + &os;; mas em alguns casos pode ser necessário + reportá-los aos autores originais, caso o problema + não seja especifico do &os;. Normalmente estes bugs + irão ficar sob as categorias <literal>bin</literal> + ou <literal>gnu</literal>.</para> + </listitem> + + <listitem> + <para>Os aplicativos individuais que não estão + na base do sistema, mas que fazem parte da + coleção de Ports do &os; (Categoria + <literal>ports</literal>). A maioria destes aplicativos + não são escritos por desenvolvedores do + &os;; o que o &os; oferece é apenas um sistema para + facilitar a instalação do aplicativo. + Portanto, você deve relatar um problema para os + desenvolvedores do &os; apenas quando você acreditar + que o problema é específico do &os;, caso + contrário, você deve reportá-lo aos + autores do software.</para> + </listitem> + + </itemizedlist> + + <para>A seguir você deve verificar se o problema é + ou não atual. Existem poucas coisas que aborrecem um + desenvolvedor mais do que receber um relatório de + problema a respeito de um bug que ele já corrigiu.</para> + + <para>Se o problema está na base do sistema, você + deverá primeiro ler a seção do FAQ sobre + <ulink url="&url.books.faq;/introduction.html#LATEST-VERSION"> + Versões do &os;</ulink>, se você não estiver + familiarizado com o tema. Não é possível + para o &os; corrigir problemas em versões muito antigas + do sistema base, desta forma enviar um relatório de + problema sobre um bug em uma versão muito antiga vai + provavelmente resultar apenas em um desenvolvedor aconselhando + que você atualize o seu sistema para uma versão + suportada para ver se o problema ainda ocorre. A equipe + de <literal>Security Officer</literal> mantém a + <ulink url="&url.base;/security/">lista de versões + suportadas</ulink>.</para> + + <para>Se o problema está em um port, observe que + você deverá primeiro atualizar seu sistema para a + versão mais atual da coleção de ports e ver + se o problema ainda se aplica. Devido ao ritmo acelerado de + mudanças nestas aplicações, é + inviável para o &os; suportar qualquer coisa que + não seja obrigatoriamente a versão mais + recente, e problemas com uma versão antiga do + aplicativo simplesmente não podem ser corrigidos.</para> + </section> + + <section id="pr-prep"> + <title>Preparação</title> + + <para>Uma boa regra a ser seguida sempre é realizar uma + busca a respeito do assunto antes de enviar um relatório + de problema. Pode ser que o seu problema já tenha sido + reportado anteriormente; pode ser que esteja sendo debatido nas + listas de discussão ou que tenha sido recentemente; pode + até ser que o problema já tenha sido corrigido em + uma versão mais recente do que a que você + está utilizando. Você deve portanto verificar + em todos os lugares óbvios antes de enviar o + relatório de problema. Para o &os;, isto + significa:</para> + + <itemizedlist> + <listitem> + <para>A lista de <ulink + url="&url.books.faq;/index.html">Perguntas e Respostas mais + Frequentes</ulink> sobre o &os; (FAQ). A FAQ tem por + objetivo fornecer respostas para uma grande variedade de + perguntas, tais como as que dizem respeito a <ulink + url="&url.books.faq;/hardware.html">compatibilidade de + hardware</ulink>, <ulink + url="&url.books.faq;/applications.html">aplicações + do usuário</ulink>, <ulink + url="&url.books.faq;/kernelconfig.html">Configuração + do kernel</ulink>, etc.</para> + </listitem> + + <listitem> + <para>As <ulink + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL"> + listas de discussão</ulink> — se você + não está inscrito, utilize a <ulink + url="http://www.FreeBSD.org/search/search.html#mailinglists"> + busca do histórico</ulink> no web site do + &os;. Se o seu problema não tiver sido discutido nas + listas, você pode tentar enviar uma mensagem sobre ele + e aguardar alguns dias para ver se alguém consegue + perceber algo que você tenha deixado passar + desapercebido.</para> + </listitem> + + <listitem> + <para>Opcionalmente, na internet inteira — utilize seu + mecanismo de busca preferido para localizar + referências sobre o seu problema. Você pode + encontrar referências a ele em mensagens de listas de + discussão ou de grupos de noticias dos quais + você nunca ouviu falar ou nos quais sequer pensou + em procurar.</para> + </listitem> + + <listitem> + <para>Na sequência, verifique o <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + banco de dados com os relatórios de problema do + &os;</ulink> (GNATS). A menos que o seu problema seja + recente ou muito obscuro, existe uma boa chance dele + já ter sido reportado.</para> + </listitem> + + <listitem> + <para>E o mais importante, você deve verificar se a + documentação existente no código base + não endereça o seu problema.</para> + + <para>Para o código base do &os; você deve + estudar cuidadosamente o conteúdo do arquivo + <filename>/usr/src/UPDATING</filename> disponível no + seu sistema de arquivos ou a sua versão mais + recente no <ulink + url="http://svnweb.freebsd.org/base/head/UPDATING"> + Repositório Subversion</ulink>. (Esta + informação é vital se você + estiver atualizando de uma versão para outra + — especialmente se estiver atualizando para o + &os.current;).</para> + + <para>No entanto, se o problema é com algo que foi + instalado como uma parte da coleção de ports + do &os; você deve consultar o + <filename>/usr/ports/UPDATING</filename> (para os ports + individuais) ou o <filename>/usr/ports/CHANGES</filename> + (para mudanças que afetam a Coleção de + Ports inteira). Estes arquivos também estão + disponíveis no SVNWeb, nos urls <ulink + url="http://svnweb.freebsd.org/ports/head/UPDATING"></ulink> + e <ulink + url="http://svnweb.freebsd.org/ports/head/CHANGES"></ulink> + respectivamente.</para> + </listitem> + </itemizedlist> + </section> + + <section id="pr-writing"> + <title>Escrevendo o Relatório de Problema</title> + + <para>Agora que você decidiu que o seu assunto merece um + relatório de problema (PR), e que ele é um + problema do &os;, é hora de escrever o relatório + em si. Mas antes de entrarmos na mecânica do programa + utilizado para gerar e enviar os PRs, aqui estão + algumas dicas e truques para ajudá-lo a garantir que o + seu PR será o mais efetivo possível.</para> + + <section> + <title>Dicas e truques para escrever um bom relatório de + problema.</title> + + <itemizedlist> + <listitem> + <para><emphasis>Não deixe a linha de + <quote>Synopsis</quote> (sinopse) em branco.</emphasis> + Os PRs são enviados para listas de discussão + no mundo todo (nas quais a <quote>Synopsis</quote> + é utilizada como linha de + <literal>Subject:</literal>), além de serem + armazenados em um banco de dados. Qualquer pessoa + que vier a navegar no banco de dados pelas + sinopses, e encontrar um PR com a linha de assunto + em branco, tende a pulá-lo. Lembre-se que os PRs + permanecem na base de dados até que sejam fechados + por alguém; os anônimos normalmente + irão desaparecer em meio ao ruído.</para> + </listitem> + + <listitem> + <para><emphasis>Evite utilizar uma <quote>Synopsis</quote> + (sinopse) fraca.</emphasis> Você não + pode assumir que alguém que esteja lendo o seu PR + conheça todo o contexto que motivou o seu envio, + desta forma quanto mais informação + você fornecer, melhor. Por exemplo, a que + parte do sistema o problema se aplica? O problema + ocorre durante a instalação ou durante a + execução do sistema? Para ilustrar, ao + invés de utilizar <literal>Synopsis: o + portupgrade está quebrado</literal>, veja o + quão mais claro e mais eficiente seria + utilizar <literal>Synopsis: port sysutils/portupgrade + gerando coredumps no -current</literal>. (No caso de um + port, é especialmente útil ter a categoria + e o nome do port na linha de sinopse.)</para> + </listitem> + + <listitem> + <para><emphasis>Se você possui um patch, + mencione-o.</emphasis> Um PR que inclui um + <literal>patch</literal> é muito mais + provável de ser analisado do que um sem. Se + você estiver incluindo um, coloque a palavra + <literal>[patch]</literal> no inicio da linha + de sinopse. (Embora não seja obrigatório + utilizar exatamente esta palavra, por + convenção, é ela que é + utilizada.)</para> + </listitem> + + <listitem> + <para><emphasis>Se você é um + <literal>maintainer</literal> (mantenedor), + diga-o.</emphasis> Se você está mantendo uma + parte do código fonte (por exemplo, um port), + você deve considerar a possibilidade de incluir as + palavras <literal>[maintainer update]</literal> (incluindo + os colchetes) no inicio da linha de sinópse e + deve definir a <quote><literal>class</literal></quote> + (classe) do seu PR para maintainer-update. Desta forma + qualquer <literal>committer</literal> que manusear o seu + PR não terá de verificar o + <filename>Makefile</filename> do port, para certificar-se + de que a atualização foi enviada pelo + maintainer.</para> + </listitem> + + <listitem> + <para><emphasis>Seja específico.</emphasis> Quanto + mais informações você fornecer sobre o + problema que você está tendo, melhores + serão as suas chances de obter uma resposta.</para> + + <itemizedlist> + <listitem> + <para>Inclua a versão do &os; que você + está utilizando (existe um lugar para colocar + esta informação, veja abaixo) e em qual + arquitetura. Você incluir a + informação se está executando a + partir de um Release (e.g. de um CDROM ou Download), + ou a partir de um sistema mantido com o &man.cvsup.1; + (e neste caso, quando foi atualizado pela ultima + vez). Se você estiver utilizando o + &os.current;, esta vai ser a primeira coisa que + alguém irá lhe perguntar, porque as + correções (especialmente para os + problemas de alto nível) tendem a serem + realizadas muito rapidamente, e espera-se que os + usuários do &os.current; mantenham-se + atualizados.</para> + </listitem> + + <listitem> + <para>Inclua quais opções globais + você especificou no seu + <filename>make.conf</filename>. + Observação: É conhecido que + utilizar <literal>-O2</literal> (e acima disso) com o + &man.gcc.1; gera problemas em muitas + situações. Apesar dos desenvolvedores + do &os; aceitarem patches, eles normalmente não + estão dispostos a investigar este tipo de + problema por uma simples falta de tempo e de + voluntários, e ao invés disso podem + responder apenas que isto não é + suportado.</para> + </listitem> + + <listitem> + <para>Se o problema pode ser reproduzido facilmente, + inclua informações para possibilitar + que ele seja reproduzido pelos desenvolvedores. Se + o problema só pode ser + demonstrado com a entrada de um conjunto de dados + específico, você deverá incluir um + exemplo destas informações, além + de informar qual é resultado + atual (errado) e qual era o resultado esperado + (correto). Se o conjunto de dados for muito grande ou + se o mesmo não puder ser tornado + público, tente criar um arquivo com o + mínimo + de informações necessárias para + replicar o problema, e que possa ser incluído + no seu PR.</para> + </listitem> + + <listitem> + <para> + Se for um problema com o kernel, esteja preparado para + fornecer as seguintes informações + (Você não precisa fornecer estas + informações por padrão, o que + só tende a encher o banco de dados, mas + você deve incluir os trechos acreditar que + são relevantes):</para> + <itemizedlist> + <listitem> + <para>A configuração do seu kernel + (incluindo quais dispositivos de hardware + você tem instalados)</para> + </listitem> + <listitem> + <para>Se você tem ou não + opções de depuração + habilitadas (tais como + <literal>WITNESS</literal>), e em caso afirmativo, + se o problema continua ocorrendo quando + você altera a lógica de + configuração destas + opções</para> + </listitem> + <listitem> + <para>O texto completo de qualquer + <literal>backtrace</literal>, + <literal>panic</literal> e outras + mensagens no console, ou os registros do + <filename>/var/log/messages</filename>, caso tenha + sido gerado algum</para> + </listitem> + <listitem> + <para>A saída do <command>pciconf + -l</command> e as partes relevantes da + saída do <command>dmesg</command> se o + problema estiver relacionado a um componente de + hardware</para> + </listitem> + <listitem> + <para>O fato de que você leu o + <filename>src/UPDATING</filename> e que o seu + problema não está listado ali + (é certeza que alguém vai + perguntar)</para> + </listitem> + <listitem> + <para>Se você consegue ou não executar + outro kernel (Isto é para poder descartar a + possibilidade de ser um problema de hardware tais + como falha nos discos rígidos e + superaquecimento dos processadores, cujos + sintomas podem se confundir com problemas no + kernel)</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Se for um problema com um port, esteja preparado + para fornecer as seguintes informações + (Você não precisa fornecer estas + informações por padrão, o que + só tende a encher o banco de dados, mas + você deve incluir os trechos acreditar que + são relevantes):</para> + + <itemizedlist> + <listitem> + <para>Quais ports você tem instalados</para> + </listitem> + <listitem> + <para>As variáveis de ambiente que substituem + os padrões do + <filename>bsd.port.mk</filename>, como por exemplo + <makevar>PORTSDIR</makevar></para> + </listitem> + <listitem> + <para>O fato de que você leu o + <filename>ports/UPDATING</filename> e que o seu + problema não está listado ali + (é certeza que alguém vai + perguntar)</para> + </listitem> + </itemizedlist> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para><emphasis>Evite pedidos vagos de novas + funcionalidades.</emphasis> Os PRs no formato + <quote>alguém realmente deveria implementar algo + que faz isso e aquilo</quote> são menos + prováveis de obterem uma resposta do + que os que são mais específicos. Lembre-se, + o código está disponível para todos, + de forma que se você deseja uma nova funcionalidade, + a melhor maneira de ter certeza de que ela + será incluída é começar a + trabalhar! Também considere o fato de que + muitas destas sugestões fariam mais sentido + como um tópico de discussão na + <literal>freebsd-questions</literal> do que + como uma entrada no banco de dados de PRs, como + discutido acima.</para> + </listitem> + + <listitem> + <para><emphasis>Certifique-se de que ninguém tenha + submetido um PR semelhante antes.</emphasis> Embora isso + já tenha sido mencionado anteriormente, faz sentido + repetir aqui. Esta verificação irá + lhe tomar apenas 1 ou 2 minutos no uso do <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + mecanismo de busca</ulink> do banco de dados de PRs. + (é claro, todos são culpados de já + terem esquecido de fazer isso de uma vez ou outra.)</para> + </listitem> + + <listitem> + <para> + <emphasis>Relate apenas um problema em cada + relatório.</emphasis> Evite incluir dois ou mais + problemas em um mesmo relatório caso eles + não estejam relacionados. Quando + você submeter um <literal>patch</literal>, evite + adicionar várias funcionalidades ou corrigir + vários bugs em um mesmo PR, a menos que eles + sejam estritamente relacionados — Este tipo de + PR muitas vezes demanda mais tempo para ser + resolvido.</para> + </listitem> + + <listitem> + <para> <emphasis>Evite solicitações + polêmicas.</emphasis> Se o seu PR está + relacionado a um tema que foi polêmico no passado, + você deve estar preparado para não somente + disponibilizar um <literal>patch</literal>, como + também para defender porque o seu + <literal>patch</literal> é <quote>a coisa certa a + se fazer</quote>. Como mencionado acima, realizar uma + busca cuidadosa no histórico das <ulink + url="http://www.FreeBSD.org/search/search.html#mailinglists">listas + de discussão</ulink> é sempre uma boa + forma de se preparar.</para> + </listitem> + + <listitem> + <para><emphasis>Seja educado.</emphasis> Praticamente + todas as pessoas que potencialmente podem trabalhar no + seu PR são voluntários. Ninguém + gosta de receber ordens para fazer algo que eles já + estão fazendo por alguma outra + motivação a qual não é a de + ganho financeiro. Esta é uma boa coisa para ter + sempre em mente num projeto de código + aberto.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Antes de você iniciar</title> + + <para>Antes de executar o programa &man.send-pr.1;, + certifique-se que a sua variável de ambiente + <envar>VISUAL</envar> (ou a <envar>EDITOR</envar> se a + <envar>VISUAL</envar> não estiver definida) + está definida com seu editor preferido.</para> + + <para>Você também deve certificar-se de que o seu + sistema de entrega de emails esta funcionando corretamente. O + &man.send-pr.1; utiliza mensagens de email para enviar e + rastrear um relatório de problema. Se você + não pode enviar mensagens de email a partir da + máquina na qual está executando o + &man.send-pr.1;, os seus relatórios de problema + não irão chegar até a base de dados + GNATS. Para maiores detalhes de como configurar o sistema de + email no &os;, consulte o capítulo sobre <quote>Correio + Eletrônico</quote> no <ulink + url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">Handbook + do FreeBSD</ulink>.</para> + + <para>Certifique-se de que o seu sistema de email não + irá alterar a formatação da mensagem ao + encaminhá-la para o GNATS. Qualquer + <literal>patch</literal> que você enviar será + inutilizado, caso o seu sistema de email quebre + automaticamente as linhas, troque + tabulações por espaços em branco ou + altere os caracteres de mudança para uma nova linha, + etc. Entretanto, para as seções de texto + nós pedimos que você quebre manualmente as linhas + próximo dos 70 caracteres, desta forma a versão + web do PR poderá ser lida melhor.</para> + + <para>Considerações similares se aplicam se + você estiver utilizando o <ulink + url="&url.base;/send-pr.html">formulário web de + submissão de PR</ulink> ao invés de utilizar o + &man.send-pr.1;. Observe que operações de + copiar-e-colar possuem seus próprios efeitos colaterais + na formatação do texto. Em certos casos, pode + ser necessário usar o &man.uuencode.1; para garantir + que os patches cheguem sem modificações.</para> + + <para>Finalmente, se a sua submissão será longa, + você deve preparar o texto do seu + relatório offline, desta forma nada será + perdido no caso de você ter problemas quando for + submetê-lo. Isto pode ser um problema, em especial, + se você estiver utilizando o <ulink + url="&url.base;/send-pr.html">formulário + web</ulink>.</para> + </section> + + <section> + <title>Anexando <literal>patches</literal> ou arquivos</title> + + <para>As instruções abaixo se aplicam ao envio + de PRs por email:</para> + + <para>O programa &man.send-pr.1; tem a capacidade de anexar + arquivos em um relatório de problemas. Você + pode anexar quantos arquivos desejar desde que os mesmos + possuam nomes únicos (i.e. o nome próprio do + arquivo, sem o caminho de diretório). Basta usar a + opção <option>-a</option> na linha de comando + para anexar os arquivos desejados:</para> + +<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen> + + <para>Não se preocupe com os arquivos binários, + eles serão encodados automaticamente de forma a + não perturbar o seu agente de correio.</para> + + <para>Se você anexar um <literal>patch</literal>, tenha + certeza de utilizar a opção <option>-c</option> + ou <option>-u</option> no &man.diff.1; para criar um diff + contextual ou um diff unificado (o formato unificado é + preferido), e tenha certeza de especificar os números + de revisão exatos dos arquivos que você + modificou, desta forma o desenvolvedor que ler seu + relatório terá condições de + aplicá-los facilmente. Para problemas com o kernel ou + com os aplicativos do sistema base, um + <literal>patch</literal> para o &os.current; (o ramo HEAD do + CVS) é preferido uma vez que todo novo código + deve ser aplicado e testado primeiro nele. Depois que forem + realizados os testes apropriados, o código será + fundido ou migrado para o ramo &os.stable;.</para> + + <para>Se você juntar um <literal>patch</literal> + no corpo do email, em vez de enviá-lo como um + arquivo anexo, você estará sujeito a + ocorrência de um problema bastante comum ocasionado + pela tendência de alguns clientes de email de converter + tabs em espaços, o que irá arruinar + completamente qualquer coisa que você tenha enviado + com intenção de que fosse parte de um + Makefile.</para> + + <para>Não envie <literal>patches</literal> como anexos + usando <command>Content-Transfer-Encoding: quoted-printable + </command>. Isto irá realizar + <literal>character escaping</literal> e o + <literal>patch</literal> inteiro estará + inutilizado.</para> + + <para>Observe também que incluir pequenos + <literal>patches</literal> em um PR é normalmente a + coisa certa a se fazer — particularmente quando ele + corrige o problema descrito no PR — grandes + <literal>patches</literal> e especialmente código novo, + que normalmente requerem uma revisão substancial antes + de serem incorporados, devem ser colocados em um servidor web + ou de FTP, e a url deve ser incluída no PR ao + invés do <literal>patch</literal> propriamente dito. + Os <literal>patches</literal> dentro de um email tendem a se + deformar, especialmente quando o GNATS está envolvido, + e quanto maior o patch, maior é a dificuldade para + ambas as partes em consertá-lo. Além de que, ao + colocar o <literal>patch</literal> na web, você pode + modificá-lo sem ter que reenviar o arquivo completo + como um <literal>followup</literal> do PR original. + Além disso, os grandes <literal>patches</literal> + simplesmente aumentam o tamanho do banco de dados, uma vez que + os relatórios de problema fechados não + são deletados, continuando a existir marcados como + <literal>closed</literal>.</para> + + <para>Você deve observar que a menos que + especifique explicitamente no seu PR ou diretamente no seu + patch, qualquer correção que você envie + será considerada como estando licenciada sob os mesmos + termos do arquivo original que você modificou.</para> + </section> + + <section> + <title>Preenchendo o template</title> + + <para>As instruções abaixo se aplicam apenas ao + envio de PRs por email:</para> + + <para>Quando você executar o programa &man.send-pr.1;, + você será apresentado a um template. O template + consiste em uma lista de campos, alguns dos quais + estarão pré-preenchidos, e alguns irão + possuir comentários explicando o seu propósito + ou então listando os valores aceitáveis. + Não se preocupe com os comentários, eles + serão removidos automaticamente se você + não modificá-los ou então os remova + você mesmo.</para> + + <para>Na parte superior do template, logo abaixo das linhas + <literal>SEND-PR:</literal>, está o cabeçalho do + email. Você normalmente não necessita + modificá-lo, a menos que você esteja enviando o + relatório de problema a partir de uma máquina ou + de uma conta a qual pode enviar, mas não pode receber + emails, neste caso você deve configurar manualmente os + campos <literal>From:</literal> e <literal>Reply-To:</literal> + para o seu endereço de email real. Você + também pode querer enviar uma cópia do + relatório para você mesmo (ou para alguma outra + pessoa) através do uso de uma cópia carbono, + adicionando um ou mais endereços de email na linha de + cabeçalho <literal>Cc:</literal>.</para> + + <para>Os campos de linha única descritos abaixo, + estão disponíveis apenas no template do + email:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Submitter-Id:</emphasis> Não altere + este campo. O valor padrão é + <literal>current-users</literal> e está correto, + mesmo se você estiver executando o + &os.stable;.</para> + </listitem> + + <listitem> + <para><emphasis>Confidential:</emphasis> Não altere + este campo. O valor padrão é + <literal>no</literal>. Não tem sentido + alterá-lo já que não existem + relatórios de problema confidenciais no &os; + — o banco de dados de PR é + distribuído mundialmente pelo + <application>CVSup</application>.</para> + </listitem> + + <listitem> + <para><emphasis>Severity:</emphasis> Escolha uma + opção entre <literal>non-critical</literal>, + <literal>serious</literal> ou <literal>critical</literal>. + Não faça escândalo; abstenha-se de + rotular seu problema como <literal>critical</literal> a + menos que ele realmente seja (por ex. questões de + corrupção de dados, grave retrocesso de + funcionalidade no -CURRENT em relação a + versão anterior, etc)ou de + <literal>serious</literal> a menos que seja algo que vai + afetar muitos usuários (Kernel panic ou travamentos + do sistema; Problemas com algum driver de dispositivo em + particular ou com utilitários de sistema). Os + desenvolvedores do &os; não irão + necessariamente trabalhar no seu problema mais + rápido se você inflar sua importância + uma vez que existem muitas outras pessoas que fizeram + exatamente isso — na verdade, alguns desenvolvedores + prestam pouca atenção a este campo por causa + disso.</para> + + <note> + <para>Problemas de segurança + <emphasis>não</emphasis> devem ser submetidos + para o GNATS, pois todas as informações + no GNATS são de conhecimento público. + Por favor, envie estes problemas seguindo as nossas + <ulink url="http://security.freebsd.org/#how">diretrizes + sobre relatórios de segurança</ulink>. + </para> + + + </note> + </listitem> + + <listitem> + <para><emphasis>Priority:</emphasis> Escolha uma + opção entre <literal>low</literal>, + <literal>medium</literal> ou <literal>high</literal>. + <literal>high</literal> deve ser reservada para os + problemas que afetam praticamente todos os + usuários do &os; e <literal>medium</literal> para + os problemas que vão afetar muitos + usuários.</para> + + <note> + <para>Este campo tornou-se tão amplamente abusado que + perdeu quase que completamente seu objetivo.</para> + </note> + </listitem> + </itemizedlist> + + <para>A próxima seção descreve os campos + que são comuns entre a interface por email e a + <ulink url="&url.base;/send-pr.html">interface web</ulink>:</para> + + <itemizedlist> + + <listitem> + <para><emphasis>Originator:</emphasis> + Por favor informe seu nome completo, seguido opcionalmente + pelo seu endereço de email entre colchetes. + Na interface de email, este campo é normalmente + pré-preenchido com o campo + <literal>gecos</literal> do usuário com o qual + você está atualmente logado.</para> + + <note> + <para>O endereço de email que você utilizar + irá se tornar uma informação + pública e pode vir a se tornar disponível + para spammers. Você deverá ter um sistema + antispam funcional ou então deverá + utilizar uma conta temporária de email. + Contudo, por favor, lembre-se que se você + não utilizar uma conta de email válida, + nós não seremos capazes de entrar em + contato com você para fazer perguntas sobre o + seu PR.</para> + </note> + + </listitem> + + <listitem> + <para><emphasis>Organization:</emphasis> Campo livre para + o que você quiser colocar. Este campo não + é utilizado para nada significativo.</para> + </listitem> + + <listitem> + <para><emphasis>Synopsis:</emphasis> Preencha este campo com + uma descrição curta e precisa sobre o seu + problema. A <literal>synopsis</literal> é + utilizada como o assunto do email do relatório de + problema, e também é utilizada na listagem + de relatório de problemas e resumos; + relatórios de problema com + <literal>synopses</literal> obscuras tendem a serem + ignorados.</para> + + <para>Como mencionado acima, se o seu relatório de + problema inclui um <literal>patch</literal>, por favor, + inicie sua <literal>synopsis</literal> com + <literal>[patch]</literal> (incluindo os colchetes); se + você for um <literal>maintainer</literal> considere + adicionar <literal>[maintainer update]</literal> + (incluindo os colchetes) ao início da sua + <literal>synopsis</literal> e defina a + <quote>classe</quote> do seu PR para + <literal>maintainer-update</literal>.</para> + </listitem> + + <listitem> + <para><emphasis>Category:</emphasis> Escolha uma categoria + adequada.</para> + + <para> + A primeira coisa que você precisa fazer é + decidir em qual parte do sistema o seu problema + está. Lembre-se, o &os; é um sistema + operacional completo, o qual instala um kernel, as + bibliotecas padrão, muitos + <literal>drivers</literal> de dispositivos e um grande + número de utilitários (este conjunto + recebe o nome de <quote>sistema base</quote>). No + entanto, existem milhares de aplicativos adicionais na + Coleção de Ports. Você primeiro + precisa decidir se o problema está no sistema base + ou se está em algo que foi instalado através + da Coleção de Ports.</para> + + <para>Aqui está uma descrição das + principais categorias:</para> + + <itemizedlist> + <listitem> + <para> + Se o problema é com o Kernel, com as + bibliotecas (tal como a biblioteca C padrão, + libc), ou com um <literal>driver</literal> de + dispositivo do sistema base, em geral você vai + usar a categoria kern. (Existem algumas + exceções; veja abaixo). Em geral, estas + são coisas que estão descritas nas + seções 2, 3 ou 4 das páginas de + manual.</para> + </listitem> + + <listitem> + <para> + Se o problema é com um programa binário, + tal como o &man.sh.1; ou o &man.mount.8;, primeiro + você precisa determinar se estes programas + pertencem ao sistema base ou se foram adicionados + através da coleção de ports. Se + você estiver na dúvida, você pode + executar um <command>whereis <replaceable> + nomedoprograma</replaceable></command>, no + &os; por convenção todos os aplicativos + da coleção de ports são + instalados sob <filename + class="directory">/usr/local</filename>, embora isso + possa ser alterado por um administrador de sistemas. + Para estes, você irá utilizar a categoria + <literal>ports</literal> (sim, mesmo que a categoria + do port seja <literal>www</literal>; veja abaixo). Se + a localização do aplicativo for + <filename class="directory">/bin</filename>, <filename + class="directory">/usr/bin</filename>, <filename + class="directory">/sbin</filename>, ou <filename + class="directory">/usr/sbin</filename>, ele + faz parte do sistema base, e você + deverá utilizar a categoria + <literal>bin</literal>. (Alguns programas, como o + &man.gcc.1;, na prática utilizam a categoria + <literal>gnu</literal>, mas não se preocupe + com isso por agora.) Todos estes aplicativos + estão descritos nas seções 1 ou 8 + das páginas de manual.</para> + </listitem> + + <listitem> + <para>Se você acredita que o erro está no + script de inicialização + <literal>(rc)</literal>, ou em algum outro tipo de + arquivo de configuração não + executável, então a categoria indicada + será a <literal>conf</literal> + (configuração). Estas são coisas + descritas na seção 5 das páginas + de manual.</para> + </listitem> + + <listitem> + <para>Se você encontrou um problema na + documentação (artigos, livros, + páginas de manual, etc.), a escolha + correta para a categoria é a + opção <literal>docs</literal>.</para> + </listitem> + + <listitem> + <para>Se você está tendo problemas com as + <ulink url="http://www.FreeBSD.org">páginas web + do &os;</ulink>, a escolha apropriada é + <literal>www</literal>.</para> + + <note> + <para>Independentemente se você está + tendo algum problema com um port chamado + <literal>www/<replaceable>nomedoport</replaceable></literal>, + a categoria correta para o mesmo será + <literal>ports</literal>.</para> + </note> + </listitem> + </itemizedlist> + + <para>Existem algumas categorias mais especializadas.</para> + + <itemizedlist> + <listitem> + <para>Se o problema pode ser classificado na + categoria <literal>kern</literal>, e está + relacionado ao subsistema USB, a categoria correta + será <literal>usb</literal>.</para> + </listitem> + + <listitem> + <para>Se o problema pode ser classificado na categoria + <literal>kern</literal>, e está relacionado com + as bibliotecas de threads, a categoria correta + será <literal>threads</literal>.</para> + </listitem> + + <listitem> + <para>Se o problema está localizado no sistema + base, mas está relacionado a nossa + aderência a padrões tais como o + &posix;, a categoria correta será + <literal>standards</literal>.</para> + </listitem> + + <listitem> + <para> + Se o problema está relacionado a erros internos + de uma &java.virtual.machine; (&jvm;), mesmo que o + &java; tenha sido instalado a partir da + coleção de ports, você deve + selecionar a categoria <literal>java</literal>. + Problemas genéricos com o port do &java; devem + continuar sendo enviados na categoria + <literal>ports</literal>.</para> + </listitem> + </itemizedlist> + + <para>Isto deixa tudo mais.</para> + + <itemizedlist> + <listitem> + <para>Se você está convencido de que o + problema irá ocorrer apenas na arquitetura do + processador que você está utilizando, + selecione uma categoria específica para a sua + arquitetura: geralmente <literal>i386</literal> para + máquinas compatíveis com a arquitetura + Intel de 32 bits, <literal>amd64</literal> para + máquinas AMD executando em modo 64 bits (o que + também inclui máquinas + compatíveis com a arquitetura Intel executando + em modo EMT64); e menos comumente + <literal>ia64</literal>, <literal>powerpc</literal>, e + <literal>sparc64</literal>.</para> + + <note> + <para>Estas categorias são muitas vezes + utilizadas de forma indevida para problemas do + tipo <quote>Eu não sei</quote>. Em vez de + tentar adivinhar, por favor, apenas utilize a + categoria <literal>misc</literal>.</para> + </note> + + <example> + <title>Uso correto da categoria específica de + arquitetura.</title> + + <para>Você tem um computador comum (PC), e + acredita que encontrou um problema específico + com um chipset em particular ou com uma placa + mãe específica: A categoria correta + é <literal>i386</literal>.</para> + </example> + + <example> + <title>Uso incorreto da categoria específica de + arquitetura.</title> + + <para>Você está tendo problemas com uma + placa de expansão instalada em um barramento + bastante comum, ou um problema com um tipo + específico de disco rígido: neste + caso, é provável que o problema + ocorra em mais de uma arquitetura, e a categoria + correta seria <literal>kern</literal>.</para> + </example> + </listitem> + + <listitem> + <para>Se você realmente não sabe onde + está o problema (ou o mesmo não parece + se encaixar nas categorias acima), utilize a categoria + <literal>misc</literal>. Mas antes de fazer isto, + pode ser uma boa idéia primeiro pedir ajuda na + &a.questions;. Você poderá ser orientado + à utilizar uma das outras categorias para + obter um melhor resultado.</para> + </listitem> + </itemizedlist> + + <para>Aqui está a lista atual de categorias + (retirada do url <ulink + url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories"></ulink>):</para> + + <itemizedlist> + <listitem> + <para><literal>advocacy:</literal> problemas + relacionados a imagem pública do &os;. + Obsoleta.</para> + </listitem> + + <listitem> + <para><literal>alpha:</literal> problemas + específicos da plataforma Alpha.</para> + </listitem> + + <listitem> + <para><literal>amd64:</literal> problemas + específicos da plataforma AMD64.</para> + </listitem> + + <listitem> + <para><literal>arm:</literal> problemas + específicos da plataforma ARM.</para> + </listitem> + + <listitem> + <para><literal>bin:</literal> problemas com os programas + de nível de usuário na base do + sistema.</para> + </listitem> + + <listitem> + <para><literal>conf:</literal> problemas com os arquivos + de configuração, valores padrões, + etc.</para> + </listitem> + + <listitem> + <para><literal>docs:</literal> problemas com as + páginas de manuais ou com a + documentação online.</para> + </listitem> + + <listitem> + <para><literal>gnu:</literal> problemas com softwares + GNU, tais como &man.gcc.1; ou &man.grep.1;.</para> + </listitem> + + <listitem> + <para><literal>i386:</literal> problemas + específicos da plataforma &i386;.</para> + </listitem> + + <listitem> + <para><literal>ia64:</literal> problemas + específicos da plataforma ia64.</para> + </listitem> + + <listitem> + <para><literal>java:</literal> problemas relacionados + com a Maquina Virtual &java;.</para> + </listitem> + + <listitem> + <para><literal>kern:</literal> problemas com o kernel, + drivers de dispositivo (não específicos + à uma plataforma), ou bibliotecas do sistema + base.</para> + </listitem> + + <listitem> + <para><literal>misc:</literal> Tudo aquilo que + não se encaixa numa das outras + categorias. (observe que não existe nada que + pertença verdadeiramente a esta categoria, + exceto os problemas com a infra estrutura de build e + de release. As falhas temporárias de + compilação do <literal>HEAD</literal> + não pertencem a esta categoria. Também + observe que é fácil para as coisas se + perderem nesta categoria).</para> + </listitem> + + <listitem> + <para><literal>ports:</literal> problemas relacionados + com a Coleção de Ports.</para> + </listitem> + + <listitem> + <para><literal>powerpc:</literal> problemas + específicos da plataforma &powerpc;.</para> + </listitem> + + <listitem> + <para><literal>sparc64:</literal> problemas + específicos da plataforma &sparc64;.</para> + </listitem> + + <listitem> + <para><literal>standards:</literal> problemas + relacionados a conformidade com os + padrões.</para> + </listitem> + + <listitem> + <para><literal>threads:</literal> problemas relacionados + a implementação de threads no &os; + (especialmente no &os.current;).</para> + </listitem> + + <listitem> + <para><literal>usb:</literal> problemas relacionados a + implementação do USB no &os;.</para> + </listitem> + + <listitem> + <para><literal>www:</literal> mudanças e + melhorias no web site do &os;.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><emphasis>Class:</emphasis> Escolha uma das seguintes + opções:</para> + + <itemizedlist> + <listitem> + <para><literal>sw-bug:</literal> bugs de + software.</para> + </listitem> + + <listitem> + <para><literal>doc-bug:</literal> erros na + documentação.</para> + </listitem> + + <listitem> + <para><literal>change-request:</literal> + solicitação de novas funcionalidades + ou de alterações em funcionalidades + existentes.</para> + </listitem> + + <listitem> + <para><literal>update:</literal> + atualizações para o ports ou para + outros softwares de terceiros.</para> + </listitem> + + <listitem> + <para><literal>maintainer-update:</literal> + atualizações de ports pelos quais + você é o responsável.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><emphasis>Release:</emphasis> É a versão + do &os; que você está utilizando. Este campo + é preenchido automaticamente pelo &man.send-pr.1; e + só necessita ser alterado se você estiver + enviando o relatório de problema de um sistema + diferente do que apresenta o problema.</para> + </listitem> + </itemizedlist> + + <para>Finalmente, há uma série de campos de + várias linhas:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Environment:</emphasis> Este campo + deve descrever, da forma mais precisa + possível, o ambiente no qual o problema foi + observado. Isto inclui a versão do sistema + operacional, a versão do programa ou do arquivo + específico que contém o problema, e qualquer + outro item relevante tal como a configuração + do sistema, outros softwares instalados que tenham + influência no problema, etc. — ou seja, + simplesmente tudo o que um desenvolvedor precisar saber + para reconstruir o ambiente no qual o problema + ocorreu.</para> + </listitem> + + <listitem> + <para><emphasis>Description:</emphasis> Uma + descrição precisa e completa do problema + que você esta experimentando. Tente evitar + especular sobre as causas do problema a menos que + você tenha certeza de que está no caminho + certo, do contrário você pode induzir o + desenvolvedor a fazer suposições incorretas + sobre o problema.</para> + </listitem> + + <listitem> + <para><emphasis>How-To-Repeat:</emphasis> Um resumo com as + ações que você precisa executar para + reproduzir o problema.</para> + + </listitem> + + <listitem> + <para><emphasis>Fix:</emphasis> Preferencialmente um + <literal>patch</literal>, ou no + mínimo um <literal>workaround</literal> (o que + não só ajuda as outras pessoas que + estão com o mesmo problema, como também + auxilia o desenvolvedor a entender melhor a causa do + problema), mas se você não tem nenhuma + idéia consistente, é melhor deixar este + campo em branco do que especular.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Enviando o relatório de problemas</title> + + <para>Se você está utilizando o + &man.send-pr.1;:</para> + + <para>Uma vez que você tenha terminado de preencher o + template, salve-o, e saia do editor de texto, ao fazer isto o + &man.send-pr.1; irá lhe perguntar se você deseja + <prompt>s)end, e)dit or a)bort?</prompt>. Para ir em frente e + enviar o relatório de problema pressione + <userinput>s</userinput>, caso você queira voltar ao + editor para realizar alguma alteração pressione + <userinput>e</userinput>, ou então pressione + <userinput>a</userinput> para cancelar o envio. Se você + optar por abortar, o seu relatório de problema + irá permanecer no seu disco rígido (o + &man.send-pr.1; irá lhe informar o nome do arquivo + antes de finalizar), assim você poderá + editá-lo quando for mais conveniente, ou poderá + transferi-lo para um sistema com uma melhor + conectividade, no qual poderá enviá-lo usando a + opção <option>-f</option> com o + &man.send-pr.1;:</para> + +<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen> + + <para>Este comando irá ler o arquivo especificado, + validar o seu conteúdo, remover os comentários + e enviar o seu PR.</para> + + <para>Se você está utilizando o <ulink + url="&url.base;/send-pr.html">formulário + web</ulink>:</para> + + <para>Antes de pressionar o botão + <literal>submit</literal> para enviar o seu relatório, + você terá que preencher um campo com o texto + exibido na imagem de captcha exibida no final do + formulário. Infelizmente esta medida teve de ser + adotada devido ao mau uso do mesmo por sistemas automatizados + e por alguns indivíduos mal intencionados. É um + mal necessário do qual ninguém gosta. + Por favor, não peça para + removê-lo.</para> + + <para> + Recomendamos <emphasis>fortemente</emphasis> que você + salve o seu trabalho em algum outro lugar antes de + pressionar o botão <literal>submit</literal>. Um + problema comum e que ocorre com muitos usuários + é a visualização de uma imagem de + captcha velha exibida a partir do cache do navegador. Se + isso acontecer com você o seu envio será + rejeitado e você poderá perder o seu + trabalho.</para> + + <para>Se você, por qualquer motivo, não conseguir + visualizar as imagens, e também estiver impossibilitado + de utilizar o &man.send-pr.1;, por favor, aceite nossas + desculpas por está inconveniência e envie seu + relatório de problema por e-mail para a equipe de + bugbusters do &os;, no endereço + <email>freebsd-bugbusters@FreeBSD.org</email>.</para> + </section> + + </section> + + <section id="pr-followup"> + <title>Acompanhamento</title> + + <para> + Depois que seu relatório de problema tiver sido entregue, + você receberá uma confirmação por + e-mail com o número de rastreamento que foi + atribuído ao mesmo e uma URL a + qual você poderá utilizar para consultar o status + do seu PR. Com um pouco de sorte, alguém irá se + interessar pelo seu problema e tentará resolvê-lo, + ou, conforme o caso explicar porque não se trata de um + problema. Você será notificado automaticamente de + qualquer mudança de status, e irá + receber uma cópia de qualquer comentário ou + correção que alguém venha a anexar à + trilha de auditoria do seu relatório de problema.</para> + + <para>Se alguém lhe requisitar alguma + informação adicional, ou se você + lembrar de algo ou descobrir algo que você não + tenha mencionado no seu relatório inicial, por favor + utilize um dos dois métodos abaixo para enviar uma + atualização:</para> + + <itemizedlist> + <listitem> + <para>A forma mais fácil é utilizar o link e + <literal>followup</literal> existente na página web + individual de cada PR, a qual pode ser encontrada a partir + da <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + página de busca de relatórios</ulink>. Ao + clicar no link será aberta uma janela do seu + cliente de e-mail com os campos <literal>To:</literal> e + <literal>Subject:</literal> já corretamente + preenchidos (se o seu navegador estiver configurado + corretamente para fazer isto).</para> + </listitem> + + <listitem> + <para>Alternativamente, você pode apenas enviá-lo + para &a.bugfollowup;, certificando-se de que o número + de rastreamento está incluso no + <literal>Subject:</literal> de forma que o sistema de + acompanhamento de bugs tenha como saber em qual + relatório de problema ele deve anexar o material + recebido.</para> + + <note> + <para>Se você <emphasis>não</emphasis> incluir + o número de rastreamento, o GNATS irá se + confundir e criará um relatório de problema + completamente novo, o qual será atribuído ao + administrador do GNATS, e então o seu + <literal>followup</literal> irá ficar perdido + até que alguém tenha tempo de arrumar a + bagunça, o que pode levar dias e até mesmo + semanas para ocorrer.</para> + + <para>Forma errada:</para> + + <programlisting>Subject: Sobre o PR que eu enviei</programlisting> + + <para>Forma correta:</para> + + <programlisting>Subject: Re: ports/12345: problemas de compilação do foo/bar</programlisting> + </note> + </listitem> + + </itemizedlist> + + <para>Se o relatório de problema permanecer aberto depois + que o problema já tiver sido resolvido, basta enviar um + follow-up (da forma descrita acima) informando que o PR pode + ser fechado, e se possível, explicando como e quando o + problema foi corrigido.</para> + </section> + + <section id="pr-problems"> + <title>Se você está tendo problemas</title> + + <para>A maioria dos PRs que chegam ao sistema é processada + rapidamente; entretanto em alguns momentos o GNATS fica lento e + você pode não receber o seu email de + confirmação de imediato, levando 10 minutos ou + mesmo um pouco mais para recebê-lo. Por favor, tente ser + paciente.</para> + + <para>Além disso, uma vez que o GNATS recebe tudo por + email, é absolutamente vital que o &os; processe todas as + mensagens que chegam utilizando filtros antispam. Se você + não receber o email de confirmação em + até duas horas, você pode ter sido barrado por este + sistema; Neste caso, por favor, entre em contato com o + adminisrador do GNATS no endereço + <email>bugmeister@FreeBSD.org</email> e peça + ajuda.</para> + + <note> + <para> + Dentre as medidas antispam que utilizamos existe uma a qual + verifica a aderência da sua mensagem em + relação a uma série de abusos comums em + emails baseados em HTML (embora o sistema não + necessariamente invalide uma mensagem devido a mera + inclusão de código HTML no PR). + Recomendamos fortemente que você evite utilizar + emails no formato HTML quando estiver enviando um PR: + Não apenas é provável que a sua + mensagem seja bloqueada pelos filtros, como ela + também irá prejudicar o banco + de dados. O bom e velho email em texto puro é + fortemente preferido.</para> + </note> + + <para>Em raras ocasiões você irá se deparar + com um bug do GNATS pelo qual um PR será aceito, + receberá um número de rastreamento, mas + não irá aparecer na lista de PRs em nenhuma + consulta realizada no web site. + O que pode ter ocorrido é que o índice do banco de + dados ficou fora de sincronia com o próprio banco de + dados. Uma forma de testar se é isto que esta + acontecendo com você é acessar um PR individual + qualquer listado a partir do <ulink + url="http://www.FreeBSD.org/cgi/query-pr.cgi">formulário + de busca</ulink>, e substituir o numero do PR na URL pelo seu e + verificar se ele carrega normalmente. Se ele carregar, por + favor, notifique os administradores do GNATS no endereço + <email>bugmeister@FreeBSD.org</email>. Observe que existe uma + tarefa agendada no <literal>cron</literal> que reconstrói + periodicamente o banco de dados, de forma que a menos que + você esteja com pressa, nenhuma ação + será necessária.</para> + </section> + + <section id="pr-further"> + <title>Leituras complementares</title> + + <para>Esta é uma lista com material de referência + recomendado sobre boas práticas para se escrever e + processar um relatório de problema. Esta lista + não tem por objetivo ser uma lista completa.</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> + Como reportar bugs de forma efetiva</ulink>— Um + excelente ensaio por Simon G. Tatham sobre a + elaboração de relatórios de problemas + eficientes (não é especifico sobre o + &os;).</para> + </listitem> + <listitem> + <para><ulink + url="&url.articles.pr-guidelines;/article.html">Guia de como + lidar com relatórios de problemas</ulink> — + Uma percepção valiosa sobre como os + desenvolvedores do FreeBSD devem lidar com os + relatórios de problemas.</para> + </listitem> + </itemizedlist> + </section> +</article> diff --git a/pt_BR.ISO8859-1/books/Makefile b/pt_BR.ISO8859-1/books/Makefile index 66c9420b15..60e965ea65 100644 --- a/pt_BR.ISO8859-1/books/Makefile +++ b/pt_BR.ISO8859-1/books/Makefile @@ -6,6 +6,7 @@ # $FreeBSD$ SUBDIR+= faq +SUBDIR+= fdp-primer DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/books/fdp-primer/Makefile b/pt_BR.ISO8859-1/books/fdp-primer/Makefile new file mode 100755 index 0000000000..1732ad0096 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/Makefile @@ -0,0 +1,54 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# + +MAINTAINER=doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= structure/chapter.sgml +SRCS+= doc-build/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= translations/chapter.sgml +SRCS+= writing-style/chapter.sgml + +SRCS+= examples/appendix.sgml + +# 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 + +# Entities +SRCS+= chapters.ent + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pt_BR.ISO8859-1/books/fdp-primer/book.sgml b/pt_BR.ISO8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..8d85c5289b --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,301 @@ +<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent"> +%entities; +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +<!ENTITY % not.published "INCLUDE"> +]> + +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<book> + <bookinfo> + <title>&a.ptbr.p.fdpp; para novos colaboradores</title> + <corpauthor>Projeto de documentação do + FreeBSD</corpauthor> + <copyright> + <year>1998</year> + <year>1999</year> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <year>2008</year> + <year>2009</year> + <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> + </copyright> + + <pubdate role="rcs">$FreeBSD$</pubdate> + + <releaseinfo>$FreeBSD$</releaseinfo> + + &legalnotice; + + <abstract> + <para>Obrigado por tornar-se parte do Projeto de + Documentação do FreeBSD. A sua + contribuição é extremamente + valiosa.</para> + + <para>Este &a.ptbr.p.fdpp; cobre tudo o que você precisa + saber para começar a contribuir com o Projeto de + Documentação do FreeBSD, desde as ferramentas e + softwares que você estará utilizando (tanto + os obrigatórios quanto os recomendados) à + filosofia por trás do projeto de + documentação.</para> + + <para>Este documento é um trabalho em andamento, e + não está completo. As sessões que + sabemos estarem incompletas estão indicadas com um + <literal>*</literal> no seu nome.</para> + </abstract> + </bookinfo> + + <preface id="preface"> + <title>Prefácio</title> + +<sect1 id="preface-prompts"> + <title><foreignphrase>Prompt</foreignphrase> do interpretador de + comandos (<foreignphrase>shell</foreignphrase>)</title> + + <para>A tabela seguinte mostra o + <foreignphrase>prompt</foreignphrase> padrão do sistema + e o <foreignphrase>prompt</foreignphrase> do super + usuário. Os exemplos irão utilizar estes + <foreignphrase>prompts</foreignphrase> para indicar com qual + usuário o exemplo foi executado.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Usuário</entry> + <entry><foreignphrase>Prompt</foreignphrase></entry> + </row> + </thead> + + <tbody> + <row> + <entry>Usuário normal</entry> + <entry>&prompt.user;</entry> + </row> + + <row> + <entry><username>root</username></entry> + <entry>&prompt.root;</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 id="preface-conventions"> + <title>Convenções Tipográficas</title> + + <para>A tabela seguinte descreve as convenções + tipográficas utilizadas neste livro.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Propósito</entry> + <entry>Exemplos</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Nome de um comando.</entry> + <entry>Utilize <command>ls -a</command> para listar + todos os arquivos.</entry> + </row> + + <row> + <entry>Nome de um arquivo.</entry> + <entry>Edite o seu arquivo <filename>.login</filename> + .</entry> + </row> + + <row> + <entry>Saída + (<foreignphrase>output</foreignphrase>) + de um programa na tela do computador.</entry> + <entry><screen>Você tem email.</screen></entry> + </row> + + <row> + <entry>O que você digita, quando contrastado com a + saída (<foreignphrase>output</foreignphrase>) do + programa na tela do computador.</entry> + <entry><screen>&prompt.user; <userinput>su</userinput> +Password:</screen></entry> + </row> + + <row> + <entry>Referência a uma página de + manual.</entry> + <entry>Utilize o &man.su.1; para assumir outro nome de + usuário.</entry> + </row> + + <row> + <entry>Nome de usuário e de grupos de + usuários</entry> + <entry>Apenas o <username>root</username> pode fazer + isso.</entry> + </row> + + <row> + <entry>Ênfase</entry> + <entry>Você <emphasis>deve</emphasis> fazer + isso.</entry> + </row> + + <row> + <entry>Variáveis da linha de comando; Substitua + com o nome real ou com a variável.</entry> + <entry>Para deletar um arquivo, digite <command>rm<filename> + <replaceable>nome_do_arquivo</replaceable> + </filename></command></entry> + </row> + + <row> + <entry>Variáveis de ambiente</entry> + <entry>O <envar>$HOME</envar> é o seu + diretório <literal>home</literal>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> +</sect1> + + <sect1 id="preface-notes"> + <title>Notas, dicas, informações importantes, + avisos e exemplos</title> + + <para>Ao longo do texto aparecerão notas, avisos e + exemplos.</para> + + <note> + <para>Notas são representadas desta forma, e + contêm informações para as quais + você deveria ficar atento, pois podem afetar o que + você faz.</para> + </note> + + <tip> + <para>Dicas são representadas desta forma, e + contêm informações que você pode + achar úteis, ou que mostram uma maneira mais + fácil de fazer alguma coisa.</para> + </tip> + + <important> + <para>Informações importantes são + representadas desta forma. Normalmente elas destacam passos + extras que você pode precisar realizar.</para> + </important> + + <warning> + <para>Avisos são representados deste modo, e + contêm informações de alerta para + você sobre possíveis danos se você + não seguir as instruções. Estes danos + podem ser físicos: para o seu equipamento ou para + você; ou, podem ser não-físicos: tal + como a deleção inadvertida de arquivos + importantes.</para> + </warning> + + <example> + <title>Uma amostra de exemplo</title> + + <para>Os exemplos são representados deste modo, e + normalmente contêm exemplos que você deve + analisar, ou então, mostram como deveriam ser os + resultados de uma determinada ação.</para> + </example> + </sect1> + + <sect1 id="preface-acknowledgements"> + <title>Agradecimentos</title> + + <para>Meu muito obrigado a Sue Blake, Patrick Durusau, Jon + Hamilton, Peter Flynn, e Christopher Maden, por terem gasto + parte do seu tempo lendo os primeiros rascunhos deste + documento e por terem oferecido muitos comentários e + críticas construtivas para este trabalho.</para> + </sect1> + </preface> + + &chap.overview; + &chap.tools; + &chap.sgml-primer; + &chap.sgml-markup; + &chap.stylesheets; + &chap.structure; + &chap.doc-build; + &chap.the-website; + &chap.translations; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + + &app.examples; + +<!-- + &index; +--> +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent b/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent new file mode 100755 index 0000000000..fd6fd5cec4 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,25 @@ +<!-- + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> +<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> +<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.sgml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> +<!ENTITY chap.translations SYSTEM "translations/chapter.sgml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> +<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.sgml"> + +<!ENTITY app.examples SYSTEM "examples/appendix.sgml"> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml new file mode 100644 index 0000000000..55ad7ceeee --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml @@ -0,0 +1,585 @@ +<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38845 + +--> + +<chapter id="doc-build"> + <title>O processo de construção da + documentação</title> + + <para>A principal finalidade desse capítulo é explicar + claramente <emphasis>como o processo de criação da + documentação é organizado</emphasis>, e + <emphasis>como fazer modificações a este + processo</emphasis>.</para> + + <para>Depois de finalizar a leitura deste capítulo + você deverá:</para> + + <itemizedlist> + <listitem> + <para>Saber o que você precisa para compilar a + documentação mantida pelo FDP, em + adição ao que foi mencionado no + <link linkend="tools">capítulo Ferramentas SGML</link>. + </para> + </listitem> + + <listitem> + <para>Ser capaz de ler e entender as instruções do + <application>make</application> que estão presentes + em cada documento <filename>Makefile</filename>, assim como + ter uma visão geral do + <filename>doc.project.mk</filename>.</para> + </listitem> + + <listitem> + <para>Ser capaz de customizar o processo de + compilação usando variáveis e alvos do + <application>make</application>.</para> + </listitem> + </itemizedlist> + + <sect1> + <title>Ferramentas para construção da + documentação do FreeBSD</title> + + <para>Aqui estão suas ferramentas. Use-as de todas as + formas que puder.</para> + + <itemizedlist> + <listitem> + <para>A primeira ferramenta que você precisará + é o <application>make</application>, mais + especificamente o <application>Berkeley Make</application>. + </para> + </listitem> + + <listitem> + <para>A construção de pacotes no FreeBSD + é executada pelo + <application>pkg_create</application>. Se você + não está utilizando o FreeBSD, você + terá que viver sem o uso de pacotes, ou então + terá que compilar o código fonte você + mesmo.</para> + </listitem> + + <listitem> + <para>O <application>gzip</application> é + necessário para criar versões compactadas do + documento. O compressor <application>bzip2</application> e + os arquivos <application>zip</application> também + são suportados. O <application>tar</application> + é suportado, e a construção de + pacotes necessita dele.</para> + </listitem> + + <listitem> + <para>O <application>install</application> é o + método padrão para instalar a + documentação. Entretanto, existem + alternativas.</para> + </listitem> + </itemizedlist> + + <note> + <para>É improvável que você tenha qualquer + problema em localizar esses dois últimos, eles estão + sendo mencionados apenas para que a listagem fique completa. + </para> + </note> + </sect1> + + <sect1> + <title>Entendendo <filename>Makefile</filename>s na árvore da + documentação</title> + + <para>Há três tipos principais de + <filename>Makefile</filename>s na árvore do projeto de + documentção do FreeBSD.</para> + + <itemizedlist> + <listitem> + <para>Os <link linkend="sub-make"> + <filename>Makefile</filename>s de subdiretório</link> + simplesmente passam comandos para os diretórios + abaixo dele.</para> + </listitem> + + <listitem> + <para>Os <link linkend="doc-make"> + <filename>Makefile</filename>s de + documentação</link> descrevem o(s) + documento(s) que deve(m) ser produzido(s) a partir deste + diretório.</para> + </listitem> + + <listitem> + <para>Os <link linkend="make-includes"> + <application>Make</application> includes</link> são + os responsáveis pela produção do + documento, e geralmente possuem o nome no formato + <filename>doc.<replaceable>xxx</replaceable>.mk</filename>. + </para> + </listitem> + </itemizedlist> + + <sect2 id="sub-make"> + <title><filename>Makefile</filename>s de Subdiretórios</title> + + <para>Estes <filename>Makefile</filename>s geralmente tem a + forma:</para> + + <programlisting>SUBDIR =articles +SUBDIR+=books + +COMPAT_SYMLINK = en + +DOC_PREFIX?= ${.CURDIR}/.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> + + <para>Resumidamente, as primeiras quatro + linhas não vazias definem as variáveis do + <application>make</application>, <makevar>SUBDIR</makevar>, + <makevar>COMPAT_SYMLINK</makevar>, e + <makevar>DOC_PREFIX</makevar>.</para> + + <para>A primeira declaração da variável + <makevar>SUBDIR</makevar>, tanto quanto a + declaração da variável + <makevar>COMPAT_SYMLINK</makevar>, + mostra como atribuir um valor a uma variável, + sobrescrevendo qualquer valor anterior que a mesma + contenha.</para> + + <para>A segunda declaração da variável + <makevar>SUBDIR</makevar> mostra como um valor é + adicionado ao valor atual de uma variável. A + variável <makevar>SUBDIR</makevar> agora é + composta por <literal>articles books</literal>.</para> + + <para>A declaração do + <makevar>DOC_PREFIX</makevar> mostra como um valor é + atribuído para uma variável, mas somente se + ela ainda não estiver definida. Isto é + útil se o <makevar>DOC_PREFIX</makevar> não + for onde este <filename>Makefile</filename> pensa que + é - o usuário pode cancelar e fornecer + o valor correto.</para> + + <para>Agora o que tudo isso significa? O + <makevar>SUBDIR</makevar> lista quais subdiretórios + abaixo do atual devem ser incluídos no processo de + compilação durante a geração + do documento.</para> + + <para>O <makevar>COMPAT_SYMLINK</makevar> é + específico para compatibilizar os links + simbólicos que ligam os idiomas a sua + codificação oficial (por exemplo o + <filename>doc/en</filename> deve apontar para + <filename>en_US.ISO-8859-1</filename>).</para> + + <para>O <makevar>DOC_PREFIX</makevar> é o caminho para a + raíz da árvore do projeto de + documentação do FreeBSD. O qual nem sempre + é facil de encontrar, e que também pode ser + facilmente sobrescrito, para permitir flexibilidade. O + <makevar>.CURDIR</makevar> é uma variável + interna do <application>make</application> que contém + o caminho para o diretório atual.</para> + + <para>A linha final inclui o arquivo principal do projeto de + documentação do FreeBSD, o + <filename>doc.project.mk</filename>, ele é o + responsável por converter estas variáveis em + instruções de compilação para + uso do <application>make</application>.</para> + + </sect2> + <sect2 id="doc-make"> + <title><filename>Makefile</filename>s de Documentação</title> + + <para>Estes <filename>Makefile</filename>s ajustam várias + variáveis do <application>make</application> as quais + descrevem como construir a documentação + contida em um determinado diretório.</para> + + <para>Aqui está um exemplo:</para> + + <programlisting>MAINTAINER=nik@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# SGML content +SRCS= book.sgml + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> + + <para>A variável <makevar>MAINTAINER</makevar> é + uma muito importante. Esta variável fornece a + habilidade de reivindicar a propriedade sobre um documento no + projeto de documentação do FreeBSD, é + por meio dela que você recebe a responsabilidade de + mantê-lo.</para> + + <para><makevar>DOC</makevar> é o nome (sem a + extensão <filename>.sgml</filename>) do principal + documento criado por este diretório. A variável + <makevar>SRCS</makevar> lista todos os arquivos individuais + que compõem o documento. Ela também deve + incluir os arquivos importantes, nos quais qualquer + mudança deve resultar em uma + reconstrução.</para> + + <para>O <makevar>FORMATS</makevar> indica os formatos + nos quais o documento deve ser gerado por padrão. + O <makevar>INSTALL_COMPRESSED</makevar> contém a lista + padrão das técnicas de compressão que + devem ser usadas no documento depois que ele é gerado. + A variável <makevar>INSTALL_ONLY_COMPRESS</makevar>, + nula por padrão, deve ser definida para um valor + não nulo apenas se você desejar gerar + exclusivamente a versão compactada do documento.</para> + + <note> + <para>Nós abordamos a atribuição das + variáveis opcionais na <link + linkend="sub-make">seção anterior</link>. + </para> + </note> + + <para>Você também já deve estar + familiarizado com a atribuição da + variável <makevar>DOC_PREFIX</makevar> e com as + instruções de include.</para> + </sect2> + </sect1> + + <sect1 id="make-includes"> + <title>Includes do <application>Make</application> do projeto de documentação + do FreeBSD</title> + + <para>Isto é melhor explicado pela inspeção + no código. Aqui estão os arquivos include do + sistema:</para> + + <itemizedlist> + <listitem> + <para>O <filename>doc.project.mk</filename> é o + principal arquivo include do projeto, que inclui todos os + arquivos includes necessários.</para> + </listitem> + + <listitem> + <para>O <filename>doc.subdir.mk</filename> controla a + navegação na árvore de + documentação durante + o processo de construção e + instalação.</para> + </listitem> + + <listitem> + <para>O <filename>doc.install.mk</filename> fornece as + variáveis que afetam a propriedade e a + instalação de documentos.</para> + </listitem> + + <listitem> + <para>O <filename>doc.docbook.mk</filename> é + incluído se o <makevar>DOCFORMAT</makevar> + for <literal>docbook</literal> e se a variável + <makevar>DOC</makevar> estiver definida.</para> + </listitem> + </itemizedlist> + + <sect2> + <title><filename>doc.project.mk</filename></title> + + <para>Por inspeção:</para> + + <programlisting>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"</programlisting> + + <sect3> + + <title>Variáveis</title> + + <para>As variáveis <makevar>DOCFORMAT</makevar> e + <makevar>MAINTAINER</makevar> serão atribuídas + com valores padrão, se o valor das mesmas não + tiver sido definido no arquivo Makefile do documento.</para> + + <para>O <makevar>PREFIX</makevar> define o caminho no + qual os <link linkend="tools">aplicativos de + construção da documentação</link> + estão instalados. Para uma instalação + normal através de pacotes e/ou ports, este caminho + será sempre <filename>/usr/local</filename>.</para> + + <para>A variável <makevar>PRI_LANG</makevar> deve ser + configurada para refletir o idioma e a + codificação nativa dos usuários aos + quais os documentos se destinam. O Inglês Americano + (US English) é o padrão.</para> + + <note> + <para>A variável <makevar>PRI_LANG</makevar> de + maneira alguma afeta quais documentos serão, + ou que poderão, ser compilados. Sua + função principal é criar links para + os documentos referenciados com maior frequência no + diretório raiz de instalação da + documentação do FreeBSD.</para> + </note> + </sect3> + + <sect3> + <title>Condicionais</title> + + <para>A linha <literal>.if defined(DOC)</literal> é + um exemplo da condicional do <application>make</application> + , como em outros programas, define o comportamento se + alguma condição é verdadeira ou se + é falsa. <literal>defined</literal> é uma + função que retorna se uma dada + variável está definida ou não.</para> + + <para>A seguir, <literal>.if ${DOCFORMAT} == "docbook" + </literal>, testa se a variável <makevar>DOCFORMAT + </makevar> é <literal>"docbook"</literal>, e neste + caso, inclue o <filename>doc.docbook.mk</filename>.</para> + + <para>Os dois <literal>.endif</literal>s fecham as duas + condicionais anteriores, marcando o fim da sua + aplicação.</para> + </sect3> + </sect2> + + <sect2> + <title>doc.subdir.mk</title> + + <para>Este arquivo é muito longo para ser explicado por + inspeção, você deve ser capaz de + interpretá-lo com o conhecimento adquirido nos + capítulos anteriores, e com a pequena ajuda dada + aqui.</para> + + <sect3> + <title>Variáveis</title> + + <itemizedlist> + <listitem> + <para><makevar>SUBDIR</makevar> é a lista de + subdiretórios nos quais o processo de + construção deve ser executado.</para> + </listitem> + + <listitem> + <para><makevar>ROOT_SYMLINKS</makevar> são os nomes + dos diretórios que devem ser linkados para a + raíz de instalação do documento + a partir da sua localização atual, se o + idioma atual for o idioma primário (especificado + por <makevar>PRI_LANG</makevar>).</para> + </listitem> + + <listitem> + <para>O <makevar>COMPAT_SYMLINK</makevar> já foi + descrito na seção <link + linkend="sub-make">Makefiles de subdiretório + </link>.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Targets e Macros</title> + + <para>As dependências são descritas por + <literal><replaceable>target</replaceable>: + <replaceable>dependência1 dependência2 ... + </replaceable></literal>, nas quais, para construir o + <literal>target</literal>, você necessita + primeiramente construir as dependências + informadas.</para> + + <para>Depois desta descrição, + instruções de como construir o target podem + ser passadas, no caso do processo de conversão + entre o target e estas dependências não + tiver sido previamente definido, ou se esta + conversão em particular não for a mesma + que a definida pelo método padrão de + conversão.</para> + + <para>A dependência especial <literal>.USE</literal> + define o equivalente a uma macro.</para> + +<programlisting>_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para>No código acima, <maketarget>_SUBDIRUSE + </maketarget> é agora uma macro, a qual irá + executar determinados comandos quando for listada como + dependência.</para> + + <para>O que define esta macro a parte de outros targets? + Basicamente, ela é executada <emphasis>após + </emphasis> as instruções passadas no + processo de construção por ser uma + dependência para o mesmo, e ela não + configura o <makevar>.TARGET</makevar>, que é a + variável que contém o nome do target atual + que está sendo construído.</para> + +<programlisting>clean: _SUBDIRUSE + rm -f ${CLEANFILES}</programlisting> + + <para>No código acima, o <maketarget>clean</maketarget> + irá usar a macro <maketarget>_SUBDIRUSE</maketarget> + depois de ter executado a instrução + <command>rm -f ${CLEANFILES}</command>. De fato, isto causa + uma limpeza (<maketarget>clean</maketarget>) na + árvore de diretórios, deletando os arquivos + construídos enquanto vai + <emphasis>descendo</emphasis> pelos subdiretórios, + e não quando vai na direção + oposta.</para> + + <sect4> + <title>Targets fornecidos</title> + + <itemizedlist> + <listitem> + <para><maketarget>install</maketarget> e + <maketarget>package</maketarget>, ambos descem pela + árvore de diretórios executando a sua + versão real dentro dos subdiretórios. + (<maketarget>realinstall</maketarget> e + <maketarget>realpackage</maketarget> + respectivamente).</para> + </listitem> + + <listitem> + <para>O <maketarget>clean</maketarget> remove os + arquivos criados pelo processo de + compilação (e também desce na + árvore de diretórios). + O <maketarget>cleandir</maketarget> faz a mesma + coisa, e também remove o diretório + de objetos se este existir.</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + + <sect3> + <title>Mais Condicionais</title> + + <itemizedlist> + <listitem> + <para><literal>exists</literal> é outra + função condicional que retorna verdadeiro + se o arquivo informado existir.</para> + </listitem> + + <listitem> + <para><literal>empty</literal> retorna verdadeiro se a + variável informada estiver vazia.</para> + </listitem> + + <listitem> + <para><literal>target</literal> retorna verdadeiro se o + target informado ainda não existir.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Construção de Looping no + <command>make (.for)</command></title> + + <para>O <literal>.for</literal> fornece uma maneira de + repetir instruções definidas para cada + elemento separado por espaço em uma variável. + Ele faz isso atribuíndo uma variável para + conter o elemento atual da lista que está sendo + examinada.</para> + +<programlisting>_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para>No código acima, se <makevar>SUBDIR</makevar> + estiver vazia, nenhuma ação será + executada; se ela possuir um ou mais elementos, as + instruções entre o <literal>.for</literal> e + o <literal>.endfor</literal> serão repetidas para + cada elemento, com o <makevar>entry</makevar> + sendo substituído com o valor do elemento + atual.</para> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.sgml new file mode 100644 index 0000000000..b1fa4f7c0e --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.sgml @@ -0,0 +1,407 @@ +<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38847 + +--> + +<appendix id="examples"> + <title>Exemplos</title> + + <para>Este apêndice contém arquivos SGML de exemplo + e linhas de comando que você pode utilizar para + convertê-los de um formato para outro. Se você + instalou com sucesso as ferramentas do Projeto de + Documentação, então você será + capaz de utilizar estes exemplos imediatamente.</para> + + <para>Estes exemplos não são exaustivos — eles + não contêm todos os elementos que você pode + utilizar, particularmente para a capa do seu documento. Para + maiores exemplos de marcação DocBook você + deve examinar o código SGML deste e de outros documentos, + disponíveis no repositório <literal>doc</literal> + do <application>svn</application>, ou disponíveis online + no endereço + <ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>. + </para> + + <para>Para evitar confusão, estes exemplos utilizam a + especificação DocBook 4.1 DTD sem nenhuma + extensão particular adicionada pelo FreeBSD. Eles + também utilizam as folhas de estilo padrões + distribuídas pelo Norm Walsh, sem nenhuma + customização feita nas mesmas pelo Projeto de + Documentação do FreeBSD. Isto os torna mais + úteis como exemplos genéricos de + marcação DocBook.</para> + + + <sect1 id="examples-docbook-book"> + <title>DockBook <sgmltag>book</sgmltag></title> + + <example> + <title>DocBook <sgmltag>book</sgmltag></title> + + <programlisting><![ RCDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<book> + <bookinfo> + <title>Um exemplo de Livro</title> + + <author> + <firstname>Seu nome</firstname> + <surname>Seu sobrenome</surname> + <affiliation> + <address><email>seuemail@example.com</email></address> + </affiliation> + </author> + + <copyright> + <year>2000</year> + <holder>Texto de Copyright</holder> + </copyright> + + <abstract> + <para>Se seu livro possui um sumário ele deve ser colocado aqui.</para> + </abstract> + </bookinfo> + + <preface> + <title>Prefácio</title> + + <para>Seu livro pode ter um prefácio, se este for o caso, ele deve + ser colocado aqui.</para> + </preface> + + <chapter> + <title>Meu primeiro capítulo</title> + + <para>Este é o primeiro capítulo do meu livro.</para> + + <sect1> + <title>Minha primeira seção</title> + + <para>Esta é a primeira seção do meu livro.</para> + </sect1> + </chapter> +</book>]]></programlisting> + </example> + </sect1> + + <sect1 id="examples-docbook-article"> + <title>DocBook <sgmltag>article</sgmltag></title> + + <example> + <title>DocBook <sgmltag>article</sgmltag></title> + + <programlisting><![ RCDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<article> + <articleinfo> + <title>Um exemplo de Artigo</title> + + <author> + <firstname>Seu nome</firstname> + <surname>Seu sobrenome</surname> + <affiliation> + <address><email>seuemail@example.com</email></address> + </affiliation> + </author> + + <copyright> + <year>2000</year> + <holder>Texto de Copyright</holder> + </copyright> + + <abstract> + <para>Se o seu artigo possuir um sumário ele deve ser colocado aqui.</para> + </abstract> + </articleinfo> + + <sect1> + <title>Minha primeira seção</title> + + <para>Esta é a primeira seção do meu artigo.</para> + + <sect2> + <title>Minha primeira subseção</title> + + <para>Esta é a primeira subseção do meu artigo.</para> + </sect2> + </sect1> +</article>]]></programlisting> + </example> + </sect1> + + <sect1 id="examples-formatted"> + <title>Produzindo saídas formatadas</title> + + <para>Esta seção assume que você já + instalou os softwares listados no port <filename + role="package">textproc/docproj</filename>, seja via meta-port + ou manualmente. Além disso, ela também assume + que os seus softwares estão instalados em + subdiretórios sob o <filename>/usr/local/</filename>, + e que os diretórios nos quais os binários foram + instalados, estão mapeados no seu <envar>PATH</envar>. + Ajuste os paths conforme a necessidade do seu sistema.</para> + + <sect2> + <title>Usando o Jade</title> + + <example> + <title>Convertendo de DocBook para HTML (em um único + grande arquivo)</title> + + <screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"/> + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"/> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-1-dsssl"/> + -t sgml <co id="examples-co-jade-1-transform"/> <replaceable>file</replaceable>.sgml > <replaceable>file</replaceable>.html <co id="examples-co-jade-1-filename"/></userinput></screen> + + <calloutlist> + <callout arearefs="examples-co-jade-1-nochunks"> + <para>Especifique o parâmetro <literal>nochunks + </literal> para as folhas de estilo, forçando + que todos os outputs sejam escritos para a saída + padrão (<abbrev>STDOUT</abbrev>) (utilizando as + folhas de estilo do Norm Walsh).</para> + </callout> + + <callout arearefs="examples-co-jade-1-catalog"> + <para>Especifique os catálogos que o + <application>Jade</application> terá que + processar. Três catálogos são + requeridos. O primeiro é o catálogo + que contém as informações sobre + as folhas de estilo DSSSL. O segundo contém + informações sobre o DTD DockBook. E + o terceiro contém informações + específicas para o + <application>Jade</application>.</para> + </callout> + + <callout arearefs="examples-co-jade-1-dsssl"> + <para>Especifique o caminho completo das folhas de estilo + DSSSL as quais o <application>Jade</application> + irá utilizar quando estiver processando o + documento.</para> + </callout> + + <callout arearefs="examples-co-jade-1-transform"> + <para>Instrua o <application>Jade</application> para + realizar uma <emphasis>transformação + </emphasis> de uma DTD para outra. Neste caso, a + entrada será transformada de um DTD DocBook + para um DTD HTML.</para> </callout> + + <callout arearefs="examples-co-jade-1-filename"> + <para>Especifique o arquivo que o + <application>Jade</application> deve processar, e + redirecione a saída para o arquivo + <filename>.html</filename> desejado.</para> + </callout> + </calloutlist> + </example> + + <example> + <title>Convertendo de DocBook para HTML (vários + arquivos pequenos)</title> + + <screen>&prompt.user; <userinput>jade \ + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"/> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-2-dsssl"/> + -t sgml <co id="examples-co-jade-2-transform"/> <replaceable>file</replaceable>.sgml <co id="examples-co-jade-2-filename"/></userinput></screen> + + <calloutlist> + <callout arearefs="examples-co-jade-2-catalog"> + <para>Especifique os catálogos os quais o + <application>Jade</application> terá que + processar. Três catálogos são + requeridos. O primeiro é o catálogo + o qual contém as informações + sobre as folhas de estilo DSSSL. O segundo + contém informações sobre o DTD + DocBook. O terceiro contém + informações específicas para + o <application>Jade</application>.</para> + </callout> + + <callout arearefs="examples-co-jade-2-dsssl"> + <para>Especifique o caminho completo da folha de estilo + DSSSL a qual o <application>Jade</application> + irá utilizar quando estiver processando o + documento.</para> + </callout> + + <callout arearefs="examples-co-jade-2-transform"> + <para>Instrua o <application>Jade</application> para + realizar a <emphasis>transformação + </emphasis> de uma DTD para outra. Neste caso, a + entrada será transformada de um DTD DocBook + para um DTD HTML.</para> + </callout> + + <callout arearefs="examples-co-jade-2-filename"> + <para>Especifique o arquivo que o + <application>Jade</application> deve processar. A + folha de estilo determina como os arquivos HTML + individuais serão nomeados, inclusive o nome + do arquivo <quote>raiz</quote> (é o arquivo + que contém o inicio do documento).</para> + </callout> + </calloutlist> + + <para>Este exemplo pode continuar gerando apenas um + único arquivo HTML, dependerá da estrutura + do documento que você estiver processando e das + regras da folha de estilo selecionada, para divisão + do output.</para> + + </example> + + <example id="examples-docbook-postscript"> + <title>Convertendo de DocBook para Postscript</title> + + <para>O arquivo fonte SGML precisa ser convertido para um + arquivo &tex;.</para> + + <screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/> + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog"/> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \<co id="examples-co-jade-3-dsssl"/> + -t tex <co id="examples-co-jade-3-tex"/> <replaceable>file</replaceable>.sgml</userinput></screen> + + <calloutlist> + <callout arearefs="examples-co-jade-3-tex-backend"> + <para>Customize as folhas de estilo para utilizar as + várias opções existentes, + específicas para a produção + de saídas &tex;.</para> + </callout> + + <callout arearefs="examples-co-jade-3-catalog"> + <para>Especifique os catálogos os quais o + <application>Jade</application> terá que + processar. Três catálogos são + requeridos. O primeiro é o catálogo o + qual contém as informações sobre + as folhas de estilo DSSSL. O segundo contém + informações sobre o DTD DocBook. O + terceiro contém informações + específicas para o Jade.</para> + </callout> + + <callout arearefs="examples-co-jade-3-dsssl"> + <para>Especifique o caminho completo da folha de estilo + DSSSL a qual o <application>Jade</application> + irá utilizar quando estiver processando o + documento.</para> + </callout> + + <callout arearefs="examples-co-jade-3-tex"> + <para>Instrua o <application>Jade</application> para + converter o output para &tex;.</para> + </callout> + </calloutlist> + + <para>O arquivo <filename>.tex</filename> gerado, deve ser + agora processado pelo <command>tex</command>, especificando + o pacote de macros <literal>&jadetex</literal>.</para> + + <screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen> + + <para>Você tem que executar o <command>tex</command> + <emphasis>pelo menos</emphasis> três vezes. A + primeira execução irá processar o + documento, e determinar as áreas do documento que + são referenciadas a partir de outras partes do + documento, para uso na indexação, etc.</para> + + <para>Não fique alarmado se você visualizar + mensagens de alertas tais como <errorname>LaTeX Warning: + Reference `136' on page 5 undefined on input + line 728.</errorname> neste momento.</para> + + <para>A segunda execução reprocessa o documento + agora que certas peças de informação + são conhecidas (tais como o número de + páginas do documento). Isto permite indexar as + entradas e estabelecer as outras referências + cruzadas.</para> + + <para>A terceira execução irá realizar + a limpeza final necessária no arquivo</para> + + <para>O output deste estágio será um + <filename><replaceable>arquivo</replaceable>.dvi</filename>. + </para> + + <para>Finalmente, execute o <command>dvips</command> para + converter o arquivo <filename>.dvi</filename> para o + formato Postscript.</para> + + <screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen> + </example> + + <example> + <title>Convertendo de DocBook para PDF</title> + + <para>A primeira parte deste processo é idêntica ao + realizado quando se converte de DocBook para Postscript, + utilizando a mesma linha de comando para o + <command>jade</command> + (<xref linkend="examples-docbook-postscript"/>).</para> + + <para>Quando o arquivo <filename>.tex</filename> já + tiver sido gerado, você deve executar o + <application>pdfTeX</application> utilizando o pacote de + macros <literal>&pdfjadetex</literal>.</para> + + <screen>&prompt.user; <userinput>pdftex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen> + + <para>De novo, execute este comando três vezes.</para> + + <para>Ele irá gerar um <filename><replaceable>arquivo + </replaceable>.pdf</filename>, o qual não necessita + de nenhum processamento adicional.</para> + </example> + </sect2> + </sect1> +</appendix> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.sgml new file mode 100644 index 0000000000..b6370d426b --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,344 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38854 + +--> + +<chapter id="overview"> + <title>Visão Geral</title> + + <para>Seja bem vindo ao Projeto de Documentação do + FreeBSD. Documentação de boa qualidade é + muito importante para o sucesso do FreeBSD, e o Projeto de + Documentação do FreeBSD (FDP) é a origem + de muitos destes documentos. Suas contribuições + são muito importantes.</para> + + <para>A finalidade principal deste documento é explicar + claramente <emphasis>como o FDP é organizado</emphasis>, + <emphasis>como escrever e como submeter documentos para o FDP + </emphasis>, e <emphasis>como utilizar de forma efetiva as + ferramentas que estão disponíveis para você + enquanto estiver escrevendo</emphasis>.</para> + + <para><indexterm><primary>Sociedade</primary></indexterm>Todos + são bem vindos para se juntar ao FDP. Não + existe nenhum requisito mínimo para a sua + associação, nenhuma quota de documentos que + você precise produzir por mês. Tudo o que você + precisa fazer é se inscrever na &a.doc;.</para> + + <para>Depois que você tiver terminado de ler este documento, + você deve:</para> + + <itemizedlist> + <listitem> + <para>Saber quais documentos são mantidos pelo FDP. + </para> + </listitem> + + <listitem> + <para>Ser capaz de ler e entender o código fonte SGML + de um documento mantido pelo FDP.</para> + </listitem> + + <listitem> + <para>Ser capaz de efetuar alterações num + documento.</para> + </listitem> + + <listitem> + <para>Ser capaz de enviar suas alterações de + volta para revisão e eventual inclusão na + documentação do FreeBSD.</para> + </listitem> + </itemizedlist> + + <sect1 id="overview-doc"> + <title>Conjunto de Documentação do FreeBSD</title> + + <para>O FDP é responsável por quatro categorias de + documentos do FreeBSD.</para> + + <variablelist> + <varlistentry> + <term>Páginas de Manual</term> + + <listitem> + <para>As páginas de manual do sistema na + língua inglesa não são escritas pelo + FDP, porque elas são parte da base do sistema. + Entretanto, o FDP pode (e tem) reescrever partes das + páginas de manual existentes para torná-las + mais claras, ou para corrigir imprecisões.</para> + + <para>Os times de tradução são + responsáveis por traduzir as páginas de + manual do sistema para diferentes idiomas. Estas + traduções são mantidas pelo FDP. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FAQ</term> + + <listitem> + <para>O objetivo do FAQ é consolidar (no formato de + perguntas e respostas curtas) as perguntas que foram + feitas, ou que podem ser feitas, nas várias + listas de discussão e newsgroups dedicados ao + FreeBSD. O formato não permite respostas longas + e detalhadas.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Handbook</term> + + <listitem> + <para>O Handbook almeja ser um compreensivo recurso de + referência online para os usuários do + FreeBSD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Web Site</term> + + <listitem> + <para>Esta é a principal presença do FreeBSD + na <literal>World Wide Web</literal>, visível em + <ulink url="&url.base;/index.html"> + http://www.FreeBSD.org/</ulink> + e em muitos sites espelhos ao redor do mundo. O web + site é o primeiro contato de muitas pessoas com o + FreeBSD.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>A documentação do web site, do Handbook do + &os; e do FAQ estão disponíveis no + repositório Subversion <literal>doc/</literal>, que + está localizado em + <literal>svn://svn.FreeBSD.org/doc/</literal>.</para> + + <para>As páginas de manual estão disponíveis + no repositório Subversion <literal>src/</literal>, que + está disponível em + <literal>svn://svn.FreeBSD.org/base/</literal>.</para> + + <para>Isto significa que os logs das alterações + realizadas nestes arquivos é visível para qualquer + um, e qualquer pessoa pode utilizar o + <application>svn</application> para ver as + alterações.</para> + + <para>Em adição, muitas pessoas escreveram + tutoriais ou outros web sites relacionados ao FreeBSD. + Alguns destes trabalhos também estão armazenados + no repositório Subversion (com a permissão + do autor). Em outros casos o autor decidiu manter o seu + documento separado do repositório principal do FreeBSD. + O FDP se esforça tanto quanto possível para + fornecer os links para estes documentos.</para> + + </sect1> + + <sect1 id="overview-before"> + <title>Antes de você iniciar</title> + + <para>Este documento assume que você já sabe:</para> + + <itemizedlist> + <listitem> + <para>Como manter uma cópia local atualizada da + documentação do &os;, através da + manutenção de uma cópia local do + repositório Subversion do FreeBSD utilizando o + <application>svn</application>.</para> + </listitem> + + <listitem> + <para>Como obter e instalar um novo software utilizando o + sistema de ports ou o &man.pkg.add.1; do FreeBSD.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="overview-quick-start"> + <title>Início Rápido</title> + + <para>Se você deseja ir começando, e se sente + seguro de que pode ir pegando as coisas à medida que + avança, siga estas instruções.</para> + + <procedure> + <step> + <para>Instale o meta-port <filename role="package"> + textproc/docproj</filename>.</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput> +&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + </step> + + <step> + <para>Obtenha uma cópia local da árvore de + documentação do FreeBSD (<filename>doc</filename>) + utilizando o <application>svn</application>.</para> + + <para>Se a velocidade da sua conexão ou se o espaço de + armazenamento do seu disco local forem motivo de + preocupação, o mínimo que você + vai precisar será uma cópia de trabalho dos + diretórios <filename>head/share</filename>, e + <filename>head/<replaceable>idioma</replaceable>/share</filename> + . Por exemplo:</para> + + <screen>&prompt.user; <userinput>mkdir -p head/share</userinput> +&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput> +&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/share head/share</userinput> +&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen> + + <para>Se você tiver abundância de espaço + em disco, você pode retirar uma cópia de + trabalho completa (de todos os subdiretórios da + árvore doc).</para> + + <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head head</userinput></screen> + + </step> + + <step> + <para>Se você está preparando uma + alteração de um artigo ou livro existente, + retire uma versão de trabalho do arquivo do + repositório. Se você está planejando + contribuir com um novo livro ou artigo, então + utilize um dos existentes como guia.</para> + + <para>Por exemplo, se você deseja contribuir com um + novo artigo sobre como configurar uma VPN entre o FreeBSD + e o Windows 2000, você pode fazer o seguinte:</para> + + <procedure> + <step> + <para>Retire uma cópia de trabalho do + diretório <filename>articles</filename>.</para> + + <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen> + + </step> + + <step> + <para>Copie um artigo existente para utilizar como + template. Neste caso, você decidiu que o seu + novo artigo iria para um diretório chamado + <filename>vpn-w2k</filename>.</para> + + <screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput> +&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen> + + </step> + </procedure> + + <para>Se você deseja editar um documento existente, + como por exemplo o FAQ, o qual está em <filename> + head/en_US.ISO8859-1/books/faq</filename>, você deve + retirar a cópia de trabalho do repositório + da seguinte forma:</para> + + <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq</userinput></screen> + + </step> + + <step> + <para>Edite os arquivos <filename>.sgml</filename> + utilizando o editor da sua preferência.</para> + </step> + + <step> + <para>Teste a marcação SGML utilizando o alvo + <maketarget>lint</maketarget> com o comando make. Isto + irá listar rapidamente qualquer erro existente no + documento sem realizar qualquer tipo de + transformação no seu arquivo, o que + consumiria tempo.</para> + + <screen>&prompt.user; <userinput>make lint</userinput></screen> + + <para>Quando você estiver pronto para efetivamente + compilar o documento, você pode especificar um + único formato ou uma lista de formatos de destino, + na variável <varname>FORMATS</varname>. Atualmente + os formatos suportados são, <literal>html</literal>, + <literal>html-split</literal>, <literal>txt</literal>, + <literal>ps</literal>, <literal>pdf</literal>, e + <literal>rtf</literal>. A lista mais atualizada dos + formatos suportados está listada no início do + arquivo <filename>head/share/mk/doc.docbook.mk</filename>. + Certifique-se de utilizar aspas + (<literal>"</literal>) em volta da lista de formatos quando + você estiver compilando mais de um formato num + único comando.</para> + + <para>Por exemplo, para converter o documento apenas para + <literal>html</literal>, você deve utilizar:</para> + + <screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen> + + <para>Mas quando você deseja converter o documento + tanto para o formato <literal>html</literal> quanto para + o formato <literal>txt</literal>, você pode utilizar + duas execuções separadas do &man.make.1;, + como a seguir:</para> + + <screen>&prompt.user; <userinput>make FORMATS=html</userinput> +&prompt.user; <userinput>make FORMATS=txt</userinput></screen> + + <para>ou, você pode fazer isso em um único + comando:</para> + + <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen> + </step> + + <step> + <para>Envie suas alterações utilizando o + &man.send-pr.1;.</para> + </step> + </procedure> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..7d4566414d --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,195 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<chapter id="psgml-mode"> + <title>Usando <literal>sgml-mode</literal> com o + <application>Emacs</application></title> + + <para>As versões recentes do <application>Emacs</application> + ou <application>XEmacs</application> (disponível na + coleção dos <literal>ports</literal>) contêm + um pacote muito útil chamado PSGML (ele pode ser instalado + pelo <filename role="package">editors/psgml</filename>). Ele + é automaticamente invocado quando um arquivo com a + extensão <filename>.sgml</filename> é carregado, ou + executando <command>M-x sgml-mode</command>, ele é a + modalidade principal para tratar dos elementos e dos atributos de + um arquivo SGML.</para> + + <para>Compreender alguns dos comandos fornecidos por esta modalidade + pode tornar o trabalho com os documentos em SGML, tais como o + Handbook, muito mais fácil.</para> + + <variablelist> + <varlistentry> + <term><command>C-c C-e</command></term> + + <listitem> + <para>Executa o <function>sgml-insert-element</function>. + Você será questionado sobre o nome do elemento + que deseja inserir no ponto atual. Você pode usar a + tecla <keycap>TAB</keycap> para completar o elemento. + Os elementos que são inválidos no ponto + atual não serão permitidos.</para> + + <para>As tags de abertura e de fechamento para o elemento + serão inseridas. Se o elemento contiver outro, + obrigatórios, os elementos destes também + serão inseridos.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c =</command></term> + + <listitem> + <para>Executa o <function>sgml-change-element-name</function>. + Coloque o cursor dentro de um elemento e execute este + comando. Você será questionado sobre o nome do + elemento para o qual você deseja mudar. As tags de + abertura e de fechamento do elemento atual serão + alterados para o novo elemento.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-r</command></term> + + <listitem> + <para>Executa o <function>sgml-tag-region</function>. + Selecione algum texto (posicione o cursor no começo + do texto, de <command>C-espaço</command>, agora + posicione o cursor no final do texto, + de <command>C-espaço</command>) e + execute então este comando. Você + será questionado sobre o nome do elemento que deseja + inserir. Este elemento será inserido então + imediatamente antes e depois da região + marcada.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c -</command></term> + + <listitem> + <para>Executa o <function>sgml-untag-element</function>. + Coloque o cursor dentro da tag de abertura ou de fechamento + do elemento que você quer remover, e execute este + comando. As tags de abertura ou de fechamento do elemento + serão removidas.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-q</command></term> + + <listitem> + <para>Executa o <function>sgml-fill-element</function>. + Irá reformatar recursivamente o elemento atual. A + reformatação <emphasis>afetará + </emphasis> o conteúdo em que os espaços em + branco são significativos, como dentro de elementos + <sgmltag>programlisting</sgmltag>, assim utilize este + comando com cuidado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-a</command></term> + + <listitem> + <para>Executa o <function>sgml-edit-attributes</function>. + Abre um segundo <literal>buffer</literal> que contém + uma lista de todos os atributos e valores atuais para o + elemento mais próximo. Use a tecla + <keycap>TAB</keycap> para navegar entre os atributos, + utilize <command>C-k</command> para remover um + valor existente e para substituí-lo com um novo, + utilize <command>C-c C-c</command> para fechar este + <literal>buffer</literal> e para retornar ao documento + principal.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-v</command></term> + + <listitem> + <para>Executa o <function>sgml-validate</function>. + Você será questionado se deseja salvar + o documento atual (se necessário) e então + executa uma validação do SGML. + A saída da validação é + capturada em um novo <literal>buffer</literal>, e + você poderá então navegar de + um foco de problema para outro, corrigindo os erros + de marcação durante este processo.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c /</command></term> + <listitem> + <para>Executa <function>sgml-insert-end-tag</function>. + Insere a tag de fechamento para o elemento atual que + está aberto.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Sem dúvida há outras funções + úteis desta modalidade, mas estas são as que + você irá utilizar com mais frequência.</para> + + <para>Você também pode usar as seguintes entradas no + <filename>.emacs</filename> para ajustar o espaçamento + apropriado, a identação, e a largura de coluna para + trabalhar com o projeto de documentação.</para> + + <programlisting> (defun local-sgml-mode-hook + (setq fill-column 70 + indent-tabs-mode nil + next-line-add-newlines nil + standard-indent 4 + sgml-indent-data t) + (auto-fill-mode t) + (setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))) + (add-hook 'psgml-mode-hook + '(lambda () (local-psgml-mode-hook)))</programlisting> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..78ebc0dbc9 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,139 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<chapter id="see-also"> + <title>Veja também</title> + + <para>Este documento não é deliberadamente uma + discussão exaustiva sobre SGML, DTDs, ou do projeto de + documentação do FreeBSD. Para obter maiores + informações, sugerimos que você visite os + seguintes sítios web.</para> + + <sect1 id="see-also-fdp"> + <title>Projeto de documentação do FreeBSD</title> + + <itemizedlist> + <listitem> + <para><ulink + url="&url.base;/docproj/index.html">Páginas web do + Projeto de documentação do + FreeBSD</ulink></para> + </listitem> + + <listitem> + <para><ulink url="&url.books.handbook;/index.html">Manual do + FreeBSD</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="see-also-sgml"> + <title>SGML</title> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.oasis-open.org/cover/">Página web + sobre SGML/XML,</ulink> referências detalhadas sobre + SGML</para> + </listitem> + + <listitem> + <para><ulink + url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"> + Uma breve introdução ao SGML</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="see-also-html"> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.w3.org/">Consórcio + <literal>World Wide Web</literal></ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.w3.org/TR/REC-html40/">As + especificações do HTML 4.0</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="see-also-docbook"> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oasis-open.org/docbook/">O + comitê técnico do DocBook</ulink>, + responsáveis pelo DTD DocBook.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.docbook.org/">DocBook: O guia + definitivo</ulink>, documentação online para + o DTD DocBook.</para> + + </listitem> + + <listitem> + <para><ulink + url="http://docbook.sourceforge.net/">Repositório + aberto de DocBook</ulink> contém folhas de estilo + DSSSL e outros recursos para pessoas que utilizam + DocBook.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="see-also-linuxdoc"> + <title>Projeto de documentação do Linux</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.tldp.org/">Pagínas web + do projeto de documentação do Linux</ulink> + </para> + </listitem> + </itemizedlist> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..eb54dbfe27 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,3040 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38851 + +--> + +<chapter id="sgml-markup"> + <title>Marcação SGML</title> + + <para>Esse capítulo descreve as duas linguagens de + marcação que você vai encontrar quando for + contribuir para o projeto de documentação do + FreeBSD. Cada seção descreve a linguagem de + marcação, e detalha a marcação que + você provavelmente vai querer usar ou que já + está utilizando.</para> + + <para>Estas linguagens de marcação contém um + grande número de elementos, e as vezes pode ser + confuso escolher qual elemento usar em uma situação + específica. Esta seção apresenta os elementos + que provavelmente você vai precisar e fornece exemplos de + como utilizá-los.</para> + + <para>Esta <emphasis>não</emphasis> é uma lista + detalhada de elementos, uma vez que ela apenas ratifica a + documentação de cada linguagem. O objetivo desta + seção é listar os elementos mais + úteis para você. Se você tiver alguma + dúvida sobre qual a melhor forma de marcar um pedaço + específico do seu documento, por favor, envie a sua + dúvida para a &a.doc;.</para> + + <note> + <title>Inline Versus Block</title> + + <para>No restante deste documento, quando descrevermos um elemento + como <emphasis>inline</emphasis> significará que o elemento + pode ocorrer dentro de um bloco de elementos, que ele não + acarretará em uma quebra de linha. Um elemento + <emphasis>block</emphasis>, por comparação, irá + causar uma quebra de linha (e outros processamentos) quando for + encontrado.</para> + </note> + + <sect1 id="sgml-markup-html"> + <title>HTML</title> + + <para>O HTML, Linguagem de Marcação de Hypertexto, + é a linguagem de marcação escolhida para a + <literal>World Wide Web</literal>. Maiores informações + podem ser encontradas em + <ulink url="http://www.w3.org/"></ulink>.</para> + + <para>O HTML é utilizado para a marcação das + páginas do web site do FreeBSD. Ele não deveria ser + utilizado (geralmente) para marcar outros tipos de documentos + já que o <literal>DocBook</literal> oferece uma maior + variedade de elementos. Consequentemente, você só + irá encontrar páginas em HTML se estiver escrevendo + para o web site.</para> + + <para>O HTML já passou por algumas versões, 1, 2, 3.0, + 3.2 e a última, 4.0 (disponível nas duas variantes, + <emphasis>strict</emphasis> e <emphasis>loose</emphasis>).</para> + + <para>Os HTML DTD's estão disponíveis na + coleção de <literal>ports</literal> na pasta + <filename role="package">textproc/html</filename>. Eles + são automaticamente instalados como parte do + <literal>port</literal> + <filename role="package">textproc/docproj</filename></para> + + <sect2> + <title>Identificador Público Formal (IPF)</title> + + <para>Existem vários IPF's para o HTML, os quais dependem + da versão (também conhecida como nível) + do HTML que você quer declarar compatível com seu + documento.</para> + + <para>A maioria dos documentos HTML no web site do + FreeBSD estão de acordo com a versão + <literal>loose</literal> do HTML 4.0.</para> + + <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Elementos de Seção</title> + + <para>Um documento HTML é normalmente dividido em duas + partes. A primeira é chamada de + <emphasis>head</emphasis>, a qual contém + meta-informações sobre o documento, tais como o + seu título, o nome do autor, o documento pai e assim por + diante. A segunda parte, o <emphasis>body</emphasis> é + contém o conteúdo que vai ser exibido para o + usuário.</para> + + <para>Estas seções são indicadas pelos + elementos <sgmltag>head</sgmltag> e <sgmltag>body</sgmltag>, + respectivamente. Esses elementos estão contidos dentro + de um elemento <sgmltag>html</sgmltag> de alto-nível.</para> + + <example> + <title>Estrutura Normal de um Documento HTML</title> + + <programlisting><html> + <head> + <title><replaceable>Título do Documento</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Bloco de Elementos</title> + + <sect3> + <title>Cabeçalho</title> + + <para>O HTML permite a denotação de + cabeçalho em seu documento, de até seis + níveis diferentes. </para> + + <para>O maior e mais proeminente cabeçalho é o + <sgmltag>h1</sgmltag>, depois vem o <sgmltag>h2</sgmltag>, + assim por diante até <sgmltag>h6</sgmltag>. + </para> + + <para>O conteúdo dos elementos é o texto do + cabeçalho.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, e + outras Tags de Header.</title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<h1>Primeira seção</h1> + +<!-- a introdução do documento entra aqui --> + +<h2>Este é o cabeçalho da primeira seção</h2> + +<!-- O conteúdo da primeira seção entra aqui --> + +<h3>Este é o cabeçalho da primeira subseção</h3> + +<!-- O conteúdo da primeira subseção entra aqui --> + +<h2>Este é o heading para a segunda seção</h2> + +<!-- O conteúdo da segunda seção entra aqui -->]]></programlisting> + </example> + + <para>Geralmente, uma página HTML deveria ter um + cabeçalho de primeiro nível + (<sgmltag>h1</sgmltag>). Este poderia conter muitos + cabeçalhos de segundo nível + (<sgmltag>h2</sgmltag>), os quais por sua vez podem conter + muitos cabeçalhos de terceiro nível. Cada + elemento <sgmltag>h<replaceable>n</replaceable></sgmltag> + deve ter o mesmo elemento, sendo que os elementos mais acima + na hierarquia estarão subtraídos de um. Deve-se evitar + buracos na numeração.</para> + + <example> + <title>Má organização de elementos + <sgmltag>h<replaceable>n</replaceable></sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<h1>Primeira seção</h1> + +<!-- Introdução do documento --> + +<h3>Subseção</h3> + +<!-- Isto é ruim, não foi usado <h2> -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Parágrafos</title> + + <para>O HTML suporta elementos formados de um único + parágrafo <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Isto é um parágrafo. Pode conter qualquer outro elemento</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Bloco de Citação</title> + + <para>Um bloco de citação é uma + citação estendida de outro documento que + não deveria aparecer no parágrafo + atual.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Um pequeno trecho da constituição dos Estados Unidos:</p> + +<blockquote> +Nós, povo dos Estados Unidos, com o objetivo de fazer uma +união mais perfeita, estabelecer justiça, garantir +tranquilidade doméstica, promover uma defesa comum, promover +bem estar geral, assegurar as benções da liberdade para +nós mesmos e nossa posteridade, organizamos e estabelecemos +essa constituição para os estados Unidos da América. +</blockquote>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Listas</title> + + <para>Você pode apresentar ao usuário três + tipos de listas, ordenadas, desordenadas e de + definição. + </para> + + <para>Tipicamente, cada entrada em uma lista ordenada, + é numerada enquanto nas listas desordenadas + serão processadas por um bullet point. Listas de + definição são compostas de duas + partes para cada entrada a primeira é o termo a ser + definido, e a segunda, é a definição + em si.</para> + + <para>As Listas ordenadas, desordenadas e de + definição, são indicadas pelos + elementos <sgmltag>ol</sgmltag>, <sgmltag>ul</sgmltag> e + <sgmltag>dl</sgmltag>, respectivamente.</para> + + <para>Listas ordenadas e desordenadas contém itens de + lista, indicados pelo elemento <sgmltag>li</sgmltag>. Um + item de lista pode conter texto, podendo inclusive conter + um ou mais elementos <sgmltag>p</sgmltag>.</para> + + <para>Listas de definição contém o termo + a ser definido (<sgmltag>dt</sgmltag>) e a + descrição do termo (<sgmltag>dd</sgmltag>). + A definição de um termo só pode conter + elementos <literal>inline</literal>. A + descrição do termo pode conter elementos do + tipo <literal>block</literal>.</para> + + <example> + <title><sgmltag>ul</sgmltag> e <sgmltag>ol</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Uma lista não ordenada. Os itens serão provavelmente +precedidos por uma esfera sólida.</p> + +<ul> + <li>Primeiro item</li> + + <li>Segundo item</li> + + <li>Terceiro item</li> +</ul> + +<p>Uma lista ordenada, com itens de lista com vários +parágrafos. Cada item (nota: não cada parágrafo) +será numerado.</p> + +<ol> + <li><p>Este é o primeiro item. Tem apenas um parágrafo.</p></li> + + <li><p>Este é o primeiro parágrafo do segundo item.</p> + + <p>Este é o segundo parágrafo do segundo item.</p></li> + + <li><p>Este é o primeiro e único parágrafo do terceiro item.</p></li> +</ol>]]></programlisting> + </example> + + <example> + <title>Listas de Definição com + <sgmltag>dl</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<dl> + <dt>Termo 1</dt> + + <dd><p>Parágrafo 1 da definição 1.</p> + + <p>Parágrafo 2 da definição 1.</p></dd> + + <dt>Termo 2</dt> + + <dd><p>Parágrafo 1 da definição 2.</p></dd> + + <dt>Termo 3</dt> + + <dd><p>Parágrafo 1 da definição 3.</p></dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Texto Pré-Formatado</title> + + <para>Você pode indicar que o texto deve ser + apresentado exatamente como esta no arquivo. Tipicamente, + isto significa que o texto será mostrado em fonte fixa, + múltiplos espaços não serão fundidos em + um e que as quebras de linha no texto serão + significativas.</para> + + <para>Para fazer isto, envolva o conteúdo com o + elemento <sgmltag>pre</sgmltag>:</para> + + <example> + <title><sgmltag>pre</sgmltag></title> + + <para>Você pode usar <sgmltag>pre</sgmltag> para + marcar uma mensagem de email;</para> + + <programlisting><![ RCDATA [<pre> + From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N +</pre>]]></programlisting> + + <para>Tenha em mente que o <literal><</literal> e o + <literal>&</literal> continuam sendo reconhecidos como + caracteres especiais em um texto pré-formatado. + É por isto que nos exemplos tivemos que utilizar + <literal>&lt;</literal> ao invés de + <literal><</literal>. Para manter a consistência, + o <literal>&gt;</literal> também foi utilizado + no lugar do <literal>></literal>. Fique atento para + caracteres especiais que podem aparecer em textos copiados + de origens não formatadas, como por exemplo, de uma + mensagem de email ou do código fonte de um + programa.</para> + + </example> + </sect3> + + <sect3> + <title>Tabelas</title> + + <note> + <para>A maioria dos navegadores de modo texto (tal como o + Lynx) não apresentam tabelas de maneira muito + eficiente. Se você quiser que o seu conteúdo + seja apresentado em forma de tabelas, você deve + considerar outra marcação para evitar + problemas.</para> + </note> + + <para>Marque a informação tabular com o elemento + <sgmltag>table</sgmltag>. Uma tabela consiste de uma ou + mais linhas (<sgmltag>tr</sgmltag>), cada uma contendo uma + ou mais células de dados (<sgmltag>td</sgmltag>). + As células podem conter outros elementos de bloco, + como parágrafos ou listas. Também pode + conter outra tabela (este aninhamento pode ser repetido + indefinidamente). Se a célula contém apenas + um parágrafo, então não é + necessário incluir o elemento <sgmltag>p</sgmltag>.</para> + + <example> + <title>Uso Simples de <sgmltag>table</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Esta é uma simples tabela 2x2.</p> + +<table> + <tr> + <td>Célula esquerda superior</td> + + <td>Célula direita superior</td> + </tr> + + <tr> + <td>Célula esquerda inferior</td> + + <td>Célula direita inferior</td> + </tr> +</table>]]></programlisting></example> + + <para>Uma célula pode se estender por muitas linhas + e colunas. Para indicar isto, coloque o atributo + <literal>rowspan</literal> e/ou <literal>colspan</literal>, + com valores que indiquem o número de linhas ou + colunas a serem ocupados.</para> + + <example> + <title>Utiliizando <literal>rowspan</literal></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Uma célula comprida e estreita na esquerda e duas +células pequenas à direita.</p> + +<table> + <tr> + <td rowspan="2">Comprida e estreita</td> + </tr> + + <tr> + <td>Célula superior</td> + + <td>Célula inferior</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Usando <literal>colspan</literal></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Uma célula longa em cima, duas células abaixo.</p> + +<table> + <tr> + <td colspan="2">Célula superior</td> + </tr> + + <tr> + <td>Célula inferior esquerda</td> + + <td>Célula inferior direita</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Usando <literal>rowspan</literal> e + <literal>colspan</literal> juntos</title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Numa tabela 3x3, o bloco superior esquerdo é um conjunto +2x2 fundidos em um. As outras células são normais.</p> + +<table> + <tr> + <td colspan="2" rowspan="2">Célula esquerda superior grande</td> + + <td>Célula direita superior</td> + </tr> + + <tr> + <!-- Como a célula grande à esquerda funde-se com esta linha, + o primeiro <td> ocorrerá à a sua direita. --> + <td>Célula do meio a direita</td> + </tr> + + <tr> + <td>Célula inferior esquerda</td> + + <td>Célula inferior central</td> + + <td>Célula inferior direita</td> + </tr> +</table>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Elementos In-line</title> + + <sect3> + <title>Enfatizando a Informação</title> + + <para>Você tem dois níveis de ênfase + disponíveis em HTML, <sgmltag>em</sgmltag> e + <sgmltag>strong</sgmltag>. O <sgmltag>em</sgmltag> é + para uma ênfase simples e o <sgmltag>strong</sgmltag> + indica uma ênfase mais forte.</para> + + <para>Em geral, <sgmltag>em</sgmltag> é apresentada em + itálico e <sgmltag>strong</sgmltag> é + apresentada em negrito. Mas nem sempre é assim, e + você não deve contar com isso.</para> + + <example> + <title><sgmltag>em</sgmltag> e <sgmltag>strong</sgmltag> + </title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p><em>Este</em> foi enfatizado +enquanto <strong>este</strong> foi fortemente enfatizado.</p>]]> + </programlisting> + </example> + </sect3> + + <sect3> + <title>Negrito e Itálico</title> + + <para>Uma vez que o HTML inclui marcação de + apresentação, você também pode + indicar que um conteúdo deve ser apresentado em + negrito ou itálico. Os elementos são + <sgmltag>b</sgmltag> e <sgmltag>i</sgmltag> + respectivamente.</para> + + <example> + <title><sgmltag>b</sgmltag> e <sgmltag>i</sgmltag></title> + + <programlisting><![ RCDATA [<p><b>Este</b> esta em negrito, +enquanto <i>este</i> está em itálico.</p>]]> + </programlisting> + </example> + </sect3> + + <sect3> + <title>Indicando Texto de Fonte Fixa</title> + + <para>Se você tiver conteúdo que deve ser + apresentado em fonte fixa (typewriter), use + <sgmltag>tt</sgmltag> (de <quote>teletipo</quote>).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p> Este documento foi originalmente por +Nik Clayton, que pode ser encontrado por email em +<tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Tamanho do Conteúdo</title> + + <para>Você pode indicar que o conteúdo deve ser + apresentado em uma fonte maior ou menor. Existem + três maneiras de fazer isto:</para> + + <orderedlist> + <listitem> + <para>Use <sgmltag>big</sgmltag> e + <sgmltag>small</sgmltag> + em torno do texto que você deseja mudar o + tamanho. Estas tags podem ser aninhadas, assim + <literal><big><big>Este é muito + maior</big></big></literal> é + possível.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> com o atributo + <literal>size</literal> ajustado para + <literal>+1</literal> ou <literal>-1</literal> + respectivamente. Isto tem o mesmo efeito que + <sgmltag>big</sgmltag> ou <sgmltag>small</sgmltag>. + Entretanto esta forma está ultrapassada.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> com o atributo + <literal>size</literal> com um número entre + <literal>1</literal> e <literal>7</literal>. + O tamanho da fonte padrão é + <literal>3</literal>. Esta forma está + ultrapassada.</para> + </listitem> + </orderedlist> + + <example> + <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, e + <sgmltag>font</sgmltag></title> + + <para>Todos os fragmentos fazem a mesma coisa.</para> + + <programlisting><![ RCDATA [<p>Este texto é <small>ligeiramente menor</small>. +Mas este texto é <big>ligeiramente maior</big>.</p> + +<p>Este texto é <font size="-1">ligeiramente menor</font>. +Mas este texto é <font size="+1">ligeiramente maior</font>.</p> + +<p>Este texto é <font size="2">ligeiramente menor</font>. +Mas este texto é <font size="4">ligeiramente maior</font>.</p>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Os links também são elementos in-line.</para> + </note> + + <sect3> + <title>Ligando-se a Outros Documentos</title> + + <para>Para incluir um link para outro documento na WWW + você deve saber o URL do documento ao qual deseja se + ligar.</para> + + <para>O link é indicado com <sgmltag>a</sgmltag>, e o + atributo <literal>href</literal> contém o URL do + documento de destino. O conteúdo do elemento se torna o + link, e geralmente é indicado para o usuário + de alguma maneira (sublinhado, mudança de cor, o + formato do cursor do mouse muda quando está sobre + ele, etc.</para> + + <example> + <title>Usando <literal><a href="..."></literal> + </title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p>Maiores informações estão disponíveis no +<a href="http://www.FreeBSD.org/">web site do FreeBSD</a>.</p>]]></programlisting> + </example> + + <para>Este link irá levar o usuário ao topo do + documento escolhido.</para> + </sect3> + + <sect3> + <title>Ligando-se a Outras Partes de um Documento</title> + + <para>Para fazer um link a um ponto dentro de outro + documento (ou dentro do mesmo documento), é + necessário que o autor do documento inclua + âncoras ao qual você possa se ligar.</para> + + <para>Âncoras são indicadas com + <sgmltag>a</sgmltag> e o atributo <literal>name</literal> + ao invés de <literal>href</literal>.</para> + + <example> + <title>Usando <literal><a name="..."></literal> + </title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<p><a name="para1">Este</a> parágrafo pode ser referenciado +em outros links com o nome<tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>Para fazer um link a uma determinada parte de um + documento, faça um link normal para aquele documento, + mas inclua o nome da âncora após o + símbolo <literal>#</literal>.</para> + + <example> + <title>Link para uma determinada parte de outro + documento</title> + + <para>Suponha que o exemplo <literal>para1</literal> esteja + em um documento chamado <filename>foo.html</filename>. + </para> + + <programlisting><![ RCDATA [<p>Mais informação no <a href="foo.html#para1">primeiro +parágrafo</a> de <tt>foo.html</tt>.</p>]]> + </programlisting> + </example> + + <para>Se você for incluir um link para uma âncora + dentro do mesmo documento você pode omitir o URL do + documento, e usar apenas o nome da âncora (precedido + por <literal>#</literal>).</para> + + <example> + <title>Links para determinada parte do mesmo + documento</title> + + <para>Suponha que o exemplo <literal>para1</literal> esteja neste documento</para> + + <programlisting><![ RCDATA [<p>Mais informação no <a href="#para1">primeiro +parágrafo</a> deste documento.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1 id="sgml-markup-docbook"> + <title>DocBook</title> + + <para>O DocBook foi originalmente desenvolvido por HaL Computer + Systems e O'Reilly & Associates como um DTD para escrever + documentação técnica + <footnote><para>Uma pequena história sobre este assunto + pode ser encontrada em + <ulink url="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> + http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>. + </para></footnote>. E desde 1998 tem sido mantido pelo + <ulink + url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</ulink>. Desta forma, ao + contrário do LinuxDoc e do HTML, o DocBook é + fortemente orientado a marcação que descreve + <emphasis>o que</emphasis> é alguma coisa, ao + invés de descrever <emphasis>como</emphasis> ela deve + ser apresentada.</para> + + <note> + <title>Formal Versus Informal</title> + + <para>Alguns elementos podem existir em duas formas, + <emphasis>formal</emphasis> e <emphasis>informal</emphasis>. + Tipicamente, a versão formal dos elementos + consistirá de um título seguido da + versão informal do elemento. A versão informal + não terá um título.</para> + </note> + + <para>O DocBook DTD está disponível na + coleção de ports como + <filename role="package">textproc/docbook</filename>. + Ele é automaticamente instalado como parte do port + <filename role="package">textproc/docproj</filename>.</para> + + <sect2> + <title>Extensões FreeBSD</title> + + <para>O Projeto de Documentação do FreeBSD + ampliou o DocBook DTD adicionando alguns elementos novos. + Estes elementos têm como objetivo tornar algumas + marcações mais precisas.</para> + + <para>Os elementos específicos introduzidos pelo FreeBSD + estarão claramente destacados quando forem listados + abaixo.</para> + + <para>No restante deste documento, o termo + <quote>DocBook</quote> deve ser interpretado como sendo a + versão do DocBook DTD ampliado pelo projeto de + documentação do FreeBSD.</para> + + <note> + <para>Não existe nada nestas extenssões + que seja específico ao FreeBSD, apenas percebemos + que elas seriam melhorias para este projeto em particular. + Se alguém dos demais projetos *nix (NetBSD, OpenBSD, + Linux, ...) tiver interesse em colaborar para a + criação de um conjunto de extensões + DocBook padrão, por favor entre em + contato com &a.doceng;.</para> + </note> + + <para>As extensões &os; não estão + (atualmente) na coleção de ports. Elas + estão armazenadas na árvore Subversion do &os;, + como <ulink + url="http://svnweb.FreeBSD.org/doc/head/share/sgml/freebsd.dtd"> + head/share/sgml/freebsd.dtd</ulink>.</para> + </sect2> + + <sect2> + <title>Identificador Formal Público (IFP)</title> + + <para>De acordo com as diretrizes DocBook para a escrita de + IPF's para adaptação do DocBook, o IPF para + o DocBook estendido do FreeBSD é:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Estrutura dos Documentos</title> + + <para>DocBook permite que você estruture sua + documentação de várias maneiras. No + projeto de documentação do FreeBSD nós + estamos utilizando dois tipos primários de documentos + DocBook: o livro e o artigo.</para> + + <para>Um livro é organizado em + <sgmltag>chapter</sgmltag>s (capítulos). Isso é um + requerimento obrigatório. Podem existir + <sgmltag>part</sgmltag>s (partes) entre o livro e os + capítulos para fornecer mais uma camada de + organização. O Handbook, por exemplo, + é organizado desta maneira.</para> + + <para>Um capítulo pode (ou não) conter uma ou mais + sessões. Estas são indicadas pelo elemento + <sgmltag>sect1</sgmltag>. Se uma sessão + contém outra sessão, então use o + elemento <sgmltag>sect2</sgmltag>, e assim por diante + até <sgmltag>sect5</sgmltag>.</para> + + <para>Capítulos e sessões contém o + restante do conteúdo.</para> + + <para>Um artigo é mais simples do que um livro, e + não usa capítulos. Ao invés disso, o + conteúdo de um artigo é organizado em uma ou + mais sessões, usando os mesmos elementos + <sgmltag>sect1</sgmltag> (e <sgmltag>sect2</sgmltag> e assim por + diante) que são usados nos livros.</para> + + <para>Obviamente, você deve considerar a natureza da + documentação que você esta escrevendo + para poder decidir se é melhor uma + marcação formatada como um livro ou um artigo. + Artigos suportam bem informações + que não precisam ser divididas em capítulos, + isto é, relativamente pequena, com mais ou menos 20 + a 25 páginas de conteúdo. Livros suportam + melhor informações que se dividem em + capítulos com apêndices e conteúdos similares. + </para> + + <para>Os <ulink url="&url.base;/docs.html">tutoriais sobre + FreeBSD</ulink> estão marcados na forma de artigos, + enquanto por exemplo este documento, + o <ulink url="&url.books.faq;/index.html">FAQ do FreeBSD</ulink>, + e o <ulink url="&url.books.handbook;/index.html">Handbook do + FreeBSD</ulink> estão marcados na forma como livros.</para> + + <sect3> + <title>Iniciando um Livro</title> + + <para>O conteúdo de um livro deve estar contido + dentro do elemento <sgmltag>book</sgmltag>. Assim como + outros elementos de marcação estrutural, esse + elemento pode conter elementos que incluam + informações adicionais sobre o livro. Isto + é tanto meta-informação, utilizada para + fins de referência, ou conteúdo adicional + usado para produzir uma página de + título.</para> + + <para>Estas informações adicionais devem estar + contidas dentro do elemento <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Modelo padrão <sgmltag>book</sgmltag> com + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><book> + <bookinfo> + <title><replaceable>Seu título aqui</replaceable></title> + + <author> + <firstname><replaceable>Seu primeiro nome aqui</replaceable></firstname> + <surname><replaceable>Seu sobrenome</replaceable></surname> + <affiliation> + <address><email><replaceable>Seu endereço de correio eletrônico aqui</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>seu endereço de email</replaceable>"><replaceable>Seu nome</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Inclua um resumo do conteúdo do seu livro aqui.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Começando um Artigo</title> + + <para>O conteúdo do artigo deve estar contido dentro + do elemento <sgmltag>article</sgmltag>. Assim como + outros elementos de marcação estrutural, + esse elemento pode conter elementos que incluam + informações adicionais sobre o artigo. + Isto é tanto meta-informação, + utilizada para fins de referência, ou conteúdo + adicional usado para produzir uma página de + título.</para> + + <para>Estas informações adicionais devem estar + contidas dentro do elemento + <sgmltag>articleinfo</sgmltag>.</para> + + <example> + <title>Modelo padrão <sgmltag>article</sgmltag> com + <sgmltag>articleinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><article> + <articleinfo> + <title><replaceable>Seu título aqui</replaceable></title> + + <author> + <firstname><replaceable>Seu primeiro nome</replaceable></firstname> + <surname><replaceable>Seu sobrenome</replaceable></surname> + <affiliation> + <address><email><replaceable>Seu endereço de email</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>seu endereço de email</replaceable>"><replaceable>Seu nome</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Inclua um resumo do conteúdo do artigo aqui.</replaceable></para> + </abstract> + </articleinfo> + + … + +</article></programlisting> + </example> + </sect3> + <sect3> + <title>Indicando Capítulos</title> + + <para>Utilize <sgmltag>chapter</sgmltag> para marcar seus + capítulos. Cada capítulo tem + obrigatoriamente um <sgmltag>title</sgmltag>. + Artigos não contêm capítulos, estes + são reservados para os livros.</para> + + <example> + <title>Um capítulo simples</title> + + <programlisting><![ RCDATA [<chapter> + <title>Título do capítulo</title> + + ... +</chapter>]]></programlisting> + </example> + + <para>Um capítulo não pode ser vazio; ele + precisa conter elementos além do + <sgmltag>title</sgmltag>. Se você precisar incluir + um capítulo vazio então você + precisará incluir um parágrafo vazio.</para> + + <example> + <title>Capítulos Vazios</title> + + <programlisting><![ RCDATA [<chapter> + <title>Isto é um capítulo vazio</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sessões Abaixo dos Capítulos</title> + + <para>Em um livro, os capítulos podem (mas não + é obrigatoriamente necessário) ser + quebrados em seções, subseções, + e assim por diante. Em um artigo, as seções + são os principais elementos estruturais, e cada artigo + deve conter pelo menos uma seção. Utilize o + elemento <sgmltag>sect<replaceable>n</replaceable></sgmltag>. O + <replaceable>n</replaceable> indica o número da + seção o qual identifica o nível da + seção.</para> + + <para>A primeira + <sgmltag>sect<replaceable>n</replaceable></sgmltag> é + <sgmltag>sect1</sgmltag>. Você pode ter uma ou mais + desta em um só capítulo. Elas podem conter + um ou mais elementos <sgmltag>sect2</sgmltag>, e assim por + diante, até <sgmltag>sect5</sgmltag>.</para> + + <example> + <title>Seções em Capítulos</title> + + <programlisting><![ RCDATA [<chapter> + <title>Um exemplo de capítulo</title> + + <para>Algum texto dentro do capítulo</para> + + <sect1> + <title>Primeira seção (1.1)</title> + + … + </sect1> + + <sect1> + <title>Segunda seção (1.2)</title> + + <sect2> + <title>Primeira subseção (1.2.1)</title> + + <sect3> + <title>Primeira sub-subseção (1.2.1.1)</title> + + … + </sect3> + </sect2> + + <sect2> + <title>Segunda subseção (1.2.2)</title> + + … + </sect2> + </sect1> +</chapter>]]></programlisting> + </example> + + <note> + <para>Este exemplo inclui os números das + seções nos títulos de + seções. Você não deve fazer + isso nos seus documentos. A inserção dos + números de seção é realizada + pelas folhas de estilo (falaremos delas mais a frente), e + você não precisa gerenciá-los + manualmente.</para> + </note> + </sect3> + + <sect3> + <title>Subdividindo Utilizando o Elemento + <sgmltag>Part</sgmltag></title> + + <para>Você pode introduzir outra camada de + organização entre <sgmltag>book</sgmltag> e + <sgmltag>chapter</sgmltag> utilizando uma ou mais + <sgmltag>part</sgmltag>s. Isto não pode ser + feito em um <sgmltag>article</sgmltag>.</para> + + <programlisting><![ RCDATA [<part> + <title>Introdução</title> + + <chapter> + <title>Visão Geral</title> + + ... + </chapter> + + <chapter> + <title>O que é FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>História</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Elementos de Blocos</title> + + <sect3> + <title>Parágrafos</title> + + <para>O DocBook suporta três tipos de parágrafos: + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, e + <sgmltag>simpara</sgmltag>.</para> + + <para>Na maioria das vezes você só vai precisar + usar <sgmltag>para</sgmltag>. O + <sgmltag>formalpara</sgmltag> inclui um elemento + <sgmltag>title</sgmltag>, e o <sgmltag>simpara</sgmltag> + desabilita alguns elementos dentro de + <sgmltag>para</sgmltag>. Fique com o + <sgmltag>para</sgmltag>.</para> + + <example> + <title><sgmltag>para</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>Isso é um parágrafo. E pode conter quase + qualquer outro elemento.</para> ]]></programlisting> + + <para>Aparência:</para> + + <para>Isso é um parágrafo. E pode conter + quase qualquer outro elemento.</para> + </example> + </sect3> + + <sect3> + <title>Bloco de Citações</title> + + <para>Um bloco de citação é uma longa + citação de outro documento que não + deveria aparecer no parágrafo atual. Você + não irá usá-lo com muita + frequência.</para> + + <para>Um bloco de citação pode conter + opcionalmente um título e uma atribuição + (ou eles podem ser deixados sem título e sem + atributos)</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>Um pequeno pedaço da Constituição dos Estados Unidos:</para> + +<blockquote> + <title>Preâmbulo da constituição dos Estados Unidos.</title> + + <attribution>Copiado de um site qualquer</attribution> + + <para>Nós, povo dos Estados Unidos, com o objetivo de + fazer uma união mais perfeita, estabelecer justiça, + garantir tranquilidade doméstica, promover uma defesa comum, promover + bem estar geral, assegurar as benções da + liberdade para nós mesmos e nossa posteridade, organizamos e + estabelecemos essa constituição para os estados Unidos + da América.</para> +</blockquote>]]></programlisting> + + <para>Aparência:</para> + + <para>Um pequeno pedaço da + Constituição dos Estados Unidos</para> + + <blockquote> + <title>Preâmbulo da constituição dos Estados Unidos.</title> + + <attribution>Copiado de um site qualquer</attribution> + + <para>Nós, povo dos Estados Unidos, com o objetivo de + fazer uma união mais perfeita, estabelecer justiça, + garantir tranquilidade doméstica, promover uma defesa comum, promover + bem estar geral, assegurar as benções da + liberdade para nós mesmos e nossa posteridade, organizamos e + estabelecemos essa constituição para os estados Unidos + da América.</para> + </blockquote> + </example> + </sect3> + + <sect3> + <title>Dicas, notas, avisos, informações + importantes e sidebars.</title> + + <para>Talvez você precise incluir + informações extras separadas do corpo + principal do texto. Tipicamente isto é + <quote>meta</quote> informação que o + usuário deve tomar conhecimento.</para> + + <para>Dependendo da natureza da informação, + devemos utilizar o elemento <sgmltag>tip</sgmltag>, + <sgmltag>note</sgmltag>, <sgmltag>warning</sgmltag>, + <sgmltag>caution</sgmltag>, ou <sgmltag>important</sgmltag>. + Alternativamente, se a informação é + relacionada ao corpo principal do texto e não se + encaixa em nenhum dos objetos acima, utilize + <sgmltag>sidebar</sgmltag>.</para> + + <para>As circunstâncias na qual se deve escolher um elemento ao invés + do outro não é clara. A documentação do DocBook sugere que: +</para> + + <itemizedlist> + <listitem> + <para>A <sgmltag>note</sgmltag> é uma + informação que deve ser lida por todos + os leitores.</para> + </listitem> + + <listitem> + <para>A <sgmltag>important</sgmltag> é uma + variação do <sgmltag>note</sgmltag>. + </para> + </listitem> + + <listitem> + <para>A <sgmltag>caution</sgmltag> é usada para + informar sobre uma possível perda de dados ou + possível dano causado pelo software.</para> + </listitem> + + <listitem> + <para>O <sgmltag>warning</sgmltag> é usado para + informações sobre possíveis danos + ao hardware, sobre risco de vida ou de ferimento a um + membro.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<warning> +<para>Instalar o FreeBSD talvez faça com que você queira +desinstalar o Windows do seu Hard disk.</para> +</warning>]]></programlisting> + </example> + + <para>Aparência:</para> + <!-- Need to do this outside of the example --> + <warning> + <para>Instalar o FreeBSD talvez faça com que + você queira desinstalar o Windows do seu Hard + disk.</para> + </warning> + </sect3> + + <sect3> + <title>Listas e Procedimentos</title> + + <para>Você frequentemente vai precisar listar + fragmentos de informação para o + usuário, ou apresentar para eles um passo a passo + o qual eles devem seguir para alcançar um objetivo + específico.</para> + + <para>Para fazer isso, utilize + <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, ou + <sgmltag>procedure</sgmltag> <footnote><para>Há + outros tipos de elementos de lista no DocBook, mas + não vamos nos preocupar com eles no momento.</para> + </footnote>. + </para> + + <para>Os elementos <sgmltag>itemizedlist</sgmltag> e + <sgmltag>orderedlist</sgmltag> são similares aos + seus equivalentes em HTML, <sgmltag>ul</sgmltag> e + <sgmltag>ol</sgmltag>. Cada um consiste de um ou mais + elementos <sgmltag>listitem</sgmltag>, e cada + <sgmltag>listitem</sgmltag> contém um ou mais + elementos de bloco. O elemento <sgmltag>listitem</sgmltag> + é analogo à <sgmltag>li</sgmltag> do HTML. + Entretanto, ao contrário do que ocorre no HTML, aqui + elas são obrigatórias.</para> + + <para>O elemento <sgmltag>procedure</sgmltag> é + ligeiramente diferente. Ele consiste de + <sgmltag>step</sgmltag>s, que por sua vez consistem de + mais <sgmltag>step</sgmltag>s ou + <sgmltag>substep</sgmltag>s. Cada <sgmltag>step</sgmltag> + contém elementos de bloco.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, e + <sgmltag>procedure</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<itemizedlist> + <listitem> + <para>Esse é o primeiro item enumerado.</para> + </listitem> + + <listitem> + <para>Esse é o segundo item enumerado.</para> + </listitem> +</itemizedlist> + +<orderedlist> + <listitem> + <para>Esse é o primeiro item ordenado.</para> + </listitem> + + <listitem> + <para>Esse é o segundo item ordenado.</para> + </listitem> +</orderedlist> + +<procedure> + <step> + <para>Faça isto.</para> + </step> + + <step> + <para>Depois faça isto.</para> + </step> + + <step> + <para>E agora faça isto.</para> + </step> +</procedure>]]></programlisting> + + <para>Aparência:</para> + + <itemizedlist> + <listitem> + <para>Esse é o primeiro item enumerado.</para> + </listitem> + + <listitem> + <para>Esse é o segundo item enumerado.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>Esse é o primeiro item ordenado.</para> + </listitem> + + <listitem> + <para>Esse é o segundo item ordenado.</para> + </listitem> + </orderedlist> + </example> + + <!-- Can't have <procedure> inside <example>, so this is a cheat --> + + <procedure> + <step> + <para>Faça isto.</para> + </step> + + <step> + <para>Depois faça isto.</para> + </step> + + <step> + <para>E agora faça isto.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Mostrando Amostras de Arquivos</title> + + <para>Se você quiser mostrar um trecho de um + arquivo (ou talvez um arquivo inteiro) ao usuário, + use o elemento <sgmltag>programlisting</sgmltag></para> + + <para>Espaços e quebras de linha + <emphasis>são</emphasis> importantes dentro do + <sgmltag>programlisting</sgmltag>. Em particular, isso + significa que a tag de abertura deve aparecer na mesma + linha que a primeira linha do programa, e a tag de + fechamento deve estar na última linha do programa, + do contrário linhas em branco espúrias podem ser + incluídas.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA[<para>Quando você tiver terminado, seu programa deve estar assim:</para> + +<programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Note como os colchetes na linha + <literal>#include</literal> precisaram ser referenciados + através de suas entidades ao invés de + incluídas literalmente.</para> + + <para>Aparência:</para> + + <para>Quando você tiver terminado, seu programa + deve estar assim;</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + </sect3> + + <sect3> + <title>Chamadas</title> + + <para>Uma chamada é um mecanismo para fazer + referência a um pedaço de texto ou uma + posição específica de um exemplo + anterior sem ligar a ele no texto.</para> + + <para>Para fazer isso, marque as áreas de interesse + no seu exemplo (<sgmltag>programlisting</sgmltag>, + <sgmltag>literallayout</sgmltag>, ou o que for) com o + elemento <sgmltag>co</sgmltag>. Cada elemento deve ter + um <literal>id</literal> único atribuído a ele. + Insira um <sgmltag>calloutlist</sgmltag> no final do + exemplo acima fazendo referência de volta a ele, + exibindo comentários adicionais.</para> + + <example> + <title><sgmltag>co</sgmltag> e + <sgmltag>calloutlist</sgmltag></title> + + <programlisting><![ RCDATA[<para>Quando você tivert terminado, seu prograva deve estar assim;</para> + +<programlisting>#include <stdio.h> <co id="co-ex-include"/> + +int <co id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co id="co-ex-printf"/> +}</programlisting> + +<calloutlist> + <callout arearefs="co-ex-include"> + <para>Inclui o arquivo padrão de IO.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Especifica que <function>main()</function> retorna um inteiro.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>A chamada <function>printf()</function> que escreve <literal>hello, + world</literal> na saída padrão.</para> + </callout> +</calloutlist>]]></programlisting> + + <para>Aparência:</para> + + <para>Quando você tiver terminado, seu programa + deve estar assim;</para> + + <programlisting>#include <stdio.h> <co id="co-ex-include"/> + +int <co id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para>Inclui o arquivo padrão de IO.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Especifica que <function>main()</function> retorna um + inteiro.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>A chamada <function>printf()</function> escreve + <literal>hello, world</literal> na saída padrão + </para> + </callout> + </calloutlist> + </example> + </sect3> + + <sect3> + <title>Tabelas</title> + + <para>Ao contrário do HTML, você não + precisa usar tabelas para acertar o layout, as folhas de + estilo cuidam disto para você. Utilize tabelas + apenas para marcação de dados tabulares.</para> + + <para>De maneira geral (veja a documentação + do DocBook para mais detalhes) uma tabela (que pode ser + formal ou informal) consiste de um elemento + <sgmltag>table</sgmltag>. O qual contém ao menos um + elemento <sgmltag>tgroup</sgmltag>, que especifica (como + um atributo) o número de colunas neste grupo da + tabela. Dentro do grupo tabela você pode ter um elemento + <sgmltag>thead</sgmltag>, que contém os elementos + para o cabeçalho da tabela (cabeçalho da + coluna), e um <sgmltag>tbody</sgmltag> que contém + o corpo da tabela.</para> + + <para>Tanto o <sgmltag>tgroup</sgmltag> quanto o + <sgmltag>thead</sgmltag> contém elementos + <sgmltag>row</sgmltag>, que por sua vez contém + elementos <sgmltag>entry</sgmltag>. Cada elemento + <sgmltag>entry</sgmltag> especifica uma célula da + tabela.</para> + + <example> + <title><sgmltag>informaltable</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Este é o cabeçalho da coluna 1</entry> + <entry>Este é o cabeçalho da coluna 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Linha 1, coluna 1</entry> + <entry>Linha 1, coluna 2</entry> + </row> + + <row> + <entry>Linha 2, coluna 1</entry> + <entry>Linha 2, coluna 2</entry> + </row> + </tbody> + </tgroup> +</informaltable>]]></programlisting> + + <para>Aparência:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Este é o cabeçalho da coluna + 1</entry> + <entry>Este é o cabeçalho da coluna + 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Linha 1, coluna 1</entry> + <entry>Linha 1, coluna 2</entry> + </row> + + <row> + <entry>Linha 2, coluna 1</entry> + <entry>Linha 2, coluna 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>Sempre utilize o atributo <literal>pgwide</literal> + com o valor <literal>1</literal> junto ao elemento + <sgmltag>informaltable</sgmltag>. Um bug no Internet + Explorer pode fazer com que a tabela renderize de forma + incorreta se ele for omitido.</para> + + <para>Se você não quiser borda na tabela + adicione o atributo <literal>frame</literal> ao elemento + <sgmltag>informaltable</sgmltag> com o valor + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + + <example> + <title>Tabelas com <literal>frame="none"</literal></title> + + <para>Aparência:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Este é o cabeçalho da coluna + 1</entry> + <entry>Este é o cabeçalho da coluna + 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Linha 1, coluna 1</entry> + <entry>Linha 1, coluna 2</entry> + </row> + + <row> + <entry>Linha 2, coluna 1</entry> + <entry>Linha 2, coluna 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect3> + + <sect3> + <title>Exemplos para o Usuário Seguir</title> + + <para>Muitas vezes você irá precisar mostrar + exemplos para que o usuário siga. Normalmente, + isso irá consistir de diálogos com o + computador, nos quais o usuário digita um comando, + e obtém uma resposta de volta, ele digita outro + comando e recebe outra reposta, e assim por diante.</para> + + <para>Vários elementos e entidades podem ser utilizados + nestes casos.</para> + + <variablelist> + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Tudo que o usuário visualizar neste exemplo + estará na tela do computador, assim o + próximo elemento é + <sgmltag>screen</sgmltag>.</para> + + <para>Dentro da marcação do + <sgmltag>screen</sgmltag>, espaços em branco + são significativos.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> e + <literal>&prompt.user;</literal></term> + + <listitem> + + <para>Algumas das coisas que o usuário + irá visualizar na tela + são prompts do computador (seja do + sistema operacional, da linha de comando shell ou + de uma aplicação). Estes prompts devem + ser marcados usando <sgmltag>prompt</sgmltag>.</para> + + <para>Por serem especiais, os prompts de shell do + usuário normal e do usuário root + estão disponíveis como uma entidade. + Sempre que quiser indicar que o usuário + está em um prompt do shell, use + <literal>&prompt.root;</literal> para o + usuário root e + <literal>&prompt.user;</literal> para o + usuário normal, conforme for necessário. + Estas entidades não precisam estar dentro de + um <sgmltag>prompt</sgmltag>.</para> + + <note> + <para><literal>&prompt.root;</literal> e + <literal>&prompt.user;</literal> são + extensões do FreeBSD ao DocBook, e + não são parte do DTD original.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>Quanto estiver mostrando um texto que o + usuário deva digitar, envolva-o com as tags + <sgmltag>userinput</sgmltag>. Ele provavelmente + será mostrado diferente para o + usuário.</para> + + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, e + <sgmltag>userinput</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<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>]]></programlisting> + + <para>Aparência:</para> + + <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> + </example> + + <note> + <para>Ainda que estejamos mostrando o conteúdo do + arquivo <filename>foo2</filename>, ele + <emphasis>não</emphasis> está marcado como + <sgmltag>programlisting</sgmltag>. Deixe o + <sgmltag>programlisting</sgmltag> para mostrar fragmentos + de arquivos fora do contexto de ação do + usuário.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Elementos In-line</title> + + <sect3> + <title>Enfatizando a Informação</title> + + <para>Quando você quiser enfatizar uma palavra ou frase + em particular, use <sgmltag>emphasis</sgmltag>. Ela pode + ser apresentada em itálico, ou negrito, ou pode ser + falada diferentemente com um sistema texto-para-fala.</para> + + <para>Não há uma maneira de mudar a + apresentação da ênfase no seu documento, + não existe um equivalente ao <sgmltag>b</sgmltag> e + ao <sgmltag>i</sgmltag> do HTML. Se a + informação que você está + apresentando é importante então considere + usar <sgmltag>important</sgmltag> ao invés de + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>O FreeBSD é sem dúvida <emphasis>o</emphasis> melhor sistema operacional tipo Unix +para a arquitetura Intel.</para>]]></programlisting> + + <para>Aparência:</para> + <para>O FreeBSD é sem dúvida + <emphasis>o</emphasis> melhor sistema operacional tipo + Unix para a arquitetura Intel.</para> + </example> + </sect3> + + <sect3> + <title>Citações</title> + + <para>Para citar um texto de outro documento ou fonte, ou para + denotar uma frase que está sendo usada figuradamente, use + <sgmltag>quote</sgmltag>. Dentro da tag + <sgmltag>quote</sgmltag>, você pode usar a maioria + das marcações disponíveis para um texto + normal.</para> + + <example> + <title>Citações</title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>Entretanto, certifique-se que a busca não vá além do <quote>limite entre + a administração local e pública</quote> como diz o RFC 1535.</para>]]></programlisting> + + <para>Aparência:</para> + + <para>Entretanto, certifique-se que a busca não + vá além do <quote>limite entre a + administração local e pública</quote> + como diz o RFC 1535.</para> + </example> + </sect3> + + <sect3> + <title>Teclas, Mouse e Combinações</title> + + <para>Para se referir a uma tecla específica do + teclado, use <sgmltag>keycap</sgmltag>. Para se referir + a um botão do mouse, use + <sgmltag>mousebutton</sgmltag>. E para se referir a + combinação de digitar uma tecla e um clique do + mouse, envolva-os com <sgmltag>keycombo</sgmltag>.</para> + + <para>O <sgmltag>keycombo</sgmltag> tem um atributo chamado + <literal>action</literal>, que pode ser + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal>, ou <literal>simul</literal>. Os + dois últimos dizem se teclas ou botões devem + ser pressionados em sequência ou simultaneamente. + </para> + + <para>As folhas de estilo colocam automaticamente o + símbolo de ligação, tal como + <literal>+</literal>, entre os nomes das teclas, quando + elas estiverem envolvidas com + <sgmltag>keycombo</sgmltag>.</para> + + <example> + <title>Teclas, Mouse e Combinações</title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>Para mudar para o segundo terminal virtual, digite + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + +<para>Sair do <command>vi</command> sem salvar o seu trabalho, digite + <keycombo action="seq"> <keycap>Esc</keycap><keycap>:</keycap> + <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> + +<para>Meu gerenciador de janela é configurado de forma que + <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>botão direito</mousebutton> + </keycombo> do mouse é usado para mover as janelas.</para> +]]></programlisting> + + <para>Aparência:</para> + + <para>Para mudar para o segundo terminal virtual, digite + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>. + </para> + + <para>Sair do <command>vi</command> sem salvar o seu + trabalho, digite <keycombo action="seq"> + <keycap>Esc</keycap><keycap>:</keycap> + <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> + + <para>Meu gerenciador de janela é configurado de + forma que <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>botão direito</mousebutton> + </keycombo> do mouse é usado para mover as + janelas.</para> + </example> + </sect3> + + <sect3> + <title>Aplicações, Comandos, + Opções e Citações</title> + + <para>Frequentemente você irá fazer + referência tanto a aplicações quanto + a comandos quando estiver escrevendo a + documentação. A distinção entre + eles é simples: uma + aplicação é o nome de um pacote de + programas (ou possivelmente apenas um) que executa + uma tarefa em particular. Um comando é o nome de + um programa que o usuário pode executar.</para> + + <para>Além disso, você eventualmente + precisará listar uma ou mais opções + que um comando pode aceitar.</para> + + <para>Finalmente, você irá querer listar um + comando com o número da sua seção no + manual, na forma <quote>comando(número)</quote> que + é tão comum nos manuais de Unix.</para> + + <para>Você deve marcar o nome de uma + aplicação com <sgmltag>application</sgmltag>. + </para> + + <para>Quando você quiser listar um comando com o + número da sua seção no manual (o que + deve acontecer na maioria das vezes) o elemento do DocBook + que deve ser utilizado é o + <sgmltag>citerefentry</sgmltag>. Ele irá ter mais + dois elementos, <sgmltag>refentrytitle</sgmltag> e + <sgmltag>manvolnum</sgmltag>. O conteúdo de + <sgmltag>refentrytitle</sgmltag> é o nome do comando, + e o conteúdo de <sgmltag>manvolnum</sgmltag> é + a seção da página do manual.</para> + + <para>Pode ser trabalhoso escrever desta forma, para + facilitar este processo foram criadas uma série de + <link linkend="sgml-primer-general-entities">entidades + gerais</link>. Cada entidade está na + forma <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>O arquivo que contém estas entidades + é o <filename>doc/share/sgml/man-refs.ent</filename>, + o qual pode ser referenciado utilizando o seguinte FPI:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Portanto, a introdução à sua + documentação provavelmente será assim: + </para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + + <para>Use o elemento <sgmltag>command</sgmltag> quando quiser + incluir um comando <quote>in-line</quote> para ser + apresentado como algo que deveria ser digitado pelo + usuário.</para> + + <para>Use o elemento <sgmltag>option</sgmltag> para marcar as + opções que serão passadas para um + comando.</para> + + <para>Quando diversas referências a um mesmo comando + estiverem próximas é melhor usar a + notação <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + para marcar a primeira referência ao mesmo e depois + utilizar <sgmltag>command</sgmltag> para marcar as + referências subsequentes. Isto fará a + saída gerada, especialmente em HTML, ficar + visualmente melhor.</para> + + <para>Isto pode ser confuso, e muitas vezes a escolha nem + sempre é clara. Acredito que o exemplo abaixo + ajudará a tornar as coisas mais claras.</para> + + <example> + <title>Aplicações, Comandos, + Opções</title> + + <para>Uso:</para> + + <programlisting><![ CDATA [<para>O <application>Sendmail</application> é a aplicação + de email mais utilizada em Unix.</para> + +<para>O <application>Sendmail</application> inclui os programas + <citerefentry> + <refentrytitle>Sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, e &man.newaliases.1;.</para> + + +<para>Um dos parâmetros de linha de comando para o <citerefentry> + <refentrytitle>Sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, ira mostrar o atual estado da + mensagem na fila de email. + Verifique isto na linha de comando usando <command>sendmail -bp</command>.</para>]]></programlisting> + + <para>Aparência:</para> + + <para>O <application>Sendmail</application> é a + aplicação de email mais utilizada em + Unix.</para> + + <para>O <application>Sendmail</application> inclui os programas + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, and &man.newaliases.1;.</para> + + <para>Um dos parâmetros de linha de comando para o + <citerefentry><refentrytitle>sendmail</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <option>-bp</option>, irá mostrar o atual estado + da mensagem na fila de email. Verifique isto na linha de + comando usando <command>sendmail -bp</command>.</para> + </example> + + <note> + <para>Veja como a notação + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + é mais fácil de acompanhar.</para> + </note> + </sect3> + + <sect3> + <title>Arquivos, Diretórios, Extensões</title> + + <para>Sempre que quiser se referir ao nome de um arquivo, + diretório ou uma extensão de arquivo, use + o elemento <sgmltag>filename</sgmltag>.</para> + + <example> + <title><sgmltag>filename</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>O fonte SGML do Handbook em Inglês pode ser encotrado em + <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. + O primeiro arquivo neste diretório é chamado <filename>book.sgml</filename>. + Você também deve ver o <filename>Makefile</filename> + e alguns arquivos com a extensão <filename>.ent</filename>.</para>]]></programlisting> + + <para>Aparência:</para> + + <para>O fonte SGML do Handbook em Inglês pode ser + encotrado em <filename>/usr/doc/en/handbook/</filename>. + O primeiro arquivo neste diretório é + chamado <filename>handbook.sgml</filename>. Você + também deve ver o <filename>Makefile</filename> + e alguns arquivos com a extensão + <filename>.ent</filename>.</para> + + </example> + </sect3> + + <sect3> + <title>O Nome dos Ports</title> + + <note> + <title>Extensões FreeBSD</title> + + <para>Estes elementos são parte das extensões + do FreeBSD ao DocBook, e não existem no DTD + DocBook original.</para> + </note> + + <para>Você pode precisar incluir o nome de um programa + da Coleção de Ports do FreeBSD na + documentação. Use a tag + <sgmltag>filename</sgmltag> com o atributo + <literal>role</literal> ajustado para <literal>package + </literal> para identificá-lo. Uma vez que a + coleção de ports pode ser instalada em diversos + lugares, inclua apenas a categoria e o nome do port, + não inclua o <filename>/usr/ports</filename>.</para> + + <example> + <title>Tag <sgmltag>filename</sgmltag> com o atributo + <literal>package</literal></title> + + <para>Use:</para> + + <programlisting><![ RCDATA [<para>Instale o port <filename role="package">net/ethereal</filename> +para ver o tráfego na rede.</para>]]></programlisting> + + <para>Aparência:</para> + + <para>Instale o port + <filename role="package">net/ethereal</filename> + para ver o tráfego na rede.</para> + </example> + </sect3> + + <sect3> + <title>Dispositivos</title> + + <note> + <title>Extensões FreeBSD</title> + + <para>Estes elementos são parte das extensões + do FreeBSD ao DocBook, e não existem no DTD + DocBook original.</para> + </note> + + <para>Você tem 2 opções para se referir a + um dispositivo. Você pode se referir ao dispositivo + da forma como ele aparece no <filename>/dev</filename>, + ou você pode usar o nome do dispositivo como ele aparece + no kernel. No segundo caso, use o elemento + <sgmltag>devicename</sgmltag>.</para> + + <para>Em alguns casos você não terá escolha. + Alguns dispositivos, como as placas de rede, não + tem entrada no <filename>/dev</filename>, ou as entradas + são muito diferentes das esperadas.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ +<para><devicename>sio</devicename> é usado para comunicação + serial no FreeBSD. <devicename>sio</devicename> se manifesta + através de entradas em <filename>/dev</filename>, incluindo + <filename>/dev/ttyd0</filename> e <filename>/dev/cuaa0</filename>. + </para> + +<para>Por outro lado, dispositivos de rede, tais como <devicename>ed0</devicename> + não aparecem <filename>/dev</filename>. + </para> + +<para>No MS-DOS, o primeiro disco flexível é chamado de <devicename>a:</devicename>. + No FreeBSD é <filename>/dev/fd0</filename>. + </para>]]></programlisting> + + <para>Aparência:</para> + <para><devicename>sio</devicename> é usado para + comunicação serial no FreeBSD. + <devicename>sio</devicename> se manifesta através + de entradas em <filename>/dev</filename>, incluindo + <filename>/dev/ttyd0</filename> e + <filename>/dev/cuaa0</filename>.</para> + + <para>Por outro lado, dispositivos de rede, tais como + <devicename>ed0</devicename> não aparecem + <filename>/dev</filename>.</para> + + <para>No MS-DOS, o primeiro disco flexível é + chamado de <devicename>a:</devicename>. No FreeBSD é + <filename>/dev/fd0</filename>.</para> + + </example> + </sect3> + + <sect3> + <title>Hosts, Domínios, Endereços IP e etc.</title> + + <note> + <title>Extensões FreeBSD</title> + + <para>Estes elementos são parte das extensões + do FreeBSD ao DocBook, e não existem no DTD + DocBook original.</para> + </note> + + <para>Você pode marcar a informação sobre + a identificação de computadores em rede + (hosts) de diversas maneiras. Todas elas usam + <sgmltag>hostid</sgmltag> como elemento, com o atributo + <literal>role</literal> dizendo o tipo da + informação marcada.</para> + + <variablelist> + <varlistentry> + <term>Sem o atributo <literal>role</literal>, ou + <literal>role="hostname"</literal></term> + + <listitem> + <para>Sem o atributo <literal>role</literal> (i.e., + <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) + a informação marcada é + simplesmente o nome do computador, tal como + <literal>freefall</literal> ou + <literal>wcarchive</literal>. Você pode + especificar explicitamente com + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>O texto é um nome de domínio, tal + como <literal>FreeBSD.org</literal> ou + <literal>ngo.org.uk</literal>. Não há o + componente do nome do computador (hostname).</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>O texto é um nome completo, com o nome do + computador e do domínio. O termo + <literal>fqdn</literal> significa <quote>Fully + Qualified Domain Name</quote> - Nome de + Domínio Completamente Qualificado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>O texto é um endereço IP, + provavelmente expresso como <literal>dotted + quad</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ip6addr"</literal></term> + + <listitem> + <para>O texto é um endereço IPv6.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>O texto é uma máscara de rede, que + pode ser expressa como <literal>dotted quad</literal>, + uma string hexadecimal ou como <literal>/</literal> + seguido de um número.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>O texto é um endereço MAC Ethernet, + expresso como números hexadecimais de 2 digitos + separados por dois pontos (:).</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>Hostid</sgmltag> e <literal>Roles</literal></title> + + <para>Use:</para> + + <programlisting><![ RCDATA [ +<para>A máquina local sempre pode ser referida pelo nome +<hostid>localhost</hostid>, que terá o endereço IP +<hostid role="ipaddr">127.0.0.1</hostid>.</para> + + +<para>O domínio <hostid role="domainname">FreeBSD.org</hostid> +contém vários hosts diferentes, incluindo +<hostid role="fqdn">freefall.FreeBSD.org</hostid> e +<hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para> + +<para>Quando estiver adicionando um apelido para uma interface (usando +<command>ifconfig</command>) <emphasis>sempre</emphasis> use a +máscara de rede <hostid role="netmask">255.255.255.255</hostid> (que +também pode ser expressa como <hostid role="netmask">0xffffffff</hostid>). +</para> + +<para>O endereço MAC identifica unicamente cada placa de rede +existente. Um endereço MAC típico se parece com <hostid +role="mac">08:00:20:87:ef:d0</hostid>).</para> +]]></programlisting> + + <para>Aparência:</para> + + <para>A máquina local sempre pode ser referida pelo + nome <hostid>localhost</hostid>, que terá o + endereço IP + <hostid role="ipaddr">127.0.0.1</hostid>.</para> + + <para>O domínio + <hostid role="domainname">FreeBSD.org</hostid> + contém vários hosts diferentes, incluindo + <hostid role="fqdn">freefall.FreeBSD.org</hostid> e + <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para> + + <para>Quando estiver adicionando um apelido para uma + interface (usando <command>ifconfig</command>) + <emphasis>sempre</emphasis> use a máscara de + rede <hostid role="netmask">255.255.255.255</hostid> (que + também pode ser expressa como + <hostid role="netmask">0xffffffff</hostid>).</para> + + <para>O endereço MAC identifica unicamente cada + placa de rede existente. Um endereço MAC + típico se parece com + <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>Extensões FreeBSD</title> + + <para>Estes elementos são parte das extensões + do FreeBSD ao DocBook, e não existem no DTD + DocBook original.</para> + </note> + + <para>Quando precisar se referir a um nome de usuário + específico, tal como <literal>root</literal> ou + <literal>bin</literal>, use o elemento + <sgmltag>username</sgmltag>.</para> + + <example> + <title><sgmltag>Username</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [<para>Para executar a maioria das funções administrativas você precisará + ser <username>root</username>.</para>]]></programlisting> + + <para>Aparência:</para> + + <para>Para executar a maioria das funções + administrativas você precisará ser + <username>root</username>.</para> + </example> + </sect3> + + <sect3> + <title>Descrevendo <filename>Makefile</filename>s</title> + + <note> + <title>Extensões FreeBSD</title> + + <para>Estes elementos são parte das extensões + do FreeBSD ao DocBook, e não existem no DTD + DocBook original.</para> + </note> + + <para>Existem dois elementos para descrever partes de + <filename>Makefile</filename>s, + <sgmltag>maketarget</sgmltag> e <sgmltag>makevar</sgmltag>. + </para> + + <para>O <sgmltag>maketarget</sgmltag> identifica uma alvo de + construção exportado por um + <filename>Makefile</filename> que pode ser passado como um + parâmetro ao <command>make</command>. O + <sgmltag>makevar</sgmltag> identifica uma variável + que pode ser ajustada (no ambiente, na linha de comando do + <command>make</command>, ou dentro do + <filename>Makefile</filename>) para influenciar o + processo.</para> + + <example> + <title><sgmltag>Maketarget</sgmltag> e + <sgmltag>Makevar</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ +<para>Dois alvos comuns em um <filename>Makefile</filename> são +<maketarget>all</maketarget> e <maketarget>clean</maketarget>.</para> + +<para>Tipicamente, usar <maketarget>all</maketarget> irá refazer a +aplicação, usar <maketarget>clean</maketarget> irá remover os +arquivos temporários (<filename>.o</filename> por exemplo) criados +pelo processo de construção.</para> + +<para><maketarget>clean</maketarget> pode ser controlado por +muitas variáveis, incluindo <makevar>CLOBBER</makevar> e +<makevar>RECURSE</makevar>.</para> +]]></programlisting> + + <para>Aparência:</para> + + <para>Dois alvos comuns em um <filename>Makefile</filename> + são <maketarget>all</maketarget> e + <maketarget>clean</maketarget>.</para> + + <para>Tipicamente, usar <maketarget>all</maketarget> + irá refazer a aplicação, usar + <maketarget>clean</maketarget> irá remover os + arquivos temporários (<filename>.o</filename> + por exemplo) criados pelo processo de + construção.</para> + + <para>O <maketarget>clean</maketarget> pode ser controlado + por muitas variáveis, incluindo + <makevar>CLOBBER</makevar> e + <makevar>RECURSE</makevar>.</para> + </example> + </sect3> + + <sect3> + <title>Texto Literal</title> + + <para>Com frequência você irá precisar + incluir texto <quote>literal</quote> na + documentação. Este texto que é + originado de outro arquivo, ou que deve ser copiado de + forma fiel da documentação para outro + arquivo.</para> + + <para>Às vezes, o <sgmltag>programlisting</sgmltag> + será suficiente. Mas o + <sgmltag>programlisting</sgmltag> nem sempre é + apropriado, particularmente quando você quer incluir + uma parte de um arquivo <quote>in-line</quote> com todos + os parágrafos.</para> + + <para>Nestas ocasiões, use <sgmltag>literal</sgmltag>. + </para> + + <example> + <title><sgmltag>Literal</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ <para>A linha <literal>maxusers 10</literal> no arquivo de +configuração do kernel determina o tamanho de muitas tabelas +do sistema, e diz aproximadamente quantos logins simultâneos +o sistema irá suportar.</para> +]]></programlisting> + + <para>Aparência:</para> + <para>A linha <literal>maxusers 10</literal> no arquivo de + configuração do kernel determina o tamanho + de muitas tabelas do sistema, e diz aproximadamente + quantos logins simultâneos o sistema irá + suportar.</para> + + </example> + </sect3> + + <sect3> + <title>Mostrando Itens que o Usuário + <emphasis>Deve</emphasis> Preencher</title> + + <para>Muitas vezes você irá querer mostrar ao + usuário o que fazer, ou precisará se referir a + um arquivo, a uma linha de comando ou coisa parecida, na + qual ele não poderá simplesmente copiar o + exemplo que você forneceu, mas na qual ele + terá deve dar alguma informação por + ele mesmo.</para> + + <para>O elemento <sgmltag>replaceable</sgmltag> foi criado para + estas ocasiões. Use ele dentro de outros elementos para + indicar partes do conteúdo do elemento que o + usuário deve substituir.</para> + + <example> + <title><sgmltag>replaceable</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ CDATA [<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting> + + <para>Aparência:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>comando</replaceable></userinput></screen> + </informalexample> + + <para>O <sgmltag>replaceable</sgmltag> pode ser usado em + muitos elementos diferentes, incluindo + <sgmltag>literal</sgmltag>. Este exemplo também + mostra que <sgmltag>replaceable</sgmltag> só deve + envolver o conteúdo que o usuário + <emphasis>deve</emphasis> fornecer. O outro + conteúdo não deve ser alterado.</para> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ +<para>A linha <literal>maxusers <replaceable>n</replaceable></literal> +no arquivo de configuração do kernel determina o tamanho de muitas +tabelas do sistema, e diz aproximadamente quantos logins simultâneos +o sistema irá suportar. +</para> + +<para>Para uma estação de trabalho, <literal>32</literal> é um +bom valor para <replaceable>n</replaceable>.</para> +]]></programlisting> + + <para>Aparência:</para> + <para>A linha <literal>maxusers + <replaceable>n</replaceable></literal> + no arquivo de configuração do kernel + determina o tamanho de muitas tabelas do sistema, e diz + aproximadamente quantos logins simultâneos o sistema + irá suportar.</para> + + <para>Para uma estação de trabalho, + <literal>32</literal> é um bom valor para + <replaceable>n</replaceable>.</para> + </example> + </sect3> + + <sect3> + <title>Citando erros do sistema</title> + + <para>Você pode querer mostrar erros gerados pelo + FreeBSD. Marque-os com <sgmltag>errorname</sgmltag>. + Isto indicará o erro exato que aparece.</para> + <example> + <title><sgmltag>errorname</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ +<screen><errorname>Panic: cannot mount root</errorname></screen> ]]> +</programlisting> + + + <para>Aparência:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect3> + </sect2> + + <sect2> + <title>Imagens</title> + + <important> + <para>O suporte a imagem na documentação ainda + é extremamente experimental. O mecanismo aqui + descrito provavelmente não irá mudar, mas + isto não é garantido.</para> + + <para>Você precisará instalar o port + <filename role="package">graphics/ImageMagick</filename> + que é usado para converter entre os diferentes + formatos de imagens. Ele é grande e a sua maior + parte não é necessária. Entretanto, + enquanto nós ainda estamos trabalhando nos + <filename>Makefile</filename>s e em outros itens da + infraestrutura, ele torna as coisas mais + fáceis. Este port <emphasis>não</emphasis> + está no meta port + <filename role="package">textproc/docproj</filename>, + você deve instalá-lo manualmente.</para> + + <para>O melhor exemplo do que acontece na prática + é o documento + <filename>doc/en_US.ISO8859-1/articles/vm-design/ + </filename>. Se você se sentir inseguro na + descrição que segue, dê uma olhada nos + arquivos deste diretório e veja como tudo se + encaixa. Experimente criar versões com diferentes + formatos de saída do documento para ver como a + marcação de imagem aparece no documento final. + </para> + </important> + + <sect3> + <title>Formatos de Imagens</title> + + <para>Atualmente suportamos dois formatos de imagens. O + formato que você deve usar depende da natureza da + sua imagem.</para> + + <para>Para imagens vetoriais, tais como diagramas de rede, + linhas temporais e similares, use Encapsulated Postscript, + e certifique-se que suas imagens tenham a extensão + <filename>.eps</filename>.</para> + + <para>Para bitmaps, tais como a captura de uma tela, use o + formato Portable Network Graphic, e certifique-se que suas + imagens tenham a extensão + <filename>.png</filename>.</para> + + <para>Estes são os <emphasis>únicos</emphasis> + formatos de imagem que podem ser gravados no + repositório Subversion.</para> + + <para>Use o formato correto para a imagem correta. Espera-se + que a sua documentação tenha tanto imagens + EPS quanto PNG. Os <filename>Makefile</filename>s + asseguram que o formato correto seja escolhido dependendo + do formato de saída da sua + documentação. <emphasis>Não faça + commit da mesma imagem nos dois formatos diferentes para o + repositório</emphasis>.</para> + + <important> + <para>É esperado que o projeto de + documentação passe a utilizar no futuro o + formato Scalable Vector Graphic (SVG) para imagens + vetoriais. Entretanto, o atual estado das ferramentas + de edição torna isto impraticável. + </para> + </important> + </sect3> + + <sect3> + <title>Marcação</title> + + <para>A marcação para uma imagem é + relativamente simples. Primeiro, marque um + <sgmltag>mediaobject</sgmltag>. O + <sgmltag>mediaobject</sgmltag> pode conter outros objetos + mais específicos. Estamos interessandos em dois, + o <sgmltag>imageobject</sgmltag> e o + <sgmltag>textobject</sgmltag>.</para> + + <para>Você deve incluir um + <sgmltag>imageobject</sgmltag>, e dois elementos + <sgmltag>textobject</sgmltag>. O + <sgmltag>imageobject</sgmltag> irá apontar para o + nome do arquivo da imagem que será usada + (sem a extensão). Os elementos + <sgmltag>textobject</sgmltag> contém a + informação que será apresentada ao + usuário junto, ou não, com a imagem.</para> + + <para>Há duas circunstâncias em que isso pode + ocorrer.</para> + + <itemizedlist> + <listitem> + <para>Quando o leitor estiver vendo a + documentação em HTML. Neste caso, cada + imagem precisará ter um texto alternativo + associado para mostrar ao usuário, tipicamente + enquanto a imagem estiver sendo carregada, ou se ele + parar o ponteiro do mouse sobre a imagem.</para> + </listitem> + + <listitem> + <para>Quando o leitor estiver vendo a + documentação em modo texto. Neste caso, + cada imagem deve ter uma ASCII art equivalente para + mostrar ao usuário.</para> + </listitem> + </itemizedlist> + + <para>Um exemplo provavelmente irá tornar as coisas + mais fáceis de se entender. Suponha que você + tenha uma imagem, chamada <filename>fig1</filename>, que + você queira incluir no documento. Esta imagem + é um retângulo com um A dentro dele. A + marcação para isso será:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="fig1"> <co id="co-image-ext"/> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ <co id="co-image-literal"/> +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>Uma figura</phrase> <co id="co-image-phrase"/> + </textobject> +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para>Inclua um elemento <sgmltag>imagedata</sgmltag> + dentro do elemento <sgmltag>imageobject</sgmltag>. + O atributo <literal>fileref</literal> deve conter o + nome da imagem a ser incluída, sem a extensão. + As folhas de estilo irão decidir qual a + extensão deve ser adicionada ao nome do arquivo + automaticamente.</para> + </callout> + + <callout arearefs="co-image-literal"> + <para>O primeiro <sgmltag>textobject</sgmltag> deve conter + um elemento <sgmltag>literallayout</sgmltag>, onde o + atributo <literal>class</literal> é ajustado para + <literal>monospaced</literal>. Esta é a + oportunidade para você demonstrar suas habilidades + com ASCII art. O conteúdo será usado se o + documento for convertido para texto puro.</para> + + <para>Veja como as primeras e últimas linhas do + conteúdo do elemento <sgmltag>literallayout + </sgmltag> fica próximo a tag do elemento. + Isso assegura que não sejam incluídos + espaços extras.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para>O segundo <sgmltag>textobject</sgmltag> deve conter + um único elemento <sgmltag>phrase</sgmltag>. O + conteúdo deste elemento se tornará o atributo + <literal>alt</literal> para as imagens quando o + documento for convertido para HTML.</para> + </callout> + </calloutlist> + </sect3> + + <sect3> + <title>Entradas no <filename>Makefile</filename></title> + + <para>Suas imagens devem estar listadas na variável + <makevar>IMAGES</makevar> do <filename>Makefile</filename>. + Esta variável deve conter o nome de todos + <emphasis>fontes</emphasis> das suas imagens. Por exemplo, + se você criou três figuras, + <filename>fig1.eps</filename>, + <filename>fig2.png</filename>, + <filename>fig3.png</filename>, então o seu + <filename>Makefile</filename> deve ter linhas como estas. + </para> + + <programlisting>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>ou</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para>De novo, o <filename>Makefile</filename> irá + fazer uma lista completa das imagens necessárias + para criar o seu documento fonte, você precisa + listar apenas as imagens que + <emphasis>você</emphasis> fornece.</para> + </sect3> + + <sect3> + <title>Imagens e Capítulos em Subdiretórios</title> + + <para>Você precisa ser cuidadoso quando separar a sua + documentação em arquivos menores (veja + <xref linkend="sgml-primer-include-using-gen-entities"/>) em + diretórios diferentes.</para> + + <para>Suponha que você tenha um livro com três + capítulos, e os capítulos estão + armazenados cada um no seu próprio diretório, + chamados <filename>chapter1/chapter.sgml</filename>, + <filename>chapter2/chapter.sgml</filename>, e + <filename>chapter3/chapter.sgml</filename>. Se cada + capítulo tiver imagens associadas a eles, é + sugerido que você as coloque dentro do respectivo + subdiretório de cada capítulo + (<filename>chapter1/</filename>, + <filename>chapter2/</filename>, + <filename>chapter3/</filename>).</para> + + <para>Entretanto, se você fizer isso você deve + incluir o nome dos diretórios na variável + <makevar>IMAGES</makevar> no <filename>Makefile</filename>, + <emphasis>e</emphasis> deve incluir o nome do + diretório no elemento <sgmltag>imagedata</sgmltag> + do seu documento.</para> + + <para>Por exemplo, se você tiver + <filename>chapter1/fig1.png</filename>, então + <filename>chapter1/chapter.sgml</filename> deve + conter:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/> + </imageobject> + + … + +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para>O nome do diretório deve ser incluído no + atributo <literal>fileref</literal></para> + </callout> + </calloutlist> + + <para>O <filename>Makefile</filename> deve conter:</para> + + <programlisting>… +IMAGES= chapter1/fig1.png +…</programlisting> + + <para>Desta forma tudo deve funcionar.</para> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links também são elementos in-line.</para> + </note> + + <sect3> + <title>Ligando-se a outras partes no mesmo documento</title> + + <para>Links dentro do mesmo documento exigem que você + especifique de onde você esta se ligando (i.e., + o texto no qual o usuário irá clicar, ou + indicando de outra maneira a origem do link) e para onde + você está se ligando (o destino do + link).</para> + + <para>Cada elemento dentro do DocBook tem um atributo chamado + <literal>id</literal>. Você pode por um texto neste + atributo para identificar unicamente o elemento associado + a ele.</para> + + <para>Este valor será usado quando você + especificar a origem do link.</para> + + <para>Normalmente, você irá se ligar apenas a + capítulos ou seções, assim você + irá colocar o atributo <literal>id</literal> nestes + elementos.</para> + + <example> + <title>O atributo <literal>id</literal> em capítulos + ou seções</title> + + <programlisting><![ RCDATA [<chapter id="chapter1"> + <title>Introdução</title> + + <para>Esta é a introdução. Contém uma + subseção que também será identificada. + </para> + <sect1 id="chapter1-sect1"> + <title>Subseção 1</title> + + <para>Esta é a subseção.</para> + </sect1> +</chapter>]]></programlisting> + </example> + + <para>Obviamente, você deve usar nomes mais descritivos. + Estes nomes devem ser únicos dentro do documento + (i.e., não apenas no arquivo, mas sim no documento + no qual o arquivo está incluído). Repare como o + <literal>id</literal> é construído adicionando-se + texto ao <literal>id</literal> do capítulo. Isto + ajuda a garantir que eles sejam únicos.</para> + + <para>Se você quiser permitir ao usuário saltar + para uma parte específica do documento + (possivelmente para o meio do parágrafo ou um + exemplo), use o elemento <sgmltag>anchor</sgmltag>. Este + elemento não tem conteúdo, mas aceita o atributo + <literal>id</literal>.</para> + + <example> + <title><sgmltag>anchor</sgmltag></title> + + <programlisting><![ RCDATA [<para> +Este parágrafo tem um <anchor id="para1">alvo dentro dele. +O qual não irá aparecer no documento +</para>]]></programlisting> + </example> + + <para>Quando você quiser dar ao usuário um link + que possa ser ativado (provavelmente clicando-se) para ir + para outra seção do documento que tenha um + atributo <literal>id</literal>, você pode usar + <sgmltag>xref</sgmltag> ou <sgmltag>link</sgmltag>.</para> + + <para>Ambos os elementos têm um atributo + <literal>linkend</literal>. O valor deste atributo deve + ser o mesmo usado no atributo <literal>id</literal> + (não importa se ele ainda não ocorreu no + documento; isto funciona tanto para um link à frente + quanto para trás).</para> + + <para>Se você utilizar o <sgmltag>xref</sgmltag> + então você não terá controle + sobre o texto do link. Ele será gerado para + você.</para> + + <example> + <title>Usando <sgmltag>xref</sgmltag></title> + + <para>Assuma que este fragmento apareça em algum + lugar de um documento que inclua o <literal>id</literal> + do exemplo.</para> + + <programlisting><![ RCDATA [ +<para>Maiores informações podem ser encontradas + em <xref linkend="chapter1"/></para> + +<para>Informações mais específicas podem ser + encontradas na <xref linkend="chapter1-sect1"/>.</para> +]]></programlisting> + + <para>O texto do link será gerado automaticamente, e + irá se parecer com (As palavras em + <emphasis>itálico</emphasis> indicam o texto que + será o link):</para> + + <blockquote> + <para>Maiores informações podem ser encontradas + no <emphasis>Capítulo Um</emphasis>.</para> + + <para>Informações mais específicas + podem ser encontradas na <emphasis>seção + chamada Subseção 1</emphasis>.</para> + </blockquote> + </example> + + <para>Observe como o texto do link é deduzido a + partir do título da seção ou do + número do capítulo.</para> + + <note> + <para>Isto significa que você <emphasis>não + pode</emphasis> usar <sgmltag>xref</sgmltag> para se + ligar a um atributo <literal>id</literal> em um elemento + <sgmltag>anchor</sgmltag>. O <sgmltag>anchor</sgmltag> + não tem conteúdo, desta forma o + <sgmltag>xref</sgmltag> não pode gerar o texto + para o link.</para> + </note> + + <para>Se você quiser controlar o texto do link + você deverá utilizar <sgmltag>link</sgmltag>. + Este elemento envolve o conteúdo, e o conteúdo + será usado para o link.</para> + + <example> + <title>Usando <sgmltag>link</sgmltag></title> + + <para>Assuma que este fragmento aparece em algum lugar em + um documento que inclui o <literal>id</literal> do + exemplo.</para> + + <programlisting><![ RCDATA [ +<para>Maiores informações podem ser encontradas +<link linkend="chapter1">no primeiro capítulo</link>. +</para> + +<para>Informações mais específicas podem ser encontradas +<link linkend="chapter1-sect1">nesta</link> seção +</para> +]]></programlisting> + + <para>Isto irá gerar o seguinte (Palavras em + <emphasis>itálico</emphasis> indicam o texto que + será o link):</para> + + <blockquote> + <para>Maiores informações podem ser + encontradas <emphasis>no primeiro capítulo + </emphasis>.</para> + + <para>Informações mais específicas + podem ser encontradas <emphasis>nesta + </emphasis> seção</para> + </blockquote> + </example> + + <note> + <para>Este último é um mau exemplo. + Nunca use palavras como <quote>esta</quote> ou + <quote>aqui</quote> como origem do link. O leitor + terá que procurar no contexto próximo para + ver para onde o link o está levando.</para> + </note> + + <note> + <para>Você <emphasis>pode</emphasis> usar o elemento + <sgmltag>link</sgmltag> para incluir um link para um + <literal>id</literal> em um elemento + <sgmltag>anchor</sgmltag>, uma vez que o conteúdo + de <sgmltag>link</sgmltag> define o texto que será + usado para o link.</para> + </note> + </sect3> + + <sect3> + <title>Ligando-se a documentos na WWW</title> + + <para>Ligar-se a um documento externo é muito mais + simples, desde que você saiba o URL do documento ao + qual deseja se ligar. Basta utilizar o elemento + <sgmltag>ulink</sgmltag>. O atributo <literal>url + </literal> é o URL da página para o qual + o link aponta, e o conteúdo do elemento é + o texto que será mostrado para o usuário + ativar.</para> + + <example> + <title><sgmltag>ulink</sgmltag></title> + + <para>Uso:</para> + + <programlisting><![ RCDATA [ +<para>É claro que você pode parar de ler este documento e ir para a +<ulink url="&url.base;/index.html">Página principal do FreeBSD</ulink> +</para> +]]></programlisting> + + <para>Aparência:</para> + + <para>É claro que você pode parar de ler este + documento e ir para a + <ulink url="&url.base;/index.html">Página principal + do FreeBSD</ulink></para> + </example> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..20e7f7f5aa --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1885 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<chapter id="sgml-primer"> + <title>SGML Primer</title> + + <para>A maioria dos documentos do FDP é escrita utilizando + SGML. Este capítulo irá explicar exatamente o que + isso significa, como ler e compreender os fontes dos documentos + e os truques de SGML que você irá se defrontar na + documentação.</para> + + <para>Partes desta seção foram inspiradas no documento + <ulink url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html"> + Começando a utilizar o DocBook</ulink> de autoria do + Mark Galassi.</para> + + <sect1 id="sgml-primer-overview"> + <title>Visão Geral</title> + + <para>Antigamente, era simples de se lidar com um texto + eletrônico. Naquela época, você tinha que + saber em qual conjunto de caracteres o seu documento havia sido + escrito (ASCII, EBCDIC ou um dos inúmeros outros), e mais + nada. O texto era texto, e o que você via era + realmente o que você tinha. Nenhuma frescura, nenhuma + formatação, nenhuma inteligência.</para> + + <para>Inevitavelmente, isto não era o suficiente. + Uma vez que você tem o texto em uma máquina num + formato utilizável, você espera que o equipamento + seja capaz de usá-lo e manipulá-lo de forma + inteligente. Você pode desejar indicar que uma + determinada frase deve ser enfatizada, ou adicionada a um + glossário, ou ser interligada a outra parte do + documento. Você pode querer que os nomes dos arquivos + sejam exibidos com uma fonte de estilo <quote>typewriter</quote> + quando forem exibidos na tela, mas como <quote>itálico + </quote> quando impresso, ou qualquer outra opção + dentre a infinidade de opções disponíveis para + apresentação.</para> + + <para>Esperava-se que a inteligência artificial (AI) + torna-se isso fácil. O seu computador leria o + documento e identificaria automaticamente as frases chave, + nomes de arquivos, os campos que o leitor teria que preencher, + e muito mais. Infelizmente, a vida real não evoluiu + como esperado, e os nossos computadores necessitam de algum + auxílio antes que eles possam processar significativamente + nosso texto.</para> + + <para>Mais precisamente, eles precisam de ajuda para identificar + o que é o que. Vejamos o texto abaixo:</para> + + <blockquote> + <para>Para remover o <filename>/tmp/foo</filename> utilize + &man.rm.1;.</para> + + <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> + </blockquote> + + <para>Nele podemos facilmente visualizar quais partes + são nomes de arquivos, quais são comandos que + devem ser digitados, quais partes são + referências às páginas de manual, etc. + Mas o computador processando o documento não pode. + Para isto nós precisamos utilizar uma + marcação (<literal>markup</literal>).</para> + + <para>A <quote>marcação</quote> é comumente + utilizada para descrever a <quote>adição de + valor</quote> ou o <quote>aumento de custo</quote>. O termo + (term) faz exame de ambos os meios quando aplicados ao texto. + A marcação é um texto adicional incluído + no documento, e de alguma forma destacado do seu conteúdo, + de modo que os programas que forem processá-lo possam ler + as marcações e utilizá-las ao tomar + decisões sobre o documento. Os editores podem ocultar + a marcação do usuário, de forma que o + usuário não se distraia com ele.</para> + + <para>As informações extras armazenadas na + marcação <emphasis>adicionam valor</emphasis> ao + documento. Tipicamente a adição da + marcação ao documento precisa ser realizada por + uma pessoa — apesar de tudo, se os computadores pudessem + reconhecer suficientemente bem o texto para adicionar as + marcações, então não haveria + necessidade de adicioná-las em primeiro lugar. Isto + <emphasis>aumenta o custo</emphasis> (isto é, o + esforço requerido) para criar o documento.</para> + + <para>O exemplo acima foi na verdade escrito neste documento + como se segue:</para> + + <programlisting><![ CDATA [ +<para>Para remover <filename>/tmp/foo</filename> utilize &man.rm.1;.</para> + +<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> + + <para>Como você pode ver, a marcação + está claramente separada do conteúdo.</para> + + <para>Obviamente, se você estiver iniciando no uso de + marcações, você precisa definir o que a + sua marcação significa, e como ela será + interpretada. Você vai precisar de uma linguagem de + marcação a qual você possa seguir quando + estiver marcando os seus documentos.</para> + + <para>Naturalmente, uma linguagem de marcação pode + não ser o bastante. Os requisitos de uma linguagem de + marcação destinada formatação de + documentos técnicos são diferentes dos requisitos + de uma linguagem de marcação destinada a + formatação de receitas culinárias. Esta, + por sua vez, seria muito diferente de uma linguagem de + marcação usada para formatar poemas. O que + você realmente precisa é de uma linguagem + primária, a qual você possa utilizar para + escrever estas e outras linguagens de marcação. + Uma <emphasis>meta linguagem de + marcação</emphasis>.</para> + + <para>É exatamente isso que a <foreignphrase>Standard + Generalized Markup Language</foreignphrase> (SGML) é. + Muitas linguagens de marcação foram escritas em + SGML, incluindo as duas mais utilizadas pelo FDP, o HTML e o + DocBook.</para> + + <para>Cada definição de linguagem é mais + corretamente chamada de Definição de Tipo de + Documento (DTD). O DTD especifica o nome dos elementos que + podem ser utilizados, em qual ordem eles aparecem (e se alguma + marcação pode ser utilizada dentro de outra + marcação) e as informações + relacionadas. Um DTD é algumas vezes referenciado como + uma <emphasis>aplicação</emphasis> do SGML.</para> + + <para id="sgml-primer-validating">Um DTD é uma + especificação <emphasis>completa</emphasis> de + todos os elementos que podem ser utilizados, da ordem em que + podem aparecer, quais elementos são obrigatórios, + quais são opcionais, e assim por diante. Isto torna + possível escrever um interpretador (parser) SGML, que + leia ambos os DTD e um documento que reividique se adequar ao + DTD. O interpretador pode então confirmar se todos os + elementos obrigatórios do DTD estão (ou + não) presentes no documento na ordem correta, e se + existem erros na marcação. Isto é + normalmente referenciado como <quote>validação + do documento</quote>.</para> + + <note> + <para>Este processamento simplesmente confirma se a escolha + dos elementos, a sua ordenação, etc, + estão de acordo com o especificado no DTD. Ele <emphasis> + não</emphasis> verifica se você utilizou a + marcação <emphasis>adequada</emphasis> para o + conteúdo. Se você tentasse marcar todos os + nomes de arquivo em seu documento como nomes de + funções, o interpretador não iria + apontar isto como um erro (assumindo, naturalmente, que a sua + DTD define elementos para nomes de arquivos e para + funções, e que eles podem ser utilizados nos + mesmos lugares).</para> + </note> + + <para>É provável que a maioria das suas + contribuições ao projeto de + documentação irão se constituir de + conteúdos marcados tanto em HTML quanto em DocBook, + em vez de alterações nos DTDs. + Por esta razão este livro não irá abordar + a criação de um DTD.</para> + </sect1> + + <sect1 id="sgml-primer-elements"> + <title>Elementos, tags, e atributos</title> + + <para>Todos os DTDs escritos em SGML compartilham certas + características. Isto é uma dura surpresa, + como a filosofia por de trás do SGML nos + mostrará ser completamente inevitável. Uma das + manifestações mais óbvias desta filosofia + está no <emphasis>conteúdo</emphasis> e nos + <emphasis>elementos</emphasis>.</para> + + <para>A sua documentação (independente se é + uma única página web ou um livro longo) é + composta de conteúdo. Este conteúdo é + então dividido (e de novo subdividido) em elementos. O + propósito da adição de + marcações é atribuir nome e identidade + para os limites destes elementos de forma a possibilitar o + processamento adicional.</para> + + <para>Por exemplo, considere um livro típico. No + nível mais alto, o livro por si só é um + elemento. Este elemento <quote>livro</quote> (book) obviamente + contém capítulos, os quais também podem + ser considerados elementos em sua própria forma. Cada + capítulo irá conter mais elementos, tais como + parágrafos, citações, notas de + rodapé, etc. Cada parágrafo pode conter + elementos adicionais, identificando o conteúdo que era + de discurso direto, ou o nome de um personagem da + história.</para> + + <para>Você pode preferir pensar nisto como uma + <quote>quebra</quote> do conteúdo. No nível + mais alto você tem um pedaço, o Livro. Olhando + um pouco mais abaixo, você tem mais pedaços, os + capítulos individuais. Estes estão divididos + em pedaços ainda menores, os parágrafos, notas + de rodapé, nomes de personagens, etc.</para> + + <para>Observe que você pode fazer esta + diferenciação entre os diferentes elementos do + conteúdo sem recorrer a nenhum termo SGML. Na + realidade é surpreendentemente fácil de usar. + Você pode fazer isso utilizando uma caneta de + marcação e uma cópia impressa do livro, + utilizando diferentes cores para indicar os diferentes + pedaços do conteúdo.</para> + + <para>Naturalmente, nós não possuímos uma caneta + eletrônica de marcação, assim nós + necessitamos de alguma outra maneira de indicar a que elemento + cada peça de conteúdo pertence. Nas linguagens + escritas em SGML (HTML, DocBook, etc) isto é feito + através do uso de <emphasis>tags</emphasis>.</para> + + <para>Uma tag é utilizada para identificar onde um elemento + particular começa e onde ele termina. <emphasis>A tag + não é uma parte própria do elemento + </emphasis>. Porque cada DTD foi normalmente escrito para + marcar um tipo específico de informação, + cada um deles reconhecerá diferentes elementos, e + terá nomes diferentes para cada tag.</para> + + <para>Para um elemento chamado <replaceable>element-name + </replaceable> a tag de início normalmente irá + se parecer com + <sgmltag><replaceable>element-name</replaceable></sgmltag>. E + a tag correspondente de fechamento para este elemento seria + <sgmltag>/<replaceable>element-name</replaceable></sgmltag>. + </para> + + <example> + <title>Utilizando um elemento (tags de inicio e fim)</title> + + <para>O HTML possui um elemento para indicar que o + conteúdo envolvido por este elemento é um + parágrafo, chamado <sgmltag>p</sgmltag>. Este + elemento possui ambas as tags de início e de fim. + </para> + + <programlisting><![ RCDATA [<p>Este é um parágrafo. Ele inicia com a tag de inicio do + elemento 'p', e irá terminar com a tag de fim para o + elemento 'p'.</p> + +<p>Este é um outro parágrafo. Mas este é muito menor.</p>]]></programlisting> + </example> + + <para>Nem todos os elementos requerem uma tag de + finalização. Alguns elementos não + possuem conteúdo. Por exemplo, em HTML você pode + indicar que deseja que uma linha horizontal apareça no + documento. Obviamente, esta linha não possui + conteúdo, assim apenas a tag de inicio é + requerida para este elemento.</para> + + <example> + <title>Utilizando um elemento (Apenas tag de início) + </title> + + <para>O HTML possui um elemento para indicar uma linha + horizontal, chamado <sgmltag>hr</sgmltag>. Este elemento + não contém nenhum conteúdo, assim ele + possui apenas uma tag de inicio.</para> + + <programlisting><![ RCDATA [<p>Este é um parágrafo.</p> + +<hr> + +<p>Este é outro parágrafo. Uma linha horizontal o separa do + parágrafo anterior.</p>]]></programlisting> + </example> + + <para>Se isto não é óbvio agora, os + elementos podem conter outros elementos. No exemplo anterior + do livro, o elemento livro continha todos os elementos + capítulos, os quais por sua vez continham todos os + elementos parágrafos, etc.</para> + + <example> + <title>Elementos contendo elementos; <sgmltag>em</sgmltag> + </title> + + <programlisting><![ RCDATA [<p>Este é um <em>parágrafo</em> simples no qual + algumas das <em>palavras</em> foram <em>enfatizadas</em>.</p>]]></programlisting> + </example> + + <para>O DTD irá especificar as regras detalhando quais + elementos podem conter outros elementos, e o que exatamente + eles podem conter.</para> + + <important> + <para>As pessoas sempre confundem os termos tags e elementos, + e utilizam os termos como se eles fossem + intercambiáveis. Eles não são.</para> + + <para>Um elemento é uma parte conceitual do seu + documento. Um elemento possui um inicio e fim determinados. + As tags marcam onde os elementos começam e terminam. + </para> + + <para>Quando este documento (ou qualquer pessoa que + conheça SGML) se refere a <quote>tag + <sgmltag>p</sgmltag></quote> estamos nos referindo + literalmente ao texto de três caracteres + <literal><</literal>, <literal>p</literal> e + <literal>></literal>. Mas a frase <quote>o elemento + <sgmltag>p</sgmltag></quote> se refere ao elemento inteiro. + </para> + + <para>Esta distinção + <emphasis>é</emphasis> muito sutil. Mas mantenha ela + em mente</para> + </important> + + <para>Os elementos podem ter atributos. Um atributo possui um + nome e um valor, e é utilizado para adicionar + informações extras ao elemento. Esta pode ser + a informação a qual indica como o conteúdo + deve ser renderizado, ou pode ser algo que identifique a + ocorrência única do elemento, ou pode ser qualquer + outra coisa.</para> + + <para>O atributo de um elemento é sempre escrito + <emphasis>dentro</emphasis> da tag de início para + aquele elemento, e assume a forma + <literal><replaceable>nome-do-atributo</replaceable>="<replaceable>valor-do-atributo</replaceable>"</literal>.</para> + + <para>Nas versões suficientemente recentes do HTML, o + elemento <sgmltag>p</sgmltag> possui um atributo chamado + <sgmltag>align</sgmltag>, o qual sugere o alinhamento + (Justificação) de um parágrafo para o programa + que estiver exibindo o HTML.</para> + + <para>O atributo <literal>align</literal> pode assumir um de + quatro valores possíveis, <literal>left</literal> + (esquerda), <literal>center</literal> (centralizado), + <literal>right</literal> (direita) e <literal>justify</literal> + (justificado). Se o atributo não for especificado + será assumido o valor padrão + <literal>left</literal>.</para> + + <example> + <title>Utilizando um elemento com um atributo</title> + + <programlisting><![ RCDATA [<p align="left">A inclusão de um atributo de alinhamento neste + parágrafo foi supérfluo, uma vez que o alinhamento + padrão é left (esquerda).</p> + +<p align="center">Isto pode aparecer no centro.</p>]]></programlisting> + </example> + + <para>Alguns atributos irão assumir apenas valores + específicos, como o <literal>left</literal> ou + <literal>justify</literal>. Outros irão permitir que + você entre com qualquer coisa que deseje. Se você + precisar incluir aspas (<literal>"</literal>) no valor de um + atributo, você deve envolver o valor do atributo com + aspas simples (<literal>'</literal>).</para> + + <example> + <title>Aspas simples envolta de atributos</title> + + <programlisting><![ RCDATA [<p align='right'>Eu estou a direita!</p>]]></programlisting> + </example> + + <para>Algumas vezes você não precisa utilizar aspas + em volta de todos os valores dos atributos. Entretanto, a + regra para fazer isso é muito sutil, e é muito + mais simples <emphasis>sempre</emphasis> utilizar as aspas em + volta dos valores dos seus atributos.</para> + + <para>A informação nos atributos, elementos e tags + são armazenados nos catálogos SGML. Várias + ferramentas do projeto de documentação utilizam + estes arquivos de catalogo para validarem o seu trabalho. As + ferramentas no <filename role="package">textproc/docproj</filename> + incluem uma variedade de arquivos de catalogo + SGML. O projeto de documentação do FreeBSD + inclui seu próprio conjunto de arquivos de catálogos. + Suas ferramentas precisam reconhecer ambos os tipos de + arquivos de catalogo.</para> + + <sect2> + <title>Para você fazer…</title> + + <para>Para poder praticar com os exemplos deste documento + você precisará instalar alguns aplicativos no + seu sistema, além de assegurar que as variáveis + de ambiente estejam corretamente configuradas.</para> + + <procedure> + <step> + <para>Faça o download e instale o + <filename role="package">textproc/docproj</filename> + a partir do sistema de ports do FreeBSD. Ele é um + <emphasis>meta-port</emphasis> o qual deve efetuar o + download e a instalação de todos os + aplicativos e arquivos de suporte que são + utilizados pelo projeto de documentação. + </para> + </step> + + <step> + <para>Adicione linhas ao seu arquivo de + inicialização do shell para configurar a + variável de ambiente + <envar>SGML_CATALOG_FILES</envar>. (Se você + não estiver trabalhando com a versão no + idioma inglês da documentação, + você pode precisar substituir o caminho com o + diretório correto para o seu idioma.)</para> + + <example id="sgml-primer-envars"> + <title><filename>.profile</filename>, para os + usuários dos shells &man.sh.1; e &man.bash.1; + </title> + + <programlisting>SGML_ROOT=/usr/local/share/sgml +SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog +SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES</programlisting> + </example> + + <example> + <title><filename>.cshrc</filename>, para os + usuários dos shell &man.csh.1; e &man.tcsh.1; + </title> + + <programlisting>setenv SGML_ROOT /usr/local/share/sgml +setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog +setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES</programlisting> + </example> + + <para>Para carregar estas variáveis, execute um + logout do sistema, logando novamente em seguida, ou + execute os comandos acima na sua linha de comando para + configurar os valores das variáveis.</para> + </step> + </procedure> + + <procedure> + <step> + <para>Crie o arquivo <filename>example.sgml</filename>, e + entre com o seguinte texto:</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + +<html> + <head> + <title>Um exemplo de arquivo HTML</title> + </head> + + <body> + <p>Este é um parágrafo contendo algum texto.</p> + + <p>Este parágrafo contém mais algum texto.</p> + + <p align="right">Este parágrafo pode estar alinhado a direita.</p> + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Tente validar este arquivo utilizando um interpretador + SGML.</para> + + <para>Um dos componentes do + <filename role="package">textproc/docproj</filename> + é o <command>onsgmls</command>, um <link + linkend="sgml-primer-validating">interpretador de + validação</link>. Normalmente, o + <command>onsgmls</command> lê um documento marcado + de acordo com um DTD SGML e retorna uma cópia do + conjunto de informações sobre a estrutura + dos elementos (ESIS, mas isso não é + importante agora).</para> + + <para>Entretanto, quando o <command>onsgmls</command> + é executado com o parâmetro + <option>-s</option>, ele irá suprimir o output + normal, e imprimir apenas as mensagens de erro. Isto o + torna um meio útil de verificar se o seu documento + é válido ou não.</para> + + <para>Utilize o <command>onsgmls</command> para verificar + se o seu documento é válido:</para> + + <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput></screen> + + <para>Como você irá ver, o + <command>onsgmls</command> irá executar sem + retornar nenhuma mensagem. Isto significa que o seu + documento foi validado com sucesso.</para> + </step> + + <step> + <para>Veja o que acontece quando um elemento + obrigatório é omitido. Tente remover as + tags <sgmltag>title</sgmltag> e <sgmltag>/title</sgmltag> + , e execute novamente a validação.</para> + + <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput> +onsgmls:example.sgml:5:4:E: character data is not allowed here +onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> + + <para>As mensagens de erro emitidas pelo + <command>onsgmls</command> são organizadas em + grupos separados por dois pontos, ou colunas.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Coluna</entry> + <entry>Propósito</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>O nome do programa que está gerando + o erro. Ela será sempre + <literal>onsgmls</literal>.</entry> + </row> + + <row> + <entry>2</entry> + <entry>O nome do arquivo que contém o erro. + </entry> + </row> + + <row> + <entry>3</entry> + <entry>Número da linha na qual o erro + aparece.</entry> + </row> + + <row> + <entry>4</entry> + <entry>Número da coluna na qual o erro + aparece.</entry> + </row> + + <row> + <entry>5</entry> + <entry>Um código de uma letra indicando a + natureza da mensagem. <literal>I</literal> indica + uma mensagem informativa, <literal>W</literal> + é para um aviso, e <literal>E</literal> + é para um erro <footnote> + <para>Ele não está sempre na + quinta coluna. O + <command>onsgmls -sv</command> exibe + <literal>onsgmls:I: "OpenSP" version "1.5.2" + </literal> (depende da versão + instalada). Como você pode ver, + esta é uma mensagem informativa.</para> + </footnote>, e <literal>X</literal> é + para uma referência cruzada. Como + você pode ver, estas mensagens são + erros.</entry> + </row> + + <row> + <entry>6</entry> + <entry>O texto da mensagem.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>A simples omissão das tags + <sgmltag>title</sgmltag> gerou 2 erros diferentes.</para> + + <para>O primeiro erro indica que o conteúdo (neste caso, + caracteres, ou melhor, a tag de inicio de um elemento) + ocorreu onde o interpretador SGML estava esperando outra + coisa. Neste caso, o interpretador estava esperando + encontrar uma das tags de início para os elementos + que são válidos dentro do + <sgmltag>head</sgmltag> (como a <sgmltag>title</sgmltag> + ).</para> + + <para>O segundo erro é porque o elemento + <sgmltag>head</sgmltag> <emphasis>deve</emphasis> conter + o elemento <sgmltag>title</sgmltag>. Por causa disso o + <command>onsgmls</command> considera que o elemento + não foi corretamente finalizado. Entretanto, a + tag de finalização indica que o elemento + foi fechado antes que estivesse terminado.</para> + </step> + + <step> + <para>Coloque de volta o elemento + <sgmltag>title</sgmltag>.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="sgml-primer-doctype-declaration"> + <title>A declaração DOCTYPE</title> + + <para>O inicio de cada documento que você escrever deve + especificar o nome do DTD o qual se aplica ao seu documento. Isto + deve ser feito para que os interpretadores SGML possam determinar + o DTD e assegurar que o documento esta em conformidade com o + mesmo.</para> + + <para>Esta informação é geralmente + expressada em uma linha, na declaração + DOCTYPE.</para> + + <para>Uma declaração típica para um + documento escrito para conformar-se com a versão 4.0 + do DTD HTML se parece com esta:</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> + + <para>Esta linha contém diferentes componentes.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>É o <emphasis>indicador</emphasis> que indica + que se trata de uma declaração SGML. Esta + linha está declarando o tipo do documento.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Mostra que esta é uma declaração + SGML para o tipo de documento.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>O nome do primeiro + <link linkend="sgml-primer-elements">elemento</link> o + qual irá aparecer no documento</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal> + </term> + + <listitem> + <para>Lista o Identificador Público Formal (FPI) + <indexterm> <primary>Identificar Público + Formal</primary> </indexterm> para o DTD ao qual este + documento conforma-se. O seu interpretador SGML + irá utiliza-lo para encontrar o DTD correto quando + estiver processando o documento.</para> + + <para>O <literal>PUBLIC</literal> não faz parte do + FPI, ele indica para o processador SGML como localizar + o DTD referenciado na FPI. Outras formas de informar ao + interpretador SGML como localizar o DTD serão + abordadas <link + linkend="sgml-primer-fpi-alternatives">mais tarde</link> + .</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Retorno ao documento.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title>Identificadores públicos formais (FPIs) + <indexterm significance="preferred"><primary>Identificadores + Públicos Formais</primary></indexterm> +</title> + + <note> + <para>Você não precisa conhecê-los, mas + eles são um background útil, e podem + ajudá-lo a depurar problemas quando o seu + processador SGML não puder localizar o DTD que + você esta utilizando.</para> + </note> + + <para>Os FPIs devem seguir uma sintaxe específica. + Esta sintaxe é a seguinte:</para> + + <programlisting>"<replaceable>Proprietário</replaceable>//<replaceable>Palavra-Chave</replaceable> <replaceable>Descrição</replaceable>//<replaceable>Idioma</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Proprietário</replaceable></term> + + <listitem> + <para>Isto indica o proprietário da FPI.</para> + + <para>Se este conjunto de caracteres começar + com <quote>ISO</quote> significará que o FPI + é de propriedade do ISO. Por exemplo, a FPI + <literal>"ISO 8879:1986//ENTITIES Greek Symbols//EN" + </literal> lista o <literal>ISO 8879:1986</literal> + como sendo o proprietário do conjunto de + entidades dos símbolos Gregos. O ISO 8879:1986 + é o numero da ISO para o padrão SGML. + </para> + + <para>De outra forma, este conjunto de caracteres + irá se parecer com <literal>-//<replaceable> + Proprietário</replaceable></literal> ou + <literal>+//<replaceable>Proprietário + </replaceable></literal> (Observe que a única + diferença é a introdução do + <literal>+</literal> ou do <literal>-</literal>).</para> + + <para>Se o conjunto de caracteres começar com + <literal>-</literal> significa que o + proprietário da informação + não é registrado, se começar com + um <literal>+</literal> significa que ele é + registrado.</para> + + <para>O ISO 9070:1991 define como os nomes registrados + são gerados; ele pode ser derivado do numero de + uma publicação ISO, de um código + ISBN, ou um código de organização + atribuído de acordo com o ISO 6523. Além disso, + uma autoridade de registro pode ser criada a fim de + atribuir nomes registrados. O conselho ISO delegou + isto ao <literal>American National Standards + Institute</literal> (ANSI).</para> + + <para>Como o Projeto FreeBSD não foi registrado o + conjunto de caracteres de proprietário é + <literal>-//FreeBSD</literal>. E como você pode + ver, o W3C também não é um + proprietário registrado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Palavra-Chave</replaceable></term> + + <listitem> + <para>Existem diversas palavras-chave as quais indicam o + tipo de informação no arquivo. Algumas + das palavras chaves mais comuns são + <literal>DTD</literal>, <literal>ELEMENT</literal>, + <literal>ENTITIES</literal>, e <literal>TEXT</literal>. + A palavra chave <literal>DTD</literal> é + utilizada apenas para os arquivos DTD, a + <literal>ELEMENT</literal> é normalmente + utilizada para fragmentos DTD os quais contenham + apenas entidades e declarações de + elementos. A palavra <literal>TEXT</literal> é + utilizada para o conteúdo SGML (texto e tags). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Descricão</replaceable></term> + + <listitem> + <para>Qualquer descrição que você + deseje fornecer para o conteúdo deste arquivo. + O que pode incluir um número de versão ou + qualquer texto curto o qual seja significativo para + você e único para o sistema SGML.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Idioma</replaceable></term> + + <listitem> + <para>Este é um código ISO de duas letras o + qual identifica o idioma nativo do arquivo. O + código <literal>EN</literal> é utilizado + para o idioma inglês.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title>Arquivos de <filename>catálogo</filename> + </title> + + <para>Se você utilizar a sintaxe acima e processar este + documento utilizando um processador SGML, o processador + irá precisar de uma forma de associar a FPI ao nome + do arquivo no seu computador o qual contém o DTD. + </para> + + <para>Para isto devemos utilizar um arquivo de + catálogo. Um arquivo de catálogo (tipicamente + chamado de <filename>catalog</filename>) contém + linhas as quais mapeiam FPIs para nomes de arquivos. Por + exemplo, se o arquivo de catálogo contiver a linha: + </para> + + <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> + + <para>O processador SGML saberia que deveria procurar pelo + DTD <filename>strict.dtd</filename> no subdiretório + <filename>4.0</filename> de qualquer diretório que + possuísse um arquivo <filename>catalog</filename> contendo + esta linha.</para> + + <para>Veja o conteúdo do + <filename>/usr/local/share/sgml/html/catalog</filename>. + Este é o arquivo de catálogo para o DTD HTML + o qual será instalado como parte do port + <filename role="package">textproc/docproj</filename>.</para> + </sect3> + + <sect3> + <title><envar>SGML_CATALOG_FILES</envar></title> + + <para>A fim de encontrar um arquivo de + <filename>catálogo</filename>, o seu processador SGML + precisará saber onde procurar. Muitos deles possuem + recursos de parâmetros de linha de comando para + especificar o caminho para um ou mais catálogos. + </para> + + <para>Adicionalmente, você pode definir a + variável de ambiente + <envar>SGML_CATALOG_FILES</envar> para apontar para os + arquivos. Esta variável deve consistir de uma + lista, separada por dois pontos (":"), de arquivos de + catálogo (incluindo seus caminhos completos).</para> + + <para>Tipicamente, você precisará incluir os + seguintes arquivos:</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/share/sgml/docbook/4.1/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/html/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> + </listitem> + </itemizedlist> + + <para>Você <link linkend="sgml-primer-envars">já + deve ter feito isto</link>.</para> + </sect3> + </sect2> + + <sect2 id="sgml-primer-fpi-alternatives"> + <title>Alternativas aos FPIs</title> + + <para>Ao invés de utilizar um FPI para indicar o DTD ao + qual o documento conforma-se (e consequentemente, quais + arquivos no sistema contém o DTD), você pode + especificar explicitamente o nome do arquivo. </para> + + <para>A sintaxe para isto é ligeiramente diferente: + </para> + + <programlisting><![ RCDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + + <para>A palavra chave <literal>SYSTEM</literal> indica que o + processador SGML deve encontrar o DTD em um local + específico do sistema. Isto tipicamente (mas + não sempre) significa que o DTD será fornecido + como um nome de arquivo.</para> + + <para>O uso de FPIs é preferido por razões de + portabilidade. Você pode não desejar ter que + enviar uma cópia do DTD junto com seu documento, e + se você utilizasse um identificador + <literal>SYSTEM</literal> todos necessitariam manter os seus + DTDs no mesmo lugar que você.</para> + </sect2> + </sect1> + + <sect1 id="sgml-primer-sgml-escape"> + <title>Voltando para o SGML</title> + + <para>Como mencionado anteriormente, o SGML é utilizado + somente quando escrevemos um DTD. Isto não é + estritamente verdade. Existem certas sintaxes SGML as quais + você poderá desejar utilizar com os seus + documentos. Por exemplo, você pode incluir + comentários no seu documento, e eles serão + ignorados pelo interpretador. Os comentários são + adicionados utilizando sintaxe SGML. Outros usos para a sintaxe + SGML no seu documento serão mostrados mais tarde.</para> + + <para>Obviamente, você precisa indicar de alguma forma ao + processador SGML que o conteúdo seguinte não se + trata de elementos do documento, mas sim de SGML sobre o qual + o interpretador deve atuar.</para> + + <para>Estas sessões são marcadas no seu documento + com <literal><! ... ></literal>. Tudo entre estes + delimitadores é sintaxe SGML tal como você pode + encontrar dentro de um DTD.</para> + + <para>Como você pode perceber, a + <link linkend="sgml-primer-doctype-declaration"> + declaração DOCTYPE </link> é um exemplo + de sintaxe SGML a qual você precisa incluir no seu + documento.</para> + </sect1> + + <sect1 id="sgml-primer-comments"> + <title>Comentários</title> + + <para>Comentários são uma construção + SGML, e são normalmente válidos apenas dentro de + um DTD. Entretanto, como mostrou a + <xref linkend="sgml-primer-sgml-escape"/>, é possível + utilizar sintaxe SGML com os seus documentos.</para> + + <para>O delimitador para um comentário SGML é o + conjunto de caracteres <quote><literal>--</literal></quote>. + A primeira ocorrência deste conjunto de caracteres abre + um comentário e a segunda fecha.</para> + + <example> + <title>Comentário SGML genérico</title> + + <programlisting><!-- Teste de comentário --></programlisting> + + <programlisting><![ RCDATA [ +<!-- Este é o interior do comentário --> + +<!-- Este é outro comentário --> + +<!-- Esta é uma forma + de fazer comentários de várias linhas --> + +<!-- Esta é outra forma -- + -- de fazer comentários de várias linhas -->]]></programlisting> + </example> + + <![ %output.print; [ + <important> + <title>Utilize 2 traços</title> + + <para>Existe um problema com a produção de + versões Postscript e PDF deste documento. O exemplo + acima provavelmente mostra apenas um símbolo de + hífen, <literal>-</literal> depois do + <literal><!</literal> e antes do <literal>></literal>. + </para> + + <para>Você <emphasis>deve</emphasis> utilizar dois + <literal>-</literal> e <emphasis>não</emphasis> um. + As versões Postscript e PDF traduzem os dois + <literal>-</literal> do original para um mais longo, e mais + profissional <emphasis>em-dash</emphasis>, e quebra este + exemplo no processo.</para> + + <para>As versões HTML, texto plano, e RTF deste + documento não são afetadas.</para> + </important> + ]]> + + <para>Se você já utilizou HTML antes, você pode ter + sido exposto a regras diferentes para comentários. Em + particular, você pode pensar que o conjunto de caracteres + <literal><!--</literal> abre um comentário e que ele + apenas é fechado por um <literal>--></literal>.</para> + + <para>Este <emphasis>não</emphasis> é o caso. + Muitos dos navegadores web possuem interpretadores HTML + quebrados, e irão aceitar isso como válido. + Entretanto, os interpretadores SGML utilizados pelo projeto + de documentação são muito mais + rígidos, e irão rejeitar os documentos que + contiverem este erro.</para> + + <example> + <title>Comentários SGML errados</title> + + <programlisting><![ RCDATA [ +<!-- Este é o comentário -- + + Isto está fora do comentário! + + -- de volta para dentro do comentário -->]]></programlisting> + + <para>O interpretador SGML irá tratar isto como ele + é realmente;</para> + + <programlisting><!Isto está fora do comentário></programlisting> + + <para>Isto não é um SGML válido, e pode + dar mensagens de erro confusas.</para> + + <programlisting><![ RCDATA [<!--------------- Isto é uma idéia muito ruim --------------->]]></programlisting> + + <para>E como o exemplo sugere, <emphasis>não escreva + </emphasis> comentários como esse.</para> + + <programlisting><![ RCDATA [<!--===================================================-->]]></programlisting> + + <para>Esta é uma abordagem (ligeiramente) melhor, mas + ele ainda é potencialmente confuso para as pessoas + novas no uso do SGML.</para> + + </example> + + <sect2> + <title>Para você fazer…</title> + + <procedure> + <step> + <para>Adicione alguns comentários ao arquivo + <filename>example.sgml</filename> e verifique se ele + continua válido usando o <command>onsgmls</command>. + </para> + </step> + + <step> + <para>Adicione alguns comentários inválidos ao + <filename>example.sgml</filename> e veja as mensagens de + erro que o <command>onsgmls</command> emite quando + encontra um comentário inválido.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="sgml-primer-entities"> + <title>Entidades</title> + + <para>Entidades são um mecanismo para atribuir nomes para + pedaços de conteúdo. Quando o interpretador + SGML processar o seu documento, qualquer entidade que ele + encontrar será substituída pelo conteúdo da + entidade.</para> + + <para>Esta é uma boa forma de ter pedaços de + conteúdo reutilizáveis e facilmente + alteráveis em seus documentos SGML. Esta é + também a única forma de incluir um arquivo + marcado dentro de outro utilizando SGML.</para> + + <para>Existem dois tipos de entidades que podem ser utilizadas + em duas situações diferentes; + <emphasis>Entidades gerais</emphasis> e + <emphasis>Entidades de parâmetros</emphasis>.</para> + + <sect2 id="sgml-primer-general-entities"> + <title>Entidades gerais</title> + + <para>Você não pode utilizar uma entidade geral + em um contexto SGML (embora você as defina em um). + Elas podem ser utilizadas apenas no seu documento. Compare + isto com as <link linkend="sgml-primer-parameter-entities"> + entidades de parâmetros</link>.</para> + + <para>Cada entidade geral possui um nome. Quando você + quer referenciar uma entidade geral (e consequentemente + incluir o texto que ela representa no seu documento), + você escreve + <literal>&<replaceable>nome-da-entidade</replaceable>;</literal>. + Por exemplo, suponha que você possui uma + entidade chamada <literal>current.version</literal>, a qual + expande para a versão atual do seu produto. + Você pode escrever:</para> + + <programlisting><![ RCDATA [<para>A versão atual do nosso produto é &current.version;.</para>]]></programlisting> + + <para>Quando o número de versão mudar, + você pode simplesmente alterar a definição + do valor da entidade geral e reprocessar o seu documento. + </para> + + <para>Você também pode utilizar entidades gerais + para incorporar caracteres que você não poderia + incorporar de outra forma em um documento SGML. Por exemplo, + os caracteres <literal><</literal> e + <literal>&</literal> não podem aparecer normalmente + em um documento SGML. Quando o interpretador SGML vê + o símbolo <literal><</literal> ele assume que + aquilo é uma tag (uma tag de abertura ou de fechamento) + que está a ponto de aparecer, e quando ele vê o + símbolo <literal>&</literal> ele assume que o + próximo texto será o nome de uma entidade. + </para> + + <para>Felizmente, você pode utilizar as duas entidades + gerais <literal>&lt;</literal> e + <literal>&amp;</literal> sempre que você precisar + incluí-los.</para> + + <para>Uma entidade geral só pode ser definida dentro de + um contexto SGML. Tipicamente, isto é feito + imediatamente depois da declaração DOCTYPE. + </para> + + <example> + <title>Definindo uma entidade geral</title> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]>]]></programlisting> + + <para>Observe como a declaração DOCTYPE foi + estendida adicionando-se um colchete no final da primeira + linha. As duas entidades estão definidas nas + próximas duas linhas, antes que o colchete seja + fechado, e então a declaração DOTYPE + é fechada.</para> + + <para>O colchete é necessário para indicar + que nós estamos extendendo o DTD indicado pela + declaração DOCTYPE.</para> + </example> + </sect2> + + <sect2 id="sgml-primer-parameter-entities"> + <title>Entidades de parâmetro</title> + + <para>Assim como as + <link linkend="sgml-primer-general-entities">entidades gerais</link> + , as entidades de parâmetro são utilizadas para + atribuir um nome a pedaços reutilizáveis de + texto. Entretanto, enquanto as entidades gerais só + podem ser utilizadas com o seu documento, as entidades de + parâmetro podem ser utilizadas apenas dentro de um + <link linkend="sgml-primer-sgml-escape">contexto SGML</link>. + </para> + + <para>As entidades de parâmetro são definidas de uma + forma similar as entidades gerais. Entretanto, ao + invés de utilizar + <literal>&<replaceable>nome-da-entidade</replaceable>;</literal> + como referência, utiliza + <literal>%<replaceable>nome-da-entidade</replaceable>;</literal> + <footnote><para>Entidades de + <emphasis>P</emphasis>arâmetro utilizam o símbolo de + <emphasis>P</emphasis>orcentagem.</para> </footnote>. + A definição também inclui o + <literal>%</literal> entre a palavra chave + <literal>ENTITY</literal> e o nome da entidade.</para> + + <example> + <title>Definindo entidades de parâmetros</title> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY % param.some "some"> +<!ENTITY % param.text "text"> +<!ENTITY % param.new "%param.some more %param.text"> + +<!-- %param.new agora contém "some more text" --> +]>]]></programlisting> + </example> + + <para>Isto pode não parecer particularmente + útil. Mas ele será.</para> + + </sect2> + + <sect2> + <title>Para você fazer…</title> + + <procedure> + <step> + <para>Adicione uma entidade geral ao + <filename>example.sgml</filename>.</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ +<!ENTITY version "1.1"> +]> + +<html> + <head> + <title>Um exemplo de arquivo HTML</title> + </head> + + <!-- Você pode ter alguns comentários aqui também --> + + <body> + <p>Este é um parágrafo contendo algum texto.</p> + + <p>Este parágrafo contém mais algum texto.</p> + + <p align="right">Este parágrafo pode estar alinhado a direita.</p> + + <p>A versão atual deste documento é: &version;</p> + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Valide o documento utilizando o <command>onsgmls + </command></para> + </step> + + <step> + <para>Carregue o arquivo <filename>example.sgml</filename> + no seu navegador web (Você pode precisar + copiá-lo para <filename>example.html</filename> + antes que o seu navegador possa reconhecê-lo como + um documento HTML).</para> + + <para>A menos que o seu navegador seja muito + avançado, você não irá ver a + entidade referenciada por <literal>&version;</literal> + substituída pelo número de versão. + A maioria dos navegadores web possuem interpretadores + muito simplistas os quais não manuseiam + corretamente SGML <footnote><para>Isto é uma + vergonha. Imagine todos os problemas e <literal>hacks + </literal> (tais como os Server Side Includes) que + poderiam ser evitados se eles o fizessem.</para> + </footnote>.</para> + </step> + + <step> + <para>A solução é + <emphasis>normalizar</emphasis> seu documento utilizando + um normalizador SGML. Um normalizador lê um SGML + válido e retorna um SGML igualmente válido + o qual foi transformado de alguma forma. Uma das formas + em que o normalizador transforma o SGML é + expandindo todas as entidades referenciadas no documento, + substituindo as entidades pelo texto que elas + representam.</para> + + <para>Você pode utilizar o <command>osgmlnorm + </command> para fazer isto:</para> + + <screen>&prompt.user; <userinput>osgmlnorm example.sgml > example.html</userinput></screen> + + <para>Você deve encontrar uma cópia + normalizada (isto é, entidades referenciadas + expandidas) do seu documento no arquivo + <filename>example.html</filename>, pronta para ser + carregada no seu navegador web.</para> + </step> + + <step> + <para>Se você examinar o retorno do + <command>osgmlnorm</command> você ira ver que ele + não inclui a declaração DOCTYPE no + inicio. Para incluí-la você precisa + utilizar a opção <option>-d</option>:</para> + + <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="sgml-primer-include"> + <title>Utilizando entidades para incluir arquivos</title> + + <para>As entidades (ambas <link + linkend="sgml-primer-general-entities">gerais</link> e de <link + linkend="sgml-primer-parameter-entities">parâmetros</link>) + são particularmente úteis quando utilizadas + para incluir um arquivo dentro de outro.</para> + + <sect2 id="sgml-primer-include-using-gen-entities"> + <title>Utilizando entidades gerais para incluir arquivos</title> + + <para>Suponha que você possui algum conteúdo para um + livro SGML organizado em arquivos, um arquivo por capítulo, + chamados <filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, e assim por diante, com + um arquivo <filename>book.sgml</filename> que irá + conter estes capítulos.</para> + + <para>A fim de utilizar o conteúdo destes arquivos como + os valores para as suas entidades, você as declara com + a palavra chave <literal>SYSTEM</literal>. Isto direciona o + interpretador SGML para utilizar o conteúdo dos + arquivos nomeados como o valor da entidade.</para> + + <example> + <title>Utilizando entidades gerais para incluir + arquivos</title> + + <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> +<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> +<!ENTITY chapter.3 SYSTEM "chapter3.sgml"> +<!-- e assim por diante --> +]> + +<html> + <!-- Utilize as entidades para carregar os capítulos --> + + &chapter.1; + &chapter.2; + &chapter.3; +</html>]]></programlisting> + </example> + + <warning> + <para>Quando utilizar uma entidade geral para incluir outros + arquivos em um documento, os arquivos que estiverem sendo + inclusos (<filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, etc) + <emphasis>não devem</emphasis> iniciar com uma + declaração DOCTYPE. Isto é um erro + de sintaxe.</para> + </warning> + </sect2> + + <sect2> + <title>Utilizando entidades de parâmetro para incluir + arquivos</title> + + <para>Recorde-se que uma entidade de parâmetro só pode + ser utilizada dentro de um contexto SGML. Por que + então você desejaria incluir um arquivo dentro + de um contexto do SGML?</para> + + <para>Você pode utilizar isto para assegurar-se de que + você pode reutilizar as suas entidades gerais.</para> + + <para>Suponha que você possui muitos capítulos em seu + documento, e você reutiliza estes capítulos em dois + livros diferentes, cada livro organizando os capítulos de + uma forma diferente.</para> + + <para>Você pode listar as entidades no topo de cada + livro, mas isto rapidamente torna-se incomodo de gerenciar. + </para> + + <para>Em vez de disso, coloque as definições das + suas entidades gerais em um arquivo, e utilize uma entidade + de parâmetro para incluir este arquivo dentro do seu + documento.</para> + + <example> + <title>Utilizando entidades de parâmetro para incluir + arquivos.</title> + + <para>Primeiro, coloque as suas definições de + entidades em um arquivo separado, chamado + <filename>chapters.ent</filename>. Este arquivo + contém o seguinte:</para> + + <programlisting><![ RCDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> +<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> +<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> + + <para>Agora crie uma entidade de parâmetro para referenciar + o conteúdo do arquivo. E então utilize a + entidade de parâmetro para carregar o arquivo no seu + documento, o que tornará todas as entidades gerais + disponíveis para uso. Feito isso, utilize as + entidades gerais como antes;</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!-- Define uma entidade de parâmetro para carregar as entidades gerais de capitulo --> +<!ENTITY % chapters SYSTEM "chapters.ent"> + +<!-- Agora utilize a entidade de parâmetro para carregar neste arquivo --> +%chapters; +]> + +<html> + &chapter.1; + &chapter.2; + &chapter.3; +</html>]]></programlisting> + </example> + </sect2> + + <sect2> + <title>Para você fazer…</title> + + <sect3> + <title>Utilizando entidades gerais para incluir arquivos + </title> + + <procedure> + <step> + <para>Crie três arquivos, + <filename>para1.sgml</filename>, + <filename>para2.sgml</filename>, e + <filename>para3.sgml</filename>.</para> + + <para>Coloque um conteúdo similar ao seguinte em + cada arquivo:</para> + + <programlisting><![ RCDATA [<p>Este é o primeiro parágrafo.</p>]]></programlisting> + </step> + + <step> + <para>Edite o arquivo <filename>example.sgml</filename> + para que ele se pareça com este:</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.sgml"> +<!ENTITY para2 SYSTEM "para2.sgml"> +<!ENTITY para3 SYSTEM "para3.sgml"> +]> + +<html> + <head> + <title>Um exemplo de arquivo HTML</title> + </head> + + <body> + <p>A versão atual deste documento é: &version;</p> + + &para1; + &para2; + &para3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Produza o arquivo + <filename>example.html</filename> através da + normalização do arquivo + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Carregue o arquivo + <filename>example.html</filename> no seu navegador web, + e confirme que os arquivos + <filename>para<replaceable>n</replaceable>.sgml</filename> + foram incluídos no <filename>example.html</filename>. + </para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Utilizando uma entidade de parâmetro para incluir + arquivos.</title> + + <note> + <para>Você deve ter executado os passos anteriores + primeiro.</para> + </note> + + <procedure> + <step> + <para>Edite o arquivo + <filename>example.sgml</filename> para que ele se + pareça com este:</para> + + <programlisting><![ RCDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY % entities SYSTEM "entities.sgml"> %entities; +]> + +<html> + <head> + <title>Um exemplo de arquivo HTML</title> + </head> + + <body> + <p>A versão atual deste documento é: &version;</p> + + &para1; + &para2; + &para3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Crie um novo arquivo chamado + <filename>entities.sgml</filename>, com este + conteúdo:</para> + + <programlisting><![ RCDATA [<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.sgml"> +<!ENTITY para2 SYSTEM "para2.sgml"> +<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> + </step> + + <step> + <para>Produza o arquivo <filename>example.html</filename> + através da normalização do arquivo + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Carregue o arquivo + <filename>example.html</filename> no seu navegador web + e confirme que os arquivos + <filename>para<replaceable>n</replaceable>.sgml</filename> + foram incluídos no arquivo + <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1 id="sgml-primer-marked-sections"> + <title>Sessões marcadas</title> + + <para>O SGML fornece um mecanismo para indicar que uma parte + particular do documento deve ser processada de uma forma + especial. Estas partes são denominadas + <quote>sessões marcadas</quote>.</para> + + <example> + <title>Estrutura de uma sessão marcada</title> + + <programlisting><![ <replaceable>Palavra-chave</replaceable> [ + Conteúdo da sessão marcada +]]></programlisting> + </example> + + <para>Como você esperaria, sendo uma + construção SGML, uma sessão + marcada inicia com um <literal><!</literal>.</para> + + <para>O primeiro colchete começa a limitar a sessão + marcada.</para> + + <para>A <replaceable>Palavra-chave</replaceable> descreve como + esta sessão marcada deve ser processada pelo + interpretador.</para> + + <para>O segundo colchete indica que o conteúdo da + sessão marcada inicia aqui.</para> + + <para>A sessão marcada é finalizada pelo fechamento + dos dois colchetes e então retornando ao contexto do + documento a partir do contexto SGML com o + <literal>></literal>.</para> + + <sect2> + <title>Palavras-Chave de sessões marcadas</title> + + <sect3> + <title><literal>CDATA</literal>, + <literal>RCDATA</literal></title> + + <para>Estas palavras chave denotam o <emphasis>modelo do + conteúdo</emphasis> das sessões marcadas, e + permitem que você o altere a partir do padrão. + </para> + + <para>Quando um interpretador SGML esta processando um + documento ele tenta seguir o que chamamos de <quote>modelo + de conteúdo</quote></para> + + <para>Resumidamente, o modelo de conteúdo descreve + que tipo de conteúdo o interpretador esta esperando + encontrar, e o que fará com ele quando o encontrar. + </para> + + <para>Os dois modelos de conteúdo que você + provavelmente irá achar mais úteis + são o <literal>CDATA</literal> e o + <literal>RCDATA</literal>.</para> + + <para>O <literal>CDATA</literal> é para + <quote>Dados de Caracter</quote>. Se o interpretador + está neste modelo de conteúdo então ele + está esperando encontrar caracteres, e apenas + caracteres. Neste modelo os símbolos + <literal><</literal> e o <literal>&</literal> + perdem o seu status especial, e serão tratados como + caracteres ordinários.</para> + + <para>O <literal>RCDATA</literal> é para + <quote>Referências de entidade e dados de caracter + </quote>. Se o interpretador está neste + modelo de conteúdo ele está esperando + encontrar caracteres <emphasis>e</emphasis> entidades. + O símbolo <literal><</literal> perde + o seu status especial, mas o <literal>&</literal> + continuará sendo tratado como o inicio de uma + entidade geral.</para> + + <para>Isto é particularmente útil se você + está incluindo algum texto literal o qual + contém muitos caracteres <literal><</literal> e + <literal>&</literal>. Ao invés de atravessar o + texto todo tendo que verificar se todos os + <literal><</literal> estão convertidos para um + <literal>&lt;</literal> e todos os + <literal>&</literal> estão convertidos para um + <literal>&amp;</literal> pode ser mais simples marcar + a sessão como contendo apenas + <literal>CDATA</literal>. Quando o interpretador SGML + encontrá-los ele irá ignorar os símbolos + <literal><</literal> e <literal>&</literal> + embutidos no conteúdo.</para> + + <note> + <para>Quando você utiliza <literal>CDATA</literal> ou + <literal>RCDATA</literal> nos exemplos de texto marcado em + SGML, tenha em mente que o conteúdo do + <literal>CDATA</literal> não é validado. + Você tem que verificar o SGML incluso no texto + utilizando algum outro meio. Você pode, por + exemplo, escrever o exemplo em outro documento, + validar o código de exemplo, e então + colá-lo para o seu conteúdo + <literal>CDATA</literal>.</para> + </note> + + <!-- O assentamento de CDATA dentro do exemplo seguinte é repugnante --> + + <example> + <title>Utilizando uma sessão marcada como + CDATA</title> + + <programlisting><para>Aqui está um exemplo de como você incluiria algum texto que contenha muitos + símbolos <literal>&lt;</literal> e <literal>&amp;</literal>. + O texto de exemplo é um fragmento de HTML. + O texto circunvizinho (<para> e <programlisting>) é do + DocBook.</para> + +<programlisting> + <![ CDATA [ <![ RCDATA [ + <p>Esta é uma amostra que apresenta alguns elementos de HTML. + Uma vez que os símbolos de < e > são utilizados muitas vezes, é + mais fácil dizer que o exemplo todo é uma sessão marcada do + tipo CDATA, do que utilizar nomes de entidades para representar + estes símbolos ao longo de todo o texto.</p> + + <ul> + <li>Este é um item de lista</li> + <li>Este é um segundo item de lista</li> + <li>Este é um terceiro item de lista</li> + </ul> + + <p>Este é o final do exemplo.</p>]]> + ]]> +</programlisting></programlisting> + + <para>Se você examinar o fonte deste documento + você irá ver que esta técnica foi + utilizada por toda parte.</para> + </example> + </sect3> + + <sect3> + <title><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para>Se a palavra chave for <literal>INCLUDE</literal> + então o conteúdo da sessão marcada + será processado. Se a palavra chave for + <literal>IGNORE</literal> então a sessão + marcada será ignorada e não será + processada. Ela não irá aparecer no + output.</para> + + <example> + <title>Utilizando <literal>INCLUDE</literal> e + <literal>IGNORE</literal> nas sessões marcadas</title> + + <programlisting><![ INCLUDE [ + Este texto será processado e incluído. +]]> + +<![ IGNORE [ + Este texto não será processado nem incluído. +]]></programlisting> + </example> + + <para>Por si só, isto não é muito + útil. Se você desejar remover o texto do seu + documento você pode cortá-lo fora, ou + comentá-lo.</para> + + <para>Torna-se mais útil quando você utilizar + <link linkend="sgml-primer-parameter-entities">entidades de + parâmetro</link> para controlá-lo. Lembre-se que + entidades de parâmetro só podem ser utilizadas em um + contexto SGML, e que a palavra chave de uma sessão + marcada <emphasis>é</emphasis> um contexto + SGML.</para> + + <para>Por exemplo, suponha que você produza uma + cópia impressa e uma versão eletrônica + de alguma documentação. Você pode + desejar incluir na versão eletrônica algum + conteúdo extra, o qual não deve aparecer na + versão impressa.</para> + + <para>Crie uma entidade de parâmetro, e configure seu valor + para <literal>INCLUDE</literal>. Escreva seu documento, + usando uma sessão marcada para delimitar o + conteúdo + que deve aparecer apenas na versão eletrônica. + Nesta sessão marcada utilize a entidade de parâmetro + no lugar da palavra chave.</para> + + <para>Quando você desejar produzir uma cópia + impressa do documento, altere o valor da entidade de + parâmetro para <literal>IGNORE</literal> e reprocesse o + documento.</para> + + <example> + <title>Utilizando uma entidade de parâmetro para + controlar uma sessão marcada</title> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY % electronic.copy "INCLUDE"> +]]> + +... + +<![ %electronic.copy [ + Este conteúdo deve aparecer apenas na versão eletrônica do + documento. +]]></programlisting> + + <para>Quando for produzir uma versão impressa do + documento, altere a definição da entidade + para;</para> + + <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> + + <para>Ao reprocessar o documento, a sessão marcada + que utilizar a entidade <literal>%electronic.copy + </literal> como a sua palavra chave será + ignorada.</para> + </example> + </sect3> + </sect2> + + <sect2> + <title>Para você fazer…</title> + + <procedure> + <step> + <para>Crie um novo arquivo chamado + <filename>section.sgml</filename>, o qual deve conter o + seguinte conteúdo:</para> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY % text.output "INCLUDE"> +]> + +<html> + <head> + <title>Um exemplo utilizando uma sessão marcada.</title> + </head> + + <body> + <p>Este parágrafo <![ CDATA [contêm muitos caracteres < + (< < < < <) de forma que é mais simples utilizar + uma sessão marcada do tipo CDATA.]]></p> + + <![ IGNORE [ + <p>Este parágrafo definitivamente não será incluído + no output.</p> + ]]> + + <![ <![ CDATA [%text.output]]> [ + <p>Este parágrafo pode ou não aparecer no output.</p> + + <p>A sua ocorrência é controlada pela entidade de parâmetro <![CDATA[%text.output]]> + .</p> + ]]> + </body> +</html></programlisting> + </step> + + <step> + <para>Normalize este arquivo utilizando o + <command>osgmlnorm</command> e examine o resultado. + Observe quais parágrafos apareceram, quais desapareceram + e o que aconteceu com o conteúdo da + sessão marcada como CDATA.</para> + </step> + + <step> + <para>Altere a definição da entidade + <literal>text.output</literal> de <literal>INCLUDE + </literal> para <literal>IGNORE</literal>. Re-normalize + o arquivo, e observe o resultado para ver o que foi + alterado.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="sgml-primer-conclusion"> + <title>Conclusão</title> + + <para>Esta é a conclusão da introdução + ao SGML. Devido a restrições de espaço e + complexidade, diversos assuntos não foram abordados em + profundidade (ou sequer foram abordados). Entretanto, as + sessões prévias cobriram o suficiente do SGML + para que você possa seguir a organização + da documentação do FDP.</para> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/structure/chapter.sgml new file mode 100644 index 0000000000..84ac000700 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -0,0 +1,354 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38868 + +--> + +<chapter id="structure"> + + <title>Estruturando Documentos Sob <filename>doc/</filename></title> + + <para>A árvore <filename>doc/</filename> é organizada + de uma forma particular, e os documentos que compõe o + &a.ptbr.p.fdpp; devem ser por isso organizados de forma + particular. O objetivo é tornar simples a + adição de nova documentação à + árvore, e:</para> + + <orderedlist> + <listitem> + <para>Facilitar a automatização da + conversão de documentos para outros + formatos.</para> + </listitem> + + <listitem> + <para>Promover consistência entre diferentes formas de + organizar a documentação, facilitar a troca + entre diferentes documentos.</para> + </listitem> + + <listitem> + <para>Facilitar a decisão de onde na árvore uma + nova documentação deveria ser colocada.</para> + </listitem> + </orderedlist> + + <para>Além disso, a árvore de + documentação tem de acomodar + documentação que pode estar em muitas diferentes + línguas e muitas diferentes codificações. + É importante que a estrutura da árvore de + documentação não force nenhum padrão + particular ou preferência cultural.</para> + + <sect1 id="structure-top"> + <title>O Nível Superior, <filename>doc/</filename></title> + + <para>Existem dois tipos de diretórios sob + <filename>doc/</filename>, cada um com nomes de + diretórios e significados muito específicos. + </para> + + <segmentedlist> + + <segtitle>Diretório</segtitle> + + <segtitle>Significado</segtitle> + + <seglistitem> + + <seg><filename>share/</filename></seg> + + <seg>Contém arquivos que não são + específicos as várias traduções + e codificações da documentação. + Contém subdiretórios para promover uma melhor + categorização da + informação. Por exemplo, os arquivos que + compõem a infraestrutura de &man.make.1; encontram-se + em <filename>share/mk</filename>, enquanto os arquivos + adicionais para suporte SGML (como as extensões do + FreeBSD ao DocBook DTD) encontram-se em + <filename>share/sgml</filename>.</seg> + </seglistitem> + + <seglistitem> + + <seg><filename><replaceable>idioma</replaceable>.<replaceable>codificação</replaceable>/</filename></seg> + + <seg>Existe um diretório para cada + tradução e codificação da + documentação, por exemplo + <filename>en_US.ISO8859-1/</filename> e + <filename>zh_TW.Big5/</filename>. Os nomes são + longos, mas ao especificar completamente a língua e + codificação prevenimos qualquer futura dor de + cabeça caso um time de tradução queira + prover a documentação na mesma língua + mas em mais de uma codificação. Isto + também nos isola completamente de quaisquer + problemas que possam ser causados por uma mudança + para Unicode.</seg> + </seglistitem> + </segmentedlist> + </sect1> + + <sect1 id="structure-locale"> + + <title>Os Diretórios de <filename><replaceable>idioma</replaceable>.<replaceable>codificação</replaceable></filename></title> + + <para>Estes diretórios contêm os documentos + propriamente ditos. A documentação é + dividida em até três categorias adicionais neste + nível, indicadas pelos diferentes nomes de + diretórios.</para> + + <segmentedlist> + + <segtitle>Diretório</segtitle> + + <segtitle>Conteúdo</segtitle> + + <seglistitem> + <seg><filename>articles</filename></seg> + + <seg>Documentação codificada como DocBook + <sgmltag>article</sgmltag> (ou equivalente). + Razoavelmente pequena, e separada em + seções. Normalmente disponível apenas + como um arquivo HTML.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>books</filename></seg> + + <seg>Documentação codificada como DocBook + <sgmltag>book</sgmltag> (ou equivalente). + Com o tamanho de um livro, e separada em + capítulos. Normalmente disponível tanto como + um grande arquivo HTML (para pessoas com conexões + rápidas, ou que queiram imprimí-la facilmente + a partir de um navegador Internet) quanto como uma + coleção de pequenos arquivos + interligados.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>man</filename></seg> + + <seg>Para traduções das páginas de manual + do sistema. Este diretório conterá um ou mais + diretórios + <filename>man<replaceable>n</replaceable></filename>, + correspondendo as seções que foram + traduzidas.</seg> + </seglistitem> + </segmentedlist> + + <para>Nem todo diretório + <filename><replaceable>idioma</replaceable>.<replaceable>codificação</replaceable></filename> + conterá todos estes diretórios. Isto depende de + quantos documentos já foram traduzidos pelo time de + tradução.</para> + </sect1> + + <sect1 id="structure-document"> + <title>Informação Específica do + Documento</title> + + <para>Esta sessão contém observações + específicas sobre documentos particulares controlados pelo + FDP.</para> + + <sect2> + <title>O Handbook</title> + + <subtitle><filename>books/handbook/</filename></subtitle> + + <para>O Handbook é escrito de forma a obedecer a + versão estendida do DTD DocBook utilizado pelo + projeto FreeBSD.</para> + + <para>O Handbook é organizado como um + <sgmltag>book</sgmltag> Docbook. Ele está dividido + em <sgmltag>part</sgmltag>es, e cada uma delas pode conter + diversos <sgmltag>chapter</sgmltag>s (Capítulos). Os + <sgmltag>chapter</sgmltag>s estão subdivididos + em seções (<sgmltag>sect1</sgmltag>) e + subseções (<sgmltag>sect2</sgmltag>, + <sgmltag>sect3</sgmltag>) e assim por diante.</para> + + <sect3> + <title>Organização Fisíca</title> + + <para>Existem diversos arquivos e diretórios dentro do + diretório <filename>handbook</filename>.</para> + + <note> + <para>A organização do Handbook pode mudar + ao longo do tempo, e este documento pode ficar defasado + no detalhamento destas alterações + organizacionais. Se você tiver alguma pergunta sobre + como o Handbook é organizado, por favor entre em + contato com a &a.doc;.</para> + </note> + + <sect4> + <title><filename>Makefile</filename></title> + + <para>O <filename>Makefile</filename> define algumas + variáveis as quais afetam a forma como o fonte + SGML é convertido para outros formatos, e lista + os vários arquivos fonte que compõem o + Handbook. Ele também inclui um arquivo + padrão chamado <filename>doc.project.mk</filename>, + o qual contém o restante do código + responsável por realizar a conversão dos + documentos de um formato para outro.</para> + </sect4> + + <sect4> + <title><filename>book.sgml</filename></title> + + <para>Este é o documento de mais alto nível + do Handbook. Ele contém as + <link linkend="sgml-primer-doctype-declaration"> + declarações DOCTYPE</link> do Handbook, + assim como os elementos que descrevem a estrutura do + Handbook.</para> + + <para>O <filename>book.sgml</filename> utiliza <link + linkend="sgml-primer-parameter-entities">entidades de + parâmetro</link> para carregar os arquivos com + extensão <filename>.ent</filename>. Estes + arquivos (descritos abaixo) definem as + <link linkend="sgml-primer-general-entities"> + entidades gerais</link> as quais são utilizadas + ao longo de todo o Handbook.</para> + </sect4> + + <sect4> + <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> + + <para>Cada capítulo do Handbook é armazenado + em um arquivo chamado <filename>chapter.sgml</filename> + localizado em um diretório separado dos outros + capítulos. Cada diretório é nomeado + depois do valor do atributo <literal>id</literal> no + elemento <sgmltag>chapter</sgmltag>.</para> + + <para>Por exemplo, se um dos arquivos de capítulos + contiver:</para> + + <programlisting><![ CDATA [ +<chapter id="kernelconfig"> +... +</chapter>]]></programlisting> + + <para>Então ele será chamado de + <filename>chapter.sgml</filename> e será + armazenadao no diretório <filename>kernelconfig + </filename>. Em geral, todo o conteúdo do + capítulo será mantido neste arquivo.</para> + + <para>Quando a versão HTML do Handbook for + produzida, será gerado um arquivo + <filename>kernelconfig.html</filename>. Isto ocorre + devido ao valor do atributo <literal>id</literal> e + não está relacionado ao nome do + diretório.</para> + + <para>Nas versões anteriores do Handbook os + arquivos eram armazenados no mesmo diretório + que o <filename>book.sgml</filename>, e depois nomeados + a partir do valor do atributo <literal>id</literal> + presente no elemento <sgmltag>chapter</sgmltag> do + arquivo. Agora, é possível incluir imagens + em cada capítulo. As imagens de cada + capítulo do Handbook são + armazenadas dentro de + <filename class="directory">share/images/books/handbook</filename>. + Observe que as versões localizadas destas imagens + devem ser colocadas no mesmo diretório com o + código fonte SGML de cada capítulo. + Colisões de + <foreignphrase>namespace</foreignphrase> são + inevitáveis, e é muito mais simples + trabalhar com vários diretórios que + contenham poucos arquivos em cada um, do que trabalhar + com um diretório que contenha muitos + arquivos.</para> + + <para>Um exame rápido vai mostrar que existem muitos + diretórios com um único arquivo + <filename>chapter.sgml</filename>, incluindo + <filename>basics/chapter.sgml</filename>, + <filename>introduction/chapter.sgml</filename>, e + <filename>printing/chapter.sgml</filename>.</para> + + <important> + <para>Os capítulos e/ou diretórios + não devem ser nomeados de forma que + reflitam sua ordem no Handbook. Esta + ordenação pode mudar com uma + reorganização do conteúdo + do Handbook; este tipo de reorganização + não deve (geralmente) incluir a necessidade de + renomear os arquivos (a menos que um capítulo + inteiro esteja sendo promovido ou rebaixado na + hierarquia).</para> + </important> + + <para>Cada arquivo <filename>chapter.sgml</filename> + não será um documento SGML completo. Em + particular, eles não terão as suas + próprias linhas DOCTYPE no início do + arquivo.</para> + + <para>Isto é uma infelicidade pois torna + impossível tratá-los como arquivos SGML + genéricos e simplesmente convertê-los para + HTML, RTF, PS, e outros formatos da mesma forma que o + Handbook principal é gerado. Isto irá + forçá-lo a reconstruir o Handbook inteiro + sempre que você desejar ver o efeito de uma + alteração realizada em apenas um + capítulo.</para> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..3cb3e9a9a5 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,102 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38869 + +--> + +<chapter id="stylesheets"> + <title>* Folhas de Estilo</title> + + <para>O SGML não diz nada sobre como um documento deve ser + exibido ao usuário, ou formatado para impressão. + Para fazer isto, várias linguagens foram + desenvolvidas para descrever folhas de estilo, incluindo DynaText, + Panorama, SPICE, JSSS, FOSI, CSS, e DSSSL.</para> + + <para>Para o <literal>DocBook</literal>, nós estamos usando + folhas de estilo escritas em DSSSL. Para o HTML nós + estamos usando o CSS.</para> + + <sect1 id="stylesheets-dsssl"> + <title>* DSSSL</title> + + <para>O projeto de documentação usa uma + versão ligeiramente customizada das folhas de estilo + modulares do <literal>DocBook</literal> de Norm Walsh.</para> + + <para>Elas podem ser encontradas no <filename + role="package">textproc/dsssl-docbook-modular</filename>. + </para> + + <para>As folhas de estilo modificadas não estão no + sistema de <literal>ports</literal>. Elas são parte do + repositório de fontes do projeto de + documentação, e podem ser encontradas em + <filename>doc/share/sgml/freebsd.dsl</filename>. Elas + estão bem comentadas, e como a conclusão desta + seção está pendente, recomendamos que + você examine este arquivo para ver como algumas das + opções disponíveis nas folhas de estilo + padrão foram configuradas para customizar a + saída para o projeto de documentação do + FreeBSD. Este arquivo também contém exemplos + que mostram como estender os elementos que a folha de estilo + compreende, que é como os elementos específicos + para o FreeBSD foram formatados.</para> + </sect1> + + <sect1 id="stylesheets-css"> + <title>CSS</title> + + <para>Folha de estilo em cascata (CSS) é um + mecanismo para anexar a informação de estilo + (fontes, peso, tamanho, cor, e assim por diante) aos elementos + de um documento HTML sem abusar do HTML para + fazê-lo.</para> + + <sect2> + <title>Documentos DocBook </title> + + <para>As folhas de estilo DSSSL do FreeBSD incluem uma + referência para a folha de estilo, + <filename>docbook.css</filename>, a qual espera-se aparecer + no mesmo diretório dos arquivos HTML. Este arquivo + CSS geral do projeto é copiado de + <filename>doc/share/misc/docbook.css</filename> quando os + documentos são convertidos para HTML, e é + instalado automaticamente.</para> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100755 index 0000000000..ab9828002a --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,266 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38870 + +--> + +<chapter id="the-website"> + <title>O Website</title> + + <sect1 id="the-website-prep"> + <title>Preparação</title> + + <para>Utilize um disco que tenha espaço livre suficiente. + Você irá precisar de 200 MB a 500 MB, + dependendo do método que escolher. Este espaço + irá abrigar as ferramentas SGML, um subconjunto da + árvore <application>svn</application>, os arquivos + temporários de trabalho e as páginas web + instaladas.</para> + + <note> + <para>Certifique-se que seus ports de + documentação estão atualizados! Quando + na dúvida, remova os ports antigos usando o comando + &man.pkg.delete.1; antes de instalar o port. Por exemplo, + nós atualmente dependemos do jade-1.2, e se você + tem instalado o jade-1.1, por favor execute:</para> + + <screen>&prompt.root; <userinput><command>pkg_delete jade-1.1</command></userinput></screen> + </note> + + <sect2 id="the-website-svn"> + <title>Usando o <command>svn</command></title> + + <para>O <command>svn</command> é necessário para + se obter (<quote><literal>check out</literal></quote>) os + arquivos do <literal>doc/</literal> a partir do + repositório Subversion. O <command>svn</command> pode + ser instalado com o &man.pkg.add.1; ou a partir da + coleção de Ports do &os;, executando:</para> + + <screen>&prompt.root; <userinput><command>cd /usr/ports/devel/subversion</command></userinput> +&prompt.root; <userinput><command>make</command> <maketarget>install clean</maketarget></userinput></screen> + + <para>Para obter os arquivos com o código fonte completo do + web site do &os;, execute:</para> + + <screen>&prompt.root; <userinput><command>svn checkout svn://svn.FreeBSD.org/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen> + + <tip> + <para>Se o comando <command>svn</command> não estiver sendo + executado pelo usuário <username>root</username>, + certifique-se de que o diretório <filename + class="directory">/usr/build</filename> possui as + permissões adequadas ao usuário utilizado. Se + não for possível alterar as permissões, + utilize um diretório diferente para armazenar os + arquivos do web site.</para> + </tip> + + <para>Quando o <command>svn</command> terminar, a versão + atual do website do &os; estará disponível em + <filename class="directory">/usr/build</filename>. Se vocé + utilizou um diretório alvo diferente, substitua o + <filename class="directory">/usr/build</filename> + apropriadamente ao longo do restante deste documento.</para> + + <para>É isso! Agora você pode proceder com a + <link linkend="the-website-build"> geração do + web site</link>.</para> + </sect2> + </sect1> + + <sect1 id="the-website-build"> + <title>Construa as páginas web do início</title> + + <para>Depois de ter completado os passos necessários + para obter os arquivos com o código fonte do website, + você estará pronto para iniciar a + compilação do web site. No nosso + exemplo, o diretório de compilação + é <filename + class="directory"><replaceable>/usr/build</replaceable> + </filename> e todos os arquivos necessários + já estão disponíveis no mesmo.</para> + + <procedure> + <step> + <para>Vá para o diretório de + compilação:</para> + +<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput></screen> + </step> + + <step> + <para>A compilação do web site + deve ser iniciada de dentro do diretório <filename + class="directory">en_US.ISO8859-1/htdocs</filename> + executando o comando &man.make.1; <maketarget>all + </maketarget>, para criar as páginas web:</para> + +<screen>&prompt.root; <userinput><command>cd</command> en_US.ISO8859-1/htdocs </userinput> +&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen> + </step> + </procedure> + </sect1> + + <sect1 id="the-website-install"> + <title>Instalando as web pages em seu Web Server</title> + + <procedure> + <step> + <para>Se você tiver saído do + diretório <filename + class="directory">en_US.ISO8859-1/htdocs</filename>, volte + para dele.</para> + +<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</replaceable></userinput></screen> + </step> + + <step> + <para>Execute o comando &man.make.1; <maketarget>install + </maketarget>, definindo a variável <makevar>DESTDIR + </makevar> para o nome do diretório no qual deseja + instalar os arquivos. Eles serão instalados no + <filename class="directory">$DESTDIR/data</filename> o qual + deve estar configurado para ser o diretório raiz do + seu servidor web.</para> + +<screen>&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen> + </step> + + <step> + <para>Se você já instalou previamente + as páginas web dentro deste mesmo diretório o + processo de instalação não irá + remover nenhuma página web antiga ou desatualizada. + Por exemplo, se você compilar e instalar uma nova + cópia do web site todos os dias, o comando + abaixo irá procurar e remover todos os arquivos que + não tenham sido alterados nos últimos + três dias.</para> + +<screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-print0</option> | <command>xargs</command> <option>-0</option> <command>rm</command></userinput></screen> + </step> + </procedure> + </sect1> + + <sect1 id="the-website-env"> + <title>Variáveis de ambiente</title> + + <variablelist> + <varlistentry> + <term><makevar>ENGLISH_ONLY</makevar></term> + + <listitem> + <para>Se esta variável estiver definida e não + for vazia, apenas a documentação em Inglês + será compilada e instalada. Todas as + traduções serão ignoradas. + Por exemplo:</para> + +<screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen> + + <para>Se você quiser desabilitar a variável + <makevar>ENGLISH_ONLY</makevar> e compilar todas as + páginas, incluindo traduções, basta + definir a variável <makevar>ENGLISH_ONLY</makevar> + para um valor vazio:</para> + +<screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=""</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen> + + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>WEB_ONLY</makevar></term> + + <listitem> + <para>Se esta variável estiver definida e não + for vazia, apenas as páginas HTML do diretório + <filename class="directory">en_US.ISO8859-1/htdocs</filename> + serão compiladas e instaladas. Todos os demais + documentos do diretório <filename + class="directory">en_US.ISO8859-1</filename> (Handbook, FAQ, + Tutorais, etc) serão ignorados. Por exemplo:</para> + + <screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen> + + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>WEB_LANG</makevar></term> + + <listitem> + <para>Se esta variável estiver definida, apenas as + páginas web no idioma especificado por ela + serão compiladas e instaladas dentro do + diretório <filename class="directory"> + <replaceable>/usr/build</replaceable></filename>. + Todos os demais idiomas serão ignorados. Por + exemplo:</para> + +<screen>&prompt.root; <userinput>make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install</userinput></screen> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>NOPORTSCVS</makevar></term> + + <listitem> + <para>Se esta variável estiver definida, o processo de + compilação não fará o check + out dos arquivos do ports do repositório cvs. + Ao invés disso, ele irá copiar os arquivos + a partir do <filename class="directory">/usr/ports + </filename> (ou do local definido na variável + <envar>PORTSBASE</envar>).</para> + </listitem> + </varlistentry> + </variablelist> + + <para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>, + <makevar>ENGLISH_ONLY</makevar> e <makevar>NOPORTSCVS</makevar> + são variáveis do <command>make</command>. + Você pode definir estas variáveis no + <filename>/etc/make.conf</filename>, + no <filename>Makefile.inc</filename>, ou ainda como + variáveis de ambiente na linha de comando ou nos + arquivos de inicialização do seu + <foreignphrase>shell</foreignphrase>.</para> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/tools/chapter.sgml new file mode 100644 index 0000000000..3b43646fe5 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,330 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<chapter id="tools"> + <title>Ferramentas</title> + + <para>O FDP utiliza diferentes ferramentas como auxílio no + gerenciamento da documentação do FreeBSD, e na + conversão para diferentes formatos, e assim por diante. + Você irá precisar utilizar estas ferramentas + se for trabalhar com a documentação do &os;.</para> + + <para>Todas estas ferramentas estão disponíveis como + <literal>Ports</literal> e <literal>Packages</literal> do FreeBSD, + simplificando enormemente o seu trabalho para + instalá-las.</para> + + <para>Você precisará instalar estas ferramentas antes + de trabalhar com qualquer exemplo dos próximos + capítulos. O uso real destas ferramentas será + abordado nos próximos capítulos.</para> + + <tip> + <title>Se possível use o <filename role="package"> + textproc/docproj</filename></title> + + <para>Você pode economizar bastante tempo se instalar o + <literal>port</literal> <filename + role="package">textproc/docproj</filename>. Este é um + <emphasis>meta-port</emphasis> que por si só não + contém nenhum programa. Ao invés disto, ele + depende que já estejam instalados corretamente + vários outros <literal>ports</literal>. O processo de + instalação <emphasis>irá</emphasis> + baixar e instalar automaticamente todos os pacotes + listados como necessários neste capítulo.</para> + + <para>Um dos pacotes que você pode precisar é o + conjunto de macros <application>JadeTeX</application>. No + entanto, esse conjunto de macros requer que o &tex; esteja + instalado. O &tex; é um pacote grande, e ele somente + será necessário se você quiser gerar + documentos nos formatos Postscript ou PDF.</para> + + <para>Para economizar seu tempo e espaço em disco + você deve especificar se quer, ou não, a + instalação do <application>JadeTeX</application> + (e por consequência do &tex;) quando o + <literal>port</literal> for instalado. Conforme + necessário, faça:</para> + + <screen>&prompt.root;<userinput> make JADETEX=yes install</userinput></screen> + + <para>ou</para> + + <screen>&prompt.root;<userinput> make JADETEX=no install</userinput></screen> + + <para>Alternativamente você pode instalar o + <filename role="package">textproc/docproj-jadetex</filename> ou o + <filename role="package">textproc/docproj-nojadetex</filename>. + Estes <literal>ports</literal> secundários irão + definir a variável <makevar>JADETEX</makevar> para + você, consequentemente eles irão instalar o mesmo + conjunto de aplicativos na sua máquina. Observe que + você poderá produzir apenas documentos em HTML e + ASCII se você não instalar o + <application>JadeTeX</application>. Para produzir documentos + em PostScript e PDF você irá precisar do &tex;. + </para> + </tip> + + <sect1 id="tools-mandatory"> + <title>Ferramentas Obrigatórias</title> + + <sect2> + <title>Software</title> + + <para>Estes programas são necessários para + você trabalhar com a documentação do + FreeBSD, e permitirão a conversão + da mesma para os formatos HTML, texto puro e RTF. Eles + estão todos incluídos em + <filename role="package">textproc/docproj</filename>.</para> + + <variablelist> + <varlistentry> + <term><application>Jade</application> + (<filename role="package">textproc/jade</filename>)</term> + + <listitem> + <para>Uma implementação DSSSL. Utilizado + para a conversão de documentos escritos com + linguagem de marcas para outros formatos, incluindo + HTML e &tex;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Tidy</application> + (<filename role="package">www/tidy</filename>)</term> + + <listitem> + <para>Um HTML <foreignphrase><quote>pretty printer</quote> + </foreignphrase>, utilizado para reformatar alguns dos + HTMLs gerados automaticamente ficando mais + fácil de entendê-los.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Links</application> + (<filename role="package">www/links</filename>)</term> + + <listitem> + <para>Um navegador WWW em modo texto que também + converte arquivos HTML para texto puro.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>peps</application> + (<filename role="package">graphics/peps</filename>)</term> + + <listitem> + <para>Parte da documentação inclui imagens, + algumas delas estão armazenadas como arquivos EPS. + Estas imagens precisam ser convertidas para o formato + PNG antes de serem exibidas em um navegador + <literal>web</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Entidades e DTDs</title> + + <para>Estes são os conjuntos de DTDs e de entidades + usados pelo FDP. Eles precisam estar instalados para que + você possa trabalhar com qualquer parte da + documentação.</para> + + <variablelist> + <varlistentry> + <term>HTML DTD + (<filename role="package">textproc/html</filename>)</term> + + <listitem> + <para>HTML é a linguagem de marcas escolhida para a + <literal>World Wide Web</literal>, e é usada no + <literal>web site</literal> do FreeBSD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook DTD + (<filename role="package">textproc/docbook</filename>) + </term> + + <listitem> + <para>DocBook é uma linguagem de marcas projetada + para documentação técnica. Toda a + documentação do FreeBSD está + escrita em DocBook.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ISO 8879 entities + (<filename role="package">textproc/iso8879</filename>) + </term> + + <listitem> + <para>19 dos conjuntos de entidade de caracter ISO + 8879:1986 utilizados por muitos DTDs. Inclui + símbolos matemáticos nomeados, + caracteres do conjunto de caracter Latin + (acentos, diacríticos e assim por diante), e + símbolos gregos.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Stylesheets</title> + + <para>As <literal>Stylesheets</literal> são usadas na + conversão e formatação de documentos + para serem apresentados na tela, impressos, e assim por + diante.</para> + + <variablelist> + <varlistentry> + <term>Modular DocBook Stylesheets + (<filename role="package">textproc/dsssl-docbook-modular + </filename>)</term> + + <listitem> + <para>As <literal>Modular DocBook Stylesheets</literal> + são usadas na conversão da + documentação escrita em DocBook para + outros formatos, tais como HTML ou RTF.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 id="tools-optional"> + <title>Ferramentas Opcionais</title> + + <para>Você não precisa ter qualquer uma das + ferramentas a seguir instaladas. Entretanto, você + poderá achar mais fácil trabalhar com a + documentação se elas estiverem disponíveis, + elas também oferecem uma maior flexibilidade em + relação aos formatos nos quais os documentos podem + ser gerados.</para> + + <sect2> + <title>Software</title> + + <variablelist> + <varlistentry> + <term><application>JadeTeX</application> e + <application>teTeX</application> + (<filename role="package">print/jadetex</filename> e + <filename role="package">print/teTeX</filename>)</term> + + <listitem> + <para>O <application>Jade</application> e o + <application>teTeX</application> são usados para + converter DocBook para os formatos DVI, Postscript, e + PDF. As macros do <application>JadeTeX</application> + são necessárias para estas + conversões.</para> + + <para>Se você não pretende converter seus + documentos para um destes formatos (i.e., HTML, texto + puro, e RTF são o suficiente) então + não será preciso instalar o + <application>JadeTeX</application> e + <application>teTeX</application>. Isto pode resultar em + uma boa economia de tempo e espaço em disco, + já que o <application>teTeX</application> + possui tamanho de aproximadamente 30MB.</para> + + <important> + <para>Se você decidir instalar o + <application>JadeTeX</application> e + <application>teTeX</application> então + será preciso configurar o + <application>teTeX</application> depois do + <application>JadeTeX</application> ter sido + instalado. O arquivo + <filename>print/jadetex/pkg-message</filename> + contém instruções detalhadas + sobre o que é preciso ser feito.</para> + </important> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> ou + <application>XEmacs</application> + (<filename role="package">editors/emacs</filename> ou + <filename role="package">editors/xemacs</filename>)</term> + + <listitem> + <para>Ambos editores incluem um modo especial para a + edição de documentos com uma linguagem de + marcas que siga um SGML DTD. Esse modo inclui comandos + para reduzir o volume total de digitação a + ser feita, o que ajuda a reduzir a possibilidade de + erros.</para> + + <para>Você não precisa utilizá-los, + qualquer editor pode ser usado para editar documentos + escritos com linguagem de marcas. Entretanto, + se optar por usá-los você poderá + constatar que eles tornam seu trabalho + mais eficiente.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Se alguém tiver sugestões sobre algum outro + <literal>software</literal> que seja útil para a + manipulação de documentos SGML, por favor + informe a &a.doceng;, desta forma ele poderá ser + adicionado a esta lista.</para> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/translations/chapter.sgml new file mode 100644 index 0000000000..d0a68a7347 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/translations/chapter.sgml @@ -0,0 +1,557 @@ +<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38888 + +--> + +<chapter id="translations"> + <title>Traduções</title> + + <para>Este é o <literal>FAQ</literal> para as pessoas que + traduzem a documentação do FreeBSD + (<literal>FAQ</literal>, &a.ptbr.p.handbook;, tutoriais, + páginas de manual e outros) para diferentes + línguas.</para> + + <para>Ele é <emphasis>fortemente</emphasis> baseado na + tradução do <literal>FAQ</literal> do Projeto + Alemão de Documentação do FreeBSD, originalmente + escrito por Frank Gründer + <email>elwood@mc5sys.in-berlin.de</email> e traduzido novamente + para o inglês por Bernd Warken + <email>bwarken@mayn.de</email>.</para> + + <para>Este <literal>FAQ</literal> é mantido pela + &a.doceng;.</para> + + <qandaset> + <qandaentry> + <question> + <para>Porque um <literal>FAQ</literal>?</para> + + </question> + + <answer> + <para>Mais e mais pessoas estão se juntando à lista + de discussão FreeBSD-doc e estão se oferecendo + para traduzir a documentação do FreeBSD para + outras línguas. Este <literal>FAQ</literal> visa + responder as suas perguntas, de forma que eles possam + iniciar a tradução da documentação + o quanto antes.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>O que significa <phrase>i18n</phrase> e <phrase>l10n</phrase> + </para> + </question> + + <answer> + <para><phrase>i18n</phrase> significa + <phrase>internacionalização</phrase> e + <phrase>l10n</phrase> significa + <phrase>locallização</phrase>. São + apenas abreviações.</para> + + <para><phrase>i18n</phrase> pode ser lido como + <quote>i</quote> seguido por 18 letras, seguidas por + <quote>n</quote>. Similarmente, <phrase>l10n</phrase> + é <quote>l</quote> seguido por 10 letras, seguidas + por <quote>n</quote>.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Existe uma lista de discussão para + tradutores?</para> + </question> + + <answer> + <para>Sim. Os diferentes grupos de tradução + possuem as suas próprias listas de discussão. + A <ulink + url="http://www.FreeBSD.org/docproj/translations.html"> + lista dos projetos de tradução</ulink> possui + maiores informações sobre as listas de + discussão e sobre os web sites mantidos por + cada um dos projetos de tradução.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>São necessários mais tradutores?</para> + </question> + + <answer> + <para>Sim. Quanto maior o número de pessoas trabalhando na + tradução, mais rapidamente ela será + finalizada, e mais rapidamente as mudanças na + documentação em Inglês serão + refletidas nos documentos traduzidos.</para> + + <para>Você não precisa ser um tradutor + profissional para poder ajudar.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Quais idiomas eu preciso conhecer?</para> + </question> + + <answer> + <para>Idealmente, você deverá possuir bons + conhecimentos de Inglês escrito, e obviamente + necessitará ser fluente na língua para a qual + estiver traduzindo.</para> + + <para>O conhecimento do idioma Inglês não + é estritamente necessário. Por exemplo, + você poderia fazer uma tradução do FAQ + para o idioma Húngaro a partir da versão + em Espanhol do documento.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Quais softwares eu preciso conhecer?</para> + </question> + + <answer> + <para>É fortemente recomendado que você + mantenha uma cópia local do repositório + Subversion do FreeBSD (ao menos da parte referente a + documentação). Isto pode ser feito + executando o comando:</para> + + <screen>&prompt.user; <userinput><command>svn</command> checkout svn://svn.FreeBSD.org/doc/head/ head</userinput></screen> + + <note> + <para>Você irá precisar ter o <filename + role="package">devel/subversion</filename> instalado.</para> + </note> + + <para>Você deverá ter conhecimentos + básicos de <application>svn</application>. Ele + permitirá que você veja o que mudou entre as + diferentes versões dos arquivos que compõem a + documentação.</para> + + <para>Por exemplo, para ver as diferenças entre as + revisões <literal>r33733</literal> e + <literal>r33734</literal> do + <filename>en_US.ISO8859-1/books/fdp-primer/book.sgml + </filename>, execute:</para> + + <screen>&prompt.user; <userinput><command>svn</command> diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> <filename>en_US.ISO8859-1/books/fdp-primer/book.sgml</filename></userinput></screen> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Como eu faço para descobrir se já existem + outras pessoas traduzindo documentos para o meu + idioma?</para> + + </question> + + <answer> + <para><ulink + url="http://www.FreeBSD.org/docproj/translations.html">A + página do Projeto de Tradução da + Documentação</ulink> lista os trabalhos de + tradução que são conhecidos atualmente. + Se outros já estão trabalhando na + tradução da documentação para + o seu idioma, por favor, não duplique os + esforços. Ao invés disso, faça contato + com o grupo para ver como pode ajudá-los.</para> + + <para>Se não existir nenhum projeto de + tradução para o seu idioma listado nesta + página, envie uma mensagem para &a.doc; para o + caso de alguém estar pensando em fazer a + tradução, mas ainda não tiver + anunciado nada.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Ninguém mais está traduzindo para o meu + idioma. O que eu faço?</para> + </question> + + <answer> + <para>Parabés, você acabou de + começar o <quote>FreeBSD <replaceable> + sua-língua-aqui</replaceable> Documentation + Translation Project</quote>. Bem vindo a bordo.</para> + + <para>Primeiro, pense se você terá o tempo + necessário. Uma vez que você é a + única pessoa trabalhando no seu idioma no + momento, será sua a responsabilidade de publicar + o seu trabalho e coordenar qualquer voluntário que + queira ajudá-lo.</para> + + <para>Escreva um email para a lista de discussão do + Projeto de Documentação, anunciando que + você irá traduzir a + documentação, assim a página do Projeto + de Traduções de Documentação + poderá ser atualizada.</para> + + <para>Se já existir alguém em seu país + provendo o espelhamento de serviços do FreeBSD, + você deve contacta-lo e perguntar se você pode + ter algum espaço web para seu projeto, e se + possível um endereço de email ou mesmo um + serviço de lista de discussão.</para> + + <para>Então escolha um documento e comece a traduzir. + É melhor começar com algo razoavelmente + pequeno como <literal>FAQ</literal> ou um dos + tutoriais.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Eu já tenho alguns documentos traduzidos, para + onde eu devo enviá-los?</para> + </question> + + <answer> + <para>Isso depende. Se você já está + trabalhando com uma equipe de tradução + (tal como a equipe japonesa, ou a equipe alemã) + então ela terá seus próprios + procedimentos para manipular a documentação + submetida, e estes serão descritos em seus + web sites.</para> + + <para>Se você for a única pessoa trabalhando em + um determinado idioma (ou se você é o + responsável pelo projeto de tradução e + quer submeter suas mudanças de volta para o projeto + FreeBSD) então você deve enviar sua + tradução ao Projeto FreBSD (veja pergunta + seguinte).</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Eu sou a única pessoa trabalhando na + tradução para este idioma, como faço + para enviar meus documentos?</para> + + <para>ou</para> + + <para>Nós somos uma equipe de tradução, e + queremos submeter os documentos que nossos membros traduziram + para nós.</para> + </question> + + <answer> + <para>Primeiramente certifique-se que sua + tradução está organizada corretamente. + Isto significa que ela deve se encaixar na árvore de + diretórios corrente e ser processada de maneira + correta.</para> + + <para>Atualmente a documentação do FreeBSD + é armazenada em um diretório de nível + superior chamado <filename>head/</filename>. Os + diretórios abaixo deste são nomeados de acordo + com o código do idioma em que eles estão + escritos, definidos na ISO639 + (<filename>/usr/share/misc/iso639</filename> em uma + versão do FreeBSD mais nova que 20 de janeiro de + 1999).</para> + + <para>Se seu idioma puder ser codificado de maneiras + diferentes (por exemplo, Chinês) então + deverão existir outros diretórios abaixo deste, + um para cada formato que você tenha forncecido.</para> + + <para>Finalmente você deve ter diretórios para + cada original.</para> + + <para>Por exemplo, em uma hipotética + tradução para o Sueco ficaria assim:</para> + + <programlisting> +head/ + sv_SE.ISO8859-1/ + Makefile + htdocs/ + docproj + books/ + faq/ + Makefile + book.sgml</programlisting> + + <para><literal>sv_SE.ISO8859-1</literal> é o nome da + tradução, na forma + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>. + Repare nos dois Makefiles que serão usados para + construir a documentação.</para> + + <para>Use &man.tar.1; e &man.gzip.1; para compactar sua + documentação, e envie para o projeto.</para> + +<screen>&prompt.user; <userinput>cd doc</userinput> +&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> +&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen> + + <para>Coloque o arquivo <filename>swedish-docs.tar.gz</filename> + em algum lugar. Se você não tiver acesso ao seu + próprio espaço web (talvez seu ISP + não disponibilize um), então você pode + enviar um email para &a.doceng;, e combinar de enviar os + arquivos por email quando for conveniente.</para> + + <para>De qualquer forma, você deve usar o + &man.send-pr.1; para enviar um relatório indicando + que você submeteu a documentação. + Seria muito útil se você conseguisse outras + pessoas para revisar a sua tradução antes de + submetê-la, uma vez que é improvável que + a pessoa que irá disponibilizá-la no + repositório seja fluente no seu idoma.</para> + + <para>Alguém (provavelmente o gerente do projeto de + documentação, atualmente &a.doceng;) + irá examinar os seus arquivos e irá + confirmar se eles compilam sem erros. Em especial, os + seguintes items serão verificados:</para> + + <orderedlist> + <listitem> + <para>Todos os seus arquivos usam strings RCS + (tais como "ID")?</para> + </listitem> + + <listitem> + <para>O <command>make all</command> no diretório + <filename>sv_SE.ISO8859-1</filename> funciona + corretamente?</para> + </listitem> + + <listitem> + <para>O <command>make install</command> + funciona corretamente?</para> + </listitem> + </orderedlist> + + <para>Se houver algum problema, a pessoa que estiver + examinando a sua submissão irá entrar em + contato para que você faça as + correções.</para> + + <para>Se não exitir nenhum problema, os seus documentos + traduzidos serão disponibilizados no repositório + o quanto antes.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Posso incluir uma língua ou um texto específico + do país em minha tradução?</para> + </question> + + <answer> + <para>Nós preferimos que você não + faça isso.</para> + + <para>Por exemplo, suponha que você esteja + traduzindo o &a.ptbr.p.handbook; para o Coreano e queira + incluir uma seção sobre varejistas na + Coréia em seu &a.ptbr.p.handbook;.</para> + + <para>Não há razão pela qual esta + informação não deva estar nas + versões em Inglês (ou Alemão, ou + Espanhol, ou Japonâs, ou …). É + possível que uma pessoa que fale Inglês na + Coréia possa tentar obter uma cópia do + FreeBSD enquanto esteja ali. Isso também ajuda a + aumentar a presença perceptível do FreeBSD + ao redor do mundo, o que não é uma coisa + ruim.</para> + + <para>Se você tem uma informação + específica do seu país, por favor, submeta ela para + alteração no &a.ptbr.p.handbook; em + Inglês (usando &man.send-pr.1;) e depois traduza + novamente para sua língua no &a.ptbr.p.handbook; + traduzido.</para> + + <para>Obrigado.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Como os caracteres específicos do idioma + podem ser incluídos?</para> + </question> + + <answer> + <para>Caracteres não-ASCII devem ser + incluídos na documentação usando + entidades SGML.</para> + + <para>Resumidamente, eles são um ``e'' comercial + (&), o nome da entidade e um + ponto-e-vírgula (;).</para> + + <para>Os nomes de entidades estão definidos no ISO8879, + que está na árvore do ports como <filename + role="package">textproc/iso8879</filename>.</para> + + <para>Alguns exemplos Incluem</para> + + <segmentedlist> + <segtitle>Entidade</segtitle> + + <segtitle>Aparência</segtitle> + + <segtitle>Descrição</segtitle> + + <seglistitem> + <seg>&eacute;</seg> + <seg>é</seg> + <seg><quote>e</quote> minúsculo com acento + agudo</seg> + </seglistitem> + + <seglistitem> + <seg>&Eacute;</seg> + <seg>É</seg> + <seg><quote>E</quote> maiúsculo com acento + agudo</seg> + </seglistitem> + + <seglistitem> + <seg>&uuml;</seg> + <seg>ü</seg> + <seg><quote>u</quote> minúsculo com trema</seg> + </seglistitem> + </segmentedlist> + + <para>Depois que você instalar o pacote iso8879, + os arquivos em + <filename>/usr/local/share/sgml/iso8879</filename> + conterão a lista completa.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Dirigindo-se ao leitor</para> + </question> + + <answer> + <para>Nos documentos em Inglês, o leitor é + tratado por <quote>você</quote>, não há + distinção entre formal/informal como existe em + alguns idiomas.</para> + + <para>Se você estiver traduzindo para um idioma que + tenha esta distinção, use qualquer forma que + normalmente é usada em outras + documentações técnicas. Na + dúvida, use a forma mais polida.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Eu preciso colocar alguma informação + adicional nas minhas traduções?</para> + </question> + + <answer> + <para>Sim.</para> + + <para>O cabeçalho da versão em Inglês + de cada documento será parecido com o texto exibido + abaixo:</para> + + <programlisting><!-- + The FreeBSD Documentation Project + + $FreeBSD: head/en_US.ISO8859-1/books/faq/book.sgml 38674 2012-04-14 13:52:52Z $ +--></programlisting> + + <para>A forma exata pode mudar, mas ela sempre + incluirá a linha $FreeBSD$ e a frase + <literal>The FreeBSD Documentation Project</literal>. Note + que o $FreeBSD é inserido pelo svn, portanto + ele deve estar vazio (apenas + <literal>$FreeBSD$</literal>) para novos + documentos.</para> + + <para>O seu documento traduzido deve incluir sua + própria linha $FreeBSD$, e você deve mudar + a linha <literal>FreeBSD Documentation Project</literal> para + <literal>The FreeBSD <replaceable>language</replaceable> + Documentation Project</literal>.</para> + + <para>Você deve ainda adicionar uma terceira linha que + indicará qual revisão do texto em inglês + o texto é baseado.</para> + + <para>Assim, a versão em Espanhol deste arquivo pode + começar com:</para> + + <programlisting><!-- + The FreeBSD Spanish Documentation Project + $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.sgml 38826 2012-05-17 19:12:14Z hrs $ + Original revision: r38674 + --></programlisting> + </answer> + </qandaentry> + </qandaset> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/pt_BR.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100755 index 0000000000..83bdf4395e --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,540 @@ +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38872 + +--> + + <chapter id="writing-style"> + <title>Estilo de Escrita</title> + + <para>A fim de promover a consistência entre os + inúmeros autores da documentação do + FreeBSD, foram criadas algumas diretrizes para que os + autores sigam.</para> + + <variablelist> + <varlistentry> + <term>Use a Grafia Inglesa Americana</term> + + <listitem> + <para>Existem diversas variantes do inglês, com + grafias diferentes para a mesma palavra. Onde as + grafias diferem, use a variante inglesa americana. + Por exemplo: + <quote>color</quote>, não <quote>colour</quote>, + <quote>rationalize</quote>, não + <quote>rationalise</quote>, e assim por diante.</para> + + <note> + <para>O uso do Inglês Britânico pode ser aceito + para a contribuição de artigos, contudo a + ortografia deverá ser consistente ao longo de todo o + documento. Os outros documentos, tais como livros, web sites, + páginas de manual, etc. deverão utilizar o + Inglês Americano.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>Não use contrações</term> + + <listitem> + <para>Não use contrações. Soletre + sempre a frase por completo. A frase <quote> + <foreignphrase> Don't use contractions</foreignphrase> + </quote> seria errada.</para> + + <para>Evite fazer uso das contrações para + obter um tom mais formal, será mais preciso, e + ligeiramente mais fácil para os tradutores.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Use a vírgula de série</term> + + <listitem> + <para>Em uma lista de artigos dentro de um + parágrafo, separe cada artigo do outro com uma + vírgula. Separe o último artigo do outro + com uma vírgula e a palavra <quote>e</quote>. + </para> + + <para>Por o exemplo, observe o seguinte: </para> + + <blockquote> + <para>Esta é uma lista de um, dois e três + artigos.</para> + </blockquote> + + <para>Isto é uma lista de três artigos, + <quote>um</quote>, <quote>dois</quote>, e + <quote>três</quote>, ou de uma lista de dois + artigos, <quote>um</quote> e <quote>dois e + três</quote>?</para> + + <para>É melhor ser explícito e incluir uma + vírgula de série: </para> + + <blockquote> + <para>Esta é uma lista de um, dois, e três + artigos.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Evite frases redundantes</term> + + <listitem> + <para>Tente não usar frases redundantes. No detalhe, + <quote>o comando</quote>, <quote>o arquivo</quote>, e + <quote>o comando man</quote> são provavelmente + redundantes.</para> + + <para>Estes dois exemplos mostram isto para comandos. O + segundo exemplo é preferido.</para> + + <informalexample> + <para>Use o comando <command>cvsup</command> para + atualizar seus fontes.</para> + </informalexample> + + <informalexample> + <para>Use o <command>cvsup</command> para atualizar seus + fontes.</para> + </informalexample> + + <para>Estes dois exemplos mostram isto para nomes de + arquivo. O segundo exemplo é preferido.</para> + + <informalexample> + <para>… no arquivo + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>… no + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>Estes dois exemplos mostram isto para + referências aos manuais. O segundo exemplo + é preferido (o segundo exemplo usa + <sgmltag>citerefentry</sgmltag>).</para> + + <informalexample> + <para>Veja o <command>man csh</command> para maiores + informações</para> + </informalexample> + + <informalexample> + <para>veja o &man.csh.1;</para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry> + <term>Dois espaços no final das + sentenças.</term> + + <listitem> + <para>Use sempre dois espaços no fim das + sentenças, isto melhora a legibilidade, e + facilita o uso de ferramentas tais como o + <application>Emacs</application>.</para> + + <para>Lembre-se que uma letra em caixa alta depois de um + período, nem sempre denota uma sentença + nova, especialmente na grafia de nomes. <quote>Jordan K. + Hubbard</quote> é um bom exemplo; tem um + <literal>H</literal> em caixa alta depois de um + período e um espaço, e não há + certamente uma sentença nova lá.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Para maiores informações sobre estilo de + escrita, consulte <ulink url="http://www.bartleby.com/141/"> + Elementos de Estilo</ulink>, por William Strunk.</para> + + <sect1 id="writing-style-guide"> + + <title>Guia de Estilo</title> + + <para>Para manter o código fonte da + documentação consistente quando muitas pessoas + diferentes o estão editando, por favor siga estas + convenções de estilo.</para> + + <sect2> + <title>Caixa de Letra (Maiúscula/Minúscula) + </title> + + <para>As <literal>tags</literal> devem ser utilizadas em + caixa baixa, <literal><para></literal>, + <emphasis>não</emphasis> + <literal><PARA></literal>.</para> + + <para>O texto que aparece em contextos do SGML é + escrito geralmente em caixa alta, + <literal><!ENTITY…></literal>, e + <literal><!DOCTYPE…></literal>, + <emphasis>não</emphasis> + <literal><!entity…></literal> e + <literal><!doctype…></literal>.</para> + </sect2> + + <sect2> + <title>Acrônimos</title> + + <para>Um acrônimo normalmente deve ser soletrado na primeira + vez que ele aparecer em um livro, como por exemplo: + "Network Time Protocol (<acronym role="Network Time + Protocol">NTP</acronym>)". Depois que um acrônimo for + definido, você deveria passar a utilizar apenas ele + (e não o termo completo, a não ser que isso + faça mais sentido contextualmente). Normalmente um + acrônimo é definido uma única vez por + livro. Mas se você preferir, você também pode + definí-lo quando ele aparecer pela primeira vez em + cada capítulo.</para> + + <para>Nas três primeiras vezes que um acrônimo for + utilizado ele deve ser destacado com a tag + <acronym> utilizando o atributo <literal>role + </literal> setado com o termo completo como seu valor. + Isto irá permitir que o link para o + glossário seja criado, e habilitará um + <foreignphrase>mouseover</foreignphrase> que quando + renderizado irá exibir o termo completo.</para> + </sect2> + + <sect2> + <title>Identação</title> + + <para>Cada arquivo começa com a identação + ajustada na coluna 0, <emphasis>independentemente</emphasis> + do nível de identação do arquivo que + pode vir a incluí-lo.</para> + + <para>As tags de abertura aumentam o nível de + identação em 2 espaços, as tags de + fechamento diminuem o nível de + identação em 2 espaços. Blocos de + 8 espaços no começo de uma linha devem ser + subistituidos por um Tab. Não use espaços + na frente dos Tabs, e não adicione espaços + em branco no final de uma linha. O conteúdo dentro + de um elemento deve ser identado por dois espaços + caso ele ocupe mais de uma linha.</para> + + <para>Por exemplo, o código para esta + seção seria algo como:</para> + + <programlisting><![ CDATA [+--- This is column 0 +V +<chapter> + <title>...</title> + + <sect1> + <title>...</title> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + ... + </sect2> + </sect1> +</chapter>]]></programlisting> + + <para>Se você usar o <application>Emacs</application> ou + <application>XEmacs</application> para editar os arquivos + o <literal>sgml-mode</literal> será + carregado automaticamente, e as variáveis locais + do Emacs ao final de cada arquivo devem reforçar + estes estilos.</para> + + <para>Os usuários do <application>Vim</application> + podem querer configurar o seu editor da seguinte + forma:</para> + + <programlisting>augroup sgmledit + autocmd FileType sgml set formatoptions=cq2l " Special formatting options + autocmd FileType sgml set textwidth=70 " Wrap lines at 70 spaces + autocmd FileType sgml set shiftwidth=2 " Automatically indent + autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces + autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab + autocmd FileType sgml set autoindent " Automatic indentation +augroup END</programlisting> + </sect2> + + <sect2> + <title>Estilo de Tags</title> + + <sect3> + <title>Espaçamento de Tags</title> + + <para>Tags que começam na mesma + identação que um Tag precedente devem ser + separados por uma linha em branco, e aqueles que + não estão na mesma identação + que um Tag precedente não, observe:</para> + + <informalexample> + <programlisting><![ CDATA [<article> + <articleinfo> + <title>NIS</title> + + <pubdate>October 1999</pubdate> + + <abstract> + <para>... + ... + ...</para> + </abstract> + </articleinfo> + + <sect1> + <title>...</title> + + <para>...</para> + </sect1> + + <sect1> + <title>...</title> + + <para>...</para> + </sect1> +</article>]]></programlisting> + </informalexample> + </sect3> + + <sect3> + <title>Separando Tags</title> + + <para>Tags tais como <sgmltag>itemizedlist</sgmltag> que + terão sempre algum Tag adicional dentro dele, e que + não fazem exame dos dados eles mesmos, + estarão sempre sozinhos em uma linha.</para> + + <para>Tags tais como <sgmltag>para</sgmltag> e + <sgmltag>term</sgmltag> não necessitam outros Tags + para conter caracteres normais, e o seu + conteúdo começa imediatamente depois do + Tag, <emphasis>na mesma linha</emphasis>.</para> + + <para>O mesmo se aplica quando estes dois tipos de Tag se + fecham.</para> + + <para>Isto conduz a um problema óbvio ao misturar + estes Tags.</para> + + <para>Quando um Tag de abertura que não pode conter + caracteres normais é utilizado logo + após um Tag do tipo que requer outros Tags dentro + dele para conter caracteres normais, eles devem + estar em linhas separadas e o segundo Tag deve ser + corretamente identado.</para> + + <para>Quando um Tag que possa conter caracteres + normais se fecha imediatamente depois que um Tag que + não pode conter caracteres normais + se fecha, eles podem coexistir na mesma linha.</para> + </sect3> + </sect2> + + <sect2> + <title>Mudanças nos espaços em branco.</title> + + <para>Ao enviar mudanças, não envie + mudanças de conteúdo ao mesmo tempo que + mudanças no formato.</para> + + <para>Desta forma as equipes que convertem o manual para + outras línguas podem ver rapidamente o que de fato + mudou no conteúdo com o seu envio, sem ter que se + decidir se uma linha mudou por causa do conteúdo, + ou apenas porque foi reformatada.</para> + + <para>Por exemplo, se você adicionar duas + sentenças a um parágrafo, de forma que o + comprimento das linhas no mesmo agora excedem 80 colunas, + envie sua mudança sem corrigir o comprimento da + linha. Ajuste então a quebra de linha e envie uma + segunda mudança. Na mensagem de + <literal>commit</literal> da segunda mudança, + deixe claro que se trata apenas de um ajuste de + formatação, e que a equipe da + tradução pode ignorá-la.</para> + </sect2> + + <sect2> + <title><foreignphrase>Nonbreaking space</foreignphrase> + </title> + + <para>Evite as quebras de linha nos locais onde elas ficarem + feias ou onde dificultarem a compreensão de uma + sentença. As quebras de linha dependem da largura + do meio de saída escolhido. Em particular, + visualizar um documento em HTML com um navegador em modo + texto pode conduzir a parágrafos mal formatados como o + exemplo a seguir:</para> + + <literallayout class="monospaced"> + Data capacity ranges from 40 MB to 15 + GB. Hardware compression …</literallayout> + + <para>A entidade geral <literal>&nbsp;</literal> proibe a + quebra de linha entre partes que devem permanecer juntas. + Utilize <foreignphrase>nonbreaking spaces </foreignphrase> + nos seguintes lugares:</para> + + <itemizedlist> + <listitem> + <para>Entre números e suas unidades:</para> + + <programlisting><![ CDATA [57600 bps]]></programlisting> + </listitem> + + <listitem> + <para>Entre os nomes dos programas e os seus + números de versão:</para> + <programlisting><![ CDATA [FreeBSD 4.7]]></programlisting> + </listitem> + + <listitem> + <para>Entre nomes compostos (utilize com cuidado quando + estiver lidando com nomes com mais de 3 ou 4 palavras, + como por exemplo, <quote>The FreeBSD Brazilian + Portuguese Documentation Project</quote>):</para> + <programlisting><![ CDATA [Sun Microsystems]]></programlisting> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="writing-style-word-list"> + <title>Lista de Palavras</title> + + <para>O que se segue é uma pequena lista das palavras + com a grafia da maneira que deve ser usada no projeto da + documentação do FreeBSD. Se a palavra que + você está procurando não estiver nesta + lista, por favor consulte a + <ulink url="http://www.oreilly.com/oreilly/author/stylesheet.html"> + lista de palavras da O'Reilly</ulink>.</para> + + <itemizedlist> + <listitem> + <para>2.2.X</para> + </listitem> + + <listitem> + <para>4.X-STABLE</para> + </listitem> + + <listitem> + <para>CD-ROM</para> + </listitem> + + <listitem> + <para>DoS <emphasis>(Denial of Service)</emphasis> </para> + </listitem> + + <listitem> + <para>Ports Collection</para> + </listitem> + + <listitem> + <para>IPsec</para> + </listitem> + + <listitem> + <para>Internet</para> + </listitem> + + <listitem> + <para>MHz</para> + </listitem> + + <listitem> + <para>Soft Updates</para> + </listitem> + + <listitem> + <para>Unix</para> + </listitem> + + <listitem> + <para>disk label</para> + </listitem> + + <listitem> + <para>email</para> + </listitem> + + <listitem> + <para>file system</para> + </listitem> + + <listitem> + <para>manual page</para> + </listitem> + + <listitem> + <para>mail server</para> + </listitem> + + <listitem> + <para>name server</para> + </listitem> + + <listitem> + <para>null-modem</para> + </listitem> + + <listitem> + <para>web server</para> + </listitem> + </itemizedlist> + + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/share/sgml/articles.ent b/pt_BR.ISO8859-1/share/sgml/articles.ent new file mode 100644 index 0000000000..008b088743 --- /dev/null +++ b/pt_BR.ISO8859-1/share/sgml/articles.ent @@ -0,0 +1,34 @@ +<!-- + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<!ENTITY % l10n PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN"> +%l10n; +<!ENTITY % l10n-common PUBLIC "-//FreeBSD//ENTITIES DocBook Language Neutral Entities//EN"> +%l10n-common; +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; +<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN"> +%freebsd; +<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> +%authors; +<!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//PTBR"> +%teams; +<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//PTBR"> +%mailing-lists; +<!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//PTBR"> +%newsgroups; +<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN"> +%trademarks; +<!ENTITY % urls PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN"> +%urls; +<!ENTITY % words PUBLIC "-//FreeBSD//ENTITIES DocBook Specific Word Translations Entities//PTBR"> +%words; + diff --git a/pt_BR.ISO8859-1/share/sgml/books.ent b/pt_BR.ISO8859-1/share/sgml/books.ent new file mode 100644 index 0000000000..3b010d9589 --- /dev/null +++ b/pt_BR.ISO8859-1/share/sgml/books.ent @@ -0,0 +1,35 @@ +<!-- + + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + $FreeBSD$ + + Original revision: r38826 + +--> + +<!ENTITY % l10n PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN"> +%l10n; +<!ENTITY % l10n-common PUBLIC "-//FreeBSD//ENTITIES DocBook Language Neutral Entities//EN"> +%l10n-common; +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; +<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//PTBR"> +%bookinfo; +<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN"> +%freebsd; +<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> +%authors; +<!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//PTBR"> +%teams; +<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//PTBR"> +%mailing-lists; +<!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//EN"> +%newsgroups; +<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN"> +%trademarks; +<!ENTITY % urls PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN"> +%urls; +<!ENTITY % words PUBLIC "-//FreeBSD//ENTITIES DocBook Specific Word Translations Entities//PTBR"> +%words; diff --git a/pt_BR.ISO8859-1/share/sgml/catalog b/pt_BR.ISO8859-1/share/sgml/catalog index 2cc1045538..fb62087034 100644 --- a/pt_BR.ISO8859-1/share/sgml/catalog +++ b/pt_BR.ISO8859-1/share/sgml/catalog @@ -7,7 +7,7 @@ -- The FreeBSD Documentation Project -- The FreeBSD Brazilian Portuguese Documentation Project - -- Original revision: 1.5 + -- Original revision: r38826 -- -- $FreeBSD$ @@ -29,7 +29,7 @@ PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//PTBR" "newsgroups.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//PTBR" - "teams.ent" + "teams.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Translators Entities//PTBR" "translators.ent" @@ -40,15 +40,9 @@ PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//PTBR" PUBLIC "-//FreeBSD//ENTITIES DocBook Specific Word Translations Entities//PTBR" "words.ent" -PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//PTBR" - "freebsd.dsl" +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//PTBR" + "books.ent" -PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//PTBR" - "mailing-lists.ent" - -PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//PTBR" - "teams.ent" - -PUBLIC "-//FreeBSD//ENTITIES DocBook Translator Entities//PTBR" - "translators.ent" +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//PTBR" + "articles.ent" diff --git a/pt_BR.ISO8859-1/share/sgml/entities.ent b/pt_BR.ISO8859-1/share/sgml/entities.ent index f7b68403bb..2b33004402 100644 --- a/pt_BR.ISO8859-1/share/sgml/entities.ent +++ b/pt_BR.ISO8859-1/share/sgml/entities.ent @@ -23,3 +23,5 @@ %trademarks; <!ENTITY % trademarks-en PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN"> %trademarks-en; +<!ENTITY % urls PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN"> +%urls; diff --git a/pt_BR.ISO8859-1/share/sgml/freebsd.dsl b/pt_BR.ISO8859-1/share/sgml/freebsd.dsl index b866f9432e..287b6e6eb5 100644 --- a/pt_BR.ISO8859-1/share/sgml/freebsd.dsl +++ b/pt_BR.ISO8859-1/share/sgml/freebsd.dsl @@ -2,7 +2,7 @@ The FreeBSD Documentation Project The FreeBSD Brazilian Portuguese Documentation Project - Original revision: 1.14 + Original revision: r38826 $FreeBSD$ --> @@ -55,6 +55,17 @@ (create-link (list (list "HREF" "mailto:doc@FreeBSD.org")) (literal "doc@FreeBSD.org")) (literal ">."))))) + (define (local-ptbr-label-title-sep) + (list + (list (normalize "warning") ": ") + (list (normalize "caution") ": ") + (list (normalize "chapter") " ") + (list (normalize "sect1") " ") + (list (normalize "sect2") " ") + (list (normalize "sect3") " ") + (list (normalize "sect4") " ") + (list (normalize "sect5") " ") + )) ]]> </style-specification-body> </style-specification> diff --git a/pt_BR.ISO8859-1/share/sgml/mailing-lists.ent b/pt_BR.ISO8859-1/share/sgml/mailing-lists.ent index a25892140d..38053129c4 100644 --- a/pt_BR.ISO8859-1/share/sgml/mailing-lists.ent +++ b/pt_BR.ISO8859-1/share/sgml/mailing-lists.ent @@ -4,11 +4,15 @@ The FreeBSD Documentation Project The FreeBSD Brazilian Portuguese Documentation Project - Original revision: 1.1 + Original revision: r38826 $FreeBSD$ --> -<!ENTITY a.advocacy "lista de discussão FreeBSD +<!ENTITY a.mailman.listinfo "http://lists.FreeBSD.org/mailman/listinfo"> +<!ENTITY a.mailman.lists "<ulink url='&a.mailman.listinfo;'>FreeBSD list server</ulink>"> +<!ENTITY a.mailman.lists.link "<ulink url='&a.mailman.listinfo;'>&a.mailman.listinfo;</ulink>"> + +<!ENTITY a.advocacy "lista de discussão FreeBSD <foreignphrase>advocacy</foreignphrase> [English Content/Conteúdo em Inglês] <email>freebsd-advocacy@FreeBSD.org</email>"> @@ -239,9 +243,8 @@ [English Content/Conteúdo em Inglês] <email>freebsd-policy@FreeBSD.org</email>"> -<!ENTITY a.ports "lista de discussão sobre FreeBSD - <literal>ports</literal> e o sistema de <literal>ports</literal> - FreeBSD +<!ENTITY a.ports "lista de discussão sobre o sistema de + <literal>ports</literal> do FreeBSD [English Content/Conteúdo em Inglês] <email>freebsd-ports@FreeBSD.org</email>"> @@ -256,10 +259,9 @@ [English Content/Conteúdo em Inglês] <email>freebsd-qa@FreeBSD.org</email>"> -<!ENTITY a.questions "lista de discussão FreeBSD de perguntas - genéricas - [English Content/Conteúdo em Inglês] - <email>freebsd-questions@FreeBSD.org</email>"> +<!ENTITY a.questions.url "&a.mailman.listinfo;/freebsd-questions"> +<!ENTITY a.questions "<ulink url='&a.questions.url;'>lista de discussão do FreeBSD de perguntas genéricas</ulink> [English Content/Conteúdo em Inglês]"> +<!ENTITY a.questions.name "<ulink url='&a.questions.url;'>freebsd-questions</ulink>"> <!ENTITY a.realtime "lista de discussão FreeBSD de extensões de tempo real @@ -330,4 +332,14 @@ <email>freebsd-www@FreeBSD.org</email>"> <!ENTITY a.majordomo "<email>majordomo@FreeBSD.org</email>"> +<!ENTITY a.bugfollowup "<email>bug-followup@FreeBSD.org</email>"> +<!ENTITY a.bugsubmit "&a.bugfollowup;"> + +<!ENTITY a.cvs-ports.url "&a.mailman.listinfo;/cvs-ports"> +<!ENTITY a.cvs-ports "<ulink url='&a.cvs-ports.url;'>FreeBSD CVS ports commit list</ulink>"> +<!ENTITY a.cvs-ports.name "<ulink url='&a.cvs-ports.url;'>cvs-ports</ulink>"> + +<!ENTITY a.ports-bugs.url "&a.mailman.listinfo;/freebsd-ports-bugs"> +<!ENTITY a.ports-bugs "<ulink url='&a.ports-bugs.url;'>FreeBSD ports bugs mailing list</ulink>"> +<!ENTITY a.ports-bugs.name "<ulink url='&a.ports-bugs.url;'>freebsd-ports-bugs</ulink>"> diff --git a/pt_BR.ISO8859-1/share/sgml/translators.ent b/pt_BR.ISO8859-1/share/sgml/translators.ent index 5b4c727213..99a9f543e7 100644 --- a/pt_BR.ISO8859-1/share/sgml/translators.ent +++ b/pt_BR.ISO8859-1/share/sgml/translators.ent @@ -5,7 +5,7 @@ Tradutores para Portugues Obs: ordenados por sobrenome - Versao original: 1.6 + Versao original: r38826 $FreeBSD$ --> @@ -22,6 +22,8 @@ "Araujo, Gilberto M. <email>araujo@iguabanet.com.br</email>"> <!ENTITY a.ptbr.jmelo "Jean Milanez Melo <email>jmelo@freebsdbrasil.com.br</email>"> +<!ENTITY a.ptbr.atnpessoa + "Antonio Pessoa <email>atnpessoa@gmail.com</email>"> <!ENTITY a.ptbr.xenobok "Josê Porfírio <email>poool@terra.com.br</email>"> <!ENTITY a.ptbr.surf |