os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

pt_BR.ISO8859-1/books/fdp-primer: converted to .po

Browse source 
* content synchronized with en_US document (rev 52151)
* book.xml converted to .po
* .po file was translated to pt_BR
* pt_BR.po and book.xml file has been set to UTF-8 encoding
* chapter.xml files in all sub directory under fdp-primer has been set with fbsd:nokeywords yes since it doesnt have $FreeBSD$ tag
* information about volunteers who translated and/or revised the document was added to the header of the .po file.

Reviewed by: dbaio
Approved by: gabor (mentor, implicit)
Obtained from: The FreeBSD Brazilian Portuguese Documentation Project
Differential Revision: https://reviews.freebsd.org/D16997
This commit is contained in:
Edson Brandi 2018-09-06 01:10:32 +00:00
parent e57181d729
commit 8d4d8b3381
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=52225
22 changed files with 33603 additions and 2937 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
pt_BR.ISO8859-1/books/fdp-primer/Makefile
View file

@ -1,13 +1,12 @@
#
# The FreeBSD Documentation Project
# The FreeBSD Brazilian Portuguese Documentation Project
#
#
# $FreeBSD$
#
# Original revision: r38826
#
MAINTAINER=doc@FreeBSD.org
MAINTAINER=ebrandi@FreeBSD.org
DOC?= book
@ -16,25 +15,29 @@ FORMATS?= html-split html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
#
# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
# XML content
SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= psgml-mode/chapter.xml
SRCS+= see-also/chapter.xml
SRCS+= sgml-markup/chapter.xml
SRCS+= sgml-primer/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= tools/chapter.xml
SRCS+= working-copy/chapter.xml
SRCS+= structure/chapter.xml
SRCS+= doc-build/chapter.xml
SRCS+= the-website/chapter.xml
SRCS+= tools/chapter.xml
SRCS+= the-website/chapter.xml
SRCS+= xml-primer/chapter.xml
SRCS+= xhtml-markup/chapter.xml
SRCS+= docbook-markup/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= translations/chapter.xml
SRCS+= writing-style/chapter.xml
SRCS+= po-translations/chapter.xml
SRCS+= manpages/chapter.xml
SRCS+= writing-style/chapter.xml
SRCS+= editor-config/chapter.xml
SRCS+= see-also/chapter.xml
SRCS+= examples/appendix.xml
@ -44,11 +47,15 @@ IMAGES_LIB+= callouts/2.png
IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
IMAGES_LIB+= callouts/6.png
IMAGES_LIB+= callouts/7.png
IMAGES_LIB+= callouts/8.png
IMAGES_LIB+= callouts/9.png
# Entities
SRCS+= chapters.ent
SRCS+= chapters.ent
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

7473
pt_BR.ISO8859-1/books/fdp-primer/book.xml
View file

File diff suppressed because it is too large Load diff

31
pt_BR.ISO8859-1/books/fdp-primer/chapters.ent
View file

@ -5,21 +5,24 @@
$FreeBSD$
Original revision: r38826
-->
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.xml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml">
<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml">
<!ENTITY chap.manpages SYSTEM "manpages/chapter.xml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">
<!ENTITY app.examples SYSTEM "examples/appendix.xml">
<!ENTITY app.examples SYSTEM "examples/appendix.xml">

692
pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,141 +28,151 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build">
<title>O processo de construção da
documentação</title>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="doc-build">
<title>The Documentation Build Process</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>This chapter covers organization of the documentation build
process and how &man.make.1; is used to control it.</para>
<para>Depois de finalizar a leitura deste capítulo
você deverá:</para>
<sect1 xml:id="doc-build-rendering">
<title>Rendering DocBook into Output</title>
<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>
<para>Different types of output can be produced from a single
DocBook source file. The type of output desired is set with the
<varname>FORMATS</varname> variable. A list of known formats is
stored in <varname>KNOWN_FORMATS</varname>:</para>
<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>
<screen xml:id="doc-build-rendering-known-formats">&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
&prompt.user; <userinput>make -V KNOWN_FORMATS</userinput></screen>
<listitem>
<para>Ser capaz de customizar o processo de
compilação usando variáveis e alvos do
<application>make</application>.</para>
</listitem>
</itemizedlist>
<table xml:id="doc-build-rendering-common-formats" frame="none">
<title>Common Output Formats</title>
<sect1>
<title>Ferramentas para construção da
documentação do FreeBSD</title>
<tgroup cols="3">
<thead>
<row>
<entry><varname>FORMATS</varname> Value</entry>
<entry>File Type</entry>
<entry>Description</entry>
</row>
</thead>
<para>Aqui estão suas ferramentas. Use-as de todas as
formas que puder.</para>
<tbody>
<row>
<entry><literal>html</literal></entry>
<entry><acronym>HTML</acronym>, one file</entry>
<entry>A single <filename>book.html</filename> or
<filename>article.html</filename>.</entry>
</row>
<itemizedlist>
<listitem>
<para>A primeira ferramenta que você precisará
é o <application>make</application>, mais
especificamente o <application>Berkeley Make</application>.
</para>
</listitem>
<row>
<entry><literal>html-split</literal></entry>
<entry><acronym>HTML</acronym>, multiple files</entry>
<entry>Multiple <acronym>HTML</acronym> files, one for
each chapter or section, for use on a typical web
site.</entry>
</row>
<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>
<row>
<entry><literal>pdf</literal></entry>
<entry><acronym>PDF</acronym></entry>
<entry>Portable Document Format</entry>
</row>
</tbody>
</tgroup>
</table>
<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>
<para>The default output format can vary by document, but is
usually <literal>html-split</literal>. Other formats are chosen
by setting <varname>FORMATS</varname> to a specific value.
Multiple output formats can be created at a single time by
setting <varname>FORMATS</varname> to a list of formats.</para>
<listitem>
<para>O <application>install</application> é o
método padrão para instalar a
documentação. Entretanto, existem
alternativas.</para>
</listitem>
</itemizedlist>
<example xml:id="doc-build-formats-example-html">
<title>Build a Single HTML Output File</title>
<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>
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
&prompt.user; <userinput>make FORMATS=html</userinput></screen>
</example>
<example xml:id="doc-build-formats-example-html-split-pdf">
<title>Build HTML-Split and <acronym>PDF</acronym> Output
Files</title>
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
&prompt.user; <userinput>make FORMATS="html-split pdf"</userinput></screen>
</example>
</sect1>
<sect1>
<title>Entendendo <filename>Makefile</filename>s na árvore da
documentação</title>
<sect1 xml:id="doc-build-toolset">
<title>The &os; Documentation Build Toolset</title>
<para>Há três tipos principais de
<filename>Makefile</filename>s na árvore do projeto de
documentção do FreeBSD.</para>
<para>These are the tools used to build and install the
<acronym>FDP</acronym> documentation.</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>
<para>The primary build tool is &man.make.1;, specifically
<application>Berkeley Make</application>.</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>
<para>Package building is handled by &os;'s
&man.pkg-create.8;.</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.xxx.mk</filename>.
</para>
<para>&man.gzip.1; is used to create compressed versions of
the document. &man.bzip2.1; archives are also supported.
&man.tar.1; is used for package building.</para>
</listitem>
<listitem>
<para>&man.install.1; is used to install the
documentation.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="doc-build-makefiles">
<title>Understanding <filename>Makefile</filename>s in the
Documentation Tree</title>
<para>There are three main types of <filename>Makefile</filename>s
in the &os; Documentation Project tree.</para>
<itemizedlist>
<listitem>
<para><link linkend="sub-make">Subdirectory
<filename>Makefile</filename>s</link> simply pass
commands to those directories below them.</para>
</listitem>
<listitem>
<para><link linkend="doc-make">Documentation
<filename>Makefile</filename>s</link> describe the
documents that are produced from this
directory.</para>
</listitem>
<listitem>
<para><link
linkend="make-includes"><application>Make</application>
includes</link> are the glue that perform the document
production, and are usually of the form
<filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
</listitem>
</itemizedlist>
<sect2 xml:id="sub-make">
<title><filename>Makefile</filename>s de Subdiretórios</title>
<title>Subdirectory <filename>Makefile</filename>s</title>
<para>Estes <filename>Makefile</filename>s geralmente tem a
forma:</para>
<para>These <filename>Makefile</filename>s usually take the form
of:</para>
<programlisting>SUBDIR =articles
SUBDIR+=books
@ -172,74 +182,58 @@ 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>, <varname>SUBDIR</varname>,
<varname>COMPAT_SYMLINK</varname>, e
<para>The first four non-empty lines define the &man.make.1;
variables <varname>SUBDIR</varname>,
<varname>COMPAT_SYMLINK</varname>, and
<varname>DOC_PREFIX</varname>.</para>
<para>A primeira declaração da variável
<varname>SUBDIR</varname>, tanto quanto a
declaração da variável
<varname>COMPAT_SYMLINK</varname>,
mostra como atribuir um valor a uma variável,
sobrescrevendo qualquer valor anterior que a mesma
contenha.</para>
<para>The <varname>SUBDIR</varname> statement and
<varname>COMPAT_SYMLINK</varname> statement show how to
assign a value to a variable, overriding any previous
value.</para>
<para>A segunda declaração da variável
<varname>SUBDIR</varname> mostra como um valor é
adicionado ao valor atual de uma variável. A
variável <varname>SUBDIR</varname> agora é
composta por <literal>articles books</literal>.</para>
<para>The second <varname>SUBDIR</varname> statement shows how a
value is appended to the current value of a variable. The
<varname>SUBDIR</varname> variable is now <literal>articles
books</literal>.</para>
<para>A declaração do
<varname>DOC_PREFIX</varname> mostra como um valor é
atribuído para uma variável, mas somente se
ela ainda não estiver definida. Isto é
útil se o <varname>DOC_PREFIX</varname> não
for onde este <filename>Makefile</filename> pensa que
é - o usuário pode cancelar e fornecer
o valor correto.</para>
<para>The <varname>DOC_PREFIX</varname> assignment shows how a
value is assigned to the variable, but only if it is not
already defined. This is useful if
<varname>DOC_PREFIX</varname> is not where this
<filename>Makefile</filename> thinks it is - the user can
override this and provide the correct value.</para>
<para>Agora o que tudo isso significa? O
<varname>SUBDIR</varname> lista quais subdiretórios
abaixo do atual devem ser incluídos no processo de
compilação durante a geração
do documento.</para>
<para>What does it all mean? <varname>SUBDIR</varname>
mentions which subdirectories below this one the build process
should pass any work on to.</para>
<para>O <varname>COMPAT_SYMLINK</varname> é
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><varname>COMPAT_SYMLINK</varname> is specific to
compatibility symlinks (amazingly enough) for languages to
their official encoding (<filename>doc/en</filename> would
point to <filename>en_US.ISO-8859-1</filename>).</para>
<para>O <varname>DOC_PREFIX</varname> é 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
<varname>.CURDIR</varname> é 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>
<para><varname>DOC_PREFIX</varname> is the path to the root of
the &os; Document Project tree. This is not always that easy
to find, and is also easily overridden, to allow for
flexibility. <varname>.CURDIR</varname> is a &man.make.1;
builtin variable with the path to the current
directory.</para>
<para>The final line includes the &os; Documentation Project's
project-wide &man.make.1; system file
<filename>doc.project.mk</filename> which is the glue which
converts these variables into build instructions.</para>
</sect2>
<sect2 xml:id="doc-make">
<title><filename>Makefile</filename>s de Documentação</title>
<title>Documentation <filename>Makefile</filename>s</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>These <filename>Makefile</filename>s set &man.make.1;
variables that describe how to build the documentation
contained in that directory.</para>
<para>Aqui está um exemplo:</para>
<para>Here is an example:</para>
<programlisting>MAINTAINER=nik@FreeBSD.org
@ -257,86 +251,67 @@ DOC_PREFIX?= ${.CURDIR}/../../..
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
<para>A variável <varname>MAINTAINER</varname> é
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>The <varname>MAINTAINER</varname> variable allows
committers to claim ownership of a document in the &os;
Documentation Project, and take responsibility for maintaining
it.</para>
<para><varname>DOC</varname> é o nome (sem a
extensão <filename>.xml</filename>) do principal
documento criado por este diretório. A variável
<varname>SRCS</varname> 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><varname>DOC</varname> is the name (sans the
<filename>.xml</filename> extension) of the main document
created by this directory. <varname>SRCS</varname> lists all
the individual files that make up the document. This should
also include important files in which a change should result
in a rebuild.</para>
<para>O <varname>FORMATS</varname> indica os formatos
nos quais o documento deve ser gerado por padrão.
O <varname>INSTALL_COMPRESSED</varname> 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 <varname>INSTALL_ONLY_COMPRESS</varname>,
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>
<para><varname>FORMATS</varname> indicates the default formats
that should be built for this document.
<varname>INSTALL_COMPRESSED</varname> is the default list of
compression techniques that should be used in the document
build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by
default, should be non-empty if only compressed documents are
desired in the build.</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 <varname>DOC_PREFIX</varname> e com as
instruções de include.</para>
<para>The <varname>DOC_PREFIX</varname> and include statements
should be familiar already.</para>
</sect2>
</sect1>
<sect1 xml:id="make-includes">
<title>Includes do <application>Make</application> do projeto de documentação
do FreeBSD</title>
<title>&os; Documentation Project
<application>Make</application> Includes</title>
<para>Isto é melhor explicado pela inspeção
no código. Aqui estão os arquivos include do
sistema:</para>
<para>&man.make.1; includes are best explained by inspection of
the code. Here are the system include files:</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>
<para><filename>doc.project.mk</filename> is the main project
include file, which includes all the following include
files, as necessary.</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>
<para><filename>doc.subdir.mk</filename> handles traversing of
the document tree during the build and install
processes.</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>
<para><filename>doc.install.mk</filename> provides variables
that affect ownership and installation of documents.</para>
</listitem>
<listitem>
<para>O <filename>doc.docbook.mk</filename> é
incluído se o <varname>DOCFORMAT</varname>
for <literal>docbook</literal> e se a variável
<varname>DOC</varname> estiver definida.</para>
<para><filename>doc.docbook.mk</filename> is included if
<varname>DOCFORMAT</varname> is <literal>docbook</literal>
and <varname>DOC</varname> is set.</para>
</listitem>
</itemizedlist>
<sect2>
<sect2 xml:id="includes-doc-project-mk">
<title><filename>doc.project.mk</filename></title>
<para>Por inspeção:</para>
<para>By inspection:</para>
<programlisting>DOCFORMAT?= docbook
MAINTAINER?= doc@FreeBSD.org
@ -353,230 +328,203 @@ PRI_LANG?= en_US.ISO8859-1
.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>
<sect3>
<sect3 xml:id="doc-project-mk-variables">
<title>Variáveis</title>
<title>Variables</title>
<para>As variáveis <varname>DOCFORMAT</varname> e
<varname>MAINTAINER</varname> 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><varname>DOCFORMAT</varname> and
<varname>MAINTAINER</varname> are assigned default values,
if these are not set by the document make file.</para>
<para>O <varname>PREFIX</varname> 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><varname>PREFIX</varname> is the prefix under which the
<link linkend="tools">documentation building tools</link>
are installed. For normal package and port installation,
this is <filename>/usr/local</filename>.</para>
<para>A variável <varname>PRI_LANG</varname> 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>
<para><varname>PRI_LANG</varname> should be set to whatever
language and encoding is natural amongst users these
documents are being built for. US English is the
default.</para>
<note>
<para>A variável <varname>PRI_LANG</varname> 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>
<para><varname>PRI_LANG</varname> does not affect which
documents can, or even will, be built. Its main use is
creating links to commonly referenced documents into the
&os; documentation install root.</para>
</note>
</sect3>
<sect3>
<title>Condicionais</title>
<sect3 xml:id="doc-project-mk-conditionals">
<title>Conditionals</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>The <literal>.if defined(DOC)</literal> line is an
example of a &man.make.1; conditional which, like in other
programs, defines behavior if some condition is true or if
it is false. <literal>defined</literal> is a function which
returns whether the variable given is defined or not.</para>
<para>A seguir, <literal>.if ${DOCFORMAT} == "docbook"
</literal>, testa se a variável <varname>DOCFORMAT
</varname> é <literal>"docbook"</literal>, e neste
caso, inclue o <filename>doc.docbook.mk</filename>.</para>
<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
tests whether the <varname>DOCFORMAT</varname> variable is
<literal>"docbook"</literal>, and in this case, includes
<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>
<para>The two <literal>.endif</literal>s close the two above
conditionals, marking the end of their application.</para>
</sect3>
</sect2>
<sect2>
<title>doc.subdir.mk</title>
<sect2 xml:id="includes-doc-subdir-mk">
<title><filename>doc.subdir.mk</filename></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>
<para>This file is too long to explain in detail. These notes
describe the most important features.</para>
<sect3>
<title>Variáveis</title>
<sect3 xml:id="doc-subdir-mk-variables">
<title>Variables</title>
<itemizedlist>
<listitem>
<para><varname>SUBDIR</varname> é a lista de
subdiretórios nos quais o processo de
construção deve ser executado.</para>
<para><varname>SUBDIR</varname> is a list of
subdirectories that the build process should go further
down into.</para>
</listitem>
<listitem>
<para><varname>ROOT_SYMLINKS</varname> 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 <varname>PRI_LANG</varname>).</para>
<para><varname>ROOT_SYMLINKS</varname> is the name of
directories that should be linked to the document
install root from their actual locations, if the current
language is the primary language (specified by
<varname>PRI_LANG</varname>).</para>
</listitem>
<listitem>
<para>O <varname>COMPAT_SYMLINK</varname> já foi
descrito na seção <link linkend="sub-make">Makefiles de subdiretório
</link>.</para>
<para><varname>COMPAT_SYMLINK</varname> is described in
the
<link linkend="sub-make">Subdirectory Makefile</link>
section.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Targets e Macros</title>
<sect3 xml:id="doc-subdir-mk-targets-macro">
<title>Targets and Macros</title>
<para>As dependências são descritas por
<literal>target:
dependência1 dependência2 ...
</literal>, nas quais, para construir o
<literal>target</literal>, você necessita
primeiramente construir as dependências
informadas.</para>
<para>Dependencies are described by
<literal><replaceable>target</replaceable>:
<replaceable>dependency1 dependency2
...</replaceable></literal> tuples, where to build
<literal>target</literal>, the given
dependencies must be built first.</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>After that descriptive tuple, instructions on how to
build the target may be given, if the conversion process
between the target and its dependencies are not previously
defined, or if this particular conversion is not the same as
the default conversion method.</para>
<para>A dependência especial <literal>.USE</literal>
define o equivalente a uma macro.</para>
<para>A special dependency <literal>.USE</literal> defines
the equivalent of a macro.</para>
<programlisting>_SUBDIRUSE: .USE
<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===&gt; ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} &amp;&amp; \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para>No código acima, <buildtarget>_SUBDIRUSE
</buildtarget> é agora uma macro, a qual irá
executar determinados comandos quando for listada como
dependência.</para>
<para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is
now a macro which will execute the given commands when it is
listed as a dependency.</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 <varname>.TARGET</varname>, que é a
variável que contém o nome do target atual
que está sendo construído.</para>
<para>What sets this macro apart from other targets?
Basically, it is executed <emphasis>after</emphasis> the
instructions given in the build procedure it is listed as a
dependency to, and it does not adjust
<varname>.TARGET</varname>, which is the variable which
contains the name of the target currently being
built.</para>
<programlisting>clean: _SUBDIRUSE
<programlisting>clean: _SUBDIRUSE
rm -f ${CLEANFILES}</programlisting>
<para>No código acima, o <buildtarget>clean</buildtarget>
irá usar a macro <buildtarget>_SUBDIRUSE</buildtarget>
depois de ter executado a instrução
<command>rm -f ${CLEANFILES}</command>. De fato, isto causa
uma limpeza (<buildtarget>clean</buildtarget>) 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>
<para>In the above, <buildtarget>clean</buildtarget> will use
the <buildtarget>_SUBDIRUSE</buildtarget> macro after it has
executed the instruction
<command>rm -f ${CLEANFILES}</command>. In effect, this
causes <buildtarget>clean</buildtarget> to go further and
further down the directory tree, deleting built files as it
goes <emphasis>down</emphasis>, not on the way back
up.</para>
<sect4>
<title>Targets fornecidos</title>
<sect4 xml:id="doc-subdir-mk-provided-targets">
<title>Provided Targets</title>
<itemizedlist>
<listitem>
<para><buildtarget>install</buildtarget> e
<buildtarget>package</buildtarget>, ambos descem pela
árvore de diretórios executando a sua
versão real dentro dos subdiretórios.
(<buildtarget>realinstall</buildtarget> e
<buildtarget>realpackage</buildtarget>
respectivamente).</para>
<para><buildtarget>install</buildtarget> and
<buildtarget>package</buildtarget> both go down the
directory tree calling the real versions of themselves
in the subdirectories
(<buildtarget>realinstall</buildtarget> and
<buildtarget>realpackage</buildtarget>
respectively).</para>
</listitem>
<listitem>
<para>O <buildtarget>clean</buildtarget> remove os
arquivos criados pelo processo de
compilação (e também desce na
árvore de diretórios).
O <buildtarget>cleandir</buildtarget> faz a mesma
coisa, e também remove o diretório
de objetos se este existir.</para>
<para><buildtarget>clean</buildtarget> removes files
created by the build process (and goes down the
directory tree too).
<buildtarget>cleandir</buildtarget> does the same, and
also removes the object directory, if any.</para>
</listitem>
</itemizedlist>
</sect4>
</sect3>
<sect3>
<title>Mais Condicionais</title>
<sect3 xml:id="doc-subdir-mk-conditionals">
<title>More on Conditionals</title>
<itemizedlist>
<listitem>
<para><literal>exists</literal> é outra
função condicional que retorna verdadeiro
se o arquivo informado existir.</para>
<para><literal>exists</literal> is another condition
function which returns true if the given file
exists.</para>
</listitem>
<listitem>
<para><literal>empty</literal> retorna verdadeiro se a
variável informada estiver vazia.</para>
<para><literal>empty</literal> returns true if the given
variable is empty.</para>
</listitem>
<listitem>
<para><literal>target</literal> retorna verdadeiro se o
target informado ainda não existir.</para>
<para><literal>target</literal> returns true if the given
target does not already exist.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Construção de Looping no
<command>make (.for)</command></title>
<sect3 xml:id="doc-subdir-mk-looping">
<title>Looping Constructs in <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>
<para><literal>.for</literal> provides a way to repeat a set
of instructions for each space-separated element in a
variable. It does this by assigning a variable to contain
the current element in the list being examined.</para>
<programlisting>_SUBDIRUSE: .USE
<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===&gt; ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} &amp;&amp; \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>
<para>No código acima, se <varname>SUBDIR</varname>
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 <varname>entry</varname>
sendo substituído com o valor do elemento
atual.</para>
<para>In the above, if <varname>SUBDIR</varname> is empty, no
action is taken; if it has one or more elements, the
instructions between <literal>.for</literal> and
<literal>.endfor</literal> would repeat for every element,
with <varname>entry</varname> being replaced with the value
of the current element.</para>
</sect3>
</sect2>
</sect1>

