diff options
| author | Gabor Kovesdan <gabor@FreeBSD.org> | 2012-09-05 05:16:32 +0000 |
|---|---|---|
| committer | Gabor Kovesdan <gabor@FreeBSD.org> | 2012-09-05 05:16:32 +0000 |
| commit | 4f25a718f4b34b91e810d9001f77174f1221a1e4 (patch) | |
| tree | 91afd6550f6ea9bb0522c13bec59336f45f5a436 /pt_BR.ISO8859-1/books/fdp-primer | |
| parent | fd0cb5c634db773c240c4eaab137622d7ffd21bd (diff) | |
| download | doc-4f25a718f4b34b91e810d9001f77174f1221a1e4.tar.gz doc-4f25a718f4b34b91e810d9001f77174f1221a1e4.zip | |
- Add new Brazilian Portuguese translation of fdp-primer
PR: docs/170470
Submitted by: Edson Brandi <ebrandi@fugspbr.org>
Obtained from: The FreeBSD Brazilian Portuguese Documentation Project
(http://doc.fug.com.br)
Notes
Notes:
svn path=/head/; revision=39500
Diffstat (limited to 'pt_BR.ISO8859-1/books/fdp-primer')
16 files changed, 9123 insertions, 0 deletions
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..fafed65f5f --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,300 @@ +<!-- 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 + +--> + +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % books.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//PTBR"> +%books.ent; +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +<!ENTITY % not.published "INCLUDE"> +<!-- ENTITY index SYSTEM "index.sgml" --> +]> + +<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> + + &bookinfo.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..6edd481b9b --- /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..6e72ad7aea --- /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..e89deeaba8 --- /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> |