<!-- EN-Revision: 327173 Maintainer: fibbarth Status: ready -->
<!-- CREDITS: felipe, ae -->
<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Sobre o manual</title>
<sect1 xml:id="about.formats">
<title>Formatos</title>
<para>
O manual PHP é fornecido em diversos formatos. Estes formatos podem ser divididos
em dois grupos: formatos de leitura online, e em pacotes para download.
</para>
<note>
<para>
Algumas editoras fizeram versões impressas deste manual. Porém estas versões não
são recomendadas, pois tendem a se tornar rapidamente desatualizadas.
</para>
</note>
<para>
O manual PHP pode ser lido online no <link xlink:href="&url.php;">website PHP.net</link>,
e em numerosos outros sites mirror. Para melhor performance, escola
o mirror mais próximo. A versão online do manual PHP tem atualmente duas folhas de estilo
<acronym>CSS</acronym>, uma web amigável e a outra folha de estilo para impressão.
</para>
<para>
Duas vantagens notáveis do manual online sobre a maioria dos formatos offline é a
integração das <link linkend="about.notes">notas dos usuários</link> e os <link xlink:href="&url.php.urlhowto;">atalhos de URL</link> que
podem ser usadas para ir rapidamente para partes do manual. Uma óbvia desvantagem é
o requisito de estar online para visualização desta edição do manual.
</para>
<para>
Existem diversos formatos offline do manual, e o formato mais adequado
depende do sistema operacional e escolha pessoal de estilo leitura.
Para informações de como o manual é gerado e em quais formatos,
veja a seção <link linkend="about.generate">'Como nós geramos os formatos'</link>
deste apêndice.
</para>
<para>
A versão HTML é o formato mais multi-plataforma deste manual. Esta versão está disponível
como um único arquivo HTML e como um pacote de arquivos individuais para cada seção
(que resulta em uma coleção de milhares de arquivos). Nós disponibilizamos esta versão
compactada, então para descompactação é necessário um programa para recuperar os arquivos
contidos dentro deste pacote.
</para>
<!--
A versão PDF do manual PHP está atualmente indisponível. Talves
um dia ele vai existir.
<para>
Outro popular formato multi-plataforma, talvez o formato mais adequado para
impressão, é o PDF (também conhecido como Adobe Acrobat). Mas cuidado, pois o manual
contém mais de 2000 páginas, e é constantemente revisado.
</para>
<note>
<para>
Existe muitos programas para visualizar arquivos <acronym>PDF</acronym>, tais como o
<link xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>.
</para>
</note>
-->
<para>
Para a plataforma Windows, a versão <productname>Windows HTML Help</productname>
do manual condensa os originais no formato HTML para o uso com o
<productname>Windows HTML Help</productname>. Esse
formato tem busca de textos, índice completo e marcadores. Vários
ambientes de desenvolvimento populares do PHP no Windows se integram com
esse formato da documentação para facilitar o acesso a documentação. Visualizadores de CHM para
Linux também estão disponíveis. Veja
<link xlink:href="&url.xchm;">xCHM</link> or
<link xlink:href="&url.gnochm;">GnoCHM</link>.
</para>
<para>
Existe também uma <link xlink:href="&url.php.echm;">versão CHM extendida</link>
disponível, que não é atualizada frequentemente, mas que oferece muitos recursos
adicionais. Está apenas disponível através do <productname>Microsoft Windows</productname>
, devido as tecnologias usadas para compilar essas páginas.
</para>
</sect1>
<sect1 xml:id="about.notes">
<title>Sobre as notas dos usuários</title>
<para>
As notas dos usuários possuem um importante papel no desenvolvimento deste
manual. Ao permitir que os leitores do manual possam contribuir com exemplos,
ressalvas, e outros esclarecimentos através de seus navegadores, somos capazes de
incorporar este feedback dentro do texto principal do manual. E até que as notas
sejam incorporadas, elas podem ser vistas na sua forma online, e em alguns dos
formatos offline.
</para>
<note>
<para>
As notas dos usuários não são moderadas antes delas aparecem online, então
a qualidade da escrita ou exemplo do código, e mesmo a veracidade da contribuição,
não pode ser garantida. (Note que não há garantia de qualidade ou exatidão do próprio
manual).
</para>
</note>
<note>
<para>
Para fins distribuição, as notas fornecidas por usuários são
consideradas parte do manual do PHP, e por isso são cobertas pela
mesma licença desta documentação (atualmente a licença,
Creative Commons Attribution). Para
mais detalhes, veja a página de <link linkend="copyright">
copyright do manual</link>.
</para>
</note>
</sect1>
<sect1 xml:id="about.prototypes">
<title>Como ler a definição de função (protótipo)</title>
<para>
Cada função do manual é documentada para uma referência rápida. E conhecendo
como ler e entender o texto vai fazer aprender PHP muito mais facilmente.
Mais do que simplesmente estudar exemplos ou copiar/colar, todos deveriam
saber como ler as definições de funções (protótipos). Vamos começar:
</para>
<note>
<title>
Pré-requisito: Entendimento básico de <link linkend="language.types">tipos</link>
</title>
<para>
Mesmo PHP sendo uma linguagem fracamente tipada, é importante ter um básico
entendimento dos <link linkend="language.types">tipos</link> pois eles tem
um importante significado.
</para>
</note>
<para>
Definições das funções nos dizem que
tipo de valor é
<link linkend="functions.returning-values">retornado</link>.
Vamos usar a definição do <function>strlen</function> como nosso primeiro exemplo:
</para>
<para>
<screen role="html">
<![CDATA[
strlen
(PHP 4, PHP 5)
strlen -- Obtém o tamanho da string
Descrição
int strlen ( string $string )
Retorna o tamanho de uma dada string.
]]>
</screen>
</para>
<para>
<table>
<title>Explicação da definição da função</title>
<tgroup cols="2">
<thead>
<row>
<entry>Parte</entry>
<entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>
strlen
</entry>
<entry>
Nome da função.
</entry>
</row>
<row>
<entry>
(PHP 4, PHP 5)
</entry>
<entry>
strlen() está disponível em todas as versões do PHP 4 e PHP 5
</entry>
</row>
<row>
<entry>
int
</entry>
<entry>
Tipo do valor que esta função retorna, que é um
<type>integer</type> (isto é, o comprimento de uma string é
medida em números).
</entry>
</row>
<row>
<entry>
( string $string )
</entry>
<entry>
O primeiro (e neste caso, o único) parâmetro/argumento para esta
função é chamado <parameter>string</parameter>, e é uma
<type>string</type>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Poderíamos reescrever a definição da função acima de uma maneira genérica
</para>
<para>
<screen>
<![CDATA[
tipo retornado nome da função ( tipo do parâmetro nome do parâmetro )
]]>
</screen>
</para>
<para>
Muitas funções recebem múltiplos parâmetros, tais como o <function>in_array</function>.
O protótipo segue abaixo:
</para>
<para>
<screen>
<![CDATA[
bool in_array ( mixed $needle, array $haystack [, bool $strict])
]]>
</screen>
</para>
<para>
O que isso significa? in_array() retorna um valor
<link linkend="language.types.boolean">booleano</link>, &true; em caso
de sucesso (se <parameter>needle</parameter> foi encontrado em
<parameter>haystack</parameter>) ou &false; em caso de falha
(<parameter>needle</parameter> não foi encontrado em
<parameter>haystack</parameter>). O primeiro parâmetro é chamado
<parameter>needle</parameter> e pode de ser de vários
<link linkend="language.types">tipos</link>, por isso nós dizemos que ele é
"<emphasis>mixed</emphasis>". Esse <parameter>needle</parameter> mixed
(que nós estamos procurando) pode ser tanto um valor escalar (string, inteiro,
ou <link linkend="language.types.float">float</link>), ou um
<link linkend="language.types.array">array</link>.
<parameter>haystack</parameter> (o array onde nós estamos procurando) é o
segundo parâmetro. O terceiro parâmetro <emphasis>opcional</emphasis> é
chamado <parameter>strict</parameter>. Todos os parâmetros opcionais aparecem
dentro de <emphasis>[</emphasis> colchetes <emphasis>]</emphasis>. O manual
diz que o default do parâmetro <parameter>strict</parameter> é o
booleano &false;. Veja a página de do manual de cada função para detalhes de
como elas funcionam.
</para>
<para>
Existem funções com informações de versões do PHP mais complexas. Veja
<function>html_entity_decode</function> como um exemplo:
</para>
<para>
<screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5)
]]>
</screen>
</para>
<para>
Isto significa que esta função está somente disponível
a partir da versão PHP 4.3.0.
</para>
</sect1>
<sect1 xml:id="about.phpversions">
<title>Versões do PHP documentadas neste manual</title>
<para>
<!-- FIXME PHP_6 What is the latest? -->
O manual contém informações sobre as passadas, presente, e futuras versões do PHP.
Modificações no comportamento são documentados como notas, changelogs, e em
trechos nas páginas do manual.
A mais antiga versão documentada é o PHP 4.1.0, e a última sendo a PHP 5.x.x.
</para>
<para>
Quando a documentação existir para versões mais recentes de desenvolvimento (unreleased)
do PHP, será marcado como "available in Git" ou "development
version." E essas mudanças devem sem planejadas para, em casos raros elas
podem ser mudadas.
</para>
<para>
Todo desenvolvimento ocorre no Git e pode ser feito check out como descrito na
página<link xlink:href="&url.php.anongit;">acesso anônimo ao Git
</link>. Ou, essas mesmas fontes podem ser baixadas como <link xlink:href="&url.php.snapshots;">PHP snapshots</link>,
que estão disponíveis para os branch's mais ativos do PHP.
</para>
<para>
E para esclarecer, o manual refere-se: maiores, menores e específicas releases do PHP.
Usando o PHP <literal>5.3.1</literal> como exemplo, o <emphasis>5</emphasis>
refere a versão maior, <emphasis>3</emphasis> para menor, e
<emphasis>1</emphasis> é o específica release. Tipicamente o PHP somente adiciona novas features
em maiores e menores releases, e corrige bugs em específicas releases. Porém, esta
convenção não é sempre verdade.
</para>
<para>
Observe que o manual PHP é escrito no tempo presente, e não no futuro,
mesmo que para recursos documentados que ainda não estão disponíveis.
A razão para isto é que o manual pode resistir ao teste do tempo,
assim não sendo necessário tediosas atualizações para toda nova release
do PHP.
</para>
<para>
Muitas vezes o manual php lista "Valores Defaults" para as diretivas do PHP.
Esses valores são baseados em como o PHP se comporta sem um arquivo de configuração
&php.ini;, de modo que estas podem variar a partir de valores encontrados nos arquivos
<filename>php.ini-development</filename> e <filename>php.ini-production</filename>
distribuídos. Eles também referem-se a última versão do PHP. Veja o <link linkend="ini.list">Apêndice Diretivas do PHP
</link> para ter detalhes deste valores e mudanças.
</para>
</sect1>
<sect1 xml:id="about.more">
<title>Como encontrar mais informações sobre o manual PHP.</title>
<para>
Este manual tenta fornecer instruções sobre práticas gerais de programação.
Pela primeira vez - ou apenas no início - programadores podem encontrar
dificuldades para aprender como programar em PHP usando o manual exclusivamente.
Em vez disso, procure um texto mais orientado para iniciantes.
</para>
<para>
Há uma série de listas de discussão ativas para todos os aspectos da
programação com PHP.Se ficou preso com algum problema, considere o uso dessas listas.
Para opções de suporte, incluindo listas de discussão, visualização <link
xlink:href="&url.php.support;">da página de suporte do PHP.net</link>. Além disso,
há uma lista de sites dedicadas para artigos do PHP, fóruns, e galerias de código na
<link xlink:href="&url.php.links;">página de links PHP.net</link>.
</para>
</sect1>
<sect1 xml:id="about.howtohelp">
<title>Como ajudar a melhoras a documentação</title>
<para>
Há três maneiras de ajudar a melhoras a documentação.
</para>
<para>
Se um erro é encontrado no manual, em qualquer linguagem, favor reporte-nos
usando o sistema de bug em <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
Classifique o bug <literal>"Documentation Problem"</literal>. Todos os problemas
relacionados com a documentação, inclusive sobre os formatos de manuais, deverão ser
apresentados em relatórios de bugs.
</para>
<note>
<para>
Por favor não abuse do sistema de bugs enviado pedidos de ajuda.
Neste caso, use uma das muitas opções
<link xlink:href="&url.php.support;">opções de suporte</link>.
</para>
</note>
<para>
Ao contribuir com notas, os usuários podem fornecer exemplos adicionais,
e esclarecimento para outros leitores. Mas por favor, não envie reporte de bug
usando o sistema de anotações. Para mais detalhes, veja a seção intitulada <link
linkend="about.notes">'Sobre as notas de usuários'</link>.
</para>
<para>
O manual PHP é traduzindo na maiorias da línguas. Sabendo Inglês e uma língua
estrangeira permite uma maneira de ajudar a melhorar o manual PHP
trabalhando com um time de tradução. Para mais informações sobre como iniciar
uma nova tradução, ou ajudar no projeto de tradução atual, por favor leia
<link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
</para>
<para>
O Projeto de documentação do PHP também possui um canal IRC onde autores
se reunem. No <literal>#php.doc</literal> em
<literal>irc.efnet.org</literal> e discutem maneiras de melhorar
a documentação PHP.
</para>
</sect1>
<sect1 xml:id="about.generate">
<title>Como nós geramos os formatos</title>
<para>
Este Manual é escrito em <acronym>XML</acronym> usando o<link
xlink:href="&url.docbook.xml;">DocBook XML DTD</link>, usando <link
xlink:href="&url.phd;"><acronym>PhD</acronym></link> (The [PH]P based
[D]ocBook renderer) para manutenção e formatação.
</para>
<para>
Usando <acronym>XML</acronym> como formato, nos da a
capacidade para gerar diversos outros formatos de saída a partir
de seu arquivo fonte, ao mesmo tempo que a manutenção é feita em apenas
um único lugar para todos os formatos.
A ferramente usada para formatar o manual online é <link xlink:href="&url.phd;">PhD</link>.
Usamos <link xlink:href="&url.winhelp;">Microsoft HTML Help Workshop</link> para gerar o
formato <productname>Windows HTML Help</productname> do manual e, é claro, o próprio PHP
para fazermos algumas conversões e formatações.
</para>
<para>
O manual PHP é gerado em várias linguagens e formatos, veja
<link xlink:href="&url.php.docs;">&url.php.docs;</link> para maiores detalhes.
A código fonte <acronym>XML</acronym> pode ser baixado da SVN e visualizado
em <link xlink:href="&url.php.svn;">&url.php.svn;</link>. A documentação é
no módulo <literal>phpdoc</literal>.
</para>
</sect1>
<sect1 xml:id="about.translations">
<title>Traduções</title>
<para>
O manual PHP está disponível não apenas em vários formatos, mas
também em várias linguagens. O texto do manual é escrito em Inglês, então
grupos de pessoas ao redor do mundo fazem as traduções para suas línguas nativas.
Se a tradução para uma específica função ou capítulo ainda não foi
feita, o sistema de compilação do manual utiliza a versão original em Inglês.
</para>
<para>
Pessoas envolvidas na tradução iniciam do código fonte <acronym>XML</acronym>
disponível para <link xlink:href="&url.php.svn;">&url.php.svn;</link>
e partir daí é feita tradução para sua língua mãe. Eles
<emphasis>não utilizam</emphasis> a versão gerada (como
<acronym>HTML</acronym> ou plain text) como o sistema de compilação do manual
que converte os fontes <acronym>XML</acronym> para formatos mais legíveis.
</para>
<note>
<para>
Para colaborar com a tradução da documentação
entre em contato com time de traduções/documentação inscrevendo-se na
lista de discussão do phpdoc: envie um e-mail vazio para <link
xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
O endereço da lista de discussão é <literal>&email.php.doc;</literal>. Depois, envie
uma mensagem com interesse de traduzir o manual e alguém irá responder com o feedback
sobre com orientações para iniciar uma nova tradução de linguagem, ou para
participar do time de documentação da língua desejada.
</para>
</note>
<para>
Atualmente o manual está disponível, parcialmente ou não, em 10 linguagens.
</para>
<para>
Todos eles podem ser baixados aqui: <link xlink:href="&url.php.docs;">&url.php.docs;</link>.
</para>
</sect1>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
git-svn-id: https://svn.php.net/repository/phpdoc/pt_BR/trunk@331709 c90b9560-bf6c-de11-be94-00142212c4b1
- All id attributes are now xml:id
- Add docbook namespace to all root elements
- Replace <ulink /> with <link xlink:href />
- Minor markup fixes here and there
- Bump EN-Revision where appropriate
git-svn-id: https://svn.php.net/repository/phpdoc/pt_BR/trunk@238335 c90b9560-bf6c-de11-be94-00142212c4b1