2761
pt_BR.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Normal file
View file

File diff suppressed because it is too large Load diff

248
pt_BR.ISO8859-1/books/fdp-primer/editor-config/chapter.xml Normal file
View file

@ -0,0 +1,248 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 2013 Warren Block
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHORS OR CONTRIBUTORS 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 SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="editor-config">
<title>Editor Configuration</title>
<para>Adjusting text editor configuration can make working on
document files quicker and easier, and help documents conform to
<acronym>FDP</acronym> guidelines.</para>
<sect1 xml:id="editor-config-vim">
<title><application>Vim</application></title>
<para>Install from <package>editors/vim</package>,
<package>editors/vim-console</package>, or
<package>editors/vim-tiny</package> then follow the
configuration instructions in
<xref linkend="editor-config-vim-config"/>.</para>
<sect2 xml:id="editor-config-vim-use">
<title>Use</title>
<para>Press <keycap>P</keycap> to reformat paragraphs or text
that has been selected in Visual mode. Press
<keycap>T</keycap> to replace groups of eight spaces with a
tab.</para>
</sect2>
<sect2 xml:id="editor-config-vim-config">
<title>Configuration</title>
<para>Edit <filename>~/.vimrc</filename>, adding these
lines to the end of the file:</para>
<programlisting>if has("autocmd")
au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
au BufNewFile,BufRead *.[1-9] call ShowSpecial()
endif " has(autocmd)
function Set_Highlights()
"match ExtraWhitespace /^\s* \s*\|\s\+$/
highlight default link OverLength ErrorMsg
match OverLength /\%71v.\+/
return 0
endfunction
function ShowSpecial()
setlocal list listchars=tab:>>,trail:*,eol:$
hi def link nontext ErrorMsg
return 0
endfunction " ShowSpecial()
function Set_SGML()
setlocal number
syn match sgmlSpecial "&amp;[^;]*;"
setlocal syntax=sgml
setlocal filetype=xml
setlocal shiftwidth=2
setlocal textwidth=70
setlocal tabstop=8
setlocal softtabstop=2
setlocal formatprg="fmt -p"
setlocal autoindent
setlocal smartindent
" Rewrap paragraphs
noremap P gqj
" Replace spaces with tabs
noremap T :s/ /\t/&lt;CR&gt;
call ShowSpecial()
call Set_Highlights()
return 0
endfunction " Set_SGML()</programlisting>
</sect2>
</sect1>
<sect1 xml:id="editor-config-emacs">
<title><application>Emacs</application></title>
<para>Install from <package>editors/emacs</package> or
<package>editors/emacs-devel</package>.</para>
<sect2 xml:id="editor-config-emacs-validation">
<title>Validation</title>
<para>Emacs's nxml-mode uses compact relax NG schemas for
validating XML. A compact relax NG schema for FreeBSD's
extension to DocBook 5.0 is included in the documentation
repository. To configure nxml-mode to validate using this
schema, create
<filename>~/.emacs.d/schema/schemas.xml</filename> and add
these lines to the file:</para>
<programlisting><tag class="starttag">locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"</tag>
<tag class="starttag">documentElement localName="section" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="chapter" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="article" typeId="DocBook"</tag>
<tag class="starttag">documentElement localName="book" typeId="DocBook"</tag>
<tag class="starttag">typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc"</tag>
<tag class="endtag">locatingRules</tag></programlisting>
</sect2>
<sect2 xml:id="editor-config-emacs-igor">
<title>Automated Proofreading with Flycheck and Igor</title>
<para>The Flycheck package is available from Milkypostman's
Emacs Lisp Package Archive (<acronym>MELPA</acronym>). If
<acronym>MELPA</acronym> is not already in Emacs's
packages-archives, it can be added by evaluating</para>
<programlisting>(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)</programlisting>
<para>Add the line to Emacs's initialization file (one of
<filename>~/.emacs</filename>,
<filename>~/.emacs.el</filename>, or
<filename>~.emacs.d/init.el</filename>) to make this change
permanent.</para>
<para>To install Flycheck, evaluate</para>
<programlisting>(package-install 'flycheck)</programlisting>
<para>Create a Flycheck checker for
<package>textproc/igor</package> by evaluating</para>
<programlisting>(flycheck-define-checker igor
"FreeBSD Documentation Project sanity checker.
See URLs https://www.freebsd.org/docproj/ and
http://www.freshports.org/textproc/igor/."
:command ("igor" "-X" source-inplace)
:error-parser flycheck-parse-checkstyle
:modes (nxml-mode)
:standard-input t)
(add-to-list 'flycheck-checkers 'igor 'append)</programlisting>
<para>Again, add these lines to Emacs's initialization file to
make the changes permanent.</para>
</sect2>
<sect2 xml:id="editor-config-emacs-specifc">
<title>FreeBSD Documentation Specific Settings</title>
<para>To apply settings specific to the FreeBSD documentation
project, create <filename>.dir-locals.el</filename> in the
root directory of the documentation repository and add these
lines to the file:</para>
<programlisting>;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((nxml-mode
(eval . (turn-on-auto-fill))
(fill-column . 70)
(eval . (require 'flycheck))
(eval . (flycheck-mode 1))
(flycheck-checker . igor)
(eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))</programlisting>
</sect2>
</sect1>
<sect1 xml:id="editor-config-nano">
<title><application>nano</application></title>
<para>Install from
<package>editors/nano</package> or
<package>editors/nano-devel</package>.</para>
<sect2 xml:id="editor-config-nano-config">
<title>Configuration</title>
<para>Copy the sample <acronym>XML</acronym> syntax highlight
file to the user's home directory:</para>
<screen>&prompt.user; <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen>
<para>Use an editor to replace the lines in the
<filename>~/.nanorc</filename> <literal>syntax "xml"</literal>
block with these rules:</para>
<programlisting>syntax "xml" "\.([jrs]html?|xml|xslt?)$"
# trailing whitespace
color ,blue "[[:space:]]+$"
# multiples of eight spaces at the start a line
# (after zero or more tabs) should be a tab
color ,blue "^([TAB]*[ ]{8})+"
# tabs after spaces
color ,yellow "( )+TAB"
# highlight indents that have an odd number of spaces
color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
# lines longer than 70 characters
color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisting>
<para>Process the file to create embedded tabs:</para>
<screen>&prompt.user; <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen>
</sect2>
<sect2 xml:id="editor-config-nano-use">
<title>Use</title>
<para>Specify additional helpful options when running the
editor:</para>
<screen>&prompt.user; <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen>
<para>Users of &man.csh.1; can define an alias in
<filename>~/.cshrc</filename> to automate these
options:</para>
<programlisting>alias nano "nano -AKipwz -r 70 -T8"</programlisting>
<para>After the alias is defined, the options will be added
automatically:</para>
<screen>&prompt.user; <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen>
</sect2>
</sect1>
</chapter>

451
pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,95 +28,80 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples">
<title>Exemplos</title>
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="examples">
<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 &mdash; 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
<uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.
</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>
<title>Examples</title>
<para>These examples are not exhaustive&mdash;they do not contain
all the elements that might be desirable to use, particularly in a
document's front matter. For more examples of DocBook markup,
examine the <acronym>XML</acronym> source for this and other
documents available in the <application>Subversion</application>
<literal>doc</literal> repository, or available online starting at
<uri
xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
<sect1 xml:id="examples-docbook-book">
<title>DockBook <tag>book</tag></title>
<title>DocBook <tag>book</tag></title>
<example>
<title>DocBook <tag>book</tag></title>
<programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"&gt;
<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>
<tag class="starttag">book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:lang="en"</tag>
<copyright>
<year>2000</year>
<holder>Texto de Copyright</holder>
</copyright>
<tag class="starttag">info</tag>
<tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag>
<abstract>
<para>Se seu livro possui um sumário ele deve ser colocado aqui.</para>
</abstract>
</bookinfo>
<tag class="starttag">author</tag>
<tag class="starttag">personname</tag>
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
<tag class="endtag">personname</tag>
<preface>
<title>Prefácio</title>
<tag class="starttag">affiliation</tag>
<tag class="starttag">address</tag>
<tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
<tag class="endtag">address</tag>
<tag class="endtag">affiliation</tag>
<tag class="endtag">author</tag>
<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>
<tag class="starttag">copyright</tag>
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
<tag class="endtag">copyright</tag>
<para>Este é o primeiro capítulo do meu livro.</para>
<tag class="starttag">abstract</tag>
<tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag>
<tag class="endtag">abstract</tag>
<tag class="endtag">info</tag>
<sect1>
<title>Minha primeira seção</title>
<tag class="starttag">preface</tag>
<tag class="starttag">title</tag>Preface<tag class="endtag">title</tag>
<para>Esta é a primeira seção do meu livro.</para>
</sect1>
</chapter>
</book>]]></programlisting>
<tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed
here.<tag class="endtag">para</tag>
<tag class="endtag">preface</tag>
<tag class="starttag">chapter</tag>
<tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag>
<tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag>
<tag class="starttag">sect1</tag>
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
<tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag>
<tag class="endtag">sect1</tag>
<tag class="endtag">chapter</tag>
<tag class="endtag">book</tag></programlisting>
</example>
</sect1>
@ -126,281 +111,51 @@
<example>
<title>DocBook <tag>article</tag></title>
<programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<programlisting>&lt;!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"&gt;
<article>
<articleinfo>
<title>Um exemplo de Artigo</title>
<tag class="starttag">article xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:lang="en"</tag>
<author>
<firstname>Seu nome</firstname>
<surname>Seu sobrenome</surname>
<affiliation>
<address><email>seuemail@example.com</email></address>
</affiliation>
</author>
<tag class="starttag">info</tag>
<tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>
<copyright>
<year>2000</year>
<holder>Texto de Copyright</holder>
</copyright>
<tag class="starttag">author</tag>
<tag class="starttag">personname</tag>
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
<tag class="endtag">personname</tag>
<abstract>
<para>Se o seu artigo possuir um sumário ele deve ser colocado aqui.</para>
</abstract>
</articleinfo>
<tag class="starttag">affiliation</tag>
<tag class="starttag">address</tag>
<tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag>
<tag class="endtag">address</tag>
<tag class="endtag">affiliation</tag>
<tag class="endtag">author</tag>
<sect1>
<title>Minha primeira seção</title>
<tag class="starttag">copyright</tag>
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
<tag class="endtag">copyright</tag>
<para>Esta é a primeira seção do meu artigo.</para>
<tag class="starttag">abstract</tag>
<tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag>
<tag class="endtag">abstract</tag>
<tag class="endtag">info</tag>
<sect2>
<title>Minha primeira subseção</title>
<tag class="starttag">sect1</tag>
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
<para>Esta é a primeira subseção do meu artigo.</para>
</sect2>
</sect1>
</article>]]></programlisting>
<tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag>
<tag class="starttag">sect2</tag>
<tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag>
<tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag>
<tag class="endtag">sect2</tag>
<tag class="endtag">sect1</tag>
<tag class="endtag">article</tag></programlisting>
</example>
</sect1>
<sect1 xml:id="examples-formatted">
<title>Produzindo saídas formatadas</title>
<para>Esta seção assume que você já
instalou os softwares listados no port <package>textproc/docproj</package>, 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 xml:id="examples-co-jade-1-nochunks"/>
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-1-dsssl"/>
-t sgml <co xml:id="examples-co-jade-1-transform"/> file.xml &gt; file.html <co xml: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/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-2-dsssl"/>
-t sgml <co xml:id="examples-co-jade-2-transform"/> file.xml <co xml: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 xml: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 xml:id="examples-co-jade-3-tex-backend"/>
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-catalog"/>
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co xml:id="examples-co-jade-3-dsssl"/>
-t tex <co xml:id="examples-co-jade-3-tex"/> file.xml</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>&amp;jadetex</literal>.</para>
<screen>&prompt.user; <userinput>tex "&amp;jadetex" file.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>arquivo.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 file.ps file.dvi</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>&amp;pdfjadetex</literal>.</para>
<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" file.tex</userinput></screen>
<para>De novo, execute este comando três vezes.</para>
<para>Ele irá gerar um <filename>arquivo
.pdf</filename>, o qual não necessita
de nenhum processamento adicional.</para>
</example>
</sect2>
</sect1>
</appendix>

718
pt_BR.ISO8859-1/books/fdp-primer/manpages/chapter.xml Normal file
View file

@ -0,0 +1,718 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="manpages">
<title>Manual Pages</title>
<sect1 xml:id="manpages-introduction">
<title>Introduction</title>
<para><emphasis>Manual pages</emphasis>, commonly shortened to
<emphasis>man pages</emphasis>, were conceived as
readily-available reminders for command syntax, device driver
details, or configuration file formats. They have become an
extremely valuable quick-reference from the command line for
users, system administrators, and programmers.</para>
<para>Although intended as reference material rather than
tutorials, the EXAMPLES sections of manual pages often
provide detailed use case.</para>
<para>Manual pages are generally shown interactively by the
&man.man.1; command. When the user types
<command>man ls</command>, a search is performed for a manual
page matching <literal>ls</literal>. The first matching result
is displayed.</para>
</sect1>
<sect1 xml:id="manpages-sections">
<title>Sections</title>
<para>Manual pages are grouped into <emphasis>sections</emphasis>.
Each section contains manual pages for a specific category of
documentation:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Section Number</entry>
<entry>Category</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>General Commands</entry>
</row>
<row>
<entry>2</entry>
<entry>System Calls</entry>
</row>
<row>
<entry>3</entry>
<entry>Library Functions</entry>
</row>
<row>
<entry>4</entry>
<entry>Kernel Interfaces</entry>
</row>
<row>
<entry>5</entry>
<entry>File Formats</entry>
</row>
<row>
<entry>6</entry>
<entry>Games</entry>
</row>
<row>
<entry>7</entry>
<entry>Miscellaneous</entry>
</row>
<row>
<entry>8</entry>
<entry>System Manager</entry>
</row>
<row>
<entry>9</entry>
<entry>Kernel Developer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 xml:id="manpages-markup">
<title>Markup</title>
<para>Various markup forms and rendering programs have been used
for manual pages. &os; has used &man.groff.7; and the newer
&man.mandoc.1;. Most existing &os; manual pages, and all new
ones, use the &man.mdoc.7; form of markup. This is a simple
line-based markup that is reasonably expressive. It is mostly
semantic: parts of text are marked up for what they are, rather
than for how they should appear when rendered. There is some
appearance-based markup which is usually best avoided.</para>
<para>Manual page source is usually interpreted and displayed to
the screen interactively. The source files can be ordinary text
files or compressed with &man.gzip.1; to save space.</para>
<para>Manual pages can also be rendered to other formats,
including PostScript for printing or <acronym>PDF</acronym>
generation. See &man.man.1;.</para>
<tip>
<para>Testing a new manual page can be challenging when it is
not located in the normal manual page search path.
&man.man.1; also does not look in the current directory. If
the new manual page is in the current directory, prefix
the filename with a <literal>./</literal>:</para>
<screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen>
<para>An absolute path can also be used:</para>
<screen>&prompt.user; <userinput>man /home/xsmith/mynewmanpage.8</userinput></screen>
</tip>
<sect2 xml:id="manpages-markup-sections">
<title>Manual Page Sections</title>
<para>Manual pages are composed of several standard sections.
Each section has a title in upper case, and the sections for a
particular type of manual page appear in a specific order.
For a category 1 General Command manual page, the sections
are:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Section Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>NAME</entry>
<entry>Name of the command</entry>
</row>
<row>
<entry>SYNOPSIS</entry>
<entry>Format of options and arguments</entry>
</row>
<row>
<entry>DESCRIPTION</entry>
<entry>Description of purpose and usage</entry>
</row>
<row>
<entry>ENVIRONMENT</entry>
<entry>Environment settings that affect
operation</entry>
</row>
<row>
<entry>EXIT STATUS</entry>
<entry>Error codes returned on exit</entry>
</row>
<row>
<entry>EXAMPLES</entry>
<entry>Examples of usage</entry>
</row>
<row>
<entry>COMPATIBILITY</entry>
<entry>Compatibility with other implementations</entry>
</row>
<row>
<entry>SEE ALSO</entry>
<entry>Cross-reference to related manual pages</entry>
</row>
<row>
<entry>STANDARDS</entry>
<entry>Compatibility with standards like POSIX</entry>
</row>
<row>
<entry>HISTORY</entry>
<entry>History of implementation</entry>
</row>
<row>
<entry>BUGS</entry>
<entry>Known bugs</entry>
</row>
<row>
<entry>AUTHORS</entry>
<entry>People who created the command or wrote the
manual page.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Some sections are optional, and the combination of
sections for a specific type of manual page vary. Examples of
the most common types are shown later in this chapter.</para>
</sect2>
<sect2 xml:id="manpages-markup-macros">
<title>Macros</title>
<para>&man.mdoc.7; markup is based on
<emphasis>macros</emphasis>. Lines that begin with a dot
contain macro commands, each two or three letters long. For
example, consider this portion of the &man.ls.1; manual
page:</para>
<programlisting xml:id="manpages-markup-macros-example-ls">
.Dd December 1, 2015 <co xml:id="co-manpages-macro-example-ls-1"/>
.Dt LS 1
.Sh NAME <co xml:id="co-manpages-macro-example-ls-2"/>
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS <co xml:id="co-manpages-macro-example-ls-3"/>
.Nm <co xml:id="co-manpages-macro-example-ls-4"/>
.Op Fl -libxo <co xml:id="co-manpages-macro-example-ls-5"/>
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <co xml:id="co-manpages-macro-example-ls-6"/>
.Op Fl D Ar format <co xml:id="co-manpages-macro-example-ls-7"/>
.Op Ar <co xml:id="co-manpages-macro-example-ls-8"/>
.Sh DESCRIPTION <co xml:id="co-manpages-macro-example-ls-9"/>
For each operand that names a
.Ar file
of a type other than
directory,
.Nm
displays its name as well as any requested,
associated information.
For each operand that names a
.Ar file
of type directory,
.Nm
displays the names of files contained
within that directory, as well as any requested, associated
information.</programlisting>
<calloutlist>
<callout arearefs="co-manpages-macro-example-ls-1">
<para>A <emphasis>Document date</emphasis> and
<emphasis>Document title</emphasis> are defined.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-2">
<para>A <emphasis>Section header</emphasis> for the NAME
section is defined. Then the <emphasis>Name</emphasis>
of the command and a one-line
<emphasis>Name description</emphasis> are defined.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-3">
<para>The SYNOPSIS section begins. This section describes
the command-line options and arguments accepted.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-4">
<para><emphasis>Name</emphasis> (<literal>.Nm</literal>) has
already been defined, and repeating it here just displays
the defined value in the text.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-5">
<para>An <emphasis>Optional</emphasis>
<emphasis>Flag</emphasis> called <literal>-libxo</literal>
is shown. The <literal>Fl</literal> macro adds a dash to
the beginning of flags, so this appears in the manual
page as <literal>--libxo</literal>.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-6">
<para>A long list of optional single-character flags are
shown.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-7">
<para>An optional <literal>-D</literal> flag is defined. If
the <literal>-D</literal> flag is given, it must be
followed by an <emphasis>Argument</emphasis>. The
argument is a <emphasis>format</emphasis>, a string that
tells &man.ls.1; what to display and how to display it.
Details on the format string are given later in the manual
page.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-8">
<para>A final optional argument is defined. Because no name
is specified for the argument, the default of
<literal>file ...</literal> is used.</para>
</callout>
<callout arearefs="co-manpages-macro-example-ls-9">
<para>The <emphasis>Section header</emphasis> for the
DESCRIPTION section is defined.</para>
</callout>
</calloutlist>
<para>When rendered with the command <command>man ls</command>,
the result displayed on the screen looks like this:</para>
<programlisting>LS(1) FreeBSD General Commands Manual LS(1)
NAME
ls &mdash; list directory contents
SYNOPSIS
ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
[file ...]
DESCRIPTION
For each operand that names a file of a type other than directory, ls
displays its name as well as any requested, associated information. For
each operand that names a file of type directory, ls displays the names
of files contained within that directory, as well as any requested,
associated information.</programlisting>
<para>Optional values are shown inside square brackets.</para>
</sect2>
<sect2 xml:id="manpages-markup-guidelines">
<title>Markup Guidelines</title>
<para>The &man.mdoc.7; markup language is not very strict. For
clarity and consistency, the &os; Documentation project adds
some additional style guidelines:</para>
<variablelist>
<varlistentry>
<term>Only the first letter of macros is upper case</term>
<listitem>
<para>Always use upper case for the first letter of a
macro and lower case for the remaining letters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Begin new sentences on new lines</term>
<listitem>
<para>Start a new sentence on a new line, do not begin it
on the same line as an existing sentence.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Update <literal>.Dd</literal> when making non-trivial
changes to a manual page</term>
<listitem>
<para>The <emphasis>Document date</emphasis> informs the
reader about the last time the manual page was updated.
It is important to update whenever non-trivial changes
are made to the manual pages. Trivial changes like
spelling or punctuation fixes that do not affect usage
can be made without updating
<literal>.Dd</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Give examples</term>
<listitem>
<para>Show the reader examples when possible. Even
trivial examples are valuable, because what is trivial
to the writer is not necessarily trivial to the reader.
Three examples are a good goal. A trivial example shows
the minimal requirements, a serious example shows actual
use, and an in-depth example demonstrates unusual or
non-obvious functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Include the BSD license</term>
<listitem>
<para>Include the BSD license on new manual pages. The
preferred license is available from the <link
xlink:href="&url.articles.committers-guide;pref-license">Committer's
Guide</link>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 xml:id="manpages-markup-tricks">
<title>Markup Tricks</title>
<para>Add a space before punctuation on a line with
macros. Example:</para>
<programlisting>.Sh SEE ALSO
.Xr geom 4 ,
.Xr boot0cfg 8 ,
.Xr geom 8 ,
.Xr gptboot 8</programlisting>
<para>Note how the commas at the end of the
<literal>.Xr</literal> lines have been placed after a space.
The <literal>.Xr</literal> macro expects two parameters to
follow it, the name of an external manual page, and a section
number. The space separates the punctuation from the section
number. Without the space, the external links would
incorrectly point to section <literal>4,</literal> or
<literal>8,</literal>.</para>
</sect2>
<sect2 xml:id="manpages-markup-important-macros">
<title>Important Macros</title>
<para>Some very common macros will be shown here. For
more usage examples, see &man.mdoc.7;, &man.groff.mdoc.7;, or
search for actual use in
<filename>/usr/share/man/man*</filename> directories. For
example, to search for examples of the <literal>.Bd</literal>
<emphasis>Begin display</emphasis> macro:</para>
<screen>&prompt.user; <userinput>find /usr/share/man/man* | xargs zgrep '.Bd'</userinput></screen>
<sect3 xml:id="manpages-markup-important-macros-organizational">
<title>Organizational Macros</title>
<para>Some macros are used to define logical blocks of a
manual page.</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Organizational Macro</entry>
<entry>Use</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>.Sh</literal></entry>
<entry>Section header. Followed by the name of
the section, traditionally all upper case.
Think of these as chapter titles.</entry>
</row>
<row>
<entry><literal>.Ss</literal></entry>
<entry>Subsection header. Followed by the name of
the subsection. Used to divide a
<literal>.Sh</literal> section into
subsections.</entry>
</row>
<row>
<entry><literal>.Bl</literal></entry>
<entry>Begin list. Start a list of items.</entry>
</row>
<row>
<entry><literal>.El</literal></entry>
<entry>End a list.</entry>
</row>
<row>
<entry><literal>.Bd</literal></entry>
<entry>Begin display. Begin a special area of
text, like an indented area.</entry>
</row>
<row>
<entry><literal>.Ed</literal></entry>
<entry>End display.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3 xml:id="manpages-markup-important-macros-inline">
<title>Inline Macros</title>
<para>Many macros are used to mark up inline text.</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Inline Macro</entry>
<entry>Use</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>.Nm</literal></entry>
<entry>Name. Called with a name as a parameter on the
first use, then used later without the parameter to
display the name that has already been
defined.</entry>
</row>
<row>
<entry><literal>.Pa</literal></entry>
<entry>Path to a file. Used to mark up filenames and
directory paths.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="manpages-sample-structures">
<title>Sample Manual Page Structures</title>
<para>This section shows minimal desired man page contents for
several common categories of manual pages.</para>
<sect2 xml:id="manpages-sample-structures-section-1-8">
<title>Section 1 or 8 Command</title>
<para>The preferred basic structure for a section 1 or 8
command:</para>
<programlisting xml:id="manpages-sample-structures-section-1-8-sample">.Dd August 25, 2017
.Dt EXAMPLECMD 8
.Os
.Sh NAME
.Nm examplecmd
.Nd "command to demonstrate section 1 and 8 man pages"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility does nothing except demonstrate a trivial but complete
manual page for a section 1 or 8 command.
.Sh SEE ALSO
.Xr exampleconf 5
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
</sect2>
<sect2 xml:id="manpages-sample-structures-section-4">
<title>Section 4 Device Driver</title>
<para>The preferred basic structure for a section 4 device
driver:</para>
<programlisting xml:id="manpages-sample-structures-section-4-sample">.Dd August 25, 2017
.Dt EXAMPLEDRIVER 4
.Os
.Sh NAME
.Nm exampledriver
.Nd "driver to demonstrate section 4 man pages"
.Sh SYNOPSIS
To compile this driver into the kernel, add this line to the
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device exampledriver"
.Ed
.Pp
To load the driver as a module at boot, add this line to
.Xr loader.conf 5 :
.Bd -literal -offset indent
exampledriver_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an opportunity to show a skeleton or template
file for section 4 manual pages.
.Sh HARDWARE
The
.Nm
driver supports these cards from the aptly-named Nonexistent
Technologies:
.Pp
.Bl -bullet -compact
.It
NT X149.2 (single and dual port)
.It
NT X149.8 (single port)
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "flashing green light"
Something bad happened.
.It "flashing red light"
Something really bad happened.
.It "solid black light"
Power cord is unplugged.
.El
.Sh SEE ALSO
.Xr example 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 49.2 .
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
</sect2>
<sect2 xml:id="manpages-sample-structures-section-5">
<title>Section 5 Configuration File</title>
<para>The preferred basic structure for a section 5
configuration file:</para>
<programlisting xml:id="manpages-sample-structures-section-5-sample">.Dd August 25, 2017
.Dt EXAMPLECONF 5
.Os
.Sh NAME
.Nm example.conf
.Nd "config file to demonstrate section 5 man pages"
.Sh DESCRIPTION
.Nm
is an example configuration file.
.Sh SEE ALSO
.Xr example 8
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
</sect2>
</sect1>
<sect1 xml:id="manpages-examples-as-templates">
<title>Example Manual Pages to Use as Templates</title>
<para>Some manual pages are suitable as in-depth examples.</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Manual Page</entry>
<entry>Path to Source Location</entry>
</row>
</thead>
<tbody>
<row>
<entry>&man.cp.1;</entry>
<entry><filename>/usr/src/bin/cp/cp.1</filename></entry>
</row>
<row>
<entry>&man.vt.4;</entry>
<entry><filename>/usr/src/share/man/man4/vt.4</filename></entry>
</row>
<row>
<entry>&man.crontab.5;</entry>
<entry><filename>/usr/src/usr.sbin/cron/crontab/crontab.5</filename></entry>
</row>
<row>
<entry>&man.gpart.8;</entry>
<entry><filename>/usr/src/sbin/geom/class/part/gpart.8</filename></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 xml:id="manpages-resources">
<title>Resources</title>
<para>Resources for manual page writers:</para>
<itemizedlist>
<listitem>
<para>&man.man.1;</para>
</listitem>
<listitem>
<para>&man.mandoc.1;</para>
</listitem>
<listitem>
<para>&man.groff.mdoc.7;</para>
</listitem>
<listitem>
<para><link
xlink:href="http://manpages.bsd.lv/mdoc.html">Practical
UNIX Manuals: mdoc</link></para>
</listitem>
<listitem>
<para><link
xlink:href="http://manpages.bsd.lv/history.html">History
of UNIX Manpages</link></para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

456
pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml
View file

@ -7,14 +7,14 @@
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.
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.
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
@ -28,317 +28,237 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
<title>Visão Geral</title>
<title>Overview</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>Welcome to the &os; Documentation Project
(<acronym>FDP</acronym>). Quality documentation is crucial
to the success of &os;, and we value your contributions very
highly.</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>This document describes how the <acronym>FDP</acronym> is
organized, how to write and submit documentation, and how to
effectively use the available tools.</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>Everyone is welcome to contribute to the
<acronym>FDP</acronym>. Willingness to contribute is the only
membership requirement.</para>
<para>Depois que você tiver terminado de ler este documento,
você deve:</para>
<para>This primer shows how to:</para>
<itemizedlist>
<listitem>
<para>Saber quais documentos são mantidos pelo FDP.
</para>
<para>Identify which parts of &os; are maintained by the
<acronym>FDP</acronym>.</para>
</listitem>
<listitem>
<para>Ser capaz de ler e entender o código fonte SGML
de um documento mantido pelo FDP.</para>
<para>Install the required documentation tools and files.</para>
</listitem>
<listitem>
<para>Ser capaz de efetuar alterações num
documento.</para>
<para>Make changes to the documentation.</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>
<para>Submit changes back for review and inclusion in the &os;
documentation.</para>
</listitem>
</itemizedlist>
<sect1 xml: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
<link xlink:href="&url.base;/index.html">
http://www.FreeBSD.org/</link>
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 xml: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 xml:id="overview-quick-start">
<title>Início Rápido</title>
<title>Quick Start</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>
<para>Some preparatory steps must be taken before editing the &os;
documentation. First, subscribe to the &a.doc;. Some team
members also interact on the <literal>#bsddocs</literal>
<acronym>IRC</acronym> channel on
<link xlink:href="http://www.efnet.org/">EFnet</link>. These
people can help with questions or problems involving the
documentation.</para>
<procedure>
<step>
<para>Instale o meta-port <package>
textproc/docproj</package>.</para>
<para>Install the
<package>textproc/docproj</package> meta-package
and <application>Subversion</application>.
This meta-package installs all of the software needed to
edit and build &os; documentation. The
<application>Subversion</application> package is needed to
obtain a working copy of the documentation and generate
patches with.</para>
<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
<screen>&prompt.root; <userinput>pkg install docproj subversion</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/idioma/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>
<para>Install a local working copy of the documentation from
the &os; repository in
<filename>~/doc</filename> (see
<xref linkend="working-copy"/>).</para>
<screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></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>
<para>Configure the text editor:</para>
<screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen>
<itemizedlist>
<listitem>
<para>Word wrap set to 70 characters.</para>
</listitem>
</step>
<listitem>
<para>Tab stops set to 2.</para>
</listitem>
<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>
<listitem>
<para>Replace each group of 8 leading spaces with a
single tab.</para>
</listitem>
</itemizedlist>
<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>
<para>Specific editor configurations are listed in
<xref linkend="editor-config"/>.</para>
</step>
<step>
<para>Edite os arquivos <filename>.xml</filename>
utilizando o editor da sua preferência.</para>
<para>Update the local working copy:</para>
<screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>Teste a marcação SGML utilizando o alvo
<buildtarget>lint</buildtarget> 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>
<para>Edit the documentation files that require changes. If a
file needs major changes, consult the mailing list for
input.</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>
<para>References to tag and entity usage can be found in
<xref linkend="xhtml-markup"/> and
<xref linkend="docbook-markup"/>.</para>
</step>
<step>
<para>Envie suas alterações utilizando o
&man.send-pr.1;.</para>
<para>After editing, check for problems by running:</para>
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
<para>Review the output and edit the file to fix any problems
shown, then rerun the command to find any remaining
problems. Repeat until all of the errors are
resolved.</para>
</step>
<step>
<para><emphasis>Always</emphasis> build-test changes before
submitting them. Running <userinput>make</userinput> in the
top-level directory of the documentation being edited will
generate that documentation in split HTML format. For
example, to build the English version of the Handbook in
<acronym>HTML</acronym>, run <command>make</command> in the
<filename>en_US.ISO8859-1/books/handbook/</filename>
directory.</para>
</step>
<step>
<para>When changes are complete and tested, generate a
<quote>diff file</quote>:</para>
<screen>&prompt.user; <userinput>cd ~/doc</userinput>
&prompt.user; <userinput>svn diff &gt; <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
<para>Give the diff file a descriptive name. In the example
above, changes have been made to the
<filename>bsdinstall</filename> portion of
the Handbook.</para>
</step>
<step>
<para>Submit the diff file using the web-based <link
xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation">Problem
Report</link> system. If using the web form, enter a
Summary of <emphasis>[patch] <replaceable>short description
of problem</replaceable></emphasis>. Select the
Component <literal>Documentation</literal>. In the
Description field, enter a short description of the changes
and any important details about them. Use the
<guibutton>[&nbsp;Add an attachment&nbsp;]</guibutton>
button to attach the diff file. Finally, use the
<guibutton>[&nbsp;Submit Bug&nbsp;]</guibutton> button to
submit your diff to the problem report system.</para>
</step>
</procedure>
</sect1>
<sect1 xml:id="overview-doc">
<title>The &os; Documentation Set</title>
<para>The <acronym>FDP</acronym> is responsible for four
categories of &os; documentation.</para>
<itemizedlist>
<listitem>
<para><emphasis>Handbook</emphasis>: The Handbook is the
comprehensive online resource and reference for &os;
users.</para>
</listitem>
<listitem>
<para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym>
uses a short question and answer format to address questions
that are frequently asked on the various mailing lists and
forums devoted to &os;. This format does not permit long
and comprehensive answers.</para>
</listitem>
<listitem>
<para><emphasis>Manual pages</emphasis>: The English language
system manual pages are usually not written by the
<acronym>FDP</acronym>, as they are part of the base system.
However, the <acronym>FDP</acronym> can reword parts of
existing manual pages to make them clearer or to correct
inaccuracies.</para>
</listitem>
<listitem>
<para><emphasis>Web site</emphasis>: This is the main &os;
presence on the web, visible at <link
xlink:href="https://www.freebsd.org/index.html">
https://www.FreeBSD.org/</link>
and many mirrors around the world. The web site is
typically a new user's first exposure to &os;.</para>
</listitem>
</itemizedlist>
<para>Translation teams are responsible for translating the
Handbook and web site into different languages. Manual pages
are not translated at present.</para>
<para>Documentation source for the &os; web site, Handbook, and
<acronym>FAQ</acronym> is available in the documentation
repository at
<literal>https://svn.FreeBSD.org/doc/</literal>.</para>
<para>Source for manual pages is available in a separate
source repository located at
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
<para>Documentation commit messages are visible with
<command>svn log</command>. Commit messages are also
archived at <uri xlink:href="&a.svn-doc-all.url;">
&a.svn-doc-all.url;</uri>.</para>
<para>Web frontends to both of these repositories are available
at <link xlink:href="https://svnweb.FreeBSD.org/doc/"></link>
and <link
xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para>
<para>Many people have written tutorials or how-to articles about
&os;. Some are stored as part of the <acronym>FDP</acronym>
files. In other cases, the author has decided to keep the
documentation separate. The <acronym>FDP</acronym> endeavors to
provide links to as much of this external documentation as
possible.</para>
</sect1>
</chapter>

927
pt_BR.ISO8859-1/books/fdp-primer/po-translations/chapter.xml Normal file
View file

@ -0,0 +1,927 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="po-translations">
<title><acronym>PO</acronym> Translations</title>
<sect1 xml:id="po-translations-introduction">
<title>Introduction</title>
<para>The <link
xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym>
<application>gettext</application></link> system offers
translators an easy way to create and maintain translations of
documents. Translatable strings are extracted from the original
document into a <acronym>PO</acronym> (Portable Object) file.
Translated versions of the strings are entered with a separate
editor. The strings can be used directly or built into a
complete translated version of the original document.</para>
</sect1>
<sect1 xml:id="po-translations-quick-start">
<title>Quick Start</title>
<para>The procedure shown in
<xref linkend="overview-quick-start"/> is assumed to have
already been performed, but the <literal>TRANSLATOR</literal>
option must be enabled in the
<package role="port">textproc/docproj</package> port. If that
option was not enabled, display the options menu and enable
it, then reinstall the port:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make config</userinput>
&prompt.root; <userinput>make clean deinstall install clean</userinput></screen>
<para>This example shows the creation of a Spanish translation of
the short <link xlink:href="&url.articles.leap-seconds.en;">Leap
Seconds</link> article.</para>
<procedure xml:id="po-translations-quick-start-install-po-editor">
<title>Install a <acronym>PO</acronym> Editor</title>
<step>
<para>A <acronym>PO</acronym> editor is needed to edit
translation files. This example uses
<package role="ports">editors/poedit</package>.</para>
<screen>&prompt.root; <userinput>cd /usr/ports/editors/poedit</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
</step>
</procedure>
<procedure xml:id="po-translations-quick-start-initial-setup">
<title>Initial Setup</title>
<para>When a new translation is first created, the directory
structure and <filename>Makefile</filename> must be created or
copied from the English original:</para>
<step>
<para>Create a directory for the new translation. The
English article source is in
<filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>.
The Spanish translation will go in
<filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>.
The path is the same except for the name of the language
directory.</para>
<screen>&prompt.user; <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
</step>
<step>
<para>Copy the <filename>Makefile</filename> from the original
document into the translation directory:</para>
<screen>&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
</step>
</procedure>
<procedure xml:id="po-translations-quick-start-translation">
<title>Translation</title>
<para>Translating a document consists of two steps: extracting
translatable strings from the original document, and entering
translations for those strings. These steps are repeated
until the translator feels that enough of the document has
been translated to produce a usable translated
document.</para>
<step>
<para>Extract the translatable strings from the original
English version into a <acronym>PO</acronym> file:</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
&prompt.user; <userinput>make po</userinput></screen>
</step>
<step>
<para>Use a <acronym>PO</acronym> editor to enter translations
in the <acronym>PO</acronym> file. There are several
different editors available. <filename>poedit</filename>
from <package role="port">editors/poedit</package> is shown
here.</para>
<para>The <acronym>PO</acronym> file name is the
two-character language code followed by an underline and a
two-character region code. For Spanish, the file name is
<filename>es_ES.po</filename>.</para>
<screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
</step>
</procedure>
<procedure
xml:id="po-translations-quick-generating-a-translated-document">
<title>Generating a Translated Document</title>
<step>
<para>Generate the translated document:</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
&prompt.user; <userinput>make tran</userinput></screen>
<para>The name of the generated document matches the name
of the English original, usually
<filename>article.xml</filename> for articles or
<filename>book.xml</filename> for books.</para>
</step>
<step>
<para>Check the generated file by rendering it to
<acronym>HTML</acronym> and viewing it with a
web browser:</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
&prompt.user; <userinput>firefox article.html</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 xml:id="po-translations-creating">
<title>Creating New Translations</title>
<para>The first step to creating a new translated document is
locating or creating a directory to hold it. &os; puts
translated documents in a subdirectory named for their
language and region in the format
<filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>.
<replaceable>lang</replaceable> is a two-character lowercase
code. It is followed by an underscore character and then the
two-character uppercase <replaceable>REGION</replaceable>
code.</para>
<table xml:id="po-translations-language-names" frame="none">
<title>Language Names</title>
<tgroup cols="5">
<thead>
<row>
<entry>Language</entry>
<entry>Region</entry>
<entry>Translated Directory Name</entry>
<entry><acronym>PO</acronym> File Name</entry>
<entry>Character Set</entry>
</row>
</thead>
<tbody>
<row>
<entry>English</entry>
<entry>United States</entry>
<entry><filename>en_US.ISO8859-1</filename></entry>
<entry><filename>en_US.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>Bengali</entry>
<entry>Bangladesh</entry>
<entry><filename>bn_BD.UTF-8</filename></entry>
<entry><filename>bn_BD.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>
</row>
<row>
<entry>Danish</entry>
<entry>Denmark</entry>
<entry><filename>da_DK.ISO8859-1</filename></entry>
<entry><filename>da_DK.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>German</entry>
<entry>Germany</entry>
<entry><filename>de_DE.ISO8859-1</filename></entry>
<entry><filename>de_DE.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>Greek</entry>
<entry>Greece</entry>
<entry><filename>el_GR.ISO8859-7</filename></entry>
<entry><filename>el_GR.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-7</entry>
</row>
<row>
<entry>Spanish</entry>
<entry>Spain</entry>
<entry><filename>es_ES.ISO8859-1</filename></entry>
<entry><filename>es_ES.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>French</entry>
<entry>France</entry>
<entry><filename>fr_FR.ISO8859-1</filename></entry>
<entry><filename>fr_FR.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>Hungarian</entry>
<entry>Hungary</entry>
<entry><filename>hu_HU.ISO8859-2</filename></entry>
<entry><filename>hu_HU.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-2</entry>
</row>
<row>
<entry>Italian</entry>
<entry>Italy</entry>
<entry><filename>it_IT.ISO8859-15</filename></entry>
<entry><filename>it_IT.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-15</entry>
</row>
<row>
<entry>Japanese</entry>
<entry>Japan</entry>
<entry><filename>ja_JP.eucJP</filename></entry>
<entry><filename>ja_JP.po</filename></entry>
<entry><acronym>EUC</acronym> JP</entry>
</row>
<row>
<entry>Korean</entry>
<entry>Korea</entry>
<entry><filename>ko_KR.UTF-8</filename></entry>
<entry><filename>ko_KR.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>
</row>
<row>
<entry>Mongolian</entry>
<entry>Mongolia</entry>
<entry><filename>mn_MN.UTF-8</filename></entry>
<entry><filename>mn_MN.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>
</row>
<row>
<entry>Dutch</entry>
<entry>Netherlands</entry>
<entry><filename>nl_NL.ISO8859-1</filename></entry>
<entry><filename>nl_NL.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>Polish</entry>
<entry>Poland</entry>
<entry><filename>pl_PL.ISO8859-2</filename></entry>
<entry><filename>pl_PL.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-2</entry>
</row>
<row>
<entry>Portuguese</entry>
<entry>Brazil</entry>
<entry><filename>pt_BR.ISO8859-1</filename></entry>
<entry><filename>pt_BR.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-1</entry>
</row>
<row>
<entry>Russian</entry>
<entry>Russia</entry>
<entry><filename>ru_RU.KOI8-R</filename></entry>
<entry><filename>ru_RU.po</filename></entry>
<entry><acronym>KOI</acronym>8-R</entry>
</row>
<row>
<entry>Turkish</entry>
<entry>Turkey</entry>
<entry><filename>tr_TR.ISO8859-9</filename></entry>
<entry><filename>tr_TR.po</filename></entry>
<entry><acronym>ISO</acronym> 8859-9</entry>
</row>
<row>
<entry>Chinese</entry>
<entry>China</entry>
<entry><filename>zh_CN.UTF-8</filename></entry>
<entry><filename>zh_CN.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>
</row>
<row>
<entry>Chinese</entry>
<entry>Taiwan</entry>
<entry><filename>zh_TW.UTF-8</filename></entry>
<entry><filename>zh_TW.po</filename></entry>
<entry><acronym>UTF</acronym>-8</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The translations are in subdirectories of the main
documentation directory, here assumed to be
<filename>~/doc/</filename> as shown in
<xref linkend="overview-quick-start"/>. For example, German
translations are located in
<filename>~/doc/de_DE.ISO8859-1/</filename>, and French
translations are in
<filename>~/doc/fr_FR.ISO8859-1/</filename>.</para>
<para>Each language directory contains separate subdirectories
named for the type of documents, usually
<filename>articles/</filename> and
<filename>books/</filename>.</para>
<para>Combining these directory names gives the complete path to
an article or book. For example, the French translation of the
NanoBSD article is in
<filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>,
and the Mongolian translation of the Handbook is in
<filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>.</para>
<para>A new language directory must be created when translating
a document to a new language. If the language directory already
exists, only a subdirectory in the
<filename>articles/</filename> or <filename>books/</filename>
directory is needed.</para>
<para>&os; documentation builds are controlled by a
<filename>Makefile</filename> in the same directory. With
simple articles, the <filename>Makefile</filename> can often
just be copied verbatim from the original English directory.
The translation process combines multiple separate
<filename>book.xml</filename> and
<filename>chapter.xml</filename> files in books into a single
file, so the <filename>Makefile</filename> for book translations
must be copied and modified.</para>
<example xml:id="po-translations-creating-example">
<title>Creating a Spanish Translation of the Porter's
Handbook</title>
<para>Create a new Spanish translation of the
<link xlink:href="&url.books.porters-handbook.en;">Porter's
Handbook</link>. The original is a book in
<filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para>
<procedure>
<step>
<para>The Spanish language books directory
<filename>~/doc/es_ES.ISO8859-1/books/</filename> already
exists, so only a new subdirectory for the Porter's
Handbook is needed:</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
&prompt.user; <userinput>svn mkdir porters-handbook</userinput>
A porters-handbook</screen>
</step>
<step>
<para>Copy the <filename>Makefile</filename> from the
original book:</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>
A Makefile</screen>
<para>Modify the contents of the
<filename>Makefile</filename> to only expect a single
<filename>book.xml</filename>:</para>
<programlisting>#
# &dollar;FreeBSD&dollar;
#
# Build the FreeBSD Porter's Handbook.
#
MAINTAINER=doc@FreeBSD.org
DOC?= book
FORMATS?= html-split
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
# XML content
SRCS= book.xml
# Images from the cross-document image library
IMAGES_LIB+= callouts/1.png
IMAGES_LIB+= callouts/2.png
IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
IMAGES_LIB+= callouts/6.png
IMAGES_LIB+= callouts/7.png
IMAGES_LIB+= callouts/8.png
IMAGES_LIB+= callouts/9.png
IMAGES_LIB+= callouts/10.png
IMAGES_LIB+= callouts/11.png
IMAGES_LIB+= callouts/12.png
IMAGES_LIB+= callouts/13.png
IMAGES_LIB+= callouts/14.png
IMAGES_LIB+= callouts/15.png
IMAGES_LIB+= callouts/16.png
IMAGES_LIB+= callouts/17.png
IMAGES_LIB+= callouts/18.png
IMAGES_LIB+= callouts/19.png
IMAGES_LIB+= callouts/20.png
IMAGES_LIB+= callouts/21.png
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
<para>Now the document structure is ready for the translator
to begin translating with
<command>make po</command>.</para>
</step>
</procedure>
</example>
<example xml:id="po-translations-creating-example-french">
<title>Creating a French Translation of the
<acronym>PGP</acronym> Keys Article</title>
<para>Create a new French translation of the
<link
xlink:href="&url.articles.pgpkeys;"><acronym>PGP</acronym>
Keys article</link>. The original is an article in
<filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>.</para>
<procedure>
<step>
<para>The French language article directory
<filename>~/doc/fr_FR.ISO8859-1/articles/</filename>
already exists, so only a new subdirectory for the
<acronym>PGP</acronym> Keys article is needed:</para>
<screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
&prompt.user; <userinput>svn mkdir pgpkeys</userinput>
A pgpkeys</screen>
</step>
<step>
<para>Copy the <filename>Makefile</filename> from the
original article:</para>
<screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>
&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>
A Makefile</screen>
<para>Check the contents of the
<filename>Makefile</filename>. Because this is a simple
article, in this case the <filename>Makefile</filename>
can be used unchanged. The <literal>$&os;...$</literal>
version string on the second line will be replaced by the
version control system when this file is committed.</para>
<programlisting>#
# &dollar;FreeBSD&dollar;
#
# Article: PGP Keys
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
# To build with just key fingerprints, set FINGERPRINTS_ONLY.
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
<para>With the document structure complete, the
<acronym>PO</acronym> file can be created with
<command>make po</command>.</para>
</step>
</procedure>
</example>
</sect1>
<sect1 xml:id="po-translations-translating">
<title>Translating</title>
<para>The <application>gettext</application> system greatly
reduces the number of things that must be tracked by a
translator. Strings to be translated are extracted from the
original document into a <acronym>PO</acronym> file. Then a
<acronym>PO</acronym> editor is used to enter the translated
versions of each string.</para>
<para>The &os; <acronym>PO</acronym> translation system does not
overwrite <acronym>PO</acronym> files, so the extraction step
can be run at any time to update the <acronym>PO</acronym>
file.</para>
<para>A <acronym>PO</acronym> editor is used to edit the file.
<package role="port">editors/poedit</package> is shown in
these examples because it is simple and has minimal
requirements. Other <acronym>PO</acronym> editors offer
features to make the job of translating easier. The Ports
Collection offers several of these editors, including
<package role="port">devel/gtranslator</package>.</para>
<para>It is important to preserve the <acronym>PO</acronym> file.
It contains all of the work that translators have done.</para>
<example xml:id="po-translations-translating-example">
<title>Translating the Porter's Handbook to Spanish</title>
<para>Enter Spanish translations of the contents of the Porter's
Handbook.</para>
<procedure>
<step>
<para>Change to the Spanish Porter's Handbook directory and
update the <acronym>PO</acronym> file. The generated
<acronym>PO</acronym> file is called
<filename>es_ES.po</filename> as shown in
<xref linkend="po-translations-language-names"/>.</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
&prompt.user; <userinput>make po</userinput></screen>
</step>
<step>
<para>Enter translations using a <acronym>PO</acronym>
editor:</para>
<screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
</step>
</procedure>
</example>
</sect1>
<sect1 xml:id="po-translations-tips">
<title>Tips for Translators</title>
<sect2 xml:id="po-translations-tips-xmltags">
<title>Preserving <acronym>XML</acronym> Tags</title>
<para>Preserve <acronym>XML</acronym> tags that are shown in
the English original.</para>
<example>
<title>Preserving <acronym>XML</acronym> Tags</title>
<para>English original:</para>
<programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>
<para>Spanish translation:</para>
<programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>
</example>
</sect2>
<sect2 xml:id="po-translations-tips-spaces">
<title>Preserving Spaces</title>
<para>Preserve existing spaces at the beginning and end of
strings to be translated. The translated version must have
these spaces also.</para>
</sect2>
<sect2 xml:id="po-translations-tips-verbatim">
<title>Verbatim Tags</title>
<para>The contents of some tags should be copied verbatim, not
translated:</para>
<itemizedlist xml:id="po-translations-tips-verbatim-list">
<listitem>
<para><tag class="starttag">citerefentry</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">command</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">filename</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">literal</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">manvolnum</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">orgname</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">package</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">programlisting</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">prompt</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">refentrytitle</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">screen</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">userinput</tag></para>
</listitem>
<listitem>
<para><tag class="starttag">varname</tag></para>
</listitem>
</itemizedlist>
</sect2>
<sect2 xml:id="po-translations-literal-dollar">
<title><literal>&dollar;FreeBSD&dollar;</literal>
Strings</title>
<para>The &dollar;FreeBSD&dollar; version strings used in
files require special handling. In examples like
<xref linkend="po-translations-creating-example"/>, these
strings are not meant to be expanded. The English documents
use <literal>&amp;dollar;</literal> entities to avoid
including actual literal dollar signs in the file:</para>
<programlisting>&amp;dollar;FreeBSD&amp;dollar;</programlisting>
<para>The <literal>&amp;dollar;</literal> entities are not seen
as dollar signs by the version control system and so the
string is not expanded into a version string.</para>
<para>When a <acronym>PO</acronym> file is created, the
<literal>&amp;dollar;</literal> entities used in examples are
replaced with actual dollar signs. The resulting literal
<literal>&dollar;FreeBSD&dollar;</literal> string will be
wrongly expanded by the version control system when the file
is committed.</para>
<para>The same technique as used in the English documents can be
used in the translation. The <literal>&amp;dollar;</literal>
is used to replace the dollar sign in the translation entered
into the <acronym>PO</acronym> editor:</para>
<programlisting>&amp;dollar;FreeBSD&amp;dollar;</programlisting>
</sect2>
<!--
<sect2 xml:id="po-translations-tips-makefile">
<title>Modifying the <filename>Makefile</filename></title>
<para>What needs to be changed in the
<filename>Makefile</filename>?</para>
</sect2>
<sect2 xml:id="po-translations-tips-locale">
<title>Setting Locales for Editing</title>
<para>Locale settings so the <acronym>PO</acronym> editor works
correctly?</para>
</sect2>
<sect2 xml:id="po-translations-tips-poeditors">
<title>Settings for Specific <acronym>PO</acronym>
Editors</title>
<para>Per bcr: turn off "intelligent quotes" in
Mac poedit.</para>
</sect2>
<sect2 xml:id="po-translations-tips-tm">
<title>Using Translation Memory</title>
<para>Using translation memory. Saving, updating, sharing
with other members of a translation team.</para>
</sect2>
<sect2 xml:id="po-translations-tips-submitting">
<title>Submitting Translations</title>
<para>Submitting translations as diffs, committing
<acronym>PO</acronym> files.</para>
</sect2>
-->
</sect1>
<sect1 xml:id="po-translations-building">
<title>Building a Translated Document</title>
<para>A translated version of the original document can be created
at any time. Any untranslated portions of the original will be
included in English in the resulting document. Most
<acronym>PO</acronym> editors have an indicator that shows how
much of the translation has been completed. This makes it easy
for the translator to see when enough strings have been
translated to make building the final document
worthwhile.</para>
<example xml:id="po-translations-building-example">
<title>Building the Spanish Porter's Handbook</title>
<para>Build and preview the Spanish version of the Porter's
Handbook that was created in an earlier example.</para>
<procedure>
<step>
<para>Build the translated document. Because the original
is a book, the generated document is
<filename>book.xml</filename>.</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
&prompt.user; <userinput>make tran</userinput></screen>
</step>
<step>
<para>Render the translated <filename>book.xml</filename> to
<acronym>HTML</acronym> and view it with
<application>Firefox</application>. This is the
same procedure used with the English version of the
documents, and other <varname>FORMATS</varname> can
be used here in the same way. See <xref
linkend="doc-build-rendering-common-formats"/>.</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
&prompt.user; <userinput>firefox book.html</userinput></screen>
</step>
</procedure>
</example>
</sect1>
<sect1 xml:id="po-translations-submitting">
<title>Submitting the New Translation</title>
<para>Prepare the new translation files for submission. This
includes adding the files to the version control system, setting
additional properties on them, then creating a diff for
submission.</para>
<para>The diff files created by these examples can be attached to
a <link
xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation
bug report</link> or <link
xlink:href="https://reviews.freebsd.org/">code
review</link>.</para>
<example xml:id="po-translations-submitting-spanish">
<title>Spanish Translation of the NanoBSD Article</title>
<procedure>
<step>
<para>Add a &os; version string comment as the first
line of the <acronym>PO</acronym> file:</para>
<programlisting>#&dollar;FreeBSD&dollar;</programlisting>
</step>
<step>
<para>Add the <filename>Makefile</filename>, the
<acronym>PO</acronym> file, and the generated
<acronym>XML</acronym> translation to
version control:</para>
<screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
&prompt.user; <userinput>ls</userinput>
Makefile article.xml es_ES.po
&prompt.user; <userinput>svn add Makefile article.xml es_ES.po</userinput>
A Makefile
A article.xml
A es_ES.po</screen>
</step>
<step>
<para>Set the
<application>Subversion</application>
<literal>svn:keywords</literal> properties on these files
to <literal>FreeBSD=%H</literal> so
<literal>&dollar;FreeBSD&dollar;</literal> strings are
expanded into the path, revision, date, and author when
committed:</para>
<screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>
property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'es_ES.po'</screen>
</step>
<step>
<para>Set the <acronym>MIME</acronym> types of the files.
These are <literal>text/xml</literal> for books and
articles, and
<literal>text/x-gettext-translation</literal> for the
<acronym>PO</acronym> file.</para>
<screen>&prompt.user; <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>
property 'svn:mime-type' set on 'es_ES.po'
&prompt.user; <userinput>svn propset svn:mime-type text/xml article.xml</userinput>
property 'svn:mime-type' set on 'article.xml'</screen>
</step>
<step>
<para>Create a diff of the new files from the
<filename>~/doc/</filename> base directory so the full
path is shown with the filenames. This helps committers
identify the target language directory.</para>
<screen>&prompt.user; <userinput>cd ~/doc</userinput>
<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen>
</step>
</procedure>
</example>
<example xml:id="po-translations-submitting-korean-utf8">
<title>Korean <acronym>UTF-8</acronym> Translation of the
Explaining-BSD Article</title>
<procedure>
<step>
<para>Add a &os; version string comment as the first
line of the <acronym>PO</acronym> file:</para>
<programlisting>#&dollar;FreeBSD&dollar;</programlisting>
</step>
<step>
<para>Add the <filename>Makefile</filename>, the
<acronym>PO</acronym> file, and the generated
<acronym>XML</acronym> translation to
version control:</para>
<screen>&prompt.user; <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput>
&prompt.user; <userinput>ls</userinput>
Makefile article.xml ko_KR.po
&prompt.user; <userinput>svn add Makefile article.xml ko_KR.po</userinput>
A Makefile
A article.xml
A ko_KR.po</screen>
</step>
<step>
<para>Set the <application>Subversion</application>
<literal>svn:keywords</literal> properties on these files
to <literal>FreeBSD=%H</literal> so
<literal>&dollar;FreeBSD&dollar;</literal> strings are
expanded into the path, revision, date, and author when
committed:</para>
<screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>
property 'svn:keywords' set on 'Makefile'
property 'svn:keywords' set on 'article.xml'
property 'svn:keywords' set on 'ko_KR.po'</screen>
</step>
<step>
<para>Set the <acronym>MIME</acronym> types of the files.
Because these files use the <acronym>UTF-8</acronym>
character set, that is also specified. To prevent the
version control system from mistaking these files for
binary data, the <literal>fbsd:notbinary</literal>
property is also set:</para>
<screen>&prompt.user; <userinput>svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po</userinput>
property 'svn:mime-type' set on 'ko_KR.po'
&prompt.user; <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput>
property 'fbsd:notbinary' set on 'ko_KR.po'
&prompt.user; <userinput>svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml</userinput>
property 'svn:mime-type' set on 'article.xml'
&prompt.user; <userinput>svn propset fbsd:notbinary yes article.xml</userinput>
property 'fbsd:notbinary' set on 'article.xml'</screen>
</step>
<step>
<para>Create a diff of these new files from the
<filename>~/doc/</filename> base directory:</para>
<screen>&prompt.user; <userinput>cd ~/doc</userinput>
<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput></screen>
</step>
</procedure>
</example>
</sect1>
</chapter>

175
pt_BR.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,49 +28,38 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="psgml-mode">
<title>Usando <literal>sgml-mode</literal> com o
<title>Using <literal>sgml-mode</literal> with
<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 <package>editors/psgml</package>). Ele
é automaticamente invocado quando um arquivo com a
extensão <filename>.xml</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>Recent versions of <application>Emacs</application> or
<application>XEmacs</application> (available from the Ports
Collection) contain a very useful package called PSGML (can be
installed from <package>editors/psgml</package>).
Automatically invoked when a file with the
<filename>.xml</filename> extension is loaded, or by typing
<command>M-x sgml-mode</command>, it is a major mode for dealing
with SGML files, elements and attributes.</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>
<para>An understanding of some of the commands provided by this mode
can make working with SGML documents such as the Handbook much
easier.</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>Runs <function>sgml-insert-element</function>. You will
be prompted for the name of the element to insert at the
current point. You can use the <keycap>Tab</keycap> key to
complete the element. Elements that are not valid at the
current point will be disallowed.</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>
<para>The start and end tags for the element will be inserted.
If the element contains other, mandatory, elements then
these will be inserted as well.</para>
</listitem>
</varlistentry>
@ -78,12 +67,11 @@
<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>
<para>Runs <function>sgml-change-element-name</function>.
Place the point within an element and run this command. You
will be prompted for the name of the element to change to.
Both the start and end tags of the current element will be
changed to the new element.</para>
</listitem>
</varlistentry>
@ -91,16 +79,12 @@
<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>
<para>Runs <function>sgml-tag-region</function>. Select some
text (move to start of text, <command>C-space</command>,
move to end of text, <command>C-space</command>) and then
run this command. You will be prompted for the element to
use. This element will then be inserted immediately before
and after your marked region.</para>
</listitem>
</varlistentry>
@ -108,11 +92,10 @@
<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>
<para>Runs <function>sgml-untag-element</function>. Place the
point within the start or end tag of an element you want to
remove, and run this command. The element's start and end
tags will be removed.</para>
</listitem>
</varlistentry>
@ -120,13 +103,12 @@
<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
<tag>programlisting</tag>, assim utilize este
comando com cuidado.</para>
<para>Runs <function>sgml-fill-element</function>. Will
recursively fill (i.e., reformat) content from the current
element in. The filling <emphasis>will</emphasis> affect
content in which whitespace is significant, such as within
<tag>programlisting</tag> elements, so run this
command with care.</para>
</listitem>
</varlistentry>
@ -134,16 +116,13 @@
<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>
<para>Runs <function>sgml-edit-attributes</function>. Opens a
second buffer containing a list of all the attributes for
the closest enclosing element, and their current values.
Use <keycap>Tab</keycap> to navigate between attributes,
<command>C-k</command> to remove an existing value and
replace it with a new one, <command>C-c C-c</command> to
close this buffer and return to the main document.</para>
</listitem>
</varlistentry>
@ -151,36 +130,32 @@
<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>
<para>Runs <function>sgml-validate</function>. Prompts you to
save the current document (if necessary) and then runs an
SGML validator. The output from the validator is captured
into a new buffer, and you can then navigate from one
troublespot to the next, fixing markup errors as you
go.</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>
<term><command>C-c /</command></term>
<listitem>
<para>Runs <function>sgml-insert-end-tag</function>. Inserts
the end tag for the current open element.</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>Doubtless there are other useful functions of this mode, but
those are the ones I use most often.</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>
<para>You can also use the following entries in
<filename>.emacs</filename> to set proper spacing, indentation,
and column width for working with the Documentation
Project.</para>
<programlisting> (defun local-sgml-mode-hook
(setq fill-column 70

17312
pt_BR.ISO8859-1/books/fdp-primer/pt_BR.po Normal file
View file

File diff suppressed because it is too large Load diff

100
pt_BR.ISO8859-1/books/fdp-primer/see-also/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,53 +28,38 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also">
<title>Veja também</title>
<title>See Also</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>
<para>This document is deliberately not an exhaustive discussion of
XML, the DTDs listed, and the FreeBSD Documentation Project. For
more information about these, you are encouraged to see the
following web sites.</para>
<sect1 xml:id="see-also-fdp">
<title>Projeto de documentação do FreeBSD</title>
<title>The FreeBSD Documentation Project</title>
<itemizedlist>
<listitem>
<para><link xlink:href="&url.base;/docproj/index.html">Páginas web do
Projeto de documentação do
FreeBSD</link></para>
<para><link xlink:href="&url.base;/docproj/index.html">The FreeBSD
Documentation Project web pages</link></para>
</listitem>
<listitem>
<para><link xlink:href="&url.books.handbook;/index.html">Manual do
FreeBSD</link></para>
<para><link xlink:href="&url.books.handbook;/index.html">The FreeBSD
Handbook</link></para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-sgml">
<title>SGML</title>
<sect1 xml:id="see-also-xml">
<title>XML</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.oasis-open.org/cover/">Página web
sobre SGML/XML,</link> referências detalhadas sobre
SGML</para>
</listitem>
<listitem>
<para><link xlink:href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">
Uma breve introdução ao SGML</link></para>
<para><link xlink:href="http://www.w3.org/XML/">W3C's XML page
SGML/XML web page</link></para>
</listitem>
</itemizedlist>
</sect1>
@ -84,13 +69,13 @@
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.w3.org/">Consórcio
<literal>World Wide Web</literal></link></para>
<para><link xlink:href="http://www.w3.org/">The World Wide Web
Consortium</link></para>
</listitem>
<listitem>
<para><link xlink:href="http://www.w3.org/TR/REC-html40/">As
especificações do HTML 4.0</link></para>
<para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML
4.0 specification</link></para>
</listitem>
</itemizedlist>
</sect1>
@ -100,36 +85,23 @@
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.oasis-open.org/docbook/">O
comitê técnico do DocBook</link>,
responsáveis pelo DTD DocBook.</para>
<para><link xlink:href="http://www.oasis-open.org/docbook/">The
DocBook Technical Committee</link>, maintainers of the
DocBook DTD</para>
</listitem>
<listitem>
<para><link xlink:href="http://www.docbook.org/">DocBook: O guia
definitivo</link>, documentação online para
o DTD DocBook.</para>
<para><link xlink:href="http://www.docbook.org/">DocBook: The
Definitive Guide</link>, the online documentation for the
DocBook DTD</para>
</listitem>
<listitem>
<para><link xlink:href="http://docbook.sourceforge.net/">Repositório
aberto de DocBook</link> contém folhas de estilo
DSSSL e outros recursos para pessoas que utilizam
DocBook.</para>
<para><link xlink:href="http://docbook.sourceforge.net/">The DocBook
Open Repository</link> contains DSSSL stylesheets and
other resources for people using DocBook</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="see-also-linuxdoc">
<title>Projeto de documentação do Linux</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://www.tldp.org/">Pagínas web
do projeto de documentação do Linux</link>
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

499
pt_BR.ISO8859-1/books/fdp-primer/structure/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,324 +28,285 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="structure">
<title>Documentation Directory Structure</title>
<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>
<para>Files and directories in the
<filename>doc/</filename> tree follow a
structure meant to:</para>
<orderedlist>
<listitem>
<para>Facilitar a automatização da
conversão de documentos para outros
formatos.</para>
<para>Make it easy to automate converting the document to other
formats.</para>
</listitem>
<listitem>
<para>Promover consistência entre diferentes formas de
organizar a documentação, facilitar a troca
entre diferentes documentos.</para>
<para>Promote consistency between the different documentation
organizations, to make it easier to switch between working on
different documents.</para>
</listitem>
<listitem>
<para>Facilitar a decisão de onde na árvore uma
nova documentação deveria ser colocada.</para>
<para>Make it easy to decide where in the tree new documentation
should be placed.</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>
<para>In addition, the documentation tree must accommodate
documents in many different languages and encodings. It is
important that the documentation tree structure does not enforce
any particular defaults or cultural preferences.</para>
<sect1 xml:id="structure-top">
<title>O Nível Superior, <filename>doc/</filename></title>
<title>The Top Level,
<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>
<para>There are two types of directory under
<filename>doc/</filename>, each with very
specific directory names and meanings.</para>
<segmentedlist>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Directory</entry>
<entry>Usage</entry>
</row>
</thead>
<segtitle>Diretório</segtitle>
<tbody>
<row>
<entry valign="top">
<filename>share</filename></entry>
<segtitle>Significado</segtitle>
<entry>Contains files that are not specific to the various
translations and encodings of the documentation.
Contains subdirectories to further categorize the
information. For example, the files that comprise the
&man.make.1; infrastructure are in
<filename>share/mk</filename>, while the additional
<acronym>XML</acronym> support files (such as the &os;
extended DocBook <acronym>DTD</acronym>) are in
<filename>share/xml</filename>.</entry>
</row>
<seglistitem>
<row>
<entry valign="top">
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
<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/xml</filename>.</seg>
</seglistitem>
<seglistitem>
<seg><filename>idioma.codificação/</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>
<entry>One directory exists for each available translation
and encoding of the documentation, for example
<filename>en_US.ISO8859-1/</filename>
and <filename>zh_TW.UTF-8/</filename>.
The names are long, but by fully specifying the language
and encoding we prevent any future headaches when a
translation team wants to provide documentation in the
same language but in more than one encoding. This also
avoids problems that might be caused by a future switch
to Unicode.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 xml:id="structure-locale">
<title>The
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
Directories</title>
<title>Os Diretórios de <filename>idioma.codificação</filename></title>
<para>These directories contain the documents themselves. The
documentation is split into up to three more categories at
this level, indicated by the different directory names.</para>
<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>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Directory</entry>
<entry>Usage</entry>
</row>
</thead>
<segmentedlist>
<tbody>
<row>
<entry valign="top">
<filename>articles</filename></entry>
<segtitle>Diretório</segtitle>
<entry>Documentation marked up as a DocBook
<tag>article</tag> (or equivalent). Reasonably
short, and broken up into sections. Normally only
available as one <acronym>XHTML</acronym> file.</entry>
</row>
<segtitle>Conteúdo</segtitle>
<row>
<entry valign="top"><filename>books</filename></entry>
<seglistitem>
<seg><filename>articles</filename></seg>
<entry>Documentation marked up as a DocBook
<tag>book</tag> (or equivalent). Book length,
and broken up into chapters. Normally available as both
one large <acronym>XHTML</acronym> file (for people with
fast connections, or who want to print it easily from a
browser) and as a collection of linked, smaller
files.</entry>
</row>
<seg>Documentação codificada como DocBook
<tag>article</tag> (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>
<row>
<entry valign="top">
<filename>man</filename></entry>
<seg>Documentação codificada como DocBook
<tag>book</tag> (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>
<entry>For translations of the system manual pages. This
directory will contain one or more <filename
role="directory">man<replaceable>N</replaceable></filename>
directories, corresponding to the sections that have
been translated.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<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>mann</filename>,
correspondendo as seções que foram
traduzidas.</seg>
</seglistitem>
</segmentedlist>
<para>Nem todo diretório
<filename>idioma.codificação</filename>
conterá todos estes diretórios. Isto depende de
quantos documentos já foram traduzidos pelo time de
tradução.</para>
<para>Not every <filename
role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
directory will have all of these subdirectories. It depends on
how much translation has been accomplished by that translation
team.</para>
</sect1>
<sect1 xml:id="structure-document">
<title>Informação Específica do
Documento</title>
<title>Document-Specific Information</title>
<para>Esta sessão contém observações
específicas sobre documentos particulares controlados pelo
FDP.</para>
<para>This section contains specific notes about particular
documents managed by the FDP.</para>
<sect2>
<title>O Handbook</title>
<sect2 xml:id="structure-document-handbook">
<title>The 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>The Handbook is written in DocBook <acronym>XML</acronym>
using the &os; DocBook extended <acronym>DTD</acronym>.</para>
<para>The Handbook is organized as a DocBook
<tag>book</tag>. The book is divided into
<tag>part</tag>s, each of which contains several
<tag>chapter</tag>s. <tag>chapter</tag>s are
further subdivided into sections (<tag>sect1</tag>)
and subsections (<tag>sect2</tag>,
<tag>sect3</tag>) and so on.</para>
<sect3 xml:id="structure-document-handbook-physical">
<title>Physical Organization</title>
<para>There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<para>O Handbook é organizado como um
<tag>book</tag> Docbook. Ele está dividido
em <tag>part</tag>es, e cada uma delas pode conter
diversos <tag>chapter</tag>s (Capítulos). Os
<tag>chapter</tag>s estão subdivididos
em seções (<tag>sect1</tag>) e
subseções (<tag>sect2</tag>,
<tag>sect3</tag>) 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>
<para>The Handbook's organization may change over time, and
this document may lag in detailing the organizational
changes. Post questions about Handbook organization to
the &a.doc;.</para>
</note>
<sect4>
<sect4 xml:id="structure-document-handbook-physical-Makefile">
<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>
<para>The <filename>Makefile</filename> defines some
variables that affect how the <acronym>XML</acronym>
source is converted to other formats, and lists the
various source files that make up the Handbook. It then
includes the standard <filename>doc.project.mk</filename>,
to bring in the rest of the code that handles converting
documents from one format to another.</para>
</sect4>
<sect4>
<sect4 xml:id="structure-document-handbook-physical-book-xml">
<title><filename>book.xml</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
<para>This is the top level document in the Handbook. It
contains the Handbook's <link
linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that
describe the Handbook's structure.</para>
<para><filename>book.xml</filename> uses <link
linkend="xml-primer-parameter-entities">parameter
entities</link> to load in the files with the
<filename>.ent</filename> extension. These files
(described later) then define <link
linkend="xml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
<para>O <filename>book.xml</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>directory/chapter.xml</filename></title>
<sect4
xml:id="structure-document-handbook-physical-chapters-xml">
<title><filename
role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
<para>Cada capítulo do Handbook é armazenado
em um arquivo chamado <filename>chapter.xml</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 <tag>chapter</tag>.</para>
<para>Por exemplo, se um dos arquivos de capítulos
contiver:</para>
<programlisting><![CDATA[
<chapter id="kernelconfig">
<para>Each chapter in the Handbook is stored in a file
called <filename>chapter.xml</filename> in a separate
directory from the other chapters. Each directory is
named after the value of the <literal>id</literal>
attribute on the <tag>chapter</tag>
element.</para>
<para>For example, if one of the chapter files
contains:</para>
<programlisting><tag class="starttag">chapter id="kernelconfig"</tag>
...
</chapter>]]></programlisting>
<tag class="endtag">chapter</tag></programlisting>
<para>Então ele será chamado de
<filename>chapter.xml</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.xml</filename>, e depois nomeados
a partir do valor do atributo <literal>id</literal>
presente no elemento <tag>chapter</tag> 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>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.xml</filename>, incluindo
<filename>basics/chapter.xml</filename>,
<filename>introduction/chapter.xml</filename>, e
<para>Then it will be called
<filename>chapter.xml</filename> in the
<filename>kernelconfig</filename> directory. In general,
the entire contents of the chapter are in this one
file.</para>
<para>When the <acronym>XHTML</acronym> version of the
Handbook is produced, this will yield
<filename>kernelconfig.html</filename>. This is because
of the <literal>id</literal> value, and is not related to
the name of the directory.</para>
<para>In earlier versions of the Handbook, the files were
stored in the same directory as
<filename>book.xml</filename>, and named after the value
of the <literal>id</literal> attribute on the file's
<tag>chapter</tag> element. Now, it is possible to
include images in each chapter. Images for each Handbook
chapter are stored within
<filename>share/images/books/handbook</filename>. The
localized version of these images should be placed in the
same directory as the <acronym>XML</acronym> sources for
each chapter. Namespace collisions are inevitable, and it
is easier to work with several directories with a few
files in them than it is to work with one directory that
has many files in it.</para>
<para>A brief look will show that there are many directories
with individual <filename>chapter.xml</filename> files,
including <filename>basics/chapter.xml</filename>,
<filename>introduction/chapter.xml</filename>, and
<filename>printing/chapter.xml</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>
<para>Do not name chapters or directories after
their ordering within the Handbook. This ordering can
change as the content within the Handbook is
reorganized. Reorganization should be possible without
renaming files, unless entire chapters are being
promoted or demoted within the hierarchy.</para>
</important>
<para>Cada arquivo <filename>chapter.xml</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>
<para>The <filename>chapter.xml</filename> files are not
complete <acronym>XML</acronym> documents that can be
built individually. They can only be built
as parts of the whole Handbook.</para>
</sect4>
</sect3>
</sect2>

113
pt_BR.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,74 +28,49 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets">
<title>* Folhas de Estilo</title>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="stylesheets">
<title>Style Sheets</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><acronym>XML</acronym> is concerned with content, and says
nothing about how that content should be presented to the reader
or rendered on paper. Multiple <emphasis>style sheet</emphasis>
languages have been developed to describe visual layout, including
Extensible Stylesheet Language Transformation
(<acronym>XSLT</acronym>), Document Style Semantics and
Specification Language (<acronym>DSSSL</acronym>), and Cascading
Style Sheets (<acronym>CSS</acronym>).</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 xml: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 <package>textproc/dsssl-docbook-modular</package>.
</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/xml/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>
<para>The <acronym>FDP</acronym> documents use
<acronym>XSLT</acronym> stylesheets to transform DocBook into
<acronym>XHTML</acronym>, and then <acronym>CSS</acronym>
formatting is applied to the <acronym>XHTML</acronym> pages.
Printable output is currently rendered with legacy
<acronym>DSSSL</acronym> stylesheets, but this will probably
change in the future.</para>
<sect1 xml:id="stylesheets-css">
<title>CSS</title>
<title><acronym>CSS</acronym></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>
<para>Cascading Style Sheets (<acronym>CSS</acronym>) are a
mechanism for attaching style information (font, weight, size,
color, and so forth) to elements in an <acronym>XHTML</acronym>
document without abusing <acronym>XHTML</acronym> to do
so.</para>
<sect2>
<title>Documentos DocBook </title>
<sect2 xml:id="stylesheets-css-documents">
<title>The DocBook Documents</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>
<para>The &os; <acronym>XSLT</acronym> and
<acronym>DSSSL</acronym> stylesheets refer to
<filename>docbook.css</filename>, which is expected to be
present in the same directory as the <acronym>XHTML</acronym>
files. The project-wide <acronym>CSS</acronym> file is copied
from <filename>doc/share/misc/docbook.css</filename> when
documents are converted to <acronym>XHTML</acronym>, and is
installed automatically.</para>
</sect2>
</sect1>
</chapter>

460
pt_BR.ISO8859-1/books/fdp-primer/the-website/chapter.xml
View file

@ -28,234 +28,258 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
<title>O Website</title>
<sect1 xml:id="the-website-prep">
<title>Preparação</title>
<para>Utilize um disco que tenha espaço livre suficiente.
Você irá precisar de 200&nbsp;MB a 500&nbsp;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>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="the-website">
<title>The Website</title>
<screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
</note>
<para>The &os; web site is part of the &os; documents. Files for
the web site are stored in the
<filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the
document tree directory, <filename>~/doc</filename> in this
example.</para>
<sect2 xml: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>cd /usr/ports/devel/subversion</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>Para obter os arquivos com o código fonte completo do
web site do &os;, execute:</para>
<screen>&prompt.root; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/ /usr/build</userinput></screen>
<tip>
<para>Se o comando <command>svn</command> não estiver sendo
executado pelo usuário <systemitem class="username">root</systemitem>,
certifique-se de que o diretório <filename>/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>/usr/build</filename>. Se vocé
utilizou um diretório alvo diferente, substitua o
<filename>/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 xml: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>/usr/build
</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>cd /usr/build</userinput></screen>
</step>
<step>
<para>A compilação do web site
deve ser iniciada de dentro do diretório <filename>en_US.ISO8859-1/htdocs</filename>
executando o comando &man.make.1; <buildtarget>all
</buildtarget>, para criar as páginas web:</para>
<screen>&prompt.root; <userinput>cd en_US.ISO8859-1/htdocs </userinput>
&prompt.root; <userinput>make all</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 xml: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>en_US.ISO8859-1/htdocs</filename>, volte
para dele.</para>
<screen>&prompt.root; <userinput>cd /usr/build/en_US.ISO8859-1/htdocs</userinput></screen>
</step>
<step>
<para>Execute o comando &man.make.1; <buildtarget>install
</buildtarget>, definindo a variável <varname>DESTDIR
</varname> para o nome do diretório no qual deseja
instalar os arquivos. Eles serão instalados no
<filename>$DESTDIR/data</filename> o qual
deve estar configurado para ser o diretório raiz do
seu servidor web.</para>
<screen>&prompt.root; <userinput>env DESTDIR=/usr/local/www make install</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>find /usr/local/www -ctime 3 -print0 | xargs -0 rm</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 xml:id="the-website-env">
<title>Variáveis de ambiente</title>
<title>Environment Variables</title>
<para>Several environment variables control which parts of the
web site are built or installed, and to which
directories.</para>
<tip>
<para>The web build system uses &man.make.1;, and considers
variables to be set when they have been defined, even if they
are empty. The examples here show the recommended ways of
defining and using these variables. Setting or defining these
variables with other values or methods might lead to
unexpected surprises.</para>
</tip>
<variablelist>
<varlistentry>
<term><varname>ENGLISH_ONLY</varname></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>make ENGLISH_ONLY=YES all install</userinput></screen>
<para>Se você quiser desabilitar a variável
<varname>ENGLISH_ONLY</varname> e compilar todas as
páginas, incluindo traduções, basta
definir a variável <varname>ENGLISH_ONLY</varname>
para um valor vazio:</para>
<screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>WEB_ONLY</varname></term>
<listitem>
<para>Se esta variável estiver definida e não
for vazia, apenas as páginas HTML do diretório
<filename>en_US.ISO8859-1/htdocs</filename>
serão compiladas e instaladas. Todos os demais
documentos do diretório <filename>en_US.ISO8859-1</filename> (Handbook, FAQ,
Tutorais, etc) serão ignorados. Por exemplo:</para>
<screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>WEB_LANG</varname></term>
<varlistentry xml:id="the-website-env-destdir">
<term><varname>DESTDIR</varname></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>
/usr/build</filename>.
Todos os demais idiomas serão ignorados. Por
exemplo:</para>
<para>DESTDIR specifies the path where the web site files
are to be installed.</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><varname>NOPORTSCVS</varname></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>/usr/ports
</filename> (ou do local definido na variável
<envar>PORTSBASE</envar>).</para>
<para>This variable is best set with &man.env.1; or the user
shell's method of setting environment variables,
<command>setenv</command> for &man.csh.1; or
<command>export</command> for &man.sh.1;.</para>
</listitem>
</varlistentry>
</variablelist>
<para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
<varname>ENGLISH_ONLY</varname> e <varname>NOPORTSCVS</varname>
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>
<variablelist>
<varlistentry xml:id="the-website-env-englishonly">
<term><varname>ENGLISH_ONLY</varname></term>
<listitem>
<para>Default: undefined. Build and include all
translations.</para>
<para><userinput>ENGLISH_ONLY=yes</userinput>: use only
the English documents and ignore all translations.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="the-website-env-webonly">
<term><varname>WEB_ONLY</varname></term>
<listitem>
<para>Default: undefined. Build both the web site
and all the books and articles.</para>
<para><userinput>WEB_ONLY=yes</userinput>: build or install
only <acronym>HTML</acronym> pages from the
<filename>en_US.ISO8859-1/htdocs</filename> directory.
Other directories and documents, including books and
articles, will be ignored.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="the-website-env-weblang">
<term><varname>WEB_LANG</varname></term>
<listitem>
<para>Default: undefined. Build and include all the
available languages on the web site.</para>
<para>Set to a space-separated list of languages to be
included in the build
or install. The formats are the same as the directory
names in the document root directory. For example, to
include the German and French documents:</para>
<screen><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
</listitem>
</varlistentry>
</variablelist>
<para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
and <varname>ENGLISH_ONLY</varname> are &man.make.1; variables
and can be set in <filename>/etc/make.conf</filename>,
<filename>Makefile.inc</filename>, as environment variables on
the command line, or in dot files.</para>
</sect1>
<sect1 xml:id="the-website-build">
<title>Building and Installing the Web Pages</title>
<para>Having obtained the documentation and web site source files,
the web site can be built.</para>
<para>An actual installation of the web site is run as the
<systemitem class="username">root</systemitem> user because the
permissions on the web server directory will not allow files to
be installed by an unprivileged user. For testing, it can be
useful to install the files as a normal user to a temporary
directory.</para>
<para>In these examples, the web site files are built by user
<systemitem class="username">jru</systemitem> in their home
directory, <filename>~/doc</filename>, with a full path of
<filename>/usr/home/jru/doc</filename>.</para>
<tip>
<para>The web site build uses the <filename>INDEX</filename>
from the Ports Collection and might fail if that file or
<filename>/usr/ports</filename> is not present. The simplest
approach is to install the <link
xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
Collection</link>.</para>
</tip>
<example xml:id="the-website-examples-build">
<title>Build the Full Web Site and All Documents</title>
<para>Build the web site and all documents. The resulting files
are left in the document tree:</para>
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
&prompt.user; <userinput>make all</userinput></screen>
</example>
<example xml:id="the-website-examples-buildinstall-englishonly">
<title>Build Only the Web Site in English</title>
<para>Build the web site only, in English, as user
<systemitem class="username">jru</systemitem>, and install
the resulting files into <filename>/tmp/www</filename> for
testing:</para>
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
&prompt.user; <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>
<para>Changes to static files can usually be tested by viewing
the modified files directly with a web browser. If the site
has been built as shown above, a modified main page can be
viewed with:</para>
<screen>&prompt.user; <userinput>firefox /tmp/www/data/index.html</userinput></screen>
<para>Modifications to dynamic files can be tested with a web
server running on the local system. After building the site
as shown above, this
<filename>/usr/local/etc/apache24/httpd.conf</filename> can be
used with <package>www/apache24</package>:</para>
<programlisting># httpd.conf for testing the FreeBSD website
Define TestRoot "/tmp/www/data"
# directory for configuration files
ServerRoot "/usr/local"
Listen 80
# minimum required modules
LoadModule authz_core_module libexec/apache24/mod_authz_core.so
LoadModule mime_module libexec/apache24/mod_mime.so
LoadModule unixd_module libexec/apache24/mod_unixd.so
LoadModule cgi_module libexec/apache24/mod_cgi.so
LoadModule dir_module libexec/apache24/mod_dir.so
# run the webserver as user and group
User www
Group www
ServerAdmin you@example.com
ServerName fbsdtest
# deny access to all files
&lt;Directory /&gt;
AllowOverride none
Require all denied
&lt;/Directory&gt;
# allow access to the website directory
DocumentRoot "${TestRoot}"
&lt;Directory "${TestRoot}"&gt;
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
&lt;/Directory&gt;
# prevent access to .htaccess and .htpasswd files
&lt;Files ".ht*"&gt;
Require all denied
&lt;/Files&gt;
ErrorLog "/var/log/httpd-error.log"
LogLevel warn
# set up the CGI script directory
&lt;Directory "${TestRoot}/cgi"&gt;
AllowOverride None
Options None
Require all granted
Options +ExecCGI
AddHandler cgi-script .cgi
&lt;/Directory&gt;
Include etc/apache24/Includes/*.conf</programlisting>
<para>Start the web server with</para>
<screen>&prompt.root; <userinput>service apache24 onestart</userinput></screen>
<para>The web site can be viewed at <link
xlink:href="http://localhost"/>. Be aware that many links
refer to the real &os; site by name, and those links will
still go to the external site instead of the local test
version. Fully testing the local site will require
temporarily setting <acronym>DNS</acronym> so
<literal>www.FreeBSD.org</literal> resolves to
<literal>localhost</literal> or the local
<acronym>IP</acronym> address.</para>
</example>
<example xml:id="the-website-examples-buildinstall">
<title>Build and Install the Web Site</title>
<para>Build the web site and all documents as user
<systemitem class="username">jru</systemitem>. Install the
resulting files as
<systemitem class="username">root</systemitem> into the
default directory,
<filename>/root/public_html</filename>:</para>
<screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.user; <userinput>make all</userinput>
&prompt.user; <userinput>su -</userinput>
Password:
&prompt.root; <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</example>
<para>The install process does not delete any old or outdated
files that existed previously in the same directory. If a new
copy of the site is built and installed every day, this command
will find and delete all files that have not been updated in
three days:</para>
<screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
</sect1>
</chapter>

336
pt_BR.ISO8859-1/books/fdp-primer/tools/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,213 +28,72 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
<title>Ferramentas</title>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="tools">
<title>Tools</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>Several software tools are used to manage the FreeBSD
documentation and render it to different output formats. Some of
these tools are required and must be installed before working
through the examples in the following chapters. Some are
optional, adding capabilities or making the job of creating
documentation less demanding.</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>
<sect1 xml:id="tools-required">
<title>Required Tools</title>
<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>
<para>Install
<package>textproc/docproj</package> from the
Ports Collection. This <emphasis>meta-port</emphasis> installs
all the applications required to do useful work with the &os;
documentation. Some further notes on particular components are
given below.</para>
<tip>
<title>Se possível use o <package>
textproc/docproj</package></title>
<sect2 xml:id="tools-required-dtd-entities">
<title><acronym>DTD</acronym>s and
<acronym>Entities</acronym></title>
<para>Você pode economizar bastante tempo se instalar o
<literal>port</literal> <package>textproc/docproj</package>. 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
<package>textproc/docproj-jadetex</package> ou o
<package>textproc/docproj-nojadetex</package>.
Estes <literal>ports</literal> secundários irão
definir a variável <varname>JADETEX</varname> 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 xml: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
<package>textproc/docproj</package>.</para>
<para>&os; documentation uses several Document Type Definitions
(<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym>
entities. These are all installed by the
<package>textproc/docproj</package>
port.</para>
<variablelist>
<varlistentry>
<term><application>Jade</application>
(<package>textproc/jade</package>)</term>
<term><acronym>XHTML</acronym> <acronym>DTD</acronym>
(<package>textproc/xhtml</package>)</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>
(<package>www/tidy</package>)</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>
(<package>www/links</package>)</term>
<listitem>
<para>Um navegador WWW em modo texto que também
converte arquivos HTML para texto puro.</para>
<para><acronym>XHTML</acronym> is the markup language of
choice for the World Wide Web, and is used throughout
the &os; web site.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>peps</application>
(<package>graphics/peps</package>)</term>
<term>DocBook <acronym>DTD</acronym>
(<package>textproc/docbook-xml</package>)</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>
<para>DocBook is designed for marking up technical
documentation. Most of the &os; documentation is
written in DocBook.</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
(<package>textproc/html</package>)</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
(<package>textproc/docbook</package>)
</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
(<package>textproc/iso8879</package>)
</term>
(<package>textproc/iso8879</package>)</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
(<package>textproc/dsssl-docbook-modular
</package>)</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>
<para>Character entities from the ISO 8879:1986 standard
used by many <acronym>DTD</acronym>s. Includes named
mathematical symbols, additional characters in the Latin
character set (accents, diacriticals, and so on), and
Greek symbols.</para>
</listitem>
</varlistentry>
</variablelist>
@ -242,88 +101,43 @@
</sect1>
<sect1 xml:id="tools-optional">
<title>Ferramentas Opcionais</title>
<title>Optional Tools</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>
<para>These applications are not required, but can make working on
the documentation easier or add capabilities.</para>
<sect2>
<sect2 xml:id="tools-optional-software">
<title>Software</title>
<variablelist>
<varlistentry>
<term><application>JadeTeX</application> e
<application>teTeX</application>
(<package>print/jadetex</package> e
<package>print/teTeX</package>)</term>
<term><application>Vim</application>
(<package>editors/vim</package>)</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>
<para>A popular editor for working with
<acronym>XML</acronym> and derived documents, like
DocBook <acronym>XML</acronym>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> ou
<term><application>Emacs</application> or
<application>XEmacs</application>
(<package>editors/emacs</package> ou
(<package>editors/emacs</package> or
<package>editors/xemacs</package>)</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>
<para>Both of these editors include a special mode for
editing documents marked up according to an
<acronym>XML</acronym> <acronym>DTD</acronym>. This
mode includes commands to reduce the amount of typing
needed, and help reduce the possibility of
errors.</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>

604
pt_BR.ISO8859-1/books/fdp-primer/translations/chapter.xml
View file

@ -6,20 +6,20 @@
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.
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.
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,
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)
@ -28,492 +28,423 @@
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations">
<title>Traduções</title>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="translations">
<title>Translations</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>This is the FAQ for people translating the FreeBSD
documentation (FAQ, Handbook, tutorials, manual pages, and others)
to different languages.</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&uuml;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>It is <emphasis>very</emphasis> heavily based on the
translation FAQ from the FreeBSD German Documentation Project,
originally written by Frank Gr&uuml;nder
<email>elwood@mc5sys.in-berlin.de</email> and translated back to
English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
<para>Este <literal>FAQ</literal> é mantido pela
&a.doceng;.</para>
<para>The FAQ is maintained by the &a.doceng;.</para>
<qandaset>
<qandaentry>
<question>
<para>Porque um <literal>FAQ</literal>?</para>
<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
mean?</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>
<para><phrase>i18n</phrase> means
<phrase>internationalization</phrase> and
<phrase>l10n</phrase> means <phrase>localization</phrase>.
They are just a convenient shorthand.</para>
<para><phrase>i18n</phrase> can be read as <quote>i</quote>
followed by 18 letters, followed by <quote>n</quote>.
Similarly, <phrase>l10n</phrase> is <quote>l</quote>
followed by 10 letters, followed by <quote>n</quote>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>O que significa <phrase>i18n</phrase> e <phrase>l10n</phrase>
</para>
<para>Is there a mailing list for translators?</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>
<para>Yes. Different translation groups have their own
mailing lists. The <link
xlink:href="https://www.freebsd.org/docproj/translations.html">list
of translation projects</link> has more information about
the mailing lists and web sites run by each translation
project. In addition there is
<email>freebsd-translators@freebsd.org</email> for general
translation discussion.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Existe uma lista de discussão para
tradutores?</para>
<para>Are more translators needed?</para>
</question>
<answer>
<para>Sim. Os diferentes grupos de tradução
possuem as suas próprias listas de discussão.
A <link xlink:href="http://www.FreeBSD.org/docproj/translations.html">
lista dos projetos de tradução</link> 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>
<para>Yes. The more people work on translation the faster it
gets done, and the faster changes to the English
documentation are mirrored in the translated
documents.</para>
<para>You do not have to be a professional translator to be
able to help.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>São necessários mais tradutores?</para>
<para>What languages do I need to know?</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>
<para>Ideally, you will have a good knowledge of written
English, and obviously you will need to be fluent in the
language you are translating to.</para>
<para>English is not strictly necessary. For example, you
could do a Hungarian translation of the FAQ from the Spanish
translation.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Quais idiomas eu preciso conhecer?</para>
<para>What software do I need to know?</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>It is strongly recommended that you maintain a local
copy of the FreeBSD Subversion repository (at least the
documentation part). This can be done by running:</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>
<screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>
<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>svn checkout svn://svn.FreeBSD.org/doc/head/ head</userinput></screen>
<para><link
xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>
is a public <literal>SVN</literal> server. Verify the
server certificate from the list of <link
xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
mirror sites</link>.</para>
<note>
<para>Você irá precisar ter o <package>devel/subversion</package> instalado.</para>
<para>This will require the
<package>devel/subversion</package> package to be
installed.</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>You should be comfortable using
<application>svn</application>. This will allow you to see
what has changed between different versions of the files
that make up the documentation.</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.xml
</filename>, execute:</para>
<para>For example, to view the differences between revisions
<literal>r33733</literal> and <literal>r33734</literal> of
<filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
run:</para>
<screen>&prompt.user; <userinput>svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
<screen>&prompt.user; <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
<para>Please see the complete explanation of using
<application>Subversion</application> in &os; in the <link
xlink:href="&url.books.handbook;/svn.html">&os;
Handbook</link>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Como eu faço para descobrir se já existem
outras pessoas traduzindo documentos para o meu
idioma?</para>
<para>How do I find out who else might be translating to the
same language?</para>
</question>
<answer>
<para><link xlink:href="http://www.FreeBSD.org/docproj/translations.html">A
página do Projeto de Tradução da
Documentação</link> 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>The <link
xlink:href="https://www.FreeBSD.org/docproj/translations.html">Documentation
Project translations page</link> lists the translation
efforts that are currently known about. If others are
already working on translating documentation to your
language, please do not duplicate their efforts. Instead,
contact them to see how you can help.</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>
<para>If no one is listed on that page as translating for your
language, then send a message to the &a.doc; in case someone
else is thinking of doing a translation, but has not
announced it yet.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Ninguém mais está traduzindo para o meu
idioma. O que eu faço?</para>
<para>No one else is translating to my language. What do I
do?</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>Congratulations, you have just started the
<quote>FreeBSD <replaceable>your-language-here</replaceable>
Documentation Translation Project</quote>. Welcome
aboard.</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>First, decide whether or not you have got the time to
spare. Since you are the only person working on your
language at the moment it is going to be your responsibility
to publicize your work and coordinate any volunteers that
might want to help you.</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>Write an email to the Documentation Project mailing
list, announcing that you are going to translate the
documentation, so the Documentation Project translations
page can be maintained.</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>
<para>If there is already someone in your country providing
FreeBSD mirroring services you should contact them and ask
if you can have some webspace for your project, and possibly
an email address or mailing list services.</para>
<para>Then pick a document and start translating. It is best
to start with something fairly small&mdash;either the FAQ,
or one of the tutorials.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Eu já tenho alguns documentos traduzidos, para
onde eu devo enviá-los?</para>
<para>I have translated some documentation, where do I send
it?</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>That depends. If you are already working with a
translation team (such as the Japanese team, or the German
team) then they will have their own procedures for handling
submitted documentation, and these will be outlined on their
web pages.</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>
<para>If you are the only person working on a particular
language (or you are responsible for a translation project
and want to submit your changes back to the FreeBSD project)
then you should send your translation to the FreeBSD project
(see the next question).</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>I am the only person working on translating to this
language, how do I submit my translation?</para>
<para>ou</para>
<para>or</para>
<para>Nós somos uma equipe de tradução, e
queremos submeter os documentos que nossos membros traduziram
para nós.</para>
<para>We are a translation team, and want to submit
documentation that our members have translated for
us.</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>First, make sure your translation is organized properly.
This means that it should drop into the existing
documentation tree and build straight away.</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>Currently, the FreeBSD documentation is stored in a top
level directory called <filename>head/</filename>.
Directories below this are named according to the language
code they are written in, as defined in ISO639
(<filename>/usr/share/misc/iso639</filename> on a version of
FreeBSD newer than 20th January 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>If your language can be encoded in different ways (for
example, Chinese) then there should be directories below
this, one for each encoding format you have provided.</para>
<para>Finalmente você deve ter diretórios para
cada original.</para>
<para>Finally, you should have directories for each
document.</para>
<para>Por exemplo, em uma hipotética
tradução para o Sueco ficaria assim:</para>
<para>For example, a hypothetical Swedish translation might
look like:</para>
<programlisting>
head/
<programlisting>head/
sv_SE.ISO8859-1/
Makefile
htdocs/
docproj
Makefile
htdocs/
docproj/
books/
faq/
Makefile
book.xml</programlisting>
<para><literal>sv_SE.ISO8859-1</literal> é o nome da
tradução, na forma
<filename>lang.encoding</filename>.
Repare nos dois Makefiles que serão usados para
construir a documentação.</para>
<para><literal>sv_SE.ISO8859-1</literal> is the name of the
translation, in
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
form. Note the two Makefiles, which will be used to build
the documentation.</para>
<para>Use &man.tar.1; e &man.gzip.1; para compactar sua
documentação, e envie para o projeto.</para>
<para>Use &man.tar.1; and &man.gzip.1; to compress up your
documentation, and send it to the project.</para>
<screen>&prompt.user; <userinput>cd doc</userinput>
<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>Put <filename>swedish-docs.tar.gz</filename> somewhere.
If you do not have access to your own webspace (perhaps your
ISP does not let you have any) then you can email
&a.doceng;, and arrange to email the files when it is
convenient.</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>Either way, you should use Bugzilla to submit a
report indicating that you have submitted the documentation.
It would be very helpful if you could get other people to
look over your translation and double check it first, since
it is unlikely that the person committing it will be fluent
in the language.</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>
<para>Someone (probably the Documentation Project Manager,
currently &a.doceng;) will then take your translation and
confirm that it builds. In particular, the following things
will be looked at:</para>
<orderedlist>
<listitem>
<para>Todos os seus arquivos usam strings RCS
(tais como "ID")?</para>
<para>Do all your files use RCS strings (such as
"ID")?</para>
</listitem>
<listitem>
<para>O <command>make all</command> no diretório
<filename>sv_SE.ISO8859-1</filename> funciona
corretamente?</para>
<para>Does <command>make all</command> in the
<filename>sv_SE.ISO8859-1</filename> directory work
correctly?</para>
</listitem>
<listitem>
<para>O <command>make install</command>
funciona corretamente?</para>
<para>Does <command>make install</command> work
correctly?</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>
<para>If there are any problems then whoever is looking at the
submission will get back to you to work them out.</para>
<para>If there are no problems your translation will be
committed as soon as possible.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Posso incluir uma língua ou um texto específico
do país em minha tradução?</para>
<para>Can I include language or country specific text in my
translation?</para>
</question>
<answer>
<para>Nós preferimos que você não
faça isso.</para>
<para>We would prefer that you did not.</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>For example, suppose that you are translating the
Handbook to Korean, and want to include a section about
retailers in Korea in your 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 &hellip;). É
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>There is no real reason why that information should not
be in the English (or German, or Spanish, or Japanese, or
&hellip;) versions as well. It is feasible that an English
speaker in Korea might try to pick up a copy of FreeBSD
whilst over there. It also helps increase FreeBSD's
perceived presence around the globe, which is not a bad
thing.</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>If you have country specific information, please submit
it as a change to the English Handbook (using
Bugzilla) and then translate the change back to your
language in the translated Handbook.</para>
<para>Obrigado.</para>
<para>Thanks.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Como os caracteres específicos do idioma
podem ser incluídos?</para>
<para>How should language specific characters be
included?</para>
</question>
<answer>
<para>Caracteres não-ASCII devem ser
incluídos na documentação usando
entidades SGML.</para>
<para>Non-ASCII characters in the documentation should be
included using SGML entities.</para>
<para>Resumidamente, eles são um ``e'' comercial
(&amp;), o nome da entidade e um
ponto-e-vírgula (;).</para>
<para>Briefly, these look like an ampersand (&amp;), the name
of the entity, and a semi-colon (;).</para>
<para>Os nomes de entidades estão definidos no ISO8879,
que está na árvore do ports como <package>textproc/iso8879</package>.</para>
<para>The entity names are defined in ISO8879, which is in the
ports tree as <package>textproc/iso8879</package>.</para>
<para>Alguns exemplos Incluem</para>
<para>A few examples include:</para>
<segmentedlist>
<segtitle>Entidade</segtitle>
<segtitle>Entity</segtitle>
<segtitle>Aparência</segtitle>
<segtitle>Appearance</segtitle>
<segtitle>Descrição</segtitle>
<segtitle>Description</segtitle>
<seglistitem>
<seg>&amp;eacute;</seg>
<seg>é</seg>
<seg><quote>e</quote> minúsculo com acento
agudo</seg>
<seg>&eacute;</seg>
<seg>Small <quote>e</quote> with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&amp;Eacute;</seg>
<seg>É</seg>
<seg><quote>E</quote> maiúsculo com acento
agudo</seg>
<seg>&Eacute;</seg>
<seg>Large <quote>E</quote> with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&amp;uuml;</seg>
<seg>&uuml;</seg>
<seg><quote>u</quote> minúsculo com trema</seg>
<seg>Small <quote>u</quote> with an umlaut</seg>
</seglistitem>
</segmentedlist>
<para>Depois que você instalar o pacote iso8879,
os arquivos em
<filename>/usr/local/share/xml/iso8879</filename>
conterão a lista completa.</para>
<para>After you have installed the iso8879 port, the files in
<filename>/usr/local/share/xml/iso8879</filename> contain
the complete list.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Dirigindo-se ao leitor</para>
<para>Addressing the reader</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>In the English documents, the reader is addressed as
<quote>you</quote>, there is no formal/informal distinction
as there is in some languages.</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>
<para>If you are translating to a language which does
distinguish, use whichever form is typically used in other
technical documentation in your language. If in doubt, use
a mildly polite form.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Eu preciso colocar alguma informação
adicional nas minhas traduções?</para>
<para>Do I need to include any additional information in my
translations?</para>
</question>
<answer>
<para>Sim.</para>
<para>Yes.</para>
<para>O cabeçalho da versão em Inglês
de cada documento será parecido com o texto exibido
abaixo:</para>
<para>The header of the English version of each document will
look something like this:</para>
<programlisting>&lt;!--
The FreeBSD Documentation Project
@ -521,32 +452,31 @@ head/
&dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &dollar;
--&gt;</programlisting>
<para>A forma exata pode mudar, mas ela sempre
incluirá a linha &dollar;FreeBSD&dollar; e a frase
<literal>The FreeBSD Documentation Project</literal>. Note
que o &dollar;FreeBSD é inserido pelo svn, portanto
ele deve estar vazio (apenas
<literal>&dollar;FreeBSD&dollar;</literal>) para novos
documentos.</para>
<para>The exact boilerplate may change, but it will always
include a &dollar;FreeBSD&dollar; line and the phrase
<literal>The FreeBSD Documentation Project</literal>.
Note that the &dollar;FreeBSD part is expanded automatically
by Subversion, so it should be empty (just
<literal>&dollar;FreeBSD&dollar;</literal>) for new
files.</para>
<para>O seu documento traduzido deve incluir sua
própria linha &dollar;FreeBSD&dollar;, e você deve mudar
a linha <literal>FreeBSD Documentation Project</literal> para
<literal>The FreeBSD language
Documentation Project</literal>.</para>
<para>Your translated documents should include their own
&dollar;FreeBSD&dollar; line, and change the
<literal>FreeBSD Documentation Project</literal> line to
<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>
<para>In addition, you should add a third line which indicates
which revision of the English text this is based on.</para>
<para>So, the Spanish version of this file might start:</para>
<programlisting>&lt;!--
The FreeBSD Spanish Documentation Project
&dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
Original revision: r38674
--&gt;</programlisting>
&dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
Original revision: r38674
--&gt;</programlisting>
</answer>
</qandaentry>
</qandaset>

184
pt_BR.ISO8859-1/books/fdp-primer/working-copy/chapter.xml Normal file
View file

@ -0,0 +1,184 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 2013 Warren Block
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHORS OR CONTRIBUTORS 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 SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="working-copy">
<title>The Working Copy</title>
<para>The <emphasis>working copy</emphasis> is a copy of the &os;
repository documentation tree downloaded onto the local computer.
Changes are made to the local working copy, tested, and then
submitted as patches to be committed to the main
repository.</para>
<para>A full copy of the documentation tree can occupy 700 megabytes
of disk space. Allow for a full gigabyte of space to have room
for temporary files and test versions of various output
formats.</para>
<para><link
xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link>
is used to manage the &os; documentation files. It is obtained by
installing the <application>Subversion</application>
package:</para>
<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
<sect1 xml:id="working-copy-doc-and-src">
<title>Documentation and Manual Pages</title>
<para>&os; documentation is not just books and articles. Manual
pages for all the commands and configuration files are also part
of the documentation, and part of the <acronym>FDP</acronym>'s
territory. Two repositories are involved:
<literal>doc</literal> for the books and articles, and
<literal>base</literal> for the operating system and manual
pages. To edit manual pages, the <literal>base</literal>
repository must be checked out separately.</para>
<para>Repositories may contain multiple versions of documentation
and source code. New modifications are almost always made only
to the latest version, called <literal>head</literal>.</para>
</sect1>
<sect1 xml:id="working-copy-choosing-directory">
<title>Choosing a Directory</title>
<para>&os; documentation is traditionally stored in
<filename>/usr/doc/</filename>, and system
source code with manual pages in
<filename>/usr/src/</filename>. These
directory trees are relocatable, and users may want to put the
working copies in other locations to avoid interfering with
existing information in the main directories. The examples
that follow use <filename>~/doc</filename>
and <filename>~/src</filename>, both
subdirectories of the user's home directory.</para>
</sect1>
<sect1 xml:id="working-copy-checking-out">
<title>Checking Out a Copy</title>
<para>A download of a working copy from the repository is called
a <emphasis>checkout</emphasis>, and done with
<command>svn checkout</command>. This example checks out a
copy of the latest version (<literal>head</literal>) of
the main documentation tree:</para>
<screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
<para>A checkout of the source code to work on manual pages is
very similar:</para>
<screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-updating">
<title>Updating a Working Copy</title>
<para>The documents and files in the &os; repository change daily.
People modify files and commit changes frequently. Even a short
time after an initial checkout, there will already be
differences between the local working copy and the main &os;
repository. To update the local version with the changes that
have been made to the main repository, use
<command>svn update</command> on the directory containing the
local working copy:</para>
<screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
<para>Get in the protective habit of using
<command>svn update</command> before editing document files.
Someone else may have edited that file very recently, and the
local working copy will not include the latest changes until it
has been updated. Editing the newest version of a file is much
easier than trying to combine an older, edited local file with
the newer version from the repository.</para>
</sect1>
<sect1 xml:id="working-copy-revert">
<title>Reverting Changes</title>
<para>Sometimes it turns out that changes were
not necessary after all, or the writer just wants to start over.
Files can be <quote>reset</quote> to their unchanged form with
<command>svn revert</command>. For example, to erase the edits
made to <filename>chapter.xml</filename> and reset it to
unmodified form:</para>
<screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen>
</sect1>
<sect1 xml:id="working-copy-making-diff">
<title>Making a Diff</title>
<para>After edits to a file or group of files are completed, the
differences between the local working copy and the version on
the &os; repository must be collected into a single file for
submission. These <emphasis>diff</emphasis> files are produced
by redirecting the output of <command>svn diff</command> into a
file:</para>
<screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
&prompt.user; <userinput>svn diff &gt; <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
<para>Give the file a meaningful name that identifies the
contents. The example above is for spelling fixes to the whole
documentation tree.</para>
<para>If the diff file is to be submitted with the web
<quote><link
xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit
a &os; problem report</link></quote> interface, add a
<filename>.txt</filename> extension to give the earnest and
simple-minded web form a clue that the contents are plain
text.</para>
<para>Be careful: <command>svn diff</command> includes all changes
made in the current directory and any subdirectories. If there
are files in the working copy with edits that are not ready to
be submitted yet, provide a list of only the files that are to
be included:</para>
<screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> &gt; <replaceable>disks-printers.diff</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-subversion-references">
<title><application>Subversion</application> References</title>
<para>These examples show very basic usage of
<application>Subversion</application>. More detail is available
in the <link
xlink:href="http://svnbook.red-bean.com/">Subversion
Book</link> and the <link
xlink:href="http://subversion.apache.org/docs/">Subversion
documentation</link>.</para>
</sect1>
</chapter>

932
pt_BR.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
View file

File diff suppressed because it is too large Load diff

604
pt_BR.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml Normal file
View file

@ -0,0 +1,604 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="xhtml-markup">
<title><acronym>XHTML</acronym> Markup</title>
<sect1 xml:id="xhtml-markup-introduction">
<title>Introduction</title>
<para>This chapter describes usage of the <acronym>XHTML</acronym>
markup language used for the &os; web site.</para>
<para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
version of the HyperText Markup Language, the markup language of
choice on the World Wide Web. More information can be found at
<uri
xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
<para><acronym>XHTML</acronym> is used to mark up pages on the
&os; web site. It is usually not used to mark up other
documentation, since DocBook offers a far richer set of elements
from which to choose. Consequently, <acronym>XHTML</acronym>
pages will normally only be encountered when writing for the web
site.</para>
<para><acronym>HTML</acronym> has gone through a number of
versions. The <acronym>XML</acronym>-compliant version
described here is called <acronym>XHTML</acronym>. The latest
widespread version is <acronym>XHTML</acronym> 1.0, available in
both <emphasis>strict</emphasis> and
<emphasis>transitional</emphasis> variants.</para>
<para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
available from the Ports Collection in
<package>textproc/xhtml</package>. They are automatically
installed by the <package>textproc/docproj</package>
port.</para>
<note>
<para>This is <emphasis>not</emphasis> an exhaustive list of
elements, since that would just repeat the documentation for
<acronym>XHTML</acronym>. The aim is to list those elements
most commonly used. Please post questions about elements or
uses not covered here to the &a.doc;.</para>
</note>
<note>
<title>Inline Versus Block</title>
<para>In the remainder of this document, when describing
elements, <emphasis>inline</emphasis> means that the element
can occur within a block element, and does not cause a line
break. A <emphasis>block</emphasis> element, by comparison,
will cause a line break (and other processing) when it is
encountered.</para>
</note>
</sect1>
<sect1 xml:id="xhtml-markup-fpi">
<title>Formal Public Identifier (<acronym>FPI</acronym>)</title>
<para>There are a number of <acronym>XHTML</acronym>
<acronym>FPI</acronym>s, depending upon the version, or
<emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
a document conforms. Most <acronym>XHTML</acronym> documents on
the &os; web site comply with the transitional version of
<acronym>XHTML</acronym> 1.0.</para>
<programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
</sect1>
<sect1 xml:id="xhtml-markup-sectional-elements">
<title>Sectional Elements</title>
<para>An <acronym>XHTML</acronym> document is normally split into
two sections. The first section, called the
<emphasis>head</emphasis>, contains meta-information about the
document, such as its title, the name of the author, the parent
document, and so on. The second section, the
<emphasis>body</emphasis>, contains content that will be
displayed to the user.</para>
<para>These sections are indicated with <tag>head</tag>
and <tag>body</tag> elements respectively. These
elements are contained within the top-level
<tag>html</tag> element.</para>
<example>
<title>Normal <acronym>XHTML</acronym> Document
Structure</title>
<programlisting><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
<tag class="starttag">head</tag>
<tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
<tag class="endtag">head</tag>
<tag class="starttag">body</tag>
&hellip;
<tag class="endtag">body</tag>
<tag class="endtag">html</tag></programlisting>
</example>
</sect1>
<sect1 xml:id="xhtml-markup-block-elements">
<title>Block Elements</title>
<sect2 xml:id="xhtml-markup-block-elements-headings">
<title>Headings</title>
<para><acronym>XHTML</acronym> has tags to denote headings in
the document at up to six different levels.</para>
<para>The largest and most prominent heading is
<tag>h1</tag>, then <tag>h2</tag>,
continuing down to <tag>h6</tag>.</para>
<para>The element's content is the text of the heading.</para>
<example>
<title><tag>h1</tag>, <tag>h2</tag>,
and Other Header Tags</title>
<para>Usage:</para>
<programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>
&lt;!-- Document introduction goes here --&gt;
<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>
&lt;!-- Content for the first section goes here --&gt;
<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag>
&lt;!-- Content for the first sub-section goes here --&gt;
<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag>
&lt;!-- Content for the second section goes here --&gt;</programlisting>
</example>
<para>Generally, an <acronym>XHTML</acronym> page should have
one first level heading (<tag>h1</tag>). This can
contain many second level headings (<tag>h2</tag>),
which can in turn contain many third level headings. Do not
leave gaps in the numbering.</para>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-paragraphs">
<title>Paragraphs</title>
<para><acronym>XHTML</acronym> supports a single paragraph
element, <tag>p</tag>.</para>
<example>
<title><tag>p</tag> Example</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>This is a paragraph. It can contain just about any
other element.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-block-quotations">
<title>Block Quotations</title>
<para>A block quotation is an extended quotation from another
document that will appear in a separate paragraph.</para>
<example>
<title><tag>blockquote</tag> Example</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>
<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the general
Welfare, and secure the Blessings of Liberty to ourselves and our
Posterity, do ordain and establish this Constitution for the
United States of America.<tag class="endtag">blockquote</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-lists">
<title>Lists</title>
<para><acronym>XHTML</acronym> can present the user with three
types of lists: ordered, unordered, and definition.</para>
<para>Entries in an ordered list will be numbered, while entries
in an unordered list will be preceded by bullet points.
Definition lists have two sections for each entry. The first
section is the term being defined, and the second section is
the definition.</para>
<para>Ordered lists are indicated by the <tag>ol</tag>
element, unordered lists by the <tag>ul</tag>
element, and definition lists by the <tag>dl</tag>
element.</para>
<para>Ordered and unordered lists contain listitems, indicated
by the <tag>li</tag> element. A listitem can
contain textual content, or it may be further wrapped in one
or more <tag>p</tag> elements.</para>
<para>Definition lists contain definition terms
(<tag>dt</tag>) and definition descriptions
(<tag>dd</tag>). A definition term can only contain
inline elements. A definition description can contain other
block elements.</para>
<example>
<title><tag>ul</tag> and
<tag>ol</tag> Example</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>An unordered list. Listitems will probably be
preceded by bullets.<tag class="endtag">p</tag>
<tag class="starttag">ul</tag>
<tag class="starttag">li</tag>First item<tag class="endtag">li</tag>
<tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>
<tag class="starttag">li</tag>Third item<tag class="endtag">li</tag>
<tag class="endtag">ul</tag>
<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.<tag class="endtag">p</tag>
<tag class="starttag">ol</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third
item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
<tag class="endtag">ol</tag></programlisting>
</example>
<example>
<title>Definition Lists with <tag>dl</tag></title>
<para>Usage:</para>
<programlisting><tag class="starttag">dl</tag>
<tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>
<tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>
<tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
<tag class="endtag">dl</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
<title>Pre-formatted Text</title>
<para>Pre-formatted text is shown to the user exactly as it is
in the file. Text is shown in a fixed font. Multiple spaces
and line breaks are shown exactly as they are in the
file.</para>
<para>Wrap pre-formatted text in the <tag>pre</tag>
element.</para>
<example>
<title><tag>pre</tag> Example</title>
<para>For example, the <tag>pre</tag> tags could be
used to mark up an email message:</para>
<programlisting><tag class="starttag">pre</tag> 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
&amp;lt;URL:https://people.FreeBSD.org/~nik/primer/index.html&amp;gt;
Comments appreciated.
N<tag class="endtag">pre</tag></programlisting>
<para>Keep in mind that <literal>&lt;</literal> and
<literal>&amp;</literal> still are recognized as special
characters in pre-formatted text. This is why the example
shown had to use <literal>&amp;lt;</literal> instead of
<literal>&lt;</literal>. For consistency,
<literal>&amp;gt;</literal> was used in place of
<literal>&gt;</literal>, too. Watch out for the special
characters that may appear in text copied from a plain-text
source, like an email message or program code.</para>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-block-elements-tables">
<title>Tables</title>
<para>Mark up tabular information using the
<tag>table</tag> element. A table consists of one or
more table rows (<tag>tr</tag>), each containing one
or more cells of table data (<tag>td</tag>). Each
cell can contain other block elements, such as paragraphs or
lists. It can also contain another table (this nesting can
repeat indefinitely). If the cell only contains one paragraph
then the <tag>p</tag>element is not needed.</para>
<example>
<title>Simple Use of <tag>table</tag></title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<para>A cell can span multiple rows and columns by adding the
<tag class="attribute">rowspan</tag> or
<tag class="attribute">colspan</tag> attributes with
values for the number of rows or columns to be spanned.</para>
<example>
<title>Using
<tag class="attribute">rowspan</tag></title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to
it on the right.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<example>
<title>Using
<tag class="attribute">colspan</tag></title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
<example>
<title>Using <tag class="attribute">rowspan</tag> and
<tag class="attribute">colspan</tag>
Together</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.<tag class="endtag">p</tag>
<tag class="starttag">table</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
&lt;!-- Because the large cell on the left merges into
this row, the first &lt;td&gt; will occur on its
right --&gt;
<tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="starttag">tr</tag>
<tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag>
<tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
<tag class="endtag">tr</tag>
<tag class="endtag">table</tag></programlisting>
</example>
</sect2>
</sect1>
<sect1 xml:id="xhtml-markup-inline-elements">
<title>In-line Elements</title>
<sect2
xml:id="xhtml-markup-inline-elements-emphasizing-information">
<title>Emphasizing Information</title>
<para>Two levels of emphasis are available in
<acronym>XHTML</acronym>, <tag>em</tag> and
<tag>strong</tag>. <tag>em</tag> is for a
normal level of emphasis and <tag>strong</tag>
indicates stronger emphasis.</para>
<para><tag>em</tag> is typically rendered in italic
and <tag>strong</tag> is rendered in bold. This is
not always the case, and should not be relied upon. According
to best practices, web pages only hold structural and
semantical information, and stylesheets are later applied to
them. Think of semantics, not formatting, when using these
tags.</para>
<example>
<title><tag>em</tag> and
<tag>strong</tag> Example</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while
<tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
<title>Indicating Fixed-Pitch Text</title>
<para>Content that should be rendered in a fixed pitch
(typewriter) typeface is tagged with <tag>tt</tag>
(for <quote>teletype</quote>).</para>
<example>
<title><tag>tt</tag> Example</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>Many system settings are stored in
<tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>
</sect2>
<sect2 xml:id="xhtml-markup-inline-elements-links">
<title>Links</title>
<note>
<para>Links are also inline elements.</para>
</note>
<sect3 xml:id="xhtml-markup-inline-elements-linking">
<title>Linking to Other Documents on the Web</title>
<para>A link points to the <acronym>URL</acronym> of a
document on the web. The link is indicated with
<tag>a</tag>, and the
<tag class="attribute">href</tag> attribute contains
the <acronym>URL</acronym> of the target document. The
content of the element becomes the link, indicated to the
user by showing it in a different color or with an
underline.</para>
<example>
<title>Using
<tag class="starttag">a href="..."</tag></title>
<para>Usage:</para>
<programlisting><tag class="starttag">p</tag>More information is available at the
<tag class="starttag">a href="http://www.&amp;os;.org/"</tag>&amp;os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para>This link always takes the user to the top of the linked
document.</para>
</sect3>
<sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
<title>Linking to Specific Parts of Documents</title>
<para>To link to a specific point within a document, that
document must include an <emphasis>anchor</emphasis> at the
desired point. Anchors are included by setting the
<tag class="attribute">id</tag> attribute of an
element to a name. This example creates an anchor by
setting the <tag class="attribute">id</tag>
attribute of a <tag class="element">p</tag>
element.</para>
<example>
<title>Creating an Anchor</title>
<para>Usage:</para>
<programlisting><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced
in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para>Links to anchors are similar to plain links, but include
a <literal>#</literal> symbol and the anchor's
<acronym>ID</acronym> at the end of the
<acronym>URL</acronym>.</para>
<example>
<title>Linking to a Named Part of a Different
Document</title>
<para>The <literal>samplepara</literal> example is part of a
document called <filename>foo.html</filename>. A link to
that specific paragraph in the document is constructed in
this example.</para>
<programlisting><tag class="starttag">p</tag>More information can be found in the
<tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of
<tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
</example>
<para>To link to a named anchor within the same document, omit
the document's <acronym>URL</acronym>, and just use the
<literal>#</literal> symbol followed by the name of the
anchor.</para>
<example>
<title>Linking to a Named Part of the Same Document</title>
<para>The <literal>samplepara</literal> example
resides in this document. To link to it:</para>
<programlisting><tag class="starttag">p</tag>More information can be found in the
<tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this
document.<tag class="endtag">p</tag></programlisting>
</example>
</sect3>
</sect2>
</sect1>
</chapter>

1423
pt_BR.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Normal file
View file

File diff suppressed because it is too large Load diff