diff options
| author | Edson Brandi <ebrandi@FreeBSD.org> | 2018-09-06 01:10:32 +0000 |
|---|---|---|
| committer | Edson Brandi <ebrandi@FreeBSD.org> | 2018-09-06 01:10:32 +0000 |
| commit | 8d4d8b33813024c1baa02a4df4e11220804598d0 (patch) | |
| tree | 36ed699a0bdd3d1f7310b3050fe281e56aba634c /pt_BR.ISO8859-1/books/fdp-primer | |
| parent | e57181d72917ec1aa608ed6d832e1c09893692f1 (diff) | |
| download | doc-8d4d8b33813024c1baa02a4df4e11220804598d0.tar.gz doc-8d4d8b33813024c1baa02a4df4e11220804598d0.zip | |
pt_BR.ISO8859-1/books/fdp-primer: converted to .po
* 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
Notes
Notes:
svn path=/head/; revision=52225
Diffstat (limited to 'pt_BR.ISO8859-1/books/fdp-primer')
22 files changed, 33698 insertions, 3032 deletions
diff --git a/pt_BR.ISO8859-1/books/fdp-primer/Makefile b/pt_BR.ISO8859-1/books/fdp-primer/Makefile index 0a8344590f..5904ebcfc8 100755 --- a/pt_BR.ISO8859-1/books/fdp-primer/Makefile +++ b/pt_BR.ISO8859-1/books/fdp-primer/Makefile @@ -1,13 +1,12 @@ # # The FreeBSD Documentation Project # The FreeBSD Brazilian Portuguese Documentation Project -# -# $FreeBSD$ # -# Original revision: r38826 +# $FreeBSD$ # -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" diff --git a/pt_BR.ISO8859-1/books/fdp-primer/book.xml b/pt_BR.ISO8859-1/books/fdp-primer/book.xml index 39d99c4349..01d9018be6 100644 --- a/pt_BR.ISO8859-1/books/fdp-primer/book.xml +++ b/pt_BR.ISO8859-1/books/fdp-primer/book.xml @@ -1,8 +1,33 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -]> +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!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.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 index SYSTEM "index.xml" -->]> <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -32,102 +57,77 @@ 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$ +--> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" xml:lang="pt_BR"> + <info> + <title>Primer do Projeto de Documentação do FreeBSD para Novos Colaboradores</title> - Original revision: r38826 + <author><orgname>Projeto de Documentação do FreeBSD</orgname></author> + + <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <year>2015</year> <year>2016</year> <year>2017</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright> + + <pubdate/> + + <releaseinfo/> ---> -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> - <info><title>&a.ptbr.p.fdpp; para novos colaboradores</title> - <author><orgname>Projeto de documentao do - FreeBSD</orgname></author> - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> - </copyright> - - <pubdate role="rcs">$FreeBSD$</pubdate> - - <releaseinfo>$FreeBSD$</releaseinfo> - - &legalnotice; +<legalnotice xml:id="legalnotice"> + <title>Copyright</title> + + <para>Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:</para> + + <orderedlist> + <listitem> + <para>Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.</para> + </listitem> + + <listitem> + <para>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.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 FREEBSD DOCUMENTATION PROJECT 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.</para> + </important> +</legalnotice> + <abstract> - <para>Obrigado por tornar-se parte do Projeto de - Documentao do FreeBSD. A sua - contribuio extremamente - valiosa.</para> - - <para>Este &a.ptbr.p.fdpp; cobre tudo o que voc precisa - saber para comear a contribuir com o Projeto de - Documentao do FreeBSD, desde as ferramentas e - softwares que voc estar utilizando (tanto - os obrigatrios quanto os recomendados) - filosofia por trs do projeto de - documentao.</para> - - <para>Este documento um trabalho em andamento, e - no est completo. As sesses que - sabemos estarem incompletas esto indicadas com um - <literal>*</literal> no seu nome.</para> + <para>Obrigado por fazer parte do Projeto de Documentação do FreeBSD. A sua contribuição é extremamente valiosa.</para> + + <para>Este primer cobre tudo o que você precisa saber para começar a contribuir com o Projeto de Documentação do FreeBSD, ou <acronym>FDP</acronym>, incluindo ferramentas, softwares, e a filosofia por trás do Projeto de Documentação.</para> + + <para>Este documento é um trabalho em andamento. Correções e adições são sempre bem vindas.</para> </abstract> </info> <preface xml:id="preface"> - <title>Prefcio</title> + <title>Prefácio</title> -<sect1 xml:id="preface-prompts"> - <title><foreignphrase>Prompt</foreignphrase> do interpretador de - comandos (<foreignphrase>shell</foreignphrase>)</title> + <sect1 xml:id="preface-prompts"> + <title>Prompts do Shell</title> - <para>A tabela seguinte mostra o - <foreignphrase>prompt</foreignphrase> padro do sistema - e o <foreignphrase>prompt</foreignphrase> do super - usurio. Os exemplos iro utilizar estes - <foreignphrase>prompts</foreignphrase> para indicar com qual - usurio o exemplo foi executado.</para> + <para>Esta tabela mostra o prompt padrão do sistema e o prompt do super usuário. Os exemplos usam estes prompts para indicar com qual +usuário o exemplo foi executado.</para> - <informaltable frame="none" pgwide="1"> + <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> - <entry>Usurio</entry> - <entry><foreignphrase>Prompt</foreignphrase></entry> + <entry>Usuário</entry> + <entry>Prompt</entry> </row> </thead> <tbody> <row> - <entry>Usurio normal</entry> - <entry>&prompt.user;</entry> + <entry>Usuário normal</entry> + <entry><prompt>%</prompt></entry> </row> <row> <entry><systemitem class="username">root</systemitem></entry> - <entry>&prompt.root;</entry> + <entry><prompt>#</prompt></entry> </row> </tbody> </tgroup> @@ -135,159 +135,7296 @@ </sect1> <sect1 xml:id="preface-conventions"> - <title>Convenes Tipogrficas</title> + <title>Convenções Tipográficas</title> - <para>A tabela seguinte descreve as convenes - tipogrficas utilizadas neste livro.</para> + <para>Esta tabela descreve as convenções tipográficas utilizadas neste livro.</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> - <entry>Propsito</entry> + <entry>Propósito</entry> <entry>Exemplos</entry> </row> </thead> <tbody> <row> - <entry>Nome de um comando.</entry> - <entry>Utilize <command>ls -a</command> para listar - todos os arquivos.</entry> + <entry>Nome dos comandos.</entry> + <entry>Utilize <command>ls -l</command> para listar todos os arquivos.</entry> </row> - <row> - <entry>Nome de um arquivo.</entry> - <entry>Edite o seu arquivo <filename>.login</filename> - .</entry> - </row> + <row> + <entry>Nome dos arquivos.</entry> + <entry>Edite <filename>.login</filename>.</entry> + </row> - <row> - <entry>Sada - (<foreignphrase>output</foreignphrase>) - de um programa na tela do computador.</entry> - <entry><screen>Voc tem email.</screen></entry> - </row> + <row> + <entry>Saída de um programa na tela do computador.</entry> + <entry><screen>You have mail.</screen></entry> + </row> <row> - <entry>O que voc digita, quando contrastado com a - sada (<foreignphrase>output</foreignphrase>) do - programa na tela do computador.</entry> - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> + <entry>O que o usuário digita, quando contrastado com a saída do programa na tela do computador.</entry> + + <entry><screen><prompt>%</prompt> <userinput>date +"The time is %H:%M"</userinput> +The time is 09:18</screen></entry> </row> <row> - <entry>Referncia a uma pgina de - manual.</entry> - <entry>Utilize o &man.su.1; para assumir outro nome de - usurio.</entry> + <entry>Referência a uma página de manual.</entry> + <entry>Utilize <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> para assumir outro nome de +usuário.</entry> </row> <row> - <entry>Nome de usurio e de grupos de - usurios</entry> - <entry>Apenas o <systemitem class="username">root</systemitem> pode fazer - isso.</entry> + <entry>Nome de usuário e de grupos de usuários</entry> + <entry>Apenas o <systemitem class="username">root</systemitem> pode fazer isso.</entry> </row> <row> - <entry>nfase</entry> - <entry>Voc <emphasis>deve</emphasis> fazer - isso.</entry> + <entry>Ênfase</entry> + <entry>O usuário <emphasis>deve</emphasis> fazer isso.</entry> </row> <row> - <entry>Variveis da linha de comando; Substitua - com o nome real ou com a varivel.</entry> - <entry>Para deletar um arquivo, digite <command>rm - nome_do_arquivo - </command></entry> + <entry>Texto que o usuário deve substituir com o texto real.</entry> + + <entry>Para buscar por uma palavra chave nas páginas de manual, digite <command>man -k <replaceable>keyword</replaceable></command></entry> </row> <row> - <entry>Variveis de ambiente</entry> - <entry>O <envar>$HOME</envar> o seu - diretrio <literal>home</literal>.</entry> + <entry>Variáveis de ambiente</entry> + <entry><envar>$HOME</envar> aponta para o diretório inicial do usuário.</entry> </row> </tbody> </tgroup> - </informaltable> -</sect1> + </informaltable> + </sect1> <sect1 xml:id="preface-notes"> - <title>Notas, dicas, informaes importantes, - avisos e exemplos</title> + <title>Notas, Dicas, Informações Importantes, Avisos e Exemplos</title> - <para>Ao longo do texto aparecero notas, avisos e - exemplos.</para> + <para>Notas, avisos e exemplos aparecem ao longo do texto.</para> <note> - <para>Notas so representadas desta forma, e - contm informaes para as quais - voc deveria ficar atento, pois podem afetar o que - voc faz.</para> + <para>Notas são representadas desta forma, e contêm informações para as quais se deve ficar atento, pois podem afetar o que o usuário faz.</para> </note> <tip> - <para>Dicas so representadas desta forma, e - contm informaes que voc pode - achar teis, ou que mostram uma maneira mais - fcil de fazer alguma coisa.</para> + <para>Dicas são representadas desta forma, e contêm informações úteis para o usuário, como as que mostram uma maneira mais fácil de fazer alguma coisa.</para> </tip> <important> - <para>Informaes importantes so - representadas desta forma. Normalmente elas destacam passos - extras que voc pode precisar realizar.</para> + <para>Informações importantes são representadas desta forma. Normalmente elas destacam passos extras que o usuário pode precisar realizar.</para> </important> <warning> - <para>Avisos so representados deste modo, e - contm informaes de alerta para - voc sobre possveis danos se voc - no seguir as instrues. Estes danos - podem ser fsicos: para o seu equipamento ou para - voc; ou, podem ser no-fsicos: tal - como a deleo inadvertida de arquivos - importantes.</para> + <para>Avisos são representados deste modo, e contêm informações de alerta sobre possíveis danos se não seguir as instruções. Estes danos podem ser físicos, para o equipamento ou para o usuário, ou podem ser não-físicos, tal como a deleção inadvertida de arquivos importantes.</para> </warning> <example> - <title>Uma amostra de exemplo</title> + <title>Uma Amostra de Exemplo</title> - <para>Os exemplos so representados deste modo, e - normalmente contm exemplos que voc deve - analisar, ou ento, mostram como deveriam ser os - resultados de uma determinada ao.</para> + <para>Os exemplos são representados deste modo, e normalmente contêm exemplos passo a passo, ou mostram os resultados de uma determinada ação.</para> </example> </sect1> <sect1 xml:id="preface-acknowledgements"> <title>Agradecimentos</title> - <para>Meu muito obrigado a Sue Blake, Patrick Durusau, Jon - Hamilton, Peter Flynn, e Christopher Maden, por terem gasto - parte do seu tempo lendo os primeiros rascunhos deste - documento e por terem oferecido muitos comentrios e - crticas construtivas para este trabalho.</para> + <para>Meu muito obrigado a Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, e Christopher Maden, por terem gasto parte do seu tempo lendo os primeiros rascunhos deste documento e por terem oferecido muitos comentários e críticas construtivas para este trabalho.</para> </sect1> </preface> - &chap.overview; - &chap.tools; - &chap.xml-primer; - &chap.xml-markup; - &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; - - &app.examples; + +<!-- 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 version="5.0" xml:id="overview"> + <title>Visão Geral</title> + + <para>Seja bem vindo ao Projeto de Documentação do FreeBSD.(<acronym>FDP</acronym>). Documentação de boa qualidade é +muito importante para o sucesso do FreeBSD, e nós valorizamos muito suas contribuições.</para> + + <para>Este documento descreve como o <acronym>FDP</acronym> é organizado, como escrever e como submeter documentos, e como utilizar de forma efetiva as ferramentas que estão disponíveis.</para> + + <para>Todos são bem vindos para se juntar ao <acronym>FDP</acronym>. A vontade de contribuir é o único requisito de adesão.</para> + + <para>Este primer mostra como:</para> + + <itemizedlist> + <listitem> + <para>Identificar quais partes do FreeBSD são mantidas pelo <acronym>FDP</acronym>.</para> + </listitem> + + <listitem> + <para>Instalar as ferramentas e arquivos de documentação necessários.</para> + </listitem> + + <listitem> + <para>Realizar alterações na documentação.</para> + </listitem> + + <listitem> + <para>Enviar de volta alterações para revisão e inclusão na documentação do FreeBSD.</para> + </listitem> + </itemizedlist> + + <sect1 xml:id="overview-quick-start"> + <title>Quick Start</title> + + <para>Algumas etapas preparatórias devem ser seguidas antes de editar a documentação do FreeBSD. Primeiro, se registre na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de email do projeto de documentação do FreeBSD</link>. Alguns membros do time também interagem no <acronym>IRC</acronym>, canal <literal>#bsddocs</literal> na rede <link xlink:href="http://www.efnet.org/">EFnet</link>. Estas pessoas podem ajudar com questões e problemas envolvendo documentação.</para> + + <procedure> + <step> + <para>Instale o meta-port <package>textproc/docproj</package> e o <application>Subversion</application>. Este meta-port instala todo software necessário para editar e compilar a documentação do FreeBSD. O pacote <application>Subversion</application> é necessário para obter uma cópia de trabalho da documentação e para gerar patches. </para> + + <screen><prompt>#</prompt> <userinput>pkg install docproj subversion</userinput></screen> + </step> + + <step> + <para>Obtenha uma cópia local da árvore de documentação do FreeBSD em <filename>~/doc</filename> (see <xref linkend="working-copy"/>).</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>Configure o editor de texto:</para> + + <itemizedlist> + <listitem> + <para>Defina a quebra de linha para 70 caracteres.</para> + </listitem> + + <listitem> + <para>Defina a parada de tabulação para 2.</para> + </listitem> + + <listitem> + <para>Substitua cada grupo de 8 espaços por um tab.</para> + </listitem> + </itemizedlist> + + <para>Configurações específicas por editor são informados em <xref linkend="editor-config"/>.</para> + </step> + + <step> + <para>Atualize a árvore de trabalho local:</para> + + <screen><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>Edite os arquivos de documentação que precisam de alterações. Se um arquivo precisar de grandes mudanças, consulte a lista de discussão para obter informações.</para> + + <para>Referencias pra uso de tag e entidade podem ser encontradas em <xref linkend="xhtml-markup"/> and <xref linkend="docbook-markup"/>.</para> + </step> + + <step> + <para>Após alteração, cheque por eventuais problemas rodando</para> + + <screen><prompt>%</prompt> <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para>Revise a saída e edite o arquivo para corrigir os problemas informados e, em seguida, execute novamente o comando para verificar os problemas restantes. Repita até que todos os erros sejam resolvidos.</para> + </step> + + <step> + <para><emphasis>Sempre</emphasis> realize testes de compilação antes de submeter algo. Execute <userinput>make</userinput> no diretório de nível superior da documentação alterada e assim será gerado a documentação no formato HTML com divisões. Por exemplo, pra compilar a versão Inglês do Handbook em <acronym>HTML</acronym>, execute <command>make</command> no diretório <filename>en_US.ISO8859-1/books/handbook/</filename>.</para> + </step> + + <step> + <para>Quando as alterações estiverem completas e testadas, gere um <quote>arquivo diff</quote>:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + + <para>Dê ao arquivo diff um nome. No exemplo acima, foram feitas alterações na parte <filename>bsdinstall</filename> do Handbook.</para> + </step> + + <step> + <para>Submeta o arquivo diff file pela web para o sistema de <link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation">Relatórios de Problema</link>. Se estiver usando o formulário web, insira um Sumário com <emphasis>[patch] <replaceable>descrição curta do problema</replaceable></emphasis>. Selecione o Componente <literal>Documentation</literal>. No campo de Descrição, insira uma breve descrição das alterações e quaisquer detalhes importantes sobre elas. Use o botão <guibutton>[ Add an attachment ]</guibutton> para anexar o arquivo diff. Finalmente, pressione o botão <guibutton>[ Submit Bug ]</guibutton> para enviar seu diff para o sistema de relatório de problemas.</para> + </step> + </procedure> + </sect1> + + <sect1 xml:id="overview-doc"> + <title>Conjunto de Documentação do FreeBSD</title> + + <para>O <acronym>FDP</acronym> é responsável por quatro categorias de documentação do FreeBSD.</para> + + <itemizedlist> + <listitem> + <para><emphasis>Handbook</emphasis>: O handbook almeja ser um compreensivo recurso de referência online para os usuários do FreeBSD</para> + </listitem> + + <listitem> + <para><emphasis>FAQ</emphasis>: O <acronym>FAQ</acronym> utiliza um formato curto de pergunta e resposta para abordar dúvidas que são frequentemente realizadas nas listas de discussão e fóruns dedicados ao FreeBSD. Este formato não permite respostas longas e detalhadas.</para> + </listitem> + + <listitem> + <para><emphasis>Páginas de Manual</emphasis>: As páginas de manual do sistema de língua inglesa geralmente não são escritas pelo <acronym>FDP</acronym>, pois fazem parte do sistema base. Contudo, o <acronym>FDP</acronym> pode reformular partes das páginas de manual existentes para torná-las mais claras ou para corrigir imprecisões.</para> + </listitem> + + <listitem> + <para><emphasis>Web site</emphasis>: Esta é a presença principal do FreeBSD na web, visite <link xlink:href="https://www.freebsd.org/index.html"> https://www.FreeBSD.org/</link> e muitos mirrors ao redor do mundo. O site é tipicamente o primeiro contato de um usuário novo com o FreeBSD.</para> + </listitem> + </itemizedlist> + + <para>As equipes de tradução são responsáveis por traduzir o manual e o site para diferentes idiomas. As páginas do manual não são traduzidas no momento.</para> + + <para>Código fonte do site do FreeBSD, Handbook, e <acronym>FAQ</acronym> estão disponíveis no repositório de documentação em <literal>https://svn.FreeBSD.org/doc/</literal>.</para> + + <para>Código fonte das páginas de manual estão disponíveis em um repositório diferente localizado em <literal>https://svn.FreeBSD.org/base/</literal>.</para> + + <para>As mensagens de commit de documentação podem ser visualizadas com <command>svn log</command>. As mensagens de commit também são arquivadas em <uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all"> http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>.</para> + + <para>Endereço web para ambos os repositórios disponíveis em <link xlink:href="https://svnweb.FreeBSD.org/doc/"/> e <link xlink:href="https://svnweb.FreeBSD.org/base/"/>.</para> + + <para>Muitas pessoas tem escrito tutoriais e artigos how-to sobre FreeBSD. Alguns são armazenados como parte dos arquivos <acronym>FDP</acronym>. Em outros casos, o autor decidiu manter a documentação separada. O <acronym>FDP</acronym> esforça-se para fornecer links para o máximo possível dessas documentações externas.</para> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="tools"> + <title>Ferramentas</title> + + <para>Várias ferramentas são utilizadas para gerenciar a documentação do FreeBSD e renderizá-la para diferentes formatos. Algumas dessas ferramentas são necessárias e devem ser instaladas antes de trabalhar com os exemplos nos capítulos a seguir. Algumas são opcionais, adicionando recursos ou tornando a tarefa de criar documentação mais simples.</para> + + <sect1 xml:id="tools-required"> + <title>Ferramentas Obrigatórias</title> + + <para>Instale o <package>textproc/docproj</package> pela Coleção de Ports. Este <emphasis>meta-port</emphasis> instala todos os aplicativos necessários para trabalhar com a documentação do FreeBSD. Informações adicionais específicas de alguns componentes serão informadas abaixo.</para> + + <sect2 xml:id="tools-required-dtd-entities"> + <title><acronym>DTD</acronym>s e <acronym>Entidades</acronym></title> + + <para>A documentação do FreeBSD utiliza diversas Definições de Tipos de Documento (<acronym>DTD</acronym>s) e conjuntos de entidades <acronym>XML</acronym>. Estes são todos instalados pelo port <package>textproc/docproj</package>.</para> + + <variablelist> + <varlistentry> + <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<package>textproc/xhtml</package>)</term> + + <listitem> + <para><acronym>XHTML</acronym> é a linguagem markup escolhida pela Web, e é utilizada em todo o site do FreeBSD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term> + + <listitem> + <para>O DocBook é projetado para escrever documentação técnica. A maior parte da documentação do FreeBSD é escrita no DocBook.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Entidades ISO 8879 (<package>textproc/iso8879</package>)</term> + + <listitem> + <para>Entidades do padrão ISO 8879:1986 utilizado por muitos <acronym>DTD</acronym>s. Inclui símbolos matemáticos nomeados, caracteres adicionais no conjunto de caracteres latinos (acentos, diacríticos e assim por diante) e símbolos Gregos.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 xml:id="tools-optional"> + <title>Ferramentas Opcionais</title> + + <para>Essas ferramentas não são necessárias, mas podem facilitar o trabalho na documentação ou adicionar recursos.</para> + + <sect2 xml:id="tools-optional-software"> + <title>Software</title> + + <variablelist> + + <varlistentry> + <term><application>Vim</application> (<package>editors/vim</package>)</term> + + <listitem> + <para>Um editor de texto popular que trabalha com <acronym>XML</acronym> and documentos derivados, como DocBook <acronym>XML</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> ou <application>XEmacs</application> (<package>editors/emacs</package> ou <package>editors/xemacs</package>)</term> + + <listitem> + <para>Ambos editores incluem um modo especial para editar documentos marcados como <acronym>XML</acronym> <acronym>DTD</acronym>. Esse modo inclui comandos para reduzir a quantidade de digitação necessária e ajudar a reduzir a possibilidade de erros.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="working-copy"> + <title>A Área de Trabalho</title> + + <para>A <emphasis>área de trabalho</emphasis> é uma cópia da árvore de documentação do repositório do FreeBSD baixada no computador local. As alterações são feitas na cópia de trabalho local, testadas e enviadas como patches para serem submetidas no repositório principal.</para> + + <para>Uma cópia completa da árvore de documentação pode ocupar 700 megabytes de espaço em disco. Tenha um gigabyte de espaço total para ter sobra para arquivos temporários e versões de teste dos diversos formatos de saída.</para> + + <para>O <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> é utilizado para gerenciar os arquivos de documentação do FreeBSD. Ele é obtido pela instalação do pacote <application>Subversion</application>:</para> + + <screen><prompt>#</prompt> <userinput>pkg install subversion</userinput></screen> + + <sect1 xml:id="working-copy-doc-and-src"> + <title>Documentação e Páginas de Manual</title> + + <para>A documentação do FreeBSD não é formada apenas por livros e artigos. Páginas de manual para todos os comandos e arquivos de configuração também fazem parte da documentação e fazem parte do território do <acronym>FDP</acronym>. Dois repositórios estão envolvidos: <literal>doc</literal> para os livros e artigos, e <literal>base</literal> para o sistema operacional e páginas de manual. Para editar páginas de manual, o repositório <literal>base</literal> deve ser registrado separadamente.</para> + + <para>Repositórios podem conter várias versões de documentação e código-fonte. Novas modificações quase sempre são feitas apenas para a versão mais recente, chamada <literal>head</literal>.</para> + </sect1> + + <sect1 xml:id="working-copy-choosing-directory"> + <title>Escolhendo um Diretório</title> + + <para>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.</para> + </sect1> + + <sect1 xml:id="working-copy-checking-out"> + <title>Baixando uma Cópia</title> + + <para>O processo de download de um repositório é chamado de <emphasis>checkout</emphasis> e é feito com um <command>svn checkout</command>. Este exemplo faz checkout de uma cópia da versão mais recente (<literal>head</literal>) do repositório de documentação principal:</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + + <para>O checkout do código-fonte para trabalhar nas páginas de manual é muito semelhante:</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-updating"> + <title>Atualizando</title> + + <para>Os documentos e arquivos no repositório do FreeBSD mudam diariamente. As pessoas modificam arquivos e submetem alterações com frequência. Mesmo após um checkout inicial, já haverá alterações entre a cópia de trabalho local e o repositório principal do FreeBSD. Para atualizar a versão local com as mudanças que foram feitas no repositório principal, execute <command>svn update</command> no diretório que contém a cópia de trabalho local:</para> + + <screen><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para>Adquira o hábito de proteção de executar <command>svn update</command> antes de editar os arquivos de documentação. Alguém pode ter editado esse arquivo muito recentemente e a cópia de trabalho local não incluirá essas alterações mais recentes até que ela seja atualizada. Editar a versão mais recente de um arquivo é muito mais fácil do que tentar combinar um arquivo local editado mais antigo com a versão mais recente do repositório.</para> + </sect1> + + <sect1 xml:id="working-copy-revert"> + <title>Revertendo Alterações</title> + + <para>De vez em quando acontece que algumas mudanças não eram necessárias, ou o escritor só quer começar novamente. Arquivos podem ser <quote>resetados</quote> para sua forma anterior com <command>svn revert</command>. Por exemplo, para apagar as alterações feitas no <filename>chapter.xml</filename> e redefini-las para o formato sem modificação:</para> + + <screen><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-making-diff"> + <title>Criando um Diff</title> + + <para>Após finalizar as alterações em um arquivo ou grupo de arquivos, as diferenças entre a cópia de trabalho local e a versão no repositório do FreeBSD devem ser coletadas em um único arquivo para ser submetido. Estes arquivos <emphasis>diff</emphasis> são produzidos redirecionando a saída de <command>svn diff</command> para um arquivo:</para> + + <screen><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + + <para>Dê ao arquivo um nome significativo que identifique o conteúdo. O exemplo acima é para correção ortográfica em toda a árvore de documentação.</para> + + <para>Se o arquivo diff for enviado com a interface web <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a FreeBSD problem report</link></quote>, adicione uma extensão <filename>.txt</filename> para que o formulário web identifique que o conteúdo do arquivo é texto plano.</para> + + <para>Tenha cuidado: <command>svn diff</command> inclui todas as alterações feitas no diretório atual e em quaisquer subdiretórios. Se houver arquivos na cópia de trabalho com edições que ainda não estão prontas para serem enviadas, forneça uma lista apenas dos arquivos a serem incluídos:</para> + + <screen><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-subversion-references"> + <title>Referências <application>Subversion</application></title> + + <para>Estes exemplos demonstram um uso muito básico do <application>Subversion</application>. Mais detalhes estão disponíveis no <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> e na <link xlink:href="http://subversion.apache.org/docs/">Documentação do Subversion</link>.</para> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="structure"> + <title>Estrutura de Diretórios da Documentação</title> + + <para>Arquivos e diretórios no repositório <filename>doc/</filename> seguem uma estrutura destinada a:</para> + + <orderedlist> + <listitem> + <para>Facilitar a conversão do documento para outros formatos.</para> + </listitem> + + <listitem> + <para>Promover a consistência entre as diferentes organizações de documentação, e assim facilitar a alternância entre diferentes documentos.</para> + </listitem> + + <listitem> + <para>Facilitar a decisão de onde a nova documentação deve ser colocada.</para> + </listitem> + </orderedlist> + + <para>Além disso, o repositório de documentação deve acomodar documentos em vários idiomas e codificações diferentes. É importante que a estrutura do repositório de documentação não imponha quaisquer padrões particulares ou preferências culturais.</para> + + <sect1 xml:id="structure-top"> + <title>O Nível Superior, <filename>doc/</filename></title> + + <para>Existem dois tipos de diretório em <filename>doc/</filename>, cada um com nomes de diretório e significados muito específicos.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Diretório</entry> + <entry>Uso</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"><filename>share</filename></entry> + + <entry>Contém arquivos que não são específicos das várias traduções e codificações da documentação. Contém subdiretórios para categorizar ainda mais as informações. Por exemplo, os arquivos que fazem parte da infra-estrutura <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> estão em <filename>share/mk</filename>, enquanto o suporte adicional a arquivos <acronym>XML</acronym> (como o DTBook estendido do FreeBSD <acronym>DTD</acronym>) estão em <filename>share/xml</filename>.</entry> + </row> + + <row> + <entry valign="top"><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> + + <entry>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.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="structure-locale"> + <title>Os Diretórios <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></title> + + <para>Esses diretórios contêm os próprios documentos. A documentação é dividida em até três outras categorias, indicadas pelos diferentes nomes de diretório.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Diretório</entry> + <entry>Uso</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"><filename>articles</filename></entry> + + <entry>Documentação marcada como DocBook <tag>article</tag> (ou equivalente). Conteúdo curto e dividido em seções. Normalmente disponível apenas como um arquivo <acronym>XHTML</acronym>.</entry> + </row> + + <row> + <entry valign="top"><filename>books</filename></entry> + + <entry>Documentação marcada como DocBook <tag>book</tag> (ou equivalente). Conteúdo longo e dividido em capítulos. Normalmente disponível como um grande arquivo <acronym>XHTML</acronym> (para pessoas com conexões rápidas, ou que desejam imprimi-lo facilmente de um navegador) e como uma coleção de arquivos menores e com links.</entry> + </row> + + <row> + <entry valign="top"><filename>man</filename></entry> + + <entry>Para traduções das páginas de manual do sistema. Esse diretório conterá um ou mais diretórios <filename role="directory">man<replaceable>N</replaceable></filename>, correspondendo às seções que foram traduzidas.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Nem todo diretório <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> terá todos esses subdiretórios. Depende de quanto a tradução foi realizada por essa equipe de tradução.</para> + </sect1> + + <sect1 xml:id="structure-document"> + <title>Informação Específica de Documentação</title> + + <para>Esta seção contém informações específicas sobre documentos gerenciados pelo FDP.</para> + + <sect2 xml:id="structure-document-handbook"> + <title>O Handbook</title> + + <subtitle><filename>books/handbook/</filename></subtitle> + + <para>O Handbook está escrito em DocBook <acronym>XML</acronym> usando <acronym>DTD</acronym> extendido do DocBook FreeBSD.</para> + + <para>O Handbook está organizado como um DocBook <tag>book</tag>. O livro é dividido em <tag>part</tag>s, cada uma contendo vários <tag>chapter</tag>s. Os <tag>chapter</tag>s são subdivididos em seções (<tag>sect1</tag>) e subseções (<tag>sect2</tag>, <tag>sect3</tag>) e assim por diante.</para> + + <sect3 xml:id="structure-document-handbook-physical"> + <title>Organização Física</title> + + <para>Existem vários arquivos e diretórios dentro do diretório <filename>handbook</filename>.</para> + + <note> + <para>A organização do Handbook pode ser alterada ao longo do tempo, e este documento pode estar defasado quanto ao detalhamento das mudanças organizacionais do mesmo. Envie perguntas sobre a organização do Handbook na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de discussão do projeto FreeBSD</link>.</para> + </note> + + <sect4 xml:id="structure-document-handbook-physical-Makefile"> + <title><filename>Makefile</filename></title> + + <para>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.</para> + </sect4> + + <sect4 xml:id="structure-document-handbook-physical-book-xml"> + <title><filename>book.xml</filename></title> + + <para>Este é o principal arquivo do Handbook. Ele contém a <link linkend="xml-primer-doctype-declaration">declaração DOCTYPE</link>, bem como os elementos que descrevem a estrutura do Handbook.</para> + + <para><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.</para> + </sect4> + + <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> em um diretório separado dos outros capítulos. Cada diretório é nomeado após o valor do atributo <literal>id</literal> no elemento <tag>chapter</tag>.</para> + + <para>Por exemplo, se um dos arquivos de capítulo contiver:</para> + + <programlisting><tag class="starttag">chapter id="kernelconfig"</tag> +... +<tag class="endtag">chapter</tag></programlisting> + + <para>Então ele será chamado de <filename>chapter.xml</filename> no diretório <filename>kernelconfig</filename>. Em geral, todo o conteúdo do capítulo está neste único arquivo.</para> + + <para>Quando a versão <acronym>XHTML</acronym> do Handbook for gerada, produzirá o <filename>kernelconfig.html</filename>. Isso é por causa do valor <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 <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.</para> + + <para>Com uma breve analise pode-se constatar que existem diversos diretórios com arquivos individuais <filename>chapter.xml</filename>, incluindo <filename>basics/chapter.xml</filename>, <filename>introduction/chapter.xml</filename>, e <filename>printing/chapter.xml</filename>.</para> + + <important> + <para>Não nomeie capítulos ou diretórios com a ordenação do Handbook. Essa ordenação pode mudar conforme o conteúdo do Handbook é reorganizado. A reorganização deve ser realizada sem renomear arquivos, a menos que capítulos inteiros sejam promovidos ou rebaixados dentro da hierarquia.</para> + </important> + + <para>Os arquivos <filename>chapter.xml</filename> não são arquivos completos de documentos <acronym>XML</acronym> que podem ser compilados individualmente. Eles só podem ser compilados como partes de todo o Handbook.</para> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +--> +<chapter version="5.0" xml:id="doc-build"> + <title>O Processo de Compilação da Documentação</title> + + <para>Este capítulo aborda a organização do processo de compilação da documentação e como o <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> é utilizado para isso.</para> + + <sect1 xml:id="doc-build-rendering"> + <title>Renderizando DocBook</title> + + <para>Diferentes tipos de saída podem ser produzidos a partir de um único arquivo fonte DocBook. O tipo de saída desejado é definido com a variável <varname>FORMATS</varname>. Uma lista de formatos de saída conhecidos é armazenada em <varname>KNOWN_FORMATS</varname>:</para> + + <screen xml:id="doc-build-rendering-known-formats"><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make -V KNOWN_FORMATS</userinput></screen> + + <table xml:id="doc-build-rendering-common-formats" frame="none"> + <title>Formatos de Saída Comuns</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Valor <varname>FORMATS</varname></entry> + <entry>Tipo de Arquivo</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>html</literal></entry> + <entry><acronym>HTML</acronym>, arquivo único</entry> + <entry>Um único <filename>book.html</filename> ou <filename>article.html</filename>.</entry> + </row> + + <row> + <entry><literal>html-split</literal></entry> + <entry><acronym>HTML</acronym>, vários arquivos</entry> + <entry>Vários arquivos <acronym>HTML</acronym>, um para cada capítulo ou seção, para uso em um site comum.</entry> + </row> + + <row> + <entry><literal>pdf</literal></entry> + <entry><acronym>PDF</acronym></entry> + <entry>Portable Document Format</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>O formato de saída padrão pode variar de acordo com o documento, mas geralmente é <literal>html-split</literal>. Outros formatos são escolhidos definindo <varname>FORMATS</varname> para um valor específico. Múltiplos formatos de saída podem ser criados de uma só vez definindo <varname>FORMATS</varname> para uma lista de formatos.</para> + + <example xml:id="doc-build-formats-example-html"> + <title>Compilar um Arquivo Único HTML</title> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make FORMATS=html</userinput></screen> + </example> + + <example xml:id="doc-build-formats-example-html-split-pdf"> + <title>Compilar HTML-Split e <acronym>PDF</acronym></title> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> +<prompt>%</prompt> <userinput>make FORMATS="html-split pdf"</userinput></screen> + </example> + </sect1> + + <sect1 xml:id="doc-build-toolset"> + <title>O Conjunto de Ferramentas de Compilação da Documentação do FreeBSD</title> + + <para>Estas são as ferramentas utilizadas para compilar e instalar a documentação do <acronym>FDP</acronym>.</para> + + <itemizedlist> + <listitem> + <para>A principal ferramenta de compilação é o <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, especificamente o <application>Berkeley Make</application>.</para> + </listitem> + + <listitem> + <para>A construção de pacotes é gerenciada pelo <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> do FreeBSD.</para> + </listitem> + + <listitem> + <para><citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> é usado para criar versões compactadas de um documento. <citerefentry><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> também são suportados. <citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> é usado na criação de pacotes.</para> + </listitem> + + <listitem> + <para><citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> é usado para instalar a documentação.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="doc-build-makefiles"> + + <title>Noções Básicas de <filename>Makefile</filename>s no Repositório de Documentação</title> + + <para>Existem três tipos principais de <filename>Makefile</filename>s no repositório de Documentação do Projeto FreeBSD.</para> + + <itemizedlist> + <listitem> + <para><link linkend="sub-make"><filename>Makefile</filename>s de Subdiretório</link> simplesmente passam os comandos para os diretórios abaixo deles.</para> + </listitem> + + <listitem> + <para><link linkend="doc-make"><filename>Makefile</filename>s de Documentação</link> descrevem os documentos que devem ser produzidos a partir deste diretório.</para> + </listitem> + + <listitem> + <para><link linkend="make-includes"><application>Make</application> includes</link> são os responsáveis pela produção do documento, e geralmente possuem o nome no formato <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> + </listitem> + </itemizedlist> + + <sect2 xml:id="sub-make"> + <title><filename>Makefile</filename>s de Subdiretório</title> + + <para>Estes <filename>Makefile</filename>s geralmente tem a forma de:</para> + + <programlisting>SUBDIR =articles +SUBDIR+=books + +COMPAT_SYMLINK = en + +DOC_PREFIX?= ${.CURDIR}/.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> + + <para>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>.</para> + + <para>A declaração <varname>SUBDIR</varname> e <varname>COMPAT_SYMLINK</varname> mostram como atribuir um valor a uma variável, sobrescrevendo qualquer valor anterior que a mesma contenha.</para> + + <para>A segunda declaração <varname>SUBDIR</varname> mostra como um valor é anexado ao valor atual de uma variável. A variável <varname>SUBDIR</varname> agora é composta por <literal>articles books</literal>.</para> + + <para>A declaração <varname>DOC_PREFIX</varname> mostra como um valor é atribuído para uma variável, mas somente se ela ainda não estiver definida. Isso é útil se <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>Agora o que tudo isso significa? <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>O <varname>COMPAT_SYMLINK</varname> é específico para compatibilizar os links simbólicos que ligam os idiomas a sua codificação oficial (<filename>doc/en</filename> deve apontar para <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 <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> que contém o caminho para o diretório atual.</para> + + <para>A linha final inclui o arquivo principal do <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> <filename>doc.project.mk</filename> do Projeto de Documentação do FreeBSD, ele é o responsável por converter estas variáveis em instruções de compilação.</para> + </sect2> + + <sect2 xml:id="doc-make"> + <title><filename>Makefile</filename>s de Documentação</title> + + <para>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.</para> + + <para>Aqui está um exemplo:</para> + + <programlisting>MAINTAINER=nik@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# SGML content +SRCS= book.xml + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> + + <para>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.</para> + + <para><varname>DOC</varname> é o nome (sem a extensão <filename>.xml</filename>) do principal documento criado por este diretório. O <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>FORMATS</varname> indica os formatos nos quais o documento deve ser gerado por padrã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>Você já deve estar familiarizado com a atribuição da variável <varname>DOC_PREFIX</varname> e com as instruções de include.</para> + </sect2> + </sect1> + + <sect1 xml:id="make-includes"> + <title>Includes do <application>Make</application> do Projeto de Documentação do FreeBSD</title> + + <para><citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> includes são melhor explicados por uma inspeção de código. Aqui estão os arquivos include do sistema:</para> + + <itemizedlist> + <listitem> + <para><filename>doc.project.mk</filename> é o principal arquivo include do projeto, que inclui todos os arquivos includes necessários.</para> + </listitem> + + <listitem> + <para><filename>doc.subdir.mk</filename> controla a navegação na árvore de documentação durante o processo de construção e instalação.</para> + </listitem> + + <listitem> + <para><filename>doc.install.mk</filename> fornece as variáveis que afetam a propriedade e a instalação de documentos.</para> + </listitem> + + <listitem> + <para><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> + </listitem> + </itemizedlist> + + <sect2 xml:id="includes-doc-project-mk"> + <title><filename>doc.project.mk</filename></title> + + <para>Por inspeção:</para> + + <programlisting>DOCFORMAT?= docbook +MAINTAINER?= doc@FreeBSD.org + +PREFIX?= /usr/local +PRI_LANG?= en_US.ISO8859-1 + +.if defined(DOC) +.if ${DOCFORMAT} == "docbook" +.include "doc.docbook.mk" +.endif +.endif + +.include "doc.subdir.mk" +.include "doc.install.mk"</programlisting> + + <sect3 xml:id="doc-project-mk-variables"> + + <title>Variáveis</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>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>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 é o padrão.</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> + </note> + </sect3> + + <sect3 xml:id="doc-project-mk-conditionals"> + <title>Condicionais</title> + + <para>A linha <literal>.if defined(DOC)</literal> é um exemplo da condicional do <citerefentry> <refentrytitle> make </refentrytitle> <manvolnum> 1 </manvolnum> </citerefentry> como em outros programas, define o comportamento se alguma condição é verdadeira ou se é falsa. <literal> defined </literal> é uma função que retorna se uma dada variável está definida ou não.</para> + + <para>A seguir, <literal>.if ${DOCFORMAT} == "docbook"</literal> testa se a variável <varname>DOCFORMAT</varname> é <literal>"docbook"</literal>, e neste caso, inclue o <filename>doc.docbook.mk</filename>.</para> + + <para>Os dois <literal>.endif</literal>s fecham as duas condicionais anteriores, marcando o fim da sua aplicação</para> + </sect3> + </sect2> + + <sect2 xml:id="includes-doc-subdir-mk"> + <title><filename>doc.subdir.mk</filename></title> + + <para>Este arquivo é muito longo para ser explicado em detalhes. Estas notas descrevem as principais funcionalidades.</para> + + <sect3 xml:id="doc-subdir-mk-variables"> + <title>Variáveis</title> + + <itemizedlist> + <listitem> + <para><varname>SUBDIR</varname> é a lista de subdiretórios nos quais o processo de construção deve ser executado.</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> + </listitem> + + <listitem> + <para><varname>COMPAT_SYMLINK</varname> já foi descrito na seção <link linkend="sub-make">Makefiles de Subdiretório</link>.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3 xml:id="doc-subdir-mk-targets-macro"> + <title>Targets e Macros</title> + + <para>As dependências são descritas por <literal><replaceable>target</replaceable>: <replaceable>dependência1 dependência2 ...</replaceable></literal>, nas quais, para construir o <literal>target</literal>, é necessário primeiramente construir as dependências informadas.</para> + + <para>Depois desta descrição, instruções de como construir o target podem ser passadas, no caso do processo de conversão entre o target e estas dependências não tiver sido previamente definido, ou se esta conversão em particular não for a mesma que a definida pelo método padrão de conversão.</para> + + <para>A dependência especial <literal>.USE</literal> define o equivalente a uma macro.</para> + + <programlisting>_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para>No código acima, <buildtarget>_SUBDIRUSE</buildtarget> é agora uma macro, a qual irá executar determinados comandos quando for listada como dependência.</para> + + <para>O que diferencia essa macro 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> + + <programlisting>clean: _SUBDIRUSE + rm -f ${CLEANFILES}</programlisting> + + <para>No código acima, o <buildtarget>clean</buildtarget> usará a macro <buildtarget>_SUBDIRUSE</buildtarget> depois de ter executado a instrução <command>rm -f $ {CLEANFILES}</command>. De fato, isso faz com que <buildtarget>clean</buildtarget> vá mais a fundo na árvore de diretórios, excluindo os arquivos construídos à medida que vai <emphasis>descendo</emphasis> pelos subdiretórios, e não quando vai na direção oposta.</para> + + <sect4 xml:id="doc-subdir-mk-provided-targets"> + <title>Targets Fornecidos</title> + + <itemizedlist> + <listitem> + <para><buildtarget>install</buildtarget> e <buildtarget>package</buildtarget> ambos percorrem a árvore de diretórios executando as suas versões reais dentro dos subdiretórios (<buildtarget>realinstall</buildtarget> e <buildtarget>realpackage</buildtarget> respectivamente).</para> + </listitem> + + <listitem> + <para><buildtarget>clean</buildtarget> remove arquivos criados pelo processo de compilação (e também desce na árvore de diretórios). <buildtarget>cleandir</buildtarget> faz a mesma coisa, e também remove o diretório de objetos se este existir.</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + + <sect3 xml:id="doc-subdir-mk-conditionals"> + <title>Mais Condicionais</title> + + <itemizedlist> + <listitem> + <para><literal>exists</literal> é outra função condicional que retorna verdadeiro se o arquivo informado existir.</para> + </listitem> + + <listitem> + <para><literal>empty</literal> retorna verdadeiro se a variável informada estiver vazia.</para> + </listitem> + + <listitem> + <para><literal>target</literal> retorna verdadeiro se o target informado ainda não existir.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3 xml:id="doc-subdir-mk-looping"> + <title>Construções de Looping no <command>make (.for)</command></title> + + <para><literal>.for</literal> fornece uma maneira de repetir instruções definidas para cada elemento separado por espaço em uma variável. Ele faz isso atribuíndo uma variável para conter o elemento atual da lista que está sendo examinada.</para> + + <programlisting>_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor</programlisting> + + <para>No código acima, se <varname>SUBDIR</varname> estiver vazia, nenhuma ação será executada; se ela possuir um ou mais elementos, as instruções entre <literal> .for </literal> e <literal> .endfor </literal> serão repetidas para cada elemento, com o <varname>entry</varname> sendo substituído com o valor do elemento atual.</para> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="the-website"> + <title>O Website</title> + + <para>O web site do FreeBSD é parte da documentação do FreeBSD. Os arquivos para o web site são armazenados no subdiretório <filename>en_US.ISO8859-1/htdocs</filename> do repositório <filename>~/doc</filename> neste exemplo.</para> + + <sect1 xml:id="the-website-env"> + <title>Variáveis de Ambiente</title> + + <para>Diversas variáveis de ambiente controlam quais partes do web site são compiladas ou instaladas e para quais diretórios.</para> + + <tip> + <para>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.</para> + </tip> + + <variablelist> + <varlistentry xml:id="the-website-env-destdir"> + <term><varname>DESTDIR</varname></term> + + <listitem> + <para>DESTDIR especifica o caminho onde os arquivos do web site devem ser instalados.</para> + + <para>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>.</para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry xml:id="the-website-env-englishonly"> + <term><varname>ENGLISH_ONLY</varname></term> + + <listitem> + <para>Padrão: indefinido. Compile e inclua todas as traduções.</para> + + <para><userinput>ENGLISH_ONLY=yes</userinput>: compile apenas os documentos em Inglês e ignore todas as traduções.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="the-website-env-webonly"> + <term><varname>WEB_ONLY</varname></term> + + <listitem> + <para>Padrão: indefinido. Compile o web site e todos os livros e artigos.</para> + + <para><userinput>WEB_ONLY=yes</userinput>: Compile ou instale apenas páginas <acronym>HTML</acronym> do diretório <filename>en_US.ISO8859-1/htdocs</filename>. Outros diretórios e documentos, incluindo livros e artigos, serão ignorados.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="the-website-env-weblang"> + <term><varname>WEB_LANG</varname></term> + + <listitem> + <para>Padrão: indefinido. Compile e inclua todos os idiomas disponíveis no web site.</para> + + <para>Defina com uma lista separada por espaços, todos os idiomas a serem incluídos na compilação ou instalação. Os formatos são os mesmos que os nomes de diretório no diretório raiz do documento. Por exemplo, para incluir os documentos alemão e francês:</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>, e <varname>ENGLISH_ONLY</varname> são variáveis <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> quee 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.</para> + </sect1> + + <sect1 xml:id="the-website-build"> + <title>Compilando e Instalando as Páginas Web</title> + + <para>Após obter os arquivos fontes da documentação e web site, o site pode ser compilado.</para> + + <para>Uma instalação real do web site precisa ser executada pelo usuário <systemitem class="username">root</systemitem> porque as permissões no diretório do servidor web não permitirão a instalação de arquivos por um usuário não privilegiado. Para testar, pode ser útil instalar os arquivos com um usuário normal em um diretório temporário.</para> + + <para>Nestes exemplos, os arquivos do web site são criados pelo usuário <systemitem class="username">jru</systemitem> em seu diretório home, <filename>~/doc</filename>, com um caminho completo de <filename>/usr/home/jru/doc</filename>.</para> + + <tip> + <para>A compilação do web site utiliza o arquivo <filename>INDEX</filename> da Coleção de Ports e pode falhar se este arquivo ou <filename>/usr/ports</filename> não estiver presente no sistema. A abordagem mais simples é instalar a <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/ports.html#ports-tree">Coleção de Ports</link>.</para> + </tip> + + <example xml:id="the-website-examples-build"> + <title>Compile o Web Site Completo e Todos Documentos</title> + + <para>Compile o web site e todos os documentos. Os arquivos finais são deixados na árvore de documento:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> +<prompt>%</prompt> <userinput>make all</userinput></screen> + </example> + + <example xml:id="the-website-examples-buildinstall-englishonly"> + <title>Compile Apenas o Web Site em Inglês</title> + + <para>Compile o web site apenas em Inglês, como usuário <systemitem class="username">jru</systemitem>, e instale os arquivos finais em <filename>/tmp/www</filename> para teste:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> +<prompt>%</prompt> <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen> + + <para>Alterações em arquivos estáticos geralmente podem ser testadas visualizando os arquivos modificados diretamente com um navegador web. Se o web site foi construído como apresentado acima, a página principal modificada pode ser visualizada com:</para> + + <screen><prompt>%</prompt> <userinput>firefox /tmp/www/data/index.html</userinput></screen> + + <para>Modificações em arquivos dinâmicos podem ser testadas com um servidor web rodando no sistema local. Depois de construir o site como apresentado acima, o <filename>/usr/local/etc/apache24/httpd.conf</filename> pode ser usado com <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 +<Directory /> + AllowOverride none + Require all denied +</Directory> + +# allow access to the website directory +DocumentRoot "${TestRoot}" +<Directory "${TestRoot}"> + Options Indexes FollowSymLinks + AllowOverride None + Require all granted +</Directory> + +# prevent access to .htaccess and .htpasswd files +<Files ".ht*"> + Require all denied +</Files> + +ErrorLog "/var/log/httpd-error.log" +LogLevel warn + +# set up the CGI script directory +<Directory "${TestRoot}/cgi"> + AllowOverride None + Options None + Require all granted + Options +ExecCGI + AddHandler cgi-script .cgi +</Directory> + +Include etc/apache24/Includes/*.conf</programlisting> + + <para>Inicie o servidor web com</para> + + <screen><prompt>#</prompt> <userinput>service apache24 onestart</userinput></screen> + + <para>O web site pode ser visualizado em <link xlink:href="http://localhost"/>. Esteja ciente de que muitos links se referem ao site real do FreeBSD por nome, e esses links ainda levar para o site externo em vez da versão de teste local. O teste completo do web site local exigirá a configuração temporária do <acronym>DNS</acronym> para que o endereço <literal>www.FreeBSD.org</literal> seja resolvido como <literal>localhost</literal> ou o endereço <acronym>IP</acronym> local.</para> + </example> + + <example xml:id="the-website-examples-buildinstall"> + <title>Compile e Instale o Web Site</title> + + <para>Compile o web site e todos os documentos como usuário <systemitem class="username">jru</systemitem>. Instale os arquivos finais como <systemitem class="username">root</systemitem> no diretório padrão, <filename>/root/public_html</filename>:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput> +<prompt>%</prompt> <userinput>make all</userinput> +<prompt>%</prompt> <userinput>su -</userinput> +Password: +<prompt>#</prompt> <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput> +<prompt>#</prompt> <userinput>make install</userinput></screen> + </example> + + <para>O processo de instalação não exclui nenhum arquivo antigo ou desatualizado que existia anteriormente no mesmo diretório. Se uma nova cópia do web site for criada e instalada todos os dias, esse comando localizará e excluirá todos os arquivos que não foram atualizados em três dias:</para> + + <screen><prompt>#</prompt> <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="xml-primer"> + <title>Primer XML</title> + + <para>A maioria das documentações do <acronym>FDP</acronym> é escrita com linguagens markup baseadas em <acronym>XML</acronym>. Este capítulo explica o que isso significa, como ler e entender os arquivos fontes da documentação e as técnicas de <acronym>XML</acronym> utilizadas.</para> + + <para>Partes desta seção foram inspiradas por Mark Galassi's <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</link>.</para> + + <sect1 xml:id="xml-primer-overview"> + <title>Visão Geral</title> + + <para>Nos primórdios da era computacional, o texto eletrônico era simples. Havia poucos conjuntos de caracteres como <acronym>ASCII</acronym> ou <acronym>EBCDIC</acronym>, e apenas isso. Texto era texto, e o que você lia era realmente o texto que você tinha. Sem frescuras, sem formatação, sem inteligência.</para> + + <para>Inevitavelmente, isso não era suficiente. Quando o texto está em um formato utilizável por computadores, espera-se que eles possam usá-lo e manipulá-lo de maneira inteligente. Os autores querem indicar que certas frases devem ser enfatizadas, adicionadas a um glossário ou transformadas em hiperlinks. Os nomes dos arquivos podem ser apresentados em uma fonte de estilo <quote>typewriter</quote> para exibição na tela do computador, ou como <quote>itálico</quote> quando impressos, ou qualquer outra opção dentre uma infinidade de opções para apresentação.</para> + + <para>Esperava-se que a Inteligência Artificial (IA) facilitasse isso. O computador leria o documento e identificaria automaticamente frases-chave, nomes de arquivos, textos que o leitor deveria digitar, exemplos e outros tipos. Infelizmente, na vida real não foi dessa forma, e os computadores ainda precisam de assistência antes que possam processar o texto de maneira significativa.</para> + + <para>Mais precisamente, eles precisam de ajuda para identificar o que é o quê. Considere este texto:</para> + + <blockquote> + <para>Para remover <filename>/tmp/foo</filename>, use <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <screen><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen> + </blockquote> + + <para>É fácil identificar quais partes são nomes de arquivos, quais são comandos a serem digitados, quais partes são referências a páginas de manual e assim por diante. Mas o computador que processa o documento não consegue. Para isso, precisamos utilizar markup.</para> + + <para><quote>Markup</quote> é geralmate utilizado assim <quote>adicionando valor</quote> ou <quote>aumentando o custo</quote>. O termo tem seus significados realçados quando aplicado ao texto. Markup é um texto adicional incluído no documento, diferenciado de alguma forma do conteúdo do documento, para que os programas que processam o documento possam ler a marcação e utiliza-la ao tomar decisões sobre o documento. Os editores podem ocultar o markup do usuário, para que este não se distraia com ela.</para> + + <para>A informação extras armazenada no markup <emphasis>adiciona valor</emphasis> ao documento. Adicionar markup ao documento normalmente deve ser feito por uma pessoa - afinal, se os computadores pudessem reconhecer o texto suficientemente bem para adicionar a markup, não haveria necessidade de utilizar markup. Isto <emphasis>aumenta o custo</emphasis> (o esforço necessário) para criar algum documento.</para> + + <para>O exemplo anterior é representado neste documento da seguinte forma:</para> + + <programlisting><tag class="starttag">para</tag>Para remover <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag> + +<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> + + <para>O markup é claramente separado do conteúdo.</para> + + <para>As linguagens markup definem o que as marcações significam e como elas devem ser interpretadas.</para> + + <para>Claro, uma linguagem markup pode não ser suficiente. Uma linguagem markup para documentação técnica tem requisitos muito diferentes de uma linguagem markup destinada a receitas de culinária. Isso, por sua vez, seria muito diferente de uma linguagem markup utilizada para descrever uma poesia. O que é realmente necessário é uma primeira linguagem utilizada para escrever essas outras linguagens markup. Uma <emphasis>meta linguagem markup</emphasis>.</para> + + <para>É exatamente isso que a eXtensible Markup Language (<acronym>XML</acronym>) é. Muitas linguagens markup foram escritas em <acronym>XML</acronym>, incluindo as duas mais utilizadas pelo <acronym>FDP</acronym>, <acronym>XHTML</acronym> e DocBook.</para> + + <para>Cada definição de idioma é mais apropriadamente chamada de gramática, vocabulário, esquema ou Definição de Tipo de Documento (<acronym>DTD</acronym>). Existem vários idiomas para especificar uma gramática <acronym>XML</acronym> ou um <emphasis>schema</emphasis>.</para> + + <para xml:id="xml-primer-validating">Um schema é uma especificação <emphasis>completa</emphasis> de todos os elementos que podem ser utilizados, a ordem em que devem aparecer, quais elementos são obrigatórios, quais são opcionais e assim por diante. Isso torna possível escrever um <acronym>XML</acronym> <emphasis>parser</emphasis> que lê tanto o schema quanto um documento que afirma estar em conformidade com o schema. O parser pode confirmar se todos os elementos exigidos pelo vocabulário estão ou não na ordem correta do documento ou se há algum erro no markup. Isto é normalmente conhecido como a <quote>valiidação do documento</quote>.</para> + + <note> + <para>A validação confirma se a escolha dos elementos, sua ordenação e assim por diante estão em conformidade com os listados na gramática. Ela <emphasis>não</emphasis> valida se o markup <emphasis>correto</emphasis> foi utilizado no conteúdo. Se todos os nomes de arquivo em um documento fossem marcados como sendo nomes de função, o analisador não sinalizaria isso como um erro (supondo, é claro, que o schema define elementos para nomes de arquivos e funções e que eles possam aparecer no mesmo local).</para> + </note> + + <para>A maioria das contribuições no Projeto de Documentação utilizará markup <acronym>XHTML</acronym> ou DocBook, em vez de alterações nos schemas. Por esse motivo, este livro não abordará como escrever um vocabulário.</para> + </sect1> + + <sect1 xml:id="xml-primer-elements"> + <title>Elementos, Tags e Atributos</title> + + <para>Todos os vocabulários escritos em <acronym>XML</acronym> compartilham certas características. Isso não surpreende, pois a filosofia por trás do <acronym>XML</acronym> inevitavelmente irá transparecer. Uma das manifestações mais óbvias desta filosofia é a do <emphasis>conteúdo</emphasis> e dos <emphasis>elementos</emphasis>.</para> + + <para>A documentação, seja uma única página web ou um livro extenso, é considerada como conteúdo. Este conteúdo é então dividido e subdividido em elementos. A finalidade de adicionar markup é nomear e identificar os limites desses elementos para processamento futuro.</para> + + <para>Por exemplo, considere um livro típico. No maior nível, o livro é um elemento. Este elemento <quote>livro</quote> contém obviamente capítulos, que podem ser considerados elementos também. Cada capítulo conterá mais elementos, como parágrafos, citações e notas de rodapé. Cada parágrafo pode conter outros elementos, identificando o conteúdo que foi um discurso direto ou o nome de um personagem na história.</para> + + <para>Pode ser útil pensar nisso como um conteúdo por <quote>pedaços</quote>. No nível mais alto é um pedaço, o livro. Olhando um pouco mais, encontra-se mais pedaços, os capítulos individuais. Estes são segmentados em parágrafos, notas de rodapé, nomes de caracteres e assim por diante.</para> + + <para>Observe como essa diferenciação entre diferentes elementos do conteúdo pode ser feita sem recorrer a quaisquer termos <acronym>XML</acronym>. É realmente surpreendentemente simples. Isso pode ser feito com uma caneta marca-texto e um livro impresso, usando cores diferentes para indicar diferentes partes do conteúdo.</para> + + <para>É claro que não temos um marca-texto eletrônico, então precisamos de outra maneira de indicar a qual elemento cada parte do conteúdo pertence. Em idiomas escritos em <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, e outros) isto é feito por meio de <emphasis>tags</emphasis>.</para> + + <para>Uma tag é usada para identificar onde um determinado elemento começa e onde o elemento termina. <emphasis>A tag não faz parte do próprio elemento</emphasis>. Como cada gramática foi normalmente escrita para marcar tipos específicos de informação, cada um reconhecerá elementos diferentes e, portanto, terá nomes diferentes para as tags.</para> + + <para>Para um elemento chamado <replaceable>nome-do-elemento</replaceable>, a tag inicial normalmente se parecerá com <tag class="starttag"><replaceable>nome-do-elemento</replaceable></tag>. A tag de fechamento correspondente para este elemento é <tag class="endtag"><replaceable>nome-do-elemento</replaceable></tag>.</para> + + <example> + <title>Utilizando um Elemento (Tag Inicial e Final)</title> + + <para><acronym>XHTML</acronym> possui um elemento para indicar que o conteúdo incluído pelo elemento é um parágrafo, chamado <tag>p</tag>.</para> + + <programlisting><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for + the 'p' element, and it will end with the end tag for the 'p' + element.<tag class="endtag">p</tag> + +<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting> + </example> + + <para>Alguns elementos não possuem conteúdo. Por exemplo, em <acronym>XHTML</acronym>, uma linha horizontal pode ser incluída no documento. Para estes elementos <quote>vazios</quote>, <acronym>XML</acronym> trouxe um formato abreviado que é completamente equivalente à versão de duas tags:</para> + + <example> + <title>Usando um Elemento Sem Conteúdo</title> + + <para><acronym>XHTML</acronym> tem um elemento para indicar uma linha horizontal, chamada <tag>hr</tag>. Esse elemento não possui conteúdo, e se parece com isso:</para> + + <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="starttag">hr</tag><tag class="endtag">hr</tag> + +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> + + <para>A versão abreviada consiste em uma única tag:</para> + + <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="emptytag">hr</tag> + +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> + </example> + + <para>Como mostrado acima, os elementos podem conter outros elementos. No exemplo do livro anterior, o elemento livro continha elementos de capítulo, que por sua vez continham elementos de parágrafo, e assim por diante.</para> + + <example> + <title>Elementos Dentro de Elementos; <tag>em</tag></title> + + <programlisting><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some + of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para>A gramática consiste em regras que descrevem quais elementos podem conter outros elementos e exatamente o que eles podem conter.</para> + + <important> + <para>As pessoas geralmente confundem os termos tags e elementos e usam os termos como se fossem intercambiáveis. Eles não são.</para> + + <para>Um elemento é uma parte conceitual do seu documento. Um elemento tem início e fim definidos. As tags marcam onde o elemento começa e termina.</para> + + <para>Quando este documento (ou qualquer pessoa com conhecimento sobre <acronym>XML</acronym>) refere-se a <quote>a <tag class="starttag">p</tag> tag</quote> significa o texto literal que consiste nos três caracteres <literal><</literal>, <literal>p</literal>, e <literal>></literal>. Mas a frase <quote>o elemento <tag>p</tag></quote> refere-se ao elemento inteiro.</para> + + <para>Essa distinção <emphasis>é</emphasis> muito sutil. Mas tenha isso em mente.</para> + </important> + + <para>Elementos podem ter atributos. Um atributo tem um nome e um valor e é usado para adicionar informações extras ao elemento. Isso pode ser uma informação que indica como o conteúdo deve ser renderizado ou pode ser algo que identifica exclusivamente essa ocorrência do elemento ou isso pode ser outra coisa também.</para> + + <para>Os atributos de um elemento são escritos <emphasis>dentro</emphasis> da tag de início para aquele elemento, e toma o formato <literal><replaceable>nome-do-atributo</replaceable>="<replaceable>valor-do-atributo</replaceable>"</literal>.</para> + + <para>Em <acronym>XHTML</acronym>, o elemento <tag>p</tag> tem um atributo chamado <tag class="attribute">align</tag>, que sugere um alinhamento (justificação) do parágrafo para o programa exibindo o <acronym>XHTML</acronym>.</para> + + <para>O atributo <tag class="attribute">align</tag> pode ter um dos quatro valores definidos, <literal>left</literal>, <literal>center</literal>, <literal>right</literal> e <literal>justify</literal>. Se o atributo não for especificado, o padrão será <literal>left</literal>.</para> + + <example> + <title>Usando um Elemento com um Atributo</title> + + <programlisting><tag class="starttag">p align="left"</tag>The inclusion of the align attribute + on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag> + +<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting> + </example> + + <para>Alguns atributos só aceitam valores específicos, como <literal>left</literal> ou <literal>justify</literal>. Outros permitem qualquer valor.</para> + + <example> + <title>Aspas Simples nos Atributos</title> + + <programlisting><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting> + </example> + + <para>Os valores de atributos em <acronym>XML</acronym> devem ser colocados entre aspas simples ou duplas. Aspas duplas são tradicionais. Aspas simples são úteis quando o valor do atributo contém aspas duplas.</para> + + <para>Informações sobre atributos, elementos e tags são armazenadas em arquivos de catálogo. O Projeto de Documentação usa catálogos padrão do DocBook e inclui catálogos adicionais para recursos específicos do FreeBSD. Os caminhos para os arquivos de catálogo são definidos em uma variável de ambiente para que possam ser encontradas pelas ferramentas de compilação de documentos.</para> + + <sect2 xml:id="xml-primer-elements-to-do"> + <title>Para Fazer...</title> + + <para>Antes de rodar os exemplos deste documento, instale o <package>textproc/docproj</package> pela Coleção de Ports do FreeBSD. Este é um <emphasis>meta-port</emphasis> que baixa e instala os programas padrão e arquivos de suporte necessários para o Projeto de Documentação. Os usuários de <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> devem executar o <command>rehash</command> para que o shell reconheça os novos binários depois de instalados ou efetue logout e, em seguida, faça login novamente.</para> + + <procedure> + <step> + <para>Crie <filename>example.xml</filename> e insira este texto:</para> + + <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> + + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para>Tente validar esse arquivo usando um parser <acronym>XML</acronym>.</para> + + <para>O <package>textproc/docproj</package> inclui o <link linkend="xml-primer-validating">parser</link> <command>xmllint</command>.</para> + + <para>Execute <command>xmllint</command> para validar o documento:</para> + + <screen><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput></screen> + + <para><command>xmllint</command> não retorna nada se o documento for validado com sucesso.</para> + </step> + + <step> + <para>Veja o que acontece quando os elementos obrigatórios são omitidos. Exclua a linha com as tags <tag class="starttag">title</tag> e <tag class="endtag">title</tag>, então execute novamente a validação.</para> + + <screen><prompt>%</prompt> <userinput>xmllint --valid --noout example.xml</userinput> +example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen> + + <para>Isso mostra que o erro de validação vem da linha <replaceable>cinco</replaceable> do arquivo <replaceable>example.xml</replaceable> e que o conteúdo de <tag class="starttag">head</tag> é a parte que não segue as regras da gramática <acronym>XHTML</acronym>.</para> + + <para>Em seguida, o <command>xmllint</command> mostra a linha onde o erro foi encontrado e marca a posição exata com um sinal <literal>^</literal>.</para> + </step> + + <step> + <para>Substitua o elemento <tag>title</tag>.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-doctype-declaration"> + <title>A Declaração DOCTYPE</title> + + <para>No início de cada documento pode-se especificar o nome do <acronym>DTD</acronym> ao qual o documento está em conformidade. Esta declaração DOCTYPE é usada por <acronym>XML</acronym> parsers para identificar o <acronym>DTD</acronym> e garantir que o documento esteja de acordo com ele.</para> + + <para>Uma declaração típica para um documento escrito em conformidade com a versão 1.0 do <acronym>XHTML</acronym> <acronym>DTD</acronym> se parece com isto:</para> + + <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting> + + <para>Essa linha contém vários componentes diferentes.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>O <emphasis>indicador</emphasis> mostra que esta é uma declaração <acronym>XML</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Mostra que esta é uma declaração <acronym>XML</acronym> do tipo de documento.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>Nomeia o primeiro <link linkend="xml-primer-elements">elemento</link> que aparecerá no documento.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</literal></term> + + <listitem> + <para>Lista o Identificador Público Formal (<acronym>FPI</acronym>) <indexterm> + <primary>Formal Public Identifier</primary> + </indexterm> para o <acronym>DTD</acronym> com o qual este documento está em conformidade. O <acronym>XML</acronym> parser usa isso para encontrar o <acronym>DTD</acronym> correto ao processar este documento.</para> + + <para><literal>PUBLIC</literal> não faz parte do <acronym>FPI</acronym>, mas indica ao <acronym>XML</acronym> parser como encontrar o <acronym>DTD</acronym> mencionado no <acronym>FPI</acronym>. Outras formas de informar ao <acronym>XML</acronym> parser como encontrar o <acronym>DTD</acronym> serão informadas <link linkend="xml-primer-fpi-alternatives">depois</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + + <listitem> + <para>Um nome de arquivo local ou uma <acronym>URL</acronym> para encontrar o <acronym>DTD</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Termina a declaração e retorna ao documento.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2 xml:id="doctype-declaration-fpi"> + <title>Identificadores Públicos Formais (<acronym>FPI</acronym>s)</title> + + <indexterm significance="preferred"><primary>Identificador Público Formal</primary></indexterm> + + <note> + <para xml:lang="en">It is not necessary to know this, but it is useful + background, and might help debug problems when the + <acronym>XML</acronym> processor cannot locate the + <acronym>DTD</acronym>.</para> + </note> + + <para><acronym>FPI</acronym>s devem seguir uma sintaxe específica:</para> + + <programlisting>"<replaceable>Proprietário</replaceable> +//<replaceable>Palavra-chave</replaceable> +<replaceable>Descrição</replaceable> +//<replaceable>Idioma</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Proprietário</replaceable></term> + + <listitem> + <para>O proprietário do <acronym>FPI</acronym>.</para> + + <para>O início da string identifica o proprietário do <acronym>FPI</acronym>. Por exemplo, o <acronym>FPI</acronym> <literal>"ISO 8879:1986//ENTITIES Greek Symbols//EN"</literal> lista <literal>ISO 8879:1986</literal> como sendo o proprietário para o conjunto de entidades de Símbolos Gregos. <acronym>ISO</acronym> 8879:1986 é o número na International Organization for Standardization (<acronym>ISO</acronym>) para o padrão <acronym>SGML</acronym>, o predecessor (e um superset) do <acronym>XML</acronym>.</para> + + <para>Caso contrário, essa sequência seria parecida com <literal>-//<replaceable>Proprietário</replaceable></literal> ou <literal>+//<replaceable>Proprietário</replaceable></literal> (observe que a única diferença é o <literal>+</literal> ou <literal>-</literal>).</para> + + <para>Se a string começar com <literal>-</literal>, a informação do proprietário não é registrada, com o <literal>+</literal> identifica como registrada.</para> + + <para>A <acronym>ISO</acronym> 9070:1991 define como os nomes registrados são gerados. Pode ser derivado do número de uma publicação <acronym>ISO</acronym>, um código <acronym>ISBN</acronym> ou um código de organização atribuído de acordo com a <acronym>ISO</acronym> 6523. Além disso, uma autoridade de registro poderia ser criada para atribuir nomes registrados. O conselho da <acronym>ISO</acronym> delegou isso ao American National Standards Institute (<acronym>ANSI</acronym>).</para> + + <para>Como o Projeto FreeBSD não foi registrado, a string de propriedade é <literal>-//FreeBSD</literal>. Como visto no exemplo, a <acronym>W3C</acronym> também não é registrada.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Palavra-chave</replaceable></term> + + <listitem> + <para>Existem várias palavras-chave que indicam o tipo de informação no arquivo. Algumas das palavras-chave mais comuns são <literal>DTD</literal>, <literal>ELEMENT</literal>, <literal>ENTITIES</literal> e <literal>TEXT</literal>. <literal>DTD</literal> é usada apenas para arquivos <acronym>DTD</acronym>, <literal>ELEMENT</literal> é normalmente usada para fragmentos <acronym>DTD</acronym> que contêm apenas declarações de elementos ou entidades. <literal>TEXT</literal> é usada para conteúdo <acronym>XML</acronym> (texto e tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Descrição</replaceable></term> + + <listitem> + <para>Qualquer descrição pode ser informada no conteúdo deste campo. Isso pode incluir números de versão ou qualquer texto curto que tenha significado e seja exclusivo para o sistema <acronym>XML</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Idioma</replaceable></term> + + <listitem> + <para>Um código de dois caracteres <acronym>ISO</acronym> que identifica o idioma nativo do arquivo. <literal>EN</literal> é usado para o Inglês.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3 xml:id="doctype-declaration-fpi-catalog"> + <title>Arquivos <filename>catalog</filename></title> + + <para>Com a sintaxe acima, um <acronym>XML</acronym> parser precisa ter alguma forma de transformar o <acronym>FPI</acronym> no nome do arquivo que contém o <acronym>DTD</acronym>. Um arquivo de catálogo (normalmente chamado de <filename>catalog</filename>) contém linhas que mapeiam <acronym>FPI</acronym>s para nomes de arquivos. Por exemplo, se o arquivo de catálogo continha a linha:</para> + +<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog --> + + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> + + <para>O <acronym>XML</acronym> parser sabe que o <acronym>DTD</acronym> é chamado de <filename>transitional.dtd</filename> no subdiretório <filename>1.0</filename> do diretório que continha <filename>catalog</filename>.</para> + + <para>Examine o conteúdo de <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. Este é o arquivo de catálogo dos <acronym>XHTML</acronym> <acronym>DTD</acronym> s que foram instalados como parte do port <package>textproc/docproj</package> .</para> + </sect3> + </sect2> + + <sect2 xml:id="xml-primer-fpi-alternatives"> + <title>Alternativas para <acronym>FPI</acronym> s</title> + + <para>Em vez de usar uma <acronym>FPI</acronym> para indicar o <acronym>DTD</acronym> ao qual o documento está em conformidade (e, portanto, qual arquivo no sistema contém o <acronym>DTD</acronym>), o arquivo pode ser explicitamente especificado.</para> + + <para>A sintaxe é um pouco diferente:</para> + + <programlisting><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting> + + <para>A palavra-chave <literal>SYSTEM</literal> indica que o <acronym>XML</acronym> parser deve localizar o <acronym>DTD</acronym> de uma maneira específica no sistema. Isso normalmente (mas nem sempre) significa que o <acronym>DTD</acronym> será fornecido como um nome de arquivo.</para> + + <para>Usando <acronym>FPI</acronym>s é preferível por razões de portabilidade. Se o identificador <literal>SYSTEM</literal> for usado, então o <acronym>DTD</acronym> deve ser fornecido e mantido no mesmo local para todos.</para> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-xml-escape"> + <title>De Volta para o <acronym>XML</acronym></title> + + <para>Algumas das sintaxes subjacentes do <acronym>XML</acronym> podem ser úteis em documentos. Por exemplo, os comentários podem ser incluídos no documento e serão ignorados pelo parser. Os comentários são inseridos usando a sintaxe <acronym>XML</acronym>. Outros usos para a sintaxe <acronym>XML</acronym> serão mostrados mais tarde.</para> + + <para>Seções <acronym>XML</acronym> começam com uma tag <literal><!</literal> e terminam com <literal>></literal>. Essas seções contêm instruções para o parser em vez de elementos do documento. Tudo entre essas tags são sintaxe <acronym>XML</acronym>. A declaração <link linkend="xml-primer-doctype-declaration">DOCTYPE</link> mostrada anteriormente é um exemplo da sintaxe <acronym>XML</acronym> incluída no documento.</para> + + </sect1> + + <sect1 xml:id="xml-primer-comments"> + <title>Comentários</title> + + <para>Um documento <acronym>XML</acronym> pode conter comentários. Eles podem aparecer em qualquer lugar, desde que não estejam dentro de tags. Eles até são permitidos em alguns locais dentro do <acronym>DTD</acronym> (por exemplo, entre <link linkend="xml-primer-entities">declarações de entidade</link>).</para> + + <para>Os comentários <acronym>XML</acronym> começam com a string <quote><literal><!--</literal></quote> e terminam com a string <quote><literal>--></literal></quote>.</para> + + <para>Aqui estão alguns exemplos de comentários válidos de <acronym>XML</acronym>:</para> + + <example> + <title><acronym>XML</acronym> Comentários Genéricos</title> + + <programlisting><!-- This is inside the comment --> + +<!--This is another comment--> + +<!-- This is how you + write multiline comments --> + +<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting> + </example> + + <para>Os comentários <acronym>XML</acronym> podem conter quaisquer strings, exceto <quote><literal>--</literal></quote>:</para> + + <example> + <title>Comentário <acronym>XML</acronym> Incorreto</title> + + <programlisting><!-- This comment--is wrong --></programlisting> + </example> + + <sect2 xml:id="xml-primer-comments-to-do"> + <title>Para Fazer...</title> + + <procedure> + <step> + <para>Adicione alguns comentários ao arquivo <filename>example.xml</filename> e depois o valide utilizando o <command>xmllint</command>.</para> + </step> + + <step> + <para>Adicione alguns comentários inválidos ao arquivo <filename>example.xml</filename> e veja as mensagens de erros que o <command>xmllint</command> irá retornar quando encontrar algum comentário inválido.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-entities"> + <title>Entidades</title> + + <para>Entidades são um mecanismo para atribuir nomes a partes do conteúdo. À medida que um <acronym>XML</acronym> parser processa um documento, qualquer entidade encontrada é substituída pelo conteúdo da entidade.</para> + + <para>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>.</para> + + <para>Existem dois tipos de entidades para duas situações diferentes: <emphasis>entidades gerais</emphasis> e <emphasis>entidades de parâmetros</emphasis>.</para> + + <sect2 xml:id="xml-primer-general-entities"> + <title>Entidades Gerais</title> + + <para>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>.</para> + + <para>Para incluir o texto de uma entidade geral no documento, inclua <literal>&<replaceable>nome-da-entidade</replaceable>;</literal> no texto. Por exemplo, considere uma entidade geral chamada <literal>current.version</literal>, que se expande para o número da versão atual de um produto. Para usá-la no documento, escreva:</para> + + <programlisting><tag class="starttag">para</tag>The current version of our product is + &current.version;.<tag class="endtag">para</tag></programlisting> + + <para>Quando o número da versão for alterado, edite a definição da entidade geral, substituindo o valor. Em seguida, reprocesse o documento.</para> + + <para>Entidades gerais também podem ser usadas para inserir caracteres que não poderiam ser incluídos em um documento <acronym>XML</acronym>. Por exemplo, <literal><</literal> e <literal>&</literal> normalmente não podem aparecer em um documento <acronym>XML</acronym>. O <acronym>XML</acronym> parser vê o símbolo <literal><</literal> como o início de uma tag. Da mesma forma, quando o símbolo <literal>&</literal> é visto, espera-se que o próximo texto seja um nome de entidade.</para> + + <para>Esses símbolos podem ser incluídos usando duas entidades gerais predefinidas: <literal>&lt;</literal> e <literal>&amp;</literal>.</para> + + <para>Entidades gerais só podem ser definidas dentro de um contexto <acronym>XML</acronym>. Tais definições geralmente são feitas imediatamente após a declaração DOCTYPE.</para> + + <example> + <title>Definindo Entidades Gerais</title> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]></programlisting> + + <para>A declaração DOCTYPE foi estendida adicionando um colchete no final da primeira linha. As duas entidades são então definidas nas próximas duas linhas, o colchete é fechado e, em seguida, a declaração DOCTYPE é fechada.</para> + + <para>Os colchetes são necessários para indicar que o DTD indicado pela declaração DOCTYPE está sendo estendido.</para> + </example> + </sect2> + + <sect2 xml:id="xml-primer-parameter-entities"> + <title>Entidades de Parâmetro</title> + + <para>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>.</para> + + <para xml:lang="en">Parameter entity definitions are similar to those for + general entities. However, parameter entities are included + with + <literal>%<replaceable>entity-name</replaceable>;</literal>. + The definition also includes the <literal>%</literal> between + the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <para>Para memorizar, lembre que entidade de<quote><emphasis>P</emphasis>arâmetro utiliza o símbolo de <emphasis>P</emphasis>orcentagem</quote>.</para> + + <example> + <title>Definindo Entidades de Parâmetro</title> + + <programlisting xml:lang="en"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % entity "<!ENTITY version '1.0'>"> +<!-- use the parameter entity --> +%entity; +]></programlisting> + </example> + + <para xml:lang="en">At first sight, parameter entities do not look very + useful, but they make it possible to <link linkend="xml-primer-include">include other files</link> into + an XML document.</para> + </sect2> + + <sect2 xml:id="xml-primer-to-do"> + <title>Para Fazer...</title> + + <procedure> + <step> + <para>Adicione uma entidade geral ao arquivo <filename>example.xml</filename>.</para> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <!-- There may be some comments in here as well --> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> + + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> + + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para>Valide o documento usando o <command>xmllint</command>.</para> + </step> + + <step> + <para>Carregue <filename>example.xml</filename> em um navegador web. Ele pode ter que ser copiado para o <filename>example.html</filename> antes que o navegador o reconheça como um documento <acronym>XHTML</acronym>.</para> + + <para>Navegadores mais antigos com parsers simples podem não renderizar esse arquivo conforme o esperado. A referência de entidade <literal>&version;</literal> pode não ser substituída pelo número da versão, ou o fechamento de contexto <acronym>XML</acronym> <literal>]></literal> pode não ser reconhecido e em vez disso, apresentado literalmente.</para> + </step> + + <step> + <para>A solução é <emphasis>normalizar</emphasis> o documento com um normalizador <acronym>XML</acronym>. O normalizador lê um <acronym>XML</acronym> válido e grava outro <acronym>XML</acronym> igualmente válido. Uma maneira pela qual o normalizador transforma a entrada é expandindo todas as referências de entidade no documento, substituindo as entidades pelo texto que elas representam.</para> + + <para>O <command>xmllint</command> pode ser usado para isso. Ele também tem a opção de remover a seção inicial <acronym>DTD</acronym> para que <literal>]></literal> não confunda os navegadores:</para> + + <screen><prompt>%</prompt> <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen> + + <para>Uma cópia normalizada do documento com entidades expandidas é produzida em <filename>example.html</filename>, pronta para ser carregada em um navegador web.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-include"> + <title>Usando Entidades para Incluir Arquivos</title> + + <para>Ambas as entidades <link linkend="xml-primer-general-entities">geral</link> e <link linkend="xml-primer-parameter-entities">parâmetro</link> são particularmente úteis para incluir um arquivo dentro de outro .</para> + + <sect2 xml:id="xml-primer-include-using-gen-entities"> + <title>Usando Entidades Gerais para Incluir Arquivos</title> + + <para>Considere algum conteúdo para um livro <acronym>XML</acronym> organizado em arquivos, um arquivo por capítulo, chamado <filename>chapter1.xml</filename>, <filename>chapter2.xml</filename> e assim por diante, com um <filename>book.xml</filename> que conterá esses capítulos.</para> + + <para>Para usar o conteúdo desses arquivos como valores para entidades, eles são declarados com a palavra-chave <literal>SYSTEM</literal>. Isso direciona o <acronym>XML</acronym> parser a incluir o conteúdo do arquivo nomeado como o valor da entidade.</para> + + <example> + <title>Usando Entidades Gerais para Incluir Arquivos</title> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"> +<!-- And so forth --> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <!-- Use the entities to load in the chapters --> + + &chapter.1; + &chapter.2; + &chapter.3; +<tag class="endtag">html</tag></programlisting> + </example> + + <warning> + <para>Ao usar entidades gerais para incluir outros arquivos em um documento, os arquivos que estão sendo incluídos (<filename> chapter1.xml</filename>, <filename>chapter2.xml</filename> e assim por diante)<emphasis> não devem </emphasis>começar com uma declaração DOCTYPE. Este é um erro de sintaxe porque as entidades são constructors de baixo nível e são transformadas antes que qualquer análise ocorra.</para> + </warning> + </sect2> + + <sect2 xml:id="xml-primer-include-parameter"> + <title>Usando Entidades de Parâmetro para Incluir Arquivos</title> + + <para>As entidades de parâmetro só podem ser usadas dentro de um contexto <acronym>XML</acronym>. A inclusão de um arquivo em um contexto <acronym>XML</acronym> pode ser usada para garantir que as entidades gerais sejam reutilizáveis.</para> + + <para>Suponha que haja muitos capítulos no documento, e esses capítulos foram reutilizados em dois livros diferentes, cada livro organizando os capítulos de maneira diferente.</para> + + <para>As entidades podem ser listadas no topo de cada livro, mas isso rapidamente se torna difícil de gerenciar.</para> + + <para>Em vez disso, coloque as definições gerais da entidade em um arquivo e use uma entidade de parâmetro para incluir esse arquivo no documento.</para> + + <example> + <title>Usando Entidades de Parâmetro para Incluir Arquivos</title> + + <para>Coloque as definições de entidade em um arquivo separado chamado <filename>chapters.ent</filename> contendo este texto:</para> + + <programlisting><!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting> + + <para>Crie uma entidade de parâmetro para se referir ao conteúdo do arquivo. Em seguida, use a entidade de parâmetro para carregar o arquivo no documento, o que tornará todas as entidades gerais disponíveis para uso. Em seguida, use as entidades gerais como antes:</para> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!-- Define a parameter entity to load in the chapter general entities --> +<!ENTITY % chapters SYSTEM "chapters.ent"> + +<!-- Now use the parameter entity to load in this file --> +%chapters; +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + &chapter.1; + &chapter.2; + &chapter.3; +<tag class="endtag">html</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="xml-primer-include-parameter-to-do"> + <title>Para Fazer...</title> + + <sect3 xml:id="xml-primer-include-general-entities-include"> + <title>Use Entidades Gerais para Incluir Arquivos</title> + + <procedure> + <step> + <para>Crie três arquivos, <filename>para1.xml</filename>, <filename>para2.xml</filename> e <filename>para3.xml</filename>.</para> + + <para>Coloque conteúdo como este em cada arquivo:</para> + + <programlisting><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting> + </step> + + <step> + <para>Edite <filename>example.xml</filename> para que fique assim:</para> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + + &para1; + &para2; + &para3; + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para>Gere <filename>example.html</filename> ao normalizar <filename>example.xml</filename>.</para> + + <screen><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para>Carregue <filename>example.html</filename> no navegador web e confirme se os arquivos <filename>para<replaceable>n</replaceable>.xml</filename> foram incluídos em <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3 xml:id="xml-primer-include-parameter-entities-include"> + <title>Use Entidades de Parâmetro para Incluir Arquivos</title> + + <note> + <para>As etapas anteriores devem ser concluídas antes dessa etapa.</para> + </note> + + <procedure> + <step> + <para>Edite <filename>example.xml</filename> para que fique assim:</para> + + <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % entities SYSTEM "entities.ent"> %entities; +]> + +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> + + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + + &para1; + &para2; + &para3; + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </step> + + <step> + <para>Crie um novo arquivo chamado <filename>entities.ent</filename> com este conteúdo:</para> + + <programlisting><!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> + </step> + + <step> + <para>Gere <filename>example.html</filename> ao normalizar <filename>example.xml</filename>.</para> + + <screen><prompt>%</prompt> <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para>Carregue <filename>example.html</filename> no navegador web e confirme se os arquivos <filename>para<replaceable>n</replaceable>.xml</filename> foram incluídos em <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-marked-sections"> + <title>Seções Marcadas</title> + + <para><acronym>XML</acronym> fornece um mecanismo para indicar que partes específicas do documento devem ser processadas de uma maneira especial. Estes são chamados de <quote>seções marcadas</quote>.</para> + + <example> + <title>Estrutura de uma Seção Marcada</title> + + <programlisting><![<replaceable>KEYWORD</replaceable>[ + Contents of marked section +]]></programlisting> + </example> + + <para>Como esperado de um construct <acronym>XML</acronym>, uma seção marcada começa com <literal><!</literal>.</para> + + <para>O primeiro colchete inicia a seção marcada.</para> + + <para><replaceable>KEYWORD</replaceable> descreve como esta seção marcada deve ser processada pelo parser.</para> + + <para>O segundo colchete indica o início do conteúdo da seção marcada.</para> + + <para>A seção marcada é concluída, fechando os dois colchetes e, em seguida, retornando ao contexto do documento do contexto <acronym>XML</acronym> com <literal>></literal>.</para> + + <sect2 xml:id="xml-primer-marked-section-keywords"> + <title>Palavras-chave da Seção Marcada</title> + + <sect3 xml:id="xml-primer-cdata"> + <title><literal>CDATA</literal></title> + + <para>Essas palavras-chave indicam as seções marcadas pelo <emphasis>modelo de conteúdo</emphasis> e permitem que você a altere do padrão.</para> + + <para>Quando um <acronym>XML</acronym> parser está processando um documento, ele acompanha o <quote>modelo de conteúdo</quote>.</para> + + <para>O modelo de conteúdo descreve o conteúdo que o parser espera ver e o que ele fará com esse conteúdo.</para> + + <para>O modelo de conteúdo <literal>CDATA</literal> é um dos mais úteis.</para> + + <para><literal>CDATA</literal> é para <quote>Dados de Caractere</quote>. Quando o parser está neste modelo de conteúdo, ele espera ver apenas caracteres. Nesse modelo, os símbolos <literal><</literal> e <literal>&</literal> perdem seu status especial e serão tratados como caracteres comuns.</para> + + <note> + <para>Ao usar <literal>CDATA</literal> em exemplos de texto marcados em <acronym>XML</acronym>, lembre-se de que o conteúdo de <literal>CDATA</literal> não é validado. O texto incluído deve ser verificado por outros meios. Por exemplo, o conteúdo poderia ser escrito em outro documento, validado e depois colado na seção <literal>CDATA</literal>.</para> + </note> + + <example> + <title>Usando uma Seção Marcada <literal>CDATA</literal></title> + + <programlisting><tag class="starttag">para</tag>Here is an example of how to include some text that contains + many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag> + symbols. The sample text is a fragment of + <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and + <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the + elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle + brackets are used so many times, it is simpler to say the whole + example is a CDATA marked section than to use the entity names for + the left and right angle brackets throughout.<tag class="endtag">p</tag> + + <tag class="starttag">ul</tag> + <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag> + <tag class="endtag">ul</tag> + + <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting> + </example> + </sect3> + + <sect3 xml:id="xml-primer-include-ignore"> + <title><literal>INCLUDE</literal> e <literal>IGNORE</literal></title> + + <para>Quando a palavra-chave é <literal>INCLUDE</literal>, o conteúdo da seção marcada será processado. Quando a palavra-chave é <literal>IGNORE</literal>, a seção marcada é ignorada e não será processada. Não aparecerá na saída.</para> + + <example> + <title>Usando <literal>INCLUDE</literal> e <literal>IGNORE</literal> em Seções Marcadas</title> + + <programlisting><![INCLUDE[ + This text will be processed and included. +]]> + +<![IGNORE[ + This text will not be processed or included. +]]></programlisting> + </example> + + <para>Por si só, isso não é muito útil. O texto a ser removido do documento pode ser recortado ou estar em forma de comentários.</para> + + <para>Ele se torna mais útil quando controlado por <link linkend="xml-primer-parameter-entities">entidades de parâmetro</link>, mas esse uso é limitado a arquivos de entidades.</para> + + <para>Por exemplo, suponha que a documentação tenha sido produzida em uma versão impressa e em uma versão eletrônica. Algum texto extra é desejado no conteúdo da versão eletrônica que não deveria aparecer na cópia impressa.</para> + + <para>Crie um arquivo de entidade que defina entidades gerais para incluir cada capítulo e proteja essas definições com uma entidade de parâmetro que pode ser definida como <literal>INCLUDE</literal> ou <literal>IGNORE</literal> para controlar se a entidade está definida . Após essas definições de entidades gerais condicionais, coloque mais uma definição para cada entidade geral para defini-las como um valor vazio. Essa técnica faz uso do fato de que as definições de entidade não podem ser substituídas, mas a primeira definição sempre entra em vigor. Assim, a inclusão do capítulo é controlada com a entidade de parâmetro correspondente. Definido como <literal>INCLUDE</literal>, a primeira definição de entidade geral será lida e a segunda será ignorada. Definido como <literal>IGNORE</literal>, a primeira definição será ignorada e a segunda será utilizada.</para> + + <example> + <title>Usando uma Entidade de Parâmetro para Controlar uma Seção Marcada</title> + + <programlisting><!ENTITY % electronic.copy "INCLUDE"> + +<![%electronic.copy;[ +<!ENTITY chap.preface SYSTEM "preface.xml"> +]]> + +<!ENTITY chap.preface ""></programlisting> + + <para>Ao produzir a versão impressa, altere a definição do parâmetro de entidade para:</para> + + <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> + </example> + </sect3> + </sect2> + + <sect2 xml:id="xml-primer-marked-section-keywords-to-do"> + <title>Para Fazer...</title> + + <procedure> + <step> + <para>Modifique <filename>entidades.ent</filename> para conter o seguinte texto:</para> + + <programlisting><!ENTITY version "1.1"> +<!ENTITY % conditional.text "IGNORE"> + +<![%conditional.text;[ +<!ENTITY para1 SYSTEM "para1.xml"> +]]> + +<!ENTITY para1 ""> + +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> + </step> + + <step> + <para>Normalize <filename>example.xml</filename> e observe que o texto condicional não está presente no documento de saída. Altere o parâmetro de entidade para <literal>INCLUDE</literal> e gere novamente o documento normalizado, dessa forma e o texto aparecerá novamente. Esse método faz sentido se houver mais partes condicionais dependendo da mesma condição. Por exemplo, para controlar a geração de texto impresso ou on-line.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-conclusion"> + <title>Conclusão</title> + + <para>Essa é a conclusão deste primer <acronym>XML</acronym>. Por razões de espaço e complexidade, vários assuntos não foram cobertos bem afundo. No entanto, as seções anteriores abrangem o suficiente de <acronym>XML</acronym> para apresentar a organização da documentação do <acronym>FDP</acronym>.</para> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="xhtml-markup"> + <title><acronym>XHTML</acronym> Markup</title> + + <sect1 xml:id="xhtml-markup-introduction"> + <title>Introdução</title> + + <para>Este capítulo descreve o uso da linguagem <acronym>XHTML</acronym> markup usada no site do FreeBSD.</para> + + <para><acronym>XHTML</acronym> é a versão <acronym>XML</acronym> da HyperText Markup Language, a linguagem markup escolhida na World Wide Web. Mais informações podem ser encontradas em <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> + + <para><acronym>XHTML</acronym> é usado para escrever páginas no site do FreeBSD. Geralmente não é usado para escrever outra documentação, uma vez que o DocBook oferece um conjunto muito mais rico de elementos para se escolher. Consequentemente, as páginas <acronym>XHTML</acronym> normalmente só serão encontradas ao escrever para o web site.</para> + + <para>O <acronym>HTML</acronym> passou por várias versões. A versão compatível com <acronym>XML</acronym> descrita aqui é chamada <acronym>XHTML</acronym>. A versão mais recente generalizada é o <acronym>XHTML</acronym> 1.0, disponível nas variantes <emphasis>strict</emphasis> e <emphasis>transitional</emphasis>.</para> + + <para>Os <acronym>XHTML</acronym> <acronym>DTDs</acronym> estão disponíveis na Coleção de Ports em <package>textproc/xhtml</package>. Eles são automaticamente instalados pelo port <package>textproc/docproj</package>.</para> + + <note> + <para>Isto <emphasis>não</emphasis> é uma lista completa de elementos, uma vez que isso apenas repetiria a documentação de <acronym>XHTML</acronym>. O objetivo é listar os elementos mais utilizados. Por favor, poste perguntas sobre elementos ou usos não abordados aqui na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de discussão do projeto de documentação do FreeBSD</link>.</para> + </note> + + <note> + <title>Inline Versus Block</title> + + <para>No restante deste documento, ao descrever elementos, <emphasis>inline</emphasis> significa que o elemento pode estar dentro de um elemento de bloco e não causa uma quebra de linha. Um elemento <emphasis>block</emphasis>, por outro lado, causará uma quebra de linha (e outro processamento) quando for encontrado.</para> + </note> + </sect1> + + <sect1 xml:id="xhtml-markup-fpi"> + <title>Identificador Público Formal (<acronym>FPI</acronym>)</title> + + <para>Existem vários <acronym>XHTML</acronym> <acronym>FPI</acronym>s, dependendo da versão, ou da <emphasis>versão</emphasis> do <acronym>XHTML</acronym> ao qual um documento está em conformidade. A maioria dos documentos <acronym>XHTML</acronym> no site do FreeBSD está de acordo com a versão de transição do <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>Seções de Elementos</title> + + <para>Um documento <acronym>XHTML</acronym> é normalmente dividido em duas seções. A primeira seção, chamada de <emphasis>head</emphasis>, contém meta-informações sobre o documento, como seu título, o nome do autor, o documento pai e assim por diante. A segunda seção, o<emphasis>body</emphasis>, contém o conteúdo que será exibido ao usuário.</para> + + <para>Essas seções são indicadas com os elementos <tag>head</tag> e <tag>body</tag>, respectivamente. Esses elementos estão dentro do elemento <tag>html</tag> de nível superior.</para> + + <example> + <title>Estrutura de um Documento <acronym>XHTML</acronym></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> + + … + + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> + </example> + </sect1> + + <sect1 xml:id="xhtml-markup-block-elements"> + <title>Elementos Block</title> + + <sect2 xml:id="xhtml-markup-block-elements-headings"> + <title>Cabeçalhos</title> + + <para><acronym>XHTML</acronym> tem tags para indicar títulos no documento em até seis níveis diferentes.</para> + + <para>O maior e mais importante título é <tag>h1</tag>, depois <tag>h2</tag>, seguindo até <tag>h6</tag>.</para> + + <para>O conteúdo do elemento é o texto do cabeçalho.</para> + + <example> + <title><tag>h1</tag>, <tag>h2</tag> e Outras Tags de Cabeçalho</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag> + +<!-- Document introduction goes here --> + +<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag> + +<!-- Content for the first section goes here --> + +<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag> + +<!-- Content for the first sub-section goes here --> + +<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag> + +<!-- Content for the second section goes here --></programlisting> + </example> + + <para>Geralmente, uma página <acronym>XHTML</acronym> deve ter um título de primeiro nível (<tag>h1</tag>). Nela pode conter muitos títulos de segundo nível (<tag>h2</tag>), que por sua vez podem conter muitos cabeçalhos de terceiro nível. Não deixe lacunas na numeração.</para> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-paragraphs"> + <title>Parágrafos</title> + + <para>O <acronym>XHTML</acronym> suporta um único elemento de parágrafo, <tag>p</tag>.</para> + + <example> + <title>Exemplo <tag>p</tag></title> + + <para>Uso:</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>Bloco de Citações</title> + + <para>Um bloco de citação é uma citação estendida de outro documento que aparecerá em um parágrafo separado.</para> + + <example> + <title>Exemplo <tag>blockquote</tag></title> + + <para>Uso:</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>Listas</title> + + <para>O <acronym>XHTML</acronym> pode apresentar ao usuário três tipos de listas: ordenadas, desordenadas e de definição.</para> + + <para>Entradas em uma lista ordenada serão numeradas, enquanto as entradas em uma lista não ordenada serão precedidas por marcadores. Listas de definições têm duas seções para cada entrada. A primeira seção é o termo que está sendo definido e a segunda seção é a definição.</para> + + <para>As listas ordenadas são indicadas pelo elemento <tag>ol</tag>, listas não ordenadas pelo elemento <tag>ul</tag> e listas de definição pelo elemento <tag>dl</tag>.</para> + + <para>As listas ordenadas e não ordenadas contêm listitens, indicadas pelo elemento <tag>li</tag>. Um listitem pode conter conteúdo textual ou pode ser envoltos em um ou mais elementos <tag>p</tag>.</para> + + <para>As listas de definições contêm termos de definição (<tag>dt</tag>) e descrições de definição (<tag>dd</tag>). Um termo de definição pode conter apenas elementos in-line. Uma descrição de definição pode conter outros elementos de bloco.</para> + + <example> + <title>Exemplo <tag>ul</tag> and <tag>ol</tag></title> + + <para>Uso:</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>Listas de Definição com <tag>dl</tag></title> + + <para>Uso:</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>Texto Pré-formatado</title> + + <para>Texto pré-formatado é apresentado para o usuário exatamente como está no arquivo. O texto é mostrado em uma fonte fixa. Vários espaços e quebras de linha são mostrados exatamente como estão no arquivo.</para> + + <para>Deixe o texto pré-formatado no elemento <tag>pre</tag>.</para> + + <example> + <title>Exemplo <tag>pre</tag></title> + + <para>Por exemplo, as tags <tag>pre</tag> podem ser usadas para marcar uma mensagem de email:</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 + + &lt;URL:https://people.FreeBSD.org/~nik/primer/index.html&gt; + + Comments appreciated. + + N<tag class="endtag">pre</tag></programlisting> + + <para>Tenha em mente que <literal><</literal> e <literal>&</literal> ainda são reconhecidos como caracteres especiais no texto pré-formatado. É por isso que o exemplo mostrado teve que usar <literal>&lt;</literal> em vez de <literal><</literal>. Para consistência, o <literal>&gt;</literal> também foi usado no lugar de <literal>></literal>. Fique atento com os caracteres especiais que podem aparecer no texto copiado de uma fonte de texto simples, como uma mensagem de e-mail ou código de programa.</para> + </example> + </sect2> + + <sect2 xml:id="xhtml-markup-block-elements-tables"> + <title>Tabelas</title> + + <para>Marque as informações tabulares usando o elemento <tag>table</tag>. Uma tabela consiste em uma ou mais linhas da tabela (<tag>tr</tag>), cada uma contendo uma ou mais células de dados da tabela (<tag>td</tag>). Cada célula pode conter outros elementos de bloco, como parágrafos ou listas. Também pode conter outra tabela (esse aninhamento pode repetir indefinidamente). Se a célula contiver apenas um parágrafo, o elemento <tag>p</tag> não será necessário.</para> + + <example> + <title>Uso Simples de <tag>table</tag></title> + + <para>Uso:</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>Uma célula pode abranger várias linhas e colunas adicionando os atributos <tag class="attribute">rowspan</tag> ou <tag class="attribute">colspan</tag> com valores para o número de linhas ou colunas a serem abrangido.</para> + + <example> + <title>Usando <tag class="attribute">rowspan</tag></title> + + <para>Uso:</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>Usando <tag class="attribute">colspan</tag></title> + + <para>Uso:</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>Usando <tag class="attribute">rowspan</tag> e <tag class="attribute">colspan</tag> Juntos</title> + + <para>Uso:</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> + <!-- Because the large cell on the left merges into + this row, the first <td> will occur on its + right --> + + <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>Elementos In-line</title> + + <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information"> + <title>Realçando Informação</title> + + <para>Dois níveis de ênfase estão disponíveis em <acronym>XHTML</acronym>, <tag>em</tag> e <tag>strong</tag>. <tag>em</tag> é para um nível normal de ênfase e <tag>strong</tag> indica ênfase mais forte.</para> + + <para><tag>em</tag> é normalmente renderizado em itálico e o <tag>strong</tag> é renderizado em negrito. Isso nem sempre assim e não deve ser considerado ao pé da letra. De acordo com as práticas recomendadas, as páginas web armazenam apenas informações estruturais e semânticas, e as folhas de estilo são aplicadas posteriormente a elas. Pense na semântica, não na formatação, ao usar essas tags.</para> + + <example> + <title>Exemplo <tag>em</tag> e <tag>strong</tag></title> + + <para>Uso:</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>Indicando Texto Fixo</title> + + <para>O conteúdo que deve ser renderizado em um tipo fixo de texto (typewriter) é marcado com <tag>tt</tag> (para <quote>teletype</quote>).</para> + + <example> + <title>Exemplo <tag>tt</tag></title> + + <para>Uso:</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 também são elementos in-line.</para> + </note> + + <sect3 xml:id="xhtml-markup-inline-elements-linking"> + <title>Criando Links para Outros Documentos na Web</title> + + <para>Um link aponta para uma <acronym>URL</acronym> de um documento na web. O link é indicado com a <tag>a</tag>, e o atributo <tag class="attribute">href</tag> contém a <acronym>URL</acronym> do documento de destino. O conteúdo do elemento se torna o link, indicado ao usuário, mostrando-o em uma cor diferente ou com um sublinhado.</para> + + <example> + <title>Usando <tag class="starttag">a href="..."</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">p</tag>More information is available at the + <tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting> + </example> + + <para>Esse link sempre leva o usuário ao topo do documento que foi linkado.</para> + </sect3> + + <sect3 xml:id="xhtml-markup-inline-elements-specific-parts"> + <title>Criando Links para Partes Específicas de Documentos</title> + + <para>Para linkar a um ponto específico dentro de um documento, esse documento deve incluir uma <emphasis>âncora</emphasis> no ponto desejado. As âncoras são incluídas configurando o atributo <tag class="attribute">id</tag> de um elemento para um nome. Este exemplo cria uma âncora definindo o atributo <tag class="attribute">id</tag> de um elemento <tag class="element">p</tag>.</para> + + <example> + <title>Criando uma Âncora</title> + + <para>Uso:</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 para âncoras são semelhantes aos links simples, mas incluem um símbolo <literal>#</literal> e o <acronym>ID</acronym> da âncora no final da <acronym>URL</acronym>.</para> + + <example> + <title>Criando Link para uma Parte Nomeada de um Outro Documento</title> + + <para>O exemplo <literal>samplepara</literal> é parte de um documento chamado <filename>foo.html</filename>. Um link para esse parágrafo específico no documento é construído neste exemplo.</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>Para vincular-se a uma âncora nomeada no mesmo documento, omita a <acronym>URL</acronym>do documento, e use apenas o símbolo <literal>#</literal> seguido do nome da âncora.</para> + + <example> + <title>Criando Link para uma Parte Nomeada no Mesmo Documento</title> + + <para>O exemplo <literal>samplepara</literal> reside neste documento. Para vincular a ele:</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> + + +<!-- 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 version="5.0" xml:id="docbook-markup"> + + <title>DocBook Markup</title> + + <sect1 xml:id="docbook-markup-introduction"> + <title>Introdução</title> + + <para>Este capítulo é uma introdução ao DocBook e como ele é usado na documentação do FreeBSD. O DocBook é um sistema de marcação extenso e complexo, mas o subconjunto descrito aqui abrange as partes mais usadas para a documentação do FreeBSD. Enquanto um subconjunto moderado é coberto, é impossível antecipar todas as situações. Por favor, poste questões que este documento não responde à <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de discussão do projeto de documentação do FreeBSD</link>.</para> + + <para>DocBook foi originalmente desenvolvido por HaL Computer Systems and O'Reilly & Associates para ser uma Definição de Tipo de Documento (<acronym>DTD</acronym>) para escrever documentação técnica <footnote><para>Um breve histórico pode ser encontrado em <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. Desde 1998, ele é mantido pelo <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">Comitê Técnico do DocBook</link>. Como tal, e ao contrário do LinuxDoc e do <acronym>XHTML</acronym>, o DocBook é fortemente orientado para um markup que descreve <emphasis>o que</emphasis> alguma coisa é, em vez de descrever <emphasis>como</emphasis> deve ser apresentado.</para> + + <para>O DocBook <acronym>DTD</acronym> está disponível na coleção Ports <package>textproc/docbook-xml</package>. Ele é instalado automaticamente como parte do port <package>textproc/docproj</package>.</para> + + <note> + <title>Formal Versus Informal</title> + + <para>Alguns elementos podem existir em duas formas, <emphasis>formal</emphasis> e <emphasis>informal</emphasis>. Normalmente, a versão formal do elemento consistirá em um título seguido pela versão informal do elemento. A versão informal não terá um título.</para> + </note> + + <note> + <title>Inline Versus Block</title> + + <para>No restante deste documento, ao descrever elementos, <emphasis>inline</emphasis> significa que o elemento pode estar dentro de um elemento de bloco e não causa uma quebra de linha. Um elemento <emphasis>block</emphasis>, por outro lado, causará uma quebra de linha (e outro processamento) quando for encontrado.</para> + </note> + </sect1> + + <sect1 xml:id="docbook-markup-freebsd-extensions"> + <title>Extensões do FreeBSD</title> + + <para>O Projeto de Documentação do FreeBSD estendeu o DocBook <acronym>DTD</acronym> com elementos e entidades adicionais. Essas adições servem para tornar algumas das marcações mais fáceis ou mais precisas.</para> + + <para>Ao longo deste documento, o termo <quote>DocBook</quote> é usado para indicar o DocBook <acronym>DTD</acronym> estendido do FreeBSD.</para> + + <note> + <para>A maioria dessas extensões não é exclusiva do FreeBSD, foi apenas identificado que elas eram melhorias úteis para este projeto. Se alguém de qualquer um dos outros *nix (NetBSD, OpenBSD, Linux,…) estiverem interessados em colaborar em um conjunto de extensão DocBook padrão, entre em contato com a Equipe de Engenharia de Documentação <email>doceng@FreeBSD.org</email>.</para> + </note> + + <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> + <title>Elementos do FreeBSD</title> + + <para>Os elementos adicionais do FreeBSD não estão (atualmente) na Coleção de Ports. Eles são armazenados na repositório Subversion do FreeBSD, como <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> + + <para>Os elementos específicos do FreeBSD usados nos exemplos abaixo estão claramente marcados.</para> + </sect2> + + <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> + <title>Entidades do FreeBSD</title> + + <para>Esta tabela mostra algumas das entidades mais úteis disponíveis no <acronym>FDP</acronym>. Para obter uma lista completa, consulte os arquivos <filename>*.ent</filename> em <filename>doc/share/xml</filename>.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <colspec colname="entity"/> + <colspec colname="expandsto"/> + <colspec colname="notes"/> + <thead> + <row> + <entry/> + <entry/> + <entry/> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry namest="entity" nameend="notes"><emphasis>Entidades de Nome do FreeBSD</emphasis></entry> + </row> + + <row> + <entry><literal>&os;</literal></entry> + <entry><literal>FreeBSD</literal></entry> + <entry/> + </row> + + <row> + <entry><literal>&os.stable;</literal></entry> + <entry><literal>FreeBSD-STABLE</literal></entry> + <entry/> + </row> + + <row> + <entry><literal>&os.current;</literal></entry> + <entry><literal>FreeBSD-CURRENT</literal></entry> + <entry/> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Entidades de Página de Manual</entry> + </row> + + <row> + <entry><literal>&man.ls.1;</literal></entry> + <entry><citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry>Uso: <literal>&man.ls.1; é a página de manual para o <command>ls</command>.</literal></entry> + </row> + + <row> + <entry><literal>&man.cp.1;</literal></entry> + <entry><citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry>Uso: <literal> A página de manual para <command>cp</command> é &man.cp.1;.</literal></entry> + </row> + + <row> + <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> + <entry><emphasis>link para a página de manual <replaceable>command</replaceable> na seção <replaceable>sectionnumber</replaceable></emphasis></entry> + <entry>As entidades são definidas para todas as <link xlink:href="@@URL_RELPREFIX@@/cgi/man.cgi">páginas de manual do FreeBSD</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Entidades das Listas de Email do FreeBSD</entry> + </row> + + <row> + <entry><literal>&a.doc;</literal></entry> + <entry><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">Lista de discussão do projeto de documentação do FreeBSD</link> </literal></entry> + <entry>Uso: <literal>Um link para a &a.doc;.</literal></entry> + </row> + + <row> + <entry><literal>&a.questions;</literal></entry> + <entry><literal><link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">Lista de discussão de assuntos gerais do FreeBSD</link></literal></entry> + <entry>Uso: <literal> Um link para a &a.questions;.</literal></entry> + </row> + + <row> + <entry><literal>&a.<replaceable>listname</replaceable>;</literal></entry> + <entry><emphasis>link para <replaceable>listname</replaceable></emphasis></entry> + <entry>Foram criadas entidades para todas as <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#eresources-mail">listas de email do FreeBSD</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Entidades de Link de Documento do FreeBSD</entry> + </row> + + <row> + <entry><literal>&url.books.handbook;</literal>a</entry> + <entry><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook</literal></entry> + <entry>Uso: <literal> Um link para o capítulo <link xlink:href="&url.books.handbook;/advanced-networking.html">Rede Avançado</link> do Handbook.</literal></entry> + </row> + + <row> + <entry><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> + <entry><emphasis>caminho relativo para<replaceable>bookname</replaceable></emphasis></entry> + <entry>As entidades são definidas para todos os <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/">livros FreeBSD</link>.</entry> + </row> + + <row> + <entry><literal>&url.articles.committers-guide;</literal></entry> + <entry><literal>@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide</literal></entry> + <entry>Uso: <literal>Um link para o artigo <link xlink:href="&url.articles.committers-guide;">Guia dos Committer's</link>.</literal></entry> + </row> + + <row> + <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> + <entry><emphasis>caminho relativo para <replaceable>articlename</replaceable></emphasis></entry> + <entry>As entidades são definidas para todos os <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/">artigos do FreeBSD</link></entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Outras Entidades de Sistema Operacional</entry> + </row> + + <row> + <entry><literal>&linux;</literal></entry> + <entry><trademark class="registered">Linux</trademark></entry> + <entry>O sistema operacional <trademark class="registered">Linux</trademark>.</entry> + </row> + + <row> + <entry><literal>&unix;</literal></entry> + <entry><trademark class="registered">UNIX</trademark></entry> + <entry>O sistema operacional <trademark class="registered">UNIX</trademark>.</entry> + </row> + + <row> + <entry><literal>&windows;</literal></entry> + <entry><trademark class="registered">Windows</trademark></entry> + <entry>O sistema operacional <trademark class="registered">Windows</trademark>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Entidades Diversas</entry> + </row> + + <row> + <entry><literal>&prompt.root;</literal></entry> + <entry><prompt>#</prompt></entry> + <entry>O prompt de usuário <systemitem class="username"> root </systemitem>.</entry> + </row> + + <row> + <entry><literal>&prompt.user;</literal></entry> + <entry><prompt>%</prompt></entry> + <entry>Um prompt para um usuário sem privilégios.</entry> + </row> + + <row> + <entry><literal>&postscript;</literal></entry> + <entry><trademark class="registered">PostScript</trademark></entry> + <entry>A linguagem de programação <trademark class="registered">PostScript</trademark>.</entry> + </row> + + <row> + <entry><literal>&tex;</literal></entry> + <entry><application>TeX</application></entry> + <entry>A linguagem de composição tipográfica <application>TeX</application>.</entry> + </row> + + <row> + <entry><literal>&xorg;</literal></entry> + <entry>Xorg</entry> + <entry>Xorg, Sistema X Window de código aberto.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-fpi"> + <title>Identificador Público Formal (FPI)</title> + + <para>Em conformidade com as diretrizes do DocBook, para escrever <acronym>FPI</acronym>s customizadas do DocBook, o <acronym>FPI</acronym> para o DocBook <acronym>DTD</acronym> estendido do FreeBSD é:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect1> + + <sect1 xml:id="docbook-markup-document-structure"> + <title>Estrutura do Documento</title> + + <para>O DocBook permite a documentação de estruturação de várias maneiras. O Projeto de Documentação do FreeBSD usa dois tipos principais de documentos do DocBook: o book e o article.</para> + + <para>Os livros (books) são organizados em <tag>chapter</tag> s. Este é um requisito obrigatório. Pode haver <tag>part</tag>es entre o livro e o capítulo para fornecer outra camada de organização. Por exemplo, o Handbook é organizado dessa maneira.</para> + + <para>Um capítulo(chapter) pode (ou não) conter uma ou mais seções. Estes são indicados com o elemento <tag>sect1</tag>. Se uma seção contiver outra seção, use o elemento <tag>sect2</tag> e assim por diante, até <tag>sect5</tag>.</para> + + <para>Capítulos e seções contêm o restante do conteúdo.</para> + + <para>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.</para> + + <para>A natureza do documento que está sendo escrito deve ser usada para determinar se ele é melhor marcado como um livro ou um artigo. Os artigos são adequados à informação que não precisa ser dividida em vários capítulos, ou seja, relativamente curta, em até 20-25 páginas de conteúdo. Os livros são mais adequados para informações que podem ser divididas em vários capítulos, possivelmente com apêndices e conteúdo similar também.</para> + + <para>Os <link xlink:href="@@URL_RELPREFIX@@/docs.html">Tutoriais do FreeBSD</link> estão todos marcados como artigos, enquanto este documento, o <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</link> e o <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</link> estão todos marcados como livros, por exemplo.</para> + + <sect2 xml:id="docbook-markup-starting-a-book"> + <title>Iniciando um Livro</title> + + <para>O conteúdo de um livro está dentro do elemento <tag>book</tag>. Além de conter marcação estrutural, esse elemento pode conter elementos que incluem informações adicionais sobre o livro. Isso é uma meta-informação, usada para fins de referência ou conteúdo adicional usado para produzir um título de página</para> + + <para>Esta informação adicional está em um elemento <tag>info</tag>.</para> + + <example> + <title>Exemplo de <tag>book</tag> com <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting><tag class="starttag">book</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">book</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-starting-an-article"> + <title>Iniciando um Artigo</title> + + <para>O conteúdo do artigo está dentro do elemento <tag>article</tag>. Além de conter marcação estrutural, esse elemento pode conter elementos que incluem informações adicionais sobre o artigo. Isso é uma meta-informação, usada para fins de referência ou conteúdo adicional usado para produzir um título de página.</para> + + <para>Esta informação adicional está em um elemento <tag>info</tag>.</para> + + <example> + <title>Exemplo de <tag>article</tag> com <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting><tag class="starttag">article</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$FreeBSD$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">article</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-indicating-chapters"> + <title>Criando Capítulos</title> + + <para>Use <tag>chapter</tag> para marcar seus capítulos. Cada capítulo tem um <tag>title</tag> obrigatório. Os artigos não contêm capítulos, eles são reservados para livros.</para> + + <example> + <title>Um Capítulo Simples</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> + + ... +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para>Um capítulo não pode estar vazio; ele deve conter elementos além do <tag>title</tag>. Se você precisar incluir um capítulo vazio, basta usar um parágrafo vazio.</para> + + <example> + <title>Capítulos Vazios</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag><tag class="endtag">para</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-sections-below-chapters"> + <title>Seções Abaixo dos Capítulos</title> + + <para>Nos livros, os capítulos podem (mas não precisam) ser divididos em seções, subseções e assim por diante. Nos artigos, as seções são o principal elemento estrutural e cada artigo deve conter pelo menos uma seção. Use o elemento <tag>sect<replaceable>n</replaceable></tag>. O <replaceable>n</replaceable> indica o número da seção, que identifica o nível da seção.</para> + + <para>A primeira <tag>sect<replaceable>n</replaceable></tag> é <tag>sect1</tag>. Você pode ter um ou mais destes em um capítulo. Eles podem conter um ou mais elementos <tag>sect2</tag> e assim por diante, até <tag>sect5</tag>.</para> + + <example> + <title>Seções em Capítulos</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect1</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> + + <tag class="starttag">sect3</tag> + <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect3</tag> + <tag class="endtag">sect2</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> + + … + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <note> + <para>Os números de seção são gerados automaticamente e anexados aos títulos quando o documento é renderizado em um formato de saída. Os números de seção e títulos gerados a partir do exemplo acima serão:</para> + + <itemizedlist> + <listitem> + <para>1.1. First Section</para> + </listitem> + + <listitem> + <para>1.2. Second Section</para> + </listitem> + + <listitem> + <para>1.2.1. First Sub-Section</para> + </listitem> + + <listitem> + <para>1.2.1.1. First Sub-Sub-Section</para> + </listitem> + + <listitem> + <para>1.2.2. Second Sub-Section</para> + </listitem> + </itemizedlist> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-subdividing-part"> + <title>Subdividindo Utilizando Elementos <tag>part</tag></title> + + <para><tag>part</tag>es adiciona outro nível de organização entre <tag>book</tag> e <tag>chapter</tag> com uma ou mais <tag>part</tag>es. Isso não pode ser utilizado em um <tag>article</tag>.</para> + + <programlisting><tag class="starttag">part</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>History<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> +<tag class="endtag">part</tag></programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-block-elements"> + <title>Elementos Block</title> + + <sect2 xml:id="docbook-markup-paragraphs"> + <title>Parágrafos</title> + + <para>O DocBook suporta três tipos de parágrafos: <tag>formalpara</tag>, <tag>para</tag> e <tag>simpara</tag>.</para> + + <para>Quase todos os parágrafos da documentação do FreeBSD usam <tag>para</tag>. <tag>formalpara</tag> inclui um elemento <tag>title</tag>, e <tag>simpara</tag> desabilita alguns elementos de um <tag>para</tag>. Utilize mais o <tag> para </tag>.</para> + + <example> + <title>Exemplo de um <tag>para</tag> </title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>This is a paragraph. It can contain just about any other element.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-block-quotations"> + <title>Bloco de Citações</title> + + <para>Uma cotação em bloco é uma cotação estendida de outro documento que não deve aparecer no parágrafo atual. Estes raramente são necessários.</para> + + <para>Os blockquotes podem, opcionalmente, conter um título e uma atribuição (ou podem ser deixados sem título e sem atribuição).</para> + + <example> + <title>Exemplo <tag>blockquote</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> + +<tag class="starttag">blockquote</tag> + <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> + + <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> + + <tag class="starttag">para</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">para</tag> +<tag class="endtag">blockquote</tag></programlisting> + + <para>Aparência:</para> + + <para>A small excerpt from the US Constitution:</para> + + <blockquote> + <title>Preamble to the Constitution of the United States</title> + + <attribution>Copiado de um site qualquer</attribution> + + <para>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.</para> + </blockquote> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tips-notes"> + <title>Dicas, Notas, Avisos, Cuidados e Informações Importantes</title> + + <para>Informações adicionais podem precisar ser separadas do texto principal. Normalmente, essa é a informação <quote>meta</quote> da qual o usuário deve estar ciente.</para> + + <para>Vários tipos de informações estão disponíveis: <tag>tip</tag>, <tag>note</tag>, <tag>warning</tag>, <tag>caution</tag>, e <tag>important</tag>.</para> + + <para>O tipo a ser escolhido depende da situação. A documentação do DocBook sugere:</para> + + <itemizedlist> + <listitem> + <para>A nota é para informações onde todos os leitores devem prestar atenção.</para> + </listitem> + + <listitem> + <para>Importante é uma variação de Nota.</para> + </listitem> + + <listitem> + <para>Cuidado é para informações sobre possíveis perdas de dados ou danos ao software.</para> + </listitem> + + <listitem> + <para>Aviso é para informações sobre possíveis danos ao hardware, sobre risco de vida ou de ferimento a um membro.</para> + </listitem> + </itemizedlist> + + <example> + <title>Example de <tag>tip</tag> e <tag>important</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">tip</tag> + <tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag> +<tag class="endtag">tip</tag> + +<tag class="starttag">important</tag> + <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.<tag class="endtag">para</tag> +<tag class="endtag">important</tag></programlisting> + </example> + + <para>Aparência:</para> + <!-- Need to do this outside of the example --> + <tip> + <para>FreeBSD may reduce stress.</para> + </tip> + + <important> + <para>Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-example"> + <title>Exemplos</title> + + <para>Exemplos podem ser apresentados com <tag>example</tag>.</para> + + <example> + <title><tag>example</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">example</tag> + <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag> + + <tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag> +<tag class="endtag">example</tag></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <para>Aparência:</para> + + <example> + <title><tag>example</tag> Renderizado</title> + + <para>Empty files can be created easily:</para> + + <screen><prompt>%</prompt> <userinput>touch file1 file2 file3</userinput></screen> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-lists-and-procedures"> + <title>Listas e Procedimentos</title> + + <para>Muitas vezes, as informações precisam ser apresentadas como listas ou como uma série de etapas que devem ser realizadas para atingir um objetivo específico.</para> + + <para>Para fazer isso, utilize <tag>itemizedlist</tag>, <tag>orderedlist</tag>, <tag>variablelist</tag> ou <tag>procedure</tag>. Existem outros tipos de elementos de lista no DocBook, mas não os cobriremos aqui.</para> + + <para><tag>itemizedlist</tag> e <tag>orderedlist</tag> são semelhantes às suas contrapartes em <acronym>HTML</acronym>, <tag>ul</tag> e <tag>ol</tag>. Cada um consiste em um ou mais elementos <tag>listitem</tag>, e cada <tag>listitem</tag> contém um ou mais elementos de bloco. Os elementos <tag>listitem</tag> são análogos às tags <tag>li</tag> do <acronym>HTML</acronym>. No entanto, ao contrário do HTML, eles são obrigatórios.</para> + + <example> + <title>Exemplo de <tag>itemizedlist</tag> e <tag>orderedlist</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">itemizedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">itemizedlist</tag> + +<tag class="starttag">orderedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">orderedlist</tag></programlisting> + + <para>Aparência:</para> + + <itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> + </orderedlist> + </example> + + <para xml:id="docbook-markup-varlist">Uma maneira alternativa e frequentemente útil de apresentar informações é a <tag>variablelist</tag>. Estas são listas onde cada entrada tem um termo e uma descrição. Eles são adequados para muitos tipos de descrições e apresentam informações de uma forma que geralmente é mais fácil para o leitor do que seções e subseções.</para> + + <para>Uma <tag>variablelist</tag> tem um <tag>title</tag> e, em seguida, pares de entradas <tag>term</tag> e <tag>listitem</tag>.</para> + + <example xml:id="docbook-markup-variablelist-example"> + <title>Exemplo<tag>variablelist</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">variablelist</tag> + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In parallel communications, groups of bits arrive + at the same time over multiple communications + channels.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> + + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In serial communications, bits arrive one at a + time over a single communications + channel.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> +<tag class="endtag">variablelist</tag></programlisting> + + <para>Aparência:</para> + + <variablelist> + <varlistentry> + <term>Parallel</term> + + <listitem> + <para>In parallel communications, groups of bits arrive at the same time over multiple communications channels.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Serial</term> + + <listitem> + <para>In serial communications, bits arrive one at a time over a single communications channel.</para> + </listitem> + </varlistentry> + </variablelist> + </example> + + <para>Um <tag>procedure</tag> mostra uma série de <tag>step</tag>s, que por sua vez consistem em mais <tag>step</tag>s ou <tag>substep</tag>s. Cada <tag>step</tag> contém elementos de bloco e pode incluir um título opcional.</para> + + <para>Às vezes, os passos não são sequenciais, mas apresentam uma escolha: fazer <emphasis>isso</emphasis> ou fazer <emphasis>aquilo</emphasis>, mas não ambos. Para essas escolhas alternativas, use <tag>stepalternatives</tag>.</para> + + <example> + <title>Exemplo <tag>procedure</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">procedure</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">substeps</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this smaller thing.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this other smaller thing.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + <tag class="endtag">substeps</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Finally, do one of these:<tag class="endtag">para</tag> + + <tag class="starttag">stepalternatives</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + <tag class="endtag">stepalternatives</tag> + <tag class="endtag">step</tag> +<tag class="endtag">procedure</tag></programlisting> + + <para>Aparência:</para> + + <procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <substeps> + <step> + <para>And now do this small thing.</para> + </step> + + <step> + <para>And this other small thing.</para> + </step> + </substeps> + </step> + + <step> + <para>Finally, do one of these:</para> + + <stepalternatives> + <step> + <para>Go left.</para> + </step> + + <step> + <para>Go right.</para> + </step> + </stepalternatives> + </step> + </procedure> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-showing-file-samples"> + <title>Mostrando Exemplos de Arquivos</title> + + <para>Fragmentos de um arquivo (ou talvez um arquivo completo) são mostrados agrupando-os no elemento <tag>programlisting</tag>.</para> + + <para>Espaço em branco e quebra de linha dentro de <tag>programlisting</tag> <emphasis>são</emphasis> importantes. Em particular, isso significa que a tag de abertura deve aparecer na mesma linha que a primeira linha da saída, e a tag de fechamento deve aparecer na mesma linha da última linha da saída, caso contrário linhas vazias podem ser incluídas.</para> + + <example> + <title>Exemplo <tag>programlisting</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; + +int +main(void) +{ + printf("hello, world\n"); + return 0; +}<tag class="endtag">programlisting</tag></programlisting> + + <para>Observe como os colchetes angulares na linha <literal>#include</literal> precisam ser referenciados por suas entidades, em vez de serem incluídos literalmente.</para> + + <para>Aparência:</para> + + <para>When finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); + return 0; +}</programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-callouts"> + <title>Chamadas</title> + + <para>Uma chamada é um marcador visual para se referenciar a um texto ou a uma posição específica em um exemplo.</para> + + <para>As chamadas são marcadas com o elemento <tag>co</tag>. Cada elemento deve ter um <literal>id</literal> único atribuído a ele. Após o exemplo, inclua uma <tag>calloutlist</tag> que descreve cada frase de destaque.</para> + + <example> + <title>Exemplo <tag>co</tag> e <tag>calloutlist</tag></title> + + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag> + +int <tag class="emptytag">co xml:id="co-ex-return"</tag> +main(void) +{ + printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag> +}<tag class="endtag">programlisting</tag> + +<tag class="starttag">calloutlist</tag> + <tag class="starttag">callout arearefs="co-ex-include"</tag> + <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-return"</tag> + <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an + int.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-printf"</tag> + <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes + <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> +<tag class="endtag">calloutlist</tag></programlisting> + + <para>Aparência:</para> + + <para>When finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> + +int <co xml:id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co xml:id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para>Includes the standard IO header file.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Specifies that <function>main()</function> returns an int.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>The <function>printf()</function> call that writes <literal>hello, world</literal> to standard output.</para> + </callout> + </calloutlist> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tables"> + <title>Tabelas</title> + + <para>Ao contrário de <acronym>HTML</acronym>, o DocBook não precisa de tabelas para fins de layout, já que a folha de estilo lida com esses problemas. Em vez disso, basta usar tabelas para marcar dados tabulares.</para> + + <para>Em termos gerais (e veja a documentação do DocBook para mais detalhes), uma tabela (que pode ser formal ou informal) consiste em um elemento <tag>table</tag>. Este contém pelo menos um elemento <tag>tgroup</tag>, que especifica (como um atributo) o número de colunas neste grupo de tabelas. Dentro do tgroup há um elemento <tag>thead</tag>, que contém elementos para os títulos da tabela (cabeçalhos da coluna), e um <tag>tbody</tag> que contém o corpo da tabela.</para> + + <para>Ambos <tag>tgroup</tag> e <tag>thead</tag> contêm elementos <tag>row</tag>, que por sua vez contêm elementos <tag>entry</tag>. Cada elemento <tag>entry</tag> especifica uma célula na tabela.</para> + + <example> + <title>Exemplo <tag>informaltable</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">informaltable pgwide="1"</tag> + <tag class="starttag">tgroup cols="2"</tag> + <tag class="starttag">thead</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">thead</tag> + + <tag class="starttag">tbody</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">tbody</tag> + <tag class="endtag">tgroup</tag> +<tag class="endtag">informaltable</tag></programlisting> + + <para>Aparência:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>Sempre use o atributo <literal>pgwide</literal> com um valor <literal>1</literal> com o elemento <tag>informaltable</tag>. Um erro no Internet Explorer pode fazer com que a tabela seja renderizada incorretamente se isso for omitido.</para> + + <para>As bordas da tabela podem ser escondidas configurando o atributo <literal>frame</literal> para <literal>none</literal> no elemento <tag>informaltable</tag>. Por exemplo, <literal>informaltable frame="none"</literal>.</para> + + <example> + <title>Exemplo de Tabela com <literal>frame="none"</literal></title> + + <para>Aparência:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-examples"> + <title>Exemplos para o Usuário Seguir</title> + + <para>Exemplos para o usuário seguir são freqüentemente necessários. Normalmente, eles consistem em diálogos com o computador; o usuário digita um comando, o usuário recebe uma resposta de volta, o usuário digita outro comando e assim por diante.</para> + + <para>Vários elementos e entidades podem ser utilizados nestes casos.</para> + + <variablelist> + <varlistentry> + <term><tag>screen</tag></term> + + <listitem> + <para>Tudo o que o usuário vê neste exemplo estará na tela do computador, então o próximo elemento é <tag> screen </tag>.</para> + + <para>Dentro da <tag>screen</tag>, o espaço em branco é significativo.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>prompt</tag>, <literal>&prompt.root;</literal> and <literal>&prompt.user;</literal></term> + + <listitem> + <para>Algumas das coisas que o usuário irá visualizar na tela são prompts do computador (seja do sistema operacional, da linha de comando shell ou de uma aplicação). Estes prompts devem ser marcados usando <tag>prompt</tag>.</para> + + <para>Por serem especiais, os prompts de shell do usuário normal e do usuário root estão disponíveis como uma entidade. Sempre que quiser indicar que o usuário está em um prompt do shell, use <literal>&prompt.root;</literal> para o usuário root e <literal>&prompt.user;</literal> para o usuário normal, conforme for necessário. Estas entidades não precisam estar dentro de um <tag>prompt</tag>.</para> + + <note> + <para><literal>&prompt.root;</literal> e <literal>&prompt.user;</literal> são extensões do FreeBSD ao DocBook e não são parte do <acronym>DTD</acronym> original.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>userinput</tag></term> + + <listitem> + <para>Ao exibir o texto que o usuário deve digitar, coloque-o nas tags <tag>userinput</tag>. Ele provavelmente será mostrado diferente para o usuário.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title>Exemplos <tag>screen</tag>, <tag>prompt</tag>, e <tag>userinput</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> +foo1 +foo2 +foo3 +&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> +foo2 +&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> +<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> +&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> +This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting> + + <para>Aparência:</para> + + <screen><prompt>%</prompt> <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +<prompt>%</prompt> <userinput>ls -1 | grep foo2</userinput> +foo2 +<prompt>%</prompt> <userinput>su</userinput> +<prompt>Password: </prompt> +<prompt>#</prompt> <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </example> + + <note> + <para>Ainda que estejamos mostrando o conteúdo do arquivo <filename>foo2</filename>, ele <emphasis>não</emphasis> está marcado como <tag>programlisting</tag>. Deixe o <tag>programlisting</tag> para mostrar fragmentos de arquivos fora do contexto de ações do usuário.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-inline-elements"> + <title>Elementos In-line</title> + + <sect2 xml:id="docbook-markup-inline-emphasizing"> + <title>Realçando Informação</title> + + <para>Para enfatizar uma palavra ou frase em particular, use <tag>emphasis</tag>. Isso pode ser apresentado em itálico ou negrito, ou pode ser falado diferentemente com um sistema de conversão de texto em fala.</para> + + <para>Não há uma maneira de mudar a apresentação da ênfase no documento, não existe um equivalente a <tag>b</tag> e <tag>i</tag> do <acronym>HTML</acronym> . Se as informações apresentadas forem importantes, considere apresentá-las em <tag>important</tag> em vez de <tag>emphasis</tag>.</para> + + <example> + <title>Exemplo de <tag>emphasis</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> + premiere &unix;-like operating system for the Intel + architecture.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere <trademark class="registered">UNIX</trademark>-like operating system for the Intel architecture.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-acronyms"> + <title>Siglas</title> + + <para>Muitos termos de computador são <emphasis>siglas</emphasis>, palavras formadas a partir da primeira letra de cada palavra em uma frase. Os acrônimos são marcados com elementos <tag>acronym</tag>. É útil para o leitor quando um acrônimo é definido no primeiro uso, como mostrado no exemplo abaixo.</para> + + <example> + <title>Exemplo <tag>acronym</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The + quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently + transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Request For Comments (<acronym>RFC</acronym>) 1149 defined the use of avian carriers for transmission of Internet Protocol (<acronym>IP</acronym>) data. The quantity of <acronym>IP</acronym> data currently transmitted in that manner is unknown.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-quotations"> + <title>Citações</title> + + <para>Para citar texto de outro documento ou fonte, ou para denotar uma frase que é usada de forma figurada, use <tag>quote</tag>. A maioria das tags de marcação disponíveis para texto normal também está disponível em <tag>quote</tag>.</para> + + <example> + <title>Exemplo <tag>quote</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the + <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, + as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>However, make sure that the search does not go beyond the <quote>boundary between local and public administration</quote>, as <acronym>RFC</acronym> 1535 calls it.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-keys"> + <title>Teclas, Botões do Mouse e Combinações</title> + + <para>Para se referir a uma tecla específica no teclado, use <tag>keycap</tag>. Para se referir a um botão do mouse, use <tag>mousebutton</tag>. E para se referir a combinações de pressionamentos de teclas ou cliques do mouse, coloque todos eles em <tag>keycombo</tag>.</para> + + <para><tag>keycombo</tag> tem um atributo chamado <literal>action</literal>, que pode ser um dos <literal>click</literal>, <literal>double-click</literal>, <literal>other</literal>, <literal>press</literal>, <literal>seq</literal>, ou <literal>simul</literal>. Os dois últimos valores indicam se as teclas ou botões devem ser pressionados em sequência ou simultaneamente.</para> + + <para>As folhas de estilo adicionam automaticamente quaisquer símbolos de conexão, como <literal>+</literal>, entre os nomes das chaves, quando agrupados em <tag>keycombo</tag>.</para> + + <example> + <title>Exemplos de Teclas, Botões do Mouse e Combinações</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type + <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>My window manager is configured so that + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> + <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>To switch to the second virtual terminal, press <keycombo action="simul"><keycap>Alt</keycap> <keycap>F1</keycap></keycombo>.</para> + + <para>To exit <command>vi</command> without saving changes, type <keycombo action="seq"> <keycap>Esc</keycap> <keycap>:</keycap> <keycap>q</keycap> <keycap>!</keycap></keycombo>.</para> + + <para>My window manager is configured so that <keycombo action="simul"> <keycap>Alt</keycap> <mousebutton>right</mousebutton></keycombo> mouse button is used to move windows.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-applications"> + <title>Aplicativos, Comandos, Opções e Citações</title> + + <para>Ambos os aplicativos e comandos são frequentemente utiilzados ao escrever uma documentação. A distinção entre eles é que um aplicativo é o nome de um programa ou conjunto de programas que preenche uma tarefa específica. Um comando é o nome do arquivo de um programa que o usuário pode digitar e executar em uma linha de comando.</para> + + <para>Muitas vezes é necessário mostrar algumas das opções que um comando pode ter.</para> + + <para>Finalmente, muitas vezes é útil listar um comando com seu número de seção do manual, no formato <quote>command(number)</quote> que é comum em manuais Unix.</para> + + <para>Marque nomes de aplicações com <tag>application</tag>.</para> + + <para>Para listar um comando com seu número de seção do manual (que deve ser utilizado com maior frequência), o elemento DocBook é <tag>citerefentry</tag>. Isto irá conter mais dois elementos, <tag>refentrytitle</tag> e <tag>manvolnum</tag>. O conteúdo de <tag>refentrytitle</tag> é o nome do comando, e o conteúdo do <tag>manvolnum</tag> é a seção da página de manual.</para> + + <para>Isso pode ser trabalhoso para escrever e assim uma série de <link linkend="xml-primer-general-entities">entidades gerais</link> foram criadas para tornar esse processo mais fácil. Cada entidade assume o formato <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>O arquivo que contém essas entidades está em <filename>doc/share/xml/man-refs.ent</filename> e pode ser referenciado usando este <acronym>FPI</acronym>:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Portanto, a introdução à documentação do FreeBSD geralmente incluirá isto:</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para>Use <tag>command</tag> para incluir um nome de comando <quote>in-line</quote>, mas mostre como algo que o usuário deve digitar.</para> + + <para>Use <tag>option</tag> para marcar as opções que serão passadas para um comando.</para> + + <para>Ao se referir ao mesmo comando várias vezes nas proximidades, é preferível usar a notação <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> para marcação a primeira referência e use <tag>command</tag> para marcar as referências subsequentes. Isso faz com que a saída gerada, especialmente <acronym>HTML</acronym>, apareça visualmente melhor.</para> + + <example> + <title>Exemplo de Aplicações, Comandos e Opções</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most + widely used Unix mail application.<tag class="starttag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the + <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; + programs.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current + status of messages in the mail queue. Check this on the command + line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para><application> Sendmail </application> é o aplicativo de email Unix mais utilizado.</para> + + <para>O <application> Sendmail </application> inclui o os programas <citerefentry> <refentrytitle>sendmail</refentrytitle><manvolnum>8</manvolnum> </citerefentry>, <citerefentry><refentrytitle>mailq</refentrytitle><manvolnum>1</manvolnum></citerefentry>, e o <citerefentry><refentrytitle>newaliases</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>Um dos parâmetros da linha de comando para o <citerefentry> <refentrytitle>sendmail</refentrytitle><manvolnum>8</manvolnum> </citerefentry>, <option>-bp</option>, exibirá o status atual das mensagens no fila de email. Verifique isso na linha de comando executando <command>sendmail -bp</command>.</para> + </example> + + <note> + <para>Observe como a notação <literal>&man.<replaceable/>.<replaceable>section</replaceable>;</literal> é mais fácil de ser seguida.</para> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-files"> + <title>Arquivos, Diretórios, Extensões, Nomes de Dispositivo</title> + + <para>Para se referir ao nome de um arquivo, um diretório, uma extensão de arquivo ou um nome de dispositivo, use <tag>filename</tag>.</para> + + <example> + <title>Exemplo <tag>filename</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag> O código fonte do Handbook em inglês é encontrada em + <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. + O arquivo principal é chamado <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>. + Há também um <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> e vários arquivos com a extensão <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> é o primeiro teclado detectado + pelo sistema e aparece em + <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>. <tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>O código fonte do Handbook em inglês é encontrada em <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. O arquivo principal é chamado <filename>book.xml</filename>. Há também um <filename>Makefile</filename> e vários arquivos com a extensão <filename>.ent</filename>.</para> + + <para><filename>kbd0</filename> é o primeiro teclado detectado pelo sistema e aparece em <filename>/dev</filename>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-name-of-ports"> + <title>Nome dos Ports</title> + + <note> + <title>Extensão FreeBSD</title> + + <para>Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook <acronym>DTD</acronym> original.</para> + </note> + + <para>Para incluir o nome de um programa da Coleção de Ports do FreeBSD no documento, use a tag <tag>package</tag>. Como a Coleção de Ports pode ser instalada em qualquer local, inclua apenas a categoria e o nome do port; não inclua <filename>/usr/ports</filename>.</para> + + <para>Por padrão, <tag>package</tag> refere-se a um pacote binário. Para se referir a um port que será compilado a partir do código fonte, configure o atributo <literal>role</literal> para <literal>port</literal>.</para> + + <example> + <title>Exemplo de <tag>package</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Instale o pacote binário <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> para + visualizar o tráfego de rede.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> também pode ser + compilado e instalado pela Coleção de Ports.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Instale o pacote binário <package>net/wireshark</package> para visualizar o tráfego de rede.</para> + + <para>O <package role="port">net/wireshark</package> também pode ser + compilado e instalado pela Coleção de Ports.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-hosts"> + <title>Hosts, Domínios, Endereços IP, Usuário, Grupo e Outros Itens do Sistema</title> + + <note> + <title>Extensão FreeBSD</title> + + <para>Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook <acronym>DTD</acronym> original.</para> + </note> + + <para>Informações para <quote>itens do sistema</quote> estão marcadas com <tag>systemitem</tag>. O atributo <literal>class</literal> é usado para identificar o tipo específico de informação mostrada.</para> + + <variablelist> + <varlistentry> + <term><literal>class="domainname"</literal></term> + + <listitem> + <para>O texto é um nome de domínio, como <literal>FreeBSD.org</literal> ou <literal>ngo.org.uk</literal>. Não há nenhum componente de nome de host.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="etheraddress"</literal></term> + + <listitem> + <para>O texto é um endereço Ethernet <acronym>MAC</acronym>, expresso como uma série de números hexadecimais de 2 dígitos separados por dois pontos.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="fqdomainname"</literal></term> + + <listitem> + <para>O texto é um nome de domínio FQDM, com ambos nome de domínio e hostname.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="ipaddress"</literal></term> + + <listitem> + <para>O texto é um endereço de <acronym>IP</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="netmask"</literal></term> + + <listitem> + <para>O texto é uma máscara de rede, que pode ser expressa igual a um IP, uma sequência hexadecimal ou como um <literal>/</literal> seguido por um número (notação <acronym>CIDR</acronym>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="systemname"</literal></term> + + <listitem> + <para>Com <literal>class="systemname"</literal>, as informações marcadas são o nome do host simples, como <literal>freefall</literal> ou <literal>wcarchive</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="username"</literal></term> + + <listitem> + <para>O texto é um nome de usuário, como <literal>root</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="groupname"</literal></term> + + <listitem> + <para>O texto é um grupo, como <literal>wheel</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title>Exemplos <tag>systemitem</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the + name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP + address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag> + domain contains a number of different hosts, including + <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and + <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an + interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) + <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of + <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can + also be expressed as + <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies + every network card in existence. A typical + <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like + <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To carry out most system administration functions + requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>A máquina local sempre pode ser referenciada pelo nome <systemitem>localhost</systemitem>, que terá o endereço IP <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> + + <para>O domínio <systemitem class="fqdomainname">FreeBSD.org</systemitem> contém vários hosts diferentes, incluindo <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> e <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> + + <para>Ao adicionar um alias de <acronym>IP</acronym> a uma interface (usando <command>ifconfig</command>) <emphasis>sempre</emphasis> use uma máscara de rede de <systemitem class="netmask">255.255.255.255</systemitem> (que também pode ser expressa como <systemitem class="netmask">0xffffffff</systemitem>).</para> + + <para>O endereço <acronym>MAC</acronym> identifica exclusivamente todas as placas de rede existentes. Um endereço <acronym>MAC</acronym> típico se parece com <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> + + <para>Para executar a maioria das funções de administração do sistema, é necessário efetuar login como <systemitem class="username">root</systemitem>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-uri"> + <title>Identificadores Uniformes de Recursos (<acronym>URI</acronym>s)</title> + + <para>Ocasionalmente, é útil mostrar um Identificador de Recurso Uniforme (<acronym>URI</acronym>) sem torná-lo um hiperlink ativo. O elemento <tag>uri</tag> torna isso possível:</para> + + <example> + <title>Exemplo <tag>uri</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Esta <acronym>URL</acronym> é mostrada apenas como texto: + <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. Não é criado um link.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Esta <acronym>URL</acronym> é mostrada apenas como texto: <uri>https://www.FreeBSD.org</uri>. Não é criado um link.</para> + </example> + + <para>Para criar links, consulte <xref linkend="docbook-markup-links"/>.</para> + </sect2> + + <sect2 xml:id="docbook-markup-email-addresses"> + <title>Endereços de Email</title> + + <para>Os endereços de email são marcados como elementos <tag>email</tag>. No formato de saída <acronym>HTML</acronym>, o texto marcado se torna um hiperlink para o endereço de email. Outros formatos de saída que suportam hiperlinks também podem tornar o endereço de email em um link.</para> + + <example> + <title>Exemplo de Hiperlink com <tag>email</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag> Um endereço de email que não existe, como + <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, pode ser usado como um + exemplo <tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Um endereço de email que não existe, como <email>notreal@example.com</email>, pode ser usado como exemplo.</para> + </example> + + <para>Uma extensão específica do FreeBSD permite configurar o atributo <literal>role</literal> para <literal>nolink</literal> para evitar a criação do hiperlink para o endereço de email.</para> + + <example> + <title>Exemplo de <tag>email</tag> Sem Hiperlink</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag> Às vezes, o link para um endereço de email como + <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> não é + desejado.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Às vezes, o link para um endereço de email como <email role="nolink">notreal@example.com</email> não é desejado.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-describing-makefiles"> + <title>Descrevendo <filename>Makefile</filename>s</title> + + <note> + <title>Extensão FreeBSD</title> + + <para>Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook <acronym>DTD</acronym> original.</para> + </note> + + <para>Existem dois elementos para descrever partes de <filename>Makefile</filename>s, <tag>buildtarget</tag> e <tag>varname</tag>.</para> + + <para><tag>buildtarget</tag> identifica um destino de compilação exportado por um <filename>Makefile</filename> que pode ser fornecido como um parâmetro para o <command>make</command>. <tag>varname</tag> identifica uma variável que pode ser definida (no ambiente, na linha de comando com o <command>make</command>, ou dentro do <filename>Makefile</filename>) para influenciar o processo.</para> + + <example> + <title>Exemplo de <tag>buildtarget</tag> e <tag>varname</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> + are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will + rebuild the application, and invoking + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary + files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the + build process.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a + number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag> + and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Dois alvos comuns em um <filename>Makefile</filename> são <buildtarget>all</buildtarget> e <buildtarget>clean</buildtarget>.</para> + + <para>Normalmente, invocar <buildtarget>all</buildtarget> irá reconstruir o aplicativo, e invocar <buildtarget>clean</buildtarget> removerá os arquivos temporários (<filename>.o</filename> por exemplo) criados pelo processo de compilação.</para> + + <para><buildtarget>clean</buildtarget> pode ser controlado por várias de variáveis, incluindo <varname>CLOBBER</varname> e <varname>RECURSE</varname>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-literal-text"> + <title>Texto Literal</title> + + <para>O texto literal, ou texto que deve ser inserido na íntegra, é frequentemente necessário na documentação. Este é um texto extraído de outro arquivo ou que deve ser copiado exatamente como mostrado na documentação em um outro arquivo.</para> + + <para>Na maioria das vezes, <tag>programlisting</tag> será suficiente para denotar este texto. Mas <tag>programlisting</tag> nem sempre é apropriado, particularmente quando você quer incluir uma parte de um arquivo <quote>in-line</quote> com o resto do parágrafo.</para> + + <para>Nestes casos, use <tag>literal</tag>.</para> + + <example> + <title>Exemplo <tag>literal</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>A linha <literal>maxusers 10</literal> no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-replaceable"> + <title>Mostrando Itens que o Usuário <emphasis>Deve</emphasis> Preencher</title> + + <para>Haverá diversos momentos em que o usuário irá ver o que fazer, ou será referenciado a um arquivo ou linha de comando, mas não poderá simplesmente copiar o exemplo fornecido. Em vez disso, eles precisam fornecer algumas informações.</para> + + <para><tag>replaceable</tag> é projetado para essa eventualidade. Use isso <emphasis>dentro</emphasis> de outros elementos para indicar partes do conteúdo desse elemento que o usuário deve substituir.</para> + + <example> + <title>Exemplo de <tag>replaceable</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> + + <para>Aparência:</para> + + <informalexample> + <screen><prompt>%</prompt> <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><tag>replaceable</tag> pode ser usado em diversos elementos, incluindo <tag>literal</tag>. Este exemplo também mostra que o <tag>replaceable</tag> deve estar apenas em torno do conteúdo que o usuário <emphasis>está</emphasis> destinado a fornecer. O outro conteúdo deve ser deixado de lado.</para> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value + for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>A linha <literal>maxusers <replaceable>n</replaceable></literal> no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.</para> + + <para>Para uma estação de trabalho, <literal> 32 </literal> é um bom valor para <replaceable>n</replaceable>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-gui-buttons"> + <title>Mostrando Botões <acronym>GUI</acronym></title> + + <para>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.</para> + + <example> + <title>Exemplo <tag>guibutton</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Edit the file, then click + <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the + changes.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Edite o arquivo e clique em <guibutton>[Salvar]</guibutton> para salvar as alterações.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-system-errors"> + <title>Citações de Erros do Sistema</title> + + <para>Erros de sistema gerados pelo FreeBSD são marcados com <tag>errorname</tag>. Isso indica o erro exato que aparece.</para> + + <example> + <title>Exemplo <tag>errorname</tag></title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> + + <para>Aparência:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-images"> + <title>Imagens</title> + + <important> + <para>O suporte de imagem na documentação é um pouco experimental. Os mecanismos descritos aqui provavelmente não mudarão, mas isso não é garantido.</para> + + <para>Para fornecer conversão entre diferentes formatos de imagem, o port <package>graphics/ImageMagick</package> deve estar instalado. Esse port não está incluído no meta port <package>textproc/docproj</package> e deve ser instalado separadamente.</para> + + <para>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.</para> + </important> + + <sect2 xml:id="docbook-markup-image-formats"> + <title>Formatos de Imagem</title> + + <para>Os seguintes formatos de imagem são suportados atualmente. Um arquivo de imagem será automaticamente convertido em bitmap ou imagem vetorial, dependendo do formato do documento de saída.</para> + + <para>Estes são os formatos <emphasis>somente</emphasis> nos quais as imagens devem ser enviadas para o repositório de documentação.</para> + + <variablelist> + <varlistentry> + <term><acronym>EPS</acronym> (Encapsulated Postscript)</term> + + <listitem> + <para>Imagens com base principalmente em vetores, como diagramas de rede, linhas de tempo e similares, devem estar nesse formato. Estas imagens têm uma extensão <filename>.eps</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>PNG</acronym> (Portable Network Graphic)</term> + + <listitem> + <para>Para bitmaps, como capturas de tela, use este formato. Essas imagens têm a extensão <filename>.png</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>PIC</acronym> (PIC graphics language)</term> + + <listitem> + <para><acronym>PIC</acronym> é uma linguagem para desenhar figuras baseadas em vetor simples usadas no utilitário <citerefentry><refentrytitle>pic</refentrytitle> <manvolnum>1</manvolnum></citerefentry>. Essas imagens têm a extensão <filename>.pic</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>SCR</acronym> (SCReen capture)</term> + + <listitem> + <para>Este formato é específico para capturas de tela da saída do console. O seguinte comando gera um arquivo SCR <filename>shot.scr</filename> do buffer de vídeo <filename>/dev/ttyv0</filename>:</para> + + <screen><prompt>#</prompt> <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen> + + <para>É preferível o formato <acronym>PNG</acronym> para capturas de tela porque o arquivo <acronym>SCR</acronym> contém texto sem formatação das linhas de comando para que possa ser convertido em uma imagem <acronym>PNG</acronym> ou um texto simples, dependendo do formato do documento de saída.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Use o formato apropriado para cada imagem. A documentação geralmente tem uma mistura de imagens <acronym>EPS</acronym> e <acronym>PNG</acronym>. O <filename>Makefile</filename> assegura que a imagem de formato correta seja escolhida dependendo do formato de saída usado. <emphasis> Não envie a mesma imagem ao repositório em dois formatos diferentes</emphasis>.</para> + + <important> + <para>O Projeto de Documentação pode eventualmente mudar para o formato <acronym>SVG</acronym> (Scalable Vector Graphic) para imagens vetoriais. No entanto, o estado atual das ferramentas de edição compatíveis com <acronym>SVG</acronym> torna isso inviável.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-image-file-locations"> + <title>Localizações das Imagens</title> + + <para>As imagens podem ser armazenados em um dos diversos locais abaixo, dependendo do documento e da imagem:</para> + + <itemizedlist> + <listitem> + <para>No mesmo diretório do documento em si, geralmente feito para artigos e pequenos livros que mantêm todos os arquivos em um único diretório.</para> + </listitem> + + <listitem> + <para>Em um subdiretório do documento principal. Geralmente feito quando um livro grande usa subdiretórios separados para organizar capítulos individuais.</para> + + <para>Quando as imagens são armazenadas em um subdiretório do diretório do documento principal, o nome do subdiretório deve ser incluído em seus caminhos no <filename>Makefile</filename> e no elemento <tag>imagedata</tag>.</para> + </listitem> + + <listitem> + <para>Em um subdiretório de <filename>doc/share/images</filename> nomeado após o documento. Por exemplo, as imagens do Handbook estão armazenadas em <filename>doc/share/images/books/handbook</filename>. Imagens que funcionam para várias traduções são armazenadas neste nível superior da árvore de arquivos da documentação. Geralmente, estas são imagens que podem ser usadas inalteradas em traduções não inglesas do documento.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-markup"> + <title>Marcação em Imagem</title> + + <para>As imagens são incluídas como parte de um <tag>mediaobject</tag>. O <tag>mediaobject</tag> pode conter outros objetos mais específicos. Estamos preocupados com dois, o <tag>imageobject</tag> e o <tag>textobject</tag>.</para> + + <para>Inclua um <tag>imageobject</tag> e dois elementos <tag>textobject</tag>. O <tag>imageobject</tag> apontará para o nome do arquivo de imagem sem a extensão. Os elementos <tag>textobject</tag> contêm informações que serão apresentadas ao usuário, bem como, ou em vez da própria imagem.</para> + + <para>Elementos de texto são mostrados ao leitor em várias situações. Quando o documento é exibido em <acronym>HTML</acronym>, elementos de texto são mostrados enquanto a imagem está sendo carregada ou se o ponteiro do mouse estiver sobre a imagem ou se um navegador somente texto estiver sendo usado. Em formatos como texto simples, onde os gráficos não são possíveis, os elementos de texto são mostrados em vez dos gráficos.</para> + + <para>Este exemplo mostra como incluir uma imagem chamada <filename>fig1.png</filename> em um documento. A imagem é um retângulo com um A dentro dela:</para> + + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> + <tag class="endtag">imageobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> +| A | ++---------------+<tag class="endtag">literallayout</tag> + <tag class="endtag">textobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> + <tag class="endtag">textobject</tag> +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para>Inclua um elemento <tag>imagedata</tag> dentro do elemento <tag>imageobject</tag>. O atributo <literal>fileref</literal> deve conter o nome do arquivo da imagem a ser incluída, sem a extensão. As folhas de estilo irão descobrir qual extensão deve ser adicionada ao nome do arquivo automaticamente.</para> + </callout> + + <callout arearefs="co-image-literal"> + + <para>O primeiro <tag>textobject</tag> contém um elemento <tag>literallayout</tag>, onde o atributo <literal>class</literal> é definido como <literal>monospaced</literal>. Esta é uma oportunidade para demonstrar habilidades artísticas em <acronym>ASCII</acronym>. Este conteúdo será usado se o documento for convertido em texto simples.</para> + + <para>Observe como a primeira e a última linha do conteúdo do elemento <tag>literallayout</tag> aparecem ao lado das tags do elemento. Isso garante que nenhum espaço em branco seja incluído.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para>O segundo <tag>textobject</tag> contém um único elemento <tag>phrase</tag>. O conteúdo desta frase se tornará o atributo <literal>alt</literal> para a imagem quando este documento for convertido para <acronym>HTML</acronym>.</para> + </callout> + </calloutlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-makefile-entries"> + <title>Entradas de Imagem no <filename>Makefile</filename></title> + + <para>As imagens devem estar listadas no <filename>Makefile</filename> na variável <varname>IMAGES</varname>. Esta variável deve conter os nomes de todas as imagens <emphasis>source</emphasis>. Por exemplo, se houver três figuras, <filename>fig1.eps</filename>, <filename>fig2.png</filename>, <filename>fig3.png</filename>, então o <filename>Makefile</filename> deve ter linhas como esta.</para> + + <programlisting>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>ou</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para>Novamente, o <filename>Makefile</filename> irá elaborar a lista completa de imagens necessárias para compilar o documento, você só precisa listar os arquivos de imagem que <emphasis>você</emphasis> forneceu.</para> + </sect2> + + <sect2 xml:id="docbook-markup-images-in-subdirectories"> + <title>Imagens e Capítulos em Subdiretórios</title> + + <para>Tenha cuidado ao separar a documentação em arquivos menores em diretórios diferentes (consulte <xref linkend="xml-primer-include-using-gen-entities"/>).</para> + + <para>Imagine que haja um livro com três capítulos e os capítulos sejam armazenados em seus próprios diretórios, chamados <filename>chapter1/chapter.xml</filename>, <filename>chapter2/chapter.xml</filename> e <filename>chapter3/chapter.xml</filename>. Se cada capítulo tiver imagens associadas, coloque essas imagens no subdiretório de cada capítulo (<filename>chapter1/</filename>, <filename>chapter2/</filename>, e <filename>chapter3/</filename>).</para> + + <para>No entanto, fazer isso requer a inclusão dos nomes de diretório na variável <varname>IMAGES</varname> no <filename>Makefile</filename>, <emphasis>e</emphasis> a inclusão do nome do diretório no elemento <tag>imagedata</tag> no documento.</para> + + <para>Por exemplo, se o livro tiver <filename>chapter1/fig1.png</filename>, então <filename>chapter1/chapter.xml</filename> deve conter:</para> + + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> + <tag class="endtag">imageobject</tag> + + … + +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para>O nome do diretório deve ser incluído no atributo <literal>fileref</literal>.</para> + </callout> + </calloutlist> + + <para>O <filename>Makefile</filename> deve conter:</para> + + <programlisting>… +IMAGES= chapter1/fig1.png +…</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-links"> + <title>Links</title> + + <note> + <para>Links também são elementos in-line. Para mostrar uma <acronym>URI</acronym> sem criar um link, consulte <xref linkend="docbook-markup-uri"/>.</para> + </note> + + <sect2 xml:id="docbook-markup-links-ids"> + <title>Atributos <literal>xml:id</literal></title> + + <para>A maioria dos elementos DocBook aceita um atributo <literal>xml:id</literal> para dar a essa parte do documento um nome exclusivo. O <literal>xml:id</literal> pode ser usado como um destino para uma referência cruzada ou link.</para> + + <para>Qualquer parte do documento que será um destino de link deve ter um atributo <literal>xml:id</literal>. Atribuir um <literal>xml:id</literal> a todos os capítulos e seções, mesmo que não haja planos atuais para criar link para eles, é uma boa ideia. Esses <literal>xml:id</literal> s podem ser usados como pontos de referência exclusivos por qualquer pessoa que se refira à versão do documento <acronym>HTML</acronym>.</para> + + <example> + <title><literal>xml:id</literal> em Ccapítulos e sSeções de eExemplo</title> + + <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the introduction. It contains a subsection, + which is identified as well.<tag class="endtag">para</tag> + + <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> + <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para>Use valores descritivos para nomes de <literal>xml:id</literal>. Os valores devem ser exclusivos em todo o documento, não apenas em um único arquivo. No exemplo, a subseção <literal>xml:id</literal> é construída anexando o texto ao capítulo <literal>xml:id</literal>. Isso garante que os <literal>xml:id</literal> s sejam exclusivos. Ele também ajuda o leitor e qualquer um que editar o documento a ver onde o link está localizado no documento, semelhante a um caminho de diretório para um arquivo.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-crossreferences"> + <title>Referências Cruzadas com <literal>xref</literal></title> + + <para><tag>xref</tag> fornece ao leitor um link para ir para outra seção do documento. O destino <literal>xml:id</literal> é especificado no atributo <literal>linkend</literal> e <tag>xref</tag> gera o texto do link automaticamente.</para> + + <example> + <title>Exemplo <tag>xref</tag></title> + + <para>Imagine que esse fragmento apareça em algum lugar em um documento que inclua o exemplo <literal>xml:id</literal> mostrado acima:</para> + + <programlisting><tag class="starttag">para</tag>More information can be found + in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>More specific information can be found + in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting> + + <para>O texto do link será gerado automaticamente, parecendo como (O <emphasis> enfatizado</emphasis> indica o texto do link):</para> + + <blockquote> + <para>Mais informações podem ser encontradas no <emphasis>Capítulo 1, Introdução</emphasis>.</para> + + <para>Informações mais específicas podem ser encontradas em <emphasis>Seção 1.1, <quote>Mais Detalhes</quote></emphasis>.</para> + </blockquote> + </example> + + <para>O texto do link é gerado automaticamente a partir do capítulo e número da seção e elementos <literal>title</literal>.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-to-web-documents"> + <title>Criando Links para Outros Documentos na Web</title> + + <para>O elemento link descrito aqui permite que o escritor defina o texto do link. Quando o texto do link é usado, é muito importante ser descritivo para dar ao leitor uma ideia de onde o link vai. Lembre-se que o DocBook pode ser renderizado para vários tipos de mídia. O leitor pode estar olhando para um livro impresso ou outra forma de mídia onde não há links. Se o texto do link não for descritivo o suficiente, talvez o leitor não consiga localizar a seção vinculada.</para> + + <para>O atributo <literal>xlink:href</literal> é a <acronym>URL</acronym> da página, e o conteúdo do elemento é o texto que será exibido para o usuário ativar.</para> + + <para>Em muitas situações, é preferível mostrar a <acronym>URL</acronym> real em vez do texto. Isso pode ser feito deixando de fora o texto do elemento.</para> + + <example> + <title><tag>link</tag> para um Exemplo de Página Web de Documentação do FreeBSD</title> + + <para>Link para uma <acronym>URL</acronym> de uma entidade. de livro ou artigo Para criar um link para um capítulo específico de um livro, adicione uma barra e o nome do arquivo do capítulo, seguido por uma âncora opcional dentro do capítulo. Para artigos, crie um link para a entidade <acronym>URL</acronym> do artigo, seguida por uma âncora opcional no artigo. As entidades <acronym>URL</acronym> podem ser encontradas em <filename>doc/share/xml/urls.ent</filename>.</para> + + <para>Uso para links de livros do FreeBSD:</para> + + <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN + introduction<tag class="endtag">link</tag>, then pick the nearest mirror from + the list of <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion + mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Leia a <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-intro">Introdução ao SVN</link>, em seguida, escolha o espelho mais próximo do lista de <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">sites espelho do Subversion</link>.</para> + + <para>Uso para links de artigos do FreeBSD:</para> + + <programlisting><tag class="starttag">para</tag>Read this + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article + about the BSD license<tag class="endtag">link</tag>, or just the + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Leia este <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl">artigo sobre a licença BSD</link>, ou apenas a sua <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/bsdl-gpl#intro">introdução</link>.</para> + </example> + + <example> + <title><tag>link</tag> para um Exemplo de Página Web do FreeBSD</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the + <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>Claro, você pode parar de ler este documento e ir para a <link xlink:href="@@URL_RELPREFIX@@/index.html"> página inicial do FreeBSD</link>.</para> + </example> + + <example> + <title><tag>link</tag> para um Exemplo de Página Web Externa</title> + + <para>Uso:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID + Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Aparência:</para> + + <para>A Wikipedia tem uma excelente referência em <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"> Tabelas de Partição GUID</link>.</para> + + <para>O texto do link pode ser omitido para mostrar a URL real:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>O mesmo link pode ser inserido usando notação mais curta em vez de uma tag de finalização separada:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="emptytag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Os dois métodos são equivalentes. Aparência:</para> + + <para>A Wikipedia tem uma excelente referência em Tabelas de Partição GUID: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table </uri>.</para> + </example> + </sect2> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="stylesheets"> + <title>Folhas de Estilo</title> + + <para>O <acronym>XML</acronym> se preocupa com o conteúdo e não diz nada sobre como esse conteúdo deve ser apresentado ao leitor ou renderizado no papel. Múltiplas linguagens de <emphasis>folha de estilo</emphasis> foram desenvolvidas para descrever o layout visual, incluindo a Transformação de Linguagem de Folha de Estilo Extensível (<acronym>XSLT</acronym>), Semântica de Estilo de Documento e Linguagem de Especificação (<acronym>DSSSL</acronym> ) e Folhas de Estilo em Cascata (<acronym>CSS</acronym>).</para> + + <para>Os documentos do <acronym>FDP</acronym> usam folhas de estilo <acronym>XSLT</acronym> para transformar o DocBook em <acronym>XHTML</acronym>, e então a formatação <acronym>CSS</acronym> é aplicada nas páginas <acronym>XHTML</acronym>. A saída imprimível é atualmente renderizada com folhas de estilo legadas do <acronym>DSSSL</acronym>, mas isso provavelmente mudará no futuro.</para> + + <sect1 xml:id="stylesheets-css"> + <title><acronym>CSS</acronym></title> + + <para>Folhas de estilos em cascata (<acronym>CSS</acronym>) são um mecanismo para anexar informações de estilo (font, weight, size, color e assim por diante) a elementos em um documento <acronym>XHTML</acronym> sem abusar de <acronym>XHTML</acronym> para o fazer.</para> + + <sect2 xml:id="stylesheets-css-documents"> + <title>Os Documentos DocBook</title> + + <para>As folhas de estilo <acronym>XSLT</acronym> e <acronym>DSSSL</acronym> do FreeBSD se referem a <filename>docbook.css</filename>, que deve estar presente no mesmo diretório que os arquivos <acronym>XHTML</acronym>. O arquivo <acronym>CSS</acronym> de todo o projeto é copiado de <filename>doc/share/misc/docbook.css</filename> quando os documentos são convertidos para <acronym>XHTML</acronym> e são instalados automaticamente .</para> + </sect2> + </sect1> +</chapter> + + +<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +--> +<chapter version="5.0" xml:id="translations"> + <title>Traduções</title> + + <para>Este é o FAQ para pessoas que estão traduzindo a documentação do FreeBSD (FAQ, Handbook, tutoriais, páginas de manual e outros) para diferentes idiomas.</para> + + <para>Ele é <emphasis>fortemente</emphasis> baseado na tradução do FAQ do Projeto de Documentação Alemão do FreeBSD, originalmente escrito por Frank Gründer <email>elwood@mc5sys.in-berlin.de</email> e traduzido de volta para o inglês por Bernd Warken <email>bwarken@mayn.de</email>.</para> + + <para>O FAQ é mantido pela Equipe de Engenharia de Documentação <email>doceng@FreeBSD.org</email>.</para> + + <qandaset> + <qandaentry> + <question> + <para>O que significa <phrase>i18n</phrase> e <phrase>l10n</phrase>?</para> + </question> + + <answer> + <para><phrase>i18n</phrase> significa <phrase>internacionalização</phrase> e <phrase>l10n</phrase> significa <phrase>localização</phrase>. São apenas uma abreviação.</para> + + <para><phrase>i18n</phrase> pode ser lido como <quote>i</quote> seguido por 18 letras, seguido por <quote>n</quote>. Da mesma forma, <phrase>l10n</phrase> é <quote>l</quote> seguido por 10 letras, seguido por <quote>n</quote>.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Existe uma lista de discussão para tradutores?</para> + </question> + + <answer> + <para>Sim. Diferentes grupos de tradução têm suas próprias listas de discussão. A <link xlink:href="https://www.freebsd.org/docproj/translations.html">lista dos projetos de tradução</link> possui mais informações sobre as listas de discussão e sites web mantidos por cada projeto de tradução. Além disso, existe a <email>freebsd-translators@freebsd.org</email> para discussão geral de tradução.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>São necessários mais tradutores?</para> + </question> + + <answer> + <para>Sim. Quanto mais pessoas trabalham na tradução, mais rápido ela será finalizada, e mais rapidamente as mudanças na documentação em Inglês serão refletidas nos documentos traduzidos.</para> + + <para>Você não precisa ser um tradutor profissional para poder ajudar.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Quais idiomas eu preciso saber?</para> + </question> + + <answer> + <para>Idealmente, você deverá possuir um bom conhecimento de Inglês escrito, e obviamente, precisará ser fluente no idioma para o qual está traduzindo.</para> + + <para>Inglês não é estritamente necessário. Por exemplo, você poderia fazer uma tradução Húngara do FAQ da tradução em Espanhol.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Quais softwares eu preciso conhecer?</para> + </question> + + <answer> + <para>É fortemente recomendado que você mantenha uma cópia local do repositório Subversion do FreeBSD (pelo menos a parte da documentação). Isso pode ser feito executando:</para> + + <screen><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen> + + <para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link> é um servidor público <literal>SVN</literal>. Verifique o certificado do servidor na lista de <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors">Mirrors de Subversion</link>.</para> + + <note> + <para>Será necessário que o pacote <package>devel/subversion</package> esteja instalado.</para> + </note> + + <para>Você deverá ter conhecimentos básicos de <application>svn</application>. Ele permitirá que você veja o que mudou entre as diferentes versões dos arquivos que compõem a documentação.</para> + + <para>Por exemplo, para ver as diferenças entre as revisões <literal>r33733</literal> e <literal>r33734</literal> do <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>, execute:</para> + + <screen><prompt>%</prompt> <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen> + + <para>Por favor, veja a explicação completa de como usar o <application>Subversion</application> no FreeBSD no <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html">FreeBSD 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> + </question> + + <answer> + <para>A <link xlink:href="https://www.FreeBSD.org/docproj/translations.html">página do Projeto de Tradução da Documentação</link> lista os trabalhos de tradução que são conhecidos. Se outras pessoas já estiverem trabalhando na tradução de documentação para o seu idioma, por favor, não duplique os esforços. Em vez disso, entre em contato para saber como você pode ajudar.</para> + + <para>Se não existir nenhum projeto de tradução para o seu idioma listado nesta página, envie uma mensagem para <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de discussão do projeto de documentação do FreeBSD</link> para o caso de alguém estar pensando em fazer a tradução, mas ainda não tiver anunciado nada.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Ninguém mais está traduzindo para o meu idioma. O que eu faço?</para> + </question> + + <answer> + <para>Parabéns, você acabou de iniciar o <quote> Projeto de Tradução da Documentação do FreeBSD em <replaceable>seu idioma aqui</replaceable> </quote>. Bem vindo a bordo.</para> + + <para>Primeiro, pense se você terá o tempo necessário. Uma vez que você é a única pessoa trabalhando no seu idioma no momento, será sua a responsabilidade de publicar o seu trabalho e coordenar qualquer voluntário que queira ajudá-lo.</para> + + <para>Escreva um email para a lista de discussão do Projeto de Documentação, anunciando que você irá traduzir a documentação, assim a página do Projeto de Traduções de Documentação poderá ser atualizada.</para> + + <para>Se já existir alguém em seu país provendo o espelhamento de serviços do FreeBSD, você deve contacta-lo e perguntar se você pode ter algum espaço web para seu projeto, e se possível um endereço de email ou mesmo um serviço de lista de discussão.</para> + + <para>Então escolha um documento e comece a traduzir. É melhor começar com algo razoavelmente pequeno—como o FAQ ou um dos tutoriais.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Eu já tenho alguns documentos traduzidos, para onde eu devo enviá-los?</para> + </question> + + <answer> + <para>Isso depende. Se você já está trabalhando com uma equipe de tradução (tal como a equipe japonesa, ou a equipe alemã) então ela terá seus próprios procedimentos para manipular a documentação submetida, e estes serão descritos em seus web sites.</para> + + <para>Se você for a única pessoa trabalhando em um determinado idioma (ou se você é o responsável pelo projeto de tradução e quer submeter suas mudanças de volta para o projeto FreeBSD) então você deve enviar sua tradução ao Projeto FreBSD (veja pergunta seguinte).</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Eu sou a única pessoa trabalhando na tradução para este idioma, como faço para enviar minha tradução?</para> + + <para>ou</para> + + <para>Somos uma equipe de tradução e queremos enviar a documentação que nossos membros traduziram para nós.</para> + </question> + + <answer> + <para>Primeiro, verifique se sua tradução está organizada corretamente. Isso significa que ele deve cair na árvore de documentação existente e ser compilada de maneira correta.</para> + + <para>Atualmente a documentação do FreeBSD é armazenada em um diretório de nível superior chamado <filename>head/</filename>. Os diretórios abaixo desse são nomeados de acordo com o código do idioma em que estão escritos, conforme definido na ISO639 (<filename>/usr/share/misc/iso639</filename> em uma versão do FreeBSD mais recente que 20 de janeiro de 1999).</para> + + <para>Se o seu idioma puder ser codificado de maneiras diferentes (por exemplo, Chinês), deve haver diretórios abaixo desse, um para cada formato de codificação fornecido.</para> + + <para>Finalmente, você deve ter diretórios para cada documento.</para> + + <para>Por exemplo, em uma hipotética tradução Sueca ficaria assim:</para> + + <programlisting>head/ + sv_SE.ISO8859-1/ + Makefile + htdocs/ + docproj/ + books/ + faq/ + Makefile + book.xml</programlisting> + + <para><literal>sv_SE.ISO8859-1</literal> é o nome da tradução, no formato <filename> <replaceable>lang</replaceable>.<replaceable>encoding</replaceable> </filename>. Repare nos dois Makefiles, que serão usados para compilar a documentação.</para> + + <para>Use<citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry> e <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> para compactar sua documentação e enviá-lo para o projeto.</para> + + <screen><prompt>%</prompt> <userinput>cd doc</userinput> +<prompt>%</prompt> <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> +<prompt>%</prompt> <userinput>gzip -9 swedish-docs.tar</userinput></screen> + + <para>Coloque <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), envie um email para a Equipe de Engenharia da Documentação <email>doceng@FreeBSD.org</email> e combine o envio dos arquivos por email conveniente quando for conveniente.</para> + + <para>De qualquer maneira, você deve usar o Bugzilla para enviar um relatório indicando que você enviou a documentação. Seria muito útil se você conseguir outras pessoas para checar sua tradução primeiro, já que é improvável que a pessoa que irá fazer o commit seja fluente no idioma.</para> + + <para>Alguém (provavelmente o Gerente do Projeto de Documentação, atualmente Equipe de Engenharia de Documentação <email>doceng@FreeBSD.org</email>) irá então pegar sua tradução e checar se ela compila. Em particular, as seguintes coisas serão analisadas:</para> + + <orderedlist> + <listitem> + <para>Todos os seus arquivos usam strings RCS (tais como "ID")?</para> + </listitem> + + <listitem> + <para>O <command>make all</command> no diretório <filename>sv_SE.ISO8859-1</filename> funciona corretamente?</para> + </listitem> + + <listitem> + <para>O <command>make install</command> funciona corretamente?</para> + </listitem> + </orderedlist> + + <para>Se houver algum problema, quem estiver validando a submissão irá entrar em contato para que seja feito as correções.</para> + + <para>Se não houver problemas, sua tradução será disponibilizada o mais rápido possível.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Posso incluir um texto específico do idioma ou do país em minha tradução?</para> + </question> + + <answer> + <para>Nós preferimos que você não faça isso.</para> + + <para>Por exemplo, suponha que você esteja traduzindo o Handbook para o Coreano e queira incluir uma seção sobre varejistas na Coreia em seu Handbook.</para> + + <para>Não há razão pela qual esta informação não deva estar nas versões em Inglês (ou Alemão, ou Espanhol, ou Japonâs, ou …). É possível que uma pessoa que fale Inglês na Coréia possa tentar obter uma cópia do FreeBSD enquanto esteja ali. Isso também ajuda a aumentar a presença perceptível do FreeBSD ao redor do mundo, o que não é uma coisa ruim.</para> + + <para>Se você tiver informações específicas do país, submeta-as como uma alteração do Handbook em Inglês (usando o Bugzilla) e em seguida, traduza a alteração de volta para o seu idioma no Handbook traduzido.</para> + + <para>Obrigado.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Como os caracteres específicos do idioma podem ser incluídos?</para> + </question> + + <answer> + <para>Caracteres não-ASCII na documentação devem ser incluídos usando entidades SGML.</para> + + <para>Resumidamente, eles se parecem com um "e" comercial (&), o nome da entidade e um ponto e vírgula (;).</para> + + <para>Os nomes das entidades são definidos em ISO8879, que está na árvore de ports em <package>textproc/iso8879</package>.</para> + + <para>Alguns exemplos incluem:</para> + + <segmentedlist> + <segtitle>Entidade</segtitle> + + <segtitle>Aparência</segtitle> + + <segtitle>Descrição</segtitle> + + <seglistitem> + <seg>&eacute;</seg> + <seg>é</seg> + <seg><quote>e</quote> minúsculo com acento agudo</seg> + </seglistitem> + + <seglistitem> + <seg>&Eacute;</seg> + <seg>É</seg> + <seg><quote>E</quote> maiúsculo com acento agudo</seg> + </seglistitem> + + <seglistitem> + <seg>&uuml;</seg> + <seg>ü</seg> + <seg><quote>u</quote> minúsculo com trema</seg> + </seglistitem> + </segmentedlist> + + <para>Depois de instalar o port iso8879, os arquivos em <filename> /usr/local/share/xml/iso8879</filename> conterão a lista completa.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Dirigindo-se ao leitor</para> + </question> + + <answer> + <para>Nos documentos em Inglês, o leitor é tratado por <quote>você</quote>, não há distinção entre formal/informal como existe em alguns idiomas.</para> + + <para>Se você estiver traduzindo para um idioma que tenha esta distinção, use qualquer forma que normalmente é usada em outras documentações técnicas. Na dúvida, use a forma mais educada.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Preciso incluir informações adicionais nas minhas traduções?</para> + </question> + + <answer> + <para>Sim.</para> + + <para>O cabeçalho da versão em Inglês de cada documento será algo parecido com isto:</para> + + <programlisting><!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--></programlisting> + + <para>O forma exata pode mudar, mas sempre incluirá uma linha $FreeBSD$ e a frase <literal>The FreeBSD Documentation Project</literal>. Note que a parte do $FreeBSD é expandida automaticamente pelo Subversion, portanto ela deve estar vazia (apenas <literal>$FreeBSD$</literal>) para novos arquivos.</para> + + <para>Seus documentos traduzidos devem incluir sua própria linha $FreeBSD$, e mudar a linha <literal>FreeBSD Documentation Project</literal> para <literal>The FreeBSD <replaceable>language</replaceable> Documentation Project</literal>.</para> + + <para>Você deve ainda adicionar uma terceira linha que indicará qual revisão do texto em inglês o texto é baseado.</para> + + <para>Assim, a versão em Espanhol desse arquivo pode começar com:</para> + + <programlisting><!-- + The FreeBSD Spanish Documentation Project + + $FreeBSD$ + Original revision: r38674 +--></programlisting> + </answer> + </qandaentry> + </qandaset> +</chapter> + + +<!-- + The FreeBSD Documentation Project +--> +<chapter version="5.0" xml:id="po-translations"> + + <title>Traduções <acronym>PO</acronym></title> + + <sect1 xml:id="po-translations-introduction"> + <title>Introdução</title> + + <para>O <link xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> <application>gettext</application></link> oferece aos tradutores uma maneira fácil de criar e manter traduções de documentos. Sequências traduzíveis são extraídas do documento original em um arquivo <acronym>PO</acronym> (Portable Object). Versões traduzidas das strings são inseridas com um editor separado. As strings podem ser usadas diretamente ou incorporadas em uma versão traduzida completa do documento original.</para> + </sect1> + + <sect1 xml:id="po-translations-quick-start"> + <title>Quick Start</title> + + <para>Supõe-se que o procedimento mostrado em <xref linkend="overview-quick-start"/>já tenha sido executado, mas a opção <literal>TRANSLATOR</literal> deve estar ativada no port <package role="port">textproc/docproj</package>. Se essa opção não estiver ativada, exiba o menu de opções, ative-a e reinstale o port:</para> + + <screen><prompt>#</prompt> <userinput>cd /usr/ports/textproc/docproj</userinput> +<prompt>#</prompt> <userinput>make config</userinput> +<prompt>#</prompt> <userinput>make clean deinstall install clean</userinput></screen> + + <para>Este exemplo mostra a criação de uma tradução em Espanhol do pequeno artigo <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/leap-seconds">Leap Seconds</link>.</para> + + <procedure xml:id="po-translations-quick-start-install-po-editor"> + <title>Instale um Editor <acronym>PO</acronym></title> + + <step> + <para>É necessário um editor <acronym>PO</acronym> para editar os arquivos de tradução. Este exemplo utiliza o <package role="ports">editors/poedit</package>.</para> + + <screen><prompt>#</prompt> <userinput>cd /usr/ports/editors/poedit</userinput> +<prompt>#</prompt> <userinput>make install clean</userinput></screen> + </step> + </procedure> + + <procedure xml:id="po-translations-quick-start-initial-setup"> + <title>Configuração Inicial</title> + + <para>Quando uma nova tradução é criada pela primeira vez, a estrutura do diretório e o <filename>Makefile</filename> devem ser criados ou copiados do original em Inglês:</para> + + <step> + <para>Crie um diretório para a nova tradução. O código fonte do artigo em Inglês está em <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>. A tradução em Espanhol estará em <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>. O caminho é o mesmo, exceto pelo nome do diretório de idiomas.</para> + + <screen><prompt>%</prompt> <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> + </step> + + <step> + <para>Copie o <filename>Makefile</filename> do documento original para o diretório de tradução:</para> + + <screen><prompt>%</prompt> <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>Tradução</title> + + <para>A tradução de um documento consiste em duas etapas: extrair strings traduzíveis do documento original e inserir as traduções dessas strings. Essas etapas são repetidas até que o tradutor sinta que o documento foi traduzido o suficiente para produzir um documento traduzido que seja utilizável.</para> + + <step> + <para>Extraia as strings traduzíveis da versão original em Inglês para um arquivo <acronym>PO</acronym>:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> +<prompt>%</prompt> <userinput>make po</userinput></screen> + </step> + + <step> + <para>Use um editor <acronym>PO</acronym> para inserir as traduções no arquivo <acronym>PO</acronym>. Existem vários editores diferentes disponíveis. O <filename>poedit</filename> do <package role="port">editors/poedit</package> é mostrado aqui.</para> + + <para>O nome do arquivo <acronym>PO</acronym> é o código de idioma de dois caracteres seguido por um código de região de também dois caracteres, seprados por um underline. Para espanhol, o nome do arquivo é <filename>es_ES.po</filename>.</para> + + <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> + </step> + </procedure> + + <procedure xml:id="po-translations-quick-generating-a-translated-document"> + <title>Gerando um Documento Traduzido</title> + + <step> + <para>Gere o documento traduzido:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> +<prompt>%</prompt> <userinput>make tran</userinput></screen> + + <para>O nome do documento gerado corresponde ao nome do original em Inglês, geralmente <filename>article.xml</filename> para artigos ou <filename>book.xml</filename> para livros.</para> + </step> + + <step> + <para>Verifique o arquivo gerado renderizando-o para <acronym>HTML</acronym> e exibindo-o com um navegador web:</para> + + <screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput> +<prompt>%</prompt> <userinput>firefox article.html</userinput></screen> + </step> + </procedure> + </sect1> + + <sect1 xml:id="po-translations-creating"> + <title>Criando Novas Traduções</title> + + <para>O primeiro passo para criar um novo documento traduzido é localizar ou criar um diretório para mantê-lo. O FreeBSD coloca documentos traduzidos em um subdiretório nomeado para seu idioma e região no formato <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable> </filename>. <replaceable>lang</replaceable> é um código minúsculo de dois caracteres. Ele é seguido por um caractere underline, em seguida, pelo código de duas letras maiúsculas <replaceable>REGION</replaceable>.</para> + + <table xml:id="po-translations-language-names" frame="none"> + <title>Nomes de Idioma</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>Língua</entry> + <entry>Região</entry> + <entry>Nome do Diretório Traduzido</entry> + <entry>Nome do Arquivo <acronym>PO</acronym></entry> + <entry>Conjunto de Caracteres</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Inglês</entry> + <entry>Estados Unidos</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>Dinamarquês</entry> + <entry>Dinamarca</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>Alemão</entry> + <entry>Alemanha</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>Grego</entry> + <entry>Grécia</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>Espanhol</entry> + <entry>Espanha</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>Francês</entry> + <entry>França</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>Húngaro</entry> + <entry>Hungria</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>Italiano</entry> + <entry>Itália</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>Japonês</entry> + <entry>Japão</entry> + <entry><filename>ja_JP.eucJP</filename></entry> + <entry><filename>ja_JP.po</filename></entry> + <entry><acronym>EUC</acronym> JP</entry> + </row> + + <row> + <entry>Coreano</entry> + <entry>Coréia</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>Mongol</entry> + <entry>Mongólia</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>Holandês</entry> + <entry>Holanda</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>Polonês</entry> + <entry>Polônia</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>Português</entry> + <entry>Brasil</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>Russo</entry> + <entry>Rússia</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>Turco</entry> + <entry>Turquia</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>Chinês</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>Chinês</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>As traduções estão em subdiretórios do diretório principal da documentação, aqui assumido como <filename>~/doc/</filename> como mostrado em <xref linkend="overview-quick-start"/>. Por exemplo, as traduções em alemão estão localizadas em <filename>~/doc/de_DE.ISO8859-1/</filename> e as traduções em francês estão em <filename>~/doc/fr_FR.ISO8859-1/</filename>.</para> + + <para>Cada diretório de idiomas contém subdiretórios separados para os tipos de documentos, geralmente <filename>articles/</filename> e <filename>books/</filename>.</para> + + <para>A combinação desses nomes de diretórios fornece o caminho completo para um artigo ou livro. Por exemplo, a tradução Francesa do artigo NanoBSD está em <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>, e a tradução em Mongol do manual está em <filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>.</para> + + <para>Um novo diretório de idioma deve ser criado ao traduzir um documento para um novo idioma. Se o diretório de idiomas já existir, somente um subdiretório no diretório <filename>articles/</filename> ou <filename>books/</filename> será necessário.</para> + + <para>As compilações da documentação do FreeBSD são controladas por um <filename> Makefile </filename> no mesmo diretório. Com artigos simples, o <filename> Makefile </filename> muitas vezes pode ser copiado literalmente do diretório original em inglês. O processo de tradução combina vários arquivos <filename>book.xml</filename> e <filename>chapter.xml</filename> de livros em um único arquivo, portanto, o <filename> Makefile </filename> para as traduções de livros deve ser copiado e modificado.</para> + + <example xml:id="po-translations-creating-example"> + <title>Criando uma Tradução em Espanhol do Porter's Handbook</title> + + <para>Crie uma nova tradução em Espanhol do <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook">Porter's Handbook</link>. O original é um livro em <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para> + + <procedure> + <step> + <para>O diretório de livros em Espanhol <filename>~/doc/es_ES.ISO8859-1/books/</filename> já existe, portanto, apenas um novo subdiretório para o Porter's Handbook é necessário:</para> + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput> +<prompt>%</prompt> <userinput>svn mkdir porters-handbook</userinput> +A porters-handbook</screen> + </step> + + <step> + <para>Copie o <filename>Makefile</filename> do livro original:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput> +A Makefile</screen> + + <para>Modifique o conteúdo do <filename>Makefile</filename> para esperar apenas um único <filename>book.xml</filename>:</para> + + <programlisting># +# $FreeBSD$ +# +# 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>Agora a estrutura do documento está pronta para o tradutor começar a tradução com <command>make po</command>.</para> + </step> + </procedure> + </example> + + <example xml:id="po-translations-creating-example-french"> + <title>Criando uma tradução em Francês do Artigo Chaves Open <acronym>PGP</acronym></title> + + <para>Crie uma nova tradução em Francês do <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/pgpkeys">artigo Chaves Open <acronym>PGP</acronym></link>. O original é um artigo em <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>.</para> + + <procedure> + <step> + <para>O diretório de artigos em Francês <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> já existe, portanto, apenas um novo subdiretório para o artigo Chaves Open <acronym>PGP</acronym> é necessário:</para> + <screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput> +<prompt>%</prompt> <userinput>svn mkdir pgpkeys</userinput> +A pgpkeys</screen> + </step> + + <step> + <para>Copie o <filename>Makefile</filename> do artigo original:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput> +<prompt>%</prompt> <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput> +A Makefile</screen> + + <para>Verifique o conteúdo do <filename>Makefile</filename>. Este é um artigo simples e neste caso, o <filename>Makefile</filename> pode ser usado sem altaração. A string <literal>$FreeBSD...$</literal> na segunda linha será substituída pelo sistema de controle de versão quando este arquivo sofrer um commit.</para> + + <programlisting># +# $FreeBSD$ +# +# 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>Com a estrutura do documento completa, o arquivo <acronym>PO</acronym> pode ser criado com <command>make po</command>.</para> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-translating"> + <title>Traduzindo</title> + + <para>O sistema <application>gettext</application> reduz bastante o número de itens que devem ser rastreados por um tradutor. As strings a serem traduzidas são extraídas do documento original em um arquivo <acronym>PO</acronym>. Em seguida, um editor <acronym>PO</acronym> é usado para inserir as traduções de cada string.</para> + + <para>O sistema de tradução <acronym>PO</acronym> do FreeBSD não sobrescreve os arquivos <acronym>PO</acronym>, portanto a etapa de extração pode ser executada a qualquer momento para atualizar o arquivo <acronym>PO</acronym>.</para> + + <para>Um editor <acronym>PO</acronym> é usado para editar o arquivo. <package role="port">editores/poedit</package> é usado nestes exemplos porque é simples e tem requisitos mínimos. Outros editores <acronym>PO</acronym> oferecem recursos para facilitar o trabalho de tradução. A Coleção de Ports oferece vários desses editores, incluindo o <package role="port">devel/gtranslator</package>.</para> + + <para>É importante preservar o arquivo <acronym>PO</acronym>. Ele contém todo o trabalho que os tradutores fizeram.</para> + + <example xml:id="po-translations-translating-example"> + <title>Traduzindo o Porter's Handbook para o Espanhol</title> + + <para>Digite as traduções para o Espanhol do conteúdo do Porter's Handbook.</para> + + <procedure> + <step> + <para>Mude para o diretório Espanhol do Porter's Handbook e atualize o arquivo <acronym>PO</acronym>. O arquivo <acronym>PO</acronym> gerado é chamado <filename>es_ES.po</filename> como mostrado em <xref linkend="po-translations-language-names"/>.</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>make po</userinput></screen> + </step> + + <step> + <para>Realize as traduções usando um editor de <acronym>PO</acronym>:</para> + + <screen><prompt>%</prompt> <userinput>poedit es_ES.po</userinput></screen> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-tips"> + <title>Dicas para Tradutores</title> + + <sect2 xml:id="po-translations-tips-xmltags"> + <title>Preservando Tags <acronym>XML</acronym></title> + + <para>Preserve as tags <acronym>XML</acronym> mostradas no original em Inglês.</para> + + <example> + <title>Preservando Tags <acronym>XML</acronym></title> + + <para>Inglês original:</para> + + <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting> + + <para>Tradução para o Espanhol:</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>Preservando Espaços</title> + + <para>Preserve os espaços existentes no início e no final das strings a serem traduzidas. A versão traduzida também deve ter esses espaços.</para> + </sect2> + + <sect2 xml:id="po-translations-tips-verbatim"> + <title>Tags</title> + + <para>O conteúdo de algumas tags devem ser copiadas igualmente, sem realizar tradução:</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>$FreeBSD$</literal> Strings</title> + + <para>As strings da versão $FreeBSD$ usadas nos arquivos requerem tratamento especial. Nos exemplos como <xref linkend="po-translations-creating-example"/>, essas strings não devem ser expandidas. Os documentos em inglês usam entidades <literal>&dollar;</literal> para evitar a inclusão de sinais reais de dólar no arquivo:</para> + + <programlisting>&dollar;FreeBSD&dollar;</programlisting> + + <para>As entidades <literal>&dollar;</literal> não são vistas como cifrões pelo sistema de controle de versão e, portanto, a string não é expandida em uma string de versão.</para> + + <para>Quando um arquivo <acronym>PO</acronym> é criado, as entidades <literal>&dollar;</literal> usadas nos exemplos são substituídas por cifrões reais. A sequência literal <literal>$FreeBSD$</literal> será expandida incorretamente pelo sistema de controle de versão quando o arquivo sofrer algum commit.</para> + + <para>A mesma técnica usada nos documentos em Inglês pode ser usada na tradução. O <literal>&dollar;</literal> é usado para substituir o sinal de dólar na tradução inserida no editor <acronym>PO</acronym>:</para> + + <programlisting>&dollar;FreeBSD&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>Compilando um Documento Traduzido</title> + + <para>Uma versão traduzida do documento original pode ser criada a qualquer momento. Quaisquer porções não traduzidas do original serão incluídas em Inglês no documento resultante. A maioria dos editores <acronym>PO</acronym> tem um indicador que mostra quanto da tradução foi realizada. Isso torna mais fácil para o tradutor ver quantas strings foram traduzidas para tornar a compilação do documento final utiilizável.</para> + + <example xml:id="po-translations-building-example"> + <title>Construindo o Porter's Handbook Espanhol</title> + + <para>Compile e visualize a versão em Espanhol do Porter's Handbook criado em um exemplo anterior.</para> + + <procedure> + <step> + <para>Compile o documento traduzido. Como o original é um livro, o documento gerado é <filename>book.xml</filename>.</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> +<prompt>%</prompt> <userinput>make tran</userinput></screen> + </step> + + <step> + <para>Renderize o <filename>book.xml</filename> traduzido para <acronym>HTML</acronym> e visualize-o com o <application>Firefox</application>. Este é o mesmo procedimento usado com a versão em Inglês dos documentos, e outros <varname>FORMATS</varname> podem ser usados aqui da mesma maneira. Veja <xref linkend="doc-build-rendering-common-formats"/>.</para> + + <screen><prompt>%</prompt> <userinput>make FORMATS=html</userinput> +<prompt>%</prompt> <userinput>firefox book.html</userinput></screen> + </step> + </procedure> + </example> + </sect1> + + <sect1 xml:id="po-translations-submitting"> + <title>Submetendo a Nova Tradução</title> + + <para>Prepare os novos arquivos de tradução para envio. Isso inclui adicionar os arquivos ao sistema de controle de versão, definir propriedades adicionais e criar um diff para a submissão.</para> + + <para>Os arquivos diff criados por esses exemplos podem ser anexados a um <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">relatório de bug de documentação</link> ou <link xlink:href="https://reviews.freebsd.org/">revisão de código</link>.</para> + + <example xml:id="po-translations-submitting-spanish"> + <title>Tradução Espanhola do Artigo NanoBSD</title> + + <procedure> + <step> + <para>Adicione a string FreeBSD na primeira linha do arquivo <acronym>PO</acronym>:</para> + + <programlisting>#$FreeBSD$</programlisting> + </step> + + <step> + <para>Adicione o <filename>Makefile</filename>, o arquivo <acronym>PO</acronym> e o arquivo traduzido <acronym>XML</acronym> que foi gerado para o controle de versão:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput> +<prompt>%</prompt> <userinput>ls</userinput> +Makefile article.xml es_ES.po +<prompt>%</prompt> <userinput>svn add Makefile article.xml es_ES.po</userinput> +A Makefile +A article.xml +A es_ES.po</screen> + </step> + + <step> + <para>Configure as propriedades <application>Subversion</application> <literal>svn:keywords</literal> nesses arquivos para <literal>FreeBSD=%H</literal> para que as strings <literal>$FreeBSD$</literal> sejam expandidas com o caminho, revisão, data e autor quando o arquivo sofrer o commit:</para> + + <screen><prompt>%</prompt> <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>Defina os tipos <acronym>MIME</acronym> dos arquivos. Estes são <literal>text/xml</literal> para livros e artigos, e <literal>text/x-gettext-translation</literal> para o arquivo <acronym>PO</acronym>.</para> + + <screen><prompt>%</prompt> <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput> +property 'svn:mime-type' set on 'es_ES.po' +<prompt>%</prompt> <userinput>svn propset svn:mime-type text/xml article.xml</userinput> +property 'svn:mime-type' set on 'article.xml'</screen> + </step> + + <step> + <para>Crie um diff dos novos arquivos a partir do diretório base <filename>~/doc/</filename> para que o caminho completo seja mostrado com os nomes dos arquivos. Isso ajuda os committers a identificar o diretório do idioma de destino.</para> + + <screen><prompt>%</prompt> <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>Tradução Coreana <acronym>UTF-8</acronym> do Artigo Explicando o BSD</title> + + <procedure> + <step> + <para>Adicione a string FreeBSD na primeira linha do arquivo <acronym>PO</acronym>:</para> + + <programlisting>#$FreeBSD$</programlisting> + </step> + + <step> + <para>Adicione o <filename>Makefile</filename>, o arquivo <acronym>PO</acronym> e o arquivo traduzido <acronym>XML</acronym> que foi gerado para o controle de versão:</para> + + <screen><prompt>%</prompt> <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput> +<prompt>%</prompt> <userinput>ls</userinput> +Makefile article.xml ko_KR.po +<prompt>%</prompt> <userinput>svn add Makefile article.xml ko_KR.po</userinput> +A Makefile +A article.xml +A ko_KR.po</screen> + </step> + + <step> + <para>Configure as propriedades <application>Subversion</application> <literal>svn:keywords</literal> nesses arquivos para <literal>FreeBSD=%H</literal> para que as strings <literal>$FreeBSD$</literal> sejam expandidas com o caminho, revisão, data e autor quando o arquivo sofrer o commit:</para> + + <screen><prompt>%</prompt> <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>Defina os tipos <acronym>MIME</acronym> dos arquivos. Como esses arquivos usam o conjunto de caracteres <acronym>UTF-8</acronym>, isso também é especificado. Para evitar que o sistema de controle de versão confunda esses arquivos com arquivos binários, a propriedade <literal>fbsd:notbinary</literal> também é configurada:</para> + + <screen><prompt>%</prompt> <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>%</prompt> <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput> +property 'fbsd:notbinary' set on 'ko_KR.po' +<prompt>%</prompt> <userinput>svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml</userinput> +property 'svn:mime-type' set on 'article.xml' +<prompt>%</prompt> <userinput>svn propset fbsd:notbinary yes article.xml</userinput> +property 'fbsd:notbinary' set on 'article.xml'</screen> + </step> + + <step> + <para>Crie um diff desses novos arquivos no diretório base <filename>~/doc/</filename>:</para> + + <screen><prompt>%</prompt> <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> + + +<!-- + The FreeBSD Documentation Project +--> +<chapter version="5.0" xml:id="manpages"> + + <title>Páginas de Manual</title> + + <sect1 xml:id="manpages-introduction"> + <title>Introdução</title> + + <para><emphasis>Páginas de manual</emphasis>, geralmente abreviadas como <emphasis>man pages</emphasis>, foram concebidas como lembretes prontamente disponíveis para sintaxe de comandos, detalhes de drivers de dispositivos ou formatos de arquivos de configuração. Elas se tornaram uma referência rápida extremamente valiosa de linha de comando para usuários, administradores de sistema e programadores.</para> + + <para>Embora tenham sido planejados como material de referência em vez de tutoriais, as seções EXEMPLOS das páginas de manual geralmente fornecem casos de uso detalhados.</para> + + <para>Páginas de manual são geralmente mostradas interativamente pelo comando <citerefentry><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Quando o usuário digita <command>man ls</command>, uma pesquisa é executada para uma página de manual que corresponde a <literal>ls</literal>. O primeiro resultado correspondente é exibido.</para> + </sect1> + + <sect1 xml:id="manpages-sections"> + <title>Seções</title> + + <para>As páginas de manual são agrupadas em <emphasis>seções</emphasis>. Cada seção contém páginas de manual para uma categoria específica de documentação:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Número da Seção</entry> + <entry>Categoria</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>Comandos Gerais</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>Interfaces de Kernel</entry> + </row> + + <row> + <entry>5</entry> + <entry>Formatos de Arquivo</entry> + </row> + + <row> + <entry>6</entry> + <entry>Jogos</entry> + </row> + + <row> + <entry>7</entry> + <entry>Diversos</entry> + </row> + + <row> + <entry>8</entry> + <entry>System Manager</entry> + </row> + + <row> + <entry>9</entry> + <entry>Desenvolvedor Kernel</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="manpages-markup"> + <title>Marcação</title> + + <para>Vários formulários de marcação e programas de renderização foram usados para páginas de manual. O FreeBSD usou <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>7</manvolnum></citerefentry> e o mais recente <citerefentry><refentrytitle>mandoc</refentrytitle><manvolnum>1</manvolnum></citerefentry>. A maioria das páginas de manual do FreeBSD, e todas as novas, usam o formulário <citerefentry><refentrytitle>mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry> de marcação. Esta é uma marcação simples baseada em linhas que é razoavelmente expressiva. É principalmente semântico: partes do texto são marcadas para o que são, em vez de como devem aparecer quando renderizadas. Existe alguma marcação baseada em aparência que geralmente é melhor evitar.</para> + + <para>O código fonte de página de manual geralmente é interpretada e exibido na tela interativamente. Os arquivos fontes podem ser arquivos de texto comuns ou compactados com <citerefentry><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry> para economizar espaço.</para> + + <para>As páginas de manual também podem ser renderizadas para outros formatos, incluindo PostScript para impressão ou geração de <acronym>PDF</acronym>. Veja <citerefentry><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <tip> + <para>O teste de uma nova página de manual pode ser um desafio quando o arquivo não está localizado no caminho de pesquisa normal da páginas de manual. <citerefentry><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry> também não procura no diretório atual. Se a nova página de manual estiver no diretório atual, prefixe o nome do arquivo com um <literal>./</literal>:</para> + + <screen><prompt>%</prompt> <userinput>man ./mynewmanpage.8</userinput></screen> + + <para>Um caminho absoluto também pode ser usado:</para> + + <screen><prompt>%</prompt> <userinput>man /home/xsmith/mynewmanpage.8</userinput></screen> + </tip> + + + <sect2 xml:id="manpages-markup-sections"> + <title>Seções de Página de Manual</title> + + <para>Páginas de manual são compostas por várias seções padrão. Cada seção tem um título em letras maiúsculas e as seções de um determinado tipo de página de manual aparecem em uma ordem específica. Para uma página de manual do Comando Geral da categoria 1, as seções são:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Nome da Seção</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry>NAME</entry> + <entry>Nome do Comando</entry> + </row> + + <row> + <entry>SYNOPSIS</entry> + <entry>Formato das opções e argumentos</entry> + </row> + + <row> + <entry>DESCRIPTION</entry> + <entry>Descrição da finalidade e uso</entry> + </row> + + <row> + <entry>ENVIRONMENT</entry> + <entry>Configurações de ambiente que afetam a operação</entry> + </row> + + <row> + <entry>EXIT STATUS</entry> + <entry>Códigos de erro retornados na saída</entry> + </row> + + <row> + <entry>EXAMPLES</entry> + <entry>Exemplos de uso</entry> + </row> + + <row> + <entry>COMPATIBILITY</entry> + <entry>Compatibilidade com outras implementações</entry> + </row> + + <row> + <entry>SEE ALSO</entry> + <entry>Referência cruzada para páginas de manual relacionadas</entry> + </row> + + <row> + <entry>STANDARDS</entry> + <entry>Compatibilidade com padrões como o POSIX</entry> + </row> + + <row> + <entry>HISTORY</entry> + <entry>História de implementação</entry> + </row> + + <row> + <entry>BUGS</entry> + <entry>Bugs conhecidos</entry> + </row> + + <row> + <entry>AUTHORS</entry> + <entry>Pessoas que criaram o comando ou escreveram a página de manual.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Algumas seções são opcionais e a combinação de seções para um tipo específico de página manual pode variar. Exemplos dos tipos mais comuns são mostrados mais adiante neste capítulo.</para> + </sect2> + + <sect2 xml:id="manpages-markup-macros"> + <title>Macros</title> + + <para>A marcação <citerefentry><refentrytitle>mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry> é baseada em <emphasis>macros</emphasis>. As linhas que começam com um ponto contêm comandos de macro, com duas ou três letras. Por exemplo, veja esta parte da página de manual do <citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</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>O <emphasis>Document date</emphasis> e <emphasis>Document title</emphasis> são definidos.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-2"> + <para>O <emphasis>Cabeçalho da Seção</emphasis> para a seção NAME é definido. Em seguida, são definidos o <emphasis>Nome</emphasis> do comando e uma <emphasis>Descrição do Nome</emphasis> de uma linha.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-3"> + <para>A seção SYNOPSIS começa. Esta seção descreve as opções e argumentos de linha de comando que são aceitos.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-4"> + <para><emphasis>Nome</emphasis> (<literal>.Nm</literal>) já foi definido, e repeti-lo aqui apenas exibe o valor definido no texto.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-5"> + <para>Uma <emphasis>Optional</emphasis> <emphasis>Flag</emphasis> chamada <literal>-libxo</literal> é mostrada. A macro <literal>Fl</literal> adiciona um traço ao início das flags, portanto, isso aparece na página de manual como <literal>--libxo</literal>.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-6"> + <para>Uma longa lista de sinalizadores opcionais de caracteres únicos é apresentada.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-7"> + <para>Uma flag opcional <literal>-D</literal> é definida. Se a flag <literal>-D</literal> for informada, ela deve ser seguida por um <emphasis>Argumento</emphasis>. O argumento é um <emphasis>format</emphasis>, uma string que diz <citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry> o que exibir e como exibi-lo. Detalhes sobre a string de formato são fornecidos posteriormente na página de manual.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-8"> + <para>Um argumento opcional final é definido. Como nenhum nome é especificado para o argumento, o padrão <literal>file ...</literal> é usado.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-9"> + <para>O <emphasis>Cabeçalho da Seção</emphasis> para a seção DESCRIPTION é definido.</para> + </callout> + </calloutlist> + + <para>Quando renderizado com o comando <command>man ls</command>, o resultado exibido na tela é semelhante ao seguinte:</para> + + <programlisting>LS(1) FreeBSD General Commands Manual LS(1) + +NAME + ls — 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>Valores opcionais são mostrados entre colchetes.</para> + </sect2> + + <sect2 xml:id="manpages-markup-guidelines"> + <title>Diretrizes de Marcação</title> + + <para>A linguagem de marcação <citerefentry><refentrytitle>mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry> não é muito rigorosa. Para maior clareza e consistência, o projeto Documentação do FreeBSD adiciona algumas diretrizes de estilo adicionais:</para> + + <variablelist> + <varlistentry> + <term>Apenas a primeira letra das macros é maiúscula</term> + + <listitem> + <para>Sempre use maiúsculas para a primeira letra de uma macro e minúscula para as letras restantes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Comece novas frases em novas linhas</term> + + <listitem> + <para>Inicie uma nova frase em uma nova linha, não a inicie na mesma linha de uma frase existente.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Atualizar <literal>.Dd</literal> ao fazer alterações não triviais em uma página de manual</term> + + <listitem> + <para>A <emphasis>Data do documento</emphasis> informa o leitor sobre a última vez que a página de manual foi atualizada. É importante atualizar sempre que alterações não triviais forem feitas nas páginas de manual. Alterações triviais, como correções ortográficas ou de pontuação que não afetam o uso, podem ser feitas sem atualizar <literal>.Dd</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Apresentando exemplos</term> + + <listitem> + <para>Apresente exemplos ao leitor sempre que possível. Mesmo exemplos triviais são valiosos, porque o que é trivial para o escritor não é necessariamente trivial para o leitor. Três exemplos são um bom objetivo. Um exemplo trivial mostra os requisitos mínimos, um exemplo afundo mostra o uso real e um exemplo detalhado demonstra uma funcionalidade incomum ou não óbvia.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Inclua a licença BSD</term> + + <listitem> + <para>Inclua a licença BSD em novas páginas de manual. A licença preferencial está disponível no <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guidepref-license">Guia dos Committer's</link>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="manpages-markup-tricks"> + <title>Truques de Marcação</title> + + <para>Adicione um espaço antes da pontuação em uma linha com macros. Exemplo:</para> + + <programlisting>.Sh SEE ALSO +.Xr geom 4 , +.Xr boot0cfg 8 , +.Xr geom 8 , +.Xr gptboot 8</programlisting> + + <para>Observe como as vírgulas no final das linhas <literal>.Xr</literal> foram colocadas após um espaço. A macro <literal>.Xr</literal> espera dois parâmetros, o nome de uma página de manual externa e um número de seção. O espaço separa a pontuação do número da seção. Sem o espaço, os links externos apontariam incorretamente para a seção <literal>4,</literal> ou <literal>8,</literal>.</para> + </sect2> + + <sect2 xml:id="manpages-markup-important-macros"> + <title>Macros Importantes</title> + + <para>Algumas macros muito comuns serão mostradas aqui. Para obter mais exemplos de uso, consulte <citerefentry><refentrytitle>mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>groff_mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry>, ou procure por uso real no diretório <filename>/usr/share/man/man*</filename>. Por exemplo, para procurar exemplos da macro <literal>.Bd</literal> <emphasis>Begin display</emphasis>:</para> + + <screen><prompt>%</prompt> <userinput>find /usr/share/man/man* | xargs zgrep '.Bd'</userinput></screen> + + <sect3 xml:id="manpages-markup-important-macros-organizational"> + <title>Macros Organizacionais</title> + + <para>Algumas macros são usadas para definir blocos lógicos de uma página de manual.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Macro Organizacional</entry> + <entry>Uso</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>.Sh</literal></entry> + <entry>Section header (Cabeçalho da seção). Seguido pelo nome da seção, tradicionalmente com os caracteres todos em maiúsculas. Pense neles como títulos de capítulos.</entry> + </row> + + <row> + <entry><literal>.Ss</literal></entry> + <entry>Subsection header (Cabeçalho da subseção). Seguido pelo nome da subseção. Usado para dividir uma seção <literal>.Sh</literal> em subseções.</entry> + </row> + + <row> + <entry><literal>.Bl</literal></entry> + <entry>Begin list. Comece uma lista de itens.</entry> + </row> + + <row> + <entry><literal>.El</literal></entry> + <entry>End a list (Finalize uma lista).</entry> + </row> + + <row> + <entry><literal>.Bd</literal></entry> + <entry>Begin display (Comece a exibição). Comece em uma área especial de texto, como uma área recuada.</entry> + </row> + + <row> + <entry><literal>.Ed</literal></entry> + <entry>End display (Termine a exibição).</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + + <sect3 xml:id="manpages-markup-important-macros-inline"> + <title>Macros Inline</title> + + <para>Muitas macros são usadas para marcar texto embutido.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Macro Inline</entry> + <entry>Uso</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>.Nm</literal></entry> + <entry>Name. Chamado com um nome como parâmetro no primeiro uso, usado depois sem o parâmetro para exibir o nome que já foi definido.</entry> + </row> + + <row> + <entry><literal>.Pa</literal></entry> + <entry>Path to a file (Caminho para um arquivo). Usado para marcar nomes de arquivos e caminhos de diretório.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="manpages-sample-structures"> + <title>Exemplo de Estruturas de Página de Manual</title> + + <para>Esta seção mostra o conteúdo mínimo desejável para um página de manual para várias categorias comuns de páginas de manual.</para> + + <sect2 xml:id="manpages-sample-structures-section-1-8"> + <title>Seção 1 ou 8 sobre um comando</title> + + <para>A estrutura básica preferida para uma seção 1 ou 8 sobre um comando:</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>Seção 4 sobre um Driver de Dispositivo</title> + + <para>A estrutura básica preferida para a seção 4 sobre um driver de dispositivo:</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>Seção 5 sobre um Arquivo de Configuração</title> + + <para>A estrutura básica preferida para a seção 5 sobre um arquivo de configuração:</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>Exemplos de páginas de manuais para usar como modelos</title> + + <para>Algumas destas páginas de manual são adequadas para serem usadas como exemplos detalhados.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Página Manual</entry> + <entry>Caminho para o local de origem</entry> + </row> + </thead> + + <tbody> + <row> + <entry><citerefentry><refentrytitle>cp</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry><filename>/usr/src/bin/cp/cp.1</filename></entry> + </row> + + <row> + <entry><citerefentry><refentrytitle>vt</refentrytitle><manvolnum>4</manvolnum></citerefentry></entry> + <entry><filename>/usr/src/share/man/man4/vt.4</filename></entry> + </row> + + <row> + <entry><citerefentry><refentrytitle>crontab</refentrytitle><manvolnum>5</manvolnum></citerefentry></entry> + <entry><filename>/usr/src/usr.sbin/cron/crontab/crontab.5</filename></entry> + </row> + + <row> + <entry><citerefentry><refentrytitle>gpart</refentrytitle><manvolnum>8</manvolnum></citerefentry></entry> + <entry><filename>/usr/src/sbin/geom/class/part/gpart.8</filename></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="manpages-resources"> + <title>Recursos</title> + + <para>Recursos para escritores de páginas manuais:</para> + + <itemizedlist> + <listitem> + <para><citerefentry><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> + </listitem> + + <listitem> + <para><citerefentry><refentrytitle>mandoc</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> + </listitem> + + <listitem> + <para><citerefentry><refentrytitle>groff_mdoc</refentrytitle><manvolnum>7</manvolnum></citerefentry></para> + </listitem> + + <listitem> + <para><link xlink:href="http://manpages.bsd.lv/mdoc.html">Manuais Práticos do UNIX: mdoc</link></para> + </listitem> + + <listitem> + <para><link xlink:href="http://manpages.bsd.lv/history.html">História das Man pages do UNIX</link></para> + </listitem> + </itemizedlist> + </sect1> +</chapter> + + +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +--> +<chapter version="5.0" xml:id="writing-style"> + <title>Estilo de escrita</title> + + <sect1 xml:id="writing-style-tips"> + <title>Dicas</title> + + <para>A documentação técnica pode ser melhorada pelo uso consistente de vários princípios. A maioria destes pode ser classificada em três objetivos: <emphasis>ser claro</emphasis>, <emphasis>ser completo</emphasis> e <emphasis>ser conciso</emphasis>. Essas metas podem entrar em conflito umas com as outras. Uma boa escrita consiste em um equilíbrio entre eles.</para> + + <sect2 xml:id="writing-style-be-clear"> + <title>Seja claro</title> + + <para>A clareza é extremamente importante. O leitor pode ser um novato ou ler o documento em um segundo idioma. Esforce-se por um texto simples e descomplicado que explique claramente os conceitos.</para> + + <para>Evite discurso florido ou embelezado, piadas ou expressões coloquiais. Escreva da maneira mais simples e clara possível. Um texto simples é mais fácil de se entender e de se traduzir.</para> + + <para xml:lang="en">Keep explanations as short, simple, and clear as possible. + Avoid empty phrases like <quote>in order to</quote>, which + usually just means <quote>to</quote>. Avoid potentially + patronizing words like <quote>basically</quote>. Avoid Latin + terms like <quote>i.e.,</quote> or <quote>cf.</quote>, which + may be unknown outside of academic or scientific + groups.</para> + + <para>Escreva em um estilo formal. Evite dirigir-se ao leitor como <quote>você</quote>. Por exemplo, digamos <quote>copie o arquivo para <filename>/tmp</filename></quote> em vez de <quote>você pode copiar o arquivo para <filename>/tmp</filename></quote>.</para> + + <para>Dê exemplos claros, corretos, e <emphasis>testados</emphasis>. Um exemplo trivial é melhor do que nenhum exemplo. Um bom exemplo é ainda melhor. Não dê exemplos ruins, identificáveis por desculpas ou frases como <quote>mas realmente isso nunca deve ser feito dessa forma</quote>. Exemplos ruins são piores que nenhum exemplo. Dê bons exemplos, porque <emphasis>mesmo quando avisado para não usar o exemplo como mostrado </emphasis>, o leitor normalmente só usa o exemplo como mostrado.</para> + + <para>Evite <emphasis>palavras vazias</emphasis> como <quote>deveria</quote>, <quote>poderia</quote>, <quote>tentaria</quote>, ou <quote>podia</quote>. Estas palavras implicam que o autor não tem certeza dos fatos e cria dúvidas no leitor.</para> + + <para>Da mesma forma, dê instruções como comandos imperativos: não utilize <quote>você deve fazer isso</quote>, mas apenas <quote>faça isso</quote>.</para> + </sect2> + + <sect2 xml:id="writing-style-be-complete"> + <title>Seja completo</title> + + <para>Não faça suposições sobre as habilidades do leitor. Diga-lhes o que precisam saber. Dê links para outros documentos para fornecer informações básicas sem precisar recriá-las. Coloque-se no lugar do leitor, antecipe as perguntas que eles farão e responda-os.</para> + </sect2> + + <sect2 xml:id="writing-style-be-concise"> + <title>Seja conciso</title> + + <para>Embora as funcionalidades devam ser documentadas completamente, às vezes existe tanta informação que o leitor não consegue encontrar facilmente os detalhes específicos de que necessita. O equilíbrio entre ser completo e ser conciso é um desafio. Uma abordagem é ter uma introdução e, em seguida, uma seção de <quote>início rápido</quote> que descreve a situação mais comum, seguida por uma seção de referência aprofundada.</para> + </sect2> + </sect1> + + <sect1 xml:id="writing-style-guidelines"> + <title>Diretrizes</title> + + <para>Para promover a consistência entre os inúmeros autores da documentação do FreeBSD, algumas diretrizes foram elaboradas para os autores seguirem.</para> + + <variablelist> + <varlistentry> + <term>Use a Ortografia do Inglês Americano</term> + + <listitem> + <para>Existem várias variantes do inglês, com grafias diferentes para a mesma palavra. Onde as grafias diferem, use a variante do inglês americano. <quote>color</quote>, não <quote>colour</quote>, <quote>rationalize</quote>, não <quote>rationalise</quote>, e assim por diante.</para> + + <note> + <para>O uso do inglês britânico pode ser aceito no caso de um artigo contribuído, no entanto, a ortografia deve ser consistente em todo o documento. Os outros documentos, como livros, site, páginas de manual, etc., terão que usar o inglês americano.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>Não use contrações</term> + + <listitem> + <para>Não use contrações. Sempre soletre a frase na íntegra. <quote>Do not</quote> é a forma correta, <quote>Don't</quote> é a errada.</para> + + <para>Evitar contrações contribui para um tom mais formal, é mais preciso e é um pouco mais fácil para os tradutores.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Use a vírgula serial</term> + + <listitem> + <para>Em uma lista de itens dentro de um parágrafo, separe cada item dos outros com uma vírgula. Separe o último item dos outros com uma vírgula e a letra <quote>e</quote>.</para> + + <para>Por exemplo:</para> + + <blockquote> + <para>Esta é uma lista de um, dois e três itens.</para> + </blockquote> + + <para>É uma lista de três itens, <quote>um</quote>, <quote>dois</quote> e <quote>três</quote>, ou uma lista de dois itens, <quote>um</quote> e <quote>dois e três</quote>?</para> + + <para>É melhor ser explícito e incluir uma vírgula serial:</para> + + <blockquote> + <para>Esta é uma lista de um, dois, e três itens.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Evite frases redundantes</term> + + <listitem> + <para>Não use frases redundantes. Em particular, <quote>o comando</quote>, <quote>o arquivo</quote> e o <quote>comando man</quote> são frequentemente redundantes.</para> + + <para>Por exemplo, comandos:</para> + + <informalexample> + <para>Errado: Use o comando <command>svn</command> para atualizar o código fonte.</para> + </informalexample> + + <informalexample> + <para>Correto: Use o <command>svn</command> para atualizar o código fonte.</para> + </informalexample> + + <para>Nomes de arquivo:</para> + + <informalexample> + <para>Errado:… no nome do arquivo <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>Correto:… no <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>Referências de páginas de manual (o segundo exemplo usa <tag>citerefentry</tag> com a entidade <literal>&man.csh.1;</literal>):</para> + + <informalexample> + <para>Errado: Veja <command>man csh</command> para mais informações.</para> + </informalexample> + + <informalexample> + <para>Correto: Veja <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry> + <term>Dois espaços entre frases</term> + + <listitem> + <para>Sempre use dois espaços entre as sentenças, pois isso melhora a legibilidade e facilita o uso de ferramentas como o <application>Emacs</application>.</para> + + <para>Um período e espaços seguidos por uma letra maiúscula nem sempre marcam uma nova sentença, especialmente em nomes. <quote>Jordan K. Hubbard</quote> é um bom exemplo. Ele tem um capital <literal>H</literal> após um período e um espaço, e certamente não é uma nova sentença.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Para mais informações sobre o estilo de escrita, consulte <link xlink:href="http://www.bartleby.com/141/">Elementos de Estilo</link>, de William Strunk.</para> + </sect1> + + <sect1 xml:id="writing-style-guide"> + <title>Guia de estilo</title> + + <para>Para manter o código fonte da documentação consistente quando muitas pessoas diferentes a estiverem editando, siga estas convenções de estilo.</para> + + <sect2 xml:id="writing-style-letter-case"> + <title>Letter Case</title> + + <para>As tags são digitadas em minúsculas, <tag>para</tag>, <emphasis>não</emphasis> <tag>PARA</tag>.</para> + + <para>O texto que aparece em contextos SGML é geralmente escrito em letras maiúsculas, <literal><! ENTITY ... ></literal>, e <literal><! DOCTYPE… ></literal>, <emphasis>não</emphasis> <literal><! entity… ></literal> e <literal><! doctype… ></literal>.</para> + </sect2> + + <sect2 xml:id="writing-style-acronyms"> + <title>Siglas</title> + + <para>Os acrônimos devem ser definidos na primeira vez que aparecerem em um documento, como em: <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>. Depois que o acrônimo tiver sido definido, use apenas o acrônimo, a menos que faça mais sentido contextualmente usar todo o termo. Acrônimos geralmente são definidos apenas uma vez por capítulo ou por documento.</para> + + <para>Todos os acrônimos devem ser colocados em tags <tag>acronym</tag>.</para> + </sect2> + + <sect2 xml:id="writing-style-indentation"> + <title>Indentação</title> + + <para>A primeira linha em cada arquivo começa sem recuo, <emphasis>independentemente</emphasis> do nível de recuo do arquivo que pode conter o arquivo atual.</para> + + <para>Tags de abertura aumentam o nível de recuo por dois espaços. Tags de fechamento diminuem o nível de recuo por dois espaços. Blocos de oito espaços no início de uma linha devem ser substituídos por um tab. Não use espaços na frente das tabs e não adicione espaço em branco extra no final de uma linha. O conteúdo nos elementos deve ser indentado por dois espaços se o conteúdo for executado em mais de uma linha.</para> + + <para>Por exemplo, a fonte desta seção é assim:</para> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>The first line in each file starts with no indentation, + <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of + the file which might contain the current file.<tag class="endtag">para</tag> + + ... + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + + <para>Tags contendo atributos longos seguem as mesmas regras. Seguir as regras de recuo neste caso ajuda editores e escritores a ver qual conteúdo está dentro das tags:</para> + + <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link + linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag> + section if there are problems booting. Powering down and + disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk + will allow it to be kept as an offline backup.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os; + system. Refer to the article <tag class="starttag">link + xlink:href="&url.articles.gjournal-desktop;"</tag>Implementing UFS + Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed + instructions.<tag class="endtag">para</tag></programlisting> + + <para>Quando um elemento é muito longo para caber no restante de uma linha sem quebrá-la, mover a tag inicial para a próxima linha pode facilitar a leitura do código. Neste exemplo, o elemento <literal>systemitem</literal> foi movido para a próxima linha para evitar a quebra e o recuo:</para> + + <programlisting><tag class="starttag">para</tag>With file flags, even + <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be + prevented from removing or altering files.<tag class="endtag">para</tag></programlisting> + + <para>Configurações para ajudar vários editores de texto a operar em conformidade com estas diretrizes podem ser encontradas em <xref linkend="editor-config"/>.</para> + </sect2> + + <sect2 xml:id="writing-style-tag-style"> + <title>Estilo de Tag</title> + + <sect3 xml:id="writing-style-tag-style-spacing"> + <title>Espaçamento de tag</title> + + <para>Tags que começam no mesmo recuo como uma tag anterior devem ser separadas por uma linha em branco, e aquelas que não estão no mesmo recuo como uma tag anterior não devem:</para> + + <informalexample> + <programlisting><tag class="starttag">article lang='en'</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> + + <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>... + ... + ...<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> + </informalexample> + </sect3> + + <sect3 xml:id="writing-style-tag-style-separating"> + <title>Separando Tags</title> + + <para>Tags como <tag>itemizedlist</tag>, que sempre terão outras tags dentro delas, e de fato não pegam dados de caractere, estão sempre sozinhas em uma linha.</para> + + <para>Tags como <tag>para</tag> e <tag>term</tag> não precisam de outras tags para conter dados de caracteres normais, e seus conteúdos começam imediatamente após a tag, <emphasis>na mesma linha</emphasis> .</para> + + <para>O mesmo se aplica quando esses dois tipos de tags fecham.</para> + + <para>Isso leva a um problema óbvio ao misturar essas tags.</para> + + <para>Quando uma tag inicial que não pode conter dados de caractere segue diretamente uma tag do tipo que requer outras tags dentro dela para usar dados de caractere, elas estão em linhas separadas. A segunda tag deve estar corretamente recuada.</para> + + <para>Quando uma tag que pode conter dados de caractere é fechada diretamente após uma tag que não pode conter dados de caractere fechados, eles coexistem na mesma linha.</para> + </sect3> + </sect2> + + <sect2 xml:id="writing-style-whitespace-changes"> + <title>Mudanças no espaço em branco</title> + + <para><emphasis>Não faça commit de mudanças no conteúdo ao mesmo tempo em que faz mudanças na formatação</emphasis>.</para> + + <para>Quando as alterações de conteúdo e espaço em branco são mantidas separadas, as equipes de tradução podem ver facilmente se uma alteração foi de um conteúdo que deve ser traduzido ou apenas espaço em branco.</para> + + <para>Por exemplo, se duas sentenças foram adicionadas a um parágrafo para que os comprimentos de linha passem de 80 colunas, primeiro faça commit da alteração com as linhas longas demais. Em seguida, corrija a quebra de linha e confirme essa segunda alteração. Na mensagem de confirmação da segunda alteração, indique que esta é uma alteração somente de espaço em branco a qual pode ser ignorada pelos tradutores.</para> + </sect2> + + <sect2 xml:id="writing-style-nonbreaking-space"> + <title>Espaços Não Separáveis (Non-Breaking Space)</title> + + <para>Evite quebras de linha em locais onde elas pareçam feias ou dificultem o entendimento de uma frase. Quebras de linha dependem da largura do meio de saída escolhido. Em particular, a visualização da documentação em HTML com um navegador de texto pode levar a parágrafos mal formatados como o seguinte:</para> + + <literallayout class="monospaced">A capacidade de dados varia de 40 MB a 15 +GB Compressão de hardware…</literallayout> + + <para>A entidade geral <literal>&nbsp;</literal> proíbe as quebras de linha entre as partes que estão juntas. Use espaços não separáveis nos seguintes locais:</para> + + <itemizedlist> + <listitem> + <para>entre números e unidades:</para> + <programlisting>57600&nbsp;bps</programlisting> + </listitem> + + <listitem> + <para>entre nomes de programas e números de versão:</para> + <programlisting>&os;&nbsp;9.2</programlisting> + </listitem> + + <listitem> + <para>entre nomes com várias palavras (use com cautela ao aplicar isso em nomes de mais de 3-4 palavras como <quote>The FreeBSD Portuguese Portuguese Documentation Project</quote>):</para> + <programlisting>Sun &Microsystems</programlisting> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 xml:id="writing-style-word-list"> + <title>Lista de palavras</title> + + <para>Esta lista de palavras mostra a ortografia e letras maiúsculas corretas quando usadas na documentação do FreeBSD. Se uma palavra não estiver nesta lista, pergunte sobre isso na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">lista de discussão do projeto de documentação do FreeBSD</link>.</para> + + <informaltable frame="none" pgwide="0"> + <tgroup cols="3"> + <thead> + <row> + <entry>Palavra</entry> + <entry>Código XML</entry> + <entry>Notas</entry> + </row> + </thead> + + <tbody> + <row> + <entry>CD-ROM</entry> + + <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry> + </row> + + <row> + <entry>DoS (negação de serviço)</entry> + <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry> + </row> + + <row> + <entry>email</entry> + </row> + + <row> + <entry>sistema de arquivo</entry> + </row> + + <row> + <entry>IPsec</entry> + </row> + + <row> + <entry>Internet</entry> + </row> + + <row> + <entry>página de manual</entry> + </row> + + <row> + <entry>servidor de email</entry> + </row> + + <row> + <entry>nome do servidor</entry> + </row> + + <row> + <entry>Coleção de Ports</entry> + </row> + + <row> + <entry>somente leitura</entry> + </row> + + <row> + <entry>Soft Updates</entry> + </row> + + <row> + <entry>stdin</entry> + <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>stdout</entry> + <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>stderr</entry> + <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry> + </row> + + <row> + <entry>Subversion</entry> + + <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry> + <entry>Não se refira ao aplicativo Subversion como <literal>SVN</literal> em letras maiúsculas. Para se referir ao comando, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry> + </row> + + <row> + <entry><trademark class="registered">UNIX</trademark></entry> + <entry><literal>&unix;</literal></entry> + </row> + + <row> + <entry>userland</entry> + <entry/> + <entry>coisas que se aplicam ao espaço do usuário, não ao kernel</entry> + </row> + + <row> + <entry>servidor web</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="editor-config"> + + <title>Configuração do Editor</title> + + <para>Ajustar a configuração do editor de texto pode tornar o trabalho nos arquivos da documentação mais rápido e fácil, além de ajudar os documentos a ficarem em conformidade com as diretrizes do <acronym>FDP</acronym>.</para> + + <sect1 xml:id="editor-config-vim"> + <title><application>Vim</application></title> + + <para>Instale-o a partir de <package>editors/vim</package>, <package>editors/vim-console</package>, ou <package>editors/vim-tiny</package> e siga as instruções de configuração em <xref linkend="editor-config-vim-config"/>.</para> + + <sect2 xml:id="editor-config-vim-use"> + <title>Uso</title> + + <para>Pressione <keycap>P</keycap> para reformatar parágrafos ou texto selecionado no modo Visual. Pressione <keycap>T</keycap> para substituir grupos de oito espaços por um tab.</para> + </sect2> + + <sect2 xml:id="editor-config-vim-config"> + <title>Configuração</title> + + <para>Edite o <filename>~/.vimrc</filename>, adicionando estas linhas ao final do arquivo:</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 "&[^;]*;" + 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/<CR> + 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>Instale-o a partir de <package>editors/emacs</package> ou <package>editors/emacs-devel</package>.</para> + + <sect2 xml:id="editor-config-emacs-validation"> + <title>Validação</title> + + <para>O modo nxml do Emacs usa esquemas NG relax compacto para validar o XML. Um esquema NG relax compacto para a extensão do FreeBSD para DocBook 5.0 está incluído no repositório de documentação. Para configurar o modo nxml para validar usando este esquema, crie <filename>~/.emacs.d/schema/schemas.xml</filename> e adicione estas linhas ao arquivo:</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>Revisão Automatizada com Flycheck e Igor</title> + + <para>O pacote Flycheck está disponível no Emacs Lisp Package Archive da Milkypostman (<acronym>MELPA</acronym>). Se a <acronym>MELPA</acronym> ainda não estiver nos repositórios de pacotes do Emacs, ele pode ser adicionado executando</para> + + <programlisting>(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)</programlisting> + + <para>Adicione a linha ao arquivo de inicialização do Emacs (qualquer um deles, <filename>~/.emacs</filename>, <filename>~/.emacs.el</filename>, ou <filename>~.emacs.d/init.el</filename>) para tornar esta alteração permanente.</para> + + <para>Para instalar o Flycheck, execute</para> + + <programlisting>(package-install 'flycheck)</programlisting> + + <para>Crie um verificador Flycheck para <package>textproc/igor</package> executando</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>Novamente, adicione essas linhas ao arquivo de inicialização do Emacs para tornar as mudanças permanentes.</para> + </sect2> + + <sect2 xml:id="editor-config-emacs-specifc"> + <title>Configurações Específicas da Documentação do FreeBSD</title> + + <para>Para aplicar configurações específicas para o projeto de documentação do FreeBSD, crie o arquivo <filename>.dir-locals.el</filename> no diretório raiz do repositório de documentação e adicione estas linhas ao arquivo:</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>Instale o aplicativo partir de <package>editors/nano</package> ou <package>editors/nano-devel</package>.</para> + + <sect2 xml:id="editor-config-nano-config"> + <title>Configuração</title> + + <para>Copie o arquivo com a amostra da regra para realce da sintaxe <acronym>XML</acronym> para o diretório inicial do usuário:</para> + + <screen><prompt>%</prompt> <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen> + + <para>Use um editor para substituir as linhas do <filename>~/.nanorc</filename> referentes ao bloco <literal>syntax "xml"</literal> por estas regras:</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>Processe o arquivo para criar guias incorporadas:</para> + + <screen><prompt>%</prompt> <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen> + </sect2> + + <sect2 xml:id="editor-config-nano-use"> + <title>Uso</title> + + <para>Especifique opções úteis adicionais ao executar o editor:</para> + + <screen><prompt>%</prompt> <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen> + + <para>Usuários do <citerefentry><refentrytitle>csh</refentrytitle><manvolnum>1</manvolnum></citerefentry> podem definir um alias em <filename>~/.cshrc</filename> para automatizar estas opções:</para> + + <programlisting>alias nano "nano -AKipwz -r 70 -T8"</programlisting> + + <para>Depois que o alias é definido, as opções serão adicionadas automaticamente:</para> + + <screen><prompt>%</prompt> <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen> + </sect2> + </sect1> +</chapter> + + +<!-- 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 version="5.0" xml:id="see-also"> + <title>Veja também</title> + + <para>Este documento não é deliberadamente uma discussão exaustiva de XML, das DTDs listadas e o Projeto de Documentação do FreeBSD. Para mais informações sobre estes, você é encorajado a consultar os seguintes sites.</para> + + <sect1 xml:id="see-also-fdp"> + <title>O projeto de documentação do FreeBSD</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="@@URL_RELPREFIX@@/docproj/index.html">As Páginas Web do Projeto de Documentação do FreeBSD</link></para> + </listitem> + + <listitem> + <para><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/index.html">O Handbook do FreeBSD</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-xml"> + <title>XML</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.w3.org/XML/">Página W3C's XML Página Web SGML/XML</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-html"> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.w3.org/">O Consórcio World Wide Web</link></para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.w3.org/TR/REC-html40/">A especificação HTML 4.0</link></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="see-also-docbook"> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.oasis-open.org/docbook/">O Comitê Técnico do DocBook </link>, mantenedores do DocBook DTD</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.docbook.org/">DocBook: O Guia Definitivo </link>, a documentação online do DocBook DTD</para> + </listitem> + + <listitem> + <para><link xlink:href="http://docbook.sourceforge.net/">O DocBook Open Repository</link> contém folhas de estilo DSSSL e outros recursos para pessoas que usam DocBook</para> + </listitem> + </itemizedlist> + </sect1> + +</chapter> + + + +<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +--> +<appendix version="5.0" xml:id="examples"> + + <title>Exemplos</title> + + <para>Estes exemplos não são exaustivos - eles não contêm todos os elementos que podem ser desejáveis de usar, particularmente em relação ao inicio dos documentos (Front Matter). Para mais exemplos de marcação DocBook, examine o código <acronym>XML</acronym> para este e outros documentos disponíveis no repositório <application>Subversion</application> <literal>doc</literal> ou disponível on-line a partir de <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para> + + <sect1 xml:id="examples-docbook-book"> + <title><tag>Livro</tag> DocBook</title> + + <example> + <title><tag>Livro</tag> DocBook</title> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> + +<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> + + <tag class="starttag">info</tag> + <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag> + + <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> + + <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> + + <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> + + <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> + + <tag class="starttag">preface</tag> + <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> + + <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> + + <sect1 xml:id="examples-docbook-article"> + <title><tag>Artigo</tag> DocBook</title> + + <example> + <title><tag>Artigo</tag> DocBook</title> + + <programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> + +<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> + + <tag class="starttag">info</tag> + <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag> + + <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> + + <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> + + <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> + + <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> + + <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 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> +</appendix> + <index/> </book> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent b/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent index 3dc72223c0..52c0770b3c 100755 --- a/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent +++ b/pt_BR.ISO8859-1/books/fdp-primer/chapters.ent @@ -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"> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.xml index fb98a008f5..e55650a560 100644 --- a/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.xml +++ b/pt_BR.ISO8859-1/books/fdp-primer/doc-build/chapter.xml @@ -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$ +--> +<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>This chapter covers organization of the documentation build + process and how &man.make.1; is used to control it.</para> + + <sect1 xml:id="doc-build-rendering"> + <title>Rendering DocBook into Output</title> + + <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> + + <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> + + <table xml:id="doc-build-rendering-common-formats" frame="none"> + <title>Common Output Formats</title> + + <tgroup cols="3"> + <thead> + <row> + <entry><varname>FORMATS</varname> Value</entry> + <entry>File Type</entry> + <entry>Description</entry> + </row> + </thead> + + <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> + + <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> + + <row> + <entry><literal>pdf</literal></entry> + <entry><acronym>PDF</acronym></entry> + <entry>Portable Document Format</entry> + </row> + </tbody> + </tgroup> + </table> + + <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> + + <example xml:id="doc-build-formats-example-html"> + <title>Build a Single HTML Output File</title> + + <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> - Original revision: r38845 + <sect1 xml:id="doc-build-toolset"> + <title>The &os; Documentation Build Toolset</title> ---> -<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 construo da - documentao</title> - - <para>A principal finalidade desse captulo explicar - claramente <emphasis>como o processo de criao da - documentao organizado</emphasis>, e - <emphasis>como fazer modificaes a este - processo</emphasis>.</para> - - <para>Depois de finalizar a leitura deste captulo - voc dever:</para> - - <itemizedlist> - <listitem> - <para>Saber o que voc precisa para compilar a - documentao mantida pelo FDP, em - adio ao que foi mencionado no - <link linkend="tools">captulo Ferramentas SGML</link>. - </para> - </listitem> - - <listitem> - <para>Ser capaz de ler e entender as instrues do - <application>make</application> que esto presentes - em cada documento <filename>Makefile</filename>, assim como - ter uma viso geral do - <filename>doc.project.mk</filename>.</para> - </listitem> - - <listitem> - <para>Ser capaz de customizar o processo de - compilao usando variveis e alvos do - <application>make</application>.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>Ferramentas para construo da - documentao do FreeBSD</title> - - <para>Aqui esto suas ferramentas. Use-as de todas as - formas que puder.</para> + <para>These are the tools used to build and install the + <acronym>FDP</acronym> documentation.</para> <itemizedlist> <listitem> - <para>A primeira ferramenta que voc precisar - o <application>make</application>, mais - especificamente o <application>Berkeley Make</application>. - </para> + <para>The primary build tool is &man.make.1;, specifically + <application>Berkeley Make</application>.</para> </listitem> <listitem> - <para>A construo de pacotes no FreeBSD - executada pelo - <application>pkg_create</application>. Se voc - no est utilizando o FreeBSD, voc - ter que viver sem o uso de pacotes, ou ento - ter que compilar o cdigo fonte voc - mesmo.</para> + <para>Package building is handled by &os;'s + &man.pkg-create.8;.</para> </listitem> <listitem> - <para>O <application>gzip</application> - necessrio para criar verses compactadas do - documento. O compressor <application>bzip2</application> e - os arquivos <application>zip</application> tambm - so suportados. O <application>tar</application> - suportado, e a construo de - pacotes necessita dele.</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>O <application>install</application> o - mtodo padro para instalar a - documentao. Entretanto, existem - alternativas.</para> + <para>&man.install.1; is used to install the + documentation.</para> </listitem> </itemizedlist> - - <note> - <para> improvvel que voc tenha qualquer - problema em localizar esses dois ltimos, eles esto - sendo mencionados apenas para que a listagem fique completa. - </para> - </note> </sect1> - <sect1> - <title>Entendendo <filename>Makefile</filename>s na rvore da - documentao</title> + <sect1 xml:id="doc-build-makefiles"> - <para>H trs tipos principais de - <filename>Makefile</filename>s na rvore do projeto de - documento do FreeBSD.</para> + <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>Os <link linkend="sub-make"> - <filename>Makefile</filename>s de subdiretrio</link> - simplesmente passam comandos para os diretrios - abaixo dele.</para> + <para><link linkend="sub-make">Subdirectory + <filename>Makefile</filename>s</link> simply pass + commands to those directories below them.</para> </listitem> <listitem> - <para>Os <link linkend="doc-make"> - <filename>Makefile</filename>s de - documentao</link> descrevem o(s) - documento(s) que deve(m) ser produzido(s) a partir deste - diretrio.</para> + <para><link linkend="doc-make">Documentation + <filename>Makefile</filename>s</link> describe the + documents that are produced from this + directory.</para> </listitem> <listitem> - <para>Os <link linkend="make-includes"> - <application>Make</application> includes</link> so - os responsveis pela produo do - documento, e geralmente possuem o nome no formato - <filename>doc.xxx.mk</filename>. - </para> + <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 Subdiretrios</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 no vazias definem as variveis 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 declarao da varivel - <varname>SUBDIR</varname>, tanto quanto a - declarao da varivel - <varname>COMPAT_SYMLINK</varname>, - mostra como atribuir um valor a uma varivel, - sobrescrevendo qualquer valor anterior que a mesma - contenha.</para> - - <para>A segunda declarao da varivel - <varname>SUBDIR</varname> mostra como um valor - adicionado ao valor atual de uma varivel. A - varivel <varname>SUBDIR</varname> agora - composta por <literal>articles books</literal>.</para> - - <para>A declarao do - <varname>DOC_PREFIX</varname> mostra como um valor - atribudo para uma varivel, mas somente se - ela ainda no estiver definida. Isto - til se o <varname>DOC_PREFIX</varname> no - for onde este <filename>Makefile</filename> pensa que - - o usurio pode cancelar e fornecer - o valor correto.</para> - - <para>Agora o que tudo isso significa? O - <varname>SUBDIR</varname> lista quais subdiretrios - abaixo do atual devem ser includos no processo de - compilao durante a gerao - do documento.</para> - - <para>O <varname>COMPAT_SYMLINK</varname> - especfico para compatibilizar os links - simblicos que ligam os idiomas a sua - codificao oficial (por exemplo o - <filename>doc/en</filename> deve apontar para - <filename>en_US.ISO-8859-1</filename>).</para> - - <para>O <varname>DOC_PREFIX</varname> o caminho para a - raz da rvore do projeto de - documentao do FreeBSD. O qual nem sempre - facil de encontrar, e que tambm pode ser - facilmente sobrescrito, para permitir flexibilidade. O - <varname>.CURDIR</varname> uma varivel - interna do <application>make</application> que contm - o caminho para o diretrio atual.</para> - - <para>A linha final inclui o arquivo principal do projeto de - documentao do FreeBSD, o - <filename>doc.project.mk</filename>, ele o - responsvel por converter estas variveis em - instrues de compilao para - uso do <application>make</application>.</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>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>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>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><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><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 Documentao</title> + <title>Documentation <filename>Makefile</filename>s</title> - <para>Estes <filename>Makefile</filename>s ajustam vrias - variveis do <application>make</application> as quais - descrevem como construir a documentao - contida em um determinado diretrio.</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 varivel <varname>MAINTAINER</varname> - uma muito importante. Esta varivel fornece a - habilidade de reivindicar a propriedade sobre um documento no - projeto de documentao do FreeBSD, - por meio dela que voc recebe a responsabilidade de - mant-lo.</para> - - <para><varname>DOC</varname> o nome (sem a - extenso <filename>.xml</filename>) do principal - documento criado por este diretrio. A varivel - <varname>SRCS</varname> lista todos os arquivos individuais - que compem o documento. Ela tambm deve - incluir os arquivos importantes, nos quais qualquer - mudana deve resultar em uma - reconstruo.</para> - - <para>O <varname>FORMATS</varname> indica os formatos - nos quais o documento deve ser gerado por padro. - O <varname>INSTALL_COMPRESSED</varname> contm a lista - padro das tcnicas de compresso que - devem ser usadas no documento depois que ele gerado. - A varivel <varname>INSTALL_ONLY_COMPRESS</varname>, - nula por padro, deve ser definida para um valor - no nulo apenas se voc desejar gerar - exclusivamente a verso compactada do documento.</para> - - <note> - <para>Ns abordamos a atribuio das - variveis opcionais na <link linkend="sub-make">seo anterior</link>. - </para> - </note> - - <para>Voc tambm j deve estar - familiarizado com a atribuio da - varivel <varname>DOC_PREFIX</varname> e com as - instrues de include.</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> 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><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> + + <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 documentao - do FreeBSD</title> + <title>&os; Documentation Project + <application>Make</application> Includes</title> - <para>Isto melhor explicado pela inspeo - no cdigo. Aqui esto 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 necessrios.</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 - navegao na rvore de - documentao durante - o processo de construo e - instalao.</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 - variveis que afetam a propriedade e a - instalao 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> - includo se o <varname>DOCFORMAT</varname> - for <literal>docbook</literal> e se a varivel - <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 inspeo:</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>Variveis</title> + <title>Variables</title> - <para>As variveis <varname>DOCFORMAT</varname> e - <varname>MAINTAINER</varname> sero atribudas - com valores padro, se o valor das mesmas no - 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 - construo da documentao</link> - esto instalados. Para uma instalao - normal atravs 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 varivel <varname>PRI_LANG</varname> deve ser - configurada para refletir o idioma e a - codificao nativa dos usurios aos - quais os documentos se destinam. O Ingls Americano - (US English) o padro.</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 varivel <varname>PRI_LANG</varname> de - maneira alguma afeta quais documentos sero, - ou que podero, ser compilados. Sua - funo principal criar links para - os documentos referenciados com maior frequncia no - diretrio raiz de instalao da - documentao 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> - - <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 condio verdadeira ou se - falsa. <literal>defined</literal> uma - funo que retorna se uma dada - varivel est definida ou no.</para> - - <para>A seguir, <literal>.if ${DOCFORMAT} == "docbook" - </literal>, testa se a varivel <varname>DOCFORMAT - </varname> <literal>"docbook"</literal>, e neste - caso, inclue o <filename>doc.docbook.mk</filename>.</para> - - <para>Os dois <literal>.endif</literal>s fecham as duas - condicionais anteriores, marcando o fim da sua - aplicao.</para> + <sect3 xml:id="doc-project-mk-conditionals"> + <title>Conditionals</title> + + <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><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>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 - inspeo, voc deve ser capaz de - interpret-lo com o conhecimento adquirido nos - captulos 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>Variveis</title> + <sect3 xml:id="doc-subdir-mk-variables"> + <title>Variables</title> <itemizedlist> <listitem> - <para><varname>SUBDIR</varname> a lista de - subdiretrios nos quais o processo de - construo 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> so os nomes - dos diretrios que devem ser linkados para a - raz de instalao do documento - a partir da sua localizao atual, se o - idioma atual for o idioma primrio (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 seo <link linkend="sub-make">Makefiles de subdiretrio - </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> - - <para>As dependncias so descritas por - <literal>target: - dependncia1 dependncia2 ... - </literal>, nas quais, para construir o - <literal>target</literal>, voc necessita - primeiramente construir as dependncias - informadas.</para> - - <para>Depois desta descrio, - instrues de como construir o target podem - ser passadas, no caso do processo de converso - entre o target e estas dependncias no - tiver sido previamente definido, ou se esta - converso em particular no for a mesma - que a definida pelo mtodo padro de - converso.</para> - - <para>A dependncia especial <literal>.USE</literal> - define o equivalente a uma macro.</para> - -<programlisting>_SUBDIRUSE: .USE + <sect3 xml:id="doc-subdir-mk-targets-macro"> + <title>Targets and Macros</title> + + <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>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 special dependency <literal>.USE</literal> defines + the equivalent of a macro.</para> + + <programlisting>_SUBDIRUSE: .USE .for entry in ${SUBDIR} @${ECHO} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor</programlisting> - <para>No cdigo acima, <buildtarget>_SUBDIRUSE - </buildtarget> agora uma macro, a qual ir - executar determinados comandos quando for listada como - dependncia.</para> - - <para>O que define esta macro a parte de outros targets? - Basicamente, ela executada <emphasis>aps - </emphasis> as instrues passadas no - processo de construo por ser uma - dependncia para o mesmo, e ela no - configura o <varname>.TARGET</varname>, que a - varivel que contm o nome do target atual - que est sendo construdo.</para> - -<programlisting>clean: _SUBDIRUSE + <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>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 rm -f ${CLEANFILES}</programlisting> - <para>No cdigo acima, o <buildtarget>clean</buildtarget> - ir usar a macro <buildtarget>_SUBDIRUSE</buildtarget> - depois de ter executado a instruo - <command>rm -f ${CLEANFILES}</command>. De fato, isto causa - uma limpeza (<buildtarget>clean</buildtarget>) na - rvore de diretrios, deletando os arquivos - construdos enquanto vai - <emphasis>descendo</emphasis> pelos subdiretrios, - e no quando vai na direo - 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 diretrios executando a sua - verso real dentro dos subdiretrios. - (<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 - compilao (e tambm desce na - rvore de diretrios). - O <buildtarget>cleandir</buildtarget> faz a mesma - coisa, e tambm remove o diretrio - 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 - funo 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 - varivel 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 no existir.</para> + <para><literal>target</literal> returns true if the given + target does not already exist.</para> </listitem> </itemizedlist> </sect3> - <sect3> - <title>Construo 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 instrues definidas para cada - elemento separado por espao em uma varivel. - Ele faz isso atribundo uma varivel 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} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor</programlisting> - <para>No cdigo acima, se <varname>SUBDIR</varname> - estiver vazia, nenhuma ao ser - executada; se ela possuir um ou mais elementos, as - instrues entre o <literal>.for</literal> e - o <literal>.endfor</literal> sero repetidas para - cada elemento, com o <varname>entry</varname> - sendo substitudo 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> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml new file mode 100644 index 0000000000..7c2ece8dba --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -0,0 +1,2761 @@ +<?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="docbook-markup"> + + <title>DocBook Markup</title> + + <sect1 xml:id="docbook-markup-introduction"> + <title>Introduction</title> + + <para>This chapter is an introduction to DocBook as it is used for + &os; documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for &os; documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the &a.doc;.</para> + + <para>DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a Document Type Definition + (<acronym>DTD</acronym>) for writing technical documentation + <footnote><para>A short history can be found under <link + xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. + Since 1998 it is maintained by the <link + xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</link>. As such, and unlike + LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily + oriented towards markup that describes <emphasis>what</emphasis> + something is, rather than describing <emphasis>how</emphasis> it + should be presented.</para> + + <para>The DocBook <acronym>DTD</acronym> is available from the + Ports Collection in the + <package>textproc/docbook-xml</package> + port. It is automatically installed as part of the + <package>textproc/docproj</package> + port.</para> + + <note> + <title>Formal Versus Informal</title> + + <para>Some elements may exist in two forms, + <emphasis>formal</emphasis> and <emphasis>informal</emphasis>. + Typically, the formal version of the element will consist of a + title followed by the informal version of the element. The + informal version will not have a title.</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="docbook-markup-freebsd-extensions"> + <title>&os; Extensions</title> + + <para>The &os; Documentation Project has extended the DocBook + <acronym>DTD</acronym> with additional elements and entities. + These additions serve to make some of the markup easier or more + precise.</para> + + <para>Throughout the rest of this document, the term + <quote>DocBook</quote> is used to mean the &os;-extended + DocBook <acronym>DTD</acronym>.</para> + + <note> + <para>Most of these extensions are not unique to &os;, it was + just felt that they were useful enhancements for this + particular project. Should anyone from any of the other *nix + camps (NetBSD, OpenBSD, Linux, …) be interested in + collaborating on a standard DocBook extension set, please + contact &a.doceng;.</para> + </note> + + <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> + <title>&os; Elements</title> + + <para>The additional &os; elements are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as <link + xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> + + <para>&os;-specific elements used in the examples below are + clearly marked.</para> + </sect2> + + <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> + <title>&os; Entities</title> + + <para>This table shows some of the most useful entities + available in the <acronym>FDP</acronym>. For a complete list, + see the <filename>*.ent</filename> files in + <filename>doc/share/xml</filename>.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <colspec colname="entity"/> + <colspec colname="expandsto"/> + <colspec colname="notes"/> + <thead> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry namest="entity" nameend="notes"><emphasis>&os; + Name Entities</emphasis></entry> + </row> + + <row> + <entry><literal>&os;</literal></entry> + <entry><literal>&os;</literal></entry> + <entry/> + </row> + + <row> + <entry><literal>&os.stable;</literal></entry> + <entry><literal>&os.stable;</literal></entry> + <entry/> + </row> + + <row> + <entry><literal>&os.current;</literal></entry> + <entry><literal>&os.current;</literal></entry> + <entry/> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Manual Page + Entities</entry> + </row> + + <row> + <entry><literal>&man.ls.1;</literal></entry> + <entry>&man.ls.1;</entry> + <entry>Usage: <literal>&man.ls.1; is the manual page + for + <command>ls</command>.</literal></entry> + </row> + + <row> + <entry><literal>&man.cp.1;</literal></entry> + <entry>&man.cp.1;</entry> + <entry>Usage: <literal>The manual page for + <command>cp</command> is + &man.cp.1;.</literal></entry> + </row> + + <row> + <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> + <entry><emphasis>link to + <replaceable>command</replaceable> manual page in + section + <replaceable>sectionnumber</replaceable></emphasis></entry> + <entry>Entities are defined for all the + <link xlink:href="&url.base;/cgi/man.cgi">&os; manual + pages</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">&os; Mailing List + Entities</entry> + </row> + + <row> + <entry><literal>&a.doc;</literal></entry> + <entry><literal>&a.doc;</literal></entry> + <entry>Usage: <literal>A link to the + &a.doc;.</literal></entry> + </row> + + <row> + <entry><literal>&a.questions;</literal></entry> + <entry><literal>&a.questions;</literal></entry> + <entry>Usage: <literal>A link to the + &a.questions;.</literal></entry> + </row> + + <row> + <entry><literal>&a.<replaceable>listname</replaceable>;</literal></entry> + <entry><emphasis>link to + <replaceable>listname</replaceable></emphasis></entry> + <entry>Entities are defined for all the <link + xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os; + mailing lists</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">&os; Document + Link Entities</entry> + </row> + + <row> + <entry><literal>&url.books.handbook;</literal></entry> + <entry><literal>&url.books.handbook;</literal></entry> + <entry>Usage: <literal>A link to the <link + xlink:href="&url.books.handbook;/advanced-networking.html">Advanced + Networking</link> chapter of the + Handbook.</literal></entry> + </row> + + <row> + <entry><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> + <entry><emphasis>relative path to + <replaceable>bookname</replaceable></emphasis></entry> + <entry>Entities are defined for all the <link + xlink:href="&url.doc.langbase;/books/">&os; + books</link>.</entry> + </row> + + <row> + <entry><literal>&url.articles.committers-guide;</literal></entry> + <entry><literal>&url.articles.committers-guide;</literal></entry> + <entry>Usage: <literal>A link to the <link + xlink:href="&url.articles.committers-guide;">Committer's + Guide</link> + article.</literal></entry> + </row> + + <row> + <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> + <entry><emphasis>relative path to + <replaceable>articlename</replaceable></emphasis></entry> + <entry>Entities are defined for all the <link + xlink:href="&url.doc.langbase;/articles/">&os; + articles</link>.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Other Operating + System Name Entities</entry> + </row> + + <row> + <entry><literal>&linux;</literal></entry> + <entry>&linux;</entry> + <entry>The &linux; operating system.</entry> + </row> + + <row> + <entry><literal>&unix;</literal></entry> + <entry>&unix;</entry> + <entry>The &unix; operating system.</entry> + </row> + + <row> + <entry><literal>&windows;</literal></entry> + <entry>&windows;</entry> + <entry>The &windows; operating system.</entry> + </row> + + <row> + <entry/> + <entry/> + <entry/> + </row> + + <row> + <entry namest="entity" nameend="notes">Miscellaneous + Entities</entry> + </row> + + <row> + <entry><literal>&prompt.root;</literal></entry> + <entry>&prompt.root;</entry> + <entry>The <systemitem + class="username">root</systemitem> user + prompt.</entry> + </row> + + <row> + <entry><literal>&prompt.user;</literal></entry> + <entry>&prompt.user;</entry> + <entry>A prompt for an unprivileged user.</entry> + </row> + + <row> + <entry><literal>&postscript;</literal></entry> + <entry>&postscript;</entry> + <entry>The + &postscript; programming language.</entry> + </row> + + <row> + <entry><literal>&tex;</literal></entry> + <entry>&tex;</entry> + <entry>The + &tex; typesetting language.</entry> + </row> + + <row> + <entry><literal>&xorg;</literal></entry> + <entry>&xorg;</entry> + <entry>The &xorg; open source X + Window System.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-fpi"> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing + <acronym>FPI</acronym>s for DocBook customizations, the + <acronym>FPI</acronym> for the &os; extended DocBook + <acronym>DTD</acronym> is:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect1> + + <sect1 xml:id="docbook-markup-document-structure"> + <title>Document Structure</title> + + <para>DocBook allows structuring documentation in several ways. + The &os; Documentation Project uses two primary types of DocBook + document: the book and the article.</para> + + <para>Books are organized into <tag>chapter</tag>s. + This is a mandatory requirement. There may be + <tag>part</tag>s between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. + These are indicated with the <tag>sect1</tag> element. + If a section contains another section then use the + <tag>sect2</tag> element, and so on, up to + <tag>sect5</tag>.</para> + + <para>Chapters and sections contain the remainder of the + content.</para> + + <para>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.</para> + + <para>The nature of the document being written should be used to + determine whether it is best marked up as a book or an article. + Articles are well suited to information that does not need to be + broken down into several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books + are best suited to information that can be broken up into + several chapters, possibly with appendices and similar content + as well.</para> + + <para>The <link xlink:href="&url.base;/docs.html">&os; + tutorials</link> are all marked up as articles, while this + document, the <link + xlink:href="&url.books.faq;/index.html">FAQ</link>, and the + <link + xlink:href="&url.books.handbook;/index.html">Handbook</link> + are all marked up as books, for example.</para> + + <sect2 xml:id="docbook-markup-starting-a-book"> + <title>Starting a Book</title> + + <para>The content of a book is contained within the + <tag>book</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the book. This is either + meta-information, used for reference purposes, or additional + content used to produce a title page.</para> + + <para>This additional information is contained within + <tag>info</tag>.</para> + + <example> + <title>Boilerplate <tag>book</tag> with + <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting><tag class="starttag">book</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">book</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-starting-an-article"> + <title>Starting an Article</title> + + <para>The content of the article is contained within the + <tag>article</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page.</para> + + <para>This additional information is contained within + <tag>info</tag>.</para> + + <example> + <title>Boilerplate <tag>article</tag> with + <tag>info</tag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting><tag class="starttag">article</tag> + <tag class="starttag">info</tag> + <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> + + <tag class="starttag">author</tag> + <tag class="starttag">personname</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="endtag">personname</tag> + + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> + + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> + + <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> + + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">info</tag> + + … + +<tag class="endtag">article</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-indicating-chapters"> + <title>Indicating Chapters</title> + + <para>Use <tag>chapter</tag> to mark up your chapters. + Each chapter has a mandatory <tag>title</tag>. + Articles do not contain chapters, they are reserved for + books.</para> + + <example> + <title>A Simple Chapter</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> + + ... +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para>A chapter cannot be empty; it must contain elements in + addition to <tag>title</tag>. If you need to + include an empty chapter then just use an empty + paragraph.</para> + + <example> + <title>Empty Chapters</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag><tag class="endtag">para</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-sections-below-chapters"> + <title>Sections Below Chapters</title> + + <para>In books, chapters may (but do not need to) be broken up + into sections, subsections, and so on. In articles, sections + are the main structural element, and each article must contain + at least one section. Use the + <tag>sect<replaceable>n</replaceable></tag> element. + The <replaceable>n</replaceable> indicates the section number, + which identifies the section level.</para> + + <para>The first + <tag>sect<replaceable>n</replaceable></tag> is + <tag>sect1</tag>. You can have one or more of these + in a chapter. They can contain one or more + <tag>sect2</tag> elements, and so on, down to + <tag>sect5</tag>.</para> + + <example> + <title>Sections in Chapters</title> + + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect1</tag> + + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> + + <tag class="starttag">sect3</tag> + <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> + + … + <tag class="endtag">sect3</tag> + <tag class="endtag">sect2</tag> + + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> + + … + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <note> + <para>Section numbers are automatically generated and + prepended to titles when the document is rendered to an + output format. The generated section numbers and titles + from the example above will be:</para> + + <itemizedlist> + <listitem> + <para>1.1. First Section</para> + </listitem> + + <listitem> + <para>1.2. Second Section</para> + </listitem> + + <listitem> + <para>1.2.1. First Sub-Section</para> + </listitem> + + <listitem> + <para>1.2.1.1. First Sub-Sub-Section</para> + </listitem> + + <listitem> + <para>1.2.2. Second Sub-Section</para> + </listitem> + </itemizedlist> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-subdividing-part"> + <title>Subdividing Using <tag>part</tag> + Elements</title> + + <para><tag>part</tag>s introduce another level of + organization between <tag>book</tag> and + <tag>chapter</tag> with one or more + <tag>part</tag>s. This cannot be done in an + <tag>article</tag>.</para> + + <programlisting><tag class="starttag">part</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> + + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>History<tag class="endtag">title</tag> + + ... + <tag class="endtag">chapter</tag> +<tag class="endtag">part</tag></programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-block-elements"> + <title>Block Elements</title> + + <sect2 xml:id="docbook-markup-paragraphs"> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs: + <tag>formalpara</tag>, <tag>para</tag>, and + <tag>simpara</tag>.</para> + + <para>Almost all paragraphs in &os; documentation use + <tag>para</tag>. <tag>formalpara</tag> + includes a <tag>title</tag> element, and + <tag>simpara</tag> disallows some elements from + within <tag>para</tag>. Stick with + <tag>para</tag>.</para> + + <example> + <title><tag>para</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any + other element.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-block-quotations"> + <title>Block Quotations</title> + + <para>A block quotation is an extended quotation from another + document that should not appear within the current paragraph. + These are rarely needed.</para> + + <para>Blockquotes can optionally contain a title and an + attribution (or they can be left untitled and + unattributed).</para> + + <example> + <title><tag>blockquote</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> + +<tag class="starttag">blockquote</tag> + <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> + + <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> + + <tag class="starttag">para</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">para</tag> +<tag class="endtag">blockquote</tag></programlisting> + + <para>Appearance:</para> + + <para>A small excerpt from the US Constitution:</para> + + <blockquote> + <title>Preamble to the Constitution of the United + States</title> + + <attribution>Copied from a web site + somewhere</attribution> + + <para>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.</para> + </blockquote> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tips-notes"> + <title>Tips, Notes, Warnings, Cautions, and Important + Information</title> + + <para>Extra information may need to be separated from + the main body of the text. Typically this is + <quote>meta</quote> information of which the user should be + aware.</para> + + <para>Several types of admonitions are available: + <tag>tip</tag>, <tag>note</tag>, + <tag>warning</tag>, <tag>caution</tag>, and + <tag>important</tag>.</para> + + <para>Which admonition to choose depends on the situation. + The DocBook + documentation suggests:</para> + + <itemizedlist> + <listitem> + <para>Note is for information that should be heeded by + all readers.</para> + </listitem> + + <listitem> + <para>Important is a variation on Note.</para> + </listitem> + + <listitem> + <para>Caution is for information regarding possible data + loss or software damage.</para> + </listitem> + + <listitem> + <para>Warning is for information regarding possible + hardware damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><tag>tip</tag> and <tag>important</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">tip</tag> + <tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag> +<tag class="endtag">tip</tag> + +<tag class="starttag">important</tag> + <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.<tag class="endtag">para</tag> +<tag class="endtag">important</tag></programlisting> + </example> + + <para>Appearance:</para> + <!-- Need to do this outside of the example --> + <tip> + <para>&os; may reduce stress.</para> + </tip> + + <important> + <para>Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-example"> + <title>Examples</title> + + <para>Examples can be shown with <tag>example</tag>.</para> + + <example> + <title><tag>example</tag> Source</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">example</tag> + <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag> + + <tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag> +<tag class="endtag">example</tag></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <para>Appearance:</para> + + <example> + <title>Rendered <tag>example</tag></title> + + <para>Empty files can be created easily:</para> + + <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-lists-and-procedures"> + <title>Lists and Procedures</title> + + <para>Information often needs to be presented as lists, or as a + number of steps that must be carried out in order to + accomplish a particular goal.</para> + + <para>To do this, use <tag>itemizedlist</tag>, + <tag>orderedlist</tag>, <tag>variablelist</tag>, or + <tag>procedure</tag>. There are other types of list + elements in DocBook, but we will not cover them here.</para> + + <para><tag>itemizedlist</tag> and + <tag>orderedlist</tag> are similar to their + counterparts in <acronym>HTML</acronym>, <tag>ul</tag> + and <tag>ol</tag>. Each one consists of one or more + <tag>listitem</tag> elements, and each + <tag>listitem</tag> contains one or more block + elements. The <tag>listitem</tag> elements are + analogous to <acronym>HTML</acronym>'s <tag>li</tag> + tags. However, unlike HTML, they are required.</para> + + <example> + <title><tag>itemizedlist</tag> and + <tag>orderedlist</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">itemizedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">itemizedlist</tag> + +<tag class="starttag">orderedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">orderedlist</tag></programlisting> + + <para>Appearance:</para> + + <itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> + </orderedlist> + </example> + + <para xml:id="docbook-markup-varlist">An alternate and often + useful way of presenting information is the + <tag>variablelist</tag>. These are lists where each entry has + a term and a description. They are well suited for many types + of descriptions, and present information in a form that is + often easier for the reader than sections and + subsections.</para> + + <para>A <tag>variablelist</tag> has a <tag>title</tag>, and then + pairs of <tag>term</tag> and <tag>listitem</tag> + entries.</para> + + <example xml:id="docbook-markup-variablelist-example"> + <title><tag>variablelist</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">variablelist</tag> + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In parallel communications, groups of bits arrive + at the same time over multiple communications + channels.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> + + <tag class="starttag">varlistentry</tag> + <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag> + + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>In serial communications, bits arrive one at a + time over a single communications + channel.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> + <tag class="endtag">varlistentry</tag> +<tag class="endtag">variablelist</tag></programlisting> + + <para>Appearance:</para> + + <variablelist> + <varlistentry> + <term>Parallel</term> + + <listitem> + <para>In parallel communications, groups of bits arrive + at the same time over multiple communications + channels.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Serial</term> + + <listitem> + <para>In serial communications, bits arrive one at a + time over a single communications channel.</para> + </listitem> + </varlistentry> + </variablelist> + </example> + + <para>A <tag>procedure</tag> shows a series of <tag>step</tag>s, + which may in turn consist of more <tag>step</tag>s or + <tag>substep</tag>s. Each <tag>step</tag> contains block + elements and may include an optional title.</para> + + <para>Sometimes, steps are not sequential, but present a choice: + do <emphasis>this</emphasis> or do <emphasis>that</emphasis>, + but not both. For these alternative choices, use + <tag>stepalternatives</tag>.</para> + + <example> + <title><tag>procedure</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">procedure</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">substeps</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this smaller thing.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this other smaller thing.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + <tag class="endtag">substeps</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Finally, do one of these:<tag class="endtag">para</tag> + + <tag class="starttag">stepalternatives</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> + <tag class="endtag">stepalternatives</tag> + <tag class="endtag">step</tag> +<tag class="endtag">procedure</tag></programlisting> + + <para>Appearance:</para> + + <procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <substeps> + <step> + <para>And now do this small thing.</para> + </step> + + <step> + <para>And this other small thing.</para> + </step> + </substeps> + </step> + + <step> + <para>Finally, do one of these:</para> + + <stepalternatives> + <step> + <para>Go left.</para> + </step> + + <step> + <para>Go right.</para> + </step> + </stepalternatives> + </step> + </procedure> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-showing-file-samples"> + <title>Showing File Samples</title> + + <para>Fragments of a file (or perhaps a complete file) are shown + by wrapping them in the <tag>programlisting</tag> + element.</para> + + <para>White space and line breaks within + <tag>programlisting</tag> <emphasis>are</emphasis> + significant. In particular, this means that the opening tag + should appear on the same line as the first line of the + output, and the closing tag should appear on the same line + as the last line of the output, otherwise spurious blank + lines may be included.</para> + + <example> + <title><tag>programlisting</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; + +int +main(void) +{ + printf("hello, world\n"); + return 0; +}<tag class="endtag">programlisting</tag></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by + their entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); + return 0; +}</programlisting> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-callouts"> + <title>Callouts</title> + + <para>A callout is a visual marker for referring to a + piece of text or specific position within an + example.</para> + + <para>Callouts are marked with the <tag>co</tag> + element. Each element must have a unique + <literal>id</literal> assigned to it. After the example, + include a <tag>calloutlist</tag> that describes each + callout.</para> + + <example> + <title><tag>co</tag> and + <tag>calloutlist</tag> Example</title> + + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> + +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag> + +int <tag class="emptytag">co xml:id="co-ex-return"</tag> +main(void) +{ + printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag> +}<tag class="endtag">programlisting</tag> + +<tag class="starttag">calloutlist</tag> + <tag class="starttag">callout arearefs="co-ex-include"</tag> + <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-return"</tag> + <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an + int.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> + + <tag class="starttag">callout arearefs="co-ex-printf"</tag> + <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes + <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> +<tag class="endtag">calloutlist</tag></programlisting> + + <para>Appearance:</para> + + <para>When finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> + +int <co xml:id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co xml:id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para>Includes the standard IO header file.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Specifies that <function>main()</function> returns + an int.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>The <function>printf()</function> call that writes + <literal>hello, world</literal> to standard + output.</para> + </callout> + </calloutlist> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-tables"> + <title>Tables</title> + + <para>Unlike <acronym>HTML</acronym>, DocBook does not need + tables for layout purposes, as the stylesheet handles those + issues. Instead, just use tables for marking up tabular + data.</para> + + <para>In general terms (and see the DocBook documentation for + more detail) a table (which can be either formal or informal) + consists of a <tag>table</tag> element. This contains + at least one <tag>tgroup</tag> element, which + specifies (as an attribute) the number of columns in this + table group. Within the tablegroup there is one + <tag>thead</tag> element, which contains elements for + the table headings (column headings), and one + <tag>tbody</tag> which contains the body of the + table.</para> + + <para>Both <tag>tgroup</tag> and + <tag>thead</tag> contain <tag>row</tag> + elements, which in turn contain <tag>entry</tag> + elements. Each <tag>entry</tag> element specifies + one cell in the table.</para> + + <example> + <title><tag>informaltable</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">informaltable pgwide="1"</tag> + <tag class="starttag">tgroup cols="2"</tag> + <tag class="starttag">thead</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">thead</tag> + + <tag class="starttag">tbody</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">tbody</tag> + <tag class="endtag">tgroup</tag> +<tag class="endtag">informaltable</tag></programlisting> + + <para>Appearance:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>Always use the <literal>pgwide</literal> attribute with + a value of <literal>1</literal> with the + <tag>informaltable</tag> element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted.</para> + + <para>Table borders can be suppressed by setting the + <literal>frame</literal> attribute to <literal>none</literal> + in the <tag>informaltable</tag> element. For example, + <literal>informaltable frame="none"</literal>.</para> + + <example> + <title>Table with <literal>frame="none"</literal> + Example</title> + + <para>Appearance:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-examples"> + <title>Examples for the User to Follow</title> + + <para>Examples for the user to follow are often necessary. + Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, + the user types another command, and so on.</para> + + <para>A number of distinct elements and entities come into + play here.</para> + + <variablelist> + <varlistentry> + <term><tag>screen</tag></term> + + <listitem> + <para>Everything the user sees in this example will be + on the computer screen, so the next element is + <tag>screen</tag>.</para> + + <para>Within <tag>screen</tag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>prompt</tag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the + screen are prompts from the computer (either from the + operating system, command shell, or application). These + should be marked up using + <tag>prompt</tag>.</para> + + <para>As a special case, the two shell prompts for the + normal user and the root user have been provided as + entities. To indicate the user is at a shell prompt, + use one of <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. They + do not need to be inside + <tag>prompt</tag>.</para> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are &os; + extensions to DocBook, and are not part of the + original <acronym>DTD</acronym>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>userinput</tag></term> + + <listitem> + <para>When displaying text that the user should type in, + wrap it in <tag>userinput</tag> tags. It will + be displayed differently than system output text.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><tag>screen</tag>, <tag>prompt</tag>, + and <tag>userinput</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> +foo1 +foo2 +foo3 +&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> +foo2 +&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> +<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> +&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> +This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting> + + <para>Appearance:</para> + + <screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> + marked up as <tag>programlisting</tag>. Reserve + <tag>programlisting</tag> for showing fragments of + files outside the context of user actions.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-inline-elements"> + <title>In-line Elements</title> + + <sect2 xml:id="docbook-markup-inline-emphasizing"> + <title>Emphasizing Information</title> + + <para>To emphasize a particular word or phrase, use + <tag>emphasis</tag>. This may be presented as + italic, or bold, or might be spoken differently with a + text-to-speech system.</para> + + <para>There is no way to change the presentation of the + emphasis within the document, no equivalent of + <acronym>HTML</acronym>'s <tag>b</tag> and + <tag>i</tag>. If the information being presented is + important, then consider presenting it in + <tag>important</tag> rather than + <tag>emphasis</tag>.</para> + + <example> + <title><tag>emphasis</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> + premiere &unix;-like operating system for the Intel + architecture.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>&os; is without doubt <emphasis>the</emphasis> + premiere &unix;-like operating system for the Intel + architecture.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-acronyms"> + <title>Acronyms</title> + + <para>Many computer terms are <emphasis>acronyms</emphasis>, + words formed from the first letter of each word in a + phrase. Acronyms are marked up into + <tag>acronym</tag> elements. It is helpful to the + reader when an acronym is defined on the first use, as shown + in the example below.</para> + + <example> + <title><tag>acronym</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The + quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently + transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Request For Comments (<acronym>RFC</acronym>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<acronym>IP</acronym>) data. The + quantity of <acronym>IP</acronym> data currently + transmitted in that manner is unknown.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-quotations"> + <title>Quotations</title> + + <para>To quote text from another document or source, or to + denote a phrase that is used figuratively, use + <tag>quote</tag>. Most of the markup tags available + for normal text are also available from within a + <tag>quote</tag>.</para> + + <example> + <title><tag>quote</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the + <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, + as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>However, make sure that the search does not go beyond + the <quote>boundary between local and public + administration</quote>, as <acronym>RFC</acronym> 1535 + calls it.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-keys"> + <title>Keys, Mouse Buttons, and Combinations</title> + + <para>To refer to a specific key on the keyboard, use + <tag>keycap</tag>. To refer to a mouse button, use + <tag>mousebutton</tag>. And to refer to + combinations of key presses or mouse clicks, wrap them all + in <tag>keycombo</tag>.</para> + + <para><tag>keycombo</tag> has an attribute called + <literal>action</literal>, which may be one of + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal>, or <literal>simul</literal>. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously.</para> + + <para>The stylesheets automatically add any connecting + symbols, such as <literal>+</literal>, between the key + names, when wrapped in <tag>keycombo</tag>.</para> + + <example> + <title>Keys, Mouse Buttons, and Combinations Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type + <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>My window manager is configured so that + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> + <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + + <para>To exit <command>vi</command> without saving changes, + type <keycombo action="seq"> + <keycap>Esc</keycap> + <keycap>:</keycap> + <keycap>q</keycap> + <keycap>!</keycap></keycombo>.</para> + + <para>My window manager is configured so that + <keycombo action="simul"> + <keycap>Alt</keycap> + <mousebutton>right</mousebutton></keycombo> mouse button + is used to move windows.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-applications"> + <title>Applications, Commands, Options, and Cites</title> + + <para>Both applications and commands are frequently referred to + when writing documentation. The distinction between them is + that an application is the name of a program or suite of + programs that fulfill a particular task. A command is the + filename of a program that the user can type and run at a + command line.</para> + + <para>It is often necessary to show some of the options that a + command might take.</para> + + <para>Finally, it is often useful to list a command with its + manual section number, in the <quote>command(number)</quote> + format so common in Unix manuals.</para> + + <para>Mark up application names with + <tag>application</tag>.</para> + + <para>To list a command with its manual section + number (which should be most of the time) the DocBook + element is <tag>citerefentry</tag>. This will + contain a further two elements, + <tag>refentrytitle</tag> and + <tag>manvolnum</tag>. The content of + <tag>refentrytitle</tag> is the name of the command, + and the content of <tag>manvolnum</tag> is the + manual page section.</para> + + <para>This can be cumbersome to write, and so a series of + <link linkend="xml-primer-general-entities">general + entities</link> have been created to make this easier. + Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/xml/man-refs.ent</filename>, and can be + referred to using this <acronym>FPI</acronym>:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to &os; documentation will + usually include this:</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para>Use <tag>command</tag> to include a command + name <quote>in-line</quote> but present it as something the + user should type.</para> + + <para>Use <tag>option</tag> to mark up the options + which will be passed to a command.</para> + + <para>When referring to the same command multiple times in + close proximity, it is preferred to use the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + notation to markup the first reference and use + <tag>command</tag> to markup subsequent references. + This makes the generated output, especially + <acronym>HTML</acronym>, appear visually better.</para> + + <example> + <title>Applications, Commands, and Options Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most + widely used Unix mail application.<tag class="starttag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the + <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; + programs.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current + status of messages in the mail queue. Check this on the command + line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para><application>Sendmail</application> is the most widely + used Unix mail application.</para> + + <para><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, and &man.newaliases.1; + programs.</para> + + <para>One of the command line parameters to + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the + current status of messages in the mail queue. Check this + on the command line by running + <command>sendmail -bp</command>.</para> + </example> + + <note> + <para>Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + notation is easier to follow.</para> + </note> + </sect2> + + <sect2 xml:id="docbook-markup-files"> + <title>Files, Directories, Extensions, Device Names</title> + + <para>To refer to the name of a file, a directory, a file + extension, or a device name, use <tag>filename</tag>.</para> + + <example> + <title><tag>filename</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>The source for the Handbook in English is found in + <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. + The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>. + There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a + number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected + by the system, and appears in + <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>The source for the Handbook in English is found in + <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. + The main file is called <filename>book.xml</filename>. + There is also a <filename>Makefile</filename> and a number + of files with a <filename>.ent</filename> extension.</para> + + <para><filename>kbd0</filename> is the first keyboard detected + by the system, and appears in + <filename>/dev</filename>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-name-of-ports"> + <title>The Name of Ports</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>To include the name of a program from the &os; + Ports Collection in the document, use the <tag>package</tag> + tag. Since the Ports Collection can be installed in any + number of locations, only include the category and the port + name; do not include <filename>/usr/ports</filename>.</para> + + <para>By default, <tag>package</tag> refers to a binary package. + To refer to a port that will be built from source, set the + <literal>role</literal> attribute to + <literal>port</literal>.</para> + + <example> + <title><tag>package</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary + package to view network traffic.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be + built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Install the <package>net/wireshark</package> binary + package to view network traffic.</para> + + <para><package role="port">net/wireshark</package> can also be + built and installed from the Ports Collection.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-hosts"> + <title>Hosts, Domains, IP Addresses, User Names, Group Names, + and Other System Items</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>Information for <quote>system items</quote> is marked up + with <tag>systemitem</tag>. The <literal>class</literal> + attribute is used to identify the particular type of + information shown.</para> + + <variablelist> + <varlistentry> + <term><literal>class="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>FreeBSD.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="etheraddress"</literal></term> + + <listitem> + <para>The text is an Ethernet <acronym>MAC</acronym> + address, expressed as a series of 2 digit hexadecimal + numbers separated by colons.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="fqdomainname"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with + both hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="ipaddress"</literal></term> + + <listitem> + <para>The text is an <acronym>IP</acronym> address, + probably expressed as a dotted quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be + expressed as a dotted quad, a hexadecimal string, or as + a <literal>/</literal> followed by a number + (<acronym>CIDR</acronym> notation).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="systemname"</literal></term> + + <listitem> + <para>With <literal>class="systemname"</literal> + the marked up information is the simple hostname, such + as <literal>freefall</literal> or + <literal>wcarchive</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="username"</literal></term> + + <listitem> + <para>The text is a username, like + <literal>root</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>class="groupname"</literal></term> + + <listitem> + <para>The text is a groupname, like + <literal>wheel</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><tag>systemitem</tag> and Classes Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the + name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP + address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag> + domain contains a number of different hosts, including + <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and + <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an + interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) + <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of + <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can + also be expressed as + <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies + every network card in existence. A typical + <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like + <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>To carry out most system administration functions + requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>The local machine can always be referred to by the name + <systemitem>localhost</systemitem>, which will have the IP + address + <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> + + <para>The + <systemitem class="fqdomainname">FreeBSD.org</systemitem> + domain contains a number of different hosts, including + <systemitem + class="fqdomainname">freefall.FreeBSD.org</systemitem> and + <systemitem + class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> + + <para>When adding an <acronym>IP</acronym> alias to an + interface (using <command>ifconfig</command>) + <emphasis>always</emphasis> use a netmask of + <systemitem class="netmask">255.255.255.255</systemitem> + (which can also be expressed as + <systemitem class="netmask">0xffffffff</systemitem>).</para> + + <para>The <acronym>MAC</acronym> address uniquely identifies + every network card in existence. A typical + <acronym>MAC</acronym> address looks like <systemitem + class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> + + <para>To carry out most system administration functions + requires logging in as + <systemitem class="username">root</systemitem>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-uri"> + <title>Uniform Resource Identifiers + (<acronym>URI</acronym>s)</title> + + <para>Occasionally it is useful to show a + Uniform Resource Identifier (<acronym>URI</acronym>) without + making it an active hyperlink. The <tag>uri</tag> element + makes this possible:</para> + + <example> + <title><tag>uri</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text: + <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not + create a link.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>This <acronym>URL</acronym> shows only as text: + <uri>https://www.FreeBSD.org</uri>. It does not + create a link.</para> + </example> + + <para>To create links, see + <xref linkend="docbook-markup-links"/>.</para> + </sect2> + + <sect2 xml:id="docbook-markup-email-addresses"> + <title>Email Addresses</title> + + <para>Email addresses are marked up as <tag>email</tag> + elements. In the <acronym>HTML</acronym> output format, the + wrapped text becomes a hyperlink to the email address. Other + output formats that support hyperlinks may also make the email + address into a link.</para> + + <example> + <title><tag>email</tag> with a Hyperlink Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>An email address that does not actually exist, like + <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an + example.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>An email address that does not actually exist, like + <email>notreal@example.com</email>, can be used as an + example.</para> + </example> + + <para>A &os;-specific extension allows setting the + <literal>role</literal> attribute to <literal>nolink</literal> + to prevent the creation of the hyperlink to the email + address.</para> + + <example> + <title><tag>email</tag> Without a Hyperlink Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Sometimes a link to an email address like + <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not + desired.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Sometimes a link to an email address like + <email role="nolink">notreal@example.com</email> is not + desired.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-describing-makefiles"> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, <tag>buildtarget</tag> + and <tag>varname</tag>.</para> + + <para><tag>buildtarget</tag> identifies a build target + exported by a <filename>Makefile</filename> that can be + given as a parameter to <command>make</command>. + <tag>varname</tag> identifies a variable that can be + set (in the environment, on the command line with + <command>make</command>, or within the + <filename>Makefile</filename>) to influence the + process.</para> + + <example> + <title><tag>buildtarget</tag> and + <tag>varname</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> + are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will + rebuild the application, and invoking + <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary + files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the + build process.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a + number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag> + and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Two common targets in a <filename>Makefile</filename> + are <buildtarget>all</buildtarget> and + <buildtarget>clean</buildtarget>.</para> + + <para>Typically, invoking <buildtarget>all</buildtarget> will + rebuild the application, and invoking + <buildtarget>clean</buildtarget> will remove the temporary + files (<filename>.o</filename> for example) created by the + build process.</para> + + <para><buildtarget>clean</buildtarget> may be controlled by a + number of variables, including <varname>CLOBBER</varname> + and <varname>RECURSE</varname>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-literal-text"> + <title>Literal Text</title> + + <para>Literal text, or text which should be entered verbatim, is + often needed in documentation. This is text that is excerpted + from another file, or which should be copied exactly as shown + from the documentation into another file.</para> + + <para>Some of the time, <tag>programlisting</tag> will + be sufficient to denote this text. But + <tag>programlisting</tag> is not always appropriate, + particularly when you want to include a portion of a file + <quote>in-line</quote> with the rest of the + paragraph.</para> + + <para>On these occasions, use + <tag>literal</tag>.</para> + + <example> + <title><tag>literal</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous + logins the system will support.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-replaceable"> + <title>Showing Items That the User <emphasis>Must</emphasis> + Fill In</title> + + <para>There will often be times when the user is shown + what to do, or referred to a file or command line, but + cannot simply copy the example provided. Instead, they + must supply some information themselves.</para> + + <para><tag>replaceable</tag> is designed for this + eventuality. Use it <emphasis>inside</emphasis> other + elements to indicate parts of that element's content that + the user must replace.</para> + + <example> + <title><tag>replaceable</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><tag>replaceable</tag> can be used in many + different elements, including <tag>literal</tag>. + This example also shows that <tag>replaceable</tag> + should only be wrapped around the content that the user + <emphasis>is</emphasis> meant to provide. The other content + should be left alone.</para> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value + for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>The + <literal>maxusers <replaceable>n</replaceable></literal> + line in the kernel configuration file determines the size + of many system tables, and is a rough guide to how many + simultaneous logins the system will support.</para> + + <para>For a desktop workstation, <literal>32</literal> is a + good value for <replaceable>n</replaceable>.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-gui-buttons"> + <title>Showing <acronym>GUI</acronym> Buttons</title> + + <para>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.</para> + + <example> + <title><tag>guibutton</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Edit the file, then click + <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the + changes.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Edit the file, then click + <guibutton>[ Save ]</guibutton> to save the + changes.</para> + </example> + </sect2> + + <sect2 xml:id="docbook-markup-system-errors"> + <title>Quoting System Errors</title> + + <para>System errors generated by &os; are marked with + <tag>errorname</tag>. This indicates the exact error + that appears.</para> + + <example> + <title><tag>errorname</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-images"> + <title>Images</title> + + <important> + <para>Image support in the documentation is somewhat + experimental. The mechanisms described here are unlikely to + change, but that is not guaranteed.</para> + + <para>To provide conversion between different image formats, the + <package>graphics/ImageMagick</package> + port must be installed. This port is not included in the + <package>textproc/docproj</package> meta + port, and must be installed separately.</para> + + <para>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.</para> + </important> + + <sect2 xml:id="docbook-markup-image-formats"> + <title>Image Formats</title> + + <para>The following image formats are currently supported. An + image file will automatically be converted to bitmap or vector + image depending on the output document format.</para> + + <para>These are the <emphasis>only</emphasis> formats in which + images should be committed to the documentation + repository.</para> + + <variablelist> + <varlistentry> + <term><acronym>EPS</acronym> (Encapsulated + Postscript)</term> + + <listitem> + <para>Images that are primarily vector based, such as + network diagrams, time lines, and similar, should be in + this format. These images have a + <filename>.eps</filename> extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>PNG</acronym> (Portable Network + Graphic)</term> + + <listitem> + <para>For bitmaps, such as screen captures, use this + format. These images have the <filename>.png</filename> + extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>PIC</acronym> (PIC graphics language)</term> + + <listitem> + <para><acronym>PIC</acronym> is a language for drawing + simple vector-based figures used in the &man.pic.1; + utility. These images have the + <filename>.pic</filename> extension.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><acronym>SCR</acronym> (SCReen capture)</term> + + <listitem> + <para>This format is specific to screenshots of console + output. The following command generates an SCR file + <filename>shot.scr</filename> from video buffer of + <filename>/dev/ttyv0</filename>:</para> + + <screen>&prompt.root; <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen> + + <para>This is preferable to <acronym>PNG</acronym> format + for screenshots because the <acronym>SCR</acronym> file + contains plain text of the command lines so that it can + be converted to a <acronym>PNG</acronym> image or a + plain text depending on the output document + format.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Use the appropriate format for each image. Documentation + will often have a mix of <acronym>EPS</acronym> and + <acronym>PNG</acronym> images. The + <filename>Makefile</filename>s ensure that the correct format + image is chosen depending on the output format used. + <emphasis>Do not commit the same image to the repository in + two different formats</emphasis>.</para> + + <important> + <para>The Documentation Project may eventually switch to using + the <acronym>SVG</acronym> (Scalable Vector Graphic) format + for vector images. However, the current state of + <acronym>SVG</acronym> capable editing tools makes this + impractical.</para> + </important> + </sect2> + + <sect2 xml:id="docbook-markup-image-file-locations"> + <title>Image File Locations</title> + + <para>Image files can be stored in one of several locations, + depending on the document and image:</para> + + <itemizedlist> + <listitem> + <para>In the same directory as the document itself, usually + done for articles and small books that keep all their + files in a single directory.</para> + </listitem> + + <listitem> + <para>In a subdirectory of the main document. Typically + done when a large book uses separate subdirectories to + organize individual chapters.</para> + + <para>When images are stored in a subdirectory of the + main document directory, the subdirectory name must be + included in their paths in the + <filename>Makefile</filename> and the + <tag>imagedata</tag> element.</para> + </listitem> + + <listitem> + <para>In a subdirectory of + <filename>doc/share/images</filename> named after the + document. For example, images for the Handbook are stored + in <filename>doc/share/images/books/handbook</filename>. + Images that work for multiple translations are stored in + this upper level of the documentation file tree. + Generally, these are images that can be used unchanged in + non-English translations of the document.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-markup"> + <title>Image Markup</title> + + <para>Images are included as part of a <tag>mediaobject</tag>. + The <tag>mediaobject</tag> can contain other, more specific + objects. We are concerned with two, the + <tag>imageobject</tag> and the <tag>textobject</tag>.</para> + + <para>Include one <tag>imageobject</tag>, and two + <tag>textobject</tag> elements. The <tag>imageobject</tag> + will point to the name of the image file without the + extension. The <tag>textobject</tag> elements contain + information that will be presented to the user as well as, or + instead of, the image itself.</para> + + <para>Text elements are shown to the reader in several + situations. When the document is viewed in + <acronym>HTML</acronym>, text elements are shown while the + image is loading, or if the mouse pointer is hovered over the + image, or if a text-only browser is being used. In formats + like plain text where graphics are not possible, the text + elements are shown instead of the graphical ones.</para> + + <para>This example shows how to include an image called + <filename>fig1.png</filename> in a document. The image is a + rectangle with an A inside it:</para> + + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> + <tag class="endtag">imageobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> +| A | ++---------------+<tag class="endtag">literallayout</tag> + <tag class="endtag">textobject</tag> + + <tag class="starttag">textobject</tag> + <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> + <tag class="endtag">textobject</tag> +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para>Include an <tag>imagedata</tag> element + inside the <tag>imageobject</tag> element. The + <literal>fileref</literal> attribute should contain the + filename of the image to include, without the extension. + The stylesheets will work out which extension should be + added to the filename automatically.</para> + </callout> + + <callout arearefs="co-image-literal"> + + <para>The first <tag>textobject</tag> contains a + <tag>literallayout</tag> element, where the + <literal>class</literal> attribute is set to + <literal>monospaced</literal>. This is an opportunity to + demonstrate <acronym>ASCII</acronym> art skills. This + content will be used if the document is converted to plain + text.</para> + + <para>Notice how the first and last lines of the content + of the <tag>literallayout</tag> element butt up + next to the element's tags. This ensures no extraneous + white space is included.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para>The second <tag>textobject</tag> contains a + single <tag>phrase</tag> element. The contents of + this phrase will become the <literal>alt</literal> + attribute for the image when this document is converted to + <acronym>HTML</acronym>.</para> + </callout> + </calloutlist> + </sect2> + + <sect2 xml:id="docbook-markup-image-makefile-entries"> + <title>Image <filename>Makefile</filename> Entries</title> + + <para>Images must be listed in the <filename>Makefile</filename> + in the <varname>IMAGES</varname> variable. This variable must + contain the names of all the <emphasis>source</emphasis> + images. For example, if there are three figures, + <filename>fig1.eps</filename>, <filename>fig2.png</filename>, + <filename>fig3.png</filename>, then the + <filename>Makefile</filename> should have lines like this in + it.</para> + + <programlisting>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>or</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para>Again, the <filename>Makefile</filename> will work out the + complete list of images it needs to build the source document, + you only need to list the image files <emphasis>you</emphasis> + provided.</para> + </sect2> + + <sect2 xml:id="docbook-markup-images-in-subdirectories"> + <title>Images and Chapters in Subdirectories</title> + + <para>Be careful when separating documentation into smaller + files in different directories (see <xref + linkend="xml-primer-include-using-gen-entities"/>).</para> + + <para>Suppose there is a book with three chapters, and the + chapters are stored in their own directories, called + <filename>chapter1/chapter.xml</filename>, + <filename>chapter2/chapter.xml</filename>, and + <filename>chapter3/chapter.xml</filename>. If each chapter + has images associated with it, place those images in each + chapter's subdirectory (<filename>chapter1/</filename>, + <filename>chapter2/</filename>, and + <filename>chapter3/</filename>).</para> + + <para>However, doing this requires including the directory + names in the <varname>IMAGES</varname> variable in the + <filename>Makefile</filename>, <emphasis>and</emphasis> + including the directory name in the <tag>imagedata</tag> + element in the document.</para> + + <para>For example, if the book has + <filename>chapter1/fig1.png</filename>, then + <filename>chapter1/chapter.xml</filename> should + contain:</para> + + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> + <tag class="endtag">imageobject</tag> + + … + +<tag class="endtag">mediaobject</tag></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para>The directory name must be included in the + <literal>fileref</literal> attribute.</para> + </callout> + </calloutlist> + + <para>The <filename>Makefile</filename> must contain:</para> + + <programlisting>… +IMAGES= chapter1/fig1.png +…</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="docbook-markup-links"> + <title>Links</title> + + <note> + <para>Links are also in-line elements. To show a + <acronym>URI</acronym> without creating a link, see + <xref linkend="docbook-markup-uri"/>.</para> + </note> + + <sect2 xml:id="docbook-markup-links-ids"> + <title><literal>xml:id</literal> Attributes</title> + + <para>Most DocBook elements accept an <literal>xml:id</literal> + attribute to give that part of the document a unique name. + The <literal>xml:id</literal> can be used as a target for a + crossreference or link.</para> + + <para>Any portion of the document that will be a link target + must have an <literal>xml:id</literal> attribute. Assigning + an <literal>xml:id</literal> to all chapters and sections, + even if there are no current plans to link to them, is a good + idea. These <literal>xml:id</literal>s can be used as unique + reference points by anyone referring to the + <acronym>HTML</acronym> version of the document.</para> + + <example> + <title><literal>xml:id</literal> on Chapters and + Sections Example</title> + + <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is the introduction. It contains a subsection, + which is identified as well.<tag class="endtag">para</tag> + + <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> + <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> + + <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> + </example> + + <para>Use descriptive values for <literal>xml:id</literal> + names. The values must be unique within the entire document, + not just in a single file. In the example, the subsection + <literal>xml:id</literal> is constructed by appending text to + the chapter <literal>xml:id</literal>. This ensures that the + <literal>xml:id</literal>s are unique. It also helps both + reader and anyone editing the document to see where the link + is located within the document, similar to a directory path to + a file.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-crossreferences"> + <title>Crossreferences with <literal>xref</literal></title> + + <para><tag>xref</tag> provides the reader with a link to jump to + another section of the document. The target + <literal>xml:id</literal> is specified in the + <literal>linkend</literal> attribute, and <tag>xref</tag> + generates the link text automatically.</para> + + <example> + <title><tag>xref</tag> Example</title> + + <para>Assume that this fragment appears somewhere in a + document that includes the <literal>xml:id</literal> + example shown above:</para> + + <programlisting><tag class="starttag">para</tag>More information can be found + in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> + +<tag class="starttag">para</tag>More specific information can be found + in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting> + + <para>The link text will be generated automatically, looking + like (<emphasis>emphasized</emphasis> text indicates the + link text):</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + 1, Introduction</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>Section 1.1, + <quote>More Details</quote></emphasis>.</para> + </blockquote> + </example> + + <para>The link text is generated automatically from the chapter + and section number and <literal>title</literal> + elements.</para> + </sect2> + + <sect2 xml:id="docbook-markup-links-to-web-documents"> + <title>Linking to Other Documents on the + Web</title> + + <para>The link element described here allows the writer to + define the link text. When link text is used, it is very + important to be descriptive to give the reader an idea of + where the link goes. Remember that DocBook can be rendered to + multiple types of media. The reader might be looking at a + printed book or other form of media where there are no links. + If the link text is not descriptive enough, the reader might + not be able to locate the linked section.</para> + + <para>The <literal>xlink:href</literal> attribute is the + <acronym>URL</acronym> of the page, and the content of the + element is the text that will be displayed for the user to + activate.</para> + + <para>In many situations, it is preferable to show the actual + <acronym>URL</acronym> rather than text. This can be done by + leaving out the element text entirely.</para> + + <example> + <title><tag>link</tag> to a &os; Documentation Web + Page Example</title> + + <para>Link to the book or article <acronym>URL</acronym> + entity. To link to a specific chapter in a book, add a + slash and the chapter file name, followed by an optional + anchor within the chapter. For articles, link to the + article <acronym>URL</acronym> entity, followed by an + optional anchor within the article. + <acronym>URL</acronym> entities can be found in + <filename>doc/share/xml/urls.ent</filename>.</para> + + <para>Usage for &os; book links:</para> + + <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN + introduction<tag class="endtag">link</tag>, then pick the nearest mirror from + the list of <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion + mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Read the <link + xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN + introduction</link>, then pick the nearest mirror from + the list of <link + xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion + mirror sites</link>.</para> + + <para>Usage for &os; article links:</para> + + <programlisting><tag class="starttag">para</tag>Read this + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article + about the BSD license<tag class="endtag">link</tag>, or just the + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Read this + <link xlink:href="&url.articles.bsdl-gpl;">article + about the BSD license</link>, or just the <link + xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para> + </example> + + <example> + <title><tag>link</tag> to a &os; Web Page Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the + <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go + to the <link xlink:href="&url.base;/index.html">FreeBSD + home page</link> instead.</para> + </example> + + <example> + <title><tag>link</tag> to an External Web + Page Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID + Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>Wikipedia has an excellent reference on <link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</link>.</para> + + <para>The link text can be omitted to show the actual + URL:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> + + <para>The same link can be entered using shorter + notation instead of a separate ending tag:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="emptytag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> + + <para>The two methods are equivalent. Appearance:</para> + + <para>Wikipedia has an excellent reference on GUID Partition + Tables: <uri + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para> + </example> + </sect2> + </sect1> +</chapter> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/editor-config/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/editor-config/chapter.xml new file mode 100644 index 0000000000..bc2dd0f2e5 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/editor-config/chapter.xml @@ -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 "&[^;]*;" + 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/<CR> + 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> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.xml b/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.xml index 8b7412d082..7dc16ab1ab 100644 --- a/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.xml +++ b/pt_BR.ISO8859-1/books/fdp-primer/examples/appendix.xml @@ -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> - - <para>Este apndice contm 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 - Documentao, ento voc ser - capaz de utilizar estes exemplos imediatamente.</para> - - <para>Estes exemplos no so exaustivos — eles - no contm todos os elementos que voc pode - utilizar, particularmente para a capa do seu documento. Para - maiores exemplos de marcao DocBook voc - deve examinar o cdigo SGML deste e de outros documentos, - disponveis no repositrio <literal>doc</literal> - do <application>svn</application>, ou disponveis online - no endereo - <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>. - </para> - - <para>Para evitar confuso, estes exemplos utilizam a - especificao DocBook 4.1 DTD sem nenhuma - extenso particular adicionada pelo FreeBSD. Eles - tambm utilizam as folhas de estilo padres - distribudas pelo Norm Walsh, sem nenhuma - customizao feita nas mesmas pelo Projeto de - Documentao do FreeBSD. Isto os torna mais - teis como exemplos genricos de - marcao DocBook.</para> +<appendix xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="examples"> + + <title>Examples</title> + <para>These examples are not exhaustive—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"> - -<book> - <bookinfo> - <title>Um exemplo de Livro</title> - - <author> - <firstname>Seu nome</firstname> - <surname>Seu sobrenome</surname> - <affiliation> - <address><email>seuemail@example.com</email></address> - </affiliation> - </author> - - <copyright> - <year>2000</year> - <holder>Texto de Copyright</holder> - </copyright> - - <abstract> - <para>Se seu livro possui um sumrio ele deve ser colocado aqui.</para> - </abstract> - </bookinfo> - - <preface> - <title>Prefcio</title> - - <para>Seu livro pode ter um prefcio, se este for o caso, ele deve - ser colocado aqui.</para> - </preface> - - <chapter> - <title>Meu primeiro captulo</title> - - <para>Este o primeiro captulo do meu livro.</para> - - <sect1> - <title>Minha primeira seo</title> - - <para>Esta a primeira seo do meu livro.</para> - </sect1> - </chapter> -</book>]]></programlisting> + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> + +<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> + + <tag class="starttag">info</tag> + <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag> + + <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> + + <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> + + <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> + + <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> + + <tag class="starttag">preface</tag> + <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> + + <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><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> -<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 sumrio 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 seo</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 seo 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 subseo</title> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> - <para>Esta a primeira subseo do meu artigo.</para> - </sect2> - </sect1> -</article>]]></programlisting> - </example> - </sect1> + <tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag> - <sect1 xml:id="examples-formatted"> - <title>Produzindo sadas formatadas</title> - - <para>Esta seo assume que voc j - instalou os softwares listados no port <package>textproc/docproj</package>, seja via meta-port - ou manualmente. Alm disso, ela tambm assume - que os seus softwares esto instalados em - subdiretrios sob o <filename>/usr/local/</filename>, - e que os diretrios nos quais os binrios foram - instalados, esto 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 > file.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-1-nochunks"> - <para>Especifique o parmetro <literal>nochunks - </literal> para as folhas de estilo, forando - que todos os outputs sejam escritos para a sada - padro (<abbrev>STDOUT</abbrev>) (utilizando as - folhas de estilo do Norm Walsh).</para> - </callout> - - <callout arearefs="examples-co-jade-1-catalog"> - <para>Especifique os catlogos que o - <application>Jade</application> ter que - processar. Trs catlogos so - requeridos. O primeiro o catlogo - que contm as informaes sobre - as folhas de estilo DSSSL. O segundo contm - informaes sobre o DTD DockBook. E - o terceiro contm informaes - especficas 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>transformao - </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 sada para o arquivo - <filename>.html</filename> desejado.</para> - </callout> - </calloutlist> - </example> - - <example> - <title>Convertendo de DocBook para HTML (vrios - 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 catlogos os quais o - <application>Jade</application> ter que - processar. Trs catlogos so - requeridos. O primeiro o catlogo - o qual contm as informaes - sobre as folhas de estilo DSSSL. O segundo - contm informaes sobre o DTD - DocBook. O terceiro contm - informaes especficas 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>transformao - </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 sero nomeados, inclusive o nome - do arquivo <quote>raiz</quote> ( o arquivo - que contm 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 diviso - 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 - vrias opes existentes, - especficas para a produo - de sadas &tex;.</para> - </callout> - - <callout arearefs="examples-co-jade-3-catalog"> - <para>Especifique os catlogos os quais o - <application>Jade</application> ter que - processar. Trs catlogos so - requeridos. O primeiro o catlogo o - qual contm as informaes sobre - as folhas de estilo DSSSL. O segundo contm - informaes sobre o DTD DocBook. O - terceiro contm informaes - especficas para o Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-3-dsssl"> - <para>Especifique o caminho completo da folha de estilo - DSSSL a qual o <application>Jade</application> - ir utilizar quando estiver processando o - documento.</para> - </callout> - - <callout arearefs="examples-co-jade-3-tex"> - <para>Instrua o <application>Jade</application> para - converter o output para &tex;.</para> - </callout> - </calloutlist> - - <para>O arquivo <filename>.tex</filename> gerado, deve ser - agora processado pelo <command>tex</command>, especificando - o pacote de macros <literal>&jadetex</literal>.</para> - - <screen>&prompt.user; <userinput>tex "&jadetex" file.tex</userinput></screen> - - <para>Voc tem que executar o <command>tex</command> - <emphasis>pelo menos</emphasis> trs vezes. A - primeira execuo ir processar o - documento, e determinar as reas do documento que - so referenciadas a partir de outras partes do - documento, para uso na indexao, etc.</para> - - <para>No 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 execuo reprocessa o documento - agora que certas peas de informao - so conhecidas (tais como o nmero de - pginas do documento). Isto permite indexar as - entradas e estabelecer as outras referncias - cruzadas.</para> - - <para>A terceira execuo ir realizar - a limpeza final necessria no arquivo</para> - - <para>O output deste estgio 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 idntica ao - realizado quando se converte de DocBook para Postscript, - utilizando a mesma linha de comando para o - <command>jade</command> - (<xref linkend="examples-docbook-postscript"/>).</para> - - <para>Quando o arquivo <filename>.tex</filename> j - tiver sido gerado, voc deve executar o - <application>pdfTeX</application> utilizando o pacote de - macros <literal>&pdfjadetex</literal>.</para> - - <screen>&prompt.user; <userinput>pdftex "&pdfjadetex" file.tex</userinput></screen> - - <para>De novo, execute este comando trs vezes.</para> - - <para>Ele ir gerar um <filename>arquivo - .pdf</filename>, o qual no necessita - de nenhum processamento adicional.</para> - </example> - </sect2> + <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> </appendix> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/manpages/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/manpages/chapter.xml new file mode 100644 index 0000000000..e866470d81 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/manpages/chapter.xml @@ -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 — 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> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml index 8449df3c4c..ded4a1a672 100644 --- a/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/pt_BR.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -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>Viso Geral</title> - - <para>Seja bem vindo ao Projeto de Documentao do - FreeBSD. Documentao de boa qualidade - muito importante para o sucesso do FreeBSD, e o Projeto de - Documentao do FreeBSD (FDP) a origem - de muitos destes documentos. Suas contribuies - so muito importantes.</para> - - <para>A finalidade principal deste documento explicar - claramente <emphasis>como o FDP organizado</emphasis>, - <emphasis>como escrever e como submeter documentos para o FDP - </emphasis>, e <emphasis>como utilizar de forma efetiva as - ferramentas que esto disponveis para voc - enquanto estiver escrevendo</emphasis>.</para> - - <para><indexterm><primary>Sociedade</primary></indexterm>Todos - so bem vindos para se juntar ao FDP. No - existe nenhum requisito mnimo para a sua - associao, nenhuma quota de documentos que - voc precise produzir por ms. Tudo o que voc - precisa fazer se inscrever na &a.doc;.</para> - - <para>Depois que voc tiver terminado de ler este documento, - voc deve:</para> + <title>Overview</title> + + <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>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>Everyone is welcome to contribute to the + <acronym>FDP</acronym>. Willingness to contribute is the only + membership requirement.</para> + + <para>This primer shows how to:</para> <itemizedlist> <listitem> - <para>Saber quais documentos so 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 cdigo 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 alteraes num - documento.</para> + <para>Make changes to the documentation.</para> </listitem> <listitem> - <para>Ser capaz de enviar suas alteraes de - volta para reviso e eventual incluso na - documentao 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 Documentao do FreeBSD</title> - - <para>O FDP responsvel por quatro categorias de - documentos do FreeBSD.</para> - - <variablelist> - <varlistentry> - <term>Pginas de Manual</term> - - <listitem> - <para>As pginas de manual do sistema na - lngua inglesa no so escritas pelo - FDP, porque elas so parte da base do sistema. - Entretanto, o FDP pode (e tem) reescrever partes das - pginas de manual existentes para torn-las - mais claras, ou para corrigir imprecises.</para> - - <para>Os times de traduo so - responsveis por traduzir as pginas de - manual do sistema para diferentes idiomas. Estas - tradues so 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 vrias - listas de discusso e newsgroups dedicados ao - FreeBSD. O formato no permite respostas longas - e detalhadas.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>O Handbook almeja ser um compreensivo recurso de - referncia online para os usurios do - FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web Site</term> - - <listitem> - <para>Esta a principal presena do FreeBSD - na <literal>World Wide Web</literal>, visvel 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 documentao do web site, do Handbook do - &os; e do FAQ esto disponveis no - repositrio Subversion <literal>doc/</literal>, que - est localizado em - <literal>svn://svn.FreeBSD.org/doc/</literal>.</para> - - <para>As pginas de manual esto disponveis - no repositrio Subversion <literal>src/</literal>, que - est disponvel em - <literal>svn://svn.FreeBSD.org/base/</literal>.</para> - - <para>Isto significa que os logs das alteraes - realizadas nestes arquivos visvel para qualquer - um, e qualquer pessoa pode utilizar o - <application>svn</application> para ver as - alteraes.</para> - - <para>Em adio, muitas pessoas escreveram - tutoriais ou outros web sites relacionados ao FreeBSD. - Alguns destes trabalhos tambm esto armazenados - no repositrio Subversion (com a permisso - do autor). Em outros casos o autor decidiu manter o seu - documento separado do repositrio principal do FreeBSD. - O FDP se esfora tanto quanto possvel para - fornecer os links para estes documentos.</para> + <sect1 xml:id="overview-quick-start"> + <title>Quick Start</title> - </sect1> + <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> - <sect1 xml:id="overview-before"> - <title>Antes de voc iniciar</title> + <procedure> + <step> + <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>pkg install docproj subversion</userinput></screen> + </step> - <para>Este documento assume que voc j sabe:</para> + <step> + <para>Install a local working copy of the documentation from + the &os; repository in + <filename>~/doc</filename> (see + <xref linkend="working-copy"/>).</para> - <itemizedlist> - <listitem> - <para>Como manter uma cpia local atualizada da - documentao do &os;, atravs da - manuteno de uma cpia local do - repositrio Subversion do FreeBSD utilizando o - <application>svn</application>.</para> - </listitem> + <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + </step> - <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> + <step> + <para>Configure the text editor:</para> - <sect1 xml:id="overview-quick-start"> - <title>Incio Rpido</title> + <itemizedlist> + <listitem> + <para>Word wrap set to 70 characters.</para> + </listitem> - <para>Se voc deseja ir comeando, e se sente - seguro de que pode ir pegando as coisas medida que - avana, siga estas instrues.</para> + <listitem> + <para>Tab stops set to 2.</para> + </listitem> + + <listitem> + <para>Replace each group of 8 leading spaces with a + single tab.</para> + </listitem> + </itemizedlist> + + <para>Specific editor configurations are listed in + <xref linkend="editor-config"/>.</para> + </step> - <procedure> <step> - <para>Instale o meta-port <package> - textproc/docproj</package>.</para> + <para>Update the local working copy:</para> - <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput> -&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + <screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> </step> <step> - <para>Obtenha uma cpia local da rvore de - documentao do FreeBSD (<filename>doc</filename>) - utilizando o <application>svn</application>.</para> - - <para>Se a velocidade da sua conexo ou se o espao de - armazenamento do seu disco local forem motivo de - preocupao, o mnimo que voc - vai precisar ser uma cpia de trabalho dos - diretrios <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 abundncia de espao - em disco, voc pode retirar uma cpia de - trabalho completa (de todos os subdiretrios da - rvore doc).</para> - - <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head head</userinput></screen> + <para>Edit the documentation files that require changes. If a + file needs major changes, consult the mailing list for + input.</para> + <para>References to tag and entity usage can be found in + <xref linkend="xhtml-markup"/> and + <xref linkend="docbook-markup"/>.</para> </step> <step> - <para>Se voc est preparando uma - alterao de um artigo ou livro existente, - retire uma verso de trabalho do arquivo do - repositrio. Se voc est planejando - contribuir com um novo livro ou artigo, ento - 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 cpia de trabalho do - diretrio <filename>articles</filename>.</para> - - <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen> - - </step> - - <step> - <para>Copie um artigo existente para utilizar como - template. Neste caso, voc decidiu que o seu - novo artigo iria para um diretrio chamado - <filename>vpn-w2k</filename>.</para> - - <screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput> -&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen> - - </step> - </procedure> - - <para>Se voc deseja editar um documento existente, - como por exemplo o FAQ, o qual est em <filename> - head/en_US.ISO8859-1/books/faq</filename>, voc deve - retirar a cpia de trabalho do repositrio - 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>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>Edite os arquivos <filename>.xml</filename> - utilizando o editor da sua preferncia.</para> + <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>Teste a marcao 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 - transformao no seu arquivo, o que - consumiria tempo.</para> - - <screen>&prompt.user; <userinput>make lint</userinput></screen> - - <para>Quando voc estiver pronto para efetivamente - compilar o documento, voc pode especificar um - nico formato ou uma lista de formatos de destino, - na varivel <varname>FORMATS</varname>. Atualmente - os formatos suportados so, <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 incio 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 execues 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>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 > <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>Envie suas alteraes utilizando o - &man.send-pr.1;.</para> + <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>[ Add an attachment ]</guibutton> + button to attach the diff file. Finally, use the + <guibutton>[ Submit Bug ]</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> diff --git a/pt_BR.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/pt_BR.ISO8859-1/books/fdp-primer/po-translations/chapter.xml new file mode 100644 index 0000000000..7c365f10d0 --- /dev/null +++ b/pt_BR.ISO8859-1/books/fdp-primer/po-translations/chapter.xml @@ -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 |