path: root/pt_BR.ISO8859-1/books/fdp-primer/structure/chapter.sgml

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