about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: fc7fe7faecea431a37e1f809b2ba3056e4ef2e1b Maintainer: ae Status: ready --><!-- CREDITS: felipe,ae,fibbarth,adiel,geekcom,royopa,lhsazevedo -->

<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 é disponibilizado em diversos formatos. Estes formatos podem ser divididos
   em dois grupos: formatos de leitura online e 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;">site do PHP.net</link>.
   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 usados para ir rapidamente para partes desejadas 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 do
   estilo de leitura pessoal. Para informações de como o manual é gerado em tantos
   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 estas versões compactadas, então um programa de descompactação é
   necessário para recuperar os arquivos contidos dentro destes pacotes.
  </para>
  <!--
   A versão PDF do manual PHP está "atualmente" indisponível. Talvez
   um dia ela irá existir.
  <para>
   Outro popular formato multi-plataforma, talvez o formato mais adequado para
   impressão, é o PDF (também conhecido como Adobe Acrobat). Mas esteja ciente de que 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 plataformas Windows, a versão <productname>Windows HTML Help</productname>
   do manual otimiza o formato HTML para o uso com o programa
   <productname>Windows HTML Help</productname>. Esta
   versão fornece 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 à documentação. Visualizadores de CHM para
   desktops 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 estendida</link>
   disponível, que é atualizada menos frequentemente, mas que oferece muitos recursos
   adicionais. Entretanto ela irá funcionar apenas no <productname>Microsoft Windows</productname>,
   devido às tecnologias usadas para compilar as páginas de ajuda.
  </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 esse 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 dos exemplos de código, e mesmo a veracidade da
    contribuição, não podem ser garantidas. (Não que haja qualquer garantia
    da qualidade ou exatidão do próprio texto do manual.)
   </para>
  </note>
  <note>
   <para>
    Para fins de cobertura de licença 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">Direitos Autorais
    do Manual</link>.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="about.prototypes">
   <title>Como ler uma definição de função (protótipo)</title>
   <para>
    Cada função no manual é documentada para uma referência rápida. Saber como
    ler e entender o texto tornará a aprendizagem do PHP
    muito mais fácil. 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 o PHP sendo uma linguagem fracamente tipada, é importante ter um
     entendimento básico dos <link linkend="language.types">tipos</link> pois
     eles têm 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 da função <function>strlen</function> como nosso primeiro exemplo:
   </para>
   <para>
    <screen role="html">
