The translation is temporarily closed for contributions due to maintenance, please come back later.
Context English Portuguese (Brazil) State
FreeBSD 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. A documentação do FreeBSD é tradicionalmente armazenada em <filename>/usr/doc/</filename>, e o código fonte do sistema com páginas de manual em <filename>/usr/src/</filename>. Essas árvores são realocáveis ​​e os usuários podem armazenar as cópias de trabalho em outros locais para evitar interferir nas informações existentes nos diretórios principais. Os exemplos a seguir utilizam <filename>~/doc</filename> e <filename>~/src</filename>, ambos subdiretórios do diretório pessoal do usuário.
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. Existe um diretório para cada tradução e codificação disponível da documentação, por exemplo, <filename>en_US.ISO8859-1/</filename> e <filename>zh_TW.UTF-8/</filename>. Os nomes são longos, mas ao especificar totalmente o idioma e a codificação, evitamos dores de cabeça futuras quando uma equipe de tradução desejar fornecer documentação no mesmo idioma, mas em mais de uma codificação. Isso também evita problemas que podem ser causados ​​por uma futura mudança para Unicode.
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. O <filename>Makefile</filename> define algumas variáveis ​​que afetam como o fonte <acronym>XML</acronym> é convertido em diversos formatos e lista os vários arquivos fontes que compõem o Handbook. Em seguida, ele inclui o <filename>doc.project.mk</filename> padrão, para inserir o restante do código que manipula a conversão de documentos de um formato para outro.
<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. <filename>book.xml</filename> utiliza <link linkend="xml-primer-parameter-entities">entidades de parâmetro</link> para carregar os arquivos com a extensão <filename>.ent</filename>. Esses arquivos (descritos posteriormente) e então definem as <link linkend="xml-primer-general-entities">entidades gerais</link> que são utilizadas ​​no restante do Handbook.
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. Nas versões anteriores do Handbook, os arquivos eram armazenados no mesmo diretório que <filename>book.xml</filename> e nomeados após o valor do atributo <literal>id</literal> no elemento <tag>chapter</tag>. Agora, é possível incluir imagens em cada capítulo. Imagens para cada capítulo do Handbook são armazenadas em <filename>share/images/books/handbook</filename>. As imagens devem ser colocadas no mesmo diretório que os fontes <acronym>XML</acronym> para cada capítulo. As colisões de Namespace são inevitáveis ​​e é mais fácil trabalhar com vários diretórios que contenham alguns arquivos, do que trabalhar com um único diretório que contenham muitos arquivos.
The first four non-empty lines define the <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables <varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname>, and <varname>DOC_PREFIX</varname>. As quatro primeiras linhas não vazias definem as variáveis ​​do <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <varname>SUBDIR</varname>, <varname>COMPAT_SYMLINK</varname>, e <varname>DOC_PREFIX</varname>.
These <filename>Makefile</filename>s set <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variables that describe how to build the documentation contained in that directory. Estes conjuntos de ​​<citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> <filename>Makefile</filename>s descrevem como construir a documentação contida nesse diretório.
The <varname>MAINTAINER</varname> variable allows committers to claim ownership of a document in the FreeBSD Documentation Project, and take responsibility for maintaining it. A variável <varname>MAINTAINER</varname> permite que os committers reivindiquem a propriedade de um documento no Projeto de Documentação do FreeBSD, e sejam responsáveis ​​por mantê-lo.
Environment Variables Variáveis ​​de Ambiente
Several environment variables control which parts of the web site are built or installed, and to which directories. Diversas variáveis ​​de ambiente controlam quais partes do web site são compiladas ou instaladas e para quais diretórios.
The web build system uses <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 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. O sistema de compilação do web site utiliza o <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, e valida variáveis configuradas mesmo se estiverem vazias. Os exemplos aqui mostram as formas recomendadas de configurar e utilizar essas variáveis. Definir ou configurar essas variáveis ​​com outros valores ou métodos pode levar a surpresas inesperadas.
This variable is best set with <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the user shell's method of setting environment variables, <command>setenv</command> for <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> or <command>export</command> for <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Esta variável é melhor configurada com <citerefentry><refentrytitle>env</refentrytitle><manvolnum>1</manvolnum></citerefentry> ou o método do shell do usuário para configurar variáveis ​​de ambiente, <command>setenv</command> para <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> ou <command>export</command> para <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, and <varname>ENGLISH_ONLY</varname> are <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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. <varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, e <varname>ENGLISH_ONLY</varname> são variáveis <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> que​e podem ser definidas em <filename>/etc/make.conf</filename>, <filename>Makefile.inc</filename>, como variáveis ​​de ambiente na linha de comando, ou em arquivos dot.
This is a good way to have re-usable, easily changeable chunks of content in <acronym>XML</acronym> documents. It is also the only way to include one marked up file inside another using <acronym>XML</acronym>. Esta é uma boa maneira de ter pedaços de conteúdo reutilizáveis ​​e facilmente alteráveis ​​em documentos <acronym>XML</acronym>. Também é a única maneira de incluir um arquivo markup dentro de outro usando <acronym>XML</acronym>.
General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an <acronym>XML</acronym> context. Entidades gerais são usadas para atribuir nomes a partes reutilizáveis ​​de texto. Essas entidades só podem ser usadas no documento. Elas não podem ser usadas ​​em um contexto <acronym>XML</acronym>.
Parameter entities, like <link linkend="xml-primer-general-entities">general entities</link>, are used to assign names to reusable chunks of text. But parameter entities can only be used within an <link linkend="xml-primer-xml-escape">XML context</link>. Entidades de parâmetro, como as <link linkend="xml-primer-general-entities">entidades gerais</link>, são usadas para atribuir nomes a blocos reutilizáveis ​​de texto. Mas as entidades de parâmetro só podem ser usadas dentro de um <link linkend="xml-primer-xml-escape">contexto XML</link>.
FreeBSD-specific elements used in the examples below are clearly marked. Os elementos específicos do FreeBSD usados ​​nos exemplos abaixo estão claramente marcados.
An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into one or more sections, using the same <tag>sect1</tag> (and <tag>sect2</tag> and so on) elements that are used in books. Um artigo é mais simples que um livro e não utiliza capítulos. Em vez disso, o conteúdo de um artigo é organizado em uma ou mais seções, usando os mesmos elementos <tag>sect1</tag> (e <tag>sect2</tag> e assim por diante) que são usados ​​em livros.
Buttons presented by a graphical user interface are marked with <tag>guibutton</tag>. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text. Os botões apresentados por uma interface gráfica do usuário são marcados com <tag>guibutton</tag>. Para tornar o texto mais parecido com um botão gráfico, colchetes e espaços não separáveis ​​são adicionados em volta do texto.
A good example of the use of images is the <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document. Um bom exemplo do uso de imagens é o documento <filename>graphics/ImageMagick</filename>. Examine os arquivos nesse diretório para ver como esses elementos são usados ​​juntos. Crie formatos de saída diferentes para ver como o formato determina quais imagens são mostradas no documento renderizado.