path: root/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml

<!-- 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>.xml</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>