<![CDATA[
strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Obtém o tamanho da string

Descrição
strlen ( string $string ) : int

Retorna o tamanho da string dada.
]]>
    </screen>
   </para>
   <para>
    <table>
     <title>Explicação de uma definição de 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, PHP 7)
         </entry>
         <entry>
          strlen() está disponível em todas as versões do PHP 4, 5 e 7
         </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>
        <row>
         <entry>
          int
         </entry>
         <entry>
          Tipo do valor que esta função retorna, que é um
          <type>int</type> (isto é, o comprimento de uma string é
          medido em números).
         </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[
      nome da função    ( tipo do parâmetro   nome do parâmetro ) : tipo retornado
]]>
     </screen>
    </para>
    <para>
     Muitas funções recebem múltiplos parâmetros, tais como a função <function>in_array</function>.
     Seu protótipo segue abaixo:
    </para>
    <para>
     <screen>
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
     </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>) &return.falseforfailure; (se
     <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> diferentes, por isso nós o chamamos
     "<emphasis>mixed</emphasis>" (misto). Esse <parameter>needle</parameter> mixed
     (o 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 têm valores
     padrão (default). Se o valor padrão é desconhecido, então é mostrado um <literal>?</literal>. O exemplo
     diz que o valor padrão do parâmetro <parameter>strict</parameter> é o
     booleano &false;. Veja a página do manual de cada função para detalhes de
     como elas funcionam.
    </para>
    <para>
     Além do mais o símbolo &amp; (ampersand, e comercial) antes de um parâmetro de função
     permite ao parâmetro ser passado por <link linkend="language.references.pass">referência</link>, como no exemplo abaixo:
    </para>
    <para>
     <screen>
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
     </screen>
    </para>
    <para>
     Neste exemplo podemos ver que o terceiro parâmetro opcional <parameter>&amp;$matches</parameter> será
     passado por referência.
    </para>
    <para>
     Existem também funções com informações de versões do PHP mais complexas. Tome como exemplo
     <function>html_entity_decode</function>:
    </para>
    <para>
     <screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
     </screen>
    </para>
    <para>
     Isto significa que esta função só está 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>
   O manual contém informações sobre as versões passadas, presente, e futuras
   do PHP. Modificações no comportamento são documentadas como notas, changelogs e em
   trechos nas páginas do manual.
   A versão mais antiga documentada é o PHP 7.0.0.
  </para>
  <para>
   Quando a documentação existir para versões mais recentes de desenvolvimento (unreleased)
   do PHP, será marcada como "available in Git" ou "development
   version". E, embora estas mudanças sejam planejadas, em casos raros elas
   podem mudar.
  </para>
  <para>
   Todo desenvolvimento ocorre no Git e o check out pode ser feito como descrito na
   página <link xlink:href="&url.php.anongit;">acesso anônimo ao Git
   </link>.
  </para>
  <para>
   E para esclarecer, o manual refere-se a maiores, menores e específicas releases do PHP.
   Usando o PHP <literal>7.3.1</literal> como exemplo, o <emphasis>7</emphasis>
   refere-se à versão maior, <emphasis>3</emphasis> à menor e
   <emphasis>1</emphasis> é a release específica. Tipicamente o PHP somente adiciona novas features
   em maiores e menores releases, e corrige bugs em releases específicas. Porém, esta
   convenção nem sempre é verdadeira.
  </para>
  <para>
   Observe também 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, portanto não exige tediosas
   atualizações gramaticais a cada nova release do PHP.
  </para>
  <para>
   Muitas vezes o manual do PHP lista "Valores Padrão" para as diretivas do PHP. Estes
   valores são baseados em como o PHP se comporta sem um arquivo de configuração &php.ini;,
   então podem ser diferentes dos valores encontrados nos arquivos
   <filename>php.ini-development</filename> e <filename>php.ini-production</filename>
   distribuídos. Eles também referem-se à última versão do PHP, embora entradas do changelog
   mencionem valores anteriores. Veja o <link linkend="ini.list">Apêndice Diretivas do PHP
   </link> para detalhes a respeito destes valores e mudanças.
  </para>
 </sect1>

 <sect1 xml:id="about.more">
  <title>Como encontrar mais informações sobre o PHP</title>
  <para>
   Este manual não tenta fornecer instruções sobre
   práticas gerais de programação. Programadores de primeira viagem - ou apenas começando -
   podem achar difícil aprender a programar em PHP usando
   exclusivamente este manual. Em vez disso, procure um texto mais orientado para
   iniciantes.
  </para>
  <para>
   Há uma série de listas de discussão ativas para discussões de todos os aspectos da
   programação com PHP. Se estiver preso com algum problema, considere o uso destas listas.
   Para opções de suporte, incluindo listas de discussão, veja a <link
   xlink:href="&url.php.support;">página de suporte do PHP.net</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.howtohelp">
  <title>Como ajudar a melhorar a documentação</title>
  <para>
   Há várias maneiras de ajudar a melhorar a documentação.
  </para>
  <para>
   Se um erro for encontrado neste manual, em qualquer linguagem, por favor informe-os
   usando o rastreador de problemas (issues) do respectivo repositório de linguagem em <link xlink:href="https://github.com/php/?q=doc">https://github.com/php</link>.
   Por exemplo, erros no manual em inglês devem ser reportados em
   <link xlink:href="https://github.com/php/doc-en/issues">https://github.com/php/doc-en/issues</link>.
   Todos os problemas relacionados
   com a documentação, inclusive sobre os formatos de manuais, devem ser enviados como
   relatórios de bugs.
  </para>
  <note>
   <para>
    Por favor, não abuse dos rastreadores de problemas enviando pedidos de ajuda.
    Neste caso, use uma das muitas
    <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, ressalvas e
   esclarecimentos para outros leitores. Mas por favor, não informe bugs 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>
   Também é possível enviar pull requests para o
   <link xlink:href="&url.php.git.mirror;doc-en">repositório espelho Github da documentação</link>.
  </para>
  <para>
   O manual PHP é traduzido em várias línguas. Saber inglês e uma língua
   estrangeira permite uma outra 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 muitos
   autores do manual se reúnem. Passe no canal <literal>#php.doc</literal> em
   <literal>irc.efnet.org</literal> e discuta maneiras de melhorar
   a documentação do 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>
   Usar <acronym>XML</acronym> como formato fonte nos dá
   a capacidade de gerar diversos formatos de saída a partir
   dos arquivos fonte, enquanto apenas um documento fonte é mantido para todos os formatos.
   A ferramenta 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 fazer 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.
   O código fonte <acronym>XML</acronym> pode ser baixado do git e
   visualizado em <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.translations">
  <title>Traduções</title>
  <para>
   O manual do PHP está disponível não apenas em vários formatos, mas
   também em várias linguagens. O texto do
   manual é escrito primeiro 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 em <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>
   e partir daí é feita tradução para sua língua mãe. Eles
   <emphasis>não utilizam</emphasis> as versões geradas (como
   <acronym>HTML</acronym> ou texto plano) já que é o sistema de compilação do manual que
   cuida das conversões de <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ção/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>. Informe na
    mensagem o interesse em traduzir o manual e alguém irá responder com
    orientações sobre como avançar iniciando uma nova tradução de linguagem ou
    entrando em contato com o time de documentação da língua desejada.
   </para>
  </note>
  <para>
   Atualmente o manual está disponível, parcialmente ou não, em mais de 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
-->